fix: initialize options.hooks before merging YAML node hooks (#1177)

When a workflow node defines hooks (PreToolUse/PostToolUse) in YAML but
no hooks exist yet on the options object, applyNodeConfig crashes with
"undefined is not an object" because it tries to assign properties on
the undefined options.hooks.

Initialize options.hooks to {} before the merge loop.

Reproduces with: archon workflow run archon-architect (which uses
per-node hooks extensively).

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.archon/commands/defaults/archon-fix-issue.md

@@ -131,28 +131,30 @@ git status
 
 ### 3.2 Decision Tree
 
-```
+```text
 ┌─ IN WORKTREE?
-│  └─ YES → Use it (assume it's for this work)
-│           Log: "Using worktree at {path}"
+│  └─ YES → Use current branch AS-IS. Do NOT switch branches. Do NOT create
+│           new branches. The isolation system has already set up the correct
+│           branch; any deviation operates on the wrong code.
+│           Log: "Using worktree at {path} on branch {branch}"
 │
-├─ ON MAIN/MASTER?
+├─ ON $BASE_BRANCH? (main, master, or configured base branch)
 │  └─ Q: Working directory clean?
 │     ├─ YES → Create branch: fix/issue-{number}-{slug}
 │     │        git checkout -b fix/issue-{number}-{slug}
-│     └─ NO  → Warn user:
-│              "Working directory has uncommitted changes.
-│               Please commit or stash before proceeding."
-│              STOP
+│     │        (only applies outside a worktree — e.g., manual CLI usage)
+│     └─ NO  → STOP: "Uncommitted changes on $BASE_BRANCH.
+│              Please commit or stash before proceeding."
 │
-├─ ON FEATURE/FIX BRANCH?
-│  └─ Use it (assume it's for this work)
+├─ ON OTHER BRANCH?
+│  └─ Use it AS-IS (assume it was set up for this work).
+│     Do NOT switch to another branch (e.g., one shown by `git branch` but
+│     not currently checked out).
 │     If branch name doesn't contain issue number:
 │       Warn: "Branch '{name}' may not be for issue #{number}"
 │
 └─ DIRTY STATE?
-   └─ Warn and suggest: git stash or git commit
-      STOP
+   └─ STOP: "Uncommitted changes. Please commit or stash first."
 ```
 
 ### 3.3 Ensure Up-to-Date

.archon/commands/defaults/archon-implement-issue.md

@@ -132,28 +132,30 @@ git status
 
 ### 3.2 Decision Tree
 
-```
+```text
 ┌─ IN WORKTREE?
-│  └─ YES → Use it (assume it's for this work)
-│           Log: "Using worktree at {path}"
+│  └─ YES → Use current branch AS-IS. Do NOT switch branches. Do NOT create
+│           new branches. The isolation system has already set up the correct
+│           branch; any deviation operates on the wrong code.
+│           Log: "Using worktree at {path} on branch {branch}"
 │
-├─ ON MAIN/MASTER?
+├─ ON $BASE_BRANCH? (main, master, or configured base branch)
 │  └─ Q: Working directory clean?
 │     ├─ YES → Create branch: fix/issue-{number}-{slug}
 │     │        git checkout -b fix/issue-{number}-{slug}
-│     └─ NO  → Warn user:
-│              "Working directory has uncommitted changes.
-│               Please commit or stash before proceeding."
-│              STOP
+│     │        (only applies outside a worktree — e.g., manual CLI usage)
+│     └─ NO  → STOP: "Uncommitted changes on $BASE_BRANCH.
+│              Please commit or stash before proceeding."
 │
-├─ ON FEATURE/FIX BRANCH?
-│  └─ Use it (assume it's for this work)
+├─ ON OTHER BRANCH?
+│  └─ Use it AS-IS (assume it was set up for this work).
+│     Do NOT switch to another branch (e.g., one shown by `git branch` but
+│     not currently checked out).
 │     If branch name doesn't contain issue number:
 │       Warn: "Branch '{name}' may not be for issue #{number}"
 │
 └─ DIRTY STATE?
-   └─ Warn and suggest: git stash or git commit
-      STOP
+   └─ STOP: "Uncommitted changes. Please commit or stash first."
 ```
 
 ### 3.3 Ensure Up-to-Date

.archon/commands/defaults/archon-implement.md

@@ -93,19 +93,40 @@ Provide a valid plan path or GitHub issue containing the plan.
 ### 2.1 Check Current State
 
 ```bash
+# What branch are we on?
 git branch --show-current
-git status --porcelain
+
+# Are we in a worktree?
+git rev-parse --show-toplevel
 git worktree list
+
+# Is working directory clean?
+git status --porcelain
 ```
 
 ### 2.2 Branch Decision
 
-| Current State     | Action                                               |
-| ----------------- | ---------------------------------------------------- |
-| In worktree       | Use it (log: "Using worktree")                       |
-| On base branch, clean    | Create branch: `git checkout -b feature/{plan-slug}` |
-| On base branch, dirty    | STOP: "Stash or commit changes first"                |
-| On feature branch | Use it (log: "Using existing branch")                |
+```text
+┌─ IN WORKTREE?
+│  └─ YES → Use current branch AS-IS. Do NOT switch branches. Do NOT create
+│           new branches. The isolation system has already set up the correct
+│           branch; any deviation operates on the wrong code.
+│           Log: "Using worktree at {path} on branch {branch}"
+│
+├─ ON $BASE_BRANCH? (main, master, or configured base branch)
+│  └─ Q: Working directory clean?
+│     ├─ YES → Create branch: git checkout -b feature/{plan-slug}
+│     │        (only applies outside a worktree — e.g., manual CLI usage)
+│     └─ NO  → STOP: "Stash or commit changes first"
+│
+├─ ON OTHER BRANCH?
+│  └─ Use it AS-IS. Do NOT switch to another branch (e.g., one shown by
+│     `git branch` but not currently checked out).
+│     Log: "Using existing branch {name}"
+│
+└─ DIRTY STATE?
+   └─ STOP: "Stash or commit changes first"
+```
 
 ### 2.3 Sync with Remote
 
@@ -116,7 +137,7 @@ git pull --rebase origin $BASE_BRANCH 2>/dev/null || true
 
 **PHASE_2_CHECKPOINT:**
 
-- [ ] On correct branch (not base branch with uncommitted work)
+- [ ] On correct branch (not $BASE_BRANCH with uncommitted work)
 - [ ] Working directory ready
 - [ ] Up to date with remote
 

.archon/commands/defaults/archon-plan-setup.md

@@ -112,13 +112,26 @@ gh repo view --json nameWithOwner -q .nameWithOwner
 
 ### 2.3 Branch Decision
 
-| Current State | Action |
-|---------------|--------|
-| Already on correct feature branch | Use it, log "Using existing branch: {name}" |
-| On base branch, clean working directory | Create and checkout: `git checkout -b {branch-name}` |
-| On base branch, dirty working directory | STOP with error: "Uncommitted changes on base branch. Stash or commit first." |
-| On different feature branch | STOP with error: "On branch {X}, expected {Y}. Switch branches or adjust plan." |
-| In a worktree | Use the worktree's branch, log "Using worktree branch: {name}" |
+Evaluate in order (first matching case wins):
+
+```text
+┌─ IN WORKTREE?
+│  └─ YES → Use current branch AS-IS. Do NOT switch branches. Do NOT create
+│           new branches. The isolation system has already set up the correct
+│           branch; any deviation operates on the wrong code.
+│           Log: "Using worktree branch: {name}"
+│
+├─ ON $BASE_BRANCH? (main, master, or configured base branch)
+│  └─ Q: Working directory clean?
+│     ├─ YES → Create and checkout: `git checkout -b {branch-name}`
+│     │        (only applies outside a worktree — e.g., manual CLI usage)
+│     └─ NO  → STOP: "Uncommitted changes on $BASE_BRANCH. Stash or commit first."
+│
+└─ ON OTHER BRANCH?
+   └─ Q: Does it match the expected branch for this plan?
+      ├─ YES → Use it, log "Using existing branch: {name}"
+      └─ NO  → STOP: "On branch {X}, expected {Y}. Switch branches or adjust plan."
+```
 
 ### 2.4 Sync with Remote
 

.archon/commands/e2e-echo-command.md

@@ -0,0 +1,13 @@
+---
+description: E2E test command — echoes back the user message
+argument-hint: <any text>
+---
+
+# E2E Echo Command
+
+You are a simple echo agent for testing. Your ONLY job is to repeat back the user's message.
+
+User message: $ARGUMENTS
+
+Respond with EXACTLY this format and nothing else:
+command-echo: <the user message above>

.archon/scripts/echo-args.js

@@ -0,0 +1,3 @@
+// Simple script node test — echoes input as JSON
+const input = process.argv[2] ?? 'no-input';
+console.log(JSON.stringify({ echoed: input, timestamp: new Date().toISOString() }));

.archon/scripts/echo-py.py

@@ -0,0 +1,7 @@
+"""Simple script node test — echoes input as JSON (uv/Python runtime)."""
+import json
+import sys
+from datetime import datetime, timezone
+
+input_val = sys.argv[1] if len(sys.argv) > 1 else "no-input"
+print(json.dumps({"echoed": input_val, "timestamp": datetime.now(timezone.utc).isoformat()}))

.archon/workflows/defaults/archon-interactive-prd.yaml

@@ -52,6 +52,7 @@ nodes:
   - id: foundation-gate
     approval:
       message: "Answer the foundation questions above. Your answers will guide the research phase."
+      capture_response: true
     depends_on: [initiate]
 
   # ═══════════════════════════════════════════════════════════════
@@ -106,6 +107,7 @@ nodes:
   - id: deepdive-gate
     approval:
       message: "Answer the deep dive questions above (vision, primary user, JTBD, constraints). Add any adjustments from the research."
+      capture_response: true
     depends_on: [research]
 
   # ═══════════════════════════════════════════════════════════════
@@ -172,6 +174,7 @@ nodes:
   - id: scope-gate
     approval:
       message: "Answer the scope questions above (MVP, must-haves, hypothesis, exclusions). This is the final input before PRD generation."
+      capture_response: true
     depends_on: [technical]
 
   # ═══════════════════════════════════════════════════════════════
@@ -188,11 +191,11 @@ nodes:
       **Deep dive answers**: $deepdive-gate.output
       **Scope answers**: $scope-gate.output
 
-      Generate a complete PRD file at `.claude/PRPs/prds/{kebab-case-name}.prd.md`.
+      Generate a complete PRD file at `$ARTIFACTS_DIR/prds/{kebab-case-name}.prd.md`.
 
       First create the directory:
       ```bash
-      mkdir -p .claude/PRPs/prds
+      mkdir -p $ARTIFACTS_DIR/prds
       ```
 
       **First principles rule**: Before writing the Technical Approach section, READ the
@@ -243,9 +246,9 @@ nodes:
       Read the PRD file that was just generated. The generate node output the file path:
       $generate.output
 
-      Find the PRD file — check `.claude/PRPs/prds/` for the most recently created `.prd.md` file:
+      Find the PRD file — check `$ARTIFACTS_DIR/prds/` for the most recently created `.prd.md` file:
       ```bash
-      ls -t .claude/PRPs/prds/*.prd.md | head -1
+      ls -t $ARTIFACTS_DIR/prds/*.prd.md | head -1
       ```
 
       Read the entire PRD, then verify EVERY technical claim against the actual codebase:

.archon/workflows/e2e-claude-smoke.yaml

@@ -0,0 +1,26 @@
+# E2E smoke test — Claude provider
+# Verifies: Claude connectivity (sendQuery), $nodeId.output refs
+# Design: Only uses allowed_tools: [] (no tool use) and no output_format (no structured output)
+# because the Claude CLI subprocess is slow with those features in CI.
+name: e2e-claude-smoke
+description: "Smoke test for Claude provider. Verifies prompt response."
+provider: claude
+model: haiku
+
+nodes:
+  # 1. Simple prompt — verifies Claude API connectivity via sendQuery
+  - id: simple
+    prompt: "What is 2+2? Answer with just the number, nothing else."
+    allowed_tools: []
+    idle_timeout: 30000
+
+  # 2. Assert non-empty output — fails CI if Claude returned nothing
+  - id: assert
+    bash: |
+      output="$simple.output"
+      if [ -z "$output" ]; then
+        echo "FAIL: simple node returned empty output"
+        exit 1
+      fi
+      echo "PASS: simple=$output"
+    depends_on: [simple]

.archon/workflows/e2e-codex-smoke.yaml

@@ -0,0 +1,40 @@
+# E2E smoke test — Codex provider
+# Verifies: provider selection, sendQuery, structured output
+name: e2e-codex-smoke
+description: "E2E smoke test for Codex provider. Runs a simple prompt + structured output node."
+provider: codex
+model: gpt-5.2
+
+nodes:
+  - id: simple
+    prompt: "What is 2+2? Answer with just the number, nothing else."
+    idle_timeout: 30000
+
+  - id: structured
+    prompt: "Classify this input as 'math' or 'text': '2+2=4'. Return JSON only."
+    output_format:
+      type: object
+      properties:
+        category:
+          type: string
+          enum: ["math", "text"]
+      required: ["category"]
+      additionalProperties: false
+    idle_timeout: 30000
+    depends_on: [simple]
+
+  # Assert both nodes returned output
+  - id: assert
+    bash: |
+      simple_out="$simple.output"
+      structured_out="$structured.output"
+      if [ -z "$simple_out" ]; then
+        echo "FAIL: simple node returned empty output"
+        exit 1
+      fi
+      if [ -z "$structured_out" ]; then
+        echo "FAIL: structured node returned empty output"
+        exit 1
+      fi
+      echo "PASS: simple=$simple_out structured=$structured_out"
+    depends_on: [simple, structured]

.archon/workflows/e2e-deterministic.yaml

@@ -0,0 +1,66 @@
+# E2E smoke test — deterministic nodes (no AI, no API calls)
+# Verifies: bash nodes, script nodes (bun + uv), $nodeId.output substitution,
+#           when conditions, trigger_rule join semantics
+name: e2e-deterministic
+description: "Pure DAG engine test. Exercises bash, script (bun/uv), conditions, and trigger rules with zero API calls."
+
+nodes:
+  # Layer 0 — parallel deterministic nodes
+  - id: bash-echo
+    bash: "echo '{\"status\":\"ok\",\"value\":42}'"
+
+  - id: script-bun
+    script: echo-args
+    runtime: bun
+    timeout: 30000
+
+  - id: script-python
+    script: echo-py
+    runtime: uv
+    timeout: 30000
+
+  # Layer 1 — test $nodeId.output substitution from bash
+  - id: bash-read-output
+    bash: "echo 'upstream-status: $bash-echo.output'"
+    depends_on: [bash-echo]
+
+  # Layer 1 — conditional branches (only one should run)
+  - id: branch-true
+    bash: "echo 'branch-true-ran'"
+    depends_on: [bash-echo]
+    when: "$bash-echo.output.status == 'ok'"
+
+  - id: branch-false
+    bash: "echo 'branch-false-ran'"
+    depends_on: [bash-echo]
+    when: "$bash-echo.output.status == 'fail'"
+
+  # Layer 2 — trigger_rule merge (one_success: branch-false will be skipped)
+  - id: merge-node
+    bash: "echo 'merge-ok: true=$branch-true.output false=$branch-false.output'"
+    depends_on: [branch-true, branch-false]
+    trigger_rule: one_success
+
+  # Layer 3 — final verification: assert all outputs are non-empty
+  - id: verify-all
+    bash: |
+      fail=0
+      for name in bash-echo script-bun script-python bash-read-output branch-true merge-node; do
+        echo "$name output received"
+      done
+      bash_echo="$bash-echo.output"
+      script_bun="$script-bun.output"
+      script_python="$script-python.output"
+      bash_read="$bash-read-output.output"
+      branch_t="$branch-true.output"
+      merge="$merge-node.output"
+      if [ -z "$bash_echo" ]; then echo "FAIL: bash-echo empty"; fail=1; fi
+      if [ -z "$script_bun" ]; then echo "FAIL: script-bun empty"; fail=1; fi
+      if [ -z "$script_python" ]; then echo "FAIL: script-python empty"; fail=1; fi
+      if [ -z "$bash_read" ]; then echo "FAIL: bash-read-output empty"; fail=1; fi
+      if [ -z "$branch_t" ]; then echo "FAIL: branch-true empty"; fail=1; fi
+      if [ -z "$merge" ]; then echo "FAIL: merge-node empty"; fail=1; fi
+      if [ "$fail" -eq 1 ]; then exit 1; fi
+      echo "PASS: all deterministic nodes produced output"
+    depends_on: [bash-read-output, script-bun, script-python, merge-node]
+    trigger_rule: all_success

.archon/workflows/e2e-mixed-providers.yaml

@@ -0,0 +1,38 @@
+# E2E smoke test — mixed providers (Claude + Codex in same workflow)
+# Verifies: per-node provider override, cross-provider $nodeId.output refs
+name: e2e-mixed-providers
+description: "Tests Claude and Codex providers in the same workflow with cross-provider output refs."
+
+# Default provider is claude
+provider: claude
+model: haiku
+
+nodes:
+  # 1. Claude node — default provider
+  - id: claude-node
+    prompt: "Say 'claude-ok' and nothing else."
+    allowed_tools: []
+    idle_timeout: 30000
+
+  # 2. Codex node — provider override (runs parallel with claude-node, different providers)
+  - id: codex-node
+    prompt: "Say 'codex-ok' and nothing else."
+    provider: codex
+    model: gpt-5.2
+    idle_timeout: 30000
+
+  # 3. Assert both providers returned output
+  - id: assert
+    bash: |
+      claude_out="$claude-node.output"
+      codex_out="$codex-node.output"
+      if [ -z "$claude_out" ]; then
+        echo "FAIL: claude-node returned empty output"
+        exit 1
+      fi
+      if [ -z "$codex_out" ]; then
+        echo "FAIL: codex-node returned empty output"
+        exit 1
+      fi
+      echo "PASS: claude=$claude_out codex=$codex_out"
+    depends_on: [claude-node, codex-node]

.archon/workflows/e2e-pi-all-nodes-smoke.yaml

@@ -0,0 +1,105 @@
+# E2E smoke test — Pi provider, every node type
+# Covers: prompt, command, loop (AI node types) + bash, script bun/uv
+#   (deterministic node types) + depends_on / when / trigger_rule / $nodeId.output
+#   (DAG features).
+# Skipped: `approval:` — pauses for human input, incompatible with CI.
+# Auth: ANTHROPIC_API_KEY (CI) or your local `pi /login` OAuth.
+# Expected runtime: ~10s on haiku (3 AI round-trips + deterministic nodes).
+name: e2e-pi-all-nodes-smoke
+description: 'Pi provider smoke across every CI-compatible node type.'
+provider: pi
+model: anthropic/claude-haiku-4-5
+
+nodes:
+  # ─── AI node types ──────────────────────────────────────────────────────
+
+  # 1. prompt: inline prompt (simplest AI node)
+  - id: prompt-node
+    prompt: "Reply with exactly the single word 'ok' and nothing else."
+    allowed_tools: []
+    effort: low
+    idle_timeout: 30000
+
+  # 2. command: named command file (.archon/commands/e2e-echo-command.md)
+  #    The command echoes back $ARGUMENTS (the workflow invocation message).
+  - id: command-node
+    command: e2e-echo-command
+    allowed_tools: []
+    idle_timeout: 30000
+
+  # 3. loop: iterative AI prompt until completion signal
+  #    Bounded by max_iterations: 2 so a misbehaving model can't hang CI.
+  - id: loop-node
+    loop:
+      prompt: "Reply with exactly 'DONE' and nothing else."
+      until: 'DONE'
+      max_iterations: 2
+    allowed_tools: []
+    effort: low
+    idle_timeout: 60000
+
+  # ─── Deterministic node types (no AI) ───────────────────────────────────
+
+  # 4. bash: shell script with JSON output (enables $nodeId.output.status
+  #    dot-access downstream)
+  - id: bash-json-node
+    bash: 'echo ''{"status":"ok"}'''
+
+  # 5. script: bun (TypeScript/JavaScript runtime)
+  - id: script-bun-node
+    script: echo-args
+    runtime: bun
+    timeout: 30000
+
+  # 6. script: uv (Python runtime)
+  - id: script-python-node
+    script: echo-py
+    runtime: uv
+    timeout: 30000
+
+  # ─── DAG features ───────────────────────────────────────────────────────
+
+  # 7. depends_on + $nodeId.output substitution
+  - id: downstream
+    bash: "echo 'downstream got: $prompt-node.output'"
+    depends_on: [prompt-node]
+
+  # 8. when: conditional (JSON dot-access on upstream output)
+  - id: gated
+    bash: "echo 'gated-ok'"
+    depends_on: [bash-json-node]
+    when: "$bash-json-node.output.status == 'ok'"
+
+  # 9. trigger_rule: merge multiple deps (all_success semantics)
+  - id: merge
+    bash: "echo 'merge-ok'"
+    depends_on: [downstream, gated, script-bun-node, script-python-node]
+    trigger_rule: all_success
+
+  # ─── Final assertion ────────────────────────────────────────────────────
+
+  # 10. Verify every upstream node produced non-empty output.
+  - id: assert
+    bash: |
+      fail=0
+      check() {
+        local name="$1"
+        local value="$2"
+        if [ -z "$value" ]; then
+          echo "FAIL: $name produced empty output"
+          fail=1
+        fi
+      }
+      check prompt-node "$prompt-node.output"
+      check command-node "$command-node.output"
+      check loop-node "$loop-node.output"
+      check bash-json-node "$bash-json-node.output"
+      check script-bun-node "$script-bun-node.output"
+      check script-python-node "$script-python-node.output"
+      check downstream "$downstream.output"
+      check gated "$gated.output"
+      check merge "$merge.output"
+      if [ "$fail" -eq 1 ]; then exit 1; fi
+      echo "PASS: all 9 node types produced output"
+    depends_on: [merge, loop-node, command-node]
+    trigger_rule: all_success

.archon/workflows/e2e-pi-smoke.yaml

@@ -0,0 +1,35 @@
+# E2E smoke test — Pi community provider
+# Verifies: Pi connectivity, $nodeId.output refs, async-queue bridge,
+#   and v2 wiring (thinkingLevel, allowed_tools).
+# Design: mirrors e2e-claude-smoke.yaml structure. The `allowed_tools: []`
+#   idiom disables Pi's built-in read/bash/edit/write so the smoke stays
+#   fast (no tool-use round-trips). `thinking: minimal` exercises the
+#   thinkingLevel translation path.
+# Auth: picks up either ANTHROPIC_API_KEY env var (CI) or your local
+#   `pi /login` OAuth credentials from ~/.pi/agent/auth.json.
+name: e2e-pi-smoke
+description: 'Smoke test for Pi community provider. Verifies prompt response via sendQuery.'
+provider: pi
+model: anthropic/claude-haiku-4-5
+
+nodes:
+  # 1. Simple prompt — verifies Pi harness starts, AsyncQueue bridge yields
+  #    assistant chunks, and agent_end produces a result chunk. v2 wiring:
+  #    allowed_tools: [] disables all Pi tools (LLM-only); effort: low is
+  #    translated to Pi's thinkingLevel by options-translator.ts.
+  - id: simple
+    prompt: 'What is 2+2? Answer with just the number, nothing else.'
+    allowed_tools: []
+    effort: low
+    idle_timeout: 30000
+
+  # 2. Assert non-empty output — fails CI if Pi returned nothing
+  - id: assert
+    bash: |
+      output="$simple.output"
+      if [ -z "$output" ]; then
+        echo "FAIL: simple node returned empty output"
+        exit 1
+      fi
+      echo "PASS: simple=$output"
+    depends_on: [simple]

.archon/workflows/e2e-worktree-disabled.yaml

@@ -0,0 +1,34 @@
+# E2E smoke test — workflow-level worktree.enabled: false
+# Verifies: when a workflow pins worktree.enabled: false, runs happen in the
+# live repo checkout (no worktree created, cwd == repo root). Zero AI calls.
+name: e2e-worktree-disabled
+description: "Pinned-isolation-off smoke. Asserts cwd is the repo root rather than a worktree path, regardless of how the workflow is invoked."
+
+worktree:
+  enabled: false
+
+nodes:
+  # Print cwd so the operator can eyeball it, and capture for the assertion node.
+  - id: print-cwd
+    bash: "pwd"
+
+  # Assertion: cwd must NOT contain '/.archon/workspaces/' — if it does, the
+  # policy was ignored and a worktree was created anyway. We also assert the
+  # cwd ends with a git repo (has a .git directory or file visible).
+  - id: assert-live-checkout
+    bash: |
+      cwd="$(pwd)"
+      echo "assert-live-checkout cwd=$cwd"
+      case "$cwd" in
+        */.archon/workspaces/*/worktrees/*)
+          echo "FAIL: workflow ran inside a worktree ($cwd) despite worktree.enabled: false"
+          exit 1
+          ;;
+      esac
+      if [ ! -e "$cwd/.git" ]; then
+        echo "FAIL: cwd $cwd is not a git checkout root (.git missing)"
+        exit 1
+      fi
+      echo "PASS: ran in live checkout (no worktree created by policy)"
+    depends_on: [print-cwd]
+    trigger_rule: all_success

.claude/PRPs/issues/issue-1001-1002-1003.md

@@ -0,0 +1,417 @@
+# Investigation: Interactive PRD Workflow — Three Related Bugs
+
+**Issues**: #1001, #1002, #1003
+**URLs**:
+- https://github.com/coleam00/Archon/issues/1001
+- https://github.com/coleam00/Archon/issues/1002
+- https://github.com/coleam00/Archon/issues/1003
+**Type**: BUG (all three)
+**Investigated**: 2026-04-09
+
+### Assessment
+
+| Metric     | Value  | Reasoning |
+|------------|--------|-----------|
+| Severity   | HIGH   | The interactive-prd workflow is completely non-functional: user answers are lost (#1001), output file can't be written (#1002), and CLI creates fragmented conversations (#1003). No workaround exists. |
+| Complexity | MEDIUM | 3 files affected, but changes are isolated — YAML config fix, one return type addition, one conversation ID lookup. No architectural changes. |
+| Confidence | HIGH   | All three root causes are confirmed with code evidence. The fixes are straightforward and well-understood. |
+
+---
+
+## Problem Statement
+
+The `archon-interactive-prd` workflow has three bugs that together make it completely non-functional:
+1. Approval gates don't capture user responses, so all downstream nodes receive empty strings
+2. The generate node writes to `.claude/` which the Claude SDK blocks
+3. CLI `workflow approve` creates new conversations instead of reusing the original, fragmenting the Web UI
+
+---
+
+## Analysis
+
+### Bug 1: Missing `capture_response: true` (#1001)
+
+**Evidence Chain:**
+
+WHY: Downstream nodes receive empty `$foundation-gate.output`, `$deepdive-gate.output`, `$scope-gate.output`
+↓ BECAUSE: `approveWorkflow()` stores empty string as node output
+Evidence: `packages/core/src/operations/workflow-operations.ts:176`
+```typescript
+const nodeOutput = approval.captureResponse === true ? approvalComment : '';
+```
+↓ BECAUSE: `captureResponse` is `undefined` (falsy) in the pause metadata
+Evidence: `packages/workflows/src/dag-executor.ts:2337`
+```typescript
+captureResponse: node.approval.capture_response,  // undefined when not set in YAML
+```
+↓ ROOT CAUSE: All three approval gates in the YAML lack `capture_response: true`
+Evidence: `.archon/workflows/defaults/archon-interactive-prd.yaml:52-55, 106-109, 172-175`
+
+**Git History:**
+- **Introduced**: `9de8cf2c` (Mar 30) — workflow created before `capture_response` existed
+- **Feature added**: #936 (Apr 2) — added `capture_response` support
+- **Never updated**: The workflow was not retrofitted after #936
+
+### Bug 2: Generate node writes to blocked `.claude/` path (#1002)
+
+**Evidence Chain:**
+
+WHY: `generate` node fails or produces truncated output
+↓ BECAUSE: Claude SDK blocks writes to `.claude/` directory (hardcoded safety boundary)
+↓ ROOT CAUSE: The prompt instructs AI to write to `.claude/PRPs/prds/`
+Evidence: `.archon/workflows/defaults/archon-interactive-prd.yaml:191-196`
+```yaml
+Generate a complete PRD file at `.claude/PRPs/prds/{kebab-case-name}.prd.md`.
+
+First create the directory:
+```bash
+mkdir -p .claude/PRPs/prds
+```
+```
+
+The `validate` node also reads from the same blocked path at line 246-249.
+
+`$ARTIFACTS_DIR` is pre-created by the executor at `packages/workflows/src/executor.ts:468` and is always writable (resolves to `~/.archon/workspaces/{owner}/{repo}/artifacts/runs/{runId}/`).
+
+### Bug 3: CLI approve creates new conversations (#1003)
+
+**Evidence Chain:**
+
+WHY: Each approval creates a separate conversation in the Web UI
+↓ BECAUSE: `workflowRunCommand` always generates a new conversation ID
+Evidence: `packages/cli/src/commands/workflow.ts:272`
+```typescript
+const conversationId = generateConversationId();  // always new cli-{ts}-{rand}
+```
+↓ BECAUSE: `workflowApproveCommand` calls `workflowRunCommand` without passing the original conversation ID
+Evidence: `packages/cli/src/commands/workflow.ts:865`
+```typescript
+await workflowRunCommand(result.workingPath, result.workflowName, result.userMessage ?? '', {
+  resume: true,
+  codebaseId: result.codebaseId ?? undefined,
+});
+```
+↓ ROOT CAUSE: `ApprovalOperationResult` doesn't include `conversationId`, so the approve command can't pass it through
+Evidence: `packages/core/src/operations/workflow-operations.ts:32-38`
+```typescript
+export interface ApprovalOperationResult {
+  workflowName: string;
+  workingPath: string | null;
+  userMessage: string | null;
+  codebaseId: string | null;
+  type: 'interactive_loop' | 'approval_gate';
+}
+```
+
+The workflow run DOES store `conversation_id` (DB UUID) — `packages/core/src/db/workflows.ts:52`. And `getConversationById(id)` at `packages/core/src/db/conversations.ts:19` can retrieve the `platform_conversation_id` from the DB UUID.
+
+### Affected Files
+
+| File | Lines | Action | Description |
+|------|-------|--------|-------------|
+| `.archon/workflows/defaults/archon-interactive-prd.yaml` | 52-55, 106-109, 172-175, 191-196, 246-249 | UPDATE | Add `capture_response: true` to gates; change `.claude/PRPs/prds/` to `$ARTIFACTS_DIR/prds/` |
+| `packages/core/src/operations/workflow-operations.ts` | 32-38, 202-208 | UPDATE | Add `conversationId` to `ApprovalOperationResult` and return it from `approveWorkflow` |
+| `packages/cli/src/commands/workflow.ts` | 60-69, 272, 849-880 | UPDATE | Add `conversationId` to `WorkflowRunOptions`, accept it, pass it through from approve |
+
+### Integration Points
+
+- `packages/core/src/operations/workflow-operations.ts:202` returns result consumed by CLI approve command
+- `packages/cli/src/commands/workflow.ts:865` calls `workflowRunCommand` with the result
+- `packages/cli/src/commands/workflow.ts:272` generates conversation ID (needs to accept override)
+- `packages/core/src/db/conversations.ts:19` `getConversationById()` — needed to look up platform ID from DB UUID
+- `packages/workflows/src/dag-executor.ts:2337` reads `capture_response` from node YAML
+- `packages/core/src/operations/workflow-operations.ts:176` uses `captureResponse` to decide output
+- `RejectionOperationResult` at line 40-49 should also get `conversationId` for consistency (same pattern)
+
+---
+
+## Implementation Plan
+
+### Step 1: Add `capture_response: true` to all three approval gates
+
+**File**: `.archon/workflows/defaults/archon-interactive-prd.yaml`
+**Action**: UPDATE
+
+**Current code (line 52-55):**
+```yaml
+  - id: foundation-gate
+    approval:
+      message: "Answer the foundation questions above. Your answers will guide the research phase."
+    depends_on: [initiate]
+```
+
+**Required change:**
+```yaml
+  - id: foundation-gate
+    approval:
+      message: "Answer the foundation questions above. Your answers will guide the research phase."
+      capture_response: true
+    depends_on: [initiate]
+```
+
+**Same change for `deepdive-gate` (line 106-109) and `scope-gate` (line 172-175).**
+
+---
+
+### Step 2: Change output path from `.claude/PRPs/prds/` to `$ARTIFACTS_DIR/prds/`
+
+**File**: `.archon/workflows/defaults/archon-interactive-prd.yaml`
+**Action**: UPDATE
+
+**In `generate` node (line 191):**
+
+Change:
+```
+Generate a complete PRD file at `.claude/PRPs/prds/{kebab-case-name}.prd.md`.
+
+First create the directory:
+```bash
+mkdir -p .claude/PRPs/prds
+```
+```
+
+To:
+```
+Generate a complete PRD file at `$ARTIFACTS_DIR/prds/{kebab-case-name}.prd.md`.
+
+First create the directory:
+```bash
+mkdir -p $ARTIFACTS_DIR/prds
+```
+```
+
+**In `validate` node (line 246-249):**
+
+Change:
+```
+Find the PRD file — check `.claude/PRPs/prds/` for the most recently created `.prd.md` file:
+```bash
+ls -t .claude/PRPs/prds/*.prd.md | head -1
+```
+```
+
+To:
+```
+Find the PRD file — check `$ARTIFACTS_DIR/prds/` for the most recently created `.prd.md` file:
+```bash
+ls -t $ARTIFACTS_DIR/prds/*.prd.md | head -1
+```
+```
+
+---
+
+### Step 3: Add `conversationId` to `ApprovalOperationResult` and `RejectionOperationResult`
+
+**File**: `packages/core/src/operations/workflow-operations.ts`
+**Action**: UPDATE
+
+**Current (line 32-38):**
+```typescript
+export interface ApprovalOperationResult {
+  workflowName: string;
+  workingPath: string | null;
+  userMessage: string | null;
+  codebaseId: string | null;
+  type: 'interactive_loop' | 'approval_gate';
+}
+```
+
+**Required change:**
+```typescript
+export interface ApprovalOperationResult {
+  workflowName: string;
+  workingPath: string | null;
+  userMessage: string | null;
+  codebaseId: string | null;
+  conversationId: string;
+  type: 'interactive_loop' | 'approval_gate';
+}
+```
+
+**Same for `RejectionOperationResult` (line 40-49).**
+
+---
+
+### Step 4: Return `conversationId` from `approveWorkflow`
+
+**File**: `packages/core/src/operations/workflow-operations.ts`
+**Action**: UPDATE
+
+**Current return (line 166-172 for interactive_loop path):**
+```typescript
+return {
+  workflowName: run.workflow_name,
+  workingPath: run.working_path,
+  userMessage: run.user_message,
+  codebaseId: run.codebase_id,
+  type: 'interactive_loop',
+};
+```
+
+**Required change:**
+```typescript
+return {
+  workflowName: run.workflow_name,
+  workingPath: run.working_path,
+  userMessage: run.user_message,
+  codebaseId: run.codebase_id,
+  conversationId: run.conversation_id,
+  type: 'interactive_loop',
+};
+```
+
+**Same for the approval_gate return at line 202-208.**
+
+Also update `rejectWorkflow` return values (both paths) to include `conversationId: run.conversation_id`.
+
+---
+
+### Step 5: Look up original platform conversation ID and pass it through in CLI
+
+**File**: `packages/cli/src/commands/workflow.ts`
+**Action**: UPDATE
+
+**5a. Add `conversationId` to `WorkflowRunOptions` (line 55-69):**
+```typescript
+interface WorkflowRunOptions {
+  branchName?: string;
+  fromBranch?: string;
+  noWorktree?: boolean;
+  resume?: boolean;
+  codebaseId?: string;
+  allowEnvKeys?: boolean;
+  quiet?: boolean;
+  verbose?: boolean;
+  conversationId?: string;  // Reuse existing conversation (e.g., from approve)
+}
+```
+
+**5b. Use provided `conversationId` instead of generating new one (line 272):**
+
+Change:
+```typescript
+const conversationId = generateConversationId();
+```
+
+To:
+```typescript
+const conversationId = options.conversationId ?? generateConversationId();
+```
+
+**5c. Look up platform conversation ID in `workflowApproveCommand` and pass it (line 849-880):**
+
+After `const result = await approveWorkflow(runId, comment);` (line 850), add a lookup:
+
+```typescript
+// Look up the original platform conversation ID to keep all messages in one thread
+const originalConversation = await conversationDb.getConversationById(result.conversationId);
+const platformConversationId = originalConversation?.platform_conversation_id;
+```
+
+Then pass it to `workflowRunCommand`:
+```typescript
+await workflowRunCommand(result.workingPath, result.workflowName, result.userMessage ?? '', {
+  resume: true,
+  codebaseId: result.codebaseId ?? undefined,
+  conversationId: platformConversationId ?? undefined,
+});
+```
+
+**5d. Same pattern for `workflowRejectCommand` — when the rejection triggers a retry (not cancellation), pass the original conversation ID through.**
+
+---
+
+### Step 6: Update tests
+
+**Tests to verify:**
+
+1. **YAML validation**: Run `bun run cli validate workflows archon-interactive-prd` to confirm the YAML is valid after changes
+2. **Type check**: `bun run type-check` to verify the interface changes compile
+3. **Existing tests**: Run `bun run test` to ensure no regressions
+
+**Test cases to consider adding:**
+- Unit test for `approveWorkflow` verifying `conversationId` is included in return value
+- Integration test that `workflowApproveCommand` passes conversation ID through (may require mocking)
+
+---
+
+## Patterns to Follow
+
+**From codebase — approval gate with capture_response:**
+The `capture_response` field is already used elsewhere and the schema supports it:
+```typescript
+// SOURCE: packages/workflows/src/schemas/dag-node.ts:250
+capture_response: z.boolean().optional(),
+```
+
+**From codebase — conversation lookup by DB UUID:**
+```typescript
+// SOURCE: packages/core/src/db/conversations.ts:19-24
+export async function getConversationById(id: string): Promise<Conversation | null> {
+  const result = await pool.query<Conversation>(
+    'SELECT * FROM remote_agent_conversations WHERE id = $1',
+    [id]
+  );
+  return result.rows[0] ?? null;
+}
+```
+
+**From codebase — $ARTIFACTS_DIR usage in other workflows:**
+`$ARTIFACTS_DIR` is already used in other default workflows and is pre-created by the executor.
+
+---
+
+## Edge Cases & Risks
+
+| Risk/Edge Case | Mitigation |
+|----------------|------------|
+| Original conversation deleted between run start and approve | `getConversationById` returns null → fall back to generating new ID (graceful degradation) |
+| Existing paused runs from before this fix | They work fine — `capture_response` defaults to `undefined`/false, same as current behavior. New runs will capture properly. |
+| `$ARTIFACTS_DIR` substitution in YAML | Already supported by the executor's variable substitution. Verified in `executor.ts:178-210`. |
+| Reject command also creates new conversation | Fixed in Step 5d — same pattern applied to `workflowRejectCommand` |
+
+---
+
+## Validation
+
+### Automated Checks
+
+```bash
+bun run type-check
+bun run test
+bun run lint
+bun run cli validate workflows archon-interactive-prd
+```
+
+### Manual Verification
+
+1. Run `bun run cli workflow run archon-interactive-prd "Build a todo app"` — verify it pauses at foundation-gate
+2. Run `bun run cli workflow approve <id> "My answers..."` — verify the approve reuses the same conversation
+3. Check that the `research` node receives the user's answers in `$foundation-gate.output`
+4. Complete all gates and verify the PRD is written to `$ARTIFACTS_DIR/prds/` (not `.claude/PRPs/prds/`)
+
+---
+
+## Scope Boundaries
+
+**IN SCOPE:**
+- Adding `capture_response: true` to three approval gates in `archon-interactive-prd.yaml`
+- Changing output path from `.claude/PRPs/prds/` to `$ARTIFACTS_DIR/prds/` in generate and validate nodes
+- Adding `conversationId` to `ApprovalOperationResult` and `RejectionOperationResult`
+- Returning `conversation_id` from approve/reject operations
+- Looking up and passing through original conversation ID in CLI approve/reject commands
+
+**OUT OF SCOPE (do not touch):**
+- Other workflows or default commands
+- The approval gate mechanism itself (it works correctly when `capture_response` is set)
+- The executor's variable substitution logic
+- Database schema changes (no migration needed)
+- Chat platform approve commands (Slack/Telegram already handle conversation continuity differently)
+
+---
+
+## Metadata
+
+- **Investigated by**: Claude
+- **Timestamp**: 2026-04-09
+- **Artifact**: `.claude/PRPs/issues/issue-1001-1002-1003.md`

.claude/PRPs/issues/issue-978.md

@@ -0,0 +1,538 @@
+# Investigation: One-command web UI install via `archon serve`
+
+**Issue**: #978 (https://github.com/coleam00/Archon/issues/978)
+**Type**: ENHANCEMENT
+**Investigated**: 2026-04-09T12:00:00Z
+
+### Assessment
+
+| Metric     | Value  | Reasoning                                                                                                                         |
+| ---------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| Priority   | MEDIUM | High user value (removes clone+build friction), but existing Docker path and clone path work; not blocking other work              |
+| Complexity | HIGH   | 8+ files across CLI, server, CI, build scripts; server refactor is the hardest part — `main()` is 600 lines with no library API   |
+| Confidence | HIGH   | Clear codebase analysis, all integration points mapped, no unknowns in the download/extract path; server refactor scope is bounded |
+
+---
+
+## Problem Statement
+
+The compiled Archon CLI binary includes only `packages/cli/src/cli.ts` — no server, no web UI, no `archon serve` command. Users who want the web UI must clone the entire monorepo, install Bun, run `bun install` (2274 packages), and `bun dev`. There is no one-command path to get a working web UI from the binary install.
+
+---
+
+## Analysis
+
+### Change Rationale
+
+The web UI is the most discoverable part of the product, but it's behind the highest friction install path. The proposed approach — lazy-fetching a pre-built web UI tarball from GitHub releases on first `archon serve` — keeps the CLI binary small for CLI-only users while giving web UI users a one-command experience: `brew install coleam00/archon/archon && archon serve`.
+
+### Key Design Decision: Server as Library vs Embedded Mini-Server
+
+The current server (`packages/server/src/index.ts`) is a 721-line script with a monolithic `main()` function (line 129-718). It has no `startServer()` export and cannot be imported as a library. Two approaches:
+
+**Option A: Full server refactor** — Extract `main()` into an exported `startServer(opts)` function, make `@archon/server` a dependency of `@archon/cli`, compile the full server into the binary. Binary grows from ~50MB to ~65MB. All platform adapters (Slack, Telegram, GitHub, Discord) would be compiled in.
+
+**Option B: Minimal embedded server** — Create a lightweight Hono server in `packages/cli/src/commands/serve.ts` that only registers API routes + static serving. No platform adapters. Binary stays closer to current size. Uses `registerApiRoutes()` (already exported from `packages/server/src/routes/api.ts:837`) as the core building block.
+
+**Recommendation: Option A (full refactor)** because:
+- Option B would duplicate server initialization logic and diverge over time
+- Platform adapters are only instantiated when env vars are present (all conditional, see `index.ts:296-459`) — zero cost if not configured
+- The binary size increase (~15MB) is acceptable
+- Users get the full server experience, not a subset
+
+### Affected Files
+
+| File | Lines | Action | Description |
+|------|-------|--------|-------------|
+| `packages/cli/src/commands/serve.ts` | NEW | CREATE | `archon serve` command: download web-dist, start server |
+| `packages/cli/src/cli.ts` | 57-82, 231, 266+ | UPDATE | Add `'serve'` to `noGitCommands`, add `case 'serve'` |
+| `packages/cli/package.json` | deps | UPDATE | Add `@archon/server` and `@archon/adapters` as dependencies |
+| `packages/server/src/index.ts` | 129-718 | UPDATE | Extract `main()` into exported `startServer(opts)` |
+| `packages/server/src/index.ts` | 579-593 | UPDATE | Accept `webDistPath` parameter instead of computing from `import.meta.dir` |
+| `.github/workflows/release.yml` | 140-173 | UPDATE | Add web UI build + tarball upload step |
+| `scripts/build-binaries.sh` | — | NONE | No change needed — `bun build --compile` follows imports automatically |
+| `packages/paths/src/archon-paths.ts` | — | UPDATE | Add `getWebDistPath(version)` helper |
+| Tests | NEW | CREATE | Cover download, checksum, extraction, server startup from CLI |
+
+### Integration Points
+
+- `packages/cli/src/cli.ts:57-82` imports all commands after dotenv setup
+- `packages/server/src/routes/api.ts:837` exports `registerApiRoutes(app, webAdapter, lockManager)` — the only reusable server building block
+- `packages/paths/src/bundled-build.ts` provides `BUNDLED_VERSION` for constructing release URLs
+- `packages/paths/src/archon-paths.ts:56-74` provides `getArchonHome()` for cache location
+- `packages/server/src/index.ts:581-593` resolves `webDistPath` from `import.meta.dir` — needs parameterization
+- `.github/workflows/release.yml:163-173` publishes release assets via `softprops/action-gh-release@v2`
+
+### Git History
+
+- **Server last touched**: `4b2bcb0e` (env-leak-gate polish) — active development area
+- **CLI last touched**: `dddff870` (embed git commit hash in version) — recent changes
+- **Build scripts**: `9adc54af` (wire release workflow to build-binaries.sh) — recently stabilized
+
+---
+
+## Implementation Plan
+
+### Step 1: Extract `startServer(opts)` from server's `main()`
+
+**File**: `packages/server/src/index.ts`
+**Lines**: 129-718
+**Action**: UPDATE
+
+**Current code (simplified):**
+```typescript
+async function main(): Promise<void> {
+  // 600 lines of initialization, adapter creation, route registration, Bun.serve()
+}
+
+main().catch(error => { ... process.exit(1); });
+```
+
+**Required change:**
+
+```typescript
+export interface ServerOptions {
+  /** Override the web dist path (for CLI binary with downloaded web-dist) */
+  webDistPath?: string;
+  /** Override the port */
+  port?: number;
+  /** Skip platform adapter initialization (CLI serve mode) */
+  skipPlatformAdapters?: boolean;
+}
+
+export async function startServer(opts: ServerOptions = {}): Promise<void> {
+  // Move entire main() body here
+  // Replace webDistPath computation (lines 584-588) with:
+  //   opts.webDistPath ?? pathModule.join(pathModule.dirname(pathModule.dirname(import.meta.dir)), 'web', 'dist')
+  // Replace port with: opts.port ?? getPort()
+  // Wrap platform adapter blocks with: if (!opts.skipPlatformAdapters) { ... }
+}
+
+// Keep backward compat: script entry point still works
+if (import.meta.main) {
+  startServer().catch(error => {
+    getLog().fatal({ error: error instanceof Error ? error.message : String(error) }, 'startup_failed');
+    process.exit(1);
+  });
+}
+```
+
+**Why**: Makes the server importable as a library. `import.meta.main` guard ensures the file still works as a standalone script for `bun dev`.
+
+---
+
+### Step 2: Add `getWebDistDir()` path helper
+
+**File**: `packages/paths/src/archon-paths.ts`
+**Action**: UPDATE
+
+**Add function:**
+```typescript
+/**
+ * Returns the path to the cached web UI distribution for a given version.
+ * Example: ~/.archon/web-dist/v0.3.2/
+ */
+export function getWebDistDir(version: string): string {
+  return join(getArchonHome(), 'web-dist', version);
+}
+```
+
+**Why**: Centralizes the cache location logic, consistent with existing `getArchonHome()` patterns.
+
+---
+
+### Step 3: Create `archon serve` command
+
+**File**: `packages/cli/src/commands/serve.ts`
+**Action**: CREATE
+
+```typescript
+import { existsSync } from 'fs';
+import { createLogger, getWebDistDir } from '@archon/paths';
+import { BUNDLED_IS_BINARY, BUNDLED_VERSION } from '@archon/paths/bundled-build';
+
+const log = createLogger('cli.serve');
+
+const GITHUB_REPO = 'coleam00/Archon';
+
+interface ServeOptions {
+  port?: number;
+  downloadOnly?: boolean;
+}
+
+export async function serveCommand(opts: ServeOptions): Promise<number> {
+  const version = BUNDLED_IS_BINARY ? BUNDLED_VERSION : 'dev';
+  
+  if (version === 'dev') {
+    console.error('Error: `archon serve` is for compiled binaries only.');
+    console.error('For development, use: bun run dev');
+    return 1;
+  }
+
+  const webDistDir = getWebDistDir(version);
+
+  if (!existsSync(webDistDir)) {
+    await downloadWebDist(version, webDistDir);
+  }
+
+  if (opts.downloadOnly) {
+    log.info({ webDistDir }, 'web_dist.download_completed');
+    console.log(`Web UI downloaded to: ${webDistDir}`);
+    return 0;
+  }
+
+  // Import server and start
+  const { startServer } = await import('@archon/server');
+  await startServer({
+    webDistPath: webDistDir,
+    port: opts.port,
+    skipPlatformAdapters: false, // Start all configured adapters
+  });
+
+  // Server runs until SIGINT/SIGTERM — never returns
+  return 0;
+}
+
+async function downloadWebDist(version: string, targetDir: string): Promise<void> {
+  const tarballUrl = `https://github.com/${GITHUB_REPO}/releases/download/v${version}/archon-web.tar.gz`;
+  const checksumsUrl = `https://github.com/${GITHUB_REPO}/releases/download/v${version}/checksums.txt`;
+
+  console.log(`Web UI not found locally — downloading from release v${version}...`);
+
+  // Download checksums
+  const checksumsRes = await fetch(checksumsUrl);
+  if (!checksumsRes.ok) {
+    throw new Error(`Failed to download checksums: ${checksumsRes.status} ${checksumsRes.statusText}`);
+  }
+  const checksumsText = await checksumsRes.text();
+  const expectedHash = parseChecksum(checksumsText, 'archon-web.tar.gz');
+
+  // Download tarball
+  console.log(`Downloading ${tarballUrl}...`);
+  const tarballRes = await fetch(tarballUrl);
+  if (!tarballRes.ok) {
+    throw new Error(`Failed to download web UI: ${tarballRes.status} ${tarballRes.statusText}`);
+  }
+  const tarballBuffer = await tarballRes.arrayBuffer();
+
+  // Verify checksum
+  const hasher = new Bun.CryptoHasher('sha256');
+  hasher.update(new Uint8Array(tarballBuffer));
+  const actualHash = hasher.digest('hex');
+
+  if (actualHash !== expectedHash) {
+    throw new Error(`Checksum mismatch: expected ${expectedHash}, got ${actualHash}`);
+  }
+  console.log('Checksum verified.');
+
+  // Extract to temp dir, then atomic rename
+  const tmpDir = `${targetDir}.tmp`;
+  const { mkdirSync, renameSync, rmSync } = await import('fs');
+  
+  // Clean up any previous failed attempt
+  rmSync(tmpDir, { recursive: true, force: true });
+  mkdirSync(tmpDir, { recursive: true });
+
+  // Extract tarball using tar (available on macOS/Linux)
+  const proc = Bun.spawn(['tar', 'xzf', '-', '-C', tmpDir, '--strip-components=1'], {
+    stdin: new Uint8Array(tarballBuffer),
+  });
+  const exitCode = await proc.exited;
+  if (exitCode !== 0) {
+    rmSync(tmpDir, { recursive: true, force: true });
+    throw new Error(`tar extraction failed with exit code ${exitCode}`);
+  }
+
+  // Atomic move
+  renameSync(tmpDir, targetDir);
+  console.log(`Extracted to ${targetDir}`);
+}
+
+function parseChecksum(checksums: string, filename: string): string {
+  for (const line of checksums.split('\n')) {
+    const parts = line.trim().split(/\s+/);
+    if (parts.length >= 2 && parts[1] === filename) {
+      return parts[0];
+    }
+  }
+  throw new Error(`Checksum not found for ${filename} in checksums.txt`);
+}
+```
+
+**Why**: Self-contained command following existing CLI patterns. Atomic extraction prevents half-broken state. Checksum verification prevents supply chain attacks.
+
+---
+
+### Step 4: Wire `serve` into CLI command dispatch
+
+**File**: `packages/cli/src/cli.ts`
+**Lines**: 57-82, 231, 266+
+**Action**: UPDATE
+
+**Change 1** — Add import (after line 82):
+```typescript
+import { serveCommand } from './commands/serve.js';
+```
+
+**Change 2** — Add to `noGitCommands` (line 231):
+```typescript
+const noGitCommands = ['version', 'help', 'setup', 'chat', 'continue', 'serve'];
+```
+
+**Change 3** — Add case in switch (after the existing `case 'continue'` block):
+```typescript
+case 'serve': {
+  const servePort = values.port ? Number(values.port) : undefined;
+  const downloadOnly = Boolean(values['download-only']);
+  return await serveCommand({ port: servePort, downloadOnly });
+}
+```
+
+**Change 4** — Add `--port` and `--download-only` to `parseArgs` options:
+```typescript
+port: { type: 'string' },
+'download-only': { type: 'boolean', default: false },
+```
+
+**Change 5** — Update `printUsage()` to include `serve`:
+```
+  serve              Start the web UI server (downloads web UI on first run)
+    --port <port>       Override server port (default: 3090)
+    --download-only     Download web UI without starting the server
+```
+
+**Why**: Follows exact patterns of existing commands. `serve` doesn't need a git repo.
+
+---
+
+### Step 5: Add `@archon/server` dependency to CLI package
+
+**File**: `packages/cli/package.json`
+**Action**: UPDATE
+
+Add to `dependencies`:
+```json
+"@archon/server": "workspace:*",
+"@archon/adapters": "workspace:*"
+```
+
+**Why**: The CLI needs to import `startServer` from `@archon/server`. `@archon/adapters` is a transitive dependency of `@archon/server` and should be explicit.
+
+---
+
+### Step 6: Update release CI to build and publish web UI tarball
+
+**File**: `.github/workflows/release.yml`
+**Action**: UPDATE
+
+**Add new job** (or add steps to existing `release` job, after artifact download):
+
+```yaml
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build web UI
+        run: bun --filter @archon/web run build
+
+      - name: Package web dist
+        run: |
+          tar czf dist/archon-web.tar.gz -C packages/web/dist .
+
+      - name: Generate checksums
+        run: |
+          cd dist
+          sha256sum archon-* archon-web.tar.gz > checksums.txt
+          cat checksums.txt
+```
+
+**Update** the `files:` block in the release step:
+```yaml
+          files: |
+            dist/archon-*
+            dist/archon-web.tar.gz
+            dist/checksums.txt
+```
+
+**Why**: Publishes a single platform-independent web UI tarball alongside the existing per-platform binaries. Checksums cover all artifacts.
+
+---
+
+### Step 7: Add/Update Tests
+
+**File**: `packages/cli/src/commands/serve.test.ts`
+**Action**: CREATE
+
+**Test cases to add:**
+
+```typescript
+describe('serveCommand', () => {
+  it('should reject in dev mode (non-binary)', () => {
+    // Mock BUNDLED_IS_BINARY = false
+    // Expect exit code 1 with "compiled binaries only" message
+  });
+
+  it('should download web-dist when not cached', () => {
+    // Mock fetch to return tarball + checksums
+    // Verify extraction to correct path
+  });
+
+  it('should skip download when already cached', () => {
+    // Pre-create the web-dist dir
+    // Verify no fetch calls
+  });
+
+  it('should fail on checksum mismatch', () => {
+    // Mock fetch with wrong checksum
+    // Expect error, no leftover .tmp dir
+  });
+
+  it('should handle network failure gracefully', () => {
+    // Mock fetch to throw
+    // Expect actionable error message
+  });
+
+  it('should support --download-only', () => {
+    // Mock fetch, run with downloadOnly: true
+    // Verify no startServer call
+  });
+});
+
+describe('parseChecksum', () => {
+  it('should extract hash for matching filename', () => {
+    // Known checksums.txt format
+  });
+
+  it('should throw for missing filename', () => {
+    // checksums.txt without the expected entry
+  });
+});
+```
+
+---
+
+## Patterns to Follow
+
+**From codebase — mirror these exactly:**
+
+```typescript
+// SOURCE: packages/cli/src/commands/version.ts:79-88
+// Pattern for binary detection
+if (BUNDLED_IS_BINARY) {
+  version = BUNDLED_VERSION;
+  gitCommit = BUNDLED_GIT_COMMIT;
+} else {
+  const devInfo = await getDevVersion();
+  version = devInfo.version;
+  gitCommit = await getDevGitCommit();
+}
+```
+
+```typescript
+// SOURCE: packages/paths/src/archon-paths.ts:56-74
+// Pattern for path resolution with ARCHON_HOME override
+export function getArchonHome(): string {
+  if (isDocker()) {
+    return '/.archon';
+  }
+  const envHome = process.env.ARCHON_HOME;
+  if (envHome) { /* ... */ return expandTilde(envHome); }
+  return join(homedir(), '.archon');
+}
+```
+
+```typescript
+// SOURCE: packages/server/src/index.ts:579-593
+// Pattern for static file serving (to be parameterized)
+if (process.env.NODE_ENV === 'production' || !process.env.WEB_UI_DEV) {
+  const { serveStatic } = await import('hono/bun');
+  app.use('/assets/*', serveStatic({ root: webDistPath }));
+  app.get('*', serveStatic({ root: webDistPath, path: 'index.html' }));
+}
+```
+
+---
+
+## Edge Cases & Risks
+
+| Risk/Edge Case | Mitigation |
+|---------------|------------|
+| Server refactor breaks `bun dev` | `import.meta.main` guard keeps script-mode working; test both paths |
+| Binary size bloat from including server | Monitor: current ~50MB, expected ~65MB. Acceptable for the value. |
+| Tarball extraction fails (permissions, disk space) | Atomic extraction (`.tmp` → rename); clean up on failure; clear error message |
+| GitHub release rate limiting | `fetch` will return 403 — surface the error with retry suggestion |
+| Air-gapped environments | `--download-only` allows pre-caching; future `--web-dist <path>` for offline |
+| Version mismatch (binary v0.3.2 but no release exists yet) | Fail with "release not found" — only happens if someone builds from source with wrong version |
+| `tar` not available on system | Available on all macOS/Linux; for Windows, use Bun's built-in tar or `decompress` |
+| Concurrent `archon serve` calls during first download | Atomic rename prevents corruption; second process sees complete dir or retries |
+| `@archon/server` import increases CLI startup time | Use dynamic `await import()` in serve command only — other commands unaffected |
+
+---
+
+## Validation
+
+### Automated Checks
+
+```bash
+bun run type-check
+bun run test
+bun run lint
+bun run validate  # Full pre-PR validation
+```
+
+### Manual Verification
+
+1. Run `bun run dev` — verify server still starts normally (script mode preserved)
+2. Build binary: `VERSION=test scripts/build-binaries.sh` — verify it compiles
+3. Run binary with `archon serve` — verify download + extraction + server start
+4. Run binary with `archon serve --download-only` — verify download without server
+5. Run binary with `archon serve` a second time — verify cached (no download)
+6. Run `archon workflow list` — verify no startup time regression from server dep
+7. Verify `archon serve --port 4000` — verify port override works
+
+---
+
+## Scope Boundaries
+
+**IN SCOPE:**
+- Server library refactor (extract `startServer()`)
+- `archon serve` CLI command with download + checksum + extract
+- `--port` and `--download-only` flags
+- Release CI changes to build and publish `archon-web.tar.gz`
+- Path helper for web-dist cache location
+- Tests for download/extract/checksum logic
+
+**OUT OF SCOPE (do not touch):**
+- `bun dev` workflow — stays as-is for contributors
+- Docker image — orthogonal, not affected
+- CDN mirroring — GitHub releases sufficient for now
+- `archon serve --web-version=latest` — defer to future issue
+- `archon serve --offline --web-dist=./path` — defer (can add later)
+- Homebrew formula changes — just update docs, no formula change needed
+- Auto-update of cached web-dist — version-keyed dirs handle this naturally
+- Deprecating clone-and-bun-dev — keep for contributors
+- Platform adapter lazy loading optimization — all adapters already conditional on env vars
+
+---
+
+## Implementation Order
+
+The steps have a strict dependency chain:
+
+1. **Step 2** (path helper) — no deps, can go first
+2. **Step 1** (server refactor) — the hardest part, do early
+3. **Step 5** (CLI package.json dep) — needed before Step 3
+4. **Step 3** (serve command) — depends on Steps 1, 2, 5
+5. **Step 4** (CLI wiring) — depends on Step 3
+6. **Step 7** (tests) — depends on Steps 3, 4
+7. **Step 6** (CI changes) — independent, can be done in parallel with 3-7
+
+---
+
+## Metadata
+
+- **Investigated by**: Claude
+- **Timestamp**: 2026-04-09T12:00:00Z
+- **Artifact**: `.claude/PRPs/issues/issue-978.md`

.claude/commands/plan-feature.md

@@ -23,7 +23,7 @@ Restate the feature request in your own words. Identify:
 3. **Scope boundaries** — What is explicitly in scope vs. out of scope?
 4. **Package impact** — Which of the 8 packages are affected? (`paths`, `git`, `isolation`,
    `workflows`, `core`, `adapters`, `server`, `web`)
-5. **Interface changes** — Does this touch `IPlatformAdapter`, `IAssistantClient`,
+5. **Interface changes** — Does this touch `IPlatformAdapter`, `IAgentProvider`,
    `IDatabase`, or `IWorkflowStore`? New interfaces needed?
 
 ---
@@ -85,7 +85,7 @@ Before writing tasks, reason through:
 **Interface design:**
 - Prefer extending existing narrow interfaces over creating fat ones.
 - New interface methods only if they have a concrete current caller.
-- Avoid adding methods to `IPlatformAdapter` or `IAssistantClient` unless essential.
+- Avoid adding methods to `IPlatformAdapter` or `IAgentProvider` unless essential.
 
 **Test isolation strategy:**
 - `mock.module()` is process-global and permanent in Bun — plan test file placement carefully.

.claude/commands/prime-backend.md

@@ -39,11 +39,11 @@ Read `packages/core/src/state/session-transitions.ts` in full — `TransitionTri
 
 ### 5. Understand AI Client Patterns
 
-List clients:
-!`ls packages/core/src/clients/`
+List providers:
+!`ls packages/core/src/providers/`
 
-Read `packages/core/src/clients/factory.ts` for provider selection logic.
-Read `packages/core/src/clients/claude.ts` first 50 lines — `IAssistantClient` implementation
+Read `packages/core/src/providers/factory.ts` for provider selection logic.
+Read `packages/core/src/providers/claude.ts` first 50 lines — `IAgentProvider` implementation
 with streaming event loop pattern.
 
 ### 6. Understand Database Layer
@@ -52,7 +52,7 @@ List DB modules:
 !`ls packages/core/src/db/`
 
 Read `packages/core/src/types/index.ts` (or the main types file) first 60 lines for key
-interfaces: `IPlatformAdapter`, `IAssistantClient`, `Conversation`, `Session`.
+interfaces: `IPlatformAdapter`, `IAgentProvider`, `Conversation`, `Session`.
 
 ### 7. Understand the Server
 
@@ -81,9 +81,9 @@ Summarize (under 250 words):
 - `TransitionTrigger` values and their behaviors
 - Only `plan-to-execute` immediately creates a new session; others deactivate first
 
-### AI Clients
-- `ClaudeClient` (claude-agent-sdk) and `CodexClient` (codex-sdk)
-- `IAssistantClient` streaming pattern: `for await (const event of events)`
+### AI Providers
+- `ClaudeProvider` (claude-agent-sdk) and `CodexProvider` (codex-sdk)
+- `IAgentProvider` streaming pattern: `for await (const event of events)`
 
 ### Key Database Tables
 - conversations, sessions, codebases, isolation_environments, workflow_runs, workflow_events, messages

.claude/commands/prime-workflows.md

@@ -51,7 +51,7 @@ bridges these to SSE via `WorkflowEventBridge`.
 ### 7. Understand Dependency Injection
 
 Read `packages/workflows/src/deps.ts` — `WorkflowDeps` type: `IWorkflowPlatform`,
-`IWorkflowAssistantClient`, `IWorkflowStore` injected at runtime. No direct DB or AI imports
+`IWorkflowAgentProvider`, `IWorkflowStore` injected at runtime. No direct DB or AI imports
 inside this package.
 
 ### 8. See What Workflows Are Available

.claude/commands/prime.md

@@ -64,8 +64,8 @@ Provide a concise summary (under 300 words) covering:
 
 ### Architecture
 - Package dependency order and each package's responsibility
-- Key interfaces: `IPlatformAdapter`, `IAssistantClient`, `IDatabase`, `IWorkflowStore`
-- Message flow: platform adapter → orchestrator-agent → command handler OR AI client
+- Key interfaces: `IPlatformAdapter`, `IAgentProvider`, `IDatabase`, `IWorkflowStore`
+- Message flow: platform adapter → orchestrator-agent → command handler OR AI provider
 - Workflow execution: `discoverWorkflows` → router → `executeWorkflow` (steps / loop / DAG)
 
 ### Current State

.claude/commands/validate.md

@@ -21,7 +21,7 @@ Runs `tsc --noEmit` across all 8 packages via `bun --filter '*' type-check`.
 
 **What to look for:**
 - Missing return types (explicit return types required on all functions)
-- Incorrect interface implementations (`IPlatformAdapter`, `IAssistantClient`, etc.)
+- Incorrect interface implementations (`IPlatformAdapter`, `IAgentProvider`, etc.)
 - Import type errors (use `import type` for type-only imports)
 - Package boundary violations (e.g., `@archon/workflows` importing from `@archon/core`)
 

.claude/docs/architecture-deep-dive.md

@@ -33,7 +33,7 @@ Slack event
             → Otherwise → buildOrchestratorPrompt() (prompt-builder.ts:116)
             → Prompt includes: registered projects, discovered workflows, /invoke-workflow format
           → sessionDb.getActiveSession() → transitionSession('first-message') if none (orchestrator-agent.ts:462)
-          → getAssistantClient(conversation.ai_assistant_type) (orchestrator-agent.ts:470)
+          → getAgentProvider(conversation.ai_assistant_type) (orchestrator-agent.ts:470)
           → cwd = getArchonWorkspacesPath() (orchestrator-agent.ts:458)
           → handleBatchMode() or handleStreamMode() based on getStreamingMode()
 
@@ -313,7 +313,7 @@ Narrows `IPlatformAdapter` to `WebAdapter` for web-specific methods: `setConvers
 | Message entry | `adapters/src/chat/slack/adapter.ts`, `server/src/index.ts` |
 | Orchestration | `core/src/orchestrator/orchestrator-agent.ts`, `core/src/orchestrator/orchestrator.ts` |
 | Locking | `core/src/utils/conversation-lock.ts` |
-| AI clients | `core/src/clients/claude.ts`, `core/src/clients/factory.ts` |
+| AI providers | `core/src/providers/claude.ts`, `core/src/providers/factory.ts` |
 | Commands | `core/src/handlers/command-handler.ts` |
 | Sessions | `core/src/db/sessions.ts`, `core/src/state/session-transitions.ts` |
 | Workflows | `workflows/src/executor.ts`, `workflows/src/dag-executor.ts`, `workflows/src/loader.ts` |

.claude/rules/adapters.md

@@ -1,44 +0,0 @@
----
-paths:
-  - "packages/adapters/**/*.ts"
----
-
-# Adapters Conventions
-
-## Key Patterns
-
-- **Auth is inside adapters** — every adapter checks authorization before calling `onMessage()`. Silent rejection (no error response), log with masked user ID: `userId.slice(0, 4) + '***'`.
-- **Whitelist parsing in constructor** — parse env var (`SLACK_ALLOWED_USER_IDS`, `TELEGRAM_ALLOWED_USER_IDS`, `GITHUB_ALLOWED_USERS`) using a co-located `parseAllowedUserIds()` / `parseAllowedUsers()` function. Empty list = open access.
-- **Lazy logger pattern** — ALL adapter files use a module-level `cachedLog` + `getLog()` getter so test mocks intercept `createLogger` before the logger is instantiated. Never initialize logger at module scope.
-- **Two handler patterns** (both valid):
-  - **Chat adapters** (Slack, Telegram, Discord): `onMessage(handler)` — adapter owns the event loop (polling/WebSocket), fires registered callback. Lock manager lives in the server's callback closure. Errors handled by caller via `createMessageErrorHandler`.
-  - **Forge adapters** (GitHub, Gitea): `handleWebhook(payload, signature)` — server HTTP route calls directly, returns 200 immediately. Full pipeline inside adapter (signature verification, repo cloning, command loading, context building). Lock manager injected in constructor. Errors caught internally and posted to issue/PR.
-- **Message splitting** — use shared `splitIntoParagraphChunks(message, maxLength)` from `../../utils/message-splitting`. Two-pass: paragraph breaks first, then line breaks. Limits: Slack 12000, Telegram 4096, GitHub 65000.
-- **`ensureThread()` is often a no-op** — Slack returns the same ID (already encoded as `channel:ts`), Telegram has no threads, GitHub issues are inherently threaded.
-
-## Conversation ID Formats
-
-| Platform | Format | Example |
-|----------|--------|---------|
-| Slack | `channel:thread_ts` | `C123ABC:1234567890.123456` |
-| Telegram | numeric chat ID as string | `"1234567890"` |
-| GitHub | `owner/repo#number` | `"acme/api#42"` |
-| Web | user-provided string | `"my-chat"` |
-| Discord | channel ID string | `"987654321098765432"` |
-
-## Architecture
-
-- All chat adapters implement `IPlatformAdapter` from `@archon/core`
-- GitHub adapter is webhook-based (no polling); Slack/Telegram/Discord use polling
-- GitHub adapter holds its own `ConversationLockManager` (injected in constructor)
-- Slack conversation ID encodes both channel and thread: `sendMessage()` splits on `:` to extract `thread_ts`
-- GitHub adapter adds `<!-- archon-bot-response -->` marker to prevent self-triggering loops
-- GitHub only responds to `issue_comment.created` events — NOT `issues.opened` / `pull_request.opened` (descriptions contain documentation, not commands; see #96)
-
-## Anti-patterns
-
-- Never put auth logic outside the adapter (no auth middleware in server routes)
-- Never throw from `onMessage` handlers; errors surface to the caller
-- Never call `sendMessage()` with a raw token or credential string in the message
-- Never use the generic `exec` — always use `execFileAsync` for subprocess calls
-- Never add a new adapter method to `IPlatformAdapter` unless ALL adapters need it; use optional methods (`sendStructuredEvent?`) for platform-specific capabilities

.claude/rules/cli.md

@@ -1,89 +0,0 @@
----
-paths:
-  - "packages/cli/**/*.ts"
----
-
-# CLI Conventions
-
-## Commands
-
-```bash
-# Workflow commands (require git repo)
-bun run cli workflow list [--json]
-bun run cli workflow run <name> [message] [--branch <branch>] [--from-branch <base>] [--no-worktree] [--resume]
-bun run cli workflow status [runId]
-
-# Isolation commands
-bun run cli isolation list
-bun run cli isolation cleanup [days]           # default: 7 days
-bun run cli isolation cleanup --merged         # removes merged branches + remote refs
-bun run cli complete <branch-name> [--force]   # full lifecycle: worktree + local/remote branches
-
-# Interactive
-bun run cli chat [--cwd <path>]
-
-# Setup
-bun run cli setup
-bun run cli version
-```
-
-## Startup Behavior
-
-1. Deletes `process.env.DATABASE_URL` (prevent target repo's DB from leaking in)
-2. Loads `~/.archon/.env` with `override: true`
-3. Smart Claude auth default: if no `CLAUDE_API_KEY` or `CLAUDE_CODE_OAUTH_TOKEN`, sets `CLAUDE_USE_GLOBAL_AUTH=true`
-4. Imports all commands AFTER dotenv setup
-
-## WorkflowRunOptions Interface
-
-```typescript
-interface WorkflowRunOptions {
-  branchName?: string;   // Explicit branch name for the worktree
-  fromBranch?: string;   // Override base branch (start-point for worktree)
-  noWorktree?: boolean;  // Opt out of isolation, run in live checkout
-  resume?: boolean;      // Reuse worktree from last failed run
-}
-```
-
-**Default behavior**: Creates worktree with auto-generated branch name (`archon/task-{workflow}-{timestamp}`).
-
-**Mutually exclusive** (enforced in both `cli.ts` pre-flight and `workflowRunCommand`):
-- `--branch` + `--no-worktree`
-- `--from` + `--no-worktree`
-- `--resume` + `--branch`
-
-- `--branch feature-auth` → creates/reuses worktree for that branch
-- (no flags) → creates worktree with auto-generated `archon/task-*` branch (isolation by default)
-- `--no-worktree` → runs directly in live checkout (opt-out of isolation)
-- `--from dev` → overrides the start-point for new worktree (works with or without `--branch`)
-- `--resume` → resumes last run for this conversation (mutually exclusive with `--branch`)
-
-## Git Repo Requirement
-
-Workflow and isolation commands resolve CWD to the git repo root. Run from within a git repository (subdirectories work). The CLI calls `git rev-parse --show-toplevel` to find the root.
-
-## Conversation ID Format
-
-CLI generates: `cli-{timestamp}-{random6}` (e.g., `cli-1703123456789-a7f3bc`)
-
-## Port Allocation
-
-Worktree-aware: same hash-based algorithm as server (3190–4089 range). Running `bun dev` in a worktree auto-allocates a unique port. Same worktree always gets same port.
-
-## CLIAdapter
-
-The `CLIAdapter` implements `IPlatformAdapter`. It streams output to stdout. `getStreamingMode()` defaults to `'batch'` (configurable via constructor options). No auth needed — CLI is local only.
-
-## Architecture
-
-- `@archon/cli` depends on `@archon/core`, `@archon/workflows`, `@archon/git`, `@archon/isolation`, `@archon/paths`
-- Uses `createWorkflowDeps()` from `@archon/core/workflows/store-adapter` to build workflow deps
-- Database shared with server (same `~/.archon/archon.db` or `DATABASE_URL`)
-- Conversation lifecycle: create → run workflow → persist messages (same DB as web UI)
-
-## Anti-patterns
-
-- Never run CLI commands without being inside a git repository (workflow/isolation commands will fail)
-- Never set `DATABASE_URL` in `~/.archon/.env` to point at a target app's database
-- Never use `--force` on `complete` unless branch is truly safe to delete (skips uncommitted check)
-- Never add interactive prompts inside CLI commands — use flags for all options (non-interactive tool)

.claude/rules/database.md

@@ -1,90 +0,0 @@
----
-paths:
-  - "packages/core/src/db/**/*.ts"
-  - "migrations/**/*.sql"
----
-
-# Database Conventions
-
-## 7 Tables (all prefixed `remote_agent_`)
-
-| Table | Purpose |
-|-------|---------|
-| `remote_agent_conversations` | Platform conversations, soft-delete (`deleted_at`), title, `hidden` flag |
-| `remote_agent_sessions` | AI SDK sessions with `parent_session_id` audit chain, `transition_reason` |
-| `remote_agent_codebases` | Repository metadata, `commands` JSONB |
-| `remote_agent_isolation_environments` | Git worktree tracking, `workflow_type`, `workflow_id` |
-| `remote_agent_workflow_runs` | Execution state, `working_path`, `last_activity_at` |
-| `remote_agent_workflow_events` | Step-level event log per run |
-| `remote_agent_messages` | Conversation history, tool call metadata as JSONB |
-
-## IDatabase Interface
-
-Auto-detects at startup: PostgreSQL if `DATABASE_URL` set, SQLite (`~/.archon/archon.db`) otherwise.
-
-```typescript
-import { pool, getDialect } from './connection';  // pool = IDatabase instance
-
-// $1, $2 placeholders work for both PostgreSQL and SQLite
-const result = await pool.query<Conversation>(
-  'SELECT * FROM remote_agent_conversations WHERE id = $1',
-  [id]
-);
-const row = result.rows[0]; // rows is readonly T[]
-```
-
-Use `getDialect()` for dialect-specific expressions: `dialect.generateUuid()`, `dialect.now()`, `dialect.jsonMerge(col, paramIdx)`, `dialect.jsonArrayContains(col, path, paramIdx)`, `dialect.nowMinusDays(paramIdx)`.
-
-## Import Pattern — Namespaced Exports
-
-```typescript
-// Use namespace imports for DB modules (consistent project-wide pattern)
-import * as conversationDb from '@archon/core/db/conversations';
-import * as sessionDb from '@archon/core/db/sessions';
-import * as codebaseDb from '@archon/core/db/codebases';
-import * as workflowDb from '@archon/core/db/workflows';
-import * as messageDb from '@archon/core/db/messages';
-```
-
-## INSERT Error Handling
-
-```typescript
-try {
-  const result = await pool.query('INSERT INTO remote_agent_conversations ...', params);
-  return result.rows[0];
-} catch (error) {
-  log.error({ err: error, params }, 'db_insert_failed');
-  throw new Error('Failed to create conversation');
-}
-```
-
-## UPDATE with rowCount Verification
-
-`updateConversation()` and similar throw `ConversationNotFoundError` / `SessionNotFoundError` when `rowCount === 0`. Callers must handle:
-
-```typescript
-try {
-  await db.updateConversation(conversationId, { codebase_id: codebaseId });
-} catch (error) {
-  if (error instanceof ConversationNotFoundError) {
-    // Handle missing conversation specifically
-  }
-  throw error; // Re-throw unexpected errors
-}
-```
-
-## Session Audit Trail
-
-Sessions are immutable. Every new session links back: `parent_session_id` → previous session, `transition_reason: TransitionTrigger`. Query the chain to understand history. `active = true` means the current session.
-
-## Soft Delete
-
-Conversations use soft-delete: `deleted_at IS NULL` filter should be included in all user-facing queries. `hidden = true` conversations are worker conversations (background workflows) — excluded from UI listings.
-
-## Anti-patterns
-
-- Never `SELECT *` in production queries on large tables — select specific columns
-- Never write raw SQL strings in application code outside `packages/core/src/db/` modules
-- Never bypass the `IDatabase` interface to call database drivers directly from other packages
-- Never assume `rows[0]` exists without null-checking — queries can return empty arrays
-- Never use `RETURNING *` in UPDATE when only checking success — check `rowCount` instead

.claude/rules/dx-quirks.md

@@ -1,22 +0,0 @@
-# DX Quirks
-
-## Bun Log Elision
-
-When running `bun dev` from repo root, `--filter` truncates logs to `[N lines elided]`.
-To see full logs: `cd packages/server && bun --watch src/index.ts` or `bun --cwd packages/server run dev`.
-
-## mock.module() Pollution
-
-`mock.module()` is process-global and irreversible — `mock.restore()` does NOT undo it.
-Never add `afterAll(() => mock.restore())` for `mock.module()` cleanup.
-Use `spyOn()` for internal modules (spy.mockRestore() DOES work).
-When adding tests with `mock.module()`, ensure package.json runs it in a separate `bun test` invocation.
-
-## Worktree Port Allocation
-
-Worktrees auto-allocate ports (3190-4089 range, hash-based on path). Same worktree always gets same port.
-Main repo defaults to 3090. Override: `PORT=4000 bun dev`.
-
-## bun run test vs bun test
-
-NEVER run `bun test` from repo root — it discovers all test files across packages in one process, causing ~135 mock pollution failures. Always use `bun run test` (which uses `bun --filter '*' test` for per-package isolation).

.claude/rules/isolation-patterns.md

@@ -1,40 +0,0 @@
-# Isolation Architecture Patterns
-
-## Core Design
-
-- ALL isolation logic is centralized in the orchestrator — adapters are thin
-- Every @mention auto-creates a worktree (simplicity > efficiency; worktrees are cheap)
-- Data model is work-centric (`isolation_environments` table), enabling cross-platform sharing
-- Cleanup is a separate service using git-first checks
-
-## Directory Structure
-
-```
-~/.archon/workspaces/owner/repo/
-├── source/          # Clone or symlink to local path
-├── worktrees/       # Git worktrees for this project
-├── artifacts/       # Workflow artifacts (NEVER in git)
-│   ├── runs/{id}/   # Per-run artifacts ($ARTIFACTS_DIR)
-│   └── uploads/{convId}/  # Web UI file uploads (ephemeral)
-└── logs/            # Workflow execution logs
-```
-
-## Resolution Flow
-
-1. Adapter provides `IsolationHints` (conversationId, workflowId, branch preference)
-2. Orchestrator's `validateAndResolveIsolation()` resolves hints → environment
-3. WorktreeProvider creates worktree if needed, syncs with origin first
-4. Environment tracked in `isolation_environments` table
-
-## Key Packages
-
-- `@archon/isolation` (`packages/isolation/src/`) — types, providers, resolver, error classifiers
-- `@archon/git` (`packages/git/src/`) — branch, worktree, repo operations
-- `@archon/paths` (`packages/paths/src/`) — path resolution utilities
-
-## Safety Rules
-
-- NEVER run `git clean -fd` — permanently deletes untracked files
-- Use `classifyIsolationError()` to map git errors to user-friendly messages
-- Trust git's natural guardrails (refuse to remove worktree with uncommitted changes)
-- Use `execFileAsync` (not `exec`) when calling git directly

.claude/rules/isolation.md

@@ -1,77 +0,0 @@
----
-paths:
-  - "packages/isolation/**/*.ts"
-  - "packages/git/**/*.ts"
----
-
-# Isolation & Git Conventions
-
-## Branded Types (packages/git/src/types.ts)
-
-Always use the branded constructors — they reject empty strings at runtime and prevent passing the wrong string type:
-
-```typescript
-import { toRepoPath, toBranchName, toWorktreePath } from '@archon/git';
-import type { RepoPath, BranchName, WorktreePath } from '@archon/git';
-
-const repo = toRepoPath('/home/user/owner/repo');    // RepoPath
-const branch = toBranchName('feature-auth');          // BranchName
-const wt = toWorktreePath('/home/.archon/worktrees/x'); // WorktreePath
-```
-
-Git operations return `GitResult<T>` discriminated union: `{ ok: true; value: T }` or `{ ok: false; error: GitError }`. Always check `.ok` before accessing `.value`.
-
-## IsolationResolver — 7-Step Resolution Order
-
-1. **Existing env** — use `existingEnvId` if worktree still exists on disk
-2. **No codebase** — skip isolation entirely, return `status: 'none'`
-3. **Workflow reuse** — find active env with same `(codebaseId, workflowType, workflowId)`
-4. **Linked issue sharing** — PR can reuse the worktree from a linked issue
-5. **PR branch adoption** — find existing worktree by branch name (`findWorktreeByBranch`)
-6. **Limit check + auto-cleanup** — if at `maxWorktrees` (default 25), try `makeRoom()` first
-7. **Create new** — call `provider.create(isolationRequest)` then `store.create()`
-
-If `store.create()` fails after `provider.create()` succeeds, the orphaned worktree is cleaned up best-effort before re-throwing.
-
-## Error Handling Pattern
-
-```typescript
-import { classifyIsolationError, isKnownIsolationError } from '@archon/isolation';
-
-try {
-  await provider.create(request);
-} catch (error) {
-  const err = error instanceof Error ? error : new Error(String(error));
-  if (!isKnownIsolationError(err)) {
-    throw err; // Unknown = programming bug, propagate as crash
-  }
-  const userMessage = classifyIsolationError(err); // Maps to friendly message
-  // ...send userMessage to platform, return blocked resolution
-}
-```
-
-Known error patterns: `permission denied`, `eacces`, `timeout`, `no space left`, `enospc`, `not a git repository`, `branch not found`.
-
-`IsolationBlockedError` signals ALL message handling should stop — the user has already been notified.
-
-## Git Safety Rules
-
-- **NEVER run `git clean -fd`** — permanently deletes untracked files. Use `git checkout .` instead.
-- **Always use `execFileAsync`** (from `@archon/git/exec`), never `exec` or `execSync`
-- `hasUncommittedChanges()` returns `true` on unexpected errors (conservative — prevents data loss)
-- Worktree paths follow project-scoped layout: `~/.archon/workspaces/{owner}/{repo}/worktrees/{branch}`
-
-## Architecture
-
-- `@archon/git` — zero `@archon/*` dependencies; only branded types and `execFileAsync` wrapper
-- `@archon/isolation` — depends only on `@archon/git` + `@archon/paths`
-- `IIsolationStore` interface injected into `IsolationResolver` — never call DB directly from git package
-- `IIsolationProvider` interface — `WorktreeProvider` is the only implementation
-- Stale env cleanup is best-effort: `markDestroyedBestEffort()` logs errors but never throws
-
-## Anti-patterns
-
-- Never call `git` via `exec()` or shell string — always `execFileAsync('git', [...args])`
-- Never treat `IsolationBlockedError` as recoverable — it means user was notified, stop processing
-- Never use a plain `string` where `RepoPath` / `BranchName` / `WorktreePath` is expected
-- Never skip the `isKnownIsolationError()` check — unknown errors must propagate as crashes

.claude/rules/orchestrator.md

@@ -1,121 +0,0 @@
----
-paths:
-  - "packages/core/src/orchestrator/**/*.ts"
-  - "packages/core/src/handlers/**/*.ts"
-  - "packages/core/src/state/**/*.ts"
----
-
-# Orchestrator Conventions
-
-## Message Flow — Routing Agent Architecture
-
-```
-Platform message
-  → ConversationLockManager.acquireLock()
-  → handleMessage() (orchestrator-agent.ts:383)
-      → inheritThreadContext() — copy parent's codebase/cwd if child thread
-      → Deterministic gate: 10 commands (help, status, reset, workflow, register-project, update-project, remove-project, commands, init, worktree)
-      → Everything else → AI routing call:
-          → listCodebases() + discoverAllWorkflows()
-          → buildFullPrompt() → buildOrchestratorPrompt() or buildProjectScopedPrompt()
-          → AI responds with natural language ± /invoke-workflow or /register-project
-          → parseOrchestratorCommands() extracts structured commands from AI response
-          → If /invoke-workflow found → dispatchOrchestratorWorkflow()
-          → If /register-project found → handleRegisterProject()
-          → Otherwise → send AI text to user
-```
-
-Lock manager returns `{ status: 'started' | 'queued-conversation' | 'queued-capacity' }`. Always use the return value to decide whether to emit a "queued" notice — never call `isActive()` separately (TOCTOU race).
-
-## Deterministic Commands (command-handler.ts)
-
-Only **10 commands** are handled deterministically:
-
-| Command | Behavior |
-|---------|----------|
-| `/help` | Show available commands |
-| `/status` | Show conversation/session state |
-| `/reset` | Deactivate current session |
-| `/workflow` | Subcommands: `list`, `run`, `status`, `cancel`, `reload` |
-| `/register-project` | Handled inline — creates codebase DB record |
-| `/update-project` | Handled inline — updates codebase path |
-| `/remove-project` | Handled inline — deletes codebase DB record |
-| `/commands` | List registered codebase commands |
-| `/init` | Scaffold `.archon/` in current repo |
-| `/worktree` | Worktree subcommands |
-
-**All other slash commands fall through to the AI router.** Unrecognized commands return an "Unknown command" error.
-
-## Routing AI — Prompt Building (prompt-builder.ts)
-
-The choice between prompts depends on whether the conversation has an attached project:
-
-- **No project** → `buildOrchestratorPrompt()` (prompt-builder.ts:116) — lists all projects equally, asks user to clarify if ambiguous
-- **Has project** → `buildProjectScopedPrompt()` (prompt-builder.ts:153) — active project shown first, ambiguous requests default to it
-
-Both prompts include: registered projects, discovered workflows, and the `/invoke-workflow` + `/register-project` format specification.
-
-### `/invoke-workflow` Protocol
-
-The AI emits: `/invoke-workflow <name> --project <project> --prompt "user's intent"`
-
-`parseOrchestratorCommands()` (orchestrator-agent.ts:90) parses this with:
-- Workflow name validated against discovered workflows via `findWorkflow()`
-- Project name validated via `findCodebaseByName()` — case-insensitive, supports partial path segment match (e.g., `"repo"` matches `"owner/repo"`)
-- `--project` must appear before `--prompt`
-
-### `filterToolIndicators()` (orchestrator-agent.ts:163)
-
-Batch mode only. Strips paragraphs starting with emoji tool indicators (🔧💭📝✏️🗑️📂🔍) from accumulated AI response before sending to user.
-
-## Session Transitions
-
-Sessions are **immutable** — never mutated, only deactivated and replaced. The audit trail is via `parent_session_id` + `transition_reason`.
-
-**Only `plan-to-execute` immediately creates a new session.** All other triggers only deactivate; the new session is created on the next AI message.
-
-```typescript
-import { getTriggerForCommand, shouldCreateNewSession } from '../state/session-transitions';
-
-const trigger = getTriggerForCommand('reset'); // 'reset-requested'
-if (shouldCreateNewSession(trigger)) {
-  // plan-to-execute only
-}
-```
-
-`TransitionTrigger` values: `'first-message'`, `'plan-to-execute'`, `'isolation-changed'`, `'reset-requested'`, `'worktree-removed'`, `'conversation-closed'`.
-
-## Isolation Resolution
-
-`validateAndResolveIsolation()` (orchestrator.ts:108) delegates to `IsolationResolver` and handles:
-- Sending contextual messages to the platform (e.g., "Reusing worktree from issue #42")
-- Updating the DB (`conversation.isolation_env_id`, `conversation.cwd`)
-- Retrying once when a stale reference is found (`stale_cleaned`)
-- Throwing `IsolationBlockedError` after platform notification when blocked
-
-When isolation is blocked, **stop all further processing** — `IsolationBlockedError` means the user was already notified.
-
-## Background Workflow Dispatch (Web only)
-
-`dispatchBackgroundWorkflow()` (orchestrator.ts:256) creates a hidden worker conversation (`web-worker-{timestamp}-{random}`), sets up event bridging from worker SSE → parent SSE, pre-creates the workflow run row (prevents 404 on immediate UI navigation), and fires-and-forgets `executeWorkflow()`. On completion, surfaces `result.summary` to the parent conversation.
-
-## Lazy Logger Pattern
-
-All files in this area use the deferred logger pattern — NEVER initialize at module scope:
-
-```typescript
-let cachedLog: ReturnType<typeof createLogger> | undefined;
-function getLog(): ReturnType<typeof createLogger> {
-  if (!cachedLog) cachedLog = createLogger('orchestrator');
-  return cachedLog;
-}
-```
-
-## Anti-patterns
-
-- Never call `isActive()` and then `acquireLock()` — race condition, use the lock return value
-- Never access `conversation.isolation_env_id` directly without going through the resolver
-- Never skip `IsolationBlockedError` — it must propagate to stop all further message handling
-- Never add platform-specific logic to the orchestrator; it uses `IPlatformAdapter` interface only
-- Never transition sessions by mutating them; always deactivate and create a new linked session
-- Never assume a slash command is deterministic — only the 10 listed above bypass the AI router

.claude/rules/server-api.md

@@ -1,109 +0,0 @@
----
-paths:
-  - "packages/server/**/*.ts"
----
-
-# Server API Conventions
-
-## Hono Framework
-
-```typescript
-import { Hono } from 'hono';
-import { streamSSE } from 'hono/streaming';
-import { cors } from 'hono/cors';
-
-// CORS: allow-all for single-developer tool (override with WEB_UI_ORIGIN)
-app.use('/api/*', cors({ origin: process.env.WEB_UI_ORIGIN || '*' }));
-
-// Error response helper pattern
-function apiError(c: Context, status: 400 | 404 | 500, message: string): Response {
-  return c.json({ error: message }, status);
-}
-```
-
-## SSE Streaming
-
-Always check `stream.closed` before writing. Use `stream.onAbort()` for cleanup. Hono's `streamSSE` callback receives an SSE writer:
-
-```typescript
-app.get('/api/stream/:id', (c) => {
-  return streamSSE(c, async (stream) => {
-    stream.onAbort(() => {
-      transport.removeStream(conversationId, writer);
-    });
-    // Write events:
-    if (!stream.closed) {
-      await stream.writeSSE({ data: JSON.stringify(event) });
-    }
-  });
-});
-```
-
-`SSETransport` in `src/adapters/web/transport.ts` manages the stream registry. `removeStream()` accepts an `expectedStream` reference to prevent race conditions (StrictMode double-mount).
-
-## Webhook Signature Verification
-
-```typescript
-// ALWAYS use c.req.text() for raw webhook body — JSON.parse separately
-const payload = await c.req.text();
-const signature = c.req.header('X-Hub-Signature-256') ?? '';
-
-// timingSafeEqual prevents timing attacks
-const hmac = createHmac('sha256', webhookSecret);
-const digest = 'sha256=' + hmac.update(payload).digest('hex');
-const isValid = timingSafeEqual(Buffer.from(digest), Buffer.from(signature));
-```
-
-Return 200 immediately for webhook events; process async. Never log the full signature.
-
-## Auto Port Allocation (Worktrees)
-
-`getPort()` from `@archon/core` returns:
-- Main repo: `PORT` env var or `3090`
-- Worktrees: hash-based port in range 3190–4089 (deterministic per worktree path)
-
-Same worktree always gets same port. Override with `PORT=4000` env var.
-
-## Static SPA Fallback
-
-```typescript
-// Serve web dist; fall back to index.html for client-side routing
-app.use('/*', serveStatic({ root: path.join(import.meta.dir, '../../web/dist') }));
-app.get('*', (c) => c.html(/* index.html */));
-```
-
-Use `import.meta.dir` (absolute) NOT relative paths — `bun --filter @archon/server start` changes CWD to `packages/server/`.
-
-## Graceful Shutdown
-
-```typescript
-process.on('SIGTERM', () => {
-  stopCleanupScheduler();
-  void pool.close();
-  process.exit(0);
-});
-```
-
-## Key API Routes
-
-| Method | Path | Purpose |
-|--------|------|---------|
-| GET | `/api/conversations` | List conversations |
-| POST | `/api/conversations` | Create conversation |
-| POST | `/api/conversations/:id/message` | Send message |
-| GET | `/api/stream/:id` | SSE stream |
-| GET | `/api/workflows` | List workflows |
-| POST | `/api/workflows/validate` | Validate YAML (in-memory) |
-| GET | `/api/workflows/:name` | Get single workflow |
-| PUT | `/api/workflows/:name` | Save workflow |
-| DELETE | `/api/workflows/:name` | Delete workflow |
-| GET | `/api/commands` | List commands |
-| POST | `/webhooks/github` | GitHub webhook |
-
-## Anti-patterns
-
-- Never use `c.req.json()` for webhooks — signature must be verified against raw body
-- Never expose API keys in JSON error responses
-- Never serve static files with relative paths (use `import.meta.dir`)
-- Never skip the `stream.closed` check before writing SSE
-- Never call platform adapters directly from route handlers — use `handleMessage()` + lock manager

.claude/rules/testing.md

@@ -1,105 +0,0 @@
----
-paths:
-  - "**/*.test.ts"
-  - "**/*.spec.ts"
----
-
-# Testing Conventions
-
-## CRITICAL: mock.module() Pollution Rules
-
-`mock.module()` permanently replaces modules in the **process-wide module cache**. `mock.restore()` does NOT undo it ([oven-sh/bun#7823](https://github.com/oven-sh/bun/issues/7823)).
-
-**Rules:**
-1. **Never add `afterAll(() => mock.restore())` for `mock.module()` calls** — it has no effect
-2. **Never have two test files `mock.module()` the same path with different implementations in the same `bun test` invocation**
-3. **Use `spyOn()` for internal modules** — `spy.mockRestore()` DOES work for spies
-
-```typescript
-// CORRECT: spy (restorable)
-import * as git from '@archon/git';
-const spy = spyOn(git, 'checkout');
-spy.mockImplementation(async () => ({ ok: true, value: undefined }));
-// afterEach:
-spy.mockRestore();
-
-// CORRECT: mock.module() for external deps (not restorable — isolate in separate test file)
-mock.module('@slack/bolt', () => ({ App: mock(() => mockApp), LogLevel: { INFO: 'info' } }));
-```
-
-## Test Batching Per Package
-
-Each package splits tests into separate `bun test` invocations to prevent pollution:
-
-| Package | Batches |
-|---------|---------|
-| `@archon/core` | 7 batches (clients, handlers, db+utils, path-validation, cleanup-service, title-generator, workflows, orchestrator) |
-| `@archon/workflows` | 5 batches |
-| `@archon/adapters` | 3 batches (chat+community+forge-auth, github-adapter, github-context) |
-| `@archon/isolation` | 3 batches |
-
-**Never run `bun test` from the repo root** — causes ~135 mock pollution failures. Always use:
-
-```bash
-bun run test           # Correct: per-package isolation via bun --filter '*' test
-bun run test --watch   # Watch mode (single package)
-```
-
-## Mock Pattern for Lazy Loggers
-
-All adapter/db/orchestrator files use lazy logger pattern. Mock before import:
-
-```typescript
-// MUST come before import of the module under test
-const mockLogger = {
-  fatal: mock(() => undefined), error: mock(() => undefined),
-  warn: mock(() => undefined),  info: mock(() => undefined),
-  debug: mock(() => undefined), trace: mock(() => undefined),
-};
-mock.module('@archon/paths', () => ({ createLogger: mock(() => mockLogger) }));
-
-import { SlackAdapter } from './adapter'; // Import AFTER mock
-```
-
-## Database Test Mocking
-
-```typescript
-import { createQueryResult, mockPostgresDialect } from '../test/mocks/database';
-
-const mockQuery = mock(() => Promise.resolve(createQueryResult([])));
-mock.module('./connection', () => ({
-  pool: { query: mockQuery },
-  getDialect: () => mockPostgresDialect,
-}));
-
-// In tests:
-mockQuery.mockResolvedValueOnce(createQueryResult([existingRow]));
-mockQuery.mockClear(); // in beforeEach
-```
-
-## Test Structure
-
-```typescript
-import { describe, test, expect, mock, beforeEach, afterEach } from 'bun:test';
-
-describe('ComponentName', () => {
-  beforeEach(() => {
-    mockFn.mockClear(); // Reset call counts
-  });
-
-  test('does thing when condition', async () => {
-    mockQuery.mockResolvedValueOnce(createQueryResult([fixture]));
-    const result = await functionUnderTest(input);
-    expect(result).toEqual(expected);
-    expect(mockQuery).toHaveBeenCalledTimes(1);
-  });
-});
-```
-
-## Anti-patterns
-
-- Never `import` a module before all `mock.module()` calls for its dependencies
-- Never use `afterAll(() => mock.restore())` for `mock.module()` — it silently does nothing
-- Never test with real database or filesystem in unit tests — always mock
-- Never run `bun test` from the repo root
-- Never add a new test file with conflicting `mock.module()` to an existing batch — create a new batch in the package's `package.json` test script

.claude/rules/web-frontend.md

@@ -1,90 +0,0 @@
----
-paths:
-  - "packages/web/**/*.tsx"
-  - "packages/web/**/*.ts"
-  - "packages/web/**/*.css"
----
-
-# Web Frontend Conventions
-
-## Tech Stack
-
-- React 19 + Vite 6 + TypeScript
-- Tailwind CSS v4 (CSS-first config)
-- shadcn/ui components
-- TanStack Query v5 for REST data
-- React Router v7 (`react-router`, NOT `react-router-dom`)
-- Manual `EventSource` for SSE streaming (no library)
-- **Dark theme only** — no light mode toggle
-
-## Tailwind v4 Critical Differences
-
-```css
-/* CORRECT: CSS-first import */
-@import 'tailwindcss';
-@import 'tw-animate-css';  /* NOT tailwindcss-animate */
-
-/* CORRECT: theme variables in @theme inline block */
-@theme inline {
-  --color-surface: var(--surface);
-  --color-accent-bright: var(--accent-bright);
-}
-
-/* WRONG: never use @tailwind base/components/utilities */
-```
-
-Plugin in `vite.config.ts`: `import tailwindcss from '@tailwindcss/vite'` — uses Vite plugin, **not PostCSS**. `components.json` has blank `tailwind.config` for v4.
-
-## Color Palette (oklch)
-
-All custom colors are OKLCH. Key tokens (defined in `:root` in `index.css`):
-- `--surface` (0.18): main surface
-- `--surface-elevated` (0.22): cards, popovers
-- `--background` (0.14): page background
-- `--primary` / `--ring`: blue accent at oklch(0.65 0.18 250)
-- `--text-primary` (0.93), `--text-secondary` (0.65), `--text-tertiary` (0.45)
-- `--success` (green 155), `--warning` (yellow 75), `--error` (red 25)
-
-Use CSS variables via Tailwind utilities: `bg-surface`, `text-text-primary`, `border-border`, `text-accent-bright`, etc.
-
-## SSE Streaming Pattern
-
-`useSSE()` in `src/hooks/useSSE.ts` is the single SSE consumer. It:
-- Opens `EventSource` to `/api/stream/{conversationId}`
-- Batches text events (50ms flush timer) to reduce re-renders
-- Flushes immediately before `tool_call`, `tool_result`, `workflow_dispatch` events
-- Marks disconnected only on `CLOSED` state (not `CONNECTING` — avoids flicker)
-- `handlersRef` pattern ensures stable EventSource with fresh handlers
-
-Event types: `text`, `tool_call`, `tool_result`, `error`, `conversation_lock`, `session_info`, `workflow_step`, `workflow_status`, `parallel_agent`, `workflow_artifact`, `dag_node`, `workflow_dispatch`, `workflow_output_preview`, `warning`, `retract`, `heartbeat`.
-
-## Routing
-
-```tsx
-// CORRECT
-import { BrowserRouter, Routes, Route } from 'react-router';
-// WRONG
-import { BrowserRouter } from 'react-router-dom';
-```
-
-Routes: `/` (Dashboard), `/chat`, `/chat/*`, `/workflows`, `/workflows/builder`, `/workflows/runs/:runId`, `/settings`.
-
-## API Client Pattern
-
-```typescript
-// src/lib/api.ts exports SSE_BASE_URL and REST functions
-import { SSE_BASE_URL } from '@/lib/api';
-// In dev: Vite proxies /api/* to localhost:{VITE_API_PORT}
-// API port injected at build time: import.meta.env.VITE_API_PORT
-```
-
-TanStack Query `staleTime: 10_000`, `refetchOnWindowFocus: true`.
-
-## Anti-patterns
-
-- Never add a light mode — dark-only is intentional
-- Never use `react-router-dom` — use `react-router` (v7)
-- Never configure Tailwind in `tailwind.config.js/ts` — v4 is CSS-first
-- Never use `tailwindcss-animate` — use `tw-animate-css`
-- Never open a second `EventSource` per conversation — `useSSE()` handles it
-- Never pass inline style objects for theme colors — use Tailwind classes with CSS variables

.claude/rules/workflows.md

@@ -1,100 +0,0 @@
----
-paths:
-  - "packages/workflows/**/*.ts"
-  - ".archon/workflows/**/*.yaml"
-  - ".archon/commands/**/*.md"
----
-
-# Workflows Conventions
-
-## DAG Workflow Format
-
-All workflows use the DAG (Directed Acyclic Graph) format with `nodes:`. Loop nodes are supported as a node type within DAGs.
-
-```yaml
-nodes:
-  - id: classify
-    prompt: "Is this a bug or feature? Answer JSON: {type: 'BUG'|'FEATURE'}"
-    output_format: {type: object, properties: {type: {type: string}}}
-  - id: implement
-    command: execute
-    depends_on: [classify]
-    when: "$classify.output.type == 'FEATURE'"
-  - id: run_lint
-    bash: "bun run lint"
-    depends_on: [implement]
-  - id: iterate
-    loop:
-      until: "COMPLETE"
-      max_iterations: 10
-    prompt: "Iterate until the tests pass. Signal COMPLETE when done."
-    depends_on: [run_lint]
-```
-
-## Variable Substitution
-
-| Variable | Resolved to |
-|----------|-------------|
-| `$1`, `$2`, `$3` | Positional arguments from user message |
-| `$ARGUMENTS` | All user arguments as single string |
-| `$ARTIFACTS_DIR` | Pre-created external artifacts directory |
-| `$WORKFLOW_ID` | Current workflow run ID |
-| `$BASE_BRANCH` | Base branch from config or auto-detected |
-| `$DOCS_DIR` | Documentation directory path (default: `docs/`) |
-| `$nodeId.output` | Captured stdout/AI output from completed DAG node |
-
-## WorkflowDeps — Dependency Injection
-
-`@archon/workflows` has ZERO `@archon/core` dependency. Everything is injected:
-
-```typescript
-interface WorkflowDeps {
-  store: IWorkflowStore;                           // DB abstraction
-  getAssistantClient: AssistantClientFactory;       // Returns claude or codex client
-  loadConfig: (cwd: string) => Promise<WorkflowConfig>;
-}
-
-// Core creates the adapter:
-import { createWorkflowDeps } from '@archon/core/workflows/store-adapter';
-const deps = createWorkflowDeps();
-await executeWorkflow(deps, platform, conversationId, cwd, workflow, ...);
-```
-
-## DAG Node Types
-
-- `command:` — named file from `.archon/commands/`, AI-executed
-- `prompt:` — inline prompt string, AI-executed
-- `bash:` — shell script, no AI; stdout captured as `$nodeId.output`; default timeout 120000ms
-
-DAG node options: `depends_on`, `when` (condition expression), `trigger_rule` (`all_success` | `one_success` | `none_failed_min_one_success` | `all_done`), `output_format` (JSON Schema, Claude only), `allowed_tools` / `denied_tools` (Claude only), `idle_timeout` (ms), `context: 'fresh'`, per-node `provider` and `model`.
-
-## Event Emitter for Observability
-
-```typescript
-import { getWorkflowEventEmitter } from '@archon/workflows';
-
-const emitter = getWorkflowEventEmitter();
-emitter.registerRun(runId, conversationId);
-
-// Subscribe (returns unsubscribe fn)
-const unsubscribe = emitter.subscribeForConversation(conversationId, (event) => {
-  // event.type: 'step_started' | 'step_completed' | 'node_started' | ...
-});
-```
-
-Listener errors never propagate to the executor — fire-and-forget with internal catch.
-
-## Architecture
-
-- Model validation at load time — invalid provider/model combinations fail `parseWorkflow()` with clear error
-- Resilient discovery — one broken YAML doesn't abort `discoverWorkflows()`; errors returned in `WorkflowLoadResult.errors`
-- Bundled defaults embedded in binary builds; loaded from filesystem in source builds
-- Repo workflows override bundled defaults by name
-- Router fallback: if no `/invoke-workflow` produced → falls back to `archon-assist`; raw AI response only when `archon-assist` unavailable
-
-## Anti-patterns
-
-- Never import `@archon/core` from `@archon/workflows` (circular dependency)
-- Never add `clearContext: true` to every step — context continuity is valuable; use sparingly
-- Never put `output_format` on Codex nodes — it logs a warning and is ignored
-- Never set `allowed_tools: undefined` expecting "no tools" — use `allowed_tools: []` for that

.claude/skills/archon/guides/setup.md

@@ -119,9 +119,11 @@ If Bun was just installed in Prerequisites (macOS/Linux), use `~/.bun/bin/bun` i
 3. Verify: `archon version`
 4. Check Claude is installed: `which claude`, then `claude /login` if needed
 
+> **Note — Claude Code binary path.** Archon does not bundle Claude Code. In compiled Archon binaries (quick install, Homebrew), the Claude Code SDK needs `CLAUDE_BIN_PATH` set to the absolute path of its `cli.js`. The `archon setup` wizard in Step 4 auto-detects this via `npm root -g` and writes it to `~/.archon/.env` — no manual action needed in the typical case. Source installs (`bun run`) don't need this; the SDK finds `cli.js` via `node_modules` automatically.
+
 ## Step 4: Configure Credentials
 
-The CLI loads infrastructure config (database, tokens) from `~/.archon/.env` only. This prevents conflicts with project `.env` files that may contain different database URLs.
+Archon loads infrastructure config (database, tokens) from two archon-owned files — `~/.archon/.env` (user scope) and `<cwd>/.archon/.env` (repo scope, overrides user). The project's own `<cwd>/.env` is stripped at boot so it cannot leak into Archon; `archon setup` never writes to it.
 
 Credential configuration runs in a separate terminal so your API keys stay private — the AI assistant won't see them.
 
@@ -144,7 +146,7 @@ Tell the user:
 > 2. AI assistant configuration (Claude and/or Codex)
 > 3. Platform tokens for any integrations you selected
 >
-> It saves configuration to both `~/.archon/.env` and the repo `.env`."
+> By default it saves to `~/.archon/.env` (user scope). Re-run with `archon setup --scope project` to write `<repo>/.archon/.env` instead (project overrides user for this repo). Existing values are preserved — a timestamped backup is written before every rewrite."
 
 **If the terminal opened automatically**, add:
 > "Complete the wizard in the new terminal window that just opened."
@@ -158,7 +160,7 @@ Both paths are normal — the manual path is not an error.
 
 Wait for the user to confirm they've completed the setup wizard before proceeding.
 
-### 5c: Verify Configuration
+### 4c: Verify Configuration
 
 After the user confirms setup is complete:
 
@@ -170,7 +172,7 @@ Should show:
 - `Database: sqlite` (default, zero setup) or `Database: postgresql` (if DATABASE_URL was configured)
 - No errors about missing configuration
 
-### 5d: Run Database Migrations (PostgreSQL only)
+### 4d: Run Database Migrations (PostgreSQL only)
 
 **SQLite users: skip this step.** SQLite is auto-initialized on first run with zero setup.
 
@@ -299,16 +301,21 @@ For advanced users — these are not needed for basic setup:
 
 ### Environment Files (`.env`)
 
-Infrastructure config (database URL, platform tokens) is stored in `.env` files:
+Archon's env model is scoped by directory ownership: `.archon/` is archon-owned, anything else belongs to you.
 
-| Location | Used by | Purpose |
-|----------|---------|---------|
-| `~/.archon/.env` | **CLI** | Global infrastructure config — database, AI tokens |
-| `<archon-repo>/.env` | **Server** | Platform tokens for Telegram/Slack/GitHub/Discord |
+| Path | Stripped at boot? | Archon loads? | `archon setup` writes? |
+|------|-------------------|---------------|------------------------|
+| `<cwd>/.env` | **yes** (safety guard) | never | never |
+| `<cwd>/.archon/.env` | no | yes (project scope, overrides user scope) | yes iff `--scope project` |
+| `~/.archon/.env` | no | yes (user scope) | yes iff `--scope home` (default) |
 
-**Best practice**: Use `~/.archon/.env` as the single source of truth. Symlink or copy to `<archon-repo>/.env` if running the server.
+**Which should I use?**
 
-**Note**: The CLI does NOT load `.env` from the current working directory. This prevents conflicts when running Archon from projects that have their own database configurations.
+- `~/.archon/.env` — defaults that apply everywhere (your personal `SLACK_WEBHOOK`, `DATABASE_URL`, bot tokens).
+- `<cwd>/.archon/.env` — per-project overrides (different webhook per repo, different DB per environment).
+- `<cwd>/.env` — your app's env file; archon strips these keys at boot so nothing leaks between your app and archon.
+
+`archon setup` writes to exactly one archon-owned file chosen by `--scope` (default `home`), merges into existing content so user-added keys survive, and writes a timestamped backup before every rewrite. Use `--force` to opt into wholesale overwrite (backup still written).
 
 ### Config Files (YAML)
 

.claude/skills/archon/references/workflow-dag.md

@@ -170,7 +170,7 @@ Command/prompt nodes only:
     required: [issue_type]
 ```
 
-Enables `$classify.output.issue_type` field access. Works with Claude and Codex.
+Enables `$classify.output.issue_type` field access. SDK-enforced on Claude and Codex; best-effort on Pi (schema is appended to the prompt and JSON is parsed out of the result text).
 
 ## Per-Node Provider and Model
 

.claude/skills/release/SKILL.md

@@ -97,13 +97,16 @@ Read the commit messages and the actual diffs (`git diff main..dev`) to understa
    - `pyproject.toml`: update `version = "x.y.z"`
    - `Cargo.toml`: update `version = "x.y.z"`
 
-2. **Lockfile refresh** (stack-dependent):
+2. **Workspace version sync** (monorepo only):
+   - If `scripts/sync-versions.sh` exists, run `bash scripts/sync-versions.sh` to sync all `packages/*/package.json` versions to match the root version.
+
+3. **Lockfile refresh** (stack-dependent):
    - `package.json` + `bun.lock`: run `bun install`
    - `package.json` + `package-lock.json`: run `npm install --package-lock-only`
    - `pyproject.toml` + `uv.lock`: run `uv lock --quiet`
    - `Cargo.toml`: run `cargo update --workspace`
 
-3. **`CHANGELOG.md`** — prepend new version section:
+4. **`CHANGELOG.md`** — prepend new version section:
 
 ```markdown
 ## [x.y.z] - YYYY-MM-DD
@@ -141,8 +144,8 @@ Ask: "Does this look good? I'll commit and create the PR."
 Only after user approval:
 
 ```bash
-# Stage version file, lockfile, and changelog
-git add <version-file> <lockfile> CHANGELOG.md
+# Stage version file, workspace packages, lockfile, and changelog
+git add <version-file> packages/*/package.json <lockfile> CHANGELOG.md
 git commit -m "Release x.y.z"
 
 # Push dev
@@ -186,12 +189,22 @@ git pull origin main
 git push origin dev
 ```
 
+> **Important**: This sync ensures dev has the merge commit from main. Without it,
+> dev and main diverge. The CI `update-homebrew` job only pushes the formula
+> commit to dev — it does not bring the PR merge commit onto dev. This manual
+> `git pull origin main` is what ensures dev has the merge commit.
+
 The GitHub Release is distinct from the git tag — without it, the release won't appear on the repository's Releases page. Always create it.
 
 If the user merges the PR themselves and comes back, still offer to tag, release, and sync.
 
 ### Step 10: Wait for Release Workflow and Update Homebrew Formula
 
+> **Note**: The `update-homebrew` CI job in `.github/workflows/release.yml` runs automatically
+> after the release job and handles the formula update + push to dev (part of Step 10).
+> Step 11 (tap sync to `coleam00/homebrew-archon`) is always manual. Check the Actions tab
+> before running Step 10 manually.
+
 After the tag is pushed, `.github/workflows/release.yml` builds platform binaries and uploads them to the GitHub release. This takes 5-10 minutes. The Homebrew formula SHA256 values cannot be known until these binaries exist.
 
 **Wait for all assets to appear on the release:**
@@ -200,16 +213,16 @@ After the tag is pushed, `.github/workflows/release.yml` builds platform binarie
 echo "Waiting for release workflow to finish uploading binaries..."
 for i in {1..30}; do
   ASSET_COUNT=$(gh release view "vx.y.z" --repo coleam00/Archon --json assets --jq '.assets | length')
-  # Expect 6 assets: 5 binaries (darwin-arm64, darwin-x64, linux-arm64, linux-x64, windows-x64.exe) + checksums.txt
-  if [ "$ASSET_COUNT" -ge 6 ]; then
+  # Expect 7 assets: 5 binaries (darwin-arm64, darwin-x64, linux-arm64, linux-x64, windows-x64.exe) + archon-web.tar.gz + checksums.txt
+  if [ "$ASSET_COUNT" -ge 7 ]; then
     echo "All $ASSET_COUNT assets uploaded"
     break
   fi
-  echo "  Assets so far: $ASSET_COUNT/6 — waiting 30s (attempt $i/30)..."
+  echo "  Assets so far: $ASSET_COUNT/7 — waiting 30s (attempt $i/30)..."
   sleep 30
 done
 
-if [ "$ASSET_COUNT" -lt 6 ]; then
+if [ "$ASSET_COUNT" -lt 7 ]; then
   echo "ERROR: Release workflow did not finish uploading assets after 15 minutes"
   echo "Check https://github.com/coleam00/Archon/actions for the release workflow run"
   exit 1

.claude/skills/test-release/SKILL.md

@@ -222,7 +222,23 @@ git commit -q --allow-empty -m init
 
 ### Test 3 — SDK path works (assist workflow)
 
-In the same `$TESTREPO`:
+**Prerequisite.** Compiled binaries require Claude Code installed on the host and a configured binary path. Before running this test, ensure one of:
+
+```bash
+# Option A — env var (easy for ad-hoc testing)
+# After the native installer (Anthropic's default):
+export CLAUDE_BIN_PATH="$HOME/.local/bin/claude"
+# Or after npm global install:
+export CLAUDE_BIN_PATH="$(npm root -g)/@anthropic-ai/claude-code/cli.js"
+
+# Option B — config file (persistent)
+#   Add to ~/.archon/config.yaml:
+#   assistants:
+#     claude:
+#       claudeBinaryPath: /absolute/path/to/claude
+```
+
+Then in the same `$TESTREPO`:
 
 ```bash
 "$BINARY" workflow run assist "say hello and nothing else" 2>&1 | tee /tmp/archon-test-assist.log
@@ -232,15 +248,34 @@ In the same `$TESTREPO`:
 
 - Exit code 0
 - The Claude subprocess spawns successfully (no `spawn EACCES`, `ENOENT`, or `process exited with code 1` in the early output)
+- No `Claude Code CLI not found` error (that means the resolver rejected the configured path — verify the cli.js actually exists)
 - A response is produced (any response — even just "hello" — proves the SDK round-trip works)
 
 **Common failures:**
 
+- `Claude Code not found` → `CLAUDE_BIN_PATH` / `claudeBinaryPath` is unset or points at a non-existent file. Fix the path and re-run.
+- `Module not found "/Users/runner/..."` → regression of #1210: the resolver was bypassed and the SDK's `import.meta.url` fallback leaked a build-host path. Investigate `packages/providers/src/claude/provider.ts` and the resolver.
 - `Credit balance is too low` → auth is pointing at an exhausted API key (check `CLAUDE_USE_GLOBAL_AUTH` and `~/.archon/.env`)
 - `unable to determine transport target for "pino-pretty"` → #960 regression, binary crashes on TTY
 - `package.json not found (bad installation?)` → #961 regression, `isBinaryBuild` detection broken
 - Process exits before producing output → generic spawn failure, capture stderr
 
+### Test 3b — Resolver error path (run without `CLAUDE_BIN_PATH`)
+
+Quickly verify the resolver fails loud when nothing is configured:
+
+```bash
+(unset CLAUDE_BIN_PATH; "$BINARY" workflow run assist "hello" 2>&1 | tee /tmp/archon-test-no-path.log)
+```
+
+**Pass criteria (when no `~/.archon/config.yaml` configures `claudeBinaryPath`):**
+
+- Error message contains `Claude Code not found`
+- Error message mentions both `CLAUDE_BIN_PATH` and `claudeBinaryPath` as remediation options
+- No `Module not found` stack traces referencing the CI filesystem
+
+If you *do* have `claudeBinaryPath` set globally, skip this test or temporarily rename `~/.archon/config.yaml`.
+
 ### Test 4 — Env-leak gate refuses a leaky .env (optional, for releases including #1036/#1038/#983)
 
 Create a second throwaway repo with a fake sensitive key:

.env.example

@@ -14,6 +14,20 @@ CLAUDE_USE_GLOBAL_AUTH=true
 # CLAUDE_CODE_OAUTH_TOKEN=...
 # CLAUDE_API_KEY=...
 
+# Claude Code executable path (REQUIRED for compiled Archon binaries)
+# Archon does not bundle Claude Code — install it separately and point us at it.
+# Dev mode (`bun run`) auto-resolves via node_modules.
+# Alternatively, set `assistants.claude.claudeBinaryPath` in ~/.archon/config.yaml.
+#
+# Install (Anthropic's recommended native installer):
+#   macOS/Linux: curl -fsSL https://claude.ai/install.sh | bash
+#   Windows:     irm https://claude.ai/install.ps1 | iex
+#
+# Then:
+#   CLAUDE_BIN_PATH=$HOME/.local/bin/claude       (native installer)
+#   CLAUDE_BIN_PATH=$(npm root -g)/@anthropic-ai/claude-code/cli.js  (npm alternative)
+# CLAUDE_BIN_PATH=
+
 # Codex Authentication (get from ~/.codex/auth.json after running 'codex login')
 # Required if using Codex as AI assistant
 # On Linux/Mac: cat ~/.codex/auth.json
@@ -22,9 +36,29 @@ CODEX_ID_TOKEN=
 CODEX_ACCESS_TOKEN=
 CODEX_REFRESH_TOKEN=
 CODEX_ACCOUNT_ID=
+# CODEX_BIN_PATH=  # Optional: path to Codex native binary (binary builds only)
 
-# Default AI Assistant (claude | codex)
-# Used for new conversations when no codebase specified
+# Pi (community provider — @mariozechner/pi-coding-agent)
+# One adapter, ~20 LLM backends. Archon's Pi adapter picks up credentials
+# you've already configured via the Pi CLI (`pi /login` writes to
+# ~/.pi/agent/auth.json), plus these env vars for backends you haven't
+# logged into via OAuth. Env vars override auth.json per-request.
+#
+# Use by setting `provider: pi` and `model: <pi-provider-id>/<model-id>` in
+# workflow YAML or `.archon/config.yaml` (e.g. model: google/gemini-2.5-pro).
+#
+# ANTHROPIC_API_KEY=           # Pi provider id: anthropic
+# OPENAI_API_KEY=              # Pi provider id: openai
+# GEMINI_API_KEY=              # Pi provider id: google
+# GROQ_API_KEY=                # Pi provider id: groq
+# MISTRAL_API_KEY=             # Pi provider id: mistral
+# CEREBRAS_API_KEY=            # Pi provider id: cerebras
+# XAI_API_KEY=                 # Pi provider id: xai
+# OPENROUTER_API_KEY=          # Pi provider id: openrouter
+# HUGGINGFACE_API_KEY=         # Pi provider id: huggingface
+
+# Default AI Assistant (must match a registered provider, e.g. claude, codex, pi)
+# Used for new conversations when no codebase specified — errors on unknown values
 DEFAULT_AI_ASSISTANT=claude
 
 # Title Generation Model (optional)
@@ -118,7 +152,7 @@ GITEA_ALLOWED_USERS=
 # GITEA_BOT_MENTION=archon
 
 # Server
-PORT=3000
+# PORT=3090  # Default: 3090. Uncomment to override — must match between server and Vite proxy.
 # HOST=0.0.0.0  # Bind address (default: 0.0.0.0). Set to 127.0.0.1 to restrict to localhost only.
 
 # Cloud Deployment (for --profile cloud with Caddy reverse proxy)
@@ -172,3 +206,17 @@ MAX_CONCURRENT_CONVERSATIONS=10  # Maximum concurrent AI conversations (default:
 
 # Session Retention
 # SESSION_RETENTION_DAYS=30  # Delete inactive sessions older than N days (default: 30)
+
+# Anonymous Telemetry (optional)
+# Archon sends anonymous workflow-invocation events to PostHog so maintainers
+# can see which workflows get real usage. No PII — workflow name/description +
+# platform + Archon version + a random install UUID. No identities, no prompts,
+# no paths, no code. See README "Telemetry" for the full list.
+#
+# Opt out (any one disables telemetry):
+#   ARCHON_TELEMETRY_DISABLED=1
+#   DO_NOT_TRACK=1                          (de facto standard)
+#
+# Point at a self-hosted PostHog or a different project:
+#   POSTHOG_API_KEY=phc_yourKeyHere
+#   POSTHOG_HOST=https://eu.i.posthog.com   (default: https://us.i.posthog.com)

.github/workflows/e2e-smoke.yml

@@ -0,0 +1,123 @@
+name: E2E Smoke Tests
+
+on:
+  push:
+    branches: [main, dev]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # ─── Tier 1: Deterministic (no API keys needed) ────────────────────────
+  e2e-deterministic:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.11
+
+      - name: Setup uv (for Python script nodes)
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run deterministic workflow
+        run: bun run cli workflow run e2e-deterministic --no-worktree "smoke test"
+
+  # ─── Tier 2a: Claude provider ──────────────────────────────────────────
+  e2e-claude:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.11
+
+      - name: Install Claude Code CLI
+        run: |
+          curl -fsSL https://claude.ai/install.sh | bash
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run Claude smoke test
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          CLAUDE_BIN_PATH: ~/.local/bin/claude
+        run: bun run cli workflow run e2e-claude-smoke --no-worktree "smoke test"
+
+  # ─── Tier 2b: Codex provider ───────────────────────────────────────────
+  e2e-codex:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.11
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install Codex CLI
+        run: npm install -g @openai/codex
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run Codex smoke test
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          CODEX_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        run: bun run cli workflow run e2e-codex-smoke --no-worktree "smoke test"
+
+  # ─── Tier 3: Mixed providers ───────────────────────────────────────────
+  e2e-mixed:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    needs: [e2e-claude, e2e-codex]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.11
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install Claude Code CLI
+        run: |
+          curl -fsSL https://claude.ai/install.sh | bash
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Install Codex CLI
+        run: npm install -g @openai/codex
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run mixed providers test
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          CODEX_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          CLAUDE_BIN_PATH: ~/.local/bin/claude
+        run: bun run cli workflow run e2e-mixed-providers --no-worktree "smoke test"

.github/workflows/release.yml

@@ -124,6 +124,83 @@ jobs:
             exit 1
           fi
 
+      - name: Smoke-test Claude binary-path resolver (negative case)
+        if: matrix.target == 'bun-linux-x64' && runner.os == 'Linux'
+        run: |
+          # With no CLAUDE_BIN_PATH and no config, running a Claude workflow must
+          # fail with a clear, user-facing error — NOT with "Module not found
+          # /Users/runner/..." which would indicate the resolver was bypassed.
+          BIN="$PWD/dist/${{ matrix.binary }}"
+          TMP_REPO=$(mktemp -d)
+          cd "$TMP_REPO"
+          git init -q
+          git -c user.email=ci@example.com -c user.name=ci commit --allow-empty -q -m init
+
+          # Run without CLAUDE_BIN_PATH set. Expect a clean resolver error.
+          # Capture both stdout and stderr; we only care that the resolver message is present.
+          set +e
+          OUTPUT=$(env -u CLAUDE_BIN_PATH "$BIN" workflow run archon-assist "hello" 2>&1)
+          EXIT_CODE=$?
+          set -e
+          echo "$OUTPUT"
+
+          if echo "$OUTPUT" | grep -qE 'Module not found.*Users/runner'; then
+            echo "::error::Resolver was bypassed — SDK hit the import.meta.url fallback (regression of #1210)"
+            exit 1
+          fi
+          if ! echo "$OUTPUT" | grep -q "Claude Code not found"; then
+            echo "::error::Expected 'Claude Code not found' error when CLAUDE_BIN_PATH is unset"
+            exit 1
+          fi
+          if ! echo "$OUTPUT" | grep -q "CLAUDE_BIN_PATH"; then
+            echo "::error::Error message does not reference CLAUDE_BIN_PATH remediation"
+            exit 1
+          fi
+          echo "::notice::Resolver error path works (exit code: $EXIT_CODE)"
+
+      - name: Smoke-test Claude subprocess spawn (positive case)
+        if: matrix.target == 'bun-linux-x64' && runner.os == 'Linux'
+        run: |
+          # Install Claude Code via the native installer (Anthropic's recommended
+          # default) and run a workflow with CLAUDE_BIN_PATH set. The subprocess
+          # must spawn cleanly. We do NOT require the query to succeed (no auth
+          # in CI — an auth error is fine and expected); we only fail if the SDK
+          # can't find the executable, which would indicate a resolver regression.
+          curl -fsSL https://claude.ai/install.sh | bash
+          CLI_PATH="$HOME/.local/bin/claude"
+          if [ ! -x "$CLI_PATH" ]; then
+            echo "::error::Claude Code binary not found after curl install at $CLI_PATH"
+            ls -la "$HOME/.local/bin/" || true
+            exit 1
+          fi
+          echo "Using CLAUDE_BIN_PATH=$CLI_PATH"
+
+          BIN="$PWD/dist/${{ matrix.binary }}"
+          TMP_REPO=$(mktemp -d)
+          cd "$TMP_REPO"
+          git init -q
+          git -c user.email=ci@example.com -c user.name=ci commit --allow-empty -q -m init
+
+          set +e
+          OUTPUT=$(CLAUDE_BIN_PATH="$CLI_PATH" "$BIN" workflow run archon-assist "hello" 2>&1)
+          EXIT_CODE=$?
+          set -e
+          echo "$OUTPUT"
+
+          if echo "$OUTPUT" | grep -qE 'Module not found.*(cli\.js|Users/runner)'; then
+            echo "::error::Subprocess could not find the executable (resolver regression)"
+            exit 1
+          fi
+          if echo "$OUTPUT" | grep -q "Claude Code not found"; then
+            echo "::error::Resolver failed even though CLAUDE_BIN_PATH was set to an existing file"
+            exit 1
+          fi
+          # Any of these outcomes are acceptable — they prove the subprocess spawned:
+          #   - auth error ("credit balance", "unauthorized", "authentication")
+          #   - rate-limit / API error
+          #   - successful query (if auth was injected via some other mechanism)
+          echo "::notice::Claude subprocess spawn path is healthy (exit code: $EXIT_CODE)"
+
       - name: Upload binary artifact
         uses: actions/upload-artifact@v4
         with:
@@ -145,10 +222,25 @@ jobs:
           path: dist
           merge-multiple: true
 
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.11
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build web UI
+        run: bun --filter @archon/web build
+
+      - name: Package web dist
+        run: |
+          tar czf dist/archon-web.tar.gz -C packages/web/dist .
+
       - name: Generate checksums
         run: |
           cd dist
-          sha256sum archon-* > checksums.txt
+          sha256sum archon-* archon-web.tar.gz > checksums.txt
           cat checksums.txt
 
       - name: Get version
@@ -170,6 +262,7 @@ jobs:
           generate_release_notes: true
           files: |
             dist/archon-*
+            dist/archon-web.tar.gz
             dist/checksums.txt
           body: |
             ## Installation

.github/workflows/test.yml

@@ -27,6 +27,9 @@ jobs:
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
+      - name: Check bundled defaults
+        run: bun run check:bundled
+
       - name: Type check
         run: bun run type-check
 

.gitignore

@@ -45,6 +45,9 @@ e2e-screenshots/
 .archon/logs/
 .archon/artifacts/
 
+# Cross-run workflow state (e.g. issue-triage memory)
+.archon/state/
+
 # Agent artifacts (generated, local only)
 .agents/
 .agents/rca-reports/
@@ -54,6 +57,7 @@ e2e-screenshots/
 .claude/archon/
 .claude/mockups/
 .claude/settings.local.json
+.claude/scheduled_tasks.lock
 e2e-testing-findings-session2.md
 
 # Local workspace

.prettierignore

@@ -22,6 +22,9 @@ workspace/
 # Lock files (auto-generated)
 package-lock.json
 
+# Auto-generated source (regenerated by scripts/generate-bundled-defaults.ts)
+**/*.generated.ts
+
 # Agent commands and documentation (user-managed)
 .agents/
 .claude/

CHANGELOG.md

@@ -7,6 +7,140 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Home-scoped commands at `~/.archon/commands/`** — personal command helpers now reusable across every repo. Resolution precedence: `<repoRoot>/.archon/commands/` > `~/.archon/commands/` > bundled defaults. Surfaced in the Web UI workflow-builder node palette under a dedicated "Global (~/.archon/commands/)" section.
+- **Home-scoped scripts at `~/.archon/scripts/`** — personal Bun/uv scripts now reusable across every repo. Script nodes (`script: my-helper`) resolve via `<repoRoot>/.archon/scripts/` first, then `~/.archon/scripts/`. Repo-scoped scripts with the same name override home-scoped ones silently; within a single scope, duplicate basenames across extensions still throw (unchanged from prior behavior).
+- **1-level subfolder support for workflows, commands, and scripts.** Files can live one folder deep under their respective `.archon/` root (e.g. `.archon/workflows/triage/foo.yaml`) and resolve by name or filename regardless of subfolder. Matches the existing `defaults/` convention. Deeper nesting is ignored silently — see docs for the full convention.
+- **`'global'` variant on `WorkflowSource`** — workflows at `~/.archon/workflows/` and commands at `~/.archon/commands/` now render with a distinct source label (no longer coerced to `'project'`). Web UI badges updated.
+- **`getHomeWorkflowsPath()`, `getHomeCommandsPath()`, `getHomeScriptsPath()`, `getLegacyHomeWorkflowsPath()`** helpers in `@archon/paths`, exported for both internal discovery and external callers that want to target the home scope directly.
+- **`discoverScriptsForCwd(cwd)`** in `@archon/workflows/script-discovery` — merges home-scoped + repo-scoped scripts with repo winning on name collisions. Used by the DAG executor and validator; callers no longer need to know about the two-scope shape.
+- **Workflow-level worktree policy (`worktree.enabled` in workflow YAML).** A workflow can now pin whether its runs use isolation regardless of how they were invoked: `worktree.enabled: false` always runs in the live checkout (CLI `--branch` / `--from` hard-error; web/chat/orchestrator short-circuits `validateAndResolveIsolation`), `worktree.enabled: true` requires isolation (CLI `--no-worktree` hard-errors). Omit the block to let the caller decide (current default). First consumer: `.archon/workflows/repo-triage.yaml` pinned to `enabled: false` since it's read-only.
+- **Per-project worktree path (`worktree.path` in `.archon/config.yaml`).** Opt-in repo-relative directory (e.g. `.worktrees`) where Archon places worktrees for that repo, instead of the default `~/.archon/workspaces/<owner>/<repo>/worktrees/`. Co-locates worktrees with the project so they appear in the IDE file tree. Validated as a safe relative path (no absolute, no `..`); malformed values fail loudly at worktree creation. Users opting in are responsible for `.gitignore`ing the directory themselves — no automatic file mutation. Credits @joelsb for surfacing the need in #1117.
+- **Three-path env model with operator-visible log lines.** The CLI and server now load env vars from `~/.archon/.env` (user scope) and `<cwd>/.archon/.env` (repo scope, overrides user) at boot, both with `override: true`. A new `[archon] loaded N keys from <path>` line is emitted per source (only when N > 0). `[archon] stripped N keys from <cwd> (...)` now also prints when stripCwdEnv removes target-repo env keys, replacing the misleading `[dotenv@17.3.1] injecting env (0) from .env` preamble that always reported 0. The `quiet: true` flag suppresses dotenv's own output. (#1302)
+- **`archon setup --scope home|project` and `--force` flags.** Default is `--scope home` (writes `~/.archon/.env`). `--scope project` targets `<cwd>/.archon/.env` instead. `--force` overwrites the target wholesale rather than merging; a timestamped backup is still written. (#1303)
+- **Merge-only setup writes with timestamped backups.** `archon setup` now reads the existing target file, preserves non-empty values, carries user-added custom keys forward, and writes a `<target>.archon-backup-<ISO-ts>` before every rewrite. Fixes silent PostgreSQL→SQLite downgrade and silent token loss on re-run. (#1303)
+- **`getArchonEnvPath()` and `getRepoArchonEnvPath(cwd)`** helpers in `@archon/paths`, plus a new `@archon/paths/env-loader` subpath exporting `loadArchonEnv(cwd)` shared by the CLI and server entry points.
+
+- **Inline sub-agent definitions on DAG nodes (`agents:`).** Define Claude Agent SDK `AgentDefinition`s directly in workflow YAML, keyed by kebab-case agent ID. The main agent can spawn them in parallel via the `Task` tool — useful for map-reduce patterns where a cheap model (e.g. Haiku) briefs items and a stronger model reduces. Removes the need to author `.claude/agents/*.md` files for workflow-scoped helpers. Claude only; Codex and community providers that don't support inline agents emit a capability warning and ignore the field. Merges with the internal `dag-node-skills` wrapper set by `skills:` on the same node — user-defined agents win on ID collision (a warning is logged). (#1276)
+- **Pi community provider (`@mariozechner/pi-coding-agent`).** First community provider under the Phase 2 registry (`builtIn: false`). One adapter exposes ~20 LLM backends (Anthropic, OpenAI, Google, Groq, Mistral, Cerebras, xAI, OpenRouter, Hugging Face, and more) via a `<pi-provider-id>/<model-id>` model format. Reads credentials from `~/.pi/agent/auth.json` (populated by running `pi /login` for OAuth subscriptions like Claude Pro/Max, ChatGPT Plus, GitHub Copilot) AND from env vars (env vars take priority per-request). Per-node workflow options supported: `effort`/`thinking` → Pi `thinkingLevel`; `allowed_tools`/`denied_tools` → filter Pi's 7 built-in coding tools; `skills` → resolved against `.agents/skills`, `.claude/skills` (project + user-global); `systemPrompt`; codebase env vars; session resume via `sessionId` round-trip. Unsupported fields (MCP, hooks, structured output, cost limits, fallback model, sandbox) trigger an explicit dag-executor warning rather than silently dropping. Use in workflow YAML: `provider: pi` + `model: anthropic/claude-haiku-4-5`. (#1270)
+- **`registerCommunityProviders()` aggregator** in `@archon/providers`. Process entrypoints (CLI, server, config-loader) now call one function to register every bundled community provider. Adding a new community provider is a single-line edit to this aggregator rather than touching each entrypoint — makes the Phase 2 "community providers are a localized addition" promise real.
+- **`contributing/adding-a-community-provider.md` guide** — contributor-facing walkthrough of the Phase 2 registry pattern using Pi as the reference implementation.
+
+### Fixed
+
+- **`archon setup` no longer writes to `<repo>/.env`.** Prior versions unconditionally wrote the generated config to both `~/.archon/.env` and `<repo>/.env`, destroying user-added secrets and silently downgrading PostgreSQL configs to SQLite when re-run in "Add" mode. The write side now targets exactly one archon-owned file (home or project scope via `--scope`), merges into existing content by default, and writes a timestamped backup. `<repo>/.env` is never touched — it belongs to the user's target project. (#1303)
+- **CLI and server no longer silently lose repo-local env vars.** Previously, env vars in `<repo>/.env` were parsed, deleted from `process.env` by `stripCwdEnv()`, and the only output operators saw was `[dotenv@17.3.1] injecting env (0) from .env` — which read as "file was empty." Workflows that needed `SLACK_WEBHOOK` or similar had no way to recover without knowing to use `~/.archon/.env`. The new `<cwd>/.archon/.env` path + archon-owned log lines make the load state observable and recoverable. (#1302)
+
+- **Server startup no longer marks actively-running workflows as failed.** The `failOrphanedRuns()` call has been removed from `packages/server/src/index.ts` to match the CLI precedent (`packages/cli/src/cli.ts:256-258`). Per the new CLAUDE.md principle "No Autonomous Lifecycle Mutation Across Process Boundaries", a stuck `running` row is now transitioned explicitly by the user: via the per-row Cancel/Abandon buttons on the dashboard workflow card, or `archon workflow abandon <run-id>` from the CLI. (`archon workflow cleanup` is a separate command that deletes OLD terminal runs for disk hygiene — it does not handle stuck `running` rows.) Closes #1216.
+
+### Changed
+
+- **Home-scoped workflow location moved to `~/.archon/workflows/`** (was `~/.archon/.archon/workflows/` — a double-nested path left over from reusing the repo-relative discovery helper for home scope). The new path sits next to `~/.archon/workspaces/`, `archon.db`, and `config.yaml`, matching the rest of the `~/.archon/` convention. If Archon detects workflows at the old location, it emits a one-time WARN per process with the exact migration command: `mv ~/.archon/.archon/workflows ~/.archon/workflows && rmdir ~/.archon/.archon`. The old path is no longer read — users must migrate manually (clean cut, no deprecation window). Rollback caveat: if you downgrade after migrating, move the directory back to the old location.
+- **Workflow discovery no longer takes a `globalSearchPath` option.** `discoverWorkflows()` and `discoverWorkflowsWithConfig()` now consult `~/.archon/workflows/` automatically — every caller gets home-scoped discovery for free. Previously-missed call sites in the chat command handler (`command-handler.ts`), the Web UI workflow picker (`api.ts GET /api/workflows`), and the orchestrator's single-codebase resolve path now see home-scoped workflows without needing a maintainer patch at every new call site. Closes #1136; supersedes that PR (credits @jonasvanderhaegen for surfacing the bug class).
+- **Dashboard nav tab** now shows a numeric count of running workflows instead of a binary pulse dot. Reads from the existing `/api/dashboard/runs` `counts.running` field; same 10s polling interval.
+- **Workflow run destructive actions** (Abandon, Cancel, Delete, Reject) now use a proper confirmation dialog matching the codebase-delete UX, replacing the browser's native `window.confirm()` popups. Each dialog includes context-appropriate copy describing what the action does to the run record.
+
+- **Claude Code binary resolution** (breaking for compiled binary users): Archon no longer embeds the Claude Code SDK into compiled binaries. In compiled builds, you must install Claude Code separately (`curl -fsSL https://claude.ai/install.sh | bash` on macOS/Linux, `irm https://claude.ai/install.ps1 | iex` on Windows, or `npm install -g @anthropic-ai/claude-code`) and point Archon at the executable via `CLAUDE_BIN_PATH` env var or `assistants.claude.claudeBinaryPath` in `.archon/config.yaml`. The Claude Agent SDK accepts either the native compiled binary (from the curl/PowerShell installer at `~/.local/bin/claude`) or a JS `cli.js` (from the npm install). Dev mode (`bun run`) is unaffected — the SDK resolves via `node_modules` as before. The Docker image ships Claude Code pre-installed with `CLAUDE_BIN_PATH` pre-set, so `docker run` still works out of the box. Resolves silent "Module not found /Users/runner/..." failures on macOS (#1210) and Windows (#1087).
+
+### Added
+
+- **`CLAUDE_BIN_PATH` environment variable** — highest-precedence override for the Claude Code SDK `cli.js` path (#1176)
+- **`assistants.claude.claudeBinaryPath` config option** — durable config-file alternative to the env var (#1176)
+- **Release-workflow Claude subprocess smoke test** — the release CI now installs Claude Code on the Linux runner and exercises the resolver + subprocess spawn, catching binary-resolution regressions before they ship
+
+### Removed
+
+- **`globalSearchPath` option** from `discoverWorkflows()` and `discoverWorkflowsWithConfig()`. Callers that previously passed `{ globalSearchPath: getArchonHome() }` should drop the argument; home-scoped discovery is now automatic.
+- **`@anthropic-ai/claude-agent-sdk/embed` import** — the Bun `with { type: 'file' }` asset-embedding path and its `$bunfs` extraction logic. The embed was a bundler-dependent optimization that failed silently when Bun couldn't produce a usable virtual FS path (#1210, #1087); it is replaced by explicit binary-path resolution.
+
+### Fixed
+
+- **Cross-clone worktree isolation**: prevent workflows in one local clone from silently adopting worktrees or DB state owned by another local clone of the same remote. Two clones sharing a remote previously resolved to the same `codebase_id`, causing the isolation resolver's DB-driven paths (`findReusable`, `findLinkedIssueEnv`, `tryBranchAdoption`) to return the other clone's environment. All adoption paths now verify the worktree's `.git` pointer matches the requesting clone and throw a classified error on mismatch. `archon-implement` prompt was also tightened to stop AI agents from adopting unrelated branches they see via `git branch`. Thanks to @halindrome for the three-issue root-cause mapping. (#1193, #1188, #1183, #1198, #1206)
+
+## [0.3.6] - 2026-04-12
+
+Web UI workflow experience improvements, CWD environment leak protection, and bug fixes.
+
+### Added
+
+- Workflow result card now shows status, duration, node count, and artifact links in chat (#1015)
+- Loop iteration progress display in the workflow execution view (#1014)
+- Artifact file paths in chat messages are now clickable (#1023)
+
+### Changed
+
+- CWD `.env` variables are now stripped from AI subprocess environments at the `@archon/paths` layer, replacing the old `SUBPROCESS_ENV_ALLOWLIST` approach. Prevents accidental credential leaks from target repo `.env` files (#1067, #1030, #1098, #1070)
+- Update check cache TTL reduced from 24 hours to 1 hour
+
+### Fixed
+
+- Duplicate text and tool calls appearing in workflow execution view
+- `workflow_step` SSE events not handled correctly, causing missing progress updates
+- Nested interactive elements in workflow UI causing React warnings
+- Workflow status messages not splitting correctly in WorkflowLogs
+- Incorrect `remainingMessage` suppression in stream mode causing lost output
+- Binary builds now use `BUNDLED_VERSION` for the app version instead of reading `package.json`
+
+## [0.3.5] - 2026-04-10
+
+Fixes for `archon serve` process lifecycle and static file serving.
+
+### Fixed
+
+- **`archon serve` process exits immediately**: the CLI called `process.exit(0)` after `startServer()` returned, killing the server. Now blocks on SIGINT/SIGTERM so the server stays running (#1047)
+- **Web dist path existence check**: server logs a warning at startup if the web dist directory is missing, instead of silently serving 404s
+- **Favicon route**: added explicit `/favicon.png` route for the web UI
+
+## [0.3.4] - 2026-04-10
+
+Binary env loading fix and release infrastructure improvements.
+
+### Added
+
+- **Docs site redesign**: logo, dark theme, feature cards, and enhanced CSS (#1022)
+
+### Changed
+
+- **Server env loading for binary support**: removed redundant CWD `.env` stripping — `SUBPROCESS_ENV_ALLOWLIST` and the env-leak gate already prevent target repo credentials from reaching AI subprocesses. Server now loads `~/.archon/.env` with `override: true` for all keys (not just `DATABASE_URL`), skips the `import.meta.dir` `.env` path in binary mode, and defaults `CLAUDE_USE_GLOBAL_AUTH=true` when no explicit credentials are set (#1045)
+- **Workspace version sync**: all `packages/*/package.json` versions now sync from the root `package.json` during releases via `scripts/sync-versions.sh`
+
+### Fixed
+
+- **`archon serve` crash in compiled binaries**: the CWD env stripping + baked `import.meta.dir` path caused all credentials to be lost, triggering `no_ai_credentials` exit on every startup
+- **CLI `version` command reading stale version**: dev mode now reads from the monorepo root `package.json` instead of the CLI package's own version field
+- **Release CI web build**: fixed `bun --filter` syntax and added missing `remark-gfm` transitive dependencies for Bun hoisting
+
+## [0.3.3] - 2026-04-10
+
+Binary distribution improvements, new workflow node type, and a batch of bug fixes.
+
+### Added
+
+- **`archon serve` command**: one-command way for compiled binary users to start the web UI server. Downloads a pre-built web UI tarball from GitHub releases on first run, verifies SHA-256 checksum, caches locally, then starts the full server (#1011)
+- **Automatic update check**: binary users see a notification when a newer version is available on GitHub. Non-blocking, cached for 24 hours (#1039)
+- **Script node type for DAG workflows**: `script:` nodes run inline TypeScript/Python or named scripts from `.archon/scripts/` via `bun` or `uv` runtimes. Supports `deps:` for dependency installation and `timeout:` in milliseconds (#999)
+- **Codex native binary auto-resolution**: compiled builds now locate the Codex CLI binary automatically instead of requiring a manual `CODEX_CLI_PATH` override (#995, #1012)
+
+### Fixed
+
+- **Workflow reject ignores positional reason**: `archon workflow reject <id> <reason>` now correctly passes the reason argument to the rejection handler
+- **Windows script path separators**: normalize backslashes to forward slashes in script node paths for cross-platform compatibility
+- **PowerShell `Add-ToUserPath` corruption**: installer no longer corrupts `PATH` when only a single entry exists (#1000)
+- **Validator `Promise.any` race condition**: script runtime checks no longer fail intermittently due to a `Promise.any` edge case (#1007, #1010)
+- **Interactive-prd workflow bugs**: fixes to loop gate handling, variable substitution, and node ordering (#1001, #1002, #1003, #1005)
+- **Community forge adapter exports**: added explicit export entries for Gitea and GitLab adapters so they resolve correctly in compiled builds (#1041)
+- **Workflow graph view without codebase**: the web UI workflow graph now loads correctly even when no codebase is selected (#958)
+
+## [0.3.2] - 2026-04-08
+
+Critical hotfix: compiled binaries could not spawn Claude. Also fixes an env-leak gate false-positive for unregistered working directories.
+
+### Fixed
+
+- **Claude SDK spawn in compiled binaries**: the Claude Agent SDK was resolving its `cli.js` via `import.meta.url` of the bundled module, which `bun build --compile` freezes at build time to the build host's absolute `node_modules` path. Every binary shipped from CI carried a `/Users/runner/work/Archon/...` path that existed only on the GitHub Actions runner, and every `workflow run` hit `Module not found` after three retries. Now imports `@anthropic-ai/claude-agent-sdk/embed` so `cli.js` is embedded into the binary's `$bunfs` and extracted to a real temp path at runtime (#990).
+- **Env-leak gate false-positive for unregistered cwd**: pre-spawn scan now skips cwd paths that aren't registered as codebases instead of blocking the workflow (#991, #992).
+
 ## [0.3.1] - 2026-04-08
 
 Patch release: SQLite migration fix for existing databases and release build pipeline fix.
@@ -96,7 +230,7 @@ Chat-first navigation redesign, DAG graph viewer, per-node MCP and skills, and e
 - Idle timeout not detecting stuck tool calls during execution (#649)
 - `commitAllChanges` failing on empty commits (#745)
 - Explicit base branch config now required for worktree creation (#686)
-- Subprocess-level retry added to CodexClient (#641)
+- Subprocess-level retry added to CodexProvider (#641)
 - Validate `cwd` query param against registered codebases (#630)
 - Server-internal paths redacted from `/api/config` response (#632)
 - SQLite conversations index missing `WHERE deleted_at IS NULL` (#629)
@@ -148,7 +282,7 @@ DAG hardening, security fixes, validate-pr workflow, and worktree lifecycle mana
 - **`--json` flag for `workflow list`** — machine-readable workflow output (#594)
 - **`archon-validate-pr` workflow** with per-node idle timeout support (#635)
 - **Typed SessionMetadata** with Zod validation for safer metadata handling (#600)
-- **`persistSession: false`** in ClaudeClient to avoid disk pollution from session transcripts (#626)
+- **`persistSession: false`** in ClaudeProvider to avoid disk pollution from session transcripts (#626)
 - **DAG workflow for GitHub issue resolution** with structured node pipeline
 
 ### Changed

CLAUDE.md

@@ -68,7 +68,7 @@ These are implementation constraints, not slogans. Apply them by default.
 
 **SRP + ISP — Single Responsibility + Interface Segregation**
 - Keep each module and package focused on one concern
-- Extend behavior by implementing existing narrow interfaces (`IPlatformAdapter`, `IAssistantClient`, `IDatabase`, `IWorkflowStore`) whenever possible
+- Extend behavior by implementing existing narrow interfaces (`IPlatformAdapter`, `IAgentProvider`, `IDatabase`, `IWorkflowStore`) whenever possible
 - Avoid fat interfaces and "god modules" that mix policy, transport, and storage
 - Do not add unrelated methods to an existing interface — define a new one
 
@@ -77,6 +77,12 @@ These are implementation constraints, not slogans. Apply them by default.
 - Never silently broaden permissions or capabilities
 - Document fallback behavior with a comment when a fallback is intentional and safe; otherwise throw
 
+**No Autonomous Lifecycle Mutation Across Process Boundaries**
+- When a process cannot reliably distinguish "actively running elsewhere" from "orphaned by a crash" — typically because the work was started by a different process or input source (CLI, adapter, webhook, web UI, cron) — it must not autonomously mark that work as failed/cancelled/abandoned based on a timer or staleness guess.
+- Surface the ambiguous state to the user and provide a one-click action.
+- Heuristics for *recoverable* operations (retry backoff, subprocess timeouts, hygiene cleanup of terminal-status data) remain appropriate; the rule is about destructive mutation of *non-terminal* state owned by an unknowable other party.
+- Reference: #1216 and the CLI orphan-cleanup precedent at `packages/cli/src/cli.ts:256-258`.
+
 **Determinism + Reproducibility**
 - Prefer reproducible commands and locked dependency behavior in CI-sensitive paths
 - Keep tests deterministic — no flaky timing or network dependence without guardrails
@@ -122,7 +128,7 @@ bun test --watch            # Watch mode (single package)
 bun test packages/core/src/handlers/command-handler.test.ts  # Single file
 ```
 
-**Test isolation (mock.module pollution):** Bun's `mock.module()` permanently replaces modules in the process-wide cache — `mock.restore()` does NOT undo it ([oven-sh/bun#7823](https://github.com/oven-sh/bun/issues/7823)). To prevent cross-file pollution, packages that have conflicting `mock.module()` calls split their tests into separate `bun test` invocations: `@archon/core` (7 batches), `@archon/workflows` (5), `@archon/adapters` (4), `@archon/isolation` (3). See each package's `package.json` for the exact splits.
+**Test isolation (mock.module pollution):** Bun's `mock.module()` permanently replaces modules in the process-wide cache — `mock.restore()` does NOT undo it ([oven-sh/bun#7823](https://github.com/oven-sh/bun/issues/7823)). To prevent cross-file pollution, packages that have conflicting `mock.module()` calls split their tests into separate `bun test` invocations: `@archon/core` (7 batches), `@archon/workflows` (5), `@archon/adapters` (3), `@archon/isolation` (3). See each package's `package.json` for the exact splits.
 
 **Do NOT run `bun test` from the repo root** — it discovers all test files across all packages and runs them in one process, causing ~135 mock pollution failures. Always use `bun run test` (which uses `bun --filter '*' test` for per-package isolation).
 
@@ -144,7 +150,7 @@ bun run format:check
 bun run validate
 ```
 
-This runs type-check, lint, format check, and tests. All four must pass for CI to succeed.
+This runs `check:bundled`, type-check, lint, format check, and tests. All five must pass for CI to succeed.
 
 ### ESLint Guidelines
 
@@ -198,10 +204,6 @@ bun run cli workflow run implement --branch feature-auth "Add auth"
 # Opt out of isolation (run in live checkout)
 bun run cli workflow run quick-fix --no-worktree "Fix typo"
 
-# Grant env-leak-gate consent during auto-registration (for repos whose .env
-# contains sensitive keys). Audit-logged with actor: 'user-cli'.
-bun run cli workflow run plan --cwd /path/to/leaky/repo --allow-env-keys "..."
-
 # Show running workflows
 bun run cli workflow status
 
@@ -244,6 +246,11 @@ bun run cli validate commands my-command    # Single command
 bun run cli complete <branch-name>
 bun run cli complete <branch-name> --force  # Skip uncommitted-changes check
 
+# Start the web UI server (compiled binary only, downloads web UI on first run)
+bun run cli serve
+bun run cli serve --port 4000
+bun run cli serve --download-only  # Download without starting
+
 # Show version
 bun run cli version
 ```
@@ -261,9 +268,17 @@ packages/
 │       ├── adapters/         # CLI adapter (stdout output)
 │       ├── commands/         # CLI command implementations
 │       └── cli.ts            # CLI entry point
+├── providers/                # @archon/providers - AI agent providers (SDK deps live here)
+│   └── src/
+│       ├── types.ts          # Contract layer (IAgentProvider, SendQueryOptions, MessageChunk — ZERO SDK deps)
+│       ├── registry.ts       # Typed provider registry (ProviderRegistration records)
+│       ├── errors.ts         # UnknownProviderError
+│       ├── claude/           # ClaudeProvider + parseClaudeConfig + MCP/hooks/skills translation
+│       ├── codex/            # CodexProvider + parseCodexConfig + binary-resolver
+│       ├── community/pi/     # PiProvider (builtIn: false) — @mariozechner/pi-coding-agent, ~20 LLM backends
+│       └── index.ts          # Package exports
 ├── core/                     # @archon/core - Shared business logic
 │   └── src/
-│       ├── clients/          # AI SDK clients (Claude, Codex)
 │       ├── config/           # YAML config loading
 │       ├── db/               # Database connection, queries
 │       ├── handlers/         # Command handler (slash commands)
@@ -284,7 +299,7 @@ packages/
 │       ├── executor.ts       # Workflow execution orchestrator (executeWorkflow)
 │       ├── dag-executor.ts   # DAG-specific execution logic
 │       ├── store.ts          # IWorkflowStore interface (database abstraction)
-│       ├── deps.ts           # WorkflowDeps injection types (IWorkflowPlatform, IWorkflowAssistantClient)
+│       ├── deps.ts           # WorkflowDeps injection types (IWorkflowPlatform, imports from @archon/providers/types)
 │       ├── event-emitter.ts  # Workflow observability events
 │       ├── logger.ts         # JSONL file logger
 │       ├── validator.ts      # Resource validation (command files, MCP configs, skill dirs)
@@ -378,7 +393,7 @@ import type { DagNode, WorkflowDefinition } from '@/lib/api';
 5. **`workflow_runs`** - Workflow execution tracking and state
 6. **`workflow_events`** - Step-level workflow event log (step transitions, artifacts, errors)
 7. **`messages`** - Conversation message history with tool call metadata (JSONB)
-8. **`codebase_env_vars`** - Per-project env vars injected into Claude SDK subprocess env (managed via Web UI or `env:` in config)
+8. **`codebase_env_vars`** - Per-project env vars injected into project-scoped execution surfaces (Claude, Codex, bash/script nodes, and direct chat when codebase-scoped), managed via Web UI or `env:` in config
 
 **Key Patterns:**
 - Conversation ID format: Platform-specific (`thread_ts`, `chat_id`, `user/repo#123`)
@@ -394,12 +409,13 @@ import type { DagNode, WorkflowDefinition } from '@/lib/api';
 ### Architecture Layers
 
 **Package Split:**
-- **@archon/paths**: Path resolution utilities and Pino logger factory (no @archon/* deps)
+- **@archon/paths**: Path resolution utilities, Pino logger factory, web dist cache path (`getWebDistDir`), CWD env stripper (`stripCwdEnv`, `strip-cwd-env-boot`) (no @archon/* deps; `pino` and `dotenv` are allowed external deps)
 - **@archon/git**: Git operations - worktrees, branches, repos, exec wrappers (depends only on @archon/paths)
+- **@archon/providers**: AI agent providers (Claude, Codex, Pi community) — owns SDK deps, `IAgentProvider` interface, `sendQuery()` contract, and provider-specific option translation. `@archon/providers/types` is the contract subpath (zero SDK deps, zero runtime side effects) that `@archon/workflows` imports from. Providers receive raw `nodeConfig` + `assistantConfig` and translate to SDK-specific options internally. Core providers live under `claude/` and `codex/`; community providers live under `community/` (currently `community/pi/`, registered with `builtIn: false`).
 - **@archon/isolation**: Worktree isolation types, providers, resolver, error classifiers (depends only on @archon/git + @archon/paths)
-- **@archon/workflows**: Workflow engine - loader, router, executor, DAG, logger, bundled defaults (depends only on @archon/git + @archon/paths + @hono/zod-openapi + zod; DB/AI/config injected via `WorkflowDeps`)
-- **@archon/cli**: Command-line interface for running workflows
-- **@archon/core**: Business logic, database, orchestration, AI clients (provides `createWorkflowStore()` adapter bridging core DB → `IWorkflowStore`)
+- **@archon/workflows**: Workflow engine - loader, router, executor, DAG, logger, bundled defaults (depends only on @archon/git + @archon/paths + @archon/providers/types + @hono/zod-openapi + zod; DB/AI/config injected via `WorkflowDeps`)
+- **@archon/cli**: Command-line interface for running workflows and starting the web UI server (depends on @archon/server + @archon/adapters for the serve command)
+- **@archon/core**: Business logic, database, orchestration (depends on @archon/providers for AI; provides `createWorkflowStore()` adapter bridging core DB → `IWorkflowStore`)
 - **@archon/adapters**: Platform adapters for Slack, Telegram, GitHub, Discord (depends on @archon/core)
 - **@archon/server**: OpenAPIHono HTTP server (Zod + OpenAPI spec generation via `@hono/zod-openapi`), Web adapter (SSE), API routes, Web UI static serving (depends on @archon/adapters)
 - **@archon/web**: React frontend (Vite + Tailwind v4 + shadcn/ui + Zustand), SSE streaming to server. `WorkflowRunStatus`, `WorkflowDefinition`, and `DagNode` are all derived from `src/lib/api.generated.d.ts` (generated from the OpenAPI spec via `bun generate:types`; never import from `@archon/workflows`)
@@ -424,7 +440,8 @@ import type { DagNode, WorkflowDefinition } from '@/lib/api';
 
 **2. Command Handler** (`packages/core/src/handlers/`)
 - Process slash commands (deterministic, no AI)
-- Commands: `/command-set`, `/load-commands`, `/clone`, `/getcwd`, `/setcwd`, `/repos`, `/repo`, `/repo-remove`, `/worktree`, `/workflow`, `/status`, `/commands`, `/help`, `/reset`, `/reset-context`, `/init`
+- The orchestrator treats only these top-level commands as deterministic: `/help`, `/status`, `/reset`, `/workflow`, `/register-project`, `/update-project`, `/remove-project`, `/commands`, `/init`, `/worktree`
+- `/workflow` handles subcommands like `list`, `run`, `status`, `cancel`, `resume`, `abandon`, `approve`, `reject`
 - Update database, perform operations, return responses
 
 **3. Orchestrator** (`packages/core/src/orchestrator/`)
@@ -434,10 +451,11 @@ import type { DagNode, WorkflowDefinition } from '@/lib/api';
 - Session management: Create new or resume existing
 - Stream AI responses to platform
 
-**4. AI Assistant Clients** (`packages/core/src/clients/`)
-- Implement `IAssistantClient` interface
-- **ClaudeClient**: `@anthropic-ai/claude-agent-sdk`
-- **CodexClient**: `@openai/codex-sdk`
+**4. AI Agent Providers** (`packages/providers/src/`)
+- Implement `IAgentProvider` interface
+- **ClaudeProvider**: `@anthropic-ai/claude-agent-sdk`
+- **CodexProvider**: `@openai/codex-sdk`
+- **PiProvider** (community, `builtIn: false`): `@mariozechner/pi-coding-agent` — one harness for ~20 LLM backends via `<provider>/<model>` refs (e.g. `anthropic/claude-haiku-4-5`, `openrouter/qwen/qwen3-coder`); supports extensions, skills, tool restrictions, thinking level, best-effort structured output. See `packages/docs-web/src/content/docs/getting-started/ai-assistants.md` for setup, capability matrix, and extension config.
 - Streaming: `for await (const event of events) { await platform.send(event) }`
 
 ### Configuration
@@ -458,12 +476,18 @@ assistants:
     settingSources:  # Controls which CLAUDE.md files Claude SDK loads
       - project      # Default: only project-level CLAUDE.md
       - user         # Optional: also load ~/.claude/CLAUDE.md
+    claudeBinaryPath: /absolute/path/to/claude  # Optional: Claude Code executable.
+                                                # Native binary (curl installer at
+                                                # ~/.local/bin/claude) or npm cli.js.
+                                                # Required in compiled binaries if
+                                                # CLAUDE_BIN_PATH env var is not set.
   codex:
     model: gpt-5.3-codex
     modelReasoningEffort: medium  # 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
     webSearchMode: live  # 'disabled' | 'cached' | 'live'
     additionalDirectories:
       - /absolute/path/to/other/repo
+    codexBinaryPath: /usr/local/bin/codex  # Optional: custom Codex CLI binary path
 
 # docs:
 #   path: docs  # Optional: default is docs/
@@ -524,12 +548,15 @@ curl http://localhost:3637/api/conversations/<conversationId>/messages
 ```
 ~/.archon/
 ├── workspaces/owner/repo/        # Project-centric layout
-│   ├── source/                   # Clone (from /clone) or symlink → local path
+│   ├── source/                   # Cloned repo or symlink → local path
 │   ├── worktrees/                # Git worktrees for this project
 │   ├── artifacts/                # Workflow artifacts (NEVER in git)
 │   │   ├── runs/{id}/            # Per-run artifacts ($ARTIFACTS_DIR)
 │   │   └── uploads/{convId}/     # Web UI file uploads (ephemeral)
 │   └── logs/                     # Workflow execution logs
+├── vendor/codex/                  # Codex native binary (binary builds, user-placed)
+├── web-dist/<version>/            # Cached web UI dist (archon serve, binary only)
+├── update-check.json              # Update check cache (binary builds, 24h TTL)
 ├── archon.db                     # SQLite database (when DATABASE_URL not set)
 └── config.yaml                   # Global configuration (non-secrets)
 ```
@@ -539,6 +566,8 @@ curl http://localhost:3637/api/conversations/<conversationId>/messages
 .archon/
 ├── commands/       # Custom commands
 ├── workflows/      # Workflow definitions (YAML files)
+├── scripts/        # Named scripts for script: nodes (.ts/.js for bun, .py for uv)
+├── state/          # Cross-run workflow state (gitignored — never in git)
 └── config.yaml     # Repo-specific configuration
 ```
 
@@ -551,7 +580,7 @@ curl http://localhost:3637/api/conversations/<conversationId>/messages
 
 **Quick reference:**
 - **Platform Adapters**: Implement `IPlatformAdapter`, handle auth, polling/webhooks
-- **AI Clients**: Implement `IAssistantClient`, session management, streaming
+- **AI Providers**: Implement `IAgentProvider`, session management, streaming
 - **Slash Commands**: Add to command-handler.ts, update database, no AI
 - **Database Operations**: Use `IDatabase` interface (supports PostgreSQL and SQLite via adapters)
 
@@ -665,13 +694,13 @@ async function createSession(conversationId: string, codebaseId: string) {
 
 1. **Codebase Commands** (per-repo):
    - Stored in `.archon/commands/` (plain text/markdown)
-   - Auto-detected via `/clone` or `/load-commands <folder>`
-   - Loaded by `/clone` or `/load-commands`, invoked by AI via orchestrator routing
+   - Discovered from the repository `.archon/commands/` directory
+   - Surfaced via `GET /api/commands` for the workflow builder and invoked by workflow `command:` nodes
 
 2. **Workflows** (YAML-based):
    - Stored in `.archon/workflows/` (searched recursively)
    - Multi-step AI execution chains, discovered at runtime
-   - **`nodes:` (DAG format)**: Nodes with explicit `depends_on` edges; independent nodes in the same topological layer run concurrently. Node types: `command:` (named command file), `prompt:` (inline prompt), `bash:` (shell script, stdout captured as `$nodeId.output`, no AI), `loop:` (iterative AI prompt until completion signal) . Supports `when:` conditions, `trigger_rule` join semantics, `$nodeId.output` substitution, `output_format` for structured JSON output (Claude and Codex), `allowed_tools`/`denied_tools` for per-node tool restrictions (Claude only), `hooks` for per-node SDK hook callbacks (Claude only), `mcp` for per-node MCP server config files (Claude only, env vars expanded at execution time), and `skills` for per-node skill preloading via AgentDefinition wrapping (Claude only), and `effort`/`thinking`/`maxBudgetUsd`/`systemPrompt`/`fallbackModel`/`betas`/`sandbox` for Claude SDK advanced options (Claude only, also settable at workflow level)
+   - **`nodes:` (DAG format)**: Nodes with explicit `depends_on` edges; independent nodes in the same topological layer run concurrently. Node types: `command:` (named command file), `prompt:` (inline prompt), `bash:` (shell script, stdout captured as `$nodeId.output`, no AI, receives managed per-project env vars in its subprocess environment when configured), `loop:` (iterative AI prompt until completion signal), `approval:` (human gate; pauses until user approves or rejects; `capture_response: true` stores the user's comment as `$<node-id>.output` for downstream nodes, default false), `script:` (inline TypeScript/Python or named script from `.archon/scripts/`, runs via `bun` or `uv`, stdout captured as `$nodeId.output`, no AI, receives managed per-project env vars in its subprocess environment when configured, supports `deps:` for dependency installation and `timeout:` in ms, requires `runtime: bun` or `runtime: uv`) . Supports `when:` conditions, `trigger_rule` join semantics, `$nodeId.output` substitution, `output_format` for structured JSON output (Claude and Codex via SDK enforcement; Pi best-effort via prompt augmentation + JSON extraction), `allowed_tools`/`denied_tools` for per-node tool restrictions (Claude only), `hooks` for per-node SDK hook callbacks (Claude only), `mcp` for per-node MCP server config files (Claude only, env vars expanded at execution time), and `skills` for per-node skill preloading via AgentDefinition wrapping (Claude only), `agents` for inline sub-agent definitions invokable via the Task tool (Claude only), and `effort`/`thinking`/`maxBudgetUsd`/`systemPrompt`/`fallbackModel`/`betas`/`sandbox` for Claude SDK advanced options (Claude only, also settable at workflow level)
    - Provider inherited from `.archon/config.yaml` unless explicitly set; per-node `provider` and `model` overrides supported
    - Model and options can be set per workflow or inherited from config defaults
    - `interactive: true` at the workflow level forces foreground execution on web (required for approval-gate workflows in the web UI)
@@ -684,14 +713,21 @@ async function createSession(conversationId: string, codebaseId: string) {
 
 **Defaults:**
 - Bundled in `.archon/commands/defaults/` and `.archon/workflows/defaults/`
-- Binary builds: Embedded at compile time (no filesystem access needed)
+- Binary builds: Embedded at compile time (no filesystem access needed) via `packages/workflows/src/defaults/bundled-defaults.generated.ts`
 - Source builds: Loaded from filesystem at runtime
 - Merged with repo-specific commands/workflows (repo overrides defaults by name)
 - Opt-out: Set `defaults.loadDefaultCommands: false` or `defaults.loadDefaultWorkflows: false` in `.archon/config.yaml`
+- **After adding, removing, or editing a default file, run `bun run generate:bundled`** to refresh the embedded bundle. `bun run validate` (and CI) run `check:bundled` and will fail loudly if the generated file is stale.
 
-**Global workflows** (user-level, applies to every project):
-- Path: `~/.archon/.archon/workflows/` (or `$ARCHON_HOME/.archon/workflows/`)
-- Load priority: bundled < global < repo-specific (repo overrides global by filename)
+**Home-scoped ("global") workflows, commands, and scripts** (user-level, applies to every project):
+- Workflows: `~/.archon/workflows/` (or `$ARCHON_HOME/workflows/`)
+- Commands: `~/.archon/commands/` (or `$ARCHON_HOME/commands/`)
+- Scripts: `~/.archon/scripts/` (or `$ARCHON_HOME/scripts/`)
+- Source label: `source: 'global'` on workflows and commands (scripts don't have a source label)
+- Load priority: bundled < global < project (repo overrides global by filename or script name)
+- Subfolders: supported 1 level deep (e.g. `~/.archon/workflows/triage/foo.yaml`). Deeper nesting is ignored silently.
+- Discovery is automatic — `discoverWorkflowsWithConfig(cwd, loadConfig)` and `discoverScriptsForCwd(cwd)` both read home-scoped paths unconditionally; no caller option needed
+- **Migration from pre-0.x `~/.archon/.archon/workflows/`**: if Archon detects files at the old location it emits a one-time WARN with the exact `mv` command and does NOT load from there. Move with: `mv ~/.archon/.archon/workflows ~/.archon/workflows && rmdir ~/.archon/.archon`
 - See the docs site at `packages/docs-web/` for details
 
 ### Error Handling
@@ -749,9 +785,11 @@ Pattern: Use `classifyIsolationError()` (from `@archon/isolation`) to map git er
 
 **Codebases:**
 - `GET /api/codebases` / `GET /api/codebases/:id` - List / fetch codebases
-- `POST /api/codebases` - Register a codebase (clone or local path); body accepts `allowEnvKeys` for the env-leak gate
-- `PATCH /api/codebases/:id` - Flip the `allow_env_keys` consent bit; body: `{ allowEnvKeys: boolean }`. Audit-logged at `warn` level on every grant/revoke (`env_leak_consent_granted` / `env_leak_consent_revoked`) with `codebaseId`, `path`, `files`, `keys`, `scanStatus`, `actor`
+- `POST /api/codebases` - Register a codebase (clone or local path)
 - `DELETE /api/codebases/:id` - Delete a codebase and clean up resources
+- `GET /api/codebases/:id/env` - List env var keys for a codebase (never returns values)
+- `PUT /api/codebases/:id/env` / `DELETE /api/codebases/:id/env/:key` - Upsert / delete a single codebase env var
+- `GET /api/codebases/:id/environments` - List tracked isolation environments for a codebase
 
 **Artifact Files:**
 - `GET /api/artifacts/:runId/*` - Serve a workflow artifact file by run ID and relative path; returns `text/markdown` for `.md` files, `text/plain` otherwise; 400 on path traversal (`..`), 404 if run or file not found
@@ -759,6 +797,13 @@ Pattern: Use `classifyIsolationError()` (from `@archon/isolation`) to map git er
 **Command Listing:**
 - `GET /api/commands` - List available command names (bundled + project-defined); optional `?cwd=`; returns `{ commands: [{ name, source: 'bundled' | 'project' }] }`
 
+**Providers:**
+- `GET /api/providers` - List registered AI providers; returns `{ providers: [{ id, displayName, capabilities, builtIn }] }`
+
+**System:**
+- `GET /api/health` - Health check with adapter/system status
+- `GET /api/update-check` - Check for available updates; returns `{ updateAvailable, currentVersion, latestVersion, releaseUrl }`; skips GitHub API call for non-binary builds
+
 **OpenAPI Spec:**
 - `GET /api/openapi.json` - Generated OpenAPI 3.0 spec for all Zod-validated routes
 

CONTRIBUTING.md

@@ -17,15 +17,20 @@ Thank you for your interest in contributing to Archon!
 Before submitting a PR, ensure:
 
 ```bash
-bun run type-check  # TypeScript types
-bun run lint        # ESLint
-bun run format      # Prettier
-bun run test        # All tests (per-package isolation)
+bun run check:bundled  # Bundled defaults are up to date (see note below)
+bun run type-check     # TypeScript types
+bun run lint           # ESLint
+bun run format         # Prettier
+bun run test           # All tests (per-package isolation)
 
 # Or run the full validation suite:
 bun run validate
 ```
 
+**Bundled defaults**: If you added, removed, or edited a file under
+`.archon/commands/defaults/` or `.archon/workflows/defaults/`, run
+`bun run generate:bundled` to refresh the embedded bundle before committing.
+
 **Important:** Use `bun run test` (not `bun test` from the repo root) to avoid mock pollution across packages.
 
 ### Commit Messages

Dockerfile

@@ -24,6 +24,7 @@ COPY packages/docs-web/package.json ./packages/docs-web/
 COPY packages/git/package.json ./packages/git/
 COPY packages/isolation/package.json ./packages/isolation/
 COPY packages/paths/package.json ./packages/paths/
+COPY packages/providers/package.json ./packages/providers/
 COPY packages/server/package.json ./packages/server/
 COPY packages/web/package.json ./packages/web/
 COPY packages/workflows/package.json ./packages/workflows/
@@ -107,6 +108,14 @@ RUN apt-get update && apt-get install -y --no-install-recommends nodejs npm \
 # Point agent-browser to system Chromium (avoids ~400MB Chrome for Testing download)
 ENV AGENT_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium
 
+# Pre-configure the Claude Code SDK cli.js path for any consumer that runs
+# a compiled Archon binary inside (or extending) this image. In source mode
+# (the default `bun run start` ENTRYPOINT), BUNDLED_IS_BINARY is false and
+# this variable is ignored — the SDK resolves cli.js via node_modules. Kept
+# here so extenders don't need to rediscover the path.
+# Path matches the hoisted layout produced by `bun install --linker=hoisted`.
+ENV CLAUDE_BIN_PATH=/app/node_modules/@anthropic-ai/claude-agent-sdk/cli.js
+
 # Create non-root user for running Claude Code
 # Claude Code refuses to run with --dangerously-skip-permissions as root for security
 RUN useradd -m -u 1001 -s /bin/bash appuser \
@@ -130,6 +139,7 @@ COPY packages/docs-web/package.json ./packages/docs-web/
 COPY packages/git/package.json ./packages/git/
 COPY packages/isolation/package.json ./packages/isolation/
 COPY packages/paths/package.json ./packages/paths/
+COPY packages/providers/package.json ./packages/providers/
 COPY packages/server/package.json ./packages/server/
 COPY packages/web/package.json ./packages/web/
 COPY packages/workflows/package.json ./packages/workflows/
@@ -144,6 +154,7 @@ COPY packages/core/ ./packages/core/
 COPY packages/git/ ./packages/git/
 COPY packages/isolation/ ./packages/isolation/
 COPY packages/paths/ ./packages/paths/
+COPY packages/providers/ ./packages/providers/
 COPY packages/server/ ./packages/server/
 COPY packages/workflows/ ./packages/workflows/
 

README.md

@@ -171,6 +171,22 @@ irm https://archon.diy/install.ps1 | iex
 brew install coleam00/archon/archon
 ```
 
+> **Compiled binaries need a `CLAUDE_BIN_PATH`.** The quick-install binaries
+> don't bundle Claude Code. Install it separately, then point Archon at it:
+>
+> ```bash
+> # macOS / Linux / WSL
+> curl -fsSL https://claude.ai/install.sh | bash
+> export CLAUDE_BIN_PATH="$HOME/.local/bin/claude"
+>
+> # Windows (PowerShell)
+> irm https://claude.ai/install.ps1 | iex
+> $env:CLAUDE_BIN_PATH = "$env:USERPROFILE\.local\bin\claude.exe"
+> ```
+>
+> Or set `assistants.claude.claudeBinaryPath` in `~/.archon/config.yaml`.
+> The Docker image ships Claude Code pre-installed. See [AI Assistants → Binary path configuration](https://archon.diy/docs/getting-started/ai-assistants/#binary-path-configuration-compiled-binaries-only) for details.
+
 ### Start Using Archon
 
 Once you've completed either setup path, go to your project and start working:
@@ -194,7 +210,7 @@ The coding agent handles workflow selection, branch naming, and worktree isolati
 
 ## Web UI
 
-Archon includes a web dashboard for chatting with your coding agent, running workflows, and monitoring activity. To start it, ask your coding agent to run the frontend from the Archon repo, or run `bun run dev` from the repo root yourself.
+Archon includes a web dashboard for chatting with your coding agent, running workflows, and monitoring activity. Binary installs: run `archon serve` to download and start the web UI in one step. From source: ask your coding agent to run the frontend from the Archon repo, or run `bun run dev` from the repo root yourself.
 
 Register a project by clicking **+** next to "Project" in the chat sidebar - enter a GitHub URL or local path. Then start a conversation, invoke workflows, and watch progress in real time.
 
@@ -254,7 +270,7 @@ The Web UI and CLI work out of the box. Optionally connect a chat platform for r
 ```
 ┌─────────────────────────────────────────────────────────┐
 │  Platform Adapters (Web UI, CLI, Telegram, Slack,       │
-│                    Discord, GitHub)                      │
+│                    Discord, GitHub)                     │
 └──────────────────────────┬──────────────────────────────┘
                            │
                            ▼
@@ -268,7 +284,7 @@ The Web UI and CLI work out of the box. Optionally connect a chat platform for r
       ▼                ▼          ▼                ▼
 ┌───────────┐  ┌────────────┐  ┌──────────────────────────┐
 │  Command  │  │  Workflow  │  │    AI Assistant Clients  │
-│  Handler  │  │  Executor  │  │      (Claude / Codex)    │
+│  Handler  │  │  Executor  │  │   (Claude / Codex / Pi)  │
 │  (Slash)  │  │  (YAML)    │  │                          │
 └───────────┘  └────────────┘  └──────────────────────────┘
       │              │                      │
@@ -294,17 +310,38 @@ Full documentation is available at **[archon.diy](https://archon.diy)**.
 | [Authoring Workflows](https://archon.diy/guides/authoring-workflows/) | Create custom YAML workflows |
 | [Authoring Commands](https://archon.diy/guides/authoring-commands/) | Create reusable AI commands |
 | [Configuration](https://archon.diy/reference/configuration/) | All config options, env vars, YAML settings |
-| [AI Assistants](https://archon.diy/getting-started/ai-assistants/) | Claude and Codex setup details |
+| [AI Assistants](https://archon.diy/getting-started/ai-assistants/) | Claude, Codex, and Pi setup details |
 | [Deployment](https://archon.diy/deployment/) | Docker, VPS, production setup |
 | [Architecture](https://archon.diy/reference/architecture/) | System design and internals |
 | [Troubleshooting](https://archon.diy/reference/troubleshooting/) | Common issues and fixes |
 
+## Telemetry
+
+Archon sends a single anonymous event — `workflow_invoked` — each time a workflow starts, so maintainers can see which workflows get real usage and prioritize accordingly. **No PII, ever.**
+
+**What's collected:** the workflow name, the workflow description (both authored by you in YAML), the platform that triggered it (`cli`, `web`, `slack`, etc.), the Archon version, and a random install UUID stored at `~/.archon/telemetry-id`. Nothing else.
+
+**What's *not* collected:** your code, prompts, messages, git remotes, file paths, usernames, tokens, AI output, workflow node details — none of it.
+
+**Opt out:** set any of these in your environment:
+
+```bash
+ARCHON_TELEMETRY_DISABLED=1
+DO_NOT_TRACK=1        # de facto standard honored by Astro, Bun, Prisma, Nuxt, etc.
+```
+
+Self-host PostHog or use a different project by setting `POSTHOG_API_KEY` and `POSTHOG_HOST`.
+
 ## Contributing
 
 Contributions welcome! See the open [issues](https://github.com/coleam00/Archon/issues) for things to work on.
 
 Please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting a pull request.
 
+## Star History
+
+[![Star History Chart](https://api.star-history.com/chart?repos=coleam00/Archon&type=date&legend=top-left)](https://www.star-history.com/?repos=coleam00%2FArchon&type=date&legend=top-left)
+
 ## License
 
 [MIT](LICENSE)

deploy/.env.example

@@ -46,7 +46,7 @@ TELEGRAM_BOT_TOKEN=123456789:ABC...
 # ============================================
 # Optional
 # ============================================
-PORT=3000
+PORT=3000  # Docker deployment default (the included compose/Caddy configs target :3000). For local dev (no Docker), omit PORT — server and Vite proxy both default to 3090.
 # TELEGRAM_STREAMING_MODE=stream
 # DISCORD_STREAMING_MODE=batch
 

docker-entrypoint.sh

@@ -1,6 +1,11 @@
 #!/bin/bash
 set -e
 
+# Ensure required subdirectories exist.
+# Named volumes inherit these from the image layer on first run; bind mounts do not,
+# which causes the Claude subprocess to fail silently when spawned with a missing cwd.
+mkdir -p /.archon/workspaces /.archon/worktrees
+
 # Determine if we need to use gosu for privilege dropping
 if [ "$(id -u)" = "0" ]; then
   # Running as root: fix volume permissions, then drop to appuser

eslint.config.mjs

@@ -17,9 +17,11 @@ export default tseslint.config(
       'worktrees/**',
       '.claude/worktrees/**',
       '.claude/skills/**',
+      '**/*.generated.ts', // Auto-generated source files (content inlined via JSON.stringify)
       '**/*.js',
       '*.mjs',
       '**/*.test.ts',
+      '**/src/test/**', // Test helper files (mock factories, fixtures)
       '*.d.ts', // Root-level declaration files (not in tsconfig project scope)
       '**/*.generated.d.ts', // Auto-generated declaration files (e.g. openapi-typescript output)
       'packages/web/vite.config.ts', // Vite config doesn't need type-checked linting
@@ -40,7 +42,7 @@ export default tseslint.config(
 
   // Project-specific settings
   {
-    files: ['packages/*/src/**/*.{ts,tsx}'],
+    files: ['packages/*/src/**/*.{ts,tsx}', 'scripts/**/*.ts'],
     languageOptions: {
       parserOptions: {
         projectService: true,

homebrew/archon.rb

@@ -7,28 +7,28 @@
 class Archon < Formula
   desc "Remote agentic coding platform - control AI assistants from anywhere"
   homepage "https://github.com/coleam00/Archon"
-  version "0.3.0"
+  version "0.3.6"
   license "MIT"
 
   on_macos do
     on_arm do
       url "https://github.com/coleam00/Archon/releases/download/v#{version}/archon-darwin-arm64"
-      sha256 "2ff39add5306d839b28e05e58a98442a55d7b1a27d3045999ca62e9ccc7557b9"
+      sha256 "96b6dac50b046eece9eddbb988a0c39b4f9a0e2faac66e49b977ba6360069e86"
     end
     on_intel do
       url "https://github.com/coleam00/Archon/releases/download/v#{version}/archon-darwin-x64"
-      sha256 "7d5719a00e95d05303e0fd2586f6d69c41102bde1e23b11aa7e662905c235100"
+      sha256 "09f1dbe12417b4300b7b07b531eb7391a286305f8d4eafc11e7f61f5d26eb8eb"
     end
   end
 
   on_linux do
     on_arm do
       url "https://github.com/coleam00/Archon/releases/download/v#{version}/archon-linux-arm64"
-      sha256 "8bf7c0a335455b10f7362902d78b2b9a90778d4d2e979153ab5b114d4edb996c"
+      sha256 "80b06a6ff699ec57cd4a3e49cfe7b899a3e8212688d70285f5a887bf10086731"
     end
     on_intel do
       url "https://github.com/coleam00/Archon/releases/download/v#{version}/archon-linux-x64"
-      sha256 "f1f730ebea4d77e6fa533a8fbdd194fb356ddc441160fae5f63f6225c27ff8fc"
+      sha256 "09f5dac6db8037ed6f3e5b7e9c5eb8e37f19822a4ed2bf4cd7e654780f9d00de"
     end
   end
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "archon",
-  "version": "0.3.1",
+  "version": "0.3.6",
   "private": true,
   "workspaces": [
     "packages/*"
@@ -14,9 +14,11 @@
     "build": "bun --filter '*' build",
     "build:binaries": "bash scripts/build-binaries.sh",
     "build:checksums": "bash scripts/checksums.sh",
+    "generate:bundled": "bun run scripts/generate-bundled-defaults.ts",
+    "check:bundled": "bun run scripts/generate-bundled-defaults.ts --check",
     "test": "bun --filter '*' --parallel test",
     "test:watch": "bun --filter @archon/server test:watch",
-    "type-check": "bun --filter '*' type-check",
+    "type-check": "bun --filter '*' type-check && bun x tsc --noEmit -p scripts/tsconfig.json",
     "lint": "bun x eslint . --cache",
     "lint:fix": "bun x eslint . --cache --fix",
     "format": "bun x prettier --write .",
@@ -25,7 +27,7 @@
     "build:web": "bun --filter @archon/web build",
     "dev:docs": "bun --filter @archon/docs-web dev",
     "build:docs": "bun --filter @archon/docs-web build",
-    "validate": "bun run type-check && bun run lint --max-warnings 0 && bun run format:check && bun run test",
+    "validate": "bun run check:bundled && bun run type-check && bun run lint --max-warnings 0 && bun run format:check && bun run test",
     "prepare": "husky",
     "setup-auth": "bun --filter @archon/server setup-auth"
   },

packages/adapters/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@archon/adapters",
-  "version": "0.1.0",
+  "version": "0.3.6",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./*": "./src/*"
+    "./*": "./src/*",
+    "./community/forge/gitea": "./src/community/forge/gitea/index.ts",
+    "./community/forge/gitlab": "./src/community/forge/gitlab/index.ts"
   },
   "scripts": {
     "test": "bun test src/chat/ src/community/chat/ src/community/forge/gitlab/auth.test.ts src/forge/github/auth.test.ts src/utils/ && bun test src/forge/github/adapter.test.ts && bun test src/forge/github/context.test.ts && bun test src/community/forge/gitea/adapter.test.ts && bun test src/community/forge/gitlab/adapter.test.ts",
@@ -20,7 +22,7 @@
     "@octokit/rest": "^22.0.0",
     "@slack/bolt": "^4.6.0",
     "discord.js": "^14.16.0",
-    "telegraf": "^4.16.0",
+    "grammy": "^1.36.0",
     "telegramify-markdown": "^1.3.0"
   },
   "peerDependencies": {

packages/adapters/src/chat/telegram/adapter.test.ts

@@ -52,7 +52,7 @@ describe('TelegramAdapter', () => {
       const adapter = new TelegramAdapter('fake-token-for-testing');
       const bot = adapter.getBot();
       expect(bot).toBeDefined();
-      expect(bot.telegram).toBeDefined();
+      expect(bot.api).toBeDefined();
     });
   });
 
@@ -64,9 +64,8 @@ describe('TelegramAdapter', () => {
       adapter = new TelegramAdapter('fake-token-for-testing');
       mockSendMessage = mock(() => Promise.resolve());
       // Override bot's sendMessage
-      (
-        adapter.getBot().telegram as unknown as { sendMessage: Mock<() => Promise<void>> }
-      ).sendMessage = mockSendMessage;
+      (adapter.getBot().api as unknown as { sendMessage: Mock<() => Promise<void>> }).sendMessage =
+        mockSendMessage;
     });
 
     test('should send with MarkdownV2 parse_mode', async () => {
@@ -172,7 +171,7 @@ describe('TelegramAdapter', () => {
       const adapter = new TelegramAdapter('fake-token-for-testing');
       const ctx = {
         chat: { id: 12345 },
-      } as unknown as import('telegraf').Context;
+      } as unknown as import('grammy').Context;
 
       expect(adapter.getConversationId(ctx)).toBe('12345');
     });
@@ -181,7 +180,7 @@ describe('TelegramAdapter', () => {
       const adapter = new TelegramAdapter('fake-token-for-testing');
       const ctx = {
         chat: { id: -987654321 },
-      } as unknown as import('telegraf').Context;
+      } as unknown as import('grammy').Context;
 
       expect(adapter.getConversationId(ctx)).toBe('-987654321');
     });
@@ -190,7 +189,7 @@ describe('TelegramAdapter', () => {
       const adapter = new TelegramAdapter('fake-token-for-testing');
       const ctx = {
         chat: { id: -1001234567890 },
-      } as unknown as import('telegraf').Context;
+      } as unknown as import('grammy').Context;
 
       expect(adapter.getConversationId(ctx)).toBe('-1001234567890');
     });
@@ -199,7 +198,7 @@ describe('TelegramAdapter', () => {
       const adapter = new TelegramAdapter('fake-token-for-testing');
       const ctx = {
         chat: undefined,
-      } as unknown as import('telegraf').Context;
+      } as unknown as import('grammy').Context;
 
       expect(() => adapter.getConversationId(ctx)).toThrow('No chat in context');
     });
@@ -208,7 +207,7 @@ describe('TelegramAdapter', () => {
       const adapter = new TelegramAdapter('fake-token-for-testing');
       const ctx = {
         chat: null,
-      } as unknown as import('telegraf').Context;
+      } as unknown as import('grammy').Context;
 
       expect(() => adapter.getConversationId(ctx)).toThrow('No chat in context');
     });
@@ -235,6 +234,16 @@ describe('TelegramAdapter', () => {
     });
   });
 
+  describe('stop()', () => {
+    test('should call bot.stop()', () => {
+      const adapter = new TelegramAdapter('fake-token-for-testing');
+      const mockStop = mock(() => undefined);
+      (adapter.getBot() as unknown as { stop: typeof mockStop }).stop = mockStop;
+      adapter.stop();
+      expect(mockStop).toHaveBeenCalledTimes(1);
+    });
+  });
+
   describe('start()', () => {
     beforeEach(() => {
       mockLogger.warn.mockClear();
@@ -243,14 +252,20 @@ describe('TelegramAdapter', () => {
 
     test('should retry on 409 and succeed on second attempt', async () => {
       const adapter = new TelegramAdapter('fake-token-for-testing');
-      const mockLaunch = mock<() => Promise<void>>()
+      // grammY's start() resolves when bot stops, not when started — onStart fires on startup
+      const mockStart = mock<
+        (opts?: { drop_pending_updates?: boolean; onStart?: () => void }) => Promise<void>
+      >()
         .mockRejectedValueOnce(new Error('409: Conflict: terminated by other getUpdates request'))
-        .mockResolvedValueOnce(undefined);
-      (adapter.getBot() as unknown as { launch: typeof mockLaunch }).launch = mockLaunch;
+        .mockImplementationOnce(opts => {
+          opts?.onStart?.();
+          return new Promise(() => {});
+        });
+      (adapter.getBot() as unknown as { start: typeof mockStart }).start = mockStart;
 
       await adapter.start({ retryDelayMs: 0 });
 
-      expect(mockLaunch).toHaveBeenCalledTimes(2);
+      expect(mockStart).toHaveBeenCalledTimes(2);
       expect(mockLogger.warn).toHaveBeenCalledWith(
         expect.objectContaining({ attempt: 1, maxAttempts: 3 }),
         'telegram.start_conflict_retrying'
@@ -260,41 +275,48 @@ describe('TelegramAdapter', () => {
 
     test('should throw immediately on non-409 error', async () => {
       const adapter = new TelegramAdapter('fake-token-for-testing');
-      const mockLaunch = mock<() => Promise<void>>().mockRejectedValueOnce(
-        new Error('401: Unauthorized')
-      );
-      (adapter.getBot() as unknown as { launch: typeof mockLaunch }).launch = mockLaunch;
+      const mockStart = mock<
+        (opts?: { drop_pending_updates?: boolean; onStart?: () => void }) => Promise<void>
+      >().mockRejectedValueOnce(new Error('401: Unauthorized'));
+      (adapter.getBot() as unknown as { start: typeof mockStart }).start = mockStart;
 
       await expect(adapter.start({ retryDelayMs: 0 })).rejects.toThrow('401: Unauthorized');
-      expect(mockLaunch).toHaveBeenCalledTimes(1);
+      expect(mockStart).toHaveBeenCalledTimes(1);
     });
 
     test('should retry twice on 409 and succeed on third attempt', async () => {
       const adapter = new TelegramAdapter('fake-token-for-testing');
       const conflictError = new Error('409: Conflict: terminated by other getUpdates request');
-      const mockLaunch = mock<() => Promise<void>>()
+      const mockStart = mock<
+        (opts?: { drop_pending_updates?: boolean; onStart?: () => void }) => Promise<void>
+      >()
         .mockRejectedValueOnce(conflictError)
         .mockRejectedValueOnce(conflictError)
-        .mockResolvedValueOnce(undefined);
-      (adapter.getBot() as unknown as { launch: typeof mockLaunch }).launch = mockLaunch;
+        .mockImplementationOnce(opts => {
+          opts?.onStart?.();
+          return new Promise(() => {});
+        });
+      (adapter.getBot() as unknown as { start: typeof mockStart }).start = mockStart;
 
       await adapter.start({ retryDelayMs: 0 });
 
-      expect(mockLaunch).toHaveBeenCalledTimes(3);
+      expect(mockStart).toHaveBeenCalledTimes(3);
       expect(mockLogger.warn).toHaveBeenCalledTimes(2);
     });
 
     test('should throw after exhausting all 409 retry attempts', async () => {
       const adapter = new TelegramAdapter('fake-token-for-testing');
       const conflictError = new Error('409: Conflict: terminated by other getUpdates request');
-      const mockLaunch = mock<() => Promise<void>>()
+      const mockStart = mock<
+        (opts?: { drop_pending_updates?: boolean; onStart?: () => void }) => Promise<void>
+      >()
         .mockRejectedValueOnce(conflictError)
         .mockRejectedValueOnce(conflictError)
         .mockRejectedValueOnce(conflictError);
-      (adapter.getBot() as unknown as { launch: typeof mockLaunch }).launch = mockLaunch;
+      (adapter.getBot() as unknown as { start: typeof mockStart }).start = mockStart;
 
       await expect(adapter.start({ retryDelayMs: 0 })).rejects.toThrow('409');
-      expect(mockLaunch).toHaveBeenCalledTimes(3);
+      expect(mockStart).toHaveBeenCalledTimes(3);
     });
   });
 });

packages/adapters/src/chat/telegram/adapter.ts

@@ -1,8 +1,8 @@
 /**
- * Telegram platform adapter using Telegraf SDK
+ * Telegram platform adapter using grammY SDK
  * Handles message sending with 4096 character limit splitting
  */
-import { Telegraf, Context } from 'telegraf';
+import { Bot, Context } from 'grammy';
 import type { IPlatformAdapter, MessageMetadata } from '@archon/core';
 import { createLogger } from '@archon/paths';
 import { parseAllowedUserIds, isUserAuthorized } from './auth';
@@ -20,17 +20,14 @@ function getLog(): ReturnType<typeof createLogger> {
 const MAX_LENGTH = 4096;
 
 export class TelegramAdapter implements IPlatformAdapter {
-  private bot: Telegraf;
+  private bot: Bot;
   private streamingMode: 'stream' | 'batch';
   private allowedUserIds: number[];
   private messageHandler: ((ctx: TelegramMessageContext) => Promise<void>) | null = null;
 
   constructor(token: string, mode: 'stream' | 'batch' = 'stream') {
-    // Disable handler timeout to support long-running AI operations
-    // Default is 90 seconds which is too short for complex coding tasks
-    this.bot = new Telegraf(token, {
-      handlerTimeout: Infinity,
-    });
+    // grammY does not impose a handler timeout by default (unlike Telegraf's 90s limit)
+    this.bot = new Bot(token);
     this.streamingMode = mode;
 
     // Parse Telegram user whitelist (optional - empty = open access)
@@ -87,20 +84,20 @@ export class TelegramAdapter implements IPlatformAdapter {
       let subChunk = '';
       for (const line of lines) {
         if (subChunk.length + line.length + 1 > MAX_LENGTH - 100) {
-          if (subChunk) await this.bot.telegram.sendMessage(id, subChunk);
+          if (subChunk) await this.bot.api.sendMessage(id, subChunk);
           subChunk = line;
         } else {
           subChunk += (subChunk ? '\n' : '') + line;
         }
       }
-      if (subChunk) await this.bot.telegram.sendMessage(id, subChunk);
+      if (subChunk) await this.bot.api.sendMessage(id, subChunk);
       return;
     }
 
     // Try MarkdownV2 formatting
     const formatted = convertToTelegramMarkdown(chunk);
     try {
-      await this.bot.telegram.sendMessage(id, formatted, { parse_mode: 'MarkdownV2' });
+      await this.bot.api.sendMessage(id, formatted, { parse_mode: 'MarkdownV2' });
       getLog().debug({ chunkLength: chunk.length }, 'telegram.markdownv2_chunk_sent');
     } catch (error) {
       // Fallback to stripped plain text for this chunk
@@ -113,14 +110,14 @@ export class TelegramAdapter implements IPlatformAdapter {
         },
         'telegram.markdownv2_failed'
       );
-      await this.bot.telegram.sendMessage(id, stripMarkdown(chunk));
+      await this.bot.api.sendMessage(id, stripMarkdown(chunk));
     }
   }
 
   /**
-   * Get the Telegraf bot instance
+   * Get the grammY bot instance
    */
-  getBot(): Telegraf {
+  getBot(): Bot {
     return this.bot;
   }
 
@@ -171,17 +168,15 @@ export class TelegramAdapter implements IPlatformAdapter {
    */
   async start(options?: { retryDelayMs?: number }): Promise<void> {
     // Register message handler before launch
-    this.bot.on('message', ctx => {
-      if (!('text' in ctx.message)) return;
-
+    this.bot.on('message:text', ctx => {
       const message = ctx.message.text;
       if (!message) return;
 
       // Authorization check - verify sender is in whitelist
-      const userId = ctx.from.id;
+      const userId = ctx.from?.id;
       if (!isUserAuthorized(userId, this.allowedUserIds)) {
         // Log unauthorized attempt (mask user ID for privacy)
-        const maskedId = `${String(userId).slice(0, 4)}***`;
+        const maskedId = userId !== undefined ? `${String(userId).slice(0, 4)}***` : 'unknown';
         getLog().info({ maskedUserId: maskedId }, 'telegram.unauthorized_message');
         return; // Silent rejection
       }
@@ -190,6 +185,11 @@ export class TelegramAdapter implements IPlatformAdapter {
         const conversationId = this.getConversationId(ctx);
         // Fire-and-forget - errors handled by caller
         void this.messageHandler({ conversationId, message, userId });
+      } else {
+        // Intentional: message dropped silently if handler not registered yet.
+        // In production the server always calls onMessage() before start(); this
+        // path only surfaces during development or misconfiguration.
+        getLog().debug({ chatId: ctx.chat?.id }, 'telegram.message_dropped_no_handler');
       }
     });
 
@@ -200,9 +200,26 @@ export class TelegramAdapter implements IPlatformAdapter {
     const RETRY_DELAY_MS = options?.retryDelayMs ?? 60_000;
     for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
       try {
-        // dropPendingUpdates: true — discard queued messages from while the bot was offline
+        // drop_pending_updates: true — discard queued messages from while the bot was offline
         // to avoid reprocessing stale commands after a container restart.
-        await this.bot.launch({ dropPendingUpdates: true });
+        // grammY's start() resolves only when the bot stops; use onStart callback to detect
+        // successful launch and return immediately while the bot continues running in background.
+        await new Promise<void>((resolve, reject) => {
+          this.bot
+            .start({
+              drop_pending_updates: true,
+              onStart: () => {
+                resolve();
+              },
+            })
+            .catch((err: unknown) => {
+              const error = err instanceof Error ? err : new Error(String(err));
+              // Log post-startup crashes — after onStart fires the reject() below is a no-op
+              // (Promise already settled), but the error should still be observable in logs.
+              getLog().error({ err: error }, 'telegram.bot_runtime_error');
+              reject(error);
+            });
+        });
         getLog().info('telegram.bot_started');
         return;
       } catch (err) {

packages/adapters/src/community/forge/gitlab/adapter.test.ts

@@ -80,6 +80,10 @@ mock.module('@archon/isolation', () => ({
   IsolationHints: {},
 }));
 
+// Mock global fetch to prevent real HTTP calls (gitlab.example.com hangs on CI Linux)
+const mockFetch = mock(() => Promise.resolve(new Response(JSON.stringify({}), { status: 200 })));
+globalThis.fetch = mockFetch as typeof globalThis.fetch;
+
 // Now import the adapter (after all mocks)
 const { GitLabAdapter } = await import('./adapter');
 const { ConversationLockManager } = await import('@archon/core');
@@ -158,6 +162,7 @@ describe('GitLabAdapter', () => {
   beforeEach(() => {
     mockHandleMessage.mockClear();
     mockOnConversationClosed.mockClear();
+    mockFetch.mockClear();
     // Reset env
     delete process.env.GITLAB_ALLOWED_USERS;
   });

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archon/cli",
-  "version": "0.2.13",
+  "version": "0.3.6",
   "type": "module",
   "main": "./src/cli.ts",
   "bin": {
@@ -8,14 +8,17 @@
   },
   "scripts": {
     "cli": "bun src/cli.ts",
-    "test": "bun test src/commands/version.test.ts src/commands/setup.test.ts && bun test src/commands/workflow.test.ts && bun test src/commands/isolation.test.ts && bun test src/commands/chat.test.ts",
+    "test": "bun test src/commands/version.test.ts src/commands/setup.test.ts && bun test src/commands/workflow.test.ts && bun test src/commands/isolation.test.ts && bun test src/commands/chat.test.ts && bun test src/commands/serve.test.ts",
     "type-check": "bun x tsc --noEmit"
   },
   "dependencies": {
+    "@archon/adapters": "workspace:*",
     "@archon/core": "workspace:*",
     "@archon/git": "workspace:*",
     "@archon/isolation": "workspace:*",
     "@archon/paths": "workspace:*",
+    "@archon/providers": "workspace:*",
+    "@archon/server": "workspace:*",
     "@archon/workflows": "workspace:*",
     "@clack/prompts": "^1.0.0",
     "dotenv": "^17.2.3"

packages/cli/src/cli.test.ts

@@ -26,6 +26,8 @@ describe('CLI argument parsing', () => {
         spawn: { type: 'boolean' },
         quiet: { type: 'boolean', short: 'q' },
         verbose: { type: 'boolean', short: 'v' },
+        scope: { type: 'string' },
+        force: { type: 'boolean' },
       },
       allowPositionals: true,
       strict: false,
@@ -165,6 +167,35 @@ describe('CLI argument parsing', () => {
       expect(result.positionals).toContain('/path'); // /path becomes positional
     });
   });
+
+  describe('setup --scope and --force flags (#1303)', () => {
+    it('parses --scope home', () => {
+      const result = parseCliArgs(['setup', '--scope', 'home']);
+      expect(result.values.scope).toBe('home');
+    });
+
+    it('parses --scope project', () => {
+      const result = parseCliArgs(['setup', '--scope', 'project']);
+      expect(result.values.scope).toBe('project');
+    });
+
+    it('defaults --scope to undefined when not provided', () => {
+      const result = parseCliArgs(['setup']);
+      expect(result.values.scope).toBeUndefined();
+    });
+
+    it('parses --force as boolean', () => {
+      const result = parseCliArgs(['setup', '--force']);
+      expect(result.values.force).toBe(true);
+    });
+
+    it('captures an invalid --scope value verbatim for caller validation', () => {
+      // parseArgs itself does not validate the enum; cli.ts validates and
+      // exits on unknown scope values. The test documents the contract.
+      const result = parseCliArgs(['setup', '--scope', 'nonsense']);
+      expect(result.values.scope).toBe('nonsense');
+    });
+  });
 });
 
 describe('Conversation ID generation', () => {

packages/cli/src/cli.ts

@@ -7,41 +7,21 @@
  *   archon workflow run <name> [msg]  Run a workflow
  *   archon version                    Show version info
  */
+// Must be the very first import — strips Bun-auto-loaded CWD .env keys before
+// any module reads process.env at init time (e.g. @archon/paths/logger reads LOG_LEVEL).
+import '@archon/paths/strip-cwd-env-boot';
+// Then load archon-owned env from ~/.archon/.env (user scope) and
+// <cwd>/.archon/.env (repo scope, wins over user). Both with override: true.
+// See packages/paths/src/env-loader.ts and the three-path model (#1302 / #1303).
+import { loadArchonEnv } from '@archon/paths/env-loader';
+loadArchonEnv(process.cwd());
+
 import { parseArgs } from 'util';
-import { config } from 'dotenv';
 import { resolve } from 'path';
 import { existsSync } from 'fs';
 
-// Strip all vars that Bun may have auto-loaded from CWD's .env.
-// Bun auto-loads .env relative to CWD before any user code runs. The CLI
-// runs from target repos whose .env contains keys for that app (ANTHROPIC_API_KEY,
-// DATABASE_URL, OPENAI_API_KEY, etc.) — none of which should affect Archon.
-// Strategy: parse the CWD .env without applying it, then delete those keys.
-const cwdEnvPath = resolve(process.cwd(), '.env');
-if (existsSync(cwdEnvPath)) {
-  const cwdEnvResult = config({ path: cwdEnvPath, processEnv: {} });
-  // If parse fails, cwdEnvResult.parsed is undefined — safe to skip:
-  // Bun uses the same RFC-style parser, so a file dotenv cannot parse
-  // was also unparseable by Bun and contributed no keys to process.env.
-  if (cwdEnvResult.parsed) {
-    for (const key of Object.keys(cwdEnvResult.parsed)) {
-      Reflect.deleteProperty(process.env, key);
-    }
-  }
-}
-
-// Load .env from global Archon config only (override: true so ~/.archon/.env
-// always wins over any remaining Bun-auto-loaded vars)
-const globalEnvPath = resolve(process.env.HOME ?? '~', '.archon', '.env');
-if (existsSync(globalEnvPath)) {
-  const result = config({ path: globalEnvPath, override: true });
-  if (result.error) {
-    // Logger may not be available yet (early startup), so use console for user-facing error
-    console.error(`Error loading .env from ${globalEnvPath}: ${result.error.message}`);
-    console.error('Hint: Check for syntax errors in your .env file.');
-    process.exit(1);
-  }
-}
+// CLAUDECODE=1 warning is emitted inside stripCwdEnv() (boot import above)
+// BEFORE the marker is deleted from process.env. No duplicate warning here.
 
 // Smart defaults for Claude auth
 // If no explicit tokens, default to global auth from `claude /login`
@@ -53,6 +33,11 @@ if (!process.env.CLAUDE_API_KEY && !process.env.CLAUDE_CODE_OAUTH_TOKEN) {
 
 // DATABASE_URL is no longer required - SQLite will be used as default
 
+// Bootstrap provider registry before any provider lookups
+import { registerBuiltinProviders, registerCommunityProviders } from '@archon/providers';
+registerBuiltinProviders();
+registerCommunityProviders();
+
 // Import commands after dotenv is loaded
 import { versionCommand } from './commands/version';
 import {
@@ -78,8 +63,16 @@ import { continueCommand } from './commands/continue';
 import { chatCommand } from './commands/chat';
 import { setupCommand } from './commands/setup';
 import { validateWorkflowsCommand, validateCommandsCommand } from './commands/validate';
+import { serveCommand } from './commands/serve';
 import { closeDatabase } from '@archon/core';
-import { setLogLevel, createLogger } from '@archon/paths';
+import {
+  setLogLevel,
+  createLogger,
+  checkForUpdate,
+  BUNDLED_IS_BINARY,
+  BUNDLED_VERSION,
+  shutdownTelemetry,
+} from '@archon/paths';
 import * as git from '@archon/git';
 
 /** Lazy-initialized logger (deferred so test mocks can intercept createLogger) */
@@ -110,6 +103,7 @@ Commands:
   isolation cleanup --merged Remove environments with branches merged into main
   continue <branch> [msg]    Continue work on an existing worktree with prior context
   complete <branch> [...]    Complete branch lifecycle (remove worktree + branches)
+  serve                      Start the web UI server (downloads web UI on first run)
   validate workflows [name]  Validate workflow definitions and their references
   validate commands [name]   Validate command files
   version                    Show version info
@@ -127,9 +121,8 @@ Options:
   --json                     Output machine-readable JSON (for workflow list)
   --workflow <name>          Workflow to run for 'continue' (default: archon-assist)
   --no-context               Skip context injection for 'continue'
-  --allow-env-keys           Grant env-key consent during auto-registration
-                             (bypasses the env-leak gate for this codebase;
-                             logs an audit entry)
+  --port <port>              Override server port for 'serve' (default: 3090)
+  --download-only            Download web UI without starting the server
 
 Examples:
   archon chat "What does the orchestrator do?"
@@ -155,6 +148,20 @@ async function closeDb(): Promise<void> {
   }
 }
 
+async function printUpdateNotice(quiet: boolean | undefined): Promise<void> {
+  if (quiet || !BUNDLED_IS_BINARY) return;
+  try {
+    const result = await checkForUpdate(BUNDLED_VERSION);
+    if (result?.updateAvailable) {
+      process.stderr.write(
+        `Update available: v${result.currentVersion} → v${result.latestVersion} — ${result.releaseUrl}\n`
+      );
+    }
+  } catch (err) {
+    getLog().debug({ err }, 'update_check.notice_failed');
+  }
+}
+
 /**
  * Main CLI entry point
  * Returns exit code (0 = success, non-zero = failure)
@@ -193,7 +200,10 @@ async function main(): Promise<number> {
         reason: { type: 'string' },
         workflow: { type: 'string' },
         'no-context': { type: 'boolean' },
-        'allow-env-keys': { type: 'boolean' },
+        port: { type: 'string' },
+        'download-only': { type: 'boolean' },
+        scope: { type: 'string' },
+        force: { type: 'boolean' },
       },
       allowPositionals: true,
       strict: false, // Allow unknown flags to pass through
@@ -215,8 +225,6 @@ async function main(): Promise<number> {
   const resumeFlag = values.resume as boolean | undefined;
   const spawnFlag = values.spawn as boolean | undefined;
   const jsonFlag = values.json as boolean | undefined;
-  const allowEnvKeysFlag = values['allow-env-keys'] as boolean | undefined;
-
   // Handle help flag
   if (values.help) {
     printUsage();
@@ -228,7 +236,7 @@ async function main(): Promise<number> {
   const subcommand = positionals[1];
 
   // Commands that don't require git repo validation
-  const noGitCommands = ['version', 'help', 'setup', 'chat', 'continue'];
+  const noGitCommands = ['version', 'help', 'setup', 'chat', 'continue', 'serve'];
   const requiresGitRepo = !noGitCommands.includes(command ?? '');
 
   try {
@@ -282,9 +290,30 @@ async function main(): Promise<number> {
         break;
       }
 
-      case 'setup':
-        await setupCommand({ spawn: spawnFlag, repoPath: cwd });
+      case 'setup': {
+        const rawScope = values.scope as string | undefined;
+        if (rawScope !== undefined && rawScope !== 'home' && rawScope !== 'project') {
+          console.error(`Error: Invalid --scope: "${rawScope}". Must be "home" or "project".`);
+          return 1;
+        }
+        const scope: 'home' | 'project' = rawScope ?? 'home';
+        const forceFlag = (values.force as boolean | undefined) ?? false;
+        // For --scope project, resolve to the git repo root so running from a
+        // subdirectory writes to <repo-root>/.archon/.env (what loadArchonEnv
+        // reads at boot) — not <subdir>/.archon/.env.
+        let repoPath = cwd;
+        if (scope === 'project') {
+          const repoRoot = await git.findRepoRoot(cwd);
+          if (!repoRoot) {
+            console.error('Error: --scope project requires running from inside a git repository.');
+            console.error('Run from the repo root, pass --cwd <repo>, or use --scope home.');
+            return 1;
+          }
+          repoPath = repoRoot;
+        }
+        await setupCommand({ spawn: spawnFlag, repoPath, scope, force: forceFlag });
         break;
+      }
 
       case 'workflow':
         switch (subcommand) {
@@ -328,7 +357,6 @@ async function main(): Promise<number> {
               fromBranch,
               noWorktree,
               resume: resumeFlag,
-              allowEnvKeys: allowEnvKeysFlag,
               quiet: values.quiet as boolean | undefined,
               verbose: values.verbose as boolean | undefined,
             };
@@ -376,10 +404,11 @@ async function main(): Promise<number> {
           case 'reject': {
             const rejectRunId = positionals[2];
             if (!rejectRunId) {
-              console.error('Usage: archon workflow reject <run-id> [--reason "..."]');
+              console.error('Usage: archon workflow reject <run-id> [reason]');
               return 1;
             }
-            const rejectReason = values.reason as string | undefined;
+            const rejectReason =
+              (values.reason as string | undefined) || positionals.slice(3).join(' ') || undefined;
             await workflowRejectCommand(rejectRunId, rejectReason);
             break;
           }
@@ -534,6 +563,12 @@ async function main(): Promise<number> {
         break;
       }
 
+      case 'serve': {
+        const servePort = values.port !== undefined ? Number(values.port) : undefined;
+        const downloadOnly = Boolean(values['download-only']);
+        return await serveCommand({ port: servePort, downloadOnly });
+      }
+
       default:
         if (command === undefined) {
           console.error('Missing command');
@@ -543,6 +578,7 @@ async function main(): Promise<number> {
         printUsage();
         return 1;
     }
+    await printUpdateNotice(values.quiet as boolean | undefined);
     return 0;
   } catch (error) {
     const err = error as Error;
@@ -552,6 +588,9 @@ async function main(): Promise<number> {
     }
     return 1;
   } finally {
+    // Flush queued telemetry events before the CLI process exits.
+    // Short-lived CLI commands lose buffered events if shutdown() is skipped.
+    await shutdownTelemetry();
     // Always close database connection
     await closeDb();
   }

packages/cli/src/commands/isolation.test.ts

@@ -36,7 +36,9 @@ mock.module('@archon/core/db/workflows', () => ({
   getActiveWorkflowRunByPath: mockGetActiveWorkflowRunByPath,
 }));
 
-const mockRemoveEnvironment = mock(() => Promise.resolve());
+const mockRemoveEnvironment = mock(() =>
+  Promise.resolve({ worktreeRemoved: true, branchDeleted: true, warnings: [] })
+);
 const mockCleanupMergedWorktrees = mock(() => Promise.resolve({ removed: [], skipped: [] }));
 
 mock.module('@archon/core/services/cleanup-service', () => ({
@@ -136,7 +138,11 @@ describe('isolationCompleteCommand', () => {
 
   it('completes a branch when env is found and all checks pass', async () => {
     mockFindActiveByBranchName.mockResolvedValueOnce(mockEnv);
-    mockRemoveEnvironment.mockResolvedValueOnce(undefined);
+    mockRemoveEnvironment.mockResolvedValueOnce({
+      worktreeRemoved: true,
+      branchDeleted: true,
+      warnings: [],
+    });
 
     await isolationCompleteCommand(['feature-branch'], { force: false, deleteRemote: true });
 
@@ -309,7 +315,11 @@ describe('isolationCompleteCommand', () => {
 
   it('skips PR check with warning when gh CLI is not available', async () => {
     mockFindActiveByBranchName.mockResolvedValueOnce(mockEnv);
-    mockRemoveEnvironment.mockResolvedValueOnce(undefined);
+    mockRemoveEnvironment.mockResolvedValueOnce({
+      worktreeRemoved: true,
+      branchDeleted: true,
+      warnings: [],
+    });
     mockExecFileAsync.mockImplementation((cmd: string) => {
       if (cmd === 'gh') {
         const err = Object.assign(new Error('spawn gh ENOENT'), { code: 'ENOENT' });
@@ -335,7 +345,11 @@ describe('isolationCompleteCommand', () => {
       id: 'run-abc',
       workflow_name: 'implement',
     });
-    mockRemoveEnvironment.mockResolvedValueOnce(undefined);
+    mockRemoveEnvironment.mockResolvedValueOnce({
+      worktreeRemoved: true,
+      branchDeleted: true,
+      warnings: [],
+    });
 
     await isolationCompleteCommand(['dirty-branch'], { force: true, deleteRemote: true });
 
@@ -368,7 +382,7 @@ describe('isolationCompleteCommand', () => {
       .mockResolvedValueOnce(null) // not found: branch-2
       .mockResolvedValueOnce(mockEnv); // found: branch-3 (will fail)
     mockRemoveEnvironment
-      .mockResolvedValueOnce(undefined) // branch-1 succeeds
+      .mockResolvedValueOnce({ worktreeRemoved: true, branchDeleted: true, warnings: [] }) // branch-1 succeeds
       .mockRejectedValueOnce(new Error('some error')); // branch-3 fails
 
     await isolationCompleteCommand(['branch-1', 'branch-2', 'branch-3'], {
@@ -378,6 +392,59 @@ describe('isolationCompleteCommand', () => {
 
     expect(consoleLogSpy).toHaveBeenCalledWith('\nComplete: 1 completed, 1 failed, 1 not found');
   });
+  it('counts as failed when removeEnvironment returns skippedReason (ghost worktree)', async () => {
+    mockFindActiveByBranchName.mockResolvedValueOnce(mockEnv);
+    mockRemoveEnvironment.mockResolvedValueOnce({
+      worktreeRemoved: false,
+      branchDeleted: false,
+      skippedReason: 'has uncommitted changes',
+      warnings: [],
+    });
+
+    await isolationCompleteCommand(['ghost-branch'], { force: true, deleteRemote: true });
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      '  Blocked: ghost-branch — has uncommitted changes'
+    );
+    expect(consoleErrorSpy).toHaveBeenCalledWith('    Use --force to override.');
+    expect(consoleLogSpy).toHaveBeenCalledWith('\nComplete: 0 completed, 1 failed, 0 not found');
+  });
+
+  it('counts as failed when removeEnvironment returns partial (worktree not removed, branch deleted)', async () => {
+    mockFindActiveByBranchName.mockResolvedValueOnce(mockEnv);
+    mockRemoveEnvironment.mockResolvedValueOnce({
+      worktreeRemoved: false,
+      branchDeleted: true,
+      warnings: ['Some warning'],
+      skippedReason: undefined,
+    });
+
+    await isolationCompleteCommand(['partial-branch'], { force: true, deleteRemote: true });
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      '  Partial: partial-branch — worktree was not removed from disk (branch deleted, DB updated)'
+    );
+    expect(consoleErrorSpy).toHaveBeenCalledWith('    ⚠ Some warning');
+    expect(consoleLogSpy).toHaveBeenCalledWith('\nComplete: 0 completed, 1 failed, 0 not found');
+  });
+
+  it('surfaces warnings from removeEnvironment result', async () => {
+    mockFindActiveByBranchName.mockResolvedValueOnce(mockEnv);
+    mockRemoveEnvironment.mockResolvedValueOnce({
+      worktreeRemoved: true,
+      branchDeleted: false,
+      warnings: ["Cannot delete branch 'feature-branch': checked out elsewhere"],
+    });
+
+    await isolationCompleteCommand(['feature-branch'], { force: true, deleteRemote: true });
+
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      "  Warning: Cannot delete branch 'feature-branch': checked out elsewhere"
+    );
+    // Should still count as completed since worktree was removed
+    expect(consoleLogSpy).toHaveBeenCalledWith('  Completed: feature-branch');
+    expect(consoleLogSpy).toHaveBeenCalledWith('\nComplete: 1 completed, 0 failed, 0 not found');
+  });
 });
 
 describe('isolationCleanupMergedCommand', () => {

packages/cli/src/commands/isolation.ts

@@ -13,7 +13,10 @@ import {
   getDefaultBranch,
 } from '@archon/git';
 import { getIsolationProvider } from '@archon/isolation';
-import { removeEnvironment } from '@archon/core/services/cleanup-service';
+import {
+  removeEnvironment,
+  type RemoveEnvironmentResult,
+} from '@archon/core/services/cleanup-service';
 import {
   listEnvironments,
   cleanupMergedEnvironments,
@@ -298,12 +301,37 @@ export async function isolationCompleteCommand(
     }
 
     try {
-      await removeEnvironment(env.id, {
+      const result: RemoveEnvironmentResult = await removeEnvironment(env.id, {
         force: options.force,
         deleteRemoteBranch: options.deleteRemote ?? true,
       });
-      console.log(`  Completed: ${branch}`);
-      completed++;
+
+      // Surface warnings from partial cleanup
+      for (const warning of result.warnings) {
+        console.warn(`  Warning: ${warning}`);
+      }
+
+      if (result.skippedReason) {
+        console.error(`  Blocked: ${branch} — ${result.skippedReason}`);
+        if (result.skippedReason === 'has uncommitted changes') {
+          console.error('    Use --force to override.');
+        }
+        failed++;
+      } else if (!result.worktreeRemoved) {
+        const parts: string[] = [];
+        if (result.branchDeleted) parts.push('branch deleted');
+        parts.push('DB updated');
+        console.error(
+          `  Partial: ${branch} — worktree was not removed from disk (${parts.join(', ')})`
+        );
+        for (const warning of result.warnings) {
+          console.error(`    ⚠ ${warning}`);
+        }
+        failed++;
+      } else {
+        console.log(`  Completed: ${branch}`);
+        completed++;
+      }
     } catch (error) {
       const err = error as Error;
       getLog().warn({ err, branch, envId: env.id }, 'isolation.complete_failed');

packages/cli/src/commands/serve.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect, mock, beforeEach, afterEach, spyOn } from 'bun:test';
+
+// Mock @archon/paths BEFORE importing the module under test.
+// This sets BUNDLED_IS_BINARY = false (dev mode) so serveCommand rejects.
+const mockLogger = {
+  fatal: mock(() => undefined),
+  error: mock(() => undefined),
+  warn: mock(() => undefined),
+  info: mock(() => undefined),
+  debug: mock(() => undefined),
+  trace: mock(() => undefined),
+};
+mock.module('@archon/paths', () => ({
+  createLogger: mock(() => mockLogger),
+  getWebDistDir: mock((version: string) => `/tmp/test-archon/web-dist/${version}`),
+  BUNDLED_IS_BINARY: false,
+  BUNDLED_VERSION: 'dev',
+}));
+
+import { serveCommand, parseChecksum } from './serve';
+
+describe('parseChecksum', () => {
+  const validHash = 'a'.repeat(64);
+
+  it('should extract hash for matching filename', () => {
+    const checksums = [
+      `${'b'.repeat(64)}  archon-linux-x64`,
+      `${validHash}  archon-web.tar.gz`,
+      `${'c'.repeat(64)}  archon-darwin-arm64`,
+    ].join('\n');
+
+    expect(parseChecksum(checksums, 'archon-web.tar.gz')).toBe(validHash);
+  });
+
+  it('should handle single-space separator', () => {
+    const checksums = `${validHash} archon-web.tar.gz\n`;
+    expect(parseChecksum(checksums, 'archon-web.tar.gz')).toBe(validHash);
+  });
+
+  it('should throw for missing filename', () => {
+    const checksums = `${validHash}  archon-linux-x64\n`;
+    expect(() => parseChecksum(checksums, 'archon-web.tar.gz')).toThrow(
+      'Checksum not found for archon-web.tar.gz'
+    );
+  });
+
+  it('should throw for empty checksums text', () => {
+    expect(() => parseChecksum('', 'archon-web.tar.gz')).toThrow('Checksum not found');
+  });
+
+  it('should skip blank lines', () => {
+    const checksums = `\n${validHash}  archon-web.tar.gz\n\n`;
+    expect(parseChecksum(checksums, 'archon-web.tar.gz')).toBe(validHash);
+  });
+
+  it('should throw for malformed hash (not 64 hex chars)', () => {
+    const checksums = 'short_hash  archon-web.tar.gz\n';
+    expect(() => parseChecksum(checksums, 'archon-web.tar.gz')).toThrow(
+      'Malformed checksum entry for archon-web.tar.gz'
+    );
+  });
+
+  it('should throw for uppercase hex hash', () => {
+    const checksums = `${'A'.repeat(64)}  archon-web.tar.gz\n`;
+    expect(() => parseChecksum(checksums, 'archon-web.tar.gz')).toThrow(
+      'Malformed checksum entry for archon-web.tar.gz'
+    );
+  });
+});
+
+describe('serveCommand', () => {
+  let consoleErrorSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(() => {
+    consoleErrorSpy = spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    consoleErrorSpy.mockRestore();
+  });
+
+  it('should reject in dev mode (non-binary)', async () => {
+    const exitCode = await serveCommand({});
+    expect(exitCode).toBe(1);
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      'Error: `archon serve` is for compiled binaries only.'
+    );
+  });
+
+  it('should reject with downloadOnly in dev mode', async () => {
+    const exitCode = await serveCommand({ downloadOnly: true });
+    expect(exitCode).toBe(1);
+  });
+
+  it('should reject invalid port (NaN)', async () => {
+    const exitCode = await serveCommand({ port: NaN });
+    expect(exitCode).toBe(1);
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('--port must be an integer between 1 and 65535')
+    );
+  });
+
+  it('should reject port out of range', async () => {
+    const exitCode = await serveCommand({ port: 99999 });
+    expect(exitCode).toBe(1);
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('--port must be an integer between 1 and 65535')
+    );
+  });
+
+  it('should reject port 0', async () => {
+    const exitCode = await serveCommand({ port: 0 });
+    expect(exitCode).toBe(1);
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('--port must be an integer between 1 and 65535')
+    );
+  });
+});

packages/cli/src/commands/serve.ts

@@ -0,0 +1,186 @@
+import { dirname } from 'path';
+import { existsSync, mkdirSync, renameSync, rmSync } from 'fs';
+import { createLogger, getWebDistDir, BUNDLED_IS_BINARY, BUNDLED_VERSION } from '@archon/paths';
+
+const log = createLogger('cli.serve');
+
+const GITHUB_REPO = 'coleam00/Archon';
+
+function toError(err: unknown): Error {
+  return err instanceof Error ? err : new Error(String(err));
+}
+
+export interface ServeOptions {
+  /** TCP port to bind. Ignored when downloadOnly is true. Range: 1–65535. */
+  port?: number;
+  /** Download the web UI and exit without starting the server. */
+  downloadOnly?: boolean;
+}
+
+export async function serveCommand(opts: ServeOptions): Promise<number> {
+  if (
+    opts.port !== undefined &&
+    (!Number.isInteger(opts.port) || opts.port < 1 || opts.port > 65535)
+  ) {
+    console.error(`Error: --port must be an integer between 1 and 65535, got: ${opts.port}`);
+    return 1;
+  }
+
+  if (!BUNDLED_IS_BINARY) {
+    console.error('Error: `archon serve` is for compiled binaries only.');
+    console.error('For development, use: bun run dev');
+    return 1;
+  }
+
+  const version = BUNDLED_VERSION;
+  const webDistDir = getWebDistDir(version);
+
+  if (!existsSync(webDistDir)) {
+    try {
+      await downloadWebDist(version, webDistDir);
+    } catch (err) {
+      const error = toError(err);
+      log.error({ err: error, version, webDistDir }, 'web_dist.download_failed');
+      console.error(`Error: Failed to download web UI: ${error.message}`);
+      return 1;
+    }
+  } else {
+    log.info({ webDistDir }, 'web_dist.cache_hit');
+  }
+
+  if (opts.downloadOnly) {
+    log.info({ webDistDir }, 'web_dist.download_completed');
+    console.log(`Web UI downloaded to: ${webDistDir}`);
+    return 0;
+  }
+
+  // Import server and start (dynamic import keeps CLI startup fast for other commands)
+  try {
+    const { startServer } = await import('@archon/server');
+    await startServer({
+      webDistPath: webDistDir,
+      port: opts.port,
+    });
+  } catch (err) {
+    const error = toError(err);
+    log.error({ err: error, version, webDistDir, port: opts.port }, 'server.start_failed');
+    console.error(`Error: Server failed to start: ${error.message}`);
+    return 1;
+  }
+
+  // Block forever — Bun.serve() keeps the event loop alive, but the CLI's
+  // process.exit(exitCode) would kill it. Wait on a promise that only resolves
+  // on SIGINT/SIGTERM so the server stays running.
+  await new Promise<void>(resolve => {
+    process.once('SIGINT', resolve);
+    process.once('SIGTERM', resolve);
+  });
+  return 0;
+}
+
+async function downloadWebDist(version: string, targetDir: string): Promise<void> {
+  const tarballUrl = `https://github.com/${GITHUB_REPO}/releases/download/v${version}/archon-web.tar.gz`;
+  const checksumsUrl = `https://github.com/${GITHUB_REPO}/releases/download/v${version}/checksums.txt`;
+
+  log.info({ version, targetDir }, 'web_dist.download_started');
+  console.log(`Web UI not found locally — downloading from release v${version}...`);
+
+  // Download checksums and tarball in parallel
+  console.log(`Downloading ${tarballUrl}...`);
+  const [checksumsRes, tarballRes] = await Promise.all([
+    fetch(checksumsUrl).catch((err: unknown) => {
+      throw new Error(
+        `Network error fetching checksums from ${checksumsUrl}: ${(err as Error).message}`
+      );
+    }),
+    fetch(tarballUrl).catch((err: unknown) => {
+      throw new Error(
+        `Network error fetching tarball from ${tarballUrl}: ${(err as Error).message}`
+      );
+    }),
+  ]);
+  if (!checksumsRes.ok) {
+    throw new Error(
+      `Failed to download checksums: ${checksumsRes.status} ${checksumsRes.statusText}`
+    );
+  }
+  if (!tarballRes.ok) {
+    throw new Error(`Failed to download web UI: ${tarballRes.status} ${tarballRes.statusText}`);
+  }
+  const [checksumsText, tarballBuffer] = await Promise.all([
+    checksumsRes.text(),
+    tarballRes.arrayBuffer(),
+  ]);
+  const expectedHash = parseChecksum(checksumsText, 'archon-web.tar.gz');
+
+  // Verify checksum
+  const hasher = new Bun.CryptoHasher('sha256');
+  hasher.update(new Uint8Array(tarballBuffer));
+  const actualHash = hasher.digest('hex');
+
+  if (actualHash !== expectedHash) {
+    throw new Error(`Checksum mismatch: expected ${expectedHash}, got ${actualHash}`);
+  }
+  console.log('Checksum verified.');
+
+  // Extract to temp dir, then atomic rename
+  const tmpDir = `${targetDir}.tmp`;
+
+  // Clean up any previous failed attempt
+  rmSync(tmpDir, { recursive: true, force: true });
+  mkdirSync(tmpDir, { recursive: true });
+
+  // Extract tarball using tar (available on macOS/Linux)
+  const proc = Bun.spawn(['tar', 'xzf', '-', '-C', tmpDir, '--strip-components=1'], {
+    stdin: new Uint8Array(tarballBuffer),
+    stderr: 'pipe',
+  });
+  const exitCode = await proc.exited;
+  if (exitCode !== 0) {
+    const stderrText = await new Response(proc.stderr).text();
+    cleanupAndThrow(tmpDir, `tar extraction failed (exit ${exitCode}): ${stderrText.trim()}`);
+  }
+
+  // Verify extraction produced expected layout
+  if (!existsSync(`${tmpDir}/index.html`)) {
+    cleanupAndThrow(
+      tmpDir,
+      'Extraction produced unexpected layout — index.html not found in extracted dir'
+    );
+  }
+
+  // Atomic move into place
+  mkdirSync(dirname(targetDir), { recursive: true });
+  try {
+    renameSync(tmpDir, targetDir);
+  } catch (err) {
+    cleanupAndThrow(
+      tmpDir,
+      `Failed to move extracted web UI from ${tmpDir} to ${targetDir}: ${(err as Error).message}`
+    );
+  }
+  console.log(`Extracted to ${targetDir}`);
+}
+
+function cleanupAndThrow(tmpDir: string, message: string): never {
+  rmSync(tmpDir, { recursive: true, force: true });
+  throw new Error(message);
+}
+
+/**
+ * Parse a SHA-256 checksum from a checksums.txt file (sha256sum format).
+ * Format: `<hash>  <filename>` or `<hash> <filename>`
+ */
+export function parseChecksum(checksums: string, filename: string): string {
+  for (const line of checksums.split('\n')) {
+    const parts = line.trim().split(/\s+/);
+    if (parts.length >= 2 && parts[1] === filename) {
+      const hash = parts[0];
+      if (!/^[0-9a-f]{64}$/.test(hash)) {
+        throw new Error(`Malformed checksum entry for ${filename}: "${line.trim()}"`);
+      }
+      return hash;
+    }
+  }
+  throw new Error(`Checksum not found for ${filename} in checksums.txt`);
+}

packages/cli/src/commands/setup.test.ts

@@ -11,7 +11,13 @@ import {
   generateWebhookSecret,
   spawnTerminalWithSetup,
   copyArchonSkill,
+  detectClaudeExecutablePath,
+  writeScopedEnv,
+  serializeEnv,
+  resolveScopedEnvPath,
 } from './setup';
+import * as setupModule from './setup';
+import { parse as parseDotenv } from 'dotenv';
 
 // Test directory for file operations
 const TEST_DIR = join(tmpdir(), 'archon-setup-test-' + Date.now());
@@ -148,7 +154,9 @@ CODEX_ACCOUNT_ID=account1
       expect(content).toContain('# Using SQLite (default)');
       expect(content).toContain('CLAUDE_USE_GLOBAL_AUTH=true');
       expect(content).toContain('DEFAULT_AI_ASSISTANT=claude');
-      expect(content).toContain('PORT=3000');
+      // PORT is intentionally commented out — server and Vite both default to 3090 when unset (#1152).
+      expect(content).toContain('# PORT=3090');
+      expect(content).not.toMatch(/^PORT=/m);
       expect(content).not.toContain('DATABASE_URL=');
     });
 
@@ -176,6 +184,41 @@ CODEX_ACCOUNT_ID=account1
       expect(content).toContain('CLAUDE_API_KEY=sk-test-key');
     });
 
+    it('emits CLAUDE_BIN_PATH when claudeBinaryPath is configured', () => {
+      const content = generateEnvContent({
+        database: { type: 'sqlite' },
+        ai: {
+          claude: true,
+          claudeAuthType: 'global',
+          claudeBinaryPath: '/usr/local/lib/node_modules/@anthropic-ai/claude-code/cli.js',
+          codex: false,
+          defaultAssistant: 'claude',
+        },
+        platforms: { github: false, telegram: false, slack: false, discord: false },
+        botDisplayName: 'Archon',
+      });
+
+      expect(content).toContain(
+        'CLAUDE_BIN_PATH=/usr/local/lib/node_modules/@anthropic-ai/claude-code/cli.js'
+      );
+    });
+
+    it('omits CLAUDE_BIN_PATH when not configured', () => {
+      const content = generateEnvContent({
+        database: { type: 'sqlite' },
+        ai: {
+          claude: true,
+          claudeAuthType: 'global',
+          codex: false,
+          defaultAssistant: 'claude',
+        },
+        platforms: { github: false, telegram: false, slack: false, discord: false },
+        botDisplayName: 'Archon',
+      });
+
+      expect(content).not.toContain('CLAUDE_BIN_PATH=');
+    });
+
     it('should include platform configurations', () => {
       const content = generateEnvContent({
         database: { type: 'sqlite' },
@@ -418,3 +461,278 @@ CODEX_ACCOUNT_ID=account1
     });
   });
 });
+
+describe('detectClaudeExecutablePath probe order', () => {
+  // Use spies on the exported probe wrappers so each tier can be controlled
+  // independently without touching the real filesystem or shell.
+  let fileExistsSpy: ReturnType<typeof spyOn>;
+  let npmRootSpy: ReturnType<typeof spyOn>;
+  let whichSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(() => {
+    fileExistsSpy = spyOn(setupModule, 'probeFileExists').mockReturnValue(false);
+    npmRootSpy = spyOn(setupModule, 'probeNpmRoot').mockReturnValue(null);
+    whichSpy = spyOn(setupModule, 'probeWhichClaude').mockReturnValue(null);
+  });
+
+  afterEach(() => {
+    fileExistsSpy.mockRestore();
+    npmRootSpy.mockRestore();
+    whichSpy.mockRestore();
+  });
+
+  it('returns the native installer path when present (tier 1 wins)', () => {
+    // Native path exists; subsequent probes must not be called.
+    fileExistsSpy.mockImplementation(
+      (p: string) => p.includes('.local/bin/claude') || p.includes('.local\\bin\\claude')
+    );
+    const result = detectClaudeExecutablePath();
+    expect(result).toBeTruthy();
+    expect(result).toMatch(/\.local[\\/]bin[\\/]claude/);
+    // Tier 2 / 3 must not have been consulted.
+    expect(npmRootSpy).not.toHaveBeenCalled();
+    expect(whichSpy).not.toHaveBeenCalled();
+  });
+
+  it('falls through to npm cli.js when native is missing (tier 2 wins)', () => {
+    // Use path.join so the expected result matches whatever separator the
+    // production code produces on the current platform (backslash on Windows,
+    // forward slash elsewhere).
+    const npmRoot = join('fake', 'npm', 'root');
+    const expectedCliJs = join(npmRoot, '@anthropic-ai', 'claude-code', 'cli.js');
+    npmRootSpy.mockReturnValue(npmRoot);
+    fileExistsSpy.mockImplementation((p: string) => p === expectedCliJs);
+    const result = detectClaudeExecutablePath();
+    expect(result).toBe(expectedCliJs);
+    // Tier 3 must not have been consulted.
+    expect(whichSpy).not.toHaveBeenCalled();
+  });
+
+  it('falls through to which/where when native and npm probes both miss (tier 3 wins)', () => {
+    npmRootSpy.mockReturnValue('/fake/npm/root');
+    // Native miss, npm cli.js miss, but `which claude` returns a path that exists.
+    whichSpy.mockReturnValue('/opt/homebrew/bin/claude');
+    fileExistsSpy.mockImplementation((p: string) => p === '/opt/homebrew/bin/claude');
+    const result = detectClaudeExecutablePath();
+    expect(result).toBe('/opt/homebrew/bin/claude');
+  });
+
+  it('returns null when every probe misses', () => {
+    // All defaults already return false/null; nothing to override.
+    expect(detectClaudeExecutablePath()).toBeNull();
+  });
+
+  it('does not return a which-resolved path that fails the existsSync check', () => {
+    // `which` returns a path string but the file is not actually present
+    // (stale PATH entry, dangling symlink, etc.) — must not be returned.
+    npmRootSpy.mockReturnValue('/fake/npm/root');
+    whichSpy.mockReturnValue('/stale/path/claude');
+    fileExistsSpy.mockReturnValue(false);
+    expect(detectClaudeExecutablePath()).toBeNull();
+  });
+
+  it('skips npm tier when probeNpmRoot returns null (e.g. npm not installed)', () => {
+    // npm probe fails; tier 3 must still run.
+    whichSpy.mockReturnValue('/usr/local/bin/claude');
+    fileExistsSpy.mockImplementation((p: string) => p === '/usr/local/bin/claude');
+    const result = detectClaudeExecutablePath();
+    expect(result).toBe('/usr/local/bin/claude');
+    expect(npmRootSpy).toHaveBeenCalled();
+  });
+});
+
+/**
+ * Tests for the three-path env write model (#1303).
+ *
+ * Invariants:
+ *   - <repo>/.env is NEVER written.
+ *   - Default write targets ~/.archon/.env (home scope) with merge preserving
+ *     existing non-empty values.
+ *   - --scope project writes to <repo>/.archon/.env.
+ *   - --force overwrites the target wholesale, still writes a backup.
+ *   - Merge preserves user-added keys not in the proposed content.
+ */
+describe('writeScopedEnv (#1303)', () => {
+  const ROOT = join(tmpdir(), 'archon-write-scoped-env-test-' + Date.now());
+  const HOME_DIR = join(ROOT, 'archon-home');
+  const REPO_DIR = join(ROOT, 'repo');
+  let originalArchonHome: string | undefined;
+
+  beforeEach(() => {
+    mkdirSync(HOME_DIR, { recursive: true });
+    mkdirSync(REPO_DIR, { recursive: true });
+    originalArchonHome = process.env.ARCHON_HOME;
+    process.env.ARCHON_HOME = HOME_DIR;
+  });
+
+  afterEach(() => {
+    if (originalArchonHome === undefined) delete process.env.ARCHON_HOME;
+    else process.env.ARCHON_HOME = originalArchonHome;
+    rmSync(ROOT, { recursive: true, force: true });
+  });
+
+  it('fresh home scope writes content with no backup', () => {
+    const result = writeScopedEnv('DATABASE_URL=sqlite:local\nPORT=3090\n', {
+      scope: 'home',
+      repoPath: REPO_DIR,
+      force: false,
+    });
+    expect(result.targetPath).toBe(join(HOME_DIR, '.env'));
+    expect(result.backupPath).toBeNull();
+    expect(result.preservedKeys).toEqual([]);
+    expect(readFileSync(result.targetPath, 'utf-8')).toContain('DATABASE_URL=sqlite:local');
+  });
+
+  it('merge preserves user-added custom keys across re-runs', () => {
+    // First write
+    writeScopedEnv('DATABASE_URL=sqlite:local\n', {
+      scope: 'home',
+      repoPath: REPO_DIR,
+      force: false,
+    });
+    // User adds a custom var
+    const envPath = join(HOME_DIR, '.env');
+    writeFileSync(envPath, readFileSync(envPath, 'utf-8') + 'MY_CUSTOM_SECRET=preserve-me\n');
+    // Second setup run (proposes a different-shape config)
+    const result = writeScopedEnv('DATABASE_URL=sqlite:local\nPORT=3090\n', {
+      scope: 'home',
+      repoPath: REPO_DIR,
+      force: false,
+    });
+    const merged = parseDotenv(readFileSync(result.targetPath, 'utf-8'));
+    expect(merged.MY_CUSTOM_SECRET).toBe('preserve-me');
+    expect(merged.PORT).toBe('3090');
+    expect(result.backupPath).not.toBeNull();
+  });
+
+  it('merge preserves existing PostgreSQL DATABASE_URL when proposed is SQLite', () => {
+    const envPath = join(HOME_DIR, '.env');
+    writeFileSync(envPath, 'DATABASE_URL=postgresql://localhost:5432/mydb\n');
+    const result = writeScopedEnv(
+      '# Using SQLite (default) - no DATABASE_URL needed\nDATABASE_URL=\n',
+      { scope: 'home', repoPath: REPO_DIR, force: false }
+    );
+    const merged = parseDotenv(readFileSync(result.targetPath, 'utf-8'));
+    expect(merged.DATABASE_URL).toBe('postgresql://localhost:5432/mydb');
+    expect(result.preservedKeys).toContain('DATABASE_URL');
+  });
+
+  it('merge preserves existing bot tokens', () => {
+    const envPath = join(HOME_DIR, '.env');
+    writeFileSync(
+      envPath,
+      'SLACK_BOT_TOKEN=xoxb-existing\nCLAUDE_CODE_OAUTH_TOKEN=sk-ant-existing\n'
+    );
+    // Proposed content has these keys with different/empty values
+    writeScopedEnv('SLACK_BOT_TOKEN=xoxb-new-placeholder\nCLAUDE_CODE_OAUTH_TOKEN=\n', {
+      scope: 'home',
+      repoPath: REPO_DIR,
+      force: false,
+    });
+    const merged = parseDotenv(readFileSync(join(HOME_DIR, '.env'), 'utf-8'));
+    expect(merged.SLACK_BOT_TOKEN).toBe('xoxb-existing');
+    expect(merged.CLAUDE_CODE_OAUTH_TOKEN).toBe('sk-ant-existing');
+  });
+
+  it('--force overwrites wholesale but writes a timestamped backup', () => {
+    const envPath = join(HOME_DIR, '.env');
+    writeFileSync(envPath, 'OLD_KEY=old\nDATABASE_URL=postgresql://legacy\n');
+    const result = writeScopedEnv('DATABASE_URL=sqlite:local\nNEW_KEY=new\n', {
+      scope: 'home',
+      repoPath: REPO_DIR,
+      force: true,
+    });
+    expect(result.forced).toBe(true);
+    expect(result.backupPath).not.toBeNull();
+    expect(result.backupPath).toMatch(/\.archon-backup-\d{4}-\d{2}-\d{2}T/);
+    // Backup has the old content
+    expect(readFileSync(result.backupPath as string, 'utf-8')).toContain('OLD_KEY=old');
+    // Target has the new content only — OLD_KEY is gone
+    const newContent = readFileSync(result.targetPath, 'utf-8');
+    expect(newContent).toContain('DATABASE_URL=sqlite:local');
+    expect(newContent).toContain('NEW_KEY=new');
+    expect(newContent).not.toContain('OLD_KEY');
+  });
+
+  it('--force on a non-existent target writes cleanly with no backup', () => {
+    const result = writeScopedEnv('PORT=3090\n', {
+      scope: 'home',
+      repoPath: REPO_DIR,
+      force: true,
+    });
+    expect(result.backupPath).toBeNull();
+    expect(result.forced).toBe(false); // no existing file means force was effectively a no-op
+  });
+
+  it('--scope project writes to <repo>/.archon/.env, creating the directory', () => {
+    expect(existsSync(join(REPO_DIR, '.archon'))).toBe(false);
+    const result = writeScopedEnv('FOO=bar\n', {
+      scope: 'project',
+      repoPath: REPO_DIR,
+      force: false,
+    });
+    expect(result.targetPath).toBe(join(REPO_DIR, '.archon', '.env'));
+    expect(existsSync(result.targetPath)).toBe(true);
+    expect(existsSync(join(HOME_DIR, '.env'))).toBe(false);
+  });
+
+  it('<repo>/.env is never touched by writeScopedEnv in any scope/mode', () => {
+    const repoEnvPath = join(REPO_DIR, '.env');
+    const sentinel = 'USER_SECRET=do-not-touch\n';
+    writeFileSync(repoEnvPath, sentinel);
+    // Home scope, merge
+    writeScopedEnv('FOO=bar\n', { scope: 'home', repoPath: REPO_DIR, force: false });
+    // Home scope, force
+    writeScopedEnv('FOO=baz\n', { scope: 'home', repoPath: REPO_DIR, force: true });
+    // Project scope, merge
+    writeScopedEnv('FOO=qux\n', { scope: 'project', repoPath: REPO_DIR, force: false });
+    // Project scope, force
+    writeScopedEnv('FOO=xyz\n', { scope: 'project', repoPath: REPO_DIR, force: true });
+    expect(readFileSync(repoEnvPath, 'utf-8')).toBe(sentinel);
+  });
+
+  it('resolveScopedEnvPath returns the archon-owned path for each scope', () => {
+    expect(resolveScopedEnvPath('home', REPO_DIR)).toBe(join(HOME_DIR, '.env'));
+    expect(resolveScopedEnvPath('project', REPO_DIR)).toBe(join(REPO_DIR, '.archon', '.env'));
+  });
+
+  it('serializeEnv round-trips through dotenv.parse', () => {
+    const entries = {
+      SIMPLE: 'value',
+      WITH_SPACE: 'hello world',
+      WITH_HASH: 'value#not-a-comment',
+      EMPTY: '',
+    };
+    const serialized = serializeEnv(entries);
+    const parsed = parseDotenv(serialized);
+    expect(parsed.SIMPLE).toBe('value');
+    expect(parsed.WITH_SPACE).toBe('hello world');
+    expect(parsed.WITH_HASH).toBe('value#not-a-comment');
+    expect(parsed.EMPTY).toBe('');
+  });
+
+  it('serializeEnv escapes \\r so bare CRs survive round-trip', () => {
+    const entries = { WITH_CR: 'line1\rline2', WITH_CRLF: 'a\r\nb' };
+    const serialized = serializeEnv(entries);
+    const parsed = parseDotenv(serialized);
+    expect(parsed.WITH_CR).toBe('line1\rline2');
+    expect(parsed.WITH_CRLF).toBe('a\r\nb');
+  });
+
+  it('merge treats whitespace-only existing values as empty (replaces them)', () => {
+    const envPath = join(HOME_DIR, '.env');
+    writeFileSync(envPath, 'API_KEY=   \nNORMAL=keep-me\n');
+    const result = writeScopedEnv('API_KEY=real-token\nNORMAL=from-wizard\n', {
+      scope: 'home',
+      repoPath: REPO_DIR,
+      force: false,
+    });
+    const merged = parseDotenv(readFileSync(result.targetPath, 'utf-8'));
+    // Whitespace-only API_KEY was replaced by the proposed value.
+    expect(merged.API_KEY).toBe('real-token');
+    // Non-empty NORMAL was preserved and reported.
+    expect(merged.NORMAL).toBe('keep-me');
+    expect(result.preservedKeys).toContain('NORMAL');
+    expect(result.preservedKeys).not.toContain('API_KEY');
+  });
+});

packages/cli/src/commands/setup.ts

@@ -6,7 +6,17 @@
  * - AI assistants (Claude and/or Codex)
  * - Platform connections (GitHub, Telegram, Slack, Discord)
  *
- * Writes configuration to both ~/.archon/.env and <repo>/.env
+ * Writes configuration to one archon-owned env file, chosen by --scope:
+ *   - 'home'    (default)  → ~/.archon/.env
+ *   - 'project'            → <repo>/.archon/.env
+ *
+ * Never writes to <repo>/.env — that file is stripped at boot by stripCwdEnv()
+ * (see #1302 / #1303 three-path model). Writing there would be incoherent
+ * (values would be silently deleted on the next run).
+ *
+ * Writes are merge-only by default: existing non-empty values are preserved,
+ * user-added custom keys survive, and a timestamped backup is written before
+ * every rewrite. `--force` skips the merge (proposed wins) but still backs up.
  */
 import {
   intro,
@@ -22,12 +32,18 @@ import {
   cancel,
   log,
 } from '@clack/prompts';
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, chmodSync } from 'fs';
+import { parse as parseDotenv } from 'dotenv';
 import { join, dirname } from 'path';
 import { BUNDLED_SKILL_FILES } from '../bundled-skill';
 import { homedir } from 'os';
 import { randomBytes } from 'crypto';
 import { spawn, execSync, type ChildProcess } from 'child_process';
+import { getRegisteredProviders } from '@archon/providers';
+import {
+  getArchonEnvPath as pathsGetArchonEnvPath,
+  getRepoArchonEnvPath as pathsGetRepoArchonEnvPath,
+} from '@archon/paths';
 
 // =============================================================================
 // Types
@@ -43,9 +59,12 @@ interface SetupConfig {
     claudeAuthType?: 'global' | 'apiKey' | 'oauthToken';
     claudeApiKey?: string;
     claudeOauthToken?: string;
+    /** Absolute path to Claude Code SDK's cli.js. Written as CLAUDE_BIN_PATH
+     *  in ~/.archon/.env. Required in compiled Archon binaries; harmless in dev. */
+    claudeBinaryPath?: string;
     codex: boolean;
     codexTokens?: CodexTokens;
-    defaultAssistant: 'claude' | 'codex';
+    defaultAssistant: string;
   };
   platforms: {
     github: boolean;
@@ -105,6 +124,10 @@ interface ExistingConfig {
 interface SetupOptions {
   spawn?: boolean;
   repoPath: string;
+  /** Which archon-owned file to target. Default: 'home'. */
+  scope?: 'home' | 'project';
+  /** Skip merge and overwrite the target wholesale (backup still written). Default: false. */
+  force?: boolean;
 }
 
 interface SpawnResult {
@@ -159,6 +182,85 @@ function isCommandAvailable(command: string): boolean {
   }
 }
 
+/**
+ * Probe wrappers — exported so tests can spy on each tier independently.
+ * Direct imports of `existsSync` and `execSync` cannot be intercepted by
+ * `spyOn` (esm rebinding limitation), so we route the probes through these
+ * thin wrappers and let the test mock them in isolation.
+ */
+export function probeFileExists(path: string): boolean {
+  return existsSync(path);
+}
+
+export function probeNpmRoot(): string | null {
+  try {
+    const out = execSync('npm root -g', {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
+export function probeWhichClaude(): string | null {
+  try {
+    const checkCmd = process.platform === 'win32' ? 'where' : 'which';
+    const resolved = execSync(`${checkCmd} claude`, {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    // On Windows, `where` can return multiple lines — take the first.
+    const first = resolved.split(/\r?\n/)[0]?.trim();
+    return first ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Try to locate the Claude Code executable on disk.
+ *
+ * Compiled Archon binaries need an explicit path because the Claude Agent
+ * SDK's `import.meta.url` resolution is frozen to the build host's filesystem.
+ * The SDK's `pathToClaudeCodeExecutable` accepts either:
+ *   - A native compiled binary (from the curl/PowerShell/winget installers — current default)
+ *   - A JS `cli.js` (from `npm install -g @anthropic-ai/claude-code` — older path)
+ *
+ * We probe the well-known install locations in order:
+ *   1. Native installer (`~/.local/bin/claude` on macOS/Linux, `%USERPROFILE%\.local\bin\claude.exe` on Windows)
+ *   2. npm global `cli.js`
+ *   3. `which claude` / `where claude` — fallback if the user installed via Homebrew, winget, or a custom layout
+ *
+ * Returns null on total failure so the caller can prompt the user.
+ * Detection is best-effort; the caller should let users override.
+ *
+ * Exported so the probe order can be tested directly by spying on the
+ * tier wrappers above (`probeFileExists`, `probeNpmRoot`, `probeWhichClaude`).
+ */
+export function detectClaudeExecutablePath(): string | null {
+  // 1. Native installer default location (primary Anthropic-recommended path)
+  const nativePath =
+    process.platform === 'win32'
+      ? join(homedir(), '.local', 'bin', 'claude.exe')
+      : join(homedir(), '.local', 'bin', 'claude');
+  if (probeFileExists(nativePath)) return nativePath;
+
+  // 2. npm global cli.js
+  const npmRoot = probeNpmRoot();
+  if (npmRoot) {
+    const npmCliJs = join(npmRoot, '@anthropic-ai', 'claude-code', 'cli.js');
+    if (probeFileExists(npmCliJs)) return npmCliJs;
+  }
+
+  // 3. Fallback: resolve via `which` / `where` (Homebrew, winget, custom layouts)
+  const fromPath = probeWhichClaude();
+  if (fromPath && probeFileExists(fromPath)) return fromPath;
+
+  return null;
+}
+
 /**
  * Get Node.js version if installed, or null if not
  */
@@ -209,7 +311,7 @@ After installation, run: claude /login`,
 Install using one of these methods:
 
   Recommended for macOS (no Node.js required):
-    brew install --cask codex
+    brew install codex
 
   Or via npm (requires Node.js 18+):
     npm install -g @openai/codex
@@ -226,16 +328,19 @@ After installation, run 'codex' to authenticate.`,
 };
 
 /**
- * Check for existing configuration at ~/.archon/.env
+ * Check for existing configuration at the selected scope's archon-owned env
+ * file. Defaults to home scope for backward compatibility — callers writing to
+ * project scope must pass a path so the Add/Update/Fresh decision reflects the
+ * actual target.
  */
-export function checkExistingConfig(): ExistingConfig | null {
-  const envPath = join(getArchonHome(), '.env');
+export function checkExistingConfig(envPath?: string): ExistingConfig | null {
+  const path = envPath ?? join(getArchonHome(), '.env');
 
-  if (!existsSync(envPath)) {
+  if (!existsSync(path)) {
     return null;
   }
 
-  const content = readFileSync(envPath, 'utf-8');
+  const content = readFileSync(path, 'utf-8');
 
   return {
     hasDatabase: hasEnvValue(content, 'DATABASE_URL'),
@@ -352,6 +457,62 @@ function tryReadCodexAuth(): CodexTokens | null {
 /**
  * Collect Claude authentication method
  */
+/**
+ * Resolve the Claude Code executable path for CLAUDE_BIN_PATH.
+ * Auto-detects common install locations and falls back to prompting the user.
+ * Returns undefined if the user declines to configure (setup continues; the
+ * compiled binary will error with clear instructions on first Claude query).
+ */
+async function collectClaudeBinaryPath(): Promise<string | undefined> {
+  const detected = detectClaudeExecutablePath();
+
+  if (detected) {
+    const useDetected = await confirm({
+      message: `Found Claude Code at ${detected}. Write this to CLAUDE_BIN_PATH?`,
+      initialValue: true,
+    });
+    if (isCancel(useDetected)) {
+      cancel('Setup cancelled.');
+      process.exit(0);
+    }
+    if (useDetected) return detected;
+  }
+
+  const nativeExample =
+    process.platform === 'win32' ? '%USERPROFILE%\\.local\\bin\\claude.exe' : '~/.local/bin/claude';
+
+  note(
+    'Compiled Archon binaries need CLAUDE_BIN_PATH set to the Claude Code executable.\n' +
+      'In dev (`bun run`) this is ignored — the SDK resolves it via node_modules.\n\n' +
+      'Recommended (Anthropic default — native installer):\n' +
+      `  macOS/Linux: ${nativeExample}\n` +
+      '  Windows:     %USERPROFILE%\\.local\\bin\\claude.exe\n\n' +
+      'Alternative (npm global install):\n' +
+      '  $(npm root -g)/@anthropic-ai/claude-code/cli.js',
+    'Claude binary path'
+  );
+
+  const customPath = await text({
+    message: 'Absolute path to the Claude Code executable (leave blank to skip):',
+    placeholder: nativeExample,
+  });
+
+  if (isCancel(customPath)) {
+    cancel('Setup cancelled.');
+    process.exit(0);
+  }
+
+  const trimmed = (customPath ?? '').trim();
+  if (!trimmed) return undefined;
+
+  if (!existsSync(trimmed)) {
+    log.warning(
+      `Path does not exist: ${trimmed}. Saving anyway — the compiled binary will error on first use until this is correct.`
+    );
+  }
+  return trimmed;
+}
+
 async function collectClaudeAuth(): Promise<{
   authType: 'global' | 'apiKey' | 'oauthToken';
   apiKey?: string;
@@ -534,7 +695,8 @@ async function collectCodexAuth(): Promise<CodexTokens | null> {
  */
 async function collectAIConfig(): Promise<SetupConfig['ai']> {
   const assistants = await multiselect({
-    message: 'Which AI assistant(s) will you use? (↑↓ navigate, space select, enter confirm)',
+    message:
+      'Which built-in AI assistant(s) will you use? (↑↓ navigate, space select, enter confirm)',
     options: [
       { value: 'claude', label: 'Claude (Recommended)', hint: 'Anthropic Claude Code SDK' },
       { value: 'codex', label: 'Codex', hint: 'OpenAI Codex SDK' },
@@ -653,13 +815,14 @@ After upgrading, run 'archon setup' again.`,
     return {
       claude: false,
       codex: false,
-      defaultAssistant: 'claude',
+      defaultAssistant: getRegisteredProviders().find(p => p.builtIn)?.id ?? 'claude',
     };
   }
 
   let claudeAuthType: 'global' | 'apiKey' | 'oauthToken' | undefined;
   let claudeApiKey: string | undefined;
   let claudeOauthToken: string | undefined;
+  let claudeBinaryPath: string | undefined;
   let codexTokens: CodexTokens | undefined;
 
   // Collect Claude auth if selected
@@ -668,6 +831,7 @@ After upgrading, run 'archon setup' again.`,
     claudeAuthType = claudeAuth.authType;
     claudeApiKey = claudeAuth.apiKey;
     claudeOauthToken = claudeAuth.oauthToken;
+    claudeBinaryPath = await collectClaudeBinaryPath();
   }
 
   // Collect Codex auth if selected
@@ -676,16 +840,21 @@ After upgrading, run 'archon setup' again.`,
     codexTokens = tokens ?? undefined;
   }
 
-  // Determine default assistant
-  let defaultAssistant: 'claude' | 'codex' = 'claude';
+  // Determine default assistant — use the registry, but keep setup/auth flows built-in only.
+  // Default to first registered built-in provider rather than hardcoding 'claude'.
+  let defaultAssistant = getRegisteredProviders().find(p => p.builtIn)?.id ?? 'claude';
 
   if (hasClaude && hasCodex) {
+    const providerChoices = getRegisteredProviders()
+      .filter(p => p.builtIn)
+      .map(p => ({
+        value: p.id,
+        label: p.id === 'claude' ? `${p.displayName} (Recommended)` : p.displayName,
+      }));
+
     const defaultChoice = await select({
       message: 'Which should be the default AI assistant?',
-      options: [
-        { value: 'claude', label: 'Claude (Recommended)' },
-        { value: 'codex', label: 'Codex' },
-      ],
+      options: providerChoices,
     });
 
     if (isCancel(defaultChoice)) {
@@ -703,6 +872,7 @@ After upgrading, run 'archon setup' again.`,
     claudeAuthType,
     claudeApiKey,
     claudeOauthToken,
+    ...(claudeBinaryPath !== undefined ? { claudeBinaryPath } : {}),
     codex: hasCodex,
     codexTokens,
     defaultAssistant,
@@ -1063,6 +1233,9 @@ export function generateEnvContent(config: SetupConfig): string {
       lines.push('CLAUDE_USE_GLOBAL_AUTH=false');
       lines.push(`CLAUDE_CODE_OAUTH_TOKEN=${config.ai.claudeOauthToken}`);
     }
+    if (config.ai.claudeBinaryPath) {
+      lines.push(`CLAUDE_BIN_PATH=${config.ai.claudeBinaryPath}`);
+    }
   } else {
     lines.push('# Claude not configured');
   }
@@ -1139,8 +1312,12 @@ export function generateEnvContent(config: SetupConfig): string {
   }
 
   // Server
+  // PORT is intentionally omitted: both the Hono server (packages/core/src/utils/port-allocation.ts)
+  // and the Vite dev proxy (packages/web/vite.config.ts) default to 3090 when unset, which keeps
+  // them in sync. Writing a fixed PORT here risked a mismatch if ~/.archon/.env leaks a PORT that
+  // the Vite proxy (which only reads repo-local .env) never sees — see #1152.
   lines.push('# Server');
-  lines.push('PORT=3000');
+  lines.push('# PORT=3090  # Default: 3090. Uncomment to override.');
   lines.push('');
 
   // Concurrency
@@ -1151,28 +1328,120 @@ export function generateEnvContent(config: SetupConfig): string {
 }
 
 /**
- * Write .env files to both global and repo locations
+ * Resolve the target path for the selected scope. Delegates to `@archon/paths`
+ * so Docker (`/.archon`), the `ARCHON_HOME` override, and the "undefined"
+ * literal guard behave identically to the loader. Never resolves to
+ * `<repoPath>/.env` — that path belongs to the user.
  */
-function writeEnvFiles(
-  content: string,
-  repoPath: string
-): { globalPath: string; repoEnvPath: string } {
-  const archonHome = getArchonHome();
-  const globalPath = join(archonHome, '.env');
-  const repoEnvPath = join(repoPath, '.env');
+export function resolveScopedEnvPath(scope: 'home' | 'project', repoPath: string): string {
+  if (scope === 'project') return pathsGetRepoArchonEnvPath(repoPath);
+  return pathsGetArchonEnvPath();
+}
 
-  // Create ~/.archon/ if needed
-  if (!existsSync(archonHome)) {
-    mkdirSync(archonHome, { recursive: true });
+/**
+ * Serialize a key/value map back to `KEY=value` lines. Values with whitespace,
+ * `#`, `"`, `'`, `\n`, or `\r` are double-quoted with `\\`, `"`, `\n`, `\r`
+ * escaped so round-tripping through dotenv.parse is stable.
+ */
+export function serializeEnv(entries: Record<string, string>): string {
+  const lines: string[] = [];
+  for (const [key, rawValue] of Object.entries(entries)) {
+    const value = rawValue;
+    const needsQuoting = /[\s#"'\n\r]/.test(value) || value === '';
+    if (needsQuoting) {
+      const escaped = value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r');
+      lines.push(`${key}="${escaped}"`);
+    } else {
+      lines.push(`${key}=${value}`);
+    }
+  }
+  return lines.join('\n') + (lines.length > 0 ? '\n' : '');
+}
+
+/**
+ * Produce a filesystem-safe ISO timestamp (no `:` or `.` characters).
+ */
+function backupTimestamp(): string {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+interface WriteScopedEnvResult {
+  targetPath: string;
+  backupPath: string | null;
+  /** Keys present in the existing file that were preserved against the proposed set. */
+  preservedKeys: string[];
+  /** True when `--force` overrode the merge. */
+  forced: boolean;
+}
+
+/**
+ * Write env content to exactly one archon-owned file, selected by scope.
+ * Merge-only by default (existing non-empty values win, user-added keys
+ * survive). Backs up the existing file (if any) before every rewrite, even
+ * when `--force` is set.
+ */
+export function writeScopedEnv(
+  content: string,
+  options: { scope: 'home' | 'project'; repoPath: string; force: boolean }
+): WriteScopedEnvResult {
+  const targetPath = resolveScopedEnvPath(options.scope, options.repoPath);
+  const parentDir = dirname(targetPath);
+  if (!existsSync(parentDir)) {
+    mkdirSync(parentDir, { recursive: true });
   }
 
-  // Write to global location
-  writeFileSync(globalPath, content);
+  const exists = existsSync(targetPath);
+  let backupPath: string | null = null;
+  if (exists) {
+    backupPath = `${targetPath}.archon-backup-${backupTimestamp()}`;
+    copyFileSync(targetPath, backupPath);
+    // Backups carry tokens/secrets — match the 0o600 we set on the live file.
+    chmodSync(backupPath, 0o600);
+  }
 
-  // Write to repo location
-  writeFileSync(repoEnvPath, content);
+  const preservedKeys: string[] = [];
+  let finalContent: string;
 
-  return { globalPath, repoEnvPath };
+  if (options.force || !exists) {
+    finalContent = content;
+    if (options.force && backupPath) {
+      process.stderr.write(
+        `[archon] --force: overwriting ${targetPath} (backup at ${backupPath})\n`
+      );
+    }
+  } else {
+    // Merge: existing non-empty values win; proposed-only keys are added;
+    // existing-only keys (user customizations) are preserved verbatim.
+    const existingRaw = readFileSync(targetPath, 'utf-8');
+    const existing = parseDotenv(existingRaw);
+    const proposed = parseDotenv(content);
+    const merged: Record<string, string> = { ...existing };
+    for (const [key, value] of Object.entries(proposed)) {
+      const prior = existing[key];
+      // Treat whitespace-only existing values as empty — otherwise a
+      // copy-paste stray `   ` would silently defeat the wizard's update for
+      // that key forever.
+      const priorIsEmpty = prior === undefined || prior.trim() === '';
+      if (!(key in existing) || priorIsEmpty) {
+        merged[key] = value;
+      } else {
+        preservedKeys.push(key);
+      }
+    }
+    finalContent = serializeEnv(merged);
+  }
+
+  // 0o600 — env files hold secrets. Prevents group/world-readable writes on a
+  // permissive umask. writeFileSync's default mode is 0o666 & ~umask.
+  writeFileSync(targetPath, finalContent, { mode: 0o600 });
+  // writeFileSync preserves mode for existing files; chmod guarantees 0o600
+  // even when overwriting a file that pre-existed with looser permissions.
+  chmodSync(targetPath, 0o600);
+  return { targetPath, backupPath, preservedKeys, forced: options.force && exists };
 }
 
 /**
@@ -1203,7 +1472,7 @@ export function copyArchonSkill(targetPath: string): void {
 function trySpawn(
   command: string,
   args: string[],
-  options: { detached: boolean; stdio: 'ignore'; shell?: boolean }
+  options: { detached: boolean; stdio: 'ignore' }
 ): boolean {
   try {
     const child: ChildProcess = spawn(command, args, options);
@@ -1238,7 +1507,6 @@ function spawnWindowsTerminal(repoPath: string): SpawnResult {
     trySpawn('cmd.exe', ['/c', 'start', '""', '/D', repoPath, 'cmd', '/k', 'archon setup'], {
       detached: true,
       stdio: 'ignore',
-      shell: true,
     })
   ) {
     return { success: true };
@@ -1366,8 +1634,28 @@ export async function setupCommand(options: SetupOptions): Promise<void> {
   // Interactive setup flow
   intro('Archon Setup Wizard');
 
-  // Check for existing configuration
-  const existing = checkExistingConfig();
+  // Resolve scope + target path up-front so everything downstream (existing-
+  // config check, merge, write) agrees on which file we're touching.
+  const scope: 'home' | 'project' = options.scope ?? 'home';
+  const force = options.force ?? false;
+  const targetEnvPath = resolveScopedEnvPath(scope, options.repoPath);
+
+  // If a pre-existing <repo>/.env is present, tell the operator once that
+  // archon does NOT manage it — avoids confusion for users upgrading from
+  // versions that used to write there.
+  const legacyRepoEnv = join(options.repoPath, '.env');
+  if (existsSync(legacyRepoEnv)) {
+    log.info(
+      `Note: ${legacyRepoEnv} exists but is not managed by archon.\n` +
+        '      Values there are stripped from the archon process at runtime (safety guard).\n' +
+        '      Put archon env vars in ~/.archon/.env (home scope) or ' +
+        `${join(options.repoPath, '.archon', '.env')} (project scope).`
+    );
+  }
+
+  // Check for existing configuration at the selected scope (not unconditionally
+  // ~/.archon/.env) so the Add/Update/Fresh decision reflects the actual target.
+  const existing = checkExistingConfig(targetEnvPath);
 
   type SetupMode = 'fresh' | 'add' | 'update';
   let mode: SetupMode = 'fresh';
@@ -1420,7 +1708,7 @@ export async function setupCommand(options: SetupOptions): Promise<void> {
       ai: {
         claude: existing?.hasClaude ?? false,
         codex: existing?.hasCodex ?? false,
-        defaultAssistant: 'claude',
+        defaultAssistant: getRegisteredProviders().find(p => p.builtIn)?.id ?? 'claude',
       },
       platforms: {
         github: existing?.platforms.github ?? false,
@@ -1489,13 +1777,41 @@ export async function setupCommand(options: SetupOptions): Promise<void> {
     config.botDisplayName = await collectBotDisplayName();
   }
 
-  // Generate and write configuration
-  s.start('Writing configuration files...');
+  // Generate and write configuration. Wrap in try/catch so any fs exception
+  // (permission denied, read-only FS, backup copy failure, etc.) stops the
+  // spinner cleanly and surfaces an actionable error instead of a raw stack
+  // trace after the user has filled out the entire wizard.
+  s.start('Writing configuration...');
 
   const envContent = generateEnvContent(config);
-  const { globalPath, repoEnvPath } = writeEnvFiles(envContent, options.repoPath);
+  let writeResult: ReturnType<typeof writeScopedEnv>;
+  try {
+    writeResult = writeScopedEnv(envContent, {
+      scope,
+      repoPath: options.repoPath,
+      force,
+    });
+  } catch (error) {
+    s.stop('Failed to write configuration');
+    const err = error as NodeJS.ErrnoException;
+    const code = err.code ? ` (${err.code})` : '';
+    cancel(`Could not write ${targetEnvPath}${code}: ${err.message}`);
+    process.exit(1);
+  }
 
-  s.stop('Configuration files written');
+  s.stop('Configuration written');
+
+  // Tell the operator exactly what happened — especially that <repo>/.env was
+  // NOT touched, because prior versions wrote there and this is the biggest
+  // behavior change for returning users.
+  if (writeResult.preservedKeys.length > 0) {
+    log.info(
+      `Preserved ${writeResult.preservedKeys.length} existing value(s) (use --force to overwrite): ${writeResult.preservedKeys.join(', ')}`
+    );
+  }
+  if (writeResult.backupPath) {
+    log.info(`Backup written to ${writeResult.backupPath}`);
+  }
 
   // Offer to install the Archon skill
   const shouldCopySkill = await confirm({
@@ -1596,9 +1912,8 @@ export async function setupCommand(options: SetupOptions): Promise<void> {
     `Default: ${config.ai.defaultAssistant}`,
     `Platforms: ${configuredPlatforms.length > 0 ? configuredPlatforms.join(', ') : 'None'}`,
     '',
-    'Files written:',
-    `  ${globalPath}`,
-    `  ${repoEnvPath}`,
+    `File written (${scope} scope):`,
+    `  ${writeResult.targetPath}`,
   ];
 
   if (config.platforms.github && config.github) {
@@ -1619,7 +1934,7 @@ export async function setupCommand(options: SetupOptions): Promise<void> {
   // Additional options note
   note(
     'Other settings you can customize in ~/.archon/.env:\n' +
-      '  - PORT (default: 3000)\n' +
+      '  - PORT (default: 3090)\n' +
       '  - MAX_CONCURRENT_CONVERSATIONS (default: 10)\n' +
       '  - *_STREAMING_MODE (stream | batch per platform)\n\n' +
       'These defaults work well for most users.',

packages/cli/src/commands/validate.ts

@@ -8,7 +8,9 @@ import { discoverWorkflowsWithConfig } from '@archon/workflows/workflow-discover
 import {
   validateWorkflowResources,
   validateCommand,
+  validateScript,
   discoverAvailableCommands,
+  discoverAvailableScripts,
   findSimilar,
   makeWorkflowResult,
 } from '@archon/workflows/validator';
@@ -16,6 +18,7 @@ import type {
   ValidationIssue,
   WorkflowValidationResult,
   ValidationConfig,
+  ScriptValidationResult,
 } from '@archon/workflows/validator';
 import { loadConfig, loadRepoConfig } from '@archon/core';
 
@@ -52,22 +55,22 @@ function formatIssue(issue: ValidationIssue, indent = '    '): string {
   return line;
 }
 
-function formatWorkflowResult(result: WorkflowValidationResult): string {
-  const errors = result.issues.filter(i => i.level === 'error');
-  const warnings = result.issues.filter(i => i.level === 'warning');
+function formatValidationResult(displayName: string, issues: ValidationIssue[]): string {
+  const hasErrors = issues.some(i => i.level === 'error');
+  const hasWarnings = issues.some(i => i.level === 'warning');
+  const statusLabel = hasErrors ? 'ERRORS' : hasWarnings ? 'WARNINGS' : 'ok';
 
-  const statusLabel = errors.length > 0 ? 'ERRORS' : warnings.length > 0 ? 'WARNINGS' : 'ok';
-
-  const namePad = result.workflowName.padEnd(40, ' ');
-  let output = `  ${namePad} ${statusLabel}`;
-
-  for (const issue of result.issues) {
+  let output = `  ${displayName.padEnd(40, ' ')} ${statusLabel}`;
+  for (const issue of issues) {
     output += '\n' + formatIssue(issue);
   }
-
   return output;
 }
 
+function formatWorkflowResult(result: WorkflowValidationResult): string {
+  return formatValidationResult(result.workflowName, result.issues);
+}
+
 // =============================================================================
 // Workflow validation command
 // =============================================================================
@@ -82,6 +85,8 @@ export async function validateWorkflowsCommand(
   json?: boolean
 ): Promise<number> {
   const config = await buildValidationConfig(cwd);
+  const mergedConfig = await loadConfig(cwd);
+  const defaultProvider = mergedConfig.assistant;
   const { workflows: workflowEntries, errors: loadErrors } = await discoverWorkflowsWithConfig(
     cwd,
     loadConfig
@@ -102,7 +107,7 @@ export async function validateWorkflowsCommand(
 
   // Validate successfully parsed workflows (Level 3)
   for (const { workflow } of workflowEntries) {
-    const issues = await validateWorkflowResources(workflow, cwd, config);
+    const issues = await validateWorkflowResources(workflow, cwd, config, defaultProvider);
     results.push(makeWorkflowResult(workflow.name, issues));
   }
 
@@ -175,11 +180,16 @@ export async function validateWorkflowsCommand(
 }
 
 // =============================================================================
-// Command validation command
+// Command and script validation command
 // =============================================================================
 
+function formatScriptResult(result: ScriptValidationResult): string {
+  return formatValidationResult(`[script] ${result.scriptName}`, result.issues);
+}
+
 /**
  * Validate all commands or a specific command.
+ * Also validates scripts from .archon/scripts/ alongside commands.
  * Returns exit code: 0 = all valid, 1 = errors found.
  */
 export async function validateCommandsCommand(
@@ -208,41 +218,50 @@ export async function validateCommandsCommand(
 
   // Validate all commands
   const allCommands = await discoverAvailableCommands(cwd, config);
+  const commandResults = await Promise.all(
+    allCommands.map(cmd => validateCommand(cmd, cwd, config))
+  );
 
-  if (allCommands.length === 0) {
-    if (jsonOutput) {
-      console.log(JSON.stringify({ results: [], summary: { total: 0, valid: 0, errors: 0 } }));
-    } else {
-      console.log('\nNo commands found.');
-    }
-    return 0;
-  }
+  // Validate all scripts
+  const allScripts = await discoverAvailableScripts(cwd);
+  const scriptResults = await Promise.all(allScripts.map(s => validateScript(s.name, cwd)));
 
-  const results = await Promise.all(allCommands.map(cmd => validateCommand(cmd, cwd, config)));
-
-  const totalErrors = results.filter(r => !r.valid).length;
+  const totalCommandErrors = commandResults.filter(r => !r.valid).length;
+  const totalScriptErrors = scriptResults.filter(r => !r.valid).length;
+  const totalErrors = totalCommandErrors + totalScriptErrors;
 
   if (jsonOutput) {
     console.log(
       JSON.stringify({
-        results,
+        results: commandResults,
+        scripts: scriptResults,
         summary: {
-          total: results.length,
-          valid: results.length - totalErrors,
+          total: commandResults.length + scriptResults.length,
+          valid: commandResults.length + scriptResults.length - totalErrors,
           errors: totalErrors,
         },
       })
     );
   } else {
-    console.log(`\nValidating commands in ${cwd}\n`);
-    for (const result of results) {
+    if (commandResults.length === 0 && scriptResults.length === 0) {
+      console.log('\nNo commands or scripts found.');
+      return 0;
+    }
+
+    console.log(`\nValidating commands and scripts in ${cwd}\n`);
+    for (const result of commandResults) {
       const statusLabel = result.valid ? 'ok' : 'ERRORS';
       console.log(`  ${result.commandName.padEnd(40, ' ')} ${statusLabel}`);
       for (const issue of result.issues) {
         console.log(formatIssue(issue));
       }
     }
-    console.log(`\nResults: ${results.length - totalErrors} valid, ${totalErrors} with errors`);
+    for (const result of scriptResults) {
+      console.log(formatScriptResult(result));
+    }
+    console.log(
+      `\nResults: ${commandResults.length + scriptResults.length - totalErrors} valid, ${totalErrors} with errors`
+    );
   }
 
   return totalErrors > 0 ? 1 : 0;

packages/cli/src/commands/version.ts

@@ -30,7 +30,8 @@ interface PackageJson {
  * Get version for development mode (reads package.json)
  */
 async function getDevVersion(): Promise<{ name: string; version: string }> {
-  const pkgPath = join(SCRIPT_DIR, '../../package.json');
+  // Read root package.json (monorepo version), not the CLI package's own
+  const pkgPath = join(SCRIPT_DIR, '../../../../package.json');
 
   let content: string;
   try {

packages/cli/src/commands/workflow.test.ts

@@ -107,6 +107,7 @@ mock.module('@archon/core/db/conversations', () => ({
   getOrCreateConversation: mock(() =>
     Promise.resolve({ id: 'conv-123', platform_type: 'cli', platform_conversation_id: 'cli-123' })
   ),
+  getConversationById: mock(() => Promise.resolve(null)),
   updateConversation: mock(() => Promise.resolve()),
 }));
 
@@ -309,7 +310,7 @@ describe('workflowListCommand', () => {
     expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Found 1 workflow(s)'));
   });
 
-  it('passes globalSearchPath to discoverWorkflowsWithConfig', async () => {
+  it('calls discoverWorkflowsWithConfig with (cwd, loadConfig) — home scope is internal', async () => {
     const { discoverWorkflowsWithConfig } = await import('@archon/workflows/workflow-discovery');
     (discoverWorkflowsWithConfig as ReturnType<typeof mock>).mockResolvedValueOnce({
       workflows: [],
@@ -318,11 +319,9 @@ describe('workflowListCommand', () => {
 
     await workflowListCommand('/test/path');
 
-    expect(discoverWorkflowsWithConfig).toHaveBeenCalledWith(
-      '/test/path',
-      expect.any(Function),
-      expect.objectContaining({ globalSearchPath: '/home/test/.archon' })
-    );
+    // After the globalSearchPath refactor, discovery reads ~/.archon/workflows/
+    // on every call with no option — every caller inherits home-scope for free.
+    expect(discoverWorkflowsWithConfig).toHaveBeenCalledWith('/test/path', expect.any(Function));
   });
 
   it('should throw error when discoverWorkflows fails', async () => {
@@ -866,6 +865,146 @@ describe('workflowRunCommand', () => {
     expect(createCallsAfter).toBe(createCallsBefore);
   });
 
+  // -------------------------------------------------------------------------
+  // Workflow-level `worktree.enabled` policy
+  // -------------------------------------------------------------------------
+
+  it('skips isolation when workflow YAML pins worktree.enabled: false', async () => {
+    const { discoverWorkflowsWithConfig } = await import('@archon/workflows/workflow-discovery');
+    const { executeWorkflow } = await import('@archon/workflows/executor');
+    const conversationDb = await import('@archon/core/db/conversations');
+    const codebaseDb = await import('@archon/core/db/codebases');
+    const isolation = await import('@archon/isolation');
+
+    const getIsolationProviderMock = isolation.getIsolationProvider as ReturnType<typeof mock>;
+    const providerBefore = getIsolationProviderMock.mock.results.at(-1)?.value as
+      | { create: ReturnType<typeof mock> }
+      | undefined;
+    const createCallsBefore = providerBefore?.create.mock.calls.length ?? 0;
+
+    (discoverWorkflowsWithConfig as ReturnType<typeof mock>).mockResolvedValueOnce({
+      workflows: [
+        makeTestWorkflowWithSource({
+          name: 'triage',
+          description: 'Read-only triage',
+          worktree: { enabled: false },
+        }),
+      ],
+      errors: [],
+    });
+    (conversationDb.getOrCreateConversation as ReturnType<typeof mock>).mockResolvedValueOnce({
+      id: 'conv-123',
+    });
+    (codebaseDb.findCodebaseByDefaultCwd as ReturnType<typeof mock>).mockResolvedValueOnce({
+      id: 'cb-123',
+      default_cwd: '/test/path',
+    });
+    (conversationDb.updateConversation as ReturnType<typeof mock>).mockResolvedValueOnce(undefined);
+    (executeWorkflow as ReturnType<typeof mock>).mockResolvedValueOnce({
+      success: true,
+      workflowRunId: 'run-123',
+    });
+
+    // No flags — policy alone should disable isolation
+    await workflowRunCommand('/test/path', 'triage', 'go', {});
+
+    const providerAfter = getIsolationProviderMock.mock.results.at(-1)?.value as
+      | { create: ReturnType<typeof mock> }
+      | undefined;
+    const createCallsAfter = providerAfter?.create.mock.calls.length ?? 0;
+    expect(createCallsAfter).toBe(createCallsBefore);
+  });
+
+  it('throws when workflow pins worktree.enabled: false but caller passes --branch', async () => {
+    const { discoverWorkflowsWithConfig } = await import('@archon/workflows/workflow-discovery');
+
+    (discoverWorkflowsWithConfig as ReturnType<typeof mock>).mockResolvedValueOnce({
+      workflows: [
+        makeTestWorkflowWithSource({
+          name: 'triage',
+          description: 'Read-only triage',
+          worktree: { enabled: false },
+        }),
+      ],
+      errors: [],
+    });
+
+    await expect(
+      workflowRunCommand('/test/path', 'triage', 'go', { branchName: 'feat-x' })
+    ).rejects.toThrow(/worktree\.enabled: false/);
+  });
+
+  it('throws when workflow pins worktree.enabled: false but caller passes --from', async () => {
+    const { discoverWorkflowsWithConfig } = await import('@archon/workflows/workflow-discovery');
+
+    (discoverWorkflowsWithConfig as ReturnType<typeof mock>).mockResolvedValueOnce({
+      workflows: [
+        makeTestWorkflowWithSource({
+          name: 'triage',
+          description: 'Read-only triage',
+          worktree: { enabled: false },
+        }),
+      ],
+      errors: [],
+    });
+
+    await expect(
+      workflowRunCommand('/test/path', 'triage', 'go', { fromBranch: 'dev' })
+    ).rejects.toThrow(/worktree\.enabled: false/);
+  });
+
+  it('accepts worktree.enabled: false + --no-worktree as redundant (no error)', async () => {
+    const { discoverWorkflowsWithConfig } = await import('@archon/workflows/workflow-discovery');
+    const { executeWorkflow } = await import('@archon/workflows/executor');
+    const conversationDb = await import('@archon/core/db/conversations');
+    const codebaseDb = await import('@archon/core/db/codebases');
+
+    (discoverWorkflowsWithConfig as ReturnType<typeof mock>).mockResolvedValueOnce({
+      workflows: [
+        makeTestWorkflowWithSource({
+          name: 'triage',
+          description: 'Read-only triage',
+          worktree: { enabled: false },
+        }),
+      ],
+      errors: [],
+    });
+    (conversationDb.getOrCreateConversation as ReturnType<typeof mock>).mockResolvedValueOnce({
+      id: 'conv-123',
+    });
+    (codebaseDb.findCodebaseByDefaultCwd as ReturnType<typeof mock>).mockResolvedValueOnce({
+      id: 'cb-123',
+      default_cwd: '/test/path',
+    });
+    (conversationDb.updateConversation as ReturnType<typeof mock>).mockResolvedValueOnce(undefined);
+    (executeWorkflow as ReturnType<typeof mock>).mockResolvedValueOnce({
+      success: true,
+      workflowRunId: 'run-123',
+    });
+
+    // Should not throw — redundant, not contradictory
+    await workflowRunCommand('/test/path', 'triage', 'go', { noWorktree: true });
+  });
+
+  it('throws when workflow pins worktree.enabled: true but caller passes --no-worktree', async () => {
+    const { discoverWorkflowsWithConfig } = await import('@archon/workflows/workflow-discovery');
+
+    (discoverWorkflowsWithConfig as ReturnType<typeof mock>).mockResolvedValueOnce({
+      workflows: [
+        makeTestWorkflowWithSource({
+          name: 'build',
+          description: 'Requires a worktree',
+          worktree: { enabled: true },
+        }),
+      ],
+      errors: [],
+    });
+
+    await expect(
+      workflowRunCommand('/test/path', 'build', 'go', { noWorktree: true })
+    ).rejects.toThrow(/worktree\.enabled: true/);
+  });
+
   it('throws when isolation cannot be created due to missing codebase', async () => {
     const { discoverWorkflowsWithConfig } = await import('@archon/workflows/workflow-discovery');
     const conversationDb = await import('@archon/core/db/conversations');
@@ -974,6 +1113,249 @@ describe('workflowRunCommand', () => {
       consoleWarnSpy.mockRestore();
     }
   });
+
+  it('sends dispatch message before executeWorkflow with correct metadata', async () => {
+    const { discoverWorkflowsWithConfig } = await import('@archon/workflows/workflow-discovery');
+    const { executeWorkflow } = await import('@archon/workflows/executor');
+    const conversationDb = await import('@archon/core/db/conversations');
+    const codebaseDb = await import('@archon/core/db/codebases');
+    const messagesDb = await import('@archon/core/db/messages');
+
+    (discoverWorkflowsWithConfig as ReturnType<typeof mock>).mockResolvedValueOnce({
+      workflows: [makeTestWorkflowWithSource({ name: 'assist', description: 'Help' })],
+      errors: [],
+    });
+    (conversationDb.getOrCreateConversation as ReturnType<typeof mock>).mockResolvedValueOnce({
+      id: 'conv-123',
+    });
+    (codebaseDb.findCodebaseByDefaultCwd as ReturnType<typeof mock>).mockResolvedValueOnce(null);
+    (conversationDb.updateConversation as ReturnType<typeof mock>).mockResolvedValueOnce(undefined);
+
+    // Track call order for assistant messages only (user message is added first via addMessage directly)
+    const callOrder: string[] = [];
+    (messagesDb.addMessage as ReturnType<typeof mock>).mockImplementation(
+      async (_dbId: unknown, role: unknown, content: unknown) => {
+        if (role === 'assistant') {
+          callOrder.push(`addMessage:${String(content)}`);
+        }
+      }
+    );
+    (executeWorkflow as ReturnType<typeof mock>).mockImplementation(async () => {
+      callOrder.push('executeWorkflow');
+      return { success: true, workflowRunId: 'run-1' };
+    });
+
+    await workflowRunCommand('/test/path', 'assist', 'hello', { noWorktree: true });
+
+    // Dispatch assistant message fires before executeWorkflow
+    expect(callOrder[0]).toContain('Dispatching workflow');
+    expect(callOrder[1]).toBe('executeWorkflow');
+
+    // Correct metadata shape
+    expect(messagesDb.addMessage).toHaveBeenCalledWith(
+      expect.any(String),
+      'assistant',
+      'Dispatching workflow: **assist**',
+      expect.objectContaining({
+        category: 'workflow_dispatch_status',
+        workflowDispatch: expect.objectContaining({
+          workflowName: 'assist',
+          workerConversationId: expect.stringMatching(/^cli-/),
+        }),
+      })
+    );
+  });
+
+  it('sends result card when executeWorkflow returns a summary', async () => {
+    const { discoverWorkflowsWithConfig } = await import('@archon/workflows/workflow-discovery');
+    const { executeWorkflow } = await import('@archon/workflows/executor');
+    const conversationDb = await import('@archon/core/db/conversations');
+    const codebaseDb = await import('@archon/core/db/codebases');
+    const messagesDb = await import('@archon/core/db/messages');
+
+    (discoverWorkflowsWithConfig as ReturnType<typeof mock>).mockResolvedValueOnce({
+      workflows: [makeTestWorkflowWithSource({ name: 'assist', description: 'Help' })],
+      errors: [],
+    });
+    (conversationDb.getOrCreateConversation as ReturnType<typeof mock>).mockResolvedValueOnce({
+      id: 'conv-123',
+    });
+    (codebaseDb.findCodebaseByDefaultCwd as ReturnType<typeof mock>).mockResolvedValueOnce(null);
+    (conversationDb.updateConversation as ReturnType<typeof mock>).mockResolvedValueOnce(undefined);
+    (executeWorkflow as ReturnType<typeof mock>).mockResolvedValueOnce({
+      success: true,
+      workflowRunId: 'run-42',
+      summary: 'All steps completed. Branch pushed.',
+    });
+    (messagesDb.addMessage as ReturnType<typeof mock>).mockClear();
+
+    await workflowRunCommand('/test/path', 'assist', 'hello', { noWorktree: true });
+
+    expect(messagesDb.addMessage).toHaveBeenCalledWith(
+      expect.any(String),
+      'assistant',
+      'All steps completed. Branch pushed.',
+      expect.objectContaining({
+        category: 'workflow_result',
+        workflowResult: { workflowName: 'assist', runId: 'run-42' },
+      })
+    );
+  });
+
+  it('does not send result card when executeWorkflow has no summary', async () => {
+    const { discoverWorkflowsWithConfig } = await import('@archon/workflows/workflow-discovery');
+    const { executeWorkflow } = await import('@archon/workflows/executor');
+    const conversationDb = await import('@archon/core/db/conversations');
+    const codebaseDb = await import('@archon/core/db/codebases');
+    const messagesDb = await import('@archon/core/db/messages');
+
+    (discoverWorkflowsWithConfig as ReturnType<typeof mock>).mockResolvedValueOnce({
+      workflows: [makeTestWorkflowWithSource({ name: 'assist', description: 'Help' })],
+      errors: [],
+    });
+    (conversationDb.getOrCreateConversation as ReturnType<typeof mock>).mockResolvedValueOnce({
+      id: 'conv-123',
+    });
+    (codebaseDb.findCodebaseByDefaultCwd as ReturnType<typeof mock>).mockResolvedValueOnce(null);
+    (conversationDb.updateConversation as ReturnType<typeof mock>).mockResolvedValueOnce(undefined);
+    (executeWorkflow as ReturnType<typeof mock>).mockResolvedValueOnce({
+      success: true,
+      workflowRunId: 'run-1',
+      // no summary field
+    });
+    (messagesDb.addMessage as ReturnType<typeof mock>).mockClear();
+
+    await workflowRunCommand('/test/path', 'assist', 'hello', { noWorktree: true });
+
+    // Only dispatch addMessage call, no result card
+    const resultCalls = (messagesDb.addMessage as ReturnType<typeof mock>).mock.calls.filter(
+      (args: unknown[]) => {
+        const meta = args[3] as Record<string, unknown> | undefined;
+        return meta?.category === 'workflow_result';
+      }
+    );
+    expect(resultCalls).toHaveLength(0);
+  });
+
+  it('does not throw and logs warn when result message DB persist fails', async () => {
+    const { discoverWorkflowsWithConfig } = await import('@archon/workflows/workflow-discovery');
+    const { executeWorkflow } = await import('@archon/workflows/executor');
+    const conversationDb = await import('@archon/core/db/conversations');
+    const codebaseDb = await import('@archon/core/db/codebases');
+    const messagesDb = await import('@archon/core/db/messages');
+
+    (discoverWorkflowsWithConfig as ReturnType<typeof mock>).mockResolvedValueOnce({
+      workflows: [makeTestWorkflowWithSource({ name: 'assist', description: 'Help' })],
+      errors: [],
+    });
+    (conversationDb.getOrCreateConversation as ReturnType<typeof mock>).mockResolvedValueOnce({
+      id: 'conv-123',
+    });
+    (codebaseDb.findCodebaseByDefaultCwd as ReturnType<typeof mock>).mockResolvedValueOnce(null);
+    (conversationDb.updateConversation as ReturnType<typeof mock>).mockResolvedValueOnce(undefined);
+    (executeWorkflow as ReturnType<typeof mock>).mockResolvedValueOnce({
+      success: true,
+      workflowRunId: 'run-1',
+      summary: 'Done.',
+    });
+    // addMessage is called three times: user message persist, dispatch, result
+    // CLIAdapter internally catches DB errors — it logs 'cli_message_persist_failed' and does not throw.
+    // Verify workflowRunCommand does not throw even when the result DB write fails.
+    (messagesDb.addMessage as ReturnType<typeof mock>)
+      .mockResolvedValueOnce(undefined) // user message persist succeeds
+      .mockResolvedValueOnce(undefined) // dispatch succeeds
+      .mockRejectedValueOnce(new Error('DB gone')); // result fails (caught inside CLIAdapter)
+
+    // Should not throw — the CLIAdapter swallows the DB error and logs a warn
+    await expect(
+      workflowRunCommand('/test/path', 'assist', 'hello', { noWorktree: true })
+    ).resolves.toBeUndefined();
+
+    // CLIAdapter logs 'cli_message_persist_failed' when addMessage throws internally
+    expect(mockLogger.warn).toHaveBeenCalledWith(
+      expect.objectContaining({ err: expect.any(Error) }),
+      'cli_message_persist_failed'
+    );
+  });
+
+  it('does not throw and continues to executeWorkflow when dispatch sendMessage fails', async () => {
+    const { discoverWorkflowsWithConfig } = await import('@archon/workflows/workflow-discovery');
+    const { executeWorkflow } = await import('@archon/workflows/executor');
+    const conversationDb = await import('@archon/core/db/conversations');
+    const codebaseDb = await import('@archon/core/db/codebases');
+    const messagesDb = await import('@archon/core/db/messages');
+
+    (discoverWorkflowsWithConfig as ReturnType<typeof mock>).mockResolvedValueOnce({
+      workflows: [makeTestWorkflowWithSource({ name: 'assist', description: 'Help' })],
+      errors: [],
+    });
+    (conversationDb.getOrCreateConversation as ReturnType<typeof mock>).mockResolvedValueOnce({
+      id: 'conv-123',
+    });
+    (codebaseDb.findCodebaseByDefaultCwd as ReturnType<typeof mock>).mockResolvedValueOnce(null);
+    (conversationDb.updateConversation as ReturnType<typeof mock>).mockResolvedValueOnce(undefined);
+    (executeWorkflow as ReturnType<typeof mock>).mockClear();
+    (executeWorkflow as ReturnType<typeof mock>).mockResolvedValueOnce({
+      success: true,
+      workflowRunId: 'run-1',
+    });
+    // First addMessage (user message persist) succeeds, second (dispatch) fails
+    (messagesDb.addMessage as ReturnType<typeof mock>)
+      .mockResolvedValueOnce(undefined) // user message persist succeeds
+      .mockRejectedValueOnce(new Error('DB gone')); // dispatch fails (caught inside CLIAdapter)
+
+    // Should not throw — dispatch failure must not block workflow execution
+    await expect(
+      workflowRunCommand('/test/path', 'assist', 'hello', { noWorktree: true })
+    ).resolves.toBeUndefined();
+
+    // executeWorkflow was still called despite dispatch failure
+    expect(executeWorkflow).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not send result card when workflow is paused even with summary', async () => {
+    const { discoverWorkflowsWithConfig } = await import('@archon/workflows/workflow-discovery');
+    const { executeWorkflow } = await import('@archon/workflows/executor');
+    const conversationDb = await import('@archon/core/db/conversations');
+    const codebaseDb = await import('@archon/core/db/codebases');
+    const messagesDb = await import('@archon/core/db/messages');
+
+    (discoverWorkflowsWithConfig as ReturnType<typeof mock>).mockResolvedValueOnce({
+      workflows: [makeTestWorkflowWithSource({ name: 'assist', description: 'Help' })],
+      errors: [],
+    });
+    (conversationDb.getOrCreateConversation as ReturnType<typeof mock>).mockResolvedValueOnce({
+      id: 'conv-123',
+    });
+    (codebaseDb.findCodebaseByDefaultCwd as ReturnType<typeof mock>).mockResolvedValueOnce(null);
+    (conversationDb.updateConversation as ReturnType<typeof mock>).mockResolvedValueOnce(undefined);
+    (executeWorkflow as ReturnType<typeof mock>).mockResolvedValueOnce({
+      success: true,
+      workflowRunId: 'run-paused',
+      paused: true,
+      summary: 'Steps completed so far.',
+    });
+    (messagesDb.addMessage as ReturnType<typeof mock>).mockClear();
+
+    const consoleSpy = spyOn(console, 'log').mockImplementation(() => {});
+    try {
+      await workflowRunCommand('/test/path', 'assist', 'hello', { noWorktree: true });
+
+      // Paused guard fires before summary check — no result card despite having a summary
+      const resultCalls = (messagesDb.addMessage as ReturnType<typeof mock>).mock.calls.filter(
+        (args: unknown[]) => {
+          const meta = args[3] as Record<string, unknown> | undefined;
+          return meta?.category === 'workflow_result';
+        }
+      );
+      expect(resultCalls).toHaveLength(0);
+
+      // Confirm paused message was printed
+      expect(consoleSpy).toHaveBeenCalledWith('\nWorkflow paused — waiting for approval.');
+    } finally {
+      consoleSpy.mockRestore();
+    }
+  });
 });
 
 describe('workflowStatusCommand', () => {
@@ -1381,6 +1763,58 @@ describe('workflowApproveCommand', () => {
 
     expect(codebaseDb.getCodebase).toHaveBeenCalledWith('cb-existing');
   });
+
+  it('should pass original platform conversation ID through to workflowRunCommand', async () => {
+    const workflowDb = await import('@archon/core/db/workflows');
+    const codebaseDb = await import('@archon/core/db/codebases');
+    const conversationsDb = await import('@archon/core/db/conversations');
+    const workflowDiscovery = await import('@archon/workflows/workflow-discovery');
+    const core = await import('@archon/core');
+
+    (workflowDb.getWorkflowRun as ReturnType<typeof mock>).mockResolvedValueOnce({
+      id: 'run-approve-conv',
+      workflow_name: 'implement',
+      status: 'paused',
+      user_message: 'add auth',
+      working_path: '/tmp/test-worktree',
+      codebase_id: 'cb-existing',
+      conversation_id: 'db-uuid-original',
+      metadata: { approval: { nodeId: 'review-node', message: 'Approve?' } },
+    });
+
+    // Return a conversation with the original platform ID
+    (conversationsDb.getConversationById as ReturnType<typeof mock>).mockResolvedValueOnce({
+      id: 'db-uuid-original',
+      platform_type: 'cli',
+      platform_conversation_id: 'cli-original-123',
+    });
+
+    (
+      workflowDiscovery.discoverWorkflowsWithConfig as ReturnType<typeof mock>
+    ).mockResolvedValueOnce({
+      workflows: [makeTestWorkflowWithSource({ name: 'implement' })],
+      errors: [],
+    });
+
+    (codebaseDb.getCodebase as ReturnType<typeof mock>).mockResolvedValueOnce({
+      id: 'cb-existing',
+      name: 'owner/repo',
+      default_cwd: '/path/to/main-checkout',
+    });
+
+    // Clear call history before our test so we can assert precisely
+    (conversationsDb.getOrCreateConversation as ReturnType<typeof mock>).mockClear();
+
+    try {
+      await workflowApproveCommand('run-approve-conv');
+    } catch {
+      // downstream failure is acceptable — we only need to reach getOrCreateConversation
+    }
+
+    // Verify the original platform conversation ID was passed through
+    expect(conversationsDb.getConversationById).toHaveBeenCalledWith('db-uuid-original');
+    expect(conversationsDb.getOrCreateConversation).toHaveBeenCalledWith('cli', 'cli-original-123');
+  });
 });
 
 describe('workflowAbandonCommand', () => {
@@ -1566,6 +2000,61 @@ describe('workflowRejectCommand', () => {
     expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Rejected workflow'));
   });
 
+  it('should pass original platform conversation ID through on reject-resume', async () => {
+    const workflowDb = await import('@archon/core/db/workflows');
+    const conversationsDb = await import('@archon/core/db/conversations');
+    const workflowDiscovery = await import('@archon/workflows/workflow-discovery');
+
+    const runData = {
+      id: 'run-reject-conv',
+      workflow_name: 'my-wf',
+      status: 'paused',
+      user_message: 'build it',
+      working_path: '/repo',
+      codebase_id: null,
+      conversation_id: 'db-uuid-reject',
+      metadata: {
+        approval: {
+          type: 'approval',
+          nodeId: 'gate',
+          message: 'Approve?',
+          onRejectPrompt: 'Fix: $REJECTION_REASON',
+          onRejectMaxAttempts: 3,
+        },
+        rejection_count: 0,
+      },
+    };
+    // rejectWorkflow reads the run twice internally (getRunOrThrow + updateWorkflowRun check)
+    (workflowDb.getWorkflowRun as ReturnType<typeof mock>).mockResolvedValueOnce(runData);
+
+    // Return a conversation with the original platform ID
+    (conversationsDb.getConversationById as ReturnType<typeof mock>).mockResolvedValueOnce({
+      id: 'db-uuid-reject',
+      platform_type: 'cli',
+      platform_conversation_id: 'cli-reject-456',
+    });
+
+    (
+      workflowDiscovery.discoverWorkflowsWithConfig as ReturnType<typeof mock>
+    ).mockResolvedValueOnce({
+      workflows: [makeTestWorkflowWithSource({ name: 'my-wf' })],
+      errors: [],
+    });
+
+    // Clear call history before our test so we can assert precisely
+    (conversationsDb.getOrCreateConversation as ReturnType<typeof mock>).mockClear();
+
+    try {
+      await workflowRejectCommand('run-reject-conv', 'needs work');
+    } catch {
+      // downstream workflowRunCommand failure is acceptable — we only need to reach getOrCreateConversation
+    }
+
+    // Verify the original platform conversation ID was passed through
+    expect(conversationsDb.getConversationById).toHaveBeenCalledWith('db-uuid-reject');
+    expect(conversationsDb.getOrCreateConversation).toHaveBeenCalledWith('cli', 'cli-reject-456');
+  });
+
   it('cancels when max attempts reached', async () => {
     const workflowDb = await import('@archon/core/db/workflows');
     const core = await import('@archon/core');

packages/cli/src/commands/workflow.ts

@@ -10,7 +10,7 @@ import {
 } from '@archon/core';
 import { WORKFLOW_EVENT_TYPES, type WorkflowEventType } from '@archon/workflows/store';
 import { configureIsolation, getIsolationProvider } from '@archon/isolation';
-import { createLogger, getArchonHome } from '@archon/paths';
+import { createLogger } from '@archon/paths';
 import { createWorkflowDeps } from '@archon/core/workflows/store-adapter';
 import { discoverWorkflowsWithConfig } from '@archon/workflows/workflow-discovery';
 import { resolveWorkflowName } from '@archon/workflows/router';
@@ -62,10 +62,10 @@ export interface WorkflowRunOptions {
   noWorktree?: boolean;
   resume?: boolean;
   codebaseId?: string; // Passed by resume/approve to skip path-based lookup
-  /** When true, skip the env-leak-gate during auto-registration. */
-  allowEnvKeys?: boolean;
   quiet?: boolean;
   verbose?: boolean;
+  /** Platform conversation ID (e.g. `cli-{ts}-{rand}`), NOT a DB UUID. */
+  conversationId?: string;
 }
 
 /**
@@ -119,9 +119,9 @@ function renderWorkflowEvent(event: WorkflowEmitterEvent, verbose: boolean): voi
  */
 async function loadWorkflows(cwd: string): Promise<WorkflowLoadResult> {
   try {
-    return await discoverWorkflowsWithConfig(cwd, loadConfig, {
-      globalSearchPath: getArchonHome(),
-    });
+    // Home-scoped workflows at ~/.archon/workflows/ are discovered automatically —
+    // no option needed since the discovery helper reads them unconditionally.
+    return await discoverWorkflowsWithConfig(cwd, loadConfig);
   } catch (error) {
     const err = error as Error;
     throw new Error(
@@ -178,7 +178,7 @@ export async function workflowListCommand(cwd: string, json?: boolean): Promise<
   }
 
   if (workflowEntries.length > 0) {
-    console.log(`\nFound ${String(workflowEntries.length)} workflow(s):\n`);
+    console.log(`\nFound ${workflowEntries.length} workflow(s):\n`);
 
     for (const { workflow } of workflowEntries) {
       console.log(`  ${workflow.name}`);
@@ -191,7 +191,7 @@ export async function workflowListCommand(cwd: string, json?: boolean): Promise<
   }
 
   if (errors.length > 0) {
-    console.log(`\n${String(errors.length)} workflow(s) failed to load:\n`);
+    console.log(`\n${errors.length} workflow(s) failed to load:\n`);
     for (const e of errors) {
       console.log(`  ${e.filename}: ${e.error}`);
     }
@@ -261,6 +261,37 @@ export async function workflowRunCommand(
     );
   }
 
+  // Reconcile workflow-level worktree policy with invocation flags.
+  // The workflow YAML's `worktree.enabled` pins isolation regardless of caller —
+  // a mismatch between policy and flags is a user error we surface loudly
+  // rather than silently applying one side and ignoring the other.
+  const pinnedEnabled = workflow.worktree?.enabled;
+  if (pinnedEnabled === false) {
+    if (options.branchName !== undefined) {
+      throw new Error(
+        `Workflow '${workflow.name}' sets worktree.enabled: false (runs in live checkout).\n` +
+          '  --branch requires an isolated worktree.\n' +
+          "  Drop --branch or change the workflow's worktree.enabled."
+      );
+    }
+    if (options.fromBranch !== undefined) {
+      throw new Error(
+        `Workflow '${workflow.name}' sets worktree.enabled: false (runs in live checkout).\n` +
+          '  --from/--from-branch only applies when a worktree is created.\n' +
+          "  Drop --from or change the workflow's worktree.enabled."
+      );
+    }
+    // --no-worktree is redundant but not contradictory — silently accept.
+  } else if (pinnedEnabled === true) {
+    if (options.noWorktree) {
+      throw new Error(
+        `Workflow '${workflow.name}' sets worktree.enabled: true (requires a worktree).\n` +
+          '  --no-worktree conflicts with the workflow policy.\n' +
+          "  Drop --no-worktree or change the workflow's worktree.enabled."
+      );
+    }
+  }
+
   console.log(`Running workflow: ${workflowName}`);
   console.log(`Working directory: ${cwd}`);
   console.log('');
@@ -269,7 +300,7 @@ export async function workflowRunCommand(
   const adapter = new CLIAdapter();
 
   // Generate conversation ID
-  const conversationId = generateConversationId();
+  const conversationId = options.conversationId ?? generateConversationId();
 
   // Get or create conversation in database
   let conversation;
@@ -323,7 +354,7 @@ export async function workflowRunCommand(
     const repoRoot = await git.findRepoRoot(cwd);
     if (repoRoot) {
       try {
-        const result = await registerRepository(repoRoot, options.allowEnvKeys, 'register-cli');
+        const result = await registerRepository(repoRoot);
         codebase = await codebaseDb.getCodebase(result.codebaseId);
         if (!result.alreadyExisted) {
           getLog().info({ name: result.name }, 'cli.codebase_auto_registered');
@@ -403,8 +434,14 @@ export async function workflowRunCommand(
     console.log('');
   }
 
-  // Default to worktree isolation unless --no-worktree or --resume
-  const wantsIsolation = !options.resume && !options.noWorktree;
+  // Default to worktree isolation unless --no-worktree or --resume.
+  // Workflow YAML `worktree.enabled` pins the decision — mismatches with CLI
+  // flags are rejected above, so by this point the policy (if set) and flags
+  // agree. `--resume` reuses an existing worktree and takes precedence over
+  // the pinned policy to avoid disturbing a paused run.
+  const flagWantsIsolation = !options.resume && !options.noWorktree;
+  const wantsIsolation =
+    !options.resume && pinnedEnabled !== undefined ? pinnedEnabled : flagWantsIsolation;
 
   if (wantsIsolation && codebase) {
     // Auto-generate branch identifier from workflow name + timestamp when --branch not provided
@@ -589,6 +626,24 @@ export async function workflowRunCommand(
         renderWorkflowEvent(event, verbose ?? false);
       });
 
+  // Notify Web UI that a workflow is dispatching.
+  // Mirrors the orchestrator dispatch message structure (category/segment/workflowDispatch),
+  // but omits the rocket emoji and "(background)" qualifier since the CLI runs synchronously.
+  // In the CLI path there is no separate worker conversation — the CLI itself
+  // is both the dispatcher and the executor, so workerConversationId === conversationId.
+  try {
+    await adapter.sendMessage(conversationId, `Dispatching workflow: **${workflow.name}**`, {
+      category: 'workflow_dispatch_status',
+      segment: 'new',
+      workflowDispatch: { workerConversationId: conversationId, workflowName: workflow.name },
+    });
+  } catch (dispatchError) {
+    getLog().warn(
+      { err: dispatchError as Error, conversationId },
+      'cli.workflow_dispatch_surface_failed'
+    );
+  }
+
   // Execute workflow with workingCwd (may be worktree path)
   let result: Awaited<ReturnType<typeof executeWorkflow>>;
   try {
@@ -610,6 +665,22 @@ export async function workflowRunCommand(
   if (result.success && 'paused' in result && result.paused) {
     console.log('\nWorkflow paused — waiting for approval.');
   } else if (result.success) {
+    // Surface workflow result to Web UI as a result card (mirrors orchestrator.ts result message).
+    // Paused workflows are handled in the branch above and intentionally do not get a result card.
+    if ('summary' in result && result.summary) {
+      try {
+        await adapter.sendMessage(conversationId, result.summary, {
+          category: 'workflow_result',
+          segment: 'new',
+          workflowResult: { workflowName: workflow.name, runId: result.workflowRunId },
+        });
+      } catch (surfaceError) {
+        getLog().warn(
+          { err: surfaceError as Error, conversationId },
+          'cli.workflow_result_surface_failed'
+        );
+      }
+    }
     console.log('\nWorkflow completed successfully.');
   } else {
     throw new Error(`Workflow failed: ${result.error}`);
@@ -628,25 +699,25 @@ function formatAge(startedAt: Date | string): string {
   if (Number.isNaN(date.getTime())) return 'unknown';
   const ms = Date.now() - date.getTime();
   const secs = Math.floor(ms / 1000);
-  if (secs < 60) return `${String(secs)}s`;
+  if (secs < 60) return `${secs}s`;
   const mins = Math.floor(secs / 60);
-  if (mins < 60) return `${String(mins)}m`;
+  if (mins < 60) return `${mins}m`;
   const hours = Math.floor(mins / 60);
-  if (hours < 24) return `${String(hours)}h ${String(mins % 60)}m`;
+  if (hours < 24) return `${hours}h ${mins % 60}m`;
   const days = Math.floor(hours / 24);
-  return `${String(days)}d ${String(hours % 24)}h`;
+  return `${days}d ${hours % 24}h`;
 }
 
 /**
  * Format a duration in milliseconds as a compact string.
  */
 function formatDuration(ms: number): string {
-  if (ms < 1000) return `${String(ms)}ms`;
+  if (ms < 1000) return `${ms}ms`;
   const secs = Math.round(ms / 100) / 10;
-  if (secs < 60) return `${String(secs)}s`;
+  if (secs < 60) return `${secs}s`;
   const mins = Math.floor(secs / 60);
   const remSecs = Math.round(secs % 60);
-  return `${String(mins)}m${String(remSecs)}s`;
+  return `${mins}m${remSecs}s`;
 }
 
 interface NodeSummary {
@@ -730,20 +801,16 @@ export async function workflowStatusCommand(json?: boolean, verbose?: boolean):
   }
 
   if (json) {
+    let runsOutput: unknown[] = runs;
     if (verbose) {
       const eventsPerRun = await Promise.all(
         runs.map(run =>
           workflowEventsDb.listWorkflowEvents(run.id).catch(() => [] as WorkflowEventRow[])
         )
       );
-      const runsWithEvents = runs.map((run, i) => ({
-        ...run,
-        events: eventsPerRun[i],
-      }));
-      console.log(JSON.stringify({ runs: runsWithEvents }, null, 2));
-    } else {
-      console.log(JSON.stringify({ runs }, null, 2));
+      runsOutput = runs.map((run, i) => ({ ...run, events: eventsPerRun[i] }));
     }
+    console.log(JSON.stringify({ runs: runsOutput }, null, 2));
     return;
   }
 
@@ -752,7 +819,7 @@ export async function workflowStatusCommand(json?: boolean, verbose?: boolean):
     return;
   }
 
-  console.log(`\nActive workflows (${String(runs.length)}):\n`);
+  console.log(`\nActive workflows (${runs.length}):\n`);
   for (const run of runs) {
     const age = formatAge(run.started_at);
     console.log(`  ID:     ${run.id}`);
@@ -861,10 +928,30 @@ export async function workflowApproveCommand(runId: string, comment?: string): P
   console.log('');
   console.log('Resuming workflow...');
 
+  // Look up the original platform conversation ID to keep all messages in one thread
+  let platformConversationId: string | undefined;
+  try {
+    const originalConversation = await conversationDb.getConversationById(result.conversationId);
+    platformConversationId = originalConversation?.platform_conversation_id ?? undefined;
+    if (!originalConversation) {
+      getLog().info(
+        { runId, conversationId: result.conversationId },
+        'cli.workflow_approve_conversation_not_found'
+      );
+    }
+  } catch (error) {
+    const err = error as Error;
+    getLog().warn(
+      { err, runId, conversationId: result.conversationId },
+      'cli.workflow_approve_conversation_lookup_failed'
+    );
+  }
+
   try {
     await workflowRunCommand(result.workingPath, result.workflowName, result.userMessage ?? '', {
       resume: true,
       codebaseId: result.codebaseId ?? undefined,
+      conversationId: platformConversationId,
     });
   } catch (error) {
     const err = error as Error;
@@ -900,10 +987,31 @@ export async function workflowRejectCommand(runId: string, reason?: string): Pro
   }
   console.log(`Rejected workflow: ${result.workflowName}`);
   console.log('Resuming with on_reject prompt...');
+
+  // Look up the original platform conversation ID to keep all messages in one thread
+  let platformConversationId: string | undefined;
+  try {
+    const originalConversation = await conversationDb.getConversationById(result.conversationId);
+    platformConversationId = originalConversation?.platform_conversation_id ?? undefined;
+    if (!originalConversation) {
+      getLog().info(
+        { runId, conversationId: result.conversationId },
+        'cli.workflow_reject_conversation_not_found'
+      );
+    }
+  } catch (error) {
+    const err = error as Error;
+    getLog().warn(
+      { err, runId, conversationId: result.conversationId },
+      'cli.workflow_reject_conversation_lookup_failed'
+    );
+  }
+
   try {
     await workflowRunCommand(result.workingPath, result.workflowName, result.userMessage ?? '', {
       resume: true,
       codebaseId: result.codebaseId ?? undefined,
+      conversationId: platformConversationId,
     });
   } catch (error) {
     const err = error as Error;
@@ -925,9 +1033,9 @@ export async function workflowCleanupCommand(days: number): Promise<void> {
   try {
     const { count } = await workflowDb.deleteOldWorkflowRuns(days);
     if (count === 0) {
-      console.log(`No workflow runs older than ${String(days)} days to clean up.`);
+      console.log(`No workflow runs older than ${days} days to clean up.`);
     } else {
-      console.log(`Deleted ${String(count)} workflow run(s) older than ${String(days)} days.`);
+      console.log(`Deleted ${count} workflow run(s) older than ${days} days.`);
     }
   } catch (error) {
     const err = error as Error;

packages/cli/tsconfig.json

@@ -3,14 +3,31 @@
   "compilerOptions": {
     "noEmit": true,
     "paths": {
+      "@archon/adapters": ["../adapters/src"],
+      "@archon/adapters/*": ["../adapters/src/*"],
       "@archon/core": ["../core/src"],
       "@archon/core/*": ["../core/src/*"],
+      "@archon/server": ["../server/src"],
+      "@archon/server/*": ["../server/src/*"],
       "@archon/workflows": ["../workflows/src"],
       "@archon/workflows/*": ["../workflows/src/*"],
       "@archon/paths": ["../paths/src"],
       "@archon/git": ["../git/src"]
     }
   },
-  "include": ["src/**/*", "../core/src/**/*.ts", "../workflows/src/defaults/text-imports.d.ts"],
-  "exclude": ["node_modules", "dist", "**/*.test.ts", "../core/src/**/*.test.ts"]
+  "include": [
+    "src/**/*",
+    "../core/src/**/*.ts",
+    "../server/src/**/*.ts",
+    "../adapters/src/**/*.ts",
+    "../workflows/src/defaults/text-imports.d.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/*.test.ts",
+    "../core/src/**/*.test.ts",
+    "../server/src/**/*.test.ts",
+    "../adapters/src/**/*.test.ts"
+  ]
 }

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archon/core",
-  "version": "0.2.0",
+  "version": "0.3.6",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -9,7 +9,6 @@
     "./types": "./src/types/index.ts",
     "./db": "./src/db/index.ts",
     "./db/*": "./src/db/*.ts",
-    "./clients": "./src/clients/index.ts",
     "./operations": "./src/operations/index.ts",
     "./operations/*": "./src/operations/*.ts",
     "./workflows": "./src/workflows/index.ts",
@@ -23,17 +22,16 @@
     "./state/*": "./src/state/*.ts"
   },
   "scripts": {
-    "test": "bun test src/clients/ && bun test src/handlers/command-handler.test.ts && bun test src/handlers/clone.test.ts && bun test src/db/adapters/postgres.test.ts && bun test src/db/adapters/sqlite.test.ts src/db/codebases.test.ts src/db/connection.test.ts src/db/conversations.test.ts src/db/env-vars.test.ts src/db/isolation-environments.test.ts src/db/messages.test.ts src/db/sessions.test.ts src/db/workflow-events.test.ts src/db/workflows.test.ts src/utils/defaults-copy.test.ts src/utils/worktree-sync.test.ts src/utils/conversation-lock.test.ts src/utils/credential-sanitizer.test.ts src/utils/port-allocation.test.ts src/utils/error.test.ts src/utils/error-formatter.test.ts src/utils/github-graphql.test.ts src/utils/env-allowlist.test.ts src/utils/env-leak-scanner.test.ts src/config/ src/state/ && bun test src/utils/path-validation.test.ts && bun test src/services/cleanup-service.test.ts && bun test src/services/title-generator.test.ts && bun test src/workflows/ && bun test src/operations/workflow-operations.test.ts && bun test src/operations/isolation-operations.test.ts && bun test src/orchestrator/orchestrator.test.ts && bun test src/orchestrator/orchestrator-agent.test.ts && bun test src/orchestrator/orchestrator-isolation.test.ts",
+    "test": "bun test src/handlers/command-handler.test.ts && bun test src/handlers/clone.test.ts && bun test src/db/adapters/postgres.test.ts && bun test src/db/connection.test.ts && bun test src/db/adapters/sqlite.test.ts src/db/codebases.test.ts src/db/conversations.test.ts src/db/env-vars.test.ts src/db/isolation-environments.test.ts src/db/messages.test.ts src/db/sessions.test.ts src/db/workflow-events.test.ts src/db/workflows.test.ts src/utils/defaults-copy.test.ts src/utils/worktree-sync.test.ts src/utils/conversation-lock.test.ts src/utils/credential-sanitizer.test.ts src/utils/port-allocation.test.ts src/utils/error.test.ts src/utils/error-formatter.test.ts src/utils/github-graphql.test.ts src/config/ src/state/ && bun test src/utils/path-validation.test.ts && bun test src/services/cleanup-service.test.ts && bun test src/services/title-generator.test.ts && bun test src/workflows/ && bun test src/operations/workflow-operations.test.ts && bun test src/operations/isolation-operations.test.ts && bun test src/orchestrator/orchestrator.test.ts && bun test src/orchestrator/orchestrator-agent.test.ts && bun test src/orchestrator/orchestrator-isolation.test.ts",
     "type-check": "bun x tsc --noEmit",
     "build": "echo 'No build needed - Bun runs TypeScript directly'"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.89",
     "@archon/git": "workspace:*",
     "@archon/isolation": "workspace:*",
     "@archon/paths": "workspace:*",
+    "@archon/providers": "workspace:*",
     "@archon/workflows": "workspace:*",
-    "@openai/codex-sdk": "^0.116.0",
     "pg": "^8.11.0",
     "zod": "^3"
   },

packages/core/src/clients/claude.ts

@@ -1,635 +0,0 @@
-/**
- * Claude Agent SDK wrapper
- * Provides async generator interface for streaming Claude responses
- *
- * Type Safety Pattern:
- * - Uses `Options` type from SDK for query configuration
- * - SDK message types (SDKMessage, SDKAssistantMessage, etc.) have strict
- *   type checking that requires explicit type handling for content blocks
- * - Content blocks are typed via inline assertions for clarity
- *
- * Authentication:
- * - CLAUDE_USE_GLOBAL_AUTH=true: Use global auth from `claude /login`, filter env tokens
- * - CLAUDE_USE_GLOBAL_AUTH=false: Use explicit tokens from env vars
- * - Not set: Auto-detect - use tokens if present in env, otherwise global auth
- */
-import {
-  query,
-  type Options,
-  type HookCallback,
-  type HookCallbackMatcher,
-} from '@anthropic-ai/claude-agent-sdk';
-import {
-  type AssistantRequestOptions,
-  type IAssistantClient,
-  type MessageChunk,
-  type TokenUsage,
-} from '../types';
-import { createLogger } from '@archon/paths';
-import { buildCleanSubprocessEnv } from '../utils/env-allowlist';
-import { scanPathForSensitiveKeys, EnvLeakError } from '../utils/env-leak-scanner';
-import * as codebaseDb from '../db/codebases';
-import { loadConfig } from '../config/config-loader';
-
-/** Lazy-initialized logger (deferred so test mocks can intercept createLogger) */
-let cachedLog: ReturnType<typeof createLogger> | undefined;
-function getLog(): ReturnType<typeof createLogger> {
-  if (!cachedLog) cachedLog = createLogger('client.claude');
-  return cachedLog;
-}
-
-/**
- * Content block type for assistant messages
- * Represents text or tool_use blocks from Claude API responses
- */
-interface ContentBlock {
-  type: 'text' | 'tool_use';
-  text?: string;
-  name?: string;
-  input?: Record<string, unknown>;
-  /** Stable Anthropic `tool_use_id` — used to pair `tool_call`/`tool_result` events. */
-  id?: string;
-}
-
-function normalizeClaudeUsage(usage?: {
-  input_tokens?: number;
-  output_tokens?: number;
-  total_tokens?: number;
-}): TokenUsage | undefined {
-  if (!usage) return undefined;
-  const input = usage.input_tokens;
-  const output = usage.output_tokens;
-  if (typeof input !== 'number' || typeof output !== 'number') return undefined;
-  const total = usage.total_tokens;
-
-  return {
-    input,
-    output,
-    ...(typeof total === 'number' ? { total } : {}),
-  };
-}
-
-/**
- * Build environment for Claude subprocess
- *
- * Auth behavior:
- * - CLAUDE_USE_GLOBAL_AUTH=true: Filter tokens, use global auth from `claude /login`
- * - CLAUDE_USE_GLOBAL_AUTH=false: Pass tokens through explicitly
- * - Not set: Auto-detect — use explicit tokens if present, otherwise fall back to global auth
- */
-function buildSubprocessEnv(): NodeJS.ProcessEnv {
-  const globalAuthSetting = process.env.CLAUDE_USE_GLOBAL_AUTH?.toLowerCase();
-
-  // Check for empty token values (common misconfiguration)
-  const tokenVars = ['CLAUDE_CODE_OAUTH_TOKEN', 'CLAUDE_API_KEY'] as const;
-  const emptyTokens = tokenVars.filter(v => process.env[v] === '');
-  if (emptyTokens.length > 0) {
-    getLog().warn({ emptyTokens }, 'empty_token_values');
-  }
-
-  // Warn if user has the legacy variable but not the new ones
-  if (
-    process.env.ANTHROPIC_API_KEY &&
-    !process.env.CLAUDE_CODE_OAUTH_TOKEN &&
-    !process.env.CLAUDE_API_KEY
-  ) {
-    getLog().warn(
-      { hint: 'Use CLAUDE_API_KEY or CLAUDE_CODE_OAUTH_TOKEN instead' },
-      'deprecated_anthropic_api_key_ignored'
-    );
-  }
-
-  const hasExplicitTokens = Boolean(
-    process.env.CLAUDE_CODE_OAUTH_TOKEN ?? process.env.CLAUDE_API_KEY
-  );
-
-  // Determine whether to use global auth
-  let useGlobalAuth: boolean;
-  if (globalAuthSetting === 'true') {
-    useGlobalAuth = true;
-    getLog().info({ authMode: 'global' }, 'using_global_auth');
-  } else if (globalAuthSetting === 'false') {
-    useGlobalAuth = false;
-    getLog().info({ authMode: 'explicit' }, 'using_explicit_tokens');
-  } else if (globalAuthSetting !== undefined) {
-    // Unrecognized value - warn and fall back to auto-detect
-    getLog().warn({ value: globalAuthSetting }, 'unrecognized_global_auth_setting');
-    useGlobalAuth = !hasExplicitTokens;
-  } else {
-    // Not set - auto-detect: use tokens if present, otherwise global auth
-    useGlobalAuth = !hasExplicitTokens;
-    if (hasExplicitTokens) {
-      getLog().info({ authMode: 'explicit', autoDetected: true }, 'using_explicit_tokens');
-    } else {
-      getLog().info({ authMode: 'global', autoDetected: true }, 'using_global_auth');
-    }
-  }
-
-  let baseEnv: NodeJS.ProcessEnv;
-
-  if (useGlobalAuth) {
-    // Start from allowlist-filtered env, then strip auth tokens
-    const clean = buildCleanSubprocessEnv();
-    const { CLAUDE_CODE_OAUTH_TOKEN, CLAUDE_API_KEY, ...envWithoutAuth } = clean;
-
-    // Log if we're filtering out tokens (helps debug auth issues)
-    const filtered = [
-      CLAUDE_CODE_OAUTH_TOKEN && 'CLAUDE_CODE_OAUTH_TOKEN',
-      CLAUDE_API_KEY && 'CLAUDE_API_KEY',
-    ].filter(Boolean);
-
-    if (filtered.length > 0) {
-      getLog().info({ filteredVars: filtered }, 'global_auth_filtered_tokens');
-    }
-
-    baseEnv = envWithoutAuth;
-  } else {
-    // Start from allowlist-filtered env (includes auth tokens)
-    baseEnv = buildCleanSubprocessEnv();
-  }
-
-  // Clean env vars that interfere with Claude Code subprocess
-  const cleanedVars: string[] = [];
-
-  // Strip nested-session guard marker (claude-code v2.1.41+).
-  // When the server is started from inside a Claude Code terminal, CLAUDECODE=1
-  // is inherited and causes the subprocess to refuse to launch.
-  // See: https://github.com/anthropics/claude-code/issues/25434
-  if (baseEnv.CLAUDECODE) {
-    delete baseEnv.CLAUDECODE;
-    cleanedVars.push('CLAUDECODE');
-  }
-
-  // Strip debugger env vars
-  // See: https://github.com/anthropics/claude-code/issues/4619
-  if (baseEnv.NODE_OPTIONS) {
-    delete baseEnv.NODE_OPTIONS;
-    cleanedVars.push('NODE_OPTIONS');
-  }
-  if (baseEnv.VSCODE_INSPECTOR_OPTIONS) {
-    delete baseEnv.VSCODE_INSPECTOR_OPTIONS;
-    cleanedVars.push('VSCODE_INSPECTOR_OPTIONS');
-  }
-  if (cleanedVars.length > 0) {
-    getLog().info({ cleanedVars }, 'subprocess_env_cleaned');
-  }
-
-  return baseEnv;
-}
-
-/** Max retries for transient subprocess failures (3 = 4 total attempts).
- *  SDK subprocess crashes (exit code 1) are often intermittent — AJV schema validation
- *  regressions, stale HTTP/2 connections, and other transient SDK issues typically
- *  succeed on retry 3 or 4. See: anthropics/claude-code#22973, claude-code-action#853 */
-const MAX_SUBPROCESS_RETRIES = 3;
-
-/** Delay between retries in milliseconds */
-const RETRY_BASE_DELAY_MS = 2000;
-
-/** Patterns indicating rate limiting in stderr/error messages */
-const RATE_LIMIT_PATTERNS = ['rate limit', 'too many requests', '429', 'overloaded'];
-
-/** Patterns indicating auth issues in stderr/error messages */
-const AUTH_PATTERNS = [
-  'credit balance',
-  'unauthorized',
-  'authentication',
-  'invalid token',
-  '401',
-  '403',
-];
-
-/** Patterns indicating the subprocess crashed (transient, worth retrying) */
-const SUBPROCESS_CRASH_PATTERNS = [
-  'exited with code',
-  'killed',
-  'signal',
-  // "Operation aborted" can appear when the SDK's PostToolUse hook tries to write()
-  // back to a subprocess pipe that was closed by an abort signal. This is a race
-  // condition in SDK cleanup — safe to classify as a crash and retry.
-  'operation aborted',
-];
-
-function classifySubprocessError(
-  errorMessage: string,
-  stderrOutput: string
-): 'rate_limit' | 'auth' | 'crash' | 'unknown' {
-  const combined = `${errorMessage} ${stderrOutput}`.toLowerCase();
-  if (RATE_LIMIT_PATTERNS.some(p => combined.includes(p))) return 'rate_limit';
-  if (AUTH_PATTERNS.some(p => combined.includes(p))) return 'auth';
-  if (SUBPROCESS_CRASH_PATTERNS.some(p => combined.includes(p))) return 'crash';
-  return 'unknown';
-}
-
-/**
- * Returns the current process UID, or undefined on platforms that don't support it (e.g. Windows).
- * Exported for testing — spyOn(claudeModule, 'getProcessUid') works cross-platform.
- */
-export function getProcessUid(): number | undefined {
-  return typeof process.getuid === 'function' ? process.getuid() : undefined;
-}
-
-/**
- * Claude AI assistant client
- * Implements generic IAssistantClient interface
- */
-export class ClaudeClient implements IAssistantClient {
-  private readonly retryBaseDelayMs: number;
-
-  constructor(options?: { retryBaseDelayMs?: number }) {
-    // Claude Code SDK silently rejects bypassPermissions when running as root (UID 0).
-    // Check once at construction time so the error surfaces early, not on first query.
-    // IS_SANDBOX=1 bypasses this check — the SDK itself honours this env var in sandboxed
-    // environments (Docker, VPS, CI) where running as root is expected.
-    if (getProcessUid() === 0 && process.env.IS_SANDBOX !== '1') {
-      throw new Error(
-        'Claude Code SDK does not support bypassPermissions when running as root (UID 0). ' +
-          'Run as a non-root user, set IS_SANDBOX=1, or use the Dockerfile which creates a non-root appuser.'
-      );
-    }
-    this.retryBaseDelayMs = options?.retryBaseDelayMs ?? RETRY_BASE_DELAY_MS;
-  }
-
-  /**
-   * Send a query to Claude and stream responses.
-   * Includes retry logic for transient failures (up to 3 retries with exponential backoff).
-   * Enriches errors with stderr context and classification.
-   */
-  async *sendQuery(
-    prompt: string,
-    cwd: string,
-    resumeSessionId?: string,
-    requestOptions?: AssistantRequestOptions
-  ): AsyncGenerator<MessageChunk> {
-    // Pre-spawn: check for env key leak if codebase is not explicitly consented.
-    // Use prefix lookup so worktree paths (e.g. .../worktrees/feature-branch) still
-    // match the registered source cwd (e.g. .../source).
-    const codebase =
-      (await codebaseDb.findCodebaseByDefaultCwd(cwd)) ??
-      (await codebaseDb.findCodebaseByPathPrefix(cwd));
-    if (!codebase?.allow_env_keys) {
-      // Fail-closed: a config load failure (corrupt YAML, permission denied)
-      // must NOT silently bypass the gate. Catch, log, and treat as
-      // `allowTargetRepoKeys = false` so the scanner still runs.
-      let allowTargetRepoKeys = false;
-      try {
-        const merged = await loadConfig(cwd);
-        allowTargetRepoKeys = merged.allowTargetRepoKeys;
-      } catch (configErr) {
-        getLog().warn({ err: configErr, cwd }, 'env_leak_gate.config_load_failed_gate_enforced');
-      }
-      if (!allowTargetRepoKeys) {
-        const report = scanPathForSensitiveKeys(cwd);
-        if (report.findings.length > 0) {
-          throw new EnvLeakError(report, 'spawn-existing');
-        }
-      }
-    }
-
-    // Note: If subprocess crashes mid-stream after yielding chunks, those chunks
-    // are already consumed by the caller. Retry starts a fresh subprocess, so the
-    // caller may receive partial output from the failed attempt followed by full
-    // output from the retry. This is a known limitation of async generator retries.
-    let lastError: Error | undefined;
-
-    for (let attempt = 0; attempt <= MAX_SUBPROCESS_RETRIES; attempt++) {
-      // Check if already aborted before starting attempt
-      if (requestOptions?.abortSignal?.aborted) {
-        throw new Error('Query aborted');
-      }
-
-      const stderrLines: string[] = [];
-      const toolResultQueue: { toolName: string; toolOutput: string; toolCallId?: string }[] = [];
-
-      // Create per-attempt abort controller and wire to caller's signal
-      const controller = new AbortController();
-      if (requestOptions?.abortSignal) {
-        requestOptions.abortSignal.addEventListener(
-          'abort',
-          () => {
-            controller.abort();
-          },
-          { once: true }
-        );
-      }
-
-      const options: Options = {
-        cwd,
-        env: requestOptions?.env
-          ? { ...buildSubprocessEnv(), ...requestOptions.env }
-          : buildSubprocessEnv(),
-        model: requestOptions?.model,
-        abortController: controller,
-        ...(requestOptions?.tools !== undefined ? { tools: requestOptions.tools } : {}),
-        ...(requestOptions?.disallowedTools !== undefined
-          ? { disallowedTools: requestOptions.disallowedTools }
-          : {}),
-        // Pass outputFormat for json_schema structured output (Claude Agent SDK v0.2.45+)
-        ...(requestOptions?.outputFormat !== undefined
-          ? { outputFormat: requestOptions.outputFormat }
-          : {}),
-        // Note: hooks are merged below (line with `hooks: { ... }`) — not spread here
-        // Pass MCP servers for per-node MCP support (Claude Agent SDK v0.2.74+)
-        ...(requestOptions?.mcpServers !== undefined
-          ? { mcpServers: requestOptions.mcpServers }
-          : {}),
-        // Pass allowedTools for MCP tool wildcards (e.g., 'mcp__github__*')
-        ...(requestOptions?.allowedTools !== undefined
-          ? { allowedTools: requestOptions.allowedTools }
-          : {}),
-        // Pass agents/agent for per-node skill scoping via AgentDefinition wrapping
-        ...(requestOptions?.agents !== undefined ? { agents: requestOptions.agents } : {}),
-        ...(requestOptions?.agent !== undefined ? { agent: requestOptions.agent } : {}),
-        // Skip writing session transcripts to ~/.claude/projects/ — Archon manages its own
-        // session persistence. persistSession: false reduces disk I/O and keeps the session
-        // directory clean. Claude Agent SDK v0.2.74+.
-        ...(requestOptions?.persistSession !== undefined
-          ? { persistSession: requestOptions.persistSession }
-          : {}),
-        // When forkSession is true, the SDK copies the prior session's history into a new
-        // session file, leaving the original untouched — safe to use on retries.
-        ...(requestOptions?.forkSession !== undefined
-          ? { forkSession: requestOptions.forkSession }
-          : {}),
-        // Forward Claude-only SDK options (effort, thinking, maxBudgetUsd, fallbackModel, betas, sandbox)
-        ...(requestOptions?.effort !== undefined ? { effort: requestOptions.effort } : {}),
-        ...(requestOptions?.thinking !== undefined ? { thinking: requestOptions.thinking } : {}),
-        ...(requestOptions?.maxBudgetUsd !== undefined
-          ? { maxBudgetUsd: requestOptions.maxBudgetUsd }
-          : {}),
-        ...(requestOptions?.fallbackModel !== undefined
-          ? { fallbackModel: requestOptions.fallbackModel }
-          : {}),
-        // betas: string[] from user config; SDK expects SdkBeta[] (string literal union).
-        // User-provided values are validated upstream — cast is safe.
-        ...(requestOptions?.betas !== undefined
-          ? { betas: requestOptions.betas as Options['betas'] }
-          : {}),
-        ...(requestOptions?.sandbox !== undefined ? { sandbox: requestOptions.sandbox } : {}),
-        permissionMode: 'bypassPermissions',
-        allowDangerouslySkipPermissions: true,
-        systemPrompt: requestOptions?.systemPrompt ?? { type: 'preset', preset: 'claude_code' },
-        settingSources: requestOptions?.settingSources ?? ['project'],
-        // Merge user-provided hooks with our PostToolUse capture hook
-        hooks: {
-          ...(requestOptions?.hooks ?? {}),
-          PostToolUse: [
-            ...((requestOptions?.hooks?.PostToolUse ?? []) as HookCallbackMatcher[]),
-            {
-              hooks: [
-                (async (input: Record<string, unknown>): Promise<{ continue: true }> => {
-                  const toolName = (input as { tool_name?: string }).tool_name ?? 'unknown';
-                  const toolUseId = (input as { tool_use_id?: string }).tool_use_id;
-                  const toolResponse = (input as { tool_response?: unknown }).tool_response;
-                  const output =
-                    typeof toolResponse === 'string'
-                      ? toolResponse
-                      : JSON.stringify(toolResponse ?? '');
-                  // Truncate large outputs (e.g., file reads) to prevent DB bloat
-                  const maxLen = 10_000;
-                  toolResultQueue.push({
-                    toolName,
-                    toolOutput: output.length > maxLen ? output.slice(0, maxLen) + '...' : output,
-                    ...(toolUseId !== undefined ? { toolCallId: toolUseId } : {}),
-                  });
-                  return { continue: true };
-                }) as HookCallback,
-              ],
-            },
-          ],
-          // Without this, errored / interrupted / permission-denied tools never produce
-          // a paired tool_result chunk and the corresponding UI card spins forever.
-          // SDK type: PostToolUseFailureHookInput { tool_name, tool_use_id, error, is_interrupt? }
-          PostToolUseFailure: [
-            ...((requestOptions?.hooks?.PostToolUseFailure ?? []) as HookCallbackMatcher[]),
-            {
-              hooks: [
-                (async (input: Record<string, unknown>): Promise<{ continue: true }> => {
-                  // Always return { continue: true } even on internal errors so a
-                  // malformed SDK payload can never crash the hook dispatch silently.
-                  try {
-                    const toolName = (input as { tool_name?: string }).tool_name ?? 'unknown';
-                    const toolUseId = (input as { tool_use_id?: string }).tool_use_id;
-                    const rawError = (input as { error?: string }).error;
-                    if (rawError === undefined) {
-                      getLog().debug({ input }, 'claude.post_tool_use_failure_no_error_field');
-                    }
-                    const errorText = rawError ?? 'tool failed';
-                    const isInterrupt = (input as { is_interrupt?: boolean }).is_interrupt === true;
-                    const prefix = isInterrupt ? '⚠️ Interrupted' : '❌ Error';
-                    toolResultQueue.push({
-                      toolName,
-                      toolOutput: `${prefix}: ${errorText}`,
-                      ...(toolUseId !== undefined ? { toolCallId: toolUseId } : {}),
-                    });
-                  } catch (e) {
-                    getLog().error({ err: e, input }, 'claude.post_tool_use_failure_hook_error');
-                  }
-                  return { continue: true };
-                }) as HookCallback,
-              ],
-            },
-          ],
-        },
-        stderr: (data: string) => {
-          const output = data.trim();
-          if (!output) return;
-
-          // Always capture stderr for diagnostics — previous filtering discarded
-          // useful SDK startup output, leaving stderrContext empty on crashes.
-          stderrLines.push(output);
-
-          const isError =
-            output.toLowerCase().includes('error') ||
-            output.toLowerCase().includes('fatal') ||
-            output.toLowerCase().includes('failed') ||
-            output.toLowerCase().includes('exception') ||
-            output.includes('at ') ||
-            output.includes('Error:');
-
-          const isInfoMessage =
-            output.includes('Spawning Claude Code') ||
-            output.includes('--output-format') ||
-            output.includes('--permission-mode');
-
-          if (isError && !isInfoMessage) {
-            getLog().error({ stderr: output }, 'subprocess_error');
-          }
-        },
-      };
-
-      if (resumeSessionId) {
-        options.resume = resumeSessionId;
-        getLog().debug(
-          { sessionId: resumeSessionId, forkSession: requestOptions?.forkSession },
-          'resuming_session'
-        );
-      } else {
-        getLog().debug({ cwd, attempt }, 'starting_new_session');
-      }
-
-      try {
-        for await (const msg of query({ prompt, options })) {
-          // Drain tool results captured by PostToolUse hook before processing the next message
-          while (toolResultQueue.length > 0) {
-            const tr = toolResultQueue.shift();
-            if (tr) {
-              yield {
-                type: 'tool_result',
-                toolName: tr.toolName,
-                toolOutput: tr.toolOutput,
-                ...(tr.toolCallId !== undefined ? { toolCallId: tr.toolCallId } : {}),
-              };
-            }
-          }
-
-          if (msg.type === 'assistant') {
-            const message = msg as { message: { content: ContentBlock[] } };
-            const content = message.message.content;
-
-            for (const block of content) {
-              if (block.type === 'text' && block.text) {
-                yield { type: 'assistant', content: block.text };
-              } else if (block.type === 'tool_use' && block.name) {
-                yield {
-                  type: 'tool',
-                  toolName: block.name,
-                  toolInput: block.input ?? {},
-                  ...(block.id !== undefined ? { toolCallId: block.id } : {}),
-                };
-              }
-            }
-          } else if (msg.type === 'system') {
-            // Check MCP server connection status from system/init
-            const sysMsg = msg as {
-              subtype?: string;
-              mcp_servers?: { name: string; status: string }[];
-            };
-            if (sysMsg.subtype === 'init' && sysMsg.mcp_servers) {
-              const failed = sysMsg.mcp_servers.filter(s => s.status !== 'connected');
-              if (failed.length > 0) {
-                const names = failed.map(s => `${s.name} (${s.status})`).join(', ');
-                yield { type: 'system', content: `MCP server connection failed: ${names}` };
-              }
-            } else {
-              getLog().debug({ subtype: sysMsg.subtype }, 'claude.system_message_unhandled');
-            }
-          } else if (msg.type === 'rate_limit_event') {
-            const rateLimitMsg = msg as { rate_limit_info?: Record<string, unknown> };
-            getLog().warn(
-              { rateLimitInfo: rateLimitMsg.rate_limit_info },
-              'claude.rate_limit_event'
-            );
-            yield { type: 'rate_limit', rateLimitInfo: rateLimitMsg.rate_limit_info ?? {} };
-          } else if (msg.type === 'result') {
-            const resultMsg = msg as {
-              session_id?: string;
-              is_error?: boolean;
-              subtype?: string;
-              usage?: { input_tokens?: number; output_tokens?: number; total_tokens?: number };
-              structured_output?: unknown;
-              total_cost_usd?: number;
-              stop_reason?: string | null;
-              num_turns?: number;
-              model_usage?: Record<
-                string,
-                {
-                  input_tokens: number;
-                  output_tokens: number;
-                  cache_read_input_tokens?: number;
-                  cache_creation_input_tokens?: number;
-                }
-              >;
-            };
-            const tokens = normalizeClaudeUsage(resultMsg.usage);
-            yield {
-              type: 'result',
-              sessionId: resultMsg.session_id,
-              ...(tokens ? { tokens } : {}),
-              ...(resultMsg.structured_output !== undefined
-                ? { structuredOutput: resultMsg.structured_output }
-                : {}),
-              ...(resultMsg.is_error ? { isError: true, errorSubtype: resultMsg.subtype } : {}),
-              ...(resultMsg.total_cost_usd !== undefined ? { cost: resultMsg.total_cost_usd } : {}),
-              ...(resultMsg.stop_reason != null ? { stopReason: resultMsg.stop_reason } : {}),
-              ...(resultMsg.num_turns !== undefined ? { numTurns: resultMsg.num_turns } : {}),
-              ...(resultMsg.model_usage
-                ? { modelUsage: resultMsg.model_usage as Record<string, unknown> }
-                : {}),
-            };
-          }
-        }
-        // Drain any remaining tool results from the hook queue.
-        // Must mirror the in-loop drain — PostToolUseFailure results commonly land
-        // here (they fire just before the SDK's terminal `result` message), so
-        // dropping toolCallId here would defeat the stable-pairing fix.
-        while (toolResultQueue.length > 0) {
-          const tr = toolResultQueue.shift();
-          if (tr) {
-            yield {
-              type: 'tool_result',
-              toolName: tr.toolName,
-              toolOutput: tr.toolOutput,
-              ...(tr.toolCallId !== undefined ? { toolCallId: tr.toolCallId } : {}),
-            };
-          }
-        }
-        return; // Success - exit retry loop
-      } catch (error) {
-        const err = error as Error;
-
-        // Don't retry aborted queries
-        if (controller.signal.aborted) {
-          throw new Error('Query aborted');
-        }
-
-        const stderrContext = stderrLines.join('\n');
-        const errorClass = classifySubprocessError(err.message, stderrContext);
-
-        getLog().error(
-          { err, stderrContext, errorClass, attempt, maxRetries: MAX_SUBPROCESS_RETRIES },
-          'query_error'
-        );
-
-        // Don't retry auth errors - they won't resolve
-        if (errorClass === 'auth') {
-          const enrichedError = new Error(
-            `Claude Code auth error: ${err.message}${stderrContext ? ` (${stderrContext})` : ''}`
-          );
-          enrichedError.cause = error;
-          throw enrichedError;
-        }
-
-        // Retry transient failures (rate limit, crash)
-        if (
-          attempt < MAX_SUBPROCESS_RETRIES &&
-          (errorClass === 'rate_limit' || errorClass === 'crash')
-        ) {
-          const delayMs = this.retryBaseDelayMs * Math.pow(2, attempt);
-          getLog().info({ attempt, delayMs, errorClass }, 'retrying_subprocess');
-          await new Promise(resolve => setTimeout(resolve, delayMs));
-          lastError = err;
-          continue;
-        }
-
-        // Final failure - enrich and throw
-        const enrichedMessage = stderrContext
-          ? `Claude Code ${errorClass}: ${err.message} (stderr: ${stderrContext})`
-          : `Claude Code ${errorClass}: ${err.message}`;
-        const enrichedError = new Error(enrichedMessage);
-        enrichedError.cause = error;
-        throw enrichedError;
-      }
-    }
-
-    // Should not reach here, but handle defensively
-    throw lastError ?? new Error('Claude Code query failed after retries');
-  }
-
-  /**
-   * Get the assistant type identifier
-   */
-  getType(): string {
-    return 'claude';
-  }
-}

packages/core/src/clients/codex.ts

@@ -1,554 +0,0 @@
-/**
- * Codex SDK wrapper
- * Provides async generator interface for streaming Codex responses
- *
- * With Bun runtime, we can directly import ESM packages without the
- * dynamic import workaround that was needed for CommonJS/Node.js.
- */
-import {
-  Codex,
-  type ThreadOptions,
-  type TurnOptions,
-  type TurnCompletedEvent,
-} from '@openai/codex-sdk';
-import {
-  type AssistantRequestOptions,
-  type IAssistantClient,
-  type MessageChunk,
-  type TokenUsage,
-} from '../types';
-import { createLogger } from '@archon/paths';
-import { scanPathForSensitiveKeys, EnvLeakError } from '../utils/env-leak-scanner';
-import * as codebaseDb from '../db/codebases';
-import { loadConfig } from '../config/config-loader';
-
-/** Lazy-initialized logger (deferred so test mocks can intercept createLogger) */
-let cachedLog: ReturnType<typeof createLogger> | undefined;
-function getLog(): ReturnType<typeof createLogger> {
-  if (!cachedLog) cachedLog = createLogger('client.codex');
-  return cachedLog;
-}
-
-// Singleton Codex instance
-let codexInstance: Codex | null = null;
-
-/**
- * Get or create Codex SDK instance
- * Synchronous now that we have direct ESM import
- */
-function getCodex(): Codex {
-  if (!codexInstance) {
-    codexInstance = new Codex();
-  }
-  return codexInstance;
-}
-
-/**
- * Build thread options for Codex SDK
- * Extracted to avoid duplication across thread creation paths
- */
-function buildThreadOptions(cwd: string, options?: AssistantRequestOptions): ThreadOptions {
-  return {
-    workingDirectory: cwd,
-    skipGitRepoCheck: true,
-    sandboxMode: 'danger-full-access', // Full filesystem access (needed for git worktree operations)
-    networkAccessEnabled: true, // Allow network calls (GitHub CLI, HTTP requests)
-    approvalPolicy: 'never', // Auto-approve all operations without user confirmation
-    model: options?.model,
-    modelReasoningEffort: options?.modelReasoningEffort,
-    webSearchMode: options?.webSearchMode,
-    additionalDirectories: options?.additionalDirectories,
-  };
-}
-
-const CODEX_MODEL_FALLBACKS: Record<string, string> = {
-  'gpt-5.3-codex': 'gpt-5.2-codex',
-};
-
-function isModelAccessError(errorMessage: string): boolean {
-  const m = errorMessage.toLowerCase();
-  const hasModel = m.includes('model');
-  const hasAvailabilitySignal =
-    m.includes('not available') || m.includes('not found') || m.includes('access denied');
-  return hasModel && hasAvailabilitySignal;
-}
-
-function buildModelAccessMessage(model?: string): string {
-  const normalizedModel = model?.trim();
-  const selectedModel = normalizedModel || 'the configured model';
-  const suggested = normalizedModel ? CODEX_MODEL_FALLBACKS[normalizedModel] : undefined;
-
-  const fixLine = suggested
-    ? `To fix: update your model in ~/.archon/config.yaml:\n  assistants:\n    codex:\n      model: ${suggested}`
-    : 'To fix: update your model in ~/.archon/config.yaml to one your account can access.';
-
-  const workflowLine = suggested
-    ? `Or set it per-workflow with \`model: ${suggested}\` in workflow YAML.`
-    : 'Or set it per-workflow with a valid `model:` in workflow YAML.';
-
-  return `❌ Model "${selectedModel}" is not available for your account.\n\n${fixLine}\n\n${workflowLine}`;
-}
-
-/** Max retries for transient failures (3 = 4 total attempts).
- *  Mirrors ClaudeClient retry logic — Codex process crashes are similarly intermittent. */
-const MAX_SUBPROCESS_RETRIES = 3;
-
-/** Delay between retries in milliseconds */
-const RETRY_BASE_DELAY_MS = 2000;
-
-/** Patterns indicating rate limiting in error messages */
-const RATE_LIMIT_PATTERNS = ['rate limit', 'too many requests', '429', 'overloaded'];
-
-/** Patterns indicating auth issues in error messages */
-const AUTH_PATTERNS = [
-  'credit balance',
-  'unauthorized',
-  'authentication',
-  'invalid token',
-  '401',
-  '403',
-];
-
-/** Patterns indicating a transient process crash (worth retrying) */
-const SUBPROCESS_CRASH_PATTERNS = ['exited with code', 'killed', 'signal', 'codex exec'];
-
-function classifyCodexError(
-  errorMessage: string
-): 'rate_limit' | 'auth' | 'crash' | 'model_access' | 'unknown' {
-  if (isModelAccessError(errorMessage)) return 'model_access';
-  const m = errorMessage.toLowerCase();
-  if (RATE_LIMIT_PATTERNS.some(p => m.includes(p))) return 'rate_limit';
-  if (AUTH_PATTERNS.some(p => m.includes(p))) return 'auth';
-  if (SUBPROCESS_CRASH_PATTERNS.some(p => m.includes(p))) return 'crash';
-  return 'unknown';
-}
-
-function extractUsageFromCodexEvent(event: TurnCompletedEvent): TokenUsage {
-  if (!event.usage) {
-    getLog().warn({ eventType: event.type }, 'codex.usage_null_on_turn_completed');
-    return { input: 0, output: 0 };
-  }
-  return {
-    input: event.usage.input_tokens,
-    output: event.usage.output_tokens,
-  };
-}
-
-/**
- * Codex AI assistant client
- * Implements generic IAssistantClient interface
- */
-export class CodexClient implements IAssistantClient {
-  private readonly retryBaseDelayMs: number;
-
-  constructor(options?: { retryBaseDelayMs?: number }) {
-    this.retryBaseDelayMs = options?.retryBaseDelayMs ?? RETRY_BASE_DELAY_MS;
-  }
-
-  /**
-   * Send a query to Codex and stream responses
-   * @param prompt - User message or prompt
-   * @param cwd - Working directory for Codex
-   * @param resumeSessionId - Optional thread ID to resume
-   */
-  async *sendQuery(
-    prompt: string,
-    cwd: string,
-    resumeSessionId?: string,
-    options?: AssistantRequestOptions
-  ): AsyncGenerator<MessageChunk> {
-    // Pre-spawn: check for env key leak if codebase is not explicitly consented.
-    // Use prefix lookup so worktree paths (e.g. .../worktrees/feature-branch) still
-    // match the registered source cwd (e.g. .../source).
-    const codebase =
-      (await codebaseDb.findCodebaseByDefaultCwd(cwd)) ??
-      (await codebaseDb.findCodebaseByPathPrefix(cwd));
-    if (!codebase?.allow_env_keys) {
-      // Fail-closed: a config load failure must NOT silently bypass the gate.
-      let allowTargetRepoKeys = false;
-      try {
-        const merged = await loadConfig(cwd);
-        allowTargetRepoKeys = merged.allowTargetRepoKeys;
-      } catch (configErr) {
-        getLog().warn({ err: configErr, cwd }, 'env_leak_gate.config_load_failed_gate_enforced');
-      }
-      if (!allowTargetRepoKeys) {
-        const report = scanPathForSensitiveKeys(cwd);
-        if (report.findings.length > 0) {
-          throw new EnvLeakError(report, 'spawn-existing');
-        }
-      }
-    }
-
-    const codex = getCodex();
-    const threadOptions = buildThreadOptions(cwd, options);
-
-    // Check if already aborted before starting
-    if (options?.abortSignal?.aborted) {
-      throw new Error('Query aborted');
-    }
-
-    // Track if we fell back from a failed resume (to notify user)
-    let sessionResumeFailed = false;
-
-    // Get or create thread (synchronous operations!)
-    let thread;
-    if (resumeSessionId) {
-      getLog().debug({ sessionId: resumeSessionId }, 'resuming_thread');
-      try {
-        // NOTE: resumeThread is synchronous, not async
-        // IMPORTANT: Must pass options when resuming!
-        thread = codex.resumeThread(resumeSessionId, threadOptions);
-      } catch (error) {
-        getLog().error({ err: error, sessionId: resumeSessionId }, 'resume_thread_failed');
-        // Fall back to creating new thread
-        try {
-          thread = codex.startThread(threadOptions);
-        } catch (startError) {
-          const err = startError as Error;
-          if (isModelAccessError(err.message)) {
-            throw new Error(buildModelAccessMessage(options?.model));
-          }
-          throw new Error(`Codex query failed: ${err.message}`);
-        }
-        sessionResumeFailed = true;
-      }
-    } else {
-      getLog().debug({ cwd }, 'starting_new_thread');
-      // NOTE: startThread is synchronous, not async
-      try {
-        thread = codex.startThread(threadOptions);
-      } catch (error) {
-        const err = error as Error;
-        if (isModelAccessError(err.message)) {
-          throw new Error(buildModelAccessMessage(options?.model));
-        }
-        throw new Error(`Codex query failed: ${err.message}`);
-      }
-    }
-
-    // Notify user if session resume failed (don't silently lose context)
-    if (sessionResumeFailed) {
-      yield {
-        type: 'system',
-        content: '⚠️ Could not resume previous session. Starting fresh conversation.',
-      };
-    }
-
-    let lastTodoListSignature: string | undefined;
-    let lastError: Error | undefined;
-
-    for (let attempt = 0; attempt <= MAX_SUBPROCESS_RETRIES; attempt++) {
-      // Check abort signal before each attempt
-      if (options?.abortSignal?.aborted) {
-        throw new Error('Query aborted');
-      }
-
-      // On retries, create a fresh thread (crashed thread is invalid)
-      if (attempt > 0) {
-        getLog().debug({ cwd, attempt }, 'starting_new_thread');
-        try {
-          thread = codex.startThread(threadOptions);
-        } catch (startError) {
-          const err = startError as Error;
-          if (isModelAccessError(err.message)) {
-            throw new Error(buildModelAccessMessage(options?.model));
-          }
-          throw new Error(`Codex query failed: ${err.message}`);
-        }
-      }
-
-      try {
-        // Build per-turn options (structured output schema, abort signal)
-        const turnOptions: TurnOptions = {};
-        if (options?.outputFormat) {
-          turnOptions.outputSchema = options.outputFormat.schema;
-        }
-        if (options?.abortSignal) {
-          turnOptions.signal = options.abortSignal;
-        }
-
-        // Run streamed query (this IS async)
-        const result = await thread.runStreamed(prompt, turnOptions);
-
-        // Process streaming events
-        for await (const event of result.events) {
-          // Check abort signal between events
-          if (options?.abortSignal?.aborted) {
-            getLog().info('query_aborted_between_events');
-            break;
-          }
-
-          // Log progress for item.started (visibility fix for Codex appearing to hang)
-          if (event.type === 'item.started') {
-            const item = event.item;
-            getLog().debug(
-              { eventType: event.type, itemType: item.type, itemId: item.id },
-              'item_started'
-            );
-          }
-
-          // Handle error events
-          if (event.type === 'error') {
-            getLog().error({ message: event.message }, 'stream_error');
-            // Don't send MCP timeout errors (they're optional)
-            if (!event.message.includes('MCP client')) {
-              yield { type: 'system', content: `⚠️ ${event.message}` };
-            }
-            continue;
-          }
-
-          // Handle turn failed events
-          if (event.type === 'turn.failed') {
-            const errorObj = event.error as { message?: string } | undefined;
-            const errorMessage = errorObj?.message ?? 'Unknown error';
-            getLog().error({ errorMessage }, 'turn_failed');
-            yield {
-              type: 'system',
-              content: `❌ Turn failed: ${errorMessage}`,
-            };
-            break;
-          }
-
-          // Handle item.completed events - map to MessageChunk types
-          if (event.type === 'item.completed') {
-            const item = event.item;
-
-            // Log progress with context for debugging
-            const logContext: Record<string, unknown> = {
-              eventType: event.type,
-              itemType: item.type,
-              itemId: item.id,
-            };
-            if (item.type === 'command_execution' && item.command) {
-              logContext.command = item.command;
-            }
-            getLog().debug(logContext, 'item_completed');
-
-            switch (item.type) {
-              case 'agent_message':
-                // Agent text response
-                if (item.text) {
-                  yield { type: 'assistant', content: item.text };
-                }
-                break;
-
-              case 'command_execution':
-                // Tool/command execution. The Codex SDK only emits item.completed
-                // once the command has fully run, so we emit the start + result
-                // back-to-back to close the UI's tool card immediately. Without
-                // the paired tool_result, the card spins forever until lock release.
-                if (item.command) {
-                  yield { type: 'tool', toolName: item.command };
-                  const exitSuffix =
-                    item.exit_code != null && item.exit_code !== 0
-                      ? `\n[exit code: ${item.exit_code}]`
-                      : '';
-                  yield {
-                    type: 'tool_result',
-                    toolName: item.command,
-                    toolOutput: (item.aggregated_output ?? '') + exitSuffix,
-                  };
-                } else {
-                  getLog().warn({ itemId: item.id }, 'command_execution_missing_command');
-                }
-                break;
-
-              case 'reasoning':
-                // Agent reasoning/thinking
-                if (item.text) {
-                  yield { type: 'thinking', content: item.text };
-                }
-                break;
-
-              case 'web_search':
-                if (item.query) {
-                  const searchToolName = `🔍 Searching: ${item.query}`;
-                  yield { type: 'tool', toolName: searchToolName };
-                  // Web search items only fire on completion, so close the card immediately.
-                  yield { type: 'tool_result', toolName: searchToolName, toolOutput: '' };
-                } else {
-                  getLog().debug({ itemId: item.id }, 'web_search_missing_query');
-                }
-                break;
-
-              case 'todo_list':
-                if (Array.isArray(item.items) && item.items.length > 0) {
-                  const normalizedItems = item.items.map(t => ({
-                    text: typeof t.text === 'string' ? t.text : '(unnamed task)',
-                    completed: t.completed ?? false,
-                  }));
-                  const signature = JSON.stringify(normalizedItems);
-                  if (signature !== lastTodoListSignature) {
-                    lastTodoListSignature = signature;
-                    const taskList = normalizedItems
-                      .map(t => `${t.completed ? '✅' : '⬜'} ${t.text}`)
-                      .join('\n');
-                    yield { type: 'system', content: `📋 Tasks:\n${taskList}` };
-                  }
-                } else {
-                  getLog().debug({ itemId: item.id }, 'todo_list_empty_or_invalid');
-                }
-                break;
-
-              case 'file_change': {
-                const statusIcon = item.status === 'failed' ? '❌' : '✅';
-                const rawError = 'error' in item ? (item as { error?: unknown }).error : undefined;
-                const fileErrorMessage =
-                  typeof rawError === 'string'
-                    ? rawError
-                    : typeof rawError === 'object' && rawError !== null && 'message' in rawError
-                      ? String((rawError as { message: unknown }).message)
-                      : undefined;
-
-                if (Array.isArray(item.changes) && item.changes.length > 0) {
-                  const changeList = item.changes
-                    .map(c => {
-                      const icon = c.kind === 'add' ? '➕' : c.kind === 'delete' ? '➖' : '📝';
-                      return `${icon} ${c.path ?? '(unknown file)'}`;
-                    })
-                    .join('\n');
-                  const errorSuffix =
-                    item.status === 'failed' && fileErrorMessage ? `\n${fileErrorMessage}` : '';
-                  yield {
-                    type: 'system',
-                    content: `${statusIcon} File changes:\n${changeList}${errorSuffix}`,
-                  };
-                } else if (item.status === 'failed') {
-                  getLog().warn(
-                    { itemId: item.id, status: item.status },
-                    'file_change_failed_no_changes'
-                  );
-                  const failMsg = fileErrorMessage
-                    ? `❌ File change failed: ${fileErrorMessage}`
-                    : '❌ File change failed';
-                  yield { type: 'system', content: failMsg };
-                } else {
-                  getLog().debug(
-                    { itemId: item.id, status: item.status },
-                    'file_change_no_changes'
-                  );
-                }
-                break;
-              }
-
-              case 'mcp_tool_call': {
-                const toolInfo =
-                  item.server && item.tool
-                    ? `${item.server}/${item.tool}`
-                    : (item.tool ?? item.server ?? 'MCP tool');
-                const mcpToolName = `🔌 MCP: ${toolInfo}`;
-
-                // Always emit start+result so the UI card closes. item.completed
-                // fires once the call is final (completed or failed).
-                yield { type: 'tool', toolName: mcpToolName };
-
-                if (item.status === 'failed') {
-                  getLog().warn(
-                    { server: item.server, tool: item.tool, error: item.error, itemId: item.id },
-                    'mcp_tool_call_failed'
-                  );
-                  const errMsg = item.error?.message
-                    ? `❌ Error: ${item.error.message}`
-                    : '❌ Error: MCP tool failed';
-                  yield { type: 'tool_result', toolName: mcpToolName, toolOutput: errMsg };
-                } else {
-                  // status === 'completed' (or 'in_progress', which shouldn't reach
-                  // item.completed but is closed defensively).
-                  let toolOutput = '';
-                  if (item.result?.content) {
-                    if (Array.isArray(item.result.content)) {
-                      toolOutput = JSON.stringify(item.result.content);
-                    } else {
-                      getLog().warn(
-                        {
-                          itemId: item.id,
-                          server: item.server,
-                          tool: item.tool,
-                          resultType: typeof item.result.content,
-                        },
-                        'mcp_tool_call_unexpected_result_shape'
-                      );
-                    }
-                  }
-                  yield { type: 'tool_result', toolName: mcpToolName, toolOutput };
-                }
-                break;
-              }
-
-              // Other item types are ignored (like file edits, etc.)
-            }
-          }
-
-          // Handle turn.completed event
-          if (event.type === 'turn.completed') {
-            getLog().debug('turn_completed');
-            // Yield result with thread ID for persistence
-            const usage = extractUsageFromCodexEvent(event);
-            yield {
-              type: 'result',
-              sessionId: thread.id ?? undefined,
-              tokens: usage,
-            };
-            // CRITICAL: Break out of event loop - turn is complete!
-            // Without this, the loop waits for stream to end (causes 90s timeout)
-            break;
-          }
-        }
-        return; // Success - exit retry loop
-      } catch (error) {
-        const err = error as Error;
-
-        // Don't retry aborted queries
-        if (options?.abortSignal?.aborted) {
-          throw new Error('Query aborted');
-        }
-
-        const errorClass = classifyCodexError(err.message);
-        getLog().error(
-          { err, errorClass, attempt, maxRetries: MAX_SUBPROCESS_RETRIES },
-          'query_error'
-        );
-
-        // Model access errors are never retryable
-        if (errorClass === 'model_access') {
-          throw new Error(buildModelAccessMessage(options?.model));
-        }
-
-        // Auth errors won't resolve on retry
-        if (errorClass === 'auth') {
-          const enrichedError = new Error(`Codex auth error: ${err.message}`);
-          enrichedError.cause = error;
-          throw enrichedError;
-        }
-
-        // Retry transient failures (rate limit, crash)
-        if (
-          attempt < MAX_SUBPROCESS_RETRIES &&
-          (errorClass === 'rate_limit' || errorClass === 'crash')
-        ) {
-          const delayMs = this.retryBaseDelayMs * Math.pow(2, attempt);
-          getLog().info({ attempt, delayMs, errorClass }, 'retrying_query');
-          await new Promise(resolve => setTimeout(resolve, delayMs));
-          lastError = err;
-          continue;
-        }
-
-        // Final failure - enrich and throw
-        const enrichedError = new Error(`Codex ${errorClass}: ${err.message}`);
-        enrichedError.cause = error;
-        throw enrichedError;
-      }
-    }
-
-    // Should not reach here, but handle defensively
-    throw lastError ?? new Error('Codex query failed after retries');
-  }
-
-  /**
-   * Get the assistant type identifier
-   */
-  getType(): string {
-    return 'codex';
-  }
-}

packages/core/src/clients/factory.test.ts

@@ -1,48 +0,0 @@
-import { describe, test, expect } from 'bun:test';
-import { getAssistantClient } from './factory';
-
-describe('factory', () => {
-  describe('getAssistantClient', () => {
-    test('returns ClaudeClient for claude type', () => {
-      const client = getAssistantClient('claude');
-
-      expect(client).toBeDefined();
-      expect(client.getType()).toBe('claude');
-      expect(typeof client.sendQuery).toBe('function');
-    });
-
-    test('returns CodexClient for codex type', () => {
-      const client = getAssistantClient('codex');
-
-      expect(client).toBeDefined();
-      expect(client.getType()).toBe('codex');
-      expect(typeof client.sendQuery).toBe('function');
-    });
-
-    test('throws error for unknown type', () => {
-      expect(() => getAssistantClient('unknown')).toThrow(
-        "Unknown assistant type: unknown. Supported types: 'claude', 'codex'"
-      );
-    });
-
-    test('throws error for empty string', () => {
-      expect(() => getAssistantClient('')).toThrow(
-        "Unknown assistant type: . Supported types: 'claude', 'codex'"
-      );
-    });
-
-    test('is case sensitive - Claude throws', () => {
-      expect(() => getAssistantClient('Claude')).toThrow(
-        "Unknown assistant type: Claude. Supported types: 'claude', 'codex'"
-      );
-    });
-
-    test('each call returns new instance', () => {
-      const client1 = getAssistantClient('claude');
-      const client2 = getAssistantClient('claude');
-
-      // Each call should return a new instance
-      expect(client1).not.toBe(client2);
-    });
-  });
-});

packages/core/src/clients/factory.ts

@@ -1,37 +0,0 @@
-/**
- * AI Assistant Client Factory
- *
- * Dynamically instantiates the appropriate AI assistant client based on type string.
- * Supports Claude and Codex assistants.
- */
-import type { IAssistantClient } from '../types';
-import { ClaudeClient } from './claude';
-import { CodexClient } from './codex';
-import { createLogger } from '@archon/paths';
-
-/** Lazy-initialized logger (deferred so test mocks can intercept createLogger) */
-let cachedLog: ReturnType<typeof createLogger> | undefined;
-function getLog(): ReturnType<typeof createLogger> {
-  if (!cachedLog) cachedLog = createLogger('client.factory');
-  return cachedLog;
-}
-
-/**
- * Get the appropriate AI assistant client based on type
- *
- * @param type - Assistant type identifier ('claude' or 'codex')
- * @returns Instantiated assistant client
- * @throws Error if assistant type is unknown
- */
-export function getAssistantClient(type: string): IAssistantClient {
-  switch (type) {
-    case 'claude':
-      getLog().debug({ provider: 'claude' }, 'client_selected');
-      return new ClaudeClient();
-    case 'codex':
-      getLog().debug({ provider: 'codex' }, 'client_selected');
-      return new CodexClient();
-    default:
-      throw new Error(`Unknown assistant type: ${type}. Supported types: 'claude', 'codex'`);
-  }
-}

packages/core/src/clients/index.ts

@@ -1,16 +0,0 @@
-/**
- * AI Assistant Clients
- *
- * Prefer importing from '@archon/core' for most use cases:
- *   import { ClaudeClient, getAssistantClient } from '@archon/core';
- *
- * Use this submodule path when you only need client-specific code:
- *   import { ClaudeClient } from '@archon/core/clients';
- */
-
-export { ClaudeClient } from './claude';
-export { CodexClient } from './codex';
-export { getAssistantClient } from './factory';
-
-// Re-export types for consumers importing from this submodule directly
-export type { IAssistantClient, MessageChunk } from '../types';

packages/core/src/config/config-loader.test.ts

@@ -224,7 +224,11 @@ concurrency:
       const config = await loadConfig();
 
       expect(config.assistant).toBe('claude');
-      expect(config.assistants).toEqual({ claude: {}, codex: {} });
+      // Built-ins always present; community providers (like `pi`) are
+      // seeded dynamically from the registry — check the built-ins
+      // explicitly rather than asserting an exhaustive shape.
+      expect(config.assistants.claude).toEqual({});
+      expect(config.assistants.codex).toEqual({});
       expect(config.streaming.telegram).toBe('stream');
       expect(config.concurrency.maxConversations).toBe(10);
     });
@@ -245,6 +249,31 @@ streaming:
       expect(config.streaming.telegram).toBe('batch');
     });
 
+    test('throws on unknown DEFAULT_AI_ASSISTANT env var', async () => {
+      mockReadConfigFile.mockResolvedValue('');
+      process.env.DEFAULT_AI_ASSISTANT = 'nonexistent-provider';
+
+      await expect(loadConfig()).rejects.toThrow(/not a registered provider/);
+    });
+
+    test('throws on unknown defaultAssistant in global config', async () => {
+      mockReadConfigFile.mockResolvedValue('defaultAssistant: nonexistent-provider');
+
+      await expect(loadConfig()).rejects.toThrow(/not a registered provider/);
+    });
+
+    test('throws on unknown assistant in repo config', async () => {
+      mockReadConfigFile.mockImplementation(async (path: string) => {
+        const normalized = path.replace(/\\/g, '/');
+        if (normalized.includes('/tmp/test-repo/.archon/config.yaml')) {
+          return 'assistant: nonexistent-provider';
+        }
+        return '';
+      });
+
+      await expect(loadConfig('/tmp/test-repo')).rejects.toThrow(/not a registered provider/);
+    });
+
     test('repo config overrides global config', async () => {
       // Helper to check path in cross-platform way (handles both / and \ separators)
       const pathMatches = (path: string, pattern: string): boolean => {

packages/core/src/config/config-loader.ts

@@ -28,8 +28,99 @@ export async function writeConfigFile(
 ): Promise<void> {
   await writeFile(path, content, { encoding: 'utf-8', ...options });
 }
-import type { GlobalConfig, RepoConfig, MergedConfig, SafeConfig } from './config-types';
+import type {
+  GlobalConfig,
+  RepoConfig,
+  MergedConfig,
+  SafeConfig,
+  AssistantDefaults,
+  AssistantDefaultsConfig,
+} from './config-types';
 import { createLogger } from '@archon/paths';
+import {
+  isRegisteredProvider,
+  getRegisteredProviders,
+  registerBuiltinProviders,
+  registerCommunityProviders,
+} from '@archon/providers';
+
+/**
+ * Pure read of registered provider IDs. Registration is guaranteed by
+ * `loadConfig()`'s bootstrap call before any consumer can observe the
+ * registry, so this helper must NOT trigger side-effecting registration
+ * itself — that hid the ordering coupling and surprised readers.
+ */
+function getRegisteredProviderNames(): string[] {
+  return getRegisteredProviders().map(p => p.id);
+}
+
+function mergeAssistantDefaults(
+  base: AssistantDefaults,
+  overrides?: AssistantDefaultsConfig
+): AssistantDefaults {
+  // Deep-copy every provider slot present in base. No per-provider listing —
+  // adding a new community provider must not require editing this function.
+  const merged: AssistantDefaults = { ...base };
+  for (const [providerId, providerDefaults] of Object.entries(base)) {
+    if (providerDefaults && typeof providerDefaults === 'object') {
+      merged[providerId] = { ...providerDefaults };
+    }
+  }
+
+  if (!overrides) return merged;
+
+  for (const [providerId, providerDefaults] of Object.entries(overrides)) {
+    if (!providerDefaults || typeof providerDefaults !== 'object') continue;
+    merged[providerId] = {
+      ...(merged[providerId] ?? {}),
+      ...providerDefaults,
+    };
+  }
+
+  return merged;
+}
+
+/**
+ * Per-provider allowlist of fields safe to expose to web clients.
+ *
+ * **Allowlist (not denylist) by design.** Any field not listed here is
+ * dropped on its way out. New sensitive fields on a provider default
+ * config (binary paths, credentials, absolute filesystem paths, etc.)
+ * are hidden by default — you have to opt in to expose them.
+ *
+ * Unknown provider IDs (community providers not listed below) fall back
+ * to the generic empty allowlist: the web UI sees the provider exists,
+ * but none of its defaults. Providers whose defaults are safe to surface
+ * register their fields here.
+ */
+const SAFE_ASSISTANT_FIELDS: Record<string, readonly string[]> = {
+  claude: ['model'],
+  codex: ['model', 'modelReasoningEffort', 'webSearchMode'],
+  // community providers — list each field we're confident is safe to
+  // show in the web UI. Unknown providers fall through with no fields.
+  pi: ['model'],
+};
+
+function toSafeAssistantDefaults(assistants: AssistantDefaults): SafeConfig['assistants'] {
+  const safeAssistants: SafeConfig['assistants'] = {};
+
+  for (const [providerId, providerDefaults] of Object.entries(assistants)) {
+    if (!providerDefaults || typeof providerDefaults !== 'object') continue;
+
+    const allowed = SAFE_ASSISTANT_FIELDS[providerId] ?? [];
+    const safeDefaults: Record<string, unknown> = {};
+    for (const field of allowed) {
+      const value = (providerDefaults as Record<string, unknown>)[field];
+      if (value !== undefined) {
+        safeDefaults[field] = value;
+      }
+    }
+
+    safeAssistants[providerId] = safeDefaults;
+  }
+
+  return safeAssistants;
+}
 
 /** Lazy-initialized logger (deferred so test mocks can intercept createLogger) */
 let cachedLog: ReturnType<typeof createLogger> | undefined;
@@ -38,24 +129,6 @@ function getLog(): ReturnType<typeof createLogger> {
   return cachedLog;
 }
 
-/**
- * Tracks which env-leak-gate-disabled sources have already warned in this
- * process. `loadConfig()` is called once per pre-spawn check (per workflow
- * step), so without this guard the warn would flood logs and break alert
- * rate-limiting downstream.
- */
-const envLeakGateDisabledWarnedSources = new Set<'global_config' | 'repo_config'>();
-function warnEnvLeakGateDisabledOnce(source: 'global_config' | 'repo_config'): void {
-  if (envLeakGateDisabledWarnedSources.has(source)) return;
-  envLeakGateDisabledWarnedSources.add(source);
-  getLog().warn({ source }, 'env_leak_gate_disabled');
-}
-
-// Test-only: reset the warn-once state so unit tests can re-trigger the log.
-export function resetEnvLeakGateWarnedSourcesForTests(): void {
-  envLeakGateDisabledWarnedSources.clear();
-}
-
 /**
  * Parse YAML using Bun's native YAML parser
  */
@@ -75,7 +148,7 @@ const DEFAULT_CONFIG_CONTENT = `# Archon Global Configuration
 # Bot display name (shown in messages)
 # botName: Archon
 
-# Default AI assistant (claude or codex)
+# Default AI assistant (must match a registered provider, e.g. claude, codex)
 # defaultAssistant: claude
 
 # Assistant defaults
@@ -188,13 +261,24 @@ export async function loadRepoConfig(repoPath: string): Promise<RepoConfig> {
  * Get default configuration
  */
 function getDefaults(): MergedConfig {
+  // Seed one empty entry per registered provider — built-in OR community.
+  // No per-provider listing here: adding a new provider must not require
+  // editing this function. `registerBuiltinProviders()` + any community
+  // registrations run at process bootstrap (see `packages/providers/src/
+  // registry.ts#registerCommunityProviders`), so by the time this runs the
+  // registry is populated.
+  const providers = getRegisteredProviders();
+  const registeredAssistants: AssistantDefaults = { claude: {}, codex: {} };
+  for (const provider of providers) {
+    if (!(provider.id in registeredAssistants)) {
+      registeredAssistants[provider.id] = {};
+    }
+  }
+
   return {
     botName: 'Archon',
-    assistant: 'claude',
-    assistants: {
-      claude: {},
-      codex: {},
-    },
+    assistant: providers.find(p => p.builtIn)?.id ?? 'claude',
+    assistants: registeredAssistants,
     streaming: {
       telegram: 'stream',
       discord: 'batch',
@@ -216,7 +300,6 @@ function getDefaults(): MergedConfig {
       loadDefaultCommands: true,
       loadDefaultWorkflows: true,
     },
-    allowTargetRepoKeys: false,
   };
 }
 
@@ -230,10 +313,17 @@ function applyEnvOverrides(config: MergedConfig): MergedConfig {
     config.botName = envBotName;
   }
 
-  // Assistant override
+  // Assistant override — validate against registry, error on unknown provider
   const envAssistant = process.env.DEFAULT_AI_ASSISTANT;
-  if (envAssistant === 'claude' || envAssistant === 'codex') {
-    config.assistant = envAssistant;
+  if (envAssistant && envAssistant.length > 0) {
+    if (isRegisteredProvider(envAssistant)) {
+      config.assistant = envAssistant;
+    } else {
+      throw new Error(
+        `DEFAULT_AI_ASSISTANT='${envAssistant}' is not a registered provider. ` +
+          `Available providers: ${getRegisteredProviderNames().join(', ')}`
+      );
+    }
   }
 
   // Streaming overrides
@@ -274,10 +364,7 @@ function applyEnvOverrides(config: MergedConfig): MergedConfig {
 function mergeGlobalConfig(defaults: MergedConfig, global: GlobalConfig): MergedConfig {
   const result: MergedConfig = {
     ...defaults,
-    assistants: {
-      claude: { ...defaults.assistants.claude },
-      codex: { ...defaults.assistants.codex },
-    },
+    assistants: mergeAssistantDefaults(defaults.assistants),
   };
 
   // Bot name preference
@@ -285,23 +372,19 @@ function mergeGlobalConfig(defaults: MergedConfig, global: GlobalConfig): Merged
     result.botName = global.botName;
   }
 
-  // Assistant preference
+  // Assistant preference — validate against registry
   if (global.defaultAssistant) {
-    result.assistant = global.defaultAssistant;
+    if (isRegisteredProvider(global.defaultAssistant)) {
+      result.assistant = global.defaultAssistant;
+    } else {
+      throw new Error(
+        `defaultAssistant: '${global.defaultAssistant}' in global config (~/.archon/config.yaml) ` +
+          `is not a registered provider. Available: ${getRegisteredProviderNames().join(', ')}`
+      );
+    }
   }
 
-  if (global.assistants?.claude?.model) {
-    result.assistants.claude.model = global.assistants.claude.model;
-  }
-  if (global.assistants?.claude?.settingSources) {
-    result.assistants.claude.settingSources = global.assistants.claude.settingSources;
-  }
-  if (global.assistants?.codex) {
-    result.assistants.codex = {
-      ...result.assistants.codex,
-      ...global.assistants.codex,
-    };
-  }
+  result.assistants = mergeAssistantDefaults(result.assistants, global.assistants);
 
   // Streaming preferences
   if (global.streaming) {
@@ -321,12 +404,6 @@ function mergeGlobalConfig(defaults: MergedConfig, global: GlobalConfig): Merged
     result.concurrency.maxConversations = global.concurrency.maxConversations;
   }
 
-  // Env-leak gate bypass (global)
-  if (global.allow_target_repo_keys === true) {
-    result.allowTargetRepoKeys = true;
-    warnEnvLeakGateDisabledOnce('global_config');
-  }
-
   return result;
 }
 
@@ -336,29 +413,22 @@ function mergeGlobalConfig(defaults: MergedConfig, global: GlobalConfig): Merged
 function mergeRepoConfig(merged: MergedConfig, repo: RepoConfig): MergedConfig {
   const result: MergedConfig = {
     ...merged,
-    assistants: {
-      claude: { ...merged.assistants.claude },
-      codex: { ...merged.assistants.codex },
-    },
+    assistants: mergeAssistantDefaults(merged.assistants),
   };
 
-  // Assistant override (repo-level takes precedence)
+  // Assistant override (repo-level takes precedence) — validate against registry
   if (repo.assistant) {
-    result.assistant = repo.assistant;
+    if (isRegisteredProvider(repo.assistant)) {
+      result.assistant = repo.assistant;
+    } else {
+      throw new Error(
+        `assistant: '${repo.assistant}' in repo config (.archon/config.yaml) ` +
+          `is not a registered provider. Available: ${getRegisteredProviderNames().join(', ')}`
+      );
+    }
   }
 
-  if (repo.assistants?.claude?.model) {
-    result.assistants.claude.model = repo.assistants.claude.model;
-  }
-  if (repo.assistants?.claude?.settingSources) {
-    result.assistants.claude.settingSources = repo.assistants.claude.settingSources;
-  }
-  if (repo.assistants?.codex) {
-    result.assistants.codex = {
-      ...result.assistants.codex,
-      ...repo.assistants.codex,
-    };
-  }
+  result.assistants = mergeAssistantDefaults(result.assistants, repo.assistants);
 
   // Commands config
   if (repo.commands) {
@@ -400,14 +470,6 @@ function mergeRepoConfig(merged: MergedConfig, repo: RepoConfig): MergedConfig {
     result.envVars = { ...result.envVars, ...repo.env };
   }
 
-  // Repo-level env-leak gate override (wins over global)
-  if (repo.allow_target_repo_keys !== undefined) {
-    result.allowTargetRepoKeys = repo.allow_target_repo_keys;
-    if (repo.allow_target_repo_keys) {
-      warnEnvLeakGateDisabledOnce('repo_config');
-    }
-  }
-
   return result;
 }
 
@@ -418,6 +480,9 @@ function mergeRepoConfig(merged: MergedConfig, repo: RepoConfig): MergedConfig {
  * @returns Merged configuration with all overrides applied
  */
 export async function loadConfig(repoPath?: string): Promise<MergedConfig> {
+  registerBuiltinProviders();
+  registerCommunityProviders();
+
   // 1. Start with defaults
   let config = getDefaults();
 
@@ -476,10 +541,10 @@ export async function updateGlobalConfig(updates: Partial<GlobalConfig>): Promis
     if (updates.defaultAssistant !== undefined) merged.defaultAssistant = updates.defaultAssistant;
 
     if (updates.assistants) {
-      merged.assistants = {
-        claude: { ...current.assistants?.claude, ...updates.assistants.claude },
-        codex: { ...current.assistants?.codex, ...updates.assistants.codex },
-      };
+      merged.assistants = mergeAssistantDefaults(
+        mergeAssistantDefaults(getDefaults().assistants, current.assistants),
+        updates.assistants
+      );
     }
 
     if (updates.streaming) {
@@ -520,16 +585,7 @@ export function toSafeConfig(config: MergedConfig): SafeConfig {
   return {
     botName: config.botName,
     assistant: config.assistant,
-    assistants: {
-      claude: {
-        model: config.assistants.claude.model,
-      },
-      codex: {
-        model: config.assistants.codex.model,
-        modelReasoningEffort: config.assistants.codex.modelReasoningEffort,
-        webSearchMode: config.assistants.codex.webSearchMode,
-      },
-    },
+    assistants: toSafeAssistantDefaults(config.assistants),
     streaming: {
       telegram: config.streaming.telegram,
       discord: config.streaming.discord,

packages/core/src/config/config-types.ts

@@ -10,22 +10,54 @@
  * Global configuration (non-secret user preferences)
  * Located at ~/.archon/config.yaml
  */
-import type { ModelReasoningEffort, WebSearchMode } from '../types';
 
-export interface AssistantDefaults {
-  model?: string;
-  modelReasoningEffort?: ModelReasoningEffort;
-  webSearchMode?: WebSearchMode;
-  additionalDirectories?: string[];
-}
+// Provider config defaults — canonical definitions live in @archon/providers/types.
+// Imported and re-exported here so existing consumers don't break.
+import type {
+  ClaudeProviderDefaults,
+  CodexProviderDefaults,
+  PiProviderDefaults,
+  ProviderDefaultsMap,
+} from '@archon/providers/types';
 
-export interface ClaudeAssistantDefaults {
-  model?: string;
-  /** Claude Code settingSources — controls which CLAUDE.md files are loaded.
-   *  @default ['project']
-   *  @see https://github.com/anthropics/claude-agent-sdk */
-  settingSources?: ('project' | 'user')[];
-}
+export type {
+  ClaudeProviderDefaults,
+  CodexProviderDefaults,
+  PiProviderDefaults,
+  ProviderDefaultsMap,
+};
+
+/**
+ * Intersection type: generic `ProviderDefaultsMap` (any string key) with
+ * typed built-in entries.
+ *
+ * The built-in entries exist ONLY to give call sites like
+ * `config.assistants.claude.model` IDE autocomplete without `as` casts.
+ * They do NOT provide parser safety (each provider's `parseXxxConfig`
+ * already takes `Record<string, unknown>` and defends itself).
+ *
+ * Community providers should NOT be added here — they live behind the
+ * generic `[string]` index. Adding a new community provider must not
+ * require a core-package type change; that's the whole point of Phase 2.
+ */
+export type AssistantDefaultsConfig = ProviderDefaultsMap & {
+  claude?: ClaudeProviderDefaults;
+  codex?: CodexProviderDefaults;
+};
+
+/**
+ * Required variant — built-ins are always present after `loadConfig`.
+ *
+ * `getDefaults()` seeds every registered provider (built-in + community)
+ * with `{}`, so community providers appear in the map too — just typed as
+ * `ProviderDefaults` via the generic index rather than a specific shape.
+ * `registerBuiltinProviders()` is called before `loadConfig()` at every
+ * process entrypoint, so claude/codex are guaranteed present.
+ */
+export type AssistantDefaults = ProviderDefaultsMap & {
+  claude: ClaudeProviderDefaults;
+  codex: CodexProviderDefaults;
+};
 
 export interface GlobalConfig {
   /**
@@ -38,15 +70,12 @@ export interface GlobalConfig {
    * Default AI assistant when no codebase-specific preference
    * @default 'claude'
    */
-  defaultAssistant?: 'claude' | 'codex';
+  defaultAssistant?: string;
 
   /**
    * Assistant-specific defaults (model, reasoning effort, etc.)
    */
-  assistants?: {
-    claude?: ClaudeAssistantDefaults;
-    codex?: AssistantDefaults;
-  };
+  assistants?: AssistantDefaultsConfig;
 
   /**
    * Platform streaming preferences (can be overridden per conversation)
@@ -84,20 +113,6 @@ export interface GlobalConfig {
      */
     maxConversations?: number;
   };
-
-  /**
-   * Bypass the env-leak gate globally. When true, Archon will not refuse to
-   * register or spawn subprocesses for codebases whose auto-loaded .env files
-   * contain sensitive keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc).
-   *
-   * WARNING: Weakens the env-leak gate. Keys in the target repo's .env will
-   * be auto-loaded by Bun subprocesses (Claude/Codex) and bypass Archon's
-   * env allowlist. Use only on trusted machines.
-   *
-   * YAML key: `allow_target_repo_keys`
-   * @default false
-   */
-  allow_target_repo_keys?: boolean;
 }
 
 /**
@@ -109,15 +124,12 @@ export interface RepoConfig {
    * AI assistant preference for this repository
    * Overrides global default
    */
-  assistant?: 'claude' | 'codex';
+  assistant?: string;
 
   /**
    * Assistant-specific defaults for this repository
    */
-  assistants?: {
-    claude?: ClaudeAssistantDefaults;
-    codex?: AssistantDefaults;
-  };
+  assistants?: AssistantDefaultsConfig;
 
   /**
    * Commands configuration
@@ -152,6 +164,41 @@ export interface RepoConfig {
      * @example [".env", ".archon", "data/fixtures/"]
      */
     copyFiles?: string[];
+
+    /**
+     * Initialize git submodules in new worktrees.
+     * Runs `git submodule update --init --recursive` after worktree creation
+     * when the repo contains a `.gitmodules` file. Repos without submodules
+     * pay zero cost (the check short-circuits).
+     *
+     * Set to `false` to skip submodule init (e.g., when submodules are not
+     * needed by any workflow or when fetch cost is prohibitive).
+     * @default true
+     */
+    initSubmodules?: boolean;
+
+    /**
+     * Per-project worktree directory (relative to repo root). When set,
+     * worktrees are created at `<repoRoot>/<path>/<branch>` instead of under
+     * `~/.archon/worktrees/` or the workspaces layout.
+     *
+     * Opt-in — co-locates worktrees with the repo so they appear in the IDE
+     * file tree. The user is responsible for adding the directory to their
+     * `.gitignore` (no automatic file mutation).
+     *
+     * Path resolution precedence (highest to lowest):
+     *   1. this `worktree.path` (repo-local)
+     *   2. global `paths.worktrees` (absolute override in `~/.archon/config.yaml`)
+     *   3. auto-detected project-scoped (`~/.archon/workspaces/owner/repo/...`)
+     *   4. default global (`~/.archon/worktrees/`)
+     *
+     * Must be a safe relative path: no leading `/`, no `..` segments. Absolute
+     * or escaping values fail loudly at worktree creation (Fail Fast — no silent
+     * fallback).
+     *
+     * @example '.worktrees'
+     */
+    path?: string;
   };
 
   /**
@@ -172,12 +219,6 @@ export interface RepoConfig {
    */
   env?: Record<string, string>;
 
-  /**
-   * Per-repo override for the env-leak gate bypass. Repo value wins over global.
-   * YAML key: `allow_target_repo_keys`
-   */
-  allow_target_repo_keys?: boolean;
-
   /**
    * Default commands/workflows configuration
    */
@@ -212,11 +253,8 @@ export interface RepoConfig {
  */
 export interface MergedConfig {
   botName: string;
-  assistant: 'claude' | 'codex';
-  assistants: {
-    claude: ClaudeAssistantDefaults;
-    codex: AssistantDefaults;
-  };
+  assistant: string;
+  assistants: AssistantDefaults;
   streaming: {
     telegram: 'stream' | 'batch';
     discord: 'stream' | 'batch';
@@ -260,14 +298,6 @@ export interface MergedConfig {
    * Undefined when no env vars are configured.
    */
   envVars?: Record<string, string>;
-
-  /**
-   * Effective value of the env-leak gate bypass. When true, the env scanner
-   * is skipped during registration and pre-spawn. Repo-level override wins
-   * over global (explicit `false` at repo level re-enables the gate).
-   * @default false
-   */
-  allowTargetRepoKeys: boolean;
 }
 
 /**
@@ -276,11 +306,8 @@ export interface MergedConfig {
  */
 export interface SafeConfig {
   botName: string;
-  assistant: 'claude' | 'codex';
-  assistants: {
-    claude: Pick<ClaudeAssistantDefaults, 'model'>;
-    codex: Pick<AssistantDefaults, 'model' | 'modelReasoningEffort' | 'webSearchMode'>;
-  };
+  assistant: string;
+  assistants: ProviderDefaultsMap;
   streaming: {
     telegram: 'stream' | 'batch';
     discord: 'stream' | 'batch';

packages/core/src/db/adapters/sqlite.test.ts

@@ -135,4 +135,46 @@ describe('SqliteAdapter', () => {
       ).rejects.toThrow('does not support RETURNING clause on UPDATE/DELETE');
     });
   });
+
+  describe('datetime() chronological vs lexical comparison', () => {
+    // Documents the SQLite-specific bug fixed in getActiveWorkflowRunByPath.
+    // `started_at` is TEXT in "YYYY-MM-DD HH:MM:SS" format. Comparing it
+    // directly to an ISO param "YYYY-MM-DDTHH:MM:SS.mmmZ" with `<` is
+    // LEXICAL: char 11 is space (0x20) in the column vs T (0x54) in the
+    // param, so every column value lex-sorts before every ISO param,
+    // making the comparison ALWAYS true regardless of actual time.
+    //
+    // Wrapping both sides in datetime() forces chronological comparison.
+
+    test('lexical comparison gives wrong answer for SQLite stored format vs ISO param', async () => {
+      db = createTestDb();
+      // Column-format value (afternoon) is chronologically AFTER the ISO
+      // param (morning), but lex compares char-11 (space < T) → wrong.
+      const result = await db.query<{ broken: number }>(
+        `SELECT ('2026-04-14 12:00:00' < $1) AS broken`,
+        ['2026-04-14T10:00:00.000Z']
+      );
+      // Expected by chronology: FALSE. Lex says: TRUE.
+      expect(result.rows[0].broken).toBe(1);
+    });
+
+    test('datetime() wrap on both sides gives chronological comparison', async () => {
+      db = createTestDb();
+      const result = await db.query<{ correct: number }>(
+        `SELECT (datetime('2026-04-14 12:00:00') < datetime($1)) AS correct`,
+        ['2026-04-14T10:00:00.000Z']
+      );
+      // 12:00 < 10:00 is FALSE — datetime() comparison agrees with reality.
+      expect(result.rows[0].correct).toBe(0);
+    });
+
+    test('datetime() handles equality across formats', async () => {
+      db = createTestDb();
+      const result = await db.query<{ equal: number }>(
+        `SELECT (datetime('2026-04-14 10:00:00') = datetime($1)) AS equal`,
+        ['2026-04-14T10:00:00.000Z']
+      );
+      expect(result.rows[0].equal).toBe(1);
+    });
+  });
 });

packages/core/src/db/adapters/sqlite.ts

@@ -215,22 +215,6 @@ export class SqliteAdapter implements IDatabase {
     } catch (e: unknown) {
       getLog().warn({ err: e as Error }, 'db.sqlite_migration_session_columns_failed');
     }
-
-    // Codebases columns (added in #983 — env-leak gate consent bit)
-    try {
-      const cbCols = this.db.prepare("PRAGMA table_info('remote_agent_codebases')").all() as {
-        name: string;
-      }[];
-      const cbColNames = new Set(cbCols.map(c => c.name));
-
-      if (!cbColNames.has('allow_env_keys')) {
-        this.db.run(
-          'ALTER TABLE remote_agent_codebases ADD COLUMN allow_env_keys INTEGER DEFAULT 0'
-        );
-      }
-    } catch (e: unknown) {
-      getLog().warn({ err: e as Error }, 'db.sqlite_migration_codebases_columns_failed');
-    }
   }
 
   /**
@@ -252,7 +236,6 @@ export class SqliteAdapter implements IDatabase {
         default_cwd TEXT NOT NULL,
         default_branch TEXT DEFAULT 'main',
         ai_assistant_type TEXT DEFAULT 'claude',
-        allow_env_keys INTEGER DEFAULT 0,
         commands TEXT DEFAULT '{}',
         created_at TEXT DEFAULT (datetime('now')),
         updated_at TEXT DEFAULT (datetime('now'))

packages/core/src/db/codebases.test.ts

@@ -22,7 +22,6 @@ import {
   findCodebaseByDefaultCwd,
   findCodebaseByName,
   updateCodebase,
-  updateCodebaseAllowEnvKeys,
   deleteCodebase,
 } from './codebases';
 
@@ -37,7 +36,6 @@ describe('codebases', () => {
     repository_url: 'https://github.com/user/repo',
     default_cwd: '/workspace/test-project',
     ai_assistant_type: 'claude',
-    allow_env_keys: false,
     commands: { plan: { path: '.claude/commands/plan.md', description: 'Plan feature' } },
     created_at: new Date(),
     updated_at: new Date(),
@@ -56,8 +54,8 @@ describe('codebases', () => {
 
       expect(result).toEqual(mockCodebase);
       expect(mockQuery).toHaveBeenCalledWith(
-        'INSERT INTO remote_agent_codebases (name, repository_url, default_cwd, ai_assistant_type, allow_env_keys) VALUES ($1, $2, $3, $4, $5) RETURNING *',
-        ['test-project', 'https://github.com/user/repo', '/workspace/test-project', 'claude', false]
+        'INSERT INTO remote_agent_codebases (name, repository_url, default_cwd, ai_assistant_type) VALUES ($1, $2, $3, $4) RETURNING *',
+        ['test-project', 'https://github.com/user/repo', '/workspace/test-project', 'claude']
       );
     });
 
@@ -75,8 +73,8 @@ describe('codebases', () => {
 
       expect(result).toEqual(codebaseWithoutOptional);
       expect(mockQuery).toHaveBeenCalledWith(
-        'INSERT INTO remote_agent_codebases (name, repository_url, default_cwd, ai_assistant_type, allow_env_keys) VALUES ($1, $2, $3, $4, $5) RETURNING *',
-        ['test-project', null, '/workspace/test-project', 'claude', false]
+        'INSERT INTO remote_agent_codebases (name, repository_url, default_cwd, ai_assistant_type) VALUES ($1, $2, $3, $4) RETURNING *',
+        ['test-project', null, '/workspace/test-project', 'claude']
       );
     });
 
@@ -191,6 +189,22 @@ describe('codebases', () => {
       // Original frozen object should be unchanged
       expect(frozenCommands).not.toHaveProperty('new-command');
     });
+
+    test('throws on corrupt JSON string (SQLite TEXT column)', async () => {
+      mockQuery.mockResolvedValueOnce(createQueryResult([{ commands: '{not valid json' }]));
+
+      await expect(getCodebaseCommands('codebase-123')).rejects.toThrow(
+        /Corrupt commands JSON for codebase codebase-123/
+      );
+    });
+
+    test('parses valid JSON string from SQLite TEXT column', async () => {
+      const commands = { plan: { path: 'plan.md', description: 'Plan' } };
+      mockQuery.mockResolvedValueOnce(createQueryResult([{ commands: JSON.stringify(commands) }]));
+
+      const result = await getCodebaseCommands('codebase-123');
+      expect(result).toEqual(commands);
+    });
   });
 
   describe('registerCommand', () => {
@@ -299,7 +313,6 @@ describe('codebases', () => {
             name: 'test-repo',
             default_cwd: '/workspace/test-repo',
             ai_assistant_type: 'claude',
-            allow_env_keys: false,
             repository_url: null,
             commands: {},
             created_at: new Date(),
@@ -399,26 +412,6 @@ describe('codebases', () => {
     });
   });
 
-  describe('updateCodebaseAllowEnvKeys', () => {
-    test('flips the consent bit', async () => {
-      mockQuery.mockResolvedValueOnce(createQueryResult([], 1));
-
-      await updateCodebaseAllowEnvKeys('codebase-123', true);
-
-      expect(mockQuery).toHaveBeenCalledWith(
-        'UPDATE remote_agent_codebases SET allow_env_keys = $1, updated_at = NOW() WHERE id = $2',
-        [true, 'codebase-123']
-      );
-    });
-
-    test('throws when codebase not found', async () => {
-      mockQuery.mockResolvedValueOnce(createQueryResult([], 0));
-      await expect(updateCodebaseAllowEnvKeys('missing', false)).rejects.toThrow(
-        'Codebase missing not found'
-      );
-    });
-  });
-
   describe('deleteCodebase', () => {
     test('should unlink sessions, conversations, and delete codebase', async () => {
       // First call: unlink sessions

packages/core/src/db/codebases.ts

@@ -17,13 +17,11 @@ export async function createCodebase(data: {
   repository_url?: string;
   default_cwd: string;
   ai_assistant_type?: string;
-  allow_env_keys?: boolean;
 }): Promise<Codebase> {
   const assistantType = data.ai_assistant_type ?? 'claude';
-  const allowEnvKeys = data.allow_env_keys ?? false;
   const result = await pool.query<Codebase>(
-    'INSERT INTO remote_agent_codebases (name, repository_url, default_cwd, ai_assistant_type, allow_env_keys) VALUES ($1, $2, $3, $4, $5) RETURNING *',
-    [data.name, data.repository_url ?? null, data.default_cwd, assistantType, allowEnvKeys]
+    'INSERT INTO remote_agent_codebases (name, repository_url, default_cwd, ai_assistant_type) VALUES ($1, $2, $3, $4) RETURNING *',
+    [data.name, data.repository_url ?? null, data.default_cwd, assistantType]
   );
   if (!result.rows[0]) {
     throw new Error('Failed to create codebase: INSERT succeeded but no row returned');
@@ -61,9 +59,12 @@ export async function getCodebaseCommands(
   if (typeof raw === 'string') {
     try {
       parsed = JSON.parse(raw);
-    } catch {
-      getLog().error({ codebaseId: id, raw }, 'db.codebase_commands_json_parse_failed');
-      return {};
+    } catch (err) {
+      getLog().error({ codebaseId: id, raw, err }, 'db.codebase_commands_json_parse_failed');
+      throw new Error(
+        `Corrupt commands JSON for codebase ${id}: unable to parse stored data. ` +
+          `Run UPDATE remote_agent_codebases SET commands = '{}' WHERE id = '${id}' to reset.`
+      );
     }
   } else {
     parsed = raw ?? {};
@@ -158,21 +159,6 @@ export async function updateCodebase(
   }
 }
 
-/**
- * Flip the `allow_env_keys` consent bit for an existing codebase.
- * Throws when the codebase does not exist.
- */
-export async function updateCodebaseAllowEnvKeys(id: string, allowEnvKeys: boolean): Promise<void> {
-  const dialect = getDialect();
-  const result = await pool.query(
-    `UPDATE remote_agent_codebases SET allow_env_keys = $1, updated_at = ${dialect.now()} WHERE id = $2`,
-    [allowEnvKeys, id]
-  );
-  if ((result.rowCount ?? 0) === 0) {
-    throw new Error(`Codebase ${id} not found`);
-  }
-}
-
 export async function listCodebases(): Promise<readonly Codebase[]> {
   const result = await pool.query<Codebase>(
     'SELECT * FROM remote_agent_codebases ORDER BY name ASC'

packages/core/src/db/messages.test.ts

@@ -3,6 +3,7 @@ import { createQueryResult, mockPostgresDialect } from '../test/mocks/database';
 import type { MessageRow } from './messages';
 
 const mockQuery = mock(() => Promise.resolve(createQueryResult([])));
+const mockGetDatabaseType = mock(() => 'postgresql' as const);
 
 // Mock the connection module before importing the module under test
 mock.module('./connection', () => ({
@@ -10,9 +11,22 @@ mock.module('./connection', () => ({
     query: mockQuery,
   },
   getDialect: () => mockPostgresDialect,
+  getDatabaseType: mockGetDatabaseType,
 }));
 
-import { addMessage, listMessages } from './messages';
+// Mock @archon/paths to avoid lazy logger initialization issues in tests
+mock.module('@archon/paths', () => ({
+  createLogger: mock(() => ({
+    fatal: mock(() => undefined),
+    error: mock(() => undefined),
+    warn: mock(() => undefined),
+    info: mock(() => undefined),
+    debug: mock(() => undefined),
+    trace: mock(() => undefined),
+  })),
+}));
+
+import { addMessage, listMessages, getRecentWorkflowResultMessages } from './messages';
 
 describe('messages', () => {
   beforeEach(() => {
@@ -121,4 +135,76 @@ describe('messages', () => {
       expect(mockQuery).toHaveBeenCalledWith(expect.any(String), ['conv-456', 50]);
     });
   });
+
+  describe('getRecentWorkflowResultMessages', () => {
+    beforeEach(() => {
+      mockGetDatabaseType.mockClear();
+    });
+
+    test('uses PostgreSQL JSON extraction syntax when dbType is postgresql', async () => {
+      mockGetDatabaseType.mockReturnValueOnce('postgresql');
+      mockQuery.mockResolvedValueOnce(createQueryResult([]));
+
+      await getRecentWorkflowResultMessages('conv-1');
+
+      const sql = mockQuery.mock.calls[0]?.[0] as string;
+      expect(sql).toContain("metadata->>'workflowResult'");
+      expect(sql).not.toContain('json_extract');
+    });
+
+    test('uses SQLite JSON extraction syntax when dbType is sqlite', async () => {
+      mockGetDatabaseType.mockReturnValueOnce('sqlite');
+      mockQuery.mockResolvedValueOnce(createQueryResult([]));
+
+      await getRecentWorkflowResultMessages('conv-1');
+
+      const sql = mockQuery.mock.calls[0]?.[0] as string;
+      expect(sql).toContain("json_extract(metadata, '$.workflowResult')");
+      expect(sql).not.toContain("->>'" + 'workflowResult');
+    });
+
+    test('passes correct parameters: conversationId and limit', async () => {
+      mockGetDatabaseType.mockReturnValueOnce('postgresql');
+      mockQuery.mockResolvedValueOnce(createQueryResult([]));
+
+      await getRecentWorkflowResultMessages('conv-42', 5);
+
+      expect(mockQuery).toHaveBeenCalledWith(expect.any(String), ['conv-42', 5]);
+    });
+
+    test('default limit is 3', async () => {
+      mockGetDatabaseType.mockReturnValueOnce('postgresql');
+      mockQuery.mockResolvedValueOnce(createQueryResult([]));
+
+      await getRecentWorkflowResultMessages('conv-1');
+
+      expect(mockQuery).toHaveBeenCalledWith(expect.any(String), ['conv-1', 3]);
+    });
+
+    test('returns empty array on query error (non-throwing contract)', async () => {
+      mockGetDatabaseType.mockReturnValueOnce('postgresql');
+      mockQuery.mockRejectedValueOnce(new Error('connection refused'));
+
+      const result = await getRecentWorkflowResultMessages('conv-1');
+
+      expect(result).toEqual([]);
+    });
+
+    test('returns rows from successful query', async () => {
+      const row: MessageRow = {
+        id: 'msg-1',
+        conversation_id: 'conv-1',
+        role: 'assistant',
+        content: 'Workflow summary here.',
+        metadata: '{"workflowResult":{"workflowName":"plan","runId":"run-1"}}',
+        created_at: '2026-01-01T00:00:00Z',
+      };
+      mockGetDatabaseType.mockReturnValueOnce('postgresql');
+      mockQuery.mockResolvedValueOnce(createQueryResult([row]));
+
+      const result = await getRecentWorkflowResultMessages('conv-1');
+
+      expect(result).toEqual([row]);
+    });
+  });
 });

packages/core/src/db/messages.ts

@@ -1,7 +1,7 @@
 /**
- * Database operations for conversation messages (Web UI history)
+ * Database operations for conversation messages (Web UI history and orchestrator prompt enrichment)
  */
-import { pool, getDialect } from './connection';
+import { pool, getDialect, getDatabaseType } from './connection';
 import { createLogger } from '@archon/paths';
 
 /** Lazy-initialized logger (deferred so test mocks can intercept createLogger) */
@@ -16,7 +16,7 @@ export interface MessageRow {
   conversation_id: string;
   role: 'user' | 'assistant';
   content: string;
-  metadata: string; // JSON string - parsed by frontend
+  metadata: string; // JSON string - parsed by frontend and server-side (orchestrator prompt enrichment)
   created_at: string;
 }
 
@@ -64,3 +64,34 @@ export async function listMessages(
   );
   return result.rows;
 }
+
+/**
+ * Get recent messages with workflowResult metadata for a conversation.
+ * Used to inject workflow context into the orchestrator prompt.
+ * Non-throwing — returns empty array on error.
+ */
+export async function getRecentWorkflowResultMessages(
+  conversationId: string,
+  limit = 3
+): Promise<readonly MessageRow[]> {
+  const dbType = getDatabaseType();
+  const metadataFilter =
+    dbType === 'postgresql'
+      ? "(metadata->>'workflowResult') IS NOT NULL"
+      : "json_extract(metadata, '$.workflowResult') IS NOT NULL";
+  try {
+    const result = await pool.query<Pick<MessageRow, 'id' | 'content' | 'metadata'>>(
+      `SELECT id, content, metadata FROM remote_agent_messages
+       WHERE conversation_id = $1
+       AND ${metadataFilter}
+       ORDER BY created_at DESC
+       LIMIT $2`,
+      [conversationId, limit]
+    );
+    return result.rows as MessageRow[];
+  } catch (error) {
+    const err = error as Error;
+    getLog().warn({ err, conversationId }, 'db.workflow_result_messages_query_failed');
+    return [];
+  }
+}

packages/core/src/db/workflows.test.ts

@@ -559,6 +559,60 @@ describe('workflows database', () => {
       expect(params).toEqual(['/repo/path']);
     });
 
+    test('includes pending rows within the stale-pending age window', async () => {
+      mockQuery.mockResolvedValueOnce(createQueryResult([]));
+
+      await getActiveWorkflowRunByPath('/repo/path');
+
+      const [query] = mockQuery.mock.calls[0] as [string, unknown[]];
+      // Fresh `pending` counts as active so the lock is held immediately
+      // after pre-create — without this, two near-simultaneous dispatches
+      // both pass the guard.
+      expect(query).toContain("status = 'pending'");
+      // Age window cutoff prevents orphaned pending rows (from crashed
+      // dispatches) from permanently blocking a path.
+      expect(query).toMatch(/started_at >.*INTERVAL.*milliseconds/);
+    });
+
+    test('excludes self and applies older-wins tiebreaker when self is provided', async () => {
+      mockQuery.mockResolvedValueOnce(createQueryResult([]));
+      const startedAt = new Date('2026-04-14T10:00:00Z');
+
+      await getActiveWorkflowRunByPath('/repo/path', { id: 'self-id', startedAt });
+
+      const [query, params] = mockQuery.mock.calls[0] as [string, unknown[]];
+      expect(query).toContain('id != $2');
+      // PostgreSQL branch: explicit `::timestamptz` cast on the param so
+      // the comparison is chronological, not lexical. SQLite branch wraps
+      // both sides in datetime() — covered by tests in adapters/sqlite.test.ts
+      // because this suite mocks getDatabaseType as 'postgresql'.
+      expect(query).toContain('started_at < $3::timestamptz');
+      expect(query).toContain('started_at = $3::timestamptz AND id < $2');
+      // selfStartedAt serialized to ISO — bun:sqlite rejects Date bindings.
+      expect(params).toEqual(['/repo/path', 'self-id', startedAt.toISOString()]);
+    });
+
+    test('skips self exclusion + tiebreaker when self is omitted (no caller context)', async () => {
+      mockQuery.mockResolvedValueOnce(createQueryResult([]));
+
+      await getActiveWorkflowRunByPath('/repo/path');
+
+      const [query, params] = mockQuery.mock.calls[0] as [string, unknown[]];
+      // Without `self`, neither the id-exclusion nor the tiebreaker apply.
+      expect(query).not.toContain('id !=');
+      expect(query).not.toContain('started_at <');
+      expect(params).toEqual(['/repo/path']);
+    });
+
+    test('orders by (started_at ASC, id ASC) so older-wins is deterministic', async () => {
+      mockQuery.mockResolvedValueOnce(createQueryResult([]));
+
+      await getActiveWorkflowRunByPath('/repo/path');
+
+      const [query] = mockQuery.mock.calls[0] as [string, unknown[]];
+      expect(query).toContain('ORDER BY started_at ASC, id ASC');
+    });
+
     test('returns null when no active run on path', async () => {
       mockQuery.mockResolvedValueOnce(createQueryResult([]));
 
@@ -671,6 +725,22 @@ describe('workflows database', () => {
       expect(selectParams).toEqual(['workflow-run-123']);
     });
 
+    test('refreshes started_at to NOW so resumed row competes fairly in the path-lock tiebreaker', async () => {
+      // Without this refresh, a resumed row carries its original (potentially
+      // hours-old) started_at and sorts ahead of any currently-active holder
+      // in the older-wins tiebreaker — slipping past the lock and causing
+      // two active workflows on the same working_path.
+      mockQuery.mockResolvedValueOnce(createQueryResult([], 1));
+      mockQuery.mockResolvedValueOnce(
+        createQueryResult([{ ...mockWorkflowRun, status: 'running' as const }])
+      );
+
+      await resumeWorkflowRun('workflow-run-123');
+
+      const [updateQuery] = mockQuery.mock.calls[0] as [string, unknown[]];
+      expect(updateQuery).toContain('started_at = NOW()');
+    });
+
     test('throws when no row matched (run not found)', async () => {
       // UPDATE returns rowCount 0
       mockQuery.mockResolvedValueOnce(createQueryResult([], 0));

packages/core/src/db/workflows.ts

@@ -184,13 +184,76 @@ export async function getPausedWorkflowRun(conversationId: string): Promise<Work
   }
 }
 
-export async function getActiveWorkflowRunByPath(workingPath: string): Promise<WorkflowRun | null> {
+/**
+ * Find the workflow run currently holding the lock on `workingPath`.
+ *
+ * The lock is held by any row in `(running, paused)` or `pending` younger
+ * than `STALE_PENDING_AGE_MS` (orphaned pre-creates beyond that window are
+ * ignored — they're from crashed or resume-replaced dispatches).
+ *
+ * When called from a dispatch that already pre-created its own row, pass
+ * `excludeId` and `selfStartedAt` so:
+ *   1. Self is never returned.
+ *   2. If two dispatches both have rows, the deterministic older-wins
+ *      tiebreaker `(started_at, id)` ensures both agree on which is "first."
+ *      The newer dispatch sees the older row and aborts; the older dispatch
+ *      sees nothing.
+ *
+ * Returns the holding row, or null if the path is free.
+ */
+export const STALE_PENDING_AGE_MS = 5 * 60 * 1000; // 5 minutes
+
+export async function getActiveWorkflowRunByPath(
+  workingPath: string,
+  self?: { id: string; startedAt: Date }
+): Promise<WorkflowRun | null> {
+  const isPostgres = getDatabaseType() === 'postgresql';
+  const stalePendingCutoff = isPostgres
+    ? `NOW() - INTERVAL '${String(STALE_PENDING_AGE_MS)} milliseconds'`
+    : `datetime('now', '-${String(Math.floor(STALE_PENDING_AGE_MS / 1000))} seconds')`;
+
+  // Build params + clauses dynamically. Self exclusion + tiebreaker travel
+  // together — the tiebreaker references both ids and timestamps.
+  const params: unknown[] = [workingPath];
+  const clauses: string[] = [
+    'working_path = $1',
+    `(status IN ('running', 'paused') OR (status = 'pending' AND started_at > ${stalePendingCutoff}))`,
+  ];
+  if (self !== undefined) {
+    params.push(self.id);
+    clauses.push(`id != $${String(params.length)}`);
+  }
+  if (self !== undefined) {
+    // Older-wins tiebreaker. (started_at, id) is a total order so both
+    // dispatches always agree on which is "first." Without this, two rows
+    // with similar timestamps could mutually see each other and both abort.
+    //
+    // Serialize Date to ISO string — bun:sqlite rejects Date bindings.
+    //
+    // Format-aware comparison:
+    //   PostgreSQL: started_at is TIMESTAMPTZ; cast the ISO param to
+    //     timestamptz so the comparison is chronological, not lexical.
+    //   SQLite: started_at is TEXT in "YYYY-MM-DD HH:MM:SS" format. Our
+    //     ISO param has "YYYY-MM-DDTHH:MM:SS.mmmZ". Lexical comparison is
+    //     WRONG: char 11 is space (0x20) in the column vs T (0x54) in the
+    //     param, so every column value lex-sorts before every ISO param —
+    //     making `started_at < $param` always TRUE regardless of actual
+    //     time. Wrap both sides in datetime() to force chronological
+    //     comparison via SQLite's date/time functions.
+    params.push(self.startedAt.toISOString());
+    const startedAtParam = `$${String(params.length)}`;
+    const idParam = `$${String(params.length - 1)}`;
+    const colExpr = isPostgres ? 'started_at' : 'datetime(started_at)';
+    const paramExpr = isPostgres ? `${startedAtParam}::timestamptz` : `datetime(${startedAtParam})`;
+    clauses.push(`(${colExpr} < ${paramExpr} OR (${colExpr} = ${paramExpr} AND id < ${idParam}))`);
+  }
+
   try {
     const result = await pool.query<WorkflowRun>(
       `SELECT * FROM remote_agent_workflow_runs
-       WHERE working_path = $1 AND status IN ('running', 'paused')
-       ORDER BY started_at DESC LIMIT 1`,
-      [workingPath]
+       WHERE ${clauses.join(' AND ')}
+       ORDER BY started_at ASC, id ASC LIMIT 1`,
+      params
     );
     const row = result.rows[0];
     return row ? normalizeWorkflowRun(row) : null;
@@ -309,9 +372,23 @@ export async function resumeWorkflowRun(id: string): Promise<WorkflowRun> {
   // Each phase has its own try/catch to avoid string-sniffing own errors in a shared catch.
   let updateResult: Awaited<ReturnType<typeof pool.query>>;
   try {
+    // Refresh started_at to NOW so the resumed row competes fairly with
+    // currently-active rows in getActiveWorkflowRunByPath's older-wins
+    // tiebreaker. Without this, a resumed row carries its original
+    // (potentially hours-old) started_at and would sort ahead of any
+    // currently-running holder, slipping past the path lock and causing
+    // two active workflows on the same working_path.
+    //
+    // We accept losing the original creation time here — `started_at` for
+    // an active row semantically means "when did this active phase start."
+    // The original creation time can be recovered from workflow_events
+    // history if needed for analytics.
     updateResult = await pool.query(
       `UPDATE remote_agent_workflow_runs
-       SET status = 'running', completed_at = NULL, last_activity_at = ${dialect.now()}
+       SET status = 'running',
+           completed_at = NULL,
+           started_at = ${dialect.now()},
+           last_activity_at = ${dialect.now()}
        WHERE id = $1`,
       [id]
     );

packages/core/src/handlers/clone.test.ts

@@ -20,7 +20,6 @@ const mockCreateCodebase = mock(() =>
     repository_url: 'https://github.com/owner/repo',
     default_cwd: '/home/test/.archon/workspaces/owner/repo/source',
     ai_assistant_type: 'claude',
-    allow_env_keys: false,
     commands: {},
     created_at: new Date(),
     updated_at: new Date(),
@@ -67,20 +66,6 @@ mock.module('../utils/commands', () => ({
   findMarkdownFilesRecursive: mockFindMarkdownFilesRecursive,
 }));
 
-// ── env-leak-scanner mock ───────────────────────────────────────────────────
-class MockEnvLeakError extends Error {
-  constructor(public report: unknown) {
-    super('Cannot add codebase — /test/path contains keys that will leak into AI subprocesses');
-    this.name = 'EnvLeakError';
-  }
-}
-
-const mockScanPathForSensitiveKeys = mock(() => ({ path: '', findings: [] }));
-mock.module('../utils/env-leak-scanner', () => ({
-  scanPathForSensitiveKeys: mockScanPathForSensitiveKeys,
-  EnvLeakError: MockEnvLeakError,
-}));
-
 // ── Import module under test AFTER mocks are registered ────────────────────
 import { cloneRepository, registerRepository } from './clone';
 
@@ -118,7 +103,6 @@ function clearMocks(): void {
   mockFindCodebaseByName.mockReset();
   mockUpdateCodebase.mockReset();
   mockFindMarkdownFilesRecursive.mockReset();
-  mockScanPathForSensitiveKeys.mockReset();
   mockLogger.info.mockClear();
   mockLogger.debug.mockClear();
   mockLogger.warn.mockClear();
@@ -132,7 +116,6 @@ function clearMocks(): void {
   mockFindCodebaseByName.mockResolvedValue(null);
   mockUpdateCodebase.mockResolvedValue(undefined);
   mockFindMarkdownFilesRecursive.mockResolvedValue([]);
-  mockScanPathForSensitiveKeys.mockReturnValue({ path: '', findings: [] });
 }
 
 afterAll(() => {
@@ -157,7 +140,6 @@ function makeCodebase(
     repository_url: 'https://github.com/owner/repo',
     default_cwd: '/home/test/.archon/workspaces/owner/repo/source',
     ai_assistant_type: 'claude',
-    allow_env_keys: false,
     commands: {},
     created_at: new Date(),
     updated_at: new Date(),
@@ -948,33 +930,4 @@ describe('RegisterResult shape', () => {
     expect(result.alreadyExisted).toBe(true);
     expect(result.commandCount).toBe(0);
   });
-
-  describe('env leak gate', () => {
-    test('throws EnvLeakError when scanner finds sensitive keys and allowEnvKeys is false', async () => {
-      mockScanPathForSensitiveKeys.mockReturnValueOnce({
-        path: '/home/test/.archon/workspaces/owner/repo/source',
-        findings: [{ file: '.env', keys: ['ANTHROPIC_API_KEY'] }],
-      });
-
-      await expect(cloneRepository('https://github.com/owner/repo')).rejects.toThrow(
-        'Cannot add codebase'
-      );
-    });
-
-    test('does not throw when allowEnvKeys is true, even with scanner findings present', async () => {
-      mockCreateCodebase.mockResolvedValueOnce(makeCodebase() as ReturnType<typeof makeCodebase>);
-      // Scanner is still called for the audit-log payload (files/keys), but the
-      // gate must NOT throw — the per-call grant is the bypass.
-      mockScanPathForSensitiveKeys.mockReturnValueOnce({
-        path: '/home/test/.archon/workspaces/owner/repo/source',
-        findings: [{ file: '.env', keys: ['ANTHROPIC_API_KEY'] }],
-      });
-
-      const result = await cloneRepository('https://github.com/owner/repo', true);
-
-      expect(result.codebaseId).toBe('codebase-uuid-1');
-      // Scanner is called once — for the audit log, not as a gate
-      expect(mockScanPathForSensitiveKeys).toHaveBeenCalledTimes(1);
-    });
-  });
 });

packages/core/src/handlers/clone.ts

@@ -16,12 +16,6 @@ import {
   parseOwnerRepo,
 } from '@archon/paths';
 import { findMarkdownFilesRecursive } from '../utils/commands';
-import {
-  scanPathForSensitiveKeys,
-  EnvLeakError,
-  type LeakErrorContext,
-} from '../utils/env-leak-scanner';
-import { loadConfig } from '../config/config-loader';
 import { createLogger } from '@archon/paths';
 
 /** Lazy-initialized logger (deferred so test mocks can intercept createLogger) */
@@ -46,55 +40,14 @@ export interface RegisterResult {
 async function registerRepoAtPath(
   targetPath: string,
   name: string,
-  repositoryUrl: string | null,
-  allowEnvKeys = false,
-  context: LeakErrorContext = 'register-ui'
+  repositoryUrl: string | null
 ): Promise<RegisterResult> {
-  // Scan for sensitive keys in auto-loaded .env files before registering.
-  // Two bypass paths exist (in order of precedence):
-  //   1. Per-call `allowEnvKeys=true` (Web UI checkbox or CLI --allow-env-keys)
-  //   2. Config-level `allow_target_repo_keys: true` (global YAML)
-  // When the per-call bypass is used we still emit an audit-log entry so the
-  // grant has a permanent breadcrumb (parity with the PATCH route's
-  // `env_leak_consent_granted` log).
-  if (!allowEnvKeys) {
-    const merged = await loadConfig(targetPath);
-    if (!merged.allowTargetRepoKeys) {
-      const report = scanPathForSensitiveKeys(targetPath);
-      if (report.findings.length > 0) {
-        throw new EnvLeakError(report, context);
-      }
-    }
-  } else {
-    // Per-call grant — emit audit log mirroring the PATCH route shape so the
-    // CLI/UI add-with-consent paths leave the same breadcrumbs.
-    let files: string[] = [];
-    let keys: string[] = [];
-    let scanStatus: 'ok' | 'skipped' = 'ok';
-    try {
-      const report = scanPathForSensitiveKeys(targetPath);
-      files = report.findings.map(f => f.file);
-      keys = Array.from(new Set(report.findings.flatMap(f => f.keys)));
-    } catch (scanErr) {
-      scanStatus = 'skipped';
-      getLog().warn({ err: scanErr, path: targetPath }, 'env_leak_consent_scan_skipped');
-    }
-    const actor = context === 'register-cli' ? 'user-cli' : 'user-ui';
-    getLog().warn(
-      {
-        name,
-        path: targetPath,
-        files,
-        keys,
-        scanStatus,
-        actor,
-      },
-      'env_leak_consent_granted'
-    );
-  }
-
-  // Auto-detect assistant type based on folder structure
-  let suggestedAssistant = 'claude';
+  // Auto-detect assistant type based on SDK folder conventions.
+  // Built-in providers use well-known folders (.claude/, .codex/).
+  // Falls back to first registered built-in provider if no folder detected.
+  const { getRegisteredProviders } = await import('@archon/providers');
+  const defaultProvider = getRegisteredProviders().find(p => p.builtIn)?.id ?? 'claude';
+  let suggestedAssistant = defaultProvider;
   const codexFolder = join(targetPath, '.codex');
   const claudeFolder = join(targetPath, '.claude');
 
@@ -108,7 +61,7 @@ async function registerRepoAtPath(
       suggestedAssistant = 'claude';
       getLog().debug({ path: claudeFolder }, 'assistant_detected_claude');
     } catch {
-      getLog().debug('assistant_default_claude');
+      getLog().debug({ provider: defaultProvider }, 'assistant_default_from_registry');
     }
   }
 
@@ -173,7 +126,6 @@ async function registerRepoAtPath(
     repository_url: repositoryUrl ?? undefined,
     default_cwd: targetPath,
     ai_assistant_type: suggestedAssistant,
-    allow_env_keys: allowEnvKeys,
   });
 
   // Auto-load commands if found
@@ -242,15 +194,11 @@ function normalizeRepoUrl(rawUrl: string): {
  * Local paths (starting with /, ~, or .) are delegated to registerRepository
  * to avoid wrong owner/repo naming. See #383 for broader rethink.
  */
-export async function cloneRepository(
-  repoUrl: string,
-  allowEnvKeys?: boolean,
-  context: LeakErrorContext = 'register-ui'
-): Promise<RegisterResult> {
+export async function cloneRepository(repoUrl: string): Promise<RegisterResult> {
   // Local paths should be registered (symlink), not cloned (copied)
   if (repoUrl.startsWith('/') || repoUrl.startsWith('~') || repoUrl.startsWith('.')) {
     const resolvedPath = repoUrl.startsWith('~') ? expandTilde(repoUrl) : resolve(repoUrl);
-    return registerRepository(resolvedPath, allowEnvKeys, context);
+    return registerRepository(resolvedPath);
   }
 
   const { workingUrl, ownerName, repoName, targetPath } = normalizeRepoUrl(repoUrl);
@@ -331,13 +279,7 @@ export async function cloneRepository(
   await execFileAsync('git', ['config', '--global', '--add', 'safe.directory', targetPath]);
   getLog().debug({ path: targetPath }, 'safe_directory_added');
 
-  const result = await registerRepoAtPath(
-    targetPath,
-    `${ownerName}/${repoName}`,
-    workingUrl,
-    allowEnvKeys,
-    context
-  );
+  const result = await registerRepoAtPath(targetPath, `${ownerName}/${repoName}`, workingUrl);
   getLog().info({ url: workingUrl, targetPath }, 'clone_completed');
   return result;
 }
@@ -345,11 +287,7 @@ export async function cloneRepository(
 /**
  * Register an existing local repository in the database (no git clone).
  */
-export async function registerRepository(
-  localPath: string,
-  allowEnvKeys?: boolean,
-  context: LeakErrorContext = 'register-ui'
-): Promise<RegisterResult> {
+export async function registerRepository(localPath: string): Promise<RegisterResult> {
   // Validate path exists and is a git repo
   try {
     await execFileAsync('git', ['-C', localPath, 'rev-parse', '--git-dir']);
@@ -415,5 +353,5 @@ export async function registerRepository(
   );
 
   // default_cwd is the real local path (not the symlink)
-  return registerRepoAtPath(localPath, name, remoteUrl, allowEnvKeys, context);
+  return registerRepoAtPath(localPath, name, remoteUrl);
 }

packages/core/src/handlers/command-handler.test.ts

@@ -511,7 +511,6 @@ describe('CommandHandler', () => {
           repository_url: 'https://github.com/user/my-repo',
           default_cwd: '/workspace/my-repo',
           ai_assistant_type: 'claude',
-          allow_env_keys: false,
           commands: {},
           created_at: new Date(),
           updated_at: new Date(),
@@ -567,7 +566,6 @@ describe('CommandHandler', () => {
           repository_url: 'https://github.com/owner/repo',
           default_cwd: '/workspace/repo',
           ai_assistant_type: 'claude',
-          allow_env_keys: false,
           commands: {},
           created_at: new Date(),
           updated_at: new Date(),
@@ -606,7 +604,6 @@ describe('CommandHandler', () => {
           repository_url: 'https://github.com/owner/orphaned-repo',
           default_cwd: '/workspace/orphaned-repo',
           ai_assistant_type: 'claude',
-          allow_env_keys: false,
           commands: {},
           created_at: new Date(),
           updated_at: new Date(),
@@ -721,7 +718,6 @@ describe('CommandHandler', () => {
           repository_url: 'https://github.com/user/my-repo',
           default_cwd: '/workspace/my-repo',
           ai_assistant_type: 'claude',
-          allow_env_keys: false,
           commands: {},
           created_at: new Date(),
           updated_at: new Date(),

packages/core/src/index.ts

@@ -24,8 +24,6 @@ export {
   type IWebPlatformAdapter,
   isWebAdapter,
   type MessageMetadata,
-  type MessageChunk,
-  type IAssistantClient,
 } from './types';
 
 // =============================================================================
@@ -52,13 +50,6 @@ export * as messageDb from './db/messages';
 // Re-export SessionNotFoundError for error handling
 export { SessionNotFoundError } from './db/sessions';
 
-// =============================================================================
-// AI Clients
-// =============================================================================
-export { ClaudeClient } from './clients/claude';
-export { CodexClient } from './clients/codex';
-export { getAssistantClient } from './clients/factory';
-
 // =============================================================================
 // Workflows
 // =============================================================================
@@ -145,15 +136,6 @@ export { toError } from './utils/error';
 // Credential sanitization
 export { sanitizeCredentials, sanitizeError } from './utils/credential-sanitizer';
 
-// Env leak scanner
-export {
-  EnvLeakError,
-  scanPathForSensitiveKeys,
-  formatLeakError,
-  type LeakReport,
-  type LeakErrorContext,
-} from './utils/env-leak-scanner';
-
 // GitHub GraphQL
 export { getLinkedIssueNumbers } from './utils/github-graphql';
 

packages/core/src/operations/workflow-operations.ts

@@ -34,6 +34,8 @@ export interface ApprovalOperationResult {
   workingPath: string | null;
   userMessage: string | null;
   codebaseId: string | null;
+  /** Internal DB UUID — resolve via getConversationById() to get platform_conversation_id. */
+  conversationId: string;
   type: 'interactive_loop' | 'approval_gate';
 }
 
@@ -42,6 +44,8 @@ export interface RejectionOperationResult {
   workingPath: string | null;
   userMessage: string | null;
   codebaseId: string | null;
+  /** Internal DB UUID — resolve via getConversationById() to get platform_conversation_id. */
+  conversationId: string;
   /** true = run cancelled; false = transitioning to failed for retry (has onRejectPrompt) */
   cancelled: boolean;
   /** true when cancelled specifically because max rejection attempts were reached */
@@ -168,6 +172,7 @@ export async function approveWorkflow(
         workingPath: run.working_path,
         userMessage: run.user_message,
         codebaseId: run.codebase_id,
+        conversationId: run.conversation_id,
         type: 'interactive_loop',
       };
     }
@@ -204,6 +209,7 @@ export async function approveWorkflow(
     workingPath: run.working_path,
     userMessage: run.user_message,
     codebaseId: run.codebase_id,
+    conversationId: run.conversation_id,
     type: 'approval_gate',
   };
 }
@@ -248,6 +254,7 @@ export async function rejectWorkflow(
           workingPath: run.working_path,
           userMessage: run.user_message,
           codebaseId: run.codebase_id,
+          conversationId: run.conversation_id,
           cancelled: true,
           maxAttemptsReached: true,
         };
@@ -261,6 +268,7 @@ export async function rejectWorkflow(
         workingPath: run.working_path,
         userMessage: run.user_message,
         codebaseId: run.codebase_id,
+        conversationId: run.conversation_id,
         cancelled: false,
         maxAttemptsReached: false,
       };
@@ -280,6 +288,7 @@ export async function rejectWorkflow(
     workingPath: run.working_path,
     userMessage: run.user_message,
     codebaseId: run.codebase_id,
+    conversationId: run.conversation_id,
     cancelled: true,
     maxAttemptsReached: false,
   };

packages/core/src/orchestrator/orchestrator-agent.test.ts

@@ -37,6 +37,17 @@ const mockExecuteWorkflow = mock(() => Promise.resolve());
 const mockHandleCommand = mock(() =>
   Promise.resolve({ success: true, message: 'ok', workflow: undefined })
 );
+const mockSendQuery = mock(async function* () {
+  yield { type: 'assistant', content: 'test response' };
+  yield { type: 'result', sessionId: 'session-1' };
+});
+const mockGetCodebaseEnvVars = mock(() => Promise.resolve({}));
+const mockLoadConfig = mock(() =>
+  Promise.resolve({
+    assistants: { claude: {}, codex: {} },
+    envVars: {},
+  })
+);
 
 const mockLogger = createMockLogger();
 
@@ -93,11 +104,17 @@ mock.module('@archon/workflows/executor', () => ({
   executeWorkflow: mockExecuteWorkflow,
 }));
 
-mock.module('../clients/factory', () => ({
-  getAssistantClient: mock(() => ({
-    sendQuery: mock(async function* () {}),
+mock.module('@archon/providers', () => ({
+  getAgentProvider: mock(() => ({
+    sendQuery: mockSendQuery,
     getType: mock(() => 'claude'),
+    getCapabilities: mock(() => ({})),
   })),
+  getProviderCapabilities: mock(() => ({ envInjection: true })),
+}));
+
+mock.module('../db/env-vars', () => ({
+  getCodebaseEnvVars: mockGetCodebaseEnvVars,
 }));
 
 mock.module('../utils/error-formatter', () => ({
@@ -126,7 +143,7 @@ mock.module('../db/workflow-events', () => ({
 }));
 
 mock.module('../config/config-loader', () => ({
-  loadConfig: mock(() => Promise.resolve({})),
+  loadConfig: mockLoadConfig,
 }));
 
 mock.module('../services/title-generator', () => ({
@@ -142,6 +159,16 @@ mock.module('./orchestrator', () => ({
 mock.module('./prompt-builder', () => ({
   buildOrchestratorPrompt: mock(() => 'orchestrator system prompt'),
   buildProjectScopedPrompt: mock(() => 'project scoped system prompt'),
+  formatWorkflowContextSection: mock((results: unknown[]) =>
+    results.length > 0 ? '## Recent Workflow Results\n\n...' : ''
+  ),
+}));
+
+const mockGetRecentWorkflowResultMessages = mock(() => Promise.resolve([]));
+mock.module('../db/messages', () => ({
+  addMessage: mock(() => Promise.resolve()),
+  listMessages: mock(() => Promise.resolve([])),
+  getRecentWorkflowResultMessages: mockGetRecentWorkflowResultMessages,
 }));
 
 mock.module('@archon/isolation', () => ({
@@ -181,7 +208,6 @@ function makeCodebase(name: string, id = `id-${name}`): Codebase {
     repository_url: null,
     default_cwd: `/repos/${name}`,
     ai_assistant_type: 'claude',
-    allow_env_keys: false,
     commands: {},
     created_at: new Date(),
     updated_at: new Date(),
@@ -805,7 +831,6 @@ function makeCodebaseForSync() {
     repository_url: 'https://github.com/test/repo',
     default_cwd: '/repos/test-repo',
     ai_assistant_type: 'claude',
-    allow_env_keys: false,
     commands: {},
     created_at: new Date(),
     updated_at: new Date(),
@@ -874,9 +899,19 @@ describe('discoverAllWorkflows — remote sync', () => {
     mockToRepoPath.mockClear();
     mockGetOrCreateConversation.mockReset();
     mockGetCodebase.mockReset();
+    mockSendQuery.mockClear();
+    mockGetCodebaseEnvVars.mockReset();
+    mockLoadConfig.mockReset();
     // Reset mocks between tests in this suite and restore safe defaults
     mockGetOrCreateConversation.mockImplementation(() => Promise.resolve(null));
     mockGetCodebase.mockImplementation(() => Promise.resolve(null));
+    mockGetCodebaseEnvVars.mockImplementation(() => Promise.resolve({}));
+    mockLoadConfig.mockImplementation(() =>
+      Promise.resolve({
+        assistants: { claude: {}, codex: {} },
+        envVars: {},
+      })
+    );
   });
 
   test('calls syncWorkspace with codebase.default_cwd when conversation has codebase_id', async () => {
@@ -955,6 +990,59 @@ describe('discoverAllWorkflows — remote sync', () => {
       'workspace.sync_failed'
     );
   });
+
+  test('passes merged repo and DB env vars to provider for codebase-scoped chat', async () => {
+    const conversation = makeConversation({ codebase_id: 'codebase-1' });
+    const codebase = makeCodebaseForSync();
+    mockGetOrCreateConversation.mockReturnValueOnce(Promise.resolve(conversation));
+    mockGetCodebase.mockReturnValueOnce(Promise.resolve(codebase));
+    mockGetCodebaseEnvVars.mockResolvedValueOnce({ DB_SECRET: 'db-value' });
+    mockLoadConfig.mockResolvedValueOnce({
+      assistants: { claude: {}, codex: {} },
+      envVars: { FILE_SECRET: 'file-value' },
+    });
+
+    const platform = makePlatform();
+    await handleMessage(platform, 'conv-1', 'What is the latest commit?');
+
+    expect(mockSendQuery).toHaveBeenCalled();
+    const requestOptions = mockSendQuery.mock.calls[0][3] as Record<string, unknown>;
+    expect(requestOptions.env).toEqual({
+      FILE_SECRET: 'file-value',
+      DB_SECRET: 'db-value',
+    });
+  });
+
+  test('does not load codebase env vars when conversation has no codebase_id', async () => {
+    mockGetOrCreateConversation.mockReturnValueOnce(Promise.resolve(makeConversation()));
+
+    const platform = makePlatform();
+    await handleMessage(platform, 'conv-1', 'Hello');
+
+    expect(mockGetCodebaseEnvVars).not.toHaveBeenCalled();
+  });
+
+  test('falls back to config env when codebase env loading fails', async () => {
+    const conversation = makeConversation({ codebase_id: 'codebase-1' });
+    const codebase = makeCodebaseForSync();
+    mockGetOrCreateConversation.mockReturnValueOnce(Promise.resolve(conversation));
+    mockGetCodebase.mockReturnValueOnce(Promise.resolve(codebase));
+    mockGetCodebaseEnvVars.mockRejectedValueOnce(new Error('db unavailable'));
+    mockLoadConfig.mockResolvedValueOnce({
+      assistants: { claude: {}, codex: {} },
+      envVars: { FILE_SECRET: 'file-value' },
+    });
+
+    const platform = makePlatform();
+    await handleMessage(platform, 'conv-1', 'What is the latest commit?');
+
+    expect(mockLogger.warn).toHaveBeenCalledWith(
+      expect.objectContaining({ codebaseId: 'codebase-1' }),
+      'codebase_env_vars_load_failed'
+    );
+    const requestOptions = mockSendQuery.mock.calls[0][3] as Record<string, unknown>;
+    expect(requestOptions.env).toEqual({ FILE_SECRET: 'file-value' });
+  });
 });
 
 // ─── Workflow dispatch routing — interactive flag ─────────────────────────────
@@ -971,7 +1059,6 @@ describe('workflow dispatch routing — interactive flag', () => {
       repository_url: null,
       default_cwd: '/repos/test-repo',
       ai_assistant_type: 'claude' as const,
-      allow_env_keys: false,
       commands: {},
       created_at: new Date(),
       updated_at: new Date(),
@@ -1072,7 +1159,6 @@ describe('natural-language approval routing', () => {
       repository_url: null,
       default_cwd: '/repos/test-repo',
       ai_assistant_type: 'claude' as const,
-      allow_env_keys: false,
       commands: {},
       created_at: new Date(),
       updated_at: new Date(),
@@ -1407,3 +1493,76 @@ describe('discoverAllWorkflows — merge repo workflows over global', () => {
     expect(mockDiscoverWorkflowsWithConfig).toHaveBeenCalledTimes(2);
   });
 });
+
+// ─── handleMessage — workflow context injection ───────────────────────────────
+
+describe('handleMessage — workflow context injection', () => {
+  beforeEach(() => {
+    mockGetRecentWorkflowResultMessages.mockClear();
+    mockGetOrCreateConversation.mockReset();
+    mockListCodebases.mockReset();
+    mockDiscoverWorkflowsWithConfig.mockReset();
+    mockLogger.warn.mockClear();
+
+    mockGetOrCreateConversation.mockImplementation(() => Promise.resolve(makeConversation()));
+    mockListCodebases.mockImplementation(() => Promise.resolve([]));
+    mockDiscoverWorkflowsWithConfig.mockImplementation(() =>
+      Promise.resolve({ workflows: [], errors: [] })
+    );
+    mockGetRecentWorkflowResultMessages.mockImplementation(() => Promise.resolve([]));
+  });
+
+  test('calls getRecentWorkflowResultMessages for the conversation', async () => {
+    const platform = makePlatform();
+    await handleMessage(platform, 'conv-1', 'What happened?');
+
+    expect(mockGetRecentWorkflowResultMessages).toHaveBeenCalledWith('conv-1', 3);
+  });
+
+  test('does not throw when getRecentWorkflowResultMessages returns empty array', async () => {
+    mockGetRecentWorkflowResultMessages.mockResolvedValueOnce([]);
+    const platform = makePlatform();
+
+    await expect(handleMessage(platform, 'conv-1', 'Hello')).resolves.toBeUndefined();
+  });
+
+  test('handles malformed metadata JSON without throwing', async () => {
+    const badRow = {
+      id: 'msg-1',
+      conversation_id: 'conv-1',
+      role: 'assistant' as const,
+      content: 'Summary.',
+      metadata: 'not-valid-json',
+      created_at: '2026-01-01T00:00:00Z',
+    };
+    mockGetRecentWorkflowResultMessages.mockResolvedValueOnce([badRow]);
+    const platform = makePlatform();
+
+    await expect(
+      handleMessage(platform, 'conv-1', 'What did the workflow do?')
+    ).resolves.toBeUndefined();
+  });
+
+  test('handles metadata with missing workflowResult key gracefully', async () => {
+    const rowNoWorkflowResult = {
+      id: 'msg-2',
+      conversation_id: 'conv-1',
+      role: 'assistant' as const,
+      content: 'Summary.',
+      metadata: '{"someOtherKey":"value"}',
+      created_at: '2026-01-01T00:00:00Z',
+    };
+    mockGetRecentWorkflowResultMessages.mockResolvedValueOnce([rowNoWorkflowResult]);
+    const platform = makePlatform();
+
+    await expect(handleMessage(platform, 'conv-1', 'Follow-up')).resolves.toBeUndefined();
+  });
+
+  test('continues without workflow context when outer fetch throws', async () => {
+    mockGetRecentWorkflowResultMessages.mockRejectedValueOnce(new Error('unexpected'));
+    const platform = makePlatform();
+
+    // Non-critical path — must not block message handling
+    await expect(handleMessage(platform, 'conv-1', 'Hello')).resolves.toBeUndefined();
+  });
+});

packages/core/src/orchestrator/orchestrator-agent.ts

@@ -13,9 +13,9 @@ import type {
   HandleMessageContext,
   Conversation,
   Codebase,
-  AssistantRequestOptions,
   AttachedFile,
 } from '../types';
+import type { SendQueryOptions } from '@archon/providers/types';
 import { ConversationNotFoundError } from '../types';
 import * as db from '../db/conversations';
 import * as codebaseDb from '../db/codebases';
@@ -24,8 +24,8 @@ import * as commandHandler from '../handlers/command-handler';
 import { formatToolCall } from '@archon/workflows/utils/tool-formatter';
 import { classifyAndFormatError } from '../utils/error-formatter';
 import { toError } from '../utils/error';
-import { getAssistantClient } from '../clients/factory';
-import { getArchonHome, getArchonWorkspacesPath } from '@archon/paths';
+import { getAgentProvider, getProviderCapabilities } from '@archon/providers';
+import { getArchonWorkspacesPath } from '@archon/paths';
 import { syncArchonToWorktree } from '../utils/worktree-sync';
 import { syncWorkspace, toRepoPath } from '@archon/git';
 import type { WorkspaceSyncResult } from '@archon/git';
@@ -43,9 +43,16 @@ import type { MergedConfig } from '../config/config-types';
 import { generateAndSetTitle } from '../services/title-generator';
 import { validateAndResolveIsolation, dispatchBackgroundWorkflow } from './orchestrator';
 import { IsolationBlockedError } from '@archon/isolation';
-import { buildOrchestratorPrompt, buildProjectScopedPrompt } from './prompt-builder';
+import {
+  buildOrchestratorPrompt,
+  buildProjectScopedPrompt,
+  formatWorkflowContextSection,
+} from './prompt-builder';
+import type { WorkflowResultContext } from './prompt-builder';
+import * as messageDb from '../db/messages';
 import * as workflowDb from '../db/workflows';
 import * as workflowEventDb from '../db/workflow-events';
+import { getCodebaseEnvVars } from '../db/env-vars';
 import type { ApprovalContext } from '@archon/workflows/schemas/workflow-run';
 
 /** Lazy-initialized logger (deferred so test mocks can intercept createLogger) */
@@ -221,31 +228,43 @@ async function dispatchOrchestratorWorkflow(
     codebase_id: codebase.id,
   });
 
-  // Validate and resolve isolation
+  // Validate and resolve isolation.
+  // A workflow with `worktree.enabled: false` short-circuits the resolver entirely
+  // and runs in the live checkout — no worktree creation, no env row. This is the
+  // declarative equivalent of CLI `--no-worktree` for workflows that should always
+  // run live (e.g. read-only triage, docs generation on the main checkout).
   let cwd: string;
-  try {
-    const result = await validateAndResolveIsolation(
-      { ...conversation, codebase_id: codebase.id },
-      codebase,
-      platform,
-      conversationId,
-      isolationHints
+  if (workflow.worktree?.enabled === false) {
+    getLog().info(
+      { workflowName: workflow.name, conversationId, codebaseId: codebase.id },
+      'workflow.worktree_disabled_by_policy'
     );
-    cwd = result.cwd;
-  } catch (error) {
-    if (error instanceof IsolationBlockedError) {
-      getLog().warn(
-        {
-          reason: error.reason,
-          conversationId,
-          codebaseId: codebase.id,
-          workflowName: workflow.name,
-        },
-        'isolation_blocked'
+    cwd = codebase.default_cwd;
+  } else {
+    try {
+      const result = await validateAndResolveIsolation(
+        { ...conversation, codebase_id: codebase.id },
+        codebase,
+        platform,
+        conversationId,
+        isolationHints
       );
-      return;
+      cwd = result.cwd;
+    } catch (error) {
+      if (error instanceof IsolationBlockedError) {
+        getLog().warn(
+          {
+            reason: error.reason,
+            conversationId,
+            codebaseId: codebase.id,
+            workflowName: workflow.name,
+          },
+          'isolation_blocked'
+        );
+        return;
+      }
+      throw error;
     }
-    throw error;
   }
 
   // Dispatch workflow
@@ -381,9 +400,9 @@ async function discoverAllWorkflows(conversation: Conversation): Promise<Discove
   let config: MergedConfig | undefined;
 
   try {
-    const result = await discoverWorkflowsWithConfig(getArchonWorkspacesPath(), loadConfig, {
-      globalSearchPath: getArchonHome(),
-    });
+    // Home-scoped workflows at ~/.archon/workflows/ are discovered automatically
+    // by discoverWorkflowsWithConfig — no option needed.
+    const result = await discoverWorkflowsWithConfig(getArchonWorkspacesPath(), loadConfig);
     workflows = [...result.workflows];
     allErrors.push(...result.errors);
   } catch (error) {
@@ -451,7 +470,8 @@ function buildFullPrompt(
   message: string,
   issueContext: string | undefined,
   threadContext: string | undefined,
-  attachedFiles?: AttachedFile[]
+  attachedFiles?: AttachedFile[],
+  workflowContext?: string
 ): string {
   const scopedCodebase = conversation.codebase_id
     ? codebases.find(c => c.id === conversation.codebase_id)
@@ -471,11 +491,14 @@ function buildFullPrompt(
           .join('\n')
       : '';
 
+  const workflowContextSuffix = workflowContext ? '\n\n---\n\n' + workflowContext : '';
+
   if (threadContext) {
     return (
       systemPrompt +
       '\n\n---\n\n## Thread Context (previous messages)\n\n' +
       threadContext +
+      workflowContextSuffix +
       '\n\n---\n\n## Current Request\n\n' +
       message +
       contextSuffix +
@@ -483,7 +506,14 @@ function buildFullPrompt(
     );
   }
 
-  return systemPrompt + '\n\n---\n\n## User Message\n\n' + message + contextSuffix + fileSuffix;
+  return (
+    systemPrompt +
+    workflowContextSuffix +
+    '\n\n---\n\n## User Message\n\n' +
+    message +
+    contextSuffix +
+    fileSuffix
+  );
 }
 
 // ─── Main Handler ───────────────────────────────────────────────────────────
@@ -731,6 +761,44 @@ export async function handleMessage(
       });
     }
 
+    // Build workflow context for follow-up awareness
+    let workflowContext: string | undefined;
+    try {
+      const recentResultMessages = await messageDb.getRecentWorkflowResultMessages(
+        conversation.id,
+        3
+      );
+      if (recentResultMessages.length > 0) {
+        const workflowResults: WorkflowResultContext[] = recentResultMessages.map(msg => {
+          let workflowName = 'unknown';
+          let runId = 'unknown';
+          try {
+            const parsed =
+              typeof msg.metadata === 'string' ? JSON.parse(msg.metadata) : msg.metadata;
+            const meta = parsed as {
+              workflowResult?: { workflowName?: string; runId?: string };
+            };
+            workflowName = meta.workflowResult?.workflowName ?? 'unknown';
+            runId = meta.workflowResult?.runId ?? 'unknown';
+          } catch (metaErr) {
+            // Malformed metadata — use defaults
+            getLog().warn(
+              { err: metaErr as Error, conversationId, messageId: msg.id },
+              'orchestrator.workflow_result_metadata_parse_failed'
+            );
+          }
+          return { workflowName, runId, summary: msg.content };
+        });
+        workflowContext = formatWorkflowContextSection(workflowResults);
+      }
+    } catch (error) {
+      getLog().warn(
+        { err: error as Error, conversationId },
+        'orchestrator.workflow_context_fetch_failed'
+      );
+      // Non-critical — continue without context
+    }
+
     const fullPrompt = buildFullPrompt(
       conversation,
       codebases,
@@ -738,7 +806,8 @@ export async function handleMessage(
       message,
       issueContext,
       threadContext,
-      attachedFiles
+      attachedFiles,
+      workflowContext
     );
     const cwd = getArchonWorkspacesPath();
 
@@ -751,17 +820,41 @@ export async function handleMessage(
       });
     }
 
-    // 5. Send to AI client
-    const aiClient = getAssistantClient(conversation.ai_assistant_type);
+    // 5. Send to AI provider
+    const aiClient = getAgentProvider(conversation.ai_assistant_type);
     getLog().debug({ assistantType: conversation.ai_assistant_type }, 'sending_to_ai');
 
     // Reuse the config already loaded during workflow discovery (avoids a second disk read).
     // Fall back to loadConfig only when no codebase is scoped (discoveredConfig is undefined).
     const config = discoveredConfig ?? (await loadConfig());
-    const requestOptions: AssistantRequestOptions = {
-      ...(conversation.ai_assistant_type === 'claude' && config.assistants.claude.settingSources
-        ? { settingSources: config.assistants.claude.settingSources }
-        : {}),
+    const providerKey = conversation.ai_assistant_type;
+    let dbEnvVars: Record<string, string> = {};
+    if (conversation.codebase_id) {
+      try {
+        dbEnvVars = await getCodebaseEnvVars(conversation.codebase_id);
+      } catch (error) {
+        getLog().warn(
+          { err: error as Error, codebaseId: conversation.codebase_id },
+          'codebase_env_vars_load_failed'
+        );
+      }
+    }
+    const effectiveEnv = { ...(config.envVars ?? {}), ...dbEnvVars };
+
+    // Warn if provider doesn't support env injection but env vars are configured
+    if (Object.keys(effectiveEnv).length > 0) {
+      const providerCaps = getProviderCapabilities(providerKey);
+      if (!providerCaps.envInjection) {
+        getLog().warn(
+          { provider: providerKey, envVarCount: Object.keys(effectiveEnv).length },
+          'orchestrator.unsupported_env_injection'
+        );
+      }
+    }
+
+    const requestOptions: SendQueryOptions = {
+      assistantConfig: config.assistants[providerKey] ?? {},
+      env: Object.keys(effectiveEnv).length > 0 ? effectiveEnv : undefined,
     };
 
     const mode = platform.getStreamingMode();
@@ -824,14 +917,14 @@ async function handleStreamMode(
   originalMessage: string,
   codebases: readonly Codebase[],
   workflows: readonly WorkflowDefinition[],
-  aiClient: ReturnType<typeof getAssistantClient>,
+  aiClient: ReturnType<typeof getAgentProvider>,
   fullPrompt: string,
   cwd: string,
   session: { id: string; assistant_session_id: string | null },
   isolationHints: HandleMessageContext['isolationHints'],
   conversation: Conversation,
   issueContext?: string,
-  requestOptions?: AssistantRequestOptions
+  requestOptions?: SendQueryOptions
 ): Promise<void> {
   const allMessages: string[] = [];
   let newSessionId: string | undefined;
@@ -873,8 +966,19 @@ async function handleStreamMode(
       if (!commandDetected && platform.sendStructuredEvent) {
         await platform.sendStructuredEvent(conversationId, msg);
       }
-    } else if (msg.type === 'result' && msg.sessionId) {
-      newSessionId = msg.sessionId;
+    } else if (msg.type === 'result') {
+      if (msg.sessionId) {
+        newSessionId = msg.sessionId;
+      }
+      if (msg.isError) {
+        getLog().warn({ conversationId, errorSubtype: msg.errorSubtype }, 'ai_result_error');
+        const syntheticError = new Error(msg.errorSubtype ?? 'AI result error');
+        await platform.sendMessage(conversationId, classifyAndFormatError(syntheticError));
+        if (newSessionId) {
+          await tryPersistSessionId(session.id, newSessionId);
+        }
+        return;
+      }
       if (!commandDetected && platform.sendStructuredEvent) {
         await platform.sendStructuredEvent(conversationId, msg);
       }
@@ -940,14 +1044,14 @@ async function handleBatchMode(
   originalMessage: string,
   codebases: readonly Codebase[],
   workflows: readonly WorkflowDefinition[],
-  aiClient: ReturnType<typeof getAssistantClient>,
+  aiClient: ReturnType<typeof getAgentProvider>,
   fullPrompt: string,
   cwd: string,
   session: { id: string; assistant_session_id: string | null },
   isolationHints: HandleMessageContext['isolationHints'],
   conversation: Conversation,
   issueContext?: string,
-  requestOptions?: AssistantRequestOptions
+  requestOptions?: SendQueryOptions
 ): Promise<void> {
   const allChunks: { type: string; content: string }[] = [];
   const assistantMessages: string[] = [];
@@ -985,8 +1089,19 @@ async function handleBatchMode(
         allChunks.push({ type: 'tool', content: toolMessage });
         getLog().debug({ toolName: msg.toolName }, 'tool_call');
       }
-    } else if (msg.type === 'result' && msg.sessionId) {
-      newSessionId = msg.sessionId;
+    } else if (msg.type === 'result') {
+      if (msg.sessionId) {
+        newSessionId = msg.sessionId;
+      }
+      if (msg.isError) {
+        getLog().warn({ conversationId, errorSubtype: msg.errorSubtype }, 'ai_result_error');
+        const syntheticError = new Error(msg.errorSubtype ?? 'AI result error');
+        await platform.sendMessage(conversationId, classifyAndFormatError(syntheticError));
+        if (newSessionId) {
+          await tryPersistSessionId(session.id, newSessionId);
+        }
+        return;
+      }
     }
 
     if (!commandDetected && allChunks.length > MAX_BATCH_TOTAL_CHUNKS) {
@@ -1189,11 +1304,12 @@ async function handleRegisterProject(
     return `Project "${projectName}" is already registered (path: ${alreadyExists.default_cwd}).`;
   }
 
-  // Create codebase record
+  // Use config default provider instead of hardcoding 'claude'
+  const config = await loadConfig();
   const codebase = await codebaseDb.createCodebase({
     name: projectName,
     default_cwd: projectPath,
-    ai_assistant_type: 'claude',
+    ai_assistant_type: config.assistant,
   });
 
   getLog().info(

packages/core/src/orchestrator/orchestrator-isolation.test.ts

@@ -50,14 +50,14 @@ mock.module('../handlers/command-handler', () => ({
   })),
 }));
 
-mock.module('../clients/factory', () => ({
-  getAssistantClient: mock(() => null),
+mock.module('@archon/providers', () => ({
+  getAgentProvider: mock(() => null),
 }));
 
 mock.module('../workflows/store-adapter', () => ({
   createWorkflowDeps: mock(() => ({
     store: {},
-    getAssistantClient: () => ({}),
+    getAgentProvider: () => ({}),
     loadConfig: async () => ({}),
   })),
 }));
@@ -176,7 +176,6 @@ function makeCodebase(overrides?: Partial<Codebase>): Codebase {
     id: 'cb-1',
     name: 'test-repo',
     default_cwd: '/workspace/test-repo',
-    allow_env_keys: false,
     commands: {},
     created_at: new Date(),
     updated_at: new Date(),

packages/core/src/orchestrator/orchestrator.test.ts

@@ -79,11 +79,11 @@ mock.module('../handlers/command-handler', () => ({
   parseCommand: mockParseCommand,
 }));
 
-// AI client mock
-const mockGetAssistantClient = mock(() => null);
+// AI provider mock
+const mockGetAgentProvider = mock(() => null);
 
-mock.module('../clients/factory', () => ({
-  getAssistantClient: mockGetAssistantClient,
+mock.module('@archon/providers', () => ({
+  getAgentProvider: mockGetAgentProvider,
 }));
 
 // Workflow mocks
@@ -96,7 +96,7 @@ const mockFindWorkflow = mock((name: string, workflows: readonly WorkflowDefinit
 mock.module('../workflows/store-adapter', () => ({
   createWorkflowDeps: mock(() => ({
     store: {},
-    getAssistantClient: () => ({}),
+    getAgentProvider: () => ({}),
     loadConfig: async () => ({}),
   })),
 }));
@@ -216,7 +216,6 @@ const mockCodebase: Codebase = {
   repository_url: 'https://github.com/user/repo',
   default_cwd: '/workspace/test-project',
   ai_assistant_type: 'claude',
-  allow_env_keys: false,
   commands: {},
   created_at: new Date(),
   updated_at: new Date(),
@@ -274,7 +273,7 @@ function clearAllMocks(): void {
   mockTransitionSession.mockClear();
   mockHandleCommand.mockClear();
   mockParseCommand.mockClear();
-  mockGetAssistantClient.mockClear();
+  mockGetAgentProvider.mockClear();
   mockDiscoverWorkflows.mockClear();
   mockExecuteWorkflow.mockClear();
   mockFindWorkflow.mockClear();
@@ -457,7 +456,7 @@ describe('orchestrator-agent handleMessage', () => {
     mockGetActiveSession.mockResolvedValue(null);
     mockCreateSession.mockResolvedValue(mockSession);
     mockTransitionSession.mockResolvedValue(mockSession);
-    mockGetAssistantClient.mockReturnValue(mockClient);
+    mockGetAgentProvider.mockReturnValue(mockClient);
     mockDiscoverWorkflows.mockResolvedValue({ workflows: [], errors: [] });
     mockParseCommand.mockImplementation((message: string) => {
       const parts = message.split(/\s+/);
@@ -479,7 +478,7 @@ describe('orchestrator-agent handleMessage', () => {
 
       expect(mockHandleCommand).toHaveBeenCalled();
       expect(platform.sendMessage).toHaveBeenCalledWith('chat-456', 'Status info');
-      expect(mockGetAssistantClient).not.toHaveBeenCalled();
+      expect(mockGetAgentProvider).not.toHaveBeenCalled();
     });
 
     test('delegates /help to command handler', async () => {
@@ -676,7 +675,7 @@ describe('orchestrator-agent handleMessage', () => {
       await handleMessage(platform, 'chat-456', 'hello');
 
       expect(mockTransitionSession).not.toHaveBeenCalled();
-      // Should pass existing assistant_session_id to AI client
+      // Should pass existing assistant_session_id to AI provider
       expect(mockClient.sendQuery).toHaveBeenCalledWith(
         expect.any(String),
         expect.any(String),
@@ -699,8 +698,8 @@ describe('orchestrator-agent handleMessage', () => {
 
   // ─── settingSources forwarding ────────────────────────────────────────
 
-  describe('settingSources forwarding', () => {
-    test('passes settingSources from config to AI client for claude', async () => {
+  describe('assistantConfig forwarding', () => {
+    test('passes assistantConfig with settingSources for claude', async () => {
       mockLoadConfig.mockResolvedValueOnce({
         botName: 'Archon',
         assistant: 'claude',
@@ -725,11 +724,13 @@ describe('orchestrator-agent handleMessage', () => {
         expect.any(String),
         expect.any(String),
         expect.anything(),
-        expect.objectContaining({ settingSources: ['project', 'user'] })
+        expect.objectContaining({
+          assistantConfig: expect.objectContaining({ settingSources: ['project', 'user'] }),
+        })
       );
     });
 
-    test('does not pass settingSources for non-claude assistant', async () => {
+    test('passes codex assistantConfig for codex assistant', async () => {
       const codexConversation: Conversation = {
         ...mockConversation,
         ai_assistant_type: 'codex',
@@ -754,15 +755,16 @@ describe('orchestrator-agent handleMessage', () => {
           yield { type: 'result', sessionId: 'codex-session' };
         }),
       };
-      mockGetAssistantClient.mockReturnValueOnce(codexClient);
+      mockGetAgentProvider.mockReturnValueOnce(codexClient);
 
       await handleMessage(platform, 'chat-456', 'hello');
 
-      // settingSources should NOT be in requestOptions since assistant type is codex
+      // Should pass codex assistantConfig, not claude's
       const callArgs = codexClient.sendQuery.mock.calls[0];
       const requestOptions = callArgs?.[3] as Record<string, unknown> | undefined;
       expect(requestOptions).toBeDefined();
       expect(requestOptions).not.toHaveProperty('settingSources');
+      expect(requestOptions?.assistantConfig).toBeDefined();
     });
   });
 
@@ -1151,10 +1153,11 @@ describe('orchestrator-agent handleMessage', () => {
 
       await handleMessage(platform, 'chat-456', 'help');
 
+      // Discovery is called positionally with (cwd, loadConfig) — no options arg.
+      // Home-scoped workflows (~/.archon/workflows/) are discovered internally.
       expect(mockDiscoverWorkflows).toHaveBeenCalledWith(
         '/home/test/.archon/workspaces',
-        expect.any(Function),
-        { globalSearchPath: '/home/test/.archon' }
+        expect.any(Function)
       );
     });