From 075764fe77a75fd3ac6330605ffc8bfeb3704b47 Mon Sep 17 00:00:00 2001
From: Andrey Avtomonov <andreybavt@gmail.com>
Date: Mon, 11 May 2026 10:40:30 +0200
Subject: [PATCH] [codex] Add Conductor workspace setup (#5)

* Add Conductor workspace setup

* Refine Conductor setup script structure

* Separate Conductor setup steps

* Consolidate Conductor setup script

* Use KTX env var for agent overlays

* Restore Orbit verification summary docs
---
 .../orbit-relationship-verification/README.md |  9 +++++++++
 scripts/conductor-scripts.test.mjs            | 12 +++++++++++-
 scripts/conductor-setup.sh                    | 19 +++++++++++++++++++
 3 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/examples/orbit-relationship-verification/README.md b/examples/orbit-relationship-verification/README.md
index 9f192299..245411b6 100644
--- a/examples/orbit-relationship-verification/README.md
+++ b/examples/orbit-relationship-verification/README.md
@@ -11,6 +11,15 @@ Run from the KTX workspace root:
 pnpm run relationships:verify-orbit
 ```
 
+Expected relationship summary:
+
+```text
+Accepted: 9
+Review: 0
+Rejected: 0
+Skipped: 0
+```
+
 The command refreshes:
 
 ```text
diff --git a/scripts/conductor-scripts.test.mjs b/scripts/conductor-scripts.test.mjs
index 38689def..d33fa73a 100644
--- a/scripts/conductor-scripts.test.mjs
+++ b/scripts/conductor-scripts.test.mjs
@@ -17,16 +17,26 @@ describe('Conductor workspace scripts', () => {
     assert.equal(manifest.runScriptMode, 'nonconcurrent');
   });
 
-  it('sets up exact uv, Python packages, JS packages, and the built CLI', async () => {
+  it('sets up exact uv, local files, Python packages, JS packages, and the built CLI', async () => {
     const setupScript = await readText('scripts/conductor-setup.sh');
 
     assert.match(setupScript, /read_required_uv_version\(\)/);
     assert.match(setupScript, /\.context\/bin\/uv-\$required_version/);
+    assert.match(setupScript, /link_agent_overlays/);
+    assert.match(setupScript, /CONDUCTOR_ROOT_PATH/);
     assert.match(setupScript, /uv sync --all-packages --all-groups/);
     assert.match(setupScript, /pnpm install --frozen-lockfile --prefer-offline/);
     assert.match(setupScript, /pnpm run native:rebuild/);
     assert.match(setupScript, /pnpm run build/);
     assert.match(setupScript, /packages\/cli\/dist\/bin\.js dev doctor setup --no-input/);
+    assert.doesNotMatch(setupScript, /scripts\/conductor\//);
+  });
+
+  it('links private agent overlays when KTX_AGENT_OVERLAYS_ROOT is set', async () => {
+    const workspaceScript = await readText('scripts/conductor-setup.sh');
+
+    assert.match(workspaceScript, /KTX_AGENT_OVERLAYS_ROOT/);
+    assert.match(workspaceScript, /ln -s "\$\{KTX_AGENT_OVERLAYS_ROOT\}\/\.agents" \.agents/);
   });
 
   it('runs the KTX daemon on the documented fixed local port', async () => {
diff --git a/scripts/conductor-setup.sh b/scripts/conductor-setup.sh
index 729b03b0..3bb40b40 100755
--- a/scripts/conductor-setup.sh
+++ b/scripts/conductor-setup.sh
@@ -82,8 +82,27 @@ resolve_uv_for_project() {
   printf '%s\n' "$workspace_uv"
 }
 
+link_agent_overlays() {
+  if [ -z "${KTX_AGENT_OVERLAYS_ROOT:-}" ] || [ ! -d "${KTX_AGENT_OVERLAYS_ROOT}/.agents" ]; then
+    return 0
+  fi
+
+  if [ -L .agents ]; then
+    return 0
+  fi
+
+  if [ -e .agents ]; then
+    echo "Skipping .agents symlink because .agents already exists and is not a symlink." >&2
+    return 0
+  fi
+
+  ln -s "${KTX_AGENT_OVERLAYS_ROOT}/.agents" .agents
+}
+
 echo "=== Conductor KTX workspace setup ==="
 
+link_agent_overlays
+
 if [ -n "${CONDUCTOR_ROOT_PATH:-}" ] && [ -f "$CONDUCTOR_ROOT_PATH/.env" ]; then
   ln -sf "$CONDUCTOR_ROOT_PATH/.env" .env
   echo "Linked .env"