diff --git a/.archon/commands/defaults/archon-fix-issue.md b/.archon/commands/defaults/archon-fix-issue.md
index 516ae4d22d..335b421429 100644
--- a/.archon/commands/defaults/archon-fix-issue.md
+++ b/.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
diff --git a/.archon/commands/defaults/archon-implement-issue.md b/.archon/commands/defaults/archon-implement-issue.md
index 66f7411b10..4a8c980552 100644
--- a/.archon/commands/defaults/archon-implement-issue.md
+++ b/.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
diff --git a/.archon/commands/defaults/archon-implement.md b/.archon/commands/defaults/archon-implement.md
index 4bcd7bf1c5..605d3020d8 100644
--- a/.archon/commands/defaults/archon-implement.md
+++ b/.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
 
diff --git a/.archon/commands/defaults/archon-plan-setup.md b/.archon/commands/defaults/archon-plan-setup.md
index 812d0f8246..668b74c69f 100644
--- a/.archon/commands/defaults/archon-plan-setup.md
+++ b/.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
 
diff --git a/.archon/commands/e2e-echo-command.md b/.archon/commands/e2e-echo-command.md
new file mode 100644
index 0000000000..7d67fa3e2c
--- /dev/null
+++ b/.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>
diff --git a/.archon/scripts/echo-args.js b/.archon/scripts/echo-args.js
new file mode 100644
index 0000000000..140a9ae4c9
--- /dev/null
+++ b/.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() }));
diff --git a/.archon/scripts/echo-py.py b/.archon/scripts/echo-py.py
new file mode 100644
index 0000000000..a4f565218c
--- /dev/null
+++ b/.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()}))
diff --git a/.archon/workflows/defaults/archon-adversarial-dev.yaml b/.archon/workflows/defaults/archon-adversarial-dev.yaml
index 2ab207dc03..68722c8b1a 100644
--- a/.archon/workflows/defaults/archon-adversarial-dev.yaml
+++ b/.archon/workflows/defaults/archon-adversarial-dev.yaml
@@ -101,7 +101,9 @@ nodes:
         "status": "running"
       }
       STATEEOF
-      sed -i "s/SPRINT_COUNT_PLACEHOLDER/$SPRINT_COUNT/" "$ARTIFACTS/state.json"
+      STATE_TMP="$ARTIFACTS/state.json.tmp"
+      sed "s/SPRINT_COUNT_PLACEHOLDER/$SPRINT_COUNT/" "$ARTIFACTS/state.json" > "$STATE_TMP"
+      mv "$STATE_TMP" "$ARTIFACTS/state.json"
 
       echo "{\"totalSprints\": $SPRINT_COUNT, \"appDir\": \"$ARTIFACTS/app\", \"artifactsDir\": \"$ARTIFACTS\"}"
     timeout: 30000
diff --git a/.archon/workflows/e2e-claude-smoke.yaml b/.archon/workflows/e2e-claude-smoke.yaml
new file mode 100644
index 0000000000..29cd10c3b4
--- /dev/null
+++ b/.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]
diff --git a/.archon/workflows/e2e-codex-smoke.yaml b/.archon/workflows/e2e-codex-smoke.yaml
new file mode 100644
index 0000000000..f24336b36e
--- /dev/null
+++ b/.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]
diff --git a/.archon/workflows/e2e-deterministic.yaml b/.archon/workflows/e2e-deterministic.yaml
new file mode 100644
index 0000000000..48e2288855
--- /dev/null
+++ b/.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
diff --git a/.archon/workflows/e2e-mixed-providers.yaml b/.archon/workflows/e2e-mixed-providers.yaml
new file mode 100644
index 0000000000..9f5c408a37
--- /dev/null
+++ b/.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]
diff --git a/.archon/workflows/e2e-pi-all-nodes-smoke.yaml b/.archon/workflows/e2e-pi-all-nodes-smoke.yaml
new file mode 100644
index 0000000000..15abb3bb0b
--- /dev/null
+++ b/.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
diff --git a/.archon/workflows/e2e-pi-smoke.yaml b/.archon/workflows/e2e-pi-smoke.yaml
new file mode 100644
index 0000000000..af8c2164f8
--- /dev/null
+++ b/.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]
diff --git a/.archon/workflows/e2e-worktree-disabled.yaml b/.archon/workflows/e2e-worktree-disabled.yaml
new file mode 100644
index 0000000000..4c1948e62a
--- /dev/null
+++ b/.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
diff --git a/.archon/workflows/repo-triage.yaml b/.archon/workflows/repo-triage.yaml
new file mode 100644
index 0000000000..0dac0b5577
--- /dev/null
+++ b/.archon/workflows/repo-triage.yaml
@@ -0,0 +1,1588 @@
+name: repo-triage
+description: >-
+  Periodic repo maintenance — in parallel, triages open issues (labels +
+  dedup detection + 3-day auto-close) and cross-references open PRs against
+  open issues (conservative: suggests Closes #X only when a PR fully
+  addresses an issue, never closes anything itself). State is persisted
+  under .archon/state/ so prior runs are remembered. Designed for periodic
+  runs; safe to re-run; idempotent.
+interactive: false
+
+# Read-only triage runs directly in the live checkout. Creating a worktree
+# every run would be wasted work (nothing is mutated) and would scatter stale
+# branches under ~/.archon/workspaces/<owner>/<repo>/worktrees/.
+worktree:
+  enabled: false
+
+nodes:
+  # ---------------------------------------------------------------------------
+  # Issue triage — runs concurrently with pr-link (no depends_on between them).
+  # ---------------------------------------------------------------------------
+  - id: triage-issues
+    model: sonnet
+    allowed_tools: [Bash, Read, Write, Task]
+    agents:
+      brief-gen:
+        description: >-
+          Reads a single GitHub issue and returns a concise JSON brief,
+          plus a template-adherence check if the caller provided template
+          context. Used for duplicate detection + template-fill reporting.
+        model: haiku
+        tools: [Bash, Read]
+        prompt: |
+          You are a concise GitHub issue summariser. The caller's prompt
+          will include an issue number AND (optionally) the issue
+          templates from `.github/ISSUE_TEMPLATE/`.
+
+          Fetch the issue:
+            gh issue view <N> --json number,title,body,labels,author
+
+          Return ONLY a single JSON object — no fences, no prose:
+
+          {
+            "number": <N>,
+            "summary": "2-3 sentence neutral summary",
+            "primarySymptom": "one short sentence — the core symptom or ask",
+            "area": "best-guess tag, e.g. backend, frontend, docs, core, isolation, cli, workflows, providers",
+            "templateAdherence": {
+              "templateType": "bug_report | feature_request | other | none",
+              "sectionsFilled": ["<section headers where the reporter wrote non-trivial content>"],
+              "sectionsMissing": ["<template section headers clearly left empty or untouched>"],
+              "quality": "good | partial | empty | no-template-context"
+            }
+          }
+
+          Template-adherence rules:
+          - If the caller did NOT include templates → `quality: "no-template-context"`, skip sections.
+          - `quality: "good"` = most template sections have real content.
+          - `quality: "partial"` = headers present but several sections look blank/placeholder.
+          - `quality: "empty"` = body has nothing matching the template shape.
+          - A section counts as MISSING when its body is empty, whitespace-only,
+            or contains only HTML-comment placeholders like `<!-- ... -->`.
+            Such sections must go in `sectionsMissing`, NOT `sectionsFilled`.
+
+          Be terse. If the issue body is empty, set area='unknown' and
+          quality='empty'.
+
+          ERROR HANDLING — if the `gh issue view` call fails (auth,
+          rate limit, network, or non-zero exit), do NOT emit JSON.
+          Instead print exactly one line on stdout:
+              ERROR: <one-line reason>
+          The orchestrator detects the `ERROR:` prefix and handles it
+          (logs, counts, may abort). Never emit partial/fabricated JSON.
+    prompt: |
+      You are the issue-triage orchestrator for the repository in the
+      current working directory.
+
+      # Mode check — READ THIS FIRST
+
+      Run once at the start:
+          echo "DRY_RUN=${DRY_RUN:-0}"
+
+      If DRY_RUN=1 — READ-ONLY mode:
+        - Do all read-only work (gh list/view/api, state file reads, clustering).
+        - For every mutation you WOULD have made (label, comment, close,
+          state write), print a line prefixed `[DRY] would ...` with the
+          full body you would have posted.
+        - Do NOT run `gh issue (comment|close|edit)`. Do NOT use the Write
+          tool on `.archon/state/*.json`.
+        - When delegating via Task to triage-agent/brief-gen, PREPEND this
+          exact sentence to every Task prompt:
+              "DRY_RUN=1 is active. Do NOT apply labels or mutate the
+               issue in any way. Instead print `[DRY] would ...` lines
+               describing what you would have done."
+        - End with the standard summary table, but prefix the title
+          `## (DRY RUN) Issue triage — <now>`.
+
+      Your job on every (non-dry) run:
+        1. Apply labels to any unlabeled open issues (delegate to triage-agent)
+        2. Generate or refresh briefs for new/changed open issues (delegate to brief-gen)
+        3. Detect potential duplicates across all briefs
+        4. Comment on suspected duplicates with a "reply in 3 days or auto-close" note
+        5. Auto-close stale warnings from prior runs whose authors never replied
+        6. Persist state so future runs remember what's already been processed
+
+      # State file
+
+      Location: `.archon/state/triage-state.json` (relative to repo root).
+      Before reading or writing, ensure the directory exists:
+
+          mkdir -p .archon/state
+
+      Shape — on first run the file may not exist; treat missing as:
+
+          {
+            "version": 1,
+            "lastRunAt": null,
+            "briefs": {},
+            "pendingDedupComments": {}
+          }
+
+      - `briefs[<issueNumber>]`: { sha, summary, primarySymptom, area, briefedAt }
+          - `sha`: short digest of `title + "\n" + body + "\n" + updatedAt`,
+            e.g. `printf '%s\n%s\n%s' "$T" "$B" "$U" | shasum | cut -c1-12`.
+      - `pendingDedupComments[<issueNumber>]`: { canonical, botCommentId, postedAt }
+          - `postedAt`: ISO-8601 UTC (`date -u +%FT%TZ`).
+          - `botCommentId`: the comment ID from `gh issue comment` — if you
+            can't parse one, keep the full returned URL.
+
+      # Step-by-step
+
+      ## 1. Read state
+      ```
+      cat .archon/state/triage-state.json 2>/dev/null
+      ```
+      Parse handling:
+        - ENOENT (file missing) → start from default shape above.
+        - Empty file (zero bytes / whitespace only) → start from default shape.
+        - JSON.parse THROWS (corrupt state) → ABORT the node loudly.
+          Print: `[triage-issues] ABORT: .archon/state/triage-state.json
+          is corrupt — refusing to reset tracked state. Restore from a
+          backup (check git history if tracked, or a local timestamped
+          copy) or delete the file to start fresh.`
+          Then stop the node with a non-zero status. Do NOT fall through
+          to default — that would silently reset `pendingDedupComments`
+          and restart the 3-day auto-close clock indefinitely.
+
+      ## 2. Fetch all open issues
+      ```
+      gh issue list --state open \
+        --json number,title,body,author,labels,comments,createdAt,updatedAt \
+        --limit 200 > "$ARTIFACTS_DIR/issues.json"
+      ```
+      (`gh issue list` already excludes PRs.)
+
+      Also read issue templates ONCE at this point for the template-
+      adherence check downstream:
+      ```
+      for tpl in .github/ISSUE_TEMPLATE/*.md; do
+        [ -f "$tpl" ] && printf '### %s\n```\n' "$(basename "$tpl")" && cat "$tpl" && printf '\n```\n\n'
+      done > "$ARTIFACTS_DIR/issue-templates.md"
+      ```
+      If no templates exist, the file will be empty — that's fine.
+
+      ## 3. Classify work
+      For each open issue:
+        - If `labels` is empty → needs LABEL.
+        - Compute sha. If no entry in `state.briefs[N]` OR stored sha differs
+          → needs BRIEF. Otherwise reuse the cached brief.
+
+      ## 4. LABEL PASS — parallel fan-out to triage-agent
+
+      PREFLIGHT: verify the on-disk sub-agent definition exists before
+      attempting any Task call:
+
+          test -f .claude/agents/triage-agent.md
+
+      If missing, SKIP the whole label pass (do not attempt Task calls
+      that would fail obscurely at runtime). Log:
+          "[triage-issues] label pass skipped: .claude/agents/triage-agent.md
+           missing — install the skill-adjacent agent file to enable labeling."
+      Continue to the brief pass — labeling is a nice-to-have, not a blocker.
+
+      Spawn the existing on-disk `triage-agent` sub-agent in PARALLEL (a
+      single assistant turn with multiple Task tool calls — this matters
+      for speed). Per-task prompt:
+
+          "Triage open issue #<N> in this repository. Fetch it via
+           `gh issue view`, classify by type/effort/priority/area, and
+           apply the missing label categories via `gh issue edit`.
+           Respect existing labels."
+
+      Wait for all label tasks to settle before moving on.
+
+      ## 5. BRIEF PASS — parallel fan-out to brief-gen
+      For every issue that needs a brief, spawn the inline `brief-gen`
+      sub-agent in PARALLEL (single turn, multiple Task calls).
+
+      Per-task prompt template:
+          "Brief issue #<N>.
+
+           <if issue-templates.md has content, inline it here with a header>
+           ISSUE TEMPLATES (for templateAdherence check):
+           <file contents>"
+
+      If `$ARTIFACTS_DIR/issue-templates.md` is empty, omit the template
+      block — brief-gen will return `quality: "no-template-context"`.
+
+      Parse each response as JSON. On parse failure OR when the response
+      starts with `ERROR:` (sub-agent signalling a gh/auth/rate-limit
+      problem — see brief-gen prompt):
+        - Log the failed issue number and the first 200 chars of the
+          raw response.
+        - Track in a `failedBriefs` array for the summary (`failed=N`
+          with the list of numbers).
+        - Do NOT merge into state (keep the previous cached brief).
+      Merge successful results into `state.briefs[N]` with a freshly
+      computed sha and `briefedAt = now-iso`. Preserve `templateAdherence`.
+
+      If `failedBriefs.length > 0` AND the failures look systemic
+      (≥50% of briefs this run failed), ABORT before the cluster pass
+      — a broken briefing run produces bad clusters. Report the counts.
+
+      ## 6. CLUSTER PASS — detect duplicates
+      Using fresh + cached briefs:
+        - Group issues whose `summary` + `primarySymptom` describe the
+          same underlying problem. Prefer matches where `area` is the same.
+        - A cluster of size 1 is NOT a duplicate — skip.
+        - For each cluster of 2+: the oldest (lowest number) is `canonical`.
+        - Members already in `state.pendingDedupComments` are already
+          tracked — SKIP. Everything else is a NEW dedup to act on.
+
+      Be CONSERVATIVE. False negatives are fine — this workflow re-runs.
+      False positives create noise. If two issues share a surface keyword
+      but describe different root causes, do not cluster.
+
+      ## 7. ACT PASS — comment + track
+      For each NEW dedup candidate #N with canonical #C:
+        - Post a comment on #N:
+
+              @<reporter-of-N> this looks like it may overlap with #<C>.
+              Could you confirm whether it's a duplicate? If there is no
+              reply within 3 days this issue will be auto-closed.
+
+          Via: `gh issue comment <N> --body "..."` — capture the comment ID.
+        - Record in state:
+              pendingDedupComments[N] = {
+                canonical: C,
+                botCommentId: "<id>",
+                postedAt: "<now-iso>"
+              }
+
+      Post sequentially (not via Task) so you can reliably capture each
+      comment ID.
+
+      ## 8. RECONCILE PASS — 3-day auto-close
+      Cache the bot's GitHub login once at the top of the run:
+          gh api user --jq .login
+
+      For each entry `(N, { canonical, botCommentId, postedAt })`:
+        - Fetch current comments: `gh issue view <N> --json comments`
+        - Identify comments created AFTER `postedAt` whose author is NOT
+          the cached bot login.
+        - If ANY non-bot reply after `postedAt` → drop entry from state
+          (humans are engaged).
+        - VALIDATE `postedAt` parses as ISO-8601 first. If it doesn't
+          parse (corrupt state), LOG and SKIP this entry — do NOT close
+          on a bad timestamp, do NOT skip silently. Leave the entry in
+          state for operator review.
+        - Else if `now - postedAt >= 3 days`:
+            - Post closing comment on #N:
+                  "Auto-closing: no reply within 3 days of the duplicate
+                   check. Please reopen if this is still relevant."
+            - `gh issue close <N> --reason "not planned"` — capture
+              exit code. If non-zero (network, rate limit, issue
+              already-closed-elsewhere), DO NOT drop state: set
+              `closeAttemptFailed: true` on the entry for retry next
+              run, and log the failure.
+            - ONLY drop entry from state on close success (exit 0).
+        - Else → keep the entry as-is (will be revisited next run).
+
+      ## 9. SAVE
+      Set `state.lastRunAt = <now-iso>`. Use the Write tool to persist
+      `.archon/state/triage-state.json` as formatted JSON (2-space indent).
+
+      ## 10. Summary output
+      Print a single compact block:
+
+          ## Issue triage — <now>
+          Labels applied:         <N>
+          Briefs: fresh=<N>, cached=<M>, failed=<K>
+          New dedup clusters:     <N>
+          Dedup comments posted:  <N>
+          Auto-closed this run:   <N>
+          Still pending (waiting on reply): <N>
+          Template fill (of issues briefed this run):
+            good=<N>, partial=<N>, empty=<N>, no-template-context=<N>
+            Issues with empty templates (#):
+              <list of up to 10 numbers, rest truncated "… +K more">
+
+      No other prose.
+
+      # Guardrails
+
+      - NEVER close an issue that is not tracked in `pendingDedupComments`
+        with `postedAt` ≥ 3 days ago AND no reply after that timestamp.
+      - NEVER label issues yourself — always delegate to `triage-agent`.
+      - If `gh` returns an auth error or rate limit, stop the run cleanly
+        and report in the summary. Do NOT partially mutate state.
+      - State writes are ATOMIC per run — only write the final merged
+        state once at step 9. If a pass fails midway, the previous state
+        remains.
+      - Parallel Task fan-out is strict: ONE assistant turn with MANY
+        Task tool calls, not sequential Task calls.
+
+  # ---------------------------------------------------------------------------
+  # Closed-dedup check — follow-up to triage-issues. Checks whether any
+  # currently open issue duplicates a recently-closed one (reporter may not
+  # have noticed their case is already fixed or declined). Reads open-issue
+  # briefs from the state file produced by triage-issues as its context
+  # artifact. Runs in parallel with link-prs once triage-issues is done.
+  # ---------------------------------------------------------------------------
+  - id: closed-dedup-check
+    depends_on: [triage-issues]
+    model: sonnet
+    allowed_tools: [Bash, Read, Write, Task]
+    agents:
+      closed-brief-gen:
+        description: >-
+          Reads a single recently-CLOSED GitHub issue and returns a JSON
+          brief including close reason and any closing PR reference.
+        model: haiku
+        tools: [Bash, Read]
+        prompt: |
+          You are a concise summariser for CLOSED GitHub issues. You will
+          be given an issue number in the caller's prompt.
+
+          Fetch the issue with:
+            gh issue view <N> --json number,title,body,stateReason,closedAt,comments,labels
+
+          Also check the closing comment thread for any `#<pr>` reference
+          that looks like it closed the issue (keywords: closed by, fixed by,
+          resolved by, Closes, Fixes, Resolves).
+
+          Return ONLY a single JSON object on stdout — no fences, no prose:
+
+          {
+            "number": <N>,
+            "summary": "2-3 sentence summary of what the issue was",
+            "primarySymptom": "one short sentence — the core symptom",
+            "area": "single best-guess area tag (same vocabulary as open briefs)",
+            "closedAt": "<ISO timestamp>",
+            "stateReason": "completed | not_planned | duplicate | null (normalize gh CLI's UPPERCASE output to lowercase)",
+            "resolvedByPr": "<PR number if identifiable from closing thread, else null>"
+          }
+
+          Be terse. If `stateReason` (normalized to lowercase) is
+          `not_planned` or `duplicate`, that matters for the match
+          verdict downstream — include it honestly.
+
+          ERROR HANDLING — if `gh issue view` fails, print exactly:
+              ERROR: <one-line reason>
+          on a single stdout line. Do NOT emit partial/fabricated JSON.
+    prompt: |
+      You check whether any currently OPEN issue duplicates a recently
+      CLOSED one. A reporter may have filed a bug that was fixed months
+      ago under a different number, or one that was already declined.
+
+      # Mode check — READ FIRST
+
+      Run once:
+          echo "DRY_RUN=${DRY_RUN:-0} SKIP_CLOSED_DEDUP=${SKIP_CLOSED_DEDUP:-0}"
+
+      If SKIP_CLOSED_DEDUP=1 — print
+          "Skipping closed-dedup-check per SKIP_CLOSED_DEDUP=1"
+      and exit immediately. No gh calls, no state read, no Task fan-out.
+
+      If DRY_RUN=1 — READ-ONLY:
+        - Do read-only work (gh list/view, state reads, clustering).
+        - For every mutation (comment, close, state write), print `[DRY] would ...`.
+        - Do NOT run gh issue comment/close.
+        - Do NOT use Write on `.archon/state/*.json`.
+        - When spawning closed-brief-gen via Task, prepend to its prompt:
+              "DRY_RUN=1 is active. Run only read-only gh commands."
+        - End with a summary prefixed `## (DRY RUN) Closed-dedup check — <now>`.
+
+      # Context artifact from triage-issues
+
+      Open-issue briefs live in:
+          .archon/state/triage-state.json
+
+      Schema (written by the triage-issues node earlier in this run):
+
+          {
+            "version": 1,
+            "lastRunAt": "...",
+            "briefs": { "<number>": { sha, summary, primarySymptom, area, briefedAt } },
+            "pendingDedupComments": { ... }
+          }
+
+      Distinguish "upstream didn't run / crashed" from "upstream ran
+      with nothing to process" via `lastRunAt`:
+
+        - File missing OR JSON.parse throws → treat as upstream-crashed.
+          Print: "[closed-dedup-check] SKIP: triage-state.json missing
+          or corrupt — upstream triage-issues node likely failed. Fix
+          that run before retrying."
+        - File present with `lastRunAt == null` → same upstream-crashed
+          message.
+        - File present with `lastRunAt` set AND `briefs` empty → print
+          "No open-issue briefs to cross-match — nothing to do." and exit.
+          (This is a legitimate quiet day.)
+        - Otherwise → proceed.
+
+      # State file (this node)
+
+      Separate file to isolate concerns from triage-issues:
+          .archon/state/closed-dedup-state.json
+
+      Default shape when missing:
+
+          {
+            "version": 1,
+            "lastRunAt": null,
+            "closedBriefs": {},
+            "closedMatchComments": {}
+          }
+
+      - `closedBriefs[<closedIssue>]`: { sha, summary, primarySymptom, area, closedAt, stateReason, resolvedByPr, briefedAt }
+      - `closedMatchComments[<openIssue>]`: { matchedClosed, botCommentId, postedAt }
+
+      `mkdir -p .archon/state` before any write.
+
+      # Step-by-step
+
+      ## 1. Read both state files
+      - Read `.archon/state/triage-state.json` — grab `briefs` (open-issue briefs).
+      - Read `.archon/state/closed-dedup-state.json`:
+          ENOENT / empty → default shape. JSON.parse throw → ABORT loudly
+          (same rule as triage-issues step 1: never silently reset
+          tracked state; corrupt file means a backup restore or explicit
+          deletion, never a reset).
+
+      ## 2. Fetch recently-closed issues (last 90 days)
+      Compute cutoff:
+          CUTOFF=$(date -u -v-90d +%Y-%m-%d 2>/dev/null || date -u -d '90 days ago' +%Y-%m-%d)
+
+      Fetch:
+          gh issue list --state closed --limit 200 \
+            --json number,title,body,labels,stateReason,closedAt \
+            --search "closed:>${CUTOFF}" > "$ARTIFACTS_DIR/closed-issues.json"
+
+      Filter out any closed issue whose `stateReason` (case-insensitive) matches `duplicate`
+      — those are noise for our matching (they were already dedup'd against canonical).
+      Note: `gh issue view --json stateReason` returns UPPERCASE (`COMPLETED`, `NOT_PLANNED`,
+      `DUPLICATE`), while the `gh issue close --reason` flag wants lowercase with a space
+      (`"completed"`, `"not planned"`). Lowercase-compare downstream.
+
+      ## 3. Classify work
+      For each closed issue:
+        - Compute sha of `title + "\n" + body + "\n" + closedAt`.
+        - If `state.closedBriefs[N]` exists AND sha matches → reuse.
+        - Else → needs BRIEF.
+
+      ## 4. BRIEF PASS — parallel Task fan-out to closed-brief-gen
+      Spawn `closed-brief-gen` in PARALLEL (single assistant turn, multiple
+      Task calls) for every closed issue needing a brief. Per-task prompt:
+
+          "Brief closed issue #<N>."
+
+      Parse each JSON response. On parse failure OR `ERROR:` sentinel:
+      log the issue number + first 200 chars, track in `failedClosedBriefs`,
+      skip. Merge successes into `state.closedBriefs`. Abort the cluster
+      pass if ≥50% failed (same rule as triage-issues).
+
+      ## 5. CROSS-CLUSTER PASS — match open vs closed
+      For each OPEN issue brief (from triage-state.json):
+        - Find the best match (if any) among `closedBriefs`. Same
+          conservative rules as triage-issues:
+            - `area` should match
+            - `primarySymptom` + `summary` should describe the same problem
+            - SKIP weak keyword-only matches
+        - Pick at most ONE closed match per open issue (the strongest).
+
+      A match that is ALREADY recorded in `state.closedMatchComments[<open>]`
+      → SKIP (already acted on).
+
+      Everything else is a NEW closed-dedup candidate.
+
+      ## 6. ACT PASS — comment + track
+      For each NEW candidate (open #O → closed #C):
+
+        - Fetch the reporter's login (not stored in briefs):
+              gh issue view <O> --json author --jq .author.login
+
+        - Build the comment body (tag the reporter):
+
+              @<reporter-of-O> this looks like it may have been resolved
+              by #<C> (closed <date> as <stateReason><if resolvedByPr: ",
+              via PR #<pr>">). Could you check whether that fix addresses
+              your case? If there is no reply within 3 days this issue will
+              be auto-closed.
+
+        - Post: `gh issue comment <O> --body "..."`
+          Capture comment ID.
+        - Record in state:
+              closedMatchComments[O] = {
+                matchedClosed: C,
+                botCommentId: "<id>",
+                postedAt: "<now-iso>"
+              }
+
+      Post sequentially (not via Task) so you can capture comment IDs.
+
+      ## 7. RECONCILE PASS — 3-day auto-close
+      Cache bot login once at top-of-run: `gh api user --jq .login`.
+
+      For each entry `(O, { matchedClosed, botCommentId, postedAt })` in
+      `state.closedMatchComments`:
+        - Fetch: `gh issue view <O> --json comments`
+        - Find comments AFTER `postedAt` whose author is NOT the bot.
+        - If reporter replied → drop entry (engaged).
+        - VALIDATE `postedAt` parses as ISO-8601 first. If not: log and
+          skip this entry; never close on a bad timestamp.
+        - Else if `now - postedAt >= 3 days`:
+            - Post closing comment:
+                  "Auto-closing: no reply within 3 days of the closed-match
+                   check. Please reopen if your case is NOT resolved by
+                   #<matchedClosed>."
+            - `gh issue close <O> --reason "not planned"` — capture exit
+              code. On non-zero: set `closeAttemptFailed: true` on the
+              entry for retry, log the failure, do NOT drop state.
+            - Only drop entry on exit 0.
+            - Drop entry from state.
+        - Else → keep as-is.
+
+      ## 8. SAVE
+      Set `state.lastRunAt = <now-iso>`. Write
+      `.archon/state/closed-dedup-state.json` with the Write tool
+      (2-space JSON).
+
+      ## 9. Summary output
+          ## Closed-dedup check — <now>
+          Open briefs loaded:          <N>   (from triage-issues)
+          Closed issues in window:     <N>   (last 90 days, non-duplicate)
+          Closed briefs: fresh=<N>, cached=<M>, failed=<K>
+          New closed-match candidates: <N>
+          Comments posted:             <N>
+          Auto-closed this run:        <N>
+          Still pending (waiting on reply): <N>
+
+      # Guardrails
+      - NEVER close an open issue unless it's been tracked in
+        `closedMatchComments` for ≥3 days AND had no non-bot reply.
+      - Be MORE conservative here than triage-issues — false positives
+        suggest a reporter's bug is already fixed when it isn't, and that
+        erodes trust. When in doubt, skip.
+      - If `gh` errors (auth, rate limit), abort cleanly and summarise.
+      - State writes are ATOMIC — one Write at step 8.
+      - Parallel Task fan-out required for step 4 only. Step 6 is sequential
+        to capture comment IDs reliably.
+
+  # ---------------------------------------------------------------------------
+  # Closed-PR dedup check — standalone. For each OPEN PR, checks whether a
+  # recently-CLOSED PR covered the same change (superseded, rejected, or
+  # merged variant). Comments only — NEVER closes an open PR (author's work
+  # is too valuable to discard without consent). Runs in parallel with the
+  # other top-level nodes.
+  # ---------------------------------------------------------------------------
+  - id: closed-pr-dedup-check
+    model: sonnet
+    allowed_tools: [Bash, Read, Write, Task]
+    agents:
+      pr-brief-gen:
+        description: >-
+          Reads a single PR (open OR closed) and returns a compact JSON
+          brief suitable for cross-comparison.
+        model: haiku
+        tools: [Bash, Read]
+        prompt: |
+          You summarise a single GitHub PR. You will be given a PR number
+          and a `state` hint (open/closed) in the caller's prompt.
+
+          Fetch:
+            gh pr view <N> --json number,title,body,state,headRefName,changedFiles,additions,deletions,mergedAt,closedAt,stateReason
+            gh pr diff <N> --color=never | head -c 30000
+
+          Return ONLY a single JSON object — no fences, no prose:
+
+          {
+            "number": <N>,
+            "state": "open" | "closed" | "merged",
+            "stateReason": "<closed reason if applicable, else null>",
+            "title": "<title>",
+            "summary": "2-3 sentence neutral summary of what the PR changes",
+            "intent": "one-sentence core goal (bug fix X, add feature Y, refactor Z)",
+            "scope": "affected-area tag (backend/frontend/docs/core/providers/etc)",
+            "filesChanged": <count>,
+            "mergedAt": "<iso or null>",
+            "closedAt": "<iso or null>"
+          }
+
+          Be terse. Don't quote commit messages verbatim unless they are
+          the only information available.
+
+          If the diff was truncated (you hit the 30,000-char limit when
+          reading `gh pr diff`), set `diffTruncated: true` on the brief
+          output so the orchestrator knows to be more conservative about
+          `fully-addresses` claims.
+
+          ERROR HANDLING — if `gh pr view` or `gh pr diff` fails, print:
+              ERROR: <one-line reason>
+          on a single stdout line. Do NOT emit partial/fabricated JSON.
+    prompt: |
+      You find OPEN PRs that duplicate or supersede a recently-CLOSED PR.
+      A contributor may have missed that a similar change was already
+      merged, rejected, or abandoned — flag it so a maintainer can decide.
+
+      # Mode check — READ FIRST
+
+      Run once:
+          echo "DRY_RUN=${DRY_RUN:-0} SKIP_CLOSED_PR_DEDUP=${SKIP_CLOSED_PR_DEDUP:-0}"
+
+      If SKIP_CLOSED_PR_DEDUP=1 — print
+          "Skipping closed-pr-dedup-check per SKIP_CLOSED_PR_DEDUP=1"
+      and exit immediately.
+
+      If DRY_RUN=1 — READ-ONLY:
+        - All read-only gh calls OK.
+        - Do NOT run `gh pr comment`. Do NOT use Write on state files.
+        - Print `[DRY] would ...` for every mutation.
+        - When spawning pr-brief-gen via Task, prepend:
+              "DRY_RUN=1 is active. Run only read-only gh commands."
+        - End with a summary prefixed `## (DRY RUN) Closed-PR dedup — <now>`.
+
+      # State file
+
+      Location: `.archon/state/closed-pr-dedup-state.json`.
+      `mkdir -p .archon/state` before any write.
+
+      Default shape when missing:
+
+          {
+            "version": 1,
+            "lastRunAt": null,
+            "openBriefs": {},
+            "closedBriefs": {},
+            "closedMatchComments": {}
+          }
+
+      - `openBriefs[<prNumber>]`: { sha, brief-fields..., briefedAt }
+      - `closedBriefs[<prNumber>]`: { sha, brief-fields..., briefedAt }
+      - `closedMatchComments[<openPr>]`: { matchedClosed, botCommentId, postedAt }
+
+      # Step-by-step
+
+      ## 1. Read state
+      ```
+      cat .archon/state/closed-pr-dedup-state.json 2>/dev/null
+      ```
+      Parse JSON:
+        ENOENT / empty → default shape. JSON.parse throw → ABORT loudly
+        (never silently reset tracked state; corrupt file means a backup
+        restore or explicit deletion, never a reset).
+
+      ## 2. Fetch PRs
+      Compute the cutoff:
+          CUTOFF=$(date -u -v-90d +%Y-%m-%d 2>/dev/null || date -u -d '90 days ago' +%Y-%m-%d)
+
+      ```
+      gh pr list --state open --limit 100 \
+        --json number,title,body,headRefName,updatedAt,author \
+        > "$ARTIFACTS_DIR/open-prs.json"
+
+      gh pr list --state closed --limit 200 \
+        --json number,title,body,state,closedAt,mergedAt \
+        --search "closed:>${CUTOFF}" \
+        > "$ARTIFACTS_DIR/closed-prs.json"
+      ```
+
+      (`--state closed` includes both merged and non-merged closed PRs.)
+
+      ## 3. Classify work
+      For both open and closed PRs:
+        - Compute a sha of `title + "\n" + body + "\n" + (mergedAt ?? closedAt ?? headRefName)`.
+        - If an entry exists in the corresponding `state.{open,closed}Briefs`
+          and the sha matches → reuse the cached brief.
+        - Else → needs BRIEF.
+
+      ## 4. BRIEF PASS — parallel Task fan-out to pr-brief-gen
+      Spawn `pr-brief-gen` in PARALLEL for every PR needing a brief
+      (open AND closed, all in a single assistant turn if possible — the
+      sub-agent handles both via the `state` hint).
+
+      Per-task prompt template:
+          "Brief PR #<N> — state=<open|closed>."
+
+      Parse each JSON response. On parse failure OR `ERROR:` sentinel:
+      log the PR number + first 200 chars, track in `failedBriefs`, skip.
+      Merge successes into the appropriate `{open,closed}Briefs` bucket.
+      Abort the cluster pass if ≥50% failed.
+
+      ## 5. CROSS-CLUSTER PASS — match open vs closed
+      For each OPEN PR brief:
+        - Find the strongest match among `closedBriefs`. Match rules (all
+          should broadly agree before declaring a duplicate):
+            - `scope` matches
+            - `intent` is substantially the same (not just same area)
+            - `title` is semantically close OR the diffs plausibly touch
+              the same files (look at `filesChanged` counts + bodies)
+        - Pick at most ONE closed match per open PR.
+
+      Skip open PRs already in `state.closedMatchComments`.
+
+      Be STRICT. PR duplication calls are higher-stakes than issue
+      duplication — suggesting a maintainer's merged change already did
+      the work of someone's open PR is embarrassing if wrong. When in
+      doubt, skip.
+
+      ## 6. ACT PASS — comment + record
+      For each NEW candidate (open PR #O → closed PR #C):
+
+        - Determine the close flavour for the comment text (always tag
+          the open PR's author):
+            - If `closedBriefs[C].state == "merged"` →
+                "@<pr-author> this PR looks similar to the already-merged
+                 #<C> (merged <date>). Please check whether your change
+                 is still needed — rebase on main and confirm."
+            - Else (closed unmerged) →
+                "@<pr-author> this PR looks similar to #<C>, which was
+                 closed on <date> (<stateReason>). You may want to read
+                 the discussion there before pushing further."
+
+        - Idempotency: fetch `gh pr view <O> --json comments`. If the
+          fetch fails (non-zero exit), SKIP POSTING and log the error —
+          never fall through to post-anyway (that would double-post on
+          every gh hiccup). Only when the fetch succeeds AND no existing
+          comment has the same body do we proceed.
+
+        - Post: `gh pr comment <O> --body "..."`. Capture comment ID.
+
+        - Record in state:
+              closedMatchComments[O] = {
+                matchedClosed: C,
+                botCommentId: "<id>",
+                postedAt: "<now-iso>"
+              }
+
+      Post sequentially (not via Task) for reliable comment-ID capture.
+
+      NO auto-close. PRs are author work product; closing them without
+      consent discards effort. A reminder comment is the right ceiling.
+      Entries stay in `closedMatchComments` indefinitely (never reconciled)
+      so we never re-post on the same PR.
+
+      ## 7. SAVE
+      Set `state.lastRunAt = <now-iso>`. Write
+      `.archon/state/closed-pr-dedup-state.json` with the Write tool.
+
+      ## 8. Summary output
+          ## Closed-PR dedup — <now>
+          Open PRs scanned:             <N>
+          Closed PRs in window:         <N>   (last 90 days)
+          Briefs: fresh_open=<N>, cached_open=<N>, fresh_closed=<N>, cached_closed=<N>, failed=<N>
+          New closed-match candidates:  <N>
+          Comments posted:              <N>
+          Total tracked matches (all time): <N>
+
+      # Guardrails
+      - NEVER close an open PR. Comment only.
+      - Idempotent comments — always check existing PR comments before
+        posting to avoid noise.
+      - State writes are ATOMIC — one Write at step 7.
+      - Parallel Task fan-out for step 4 only. Step 6 sequential.
+      - Strict matching — false positives on PR dedup are a maintainer
+        trust hit. When ambiguous, skip.
+
+  # ---------------------------------------------------------------------------
+  # PR ↔ issue linker — runs concurrently with triage-issues.
+  # ---------------------------------------------------------------------------
+  - id: link-prs
+    model: sonnet
+    allowed_tools: [Bash, Read, Write, Task]
+    agents:
+      pr-issue-matcher:
+        description: >-
+          Given one PR (title + body + diff) and a compact list of open
+          issues, returns related-issue matches AND a template-adherence
+          check if the caller provided the PR template. Conservative —
+          prefers "related" over "fully-addresses" when in doubt.
+        model: haiku
+        tools: [Bash, Read]
+        prompt: |
+          You match a single GitHub PR to the open issues it touches AND
+          score its adherence to the repository's PR template (if the
+          caller provided one).
+
+          Inputs in the caller's prompt:
+            - PR number
+            - Compact issue list (one per line: `#<N> <title> — <body excerpt>`)
+            - Optional PR_TEMPLATE section
+
+          Your work:
+            1. Fetch the PR:
+                 gh pr view <N> --json number,title,body,files,headRefName
+            2. Fetch a compact diff:
+                 gh pr diff <N> --color=never | head -c 60000
+            3. For each open issue, decide:
+               - `fully-addresses`: PR's scope CLEARLY covers EVERY symptom
+                 in the issue. Err strictly toward "related" if unsure.
+               - `related`: touches same area / partial fix.
+               - `unrelated`: omit.
+            4. Score template adherence against the PR_TEMPLATE (if present):
+               - Enumerate the `(required)` sections and other section
+                 headers from the template.
+               - Mark each section as filled (non-trivial reporter content)
+                 or missing (empty / placeholder / HTML-comment-only).
+
+          Return ONLY a single JSON object — no fences, no prose:
+
+          {
+            "prNumber": <N>,
+            "candidates": [
+              {
+                "issue": <issueNumber>,
+                "relation": "fully-addresses" | "related",
+                "evidence": "one-sentence justification citing files/symptoms"
+              }
+            ],
+            "templateAdherence": {
+              "sectionsFilled": ["<section titles with real content>"],
+              "sectionsMissing": ["<empty / placeholder section titles>"],
+              "requiredMissing": ["<subset of sectionsMissing that are marked (required)>"],
+              "quality": "good | partial | empty | no-template-context"
+            }
+          }
+
+          `quality` scale:
+          - "good" = required sections all filled AND most non-required too
+          - "partial" = some required sections empty but not all
+          - "empty" = essentially no template content beyond headers
+          - "no-template-context" = caller didn't include PR_TEMPLATE
+
+          No matches: candidates=[]. Always return templateAdherence
+          (may be no-template-context).
+
+          Default bias: when the PR description doesn't explicitly claim
+          to close the issue, mark it `related`, never `fully-addresses`.
+
+          ERROR HANDLING — if `gh pr view` or `gh pr diff` fails, print:
+              ERROR: <one-line reason>
+          on a single stdout line. Do NOT emit partial/fabricated JSON.
+    prompt: |
+      You are the PR-to-issue linker for the repository in the current
+      working directory.
+
+      # Mode check — READ THIS FIRST
+
+      Run once at the start:
+          echo "DRY_RUN=${DRY_RUN:-0} SKIP_PR_LINK=${SKIP_PR_LINK:-0}"
+
+      If SKIP_PR_LINK=1 — print exactly:
+          "Skipping link-prs per SKIP_PR_LINK=1 — no state read, no gh
+           calls, no comments."
+      and exit immediately. Do not read state, do not call gh, do not
+      use Task. This is the "staged rollout" escape hatch for the first
+      live run of the full workflow.
+
+      If DRY_RUN=1 — READ-ONLY mode:
+        - Do all read-only work (gh list/view/diff, state reads, matching).
+        - For every mutation you WOULD have made (PR/issue comment, state
+          write), print a line prefixed `[DRY] would ...` with the full
+          body you would have posted on which target.
+        - Do NOT run `gh issue comment` or `gh pr comment`. Do NOT use
+          the Write tool on `.archon/state/*.json`.
+        - When delegating via Task to pr-issue-matcher, PREPEND this exact
+          sentence to every Task prompt:
+              "DRY_RUN=1 is active. Run only read-only gh commands."
+          (pr-issue-matcher is already read-only, so this is belt-and-braces.)
+        - End with the standard summary table, but prefix the title
+          `## (DRY RUN) PR-issue linker — <now>`.
+
+      Your job on every (non-dry, non-skipped) run:
+        1. For every open PR not yet fully processed, identify related
+           open issues via the pr-issue-matcher sub-agent.
+        2. Add a `Closes #X` SUGGESTION comment on the PR only when the
+           matcher says the PR fully addresses the issue AND you — the
+           orchestrator — agree after re-reading the issue + PR diff.
+        3. Otherwise post a conservative "related to #X" cross-reference
+           comment on the PR, plus a mirror comment on the issue.
+        4. Persist state to avoid re-commenting on the same link.
+
+      # State file
+
+      Location: `.archon/state/pr-state.json`. `mkdir -p .archon/state`
+      before any write.
+
+      Default shape when missing:
+
+          {
+            "version": 1,
+            "lastRunAt": null,
+            "linkedPrs": {}
+          }
+
+      - `linkedPrs[<prNumber>]`: {
+           sha,                 # digest of title + body + headRefName
+           processedAt,
+           related: [<issueNumber>, ...],
+           fullyAddresses: [<issueNumber>, ...],
+           templateAdherence: { quality, requiredMissing, sectionsFilled, sectionsMissing },
+           templateNudgedAt: "<iso>",   # set only when we posted a template-nudge comment
+           commentIds: {                # bot-comment IDs for everything we posted,
+             fullyAddresses: { "<issue>": "<id>", ... },  #   keyed by target issue.
+             related: {
+               pr:    { "<issue>": "<id>", ... },         # comment on this PR referencing issue
+               issue: { "<issue>": "<id>", ... }          # mirror comment on the issue
+             },
+             templateNudge: "<id>"      # comment on this PR nudging template fill
+           }
+         }
+
+      # Step-by-step
+
+      ## 1. Read state
+      ```
+      cat .archon/state/pr-state.json 2>/dev/null
+      ```
+      Parse JSON:
+        ENOENT / empty → default shape. JSON.parse throw → ABORT loudly
+        (never silently reset tracked state; corrupt file means a backup
+        restore or explicit deletion, never a reset).
+
+      ## 2. Fetch
+      ```
+      gh pr list --state open \
+        --json number,title,body,headRefName,author,updatedAt \
+        --limit 100 > "$ARTIFACTS_DIR/prs.json"
+
+      gh issue list --state open \
+        --json number,title,body,labels,author \
+        --limit 200 > "$ARTIFACTS_DIR/issues.json"
+      ```
+
+      Also read the PR template ONCE for the template-adherence check:
+      ```
+      if [ -f .github/pull_request_template.md ]; then
+        cp .github/pull_request_template.md "$ARTIFACTS_DIR/pr-template.md"
+      elif [ -f .github/PULL_REQUEST_TEMPLATE.md ]; then
+        cp .github/PULL_REQUEST_TEMPLATE.md "$ARTIFACTS_DIR/pr-template.md"
+      else
+        : > "$ARTIFACTS_DIR/pr-template.md"   # empty = no template in repo
+      fi
+      ```
+      If the file is empty, skip the entire template-adherence behavior
+      below (matcher returns `quality: "no-template-context"`).
+
+      ## 3. Classify
+      For each open PR:
+        - Compute sha of `title + "\n" + body + "\n" + headRefName`.
+        - If `state.linkedPrs[N]` exists AND its sha matches → SKIP.
+        - Else → needs MATCHING.
+
+      ## 4. MATCH PASS — parallel Task fan-out to pr-issue-matcher
+      Spawn `pr-issue-matcher` in PARALLEL for every PR needing matching
+      (single turn, multiple Task calls).
+
+      Per-task prompt template:
+          "Match PR #<N> against the open issues below.
+           <issues list — one per line: `#<num> <title> — <first 120 chars of body>`>
+
+           <if pr-template.md is non-empty, append:>
+           PR_TEMPLATE (for templateAdherence scoring):
+           <file contents>"
+
+      Keep the issue list compact. Parse each response as JSON. On parse
+      failure OR `ERROR:` sentinel: log the PR number + first 200 chars,
+      track in `failedMatches`, skip that PR. Preserve the full
+      `templateAdherence` object in `state.linkedPrs[<pr>]` for the
+      digest downstream. Abort the downstream passes if ≥50% of PRs
+      failed matching (same half-failure rule as the briefing passes).
+
+      ## 5. VERIFY PASS — confirm any "fully-addresses"
+      Haiku is optimistic; Sonnet (you) owns the final judgment. For each
+      candidate tagged `fully-addresses`:
+        - Read issue body fully: `gh issue view <issue> --json body,title,labels`
+        - Read PR body + diff:   `gh pr view <pr> --json body,title`
+                                 `gh pr diff <pr> --color=never`
+        - Decide: does the PR's change set plausibly resolve EVERY
+          symptom/ask in the issue body? If ANY part is out of scope,
+          ambiguous, or only partially addressed → DOWNGRADE to `related`.
+
+      When in doubt, downgrade.
+
+      Additional rule for PR-vs-closed-PR matches (`closed-pr-dedup-check`
+      feeds this pattern too): if either side's brief has
+      `diffTruncated: true`, the evidence is partial — downgrade any
+      `fully-addresses`-shaped claim to `related` by default, since we
+      can't be confident about unseen diff regions.
+
+      ## 6. ACT PASS — comment + record
+      Before posting ANY comment, check idempotency: fetch existing
+      comments on the target (`gh pr view <pr> --json comments` /
+      `gh issue view <issue> --json comments`) and skip if a comment with
+      the same body already exists.
+
+      For each PR's confirmed candidates:
+
+        - `fully-addresses` (post-verify):
+            - If the PR body does NOT already contain `Closes #<issue>`
+              / `Fixes #<issue>` / `Resolves #<issue>` (case-insensitive):
+              post a PR comment tagging the PR author:
+
+                  "@<pr-author> this PR appears to fully address #<issue>.
+                   Consider adding `Closes #<issue>` to the PR body so
+                   the issue auto-closes on merge."
+
+              Capture the returned comment ID from the `gh pr comment`
+              URL (the number after `#issuecomment-`) and record it:
+                  state.linkedPrs[<pr>].commentIds.fullyAddresses[<issue>] = "<id>"
+
+            - Add <issue> to `state.linkedPrs[<pr>].fullyAddresses`.
+
+        - `related`:
+            - On the PR (tag the PR author):
+                  "@<pr-author> related to #<issue> — overlapping area or partial fix."
+              Capture ID:
+                  state.linkedPrs[<pr>].commentIds.related.pr[<issue>] = "<id>"
+            - On the issue (tag the issue reporter):
+                  "@<issue-reporter> potentially related to PR #<pr>."
+              Capture ID:
+                  state.linkedPrs[<pr>].commentIds.related.issue[<issue>] = "<id>"
+            - Add <issue> to `state.linkedPrs[<pr>].related`.
+
+      On idempotent SKIP (existing comment found), do NOT attempt to
+      extract an ID — leave the slot absent.
+
+      Post sequentially — don't Task-fan-out this step.
+
+      ## 6b. TEMPLATE NUDGE PASS — auto-comment on low-quality PR fills
+
+      ### First-run grandfather guard
+
+      Before the nudge logic, check whether this is the baseline run.
+      Condition: the `state.linkedPrs` object **as read at the start of
+      this run** (step 1) was empty.
+
+      If baseline → DO NOT POST any template-nudge comments this run.
+      Instead, for every PR that WOULD have been nudged, stamp
+      `state.linkedPrs[<pr>].templateNudgedAt = "<first-run-baseline>"`
+      so future runs treat them as already handled. Print a single line:
+
+          [grandfather] baseline run — snapshotting N PRs without posting
+          nudges. Future runs will only nudge new low-quality PRs.
+
+      Skip the entire rest of this step on the baseline run.
+
+      ### Normal nudge logic (second run onward)
+
+      Only runs if `pr-template.md` is non-empty (i.e. the repo HAS a
+      template). For each PR processed this run whose matcher returned
+      `templateAdherence.quality ∈ {"empty", "partial"}` AND whose
+      `requiredMissing` list is non-empty:
+
+        - Skip if `state.linkedPrs[<pr>].templateNudgedAt` already exists
+          (we've nudged before — don't badger the contributor again).
+        - Skip if the PR is marked `draft` (contributors often fill
+          templates later on drafts).
+        - Build the comment:
+
+              Hi @<pr-author> — thanks for opening this PR.
+
+              This repository uses a PR template at
+              `.github/pull_request_template.md` with several required
+              sections. A few of them appear to be empty or placeholder
+              here:
+
+              - <requiredMissing[0]>
+              - <requiredMissing[1]>
+              - ...
+
+              Could you fill those out (even briefly)? The template
+              helps reviewers understand scope, risk, and rollback — it
+              speeds up review significantly.
+
+              If a section genuinely doesn't apply, just write "N/A" in
+              it rather than leaving it blank.
+
+        - Idempotency: `gh pr view <pr> --json comments` — skip if an
+          existing comment already mentions "pull_request_template.md"
+          or starts with the exact greeting.
+        - Post: `gh pr comment <pr> --body "..."`. Capture the comment ID
+          from the returned URL.
+        - Record in state:
+              state.linkedPrs[<pr>].templateNudgedAt = "<now-iso>"
+              state.linkedPrs[<pr>].commentIds.templateNudge = "<id>"
+
+      Do NOT nudge PRs with `quality: "good"` or `"no-template-context"`.
+
+      ## 7. SAVE
+      For every PR processed this run (success or skip), MERGE into
+      the existing `state.linkedPrs[<pr>]` entry (do NOT replace — that
+      would lose `commentIds` / `templateNudgedAt` / `templateAdherence`
+      captured earlier in this run AND the baseline grandfather flag).
+
+      Merge semantics (spread existing first, then apply this run's updates):
+
+          const existing = state.linkedPrs[<pr>] ?? {};
+          state.linkedPrs[<pr>] = {
+            ...existing,                              // preserves commentIds, templateNudgedAt,
+                                                       // templateAdherence, any prior sha history
+            sha: <new-sha>,
+            processedAt: <now-iso>,
+            related: <this-run-related-array>,
+            fullyAddresses: <this-run-fullyAddresses-array>,
+            templateAdherence: <this-run-adherence-or-existing>,
+            // any commentIds/templateNudgedAt captured during steps 6 + 6b
+            // are already in `existing` and survive the spread
+          };
+
+      Update `state.lastRunAt`. Write `.archon/state/pr-state.json` in
+      ONE Write call at the end of the node.
+
+      ## 8. Summary
+          ## PR-issue linker — <now>
+          PRs scanned:                        <N>
+          PRs newly processed:                <N>
+          Fully-addresses suggestions posted: <N>
+          Related cross-refs posted:          <N>
+          Template nudges posted this run:    <N>
+          PR template fill (of PRs processed this run):
+            good=<N>, partial=<N>, empty=<N>, no-template-context=<N>
+
+      # Guardrails
+
+      - NEVER close an issue. GitHub closes issues on merge via the
+        `Closes #X` keyword — that is the only closure path this workflow
+        endorses.
+      - NEVER add `Closes #X` to the PR body yourself; only SUGGEST via a
+        comment. Maintainers decide.
+      - Default to `related`. Only suggest `fully-addresses` when the
+        evidence is overwhelming.
+      - If `gh` errors out (auth, rate limit), abort cleanly and summarise.
+      - State writes are ATOMIC per run — a single Write at step 7.
+      - Parallel Task fan-out is required for the match pass only. Act
+        pass is sequential for idempotent comment-ID capture.
+      - Template nudge comments happen AT MOST ONCE per PR (tracked via
+        `templateNudgedAt`). Never re-nudge — contributors will ignore us.
+
+  # ---------------------------------------------------------------------------
+  # Stale nudge — standalone. For issues and PRs untouched for STALE_DAYS
+  # (default 60), post a gentle "still relevant?" comment. No auto-close —
+  # this is a reminder, not an ultimatum. Tracked in state so we only
+  # nudge each item once per quiet period.
+  # ---------------------------------------------------------------------------
+  - id: stale-nudge
+    model: sonnet
+    allowed_tools: [Bash, Read, Write]
+    prompt: |
+      You post gentle reminders on GitHub issues and PRs that have gone
+      quiet. No auto-close. No Task fan-out needed — this is direct work.
+
+      # Mode check — READ FIRST
+
+      Run once:
+          echo "DRY_RUN=${DRY_RUN:-0} SKIP_STALE_NUDGE=${SKIP_STALE_NUDGE:-0} STALE_DAYS=${STALE_DAYS:-60}"
+
+      If SKIP_STALE_NUDGE=1 — print
+          "Skipping stale-nudge per SKIP_STALE_NUDGE=1"
+      and exit immediately.
+
+      If DRY_RUN=1 — READ-ONLY. Print `[DRY] would ...` for each would-be
+      comment. Do NOT run `gh issue comment` / `gh pr comment`. Do NOT
+      use Write on the state file. End with summary prefixed `## (DRY RUN)`.
+
+      # State file
+
+      Location: `.archon/state/stale-nudge-state.json`.
+      `mkdir -p .archon/state` before any write.
+
+      Default shape:
+
+          {
+            "version": 1,
+            "lastRunAt": null,
+            "nudged": {}
+          }
+
+      - `nudged["issue/<N>" | "pr/<N>"]`: { nudgedAt, updatedAtAtNudge, botCommentId }
+        - Re-nudge allowed only when the item has been updated AFTER
+          `nudgedAt` AND has gone quiet again for ≥ STALE_DAYS. Otherwise
+          skip — don't spam.
+
+      # Step-by-step
+
+      ## 1. Read state
+      ```
+      cat .archon/state/stale-nudge-state.json 2>/dev/null
+      ```
+      Parse JSON:
+        ENOENT / empty → default shape. JSON.parse throw → ABORT loudly
+        (never silently reset tracked state; corrupt file means a backup
+        restore or explicit deletion, never a reset).
+
+      ## 2. Fetch stale items
+      Compute cutoff (STALE_DAYS ago):
+          DAYS=${STALE_DAYS:-60}
+          CUTOFF=$(date -u -v-${DAYS}d +%Y-%m-%d 2>/dev/null || date -u -d "${DAYS} days ago" +%Y-%m-%d)
+
+      Stale open issues:
+          gh issue list --state open --limit 200 \
+            --json number,title,author,updatedAt,labels \
+            --search "updated:<${CUTOFF}" > "$ARTIFACTS_DIR/stale-issues.json"
+
+      Stale open PRs (skip drafts):
+          gh pr list --state open --limit 100 \
+            --json number,title,author,updatedAt,isDraft \
+            --search "updated:<${CUTOFF}" > "$ARTIFACTS_DIR/stale-prs.json"
+
+      ## 3. Filter
+      For each item:
+        - Skip PRs where `isDraft == true` — drafts are often WIP, nudging
+          them is rude.
+        - Skip any item with a label matching `wontfix`, `blocked`,
+          `needs-maintainer`, `pinned`, `keep-open` (common "do not bother"
+          signals). Check current labels via the fetched JSON.
+        - Skip if `state.nudged["<type>/<N>"]` exists AND the item's
+          `updatedAt` is ≤ `nudgedAt` (nothing has changed since we nudged).
+
+      Everything else is a NEW nudge candidate.
+
+      ## 4. Post nudges (sequential)
+      For each candidate, build the comment body:
+
+        Issues:
+            @<author> this issue has been quiet for <N> days. Is it still
+            relevant? A quick update on current status would help with
+            triage. No reply needed if it's no longer blocking you.
+
+        PRs:
+            @<author> this PR has been quiet for <N> days. Is it still
+            active? Happy to help unblock if review feedback or a rebase
+            is needed — just drop a note.
+
+      Idempotency: `gh {issue,pr} view <N> --json comments` — skip if any
+      existing comment CONTAINS the substring "has been quiet for" (a
+      prefix check fails because the posted body starts with `@<author>`,
+      not the phrase). If the fetch itself fails, SKIP POSTING rather
+      than fall through to post-anyway.
+
+      Post: `gh issue comment <N> --body "..."` / `gh pr comment <N> --body "..."`.
+      Capture the comment ID from the returned URL (the number after
+      `#issuecomment-`).
+      Record: `state.nudged["<type>/<N>"] = {
+                nudgedAt: <now-iso>,
+                updatedAtAtNudge: <item.updatedAt>,
+                botCommentId: "<id>"
+              }`
+
+      ## 5. SAVE
+      Set `state.lastRunAt = <now-iso>`. Write
+      `.archon/state/stale-nudge-state.json`.
+
+      ## 6. Summary
+          ## Stale nudge — <now>
+          STALE_DAYS window:             <N>
+          Stale issues found:            <N>
+          Stale PRs found (non-draft):   <N>
+          Filtered out (labels/draft/already-nudged): <N>
+          New nudges posted — issues:    <N>
+          New nudges posted — PRs:       <N>
+
+      # Guardrails
+
+      - NEVER auto-close here. This node is comment-only, always.
+      - Respect "do-not-bother" labels: wontfix, blocked, needs-maintainer,
+        pinned, keep-open. (Add more via PR if missed.)
+      - One nudge per quiet period. Re-nudge only if the item was updated
+        after the prior nudge AND went quiet again.
+      - If `gh` errors out, abort cleanly. State stays atomic.
+
+  # ---------------------------------------------------------------------------
+  # Digest — runs LAST, after every other node. Reads each prior node's
+  # final assistant output via $<nodeId>.output and synthesises one
+  # maintainer-facing report to $ARTIFACTS_DIR/digest.md. Pure synthesis —
+  # no gh calls, no mutations, no Task fan-out.
+  # ---------------------------------------------------------------------------
+  - id: digest
+    depends_on:
+      - triage-issues
+      - link-prs
+      - closed-dedup-check
+      - closed-pr-dedup-check
+      - stale-nudge
+    model: sonnet
+    allowed_tools: [Bash, Read, Write]
+    prompt: |
+      You synthesise the outputs of all prior nodes in this run into one
+      maintainer-facing digest.
+
+      # Inputs
+
+      Each prior node's final summary is available via variable
+      substitution:
+
+      - $triage-issues.output
+      - $link-prs.output
+      - $closed-dedup-check.output
+      - $closed-pr-dedup-check.output
+      - $stale-nudge.output
+
+      Some may include `(DRY RUN)` prefix or a "Skipping … per SKIP_X=1"
+      line — pass those through honestly.
+
+      You may also read the state files under `.archon/state/` for any
+      counts the summaries omitted, but keep it light — this is a digest,
+      not a re-analysis.
+
+      # Comment-URL index — REQUIRED
+
+      The digest MUST include a direct GitHub URL for every bot comment
+      this run posted. Build URLs from state files.
+
+      Steps:
+
+      1. Determine the repo slug:
+             SLUG=$(gh repo view --json nameWithOwner --jq .nameWithOwner)
+         (example: `coleam00/Archon`)
+
+      2. URL shape:
+             Issue comment: https://github.com/<slug>/issues/<N>#issuecomment-<id>
+             PR    comment: https://github.com/<slug>/pull/<N>#issuecomment-<id>
+
+      3. Sources to read (all optional — missing files mean that node
+         didn't run OR posted nothing):
+
+         a. `.archon/state/triage-state.json` → `pendingDedupComments`
+            Keyed by OPEN ISSUE number → `issues/<N>#issuecomment-<botCommentId>`.
+
+         b. `.archon/state/closed-dedup-state.json` → `closedMatchComments`
+            Keyed by OPEN ISSUE number → `issues/<N>#issuecomment-<botCommentId>`.
+
+         c. `.archon/state/closed-pr-dedup-state.json` → `closedMatchComments`
+            Keyed by OPEN PR number → `pull/<N>#issuecomment-<botCommentId>`.
+
+         d. `.archon/state/pr-state.json` → `linkedPrs[<pr>].commentIds`:
+              - `fullyAddresses[<issue>]` → comment lives ON THE PR:
+                    `pull/<pr>#issuecomment-<id>`
+              - `related.pr[<issue>]`     → `pull/<pr>#issuecomment-<id>`
+              - `related.issue[<issue>]`  → `issues/<issue>#issuecomment-<id>`
+              - `templateNudge`           → `pull/<pr>#issuecomment-<id>`
+            Note: entries may be absent (idempotent skip or pre-IDs run) —
+            in that case list the action without a URL and suffix
+            `(no ID captured)`.
+
+         e. `.archon/state/stale-nudge-state.json` → `nudged`
+            Keys: `"issue/<N>"` → `issues/<N>#issuecomment-<botCommentId>`
+                  `"pr/<N>"`    → `pull/<N>#issuecomment-<botCommentId>`
+
+      4. Include the URLs BOTH inline in the per-node sections (next to
+         the issue/PR number it acted on) AND in a dedicated "Comment
+         index" section at the end grouped by category.
+
+      5. Only surface comments posted IN THIS RUN. Use the `postedAt` /
+         `nudgedAt` timestamps: include entries whose timestamp equals
+         today's run window (≥ this run's start time). Older entries
+         from prior runs should NOT re-appear in the "just posted" tables
+         but DO appear in a separate "carry-forward pending" table so
+         maintainers see what's still on the 3-day clock.
+
+      # Output
+
+      Produce ONE markdown document. Write it to `$ARTIFACTS_DIR/digest.md`
+      using the Write tool. Then print the SAME content to stdout.
+
+      Template:
+
+          # Repo-triage digest — <now-iso>
+
+          _(Dry run)_   ← include this line only if ANY node ran with DRY_RUN=1
+
+          ## Headline numbers
+
+          | Action | Count |
+          |---|---|
+          | Labels applied | N |
+          | New duplicate clusters (open↔open) | N |
+          | New closed-match candidates (open issue ↔ closed issue) | N |
+          | Issues auto-closed this run | N |
+          | PR template nudges posted | N |
+          | Stale nudges (issues) | N |
+          | Stale nudges (PRs) | N |
+          | PR `Closes #X` suggestions posted | N |
+          | PR/issue "related to" cross-refs posted | N |
+          | Open PR vs closed PR duplicate comments | N |
+
+          ## Per-node summaries
+
+          ### triage-issues
+          <verbatim $triage-issues.output, trimmed of log noise>
+
+          ### link-prs
+          <verbatim>
+
+          ### closed-dedup-check
+          <verbatim>
+
+          ### closed-pr-dedup-check
+          <verbatim>
+
+          ### stale-nudge
+          <verbatim>
+
+          ## Template-fill snapshot
+
+          From this run's processed items:
+          - Issues: good=<N>, partial=<N>, empty=<N>, no-template=<N>
+          - PRs:    good=<N>, partial=<N>, empty=<N>, no-template=<N>
+
+          ## Comment index — this run
+
+          Every URL below was posted by this run. Click to jump to the
+          comment on GitHub.
+
+          ### Dedup warnings (open ↔ open) — 3-day clock
+          - #<openIssue> → duplicate of #<canonical> — [comment](https://github.com/<slug>/issues/<N>#issuecomment-<id>)
+
+          ### Closed-issue matches — 3-day clock
+          - #<openIssue> → matched closed #<closedIssue> (<stateReason>) — [comment](URL)
+
+          ### Closed-PR duplicates (info only, no clock)
+          - PR #<openPr> → matched #<closedPr> (<merged|closed unmerged>) — [comment](URL)
+
+          ### PR `Closes #X` suggestions
+          - PR #<pr> → suggest `Closes #<issue>` — [comment](URL)
+
+          ### Related cross-refs
+          - PR #<pr> ↔ issue #<issue>
+            - on PR: [comment](URL)
+            - on issue: [comment](URL)
+
+          ### PR template nudges
+          - PR #<pr> — [comment](URL)
+
+          ### Stale nudges
+          - Issue #<N> — [comment](URL)
+          - PR #<N> — [comment](URL)
+
+          (Omit any section whose list is empty rather than printing a
+          header with "none".)
+
+          ## Carry-forward — still on the 3-day clock from prior runs
+
+          Items whose `postedAt` is OLDER than this run but still pending
+          (no reporter reply yet, not yet auto-closed):
+
+          - #<N> → #<canonical> — posted <ISO>, <days> day(s) elapsed, [comment](URL)
+
+          (Omit the whole section if nothing is pending.)
+
+          ## Pending (waiting on human)
+
+          - Duplicate warnings awaiting reporter reply: <list #N>
+          - Closed-match warnings awaiting reporter reply: <list #N>
+          - PR template nudges sent this run: <list #PR>
+
+          ## Next scheduled run considerations
+
+          - Any items the human should look at before the next run
+            (ambiguous clusters, PR template edge cases, etc.) — 1-3 bullets
+            max. Empty section is fine.
+
+      Keep the digest scannable — a maintainer should be able to assess
+      "did anything need my attention?" in under 30 seconds.
+
+      # Post to Slack (optional)
+
+      AFTER writing `digest.md`, check the env:
+
+          echo "SLACK_WEBHOOK=${SLACK_WEBHOOK:-<unset>}"
+
+      If `SLACK_WEBHOOK` is unset or empty → print
+          "Slack post skipped: SLACK_WEBHOOK not set."
+      and finish. This is the normal path when Slack isn't wired.
+
+      If set, prepare a COMPACT Slack-flavoured variant and post it to
+      the webhook. Rules:
+
+      ## Length budget
+
+      Keep the Slack payload under ~3,500 characters. The full digest
+      stays on disk at `$ARTIFACTS_DIR/digest.md`; Slack gets a summary
+      + the comment-URL index. Never send the whole digest.md to Slack.
+
+      ## Slack mrkdwn rules (NOT standard Markdown)
+
+      - Bold: `*bold*` (NOT `**bold**`)
+      - Italics: `_italic_`
+      - Links: `<https://url|text>` (NOT `[text](url)`)
+      - Lists: use `•` or `-` at line start — no numbered lists
+      - No `##` headers — use a `*Bold line*` instead
+      - No tables — convert to bulleted key/value lines
+      - Code: single-backtick inline, triple-backtick blocks
+
+      ## Payload shape
+
+      Write the Slack text to `$ARTIFACTS_DIR/digest-slack.txt` FIRST
+      (so it lands as a traceable artifact), then read it back into a
+      JSON payload via `jq`:
+
+      ```
+      jq -cn --rawfile t "$ARTIFACTS_DIR/digest-slack.txt" \
+        '{text: $t, mrkdwn: true}' > "$ARTIFACTS_DIR/slack-payload.json"
+      ```
+
+      ## Template for the Slack text
+
+      ```
+      *Repo-triage digest — <now-iso>*
+      <if dry run: _(dry run — no mutations)_>
+
+      *Headline*
+      • Labels applied: <N>
+      • Dedup clusters (open↔open): <N>
+      • Closed-issue matches: <N>
+      • Auto-closed: <N>
+      • PR `Closes #X` suggestions: <N>
+      • Related cross-refs: <N>
+      • Closed-PR duplicates: <N>
+      • PR template nudges: <N>
+      • Stale nudges: <N>
+
+      *Comments posted this run*  (click to jump to GitHub)
+      • #<N> dup of #<canon> → <https://github.com/<slug>/issues/<N>#issuecomment-<id>|comment>
+      • #<N> may be resolved by #<closed> → <URL|comment>
+      • PR #<N> `Closes #<X>` → <URL|comment>
+      • (list every comment — if the total would push past 3,500 chars,
+         collapse the largest category to a single line:
+         "...plus N more related cross-refs")
+
+      *Pending* (3-day clock running)
+      • #<N> → #<canonical>, <M>d elapsed
+      • PR #<N> → closed #<X>
+
+      *Full digest:* `$ARTIFACTS_DIR/digest.md`
+      ```
+
+      Omit sections whose list is empty — don't print a header followed
+      by "none".
+
+      ## Posting
+
+      If `DRY_RUN=1`:
+          Print `[DRY] would POST to Slack (<bytes> chars):` followed by
+          the full payload text. Do NOT curl.
+
+      Otherwise:
+          curl -sS -X POST -H 'Content-Type: application/json' \
+            --data "@$ARTIFACTS_DIR/slack-payload.json" \
+            -w "\nHTTP_STATUS:%{http_code}\n" \
+            "$SLACK_WEBHOOK" 2>&1
+
+      The `-w "\nHTTP_STATUS:%{http_code}"` appends the HTTP status code
+      so TLS/connection/4xx/5xx errors are visible in the captured output.
+      Redirect stderr to stdout (`2>&1`) so TLS errors land in the same
+      stream. Slack returns `ok` (body) + `HTTP_STATUS:200` on success.
+      Treat anything else as failure.
+
+      Capture stdout+stderr. Slack returns `ok` on success, otherwise an
+      error body like `invalid_payload` / `channel_not_found`.
+
+      ## Failure handling
+
+      Slack posting is a side channel, not the source of truth. If curl
+      fails (non-zero exit, non-`ok` body), log the error to stdout but
+      do NOT fail the node — the digest.md on disk is authoritative.
+      Append a line to the node's stdout:
+
+          Slack post FAILED: <curl error or Slack response body>
+
+      # Guardrails
+
+      - No gh calls here. No comments. No closes. Synthesis only.
+      - If any prior node's output is missing or mangled, note it in the
+        corresponding section: "(output unavailable)". Don't invent numbers.
+      - Preserve `(DRY RUN)` markers — readers need to know if counts are
+        hypothetical.
+      - Slack posting is best-effort; digest.md on disk is the source
+        of truth.
diff --git a/.claude/commands/plan-feature.md b/.claude/commands/plan-feature.md
index d4562e0f84..c3a12c4eab 100644
--- a/.claude/commands/plan-feature.md
+++ b/.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.
diff --git a/.claude/commands/prime-backend.md b/.claude/commands/prime-backend.md
index e2ff9dafee..7c34a3bee7 100644
--- a/.claude/commands/prime-backend.md
+++ b/.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
diff --git a/.claude/commands/prime-workflows.md b/.claude/commands/prime-workflows.md
index 25509de48f..464d8f2e67 100644
--- a/.claude/commands/prime-workflows.md
+++ b/.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
diff --git a/.claude/commands/prime.md b/.claude/commands/prime.md
index 50e5f45b4c..0a70ebe35f 100644
--- a/.claude/commands/prime.md
+++ b/.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
diff --git a/.claude/commands/validate.md b/.claude/commands/validate.md
index 7e86a0dae4..658bc00def 100644
--- a/.claude/commands/validate.md
+++ b/.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`)
 
diff --git a/.claude/docs/architecture-deep-dive.md b/.claude/docs/architecture-deep-dive.md
index f5126d6fb4..d5e542b59b 100644
--- a/.claude/docs/architecture-deep-dive.md
+++ b/.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` |
diff --git a/.claude/rules/adapters.md b/.claude/rules/adapters.md
deleted file mode 100644
index d49e683378..0000000000
--- a/.claude/rules/adapters.md
+++ /dev/null
@@ -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
diff --git a/.claude/rules/cli.md b/.claude/rules/cli.md
deleted file mode 100644
index a954b6bd18..0000000000
--- a/.claude/rules/cli.md
+++ /dev/null
@@ -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. `@archon/paths/strip-cwd-env-boot` (first import) removes all Bun-auto-loaded CWD `.env` keys from `process.env`
-2. Loads `~/.archon/.env` with `override: true` (Archon config wins over shell-inherited vars)
-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)
diff --git a/.claude/rules/database.md b/.claude/rules/database.md
deleted file mode 100644
index 0f579cc1a2..0000000000
--- a/.claude/rules/database.md
+++ /dev/null
@@ -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
diff --git a/.claude/rules/dx-quirks.md b/.claude/rules/dx-quirks.md
deleted file mode 100644
index 3d05e1f843..0000000000
--- a/.claude/rules/dx-quirks.md
+++ /dev/null
@@ -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).
diff --git a/.claude/rules/isolation-patterns.md b/.claude/rules/isolation-patterns.md
deleted file mode 100644
index 0e763e03a2..0000000000
--- a/.claude/rules/isolation-patterns.md
+++ /dev/null
@@ -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
diff --git a/.claude/rules/isolation.md b/.claude/rules/isolation.md
deleted file mode 100644
index 1b849e7eca..0000000000
--- a/.claude/rules/isolation.md
+++ /dev/null
@@ -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
diff --git a/.claude/rules/orchestrator.md b/.claude/rules/orchestrator.md
deleted file mode 100644
index acc3d64fa0..0000000000
--- a/.claude/rules/orchestrator.md
+++ /dev/null
@@ -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
diff --git a/.claude/rules/server-api.md b/.claude/rules/server-api.md
deleted file mode 100644
index 912e7db877..0000000000
--- a/.claude/rules/server-api.md
+++ /dev/null
@@ -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
diff --git a/.claude/rules/testing.md b/.claude/rules/testing.md
deleted file mode 100644
index 030f697539..0000000000
--- a/.claude/rules/testing.md
+++ /dev/null
@@ -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
diff --git a/.claude/rules/web-frontend.md b/.claude/rules/web-frontend.md
deleted file mode 100644
index 7811997fde..0000000000
--- a/.claude/rules/web-frontend.md
+++ /dev/null
@@ -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
diff --git a/.claude/rules/workflows.md b/.claude/rules/workflows.md
deleted file mode 100644
index 99cf6f8913..0000000000
--- a/.claude/rules/workflows.md
+++ /dev/null
@@ -1,101 +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
-- `script:` — inline code or named file from `.archon/scripts/`, runs via `runtime: bun` (`.ts`/`.js`) or `runtime: uv` (`.py`), no AI; stdout captured as `$nodeId.output`; supports `deps:` for dependency installation and `timeout:` (ms); runtime availability checked at load time with a warning if binary is missing
-
-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`, `deps` (script nodes only — dependency list), `runtime` (script nodes only — `'bun'` or `'uv'`).
-
-## 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
diff --git a/.claude/skills/archon/guides/setup.md b/.claude/skills/archon/guides/setup.md
index 30c651d70c..b74aa55ab7 100644
--- a/.claude/skills/archon/guides/setup.md
+++ b/.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.
+
+| 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) |
 
-| Location | Used by | Purpose |
-|----------|---------|---------|
-| `~/.archon/.env` | **CLI** | Global infrastructure config — database, AI tokens |
-| `<archon-repo>/.env` | **Server** | Platform tokens for Telegram/Slack/GitHub/Discord |
+**Which should I use?**
 
-**Best practice**: Use `~/.archon/.env` as the single source of truth. Symlink or copy to `<archon-repo>/.env` if running the server.
+- `~/.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.
 
-**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 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)
 
diff --git a/.claude/skills/archon/references/workflow-dag.md b/.claude/skills/archon/references/workflow-dag.md
index aacf5aeca5..eefb380646 100644
--- a/.claude/skills/archon/references/workflow-dag.md
+++ b/.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
 
diff --git a/.claude/skills/test-release/SKILL.md b/.claude/skills/test-release/SKILL.md
index c8cfc3c4f3..31029014ea 100644
--- a/.claude/skills/test-release/SKILL.md
+++ b/.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:
diff --git a/.env.example b/.env.example
index 325e49a6fb..125ad43e98 100644
--- a/.env.example
+++ b/.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
@@ -24,8 +38,27 @@ 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)
@@ -119,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)
@@ -173,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)
diff --git a/.github/workflows/e2e-smoke.yml b/.github/workflows/e2e-smoke.yml
new file mode 100644
index 0000000000..c3ea04c612
--- /dev/null
+++ b/.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"
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index aabb0e05d4..d50be15651 100644
--- a/.github/workflows/release.yml
+++ b/.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:
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index b41d9740bd..7a2e17ef84 100644
--- a/.github/workflows/test.yml
+++ b/.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
 
diff --git a/.gitignore b/.gitignore
index a2f33c5d5c..4b225843ea 100644
--- a/.gitignore
+++ b/.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
diff --git a/.prettierignore b/.prettierignore
index 5f7484c1a6..d0dd71f9bc 100644
--- a/.prettierignore
+++ b/.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/
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 29fb4e1166..887ffe4e94 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.7] - 2026-04-22
+
+Pi community provider, home-scoped workflows/commands/scripts, worktree policy, Web UI approval-gate auto-resume, three-path env model, and a breaking change to Claude Code binary resolution for compiled binary users.
+
+### Added
+
+- **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)
+- **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)
+- **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.
+- **`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.
+- **`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
+
+### Changed
+
+- **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).
+- **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.
+
+### Fixed
+
+- **Web UI approval gates now auto-resume.** Previously, clicking Approve or Reject on a paused workflow from the Web UI only recorded the decision — the workflow never continued, and the user had to send a follow-up chat message (or use the CLI) to resume. Three fixes: (1) orchestrator-agent now threads `parentConversationId` through `executeWorkflow` for every web dispatch, (2) the `POST /approve` and `POST /reject` API handlers dispatch `/workflow run <name> <userMessage>` back through the orchestrator when `parent_conversation_id` is set and points at a web-platform parent (mirrors `workflowApproveCommand`/`workflowRejectCommand` on the CLI; non-web parents skip the auto-resume to prevent cross-adapter misrouting), and (3) the during-streaming status check in the DAG executor tolerates the `paused` state so a concurrent AI node in the same topological layer finishes its own stream rather than being aborted when a sibling approval node pauses the run. The Web UI reject button uses the proper `ConfirmRunActionDialog` with an optional reason textarea (was `window.confirm` in the chat card, and lacked a reason input on the dashboard) — the trimmed reason propagates to `$REJECTION_REASON` in the workflow's `on_reject` prompt. Credits @jonasvanderhaegen for surfacing and diagnosing the bug in #1147 (that PR was 87 commits stale on a dev that had since refactored the reject UX; this is a fresh re-do on current `dev`). Closes #1131.
+- **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.
+- **`MCP server connection failed: <plugin>` noise no longer surfaces in workflow runs.** The dag-executor now loads the workflow node's `mcp:` config file once and filters the SDK's failure message to only the servers the workflow actually configured. User-level Claude plugin MCPs (e.g. `telegram` inherited from `~/.claude/`) that fail to connect in the headless subprocess are debug-logged as `dag.mcp_plugin_connection_suppressed` instead of being forwarded to the conversation. Other provider warnings (⚠️) surface unchanged. Credits @MrFadiAi for reporting the issue in #1134 (that PR was 9 days stale and conflicting; this is a fresh re-do on current `dev`).
+- **`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)
+- **Bumped transitive `axios` to `^1.15.0` via root `overrides` to clear CVE-2025-62718** (NO_PROXY bypass via hostname normalization → potential SSRF). Archon pulls `axios` transitively through `@slack/bolt` and `@slack/web-api`; both semver ranges (`^1.12.0` and `^1.13.5`) accept the override cleanly, so no API surface changes. Credits @stefans71 for identifying and reporting the vulnerability in #1153. Closes #1053.
+- **Stale workspace symlink no longer reported as "not in a git repository" by the CLI.** When `archon workflow run` (or `--resume`) is invoked from a valid git repo whose `~/.archon/workspaces/<owner>/<repo>/source` symlink points somewhere else (common after moving/renaming the checkout), auto-registration fails but the repo is fine. Previously both the worktree-creation and resume paths fell through to the generic `Cannot create worktree: not in a git repository` / `Cannot resume: Not in a git repository` errors — a lie that sent users down the wrong diagnostic path. Both sites now preserve the registration error and throw `Cannot {create worktree,resume}: repository registration failed.` with the original cause and a concrete cleanup hint (`Remove the stale workspace entry at <path> and retry`) when the failure matches the `createProjectSourceSymlink()` shape. Credits @Bortlesboat for identifying the root cause and the parser approach in #1157. Closes #1146.
+- **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)
+
+### 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.
+
 ## [0.3.6] - 2026-04-12
 
 Web UI workflow experience improvements, CWD environment leak protection, and bug fixes.
@@ -179,7 +229,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)
@@ -231,7 +281,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
diff --git a/CLAUDE.md b/CLAUDE.md
index 0e902537dd..f2afd41e9c 100644
--- a/CLAUDE.md
+++ b/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
 
@@ -266,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)
@@ -289,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)
@@ -383,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`)
@@ -401,10 +411,11 @@ import type { DagNode, WorkflowDefinition } from '@/lib/api';
 **Package Split:**
 - **@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/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, AI clients (provides `createWorkflowStore()` adapter bridging core DB → `IWorkflowStore`)
+- **@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`)
@@ -429,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/`)
@@ -439,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
@@ -463,6 +476,11 @@ 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'
@@ -530,7 +548,7 @@ 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)
@@ -549,6 +567,7 @@ curl http://localhost:3637/api/conversations/<conversationId>/messages
 ├── 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
 ```
 
@@ -561,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)
 
@@ -675,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), `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, 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), `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)
@@ -694,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`
-
-**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)
+- **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.
+
+**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
@@ -759,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
@@ -769,7 +797,11 @@ 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:**
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index da3b90faad..c0120a16bd 100644
--- a/CONTRIBUTING.md
+++ b/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
diff --git a/Dockerfile b/Dockerfile
index da4783e019..93a537525b 100644
--- a/Dockerfile
+++ b/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/
 
diff --git a/README.md b/README.md
index 6c4c827783..7ac742f305 100644
--- a/README.md
+++ b/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:
@@ -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)
diff --git a/bun.lock b/bun.lock
index 04517f4fbf..d06d5ccac0 100644
--- a/bun.lock
+++ b/bun.lock
@@ -23,7 +23,7 @@
     },
     "packages/adapters": {
       "name": "@archon/adapters",
-      "version": "0.3.5",
+      "version": "0.3.6",
       "dependencies": {
         "@archon/core": "workspace:*",
         "@archon/git": "workspace:*",
@@ -32,7 +32,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": {
@@ -41,7 +41,7 @@
     },
     "packages/cli": {
       "name": "@archon/cli",
-      "version": "0.3.5",
+      "version": "0.3.6",
       "bin": {
         "archon": "./src/cli.ts",
       },
@@ -51,6 +51,7 @@
         "@archon/git": "workspace:*",
         "@archon/isolation": "workspace:*",
         "@archon/paths": "workspace:*",
+        "@archon/providers": "workspace:*",
         "@archon/server": "workspace:*",
         "@archon/workflows": "workspace:*",
         "@clack/prompts": "^1.0.0",
@@ -62,14 +63,13 @@
     },
     "packages/core": {
       "name": "@archon/core",
-      "version": "0.3.5",
+      "version": "0.3.6",
       "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",
       },
@@ -83,7 +83,7 @@
     },
     "packages/docs-web": {
       "name": "@archon/docs-web",
-      "version": "0.3.5",
+      "version": "0.3.6",
       "dependencies": {
         "@astrojs/starlight": "^0.38.0",
         "astro": "^6.1.0",
@@ -92,7 +92,7 @@
     },
     "packages/git": {
       "name": "@archon/git",
-      "version": "0.3.5",
+      "version": "0.3.6",
       "dependencies": {
         "@archon/paths": "workspace:*",
       },
@@ -102,7 +102,7 @@
     },
     "packages/isolation": {
       "name": "@archon/isolation",
-      "version": "0.3.5",
+      "version": "0.3.6",
       "dependencies": {
         "@archon/git": "workspace:*",
         "@archon/paths": "workspace:*",
@@ -113,11 +113,30 @@
     },
     "packages/paths": {
       "name": "@archon/paths",
-      "version": "0.3.5",
+      "version": "0.3.6",
       "dependencies": {
         "dotenv": "^17",
         "pino": "^9",
         "pino-pretty": "^13",
+        "posthog-node": "^5.29.2",
+      },
+      "peerDependencies": {
+        "typescript": "^5.0.0",
+      },
+    },
+    "packages/providers": {
+      "name": "@archon/providers",
+      "version": "0.3.6",
+      "dependencies": {
+        "@anthropic-ai/claude-agent-sdk": "^0.2.89",
+        "@archon/paths": "workspace:*",
+        "@mariozechner/pi-ai": "^0.67.5",
+        "@mariozechner/pi-coding-agent": "^0.67.5",
+        "@openai/codex-sdk": "^0.116.0",
+        "@sinclair/typebox": "^0.34.41",
+      },
+      "devDependencies": {
+        "pino": "^9",
       },
       "peerDependencies": {
         "typescript": "^5.0.0",
@@ -125,12 +144,13 @@
     },
     "packages/server": {
       "name": "@archon/server",
-      "version": "0.3.5",
+      "version": "0.3.6",
       "dependencies": {
         "@archon/adapters": "workspace:*",
         "@archon/core": "workspace:*",
         "@archon/git": "workspace:*",
         "@archon/paths": "workspace:*",
+        "@archon/providers": "workspace:*",
         "@archon/workflows": "workspace:*",
         "@hono/zod-openapi": "^0.19.6",
         "dotenv": "^17.2.3",
@@ -143,7 +163,7 @@
     },
     "packages/web": {
       "name": "@archon/web",
-      "version": "0.3.5",
+      "version": "0.3.6",
       "dependencies": {
         "@dagrejs/dagre": "^2.0.4",
         "@radix-ui/react-alert-dialog": "^1.1.15",
@@ -195,10 +215,11 @@
     },
     "packages/workflows": {
       "name": "@archon/workflows",
-      "version": "0.3.5",
+      "version": "0.3.6",
       "dependencies": {
         "@archon/git": "workspace:*",
         "@archon/paths": "workspace:*",
+        "@archon/providers": "workspace:*",
         "@hono/zod-openapi": "^0.19.6",
         "zod": "^3.25.28",
       },
@@ -208,6 +229,7 @@
     },
   },
   "overrides": {
+    "axios": "^1.15.0",
     "test-exclude": "^7.0.1",
   },
   "packages": {
@@ -231,6 +253,8 @@
 
     "@archon/paths": ["@archon/paths@workspace:packages/paths"],
 
+    "@archon/providers": ["@archon/providers@workspace:packages/providers"],
+
     "@archon/server": ["@archon/server@workspace:packages/server"],
 
     "@archon/web": ["@archon/web@workspace:packages/web"],
@@ -255,6 +279,72 @@
 
     "@astrojs/telemetry": ["@astrojs/telemetry@3.3.0", "", { "dependencies": { "ci-info": "^4.2.0", "debug": "^4.4.0", "dlv": "^1.1.3", "dset": "^3.1.4", "is-docker": "^3.0.0", "is-wsl": "^3.1.0", "which-pm-runs": "^1.1.0" } }, "sha512-UFBgfeldP06qu6khs/yY+q1cDAaArM2/7AEIqQ9Cuvf7B1hNLq0xDrZkct+QoIGyjq56y8IaE2I3CTvG99mlhQ=="],
 
+    "@aws-crypto/crc32": ["@aws-crypto/crc32@5.2.0", "", { "dependencies": { "@aws-crypto/util": "^5.2.0", "@aws-sdk/types": "^3.222.0", "tslib": "^2.6.2" } }, "sha512-nLbCWqQNgUiwwtFsen1AdzAtvuLRsQS8rYgMuxCrdKf9kOssamGLuPwyTY9wyYblNr9+1XM8v6zoDTPPSIeANg=="],
+
+    "@aws-crypto/sha256-browser": ["@aws-crypto/sha256-browser@5.2.0", "", { "dependencies": { "@aws-crypto/sha256-js": "^5.2.0", "@aws-crypto/supports-web-crypto": "^5.2.0", "@aws-crypto/util": "^5.2.0", "@aws-sdk/types": "^3.222.0", "@aws-sdk/util-locate-window": "^3.0.0", "@smithy/util-utf8": "^2.0.0", "tslib": "^2.6.2" } }, "sha512-AXfN/lGotSQwu6HNcEsIASo7kWXZ5HYWvfOmSNKDsEqC4OashTp8alTmaz+F7TC2L083SFv5RdB+qU3Vs1kZqw=="],
+
+    "@aws-crypto/sha256-js": ["@aws-crypto/sha256-js@5.2.0", "", { "dependencies": { "@aws-crypto/util": "^5.2.0", "@aws-sdk/types": "^3.222.0", "tslib": "^2.6.2" } }, "sha512-FFQQyu7edu4ufvIZ+OadFpHHOt+eSTBaYaki44c+akjg7qZg9oOQeLlk77F6tSYqjDAFClrHJk9tMf0HdVyOvA=="],
+
+    "@aws-crypto/supports-web-crypto": ["@aws-crypto/supports-web-crypto@5.2.0", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-iAvUotm021kM33eCdNfwIN//F77/IADDSs58i+MDaOqFrVjZo9bAal0NK7HurRuWLLpF1iLX7gbWrjHjeo+YFg=="],
+
+    "@aws-crypto/util": ["@aws-crypto/util@5.2.0", "", { "dependencies": { "@aws-sdk/types": "^3.222.0", "@smithy/util-utf8": "^2.0.0", "tslib": "^2.6.2" } }, "sha512-4RkU9EsI6ZpBve5fseQlGNUWKMa1RLPQ1dnjnQoe07ldfIzcsGb5hC5W0Dm7u423KWzawlrpbjXBrXCEv9zazQ=="],
+
+    "@aws-sdk/client-bedrock-runtime": ["@aws-sdk/client-bedrock-runtime@3.1031.0", "", { "dependencies": { "@aws-crypto/sha256-browser": "5.2.0", "@aws-crypto/sha256-js": "5.2.0", "@aws-sdk/core": "^3.974.0", "@aws-sdk/credential-provider-node": "^3.972.31", "@aws-sdk/eventstream-handler-node": "^3.972.14", "@aws-sdk/middleware-eventstream": "^3.972.10", "@aws-sdk/middleware-host-header": "^3.972.10", "@aws-sdk/middleware-logger": "^3.972.10", "@aws-sdk/middleware-recursion-detection": "^3.972.11", "@aws-sdk/middleware-user-agent": "^3.972.30", "@aws-sdk/middleware-websocket": "^3.972.16", "@aws-sdk/region-config-resolver": "^3.972.12", "@aws-sdk/token-providers": "3.1031.0", "@aws-sdk/types": "^3.973.8", "@aws-sdk/util-endpoints": "^3.996.7", "@aws-sdk/util-user-agent-browser": "^3.972.10", "@aws-sdk/util-user-agent-node": "^3.973.16", "@smithy/config-resolver": "^4.4.16", "@smithy/core": "^3.23.15", "@smithy/eventstream-serde-browser": "^4.2.14", "@smithy/eventstream-serde-config-resolver": "^4.3.14", "@smithy/eventstream-serde-node": "^4.2.14", "@smithy/fetch-http-handler": "^5.3.17", "@smithy/hash-node": "^4.2.14", "@smithy/invalid-dependency": "^4.2.14", "@smithy/middleware-content-length": "^4.2.14", "@smithy/middleware-endpoint": "^4.4.30", "@smithy/middleware-retry": "^4.5.3", "@smithy/middleware-serde": "^4.2.18", "@smithy/middleware-stack": "^4.2.14", "@smithy/node-config-provider": "^4.3.14", "@smithy/node-http-handler": "^4.5.3", "@smithy/protocol-http": "^5.3.14", "@smithy/smithy-client": "^4.12.11", "@smithy/types": "^4.14.1", "@smithy/url-parser": "^4.2.14", "@smithy/util-base64": "^4.3.2", "@smithy/util-body-length-browser": "^4.2.2", "@smithy/util-body-length-node": "^4.2.3", "@smithy/util-defaults-mode-browser": "^4.3.47", "@smithy/util-defaults-mode-node": "^4.2.52", "@smithy/util-endpoints": "^3.4.1", "@smithy/util-middleware": "^4.2.14", "@smithy/util-retry": "^4.3.2", "@smithy/util-stream": "^4.5.23", "@smithy/util-utf8": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-ZgiSo2wslPXlv7wK4m2ULu2VfimbVRRlho0DqXhlvZGEqvtC209cMOxfPZWJ79Fz9sf0IzmWFkDtvMYjnwyLfw=="],
+
+    "@aws-sdk/core": ["@aws-sdk/core@3.974.0", "", { "dependencies": { "@aws-sdk/types": "^3.973.8", "@aws-sdk/xml-builder": "^3.972.18", "@smithy/core": "^3.23.15", "@smithy/node-config-provider": "^4.3.14", "@smithy/property-provider": "^4.2.14", "@smithy/protocol-http": "^5.3.14", "@smithy/signature-v4": "^5.3.14", "@smithy/smithy-client": "^4.12.11", "@smithy/types": "^4.14.1", "@smithy/util-base64": "^4.3.2", "@smithy/util-middleware": "^4.2.14", "@smithy/util-utf8": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-8j+dMtyDqNXFmi09CBdz8TY6Ltf2jhfHuP6ZvG4zVjndRc6JF0aeBUbRwQLndbptFCsdctRQgdNWecy4TIfXAw=="],
+
+    "@aws-sdk/credential-provider-env": ["@aws-sdk/credential-provider-env@3.972.26", "", { "dependencies": { "@aws-sdk/core": "^3.974.0", "@aws-sdk/types": "^3.973.8", "@smithy/property-provider": "^4.2.14", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-WBHAMxyPdgeJY6ZGLvq9mJwzZ+GaNUROQbfdVshtMsDVBrZTj5ZuFjKclSjSHvKSHJ4Y4O2yvI/aA/hrJbYfng=="],
+
+    "@aws-sdk/credential-provider-http": ["@aws-sdk/credential-provider-http@3.972.28", "", { "dependencies": { "@aws-sdk/core": "^3.974.0", "@aws-sdk/types": "^3.973.8", "@smithy/fetch-http-handler": "^5.3.17", "@smithy/node-http-handler": "^4.5.3", "@smithy/property-provider": "^4.2.14", "@smithy/protocol-http": "^5.3.14", "@smithy/smithy-client": "^4.12.11", "@smithy/types": "^4.14.1", "@smithy/util-stream": "^4.5.23", "tslib": "^2.6.2" } }, "sha512-+1DwCjjpo1WoiZTN08yGitI3nUwZUSQWVWFrW4C46HqZwACjcUQ7C66tnKPBTVxrEYYDOP11A6Afmu1L6ylt3g=="],
+
+    "@aws-sdk/credential-provider-ini": ["@aws-sdk/credential-provider-ini@3.972.30", "", { "dependencies": { "@aws-sdk/core": "^3.974.0", "@aws-sdk/credential-provider-env": "^3.972.26", "@aws-sdk/credential-provider-http": "^3.972.28", "@aws-sdk/credential-provider-login": "^3.972.30", "@aws-sdk/credential-provider-process": "^3.972.26", "@aws-sdk/credential-provider-sso": "^3.972.30", "@aws-sdk/credential-provider-web-identity": "^3.972.30", "@aws-sdk/nested-clients": "^3.996.20", "@aws-sdk/types": "^3.973.8", "@smithy/credential-provider-imds": "^4.2.14", "@smithy/property-provider": "^4.2.14", "@smithy/shared-ini-file-loader": "^4.4.9", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-Fg1oJcoijwOZjTxdbx+ubqbQl8YEQ4Cwhjw6TWzQjuDEvQYNhnCXW2pN7eKtdTrdE4a6+5TVKGSm2I+i2BKIQg=="],
+
+    "@aws-sdk/credential-provider-login": ["@aws-sdk/credential-provider-login@3.972.30", "", { "dependencies": { "@aws-sdk/core": "^3.974.0", "@aws-sdk/nested-clients": "^3.996.20", "@aws-sdk/types": "^3.973.8", "@smithy/property-provider": "^4.2.14", "@smithy/protocol-http": "^5.3.14", "@smithy/shared-ini-file-loader": "^4.4.9", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-nchIrrI/7dgjG1bW/DEWOJc00K9n+kkl6B8Mk0KO6d4GfWBOXlVr9uHp7CJR9FIrjmov5SGjHXG2q9XAtkRw6Q=="],
+
+    "@aws-sdk/credential-provider-node": ["@aws-sdk/credential-provider-node@3.972.31", "", { "dependencies": { "@aws-sdk/credential-provider-env": "^3.972.26", "@aws-sdk/credential-provider-http": "^3.972.28", "@aws-sdk/credential-provider-ini": "^3.972.30", "@aws-sdk/credential-provider-process": "^3.972.26", "@aws-sdk/credential-provider-sso": "^3.972.30", "@aws-sdk/credential-provider-web-identity": "^3.972.30", "@aws-sdk/types": "^3.973.8", "@smithy/credential-provider-imds": "^4.2.14", "@smithy/property-provider": "^4.2.14", "@smithy/shared-ini-file-loader": "^4.4.9", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-99OHVQ6eZ5DTxiOWgHdjBMvLqv7xoY4jLK6nZ1NcNSQbAnYZkQNIHi/VqInc9fnmg7of9si/z+waE6YL9OQIlw=="],
+
+    "@aws-sdk/credential-provider-process": ["@aws-sdk/credential-provider-process@3.972.26", "", { "dependencies": { "@aws-sdk/core": "^3.974.0", "@aws-sdk/types": "^3.973.8", "@smithy/property-provider": "^4.2.14", "@smithy/shared-ini-file-loader": "^4.4.9", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-jibxNld3m+vbmQwn98hcQ+fLIVrx3cQuhZlSs1/hix48SjDS5/pjMLwpmtLD/lFnd6ve1AL4o1bZg3X1WRa2SQ=="],
+
+    "@aws-sdk/credential-provider-sso": ["@aws-sdk/credential-provider-sso@3.972.30", "", { "dependencies": { "@aws-sdk/core": "^3.974.0", "@aws-sdk/nested-clients": "^3.996.20", "@aws-sdk/token-providers": "3.1031.0", "@aws-sdk/types": "^3.973.8", "@smithy/property-provider": "^4.2.14", "@smithy/shared-ini-file-loader": "^4.4.9", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-honYIM17F/+QSWJRE84T4u//ofqEi7rLbnwmIpu7fgFX5PML78wbtdSAy5Xwyve3TLpE9/f9zQx0aBVxSjAOPw=="],
+
+    "@aws-sdk/credential-provider-web-identity": ["@aws-sdk/credential-provider-web-identity@3.972.30", "", { "dependencies": { "@aws-sdk/core": "^3.974.0", "@aws-sdk/nested-clients": "^3.996.20", "@aws-sdk/types": "^3.973.8", "@smithy/property-provider": "^4.2.14", "@smithy/shared-ini-file-loader": "^4.4.9", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-CyL4oWUlONQRN2SsYMVrA9Z3i3QfLWTQctI8tuKbjNGCVVDCnJf/yMbSJCOZgpPFRtxh7dgQwvpqwmJm+iytmw=="],
+
+    "@aws-sdk/eventstream-handler-node": ["@aws-sdk/eventstream-handler-node@3.972.14", "", { "dependencies": { "@aws-sdk/types": "^3.973.8", "@smithy/eventstream-codec": "^4.2.14", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-m4X56gxG76/CKfxNVbOFuYwnAZcHgS6HOH8lgp15HoGHIAVTcZfZrXvcYzJFOMLEJgVn+JHBu6EiNV+xSNXXFg=="],
+
+    "@aws-sdk/middleware-eventstream": ["@aws-sdk/middleware-eventstream@3.972.10", "", { "dependencies": { "@aws-sdk/types": "^3.973.8", "@smithy/protocol-http": "^5.3.14", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-QUqLs7Af1II9X4fCRAu+EGHG3KHyOp4RkuLhRKoA3NuFlh6TL8i+zXBl8w2LUxqm44B/Kom45hgSlwA1SpTsXQ=="],
+
+    "@aws-sdk/middleware-host-header": ["@aws-sdk/middleware-host-header@3.972.10", "", { "dependencies": { "@aws-sdk/types": "^3.973.8", "@smithy/protocol-http": "^5.3.14", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-IJSsIMeVQ8MMCPbuh1AbltkFhLBLXn7aejzfX5YKT/VLDHn++Dcz8886tXckE+wQssyPUhaXrJhdakO2VilRhg=="],
+
+    "@aws-sdk/middleware-logger": ["@aws-sdk/middleware-logger@3.972.10", "", { "dependencies": { "@aws-sdk/types": "^3.973.8", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-OOuGvvz1Dm20SjZo5oEBePFqxt5nf8AwkNDSyUHvD9/bfNASmstcYxFAHUowy4n6Io7mWUZ04JURZwSBvyQanQ=="],
+
+    "@aws-sdk/middleware-recursion-detection": ["@aws-sdk/middleware-recursion-detection@3.972.11", "", { "dependencies": { "@aws-sdk/types": "^3.973.8", "@aws/lambda-invoke-store": "^0.2.2", "@smithy/protocol-http": "^5.3.14", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-+zz6f79Kj9V5qFK2P+D8Ehjnw4AhphAlCAsPjUqEcInA9umtSSKMrHbSagEeOIsDNuvVrH98bjRHcyQukTrhaQ=="],
+
+    "@aws-sdk/middleware-user-agent": ["@aws-sdk/middleware-user-agent@3.972.30", "", { "dependencies": { "@aws-sdk/core": "^3.974.0", "@aws-sdk/types": "^3.973.8", "@aws-sdk/util-endpoints": "^3.996.7", "@smithy/core": "^3.23.15", "@smithy/protocol-http": "^5.3.14", "@smithy/types": "^4.14.1", "@smithy/util-retry": "^4.3.2", "tslib": "^2.6.2" } }, "sha512-lCz6JfelhjD6Eco1urXM2rOYRaxROSqeoY6IEKx+soegFJOajmIBCMHTAWuJl25Wf9IAST+i0/yOk9G3rMV26A=="],
+
+    "@aws-sdk/middleware-websocket": ["@aws-sdk/middleware-websocket@3.972.16", "", { "dependencies": { "@aws-sdk/types": "^3.973.8", "@aws-sdk/util-format-url": "^3.972.10", "@smithy/eventstream-codec": "^4.2.14", "@smithy/eventstream-serde-browser": "^4.2.14", "@smithy/fetch-http-handler": "^5.3.17", "@smithy/protocol-http": "^5.3.14", "@smithy/signature-v4": "^5.3.14", "@smithy/types": "^4.14.1", "@smithy/util-base64": "^4.3.2", "@smithy/util-hex-encoding": "^4.2.2", "@smithy/util-utf8": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-86+S9oCyRVGzoMRpQhxkArp7kD2K75GPmaNevd9B6EyNhWoNvnCZZ3WbgN4j7ZT+jvtvBCGZvI2XHsWZJ+BRIg=="],
+
+    "@aws-sdk/nested-clients": ["@aws-sdk/nested-clients@3.996.20", "", { "dependencies": { "@aws-crypto/sha256-browser": "5.2.0", "@aws-crypto/sha256-js": "5.2.0", "@aws-sdk/core": "^3.974.0", "@aws-sdk/middleware-host-header": "^3.972.10", "@aws-sdk/middleware-logger": "^3.972.10", "@aws-sdk/middleware-recursion-detection": "^3.972.11", "@aws-sdk/middleware-user-agent": "^3.972.30", "@aws-sdk/region-config-resolver": "^3.972.12", "@aws-sdk/types": "^3.973.8", "@aws-sdk/util-endpoints": "^3.996.7", "@aws-sdk/util-user-agent-browser": "^3.972.10", "@aws-sdk/util-user-agent-node": "^3.973.16", "@smithy/config-resolver": "^4.4.16", "@smithy/core": "^3.23.15", "@smithy/fetch-http-handler": "^5.3.17", "@smithy/hash-node": "^4.2.14", "@smithy/invalid-dependency": "^4.2.14", "@smithy/middleware-content-length": "^4.2.14", "@smithy/middleware-endpoint": "^4.4.30", "@smithy/middleware-retry": "^4.5.3", "@smithy/middleware-serde": "^4.2.18", "@smithy/middleware-stack": "^4.2.14", "@smithy/node-config-provider": "^4.3.14", "@smithy/node-http-handler": "^4.5.3", "@smithy/protocol-http": "^5.3.14", "@smithy/smithy-client": "^4.12.11", "@smithy/types": "^4.14.1", "@smithy/url-parser": "^4.2.14", "@smithy/util-base64": "^4.3.2", "@smithy/util-body-length-browser": "^4.2.2", "@smithy/util-body-length-node": "^4.2.3", "@smithy/util-defaults-mode-browser": "^4.3.47", "@smithy/util-defaults-mode-node": "^4.2.52", "@smithy/util-endpoints": "^3.4.1", "@smithy/util-middleware": "^4.2.14", "@smithy/util-retry": "^4.3.2", "@smithy/util-utf8": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-bzPdsNQnCh6TvvUmTHLZlL8qgyME6mNiUErcRMyJPywIl1BEu2VZRShel3mUoSh89bOBEXEWtjocDMolFxd/9A=="],
+
+    "@aws-sdk/region-config-resolver": ["@aws-sdk/region-config-resolver@3.972.12", "", { "dependencies": { "@aws-sdk/types": "^3.973.8", "@smithy/config-resolver": "^4.4.16", "@smithy/node-config-provider": "^4.3.14", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-QQI43Mxd53nBij0pm8HXC+t4IOC6gnhhZfzxE0OATQyO6QfPV4e+aTIRRuAJKA6Nig/cR8eLwPryqYTX9ZrjAQ=="],
+
+    "@aws-sdk/token-providers": ["@aws-sdk/token-providers@3.1031.0", "", { "dependencies": { "@aws-sdk/core": "^3.974.0", "@aws-sdk/nested-clients": "^3.996.20", "@aws-sdk/types": "^3.973.8", "@smithy/property-provider": "^4.2.14", "@smithy/shared-ini-file-loader": "^4.4.9", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-zj/PvnbQK/2KJNln5K2QRI9HSsy+B4emz2gbQyUHkk6l7Lidu83P/9tfmC2cJXkcC3vdmyKH2DP3Iw/FDfKQuQ=="],
+
+    "@aws-sdk/types": ["@aws-sdk/types@3.973.8", "", { "dependencies": { "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-gjlAdtHMbtR9X5iIhVUvbVcy55KnznpC6bkDUWW9z915bi0ckdUr5cjf16Kp6xq0bP5HBD2xzgbL9F9Quv5vUw=="],
+
+    "@aws-sdk/util-endpoints": ["@aws-sdk/util-endpoints@3.996.7", "", { "dependencies": { "@aws-sdk/types": "^3.973.8", "@smithy/types": "^4.14.1", "@smithy/url-parser": "^4.2.14", "@smithy/util-endpoints": "^3.4.1", "tslib": "^2.6.2" } }, "sha512-ty4LQxN1QC+YhUP28NfEgZDEGXkyqOQy+BDriBozqHsrYO4JMgiPhfizqOGF7P+euBTZ5Ez6SKlLAMCLo8tzmw=="],
+
+    "@aws-sdk/util-format-url": ["@aws-sdk/util-format-url@3.972.10", "", { "dependencies": { "@aws-sdk/types": "^3.973.8", "@smithy/querystring-builder": "^4.2.14", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-DEKiHNJVtNxdyTeQspzY+15Po/kHm6sF0Cs4HV9Q2+lplB63+DrvdeiSoOSdWEWAoO2RcY1veoXVDz2tWxWCgQ=="],
+
+    "@aws-sdk/util-locate-window": ["@aws-sdk/util-locate-window@3.965.5", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-WhlJNNINQB+9qtLtZJcpQdgZw3SCDCpXdUJP7cToGwHbCWCnRckGlc6Bx/OhWwIYFNAn+FIydY8SZ0QmVu3xTQ=="],
+
+    "@aws-sdk/util-user-agent-browser": ["@aws-sdk/util-user-agent-browser@3.972.10", "", { "dependencies": { "@aws-sdk/types": "^3.973.8", "@smithy/types": "^4.14.1", "bowser": "^2.11.0", "tslib": "^2.6.2" } }, "sha512-FAzqXvfEssGdSIz8ejatan0bOdx1qefBWKF/gWmVBXIP1HkS7v/wjjaqrAGGKvyihrXTXW00/2/1nTJtxpXz7g=="],
+
+    "@aws-sdk/util-user-agent-node": ["@aws-sdk/util-user-agent-node@3.973.16", "", { "dependencies": { "@aws-sdk/middleware-user-agent": "^3.972.30", "@aws-sdk/types": "^3.973.8", "@smithy/node-config-provider": "^4.3.14", "@smithy/types": "^4.14.1", "@smithy/util-config-provider": "^4.2.2", "tslib": "^2.6.2" }, "peerDependencies": { "aws-crt": ">=1.0.0" }, "optionalPeers": ["aws-crt"] }, "sha512-ccvu0FNCI0C6OqmxI/tWn7BD8qGooWuURssiIM+6vbksFO8opXR4JOGtGYPj8QYzN/vfwNYrcK344PPbYuvzRg=="],
+
+    "@aws-sdk/xml-builder": ["@aws-sdk/xml-builder@3.972.18", "", { "dependencies": { "@smithy/types": "^4.14.1", "fast-xml-parser": "5.5.8", "tslib": "^2.6.2" } }, "sha512-BMDNVG1ETXRhl1tnisQiYBef3RShJ1kfZA7x7afivTFMLirfHNTb6U71K569HNXhSXbQZsweHvSDZ6euBw8hPA=="],
+
+    "@aws/lambda-invoke-store": ["@aws/lambda-invoke-store@0.2.4", "", {}, "sha512-iY8yvjE0y651BixKNPgmv1WrQc+GZ142sb0z4gYnChDDY2YqI4P/jsSopBWrKfAt7LOJAkOXt7rC/hms+WclQQ=="],
+
     "@babel/code-frame": ["@babel/code-frame@7.29.0", "", { "dependencies": { "@babel/helper-validator-identifier": "^7.28.5", "js-tokens": "^4.0.0", "picocolors": "^1.1.1" } }, "sha512-9NhCeYjq9+3uxgdtp20LSiJXJvN0FeCtNGpJxuMFZ1Kv3cWUNb6DOhJwUvcVCzKGR66cw4njwM6hrJLqgOwbcw=="],
 
     "@babel/compat-data": ["@babel/compat-data@7.29.0", "", {}, "sha512-T1NCJqT/j9+cn8fvkt7jtwbLBfLC/1y1c7NtCeXFRgzGTsafi68MRv8yzkYSapBnFA6L3U2VSc02ciDzoAJhJg=="],
@@ -317,6 +407,8 @@
 
     "@babel/types": ["@babel/types@7.29.0", "", { "dependencies": { "@babel/helper-string-parser": "^7.27.1", "@babel/helper-validator-identifier": "^7.28.5" } }, "sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A=="],
 
+    "@borewit/text-codec": ["@borewit/text-codec@0.2.2", "", {}, "sha512-DDaRehssg1aNrH4+2hnj1B7vnUGEjU6OIlyRdkMd0aUdIUvKXrJfXsy8LVtXAy7DRvYVluWbMspsRhz2lcW0mQ=="],
+
     "@capsizecss/unpack": ["@capsizecss/unpack@4.0.0", "", { "dependencies": { "fontkitten": "^1.0.0" } }, "sha512-VERIM64vtTP1C4mxQ5thVT9fK0apjPFobqybMtA1UdUujWka24ERHbRHFGmpbbhp73MhV+KSsHQH9C6uOTdEQA=="],
 
     "@clack/core": ["@clack/core@1.1.0", "", { "dependencies": { "sisteransi": "^1.0.5" } }, "sha512-SVcm4Dqm2ukn64/8Gub2wnlA5nS2iWJyCkdNHcvNHPIeBTGojpdJ+9cZKwLfmqy7irD4N5qLteSilJlE0WLAtA=="],
@@ -433,6 +525,10 @@
 
     "@floating-ui/utils": ["@floating-ui/utils@0.2.11", "", {}, "sha512-RiB/yIh78pcIxl6lLMG0CgBXAZ2Y0eVHqMPYugu+9U0AeT6YBeiJpf7lbdJNIugFP5SIjwNRgo4DhR1Qxi26Gg=="],
 
+    "@google/genai": ["@google/genai@1.50.1", "", { "dependencies": { "google-auth-library": "^10.3.0", "p-retry": "^4.6.2", "protobufjs": "^7.5.4", "ws": "^8.18.0" }, "peerDependencies": { "@modelcontextprotocol/sdk": "^1.25.2" }, "optionalPeers": ["@modelcontextprotocol/sdk"] }, "sha512-YbkX7H9+1Pt8wOt7DDREy8XSoiL6fRDzZQRyaVBarFf8MR3zHGqVdvM4cLbDXqPhxqvegZShgfxb8kw9C7YhAQ=="],
+
+    "@grammyjs/types": ["@grammyjs/types@3.26.0", "", {}, "sha512-jlnyfxfev/2o68HlvAGRocAXgdPPX5QabG7jZlbqC2r9DZyWBfzTlg+nu3O3Fy4EhgLWu28hZ/8wr7DsNamP9A=="],
+
     "@hono/node-server": ["@hono/node-server@1.19.11", "", { "peerDependencies": { "hono": "^4" } }, "sha512-dr8/3zEaB+p0D2n/IUrlPF1HZm586qgJNXK1a9fhg/PzdtkK7Ksd5l312tJX2yBuALqDYBlG20QEbayqPyxn+g=="],
 
     "@hono/zod-openapi": ["@hono/zod-openapi@0.19.10", "", { "dependencies": { "@asteasolutions/zod-to-openapi": "^7.3.0", "@hono/zod-validator": "^0.7.1", "openapi3-ts": "^4.5.0" }, "peerDependencies": { "hono": ">=4.3.6", "zod": ">=3.0.0" } }, "sha512-dpoS6DenvoJyvxtQ7Kd633FRZ/Qf74+4+o9s+zZI8pEqnbjdF/DtxIib08WDpCaWabMEJOL5TXpMgNEZvb7hpA=="],
@@ -517,8 +613,42 @@
 
     "@jridgewell/trace-mapping": ["@jridgewell/trace-mapping@0.3.31", "", { "dependencies": { "@jridgewell/resolve-uri": "^3.1.0", "@jridgewell/sourcemap-codec": "^1.4.14" } }, "sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw=="],
 
+    "@mariozechner/clipboard": ["@mariozechner/clipboard@0.3.2", "", { "optionalDependencies": { "@mariozechner/clipboard-darwin-arm64": "0.3.2", "@mariozechner/clipboard-darwin-universal": "0.3.2", "@mariozechner/clipboard-darwin-x64": "0.3.2", "@mariozechner/clipboard-linux-arm64-gnu": "0.3.2", "@mariozechner/clipboard-linux-arm64-musl": "0.3.2", "@mariozechner/clipboard-linux-riscv64-gnu": "0.3.2", "@mariozechner/clipboard-linux-x64-gnu": "0.3.2", "@mariozechner/clipboard-linux-x64-musl": "0.3.2", "@mariozechner/clipboard-win32-arm64-msvc": "0.3.2", "@mariozechner/clipboard-win32-x64-msvc": "0.3.2" } }, "sha512-IHQpksNjo7EAtGuHFU+tbWDp5LarH3HU/8WiB9O70ZEoBPHOg0/6afwSLK0QyNMMmx4Bpi/zl6+DcBXe95nWYA=="],
+
+    "@mariozechner/clipboard-darwin-arm64": ["@mariozechner/clipboard-darwin-arm64@0.3.2", "", { "os": "darwin", "cpu": "arm64" }, "sha512-uBf6K7Je1ihsgvmWxA8UCGCeI+nbRVRXoarZdLjl6slz94Zs1tNKFZqx7aCI5O1i3e0B6ja82zZ06BWrl0MCVw=="],
+
+    "@mariozechner/clipboard-darwin-universal": ["@mariozechner/clipboard-darwin-universal@0.3.2", "", { "os": "darwin" }, "sha512-mxSheKTW2U9LsBdXy0SdmdCAE5HqNS9QUmpNHLnfJ+SsbFKALjEZc5oRrVMXxGQSirDvYf5bjmRyT0QYYonnlg=="],
+
+    "@mariozechner/clipboard-darwin-x64": ["@mariozechner/clipboard-darwin-x64@0.3.2", "", { "os": "darwin", "cpu": "x64" }, "sha512-U1BcVEoidvwIp95+HJswSW+xr28EQiHR7rZjH6pn8Sja5yO4Yoe3yCN0Zm8Lo72BbSOK/fTSq0je7CJpaPCspg=="],
+
+    "@mariozechner/clipboard-linux-arm64-gnu": ["@mariozechner/clipboard-linux-arm64-gnu@0.3.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-BsinwG3yWTIjdgNCxsFlip7LkfwPk+ruw/aFCXHUg/fb5XC/Ksp+YMQ7u0LUtiKzIv/7LMXgZInJQH6gxbAaqQ=="],
+
+    "@mariozechner/clipboard-linux-arm64-musl": ["@mariozechner/clipboard-linux-arm64-musl@0.3.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-0/Gi5Xq2V6goXBop19ePoHvXsmJD9SzFlO3S+d6+T2b+BlPcpOu3Oa0wTjl+cZrLAAEzA86aPNBI+VVAFDFPKw=="],
+
+    "@mariozechner/clipboard-linux-riscv64-gnu": ["@mariozechner/clipboard-linux-riscv64-gnu@0.3.2", "", { "os": "linux", "cpu": "none" }, "sha512-2AFFiXB24qf0zOZsxI1GJGb9wQGlOJyN6UwoXqmKS3dpQi/l6ix30IzDDA4c4ZcCcx4D+9HLYXhC1w7Sov8pXA=="],
+
+    "@mariozechner/clipboard-linux-x64-gnu": ["@mariozechner/clipboard-linux-x64-gnu@0.3.2", "", { "os": "linux", "cpu": "x64" }, "sha512-v6fVnsn7WMGg73Dab8QMwyFce7tzGfgEixKgzLP8f1GJqkJZi5zO4k4FOHzSgUufgLil63gnxvMpjWkgfeQN7A=="],
+
+    "@mariozechner/clipboard-linux-x64-musl": ["@mariozechner/clipboard-linux-x64-musl@0.3.2", "", { "os": "linux", "cpu": "x64" }, "sha512-xVUtnoMQ8v2JVyfJLKKXACA6avdnchdbBkTsZs8BgJQo29qwCp5NIHAUO8gbJ40iaEGToW5RlmVk2M9V0HsHEw=="],
+
+    "@mariozechner/clipboard-win32-arm64-msvc": ["@mariozechner/clipboard-win32-arm64-msvc@0.3.2", "", { "os": "win32", "cpu": "arm64" }, "sha512-AEgg95TNi8TGgak2wSXZkXKCvAUTjWoU1Pqb0ON7JHrX78p616XUFNTJohtIon3e0w6k0pYPZeCuqRCza/Tqeg=="],
+
+    "@mariozechner/clipboard-win32-x64-msvc": ["@mariozechner/clipboard-win32-x64-msvc@0.3.2", "", { "os": "win32", "cpu": "x64" }, "sha512-tGRuYpZwDOD7HBrCpyRuhGnHHSCknELvqwKKUG4JSfSB7JIU7LKRh6zx6fMUOQd8uISK35TjFg5UcNih+vJhFA=="],
+
+    "@mariozechner/jiti": ["@mariozechner/jiti@2.6.5", "", { "dependencies": { "std-env": "^3.10.0", "yoctocolors": "^2.1.2" }, "bin": { "jiti": "lib/jiti-cli.mjs" } }, "sha512-faGUlTcXka5l7rv0lP3K3vGW/ejRuOS24RR2aSFWREUQqzjgdsuWNo/IiPqL3kWRGt6Ahl2+qcDAwtdeWeuGUw=="],
+
+    "@mariozechner/pi-agent-core": ["@mariozechner/pi-agent-core@0.67.5", "", { "dependencies": { "@mariozechner/pi-ai": "^0.67.5" } }, "sha512-XZwAVYEja4YV3Or+Fb1fMvi/KphpaEvMcfGe1/lBNEOllDK3m6J/6MdqLJy85rettX3uKRuGjF3adDNju+LRow=="],
+
+    "@mariozechner/pi-ai": ["@mariozechner/pi-ai@0.67.5", "", { "dependencies": { "@anthropic-ai/sdk": "^0.90.0", "@aws-sdk/client-bedrock-runtime": "^3.1030.0", "@google/genai": "^1.40.0", "@mistralai/mistralai": "1.14.1", "@sinclair/typebox": "^0.34.41", "ajv": "^8.17.1", "ajv-formats": "^3.0.1", "chalk": "^5.6.2", "openai": "6.26.0", "partial-json": "^0.1.7", "proxy-agent": "^6.5.0", "undici": "^7.19.1", "zod-to-json-schema": "^3.24.6" }, "bin": { "pi-ai": "dist/cli.js" } }, "sha512-TgxI2seq+gIRy6oRQA/ogyj8c9vESMQEeICPKYe29hJCLkN/i7tgKnU9jIM+rcAJmtGaO4Iy0IL7wYV4g0qjsw=="],
+
+    "@mariozechner/pi-coding-agent": ["@mariozechner/pi-coding-agent@0.67.5", "", { "dependencies": { "@mariozechner/jiti": "^2.6.2", "@mariozechner/pi-agent-core": "^0.67.5", "@mariozechner/pi-ai": "^0.67.5", "@mariozechner/pi-tui": "^0.67.5", "@silvia-odwyer/photon-node": "^0.3.4", "ajv": "^8.17.1", "chalk": "^5.5.0", "cli-highlight": "^2.1.11", "diff": "^8.0.2", "extract-zip": "^2.0.1", "file-type": "^21.1.1", "glob": "^13.0.1", "hosted-git-info": "^9.0.2", "ignore": "^7.0.5", "marked": "^15.0.12", "minimatch": "^10.2.3", "proper-lockfile": "^4.1.2", "strip-ansi": "^7.1.0", "undici": "^7.19.1", "uuid": "^11.1.0", "yaml": "^2.8.2" }, "optionalDependencies": { "@mariozechner/clipboard": "^0.3.2" }, "bin": { "pi": "dist/cli.js" } }, "sha512-U/kZ173IDmkwq7p8zKsrhb5fpxWUW53NTKXva6fyzwx3o/tGl3PzdnyxBfv7vHz15S7mgL/dpdiF/ANUV34JTw=="],
+
+    "@mariozechner/pi-tui": ["@mariozechner/pi-tui@0.67.5", "", { "dependencies": { "@types/mime-types": "^2.1.4", "chalk": "^5.5.0", "get-east-asian-width": "^1.3.0", "marked": "^15.0.12", "mime-types": "^3.0.1" }, "optionalDependencies": { "koffi": "^2.9.0" } }, "sha512-e1dUhXDr2LUUkHmuVYxPubQnk3NYcZLNOinUVTYXCSTAEzgSq0vH5LMgf5/zHspi5AmncmJmc85Qf/VFmnpw7Q=="],
+
     "@mdx-js/mdx": ["@mdx-js/mdx@3.1.1", "", { "dependencies": { "@types/estree": "^1.0.0", "@types/estree-jsx": "^1.0.0", "@types/hast": "^3.0.0", "@types/mdx": "^2.0.0", "acorn": "^8.0.0", "collapse-white-space": "^2.0.0", "devlop": "^1.0.0", "estree-util-is-identifier-name": "^3.0.0", "estree-util-scope": "^1.0.0", "estree-walker": "^3.0.0", "hast-util-to-jsx-runtime": "^2.0.0", "markdown-extensions": "^2.0.0", "recma-build-jsx": "^1.0.0", "recma-jsx": "^1.0.0", "recma-stringify": "^1.0.0", "rehype-recma": "^1.0.0", "remark-mdx": "^3.0.0", "remark-parse": "^11.0.0", "remark-rehype": "^11.0.0", "source-map": "^0.7.0", "unified": "^11.0.0", "unist-util-position-from-estree": "^2.0.0", "unist-util-stringify-position": "^4.0.0", "unist-util-visit": "^5.0.0", "vfile": "^6.0.0" } }, "sha512-f6ZO2ifpwAQIpzGWaBQT2TXxPv6z3RBzQKpVftEWN78Vl/YweF1uwussDx8ECAXVtr3Rs89fKyG9YlzUs9DyGQ=="],
 
+    "@mistralai/mistralai": ["@mistralai/mistralai@1.14.1", "", { "dependencies": { "ws": "^8.18.0", "zod": "^3.25.0 || ^4.0.0", "zod-to-json-schema": "^3.24.1" } }, "sha512-IiLmmZFCCTReQgPAT33r7KQ1nYo5JPdvGkrkZqA8qQ2qB1GHgs5LoP5K2ICyrjnpw2n8oSxMM/VP+liiKcGNlQ=="],
+
     "@modelcontextprotocol/sdk": ["@modelcontextprotocol/sdk@1.27.1", "", { "dependencies": { "@hono/node-server": "^1.19.9", "ajv": "^8.17.1", "ajv-formats": "^3.0.1", "content-type": "^1.0.5", "cors": "^2.8.5", "cross-spawn": "^7.0.5", "eventsource": "^3.0.2", "eventsource-parser": "^3.0.0", "express": "^5.2.1", "express-rate-limit": "^8.2.1", "hono": "^4.11.4", "jose": "^6.1.3", "json-schema-typed": "^8.0.2", "pkce-challenge": "^5.0.0", "raw-body": "^3.0.0", "zod": "^3.25 || ^4.0", "zod-to-json-schema": "^3.25.1" }, "peerDependencies": { "@cfworker/json-schema": "^4.1.1" }, "optionalPeers": ["@cfworker/json-schema"] }, "sha512-sr6GbP+4edBwFndLbM60gf07z0FQ79gaExpnsjMGePXqFcSSb7t6iscpjk9DhFhwd+mTEQrzNafGP8/iGGFYaA=="],
 
     "@mswjs/interceptors": ["@mswjs/interceptors@0.41.3", "", { "dependencies": { "@open-draft/deferred-promise": "^2.2.0", "@open-draft/logger": "^0.3.0", "@open-draft/until": "^2.0.0", "is-node-process": "^1.2.0", "outvariant": "^1.4.3", "strict-event-emitter": "^0.5.1" } }, "sha512-cXu86tF4VQVfwz8W1SPbhoRyHJkti6mjH/XJIxp40jhO4j2k1m4KYrEykxqWPkFF3vrK4rgQppBh//AwyGSXPA=="],
@@ -599,6 +729,28 @@
 
     "@pinojs/redact": ["@pinojs/redact@0.4.0", "", {}, "sha512-k2ENnmBugE/rzQfEcdWHcCY+/FM3VLzH9cYEsbdsoqrvzAKRhUZeRNhAZvB8OitQJ1TBed3yqWtdjzS6wJKBwg=="],
 
+    "@posthog/core": ["@posthog/core@1.25.2", "", {}, "sha512-h2FO7ut/BbfwpAXWpwdDHTzQgUo9ibDFEs6ZO+3cI3KPWQt5XwczK1OLAuPprcjm8T/jl0SH8jSFo5XdU4RbTg=="],
+
+    "@protobufjs/aspromise": ["@protobufjs/aspromise@1.1.2", "", {}, "sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ=="],
+
+    "@protobufjs/base64": ["@protobufjs/base64@1.1.2", "", {}, "sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg=="],
+
+    "@protobufjs/codegen": ["@protobufjs/codegen@2.0.4", "", {}, "sha512-YyFaikqM5sH0ziFZCN3xDC7zeGaB/d0IUb9CATugHWbd1FRFwWwt4ld4OYMPWu5a3Xe01mGAULCdqhMlPl29Jg=="],
+
+    "@protobufjs/eventemitter": ["@protobufjs/eventemitter@1.1.0", "", {}, "sha512-j9ednRT81vYJ9OfVuXG6ERSTdEL1xVsNgqpkxMsbIabzSo3goCjDIveeGv5d03om39ML71RdmrGNjG5SReBP/Q=="],
+
+    "@protobufjs/fetch": ["@protobufjs/fetch@1.1.0", "", { "dependencies": { "@protobufjs/aspromise": "^1.1.1", "@protobufjs/inquire": "^1.1.0" } }, "sha512-lljVXpqXebpsijW71PZaCYeIcE5on1w5DlQy5WH6GLbFryLUrBD4932W/E2BSpfRJWseIL4v/KPgBFxDOIdKpQ=="],
+
+    "@protobufjs/float": ["@protobufjs/float@1.0.2", "", {}, "sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ=="],
+
+    "@protobufjs/inquire": ["@protobufjs/inquire@1.1.0", "", {}, "sha512-kdSefcPdruJiFMVSbn801t4vFK7KB/5gd2fYvrxhuJYg8ILrmn9SKSX2tZdV6V+ksulWqS7aXjBcRXl3wHoD9Q=="],
+
+    "@protobufjs/path": ["@protobufjs/path@1.1.2", "", {}, "sha512-6JOcJ5Tm08dOHAbdR3GrvP+yUUfkjG5ePsHYczMFLq3ZmMkAD98cDgcT2iA1lJ9NVwFd4tH/iSSoe44YWkltEA=="],
+
+    "@protobufjs/pool": ["@protobufjs/pool@1.1.0", "", {}, "sha512-0kELaGSIDBKvcgS4zkjz1PeddatrjYcmMWOlAuAPwAeccUrPHdUqo/J6LiymHHEiJT5NrF1UVwxY14f+fy4WQw=="],
+
+    "@protobufjs/utf8": ["@protobufjs/utf8@1.1.0", "", {}, "sha512-Vvn3zZrhQZkkBE8LSuW3em98c0FwgO4nxzv6OdSxPKJIEKY2bGbHn+mhGIPerzI4twdxaP8/0+06HBpwf345Lw=="],
+
     "@radix-ui/number": ["@radix-ui/number@1.1.1", "", {}, "sha512-MkKCwxlXTgz6CFoJx3pCwn07GKp36+aZyu/u2Ln2VrA5DcdyCZkASEDBTd8x5whTQQL5CiYf4prXKLcgQdv29g=="],
 
     "@radix-ui/primitive": ["@radix-ui/primitive@1.1.3", "", {}, "sha512-JTF99U/6XIjCBo0wqkU5sK10glYe27MRRsfwoiq5zzOEZLHU3A3KCMa5X/azekYRCJ0HlwI0crAXS/5dEHTzDg=="],
@@ -803,6 +955,10 @@
 
     "@shikijs/vscode-textmate": ["@shikijs/vscode-textmate@10.0.2", "", {}, "sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg=="],
 
+    "@silvia-odwyer/photon-node": ["@silvia-odwyer/photon-node@0.3.4", "", {}, "sha512-bnly4BKB3KDTFxrUIcgCLbaeVVS8lrAkri1pEzskpmxu9MdfGQTy8b8EgcD83ywD3RPMsIulY8xJH5Awa+t9fA=="],
+
+    "@sinclair/typebox": ["@sinclair/typebox@0.34.49", "", {}, "sha512-brySQQs7Jtn0joV8Xh9ZV/hZb9Ozb0pmazDIASBkYKCjXrXU3mpcFahmK/z4YDhGkQvP9mWJbVyahdtU5wQA+A=="],
+
     "@sindresorhus/merge-streams": ["@sindresorhus/merge-streams@4.0.0", "", {}, "sha512-tlqY9xq5ukxTUZBmoOp+m61cqwQD5pHJtFY3Mn8CA8ps6yghLH/Hw8UPdqg4OLmFW3IFlcXnQNmo/dh8HzXYIQ=="],
 
     "@slack/bolt": ["@slack/bolt@4.6.0", "", { "dependencies": { "@slack/logger": "^4.0.0", "@slack/oauth": "^3.0.4", "@slack/socket-mode": "^2.0.5", "@slack/types": "^2.18.0", "@slack/web-api": "^7.12.0", "axios": "^1.12.0", "express": "^5.0.0", "path-to-regexp": "^8.1.0", "raw-body": "^3", "tsscmp": "^1.0.6" }, "peerDependencies": { "@types/express": "^5.0.0" } }, "sha512-xPgfUs2+OXSugz54Ky07pA890+Qydk22SYToi8uGpXeHSt1JWwFJkRyd/9Vlg5I1AdfdpGXExDpwnbuN9Q/2dQ=="],
@@ -817,6 +973,94 @@
 
     "@slack/web-api": ["@slack/web-api@7.15.0", "", { "dependencies": { "@slack/logger": "^4.0.1", "@slack/types": "^2.20.1", "@types/node": ">=18", "@types/retry": "0.12.0", "axios": "^1.13.5", "eventemitter3": "^5.0.1", "form-data": "^4.0.4", "is-electron": "2.2.2", "is-stream": "^2", "p-queue": "^6", "p-retry": "^4", "retry": "^0.13.1" } }, "sha512-va7zYIt3QHG1x9M/jqXXRPFMoOVlVSSRHC5YH+DzKYsrz5xUKOA3lR4THsu/Zxha9N1jOndbKFKLtr0WOPW1Vw=="],
 
+    "@smithy/config-resolver": ["@smithy/config-resolver@4.4.16", "", { "dependencies": { "@smithy/node-config-provider": "^4.3.14", "@smithy/types": "^4.14.1", "@smithy/util-config-provider": "^4.2.2", "@smithy/util-endpoints": "^3.4.1", "@smithy/util-middleware": "^4.2.14", "tslib": "^2.6.2" } }, "sha512-GFlGPNLZKrGfqWpqVb31z7hvYCA9ZscfX1buYnvvMGcRYsQQnhH+4uN6mWWflcD5jB4OXP/LBrdpukEdjl41tg=="],
+
+    "@smithy/core": ["@smithy/core@3.23.15", "", { "dependencies": { "@smithy/protocol-http": "^5.3.14", "@smithy/types": "^4.14.1", "@smithy/url-parser": "^4.2.14", "@smithy/util-base64": "^4.3.2", "@smithy/util-body-length-browser": "^4.2.2", "@smithy/util-middleware": "^4.2.14", "@smithy/util-stream": "^4.5.23", "@smithy/util-utf8": "^4.2.2", "@smithy/uuid": "^1.1.2", "tslib": "^2.6.2" } }, "sha512-E7GVCgsQttzfujEZb6Qep005wWf4xiL4x06apFEtzQMWYBPggZh/0cnOxPficw5cuK/YjjkehKoIN4YUaSh0UQ=="],
+
+    "@smithy/credential-provider-imds": ["@smithy/credential-provider-imds@4.2.14", "", { "dependencies": { "@smithy/node-config-provider": "^4.3.14", "@smithy/property-provider": "^4.2.14", "@smithy/types": "^4.14.1", "@smithy/url-parser": "^4.2.14", "tslib": "^2.6.2" } }, "sha512-Au28zBN48ZAoXdooGUHemuVBrkE+Ie6RPmGNIAJsFqj33Vhb6xAgRifUydZ2aY+M+KaMAETAlKk5NC5h1G7wpg=="],
+
+    "@smithy/eventstream-codec": ["@smithy/eventstream-codec@4.2.14", "", { "dependencies": { "@aws-crypto/crc32": "5.2.0", "@smithy/types": "^4.14.1", "@smithy/util-hex-encoding": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-erZq0nOIpzfeZdCyzZjdJb4nVSKLUmSkaQUVkRGQTXs30gyUGeKnrYEg+Xe1W5gE3aReS7IgsvANwVPxSzY6Pw=="],
+
+    "@smithy/eventstream-serde-browser": ["@smithy/eventstream-serde-browser@4.2.14", "", { "dependencies": { "@smithy/eventstream-serde-universal": "^4.2.14", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-8IelTCtTctWRbb+0Dcy+C0aICh1qa0qWXqgjcXDmMuCvPJRnv26hiDZoAau2ILOniki65mCPKqOQs/BaWvO4CQ=="],
+
+    "@smithy/eventstream-serde-config-resolver": ["@smithy/eventstream-serde-config-resolver@4.3.14", "", { "dependencies": { "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-sqHiHpYRYo3FJlaIxD1J8PhbcmJAm7IuM16mVnwSkCToD7g00IBZzKuiLNMGmftULmEUX6/UAz8/NN5uMP8bVA=="],
+
+    "@smithy/eventstream-serde-node": ["@smithy/eventstream-serde-node@4.2.14", "", { "dependencies": { "@smithy/eventstream-serde-universal": "^4.2.14", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-Ht/8BuGlKfFTy0H3+8eEu0vdpwGztCnaLLXtpXNdQqiR7Hj4vFScU3T436vRAjATglOIPjJXronY+1WxxNLSiw=="],
+
+    "@smithy/eventstream-serde-universal": ["@smithy/eventstream-serde-universal@4.2.14", "", { "dependencies": { "@smithy/eventstream-codec": "^4.2.14", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-lWyt4T2XQZUZgK3tQ3Wn0w3XBvZsK/vjTuJl6bXbnGZBHH0ZUSONTYiK9TgjTTzU54xQr3DRFwpjmhp0oLm3gg=="],
+
+    "@smithy/fetch-http-handler": ["@smithy/fetch-http-handler@5.3.17", "", { "dependencies": { "@smithy/protocol-http": "^5.3.14", "@smithy/querystring-builder": "^4.2.14", "@smithy/types": "^4.14.1", "@smithy/util-base64": "^4.3.2", "tslib": "^2.6.2" } }, "sha512-bXOvQzaSm6MnmLaWA1elgfQcAtN4UP3vXqV97bHuoOrHQOJiLT3ds6o9eo5bqd0TJfRFpzdGnDQdW3FACiAVdw=="],
+
+    "@smithy/hash-node": ["@smithy/hash-node@4.2.14", "", { "dependencies": { "@smithy/types": "^4.14.1", "@smithy/util-buffer-from": "^4.2.2", "@smithy/util-utf8": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-8ZBDY2DD4wr+GGjTpPtiglEsqr0lUP+KHqgZcWczFf6qeZ/YRjMIOoQWVQlmwu7EtxKTd8YXD8lblmYcpBIA1g=="],
+
+    "@smithy/invalid-dependency": ["@smithy/invalid-dependency@4.2.14", "", { "dependencies": { "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-c21qJiTSb25xvvOp+H2TNZzPCngrvl5vIPqPB8zQ/DmJF4QWXO19x1dWfMJZ6wZuuWUPPm0gV8C0cU3+ifcWuw=="],
+
+    "@smithy/is-array-buffer": ["@smithy/is-array-buffer@4.2.2", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-n6rQ4N8Jj4YTQO3YFrlgZuwKodf4zUFs7EJIWH86pSCWBaAtAGBFfCM7Wx6D2bBJ2xqFNxGBSrUWswT3M0VJow=="],
+
+    "@smithy/middleware-content-length": ["@smithy/middleware-content-length@4.2.14", "", { "dependencies": { "@smithy/protocol-http": "^5.3.14", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-xhHq7fX4/3lv5NHxLUk3OeEvl0xZ+Ek3qIbWaCL4f9JwgDZEclPBElljaZCAItdGPQl/kSM4LPMOpy1MYgprpw=="],
+
+    "@smithy/middleware-endpoint": ["@smithy/middleware-endpoint@4.4.30", "", { "dependencies": { "@smithy/core": "^3.23.15", "@smithy/middleware-serde": "^4.2.18", "@smithy/node-config-provider": "^4.3.14", "@smithy/shared-ini-file-loader": "^4.4.9", "@smithy/types": "^4.14.1", "@smithy/url-parser": "^4.2.14", "@smithy/util-middleware": "^4.2.14", "tslib": "^2.6.2" } }, "sha512-qS2XqhKeXmdZ4nEQ4cOxIczSP/Y91wPAHYuRwmWDCh975B7/57uxsm5d6sisnUThn2u2FwzMdJNM7AbO1YPsPg=="],
+
+    "@smithy/middleware-retry": ["@smithy/middleware-retry@4.5.3", "", { "dependencies": { "@smithy/core": "^3.23.15", "@smithy/node-config-provider": "^4.3.14", "@smithy/protocol-http": "^5.3.14", "@smithy/service-error-classification": "^4.2.14", "@smithy/smithy-client": "^4.12.11", "@smithy/types": "^4.14.1", "@smithy/util-middleware": "^4.2.14", "@smithy/util-retry": "^4.3.2", "@smithy/uuid": "^1.1.2", "tslib": "^2.6.2" } }, "sha512-TE8dJNi6JuxzGSxMCVd3i9IEWDndCl3bmluLsBNDWok8olgj65OfkndMhl9SZ7m14c+C5SQn/PcUmrDl57rSFw=="],
+
+    "@smithy/middleware-serde": ["@smithy/middleware-serde@4.2.18", "", { "dependencies": { "@smithy/core": "^3.23.15", "@smithy/protocol-http": "^5.3.14", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-M6CSgnp3v4tYz9ynj2JHbA60woBZcGqEwNjTKjBsNHPV26R1ZX52+0wW8WsZU18q45jD0tw2wL22S17Ze9LpEw=="],
+
+    "@smithy/middleware-stack": ["@smithy/middleware-stack@4.2.14", "", { "dependencies": { "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-2dvkUKLuFdKsCRmOE4Mn63co0Djtsm+JMh0bYZQupN1pJwMeE8FmQmRLLzzEMN0dnNi7CDCYYH8F0EVwWiPBeA=="],
+
+    "@smithy/node-config-provider": ["@smithy/node-config-provider@4.3.14", "", { "dependencies": { "@smithy/property-provider": "^4.2.14", "@smithy/shared-ini-file-loader": "^4.4.9", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-S+gFjyo/weSVL0P1b9Ts8C/CwIfNCgUPikk3sl6QVsfE/uUuO+QsF+NsE/JkpvWqqyz1wg7HFdiaZuj5CoBMRg=="],
+
+    "@smithy/node-http-handler": ["@smithy/node-http-handler@4.5.3", "", { "dependencies": { "@smithy/protocol-http": "^5.3.14", "@smithy/querystring-builder": "^4.2.14", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-lc5jFL++x17sPhIwMWJ3YOnqmSjw/2Po6VLDlUIXvxVWRuJwRXnJ4jOBBLB0cfI5BB5ehIl02Fxr1PDvk/kxDw=="],
+
+    "@smithy/property-provider": ["@smithy/property-provider@4.2.14", "", { "dependencies": { "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-WuM31CgfsnQ/10i7NYr0PyxqknD72Y5uMfUMVSniPjbEPceiTErb4eIqJQ+pdxNEAUEWrewrGjIRjVbVHsxZiQ=="],
+
+    "@smithy/protocol-http": ["@smithy/protocol-http@5.3.14", "", { "dependencies": { "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-dN5F8kHx8RNU0r+pCwNmFZyz6ChjMkzShy/zup6MtkRmmix4vZzJdW+di7x//b1LiynIev88FM18ie+wwPcQtQ=="],
+
+    "@smithy/querystring-builder": ["@smithy/querystring-builder@4.2.14", "", { "dependencies": { "@smithy/types": "^4.14.1", "@smithy/util-uri-escape": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-XYA5Z0IqTeF+5XDdh4BBmSA0HvbgVZIyv4cmOoUheDNR57K1HgBp9ukUMx3Cr3XpDHHpLBnexPE3LAtDsZkj2A=="],
+
+    "@smithy/querystring-parser": ["@smithy/querystring-parser@4.2.14", "", { "dependencies": { "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-hr+YyqBD23GVvRxGGrcc/oOeNlK3PzT5Fu4dzrDXxzS1LpFiuL2PQQqKPs87M79aW7ziMs+nvB3qdw77SqE7Lw=="],
+
+    "@smithy/service-error-classification": ["@smithy/service-error-classification@4.2.14", "", { "dependencies": { "@smithy/types": "^4.14.1" } }, "sha512-vVimoUnGxlx4eLLQbZImdOZFOe+Zh+5ACntv8VxZuGP72LdWu5GV3oEmCahSEReBgRJoWjypFkrehSj7BWx1HQ=="],
+
+    "@smithy/shared-ini-file-loader": ["@smithy/shared-ini-file-loader@4.4.9", "", { "dependencies": { "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-495/V2I15SHgedSJoDPD23JuSfKAp726ZI1V0wtjB07Wh7q/0tri/0e0DLefZCHgxZonrGKt/OCTpAtP1wE1kQ=="],
+
+    "@smithy/signature-v4": ["@smithy/signature-v4@5.3.14", "", { "dependencies": { "@smithy/is-array-buffer": "^4.2.2", "@smithy/protocol-http": "^5.3.14", "@smithy/types": "^4.14.1", "@smithy/util-hex-encoding": "^4.2.2", "@smithy/util-middleware": "^4.2.14", "@smithy/util-uri-escape": "^4.2.2", "@smithy/util-utf8": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-1D9Y/nmlVjCeSivCbhZ7hgEpmHyY1h0GvpSZt3l0xcD9JjmjVC1CHOozS6+Gh+/ldMH8JuJ6cujObQqfayAVFA=="],
+
+    "@smithy/smithy-client": ["@smithy/smithy-client@4.12.11", "", { "dependencies": { "@smithy/core": "^3.23.15", "@smithy/middleware-endpoint": "^4.4.30", "@smithy/middleware-stack": "^4.2.14", "@smithy/protocol-http": "^5.3.14", "@smithy/types": "^4.14.1", "@smithy/util-stream": "^4.5.23", "tslib": "^2.6.2" } }, "sha512-wzz/Wa1CH/Tlhxh0s4DQPEcXSxSVfJ59AZcUh9Gu0c6JTlKuwGf4o/3P2TExv0VbtPFt8odIBG+eQGK2+vTECg=="],
+
+    "@smithy/types": ["@smithy/types@4.14.1", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-59b5HtSVrVR/eYNei3BUj3DCPKD/G7EtDDe7OEJE7i7FtQFugYo6MxbotS8mVJkLNVf8gYaAlEBwwtJ9HzhWSg=="],
+
+    "@smithy/url-parser": ["@smithy/url-parser@4.2.14", "", { "dependencies": { "@smithy/querystring-parser": "^4.2.14", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-p06BiBigJ8bTA3MgnOfCtDUWnAMY0YfedO/GRpmc7p+wg3KW8vbXy1xwSu5ASy0wV7rRYtlfZOIKH4XqfhjSQQ=="],
+
+    "@smithy/util-base64": ["@smithy/util-base64@4.3.2", "", { "dependencies": { "@smithy/util-buffer-from": "^4.2.2", "@smithy/util-utf8": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-XRH6b0H/5A3SgblmMa5ErXQ2XKhfbQB+Fm/oyLZ2O2kCUrwgg55bU0RekmzAhuwOjA9qdN5VU2BprOvGGUkOOQ=="],
+
+    "@smithy/util-body-length-browser": ["@smithy/util-body-length-browser@4.2.2", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-JKCrLNOup3OOgmzeaKQwi4ZCTWlYR5H4Gm1r2uTMVBXoemo1UEghk5vtMi1xSu2ymgKVGW631e2fp9/R610ZjQ=="],
+
+    "@smithy/util-body-length-node": ["@smithy/util-body-length-node@4.2.3", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-ZkJGvqBzMHVHE7r/hcuCxlTY8pQr1kMtdsVPs7ex4mMU+EAbcXppfo5NmyxMYi2XU49eqaz56j2gsk4dHHPG/g=="],
+
+    "@smithy/util-buffer-from": ["@smithy/util-buffer-from@4.2.2", "", { "dependencies": { "@smithy/is-array-buffer": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-FDXD7cvUoFWwN6vtQfEta540Y/YBe5JneK3SoZg9bThSoOAC/eGeYEua6RkBgKjGa/sz6Y+DuBZj3+YEY21y4Q=="],
+
+    "@smithy/util-config-provider": ["@smithy/util-config-provider@4.2.2", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-dWU03V3XUprJwaUIFVv4iOnS1FC9HnMHDfUrlNDSh4315v0cWyaIErP8KiqGVbf5z+JupoVpNM7ZB3jFiTejvQ=="],
+
+    "@smithy/util-defaults-mode-browser": ["@smithy/util-defaults-mode-browser@4.3.47", "", { "dependencies": { "@smithy/property-provider": "^4.2.14", "@smithy/smithy-client": "^4.12.11", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-zlIuXai3/SHjQUQ8y3g/woLvrH573SK2wNjcDaHu5e9VOcC0JwM1MI0Sq0GZJyN3BwSUneIhpjZ18nsiz5AtQw=="],
+
+    "@smithy/util-defaults-mode-node": ["@smithy/util-defaults-mode-node@4.2.52", "", { "dependencies": { "@smithy/config-resolver": "^4.4.16", "@smithy/credential-provider-imds": "^4.2.14", "@smithy/node-config-provider": "^4.3.14", "@smithy/property-provider": "^4.2.14", "@smithy/smithy-client": "^4.12.11", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-cQBz8g68Vnw1W2meXlkb3D/hXJU+Taiyj9P8qLJtjREEV9/Td65xi4A/H1sRQ8EIgX5qbZbvdYPKygKLholZ3w=="],
+
+    "@smithy/util-endpoints": ["@smithy/util-endpoints@3.4.1", "", { "dependencies": { "@smithy/node-config-provider": "^4.3.14", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-wMxNDZJrgS5mQV9oxCs4TWl5767VMgOfqfZ3JHyCkMtGC2ykW9iPqMvFur695Otcc5yxLG8OKO/80tsQBxrhXg=="],
+
+    "@smithy/util-hex-encoding": ["@smithy/util-hex-encoding@4.2.2", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-Qcz3W5vuHK4sLQdyT93k/rfrUwdJ8/HZ+nMUOyGdpeGA1Wxt65zYwi3oEl9kOM+RswvYq90fzkNDahPS8K0OIg=="],
+
+    "@smithy/util-middleware": ["@smithy/util-middleware@4.2.14", "", { "dependencies": { "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-1Su2vj9RYNDEv/V+2E+jXkkwGsgR7dc4sfHn9Z7ruzQHJIEni9zzw5CauvRXlFJfmgcqYP8fWa0dkh2Q2YaQyw=="],
+
+    "@smithy/util-retry": ["@smithy/util-retry@4.3.2", "", { "dependencies": { "@smithy/service-error-classification": "^4.2.14", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-2+KTsJEwTi63NUv4uR9IQ+IFT1yu6Rf6JuoBK2WKaaJ/TRvOiOVGcXAsEqX/TQN2thR9yII21kPUJq1UV/WI2A=="],
+
+    "@smithy/util-stream": ["@smithy/util-stream@4.5.23", "", { "dependencies": { "@smithy/fetch-http-handler": "^5.3.17", "@smithy/node-http-handler": "^4.5.3", "@smithy/types": "^4.14.1", "@smithy/util-base64": "^4.3.2", "@smithy/util-buffer-from": "^4.2.2", "@smithy/util-hex-encoding": "^4.2.2", "@smithy/util-utf8": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-N6on1+ngJ3RznZOnDWNveIwnTSlqxNnXuNAh7ez889ZZaRdXoNRTXKgmYOLe6dB0gCmAVtuRScE1hymQFl4hpg=="],
+
+    "@smithy/util-uri-escape": ["@smithy/util-uri-escape@4.2.2", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-2kAStBlvq+lTXHyAZYfJRb/DfS3rsinLiwb+69SstC9Vb0s9vNWkRwpnj918Pfi85mzi42sOqdV72OLxWAISnw=="],
+
+    "@smithy/util-utf8": ["@smithy/util-utf8@4.2.2", "", { "dependencies": { "@smithy/util-buffer-from": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-75MeYpjdWRe8M5E3AW0O4Cx3UadweS+cwdXjwYGBW5h/gxxnbeZ877sLPX/ZJA9GVTlL/qG0dXP29JWFCD1Ayw=="],
+
+    "@smithy/uuid": ["@smithy/uuid@1.1.2", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-O/IEdcCUKkubz60tFbGA7ceITTAJsty+lBjNoorP4Z6XRqaFb/OjQjZODophEcuq68nKm6/0r+6/lLQ+XVpk8g=="],
+
     "@tailwindcss/node": ["@tailwindcss/node@4.2.1", "", { "dependencies": { "@jridgewell/remapping": "^2.3.5", "enhanced-resolve": "^5.19.0", "jiti": "^2.6.1", "lightningcss": "1.31.1", "magic-string": "^0.30.21", "source-map-js": "^1.2.1", "tailwindcss": "4.2.1" } }, "sha512-jlx6sLk4EOwO6hHe1oCGm1Q4AN/s0rSrTTPBGPM0/RQ6Uylwq17FuU8IeJJKEjtc6K6O07zsvP+gDO6MMWo7pg=="],
 
     "@tailwindcss/oxide": ["@tailwindcss/oxide@4.2.1", "", { "optionalDependencies": { "@tailwindcss/oxide-android-arm64": "4.2.1", "@tailwindcss/oxide-darwin-arm64": "4.2.1", "@tailwindcss/oxide-darwin-x64": "4.2.1", "@tailwindcss/oxide-freebsd-x64": "4.2.1", "@tailwindcss/oxide-linux-arm-gnueabihf": "4.2.1", "@tailwindcss/oxide-linux-arm64-gnu": "4.2.1", "@tailwindcss/oxide-linux-arm64-musl": "4.2.1", "@tailwindcss/oxide-linux-x64-gnu": "4.2.1", "@tailwindcss/oxide-linux-x64-musl": "4.2.1", "@tailwindcss/oxide-wasm32-wasi": "4.2.1", "@tailwindcss/oxide-win32-arm64-msvc": "4.2.1", "@tailwindcss/oxide-win32-x64-msvc": "4.2.1" } }, "sha512-yv9jeEFWnjKCI6/T3Oq50yQEOqmpmpfzG1hcZsAOaXFQPfzWprWrlHSdGPEF3WQTi8zu8ohC9Mh9J470nT5pUw=="],
@@ -855,7 +1099,11 @@
 
     "@tanstack/virtual-core": ["@tanstack/virtual-core@3.13.22", "", {}, "sha512-isuUGKsc5TAPDoHSbWTbl1SCil54zOS2MiWz/9GCWHPUQOvNTQx8qJEWC7UWR0lShhbK0Lmkcf0SZYxvch7G3g=="],
 
-    "@telegraf/types": ["@telegraf/types@7.1.0", "", {}, "sha512-kGevOIbpMcIlCDeorKGpwZmdH7kHbqlk/Yj6dEpJMKEQw5lk0KVQY0OLXaCswy8GqlIVLd5625OB+rAntP9xVw=="],
+    "@tokenizer/inflate": ["@tokenizer/inflate@0.4.1", "", { "dependencies": { "debug": "^4.4.3", "token-types": "^6.1.1" } }, "sha512-2mAv+8pkG6GIZiF1kNg1jAjh27IDxEPKwdGul3snfztFerfPGI1LjDezZp3i7BElXompqEtPmoPx6c2wgtWsOA=="],
+
+    "@tokenizer/token": ["@tokenizer/token@0.3.0", "", {}, "sha512-OvjF+z51L3ov0OyAU0duzsYuvO01PH7x4t6DJx+guahgTnBHkhJdG7soQeTSFLWN3efnHyibZ4Z8l2EuWwJN3A=="],
+
+    "@tootallnate/quickjs-emscripten": ["@tootallnate/quickjs-emscripten@0.23.0", "", {}, "sha512-C5Mc6rdnsaJDjO3UpGW/CQTHtCKaYlScZTly4JIu97Jxo/odCiH0ITnDXSJPTOrEKk/ycSZ0AOgTmkDtkOsvIA=="],
 
     "@ts-morph/common": ["@ts-morph/common@0.27.0", "", { "dependencies": { "fast-glob": "^3.3.3", "minimatch": "^10.0.1", "path-browserify": "^1.0.1" } }, "sha512-Wf29UqxWDpc+i61k3oIOzcUfQt79PIT9y/MWfAGlrkjg6lBC1hwDECLXPVJAhWjiGbfBCxZd65F/LIZF3+jeJQ=="],
 
@@ -911,6 +1159,8 @@
 
     "@types/mdx": ["@types/mdx@2.0.13", "", {}, "sha512-+OWZQfAYyio6YkJb3HLxDrvnx6SWWDbC0zVPfBRzUk0/nqoDyf6dNxQi3eArPe8rJ473nobTMQ/8Zk+LxJ+Yuw=="],
 
+    "@types/mime-types": ["@types/mime-types@2.1.4", "", {}, "sha512-lfU4b34HOri+kAY5UheuFMWPDOI+OPceBSHZKp69gEyTL/mmJ4cnU6Y/rlme3UL3GyOn6Y42hyIEw0/q8sWx5w=="],
+
     "@types/ms": ["@types/ms@2.1.0", "", {}, "sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA=="],
 
     "@types/nlcst": ["@types/nlcst@2.0.3", "", { "dependencies": { "@types/unist": "*" } }, "sha512-vSYNSDe6Ix3q+6Z7ri9lyWqgGhJTmzRjZRqyq15N0Z/1/UnVsno9G/N40NBijoYx2seFDIl0+B2mgAb9mezUCA=="],
@@ -943,6 +1193,8 @@
 
     "@types/ws": ["@types/ws@8.18.1", "", { "dependencies": { "@types/node": "*" } }, "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg=="],
 
+    "@types/yauzl": ["@types/yauzl@2.10.3", "", { "dependencies": { "@types/node": "*" } }, "sha512-oJoftv0LSuaDZE3Le4DbKX+KS9G36NzOeSap90UIK0yMA/NhKJhqlSGtNDORNRaIbQfzjXDrQa0ytJ6mNRGz/Q=="],
+
     "@typescript-eslint/eslint-plugin": ["@typescript-eslint/eslint-plugin@8.57.0", "", { "dependencies": { "@eslint-community/regexpp": "^4.12.2", "@typescript-eslint/scope-manager": "8.57.0", "@typescript-eslint/type-utils": "8.57.0", "@typescript-eslint/utils": "8.57.0", "@typescript-eslint/visitor-keys": "8.57.0", "ignore": "^7.0.5", "natural-compare": "^1.4.0", "ts-api-utils": "^2.4.0" }, "peerDependencies": { "@typescript-eslint/parser": "^8.57.0", "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0", "typescript": ">=4.8.4 <6.0.0" } }, "sha512-qeu4rTHR3/IaFORbD16gmjq9+rEs9fGKdX0kF6BKSfi+gCuG3RCKLlSBYzn/bGsY9Tj7KE/DAQStbp8AHJGHEQ=="],
 
     "@typescript-eslint/parser": ["@typescript-eslint/parser@8.57.0", "", { "dependencies": { "@typescript-eslint/scope-manager": "8.57.0", "@typescript-eslint/types": "8.57.0", "@typescript-eslint/typescript-estree": "8.57.0", "@typescript-eslint/visitor-keys": "8.57.0", "debug": "^4.4.3" }, "peerDependencies": { "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0", "typescript": ">=4.8.4 <6.0.0" } }, "sha512-XZzOmihLIr8AD1b9hL9ccNMzEMWt/dE2u7NyTY9jJG6YNiNthaD5XtUHVF2uCXZ15ng+z2hT3MVuxnUYhq6k1g=="],
@@ -997,6 +1249,8 @@
 
     "ansis": ["ansis@4.2.0", "", {}, "sha512-HqZ5rWlFjGiV0tDm3UxxgNRqsOTniqoKZu0pIAfh7TZQMGuZK+hH0drySty0si0QXj1ieop4+SkSfPZBPPkHig=="],
 
+    "any-promise": ["any-promise@1.3.0", "", {}, "sha512-7UvmKalWRt1wgjL1RrGxoSJW/0QZFIegpeGvZG9kjp8vrRu55XTHbwnqq2GpXm9uLbcuhxm3IqX9OB4MZR1b2A=="],
+
     "anymatch": ["anymatch@3.1.3", "", { "dependencies": { "normalize-path": "^3.0.0", "picomatch": "^2.0.4" } }, "sha512-KMReFUr0B4t+D+OBkjR3KYqvocp2XaSzO55UcB6mgQMd3KbcE+mWTyvVV7D/zsdEbNnV6acZUutkiHQXvTr1Rw=="],
 
     "arg": ["arg@5.0.2", "", {}, "sha512-PYjyFOLKQ9y57JvQ6QLo8dAgNqswh8M1RMJYdQduT6xbWSgK36P/Z/v+p888pM69jMMfS8Xd8F6I1kQ/I9HUGg=="],
@@ -1021,7 +1275,7 @@
 
     "atomic-sleep": ["atomic-sleep@1.0.0", "", {}, "sha512-kNOjDqAh7px0XWNI+4QbzoiR/nTkHAWNud2uvnJquD1/x5a7EQZMJT0AczqK0Qn67oY/TTQ1LbUKajZpp3I9tQ=="],
 
-    "axios": ["axios@1.13.6", "", { "dependencies": { "follow-redirects": "^1.15.11", "form-data": "^4.0.5", "proxy-from-env": "^1.1.0" } }, "sha512-ChTCHMouEe2kn713WHbQGcuYrr6fXTBiu460OTwWrWob16g1bXn4vtz07Ope7ewMozJAnEquLk5lWQWtBig9DQ=="],
+    "axios": ["axios@1.15.1", "", { "dependencies": { "follow-redirects": "^1.15.11", "form-data": "^4.0.5", "proxy-from-env": "^2.1.0" } }, "sha512-WOG+Jj8ZOvR0a3rAn+Tuf1UQJRxw5venr6DgdbJzngJE3qG7X0kL83CZGpdHMxEm+ZK3seAbvFsw4FfOfP9vxg=="],
 
     "axobject-query": ["axobject-query@4.1.0", "", {}, "sha512-qIj0G9wZbMGNLjLmg1PT6v2mE9AH2zlnADJD/2tC6E00hgmhUOfEB6greHPAfLRSufHqROIUTkw6E+M3lH0PTQ=="],
 
@@ -1029,32 +1283,36 @@
 
     "balanced-match": ["balanced-match@1.0.2", "", {}, "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw=="],
 
+    "base64-js": ["base64-js@1.5.1", "", {}, "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA=="],
+
     "baseline-browser-mapping": ["baseline-browser-mapping@2.10.7", "", { "bin": { "baseline-browser-mapping": "dist/cli.cjs" } }, "sha512-1ghYO3HnxGec0TCGBXiDLVns4eCSx4zJpxnHrlqFQajmhfKMQBzUGDdkMK7fUW7PTHTeLf+j87aTuKuuwWzMGw=="],
 
+    "basic-ftp": ["basic-ftp@5.3.0", "", {}, "sha512-5K9eNNn7ywHPsYnFwjKgYH8Hf8B5emh7JKcPaVjjrMJFQQwGpwowEnZNEtHs7DfR7hCZsmaK3VA4HUK0YarT+w=="],
+
     "bcp-47": ["bcp-47@2.1.0", "", { "dependencies": { "is-alphabetical": "^2.0.0", "is-alphanumerical": "^2.0.0", "is-decimal": "^2.0.0" } }, "sha512-9IIS3UPrvIa1Ej+lVDdDwO7zLehjqsaByECw0bu2RRGP73jALm6FYbzI5gWbgHLvNdkvfXB5YrSbocZdOS0c0w=="],
 
     "bcp-47-match": ["bcp-47-match@2.0.3", "", {}, "sha512-JtTezzbAibu8G0R9op9zb3vcWZd9JF6M0xOYGPn0fNCd7wOpRB1mU2mH9T8gaBGbAAyIIVgB2G7xG0GP98zMAQ=="],
 
     "before-after-hook": ["before-after-hook@4.0.0", "", {}, "sha512-q6tR3RPqIB1pMiTRMFcZwuG5T8vwp+vUvEG0vuI6B+Rikh5BfPp2fQ82c925FOs+b0lcFQ8CFrL+KbilfZFhOQ=="],
 
+    "bignumber.js": ["bignumber.js@9.3.1", "", {}, "sha512-Ko0uX15oIUS7wJ3Rb30Fs6SkVbLmPBAKdlm7q9+ak9bbIeFf0MwuBsQV6z7+X768/cHsfg+WlysDWJcmthjsjQ=="],
+
     "body-parser": ["body-parser@2.2.2", "", { "dependencies": { "bytes": "^3.1.2", "content-type": "^1.0.5", "debug": "^4.4.3", "http-errors": "^2.0.0", "iconv-lite": "^0.7.0", "on-finished": "^2.4.1", "qs": "^6.14.1", "raw-body": "^3.0.1", "type-is": "^2.0.1" } }, "sha512-oP5VkATKlNwcgvxi0vM0p/D3n2C3EReYVX+DNYs5TjZFn/oQt2j+4sVJtSMr18pdRr8wjTcBl6LoV+FUwzPmNA=="],
 
     "boolbase": ["boolbase@1.0.0", "", {}, "sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww=="],
 
+    "bowser": ["bowser@2.14.1", "", {}, "sha512-tzPjzCxygAKWFOJP011oxFHs57HzIhOEracIgAePE4pqB3LikALKnSzUyU4MGs9/iCEUuHlAJTjTc5M+u7YEGg=="],
+
     "brace-expansion": ["brace-expansion@1.1.12", "", { "dependencies": { "balanced-match": "^1.0.0", "concat-map": "0.0.1" } }, "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg=="],
 
     "braces": ["braces@3.0.3", "", { "dependencies": { "fill-range": "^7.1.1" } }, "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA=="],
 
     "browserslist": ["browserslist@4.28.1", "", { "dependencies": { "baseline-browser-mapping": "^2.9.0", "caniuse-lite": "^1.0.30001759", "electron-to-chromium": "^1.5.263", "node-releases": "^2.0.27", "update-browserslist-db": "^1.2.0" }, "bin": { "browserslist": "cli.js" } }, "sha512-ZC5Bd0LgJXgwGqUknZY/vkUQ04r8NXnJZ3yYi4vDmSiZmC/pdSN0NbNRPxZpbtO4uAfDUAFffO8IZoM3Gj8IkA=="],
 
-    "buffer-alloc": ["buffer-alloc@1.2.0", "", { "dependencies": { "buffer-alloc-unsafe": "^1.1.0", "buffer-fill": "^1.0.0" } }, "sha512-CFsHQgjtW1UChdXgbyJGtnm+O/uLQeZdtbDo8mfUgYXCHSM1wgrVxXm6bSyrUuErEb+4sYVGCzASBRot7zyrow=="],
-
-    "buffer-alloc-unsafe": ["buffer-alloc-unsafe@1.1.0", "", {}, "sha512-TEM2iMIEQdJ2yjPJoSIsldnleVaAk1oW3DBVUykyOLsEsFmEc9kn+SFFPz+gl54KQNxlDnAwCXosOS9Okx2xAg=="],
+    "buffer-crc32": ["buffer-crc32@0.2.13", "", {}, "sha512-VO9Ht/+p3SN7SKWqcrgEzjGbRSJYTx+Q1pTQC0wrWqHx0vpJraQ6GtHx8tvcg1rlK1byhU5gccxgOgj7B0TDkQ=="],
 
     "buffer-equal-constant-time": ["buffer-equal-constant-time@1.0.1", "", {}, "sha512-zRpUiDwd/xk6ADqPMATG8vc9VPrkck7T07OIx0gnjmJAnHnTVXNQG3vfvWNuiZIkwu9KrKdA1iJKfsfTVxE6NA=="],
 
-    "buffer-fill": ["buffer-fill@1.0.0", "", {}, "sha512-T7zexNBwiiaCOGDg9xNX9PBmjrubblRkENuptryuI64URkXDFum9il/JGL8Lm8wYfAXpredVXXZz7eMHilimiQ=="],
-
     "bun-types": ["bun-types@1.3.10", "", { "dependencies": { "@types/node": "*" } }, "sha512-tcpfCCl6XWo6nCVnpcVrxQ+9AYN1iqMIzgrSKYMB/fjLtV2eyAVEg7AxQJuCq/26R6HpKWykQXuSOq/21RYcbg=="],
 
     "bundle-name": ["bundle-name@4.1.0", "", { "dependencies": { "run-applescript": "^7.0.0" } }, "sha512-tjwM5exMg6BGRI+kNmTntNsvdZS1X8BFYS6tnJ2hdH0kVxM6/eVZ2xy+FqStSWvYmtfFMDLIxurorHwDKfDz5Q=="],
@@ -1093,13 +1351,15 @@
 
     "cli-cursor": ["cli-cursor@5.0.0", "", { "dependencies": { "restore-cursor": "^5.0.0" } }, "sha512-aCj4O5wKyszjMmDT4tZj93kxyydN/K5zPWSCe6/0AV/AA1pqe5ZBIw0a2ZfPQV7lL5/yb5HsUreJ6UFAF1tEQw=="],
 
+    "cli-highlight": ["cli-highlight@2.1.11", "", { "dependencies": { "chalk": "^4.0.0", "highlight.js": "^10.7.1", "mz": "^2.4.0", "parse5": "^5.1.1", "parse5-htmlparser2-tree-adapter": "^6.0.0", "yargs": "^16.0.0" }, "bin": { "highlight": "bin/highlight" } }, "sha512-9KDcoEVwyUXrjcJNvHD0NFc/hiwe/WPVYIleQh2O1N2Zro5gWJZ/K+3DGn8w8P/F6FxOgzyC5bxDyHIgCSPhGg=="],
+
     "cli-spinners": ["cli-spinners@2.9.2", "", {}, "sha512-ywqV+5MmyL4E7ybXgKys4DugZbX0FC6LnwrhjuykIjnK9k8OQacQ7axGKnjDXWNhns0xot3bZI5h55H8yo9cJg=="],
 
     "cli-truncate": ["cli-truncate@4.0.0", "", { "dependencies": { "slice-ansi": "^5.0.0", "string-width": "^7.0.0" } }, "sha512-nPdaFdQ0h/GEigbPClz11D0v/ZJEwxmeVZGeMo3Z5StPtUTkA9o1lD6QwoirYiSDzbcwn2XcjwmCp68W1IS4TA=="],
 
     "cli-width": ["cli-width@4.1.0", "", {}, "sha512-ouuZd4/dm2Sw5Gmqy6bGyNNNe1qt9RpmxveLSO7KcgsTnU7RXfsw+/bukWGo1abgBiMAic068rclZsO4IWmmxQ=="],
 
-    "cliui": ["cliui@8.0.1", "", { "dependencies": { "string-width": "^4.2.0", "strip-ansi": "^6.0.1", "wrap-ansi": "^7.0.0" } }, "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ=="],
+    "cliui": ["cliui@7.0.4", "", { "dependencies": { "string-width": "^4.2.0", "strip-ansi": "^6.0.0", "wrap-ansi": "^7.0.0" } }, "sha512-OcRE68cOsVMXp1Yvonl/fzkQOyjLSu/8bhPDfQt0e0/Eb283TKP20Fs2MqoPsr9SwA595rRCA+QMzYc9nBP+JQ=="],
 
     "clsx": ["clsx@2.1.1", "", {}, "sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA=="],
 
@@ -1201,6 +1461,8 @@
 
     "defu": ["defu@6.1.6", "", {}, "sha512-f8mefEW4WIVg4LckePx3mALjQSPQgFlg9U8yaPdlsbdYcHQyj9n2zL2LJEA52smeYxOvmd/nB7TpMtHGMTHcug=="],
 
+    "degenerator": ["degenerator@5.0.1", "", { "dependencies": { "ast-types": "^0.13.4", "escodegen": "^2.1.0", "esprima": "^4.0.1" } }, "sha512-TllpMR/t0M5sqCXfj85i4XaAzxmS5tVA16dqvdkMwGmzI+dXLXnw3J+3Vdv7VKw+ThlTMboK6i9rnZ6Nntj5CQ=="],
+
     "delayed-stream": ["delayed-stream@1.0.0", "", {}, "sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ=="],
 
     "depd": ["depd@2.0.0", "", {}, "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw=="],
@@ -1287,6 +1549,8 @@
 
     "escape-string-regexp": ["escape-string-regexp@5.0.0", "", {}, "sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw=="],
 
+    "escodegen": ["escodegen@2.1.0", "", { "dependencies": { "esprima": "^4.0.1", "estraverse": "^5.2.0", "esutils": "^2.0.2" }, "optionalDependencies": { "source-map": "~0.6.1" }, "bin": { "esgenerate": "bin/esgenerate.js", "escodegen": "bin/escodegen.js" } }, "sha512-2NlIDTwUWJN0mRPQOdtQBzbUHvdGY2P1VXSyU83Q3xKxM7WHX2Ql8dKq782Q9TgQUNOLEzEYu9bzLNj1q88I5w=="],
+
     "eslint": ["eslint@9.39.4", "", { "dependencies": { "@eslint-community/eslint-utils": "^4.8.0", "@eslint-community/regexpp": "^4.12.1", "@eslint/config-array": "^0.21.2", "@eslint/config-helpers": "^0.4.2", "@eslint/core": "^0.17.0", "@eslint/eslintrc": "^3.3.5", "@eslint/js": "9.39.4", "@eslint/plugin-kit": "^0.4.1", "@humanfs/node": "^0.16.6", "@humanwhocodes/module-importer": "^1.0.1", "@humanwhocodes/retry": "^0.4.2", "@types/estree": "^1.0.6", "ajv": "^6.14.0", "chalk": "^4.0.0", "cross-spawn": "^7.0.6", "debug": "^4.3.2", "escape-string-regexp": "^4.0.0", "eslint-scope": "^8.4.0", "eslint-visitor-keys": "^4.2.1", "espree": "^10.4.0", "esquery": "^1.5.0", "esutils": "^2.0.2", "fast-deep-equal": "^3.1.3", "file-entry-cache": "^8.0.0", "find-up": "^5.0.0", "glob-parent": "^6.0.2", "ignore": "^5.2.0", "imurmurhash": "^0.1.4", "is-glob": "^4.0.0", "json-stable-stringify-without-jsonify": "^1.0.1", "lodash.merge": "^4.6.2", "minimatch": "^3.1.5", "natural-compare": "^1.4.0", "optionator": "^0.9.3" }, "peerDependencies": { "jiti": "*" }, "optionalPeers": ["jiti"], "bin": { "eslint": "bin/eslint.js" } }, "sha512-XoMjdBOwe/esVgEvLmNsD3IRHkm7fbKIUGvrleloJXUZgDHig2IPWNniv+GwjyJXzuNqVjlr5+4yVUZjycJwfQ=="],
 
     "eslint-config-prettier": ["eslint-config-prettier@10.1.8", "", { "peerDependencies": { "eslint": ">=7.0.0" }, "bin": { "eslint-config-prettier": "bin/cli.js" } }, "sha512-82GZUjRS0p/jganf6q1rEO25VSoHH0hKPCTrgillPjdI/3bgBhAE1QzHrHTizjpRvy6pGAvKjDJtk2pF9NDq8w=="],
@@ -1341,6 +1605,8 @@
 
     "extend": ["extend@3.0.2", "", {}, "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g=="],
 
+    "extract-zip": ["extract-zip@2.0.1", "", { "dependencies": { "debug": "^4.1.1", "get-stream": "^5.1.0", "yauzl": "^2.10.0" }, "optionalDependencies": { "@types/yauzl": "^2.9.1" }, "bin": { "extract-zip": "cli.js" } }, "sha512-GDhU9ntwuKyGXdZBUgTIe+vXnWj0fppUEtMDL0+idd5Sta8TGpHssn/eusA9mrPr9qNDym6SxAYZjNvCn/9RBg=="],
+
     "fast-content-type-parse": ["fast-content-type-parse@3.0.0", "", {}, "sha512-ZvLdcY8P+N8mGQJahJV5G4U88CSvT1rP8ApL6uETe88MBXrBHAkZlSEySdUlyztF7ccb+Znos3TFqaepHxdhBg=="],
 
     "fast-copy": ["fast-copy@4.0.2", "", {}, "sha512-ybA6PDXIXOXivLJK/z9e+Otk7ve13I4ckBvGO5I2RRmBU1gMHLVDJYEuJYhGwez7YNlYji2M2DvVU+a9mSFDlw=="],
@@ -1357,8 +1623,14 @@
 
     "fast-uri": ["fast-uri@3.1.0", "", {}, "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA=="],
 
+    "fast-xml-builder": ["fast-xml-builder@1.1.4", "", { "dependencies": { "path-expression-matcher": "^1.1.3" } }, "sha512-f2jhpN4Eccy0/Uz9csxh3Nu6q4ErKxf0XIsasomfOihuSUa3/xw6w8dnOtCDgEItQFJG8KyXPzQXzcODDrrbOg=="],
+
+    "fast-xml-parser": ["fast-xml-parser@5.5.8", "", { "dependencies": { "fast-xml-builder": "^1.1.4", "path-expression-matcher": "^1.2.0", "strnum": "^2.2.0" }, "bin": { "fxparser": "src/cli/cli.js" } }, "sha512-Z7Fh2nVQSb2d+poDViM063ix2ZGt9jmY1nWhPfHBOK2Hgnb/OW3P4Et3P/81SEej0J7QbWtJqxO05h8QYfK7LQ=="],
+
     "fastq": ["fastq@1.20.1", "", { "dependencies": { "reusify": "^1.0.4" } }, "sha512-GGToxJ/w1x32s/D2EKND7kTil4n8OVk/9mycTc4VDza13lOvpUZTGX3mFSCtV9ksdGBVzvsyAVLM6mHFThxXxw=="],
 
+    "fd-slicer": ["fd-slicer@1.1.0", "", { "dependencies": { "pend": "~1.2.0" } }, "sha512-cE1qsB/VwyQozZ+q1dGxR8LBYNZeofhEdUNGSMbQD3Gw2lAzX9Zb3uIU6Ebc/Fmyjo9AWWfnn0AUCHqtevs/8g=="],
+
     "fdir": ["fdir@6.5.0", "", { "peerDependencies": { "picomatch": "^3 || ^4" }, "optionalPeers": ["picomatch"] }, "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg=="],
 
     "fetch-blob": ["fetch-blob@3.2.0", "", { "dependencies": { "node-domexception": "^1.0.0", "web-streams-polyfill": "^3.0.3" } }, "sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ=="],
@@ -1367,6 +1639,8 @@
 
     "file-entry-cache": ["file-entry-cache@8.0.0", "", { "dependencies": { "flat-cache": "^4.0.0" } }, "sha512-XXTUwCvisa5oacNGRP9SfNtYBNAMi+RPwBFmblZEF7N7swHYQS6/Zfk7SRwx4D5j3CH211YNRco1DEMNVfZCnQ=="],
 
+    "file-type": ["file-type@21.3.4", "", { "dependencies": { "@tokenizer/inflate": "^0.4.1", "strtok3": "^10.3.4", "token-types": "^6.1.1", "uint8array-extras": "^1.4.0" } }, "sha512-Ievi/yy8DS3ygGvT47PjSfdFoX+2isQueoYP1cntFW1JLYAuS4GD7NUPGg4zv2iZfV52uDyk5w5Z0TdpRS6Q1g=="],
+
     "fill-range": ["fill-range@7.1.1", "", { "dependencies": { "to-regex-range": "^5.0.1" } }, "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg=="],
 
     "finalhandler": ["finalhandler@2.1.1", "", { "dependencies": { "debug": "^4.4.0", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "on-finished": "^2.4.1", "parseurl": "^1.3.3", "statuses": "^2.0.1" } }, "sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA=="],
@@ -1403,6 +1677,10 @@
 
     "fzf": ["fzf@0.5.2", "", {}, "sha512-Tt4kuxLXFKHy8KT40zwsUPUkg1CrsgY25FxA2U/j/0WgEDCk3ddc/zLTCCcbSHX9FcKtLuVaDGtGE/STWC+j3Q=="],
 
+    "gaxios": ["gaxios@7.1.4", "", { "dependencies": { "extend": "^3.0.2", "https-proxy-agent": "^7.0.1", "node-fetch": "^3.3.2" } }, "sha512-bTIgTsM2bWn3XklZISBTQX7ZSddGW+IO3bMdGaemHZ3tbqExMENHLx6kKZ/KlejgrMtj8q7wBItt51yegqalrA=="],
+
+    "gcp-metadata": ["gcp-metadata@8.1.2", "", { "dependencies": { "gaxios": "^7.0.0", "google-logging-utils": "^1.0.0", "json-bigint": "^1.0.0" } }, "sha512-zV/5HKTfCeKWnxG0Dmrw51hEWFGfcF2xiXqcA3+J90WDuP0SvoiSO5ORvcBsifmx/FoIjgQN3oNOGaQ5PhLFkg=="],
+
     "gensync": ["gensync@1.0.0-beta.2", "", {}, "sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg=="],
 
     "get-caller-file": ["get-caller-file@2.0.5", "", {}, "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg=="],
@@ -1419,16 +1697,26 @@
 
     "get-stream": ["get-stream@8.0.1", "", {}, "sha512-VaUJspBffn/LMCJVoMvSAdmscJyS1auj5Zulnn5UoYcY531UWmdwhRWkcGKnGU93m5HSXP9LP2usOryrBtQowA=="],
 
+    "get-uri": ["get-uri@6.0.5", "", { "dependencies": { "basic-ftp": "^5.0.2", "data-uri-to-buffer": "^6.0.2", "debug": "^4.3.4" } }, "sha512-b1O07XYq8eRuVzBNgJLstU6FYc1tS6wnMtF1I1D9lE8LxZSOGZ7LhxN54yPP6mGw5f2CkXY2BQUL9Fx41qvcIg=="],
+
     "github-slugger": ["github-slugger@2.0.0", "", {}, "sha512-IaOQ9puYtjrkq7Y0Ygl9KDZnrf/aiUJYUpVf89y8kyaxbRG7Y1SrX/jaumrv81vc61+kiMempujsM3Yw7w5qcw=="],
 
+    "glob": ["glob@13.0.6", "", { "dependencies": { "minimatch": "^10.2.2", "minipass": "^7.1.3", "path-scurry": "^2.0.2" } }, "sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw=="],
+
     "glob-parent": ["glob-parent@6.0.2", "", { "dependencies": { "is-glob": "^4.0.3" } }, "sha512-XxwI8EOhVQgWp6iDL+3b0r86f4d6AX6zSU55HfB4ydCEuXLXc5FcYeOu+nnGftS4TEju/11rt4KJPTMgbfmv4A=="],
 
     "globals": ["globals@14.0.0", "", {}, "sha512-oahGvuMGQlPw/ivIYBjVSrWAfWLBeku5tpPE2fOPLi+WHffIWbuh2tCjhyQhTBPMf5E9jDEH4FOmTYgYwbKwtQ=="],
 
+    "google-auth-library": ["google-auth-library@10.6.2", "", { "dependencies": { "base64-js": "^1.3.0", "ecdsa-sig-formatter": "^1.0.11", "gaxios": "^7.1.4", "gcp-metadata": "8.1.2", "google-logging-utils": "1.1.3", "jws": "^4.0.0" } }, "sha512-e27Z6EThmVNNvtYASwQxose/G57rkRuaRbQyxM2bvYLLX/GqWZ5chWq2EBoUchJbCc57eC9ArzO5wMsEmWftCw=="],
+
+    "google-logging-utils": ["google-logging-utils@1.1.3", "", {}, "sha512-eAmLkjDjAFCVXg7A1unxHsLf961m6y17QFqXqAXGj/gVkKFrEICfStRfwUlGNfeCEjNRa32JEWOUTlYXPyyKvA=="],
+
     "gopd": ["gopd@1.2.0", "", {}, "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg=="],
 
     "graceful-fs": ["graceful-fs@4.2.11", "", {}, "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ=="],
 
+    "grammy": ["grammy@1.42.0", "", { "dependencies": { "@grammyjs/types": "3.26.0", "abort-controller": "^3.0.0", "debug": "^4.4.3", "node-fetch": "^2.7.0" } }, "sha512-1AdCge+AkjSdp2FwfICSFnVbl8Mq3KVHJDy+DgTI9+D6keJ0zWALPRKas5jv/8psiCzL4N2cEOcGW7O45Kn39g=="],
+
     "graphql": ["graphql@16.13.1", "", {}, "sha512-gGgrVCoDKlIZ8fIqXBBb0pPKqDgki0Z/FSKNiQzSGj2uEYHr1tq5wmBegGwJx6QB5S5cM0khSBpi/JFHMCvsmQ=="],
 
     "h3": ["h3@1.15.11", "", { "dependencies": { "cookie-es": "^1.2.3", "crossws": "^0.3.5", "defu": "^6.1.6", "destr": "^2.0.5", "iron-webcrypto": "^1.2.1", "node-mock-http": "^1.0.4", "radix3": "^1.1.2", "ufo": "^1.6.3", "uncrypto": "^0.1.3" } }, "sha512-L3THSe2MPeBwgIZVSH5zLdBBU90TOxarvhK9d04IDY2AmVS8j2Jz2LIWtwsGOU3lu2I5jCN7FNvVfY2+XyF+mg=="],
@@ -1489,6 +1777,8 @@
 
     "hono": ["hono@4.12.7", "", {}, "sha512-jq9l1DM0zVIvsm3lv9Nw9nlJnMNPOcAtsbsgiUhWcFzPE99Gvo6yRTlszSLLYacMeQ6quHD6hMfId8crVHvexw=="],
 
+    "hosted-git-info": ["hosted-git-info@9.0.2", "", { "dependencies": { "lru-cache": "^11.1.0" } }, "sha512-M422h7o/BR3rmCQ8UHi7cyyMqKltdP9Uo+J2fXK+RSAY+wTcKOIRyhTuKv4qn+DJf3g+PL890AzId5KZpX+CBg=="],
+
     "html-comment-regex": ["html-comment-regex@1.1.2", "", {}, "sha512-P+M65QY2JQ5Y0G9KKdlDpo0zK+/OHptU5AaBwUfAIDJZk1MYf32Frm84EcOytfJE0t5JvkAnKlmjsXDnWzCJmQ=="],
 
     "html-escaper": ["html-escaper@3.0.3", "", {}, "sha512-RuMffC89BOWQoY0WKGpIhn5gX3iI54O6nRA0yC124NYVtzjmFWBIiFd8M0x+ZdX0P9R4lADg1mgP8C7PxGOWuQ=="],
@@ -1503,6 +1793,8 @@
 
     "http-errors": ["http-errors@2.0.1", "", { "dependencies": { "depd": "~2.0.0", "inherits": "~2.0.4", "setprototypeof": "~1.2.0", "statuses": "~2.0.2", "toidentifier": "~1.0.1" } }, "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ=="],
 
+    "http-proxy-agent": ["http-proxy-agent@7.0.2", "", { "dependencies": { "agent-base": "^7.1.0", "debug": "^4.3.4" } }, "sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig=="],
+
     "https-proxy-agent": ["https-proxy-agent@7.0.6", "", { "dependencies": { "agent-base": "^7.1.2", "debug": "4" } }, "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw=="],
 
     "human-signals": ["human-signals@5.0.0", "", {}, "sha512-AXcZb6vzzrFAUE61HnN4mpLqd/cSIwNQjtNWR0euPm6y0iqx3G4gOXaIDdtdDwZmhwe82LA6+zinmW4UBWVePQ=="],
@@ -1513,6 +1805,8 @@
 
     "iconv-lite": ["iconv-lite@0.7.2", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw=="],
 
+    "ieee754": ["ieee754@1.2.1", "", {}, "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA=="],
+
     "ignore": ["ignore@5.3.2", "", {}, "sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g=="],
 
     "import-fresh": ["import-fresh@3.3.1", "", { "dependencies": { "parent-module": "^1.0.0", "resolve-from": "^4.0.0" } }, "sha512-TR3KfrTZTYLPB6jUjfx6MF9WcWrHL9su5TObK4ZkYgBdWKPOFoSoQIdEuTuR82pmtxH2spWG9h6etwfr1pLBqQ=="],
@@ -1593,6 +1887,8 @@
 
     "jsesc": ["jsesc@3.1.0", "", { "bin": { "jsesc": "bin/jsesc" } }, "sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA=="],
 
+    "json-bigint": ["json-bigint@1.0.0", "", { "dependencies": { "bignumber.js": "^9.0.0" } }, "sha512-SiPv/8VpZuWbvLSMtTDU8hEfrZWg/mH/nV/b4o0CYbSxu1UIQPLdwKOCIyLQX+VIPO5vrLX3i8qtqFyhdPSUSQ=="],
+
     "json-buffer": ["json-buffer@3.0.1", "", {}, "sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ=="],
 
     "json-parse-even-better-errors": ["json-parse-even-better-errors@2.3.1", "", {}, "sha512-xyFwyhro/JEof6Ghe2iz2NcXoj2sloNsWr/XsERDK/oiPCfaNhl5ONfp+jQdAZRQQ0IJWNzH9zIZF7li91kh2w=="],
@@ -1623,6 +1919,8 @@
 
     "klona": ["klona@2.0.6", "", {}, "sha512-dhG34DXATL5hSxJbIexCft8FChFXtmskoZYnoPWjXQuebWYCNkVeV3KkGegCK9CP1oswI/vQibS2GY7Em/sJJA=="],
 
+    "koffi": ["koffi@2.16.0", "", {}, "sha512-h/2NJueOKWd0YYycEOWDspomizgNfuOKf/V7ZE2fytvuRtHoY9Tb+y4x6GJ6pFqaVndWn9dLK+sCI14eWtu5rA=="],
+
     "levn": ["levn@0.4.1", "", { "dependencies": { "prelude-ls": "^1.2.1", "type-check": "~0.4.0" } }, "sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ=="],
 
     "lightningcss": ["lightningcss@1.31.1", "", { "dependencies": { "detect-libc": "^2.0.3" }, "optionalDependencies": { "lightningcss-android-arm64": "1.31.1", "lightningcss-darwin-arm64": "1.31.1", "lightningcss-darwin-x64": "1.31.1", "lightningcss-freebsd-x64": "1.31.1", "lightningcss-linux-arm-gnueabihf": "1.31.1", "lightningcss-linux-arm64-gnu": "1.31.1", "lightningcss-linux-arm64-musl": "1.31.1", "lightningcss-linux-x64-gnu": "1.31.1", "lightningcss-linux-x64-musl": "1.31.1", "lightningcss-win32-arm64-msvc": "1.31.1", "lightningcss-win32-x64-msvc": "1.31.1" } }, "sha512-l51N2r93WmGUye3WuFoN5k10zyvrVs0qfKBhyC5ogUQ6Ew6JUSswh78mbSO+IU3nTWsyOArqPCcShdQSadghBQ=="],
@@ -1683,6 +1981,8 @@
 
     "log-update": ["log-update@6.1.0", "", { "dependencies": { "ansi-escapes": "^7.0.0", "cli-cursor": "^5.0.0", "slice-ansi": "^7.1.0", "strip-ansi": "^7.1.0", "wrap-ansi": "^9.0.0" } }, "sha512-9ie8ItPR6tjY5uYJh8K/Zrv/RMZ5VOlOWvtZdEHYSTFKZfIBPQa9tOAEeAWhd+AnIneLJ22w5fjOYtoutpWq5w=="],
 
+    "long": ["long@5.3.2", "", {}, "sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA=="],
+
     "longest-streak": ["longest-streak@3.1.0", "", {}, "sha512-9Ri+o0JYgehTaVBBDoMqIl8GXtbWg711O3srftcHhZ0dqnETqLaoIK0x17fUw9rFSlK/0NlsKe0Ahhyl5pXE2g=="],
 
     "lowlight": ["lowlight@3.3.0", "", { "dependencies": { "@types/hast": "^3.0.0", "devlop": "^1.0.0", "highlight.js": "~11.11.0" } }, "sha512-0JNhgFoPvP6U6lE/UdVsSq99tn6DhjjpAj5MxG49ewd2mOBVtwWYIT8ClyABhq198aXXODMU6Ox8DrGy/CpTZQ=="],
@@ -1701,6 +2001,8 @@
 
     "markdown-table": ["markdown-table@3.0.4", "", {}, "sha512-wiYz4+JrLyb/DqW2hkFJxP7Vd7JuTDm77fvbM8VfEQdmSMqcImWeeRbHwZjBjIFki/VaMK2BhFi7oUUZeM5bqw=="],
 
+    "marked": ["marked@15.0.12", "", { "bin": { "marked": "bin/marked.js" } }, "sha512-8dD6FusOQSrpv9Z1rdNMdlSgQOIP880DHqnohobOmYLElGEqAL/JvxvuxZO16r4HtjTlfPRDC1hbvxC9dPN2nA=="],
+
     "math-intrinsics": ["math-intrinsics@1.1.0", "", {}, "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g=="],
 
     "mdast-util-definitions": ["mdast-util-definitions@6.0.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "@types/unist": "^3.0.0", "unist-util-visit": "^5.0.0" } }, "sha512-scTllyX6pnYNZH/AIp/0ePz6s4cZtARxImwoPJ7kS42n+MnVsI4XbnG6d4ibehRIldYMWM2LD7ImQblVhUejVQ=="],
@@ -1837,7 +2139,7 @@
 
     "minimist": ["minimist@1.2.8", "", {}, "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA=="],
 
-    "mri": ["mri@1.2.0", "", {}, "sha512-tzzskb3bG8LvYGFF/mDTpq3jpI6Q9wc3LEmBaghu+DdCssd1FakN7Bc0hVNmEyGq1bq3RgfkCb3cmQLpNPOroA=="],
+    "minipass": ["minipass@7.1.3", "", {}, "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A=="],
 
     "mrmime": ["mrmime@2.0.1", "", {}, "sha512-Y3wQdFg2Va6etvQ5I82yUhGdsKrcYox6p7FfL1LbK2J4V01F9TGlepTIhnK24t7koZibmg82KGglhA1XK5IsLQ=="],
 
@@ -1847,6 +2149,8 @@
 
     "mute-stream": ["mute-stream@2.0.0", "", {}, "sha512-WWdIxpyjEn+FhQJQQv9aQAYlHoNVdzIzUySNV1gHUPDSdZJ3yZn7pAAbQcV7B56Mvu881q9FZV+0Vx2xC44VWA=="],
 
+    "mz": ["mz@2.7.0", "", { "dependencies": { "any-promise": "^1.0.0", "object-assign": "^4.0.1", "thenify-all": "^1.0.0" } }, "sha512-z81GNO7nnYMEhrGh9LeymoE4+Yr0Wn5McHIZMK5cfQCl+NDX08sCZgUc9/6MHni9IWuFLm1Z3HTCXu2z9fN62Q=="],
+
     "nanoid": ["nanoid@3.3.11", "", { "bin": { "nanoid": "bin/nanoid.cjs" } }, "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w=="],
 
     "natural-compare": ["natural-compare@1.4.0", "", {}, "sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw=="],
@@ -1855,6 +2159,8 @@
 
     "neotraverse": ["neotraverse@0.6.18", "", {}, "sha512-Z4SmBUweYa09+o6pG+eASabEpP6QkQ70yHj351pQoEXIs8uHbaU2DWVmzBANKgflPa47A50PtB2+NgRpQvr7vA=="],
 
+    "netmask": ["netmask@2.1.1", "", {}, "sha512-eonl3sLUha+S1GzTPxychyhnUzKyeQkZ7jLjKrBagJgPla13F+uQ71HgpFefyHgqrjEbCPkDArxYsjY8/+gLKA=="],
+
     "nlcst-to-string": ["nlcst-to-string@4.0.0", "", { "dependencies": { "@types/nlcst": "^2.0.0" } }, "sha512-YKLBCcUYKAg0FNlOBT6aI91qFmSiFKiluk655WzPF+DDMA02qIyy8uiRqI8QXtcFpEvll12LpL5MXqEmAZ+dcA=="],
 
     "node-domexception": ["node-domexception@1.0.0", "", {}, "sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ=="],
@@ -1899,6 +2205,8 @@
 
     "open": ["open@11.0.0", "", { "dependencies": { "default-browser": "^5.4.0", "define-lazy-prop": "^3.0.0", "is-in-ssh": "^1.0.0", "is-inside-container": "^1.0.0", "powershell-utils": "^0.1.0", "wsl-utils": "^0.3.0" } }, "sha512-smsWv2LzFjP03xmvFoJ331ss6h+jixfA4UUV/Bsiyuu4YJPfN+FIQGOIiv4w9/+MoHkfkJ22UIaQWRVFRfH6Vw=="],
 
+    "openai": ["openai@6.26.0", "", { "peerDependencies": { "ws": "^8.18.0", "zod": "^3.25 || ^4.0" }, "optionalPeers": ["ws", "zod"], "bin": { "openai": "bin/cli" } }, "sha512-zd23dbWTjiJ6sSAX6s0HrCZi41JwTA1bQVs0wLQPZ2/5o2gxOJA5wh7yOAUgwYybfhDXyhwlpeQf7Mlgx8EOCA=="],
+
     "openapi-typescript": ["openapi-typescript@7.13.0", "", { "dependencies": { "@redocly/openapi-core": "^1.34.6", "ansi-colors": "^4.1.3", "change-case": "^5.4.4", "parse-json": "^8.3.0", "supports-color": "^10.2.2", "yargs-parser": "^21.1.1" }, "peerDependencies": { "typescript": "^5.x" }, "bin": { "openapi-typescript": "bin/cli.js" } }, "sha512-EFP392gcqXS7ntPvbhBzbF8TyBA+baIYEm791Hy5YkjDYKTnk/Tn5OQeKm5BIZvJihpp8Zzr4hzx0Irde1LNGQ=="],
 
     "openapi3-ts": ["openapi3-ts@4.5.0", "", { "dependencies": { "yaml": "^2.8.0" } }, "sha512-jaL+HgTq2Gj5jRcfdutgRGLosCy/hT8sQf6VOy+P+g36cZOjI1iukdPnijC+4CmeRzg/jEllJUboEic2FhxhtQ=="],
@@ -1919,7 +2227,11 @@
 
     "p-retry": ["p-retry@4.6.2", "", { "dependencies": { "@types/retry": "0.12.0", "retry": "^0.13.1" } }, "sha512-312Id396EbJdvRONlngUx0NydfrIQ5lsYu0znKVUzVvArzEIt08V1qhtyESbGVd1FGX7UKtiFp5uwKZdM8wIuQ=="],
 
-    "p-timeout": ["p-timeout@4.1.0", "", {}, "sha512-+/wmHtzJuWii1sXn3HCuH/FTwGhrp4tmJTxSKJbfS+vkipci6osxXM5mY0jUiRzWKMTgUT8l7HFbeSwZAynqHw=="],
+    "p-timeout": ["p-timeout@7.0.1", "", {}, "sha512-AxTM2wDGORHGEkPCt8yqxOTMgpfbEHqF51f/5fJCmwFC3C/zNcGT63SymH2ttOAaiIws2zVg4+izQCjrakcwHg=="],
+
+    "pac-proxy-agent": ["pac-proxy-agent@7.2.0", "", { "dependencies": { "@tootallnate/quickjs-emscripten": "^0.23.0", "agent-base": "^7.1.2", "debug": "^4.3.4", "get-uri": "^6.0.1", "http-proxy-agent": "^7.0.0", "https-proxy-agent": "^7.0.6", "pac-resolver": "^7.0.1", "socks-proxy-agent": "^8.0.5" } }, "sha512-TEB8ESquiLMc0lV8vcd5Ql/JAKAoyzHFXaStwjkzpOpC5Yv+pIzLfHvjTSdf3vpa2bMiUQrg9i6276yn8666aA=="],
+
+    "pac-resolver": ["pac-resolver@7.0.1", "", { "dependencies": { "degenerator": "^5.0.0", "netmask": "^2.0.2" } }, "sha512-5NPgf87AT2STgwa2ntRMr45jTKrYBGkVU36yT0ig/n/GMAa3oPqhZfIQ2kMEimReg0+t9kZViDVZ83qfVUlckg=="],
 
     "package-manager-detector": ["package-manager-detector@1.6.0", "", {}, "sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA=="],
 
@@ -1937,16 +2249,26 @@
 
     "parse5": ["parse5@7.3.0", "", { "dependencies": { "entities": "^6.0.0" } }, "sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw=="],
 
+    "parse5-htmlparser2-tree-adapter": ["parse5-htmlparser2-tree-adapter@6.0.1", "", { "dependencies": { "parse5": "^6.0.1" } }, "sha512-qPuWvbLgvDGilKc5BoicRovlT4MtYT6JfJyBOMDsKoiT+GiuP5qyrPCnR9HcPECIJJmZh5jRndyNThnhhb/vlA=="],
+
     "parseurl": ["parseurl@1.3.3", "", {}, "sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ=="],
 
+    "partial-json": ["partial-json@0.1.7", "", {}, "sha512-Njv/59hHaokb/hRUjce3Hdv12wd60MtM9Z5Olmn+nehe0QDAsRtRbJPvJ0Z91TusF0SuZRIvnM+S4l6EIP8leA=="],
+
     "path-browserify": ["path-browserify@1.0.1", "", {}, "sha512-b7uo2UCUOYZcnF/3ID0lulOJi/bafxa1xPe7ZPsammBSpjSWQkjNxlt635YGS2MiR9GjvuXCtz2emr3jbsz98g=="],
 
     "path-exists": ["path-exists@4.0.0", "", {}, "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w=="],
 
+    "path-expression-matcher": ["path-expression-matcher@1.5.0", "", {}, "sha512-cbrerZV+6rvdQrrD+iGMcZFEiiSrbv9Tfdkvnusy6y0x0GKBXREFg/Y65GhIfm0tnLntThhzCnfKwp1WRjeCyQ=="],
+
     "path-key": ["path-key@3.1.1", "", {}, "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q=="],
 
+    "path-scurry": ["path-scurry@2.0.2", "", { "dependencies": { "lru-cache": "^11.0.0", "minipass": "^7.1.2" } }, "sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg=="],
+
     "path-to-regexp": ["path-to-regexp@8.3.0", "", {}, "sha512-7jdwVIRtsP8MYpdXSwOS0YdD0Du+qOoF/AEPIt88PcCFrZCzx41oxku1jD88hZBwbNUIEfpqvuhjFaMAqMTWnA=="],
 
+    "pend": ["pend@1.2.0", "", {}, "sha512-F3asv42UuXchdzt+xXqfW1OGlVBe+mxa2mqI0pg5yAHZPvFmY3Y6drSf/GQ1A86WgWEN9Kzh/WrgKa6iGcHXLg=="],
+
     "pg": ["pg@8.20.0", "", { "dependencies": { "pg-connection-string": "^2.12.0", "pg-pool": "^3.13.0", "pg-protocol": "^1.13.0", "pg-types": "2.2.0", "pgpass": "1.0.5" }, "optionalDependencies": { "pg-cloudflare": "^1.3.0" }, "peerDependencies": { "pg-native": ">=3.0.1" }, "optionalPeers": ["pg-native"] }, "sha512-ldhMxz2r8fl/6QkXnBD3CR9/xg694oT6DZQ2s6c/RI28OjtSOpxnPrUCGOBJ46RCUxcWdx3p6kw/xnDHjKvaRA=="],
 
     "pg-cloudflare": ["pg-cloudflare@1.3.0", "", {}, "sha512-6lswVVSztmHiRtD6I8hw4qP/nDm1EJbKMRhf3HCYaqud7frGysPv7FYJ5noZQdhQtN2xJnimfMtvQq21pdbzyQ=="],
@@ -1997,6 +2319,8 @@
 
     "postgres-interval": ["postgres-interval@1.2.0", "", { "dependencies": { "xtend": "^4.0.0" } }, "sha512-9ZhXKM/rw350N1ovuWHbGxnGh/SNJ4cnxHiM0rxE4VN41wsg8P8zWn9hv/buK00RP4WvlOyr/RBDiptyxVbkZQ=="],
 
+    "posthog-node": ["posthog-node@5.29.2", "", { "dependencies": { "@posthog/core": "1.25.2" }, "peerDependencies": { "rxjs": "^7.0.0" }, "optionalPeers": ["rxjs"] }, "sha512-rI7kkF0XqDc0G1qjx+Hb4iuY9NAlL+XQNoGOpnEpRNTUcXvjY6WlsRGZ9m2whgc39emrrYdszi/YT8wZkr2xsg=="],
+
     "powershell-utils": ["powershell-utils@0.1.0", "", {}, "sha512-dM0jVuXJPsDN6DvRpea484tCUaMiXWjuCn++HGTqUWzGDjv5tZkEZldAJ/UMlqRYGFrD/etByo4/xOuC/snX2A=="],
 
     "prelude-ls": ["prelude-ls@1.2.1", "", {}, "sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g=="],
@@ -2011,11 +2335,17 @@
 
     "prompts": ["prompts@2.4.2", "", { "dependencies": { "kleur": "^3.0.3", "sisteransi": "^1.0.5" } }, "sha512-NxNv/kLguCA7p3jE8oL2aEBsrJWgAakBpgmgK6lpPWV+WuOmY6r2/zbAVnP+T8bQlA0nzHXSJSJW0Hq7ylaD2Q=="],
 
+    "proper-lockfile": ["proper-lockfile@4.1.2", "", { "dependencies": { "graceful-fs": "^4.2.4", "retry": "^0.12.0", "signal-exit": "^3.0.2" } }, "sha512-TjNPblN4BwAWMXU8s9AEz4JmQxnD1NNL7bNOY/AKUzyamc379FWASUhc/K1pL2noVb+XmZKLL68cjzLsiOAMaA=="],
+
     "property-information": ["property-information@7.1.0", "", {}, "sha512-TwEZ+X+yCJmYfL7TPUOcvBZ4QfoT5YenQiJuX//0th53DE6w0xxLEtfK3iyryQFddXuvkIk51EEgrJQ0WJkOmQ=="],
 
+    "protobufjs": ["protobufjs@7.5.5", "", { "dependencies": { "@protobufjs/aspromise": "^1.1.2", "@protobufjs/base64": "^1.1.2", "@protobufjs/codegen": "^2.0.4", "@protobufjs/eventemitter": "^1.1.0", "@protobufjs/fetch": "^1.1.0", "@protobufjs/float": "^1.0.2", "@protobufjs/inquire": "^1.1.0", "@protobufjs/path": "^1.1.2", "@protobufjs/pool": "^1.1.0", "@protobufjs/utf8": "^1.1.0", "@types/node": ">=13.7.0", "long": "^5.0.0" } }, "sha512-3wY1AxV+VBNW8Yypfd1yQY9pXnqTAN+KwQxL8iYm3/BjKYMNg4i0owhEe26PWDOMaIrzeeF98Lqd5NGz4omiIg=="],
+
     "proxy-addr": ["proxy-addr@2.0.7", "", { "dependencies": { "forwarded": "0.2.0", "ipaddr.js": "1.9.1" } }, "sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg=="],
 
-    "proxy-from-env": ["proxy-from-env@1.1.0", "", {}, "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg=="],
+    "proxy-agent": ["proxy-agent@6.5.0", "", { "dependencies": { "agent-base": "^7.1.2", "debug": "^4.3.4", "http-proxy-agent": "^7.0.1", "https-proxy-agent": "^7.0.6", "lru-cache": "^7.14.1", "pac-proxy-agent": "^7.1.0", "proxy-from-env": "^1.1.0", "socks-proxy-agent": "^8.0.5" } }, "sha512-TmatMXdr2KlRiA2CyDu8GqR8EjahTG3aY3nXjdzFyoZbmB8hrBsTyMezhULIXKnC0jpfjlmiZ3+EaCzoInSu/A=="],
+
+    "proxy-from-env": ["proxy-from-env@2.1.0", "", {}, "sha512-cJ+oHTW1VAEa8cJslgmUZrc+sjRKgAKl3Zyse6+PV38hZe/V6Z14TbCuXcan9F9ghlz4QrFr2c92TNF82UkYHA=="],
 
     "pump": ["pump@3.0.4", "", { "dependencies": { "end-of-stream": "^1.1.0", "once": "^1.3.1" } }, "sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA=="],
 
@@ -2143,14 +2473,10 @@
 
     "safe-buffer": ["safe-buffer@5.2.1", "", {}, "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ=="],
 
-    "safe-compare": ["safe-compare@1.1.4", "", { "dependencies": { "buffer-alloc": "^1.2.0" } }, "sha512-b9wZ986HHCo/HbKrRpBJb2kqXMK9CEWIE1egeEvZsYn69ay3kdfl9nG3RyOcR+jInTDf7a86WQ1d4VJX7goSSQ=="],
-
     "safe-stable-stringify": ["safe-stable-stringify@2.5.0", "", {}, "sha512-b3rppTKm9T+PsVCBEOUR46GWI7fdOs00VKZ1+9c1EWDaDMvjQc6tUwuFyIprgGgTcWoVHSKrU8H31ZHA2e0RHA=="],
 
     "safer-buffer": ["safer-buffer@2.1.2", "", {}, "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg=="],
 
-    "sandwich-stream": ["sandwich-stream@2.0.2", "", {}, "sha512-jLYV0DORrzY3xaz/S9ydJL6Iz7essZeAfnAavsJ+zsJGZ1MOnsS52yRjU3uF3pJa/lla7+wisp//fxOwOH8SKQ=="],
-
     "sax": ["sax@1.6.0", "", {}, "sha512-6R3J5M4AcbtLUdZmRv2SygeVaM7IhrLXu9BmnOGmmACak8fiUtOsYNWUS4uK7upbmHIBbLBeFeI//477BKLBzA=="],
 
     "scheduler": ["scheduler@0.27.0", "", {}, "sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q=="],
@@ -2195,8 +2521,14 @@
 
     "slice-ansi": ["slice-ansi@5.0.0", "", { "dependencies": { "ansi-styles": "^6.0.0", "is-fullwidth-code-point": "^4.0.0" } }, "sha512-FC+lgizVPfie0kkhqUScwRu1O/lF6NOgJmlCgK+/LYxDCTk8sGelYaHDhFcDN+Sn3Cv+3VSa4Byeo+IMCzpMgQ=="],
 
+    "smart-buffer": ["smart-buffer@4.2.0", "", {}, "sha512-94hK0Hh8rPqQl2xXc3HsaBoOXKV20MToPkcXvwbISWLEs+64sBq5kFgn2kJDHb1Pry9yrP0dxrCI9RRci7RXKg=="],
+
     "smol-toml": ["smol-toml@1.6.1", "", {}, "sha512-dWUG8F5sIIARXih1DTaQAX4SsiTXhInKf1buxdY9DIg4ZYPZK5nGM1VRIYmEbDbsHt7USo99xSLFu5Q1IqTmsg=="],
 
+    "socks": ["socks@2.8.7", "", { "dependencies": { "ip-address": "^10.0.1", "smart-buffer": "^4.2.0" } }, "sha512-HLpt+uLy/pxB+bum/9DzAgiKS8CX1EvbWxI4zlmgGCExImLdiad2iCwXT5Z4c9c3Eq8rP2318mPW2c+QbtjK8A=="],
+
+    "socks-proxy-agent": ["socks-proxy-agent@8.0.5", "", { "dependencies": { "agent-base": "^7.1.2", "debug": "^4.3.4", "socks": "^2.8.3" } }, "sha512-HehCEsotFqbPW9sJ8WVYB6UbmIMv7kUUORIF2Nncq4VQvBfNBLibW9YZR5dlYCSUhwcD628pRllm7n+E+YTzJw=="],
+
     "sonic-boom": ["sonic-boom@4.2.1", "", { "dependencies": { "atomic-sleep": "^1.0.0" } }, "sha512-w6AxtubXa2wTXAUsZMMWERrsIRAdrK0Sc+FUytWvYAhBJLyuI4llrMIC1DtlNSdI99EI86KZum2MMq3EAZlF9Q=="],
 
     "source-map": ["source-map@0.7.6", "", {}, "sha512-i5uvt8C3ikiWeNZSVZNWcfZPItFQOsYTUAOkcUPGd8DqDy1uOUikjt5dG+uRlwyvR108Fb9DOd4GvXfT0N2/uQ=="],
@@ -2209,6 +2541,8 @@
 
     "statuses": ["statuses@2.0.2", "", {}, "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw=="],
 
+    "std-env": ["std-env@3.10.0", "", {}, "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg=="],
+
     "stdin-discarder": ["stdin-discarder@0.2.2", "", {}, "sha512-UhDfHmA92YAlNnCfhmq0VeNL5bDbiZGg7sZ2IvPsXubGkiNa9EC+tUTsjBRsYUAz87btI6/1wf4XoVvQ3uRnmQ=="],
 
     "stream-replace-string": ["stream-replace-string@2.0.0", "", {}, "sha512-TlnjJ1C0QrmxRNrON00JvaFFlNh5TTG00APw23j74ET7gkQpTASi6/L2fuiav8pzK715HXtUeClpBTw2NPSn6w=="],
@@ -2231,6 +2565,10 @@
 
     "strip-json-comments": ["strip-json-comments@5.0.3", "", {}, "sha512-1tB5mhVo7U+ETBKNf92xT4hrQa3pm0MZ0PQvuDnWgAAGHDsfp4lPSpiS6psrSiet87wyGPh9ft6wmhOMQ0hDiw=="],
 
+    "strnum": ["strnum@2.2.3", "", {}, "sha512-oKx6RUCuHfT3oyVjtnrmn19H1SiCqgJSg+54XqURKp5aCMbrXrhLjRN9TjuwMjiYstZ0MzDrHqkGZ5dFTKd+zg=="],
+
+    "strtok3": ["strtok3@10.3.5", "", { "dependencies": { "@tokenizer/token": "^0.3.0" } }, "sha512-ki4hZQfh5rX0QDLLkOCj+h+CVNkqmp/CMf8v8kZpkNVK6jGQooMytqzLZYUVYIZcFZ6yDB70EfD8POcFXiF5oA=="],
+
     "style-to-js": ["style-to-js@1.1.21", "", { "dependencies": { "style-to-object": "1.0.14" } }, "sha512-RjQetxJrrUJLQPHbLku6U/ocGtzyjbJMP9lCNK7Ag0CNh690nSH8woqWH9u16nMjYBAok+i7JO1NP2pOy8IsPQ=="],
 
     "style-to-object": ["style-to-object@1.0.14", "", { "dependencies": { "inline-style-parser": "0.2.7" } }, "sha512-LIN7rULI0jBscWQYaSswptyderlarFkjQ+t79nzty8tcIAceVomEVlLzH5VP4Cmsv6MtKhs7qaAiwlcp+Mgaxw=="],
@@ -2247,10 +2585,12 @@
 
     "tapable": ["tapable@2.3.0", "", {}, "sha512-g9ljZiwki/LfxmQADO3dEY1CbpmXT5Hm2fJ+QaGKwSXUylMybePR7/67YW7jOrrvjEgL1Fmz5kzyAjWVWLlucg=="],
 
-    "telegraf": ["telegraf@4.16.3", "", { "dependencies": { "@telegraf/types": "^7.1.0", "abort-controller": "^3.0.0", "debug": "^4.3.4", "mri": "^1.2.0", "node-fetch": "^2.7.0", "p-timeout": "^4.1.0", "safe-compare": "^1.1.4", "sandwich-stream": "^2.0.2" }, "bin": { "telegraf": "lib/cli.mjs" } }, "sha512-yjEu2NwkHlXu0OARWoNhJlIjX09dRktiMQFsM678BAH/PEPVwctzL67+tvXqLCRQQvm3SDtki2saGO9hLlz68w=="],
-
     "telegramify-markdown": ["telegramify-markdown@1.3.2", "", { "dependencies": { "mdast-util-gfm-table": "^0.1.6", "mdast-util-to-markdown": "^0.6.2", "remark-gfm": "^1.0.0", "remark-parse": "^9.0.0", "remark-remove-comments": "^0.2.0", "remark-stringify": "^9.0.1", "unified": "^9.0.0", "unist-util-remove": "^2.0.1", "unist-util-visit": "^2.0.3" } }, "sha512-otv/SSjJD4MQGBYcRqkSchs84nYBYQoE2BqplQTIoIMN4nT0tDZgxbU5yjdBLkNxaQfkzYja27Hl/hcVJwewcg=="],
 
+    "thenify": ["thenify@3.3.1", "", { "dependencies": { "any-promise": "^1.0.0" } }, "sha512-RVZSIV5IG10Hk3enotrhvz0T9em6cyHBLkH/YAZuKqd8hRkKhSfCGIcP2KUY0EPxndzANBmNllzWPwak+bheSw=="],
+
+    "thenify-all": ["thenify-all@1.6.0", "", { "dependencies": { "thenify": ">= 3.1.0 < 4" } }, "sha512-RNxQH/qI8/t3thXJDwcstUO4zeqo64+Uy/+sNVRBx4Xn2OX+OZ9oP+iJnNFqplFra2ZUVeKCSa2oVWi3T4uVmA=="],
+
     "thread-stream": ["thread-stream@3.1.0", "", { "dependencies": { "real-require": "^0.2.0" } }, "sha512-OqyPZ9u96VohAyMfJykzmivOrY2wfMSf3C5TtFJVgN+Hm6aj+voFhlK+kZEIv2FBh1X6Xp3DlnCOfEQ3B2J86A=="],
 
     "tiny-inflate": ["tiny-inflate@1.0.3", "", {}, "sha512-pkY1fj1cKHb2seWDy0B16HeWyczlJA9/WW3u3c4z/NiWDsO3DOU5D7nhTLE9CF0yXv/QZFY7sEJmj24dK+Rrqw=="],
@@ -2271,6 +2611,8 @@
 
     "toidentifier": ["toidentifier@1.0.1", "", {}, "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA=="],
 
+    "token-types": ["token-types@6.1.2", "", { "dependencies": { "@borewit/text-codec": "^0.2.1", "@tokenizer/token": "^0.3.0", "ieee754": "^1.2.1" } }, "sha512-dRXchy+C0IgK8WPC6xvCHFRIWYUbqqdEIKPaKo/AcTUNzwLTK6AH7RjdLWsEZcAN/TBdtfUw3PYEgPr5VPr6ww=="],
+
     "tough-cookie": ["tough-cookie@6.0.1", "", { "dependencies": { "tldts": "^7.0.5" } }, "sha512-LktZQb3IeoUWB9lqR5EWTHgW/VTITCXg4D21M+lvybRVdylLrRMnqaIONLVb5mav8vM19m44HIcGq4qASeu2Qw=="],
 
     "tr46": ["tr46@0.0.3", "", {}, "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw=="],
@@ -2309,6 +2651,8 @@
 
     "ufo": ["ufo@1.6.3", "", {}, "sha512-yDJTmhydvl5lJzBmy/hyOAA0d+aqCBuwl818haVdYCRrWV84o7YyeVm4QlVHStqNrrJSTb6jKuFAVqAFsr+K3Q=="],
 
+    "uint8array-extras": ["uint8array-extras@1.5.0", "", {}, "sha512-rvKSBiC5zqCCiDZ9kAOszZcDvdAHwwIKJG33Ykj43OKcWsnmcBRL09YTU4nOeHZ8Y2a7l1MgTd08SBe9A8Qj6A=="],
+
     "ultrahtml": ["ultrahtml@1.6.0", "", {}, "sha512-R9fBn90VTJrqqLDwyMph+HGne8eqY1iPfYhPzZrvKpIfwkWZbcYlfpsb8B9dTvBfpy1/hqAD7Wi8EKfP9e8zdw=="],
 
     "uncrypto": ["uncrypto@0.1.3", "", {}, "sha512-Ql87qFHB3s/De2ClA9e0gsnS6zXG27SkTiSJwjCc9MebbfapQfuPzumMIUMi38ezPZVNFcHI9sUIepeQfw8J8Q=="],
@@ -2369,6 +2713,8 @@
 
     "util-deprecate": ["util-deprecate@1.0.2", "", {}, "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw=="],
 
+    "uuid": ["uuid@11.1.0", "", { "bin": { "uuid": "dist/esm/bin/uuid" } }, "sha512-0/A9rDy9P7cJ+8w1c9WD9V//9Wj15Ce2MPz8Ri6032usz+NfePxx5AcN3bN+r6ZL6jEo066/yNYB3tn4pQEx+A=="],
+
     "validate-npm-package-name": ["validate-npm-package-name@7.0.2", "", {}, "sha512-hVDIBwsRruT73PbK7uP5ebUt+ezEtCmzZz3F59BSr2F6OVFnJ/6h8liuvdLrQ88Xmnk6/+xGGuq+pG9WwTuy3A=="],
 
     "vary": ["vary@1.1.2", "", {}, "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg=="],
@@ -2417,10 +2763,12 @@
 
     "yaml-ast-parser": ["yaml-ast-parser@0.0.43", "", {}, "sha512-2PTINUwsRqSd+s8XxKaJWQlUuEMHJQyEuh2edBbW8KNJz0SJPwUSD2zRWqezFEdN7IzAgeuYHFUCF7o8zRdZ0A=="],
 
-    "yargs": ["yargs@17.7.2", "", { "dependencies": { "cliui": "^8.0.1", "escalade": "^3.1.1", "get-caller-file": "^2.0.5", "require-directory": "^2.1.1", "string-width": "^4.2.3", "y18n": "^5.0.5", "yargs-parser": "^21.1.1" } }, "sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w=="],
+    "yargs": ["yargs@16.2.0", "", { "dependencies": { "cliui": "^7.0.2", "escalade": "^3.1.1", "get-caller-file": "^2.0.5", "require-directory": "^2.1.1", "string-width": "^4.2.0", "y18n": "^5.0.5", "yargs-parser": "^20.2.2" } }, "sha512-D1mvvtDG0L5ft/jGWkLpG1+m0eQxOfaBvTNELraWj22wSVUMWxZUvYgJYcKh6jGGIkJFhH4IZPQhR4TKpc8mBw=="],
 
     "yargs-parser": ["yargs-parser@22.0.0", "", {}, "sha512-rwu/ClNdSMpkSrUb+d6BRsSkLUq1fmfsY6TOpYzTwvwkg1/NRG85KBy3kq++A8LKQwX6lsu+aWad+2khvuXrqw=="],
 
+    "yauzl": ["yauzl@2.10.0", "", { "dependencies": { "buffer-crc32": "~0.2.3", "fd-slicer": "~1.1.0" } }, "sha512-p4a9I6X6nu6IhoGmBqAcbJy1mlC4j27vEPZX9F4L4/vZT3Lyq1VkFHw/V/PUcB9Buo+DG3iHkT0x3Qya58zc3g=="],
+
     "yocto-queue": ["yocto-queue@1.2.2", "", {}, "sha512-4LCcse/U2MHZ63HAJVE+v71o7yOdIe4cZ70Wpf8D/IyjDKYQLV5GD46B+hSTjJsvV5PztjvHoU580EftxjDZFQ=="],
 
     "yoctocolors": ["yoctocolors@2.1.2", "", {}, "sha512-CzhO+pFNo8ajLM2d2IW/R93ipy99LWjtwblvC1RsoSUMZgyLbYFr221TnSNT7GjGdYui6P459mw9JH/g/zW2ug=="],
@@ -2437,7 +2785,7 @@
 
     "@antfu/ni/tinyexec": ["tinyexec@1.0.2", "", {}, "sha512-W/KYk+NFhkmsYpuHq5JykngiOCnxeVL8v8dFnqxSD8qEEdRfXk1SDM6JzNqcERbcGYj9tMrDQBYV9cjgnunFIg=="],
 
-    "@archon/core/@anthropic-ai/claude-agent-sdk": ["@anthropic-ai/claude-agent-sdk@0.2.89", "", { "dependencies": { "@anthropic-ai/sdk": "^0.74.0", "@modelcontextprotocol/sdk": "^1.27.1" }, "optionalDependencies": { "@img/sharp-darwin-arm64": "^0.34.2", "@img/sharp-darwin-x64": "^0.34.2", "@img/sharp-linux-arm": "^0.34.2", "@img/sharp-linux-arm64": "^0.34.2", "@img/sharp-linux-x64": "^0.34.2", "@img/sharp-linuxmusl-arm64": "^0.34.2", "@img/sharp-linuxmusl-x64": "^0.34.2", "@img/sharp-win32-arm64": "^0.34.2", "@img/sharp-win32-x64": "^0.34.2" }, "peerDependencies": { "zod": "^4.0.0" } }, "sha512-/9W0lyBGuGHw1uu7pQafsp6BLpxfqCv1QYE0Z/eZTX6lGHht4j4Q+O3UImzjsiyEE9cGkOAwZBGAEHDEqt+QUA=="],
+    "@archon/providers/@anthropic-ai/claude-agent-sdk": ["@anthropic-ai/claude-agent-sdk@0.2.89", "", { "dependencies": { "@anthropic-ai/sdk": "^0.74.0", "@modelcontextprotocol/sdk": "^1.27.1" }, "optionalDependencies": { "@img/sharp-darwin-arm64": "^0.34.2", "@img/sharp-darwin-x64": "^0.34.2", "@img/sharp-linux-arm": "^0.34.2", "@img/sharp-linux-arm64": "^0.34.2", "@img/sharp-linux-x64": "^0.34.2", "@img/sharp-linuxmusl-arm64": "^0.34.2", "@img/sharp-linuxmusl-x64": "^0.34.2", "@img/sharp-win32-arm64": "^0.34.2", "@img/sharp-win32-x64": "^0.34.2" }, "peerDependencies": { "zod": "^4.0.0" } }, "sha512-/9W0lyBGuGHw1uu7pQafsp6BLpxfqCv1QYE0Z/eZTX6lGHht4j4Q+O3UImzjsiyEE9cGkOAwZBGAEHDEqt+QUA=="],
 
     "@astrojs/markdown-remark/remark-parse": ["remark-parse@11.0.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "mdast-util-from-markdown": "^2.0.0", "micromark-util-types": "^2.0.0", "unified": "^11.0.0" } }, "sha512-FCxlKLNGknS5ba/1lmpYijMUzX2esxW5xQqjWxw2eHFfS2MSdaHVINFmhjo+qN1WhZhNimq0dZATN9pH0IDrpA=="],
 
@@ -2453,6 +2801,10 @@
 
     "@astrojs/starlight/unist-util-visit": ["unist-util-visit@5.1.0", "", { "dependencies": { "@types/unist": "^3.0.0", "unist-util-is": "^6.0.0", "unist-util-visit-parents": "^6.0.0" } }, "sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg=="],
 
+    "@aws-crypto/sha256-browser/@smithy/util-utf8": ["@smithy/util-utf8@2.3.0", "", { "dependencies": { "@smithy/util-buffer-from": "^2.2.0", "tslib": "^2.6.2" } }, "sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A=="],
+
+    "@aws-crypto/util/@smithy/util-utf8": ["@smithy/util-utf8@2.3.0", "", { "dependencies": { "@smithy/util-buffer-from": "^2.2.0", "tslib": "^2.6.2" } }, "sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A=="],
+
     "@babel/core/semver": ["semver@6.3.1", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA=="],
 
     "@babel/helper-compilation-targets/lru-cache": ["lru-cache@5.1.1", "", { "dependencies": { "yallist": "^3.0.2" } }, "sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w=="],
@@ -2495,6 +2847,26 @@
 
     "@inquirer/core/wrap-ansi": ["wrap-ansi@6.2.0", "", { "dependencies": { "ansi-styles": "^4.0.0", "string-width": "^4.1.0", "strip-ansi": "^6.0.0" } }, "sha512-r6lPcBGxZXlIcymEu7InxDMhdW0KDxpLgoFLcguasxCaJ/SOIZwINatK9KY/tf+ZrlywOKU0UDj3ATXUBfxJXA=="],
 
+    "@mariozechner/pi-ai/@anthropic-ai/sdk": ["@anthropic-ai/sdk@0.90.0", "", { "dependencies": { "json-schema-to-ts": "^3.1.1" }, "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" }, "optionalPeers": ["zod"], "bin": { "anthropic-ai-sdk": "bin/cli" } }, "sha512-MzZtPabJF1b0FTDl6Z6H5ljphPwACLGP13lu8MTiB8jXaW/YXlpOp+Po2cVou3MPM5+f5toyLnul9whKCy7fBg=="],
+
+    "@mariozechner/pi-ai/ajv": ["ajv@8.18.0", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A=="],
+
+    "@mariozechner/pi-ai/chalk": ["chalk@5.6.2", "", {}, "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA=="],
+
+    "@mariozechner/pi-ai/undici": ["undici@7.25.0", "", {}, "sha512-xXnp4kTyor2Zq+J1FfPI6Eq3ew5h6Vl0F/8d9XU5zZQf1tX9s2Su1/3PiMmUANFULpmksxkClamIZcaUqryHsQ=="],
+
+    "@mariozechner/pi-coding-agent/ajv": ["ajv@8.18.0", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A=="],
+
+    "@mariozechner/pi-coding-agent/chalk": ["chalk@5.6.2", "", {}, "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA=="],
+
+    "@mariozechner/pi-coding-agent/ignore": ["ignore@7.0.5", "", {}, "sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg=="],
+
+    "@mariozechner/pi-coding-agent/minimatch": ["minimatch@10.2.4", "", { "dependencies": { "brace-expansion": "^5.0.2" } }, "sha512-oRjTw/97aTBN0RHbYCdtF1MQfvusSIBQM0IZEgzl6426+8jSC0nF1a/GmnVLpfB9yyr6g6FTqWqiZVbxrtaCIg=="],
+
+    "@mariozechner/pi-coding-agent/undici": ["undici@7.25.0", "", {}, "sha512-xXnp4kTyor2Zq+J1FfPI6Eq3ew5h6Vl0F/8d9XU5zZQf1tX9s2Su1/3PiMmUANFULpmksxkClamIZcaUqryHsQ=="],
+
+    "@mariozechner/pi-tui/chalk": ["chalk@5.6.2", "", {}, "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA=="],
+
     "@mdx-js/mdx/estree-walker": ["estree-walker@3.0.3", "", { "dependencies": { "@types/estree": "^1.0.0" } }, "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g=="],
 
     "@mdx-js/mdx/remark-parse": ["remark-parse@11.0.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "mdast-util-from-markdown": "^2.0.0", "micromark-util-types": "^2.0.0", "unified": "^11.0.0" } }, "sha512-FCxlKLNGknS5ba/1lmpYijMUzX2esxW5xQqjWxw2eHFfS2MSdaHVINFmhjo+qN1WhZhNimq0dZATN9pH0IDrpA=="],
@@ -2503,6 +2875,8 @@
 
     "@mdx-js/mdx/unist-util-visit": ["unist-util-visit@5.1.0", "", { "dependencies": { "@types/unist": "^3.0.0", "unist-util-is": "^6.0.0", "unist-util-visit-parents": "^6.0.0" } }, "sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg=="],
 
+    "@mistralai/mistralai/zod": ["zod@4.3.6", "", {}, "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg=="],
+
     "@modelcontextprotocol/sdk/ajv": ["ajv@8.18.0", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A=="],
 
     "@redocly/ajv/json-schema-traverse": ["json-schema-traverse@1.0.0", "", {}, "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug=="],
@@ -2531,6 +2905,8 @@
 
     "@types/sax/@types/node": ["@types/node@24.12.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g=="],
 
+    "@types/yauzl/@types/node": ["@types/node@24.12.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g=="],
+
     "@typescript-eslint/eslint-plugin/ignore": ["ignore@7.0.5", "", {}, "sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg=="],
 
     "@typescript-eslint/typescript-estree/minimatch": ["minimatch@10.2.4", "", { "dependencies": { "brace-expansion": "^5.0.2" } }, "sha512-oRjTw/97aTBN0RHbYCdtF1MQfvusSIBQM0IZEgzl6426+8jSC0nF1a/GmnVLpfB9yyr6g6FTqWqiZVbxrtaCIg=="],
@@ -2553,6 +2929,10 @@
 
     "chalk/supports-color": ["supports-color@7.2.0", "", { "dependencies": { "has-flag": "^4.0.0" } }, "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw=="],
 
+    "cli-highlight/highlight.js": ["highlight.js@10.7.3", "", {}, "sha512-tzcUFauisWKNHaRkN4Wjl/ZA07gENAjFl3J/c480dprkGTg5EQstgaNFqBfUqCq54kZRIEcreTsAgF/m2quD7A=="],
+
+    "cli-highlight/parse5": ["parse5@5.1.1", "", {}, "sha512-ugq4DFI0Ptb+WWjAdOK16+u/nHfiIrcE+sh8kZMaM0WllQKLI9rOUq6c2b7cwPkXdzfQESqvoqK6ug7U/Yyzug=="],
+
     "cliui/string-width": ["string-width@4.2.3", "", { "dependencies": { "emoji-regex": "^8.0.0", "is-fullwidth-code-point": "^3.0.0", "strip-ansi": "^6.0.1" } }, "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g=="],
 
     "cliui/strip-ansi": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="],
@@ -2563,20 +2943,32 @@
 
     "csso/css-tree": ["css-tree@2.2.1", "", { "dependencies": { "mdn-data": "2.0.28", "source-map-js": "^1.0.1" } }, "sha512-OA0mILzGc1kCOCSJerOeqDxDQ4HOh+G8NbOJFOTgOCzpw7fCBubk0fEyxp8AgOL/jvLgYA/uV0cMbe43ElF1JA=="],
 
+    "degenerator/ast-types": ["ast-types@0.13.4", "", { "dependencies": { "tslib": "^2.0.1" } }, "sha512-x1FCFnFifvYDDzTaLII71vG5uvDwgtmDTEVWAxrgeiR8VjMONcCXJx7E+USjDtHlwFmt9MysbqgF9b9Vjr6w+w=="],
+
     "dom-serializer/entities": ["entities@4.5.0", "", {}, "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw=="],
 
     "error-ex/is-arrayish": ["is-arrayish@0.2.1", "", {}, "sha512-zz06S8t0ozoDXMG+ube26zeCTNXcKIPJZJi8hBrF4idCLms4CG9QtK7qBl1boi5ODzFpjswb5JPmHCbMpjaYzg=="],
 
+    "escodegen/source-map": ["source-map@0.6.1", "", {}, "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g=="],
+
     "eslint/escape-string-regexp": ["escape-string-regexp@4.0.0", "", {}, "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA=="],
 
     "estree-util-build-jsx/estree-walker": ["estree-walker@3.0.3", "", { "dependencies": { "@types/estree": "^1.0.0" } }, "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g=="],
 
     "express/cookie": ["cookie@0.7.2", "", {}, "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w=="],
 
+    "extract-zip/get-stream": ["get-stream@5.2.0", "", { "dependencies": { "pump": "^3.0.0" } }, "sha512-nBF+F1rAZVCu/p7rjzgA+Yb4lfYXrpl7a6VmJrU8wF9I1CKvP/QwPNZHnOlwbTkY6dvtFIzFMSyQXbLoTQPRpA=="],
+
     "fast-glob/glob-parent": ["glob-parent@5.1.2", "", { "dependencies": { "is-glob": "^4.0.1" } }, "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow=="],
 
     "form-data/mime-types": ["mime-types@2.1.35", "", { "dependencies": { "mime-db": "1.52.0" } }, "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw=="],
 
+    "gaxios/node-fetch": ["node-fetch@3.3.2", "", { "dependencies": { "data-uri-to-buffer": "^4.0.0", "fetch-blob": "^3.1.4", "formdata-polyfill": "^4.0.10" } }, "sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA=="],
+
+    "get-uri/data-uri-to-buffer": ["data-uri-to-buffer@6.0.2", "", {}, "sha512-7hvf7/GW8e86rW0ptuwS3OcBGDjIi6SZva7hCyWC0yYry2cOPmLIjXAUHI6DK2HsnwJd9ifmt57i8eV2n4YNpw=="],
+
+    "glob/minimatch": ["minimatch@10.2.4", "", { "dependencies": { "brace-expansion": "^5.0.2" } }, "sha512-oRjTw/97aTBN0RHbYCdtF1MQfvusSIBQM0IZEgzl6426+8jSC0nF1a/GmnVLpfB9yyr6g6FTqWqiZVbxrtaCIg=="],
+
     "hast-util-raw/unist-util-visit": ["unist-util-visit@5.1.0", "", { "dependencies": { "@types/unist": "^3.0.0", "unist-util-is": "^6.0.0", "unist-util-visit-parents": "^6.0.0" } }, "sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg=="],
 
     "hast-util-select/unist-util-visit": ["unist-util-visit@5.1.0", "", { "dependencies": { "@types/unist": "^3.0.0", "unist-util-is": "^6.0.0", "unist-util-visit-parents": "^6.0.0" } }, "sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg=="],
@@ -2607,6 +2999,8 @@
 
     "msw/type-fest": ["type-fest@5.4.4", "", { "dependencies": { "tagged-tag": "^1.0.0" } }, "sha512-JnTrzGu+zPV3aXIUhnyWJj4z/wigMsdYajGLIYakqyOW1nPllzXEJee0QQbHj+CTIQtXGlAjuK0UY+2xTyjVAw=="],
 
+    "msw/yargs": ["yargs@17.7.2", "", { "dependencies": { "cliui": "^8.0.1", "escalade": "^3.1.1", "get-caller-file": "^2.0.5", "require-directory": "^2.1.1", "string-width": "^4.2.3", "y18n": "^5.0.5", "yargs-parser": "^21.1.1" } }, "sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w=="],
+
     "npm-run-path/path-key": ["path-key@4.0.0", "", {}, "sha512-haREypq7xkM7ErfgIyA0z+Bj4AGKlMSdlQE2jvJo6huWD1EdkKYV+G/T4nq0YEF2vgTT8kqMFKo1uHn950r4SQ=="],
 
     "openapi-typescript/yargs-parser": ["yargs-parser@21.1.1", "", {}, "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw=="],
@@ -2615,20 +3009,30 @@
 
     "p-locate/p-limit": ["p-limit@3.1.0", "", { "dependencies": { "yocto-queue": "^0.1.0" } }, "sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ=="],
 
-    "p-queue/p-timeout": ["p-timeout@7.0.1", "", {}, "sha512-AxTM2wDGORHGEkPCt8yqxOTMgpfbEHqF51f/5fJCmwFC3C/zNcGT63SymH2ttOAaiIws2zVg4+izQCjrakcwHg=="],
-
     "parse-entities/character-entities": ["character-entities@1.2.4", "", {}, "sha512-iBMyeEHxfVnIakwOuDXpVkc54HijNgCyQB2w0VfGQThle6NXn50zU6V/u+LDhxHcDUPojn6Kpga3PTAD8W1bQw=="],
 
     "parse-entities/is-alphanumerical": ["is-alphanumerical@1.0.4", "", { "dependencies": { "is-alphabetical": "^1.0.0", "is-decimal": "^1.0.0" } }, "sha512-UzoZUr+XfVz3t3v4KyGEniVL9BDRoQtY7tOyrRybkVNjDFWyo1yhXNGrrBTQxp3ib9BLAWs7k2YKBQsFRkZG9A=="],
 
     "parse-entities/is-decimal": ["is-decimal@1.0.4", "", {}, "sha512-RGdriMmQQvZ2aqaQq3awNA6dCGtKpiDFcOzrTWrDAT2MiWrKQVPmxLGHl7Y2nNu6led0kEyoX0enY0qXYsv9zw=="],
 
+    "parse5-htmlparser2-tree-adapter/parse5": ["parse5@6.0.1", "", {}, "sha512-Ofn/CTFzRGTTxwpNEs9PP93gXShHcTq255nzRYSKe8AkVpZY7e1fpmTfOyoIvjP5HG7Z2ZM7VS9PPhQGW2pOpw=="],
+
     "pino/pino-abstract-transport": ["pino-abstract-transport@2.0.0", "", { "dependencies": { "split2": "^4.0.0" } }, "sha512-F63x5tizV6WCh4R6RHyi2Ml+M70DNRXt/+HANowMflpgGFMAym/VKm6G7ZOQRjqN7XbGxK1Lg9t6ZrtzOaivMw=="],
 
     "postcss-nested/postcss-selector-parser": ["postcss-selector-parser@6.1.2", "", { "dependencies": { "cssesc": "^3.0.0", "util-deprecate": "^1.0.2" } }, "sha512-Q8qQfPiZ+THO/3ZrOrO0cJJKfpYCagtMUkXbnEfmgUjwXg6z/WBeOyS9APBBPCTSiDV+s4SwQGu8yFsiMRIudg=="],
 
     "prompts/kleur": ["kleur@3.0.3", "", {}, "sha512-eTIzlVOSUR+JxdDFepEYcBMtZ9Qqdef+rnzWdRZuMbOywu5tO2w2N7rqjoANZ5k9vywhL6Br1VRjUIgTQx4E8w=="],
 
+    "proper-lockfile/retry": ["retry@0.12.0", "", {}, "sha512-9LkiTwjUh6rT555DtE9rTX+BKByPfrMzEAtnlEtdEwr3Nkffwiihqe2bWADg+OQRjt9gl6ICdmB/ZFDCGAtSow=="],
+
+    "proper-lockfile/signal-exit": ["signal-exit@3.0.7", "", {}, "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ=="],
+
+    "protobufjs/@types/node": ["@types/node@24.12.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g=="],
+
+    "proxy-agent/lru-cache": ["lru-cache@7.18.3", "", {}, "sha512-jumlc0BIUrS3qJGgIkWZsyfAM7NCWiBcCDhnd+3NNM5KbBmLTgHVfWBcg6W+rLUsIpzpERPsvwUP7CckAQSOoA=="],
+
+    "proxy-agent/proxy-from-env": ["proxy-from-env@1.1.0", "", {}, "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg=="],
+
     "react-markdown/remark-parse": ["remark-parse@11.0.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "mdast-util-from-markdown": "^2.0.0", "micromark-util-types": "^2.0.0", "unified": "^11.0.0" } }, "sha512-FCxlKLNGknS5ba/1lmpYijMUzX2esxW5xQqjWxw2eHFfS2MSdaHVINFmhjo+qN1WhZhNimq0dZATN9pH0IDrpA=="],
 
     "react-markdown/unified": ["unified@11.0.5", "", { "dependencies": { "@types/unist": "^3.0.0", "bail": "^2.0.0", "devlop": "^1.0.0", "extend": "^3.0.0", "is-plain-obj": "^4.0.0", "trough": "^2.0.0", "vfile": "^6.0.0" } }, "sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA=="],
@@ -2735,7 +3139,7 @@
 
     "yargs/string-width": ["string-width@4.2.3", "", { "dependencies": { "emoji-regex": "^8.0.0", "is-fullwidth-code-point": "^3.0.0", "strip-ansi": "^6.0.1" } }, "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g=="],
 
-    "yargs/yargs-parser": ["yargs-parser@21.1.1", "", {}, "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw=="],
+    "yargs/yargs-parser": ["yargs-parser@20.2.9", "", {}, "sha512-y11nGElTIV+CT3Zv9t7VKl+Q3hTQoT9a1Qzezhhl6Rp21gJ/IVTW7Z3y9EWXhuUBC2Shnf+DX0antecpAwSP8w=="],
 
     "@astrojs/markdown-remark/unified/bail": ["bail@2.0.2", "", {}, "sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw=="],
 
@@ -2749,6 +3153,10 @@
 
     "@astrojs/starlight/unified/trough": ["trough@2.2.0", "", {}, "sha512-tmMpK00BjZiUyVyvrBK7knerNgmgvcV/KLVyuma/SC+TQN167GrMRciANTz09+k3zW8L8t60jWO1GpfkZdjTaw=="],
 
+    "@aws-crypto/sha256-browser/@smithy/util-utf8/@smithy/util-buffer-from": ["@smithy/util-buffer-from@2.2.0", "", { "dependencies": { "@smithy/is-array-buffer": "^2.2.0", "tslib": "^2.6.2" } }, "sha512-IJdWBbTcMQ6DA0gdNhh/BwrLkDR+ADW5Kr1aZmd4k3DIF6ezMV4R2NIAmT08wQJ3yUK82thHWmC/TnK/wpMMIA=="],
+
+    "@aws-crypto/util/@smithy/util-utf8/@smithy/util-buffer-from": ["@smithy/util-buffer-from@2.2.0", "", { "dependencies": { "@smithy/is-array-buffer": "^2.2.0", "tslib": "^2.6.2" } }, "sha512-IJdWBbTcMQ6DA0gdNhh/BwrLkDR+ADW5Kr1aZmd4k3DIF6ezMV4R2NIAmT08wQJ3yUK82thHWmC/TnK/wpMMIA=="],
+
     "@dotenvx/dotenvx/execa/get-stream": ["get-stream@6.0.1", "", {}, "sha512-ts6Wi+2j3jQjqi70w5AlN8DFnkSwC+MqmxEzdEALB2qXZYV3X/b1CTfgPLGJNMeAWxdPfU8FO1ms3NUfaHCPYg=="],
 
     "@dotenvx/dotenvx/execa/human-signals": ["human-signals@2.1.0", "", {}, "sha512-B4FFZ6q/T2jhhksgkbEW3HBvWIfDW85snkQgawt07S7J5QXTk6BkNV+0yAeZrM5QpMAdYlocGoljn0sJ/WQkFw=="],
@@ -2781,6 +3189,12 @@
 
     "@inquirer/core/wrap-ansi/strip-ansi": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="],
 
+    "@mariozechner/pi-ai/ajv/json-schema-traverse": ["json-schema-traverse@1.0.0", "", {}, "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug=="],
+
+    "@mariozechner/pi-coding-agent/ajv/json-schema-traverse": ["json-schema-traverse@1.0.0", "", {}, "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug=="],
+
+    "@mariozechner/pi-coding-agent/minimatch/brace-expansion": ["brace-expansion@5.0.4", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-h+DEnpVvxmfVefa4jFbCf5HdH5YMDXRsmKflpf1pILZWRFlTbJpxeU55nJl4Smt5HQaGzg1o6RHFPJaOqnmBDg=="],
+
     "@mdx-js/mdx/unified/bail": ["bail@2.0.2", "", {}, "sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw=="],
 
     "@mdx-js/mdx/unified/is-plain-obj": ["is-plain-obj@4.1.0", "", {}, "sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg=="],
@@ -2799,6 +3213,8 @@
 
     "@types/sax/@types/node/undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
 
+    "@types/yauzl/@types/node/undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+
     "@typescript-eslint/typescript-estree/minimatch/brace-expansion": ["brace-expansion@5.0.4", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-h+DEnpVvxmfVefa4jFbCf5HdH5YMDXRsmKflpf1pILZWRFlTbJpxeU55nJl4Smt5HQaGzg1o6RHFPJaOqnmBDg=="],
 
     "ajv-formats/ajv/json-schema-traverse": ["json-schema-traverse@1.0.0", "", {}, "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug=="],
@@ -2835,6 +3251,8 @@
 
     "form-data/mime-types/mime-db": ["mime-db@1.52.0", "", {}, "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg=="],
 
+    "glob/minimatch/brace-expansion": ["brace-expansion@5.0.4", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-h+DEnpVvxmfVefa4jFbCf5HdH5YMDXRsmKflpf1pILZWRFlTbJpxeU55nJl4Smt5HQaGzg1o6RHFPJaOqnmBDg=="],
+
     "log-update/slice-ansi/ansi-styles": ["ansi-styles@6.2.3", "", {}, "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg=="],
 
     "log-update/slice-ansi/is-fullwidth-code-point": ["is-fullwidth-code-point@5.1.0", "", { "dependencies": { "get-east-asian-width": "^1.3.1" } }, "sha512-5XHYaSyiqADb4RnZ1Bdad6cPp8Toise4TzEjcOYDHZkTCbKgiUl7WTUCpNWHuxmDt91wnsZBc9xinNzopv3JMQ=="],
@@ -2863,10 +3281,18 @@
 
     "micromark-extension-directive/parse-entities/is-hexadecimal": ["is-hexadecimal@2.0.1", "", {}, "sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg=="],
 
+    "msw/yargs/cliui": ["cliui@8.0.1", "", { "dependencies": { "string-width": "^4.2.0", "strip-ansi": "^6.0.1", "wrap-ansi": "^7.0.0" } }, "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ=="],
+
+    "msw/yargs/string-width": ["string-width@4.2.3", "", { "dependencies": { "emoji-regex": "^8.0.0", "is-fullwidth-code-point": "^3.0.0", "strip-ansi": "^6.0.1" } }, "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g=="],
+
+    "msw/yargs/yargs-parser": ["yargs-parser@21.1.1", "", {}, "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw=="],
+
     "p-locate/p-limit/yocto-queue": ["yocto-queue@0.1.0", "", {}, "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q=="],
 
     "parse-entities/is-alphanumerical/is-alphabetical": ["is-alphabetical@1.0.4", "", {}, "sha512-DwzsA04LQ10FHTZuL0/grVDk4rFoVH1pjAToYwBrHSxcrBIGQuXrQMtD5U1b0U2XVgKZCTLLP8u2Qxqhy3l2Vg=="],
 
+    "protobufjs/@types/node/undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+
     "react-markdown/unified/bail": ["bail@2.0.2", "", {}, "sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw=="],
 
     "react-markdown/unified/is-plain-obj": ["is-plain-obj@4.1.0", "", {}, "sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg=="],
@@ -3065,6 +3491,10 @@
 
     "yargs/string-width/strip-ansi": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="],
 
+    "@aws-crypto/sha256-browser/@smithy/util-utf8/@smithy/util-buffer-from/@smithy/is-array-buffer": ["@smithy/is-array-buffer@2.2.0", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-GGP3O9QFD24uGeAXYUjwSTXARoqpZykHadOmA8G5vfJPK0/DC67qa//0qvqrJzL1xc8WQWX7/yc7fwudjPHPhA=="],
+
+    "@aws-crypto/util/@smithy/util-utf8/@smithy/util-buffer-from/@smithy/is-array-buffer": ["@smithy/is-array-buffer@2.2.0", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-GGP3O9QFD24uGeAXYUjwSTXARoqpZykHadOmA8G5vfJPK0/DC67qa//0qvqrJzL1xc8WQWX7/yc7fwudjPHPhA=="],
+
     "@dotenvx/dotenvx/execa/onetime/mimic-fn": ["mimic-fn@2.1.0", "", {}, "sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg=="],
 
     "@inquirer/core/wrap-ansi/string-width/emoji-regex": ["emoji-regex@8.0.0", "", {}, "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A=="],
@@ -3073,10 +3503,24 @@
 
     "@inquirer/core/wrap-ansi/strip-ansi/ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="],
 
+    "@mariozechner/pi-coding-agent/minimatch/brace-expansion/balanced-match": ["balanced-match@4.0.4", "", {}, "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA=="],
+
     "@ts-morph/common/minimatch/brace-expansion/balanced-match": ["balanced-match@4.0.4", "", {}, "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA=="],
 
     "@typescript-eslint/typescript-estree/minimatch/brace-expansion/balanced-match": ["balanced-match@4.0.4", "", {}, "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA=="],
 
+    "glob/minimatch/brace-expansion/balanced-match": ["balanced-match@4.0.4", "", {}, "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA=="],
+
+    "msw/yargs/cliui/strip-ansi": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="],
+
+    "msw/yargs/cliui/wrap-ansi": ["wrap-ansi@7.0.0", "", { "dependencies": { "ansi-styles": "^4.0.0", "string-width": "^4.1.0", "strip-ansi": "^6.0.0" } }, "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q=="],
+
+    "msw/yargs/string-width/emoji-regex": ["emoji-regex@8.0.0", "", {}, "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A=="],
+
+    "msw/yargs/string-width/is-fullwidth-code-point": ["is-fullwidth-code-point@3.0.0", "", {}, "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg=="],
+
+    "msw/yargs/string-width/strip-ansi": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="],
+
     "remark-parse/mdast-util-from-markdown/@types/mdast/@types/unist": ["@types/unist@2.0.11", "", {}, "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA=="],
 
     "remark-parse/mdast-util-from-markdown/unist-util-stringify-position/@types/unist": ["@types/unist@2.0.11", "", {}, "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA=="],
@@ -3103,6 +3547,10 @@
 
     "yargs/string-width/strip-ansi/ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="],
 
+    "msw/yargs/cliui/strip-ansi/ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="],
+
+    "msw/yargs/string-width/strip-ansi/ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="],
+
     "telegramify-markdown/remark-gfm/mdast-util-gfm/mdast-util-gfm-autolink-literal/ccount": ["ccount@1.1.0", "", {}, "sha512-vlNK021QdI7PNeiUh/lKkC/mNHHfV0m/Ad5JoI0TYtlBnJAslM/JIkm/tGC88bkLIwO6OQ5uV6ztS6kVAtCDlg=="],
 
     "telegramify-markdown/remark-gfm/mdast-util-gfm/mdast-util-gfm-autolink-literal/mdast-util-find-and-replace": ["mdast-util-find-and-replace@1.1.1", "", { "dependencies": { "escape-string-regexp": "^4.0.0", "unist-util-is": "^4.0.0", "unist-util-visit-parents": "^3.0.0" } }, "sha512-9cKl33Y21lyckGzpSmEQnIDjEfeeWelN5s1kUW1LwdB0Fkuq2u+4GdqcGEygYxJE8GVqCl0741bYXHgamfWAZA=="],
diff --git a/deploy/.env.example b/deploy/.env.example
index 9e2d5f521f..9a0b208e74 100644
--- a/deploy/.env.example
+++ b/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
 
diff --git a/docker-entrypoint.sh b/docker-entrypoint.sh
index 6f4d516a9f..26594e5c41 100644
--- a/docker-entrypoint.sh
+++ b/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
diff --git a/eslint.config.mjs b/eslint.config.mjs
index 69bf635bd5..152c4245dd 100644
--- a/eslint.config.mjs
+++ b/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,
diff --git a/homebrew/archon.rb b/homebrew/archon.rb
index 59c801c015..0bac58a339 100644
--- a/homebrew/archon.rb
+++ b/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.5"
+  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 "2c2065e580a085baaea02504cb5451be3f68e0d9fdb13a364cd45194d5b22de1"
+      sha256 "96b6dac50b046eece9eddbb988a0c39b4f9a0e2faac66e49b977ba6360069e86"
     end
     on_intel do
       url "https://github.com/coleam00/Archon/releases/download/v#{version}/archon-darwin-x64"
-      sha256 "515aca3b2bc30d3b5d4dfb67c04648f70b66e8ed345ea6ab039e76e6578e82fe"
+      sha256 "09f1dbe12417b4300b7b07b531eb7391a286305f8d4eafc11e7f61f5d26eb8eb"
     end
   end
 
   on_linux do
     on_arm do
       url "https://github.com/coleam00/Archon/releases/download/v#{version}/archon-linux-arm64"
-      sha256 "96920d98ae0d4dc7ef78e6de4f9018a9ba2031b9c2b010fd5d748d9513c49f60"
+      sha256 "80b06a6ff699ec57cd4a3e49cfe7b899a3e8212688d70285f5a887bf10086731"
     end
     on_intel do
       url "https://github.com/coleam00/Archon/releases/download/v#{version}/archon-linux-x64"
-      sha256 "80e7d115da424d5ee47b7db773382c9b8d0db728408f9815c05081872da6b74f"
+      sha256 "09f5dac6db8037ed6f3e5b7e9c5eb8e37f19822a4ed2bf4cd7e654780f9d00de"
     end
   end
 
diff --git a/package.json b/package.json
index b296d638ca..42cc8a3714 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "archon",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "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"
   },
@@ -46,7 +48,8 @@
     "bun": "^1.3.0"
   },
   "overrides": {
-    "test-exclude": "^7.0.1"
+    "test-exclude": "^7.0.1",
+    "axios": "^1.15.0"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.74"
diff --git a/packages/adapters/package.json b/packages/adapters/package.json
index 607770f284..19dbeedd9d 100644
--- a/packages/adapters/package.json
+++ b/packages/adapters/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@archon/adapters",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -22,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": {
diff --git a/packages/adapters/src/chat/telegram/adapter.test.ts b/packages/adapters/src/chat/telegram/adapter.test.ts
index 5858878020..a3a3f20f5e 100644
--- a/packages/adapters/src/chat/telegram/adapter.test.ts
+++ b/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);
     });
   });
 });
diff --git a/packages/adapters/src/chat/telegram/adapter.ts b/packages/adapters/src/chat/telegram/adapter.ts
index c800612079..a85a78bb09 100644
--- a/packages/adapters/src/chat/telegram/adapter.ts
+++ b/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) {
diff --git a/packages/cli/package.json b/packages/cli/package.json
index bd8c7390bf..1f00737409 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@archon/cli",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "type": "module",
   "main": "./src/cli.ts",
   "bin": {
@@ -17,6 +17,7 @@
     "@archon/git": "workspace:*",
     "@archon/isolation": "workspace:*",
     "@archon/paths": "workspace:*",
+    "@archon/providers": "workspace:*",
     "@archon/server": "workspace:*",
     "@archon/workflows": "workspace:*",
     "@clack/prompts": "^1.0.0",
diff --git a/packages/cli/src/cli.test.ts b/packages/cli/src/cli.test.ts
index 40b98e4887..1806b42714 100644
--- a/packages/cli/src/cli.test.ts
+++ b/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', () => {
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index d7dedf4810..3ecd580178 100755
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -10,26 +10,16 @@
 // 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';
 
-// Load ~/.archon/.env with override: true — Archon-specific config must win
-// over shell-inherited env vars (e.g. PORT, LOG_LEVEL from shell profile).
-// CWD .env keys are already gone (stripCwdEnv above), so override only
-// affects shell-inherited values, which is the intended behavior.
-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.
 
@@ -43,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 {
@@ -76,6 +71,7 @@ import {
   checkForUpdate,
   BUNDLED_IS_BINARY,
   BUNDLED_VERSION,
+  shutdownTelemetry,
 } from '@archon/paths';
 import * as git from '@archon/git';
 
@@ -125,9 +121,6 @@ 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
 
@@ -207,9 +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
@@ -231,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();
@@ -298,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) {
@@ -344,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,
             };
@@ -576,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();
   }
diff --git a/packages/cli/src/commands/isolation.test.ts b/packages/cli/src/commands/isolation.test.ts
index 81ca60651e..0a399fb12a 100644
--- a/packages/cli/src/commands/isolation.test.ts
+++ b/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', () => {
diff --git a/packages/cli/src/commands/isolation.ts b/packages/cli/src/commands/isolation.ts
index 6e44a0fb67..a24855486a 100644
--- a/packages/cli/src/commands/isolation.ts
+++ b/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');
diff --git a/packages/cli/src/commands/serve.ts b/packages/cli/src/commands/serve.ts
index 22e8ad30e7..54210837ad 100644
--- a/packages/cli/src/commands/serve.ts
+++ b/packages/cli/src/commands/serve.ts
@@ -85,29 +85,33 @@ async function downloadWebDist(version: string, targetDir: string): Promise<void
   log.info({ version, targetDir }, 'web_dist.download_started');
   console.log(`Web UI not found locally — downloading from release v${version}...`);
 
-  // Download checksums
-  const checksumsRes = await fetch(checksumsUrl).catch((err: unknown) => {
-    throw new Error(
-      `Network error fetching checksums from ${checksumsUrl}: ${(err as Error).message}`
-    );
-  });
+  // 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}`
     );
   }
-  const checksumsText = await checksumsRes.text();
-  const expectedHash = parseChecksum(checksumsText, 'archon-web.tar.gz');
-
-  // Download tarball
-  console.log(`Downloading ${tarballUrl}...`);
-  const tarballRes = await fetch(tarballUrl).catch((err: unknown) => {
-    throw new Error(`Network error fetching tarball from ${tarballUrl}: ${(err as Error).message}`);
-  });
   if (!tarballRes.ok) {
     throw new Error(`Failed to download web UI: ${tarballRes.status} ${tarballRes.statusText}`);
   }
-  const tarballBuffer = await tarballRes.arrayBuffer();
+  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');
diff --git a/packages/cli/src/commands/setup.test.ts b/packages/cli/src/commands/setup.test.ts
index 52c47823c1..a0fa7373b5 100644
--- a/packages/cli/src/commands/setup.test.ts
+++ b/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');
+  });
+});
diff --git a/packages/cli/src/commands/setup.ts b/packages/cli/src/commands/setup.ts
index b94529cd4c..2160a99d8a 100644
--- a/packages/cli/src/commands/setup.ts
+++ b/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' : '');
+}
 
-  // Write to global location
-  writeFileSync(globalPath, content);
+/**
+ * Produce a filesystem-safe ISO timestamp (no `:` or `.` characters).
+ */
+function backupTimestamp(): string {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
 
-  // Write to repo location
-  writeFileSync(repoEnvPath, content);
+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;
+}
 
-  return { globalPath, repoEnvPath };
+/**
+ * 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 });
+  }
+
+  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);
+  }
+
+  const preservedKeys: string[] = [];
+  let finalContent: string;
+
+  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);
-
-  s.stop('Configuration files written');
+  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 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.',
diff --git a/packages/cli/src/commands/validate.ts b/packages/cli/src/commands/validate.ts
index d82a0211a7..e39a3eea6d 100644
--- a/packages/cli/src/commands/validate.ts
+++ b/packages/cli/src/commands/validate.ts
@@ -85,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
@@ -105,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));
   }
 
diff --git a/packages/cli/src/commands/workflow.test.ts b/packages/cli/src/commands/workflow.test.ts
index 7f13f8d83f..4c80ee3d50 100644
--- a/packages/cli/src/commands/workflow.test.ts
+++ b/packages/cli/src/commands/workflow.test.ts
@@ -310,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: [],
@@ -319,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 () => {
@@ -867,6 +865,254 @@ describe('workflowRunCommand', () => {
     expect(createCallsAfter).toBe(createCallsBefore);
   });
 
+  // -------------------------------------------------------------------------
+  // Stale workspace source-symlink → truthful CLI error
+  // -------------------------------------------------------------------------
+
+  it('surfaces auto-registration failures instead of claiming the repo is invalid', async () => {
+    const { discoverWorkflowsWithConfig } = await import('@archon/workflows/workflow-discovery');
+    const { registerRepository } = await import('@archon/core');
+    const conversationDb = await import('@archon/core/db/conversations');
+    const codebaseDb = await import('@archon/core/db/codebases');
+    const gitModule = await import('@archon/git');
+
+    (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);
+    (gitModule.findRepoRoot as ReturnType<typeof mock>).mockResolvedValueOnce('/test/path');
+    (registerRepository as ReturnType<typeof mock>).mockRejectedValueOnce(
+      new Error(
+        'Source symlink at /home/test/.archon/workspaces/acme/widget/source already points to ' +
+          '/home/test/.archon/workspaces/widget, expected /test/path'
+      )
+    );
+
+    const error = await workflowRunCommand('/test/path', 'assist', 'hello', {}).catch(
+      err => err as Error
+    );
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error.message).toContain('Cannot create worktree: repository registration failed.');
+    expect(error.message).toContain(
+      'Remove the stale workspace entry at /home/test/.archon/workspaces/acme/widget and retry'
+    );
+    expect(error.message).not.toContain('not in a git repository');
+  });
+
+  it('surfaces auto-registration failures on --resume instead of claiming the repo is invalid', async () => {
+    const { discoverWorkflowsWithConfig } = await import('@archon/workflows/workflow-discovery');
+    const { registerRepository } = await import('@archon/core');
+    const conversationDb = await import('@archon/core/db/conversations');
+    const codebaseDb = await import('@archon/core/db/codebases');
+    const gitModule = await import('@archon/git');
+
+    (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);
+    (gitModule.findRepoRoot as ReturnType<typeof mock>).mockResolvedValueOnce('/test/path');
+    (registerRepository as ReturnType<typeof mock>).mockRejectedValueOnce(
+      new Error(
+        'Source symlink at /home/test/.archon/workspaces/acme/widget/source already points to ' +
+          '/home/test/.archon/workspaces/widget, expected /test/path'
+      )
+    );
+
+    const error = await workflowRunCommand('/test/path', 'assist', 'hello', {
+      resume: true,
+    }).catch(err => err as Error);
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error.message).toContain('Cannot resume: repository registration failed.');
+    expect(error.message).toContain(
+      'Remove the stale workspace entry at /home/test/.archon/workspaces/acme/widget and retry'
+    );
+    expect(error.message).not.toContain('Not in a git repository');
+  });
+
+  it('falls back to generic workspace hint when registration error has an unrecognized shape', async () => {
+    const { discoverWorkflowsWithConfig } = await import('@archon/workflows/workflow-discovery');
+    const { registerRepository } = await import('@archon/core');
+    const conversationDb = await import('@archon/core/db/conversations');
+    const codebaseDb = await import('@archon/core/db/codebases');
+    const gitModule = await import('@archon/git');
+
+    (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);
+    (gitModule.findRepoRoot as ReturnType<typeof mock>).mockResolvedValueOnce('/test/path');
+    (registerRepository as ReturnType<typeof mock>).mockRejectedValueOnce(
+      new Error("EACCES: permission denied, mkdir '/home/test/.archon/workspaces/acme'")
+    );
+
+    const error = await workflowRunCommand('/test/path', 'assist', 'hello', {}).catch(
+      err => err as Error
+    );
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error.message).toContain('Cannot create worktree: repository registration failed.');
+    expect(error.message).toContain('EACCES: permission denied');
+    // Path-separator-agnostic check: on Windows path.join normalizes to `\`,
+    // on POSIX to `/`. Assert the hint prefix + the final segment separately.
+    expect(error.message).toContain('Check your Archon workspace registration under');
+    expect(error.message).toMatch(/workspaces\b/);
+    expect(error.message).not.toContain('Remove the stale workspace entry');
+  });
+
+  // -------------------------------------------------------------------------
+  // 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');
@@ -975,6 +1221,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', () => {
@@ -2029,3 +2518,51 @@ describe('workflowRunCommand — progress rendering', () => {
     expect(stderrSpy).toHaveBeenCalledWith('[slow] Completed (1m30s)\n');
   });
 });
+
+// ---------------------------------------------------------------------------
+// extractStaleWorkspaceEntry — parser edge cases
+// ---------------------------------------------------------------------------
+
+describe('extractStaleWorkspaceEntry', () => {
+  it('extracts the workspace dir from a POSIX source-symlink error', async () => {
+    const { extractStaleWorkspaceEntry } = await import('./workflow');
+    expect(
+      extractStaleWorkspaceEntry(
+        'Source symlink at /home/user/.archon/workspaces/acme/widget/source already points to /other, expected /here'
+      )
+    ).toBe('/home/user/.archon/workspaces/acme/widget');
+  });
+
+  it('extracts the workspace dir from a Windows source-symlink error (backslash sep)', async () => {
+    const { extractStaleWorkspaceEntry } = await import('./workflow');
+    expect(
+      extractStaleWorkspaceEntry(
+        'Source symlink at C:\\Users\\me\\.archon\\workspaces\\acme\\widget\\source already points to D:\\x, expected D:\\y'
+      )
+    ).toBe('C:\\Users\\me\\.archon\\workspaces\\acme\\widget');
+  });
+
+  it('returns null when the prefix does not match (unrelated error)', async () => {
+    const { extractStaleWorkspaceEntry } = await import('./workflow');
+    expect(extractStaleWorkspaceEntry('ENOENT: no such file or directory')).toBeNull();
+  });
+
+  it('returns null when the prefix matches but the delimiter is missing', async () => {
+    const { extractStaleWorkspaceEntry } = await import('./workflow');
+    expect(
+      extractStaleWorkspaceEntry('Source symlink at /some/path (truncated message)')
+    ).toBeNull();
+  });
+
+  it('returns null when the source path has no path separator at all', async () => {
+    const { extractStaleWorkspaceEntry } = await import('./workflow');
+    expect(
+      extractStaleWorkspaceEntry('Source symlink at bareword already points to /x, expected /y')
+    ).toBeNull();
+  });
+
+  it('returns null on an empty input', async () => {
+    const { extractStaleWorkspaceEntry } = await import('./workflow');
+    expect(extractStaleWorkspaceEntry('')).toBeNull();
+  });
+});
diff --git a/packages/cli/src/commands/workflow.ts b/packages/cli/src/commands/workflow.ts
index 89dd5911e4..bdee2f5398 100644
--- a/packages/cli/src/commands/workflow.ts
+++ b/packages/cli/src/commands/workflow.ts
@@ -11,6 +11,7 @@ import {
 import { WORKFLOW_EVENT_TYPES, type WorkflowEventType } from '@archon/workflows/store';
 import { configureIsolation, getIsolationProvider } from '@archon/isolation';
 import { createLogger, getArchonHome } from '@archon/paths';
+import { join } from 'node:path';
 import { createWorkflowDeps } from '@archon/core/workflows/store-adapter';
 import { discoverWorkflowsWithConfig } from '@archon/workflows/workflow-discovery';
 import { resolveWorkflowName } from '@archon/workflows/router';
@@ -62,8 +63,6 @@ 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. */
@@ -79,6 +78,57 @@ function generateConversationId(): string {
   return `cli-${String(timestamp)}-${random}`;
 }
 
+/**
+ * Parses the "Source symlink at X already points to Y, expected Z" error
+ * thrown by `createProjectSourceSymlink` in @archon/paths. Cross-package
+ * string contract — if that throw site changes wording, this parser silently
+ * stops matching. Returns the workspace dir (parent of the `source` link) so
+ * the caller can emit an exact cleanup path, or null if unrecognized.
+ */
+export function extractStaleWorkspaceEntry(message: string): string | null {
+  const prefix = 'Source symlink at ';
+  const delimiter = ' already points to ';
+  if (!message.startsWith(prefix)) return null;
+
+  const remainder = message.slice(prefix.length);
+  const delimiterIndex = remainder.indexOf(delimiter);
+  if (delimiterIndex === -1) return null;
+
+  const sourcePath = remainder.slice(0, delimiterIndex).trim();
+  const lastSeparator = Math.max(sourcePath.lastIndexOf('/'), sourcePath.lastIndexOf('\\'));
+  return lastSeparator === -1 ? null : sourcePath.slice(0, lastSeparator);
+}
+
+/**
+ * Wraps a codebase auto-registration failure for either the worktree-create or
+ * resume path. Preserves the original error message and delegates hint detail
+ * to `extractStaleWorkspaceEntry`; falls back to a workspace-root pointer when
+ * the error shape is unrecognized.
+ */
+function buildRegistrationFailureError(action: string, error: Error): Error {
+  const staleWorkspaceEntry = extractStaleWorkspaceEntry(error.message);
+  let hint: string;
+  if (staleWorkspaceEntry) {
+    hint = `Hint: Remove the stale workspace entry at ${staleWorkspaceEntry} and retry, or use --no-worktree to skip isolation.`;
+  } else {
+    // Guard against a throwing getArchonHome() (misconfigured env vars, etc.):
+    // the registration error we're wrapping is the load-bearing one — we'd
+    // rather lose the exact path in the hint than replace it with a secondary
+    // home-resolution error that masks the root cause.
+    try {
+      const workspacesPath = join(getArchonHome(), 'workspaces');
+      hint = `Hint: Check your Archon workspace registration under ${workspacesPath} and retry, or use --no-worktree to skip isolation.`;
+    } catch {
+      hint =
+        'Hint: Check your Archon workspace registration and retry, or use --no-worktree to skip isolation.';
+    }
+  }
+
+  return new Error(
+    `Cannot ${action}: repository registration failed.\nError: ${error.message}\n${hint}`
+  );
+}
+
 /** Render a workflow event to stderr as a progress line. Called only when --quiet is not set. */
 function renderWorkflowEvent(event: WorkflowEmitterEvent, verbose: boolean): void {
   switch (event.type) {
@@ -121,9 +171,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(
@@ -180,7 +230,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}`);
@@ -193,7 +243,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}`);
     }
@@ -263,6 +313,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('');
@@ -287,6 +368,7 @@ export async function workflowRunCommand(
   // Try to find a codebase for this directory
   let codebase = null;
   let codebaseLookupError: Error | null = null;
+  let codebaseRegistrationError: Error | null = null;
   try {
     codebase = await codebaseDb.findCodebaseByDefaultCwd(cwd);
   } catch (error) {
@@ -325,13 +407,14 @@ 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');
         }
       } catch (error) {
         const err = error as Error;
+        codebaseRegistrationError = err;
         getLog().warn(
           { err, errorType: err.constructor.name, repoRoot },
           'cli.codebase_auto_registration_failed'
@@ -356,6 +439,9 @@ export async function workflowRunCommand(
             'Hint: Check your database connection before using --resume.'
         );
       }
+      if (codebaseRegistrationError) {
+        throw buildRegistrationFailureError('resume', codebaseRegistrationError);
+      }
       throw new Error(
         'Cannot resume: Not in a git repository.\n' +
           'Either run from a git repo or use /clone first.'
@@ -405,8 +491,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
@@ -509,6 +601,9 @@ export async function workflowRunCommand(
           'Hint: Check your database connection, or use --no-worktree to skip isolation.'
       );
     }
+    if (codebaseRegistrationError) {
+      throw buildRegistrationFailureError('create worktree', codebaseRegistrationError);
+    }
     throw new Error(
       'Cannot create worktree: not in a git repository.\n' +
         'Run from within a git repo, or use --no-worktree to skip isolation.'
@@ -591,6 +686,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 {
@@ -612,6 +725,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}`);
@@ -630,25 +759,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 {
@@ -732,20 +861,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;
   }
 
@@ -754,7 +879,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}`);
@@ -968,9 +1093,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;
diff --git a/packages/core/package.json b/packages/core/package.json
index 8aa397ea33..31820f43f7 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@archon/core",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "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/codex-binary-guard.test.ts && bun test src/utils/codex-binary-resolver.test.ts && bun test src/utils/codex-binary-resolver-dev.test.ts && bun test src/clients/claude.test.ts src/clients/codex.test.ts src/clients/factory.test.ts && 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-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"
   },
diff --git a/packages/core/src/clients/claude.ts b/packages/core/src/clients/claude.ts
deleted file mode 100644
index 90595e1d25..0000000000
--- a/packages/core/src/clients/claude.ts
+++ /dev/null
@@ -1,657 +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';
-// The `/embed` entry point uses `import ... with { type: 'file' }` to embed
-// the SDK's `cli.js` into the compiled binary's $bunfs virtual filesystem,
-// then extracts it to a temp path at runtime so the subprocess can exec it.
-// Without this, the SDK falls back to resolving `cli.js` from
-// `import.meta.url` of its own module — which bun freezes at build time to
-// the build host's absolute node_modules path, producing a "Module not found
-// /Users/runner/..." error on any machine other than the CI runner.
-// Safe in dev too: resolves to the real on-disk cli.js.
-import cliPath from '@anthropic-ai/claude-agent-sdk/embed';
-import {
-  type AssistantRequestOptions,
-  type IAssistantClient,
-  type MessageChunk,
-  type TokenUsage,
-} from '../types';
-import { createLogger } from '@archon/paths';
-// No env filtering here — process.env is already clean:
-// stripCwdEnv() at entry point stripped CWD .env keys + CLAUDECODE markers,
-// then ~/.archon/.env was loaded as the trusted source. All keys the user sets
-// in ~/.archon/.env are intentional and pass through to the subprocess.
-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.
- *
- * process.env is already clean at this point:
- * - stripCwdEnv() at entry point removed CWD .env keys + CLAUDECODE markers
- * - ~/.archon/.env loaded with override:true as the trusted source
- *
- * Auth mode is determined by the SDK based on what tokens are present:
- * - Tokens in env → SDK uses them (explicit auth)
- * - No tokens → SDK uses `claude /login` credentials (global auth)
- * - User controls this by what they put in ~/.archon/.env
- *
- * We log the detected mode for diagnostics but don't filter — the user's
- * config is trusted. See coleam00/Archon#1067 for design rationale.
- */
-function buildSubprocessEnv(): NodeJS.ProcessEnv {
-  const hasExplicitTokens = Boolean(
-    process.env.CLAUDE_CODE_OAUTH_TOKEN ?? process.env.CLAUDE_API_KEY
-  );
-  const authMode = hasExplicitTokens ? 'explicit' : 'global';
-  getLog().info(
-    { authMode },
-    authMode === 'global' ? 'using_global_auth' : 'using_explicit_tokens'
-  );
-
-  return { ...process.env };
-}
-
-/** 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';
-}
-
-/** Default timeout for first SDK message (ms). Configurable via env var. */
-function getFirstEventTimeoutMs(): number {
-  const raw = process.env.ARCHON_CLAUDE_FIRST_EVENT_TIMEOUT_MS;
-  if (raw) {
-    const parsed = Number(raw);
-    if (Number.isFinite(parsed) && parsed > 0) return parsed;
-  }
-  return 60_000;
-}
-
-/** Build a diagnostic payload for claude.first_event_timeout log */
-function buildFirstEventHangDiagnostics(
-  subprocessEnv: Record<string, string>,
-  model: string | undefined
-): Record<string, unknown> {
-  return {
-    subprocessEnvKeys: Object.keys(subprocessEnv),
-    parentClaudeKeys: Object.keys(process.env).filter(
-      k => k === 'CLAUDECODE' || k.startsWith('CLAUDE_CODE_') || k.startsWith('ANTHROPIC_')
-    ),
-    model,
-    platform: process.platform,
-    uid: getProcessUid(),
-    isTTY: process.stdout.isTTY ?? false,
-    claudeCode: process.env.CLAUDECODE,
-    claudeCodeEntrypoint: process.env.CLAUDE_CODE_ENTRYPOINT,
-  };
-}
-
-/** Sentinel error class to identify timeout rejections in withFirstMessageTimeout. */
-class FirstEventTimeoutError extends Error {}
-
-/**
- * Wraps an async generator so that the first call to .next() must resolve
- * within `timeoutMs`. If it doesn't, aborts the controller and throws a
- * descriptive error. Subsequent .next() calls are forwarded directly.
- *
- * Uses Promise.race() — not just AbortController — because the pathological
- * case is "SDK ignores abort", so we need an independent unblocking mechanism.
- */
-export async function* withFirstMessageTimeout<T>(
-  gen: AsyncGenerator<T>,
-  controller: AbortController,
-  timeoutMs: number,
-  diagnostics: Record<string, unknown>
-): AsyncGenerator<T> {
-  // Race first event against timeout
-  let timerId: ReturnType<typeof setTimeout> | undefined;
-  let firstValue: IteratorResult<T>;
-  try {
-    firstValue = await Promise.race([
-      gen.next(),
-      new Promise<never>((_, reject) => {
-        timerId = setTimeout(() => {
-          reject(new FirstEventTimeoutError());
-        }, timeoutMs);
-      }),
-    ]);
-  } catch (err) {
-    if (err instanceof FirstEventTimeoutError) {
-      controller.abort();
-      getLog().error({ ...diagnostics, timeoutMs }, 'claude.first_event_timeout');
-      throw new Error(
-        'Claude Code subprocess produced no output within ' +
-          timeoutMs +
-          'ms. ' +
-          'See logs for claude.first_event_timeout diagnostic dump. ' +
-          'Details: https://github.com/coleam00/Archon/issues/1067'
-      );
-    }
-    throw err;
-  } finally {
-    clearTimeout(timerId);
-  }
-
-  if (firstValue.done) return;
-  yield firstValue.value;
-
-  // Forward remaining events directly
-  yield* gen;
-}
-
-/**
- * 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 && !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,
-        pathToClaudeCodeExecutable: cliPath,
-        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 {
-        const rawEvents = query({ prompt, options });
-        const timeoutMs = getFirstEventTimeoutMs();
-        const diagnostics = buildFirstEventHangDiagnostics(
-          options.env as Record<string, string>,
-          options.model
-        );
-        const events = withFirstMessageTimeout(rawEvents, controller, timeoutMs, diagnostics);
-        for await (const msg of events) {
-          // 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';
-  }
-}
diff --git a/packages/core/src/clients/codex.ts b/packages/core/src/clients/codex.ts
deleted file mode 100644
index e6e9d1dd09..0000000000
--- a/packages/core/src/clients/codex.ts
+++ /dev/null
@@ -1,581 +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';
-import { resolveCodexBinaryPath } from '../utils/codex-binary-resolver';
-
-/** 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 (async because binary path resolution is async)
-let codexInstance: Codex | null = null;
-let codexInitPromise: Promise<Codex> | null = null;
-
-/** Reset singleton state. Exported for tests only. */
-export function resetCodexSingleton(): void {
-  codexInstance = null;
-  codexInitPromise = null;
-}
-
-/**
- * Get or create Codex SDK instance.
- * Async because in compiled binary mode, binary path resolution is async.
- * Once initialized, the binary path is fixed for the process lifetime.
- */
-async function getCodex(configCodexBinaryPath?: string): Promise<Codex> {
-  if (codexInstance) return codexInstance;
-
-  // Prevent concurrent initialization race
-  if (!codexInitPromise) {
-    codexInitPromise = (async (): Promise<Codex> => {
-      const codexPathOverride = await resolveCodexBinaryPath(configCodexBinaryPath);
-      const instance = new Codex({ codexPathOverride });
-      codexInstance = instance;
-      return instance;
-    })().catch(err => {
-      // Clear promise so next call can retry (e.g. after user installs Codex)
-      codexInitPromise = null;
-      throw err;
-    });
-  }
-  return codexInitPromise;
-}
-
-/**
- * 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> {
-    // Load config once — used for env-leak gate and (on first call) codexBinaryPath resolution.
-    let mergedConfig: Awaited<ReturnType<typeof loadConfig>> | undefined;
-    try {
-      mergedConfig = await loadConfig(cwd);
-    } catch (configErr) {
-      // Fail-closed: config load failure enforces the env-leak gate (allowTargetRepoKeys stays false)
-      getLog().warn({ err: configErr, cwd }, 'env_leak_gate.config_load_failed_gate_enforced');
-    }
-
-    // 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 && !codebase.allow_env_keys) {
-      // Fail-closed: a config load failure must NOT silently bypass the gate.
-      const allowTargetRepoKeys = mergedConfig?.allowTargetRepoKeys ?? false;
-      if (!allowTargetRepoKeys) {
-        const report = scanPathForSensitiveKeys(cwd);
-        if (report.findings.length > 0) {
-          throw new EnvLeakError(report, 'spawn-existing');
-        }
-      }
-    }
-
-    // Initialize Codex SDK with binary path override (resolved from env/config/vendor).
-    // In dev mode, resolveCodexBinaryPath returns undefined and the SDK uses node_modules.
-    // In binary mode, it resolves from env/config/vendor or throws with install instructions.
-    const codex = await getCodex(mergedConfig?.assistants.codex.codexBinaryPath);
-    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';
-  }
-}
diff --git a/packages/core/src/clients/factory.test.ts b/packages/core/src/clients/factory.test.ts
deleted file mode 100644
index a8aed89f0b..0000000000
--- a/packages/core/src/clients/factory.test.ts
+++ /dev/null
@@ -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);
-    });
-  });
-});
diff --git a/packages/core/src/clients/factory.ts b/packages/core/src/clients/factory.ts
deleted file mode 100644
index 027f9843fa..0000000000
--- a/packages/core/src/clients/factory.ts
+++ /dev/null
@@ -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'`);
-  }
-}
diff --git a/packages/core/src/clients/index.ts b/packages/core/src/clients/index.ts
deleted file mode 100644
index 98b1d10f20..0000000000
--- a/packages/core/src/clients/index.ts
+++ /dev/null
@@ -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';
diff --git a/packages/core/src/config/config-loader.test.ts b/packages/core/src/config/config-loader.test.ts
index da18deded7..ac242040ac 100644
--- a/packages/core/src/config/config-loader.test.ts
+++ b/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 => {
diff --git a/packages/core/src/config/config-loader.ts b/packages/core/src/config/config-loader.ts
index 8ee702c613..4bf22d9144 100644
--- a/packages/core/src/config/config-loader.ts
+++ b/packages/core/src/config/config-loader.ts
@@ -28,32 +28,105 @@ 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';
 
-/** 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('config');
-  return cachedLog;
+/**
+ * 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;
 }
 
 /**
- * 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.
+ * 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 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');
+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;
 }
 
-// Test-only: reset the warn-once state so unit tests can re-trigger the log.
-export function resetEnvLeakGateWarnedSourcesForTests(): void {
-  envLeakGateDisabledWarnedSources.clear();
+/** 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('config');
+  return cachedLog;
 }
 
 /**
@@ -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,
diff --git a/packages/core/src/config/config-types.ts b/packages/core/src/config/config-types.ts
index 3baa3dfdca..63dd135907 100644
--- a/packages/core/src/config/config-types.ts
+++ b/packages/core/src/config/config-types.ts
@@ -10,25 +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[];
-  /** Path to the Codex CLI binary. Overrides auto-detection in compiled Archon builds.
-   *  Only relevant for the Codex provider; ignored for Claude. */
-  codexBinaryPath?: 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 {
   /**
@@ -41,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)
@@ -87,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;
 }
 
 /**
@@ -112,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
@@ -155,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;
   };
 
   /**
@@ -175,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
    */
@@ -215,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';
@@ -263,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;
 }
 
 /**
@@ -279,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';
diff --git a/packages/core/src/db/adapters/sqlite.test.ts b/packages/core/src/db/adapters/sqlite.test.ts
index 1e372065c4..326ba15204 100644
--- a/packages/core/src/db/adapters/sqlite.test.ts
+++ b/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);
+    });
+  });
 });
diff --git a/packages/core/src/db/adapters/sqlite.ts b/packages/core/src/db/adapters/sqlite.ts
index 2864e4fc43..485706d040 100644
--- a/packages/core/src/db/adapters/sqlite.ts
+++ b/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'))
diff --git a/packages/core/src/db/codebases.test.ts b/packages/core/src/db/codebases.test.ts
index ec3c249d14..b9bdbb6f1f 100644
--- a/packages/core/src/db/codebases.test.ts
+++ b/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
diff --git a/packages/core/src/db/codebases.ts b/packages/core/src/db/codebases.ts
index b9f45578b6..27adc91557 100644
--- a/packages/core/src/db/codebases.ts
+++ b/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'
diff --git a/packages/core/src/db/messages.test.ts b/packages/core/src/db/messages.test.ts
index 30cff1879c..b4bcb252b3 100644
--- a/packages/core/src/db/messages.test.ts
+++ b/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]);
+    });
+  });
 });
diff --git a/packages/core/src/db/messages.ts b/packages/core/src/db/messages.ts
index 87c95fd1e3..6157b8d486 100644
--- a/packages/core/src/db/messages.ts
+++ b/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 [];
+  }
+}
diff --git a/packages/core/src/db/workflows.test.ts b/packages/core/src/db/workflows.test.ts
index bbbfa6ccf4..c5504f51f6 100644
--- a/packages/core/src/db/workflows.test.ts
+++ b/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));
diff --git a/packages/core/src/db/workflows.ts b/packages/core/src/db/workflows.ts
index 0abfb0474d..d378261490 100644
--- a/packages/core/src/db/workflows.ts
+++ b/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]
     );
diff --git a/packages/core/src/handlers/clone.test.ts b/packages/core/src/handlers/clone.test.ts
index 7f948cfb33..c913c1a78c 100644
--- a/packages/core/src/handlers/clone.test.ts
+++ b/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);
-    });
-  });
 });
diff --git a/packages/core/src/handlers/clone.ts b/packages/core/src/handlers/clone.ts
index 3dc96f499c..366a951b8a 100644
--- a/packages/core/src/handlers/clone.ts
+++ b/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);
 }
diff --git a/packages/core/src/handlers/command-handler.test.ts b/packages/core/src/handlers/command-handler.test.ts
index 4f29e7247b..de6516cb98 100644
--- a/packages/core/src/handlers/command-handler.test.ts
+++ b/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(),
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index e212eb10c9..8c5e928a98 100644
--- a/packages/core/src/index.ts
+++ b/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';
 
diff --git a/packages/core/src/orchestrator/orchestrator-agent.test.ts b/packages/core/src/orchestrator/orchestrator-agent.test.ts
index 70080cc01a..3a4a1299c9 100644
--- a/packages/core/src/orchestrator/orchestrator-agent.test.ts
+++ b/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(),
@@ -1012,6 +1099,42 @@ describe('workflow dispatch routing — interactive flag', () => {
 
     expect(mockExecuteWorkflow).toHaveBeenCalled();
     expect(mockDispatchBackgroundWorkflow).not.toHaveBeenCalled();
+    // Regression for the auto-resume plumbing: the interactive web dispatch
+    // must pass the caller conversation's DB id as parentConversationId
+    // (11th positional arg) so the approve/reject API handlers can dispatch
+    // resume back through the orchestrator.
+    const callArgs = mockExecuteWorkflow.mock.calls[0] as unknown[];
+    expect(callArgs[10]).toBe('conv-1'); // parentConversationId = conversation.id
+  });
+
+  test('foreground_resume_detected: passes parentConversationId to executeWorkflow when a resumable run exists', async () => {
+    // Regression for the foreground-resume branch added as part of the
+    // auto-resume fix: when `findResumableRunByParentConversation` returns a
+    // paused run, the orchestrator picks the working_path from that run and
+    // must still carry parentConversationId forward so the API helpers can
+    // keep dispatching resume on subsequent approvals.
+    mockGetOrCreateConversation.mockReturnValueOnce(Promise.resolve(makeDispatchConversation()));
+    mockGetCodebase.mockReturnValueOnce(Promise.resolve(makeDispatchCodebase()));
+    mockHandleCommand.mockReturnValueOnce(Promise.resolve(makeWorkflowResult(true)));
+    mockFindResumableRunByParentConversation.mockReturnValueOnce(
+      Promise.resolve({
+        id: 'resumable-run-1',
+        workflow_name: 'test-workflow',
+        working_path: '/repos/test-repo/worktrees/feature',
+        parent_conversation_id: 'conv-1',
+        status: 'failed',
+      })
+    );
+
+    const platform = makePlatform(); // getPlatformType returns 'web'
+    await handleMessage(platform, 'conv-1', '/workflow run test-workflow');
+
+    expect(mockExecuteWorkflow).toHaveBeenCalled();
+    const callArgs = mockExecuteWorkflow.mock.calls[0] as unknown[];
+    // cwd (position 3) should come from the resumable run's working_path
+    expect(callArgs[3]).toBe('/repos/test-repo/worktrees/feature');
+    // parentConversationId (position 10) should still be the caller conversation id
+    expect(callArgs[10]).toBe('conv-1');
   });
 
   test('calls dispatchBackgroundWorkflow for non-interactive workflow on web', async () => {
@@ -1072,7 +1195,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 +1529,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();
+  });
+});
diff --git a/packages/core/src/orchestrator/orchestrator-agent.ts b/packages/core/src/orchestrator/orchestrator-agent.ts
index 97d989f47c..27b9964835 100644
--- a/packages/core/src/orchestrator/orchestrator-agent.ts
+++ b/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
@@ -274,7 +293,10 @@ async function dispatchOrchestratorWorkflow(
         workflow,
         userMessage,
         conversation.id,
-        codebase.id
+        codebase.id,
+        undefined, // issueContext
+        undefined, // isolationContext
+        conversation.id // parentConversationId — enables approve/reject auto-resume
       );
     } else if (workflow.interactive) {
       // Interactive workflows run in foreground so output stays in the user's conversation
@@ -286,7 +308,10 @@ async function dispatchOrchestratorWorkflow(
         workflow,
         userMessage,
         conversation.id,
-        codebase.id
+        codebase.id,
+        undefined, // issueContext
+        undefined, // isolationContext
+        conversation.id // parentConversationId — enables approve/reject auto-resume
       );
     } else {
       await dispatchBackgroundWorkflow(
@@ -312,7 +337,10 @@ async function dispatchOrchestratorWorkflow(
       workflow,
       userMessage,
       conversation.id,
-      codebase.id
+      codebase.id,
+      undefined, // issueContext
+      undefined, // isolationContext
+      conversation.id // parentConversationId — enables approve/reject auto-resume
     );
   }
 }
@@ -381,9 +409,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 +479,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 +500,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 +515,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 +770,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 +815,8 @@ export async function handleMessage(
       message,
       issueContext,
       threadContext,
-      attachedFiles
+      attachedFiles,
+      workflowContext
     );
     const cwd = getArchonWorkspacesPath();
 
@@ -751,17 +829,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 +926,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 +975,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 +1053,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 +1098,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 +1313,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(
diff --git a/packages/core/src/orchestrator/orchestrator-isolation.test.ts b/packages/core/src/orchestrator/orchestrator-isolation.test.ts
index f46930f02c..6bcbedb697 100644
--- a/packages/core/src/orchestrator/orchestrator-isolation.test.ts
+++ b/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(),
diff --git a/packages/core/src/orchestrator/orchestrator.test.ts b/packages/core/src/orchestrator/orchestrator.test.ts
index d5e81038da..58e5ac304e 100644
--- a/packages/core/src/orchestrator/orchestrator.test.ts
+++ b/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();
     });
   });
 
@@ -1079,7 +1081,10 @@ describe('orchestrator-agent handleMessage', () => {
         expect.anything(), // workflow
         synthesized, // synthesizedPrompt, not original message
         expect.anything(), // conversation.id
-        expect.anything() // codebase.id
+        expect.anything(), // codebase.id
+        undefined, // issueContext
+        undefined, // isolationContext
+        expect.anything() // parentConversationId — web approval auto-resume
       );
     });
 
@@ -1104,7 +1109,10 @@ describe('orchestrator-agent handleMessage', () => {
         expect.anything(),
         'fix the login bug', // original message used as fallback
         expect.anything(),
-        expect.anything()
+        expect.anything(),
+        undefined, // issueContext
+        undefined, // isolationContext
+        expect.anything() // parentConversationId — web approval auto-resume
       );
     });
 
@@ -1151,10 +1159,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)
       );
     });
 
diff --git a/packages/core/src/orchestrator/prompt-builder.test.ts b/packages/core/src/orchestrator/prompt-builder.test.ts
index 7a734950b1..5927857dfb 100644
--- a/packages/core/src/orchestrator/prompt-builder.test.ts
+++ b/packages/core/src/orchestrator/prompt-builder.test.ts
@@ -1,5 +1,5 @@
 import { describe, test, expect } from 'bun:test';
-import { buildRoutingRulesWithProject } from './prompt-builder';
+import { buildRoutingRulesWithProject, formatWorkflowContextSection } from './prompt-builder';
 
 describe('buildRoutingRulesWithProject', () => {
   test('routing rules include --prompt in invocation format', () => {
@@ -31,3 +31,42 @@ describe('buildRoutingRulesWithProject', () => {
     expect(rules).toContain('NO knowledge of the conversation history');
   });
 });
+
+describe('formatWorkflowContextSection', () => {
+  test('returns empty string for empty results array', () => {
+    expect(formatWorkflowContextSection([])).toBe('');
+  });
+
+  test('includes section header for non-empty results', () => {
+    const result = formatWorkflowContextSection([
+      { workflowName: 'plan', runId: 'run-1', summary: 'Created implementation plan.' },
+    ]);
+    expect(result).toContain('## Recent Workflow Results');
+    expect(result).toContain('Use this context to answer follow-up questions');
+  });
+
+  test('formats each result with workflowName and runId', () => {
+    const result = formatWorkflowContextSection([
+      { workflowName: 'implement', runId: 'abc-123', summary: 'Added auth module.' },
+    ]);
+    expect(result).toContain('**implement** (run: abc-123)');
+    expect(result).toContain('Added auth module.');
+  });
+
+  test('formats multiple results sequentially', () => {
+    const results = [
+      { workflowName: 'plan', runId: 'run-1', summary: 'Plan done.' },
+      { workflowName: 'implement', runId: 'run-2', summary: 'Implement done.' },
+    ];
+    const result = formatWorkflowContextSection(results);
+    expect(result).toContain('**plan**');
+    expect(result).toContain('**implement**');
+  });
+
+  test('output does not end with trailing whitespace', () => {
+    const result = formatWorkflowContextSection([
+      { workflowName: 'assist', runId: 'r-1', summary: 'Done.' },
+    ]);
+    expect(result).toBe(result.trimEnd());
+  });
+});
diff --git a/packages/core/src/orchestrator/prompt-builder.ts b/packages/core/src/orchestrator/prompt-builder.ts
index d5f307db5b..07a3a7a709 100644
--- a/packages/core/src/orchestrator/prompt-builder.ts
+++ b/packages/core/src/orchestrator/prompt-builder.ts
@@ -37,6 +37,34 @@ export function formatWorkflowSection(workflows: readonly WorkflowDefinition[]):
   return section;
 }
 
+/** WorkflowResult type for prompt context injection */
+export interface WorkflowResultContext {
+  workflowName: string;
+  runId: string;
+  summary: string;
+}
+
+/**
+ * Format recent workflow results for injection into the orchestrator prompt.
+ * Returns empty string when there are no results; buildFullPrompt checks for
+ * a non-empty string before including the section in the prompt.
+ */
+export function formatWorkflowContextSection(results: readonly WorkflowResultContext[]): string {
+  if (results.length === 0) return '';
+
+  let section = '## Recent Workflow Results\n\n';
+  section +=
+    'The following workflows recently ran in this conversation. ' +
+    'Use this context to answer follow-up questions.\n\n';
+
+  for (const r of results) {
+    section += `**${r.workflowName}** (run: ${r.runId})\n`;
+    section += r.summary + '\n\n';
+  }
+
+  return section.trimEnd();
+}
+
 /**
  * Build the routing rules section of the prompt.
  */
diff --git a/packages/core/src/services/cleanup-service.test.ts b/packages/core/src/services/cleanup-service.test.ts
index 3d1b204d35..308a13c80d 100644
--- a/packages/core/src/services/cleanup-service.test.ts
+++ b/packages/core/src/services/cleanup-service.test.ts
@@ -153,7 +153,7 @@ describe('cleanup-service', () => {
 
       // worktreeExists returns false (default)
 
-      await removeEnvironment(envId);
+      const result = await removeEnvironment(envId);
 
       // Should call destroy with branchName and canonicalRepoPath for cleanup
       expect(mockDestroy).toHaveBeenCalledWith('/path/that/does/not/exist', {
@@ -163,6 +163,9 @@ describe('cleanup-service', () => {
       });
       // Should mark as destroyed
       expect(mockUpdateStatus).toHaveBeenCalledWith(envId, 'destroyed');
+      // Should return success result
+      expect(result.worktreeRemoved).toBe(true);
+      expect(result.skippedReason).toBeUndefined();
     });
 
     test('handles git worktree remove failure for missing path', async () => {
@@ -316,6 +319,86 @@ describe('cleanup-service', () => {
       });
     });
 
+    test('returns skippedReason when worktree has uncommitted changes without force', async () => {
+      const envId = 'env-uncommitted';
+
+      mockGetById.mockResolvedValueOnce({
+        id: envId,
+        codebase_id: 'codebase-123',
+        workflow_type: 'issue',
+        workflow_id: '42',
+        provider: 'worktree',
+        working_path: '/workspace/worktrees/issue-42',
+        branch_name: 'issue-42',
+        status: 'active',
+        created_at: new Date(),
+        created_by_platform: 'github',
+        metadata: {},
+      });
+
+      mockGetCodebase.mockResolvedValueOnce({
+        id: 'codebase-123',
+        name: 'test-repo',
+        default_cwd: '/workspace/repo',
+      });
+
+      // worktreeExists returns true (path exists)
+      mockWorktreeExists.mockResolvedValueOnce(true);
+      // hasUncommittedChanges returns true
+      mockHasUncommittedChanges.mockResolvedValueOnce(true);
+
+      const result = await removeEnvironment(envId);
+
+      // Should NOT call destroy or mark as destroyed
+      expect(mockDestroy).not.toHaveBeenCalled();
+      expect(mockUpdateStatus).not.toHaveBeenCalled();
+      // Should return skipped result
+      expect(result.worktreeRemoved).toBe(false);
+      expect(result.branchDeleted).toBe(false);
+      expect(result.skippedReason).toBe('has uncommitted changes');
+    });
+
+    test('returns warnings from partial destroy', async () => {
+      const envId = 'env-partial';
+
+      mockGetById.mockResolvedValueOnce({
+        id: envId,
+        codebase_id: 'codebase-123',
+        workflow_type: 'issue',
+        workflow_id: '42',
+        provider: 'worktree',
+        working_path: '/workspace/worktrees/issue-42',
+        branch_name: 'issue-42',
+        status: 'active',
+        created_at: new Date(),
+        created_by_platform: 'github',
+        metadata: {},
+      });
+
+      mockGetCodebase.mockResolvedValueOnce({
+        id: 'codebase-123',
+        name: 'test-repo',
+        default_cwd: '/workspace/repo',
+      });
+
+      // worktreeExists returns false (default)
+
+      mockDestroy.mockResolvedValueOnce({
+        worktreeRemoved: true,
+        branchDeleted: false,
+        remoteBranchDeleted: null,
+        directoryClean: true,
+        warnings: ["Cannot delete branch 'issue-42': checked out elsewhere"],
+      });
+
+      const result = await removeEnvironment(envId);
+
+      expect(result.worktreeRemoved).toBe(true);
+      expect(result.branchDeleted).toBe(false);
+      expect(result.warnings).toEqual(["Cannot delete branch 'issue-42': checked out elsewhere"]);
+      expect(result.skippedReason).toBeUndefined();
+    });
+
     test('re-throws non-directory errors from provider.destroy', async () => {
       const envId = 'env-real-error';
 
@@ -626,10 +709,33 @@ describe('runScheduledCleanup', () => {
         metadata: {},
       },
     ]);
-    // First env: internal worktreeExists returns false
-    mockExecFileAsync.mockRejectedValueOnce(new Error('not a git repo'));
-    // Second env: internal worktreeExists returns false
-    mockExecFileAsync.mockRejectedValueOnce(new Error('not a git repo'));
+    // worktreeExists returns false for both (already default)
+    // env-error: removeEnvironment needs getById + getCodebase
+    mockGetById.mockResolvedValueOnce({
+      id: 'env-error',
+      codebase_id: 'codebase-1',
+      working_path: '/bad/path',
+      branch_name: 'bad-branch',
+      status: 'active',
+    });
+    mockGetCodebase.mockResolvedValueOnce({
+      id: 'codebase-1',
+      name: 'test-repo',
+      default_cwd: '/workspace/repo',
+    });
+    // env-good: removeEnvironment needs getById + getCodebase
+    mockGetById.mockResolvedValueOnce({
+      id: 'env-good',
+      codebase_id: 'codebase-1',
+      working_path: '/workspace/repo/worktrees/pr-1',
+      branch_name: 'pr-1',
+      status: 'active',
+    });
+    mockGetCodebase.mockResolvedValueOnce({
+      id: 'codebase-1',
+      name: 'test-repo',
+      default_cwd: '/workspace/repo',
+    });
 
     const report = await runScheduledCleanup();
 
diff --git a/packages/core/src/services/cleanup-service.ts b/packages/core/src/services/cleanup-service.ts
index 50d9da0d2a..2ee21a1f06 100644
--- a/packages/core/src/services/cleanup-service.ts
+++ b/packages/core/src/services/cleanup-service.ts
@@ -128,22 +128,42 @@ export interface RemoveEnvironmentOptions {
   deleteRemoteBranch?: boolean;
 }
 
+/**
+ * Result from removeEnvironment indicating what actually happened
+ */
+export interface RemoveEnvironmentResult {
+  /** Whether the worktree was removed from disk */
+  worktreeRemoved: boolean;
+  /** Whether the branch was deleted (null if branch cleanup was not attempted) */
+  branchDeleted: boolean | null;
+  /** If the operation was a no-op, why it was skipped */
+  skippedReason?: string;
+  /** Warnings from partial cleanup (e.g., branch couldn't be deleted) */
+  warnings: string[];
+}
+
 /**
  * Remove a specific environment
  */
 export async function removeEnvironment(
   envId: string,
   options?: RemoveEnvironmentOptions
-): Promise<void> {
+): Promise<RemoveEnvironmentResult> {
+  const noopResult: RemoveEnvironmentResult = {
+    worktreeRemoved: false,
+    branchDeleted: false,
+    warnings: [],
+  };
+
   const env = await isolationEnvDb.getById(envId);
   if (!env) {
     getLog().debug({ envId }, 'env_not_found');
-    return;
+    return { ...noopResult, skippedReason: 'environment not found' };
   }
 
   if (env.status === 'destroyed') {
     getLog().debug({ envId }, 'env_already_destroyed');
-    return;
+    return { ...noopResult, skippedReason: 'already destroyed' };
   }
 
   // Get canonical repo path from codebase for branch cleanup
@@ -164,7 +184,7 @@ export async function removeEnvironment(
       const hasChanges = await hasUncommittedChanges(toWorktreePath(env.working_path));
       if (hasChanges) {
         getLog().warn({ envId, workingPath: env.working_path }, 'env_has_uncommitted_changes');
-        return;
+        return { ...noopResult, skippedReason: 'has uncommitted changes' };
       }
     }
 
@@ -186,6 +206,12 @@ export async function removeEnvironment(
     await isolationEnvDb.updateStatus(envId, 'destroyed');
 
     getLog().info({ envId, workingPath: env.working_path }, 'env_removed');
+
+    return {
+      worktreeRemoved: destroyResult.worktreeRemoved,
+      branchDeleted: destroyResult.branchDeleted,
+      warnings: destroyResult.warnings,
+    };
   } catch (error) {
     const err = error as Error & { code?: string; stderr?: string };
     const errorText = `${err.message} ${err.stderr ?? ''}`;
@@ -202,7 +228,7 @@ export async function removeEnvironment(
     if (isPathNotFoundError) {
       await isolationEnvDb.updateStatus(envId, 'destroyed');
       getLog().info({ envId }, 'env_removed_externally');
-      return;
+      return { worktreeRemoved: true, branchDeleted: false, warnings: [] };
     }
 
     getLog().error({ err, envId }, 'env_remove_failed');
@@ -271,8 +297,12 @@ export async function runScheduledCleanup(): Promise<CleanupReport> {
         const pathExists = await worktreeExists(toWorktreePath(env.working_path));
         if (!pathExists) {
           // Path doesn't exist - call removeEnvironment to clean up branch and mark as destroyed
-          await removeEnvironment(env.id, { force: false });
-          report.removed.push(`${env.id} (path missing)`);
+          const removeResult = await removeEnvironment(env.id, { force: false });
+          if (removeResult.skippedReason) {
+            report.skipped.push({ id: env.id, reason: removeResult.skippedReason });
+          } else {
+            report.removed.push(`${env.id} (path missing)`);
+          }
           continue;
         }
 
@@ -301,8 +331,15 @@ export async function runScheduledCleanup(): Promise<CleanupReport> {
           }
 
           // Safe to remove merged branch (also delete remote branch)
-          await removeEnvironment(env.id, { force: false, deleteRemoteBranch: true });
-          report.removed.push(`${env.id} (merged)`);
+          const mergedResult = await removeEnvironment(env.id, {
+            force: false,
+            deleteRemoteBranch: true,
+          });
+          if (mergedResult.skippedReason) {
+            report.skipped.push({ id: env.id, reason: mergedResult.skippedReason });
+          } else {
+            report.removed.push(`${env.id} (merged)`);
+          }
           continue;
         }
 
@@ -328,8 +365,12 @@ export async function runScheduledCleanup(): Promise<CleanupReport> {
             continue;
           }
 
-          await removeEnvironment(env.id, { force: false });
-          report.removed.push(`${env.id} (stale)`);
+          const staleResult = await removeEnvironment(env.id, { force: false });
+          if (staleResult.skippedReason) {
+            report.skipped.push({ id: env.id, reason: staleResult.skippedReason });
+          } else {
+            report.removed.push(`${env.id} (stale)`);
+          }
         }
       } catch (error) {
         const err = error as Error;
@@ -490,8 +531,12 @@ export async function cleanupStaleWorktrees(
 
     // Safe to remove
     try {
-      await removeEnvironment(env.id);
-      result.removed.push(env.branch_name);
+      const removeResult = await removeEnvironment(env.id);
+      if (removeResult.skippedReason) {
+        result.skipped.push({ branchName: env.branch_name, reason: removeResult.skippedReason });
+      } else {
+        result.removed.push(env.branch_name);
+      }
     } catch (error) {
       const err = error as Error;
       result.skipped.push({ branchName: env.branch_name, reason: err.message });
@@ -591,8 +636,12 @@ export async function cleanupMergedWorktrees(
 
     // Safe to remove (also delete remote branch since it's merged)
     try {
-      await removeEnvironment(env.id, { deleteRemoteBranch: true });
-      result.removed.push(env.branch_name);
+      const removeResult = await removeEnvironment(env.id, { deleteRemoteBranch: true });
+      if (removeResult.skippedReason) {
+        result.skipped.push({ branchName: env.branch_name, reason: removeResult.skippedReason });
+      } else {
+        result.removed.push(env.branch_name);
+      }
     } catch (error) {
       const err = error as Error;
       result.skipped.push({ branchName: env.branch_name, reason: err.message });
diff --git a/packages/core/src/services/title-generator.test.ts b/packages/core/src/services/title-generator.test.ts
index a53499a543..0d85e43c78 100644
--- a/packages/core/src/services/title-generator.test.ts
+++ b/packages/core/src/services/title-generator.test.ts
@@ -31,13 +31,13 @@ const mockSendQuery = mock(async function* (): AsyncGenerator<MessageChunk> {
   ) => AsyncGenerator<MessageChunk>
 >;
 
-const mockGetAssistantClient = mock(() => ({
+const mockGetAgentProvider = mock(() => ({
   sendQuery: mockSendQuery,
   getType: () => 'claude',
 }));
 
-mock.module('../clients/factory', () => ({
-  getAssistantClient: mockGetAssistantClient,
+mock.module('@archon/providers', () => ({
+  getAgentProvider: mockGetAgentProvider,
 }));
 
 // ─── Import module under test (AFTER all mocks) ─────────────────────────────
@@ -50,7 +50,7 @@ describe('title-generator', () => {
   beforeEach(() => {
     mockUpdateConversationTitle.mockClear();
     mockSendQuery.mockClear();
-    mockGetAssistantClient.mockClear();
+    mockGetAgentProvider.mockClear();
 
     // Reset to default happy-path behavior
     mockSendQuery.mockImplementation(async function* (): AsyncGenerator<MessageChunk> {
@@ -58,7 +58,7 @@ describe('title-generator', () => {
       yield { type: 'result' };
     });
 
-    mockGetAssistantClient.mockImplementation(() => ({
+    mockGetAgentProvider.mockImplementation(() => ({
       sendQuery: mockSendQuery,
       getType: () => 'claude',
     }));
@@ -167,11 +167,14 @@ describe('title-generator', () => {
     expect(optionsArg.model).toBeUndefined();
   });
 
-  test('passes tools: [] to disable tool access', async () => {
+  test('passes nodeConfig with allowed_tools: [] to disable tool access', async () => {
     await generateAndSetTitle('conv-11', 'Some message', 'claude', '/tmp');
 
-    const optionsArg = mockSendQuery.mock.calls[0][3] as { model?: string; tools?: string[] };
-    expect(optionsArg.tools).toEqual([]);
+    const optionsArg = mockSendQuery.mock.calls[0][3] as {
+      model?: string;
+      nodeConfig?: { allowed_tools?: string[] };
+    };
+    expect(optionsArg.nodeConfig?.allowed_tools).toEqual([]);
   });
 
   test('handles double failure gracefully (AI fails + fallback DB write fails)', async () => {
diff --git a/packages/core/src/services/title-generator.ts b/packages/core/src/services/title-generator.ts
index 7bfb8f9179..2331a984ef 100644
--- a/packages/core/src/services/title-generator.ts
+++ b/packages/core/src/services/title-generator.ts
@@ -5,7 +5,7 @@
  * Optionally uses TITLE_GENERATION_MODEL env var for a cheaper/faster model.
  * Designed to be fire-and-forget — never throws, all errors logged internally.
  */
-import { getAssistantClient } from '../clients/factory';
+import { getAgentProvider } from '@archon/providers';
 import * as conversationDb from '../db/conversations';
 import { createLogger } from '@archon/paths';
 
@@ -26,7 +26,7 @@ const MAX_TITLE_LENGTH = 100;
  *
  * @param conversationDbId - Database UUID of the conversation
  * @param userMessage - The user's message to generate a title from
- * @param assistantType - 'claude' or 'codex'
+ * @param assistantType - Provider identifier (e.g. 'claude', 'codex')
  * @param cwd - Working directory for the AI client
  * @param workflowName - Optional workflow name for additional context
  */
@@ -47,12 +47,12 @@ export async function generateAndSetTitle(
     const titlePrompt = buildTitlePrompt(userMessage, workflowName);
 
     // Use the configured AI client with no tools (pure text generation)
-    const client = getAssistantClient(assistantType);
+    const client = getAgentProvider(assistantType);
     let generatedTitle = '';
 
     for await (const chunk of client.sendQuery(titlePrompt, cwd, undefined, {
       model: titleModel,
-      tools: [], // No tool access — pure text generation
+      nodeConfig: { allowed_tools: [] }, // No tool access — pure text generation
     })) {
       if (chunk.type === 'assistant') {
         generatedTitle += chunk.content;
diff --git a/packages/core/src/test/mocks/streaming.ts b/packages/core/src/test/mocks/streaming.ts
deleted file mode 100644
index dd7cc76906..0000000000
--- a/packages/core/src/test/mocks/streaming.ts
+++ /dev/null
@@ -1,35 +0,0 @@
-import { mock, type Mock } from 'bun:test';
-
-export interface StreamEvent {
-  type: 'text' | 'tool' | 'error' | 'complete';
-  content?: string;
-  toolName?: string;
-  toolInput?: Record<string, unknown>;
-  error?: Error;
-}
-
-export async function* createMockStream(events: StreamEvent[]): AsyncGenerator<StreamEvent> {
-  for (const event of events) {
-    yield event;
-  }
-}
-
-export const createMockAssistantClient = (
-  events: StreamEvent[] = []
-): {
-  sendMessage: Mock<() => AsyncGenerator<StreamEvent>>;
-  getType: Mock<() => string>;
-  resumeSession: Mock<() => AsyncGenerator<StreamEvent>>;
-} => ({
-  sendMessage: mock(async function* () {
-    for (const event of events) {
-      yield event;
-    }
-  }),
-  getType: mock(() => 'claude'),
-  resumeSession: mock(async function* () {
-    for (const event of events) {
-      yield event;
-    }
-  }),
-});
diff --git a/packages/core/src/types/index.ts b/packages/core/src/types/index.ts
index 549891f35e..74966e3b2c 100644
--- a/packages/core/src/types/index.ts
+++ b/packages/core/src/types/index.ts
@@ -3,9 +3,11 @@
  */
 import type { TransitionTrigger } from '../state/session-transitions';
 import type { WorkflowDefinition } from '@archon/workflows/schemas/workflow';
-import type { McpServerConfig, AgentDefinition } from '@anthropic-ai/claude-agent-sdk';
 import { z } from 'zod';
 
+// MessageChunk imported for use in IPlatformAdapter/IWebPlatformAdapter below
+import type { MessageChunk } from '@archon/providers/types';
+
 /**
  * Custom error for when a conversation is not found during update operations
  * Allows callers to programmatically handle this specific error case
@@ -57,7 +59,6 @@ export interface Codebase {
   repository_url: string | null;
   default_cwd: string;
   ai_assistant_type: string;
-  allow_env_keys: boolean;
   commands: Record<string, { path: string; description: string }>;
   created_at: Date;
   updated_at: Date;
@@ -182,53 +183,7 @@ export function isWebAdapter(adapter: IPlatformAdapter): adapter is IWebPlatform
   return adapter.getPlatformType() === 'web';
 }
 
-/**
- * Message chunk from AI assistant.
- * Discriminated union with per-type required fields for type safety.
- */
-export interface TokenUsage {
-  input: number;
-  output: number;
-  total?: number;
-  cost?: number;
-}
-
-export type MessageChunk =
-  | { type: 'assistant'; content: string }
-  | { type: 'system'; content: string }
-  | { type: 'thinking'; content: string }
-  | {
-      type: 'result';
-      sessionId?: string;
-      tokens?: TokenUsage;
-      structuredOutput?: unknown;
-      isError?: boolean;
-      errorSubtype?: string;
-      cost?: number;
-      stopReason?: string;
-      numTurns?: number;
-      modelUsage?: Record<string, unknown>;
-    }
-  | { type: 'rate_limit'; rateLimitInfo: Record<string, unknown> }
-  | {
-      type: 'tool';
-      toolName: string;
-      toolInput?: Record<string, unknown>;
-      /** Stable per-call ID from the underlying SDK (e.g. Claude `tool_use_id`).
-       *  When present, the platform adapter uses it directly instead of generating
-       *  one — guarantees `tool_call`/`tool_result` pair correctly even when
-       *  multiple tools with the same name run concurrently. */
-      toolCallId?: string;
-    }
-  | {
-      type: 'tool_result';
-      toolName: string;
-      toolOutput: string;
-      /** Matching ID for the originating `tool` chunk. See `tool` variant above. */
-      toolCallId?: string;
-    }
-  | { type: 'workflow_dispatch'; workerConversationId: string; workflowName: string };
-
+// Re-export workflow schema types for config-types.ts compatibility
 import type { ModelReasoningEffort, WebSearchMode } from '@archon/workflows/schemas/workflow';
 export type { ModelReasoningEffort, WebSearchMode };
 import type {
@@ -237,147 +192,3 @@ import type {
   SandboxSettings,
 } from '@archon/workflows/schemas/dag-node';
 export type { EffortLevel, ThinkingConfig, SandboxSettings };
-
-export interface AssistantRequestOptions {
-  model?: string;
-  modelReasoningEffort?: ModelReasoningEffort;
-  webSearchMode?: WebSearchMode;
-  additionalDirectories?: string[];
-  /**
-   * Restrict the set of built-in tools available to the assistant.
-   * - `[]` — disable all built-in tools (Claude SDK only; Codex ignores this field)
-   * - `string[]` — restrict to the named tools
-   * Omit entirely to use the assistant's default tool set.
-   * Note: `undefined` (omitted) and `[]` have different semantics — do not confuse them.
-   */
-  tools?: string[];
-  /**
-   * Remove specific tools from the assistant's available set.
-   * Applied after `tools` whitelist (if both are set, denied tools are removed from the whitelist result).
-   * Claude SDK only — Codex ignores this field.
-   */
-  disallowedTools?: string[];
-  /**
-   * Structured output schema.
-   * Claude: passed as outputFormat option to Claude Agent SDK.
-   * Codex: passed as outputSchema in TurnOptions to Codex SDK (v0.116.0+).
-   * Shape: { type: 'json_schema', schema: <JSON Schema object> }
-   */
-  outputFormat?: { type: 'json_schema'; schema: Record<string, unknown> };
-  /** SDK hooks configuration. Passed directly to Claude Agent SDK Options.hooks. Claude only — ignored for Codex. */
-  hooks?: Partial<
-    Record<
-      string,
-      {
-        matcher?: string;
-        hooks: ((
-          input: unknown,
-          toolUseID: string | undefined,
-          options: { signal: AbortSignal }
-        ) => Promise<unknown>)[];
-        timeout?: number;
-      }[]
-    >
-  >;
-  /**
-   * MCP server configuration passed to Claude Agent SDK Options.mcpServers.
-   * Uses SDK type directly — @archon/core already depends on the SDK.
-   * Claude only — Codex ignores this.
-   */
-  mcpServers?: Record<string, McpServerConfig>;
-  /** Tools to auto-allow without permission prompts (e.g., MCP tool wildcards).
-   *  Passed to Claude Agent SDK Options.allowedTools. Claude only. */
-  allowedTools?: string[];
-  /** Custom subagent definitions passed to Claude Agent SDK Options.agents.
-   *  Used for per-node skill scoping via AgentDefinition wrapping. Claude only. */
-  agents?: Record<string, AgentDefinition>;
-  /** Name of agent definition for the main thread. References a key in `agents`. Claude only. */
-  agent?: string;
-  /**
-   * Abort signal for cancelling in-flight AI requests.
-   * When aborted, the AI client should terminate the subprocess/query gracefully.
-   */
-  abortSignal?: AbortSignal;
-  /**
-   * When false (default), skips writing session transcript to ~/.claude/projects/.
-   * Claude Agent SDK v0.2.74+. The SDK default is true, but Archon overrides it to false
-   * to avoid disk pollution. Set to true only when session persistence is explicitly needed.
-   */
-  persistSession?: boolean;
-  /**
-   * When true, the SDK copies the prior session's history into a new session file
-   * before appending, leaving the original untouched. Use with `resume` to safely
-   * preserve conversation context without risk of corrupting the source session.
-   * Claude only — ignored for Codex.
-   */
-  forkSession?: boolean;
-  /**
-   * Claude Code settingSources — controls which CLAUDE.md files are loaded.
-   * Passed directly to Claude Agent SDK Options.settingSources.
-   * Claude only — ignored for Codex.
-   * @default ['project']
-   */
-  settingSources?: ('project' | 'user')[];
-  /**
-   * Additional env vars merged into Claude subprocess environment after buildSubprocessEnv().
-   * Final env: { ...buildSubprocessEnv(), ...env } (auth tokens conditionally filtered).
-   * Claude only — Codex SDK does not support env injection.
-   */
-  env?: Record<string, string>;
-  /**
-   * Controls reasoning depth for Claude. Claude only — ignored for Codex.
-   */
-  effort?: EffortLevel;
-  /**
-   * Controls Claude's thinking/reasoning behavior. Claude only — ignored for Codex.
-   */
-  thinking?: ThinkingConfig;
-  /**
-   * Maximum USD cost budget. SDK returns error_max_budget_usd result if exceeded.
-   * Claude only — ignored for Codex.
-   */
-  maxBudgetUsd?: number;
-  /**
-   * Per-node system prompt string. Overrides the default claude_code preset.
-   * Claude only — ignored for Codex.
-   */
-  systemPrompt?: string;
-  /**
-   * Fallback model if primary fails. Claude only — ignored for Codex.
-   */
-  fallbackModel?: string;
-  /**
-   * SDK beta feature flags. Claude only — ignored for Codex.
-   */
-  betas?: string[];
-  /**
-   * OS-level sandbox settings passed to Claude subprocess.
-   * Claude only — ignored for Codex.
-   */
-  sandbox?: SandboxSettings;
-}
-
-/**
- * Generic AI assistant client interface
- * Allows supporting multiple AI assistants (Claude, Codex, etc.)
- */
-export interface IAssistantClient {
-  /**
-   * Send a message and get streaming response
-   * @param prompt - User message or prompt
-   * @param cwd - Working directory for the assistant
-   * @param resumeSessionId - Optional session ID to resume
-   * @param options - Optional request options (model, provider-specific settings)
-   */
-  sendQuery(
-    prompt: string,
-    cwd: string,
-    resumeSessionId?: string,
-    options?: AssistantRequestOptions
-  ): AsyncGenerator<MessageChunk>;
-
-  /**
-   * Get the assistant type identifier
-   */
-  getType(): string;
-}
diff --git a/packages/core/src/utils/commands.ts b/packages/core/src/utils/commands.ts
index ae87cbf6bd..8204b5d716 100644
--- a/packages/core/src/utils/commands.ts
+++ b/packages/core/src/utils/commands.ts
@@ -7,11 +7,18 @@ import { join, basename } from 'path';
 /**
  * Recursively find all .md files in a directory and its subdirectories.
  * Skips hidden directories and node_modules.
+ *
+ * `maxDepth` caps how many folders deep the walk descends. Default is
+ * `Infinity` (no cap) so callers that copy arbitrary subtrees (e.g.
+ * `packages/core/src/handlers/clone.ts`) preserve existing behavior.
  */
 export async function findMarkdownFilesRecursive(
   rootPath: string,
-  relativePath = ''
+  relativePath = '',
+  options?: { maxDepth?: number }
 ): Promise<{ commandName: string; relativePath: string }[]> {
+  const maxDepth = options?.maxDepth ?? Infinity;
+  const currentDepth = relativePath ? relativePath.split(/[/\\]/).filter(Boolean).length : 0;
   const results: { commandName: string; relativePath: string }[] = [];
   const fullPath = join(rootPath, relativePath);
 
@@ -23,7 +30,12 @@ export async function findMarkdownFilesRecursive(
     }
 
     if (entry.isDirectory()) {
-      const subResults = await findMarkdownFilesRecursive(rootPath, join(relativePath, entry.name));
+      if (currentDepth >= maxDepth) continue;
+      const subResults = await findMarkdownFilesRecursive(
+        rootPath,
+        join(relativePath, entry.name),
+        options
+      );
       results.push(...subResults);
     } else if (entry.isFile() && entry.name.endsWith('.md')) {
       results.push({
diff --git a/packages/core/src/utils/env-leak-scanner.test.ts b/packages/core/src/utils/env-leak-scanner.test.ts
deleted file mode 100644
index 4d436bbc24..0000000000
--- a/packages/core/src/utils/env-leak-scanner.test.ts
+++ /dev/null
@@ -1,133 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
-import { writeFileSync, mkdirSync, rmSync } from 'fs';
-import { join } from 'path';
-import {
-  scanPathForSensitiveKeys,
-  EnvLeakError,
-  formatLeakError,
-  SENSITIVE_KEYS,
-  AUTOLOADED_FILES,
-} from './env-leak-scanner';
-
-describe('scanPathForSensitiveKeys', () => {
-  const tmpDir = '/tmp/archon-test-env-scan';
-
-  beforeEach(() => {
-    mkdirSync(tmpDir, { recursive: true });
-  });
-  afterEach(() => {
-    rmSync(tmpDir, { recursive: true, force: true });
-  });
-
-  it('returns empty findings for clean directory', () => {
-    const report = scanPathForSensitiveKeys(tmpDir);
-    expect(report.findings).toHaveLength(0);
-  });
-
-  it('returns empty findings for non-existent directory', () => {
-    const report = scanPathForSensitiveKeys('/tmp/archon-test-nonexistent-dir');
-    expect(report.findings).toHaveLength(0);
-  });
-
-  // Each sensitive key × each auto-loaded filename
-  for (const key of SENSITIVE_KEYS) {
-    for (const filename of AUTOLOADED_FILES) {
-      it(`detects ${key} in ${filename}`, () => {
-        writeFileSync(join(tmpDir, filename), `${key}=sk-test-value\nOTHER=safe\n`);
-        const report = scanPathForSensitiveKeys(tmpDir);
-        expect(report.findings).toHaveLength(1);
-        expect(report.findings[0].file).toBe(filename);
-        expect(report.findings[0].keys).toContain(key);
-        // Clean up for next iteration
-        rmSync(join(tmpDir, filename));
-      });
-    }
-  }
-
-  it('ignores commented-out keys', () => {
-    writeFileSync(join(tmpDir, '.env'), '# ANTHROPIC_API_KEY=value\n');
-    const report = scanPathForSensitiveKeys(tmpDir);
-    expect(report.findings).toHaveLength(0);
-  });
-
-  it('ignores lines without =', () => {
-    writeFileSync(join(tmpDir, '.env'), 'ANTHROPIC_API_KEY\n');
-    const report = scanPathForSensitiveKeys(tmpDir);
-    expect(report.findings).toHaveLength(0);
-  });
-
-  it('reports multiple files with findings', () => {
-    writeFileSync(join(tmpDir, '.env'), 'ANTHROPIC_API_KEY=sk-1\n');
-    writeFileSync(join(tmpDir, '.env.local'), 'OPENAI_API_KEY=sk-2\n');
-    const report = scanPathForSensitiveKeys(tmpDir);
-    expect(report.findings).toHaveLength(2);
-  });
-
-  it('reports multiple keys in same file', () => {
-    writeFileSync(join(tmpDir, '.env'), 'ANTHROPIC_API_KEY=sk-1\nOPENAI_API_KEY=sk-2\n');
-    const report = scanPathForSensitiveKeys(tmpDir);
-    expect(report.findings).toHaveLength(1);
-    expect(report.findings[0].keys).toHaveLength(2);
-  });
-
-  it('ignores non-autoloaded filenames', () => {
-    writeFileSync(join(tmpDir, '.env.secrets'), 'ANTHROPIC_API_KEY=sk-1\n');
-    const report = scanPathForSensitiveKeys(tmpDir);
-    expect(report.findings).toHaveLength(0);
-  });
-
-  it('ignores safe keys', () => {
-    writeFileSync(join(tmpDir, '.env'), 'DATABASE_URL=postgres://localhost\nNODE_ENV=dev\n');
-    const report = scanPathForSensitiveKeys(tmpDir);
-    expect(report.findings).toHaveLength(0);
-  });
-});
-
-describe('EnvLeakError', () => {
-  it('is instanceof EnvLeakError and Error', () => {
-    const report = { path: '/tmp', findings: [{ file: '.env', keys: ['ANTHROPIC_API_KEY'] }] };
-    const err = new EnvLeakError(report);
-    expect(err).toBeInstanceOf(Error);
-    expect(err).toBeInstanceOf(EnvLeakError);
-    expect(err.name).toBe('EnvLeakError');
-    expect(err.message).toContain('ANTHROPIC_API_KEY');
-    expect(err.report).toBe(report);
-  });
-
-  it('defaults context to register-ui and stores it on the error', () => {
-    const report = { path: '/x', findings: [{ file: '.env', keys: ['ANTHROPIC_API_KEY'] }] };
-    const err = new EnvLeakError(report);
-    expect(err.context).toBe('register-ui');
-    expect(err.message).toContain('Add Project');
-  });
-
-  it('produces distinct remediation bodies per context', () => {
-    const report = { path: '/x', findings: [{ file: '.env', keys: ['ANTHROPIC_API_KEY'] }] };
-    const ui = formatLeakError(report, 'register-ui');
-    const cli = formatLeakError(report, 'register-cli');
-    const spawn = formatLeakError(report, 'spawn-existing');
-    expect(ui).toContain('Add Project');
-    expect(cli).toContain('--allow-env-keys');
-    expect(cli).toContain('allow_target_repo_keys');
-    expect(spawn).toContain('Settings');
-    expect(spawn).toContain('already-registered');
-    // headers differ between register and spawn
-    expect(ui).toContain('Cannot add codebase');
-    expect(spawn).toContain('Cannot run workflow');
-  });
-
-  it('formats multiple findings', () => {
-    const report = {
-      path: '/test',
-      findings: [
-        { file: '.env', keys: ['ANTHROPIC_API_KEY'] },
-        { file: '.env.local', keys: ['OPENAI_API_KEY', 'GEMINI_API_KEY'] },
-      ],
-    };
-    const err = new EnvLeakError(report);
-    expect(err.message).toContain('.env');
-    expect(err.message).toContain('.env.local');
-    expect(err.message).toContain('OPENAI_API_KEY');
-    expect(err.message).toContain('GEMINI_API_KEY');
-  });
-});
diff --git a/packages/core/src/utils/env-leak-scanner.ts b/packages/core/src/utils/env-leak-scanner.ts
deleted file mode 100644
index 48edc2c6b7..0000000000
--- a/packages/core/src/utils/env-leak-scanner.ts
+++ /dev/null
@@ -1,155 +0,0 @@
-import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
-
-export const SENSITIVE_KEYS = new Set([
-  'ANTHROPIC_API_KEY',
-  'ANTHROPIC_AUTH_TOKEN',
-  'CLAUDE_API_KEY',
-  'CLAUDE_CODE_OAUTH_TOKEN',
-  'OPENAI_API_KEY',
-  'CODEX_API_KEY',
-  'GEMINI_API_KEY',
-]);
-
-export const AUTOLOADED_FILES = [
-  '.env',
-  '.env.local',
-  '.env.development',
-  '.env.production',
-  '.env.development.local',
-  '.env.production.local',
-];
-
-export interface LeakFinding {
-  file: string;
-  keys: string[];
-}
-
-export interface LeakReport {
-  path: string;
-  findings: LeakFinding[];
-}
-
-/**
- * Context in which the env-leak error is being surfaced. Drives the remediation
- * copy so users see guidance that matches how they hit the gate.
- *
- * - `register-ui`: Add-Project flow in the Web UI (checkbox is visible)
- * - `register-cli`: CLI auto-register path (no Web UI)
- * - `spawn-existing`: Pre-spawn check for an already-registered codebase
- */
-export type LeakErrorContext = 'register-ui' | 'register-cli' | 'spawn-existing';
-
-export class EnvLeakError extends Error {
-  public readonly context: LeakErrorContext;
-  constructor(
-    public readonly report: LeakReport,
-    context: LeakErrorContext = 'register-ui'
-  ) {
-    super(formatLeakError(report, context));
-    this.name = 'EnvLeakError';
-    this.context = context;
-  }
-}
-
-/**
- * Scan `dirPath` for auto-loaded .env files containing sensitive keys.
- * Pure function — no side effects.
- */
-export function scanPathForSensitiveKeys(dirPath: string): LeakReport {
-  const findings: LeakFinding[] = [];
-
-  for (const filename of AUTOLOADED_FILES) {
-    const fullPath = join(dirPath, filename);
-    if (!existsSync(fullPath)) continue;
-
-    let contents: string;
-    try {
-      contents = readFileSync(fullPath, 'utf8');
-    } catch (err) {
-      // File exists but is unreadable — treat as a finding to avoid silently bypassing the gate
-      const code = (err as NodeJS.ErrnoException).code;
-      findings.push({ file: filename, keys: [`[unreadable — ${code ?? 'unknown error'}]`] });
-      continue;
-    }
-
-    const foundKeys: string[] = [];
-    for (const line of contents.split('\n')) {
-      const trimmed = line.trim();
-      if (trimmed.startsWith('#') || !trimmed.includes('=')) continue;
-      const key = trimmed.split('=')[0].trim();
-      if (SENSITIVE_KEYS.has(key)) {
-        foundKeys.push(key);
-      }
-    }
-
-    if (foundKeys.length > 0) {
-      findings.push({ file: filename, keys: foundKeys });
-    }
-  }
-
-  return { path: dirPath, findings };
-}
-
-/**
- * Exhaustive per-context consent remediation copy. Using `switch` with a
- * `never` default means adding a new `LeakErrorContext` variant without
- * handling it here is a compile error — important for a security-visible path.
- */
-function consentCopy(context: LeakErrorContext): string {
-  switch (context) {
-    case 'register-cli':
-      return `    3. Acknowledge the risk and allow this codebase to use its .env key:
-       Re-run the CLI command with --allow-env-keys, or set
-       'allow_target_repo_keys: true' in ~/.archon/config.yaml to bypass this
-       gate globally.`;
-    case 'spawn-existing':
-      return `    3. Acknowledge the risk for this already-registered codebase:
-       Open the Web UI (Settings → Projects), find this project, and toggle
-       "Allow env keys". Or set 'allow_target_repo_keys: true' in
-       ~/.archon/config.yaml to bypass this gate globally.`;
-    case 'register-ui':
-      return `    3. Acknowledge the risk and allow this codebase to use its .env key:
-       Open the web UI (Settings → Projects → Add Project) and tick
-       "Allow env keys (I understand the risk)" when adding this project.`;
-    default: {
-      const exhaustive: never = context;
-      return exhaustive;
-    }
-  }
-}
-
-export function formatLeakError(
-  report: LeakReport,
-  context: LeakErrorContext = 'register-ui'
-): string {
-  const fileList = report.findings.map(f => `    ${f.file} — ${f.keys.join(', ')}`).join('\n');
-
-  const header =
-    context === 'spawn-existing'
-      ? `Cannot run workflow — ${report.path} contains keys that will leak into AI subprocesses`
-      : `Cannot add codebase — ${report.path} contains keys that will leak into AI subprocesses`;
-
-  const consent = consentCopy(context);
-
-  return `${header}
-
-  Found:
-${fileList}
-
-  Why this matters:
-  Bun subprocesses auto-load .env from their working directory. Archon cleans
-  its own environment, but Claude/Codex subprocesses running with cwd=<this repo>
-  will re-inject these keys at their own startup, bypassing archon's allowlist.
-  This can bill the wrong API account silently.
-
-  Choose one:
-    1. Remove the key from this repo's .env (recommended):
-         grep -v '^ANTHROPIC_API_KEY=' .env > .env.tmp && mv .env.tmp .env
-
-    2. Rename to a non-auto-loaded file:
-         mv .env .env.secrets
-         # update your app to load it explicitly
-
-${consent}`;
-}
diff --git a/packages/core/src/utils/error-formatter.test.ts b/packages/core/src/utils/error-formatter.test.ts
index 0e3bfe01c8..c9c82c867b 100644
--- a/packages/core/src/utils/error-formatter.test.ts
+++ b/packages/core/src/utils/error-formatter.test.ts
@@ -19,25 +19,97 @@ describe('classifyAndFormatError', () => {
     });
   });
 
-  describe('authentication errors', () => {
+  describe('Claude OAuth refresh-token errors', () => {
+    test('detects "refresh token" in message', () => {
+      const result = classifyAndFormatError(new Error('Your refresh token was already used'));
+      expect(result).toContain('Claude authentication expired');
+      expect(result).toContain('/login');
+    });
+
+    test('detects "could not be refreshed" in message', () => {
+      const result = classifyAndFormatError(new Error('Your access token could not be refreshed'));
+      expect(result).toContain('Claude authentication expired');
+    });
+
+    test('detects "log out and sign in" in message', () => {
+      const result = classifyAndFormatError(new Error('Please log out and sign in again'));
+      expect(result).toContain('Claude authentication expired');
+    });
+
+    test('detects "OAuth token has expired" in message', () => {
+      const result = classifyAndFormatError(
+        new Error('API Error: 401 OAuth token has expired. Please run /login')
+      );
+      expect(result).toContain('Claude authentication expired');
+      expect(result).toContain('claude logout && claude login');
+    });
+
+    test('detects "sign-in has expired" in message', () => {
+      const result = classifyAndFormatError(
+        new Error('Unable to start session: sign-in has expired')
+      );
+      expect(result).toContain('Claude authentication expired');
+    });
+
+    test('handles full Claude OAuth error with refresh token race condition', () => {
+      const result = classifyAndFormatError(
+        new Error(
+          'Claude Code auth error: Your access token could not be refreshed because your refresh token was already used. Please log out and sign in again.'
+        )
+      );
+      expect(result).toContain('Claude authentication expired');
+    });
+  });
+
+  describe('Claude general auth errors', () => {
+    test('detects "Claude Code auth error:" prefix for non-OAuth errors', () => {
+      const result = classifyAndFormatError(new Error('Claude Code auth error: 403 forbidden'));
+      expect(result).toContain('Claude authentication error');
+      expect(result).toContain('/login');
+    });
+  });
+
+  describe('Codex auth errors', () => {
+    test('detects Codex 401 retry exhaustion', () => {
+      const result = classifyAndFormatError(
+        new Error('Codex query failed: exceeded retry limit, last status: 401 Unauthorized')
+      );
+      expect(result).toContain('Codex authentication error');
+      expect(result).toContain('codex login');
+    });
+
+    test('detects Codex query failed with Unauthorized', () => {
+      const result = classifyAndFormatError(new Error('Codex query failed: Unauthorized'));
+      expect(result).toContain('Codex authentication error');
+      expect(result).toContain('codex login');
+    });
+  });
+
+  describe('general authentication errors', () => {
     test('detects "API key" in message', () => {
       const result = classifyAndFormatError(new Error('Invalid API key provided'));
-      expect(result).toBe('⚠️ AI service authentication error. Please check configuration.');
+      expect(result).toContain('authentication error');
+    });
+
+    test('detects "authentication_error" in message', () => {
+      const result = classifyAndFormatError(new Error('authentication_error: invalid'));
+      expect(result).toContain('authentication error');
     });
 
-    test('detects "authentication" in message', () => {
-      const result = classifyAndFormatError(new Error('authentication failed'));
-      expect(result).toBe('⚠️ AI service authentication error. Please check configuration.');
+    test('detects "authentication error" in message', () => {
+      const result = classifyAndFormatError(new Error('authentication error'));
+      expect(result).toContain('authentication error');
     });
 
     test('detects "401" in message', () => {
       const result = classifyAndFormatError(new Error('HTTP 401 Unauthorized'));
-      expect(result).toBe('⚠️ AI service authentication error. Please check configuration.');
+      expect(result).toContain('authentication error');
     });
 
-    test('detects 401 as standalone in message', () => {
-      const result = classifyAndFormatError(new Error('Status: 401'));
-      expect(result).toBe('⚠️ AI service authentication error. Please check configuration.');
+    test('does not false-positive on generic messages containing "auth"', () => {
+      // "auth" alone should NOT match — only specific patterns
+      const result = classifyAndFormatError(new Error('author name missing'));
+      expect(result).not.toContain('authentication');
     });
   });
 
@@ -232,9 +304,24 @@ describe('classifyAndFormatError', () => {
       expect(result).toBe('⚠️ AI rate limit reached. Please wait a moment and try again.');
     });
 
+    test('Claude OAuth check takes precedence over general auth check', () => {
+      // Contains both "refresh token" and "Claude Code auth error:" — OAuth branch fires first
+      const result = classifyAndFormatError(
+        new Error('Claude Code auth error: refresh token expired')
+      );
+      expect(result).toContain('Claude authentication expired');
+    });
+
+    test('Codex auth takes precedence over generic Codex error handler', () => {
+      // Contains "Codex query failed:" AND "401" — Codex auth branch fires first
+      const result = classifyAndFormatError(new Error('Codex query failed: 401 Unauthorized'));
+      expect(result).toContain('Codex authentication error');
+      expect(result).toContain('codex login');
+    });
+
     test('auth check takes precedence over short-message fallback', () => {
       const result = classifyAndFormatError(new Error('API key'));
-      expect(result).toBe('⚠️ AI service authentication error. Please check configuration.');
+      expect(result).toContain('authentication error');
     });
 
     test('Codex check is applied before generic fallback', () => {
diff --git a/packages/core/src/utils/error-formatter.ts b/packages/core/src/utils/error-formatter.ts
index 86e51f8a41..25658b5cd6 100644
--- a/packages/core/src/utils/error-formatter.ts
+++ b/packages/core/src/utils/error-formatter.ts
@@ -19,13 +19,42 @@ export function classifyAndFormatError(error: Error): string {
     return '⚠️ AI rate limit reached. Please wait a moment and try again.';
   }
 
-  // AI/SDK errors - authentication
+  // Claude-specific auth errors — OAuth token refresh failures
+  // These come from Claude Code subprocess stderr or SDK result subtypes.
+  // Recovery: `/login` in-session or `claude logout && claude login` in terminal.
+  if (
+    message.includes('refresh token') ||
+    message.includes('could not be refreshed') ||
+    message.includes('log out and sign in') ||
+    message.includes('OAuth token has expired') ||
+    message.includes('sign-in has expired')
+  ) {
+    return '⚠️ Claude authentication expired. Run `/login` inside Claude Code or `claude logout && claude login` in your terminal.';
+  }
+
+  // Claude-specific auth errors — general (subprocess crash with auth classification)
+  if (message.startsWith('Claude Code auth error:')) {
+    return '⚠️ Claude authentication error. Run `/login` inside Claude Code or check your API key configuration.';
+  }
+
+  // Codex-specific auth errors — 401 retry exhaustion
+  // Codex surfaces auth failures as "exceeded retry limit, last status: 401 Unauthorized"
+  // Recovery: `codex login` in terminal.
+  if (
+    message.includes('Codex query failed:') &&
+    (message.includes('401') || message.includes('Unauthorized'))
+  ) {
+    return '⚠️ Codex authentication error. Run `codex login` in your terminal to re-authenticate.';
+  }
+
+  // General AI/SDK authentication errors
   if (
     message.includes('API key') ||
-    message.includes('authentication') ||
+    message.includes('authentication_error') ||
+    message.includes('authentication error') ||
     message.includes('401')
   ) {
-    return '⚠️ AI service authentication error. Please check configuration.';
+    return '⚠️ AI service authentication error. Please check your API key or credentials.';
   }
 
   // Network errors - timeout
diff --git a/packages/core/src/utils/port-allocation.ts b/packages/core/src/utils/port-allocation.ts
index efb34d3198..0ecb5b74e1 100644
--- a/packages/core/src/utils/port-allocation.ts
+++ b/packages/core/src/utils/port-allocation.ts
@@ -30,7 +30,7 @@ export function calculatePortOffset(path: string): number {
  * Get the port for the Hono server
  * - If PORT env var is set: use it (explicit override, validated)
  * - If running in worktree: auto-allocate deterministic port based on path hash
- * - Otherwise: use default 3000
+ * - Otherwise: use default 3090 (matches the Vite proxy fallback in packages/web/vite.config.ts)
  *
  * Note: Exits process with code 1 if PORT env var is set but invalid (not 1-65535)
  */
diff --git a/packages/core/src/workflows/store-adapter.test.ts b/packages/core/src/workflows/store-adapter.test.ts
index 0501a88000..f193a2075c 100644
--- a/packages/core/src/workflows/store-adapter.test.ts
+++ b/packages/core/src/workflows/store-adapter.test.ts
@@ -44,8 +44,8 @@ mock.module('../db/codebases', () => ({
   getCodebase: mockGetCodebase,
 }));
 
-mock.module('../clients/factory', () => ({
-  getAssistantClient: mock(() => ({})),
+mock.module('@archon/providers', () => ({
+  getAgentProvider: mock(() => ({})),
 }));
 
 mock.module('../config/config-loader', () => ({
@@ -145,10 +145,10 @@ describe('createWorkflowStore', () => {
 });
 
 describe('createWorkflowDeps', () => {
-  test('returns WorkflowDeps with store, getAssistantClient, and loadConfig', () => {
+  test('returns WorkflowDeps with store, getAgentProvider, and loadConfig', () => {
     const deps = createWorkflowDeps();
     expect(deps.store).toBeDefined();
-    expect(typeof deps.getAssistantClient).toBe('function');
+    expect(typeof deps.getAgentProvider).toBe('function');
     expect(typeof deps.loadConfig).toBe('function');
   });
 
diff --git a/packages/core/src/workflows/store-adapter.ts b/packages/core/src/workflows/store-adapter.ts
index 0bf8683fb8..67040fda93 100644
--- a/packages/core/src/workflows/store-adapter.ts
+++ b/packages/core/src/workflows/store-adapter.ts
@@ -10,7 +10,7 @@ import * as workflowDb from '../db/workflows';
 import * as workflowEventDb from '../db/workflow-events';
 import * as codebaseDb from '../db/codebases';
 import * as envVarDb from '../db/env-vars';
-import { getAssistantClient } from '../clients/factory';
+import { getAgentProvider } from '@archon/providers';
 import { loadConfig as loadMergedConfig } from '../config/config-loader';
 import { createLogger } from '@archon/paths';
 
@@ -69,7 +69,7 @@ export function createWorkflowStore(): IWorkflowStore {
 export function createWorkflowDeps(): WorkflowDeps {
   return {
     store: createWorkflowStore(),
-    getAssistantClient,
+    getAgentProvider,
     loadConfig: loadMergedConfig,
   };
 }
diff --git a/packages/docs-web/astro.config.mjs b/packages/docs-web/astro.config.mjs
index cabfa83fd9..d4d0301cfe 100644
--- a/packages/docs-web/astro.config.mjs
+++ b/packages/docs-web/astro.config.mjs
@@ -15,7 +15,7 @@ export default defineConfig({
       head: [
         {
           tag: 'script',
-          content: `if(!localStorage.getItem('starlight-theme')){localStorage.setItem('starlight-theme','dark');document.documentElement.dataset.theme='dark';}`,
+          content: `if(!localStorage.getItem('archon-theme-init')){localStorage.setItem('archon-theme-init','1');localStorage.setItem('starlight-theme','dark');document.documentElement.dataset.theme='dark';}`,
         },
       ],
       social: [{ icon: 'github', label: 'GitHub', href: 'https://github.com/coleam00/Archon' }],
diff --git a/packages/docs-web/package.json b/packages/docs-web/package.json
index 7d0ce08d83..38ab7a44a7 100644
--- a/packages/docs-web/package.json
+++ b/packages/docs-web/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@archon/docs-web",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "private": true,
   "scripts": {
     "dev": "astro dev",
diff --git a/packages/docs-web/src/content/docs/adapters/web.md b/packages/docs-web/src/content/docs/adapters/web.md
index 79cde0277d..0025ca0219 100644
--- a/packages/docs-web/src/content/docs/adapters/web.md
+++ b/packages/docs-web/src/content/docs/adapters/web.md
@@ -81,7 +81,7 @@ Accessible via the `/dashboard` route, the Command Center shows all workflow run
 
 ### Settings
 
-The `/settings` page lets you configure assistant defaults (model, provider) without editing YAML files.
+The `/settings` page lets you configure assistant defaults (model, provider) without editing YAML files. It also includes a **Projects** section for registering and managing codebases.
 
 ## Chat Interface
 
@@ -172,6 +172,7 @@ The Workflow Builder at `/workflows/builder` provides a visual editor for creati
 - **Command picker** -- Browse available commands when configuring command nodes
 - **Validation panel** -- Real-time validation feedback as you build
 - **Undo/redo** -- Full undo/redo stack with keyboard shortcuts
+- **Delete node** -- Remove a selected node with `Delete` or `Backspace`, the Delete button in the inspector header, or the right-click context menu on any node
 - **Save** -- Saves the workflow YAML to your project's `.archon/workflows/` directory
 
 You can also browse existing workflows on the `/workflows` page and open any of them in the builder to edit.
@@ -203,10 +204,11 @@ A separate dashboard SSE stream at `/api/stream/__dashboard__` multiplexes workf
 
 ### Registering a Project
 
-From the Web UI, you can register codebases in two ways:
+From the Web UI, you can register codebases in three ways:
 
-1. **Clone from URL** -- Use the `/clone <url>` command in chat, or use the API to POST to `/api/codebases` with a `url` field
-2. **Register a local path** -- POST to `/api/codebases` with a `path` field pointing to an existing git repository
+1. **Add Project input** -- Click **+** in the sidebar or go to **Settings → Projects** and enter a GitHub URL or local path. Inputs starting with `https://`, `ssh://`, `git@`, or `git://` are treated as remote URLs (cloned); everything else is treated as a local path (registered in place).
+2. **Clone from URL via chat** -- Use the `/clone <url>` command in chat, or use the API to POST to `/api/codebases` with a `url` field
+3. **Register a local path via API** -- POST to `/api/codebases` with a `path` field pointing to an existing git repository
 
 Registered codebases appear in the sidebar's project selector.
 
diff --git a/packages/docs-web/src/content/docs/book/first-workflow.md b/packages/docs-web/src/content/docs/book/first-workflow.md
index 866de8b3f1..63040e367a 100644
--- a/packages/docs-web/src/content/docs/book/first-workflow.md
+++ b/packages/docs-web/src/content/docs/book/first-workflow.md
@@ -195,7 +195,7 @@ You've just built a mini version of `archon-idea-to-pr` — the same structure,
 |--------|-------------|-------------|
 | `name` | Identifies the workflow in `archon workflow list` | Required |
 | `description` | Shown in listings and used by the router | Required |
-| `provider` | Sets the AI provider (`claude` or `codex`) | When you need a specific provider |
+| `provider` | Sets the AI provider (any registered provider, e.g. `claude`, `codex`) | When you need a specific provider |
 | `model` | Sets the model for all nodes (`sonnet`, `opus`, `haiku`) | When you want to override the config default |
 | `context` | `fresh` starts a new session; `shared` inherits from prior node | Use `fresh` before verification nodes |
 | `depends_on` | List of node IDs that must complete before this node runs | To express ordering and fan-in |
diff --git a/packages/docs-web/src/content/docs/book/quick-reference.md b/packages/docs-web/src/content/docs/book/quick-reference.md
index ede87c0dab..ae37659f7a 100644
--- a/packages/docs-web/src/content/docs/book/quick-reference.md
+++ b/packages/docs-web/src/content/docs/book/quick-reference.md
@@ -108,7 +108,7 @@ archon workflow run my-workflow "auth refresh-tokens"
 | `name` | Yes | string | Identifies the workflow in `archon workflow list` |
 | `description` | Yes | string | Shown in listings and used by the router |
 | `nodes` | Yes | array | DAG nodes (see Node Options below) |
-| `provider` | No | `claude` \| `codex` | AI provider for all nodes (default: `claude`) |
+| `provider` | No | string | Registered provider identifier (e.g. `claude`, `codex`). Default: `claude` |
 | `model` | No | string | Model for all nodes (`sonnet`, `opus`, `haiku`, or full model ID) |
 | `modelReasoningEffort` | No | string | Codex only: `minimal` \| `low` \| `medium` \| `high` \| `xhigh` |
 | `webSearchMode` | No | string | Codex only: `disabled` \| `cached` \| `live` |
@@ -128,7 +128,7 @@ All nodes share these base fields:
 | `depends_on` | No | string[] | Node IDs that must complete before this node runs |
 | `when` | No | string | Condition expression; node is skipped if false |
 | `trigger_rule` | No | string | Join semantics when multiple upstreams exist (see Trigger Rules) |
-| `provider` | No | `claude` \| `codex` | Per-node provider override |
+| `provider` | No | string | Per-node provider override (any registered provider) |
 | `model` | No | string | Per-node model override |
 | `context` | No | `fresh` \| `shared` | Session context — `fresh` starts a new conversation, `shared` inherits from prior node |
 | `output_format` | No | JSON Schema | Enforce structured JSON output from this node |
@@ -272,7 +272,7 @@ defaults:
 | `Routing unclear — falling back to archon-assist` | No workflow matched the input | Use an explicit workflow name: `archon workflow run my-workflow "..."` |
 | `Worktree already exists for branch X` | Prior run left a worktree | Run `archon complete X` or `archon isolation cleanup` |
 | `Not a git repository` | Running outside a repo | `cd` into a git repo first — workflow and isolation commands require one |
-| `Model X is not valid for provider Y` | Provider/model mismatch | Use Claude models (`sonnet`, `opus`, `haiku`) with `provider: claude`; use other models with `provider: codex` |
+| `Model X is not valid for provider Y` | Provider/model mismatch | Each provider accepts specific models — check the provider's `isModelCompatible` rules. Claude accepts `sonnet`, `opus`, `haiku`, `claude-*`; Codex accepts other models. |
 | `$BASE_BRANCH referenced but could not be detected` | No base branch set and auto-detection failed | Set `worktree.baseBranch` in `.archon/config.yaml` or ensure `main`/`master` exists |
 | Workflow hangs with no output | Node idle timeout hit | Increase `idle_timeout` on the node (milliseconds) |
 
diff --git a/packages/docs-web/src/content/docs/contributing/adding-a-community-provider.md b/packages/docs-web/src/content/docs/contributing/adding-a-community-provider.md
new file mode 100644
index 0000000000..4a521a4a8d
--- /dev/null
+++ b/packages/docs-web/src/content/docs/contributing/adding-a-community-provider.md
@@ -0,0 +1,179 @@
+---
+title: Adding a Community Provider
+description: Step-by-step guide to adding a new AI agent provider under packages/providers/src/community/.
+---
+
+Archon's provider registry (Phase 2, [#1195](https://github.com/coleam00/Archon/pull/1195)) is designed so community providers can be added with changes localized to a single directory. This guide walks through the pattern using the Pi provider as the reference implementation (`packages/providers/src/community/pi/`).
+
+## The contract
+
+Every provider implements `IAgentProvider` from `@archon/providers/types`:
+
+```typescript
+export interface IAgentProvider {
+  sendQuery(
+    prompt: string,
+    cwd: string,
+    resumeSessionId?: string,
+    options?: SendQueryOptions,
+  ): AsyncGenerator<MessageChunk>;
+
+  getType(): string;
+  getCapabilities(): ProviderCapabilities;
+}
+```
+
+The provider yields a stream of `MessageChunk` variants (see `packages/providers/src/types.ts`). Archon normalizes every backend to this shape so platform adapters, the DAG executor, and the orchestrator don't need to know whether they're talking to Claude, Codex, Pi, or your provider.
+
+## Directory layout
+
+A community provider lives entirely under `packages/providers/src/community/<your-provider-id>/`. The Pi provider uses this layout:
+
+```
+packages/providers/src/community/pi/
+├── provider.ts          # PiProvider class (IAgentProvider impl)
+├── capabilities.ts      # PI_CAPABILITIES constant
+├── config.ts            # parsePiConfig, PiProviderDefaults
+├── model-ref.ts         # model-string parsing + compat check
+├── event-bridge.ts      # SDK-event → MessageChunk conversion
+├── session-resolver.ts  # optional: session lifecycle helpers
+├── options-translator.ts  # optional: nodeConfig → SDK-options translation
+├── registration.ts      # registerPiProvider()
+├── resource-loader.ts   # optional: SDK-specific helpers
+├── index.ts             # public exports
+└── *.test.ts            # co-located tests
+```
+
+Each file has one job. Optional files only exist when the translation surface is non-trivial — a minimal provider could fit `provider.ts` + `capabilities.ts` + `registration.ts` + `index.ts` + one test file.
+
+## Step-by-step
+
+### 1. Capabilities (start honest)
+
+Declare only what you've actually wired. The dag-executor emits a warning to the user when a workflow node uses a feature your provider doesn't support — under-declaration is self-correcting via those warnings; over-declaration means Archon silently drops configuration.
+
+```typescript
+// capabilities.ts
+import type { ProviderCapabilities } from '../../types';
+
+export const YOUR_CAPABILITIES: ProviderCapabilities = {
+  sessionResume: false,
+  mcp: false,
+  hooks: false,
+  skills: false,
+  toolRestrictions: false,
+  structuredOutput: false,
+  envInjection: false,
+  costControl: false,
+  effortControl: false,
+  thinkingControl: false,
+  fallbackModel: false,
+  sandbox: false,
+};
+```
+
+Start everything at `false`. Flip to `true` one at a time as you wire each translation, and add a test per flip.
+
+### 2. Provider class
+
+Implement `IAgentProvider`. Pattern:
+
+```typescript
+// provider.ts
+import { createLogger } from '@archon/paths';
+import type { IAgentProvider, MessageChunk, ProviderCapabilities, SendQueryOptions } from '../../types';
+import { YOUR_CAPABILITIES } from './capabilities';
+
+let cachedLog: ReturnType<typeof createLogger> | undefined;
+function getLog() {
+  if (!cachedLog) cachedLog = createLogger('provider.your-id');
+  return cachedLog;
+}
+
+export class YourProvider implements IAgentProvider {
+  async *sendQuery(prompt, cwd, resumeSessionId, options): AsyncGenerator<MessageChunk> {
+    // 1. Parse assistantConfig (user-level defaults from .archon/config.yaml)
+    // 2. Resolve model (options.model || config default)
+    // 3. Resolve auth (options.env → process.env → config)
+    // 4. Translate nodeConfig to SDK options (only for capabilities you declared)
+    // 5. Invoke SDK, yield normalized MessageChunks
+    // 6. Include sessionId in final `result` chunk (for resume)
+  }
+
+  getType() { return 'your-id'; }
+  getCapabilities() { return YOUR_CAPABILITIES; }
+}
+```
+
+See `packages/providers/src/community/pi/provider.ts` for a full reference with retry, fail-fast auth validation, and resume fallback.
+
+### 3. Registration
+
+Each community provider exports a `register*Provider()` function. Idempotent — guard with `isRegisteredProvider(id)` so it's safe to call from multiple bootstrap sites.
+
+```typescript
+// registration.ts
+import { isRegisteredProvider, registerProvider } from '../../registry';
+import { YOUR_CAPABILITIES } from './capabilities';
+import { YourProvider } from './provider';
+
+export function registerYourProvider(): void {
+  if (isRegisteredProvider('your-id')) return;
+  registerProvider({
+    id: 'your-id',
+    displayName: 'Your Provider (community)',
+    factory: () => new YourProvider(),
+    capabilities: YOUR_CAPABILITIES,
+    isModelCompatible: (model) => /* pattern check */,
+    builtIn: false, // ← important: community providers are NOT built-in
+  });
+}
+```
+
+Then add one line to the aggregator at `packages/providers/src/registry.ts`:
+
+```typescript
+export function registerCommunityProviders(): void {
+  registerPiProvider();
+  registerYourProvider(); // ← add your provider here
+}
+```
+
+**That is the entire cross-cutting change.** No entrypoint edits, no config-type edits. The aggregator is already called from the CLI, server, and config-loader bootstrap paths.
+
+### 4. Tests
+
+Co-locate tests next to your code. The Pi tests use this isolation pattern:
+
+- Mock the SDK (`mock.module` at the top of the file, before importing your provider).
+- Tests that touch `mock.module` are split into separate `bun test` invocations in `packages/providers/package.json` (see existing entries for the Pi files). Bun's `mock.module` is process-global and irreversible — splitting prevents cross-file pollution.
+- Registry test (`packages/providers/src/registry.test.ts`): add a `describe` block asserting `builtIn: false`, idempotent registration, and `isModelCompatible` behavior.
+
+### 5. Capability discipline
+
+When you're ready to wire additional capabilities, each translation gets its own small module. Pi uses:
+
+- `options-translator.ts` for thinking level, tool filters, skills resolution
+- `session-resolver.ts` for session create/open/list
+- `event-bridge.ts` for SDK-event → MessageChunk mapping
+
+This keeps the provider class readable — `provider.ts` orchestrates; the translators are unit-testable without the SDK.
+
+## What NOT to do
+
+- **Don't edit `AssistantDefaultsConfig` or `AssistantDefaults` in `packages/core/src/config/config-types.ts`.** Community provider defaults live behind the generic `[string]` index signature that was designed for this case. Adding a typed slot defeats the Phase 2 contract and forces future providers to follow suit.
+- **Don't call `registerProvider()` from CLI or server entrypoints directly.** Use the `registerCommunityProviders()` aggregator. Entrypoints should never grow per-community-provider calls.
+- **Don't overclaim capabilities.** If a workflow node uses `hooks: [...]` and your provider silently ignores it, the user has no feedback. The dag-executor warns honestly if you declare `hooks: false`.
+- **Don't write session state or credentials outside your provider's SDK-managed directory.** Archon's config, workspaces, and sessions are managed elsewhere — your provider should stay within its own SDK's storage conventions (mirror how Claude writes to `~/.claude/` and Codex uses its thread store).
+
+## Reference implementation
+
+The Pi provider at `packages/providers/src/community/pi/` is the canonical example. It covers:
+
+- Multi-backend model selection via `<pi-provider>/<model-id>` refs (parse once, validate syntactically)
+- OAuth + API-key passthrough (reads `~/.pi/agent/auth.json`, overrides per-request)
+- Async-queue bridge from callback-based SDK events to `AsyncGenerator<MessageChunk>`
+- Session resume via `SessionManager.list(cwd)` + `SessionManager.open(path)`
+- Capability translations: `effort/thinking`, `allowed_tools/denied_tools`, `skills`, `systemPrompt`
+
+Read `packages/providers/src/community/pi/provider.ts` top-to-bottom — the comments call out every design decision and link to the upstream Pi SDK behavior.
diff --git a/packages/docs-web/src/content/docs/contributing/cli-internals.md b/packages/docs-web/src/content/docs/contributing/cli-internals.md
index 2adaa99fa2..2e218621d6 100644
--- a/packages/docs-web/src/content/docs/contributing/cli-internals.md
+++ b/packages/docs-web/src/content/docs/contributing/cli-internals.md
@@ -38,8 +38,19 @@ packages/cli/
                                   │
                                   ▼
 ┌─────────────────────────────────────────────────────────────────┐
-│ cli.ts  Load environment                                        │
-│         Loads ~/.archon/.env with override: true                │
+│ strip-cwd-env-boot  (first import, side-effect)                 │
+│   stripCwdEnv(): deletes Bun-auto-loaded <cwd>/.env* keys from  │
+│   process.env + CLAUDE_CODE_* session markers. Emits            │
+│   [archon] stripped N keys from <cwd> (...) when N > 0.         │
+└─────────────────────────────────┬───────────────────────────────┘
+                                  │
+                                  ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ loadArchonEnv(cwd)  — both loads use override: true             │
+│   1. ~/.archon/.env        (home scope)                         │
+│   2. <cwd>/.archon/.env    (repo scope, wins over home)         │
+│   Emits one [archon] loaded N keys from <path> line per file    │
+│   when N > 0.                                                   │
 └─────────────────────────────────┬───────────────────────────────┘
                                   │
                                   ▼
diff --git a/packages/docs-web/src/content/docs/deployment/docker.md b/packages/docs-web/src/content/docs/deployment/docker.md
index fc1add6678..e1caf127a7 100644
--- a/packages/docs-web/src/content/docs/deployment/docker.md
+++ b/packages/docs-web/src/content/docs/deployment/docker.md
@@ -11,6 +11,11 @@ sidebar:
 
 Deploy Archon on a server with Docker. Includes automatic HTTPS, PostgreSQL, and the Web UI.
 
+> **Claude Code is pre-installed in the image.** The official `ghcr.io/coleam00/archon` image
+> ships with Claude Code installed via npm and `CLAUDE_BIN_PATH` pre-set — no extra configuration
+> required. If you build a custom image that omits the npm install, set `CLAUDE_BIN_PATH` yourself
+> to point at a mounted `cli.js` (see [AI Assistants → Binary path configuration](/getting-started/ai-assistants/#binary-path-configuration-compiled-binaries-only)).
+
 ---
 
 ## Cloud-Init (Fastest Setup)
diff --git a/packages/docs-web/src/content/docs/deployment/local.md b/packages/docs-web/src/content/docs/deployment/local.md
index 2e3c9f9618..f0ff1a021d 100644
--- a/packages/docs-web/src/content/docs/deployment/local.md
+++ b/packages/docs-web/src/content/docs/deployment/local.md
@@ -22,9 +22,11 @@ Local development with SQLite is the recommended default. No database setup is n
 ### Prerequisites
 
 - [Bun](https://bun.sh) 1.0+
-- At least one AI assistant configured (Claude Code or Codex)
+- At least one AI assistant installed and configured (Claude Code or Codex — Archon orchestrates them, it does not bundle them)
 - A GitHub token for repository cloning (`GH_TOKEN` / `GITHUB_TOKEN`)
 
+> Source installs (`bun run`) auto-resolve Claude Code's `cli.js` via `node_modules`. Compiled Archon binaries require `CLAUDE_BIN_PATH` or `assistants.claude.claudeBinaryPath` — see [AI Assistants → Binary path configuration](/getting-started/ai-assistants/#binary-path-configuration-compiled-binaries-only).
+
 ### Setup
 
 ```bash
@@ -35,7 +37,7 @@ bun install
 
 # 2. Configure environment
 cp .env.example .env
-nano .env  # Add your AI assistant tokens (Claude or Codex)
+nano .env  # Add your AI assistant tokens (Claude, Codex, or Pi)
 
 # 3. Start server + Web UI (SQLite auto-detected, no database setup needed)
 bun run dev
diff --git a/packages/docs-web/src/content/docs/getting-started/ai-assistants.md b/packages/docs-web/src/content/docs/getting-started/ai-assistants.md
index c856c9ccd4..ff4f8e6533 100644
--- a/packages/docs-web/src/content/docs/getting-started/ai-assistants.md
+++ b/packages/docs-web/src/content/docs/getting-started/ai-assistants.md
@@ -1,6 +1,6 @@
 ---
 title: AI Assistants
-description: Configure Claude Code and Codex as AI assistants for Archon.
+description: Configure Claude Code, Codex, and Pi as AI assistants for Archon.
 category: getting-started
 area: clients
 audience: [user]
@@ -9,12 +9,70 @@ sidebar:
   order: 4
 ---
 
-You must configure **at least one** AI assistant. Both can be configured if desired.
+You must configure **at least one** AI assistant. All three can be configured and mixed within workflows.
 
 ## Claude Code
 
 **Recommended for Claude Pro/Max subscribers.**
 
+Archon does not bundle Claude Code. Install it separately, then in compiled Archon binaries, point Archon at the executable. In dev (`bun run`), Archon finds it automatically via `node_modules`.
+
+### Install Claude Code
+
+Anthropic's native installer is the primary recommended install path:
+
+**macOS / Linux / WSL:**
+
+```bash
+curl -fsSL https://claude.ai/install.sh | bash
+```
+
+**Windows (PowerShell):**
+
+```powershell
+irm https://claude.ai/install.ps1 | iex
+```
+
+**Alternatives:**
+
+- macOS via Homebrew: `brew install --cask claude-code`
+- npm (any platform): `npm install -g @anthropic-ai/claude-code`
+- Windows via winget: `winget install Anthropic.ClaudeCode`
+
+See [Anthropic's setup guide](https://code.claude.com/docs/en/setup) for the full list and auto-update caveats per install path.
+
+### Binary path configuration (compiled binaries only)
+
+Compiled Archon binaries cannot auto-discover Claude Code at runtime. Supply the path via either:
+
+1. **Environment variable** (highest precedence):
+   ```ini
+   CLAUDE_BIN_PATH=/absolute/path/to/claude
+   ```
+2. **Config file** (`~/.archon/config.yaml` or a repo-local `.archon/config.yaml`):
+   ```yaml
+   assistants:
+     claude:
+       claudeBinaryPath: /absolute/path/to/claude
+   ```
+
+If neither is set in a compiled binary, Archon throws with install instructions on first Claude query.
+
+The Claude Agent SDK accepts either the native compiled binary or a JS `cli.js`.
+
+**Typical paths by install method:**
+
+| Install method | Typical executable path |
+|---|---|
+| Native curl installer (macOS/Linux) | `~/.local/bin/claude` |
+| Native PowerShell installer (Windows) | `%USERPROFILE%\.local\bin\claude.exe` |
+| Homebrew cask | `$(brew --prefix)/bin/claude` (symlink) |
+| npm global install | `$(npm root -g)/@anthropic-ai/claude-code/cli.js` |
+| Windows winget | Resolvable via `where claude` |
+| Docker (`ghcr.io/coleam00/archon`) | Pre-set via `ENV CLAUDE_BIN_PATH` in the image — no action required |
+
+If in doubt, `which claude` (macOS/Linux) or `where claude` (Windows) will resolve the executable on your PATH after any of the installers above.
+
 ### Authentication Options
 
 Claude Code supports three authentication modes via `CLAUDE_USE_GLOBAL_AUTH`:
@@ -62,6 +120,9 @@ assistants:
     settingSources:
       - project      # Default: only project-level CLAUDE.md
       - user         # Optional: also load ~/.claude/CLAUDE.md
+    # Optional: absolute path to the Claude Code executable.
+    # Required in compiled Archon binaries if CLAUDE_BIN_PATH is not set.
+    # claudeBinaryPath: /absolute/path/to/claude
 ```
 
 The `settingSources` option controls which `CLAUDE.md` files the Claude Code SDK loads. By default, only the project-level `CLAUDE.md` is loaded. Add `user` to also load your personal `~/.claude/CLAUDE.md`.
@@ -76,10 +137,46 @@ DEFAULT_AI_ASSISTANT=claude
 
 ## Codex
 
-### Authenticate with Codex CLI
+Archon does not bundle the Codex CLI. Install it, then authenticate.
+
+### Install the Codex CLI
+
+```bash
+# Any platform (primary method):
+npm install -g @openai/codex
+
+# macOS alternative:
+brew install codex
+
+# Windows: npm install works but is experimental.
+# OpenAI recommends WSL2 for the best experience.
+```
+
+Native prebuilt binaries (`.dmg`, `.tar.gz`, `.exe`) are also published on the [Codex releases page](https://github.com/openai/codex/releases) for users who prefer a direct binary — drop one in `~/.archon/vendor/codex/codex` (or `codex.exe` on Windows) and Archon will find it automatically in compiled binary mode.
+
+See [OpenAI's Codex CLI docs](https://developers.openai.com/codex/cli) for the full install matrix.
+
+### Binary path configuration (compiled binaries only)
+
+In compiled Archon binaries, if `codex` is not on the default PATH Archon expects, supply the path via either:
+
+1. **Environment variable** (highest precedence):
+   ```ini
+   CODEX_BIN_PATH=/absolute/path/to/codex
+   ```
+2. **Config file** (`~/.archon/config.yaml`):
+   ```yaml
+   assistants:
+     codex:
+       codexBinaryPath: /absolute/path/to/codex
+   ```
+3. **Vendor directory** (zero-config fallback): drop the native binary at `~/.archon/vendor/codex/codex` (or `codex.exe` on Windows).
+
+Dev mode (`bun run`) does not require any of the above — the SDK resolves `codex` via `node_modules`.
+
+### Authenticate
 
 ```bash
-# Install Codex CLI first: https://docs.codex.com/installation
 codex login
 
 # Follow browser authentication flow
@@ -130,6 +227,153 @@ If you want Codex to be the default AI assistant for new conversations without c
 DEFAULT_AI_ASSISTANT=codex
 ```
 
+## Pi (Community Provider)
+
+**One adapter, ~20 LLM backends.** Pi (`@mariozechner/pi-coding-agent`) is a community-maintained coding-agent harness that Archon integrates as the first community provider. It unlocks Anthropic, OpenAI, Google (Gemini + Vertex), Groq, Mistral, Cerebras, xAI, OpenRouter, Hugging Face, and more under a single `provider: pi` entry.
+
+Pi is registered as `builtIn: false` — it validates the community-provider seam rather than being a core-team-maintained option. If it proves stable and valuable it may be promoted to `builtIn: true` later.
+
+### Install
+
+Pi is included as a dependency of `@archon/providers` — no separate install needed. It's available immediately.
+
+### Authenticate
+
+Pi supports both OAuth subscriptions and API keys. Archon's adapter reads your existing Pi credentials from `~/.pi/agent/auth.json` (written by running `pi` → `/login`) AND from env vars — env vars take priority per-request so codebase-scoped overrides work.
+
+**OAuth subscriptions (run `pi /login` locally):**
+- Anthropic Claude Pro/Max
+- OpenAI ChatGPT Plus/Pro
+- GitHub Copilot
+- Google Gemini CLI
+- Google Antigravity
+
+**API keys (env vars):**
+
+| Pi provider id | Env var |
+|---|---|
+| `anthropic` | `ANTHROPIC_API_KEY` |
+| `openai` | `OPENAI_API_KEY` |
+| `google` | `GEMINI_API_KEY` |
+| `groq` | `GROQ_API_KEY` |
+| `mistral` | `MISTRAL_API_KEY` |
+| `cerebras` | `CEREBRAS_API_KEY` |
+| `xai` | `XAI_API_KEY` |
+| `openrouter` | `OPENROUTER_API_KEY` |
+| `huggingface` | `HUGGINGFACE_API_KEY` |
+
+Additional Pi backends exist (Azure, Bedrock, Vertex, etc.) — file an issue if you need them wired.
+
+### Extensions (on by default)
+
+A major reason to pick Pi is its **extension ecosystem**: community packages (installed via `pi install npm:<package>`) and your own local ones that hook into the agent's lifecycle. Extensions can intercept tool calls, gate execution on human review, post to external systems, render UIs — anything the Pi extension API exposes.
+
+Archon turns extensions **on by default**. To opt out in `.archon/config.yaml`:
+
+```yaml
+assistants:
+  pi:
+    enableExtensions: false   # skip extension discovery entirely
+    # interactive: false       # keep extensions loaded, but give them no UI bridge
+```
+
+Most extensions need three config surfaces:
+
+| Surface | Purpose |
+|---|---|
+| `extensionFlags` | Per-extension feature flags (maps 1:1 to Pi's `--flag` CLI switches) |
+| `env` | Env vars the extension reads at runtime (managed via `.archon/config.yaml` or the Web UI codebase env panel) |
+| Workflow-level `interactive: true` | Required for **approval-gate extensions** on the web UI — forces foreground execution so the user can respond |
+
+**Example — [plannotator](https://github.com/dmcglinn/plannotator) (human-in-the-loop plan review):**
+
+```bash
+# One-time install into your Pi home
+pi install npm:@plannotator/pi-extension
+```
+
+```yaml
+# .archon/config.yaml
+assistants:
+  pi:
+    model: anthropic/claude-haiku-4-5
+    extensionFlags:
+      plan: true              # enables the plannotator "plan" flag
+    env:
+      PLANNOTATOR_REMOTE: "1" # exposes the review URL on 127.0.0.1:19432 so you can open it from anywhere
+```
+
+```yaml
+# .archon/workflows/my-piv.yaml
+name: my-piv
+provider: pi
+interactive: true             # plannotator gates the node on human approval — required on web UI
+```
+
+When the node runs, plannotator prints a review URL and blocks until you click approve/deny in the browser. Archon's CLI/SSE batch buffer flushes that URL to you immediately so you never get stuck waiting on a node that silently wants input.
+
+### Model reference format
+
+Pi models use a `<pi-provider-id>/<model-id>` format:
+
+```yaml
+assistants:
+  pi:
+    model: anthropic/claude-haiku-4-5       # via Anthropic
+    # model: google/gemini-2.5-pro           # via Google
+    # model: groq/llama-3.3-70b-versatile   # via Groq
+    # model: openrouter/qwen/qwen3-coder    # via OpenRouter (nested slashes allowed)
+```
+
+### Usage in workflows
+
+```yaml
+name: my-workflow
+provider: pi
+model: anthropic/claude-haiku-4-5
+
+nodes:
+  - id: fast-node
+    provider: pi
+    model: groq/llama-3.3-70b-versatile   # per-node override — switches backends
+    prompt: "..."
+    effort: low
+    allowed_tools: [read, grep]            # Pi's built-in tools: read, bash, edit, write, grep, find, ls
+
+  - id: careful-node
+    provider: pi
+    model: anthropic/claude-opus-4-5
+    prompt: "..."
+    effort: high
+    skills: [archon-dev]                   # Archon name refs work — see Pi capabilities below
+```
+
+### Pi capabilities
+
+| Feature | Support | YAML field |
+|---|---|---|
+| Extensions (community + local) | ✅ (default on) | `enableExtensions: false` to disable; `interactive: false` to load without UI bridge; `extensionFlags: { <name>: true }` per extension |
+| Session resume | ✅ | automatic (Archon persists `sessionId`) |
+| Tool restrictions | ✅ | `allowed_tools` / `denied_tools` (read, bash, edit, write, grep, find, ls) |
+| Thinking level | ✅ | `effort: low\|medium\|high\|max` (max → xhigh) |
+| Skills | ✅ | `skills: [name]` (searches `.agents/skills`, `.claude/skills`, user-global) |
+| Inline sub-agents | ❌ | `agents:` is Claude-only; ignored with a warning on Pi |
+| System prompt override | ✅ | `systemPrompt:` |
+| Codebase env vars (`envInjection`) | ✅ | `.archon/config.yaml` `env:` section |
+| MCP servers | ❌ | Pi rejects MCP by design |
+| Claude-SDK hooks | ❌ | Claude-specific format |
+| Structured output | ✅ (best-effort) | `output_format:` — schema is appended to the prompt and JSON is parsed out of the assistant text (bare or ```json```-fenced); degrades cleanly when the model emits prose. Not SDK-enforced like Claude/Codex. |
+| Cost limits (`maxBudgetUsd`) | ❌ | tracked in result chunk, not enforced |
+| Fallback model | ❌ | not native in Pi |
+| Sandbox | ❌ | not native in Pi |
+
+Unsupported YAML fields trigger a visible warning from the dag-executor when the workflow runs, so you always know what was ignored.
+
+### See also
+
+- [Adding a Community Provider](../contributing/adding-a-community-provider/) — the contributor-facing guide for extending Archon with your own provider.
+- [Pi on GitHub](https://github.com/badlogic/pi-mono) — upstream project.
+
 ## How Assistant Selection Works
 
 - Assistant type is set per codebase via the `assistant` field in `.archon/config.yaml` or the `DEFAULT_AI_ASSISTANT` env var
diff --git a/packages/docs-web/src/content/docs/getting-started/configuration.md b/packages/docs-web/src/content/docs/getting-started/configuration.md
index ec836f1202..5a8588e1fa 100644
--- a/packages/docs-web/src/content/docs/getting-started/configuration.md
+++ b/packages/docs-web/src/content/docs/getting-started/configuration.md
@@ -14,9 +14,11 @@ Set these in your shell or `.env` file:
 
 | Variable | Required | Description |
 |----------|----------|-------------|
+| `CLAUDE_BIN_PATH` | Yes (binary builds) | Absolute path to the Claude Code SDK's `cli.js`. Required in compiled Archon binaries unless `assistants.claude.claudeBinaryPath` is set. Dev mode (`bun run`) auto-resolves via `node_modules`. |
 | `CLAUDE_USE_GLOBAL_AUTH` | No | Set to `true` to use credentials from `claude /login` (default when no other Claude token is set) |
 | `CLAUDE_CODE_OAUTH_TOKEN` | No | OAuth token from `claude setup-token` (alternative to global auth) |
 | `CLAUDE_API_KEY` | No | Anthropic API key for pay-per-use (alternative to global auth) |
+| `CODEX_BIN_PATH` | No | Absolute path to the Codex CLI binary. Overrides auto-detection in compiled Archon builds. |
 | `CODEX_ACCESS_TOKEN` | Yes (for Codex) | Codex access token (see [AI Assistants](/getting-started/ai-assistants/)) |
 | `DATABASE_URL` | No | PostgreSQL connection string (default: SQLite) |
 | `LOG_LEVEL` | No | `debug`, `info` (default), `warn`, `error` |
diff --git a/packages/docs-web/src/content/docs/getting-started/installation.md b/packages/docs-web/src/content/docs/getting-started/installation.md
index 4af7ba9aff..20bf4eb32b 100644
--- a/packages/docs-web/src/content/docs/getting-started/installation.md
+++ b/packages/docs-web/src/content/docs/getting-started/installation.md
@@ -47,6 +47,42 @@ bun install
 - [GitHub CLI](https://cli.github.com/) (`gh`)
 - [Claude Code](https://claude.ai/code) (`claude`)
 
+## Claude Code is required
+
+Archon orchestrates Claude Code; it does not bundle it. Install Claude Code separately:
+
+```bash
+# macOS / Linux / WSL (Anthropic's recommended installer)
+curl -fsSL https://claude.ai/install.sh | bash
+
+# Windows (PowerShell)
+irm https://claude.ai/install.ps1 | iex
+```
+
+Source installs (`bun run`) find the executable automatically via `node_modules`. Compiled binaries (quick install, Homebrew) must point at the Claude Code executable:
+
+```bash
+# After the native installer:
+export CLAUDE_BIN_PATH="$HOME/.local/bin/claude"
+
+# After `npm install -g @anthropic-ai/claude-code`:
+export CLAUDE_BIN_PATH="$(npm root -g)/@anthropic-ai/claude-code/cli.js"
+```
+
+Or set it durably in `~/.archon/config.yaml`:
+
+```yaml
+assistants:
+  claude:
+    claudeBinaryPath: /absolute/path/to/claude
+```
+
+Docker images (`ghcr.io/coleam00/archon`) ship with Claude Code pre-installed and
+`CLAUDE_BIN_PATH` pre-set — no configuration needed.
+
+See [AI Assistants → Claude Code](/getting-started/ai-assistants/#binary-path-configuration-compiled-binaries-only)
+for full details and install-layout paths.
+
 ## Verify Installation
 
 ```bash
diff --git a/packages/docs-web/src/content/docs/getting-started/overview.md b/packages/docs-web/src/content/docs/getting-started/overview.md
index f1d58ae402..5125b93503 100644
--- a/packages/docs-web/src/content/docs/getting-started/overview.md
+++ b/packages/docs-web/src/content/docs/getting-started/overview.md
@@ -20,7 +20,7 @@ Before you start, make sure you have:
 | -------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------- |
 | **Git**                          | `git --version`    | [git-scm.com](https://git-scm.com/)                                                                                 |
 | **Bun** (replaces Node.js + npm) | `bun --version`    | Linux/macOS: `curl -fsSL https://bun.sh/install \| bash` — Windows: `powershell -c "irm bun.sh/install.ps1 \| iex"` |
-| **Claude Code CLI**              | `claude --version` | [docs.claude.com/claude-code/installation](https://docs.claude.com/en/docs/claude-code/installation)                |
+| **Claude Code CLI**              | `claude --version` | [docs.claude.com/claude-code/installation](https://docs.claude.com/en/docs/claude-code/installation) — in compiled Archon binaries, also set `CLAUDE_BIN_PATH` ([details](/getting-started/ai-assistants/#binary-path-configuration-compiled-binaries-only)) |
 | **GitHub account**               | —                  | [github.com](https://github.com/)                                                                                   |
 
 > **Do not run as root.** Archon (and the Claude Code CLI it depends on) does not work when run as the `root` user. If you're on a VPS or server that only has root, create a regular user first:
@@ -383,9 +383,9 @@ assistant: claude
 commands:
   folder: .claude/commands/archon    # additional command search path
 worktree:
-  copyFiles:
-    - .env.example                   # copy into worktrees (same filename)
-    - .env
+  copyFiles:                         # gitignored files/dirs to copy into worktrees
+    - .env                           # (`.archon/` is copied automatically — no need to list it)
+    - plans/
 ```
 
 Without any `.archon/` config, the platform uses sensible defaults (bundled commands and workflows).
@@ -482,17 +482,19 @@ The CLI is standalone, but if you also want to interact via Telegram, Slack, Dis
 
 ## Troubleshooting
 
-### "Cannot create worktree: not in a git repository" (but the repo exists)
+### "Cannot create worktree: repository registration failed" (stale workspace symlink)
 
-The real cause is usually a stale symlink from a previous Archon run with a different path. Look for this in the error output:
+This happens when `~/.archon/workspaces/<owner>/<repo>/source` is a symlink pointing at a previous checkout (common after moving or renaming the repo). The error message includes the exact cleanup path to follow:
 
 ```
-Source symlink at ~/.archon/workspaces/.../source already points to <old-path>, expected <new-path>
+Cannot create worktree: repository registration failed.
+Error: Source symlink at ~/.archon/workspaces/<owner>/<repo>/source already points to <old-path>, expected <new-path>
+Hint: Remove the stale workspace entry at ~/.archon/workspaces/<owner>/<repo> and retry, or use --no-worktree to skip isolation.
 ```
 
-Fix it by manually deleting the stale workspace folder at `~/.archon/workspaces/<github-user>/<repo-name>` and retrying the command.
+Follow the hint — delete the stale workspace folder and re-run, or pass `--no-worktree` to skip isolation for one run.
 
-> In the future, `archon isolation cleanup` will handle this automatically.
+> On Archon versions before this fix, the same root cause surfaced as the misleading "Cannot create worktree: not in a git repository" (even though the repo was valid). If you see that string, upgrade and you'll get the actionable message above.
 
 ---
 
@@ -601,6 +603,6 @@ For always-on access from any device, see the [Docker Deployment Guide](/deploym
 ## Further Reading
 
 - [Configuration](/getting-started/configuration/) — All configuration options
-- [AI Assistants](/getting-started/ai-assistants/) — Claude and Codex setup details
+- [AI Assistants](/getting-started/ai-assistants/) — Claude, Codex, and Pi setup details
 - [CLI Reference](/reference/cli/) — Full CLI documentation
 - [Authoring Workflows](/guides/authoring-workflows/) — Creating custom workflows
diff --git a/packages/docs-web/src/content/docs/getting-started/quick-start.md b/packages/docs-web/src/content/docs/getting-started/quick-start.md
index 58a76a62b2..529bf6026d 100644
--- a/packages/docs-web/src/content/docs/getting-started/quick-start.md
+++ b/packages/docs-web/src/content/docs/getting-started/quick-start.md
@@ -10,8 +10,10 @@ sidebar:
 ## Prerequisites
 
 1. [Install Archon](/getting-started/installation/)
-2. Authenticate with Claude: run `claude /login` (uses your existing Claude Pro/Max subscription)
-3. Navigate to any git repository
+2. [Install Claude Code](/getting-started/ai-assistants/#claude-code) — Archon orchestrates it but does not bundle it
+3. Authenticate with Claude: run `claude /login` (uses your existing Claude Pro/Max subscription)
+4. In compiled Archon binaries, set `CLAUDE_BIN_PATH` (see [Binary path configuration](/getting-started/ai-assistants/#binary-path-configuration-compiled-binaries-only))
+5. Navigate to any git repository
 
 ## Run Your First Workflow
 
diff --git a/packages/docs-web/src/content/docs/guides/approval-nodes.md b/packages/docs-web/src/content/docs/guides/approval-nodes.md
index 42ebc48fec..c48f8c4856 100644
--- a/packages/docs-web/src/content/docs/guides/approval-nodes.md
+++ b/packages/docs-web/src/content/docs/guides/approval-nodes.md
@@ -55,9 +55,9 @@ to the user on whatever platform they're using (CLI, Slack, GitHub, etc.). On th
    block the worktree path guard (no other workflow can start on the same path).
 4. **Approve**: The user approves, which writes a `node_completed` event for
    the approval node and transitions the run to resumable. Natural-language
-   messages (recommended) and the CLI auto-resume immediately. The explicit
-   `/workflow approve` command records the approval; send a follow-up message
-   to resume.
+   messages, the CLI, and the Web UI approve button all auto-resume the
+   workflow from the paused gate. (The explicit `/workflow approve <run-id>`
+   slash command also auto-resumes when issued in the originating conversation.)
 5. **Reject**: The user rejects.
    - **Without `on_reject`**: The workflow is cancelled immediately.
    - **With `on_reject`**: The executor runs the `on_reject.prompt` via AI (with
@@ -140,7 +140,19 @@ bun run cli workflow reject <run-id> --reason "Plan needs more test coverage"
 ### Web UI
 
 Paused workflows show an amber pulsing badge on the dashboard. Click **Approve**
-or **Reject** directly on the workflow card.
+or **Reject** directly on the workflow card. Both actions auto-resume the
+workflow from the paused gate — no follow-up message required.
+
+**Reject with reason**: the Reject dialog includes an optional free-text
+reason field. The trimmed value (empty after trim → omitted) is passed to
+the workflow as `$REJECTION_REASON`, available in the `on_reject.prompt`.
+Rejects on web and chat cards use the same confirmation dialog.
+
+**Cross-platform caveat**: auto-resume via the Web UI only applies when the
+run was originally dispatched from the Web UI (parent conversation is a web
+conversation). If you approve a Slack / Telegram / GitHub-dispatched run
+from the dashboard, the decision is recorded, but the resume flow has to
+happen in the originating platform (re-run the workflow there).
 
 ### REST API
 
diff --git a/packages/docs-web/src/content/docs/guides/authoring-commands.md b/packages/docs-web/src/content/docs/guides/authoring-commands.md
index b3755d352a..849952c0d3 100644
--- a/packages/docs-web/src/content/docs/guides/authoring-commands.md
+++ b/packages/docs-web/src/content/docs/guides/authoring-commands.md
@@ -100,7 +100,7 @@ The artifact must contain **everything the next agent needs**:
 **Bad artifact**: "Fix the authentication bug in the login handler"
 
 **Good artifact**:
-```markdown
+````markdown
 ## Problem
 Users get 401 errors when token refresh races with API calls.
 
@@ -144,7 +144,7 @@ describe('refresh', () => {
 bun run type-check
 bun test src/auth/
 ```
-```
+````
 
 ---
 
diff --git a/packages/docs-web/src/content/docs/guides/authoring-workflows.md b/packages/docs-web/src/content/docs/guides/authoring-workflows.md
index 6481aefac7..0fbc282640 100644
--- a/packages/docs-web/src/content/docs/guides/authoring-workflows.md
+++ b/packages/docs-web/src/content/docs/guides/authoring-workflows.md
@@ -59,7 +59,7 @@ Workflows live in `.archon/workflows/` relative to the working directory:
 
 Archon discovers workflows recursively - subdirectories are fine. If a workflow file fails to load (syntax error, validation failure), it's skipped and the error is reported via `/workflow list`.
 
-> **Global workflows:** For workflows that apply to every project, place them in `~/.archon/.archon/workflows/`. Global workflows are overridden by same-named repo workflows. See [Global Workflows](/guides/global-workflows/).
+> **Global workflows:** For workflows that apply to every project, place them in `~/.archon/workflows/`. Global workflows are overridden by same-named repo workflows. See [Global Workflows](/guides/global-workflows/).
 
 > **CLI vs Server:** The CLI reads workflow files from wherever you run it (sees uncommitted changes). The server reads from the workspace clone at `~/.archon/workspaces/owner/repo/`, which only syncs from the remote before worktree creation. If you edit a workflow locally but don't push, the server won't see it.
 
@@ -120,12 +120,18 @@ model: sonnet
 modelReasoningEffort: medium     # Codex only
 webSearchMode: live              # Codex only
 interactive: true                # Web only: run in foreground instead of background
+worktree:                        # Optional: pin isolation behavior regardless of caller
+  enabled: false                 #   false = always run in the live checkout (CLI --no-worktree
+                                 #           and web both honor it). Use for read-only workflows
+                                 #           like triage/reporting. true = must use a worktree;
+                                 #           CLI --no-worktree hard-errors. Omit to let the
+                                 #           caller decide (current default = worktree).
 
 # Required for DAG-based
 nodes:
   - id: classify                 # Unique node ID (used for dependency refs and $id.output)
     command: classify-issue      # Loads from .archon/commands/classify-issue.md
-    output_format:               # Optional: enforce structured JSON output (Claude + Codex)
+    output_format:               # Optional: structured JSON output. SDK-enforced on Claude/Codex; best-effort (prompt + JSON extraction) on Pi.
       type: object
       properties:
         type:
@@ -188,14 +194,15 @@ nodes:
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `provider` | `'claude'` \| `'codex'` | inherited | Per-node provider override |
+| `provider` | string | inherited | Per-node provider override (any registered provider, e.g. `'claude'`, `'codex'`) |
 | `model` | string | inherited | Per-node model override |
-| `output_format` | object | — | JSON Schema for structured output (Claude and Codex) |
+| `output_format` | object | — | JSON Schema for structured output. SDK-enforced on Claude and Codex; best-effort on Pi (schema appended to prompt, JSON extracted from result text) |
 | `allowed_tools` | string[] | — | Whitelist of built-in tools. `[]` = no tools. Claude only |
 | `denied_tools` | string[] | — | Tools to remove. Applied after `allowed_tools`. Claude only |
 | `hooks` | object | — | Per-node SDK hook callbacks. Claude only. See [Hooks](/guides/hooks/) |
 | `mcp` | string | — | Path to MCP server config JSON file. Claude only. See [MCP Servers](/guides/mcp-servers/) |
 | `skills` | string[] | — | Skills to preload. Claude only. See [Skills](/guides/skills/) |
+| `agents` | object | — | Inline sub-agent definitions keyed by kebab-case ID. Claude only. See [Inline sub-agents](#inline-sub-agents) |
 | `effort` | `'low'`\|`'medium'`\|`'high'`\|`'max'` | — | Reasoning depth. Claude only. Also settable at workflow level |
 | `thinking` | string \| object | — | Thinking mode: `'adaptive'`, `'disabled'`, or `{type:'enabled', budgetTokens:N}`. Claude only. Also settable at workflow level |
 | `maxBudgetUsd` | number | — | USD cost cap; node fails if exceeded. Claude only. Per-node only |
@@ -404,6 +411,43 @@ nodes:
 - `undefined` (field absent) and `[]` have different semantics — absent means use default tool set, `[]` means no tools
 - Claude only — Codex nodes/steps emit a warning and continue (Codex doesn't support per-call tool restrictions)
 
+### Inline sub-agents
+
+Define Claude sub-agents directly in the workflow YAML, without authoring `.claude/agents/*.md` files. 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.
+
+```yaml
+nodes:
+  - id: triage
+    prompt: |
+      Fetch open issues via `gh issue list ...`. For each issue, spawn the
+      brief-gen sub-agent in parallel (one message, multiple Task tool calls)
+      to produce a 2-3 sentence brief. Then cluster briefs for duplicates.
+    model: sonnet
+    allowed_tools: [Bash, Read, Write, Task]
+    agents:
+      brief-gen:
+        description: Summarises a single GitHub issue in 2-3 sentences
+        prompt: |
+          You are concise. Read the issue provided in the caller's prompt.
+          Return JSON { summary, primarySymptom, affectedArea }.
+        model: haiku
+        tools: [Bash, Read]
+```
+
+Keys:
+
+- Agent IDs must be **kebab-case** (`^[a-z0-9]+(-[a-z0-9]+)*$`)
+- Each definition requires `description` and `prompt`; `model`, `tools`, `disallowedTools`, `skills`, and `maxTurns` are optional
+- Map is merged with any SDK-level agents and with the internal `dag-node-skills` wrapper created by `skills:` — user-defined agents win on ID collision (a warning is logged when this happens)
+- Claude only. Codex and community providers that don't support inline agents emit a warning and ignore the field
+
+**When to use `agents:` vs `.claude/agents/*.md` files:**
+
+- **`agents:` (inline)** — use when the sub-agent is specific to ONE workflow's needs. Keeps the workflow self-contained in a single YAML file; travels cleanly in PRs and forks.
+- **`.claude/agents/*.md` (on-disk)** — use when the sub-agent is shared across multiple workflows OR the whole project (for example, a `triage-agent` used by several maintenance workflows). On-disk agents live outside workflow YAMLs and are picked up automatically by the Claude Agent SDK.
+
+Both sources coexist — inline agents and on-disk agents are both available to `Task(subagent_type=...)` at runtime.
+
 ---
 
 ## Retry Configuration
@@ -474,7 +518,7 @@ This means a single transient crash may trigger up to **3 SDK retries** before a
 
 ## DAG Resume on Failure
 
-When a `nodes:` (DAG) workflow fails (including due to a server restart), the next invocation automatically resumes from where it left off — no `--resume` flag required.
+When a `nodes:` (DAG) workflow fails, the next invocation automatically resumes from where it left off — no `--resume` flag required.
 
 **How it works:**
 
@@ -483,7 +527,14 @@ When a `nodes:` (DAG) workflow fails (including due to a server restart), the ne
 3. Completed nodes are skipped; only failed and not-yet-run nodes are executed.
 4. You receive a platform message like: `Resuming workflow — skipping 3 already-completed node(s).`
 
-**Server restart**: If a server restart leaves runs in `running` status, they are automatically marked as `failed` on the next startup (with `metadata.failure_reason = 'server_restart'`). The next invocation of the same workflow at the same path auto-resumes from completed nodes.
+**Crashed servers / orphaned runs**: Archon does **not** auto-fail `running` rows on server startup — that would kill workflows actively executing in another process (CLI, adapter). If a server crash leaves a row stuck as `running`, it remains visible in the dashboard (the Dashboard nav tab shows a count of running workflows). Transition it to a terminal status explicitly:
+
+- **Web UI**: click the Abandon or Cancel button on the workflow card. Abandon marks the run `cancelled` and keeps completed-node history. Cancel also terminates any in-flight subprocess.
+- **CLI**: `archon workflow abandon <run-id>` (equivalent to the dashboard Abandon button). Run IDs are listed by `archon workflow status`.
+
+Once the row reaches a terminal status, the next invocation of the same workflow at the same path auto-resumes from completed nodes via the mechanism above.
+
+> Not to be confused with `archon workflow cleanup [days]`, which **deletes** old terminal runs (`completed`/`failed`/`cancelled`) from the database for disk hygiene. It does not transition `running` rows.
 
 **Known limitation**: AI session context from prior nodes is not restored. If a downstream node relies on in-context knowledge from a prior run's session (rather than artifacts), it may need to re-read those artifacts explicitly.
 
@@ -542,7 +593,7 @@ Model and options are resolved in this order:
 
 ```yaml
 name: my-workflow
-provider: claude     # 'claude' or 'codex' (default: from config)
+provider: claude     # Any registered provider (default: from config)
 model: sonnet        # Model override (default: from config assistants.claude.model)
 ```
 
@@ -970,12 +1021,12 @@ nodes:
 When the workflow reaches `review-gate`, it pauses and notifies you. Approve or reject via:
 
 - **Natural language** (recommended): Just type your response in the conversation — the system detects the paused workflow and auto-resumes
-- **CLI**: `bun run cli workflow approve <run-id>` or `bun run cli workflow reject <run-id>`
-- **Explicit command**: `/workflow approve <run-id>` or `/workflow reject <run-id>` (records approval; send a follow-up message to resume)
-- **Web UI**: Click the Approve/Reject buttons on the dashboard card
+- **CLI**: `bun run cli workflow approve <run-id>` or `bun run cli workflow reject <run-id>` — auto-resumes
+- **Explicit command**: `/workflow approve <run-id>` or `/workflow reject <run-id>` — auto-resumes when issued in the originating conversation
+- **Web UI**: Click the Approve/Reject buttons on the dashboard card — auto-resumes for Web-UI-dispatched runs; the Reject dialog includes an optional reason field that flows to `$REJECTION_REASON`
 - **API**: `POST /api/workflows/runs/<run-id>/approve` or `/reject`
 
-After approval via natural language or CLI, the workflow auto-resumes from the next node. The user's approval comment is available as `$review-gate.output` in downstream nodes only when `capture_response: true` is set on the approval node.
+All four paths auto-resume the workflow from the next node. The user's approval comment is available as `$review-gate.output` in downstream nodes only when `capture_response: true` is set on the approval node. Cross-platform caveat: Web-UI approvals on Slack / Telegram / GitHub-dispatched runs record the decision but do not auto-resume — re-run from the originating platform to continue.
 
 Without `on_reject`: rejecting cancels the workflow.
 With `on_reject`: rejecting triggers an AI rework prompt and re-pauses for re-review.
@@ -1119,10 +1170,11 @@ Before deploying a workflow:
 10. **`hooks`** — attach SDK hook callbacks to Claude nodes for tool control and context injection
 11. **`mcp:`** — attach per-node MCP servers via JSON config (Claude only)
 12. **`skills:`** — preload skills into Claude nodes for domain expertise
-13. **`effort` / `thinking`** — control reasoning depth and thinking mode per node or workflow (Claude only)
-14. **`maxBudgetUsd`** — set a USD cost cap per node; fails with error if exceeded (Claude only)
-15. **`systemPrompt`** — override the default system prompt per node (Claude only)
-16. **`sandbox`** — OS-level filesystem/network restrictions per node or workflow (Claude only)
-17. **Loop nodes** — use `loop:` within a DAG node for iterative execution until completion signal
-18. **Defaults as templates** — browse `.archon/workflows/defaults/` for real examples to copy and modify
-19. **Test thoroughly** — each command, the artifact flow, and edge cases
+13. **`agents:`** — inline Claude sub-agent definitions invokable via the `Task` tool
+14. **`effort` / `thinking`** — control reasoning depth and thinking mode per node or workflow (Claude only)
+15. **`maxBudgetUsd`** — set a USD cost cap per node; fails with error if exceeded (Claude only)
+16. **`systemPrompt`** — override the default system prompt per node (Claude only)
+17. **`sandbox`** — OS-level filesystem/network restrictions per node or workflow (Claude only)
+18. **Loop nodes** — use `loop:` within a DAG node for iterative execution until completion signal
+19. **Defaults as templates** — browse `.archon/workflows/defaults/` for real examples to copy and modify
+20. **Test thoroughly** — each command, the artifact flow, and edge cases
diff --git a/packages/docs-web/src/content/docs/guides/global-workflows.md b/packages/docs-web/src/content/docs/guides/global-workflows.md
index 7494a90518..282881e312 100644
--- a/packages/docs-web/src/content/docs/guides/global-workflows.md
+++ b/packages/docs-web/src/content/docs/guides/global-workflows.md
@@ -1,6 +1,6 @@
 ---
-title: Global Workflows
-description: Define user-level workflows that apply to every project on your machine.
+title: Global Workflows, Commands, and Scripts
+description: Define user-level workflows, commands, and scripts that apply to every project on your machine.
 category: guides
 area: workflows
 audience: [user]
@@ -9,45 +9,62 @@ sidebar:
   order: 8
 ---
 
-Workflows placed in `~/.archon/.archon/workflows/` are loaded globally -- they appear in
-every project's `workflow list` and can be invoked from any repository.
+Workflows placed in `~/.archon/workflows/`, commands in `~/.archon/commands/`, and scripts in `~/.archon/scripts/` are loaded globally -- they appear in every project and can be invoked from any repository. Workflows and commands carry the `source: 'global'` label in the Web UI node palette; scripts resolve under the same repo-wins-over-home precedence.
 
-## Path
+## Paths
 
 ```
-~/.archon/.archon/workflows/
+~/.archon/workflows/
+~/.archon/commands/
+~/.archon/scripts/
 ```
 
 Or, if you have set `ARCHON_HOME`:
 
 ```
-$ARCHON_HOME/.archon/workflows/
+$ARCHON_HOME/workflows/
+$ARCHON_HOME/commands/
+$ARCHON_HOME/scripts/
 ```
 
-Create the directory if it does not exist:
+Create the directories if they do not exist:
 
 ```bash
-mkdir -p ~/.archon/.archon/workflows
+mkdir -p ~/.archon/workflows ~/.archon/commands ~/.archon/scripts
 ```
 
+> **Note on location.** These are direct children of `~/.archon/` -- same level as `workspaces/`, `archon.db`, and `config.yaml`. Earlier Archon versions stored global workflows at `~/.archon/.archon/workflows/`; see [Migrating from the old path](#migrating-from-the-old-path) below.
+
+## Subfolders (1 level deep)
+
+Each directory supports one level of subfolders for grouping, matching the existing `defaults/` convention. Deeper nesting is ignored silently.
+
+```
+~/.archon/workflows/
+├── my-review.yaml              # ✅ top-level file
+├── triage/                     # ✅ 1-level subfolder (grouping)
+│   └── weekly-cleanup.yaml     # ✅ resolvable as `weekly-cleanup`
+└── team/personal/too-deep.yaml # ❌ ignored — 2 levels down
+```
+
+Resolution is by **filename without extension** (for commands) or **exact filename** (for workflows), regardless of which subfolder the file lives in. Duplicate basenames within the same scope are a user error -- keep each name unique within `~/.archon/commands/` (or `<repoRoot>/.archon/commands/`), across whatever subfolders you use.
+
 ## Load Priority
 
-1. **Bundled defaults** (lowest priority)
-2. **Global workflows** -- `~/.archon/.archon/workflows/` (override bundled by filename)
-3. **Repo-specific workflows** -- `.archon/workflows/` (override global by filename)
+1. **Bundled defaults** (lowest priority) -- the `archon-*` workflows/commands embedded in the Archon binary.
+2. **Global / home-scoped** -- `~/.archon/workflows/`, `~/.archon/commands/`, `~/.archon/scripts/` (override bundled by filename).
+3. **Repo-specific** -- `<repoRoot>/.archon/workflows/`, `<repoRoot>/.archon/commands/`, `<repoRoot>/.archon/scripts/` (override global by filename).
 
-If a global workflow has the same filename as a bundled default, the global version wins. If a repo-specific workflow has the same filename as a global one, the repo-specific version wins.
+Same-named files at a higher scope win. A repo can override a personal helper by dropping a file with the same name in its own `.archon/workflows/`, `.archon/commands/`, or `.archon/scripts/`.
 
 ## Practical Examples
 
-Global workflows are useful for personal standards that you want enforced everywhere, regardless of the project.
-
 ### Personal Code Review
 
 A workflow that runs your preferred review checklist on every project:
 
 ```yaml
-# ~/.archon/.archon/workflows/my-review.yaml
+# ~/.archon/workflows/my-review.yaml
 name: my-review
 description: Personal code review with my standards
 model: sonnet
@@ -65,7 +82,7 @@ nodes:
 A workflow that runs project-agnostic checks:
 
 ```yaml
-# ~/.archon/.archon/workflows/lint-check.yaml
+# ~/.archon/workflows/lint-check.yaml
 name: lint-check
 description: Check for common code quality issues across any project
 
@@ -84,7 +101,7 @@ nodes:
 A simple workflow for understanding unfamiliar codebases:
 
 ```yaml
-# ~/.archon/.archon/workflows/explain.yaml
+# ~/.archon/workflows/explain.yaml
 name: explain
 description: Quick explanation of a codebase or module
 model: haiku
@@ -98,38 +115,64 @@ nodes:
       Topic: $ARGUMENTS
 ```
 
+### Personal Command Helpers
+
+Commands placed in `~/.archon/commands/` are available to every workflow on the machine. Useful for prompts you reuse across projects.
+
+```markdown
+<!-- ~/.archon/commands/review-checklist.md -->
+Review the uncommitted changes in the current worktree.
+Check for:
+- Error handling gaps
+- Missing tests
+- Surprising API shapes
+- Unnecessary cleverness
+Be terse. Report findings grouped by file.
+```
+
+A workflow in any repo can then reference it:
+
+```yaml
+nodes:
+  - id: review
+    command: review-checklist
+```
+
 ## Syncing with Dotfiles
 
-If you manage your configuration with a dotfiles repository, you can include your global workflows:
+If you manage your configuration with a dotfiles repository, you can include your global content:
 
 ```bash
 # In your dotfiles repo
 dotfiles/
 └── archon/
-    └── .archon/
-        └── workflows/
-            ├── my-review.yaml
-            └── explain.yaml
+    ├── workflows/
+    │   ├── my-review.yaml
+    │   └── explain.yaml
+    └── commands/
+        └── review-checklist.md
 ```
 
 Then symlink during dotfiles setup:
 
 ```bash
-ln -sf ~/dotfiles/archon/.archon/workflows ~/.archon/.archon/workflows
+ln -sf ~/dotfiles/archon/workflows ~/.archon/workflows
+ln -sf ~/dotfiles/archon/commands  ~/.archon/commands
 ```
 
 Or copy them as part of your dotfiles install script:
 
 ```bash
-mkdir -p ~/.archon/.archon/workflows
-cp ~/dotfiles/archon/.archon/workflows/*.yaml ~/.archon/.archon/workflows/
+mkdir -p ~/.archon/workflows ~/.archon/commands
+cp ~/dotfiles/archon/workflows/*.yaml ~/.archon/workflows/
+cp ~/dotfiles/archon/commands/*.md    ~/.archon/commands/
 ```
 
-This way your personal workflows travel with you across machines.
+This way your personal workflows and commands travel with you across machines.
 
-## CLI Support
+## CLI and Web Support
 
-Both the CLI and the server discover global workflows automatically:
+Both the CLI, the server, and the Web UI discover home-scoped content automatically -- no flag, no config option.
 
 ```bash
 # Lists bundled + global + repo-specific workflows
@@ -139,14 +182,26 @@ archon workflow list
 archon workflow run my-review
 ```
 
+In the Web UI workflow builder, commands from `~/.archon/commands/` appear under a **Global (~/.archon/commands/)** section in the node palette, distinct from project and bundled entries.
+
+## Migrating from the old path
+
+Pre-refactor versions of Archon stored global workflows at `~/.archon/.archon/workflows/` (with an extra nested `.archon/`). That location is no longer read. If you have workflows there, Archon emits a one-time deprecation warning on first use telling you the exact migration command:
+
+```bash
+mv ~/.archon/.archon/workflows ~/.archon/workflows && rmdir ~/.archon/.archon
+```
+
+Run it once; the warning stops firing on subsequent invocations. There was no prior home-scoped commands location, so `~/.archon/commands/` is new capability -- nothing to migrate.
+
 ## Troubleshooting
 
 ### Workflow Not Appearing in List
 
-1. **Check the path** -- The directory must be exactly `~/.archon/.archon/workflows/` (note the double `.archon`). The first `.archon` is the Archon home directory, the second is the standard config directory structure within it.
+1. **Check the path** -- The directory must be exactly `~/.archon/workflows/` (a direct child of `~/.archon/`, not the old double-nested `~/.archon/.archon/workflows/`).
 
    ```bash
-   ls ~/.archon/.archon/workflows/
+   ls ~/.archon/workflows/
    ```
 
 2. **Check file extension** -- Workflow files must end in `.yaml` or `.yml`.
@@ -159,4 +214,4 @@ archon workflow run my-review
 
 4. **Check for name conflicts** -- If a repo-specific workflow has the same filename, it overrides the global one. The global version will not appear when you are in that repo.
 
-5. **Check ARCHON_HOME** -- If you have set `ARCHON_HOME` to a custom path, global workflows must be at `$ARCHON_HOME/.archon/workflows/`, not `~/.archon/.archon/workflows/`.
+5. **Check ARCHON_HOME** -- If you have set `ARCHON_HOME` to a custom path, global workflows must be at `$ARCHON_HOME/workflows/`, not `~/.archon/workflows/`.
diff --git a/packages/docs-web/src/content/docs/guides/mcp-servers.md b/packages/docs-web/src/content/docs/guides/mcp-servers.md
index 41f7f331cf..46474477e2 100644
--- a/packages/docs-web/src/content/docs/guides/mcp-servers.md
+++ b/packages/docs-web/src/content/docs/guides/mcp-servers.md
@@ -194,8 +194,9 @@ and cannot touch the filesystem or run shell commands.
 
 ## Connection Failure Handling
 
-MCP server connections are established when the node starts executing. If a server
-fails to connect, you'll see a message like:
+MCP server connections are established when the node starts executing. If a
+server the **workflow** configured via `mcp:` fails to connect, you'll see a
+message like:
 
 ```
 MCP server connection failed: github (failed)
@@ -204,6 +205,13 @@ MCP server connection failed: github (failed)
 The node continues executing but without the tools from the failed server.
 Check your config file path, server command, and environment variables if this happens.
 
+User-level Claude plugin MCPs inherited from `~/.claude/` (e.g. `telegram`,
+`notion`) routinely fail to connect inside the headless workflow subprocess
+and are **not** surfaced here — they're not actionable for the workflow author.
+They appear only in debug logs as `dag.mcp_plugin_connection_suppressed`. Run
+the CLI with `--verbose` (or set `LOG_LEVEL=debug` on the server) if you need
+to see them.
+
 ## Workflow Examples
 
 ### GitHub Issue Triage
@@ -378,6 +386,7 @@ bun run cli workflow run archon-smart-pr-review "Review PR #123"
 | `MCP config must be a JSON object` | Top-level value is array or string | Wrap in `{ "server-name": { ... } }` |
 | `undefined env vars: VAR_NAME` | Environment variable not set | Export the variable or add it to your `.env` |
 | `MCP server connection failed` | Server process crashed or URL unreachable | Check command/URL, test the server standalone |
+| Plugin MCP missing from workflow output | User-level plugin MCPs (from `~/.claude/`) are filtered out of workflow warnings | Run with `--verbose` and look for `dag.mcp_plugin_connection_suppressed` |
 | `mcp config but uses Codex` | Node resolved to Codex provider | Set `provider: claude` on the node or switch default |
 | `Haiku model with MCP servers` | Haiku doesn't support tool search | Use `model: sonnet` or `model: opus` instead |
 
diff --git a/packages/docs-web/src/content/docs/guides/skills.md b/packages/docs-web/src/content/docs/guides/skills.md
index 02f2fa0a74..d27262ffac 100644
--- a/packages/docs-web/src/content/docs/guides/skills.md
+++ b/packages/docs-web/src/content/docs/guides/skills.md
@@ -124,7 +124,7 @@ Step-by-step content here. The agent loads this when the skill activates.
 ## Skill Discovery
 
 Skills are discovered from these locations (via `settingSources: ['project']`
-set in ClaudeClient):
+set in ClaudeProvider):
 
 | Location | Scope |
 |----------|-------|
@@ -235,6 +235,7 @@ To use skills, ensure the node uses Claude (the default provider, or set
 
 ## Related
 
+- [Inline sub-agents](/guides/authoring-workflows/#inline-sub-agents) — `agents:` field for workflow-scoped sub-agents (composes with `skills:` on the same node; user-defined agents win on ID collision with the internal `dag-node-skills` wrapper)
 - [Per-Node MCP Servers](/guides/mcp-servers/) — `mcp:` field for external tool access
 - [Hooks](/guides/hooks/) — `hooks:` field for tool permission control
 - [skills.sh](https://skills.sh) — marketplace for discovering skills
diff --git a/packages/docs-web/src/content/docs/reference/api.md b/packages/docs-web/src/content/docs/reference/api.md
index 0e2fa8aa37..511355e091 100644
--- a/packages/docs-web/src/content/docs/reference/api.md
+++ b/packages/docs-web/src/content/docs/reference/api.md
@@ -138,7 +138,6 @@ Performs a soft delete -- the conversation is hidden but not destroyed.
 | GET | `/api/codebases` | List registered codebases |
 | GET | `/api/codebases/{id}` | Get a single codebase |
 | POST | `/api/codebases` | Register a codebase (clone or local path) |
-| PATCH | `/api/codebases/{id}` | Update env-key consent (`allowEnvKeys`) |
 | DELETE | `/api/codebases/{id}` | Delete a codebase and clean up resources |
 | GET | `/api/codebases/{id}/environments` | List isolation environments for a codebase |
 
@@ -166,16 +165,6 @@ curl -X POST http://localhost:3090/api/codebases \
   -d '{"path": "/home/user/projects/my-repo"}'
 ```
 
-### Update Env-Key Consent
-
-Flip the env-leak-gate consent bit (`allow_env_keys`) on an existing codebase. Audit-logged on every grant and revoke as `env_leak_consent_granted` / `env_leak_consent_revoked` (warn-level) including `codebaseId`, `path`, scanned `files`, matched `keys`, `scanStatus`, and `actor`.
-
-```bash
-curl -X PATCH http://localhost:3090/api/codebases/{id} \
-  -H "Content-Type: application/json" \
-  -d '{"allowEnvKeys": true}'
-```
-
 ### Delete a Codebase
 
 ```bash
diff --git a/packages/docs-web/src/content/docs/reference/architecture.md b/packages/docs-web/src/content/docs/reference/architecture.md
index 4f5c16c01e..be3dd7639e 100644
--- a/packages/docs-web/src/content/docs/reference/architecture.md
+++ b/packages/docs-web/src/content/docs/reference/architecture.md
@@ -10,7 +10,7 @@ sidebar:
 
 Comprehensive guide to understanding and extending Archon.
 
-**Navigation:** [Overview](#system-overview) | [Platforms](#adding-platform-adapters) | [AI Assistants](#adding-ai-assistant-clients) | [Isolation](#isolation-providers) | [Commands](#command-system) | [Streaming](#streaming-modes) | [Database](#database-schema)
+**Navigation:** [Overview](#system-overview) | [Platforms](#adding-platform-adapters) | [AI Providers](#adding-ai-agent-providers) | [Isolation](#isolation-providers) | [Commands](#command-system) | [Streaming](#streaming-modes) | [Database](#database-schema)
 
 ---
 
@@ -43,11 +43,11 @@ Archon is a **platform-agnostic AI coding assistant orchestrator** that connects
        │       │        │
        ▼       ▼        ▼
 ┌───────────┐ ┌───────────────┐ ┌───────────────────┐
-│ Command   │ │ AI Assistant  │ │ Isolation         │
-│ Handler   │ │ Clients       │ │ Providers         │
+│ Command   │ │ AI Agent      │ │ Isolation         │
+│ Handler   │ │ Providers     │ │ Providers         │
 │           │ │               │ │                   │
-│ (Slash    │ │ IAssistant-   │ │ IIsolationProvider│
-│ commands) │ │ Client        │ │ (worktree, etc.)  │
+│ (Slash    │ │ IAgent-       │ │ IIsolationProvider│
+│ commands) │ │ Provider      │ │ (worktree, etc.)  │
 └─────┬─────┘ └───────┬───────┘ └─────────┬─────────┘
       │               │                   │
       └───────────────┼───────────────────┘
@@ -62,7 +62,7 @@ Archon is a **platform-agnostic AI coding assistant orchestrator** that connects
 
 ### Key Design Principles
 
-1. **Interface-driven**: Both platform adapters and AI clients implement strict interfaces for swappability
+1. **Interface-driven**: Both platform adapters and AI providers implement strict interfaces for swappability
 2. **Streaming-first**: All AI responses stream through async generators for real-time delivery
 3. **Session persistence**: AI sessions survive container restarts via database storage
 4. **Generic commands**: Users define commands in Git-versioned markdown files, not hardcoded
@@ -296,64 +296,81 @@ async handleWebhook(payload: any, signature: string): Promise<void> {
 
 ---
 
-## Adding AI Assistant Clients
+## Adding AI Agent Providers
 
-AI assistant clients wrap AI SDKs and provide a unified streaming interface. Implement the `IAssistantClient` interface to add new assistants.
+AI agent providers wrap AI SDKs and provide a unified streaming interface. Implement the `IAgentProvider` interface to add new providers.
 
-### IAssistantClient Interface
+> **Note:** This section covers built-in providers maintained by the core team (Claude, Codex). For community providers (`builtIn: false`) — which live under `packages/providers/src/community/` and register through `registerCommunityProviders()` — see [Adding a Community Provider](../contributing/adding-a-community-provider/).
 
-**Location:** `packages/core/src/types/index.ts`
+### IAgentProvider Interface
+
+**Location:** `packages/providers/src/types.ts` (contract layer — zero SDK deps)
 
 ```typescript
-export interface IAssistantClient {
-  // Send a query and get streaming response
-  sendQuery(prompt: string, cwd: string, resumeSessionId?: string): AsyncGenerator<MessageChunk>;
+export interface IAgentProvider {
+  sendQuery(
+    prompt: string,
+    cwd: string,
+    resumeSessionId?: string,
+    options?: SendQueryOptions
+  ): AsyncGenerator<MessageChunk>;
 
-  // Get the assistant type identifier
   getType(): string;
+
+  getCapabilities(): ProviderCapabilities;
 }
 ```
 
 ### MessageChunk Types
 
+`MessageChunk` is a discriminated union. Only the fields for each variant are present:
+
 ```typescript
-interface MessageChunk {
-  type: 'assistant' | 'result' | 'system' | 'tool' | 'thinking';
-  content?: string; // Text content for assistant/system/thinking
-  sessionId?: string; // Session ID for result type
-  toolName?: string; // Tool name for tool type
-  toolInput?: Record<string, unknown>; // Tool parameters
-}
+export type MessageChunk =
+  | { type: 'assistant'; content: string }
+  | { type: 'system'; content: string }
+  | { type: 'thinking'; content: string }
+  | {
+      type: 'result';
+      sessionId?: string;
+      tokens?: TokenUsage;
+      structuredOutput?: unknown;
+      isError?: boolean;
+      errorSubtype?: string;
+      cost?: number;
+      stopReason?: string;
+      numTurns?: number;
+      modelUsage?: Record<string, unknown>;
+    }
+  | { type: 'rate_limit'; rateLimitInfo: Record<string, unknown> }
+  | { type: 'tool'; toolName: string; toolInput?: Record<string, unknown>; toolCallId?: string }
+  | { type: 'tool_result'; toolName: string; toolOutput: string; toolCallId?: string }
+  | { type: 'workflow_dispatch'; workerConversationId: string; workflowName: string };
 ```
 
 ### Implementation Guide
 
-**1. Create client file:** `packages/core/src/clients/your-assistant.ts`
+**1. Create provider file:** `packages/providers/src/your-assistant/provider.ts`
 
 **2. Implement the interface:**
 
 ```typescript
-import { IAssistantClient, MessageChunk } from '../types';
+import type { IAgentProvider, MessageChunk, ProviderCapabilities, SendQueryOptions } from '../types';
 
-export class YourAssistantClient implements IAssistantClient {
+export class YourAssistantProvider implements IAgentProvider {
   async *sendQuery(
     prompt: string,
     cwd: string,
-    resumeSessionId?: string
+    resumeSessionId?: string,
+    options?: SendQueryOptions,
   ): AsyncGenerator<MessageChunk> {
     // Initialize or resume session
-    let session;
-    if (resumeSessionId) {
-      log.info({ sessionId: resumeSessionId }, 'session_resumed');
-      session = await this.resumeSession(resumeSessionId);
-    } else {
-      log.info({ cwd }, 'session_started');
-      session = await this.startSession(cwd);
-    }
+    const session = resumeSessionId
+      ? await this.resumeSession(resumeSessionId)
+      : await this.startSession(cwd);
 
     // Send query to AI and stream responses
     for await (const event of this.sdk.streamQuery(session, prompt)) {
-      // Map SDK events to MessageChunk types
       if (event.type === 'text_response') {
         yield { type: 'assistant', content: event.text };
       } else if (event.type === 'tool_call') {
@@ -361,6 +378,7 @@ export class YourAssistantClient implements IAssistantClient {
           type: 'tool',
           toolName: event.tool,
           toolInput: event.parameters,
+          toolCallId: event.id,
         };
       } else if (event.type === 'thinking') {
         yield { type: 'thinking', content: event.reasoning };
@@ -374,28 +392,41 @@ export class YourAssistantClient implements IAssistantClient {
   getType(): string {
     return 'your-assistant';
   }
+
+  getCapabilities(): ProviderCapabilities {
+    // Declare only what you've actually wired. Under-declaration is honest;
+    // the dag-executor warns users if a workflow node uses a feature you
+    // declared unsupported.
+    return YOUR_ASSISTANT_CAPABILITIES;
+  }
 }
 ```
 
-**3. Register in factory:** `packages/core/src/clients/factory.ts`
+**3. Register via the typed registry:** `packages/providers/src/registry.ts`
 
-```typescript
-import { YourAssistantClient } from './your-assistant';
+Built-in providers are registered by `registerBuiltinProviders()`:
 
-export function getAssistantClient(type: string): IAssistantClient {
-  switch (type) {
-    case 'claude':
-      return new ClaudeClient();
-    case 'codex':
-      return new CodexClient();
-    case 'your-assistant':
-      return new YourAssistantClient();
-    default:
-      throw new Error(`Unknown assistant type: ${type}`);
+```typescript
+export function registerBuiltinProviders(): void {
+  const builtins: ProviderRegistration[] = [
+    {
+      id: 'your-assistant',
+      displayName: 'Your Assistant',
+      factory: () => new YourAssistantProvider(),
+      capabilities: YOUR_ASSISTANT_CAPABILITIES,
+      isModelCompatible: (model) => /* pattern check */,
+      builtIn: true,
+    },
+    // ...existing entries
+  ];
+  for (const entry of builtins) {
+    if (!registry.has(entry.id)) registry.set(entry.id, entry);
   }
 }
 ```
 
+Community providers use `registerCommunityProviders()` (same file). See the [community provider guide](../contributing/adding-a-community-provider/) for that path.
+
 **4. Add environment variables:** `.env.example`
 
 ```ini
@@ -440,7 +471,7 @@ if (trigger && shouldCreateNewSession(trigger)) {
 
 Different SDKs use different event types. Map them to MessageChunk types:
 
-**Claude Code SDK** (`packages/core/src/clients/claude.ts`):
+**Claude Code SDK** (`packages/providers/src/claude/provider.ts`):
 
 ```typescript
 for await (const msg of query({ prompt, options })) {
@@ -462,7 +493,7 @@ for await (const msg of query({ prompt, options })) {
 }
 ```
 
-**Codex SDK** (`packages/core/src/clients/codex.ts`):
+**Codex SDK** (`packages/providers/src/codex/provider.ts`):
 
 ```typescript
 for await (const event of result.events) {
@@ -1003,7 +1034,7 @@ remote_agent_codebases
 ├── name (VARCHAR)
 ├── repository_url (VARCHAR)
 ├── default_cwd (VARCHAR)
-├── ai_assistant_type (VARCHAR) -- 'claude' | 'codex'
+├── ai_assistant_type (VARCHAR) -- registered provider identifier (e.g. 'claude', 'codex')
 └── commands (JSONB) -- {command_name: {path, description}}
 
 remote_agent_conversations
@@ -1180,7 +1211,7 @@ Variable substitution (no args in this case)
          |
 Get or create session
          |
-ClaudeClient.sendQuery(prompt, cwd, sessionId)
+ClaudeProvider.sendQuery(prompt, cwd, sessionId)
          |
 Stream mode: Send each chunk immediately
          |
@@ -1212,7 +1243,7 @@ Load command file, substitute variables
          |
 Get or create session
          |
-CodexClient.sendQuery(prompt, cwd, sessionId)
+CodexProvider.sendQuery(prompt, cwd, sessionId)
          |
 Batch mode: Accumulate all chunks
          |
@@ -1236,14 +1267,17 @@ Post single comment on issue with summary
 - [ ] Add environment variables to `.env.example`
 - [ ] Test with both stream and batch modes
 
-### Adding a New AI Assistant Client
+### Adding a New AI Agent Provider
+
+This checklist is for **built-in** providers only. For community providers (`builtIn: false`), see [Adding a Community Provider](../contributing/adding-a-community-provider/) — the folder layout, registration, and capability discipline are covered there in depth.
 
-- [ ] Create `packages/core/src/clients/your-assistant.ts`
-- [ ] Implement `IAssistantClient` interface
-- [ ] Map SDK events to `MessageChunk` types
+- [ ] Create `packages/providers/src/your-assistant/provider.ts`
+- [ ] Implement `IAgentProvider` interface (sendQuery + getType + getCapabilities)
+- [ ] Map SDK events to `MessageChunk` discriminated union
 - [ ] Handle session creation and resumption
-- [ ] Implement error handling and recovery
-- [ ] Add to `packages/core/src/clients/factory.ts`
+- [ ] Declare `ProviderCapabilities` honestly — under-declare rather than over-promise
+- [ ] Implement error handling and retry classification (see Claude/Codex patterns)
+- [ ] Register in `registerBuiltinProviders()` at `packages/providers/src/registry.ts`
 - [ ] Add environment variables to `.env.example`
 - [ ] Test session persistence across restarts
 - [ ] Test plan-to-execute transition (new session)
@@ -1341,9 +1375,9 @@ Context is passed as a dedicated `issueContext` parameter to `handleMessage()`,
 
 ## Key Takeaways
 
-1. **Interfaces enable extensibility**: `IPlatformAdapter`, `IAssistantClient`, and `IIsolationProvider` allow adding platforms, AI assistants, and isolation strategies without modifying core logic
+1. **Interfaces enable extensibility**: `IPlatformAdapter`, `IAgentProvider`, and `IIsolationProvider` allow adding platforms, AI providers, and isolation strategies without modifying core logic
 
-2. **Async generators for streaming**: All AI clients return `AsyncGenerator<MessageChunk>` for unified streaming across different SDKs
+2. **Async generators for streaming**: All AI providers return `AsyncGenerator<MessageChunk>` for unified streaming across different SDKs
 
 3. **Session persistence is critical**: Store `assistant_session_id` in database to maintain context across restarts
 
@@ -1353,7 +1387,7 @@ Context is passed as a dedicated `issueContext` parameter to `handleMessage()`,
 
 6. **Plan-to-execute is special**: Only transition requiring new session (prevents token bloat during implementation)
 
-7. **Factory pattern**: `getAssistantClient()` and `getIsolationProvider()` instantiate correct implementations based on configuration
+7. **Factory pattern**: `getAgentProvider()` and `getIsolationProvider()` instantiate correct implementations based on configuration
 
 8. **Error recovery**: Always provide `/reset` escape hatch for users when sessions get stuck
 
@@ -1364,7 +1398,7 @@ Context is passed as a dedicated `issueContext` parameter to `handleMessage()`,
 **For detailed implementation examples, see:**
 
 - Platform adapter: `packages/adapters/src/chat/telegram/adapter.ts`, `packages/adapters/src/forge/github/adapter.ts`
-- AI client: `packages/core/src/clients/claude.ts`, `packages/core/src/clients/codex.ts`
+- AI provider: `packages/providers/src/claude/provider.ts`, `packages/providers/src/codex/provider.ts`
 - Isolation provider: `packages/isolation/src/providers/worktree.ts`
 - Isolation resolver: `packages/isolation/src/resolver.ts`
 - Isolation factory: `packages/isolation/src/factory.ts`
diff --git a/packages/docs-web/src/content/docs/reference/archon-directories.md b/packages/docs-web/src/content/docs/reference/archon-directories.md
index a718824c3a..b0b04f5df2 100644
--- a/packages/docs-web/src/content/docs/reference/archon-directories.md
+++ b/packages/docs-web/src/content/docs/reference/archon-directories.md
@@ -51,12 +51,16 @@ any-repo/.archon/
 │   └── execute.md
 ├── workflows/                # Workflow definitions (YAML files)
 │   └── pr-review.yaml
+├── scripts/                  # Named scripts for script: nodes (.ts/.js for bun, .py for uv)
+├── state/                    # Cross-run workflow state (gitignored)
 └── config.yaml               # Repo-specific configuration
 ```
 
 **Purpose:**
 - `commands/` - Slash commands (auto-loaded on clone)
 - `workflows/` - YAML workflow definitions, discovered recursively at runtime
+- `scripts/` - Named scripts referenced by `script:` nodes
+- `state/` - Cross-run memory written by workflows (e.g. `repo-triage` dedup state). Gitignored; never committed.
 - `config.yaml` - Project-specific settings
 
 ### Docker: `/.archon/`
diff --git a/packages/docs-web/src/content/docs/reference/cli.md b/packages/docs-web/src/content/docs/reference/cli.md
index 33f6436884..adf0471c01 100644
--- a/packages/docs-web/src/content/docs/reference/cli.md
+++ b/packages/docs-web/src/content/docs/reference/cli.md
@@ -67,15 +67,22 @@ archon chat "What does the orchestrator do?"
 Interactive setup wizard for credentials and configuration.
 
 ```bash
-archon setup
-archon setup --spawn  # Open in a new terminal window
+archon setup                      # writes ~/.archon/.env (home scope, default)
+archon setup --scope project      # writes <cwd>/.archon/.env instead
+archon setup --force              # overwrite instead of merging (backup still written)
+archon setup --spawn              # open in a new terminal window
 ```
 
 **Flags:**
 
 | Flag | Effect |
 |------|--------|
-| `--spawn` | Open setup wizard in a new terminal window |
+| `--scope home` | Write to `~/.archon/.env` (default). Applies to every project. |
+| `--scope project` | Write to `<cwd>/.archon/.env`. Overrides user scope for this repo only. |
+| `--force` | Overwrite the target file wholesale instead of merging. A timestamped backup is still written. |
+| `--spawn` | Open setup wizard in a new terminal window. |
+
+**Write safety**: `archon setup` never writes to `<cwd>/.env` — that file belongs to you. The wizard always targets one archon-owned file chosen by `--scope`, merges into existing content (so user-added keys survive), and writes a timestamped backup before every rewrite (e.g. `~/.archon/.env.archon-backup-2026-04-20T09-28-11-000Z`).
 
 ### `workflow list`
 
@@ -88,7 +95,7 @@ archon workflow list --cwd /path/to/repo
 archon workflow list --cwd /path/to/repo --json
 ```
 
-Discovers workflows from `.archon/workflows/` (recursive), `~/.archon/.archon/workflows/` (global), and bundled defaults. See [Global Workflows](/guides/global-workflows/).
+Discovers workflows from `.archon/workflows/` (recursive), `~/.archon/workflows/` (global, home-scoped), and bundled defaults. See [Global Workflows](/guides/global-workflows/).
 
 **Flags:**
 
@@ -122,7 +129,6 @@ Progress events (node start/complete/fail/skip, approval gates) are written to s
 | `--from <branch>`, `--from-branch <branch>` | Override base branch (start-point for worktree) |
 | `--no-worktree` | Opt out of isolation -- run directly in live checkout |
 | `--resume` | Resume from last failed run at the working path (skips completed nodes) |
-| `--allow-env-keys` | Grant env-leak-gate consent during auto-registration (bypasses the gate for this codebase). Audit-logged as `env_leak_consent_granted` with `actor: 'user-cli'`. See [security.md](/reference/security/#env-leak-gate-target-repo-env-keys). |
 | `--quiet`, `-q` | Suppress all progress output to stderr |
 | `--verbose`, `-v` | Also show tool-level events (tool name and duration) |
 
@@ -172,7 +178,7 @@ archon workflow resume <run-id>
 
 ### `workflow abandon`
 
-Discard a workflow run (marks it as failed). Use this to unblock a worktree when you don't want to resume.
+Discard a workflow run (marks it as `cancelled`). Use this to unblock a worktree when you don't want to resume — the path lock is released immediately so a new workflow can start.
 
 ```bash
 archon workflow abandon <run-id>
@@ -362,12 +368,15 @@ When using `--branch`, workflows run inside the worktree directory.
 
 ## Environment
 
-At startup, the CLI strips all Bun-auto-loaded CWD `.env` keys and nested Claude Code session markers from `process.env`, then loads `~/.archon/.env` as the sole trusted source. All keys you set in `~/.archon/.env` pass through to AI subprocesses — no allowlist filtering.
+At startup, the CLI strips all Bun-auto-loaded CWD `.env` keys and nested Claude Code session markers from `process.env`, then loads two archon-owned env files with `override: true`. Keys in archon-owned files pass through to AI subprocesses — no allowlist filtering.
 
 On startup, the CLI:
-1. Strips CWD `.env` keys + `CLAUDECODE` markers from `process.env` (via `stripCwdEnv`)
-2. Loads `~/.archon/.env` (all keys trusted)
-3. Auto-enables global Claude auth if no explicit tokens are set
+1. Strips `<cwd>/.env*` keys + `CLAUDECODE` markers from `process.env` (via `stripCwdEnv`). Emits `[archon] stripped N keys from <cwd> (...)` when N > 0.
+2. Loads `~/.archon/.env` (user scope). Emits `[archon] loaded N keys from ~/.archon/.env` when N > 0.
+3. Loads `<cwd>/.archon/.env` (project scope, overrides user scope). Emits `[archon] loaded N keys from <path> (repo scope, overrides user scope)` when N > 0.
+4. Auto-enables global Claude auth if no explicit tokens are set.
+
+`<cwd>/.env` is never loaded — it belongs to the target project. See [Configuration Reference: `.env` File Locations](/reference/configuration/#env-file-locations) for the full three-path model.
 
 ## Database
 
diff --git a/packages/docs-web/src/content/docs/reference/configuration.md b/packages/docs-web/src/content/docs/reference/configuration.md
index c126b968f1..d312c734a2 100644
--- a/packages/docs-web/src/content/docs/reference/configuration.md
+++ b/packages/docs-web/src/content/docs/reference/configuration.md
@@ -22,10 +22,15 @@ Archon supports a layered configuration system with sensible defaults, optional
 │   ├── worktrees/          # Git worktrees for this project
 │   ├── artifacts/          # Workflow artifacts
 │   └── logs/               # Workflow execution logs
+├── workflows/              # Home-scoped workflows (source: 'global')
+├── commands/               # Home-scoped commands (source: 'global')
+├── scripts/                # Home-scoped scripts (runtime: bun | uv)
 ├── archon.db               # SQLite database (when DATABASE_URL not set)
 └── config.yaml             # Global configuration (optional)
 ```
 
+Home-scoped `workflows/`, `commands/`, and `scripts/` apply to every project on the machine. Repo-local files at `<repoRoot>/.archon/{workflows,commands,scripts}/` override them by filename (or script name). Each directory supports one level of subfolders for grouping; deeper nesting is ignored. See [Global Workflows](/guides/global-workflows/) for details and dotfiles-sync examples.
+
 ### Repository-Level (.archon/)
 
 ```
@@ -51,7 +56,7 @@ Create `~/.archon/config.yaml` for user-wide preferences:
 
 ```yaml
 # Default AI assistant
-defaultAssistant: claude # or 'codex'
+defaultAssistant: claude # must match a registered provider (e.g. claude, codex)
 
 # Assistant defaults
 assistants:
@@ -60,12 +65,18 @@ assistants:
     settingSources:   # Which CLAUDE.md files the SDK loads (default: ['project'])
       - project       # Project-level CLAUDE.md (always recommended)
       - user          # Also load ~/.claude/CLAUDE.md (global preferences)
+    # Optional: absolute path to the Claude Code executable.
+    # Required in compiled Archon binaries when CLAUDE_BIN_PATH is not set.
+    # Accepts the native binary (~/.local/bin/claude from the curl installer)
+    # or the npm-installed cli.js. Source/dev mode auto-resolves.
+    # claudeBinaryPath: /absolute/path/to/claude
   codex:
     model: gpt-5.3-codex
     modelReasoningEffort: medium
     webSearchMode: disabled
     additionalDirectories:
       - /absolute/path/to/other/repo
+    # codexBinaryPath: /absolute/path/to/codex  # Optional: Codex CLI path
 
 # Streaming preferences per platform
 streaming:
@@ -83,11 +94,6 @@ paths:
 concurrency:
   maxConversations: 10
 
-# Env-leak gate bypass (last resort — weakens a security control)
-# allow_target_repo_keys: false  # Set true to skip the env-leak-gate
-                                 # globally for all codebases on this machine.
-                                 # `env_leak_gate_disabled` is logged once per
-                                 # process per source. See security.md.
 ```
 
 ## Repository Configuration
@@ -116,9 +122,17 @@ commands:
 # Worktree settings
 worktree:
   baseBranch: main  # Optional: auto-detected from git when not set
-  copyFiles:  # Optional: Additional files to copy to worktrees
-    - .env.example -> .env  # Rename during copy
+  copyFiles:  # Optional: Gitignored files/dirs to copy into new worktrees.
+              # `.archon/` is always copied automatically — don't list it.
+    - .env
     - .vscode               # Copy entire directory
+    - plans/                # Local plans not committed to the team repo
+  initSubmodules: true  # Optional: default true — auto-detects .gitmodules and runs
+                        # `git submodule update --init --recursive`. Set false to opt out.
+  path: .worktrees      # Optional: co-locate worktrees with the repo at
+                        # <repoRoot>/.worktrees/<branch> instead of under
+                        # ~/.archon/workspaces/<owner>/<repo>/worktrees/.
+                        # Must be relative; no absolute, no `..` segments.
 
 # Documentation directory
 docs:
@@ -135,11 +149,6 @@ defaults:
 #   MY_API_KEY: value
 #   CUSTOM_ENDPOINT: https://...
 
-# Per-repo override for the env-leak-gate bypass.
-# Set to `false` to re-enable the gate for THIS repo even when the global
-# config has `allow_target_repo_keys: true`. Set to `true` to grant the
-# bypass for THIS repo only. Wins over the global flag in either direction.
-# allow_target_repo_keys: false
 ```
 
 ### Claude settingSources
@@ -164,10 +173,39 @@ assistants:
 
 This is useful when you maintain coding style or identity preferences in `~/.claude/CLAUDE.md` and want Archon sessions to respect them.
 
-**Default behavior:** The `.archon/` directory is always copied to worktrees automatically (contains artifacts, plans, workflows). Use `copyFiles` only for additional files like `.env` or `.vscode`.
+### Worktree file copying (`worktree.copyFiles`)
+
+`git worktree add` only copies **tracked** files into a new worktree. Anything gitignored — secrets, local planning docs, agent reports, IDE settings, data fixtures — is absent by default. Archon's `worktree.copyFiles` closes that gap: after the worktree is created, each listed path is copied from the canonical repo into the worktree via raw filesystem copy (not git), so gitignored content comes along for the ride.
+
+**Defaults — no config needed for the common case.** `.archon/` is always copied automatically. If you gitignore `.archon/` (or it's just not committed), your custom commands, workflows, and scripts still reach every worktree. You do not need to list `.archon/` in `copyFiles` — it's merged in for you.
+
+**Common entries:**
+
+```yaml
+worktree:
+  copyFiles:
+    - .env                  # local secrets
+    - .vscode/              # editor settings
+    - .claude/              # per-repo Claude Code config (agents, skills, hooks)
+    - plans/                # working docs that aren't committed
+    - reports/              # agent-generated markdown reports
+    - data/fixtures/        # local-only test data
+```
+
+**Semantics:**
+
+- Each entry is a path (file or directory) relative to the repo root — source and destination are always identical. No rename syntax.
+- Missing files are silently skipped (`ENOENT` at debug level), so you can list "optional" entries without bookkeeping.
+- Directories are copied recursively.
+- Per-entry failures are isolated — one bad entry won't abort the rest. Non-ENOENT failures (permissions, disk full) are surfaced as warnings on the environment.
+- Path-traversal attempts (entries resolving outside the repo root, or absolute paths on a different drive) are rejected — the entry is logged and skipped.
+
+**Interaction with `worktree.path`:** The copy step runs identically whether worktrees live under `~/.archon/workspaces/<owner>/<repo>/worktrees/` (default) or inside the repo at `<repoRoot>/<worktree.path>/` (repo-local). Both layouts get the same gitignored-file treatment.
 
 **Defaults behavior:** The app's bundled default commands and workflows are loaded at runtime and merged with repo-specific ones. Repo commands/workflows override app defaults by name. Set `defaults.loadDefaultCommands: false` or `defaults.loadDefaultWorkflows: false` to disable runtime loading.
 
+**Submodule behavior:** When a repo contains `.gitmodules`, submodules are initialized in new worktrees by default (git's `worktree add` does not do this). The check is a cheap filesystem probe — repos without submodules pay zero cost. Submodule init failure throws a classified error (credentials, network, timeout) rather than silently producing a worktree with empty submodule directories. Set `worktree.initSubmodules: false` to opt out.
+
 **Base branch behavior:** Before creating a worktree, the canonical workspace is synced to the latest code. Resolution order:
 1. If `worktree.baseBranch` is set: Uses the configured branch. **Fails with an error** if the branch doesn't exist on remote (no silent fallback).
 2. If omitted: Auto-detects the default branch via `git remote show origin`. Works without any config for standard repos.
@@ -175,6 +213,8 @@ This is useful when you maintain coding style or identity preferences in `~/.cla
 
 **Docs path behavior:** The `docs.path` setting controls where the `$DOCS_DIR` variable points. When not configured, `$DOCS_DIR` defaults to `docs/`. Unlike `$BASE_BRANCH`, this variable always has a safe default and never throws an error. Configure it when your documentation lives outside the standard `docs/` directory (e.g., `packages/docs-web/src/content/docs`).
 
+**Worktree path behavior:** By default, every repo's worktrees live under `~/.archon/workspaces/<owner>/<repo>/worktrees/<branch>` — outside the repo, invisible to the IDE. Set `worktree.path` to opt in to a **repo-local** layout instead: worktrees are created at `<repoRoot>/<worktree.path>/<branch>` so they show up in the file tree and editor workspace. A common choice is `.worktrees`. Because worktrees now live inside the repository tree, you should add the directory to your `.gitignore` (Archon does not modify user-owned files). The configured path must be relative to the repo root; absolute paths and paths containing `..` segments fail loudly at worktree creation rather than silently falling back.
+
 ## Environment Variables
 
 Environment variables override all other configuration. They are organized by category below.
@@ -187,7 +227,7 @@ Environment variables override all other configuration. They are organized by ca
 | `PORT` | HTTP server listen port | `3090` (auto-allocated in worktrees) |
 | `LOG_LEVEL` | Logging verbosity (`fatal`, `error`, `warn`, `info`, `debug`, `trace`) | `info` |
 | `BOT_DISPLAY_NAME` | Bot name shown in batch-mode "starting" messages | `Archon` |
-| `DEFAULT_AI_ASSISTANT` | Default AI assistant (`claude` or `codex`) | `claude` |
+| `DEFAULT_AI_ASSISTANT` | Default AI assistant (must match a registered provider) | `claude` |
 | `MAX_CONCURRENT_CONVERSATIONS` | Maximum concurrent AI conversations | `10` |
 | `SESSION_RETENTION_DAYS` | Delete inactive sessions older than N days | `30` |
 | `ARCHON_SUPPRESS_NESTED_CLAUDE_WARNING` | When set to `1`, suppresses the stderr warning emitted when `archon` is run inside a Claude Code session | -- |
@@ -294,23 +334,42 @@ When `CLAUDE_USE_GLOBAL_AUTH` is unset, Archon auto-detects: it uses explicit to
 
 ### `.env` File Locations
 
-Infrastructure configuration (database URL, platform tokens) is stored in `.env` files:
+Archon keys env loading on **directory ownership, not filename**. `.archon/` (at `~/` or `<cwd>/`) is archon-owned. Anything else is yours.
+
+| Path | Stripped at boot? | Archon loads? | `archon setup` writes? |
+| --- | --- | --- | --- |
+| `<cwd>/.env` | **yes** (safety guard) | never | never |
+| `<cwd>/.archon/.env` | no | yes (repo scope, overrides user scope) | yes iff `--scope project` |
+| `~/.archon/.env` | no | yes (user scope) | yes iff `--scope home` (default) |
+
+**Load order at boot** (every entry point — CLI and server):
 
-| Component | Location | Purpose |
-|-----------|----------|---------|
-| **CLI** | `~/.archon/.env` | Global infrastructure config; CWD .env keys stripped first, then loaded with `override: true` (Archon config wins over shell-inherited vars) |
-| **Server (dev)** | `<archon-repo>/.env` + `~/.archon/.env` | Repo `.env` for platform tokens; `~/.archon/.env` loaded with `override: true` |
-| **Server (binary)** | `~/.archon/.env` | Single source of truth (repo `.env` path is not available in compiled binaries) |
+1. Strip keys Bun auto-loaded from `<cwd>/.env`, `.env.local`, `.env.development`, `.env.production` (prevents target-repo env from leaking into Archon).
+2. Load `~/.archon/.env` with `override: true` (archon config wins over shell-inherited vars).
+3. Load `<cwd>/.archon/.env` with `override: true` (repo scope wins over user scope).
 
-**How it works**: At startup, the CLI and server strip all keys that Bun auto-loaded from the current working directory (`.env`, `.env.local`, `.env.development`, `.env.production`) and any nested Claude Code session markers (`CLAUDECODE`, `CLAUDE_CODE_*` except auth vars) before loading `~/.archon/.env`. This ensures target repo keys and nested-session guards are fully removed from `process.env` before any application code runs.
+**Operator log lines** (stderr, emitted only when there is something to report):
 
-**Best practice**: Use `~/.archon/.env` as the single source of truth:
+```
+[archon] stripped 2 keys from /path/to/target-repo (.env, .env.local) to prevent target repo env from leaking into Archon processes
+[archon] loaded 3 keys from ~/.archon/.env
+[archon] loaded 2 keys from /path/to/target-repo/.archon/.env (repo scope, overrides user scope)
+```
+
+**Which file should I use?**
+
+- **`~/.archon/.env`** — user-wide defaults (your personal `SLACK_WEBHOOK`, `DATABASE_URL`, etc.). Applies to every project.
+- **`<cwd>/.archon/.env`** — per-project overrides. Different webhook per repo, different DB per environment, etc.
+- **`<cwd>/.env`** — **your app's** env file. Archon does not read this file; it strips the keys at boot so they do not leak into Archon's process.
 
 ```bash
-# Create global config
+# User-wide
 mkdir -p ~/.archon
 cp .env.example ~/.archon/.env
-# Edit with your values
+
+# Per-project override (e.g. a different Slack webhook for this repo)
+mkdir -p /path/to/repo/.archon
+printf 'SLACK_WEBHOOK=https://hooks.slack.com/...\n' > /path/to/repo/.archon/.env
 ```
 
 ## Docker Configuration
diff --git a/packages/docs-web/src/content/docs/reference/database.md b/packages/docs-web/src/content/docs/reference/database.md
index 6cab854622..a7a36ef58a 100644
--- a/packages/docs-web/src/content/docs/reference/database.md
+++ b/packages/docs-web/src/content/docs/reference/database.md
@@ -142,7 +142,7 @@ The database has 8 tables, all prefixed with `remote_agent_`:
 
 5. **`remote_agent_workflow_runs`** - Workflow execution tracking
    - Tracks active workflows per conversation
-   - Prevents concurrent workflow execution
+   - Locks concurrent execution per `working_path`: a second dispatch on a path with an active run (status `pending`/`running`/`paused`) is auto-cancelled with an actionable message. Stale `pending` rows older than 5 minutes are treated as orphaned and ignored.
    - Stores workflow state, step progress, and parent conversation linkage
 
 6. **`remote_agent_workflow_events`** - Step-level workflow event log
diff --git a/packages/docs-web/src/content/docs/reference/security.md b/packages/docs-web/src/content/docs/reference/security.md
index 4a2907d855..0515c6d5e4 100644
--- a/packages/docs-web/src/content/docs/reference/security.md
+++ b/packages/docs-web/src/content/docs/reference/security.md
@@ -114,46 +114,30 @@ The GitHub and Gitea adapters verify webhook signatures to ensure payloads origi
 ## Secrets Handling
 
 **Environment files:**
-- All secrets (API keys, tokens, webhook secrets) belong in `.env` files, never in source control.
-- The `.env.example` file in the repository contains placeholder values -- copy it and fill in real values.
-- Never commit `.env` files to git. The repository's `.gitignore` excludes them.
+- All secrets (API keys, tokens, webhook secrets) belong in archon-owned `.env` files (`~/.archon/.env` or `<cwd>/.archon/.env`), never in source control.
+- Never put archon secrets in `<cwd>/.env` — that file is stripped at boot (see below) and `archon setup` never writes to it. Put them in `~/.archon/.env` (home scope) or `<cwd>/.archon/.env` (project scope).
+- Archon's `.gitignore` excludes `.env` files. `<cwd>/.archon/.env` should also be gitignored (project-local secrets).
 
 **Subprocess env isolation:**
-- At startup, `stripCwdEnv()` removes **all** keys that Bun auto-loaded from the CWD `.env` files, plus nested Claude Code session markers (`CLAUDECODE`, `CLAUDE_CODE_*` except auth vars) and debugger vars (`NODE_OPTIONS`, `VSCODE_INSPECTOR_OPTIONS`). This runs before any module reads `process.env`.
-- `~/.archon/.env` is then loaded as the trusted source of Archon configuration. All keys the user sets there pass through to subprocesses — there is no allowlist filtering. The user controls this file and all keys are intentional.
+- At startup, `stripCwdEnv()` removes **all** keys that Bun auto-loaded from the CWD `.env` files (`.env`, `.env.local`, `.env.development`, `.env.production`), plus nested Claude Code session markers (`CLAUDECODE`, `CLAUDE_CODE_*` except auth vars) and debugger vars (`NODE_OPTIONS`, `VSCODE_INSPECTOR_OPTIONS`). This runs before any module reads `process.env`.
+- Then `loadArchonEnv(cwd)` loads archon-owned env from `~/.archon/.env` (user scope) and `<cwd>/.archon/.env` (repo scope, wins over user) with `override: true`. Both are trusted sources — the user controls them and all keys are intentional.
 - Per-codebase env vars configured via `codebase_env_vars` or `.archon/config.yaml` `env:` are merged on top at workflow execution time.
-- CWD `.env` keys are the **only** untrusted source. They belong to the target project, not to Archon.
+- `<cwd>/.env` is the **only** untrusted source. It belongs to the target project, not to Archon. Directory ownership (`.archon/`) is the security boundary — not the filename.
 
-### Env-leak gate (target repo `.env` keys)
+### Target repo `.env` isolation
 
-As a second layer of defense, Archon scans target repos for sensitive keys **before spawning** AI subprocesses. A Claude or Codex subprocess started with `cwd=/path/to/target/repo` inherits Bun's auto-loaded `.env` from that CWD — the env-leak gate catches this by scanning the target repo's `.env` files at registration and pre-spawn time.
+Archon prevents target repo `.env` from leaking into subprocesses through structural protection:
 
-**What Archon scans:** auto-loaded filenames `.env`, `.env.local`, `.env.development`, `.env.production`, `.env.development.local`, `.env.production.local`.
+1. **Boot cleanup:** `stripCwdEnv()` removes Bun-auto-loaded CWD `.env` keys from `process.env` before any application code runs.
+2. **Claude Code subprocess:** `executableArgs: ['--no-env-file']` prevents Bun from auto-loading `.env` in the Claude Code subprocess CWD.
+3. **Bun script nodes:** `bun --no-env-file` prevents script node subprocesses from loading target repo `.env`.
+4. **Bash nodes:** Not affected — bash does not auto-load `.env` files.
 
-**Scanned keys:** `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`, `OPENAI_API_KEY`, `CODEX_API_KEY`, `GEMINI_API_KEY`.
+Archon's own env sources (`~/.archon/.env`, dev `.env`) are loaded after the CWD strip and pass through to subprocesses normally.
 
-:::caution
-Renaming the file to `.env.local`, `.env.development`, etc. **does not work** — Bun auto-loads those too. Only `.env.secrets` (or any non-auto-loaded name) is safe.
-:::
-
-**Where the gate runs:**
-
-| Failure point | When | What you see |
-| --- | --- | --- |
-| Registration (Web UI) | Adding a project via Settings → Add Project | 422 with the "Allow env keys" checkbox shown inline |
-| Registration (CLI) | First `archon workflow run --cwd <repo>` auto-registers | Error message points at `--allow-env-keys` and the global config flag |
-| Pre-spawn | Existing codebase, before each Claude/Codex query | Error message points at Settings → Projects → "Allow env keys" toggle |
-
-**Primary remediation (recommended):**
-1. Remove the key from the target repo's `.env`, or
-2. Rename the file to `.env.secrets` and load it explicitly from your app code.
-
-**Secondary remediation (consent grants):**
-- **Web UI:** Settings → Projects → click "Allow env keys" on the row. Revoke from the same place. Each grant/revoke writes a `warn`-level audit log (`env_leak_consent_granted` / `env_leak_consent_revoked`) including `codebaseId`, `path`, scanned `files`, matched `keys`, `scanStatus` (`'ok'` or `'skipped'`), and `actor`.
-- **CLI:** `archon workflow run <name> "your message" --cwd <repo> --allow-env-keys` grants consent during this run's auto-registration. The grant is persisted (the codebase row is created with `allow_env_keys = true`) and logged as `env_leak_consent_granted` with `actor: 'user-cli'`.
-- **Global bypass:** set `allow_target_repo_keys: true` in `~/.archon/config.yaml` to disable the gate for all codebases on this machine. `env_leak_gate_disabled` is logged at most once per process per source (global vs. repo) the first time `loadConfig` resolves the bypass as active. A repo-level `.archon/config.yaml` with `allow_target_repo_keys: false` re-enables the gate for that repo.
-
-**Startup scan:** When `allow_target_repo_keys` is not set, the server scans every registered codebase with `allow_env_keys = false` and emits one `startup_env_leak_gate_will_block` warning per codebase **that has findings** (i.e. would actually be blocked). This gives you a chance to grant consent before hitting a fatal error mid-workflow. The scan is skipped entirely when the global bypass is active.
+**If you need env vars available during workflow execution**, use managed env injection:
+- `.archon/config.yaml` `env:` section (per-repo, checked into version control)
+- Web UI: Settings → Projects → Env Vars (per-codebase, stored in Archon DB)
 
 **CORS:**
 - API routes use `WEB_UI_ORIGIN` to restrict CORS. The default is `*` (allow all), which is appropriate for local single-developer use. Set a specific origin when exposing the server publicly.
diff --git a/packages/docs-web/src/content/docs/reference/troubleshooting.md b/packages/docs-web/src/content/docs/reference/troubleshooting.md
index 50805c7911..5e9b032293 100644
--- a/packages/docs-web/src/content/docs/reference/troubleshooting.md
+++ b/packages/docs-web/src/content/docs/reference/troubleshooting.md
@@ -280,6 +280,41 @@ docker compose exec app ls -la /.archon/workspaces
 docker compose exec app git clone https://github.com/user/repo /.archon/workspaces/test-repo
 ```
 
+## "Claude Code not found" When Running Compiled Binary
+
+**Symptom:** A workflow that uses Claude fails with:
+
+```
+Claude Code not found. Archon requires the Claude Code executable to be
+reachable at a configured path in compiled builds.
+```
+
+**Cause:** Compiled Archon binaries (`archon` from the curl/PowerShell installer or Homebrew) do not bundle Claude Code. They need an explicit path to the Claude Code executable. Source/dev mode (`bun run`) auto-resolves via `node_modules` and is unaffected.
+
+**Fix:** Install Claude Code separately and point Archon at it.
+
+```bash
+# macOS / Linux / WSL — Anthropic's recommended native installer
+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"
+```
+
+For a durable setup, set the path in `~/.archon/config.yaml` instead:
+
+```yaml
+assistants:
+  claude:
+    claudeBinaryPath: /absolute/path/to/claude
+```
+
+`archon setup` auto-detects and writes `CLAUDE_BIN_PATH` for you. Docker users do not need to do anything — the image pre-sets the variable.
+
+See the [AI Assistants → Binary path configuration](/getting-started/ai-assistants/#binary-path-configuration-compiled-binaries-only) guide for the full install matrix.
+
 ## Workflows Hang Silently When Run Inside Claude Code
 
 **Symptom:** Workflows started from within a Claude Code session (e.g., via the Terminal tool) produce no output, or the CLI emits a warning about `CLAUDECODE=1` before the workflow hangs.
@@ -299,3 +334,40 @@ ARCHON_SUPPRESS_NESTED_CLAUDE_WARNING=1 archon workflow run ...
 ```bash
 ARCHON_CLAUDE_FIRST_EVENT_TIMEOUT_MS=120000 archon workflow run ...
 ```
+
+## Worktree Belongs to a Different Clone
+
+**Symptom:** Running a workflow (especially with `--branch <name>`) from one local clone surfaces one of these errors:
+
+- `Worktree at <path> belongs to a different clone (<other-clone-path>). Remove it from that clone or use a different codebase registration.`
+- `Cannot verify worktree ownership at <path>: <reason>`
+- `Cannot adopt <path>: path contains a full git checkout, not a worktree.`
+- `Cannot adopt <path>: .git pointer is not a git-worktree reference.`
+
+**Cause:** Archon derives codebase identity from the remote URL (`owner/repo`), so two local clones of the same remote share one `codebase_id`. Worktrees are stored under a shared path (`~/.archon/workspaces/<owner>/<repo>/worktrees/`), which means a worktree created by clone A is visible on disk from clone B. The isolation system refuses to silently adopt across clones because it would operate on the wrong filesystem state.
+
+**Fix — pick one:**
+
+1. **Remove the other clone's worktree.** If you no longer need the other clone's in-progress work:
+
+   ```bash
+   # From the other clone's directory, find and remove the conflicting worktree
+   archon isolation list
+   archon complete <branch-name>          # graceful cleanup
+   # or, if no work to preserve:
+   git worktree remove <path> --force
+   ```
+
+2. **Use a different branch name** for this run so the two clones don't compete for the same worktree path:
+
+   ```bash
+   archon workflow run <name> --branch <different-name> "task"
+   ```
+
+3. **Work from a single clone.** If both local checkouts are for the same project, consolidate to one. Archon's codebase registration currently assumes one local path per remote; true multi-clone support is tracked in [#1192](https://github.com/coleam00/Archon/issues/1192).
+
+**Other variants:**
+
+- `path contains a full git checkout, not a worktree`: something non-Archon created a full git repo at the worktree path. Remove or move it.
+- `.git pointer is not a git-worktree reference`: the `.git` file at that path points somewhere unexpected (submodule, malformed). Inspect it with `cat <path>/.git` and clean up manually.
+- `Cannot verify worktree ownership`: filesystem permission or I/O error reading `<path>/.git`. Check `ls -la <path>` and file permissions on `~/.archon/workspaces`.
diff --git a/packages/git/package.json b/packages/git/package.json
index fea406f35a..dbcee1820b 100644
--- a/packages/git/package.json
+++ b/packages/git/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@archon/git",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
diff --git a/packages/git/src/exec.ts b/packages/git/src/exec.ts
index 9380e1e8b8..a085ef9375 100644
--- a/packages/git/src/exec.ts
+++ b/packages/git/src/exec.ts
@@ -8,7 +8,7 @@ const promisifiedExecFile = promisify(execFile);
 export async function execFileAsync(
   cmd: string,
   args: string[],
-  options?: { timeout?: number; cwd?: string; maxBuffer?: number }
+  options?: { timeout?: number; cwd?: string; maxBuffer?: number; env?: NodeJS.ProcessEnv }
 ): Promise<{ stdout: string; stderr: string }> {
   const result = await promisifiedExecFile(cmd, args, options);
   return {
diff --git a/packages/git/src/git.test.ts b/packages/git/src/git.test.ts
index 9c3287b04b..518a01324e 100644
--- a/packages/git/src/git.test.ts
+++ b/packages/git/src/git.test.ts
@@ -194,79 +194,78 @@ describe('git utilities', () => {
       }
     });
 
-    test('returns ~/.archon/worktrees by default for local (non-Docker)', () => {
+    test('returns workspace-scoped base for a local non-workspace repo (via path fallback)', () => {
+      // New-model invariant: every repo resolves to workspace-scoped. For a repo
+      // living outside ~/.archon/workspaces/, owner/repo is derived from the last
+      // two path segments (extractOwnerRepo) so the worktree base is still stable.
       delete process.env.WORKTREE_BASE;
       delete process.env.WORKSPACE_PATH;
       delete process.env.ARCHON_HOME;
       delete process.env.ARCHON_DOCKER;
       const result = git.getWorktreeBase('/workspace/my-repo');
-      expect(result).toBe(join(homedir(), '.archon', 'worktrees'));
-    });
-
-    test('returns /.archon/worktrees for Docker environment', () => {
-      delete process.env.WORKTREE_BASE;
-      delete process.env.ARCHON_HOME;
-      process.env.WORKSPACE_PATH = '/workspace';
-      const result = git.getWorktreeBase('/workspace/my-repo');
-      expect(result).toBe(join('/', '.archon', 'worktrees'));
-    });
-
-    test('detects Docker by HOME=/root + WORKSPACE_PATH', () => {
-      delete process.env.WORKTREE_BASE;
-      delete process.env.ARCHON_HOME;
-      delete process.env.ARCHON_DOCKER;
-      process.env.HOME = '/root';
-      process.env.WORKSPACE_PATH = '/app/workspace';
-      const result = git.getWorktreeBase('/workspace/my-repo');
-      expect(result).toBe(join('/', '.archon', 'worktrees'));
+      expect(result).toEqual({
+        base: join(homedir(), '.archon', 'workspaces', 'workspace', 'my-repo', 'worktrees'),
+        layout: 'workspace-scoped',
+      });
     });
 
-    test('uses ARCHON_HOME for local (non-Docker)', () => {
+    test('uses ARCHON_HOME for the workspace-scoped base (local non-Docker)', () => {
       delete process.env.WORKSPACE_PATH;
       delete process.env.WORKTREE_BASE;
       delete process.env.ARCHON_DOCKER;
       process.env.ARCHON_HOME = '/custom/archon';
       const result = git.getWorktreeBase('/workspace/my-repo');
-      expect(result).toBe(join('/custom/archon', 'worktrees'));
+      expect(result).toEqual({
+        base: join('/custom/archon', 'workspaces', 'workspace', 'my-repo', 'worktrees'),
+        layout: 'workspace-scoped',
+      });
     });
 
-    test('uses fixed path in Docker', () => {
+    test('uses the Docker archon home for the workspace-scoped base', () => {
       delete process.env.ARCHON_HOME;
       process.env.ARCHON_DOCKER = 'true';
       const result = git.getWorktreeBase('/workspace/my-repo');
-      expect(result).toBe(join('/', '.archon', 'worktrees'));
+      expect(result).toEqual({
+        base: join('/', '.archon', 'workspaces', 'workspace', 'my-repo', 'worktrees'),
+        layout: 'workspace-scoped',
+      });
     });
 
-    test('returns project-scoped worktrees path when repo is under workspaces', () => {
+    test('returns workspace-scoped path when repo is already under workspaces/', () => {
       delete process.env.WORKSPACE_PATH;
       delete process.env.ARCHON_DOCKER;
       delete process.env.ARCHON_HOME;
       const workspacesPath = join(homedir(), '.archon', 'workspaces');
       const repoPath = join(workspacesPath, 'acme', 'widget', 'source');
       const result = git.getWorktreeBase(repoPath);
-      expect(result).toBe(join(workspacesPath, 'acme', 'widget', 'worktrees'));
+      expect(result).toEqual({
+        base: join(workspacesPath, 'acme', 'widget', 'worktrees'),
+        layout: 'workspace-scoped',
+      });
     });
 
-    test('returns project-scoped path with ARCHON_HOME override', () => {
+    test('workspace-scoped path honors ARCHON_HOME override', () => {
       delete process.env.WORKSPACE_PATH;
       delete process.env.ARCHON_DOCKER;
       process.env.ARCHON_HOME = join('/', 'custom', 'archon');
       const repoPath = join('/', 'custom', 'archon', 'workspaces', 'acme', 'widget', 'source');
       const result = git.getWorktreeBase(repoPath);
-      expect(result).toBe(
-        join('/', 'custom', 'archon', 'workspaces', 'acme', 'widget', 'worktrees')
-      );
+      expect(result).toEqual({
+        base: join('/', 'custom', 'archon', 'workspaces', 'acme', 'widget', 'worktrees'),
+        layout: 'workspace-scoped',
+      });
     });
 
-    test('uses codebaseName to resolve project-scoped path for local repo', () => {
+    test('uses codebaseName to resolve workspace-scoped path for a local repo', () => {
       delete process.env.WORKSPACE_PATH;
       delete process.env.ARCHON_DOCKER;
       delete process.env.ARCHON_HOME;
       const localRepoPath = '/Users/rasmus/Projects/sasha-demo';
       const result = git.getWorktreeBase(localRepoPath, 'Widinglabs/sasha-demo');
-      expect(result).toBe(
-        join(homedir(), '.archon', 'workspaces', 'Widinglabs', 'sasha-demo', 'worktrees')
-      );
+      expect(result).toEqual({
+        base: join(homedir(), '.archon', 'workspaces', 'Widinglabs', 'sasha-demo', 'worktrees'),
+        layout: 'workspace-scoped',
+      });
     });
 
     test('codebaseName takes priority over workspaces path detection', () => {
@@ -276,19 +275,52 @@ describe('git utilities', () => {
       const workspacesPath = join(homedir(), '.archon', 'workspaces');
       const repoPath = join(workspacesPath, 'old-owner', 'old-repo', 'source');
       const result = git.getWorktreeBase(repoPath, 'new-owner/new-repo');
-      expect(result).toBe(join(workspacesPath, 'new-owner', 'new-repo', 'worktrees'));
+      expect(result).toEqual({
+        base: join(workspacesPath, 'new-owner', 'new-repo', 'worktrees'),
+        layout: 'workspace-scoped',
+      });
     });
 
-    test('ignores invalid codebaseName and falls back to path detection', () => {
+    test('ignores invalid codebaseName and falls back to path-derived owner/repo', () => {
+      // "invalid-no-slash" doesn't parse as owner/repo; the layout still resolves
+      // to workspace-scoped using the last two segments of the repoPath.
       delete process.env.WORKSPACE_PATH;
       delete process.env.ARCHON_DOCKER;
       delete process.env.ARCHON_HOME;
       const result = git.getWorktreeBase('/local/repo', 'invalid-no-slash');
-      expect(result).toBe(join(homedir(), '.archon', 'worktrees'));
+      expect(result).toEqual({
+        base: join(homedir(), '.archon', 'workspaces', 'local', 'repo', 'worktrees'),
+        layout: 'workspace-scoped',
+      });
+    });
+
+    test('repoLocal override wins over workspace-scoped default', () => {
+      delete process.env.WORKSPACE_PATH;
+      delete process.env.ARCHON_DOCKER;
+      delete process.env.ARCHON_HOME;
+      const repoPath = '/Users/rasmus/Projects/myapp';
+      const result = git.getWorktreeBase(repoPath, undefined, { repoLocal: '.worktrees' });
+      expect(result).toEqual({
+        base: join(repoPath, '.worktrees'),
+        layout: 'repo-local',
+      });
+    });
+
+    test('repoLocal override wins even for repos under workspaces/', () => {
+      delete process.env.WORKSPACE_PATH;
+      delete process.env.ARCHON_DOCKER;
+      delete process.env.ARCHON_HOME;
+      const workspacesPath = join(homedir(), '.archon', 'workspaces');
+      const repoPath = join(workspacesPath, 'acme', 'widget', 'source');
+      const result = git.getWorktreeBase(repoPath, 'acme/widget', { repoLocal: '.wt' });
+      expect(result).toEqual({
+        base: join(repoPath, '.wt'),
+        layout: 'repo-local',
+      });
     });
   });
 
-  describe('isProjectScopedWorktreeBase', () => {
+  describe('isProjectScopedWorktreeBase (deprecated)', () => {
     const originalArchonHome = process.env.ARCHON_HOME;
     const originalWorkspacePath = process.env.WORKSPACE_PATH;
     const originalArchonDocker = process.env.ARCHON_DOCKER;
@@ -321,19 +353,14 @@ describe('git utilities', () => {
       ).toBe(true);
     });
 
-    test('returns false for path outside workspaces', () => {
-      delete process.env.WORKSPACE_PATH;
-      delete process.env.ARCHON_DOCKER;
-      delete process.env.ARCHON_HOME;
-      expect(git.isProjectScopedWorktreeBase('/workspace/my-repo')).toBe(false);
-    });
-
-    test('returns false for path under workspaces with only owner (no repo)', () => {
+    test('returns true for a local non-workspace path (new two-layout model)', () => {
+      // In the pre-refactor three-layout model, this returned false (legacy global).
+      // Under the two-layout model every repo is workspace-scoped unless a
+      // `repoLocal` override is supplied, which this helper does not accept.
       delete process.env.WORKSPACE_PATH;
       delete process.env.ARCHON_DOCKER;
       delete process.env.ARCHON_HOME;
-      const workspacesPath = join(homedir(), '.archon', 'workspaces');
-      expect(git.isProjectScopedWorktreeBase(join(workspacesPath, 'acme'))).toBe(false);
+      expect(git.isProjectScopedWorktreeBase('/workspace/my-repo')).toBe(true);
     });
 
     test('returns true when codebaseName is provided (local repo)', () => {
@@ -345,11 +372,13 @@ describe('git utilities', () => {
       );
     });
 
-    test('returns false when codebaseName is invalid', () => {
+    test('returns true when codebaseName is invalid (falls back to path-derived)', () => {
+      // Under the two-layout model the helper always returns true for any resolvable
+      // owner/repo. Invalid codebaseName + valid repo path → still workspace-scoped.
       delete process.env.WORKSPACE_PATH;
       delete process.env.ARCHON_DOCKER;
       delete process.env.ARCHON_HOME;
-      expect(git.isProjectScopedWorktreeBase('/local/repo', 'invalid')).toBe(false);
+      expect(git.isProjectScopedWorktreeBase('/local/repo', 'invalid')).toBe(true);
     });
   });
 
@@ -1894,4 +1923,119 @@ branch refs/heads/feature/auth
       );
     });
   });
+
+  describe('verifyWorktreeOwnership', () => {
+    test('resolves for matching worktree pointer', async () => {
+      await writeFile(
+        join(testDir, '.git'),
+        'gitdir: /workspace/my-repo/.git/worktrees/issue-42\n'
+      );
+
+      await expect(
+        git.verifyWorktreeOwnership(
+          git.toWorktreePath(testDir),
+          git.toRepoPath('/workspace/my-repo')
+        )
+      ).resolves.toBeUndefined();
+    });
+
+    test('throws with "belongs to a different clone" when gitdir points elsewhere', async () => {
+      await writeFile(join(testDir, '.git'), 'gitdir: /other/clone/.git/worktrees/issue-42\n');
+
+      await expect(
+        git.verifyWorktreeOwnership(
+          git.toWorktreePath(testDir),
+          git.toRepoPath('/workspace/my-repo')
+        )
+      ).rejects.toThrow(/belongs to a different clone \(\/other\/clone\)/);
+    });
+
+    test('normalizes trailing slashes in both paths', async () => {
+      await writeFile(
+        join(testDir, '.git'),
+        'gitdir: /workspace/my-repo/.git/worktrees/issue-42\n'
+      );
+
+      await expect(
+        git.verifyWorktreeOwnership(
+          git.toWorktreePath(testDir),
+          git.toRepoPath('/workspace/my-repo/')
+        )
+      ).resolves.toBeUndefined();
+    });
+
+    test('throws EISDIR when .git is a directory (full checkout at path)', async () => {
+      await realMkdir(join(testDir, '.git'));
+
+      const promise = git.verifyWorktreeOwnership(
+        git.toWorktreePath(testDir),
+        git.toRepoPath('/workspace/my-repo')
+      );
+      await expect(promise).rejects.toThrow(/path contains a full git checkout/);
+      // Original errno is preserved on the wrapped error for robust
+      // classification downstream (not just a fragile substring match).
+      try {
+        await git.verifyWorktreeOwnership(
+          git.toWorktreePath(testDir),
+          git.toRepoPath('/workspace/my-repo')
+        );
+      } catch (err) {
+        expect((err as NodeJS.ErrnoException).code).toBe('EISDIR');
+      }
+    });
+
+    test('throws ENOENT when .git file is missing', async () => {
+      await expect(
+        git.verifyWorktreeOwnership(
+          git.toWorktreePath(testDir),
+          git.toRepoPath('/workspace/my-repo')
+        )
+      ).rejects.toThrow(/Cannot verify worktree ownership/);
+      try {
+        await git.verifyWorktreeOwnership(
+          git.toWorktreePath(testDir),
+          git.toRepoPath('/workspace/my-repo')
+        );
+      } catch (err) {
+        expect((err as NodeJS.ErrnoException).code).toBe('ENOENT');
+      }
+    });
+
+    test('throws on submodule pointer (gitdir into .git/modules/...)', async () => {
+      await writeFile(
+        join(testDir, '.git'),
+        'gitdir: /workspace/my-repo/.git/modules/vendor/submodule\n'
+      );
+
+      await expect(
+        git.verifyWorktreeOwnership(
+          git.toWorktreePath(testDir),
+          git.toRepoPath('/workspace/my-repo')
+        )
+      ).rejects.toThrow(/not a git-worktree reference/);
+    });
+
+    test('throws on corrupted .git content (no gitdir prefix)', async () => {
+      await writeFile(join(testDir, '.git'), 'this is not a git pointer at all');
+
+      await expect(
+        git.verifyWorktreeOwnership(
+          git.toWorktreePath(testDir),
+          git.toRepoPath('/workspace/my-repo')
+        )
+      ).rejects.toThrow(/not a git-worktree reference/);
+    });
+
+    test('preserves original error via `cause` chain on fs errors', async () => {
+      try {
+        await git.verifyWorktreeOwnership(
+          git.toWorktreePath(testDir),
+          git.toRepoPath('/workspace/my-repo')
+        );
+      } catch (err) {
+        expect((err as Error).cause).toBeDefined();
+        expect(((err as Error).cause as NodeJS.ErrnoException).code).toBe('ENOENT');
+      }
+    });
+  });
 });
diff --git a/packages/git/src/index.ts b/packages/git/src/index.ts
index 8cfdc865f7..39252ce4d3 100644
--- a/packages/git/src/index.ts
+++ b/packages/git/src/index.ts
@@ -24,7 +24,9 @@ export {
   isWorktreePath,
   removeWorktree,
   getCanonicalRepoPath,
+  verifyWorktreeOwnership,
 } from './worktree';
+export type { WorktreeLayout, WorktreeBaseOverride } from './worktree';
 
 // Branch operations
 export {
diff --git a/packages/git/src/worktree.ts b/packages/git/src/worktree.ts
index a7fa309385..32ad2dbbc8 100644
--- a/packages/git/src/worktree.ts
+++ b/packages/git/src/worktree.ts
@@ -1,11 +1,6 @@
 import { readFile, access } from 'fs/promises';
-import { join } from 'path';
-import {
-  createLogger,
-  getArchonWorktreesPath,
-  getArchonWorkspacesPath,
-  getProjectWorktreesPath,
-} from '@archon/paths';
+import { join, resolve } from 'path';
+import { createLogger, getArchonWorkspacesPath, getProjectWorktreesPath } from '@archon/paths';
 import { execFileAsync } from './exec';
 import type { RepoPath, BranchName, WorktreePath, WorktreeInfo } from './types';
 import { toRepoPath, toBranchName, toWorktreePath } from './types';
@@ -18,60 +13,111 @@ function getLog(): ReturnType<typeof createLogger> {
 }
 
 /**
- * Get the base directory for worktrees.
+ * Layout of a worktree base relative to the repository.
  *
- * Resolution order:
- * 1. If `codebaseName` is provided in "owner/repo" format, returns the project-scoped
- *    path directly: ~/.archon/workspaces/owner/repo/worktrees/
- * 2. For paths under ~/.archon/workspaces/owner/repo/..., extracts owner/repo from path
- *    and returns the project-scoped path.
- * 3. Otherwise, returns the legacy global path: ~/.archon/worktrees/
+ * Two layouts only — worktrees live either co-located with the repo (opt-in)
+ * or inside the user's archon workspace area (default for every repo):
+ *
+ * - `repo-local`       — `<repoRoot>/<override.repoLocal>/`  (opt-in per repo config)
+ * - `workspace-scoped` — `~/.archon/workspaces/<owner>/<repo>/worktrees/`  (default)
+ *
+ * In both layouts the base already includes all repo context, so callers append
+ * only the branch name to compose the final worktree path — there is no layout
+ * where owner/repo gets tacked on as a separate path segment.
+ */
+export type WorktreeLayout = 'repo-local' | 'workspace-scoped';
+
+/**
+ * Override inputs for `getWorktreeBase()`. All fields are optional.
+ */
+export interface WorktreeBaseOverride {
+  /**
+   * Repo-relative path where worktrees should live (e.g. `.worktrees`).
+   * Only supported override today. Must be validated as a safe relative path
+   * by the caller before reaching this layer.
+   */
+  repoLocal?: string;
+}
+
+/**
+ * Resolve the `{ owner, repo }` identity used to scope archon-managed worktrees.
+ *
+ * Precedence:
+ *   1. Explicit `codebaseName` in `owner/repo` format (from the database / web UI)
+ *   2. Path segments when `repoPath` is already under `~/.archon/workspaces/owner/repo/`
+ *   3. Last two path segments of `repoPath` (works for any local checkout)
+ *
+ * The third fallback is what lets non-cloned / locally-registered repos still
+ * land in the workspace-scoped layout — every repo gets a stable owner/repo
+ * identity derived from its filesystem path.
  */
-export function getWorktreeBase(repoPath: RepoPath, codebaseName?: string): string {
-  // If codebase name is known, use project-scoped path directly
+function resolveOwnerRepo(
+  repoPath: RepoPath,
+  codebaseName?: string
+): { owner: string; repo: string } {
   if (codebaseName) {
     const parts = codebaseName.split('/');
     if (parts.length === 2 && parts[0] && parts[1]) {
-      return getProjectWorktreesPath(parts[0], parts[1]);
+      return { owner: parts[0], repo: parts[1] };
     }
-    // codebaseName present but not "owner/repo" format — fall through to path detection.
-    // This is intentional: safe degradation to legacy global path.
     getLog().warn({ codebaseName }, 'worktree.invalid_codebase_name_format');
   }
-  // Existing path-prefix detection (cloned repos under workspaces/)
   const workspacesPath = getArchonWorkspacesPath();
   if (repoPath.startsWith(workspacesPath)) {
     const relative = repoPath.substring(workspacesPath.length + 1);
     const parts = relative.split(/[/\\]/).filter(p => p.length > 0);
     if (parts.length >= 2) {
-      return getProjectWorktreesPath(parts[0], parts[1]);
+      return { owner: parts[0], repo: parts[1] };
     }
   }
-  // Legacy global fallback (no codebase name, no workspace path match)
-  return getArchonWorktreesPath();
+  // Fallback: derive from path basename/parent-basename — covers local-registered
+  // repos that never lived under workspaces/. Delegates to extractOwnerRepo()
+  // which throws on pathologically short paths.
+  return extractOwnerRepo(repoPath);
 }
 
 /**
- * Check if the worktree base for a given repo path is project-scoped
- * (under ~/.archon/workspaces/owner/repo/worktrees/) vs legacy global.
+ * Get the base directory for worktrees and the resolved layout.
  *
- * When project-scoped, the worktree base already includes the owner/repo context,
- * so callers should NOT append owner/repo again.
+ * Resolution (highest to lowest priority):
+ *   1. `override.repoLocal` → `<repoRoot>/<repoLocal>/` (layout: `repo-local`)
+ *   2. Otherwise             → `~/.archon/workspaces/<owner>/<repo>/worktrees/`
+ *                              (layout: `workspace-scoped`)
  *
- * Resolution order mirrors `getWorktreeBase`: codebaseName → path detection → legacy.
+ * The `<owner>/<repo>` identity is resolved via `resolveOwnerRepo()` — see its
+ * docstring for the precedence. Every repo ends up with a stable workspace-scoped
+ * base; there is no `~/.archon/worktrees/owner/repo/` fallback layout.
  */
-export function isProjectScopedWorktreeBase(repoPath: RepoPath, codebaseName?: string): boolean {
-  // If codebase name is known, it's always project-scoped
-  if (codebaseName) {
-    const parts = codebaseName.split('/');
-    if (parts.length === 2 && parts[0] && parts[1]) return true;
-    // Invalid format — fall through to path detection (same safe degradation as getWorktreeBase).
+export function getWorktreeBase(
+  repoPath: RepoPath,
+  codebaseName?: string,
+  override?: WorktreeBaseOverride
+): { base: string; layout: WorktreeLayout } {
+  if (override?.repoLocal) {
+    return { base: join(repoPath, override.repoLocal), layout: 'repo-local' };
   }
-  const workspacesPath = getArchonWorkspacesPath();
-  if (!repoPath.startsWith(workspacesPath)) return false;
-  const relative = repoPath.substring(workspacesPath.length + 1);
-  const parts = relative.split(/[/\\]/).filter(p => p.length > 0);
-  return parts.length >= 2;
+  const { owner, repo } = resolveOwnerRepo(repoPath, codebaseName);
+  return {
+    base: getProjectWorktreesPath(owner, repo),
+    layout: 'workspace-scoped',
+  };
+}
+
+/**
+ * Check if the worktree base for a given repo path is workspace-scoped.
+ *
+ * Kept for backward compatibility with callers outside this package; prefer
+ * reading `layout` from `getWorktreeBase()` in new code. This helper is unaware
+ * of `override.repoLocal`, so it does not reflect per-repo overrides — use
+ * `getWorktreeBase(...).layout === 'workspace-scoped'` in override-aware code.
+ *
+ * @deprecated Use `getWorktreeBase(...).layout === 'workspace-scoped'` instead.
+ *   This helper returned `false` for pre-workspace registered repos in the old
+ *   two-layout model; in the current model every repo resolves to workspace-scoped
+ *   when no override is set, so this always returns `true`.
+ */
+export function isProjectScopedWorktreeBase(repoPath: RepoPath, codebaseName?: string): boolean {
+  return getWorktreeBase(repoPath, codebaseName).layout === 'workspace-scoped';
 }
 
 /**
@@ -256,6 +302,82 @@ export async function getCanonicalRepoPath(path: string): Promise<RepoPath> {
   return toRepoPath(path);
 }
 
+/**
+ * Verify that the worktree at the given path belongs to the expected repo.
+ *
+ * Throws if the worktree's parent repo doesn't match the request, or if
+ * ownership cannot be determined. The caller relies on the throw-or-return
+ * contract: a successful return means the caller may safely adopt the
+ * worktree. This is intentionally strict — a permissive fallback here
+ * would re-introduce the cross-checkout bug this guard exists to prevent.
+ *
+ * Paths are normalized with `resolve()` before comparison to handle trailing
+ * slashes and relative components. Symlinked paths (where canonical vs
+ * registered paths differ by symlink resolution) are not equated — callers
+ * should register codebases with consistent path forms.
+ *
+ * Error classification (surfaced via `classifyIsolationError` in
+ * `@archon/isolation/errors.ts`):
+ *   - "path contains a full git checkout" → EISDIR
+ *   - "Cannot verify worktree ownership" → ENOENT / EACCES / EIO
+ *   - "not a git-worktree reference" → submodule pointer or malformed
+ *   - "belongs to a different clone" → cross-checkout
+ */
+export async function verifyWorktreeOwnership(
+  worktreePath: WorktreePath,
+  expectedRepo: RepoPath
+): Promise<void> {
+  let gitContent: string;
+  try {
+    gitContent = await readFile(join(worktreePath, '.git'), 'utf-8');
+  } catch (error) {
+    const err = error as NodeJS.ErrnoException;
+    // Preserve the original errno on the wrapped error so downstream
+    // classifiers can match by `.code` instead of substring — resilient to
+    // Node.js message format changes. The original error is also kept via
+    // `cause` for debugging.
+    const wrap = (message: string): Error => {
+      const wrapped = new Error(message, { cause: err });
+      if (err.code) (wrapped as NodeJS.ErrnoException).code = err.code;
+      return wrapped;
+    };
+    // EISDIR: .git is a directory — path holds a full checkout, not a
+    // worktree. Refusing adoption prevents accidentally treating an
+    // unrelated repo at this path as ours.
+    if (err.code === 'EISDIR') {
+      throw wrap(
+        `Cannot adopt ${worktreePath}: path contains a full git checkout, not a worktree.`
+      );
+    }
+    // ENOENT: .git file missing despite worktreeExists() reporting true —
+    // a TOCTOU race or filesystem corruption. Fail fast.
+    // EACCES/EIO/etc.: cannot verify ownership — fail fast rather than
+    // defaulting to permissive adoption.
+    throw wrap(`Cannot verify worktree ownership at ${worktreePath}: ${err.message}`);
+  }
+
+  // gitdir: /path/to/repo/.git/worktrees/branch-name
+  const match = /gitdir: (.+)\/\.git\/worktrees\//.exec(gitContent);
+  if (!match) {
+    // Not a git-worktree pointer (e.g., submodule pointer, or malformed).
+    // We cannot confirm this is our worktree, so refuse adoption.
+    throw new Error(`Cannot adopt ${worktreePath}: .git pointer is not a git-worktree reference.`);
+  }
+
+  // Compare on resolved paths (normalizes trailing slashes and relative
+  // components) but display the raw path from the .git pointer so the user
+  // sees the value they'd recognize. On Windows, `resolve()` would prepend
+  // a drive letter to the POSIX-style gitdir, making the error message
+  // misleading and causing platform-specific test breakage.
+  const existingRepoRaw = match[1];
+  if (resolve(existingRepoRaw) !== resolve(expectedRepo)) {
+    throw new Error(
+      `Worktree at ${worktreePath} belongs to a different clone (${existingRepoRaw}). ` +
+        'Remove it from that clone or use a different codebase registration.'
+    );
+  }
+}
+
 /**
  * Extract owner and repo name from the last two segments of a repository path.
  * Throws if the path has fewer than 2 non-empty segments.
diff --git a/packages/isolation/package.json b/packages/isolation/package.json
index 0bac427a74..c145585304 100644
--- a/packages/isolation/package.json
+++ b/packages/isolation/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@archon/isolation",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
diff --git a/packages/isolation/src/errors.test.ts b/packages/isolation/src/errors.test.ts
index 30cb137cb8..0d91f89547 100644
--- a/packages/isolation/src/errors.test.ts
+++ b/packages/isolation/src/errors.test.ts
@@ -56,6 +56,14 @@ describe('classifyIsolationError', () => {
     const result = classifyIsolationError(new Error('unknown error'));
     expect(result).toContain('Could not create isolated workspace');
   });
+
+  test('matches "submodule initialization failed" with opt-out guidance', () => {
+    const result = classifyIsolationError(
+      new Error('Submodule initialization failed: fatal: could not read from remote repository')
+    );
+    expect(result).toContain('Submodule initialization failed');
+    expect(result).toContain('initSubmodules: false');
+  });
 });
 
 describe('isKnownIsolationError', () => {
@@ -87,6 +95,12 @@ describe('isKnownIsolationError', () => {
     expect(isKnownIsolationError(new Error('branch not found'))).toBe(true);
   });
 
+  test('identifies submodule initialization failure as known', () => {
+    expect(
+      isKnownIsolationError(new Error('Submodule initialization failed: network unreachable'))
+    ).toBe(true);
+  });
+
   test('returns false for unknown errors', () => {
     expect(isKnownIsolationError(new TypeError('cannot read property of null'))).toBe(false);
   });
diff --git a/packages/isolation/src/errors.ts b/packages/isolation/src/errors.ts
index 529933a4e8..5bc2cdb31e 100644
--- a/packages/isolation/src/errors.ts
+++ b/packages/isolation/src/errors.ts
@@ -16,6 +16,100 @@ export class IsolationBlockedError extends Error {
   }
 }
 
+/**
+ * Single source of truth for isolation error classification.
+ *
+ * `known: true` means the error is a recognized infrastructure/config failure
+ * that should produce a user-facing "blocked" message. `known: false` means
+ * it's classifiable (we have a helpful message) but still a programming /
+ * user-input bug that should crash rather than be absorbed as blocked state.
+ */
+const ERROR_PATTERNS: { pattern: string; message: string; known: boolean }[] = [
+  {
+    pattern: 'permission denied',
+    message:
+      '**Error:** Permission denied while creating workspace. Check file system permissions.',
+    known: true,
+  },
+  {
+    pattern: 'eacces',
+    message:
+      '**Error:** Permission denied while creating workspace. Check file system permissions.',
+    known: true,
+  },
+  {
+    pattern: 'timeout',
+    message: '**Error:** Timed out creating workspace. Git repository may be slow or unavailable.',
+    known: true,
+  },
+  {
+    pattern: 'no space left',
+    message: '**Error:** No disk space available for new workspace.',
+    known: true,
+  },
+  {
+    pattern: 'enospc',
+    message: '**Error:** No disk space available for new workspace.',
+    known: true,
+  },
+  {
+    pattern: 'not a git repository',
+    message: '**Error:** Target path is not a valid git repository.',
+    known: true,
+  },
+  {
+    // Deliberately not `known` — this is a user-input / registration bug,
+    // not an infrastructure failure. Surface classification, but crash.
+    pattern: 'cannot extract owner/repo',
+    message:
+      '**Error:** Repository path is too short to extract owner and repo name. ' +
+      'Re-register the codebase with a full path (e.g. `/home/user/owner/repo`).',
+    known: false,
+  },
+  {
+    pattern: 'branch not found',
+    message:
+      '**Error:** Branch not found. The requested branch may have been deleted or not yet pushed.',
+    known: true,
+  },
+  {
+    pattern: 'no base branch configured',
+    message:
+      '**Error:** No base branch configured. Set `worktree.baseBranch` in `.archon/config.yaml` ' +
+      'or use the `--from` flag to select a branch (e.g., `--from dev`).',
+    known: true,
+  },
+  {
+    pattern: 'belongs to a different clone',
+    message:
+      '**Error:** A worktree at the target path was created by a different local clone. ' +
+      'Remove it from that clone, or register this codebase from the same local path.',
+    known: true,
+  },
+  {
+    pattern: 'cannot verify worktree ownership',
+    message:
+      '**Error:** Cannot verify ownership of an existing worktree at the target path. ' +
+      'Check file system permissions and remove any unrelated git directories at that path.',
+    known: true,
+  },
+  {
+    pattern: 'cannot adopt',
+    message:
+      '**Error:** Refused to adopt an existing directory at the worktree path. ' +
+      'Remove it or choose a different branch/codebase registration.',
+    known: true,
+  },
+  {
+    pattern: 'submodule initialization failed',
+    message:
+      '**Error:** Submodule initialization failed. Check credentials and network access to ' +
+      'submodule remotes, or set `worktree.initSubmodules: false` in `.archon/config.yaml` ' +
+      'to opt out if submodules are not needed for your workflows.',
+    known: true,
+  },
+];
+
 /**
  * Classify isolation creation errors into user-friendly messages.
  */
@@ -23,54 +117,7 @@ export function classifyIsolationError(err: Error): string {
   const stderr = (err as Error & { stderr?: string }).stderr ?? '';
   const errorLower = `${err.message} ${stderr}`.toLowerCase();
 
-  const errorPatterns: { pattern: string; message: string }[] = [
-    {
-      pattern: 'permission denied',
-      message:
-        '**Error:** Permission denied while creating workspace. Check file system permissions.',
-    },
-    {
-      pattern: 'eacces',
-      message:
-        '**Error:** Permission denied while creating workspace. Check file system permissions.',
-    },
-    {
-      pattern: 'timeout',
-      message:
-        '**Error:** Timed out creating workspace. Git repository may be slow or unavailable.',
-    },
-    {
-      pattern: 'no space left',
-      message: '**Error:** No disk space available for new workspace.',
-    },
-    {
-      pattern: 'enospc',
-      message: '**Error:** No disk space available for new workspace.',
-    },
-    {
-      pattern: 'not a git repository',
-      message: '**Error:** Target path is not a valid git repository.',
-    },
-    {
-      pattern: 'cannot extract owner/repo',
-      message:
-        '**Error:** Repository path is too short to extract owner and repo name. ' +
-        'Re-register the codebase with a full path (e.g. `/home/user/owner/repo`).',
-    },
-    {
-      pattern: 'branch not found',
-      message:
-        '**Error:** Branch not found. The requested branch may have been deleted or not yet pushed.',
-    },
-    {
-      pattern: 'no base branch configured',
-      message:
-        '**Error:** No base branch configured. Set `worktree.baseBranch` in `.archon/config.yaml` ' +
-        'or use the `--from` flag to select a branch (e.g., `--from dev`).',
-    },
-  ];
-
-  for (const { pattern, message } of errorPatterns) {
+  for (const { pattern, message } of ERROR_PATTERNS) {
     if (errorLower.includes(pattern)) {
       return message;
     }
@@ -90,16 +137,5 @@ export function isKnownIsolationError(err: Error): boolean {
   const stderr = (err as Error & { stderr?: string }).stderr ?? '';
   const errorLower = `${err.message} ${stderr}`.toLowerCase();
 
-  const knownPatterns = [
-    'permission denied',
-    'eacces',
-    'timeout',
-    'no space left',
-    'enospc',
-    'not a git repository',
-    'branch not found',
-    'no base branch configured',
-  ];
-
-  return knownPatterns.some(pattern => errorLower.includes(pattern));
+  return ERROR_PATTERNS.some(({ pattern, known }) => known && errorLower.includes(pattern));
 }
diff --git a/packages/isolation/src/factory.ts b/packages/isolation/src/factory.ts
index fa55947840..73ac566694 100644
--- a/packages/isolation/src/factory.ts
+++ b/packages/isolation/src/factory.ts
@@ -14,7 +14,7 @@ let configuredLoader: RepoConfigLoader = () => Promise.resolve(null);
 /**
  * Configure the isolation system with a repo config loader.
  * Must be called before getIsolationProvider() for full functionality.
- * If not called, WorktreeProvider uses a no-op loader (no custom baseBranch or copyFiles).
+ * If not called, WorktreeProvider uses a no-op loader (no custom baseBranch, copyFiles, or path).
  */
 export function configureIsolation(loader: RepoConfigLoader): void {
   configuredLoader = loader;
diff --git a/packages/isolation/src/providers/worktree.test.ts b/packages/isolation/src/providers/worktree.test.ts
index bb3afffbda..329717d374 100644
--- a/packages/isolation/src/providers/worktree.test.ts
+++ b/packages/isolation/src/providers/worktree.test.ts
@@ -34,8 +34,12 @@ let syncWorkspaceSpy: Mock<typeof git.syncWorkspace>;
 
 // Mock fs.promises.access for destroy() existence check
 const mockAccess = mock(() => Promise.resolve());
+const mockReadFile = mock(() => Promise.reject(new Error('ENOENT')));
+const mockRm = mock(() => Promise.resolve());
 mock.module('node:fs/promises', () => ({
   access: mockAccess,
+  readFile: mockReadFile,
+  rm: mockRm,
 }));
 
 import { WorktreeProvider } from './worktree';
@@ -69,7 +73,19 @@ describe('WorktreeProvider', () => {
     listWorktreesSpy.mockResolvedValue([]);
     findWorktreeByBranchSpy.mockResolvedValue(null);
     getCanonicalRepoPathSpy.mockImplementation(async path => path);
-    mockAccess.mockResolvedValue(undefined); // Path exists by default
+    // Most paths exist by default (directoryExists checks for destroy etc.),
+    // but .gitmodules is absent by default — most repos don't use submodules,
+    // and default-on submodule init must skip cleanly in that case.
+    mockAccess.mockImplementation(async (path: unknown) => {
+      if (typeof path === 'string' && path.endsWith('.gitmodules')) {
+        const err = new Error('ENOENT') as NodeJS.ErrnoException;
+        err.code = 'ENOENT';
+        throw err;
+      }
+      return undefined;
+    });
+    mockReadFile.mockRejectedValue(new Error('ENOENT')); // .git file not readable by default
+    mockRm.mockResolvedValue(undefined);
 
     // Default mocks for workspace sync
     getDefaultBranchSpy.mockResolvedValue('main');
@@ -92,6 +108,8 @@ describe('WorktreeProvider', () => {
     getDefaultBranchSpy.mockRestore();
     syncWorkspaceSpy.mockRestore();
     mockAccess.mockClear();
+    mockReadFile.mockClear();
+    mockRm.mockClear();
   });
 
   describe('generateBranchName', () => {
@@ -297,16 +315,17 @@ describe('WorktreeProvider', () => {
       );
     });
 
-    test('reuses existing branch when it already exists and no fromBranch', async () => {
+    test('resets and reuses existing branch when it already exists and no fromBranch', async () => {
       const alreadyExistsError = new Error('fatal: branch already exists') as Error & {
         stderr: string;
       };
       alreadyExistsError.stderr =
         "fatal: a branch named 'archon/task-test-adapters' already exists";
 
-      // First call fails, second succeeds (fallback)
+      // First call fails (worktree add -b), second succeeds (branch -f), third succeeds (worktree add)
       execSpy.mockRejectedValueOnce(alreadyExistsError);
       execSpy.mockResolvedValueOnce({ stdout: '', stderr: '' });
+      execSpy.mockResolvedValueOnce({ stdout: '', stderr: '' });
 
       const request: IsolationRequest = {
         ...baseRequest,
@@ -316,6 +335,13 @@ describe('WorktreeProvider', () => {
 
       await provider.create(request);
 
+      // Verify branch was reset to start-point
+      expect(execSpy).toHaveBeenCalledWith(
+        'git',
+        ['-C', '/workspace/repo', 'branch', '-f', 'archon/task-test-adapters', 'origin/main'],
+        expect.any(Object)
+      );
+
       // Fallback call should not include a start-point
       expect(execSpy).toHaveBeenCalledWith(
         'git',
@@ -492,8 +518,10 @@ describe('WorktreeProvider', () => {
       );
     });
 
-    test('adopts existing worktree if found', async () => {
+    test('adopts existing worktree when repo ownership matches', async () => {
       worktreeExistsSpy.mockResolvedValue(true);
+      // .git file points to the same repo root as the request
+      mockReadFile.mockResolvedValue('gitdir: /workspace/repo/.git/worktrees/archon/issue-42\n');
 
       const env = await provider.create(baseRequest);
 
@@ -508,6 +536,56 @@ describe('WorktreeProvider', () => {
       expect(addCalls).toHaveLength(0);
     });
 
+    test('throws when worktree belongs to different repo root (cross-checkout)', async () => {
+      worktreeExistsSpy.mockResolvedValue(true);
+      mockReadFile.mockResolvedValue('gitdir: /different/repo/.git/worktrees/archon/issue-42\n');
+
+      await expect(provider.create(baseRequest)).rejects.toThrow(/belongs to a different clone/);
+    });
+
+    test('throws when .git is a directory (full checkout, not a worktree)', async () => {
+      worktreeExistsSpy.mockResolvedValue(true);
+      const eisdirError = new Error('EISDIR') as NodeJS.ErrnoException;
+      eisdirError.code = 'EISDIR';
+      mockReadFile.mockRejectedValue(eisdirError);
+
+      await expect(provider.create(baseRequest)).rejects.toThrow(
+        /path contains a full git checkout/
+      );
+    });
+
+    test('throws when .git file cannot be read (permission denied)', async () => {
+      worktreeExistsSpy.mockResolvedValue(true);
+      const eaccesError = new Error('EACCES: permission denied') as NodeJS.ErrnoException;
+      eaccesError.code = 'EACCES';
+      mockReadFile.mockRejectedValue(eaccesError);
+
+      await expect(provider.create(baseRequest)).rejects.toThrow(
+        /Cannot verify worktree ownership/
+      );
+    });
+
+    test('throws when .git pointer is not a git-worktree reference (e.g., submodule)', async () => {
+      worktreeExistsSpy.mockResolvedValue(true);
+      mockReadFile.mockResolvedValue('gitdir: /workspace/repo/.git/modules/submodule-name\n');
+
+      await expect(provider.create(baseRequest)).rejects.toThrow(/not a git-worktree reference/);
+    });
+
+    test('adopts across path normalization differences (trailing slash)', async () => {
+      const request: IsolationRequest = {
+        ...baseRequest,
+        canonicalRepoPath: '/workspace/repo/' as IsolationRequest['canonicalRepoPath'],
+      };
+      worktreeExistsSpy.mockResolvedValue(true);
+      // .git file has no trailing slash — resolve() should normalize
+      mockReadFile.mockResolvedValue('gitdir: /workspace/repo/.git/worktrees/archon/issue-42\n');
+
+      const env = await provider.create(request);
+
+      expect(env.metadata).toHaveProperty('adopted', true);
+    });
+
     test('adopts worktree by PR branch name (skill symbiosis)', async () => {
       const request: PRIsolationRequest = {
         codebaseId: 'cb-123',
@@ -522,6 +600,8 @@ describe('WorktreeProvider', () => {
       worktreeExistsSpy.mockResolvedValueOnce(false);
       // findWorktreeByBranch finds existing worktree
       findWorktreeByBranchSpy.mockResolvedValue('/workspace/worktrees/repo/feature-auth');
+      // Same-clone ownership match so adoption proceeds
+      mockReadFile.mockResolvedValue('gitdir: /workspace/repo/.git/worktrees/feature-auth\n');
 
       const env = await provider.create(request);
 
@@ -537,7 +617,26 @@ describe('WorktreeProvider', () => {
       expect(addCalls).toHaveLength(0);
     });
 
-    test('reuses existing branch if it already exists', async () => {
+    test('throws when PR-branch-adopted worktree belongs to a different clone', async () => {
+      const request: PRIsolationRequest = {
+        codebaseId: 'cb-123',
+        canonicalRepoPath: '/workspace/repo',
+        workflowType: 'pr',
+        identifier: '42',
+        prBranch: 'feature/auth',
+        isForkPR: false,
+      };
+
+      // Primary path misses, secondary findWorktreeByBranch hits
+      worktreeExistsSpy.mockResolvedValueOnce(false);
+      findWorktreeByBranchSpy.mockResolvedValue('/workspace/worktrees/repo/feature-auth');
+      // .git points to a different clone
+      mockReadFile.mockResolvedValue('gitdir: /other/clone/.git/worktrees/feature-auth\n');
+
+      await expect(provider.create(request)).rejects.toThrow(/belongs to a different clone/);
+    });
+
+    test('resets stale branch to start-point when it already exists', async () => {
       let callCount = 0;
       execSpy.mockImplementation(async (_cmd: string, args: string[]) => {
         callCount++;
@@ -571,7 +670,14 @@ describe('WorktreeProvider', () => {
         expect.any(Object)
       );
 
-      // Verify second call used existing branch
+      // Verify branch was reset to start-point before checkout
+      expect(execSpy).toHaveBeenCalledWith(
+        'git',
+        ['-C', '/workspace/repo', 'branch', '-f', 'archon/issue-42', 'origin/main'],
+        expect.any(Object)
+      );
+
+      // Verify final call used existing (reset) branch
       expect(execSpy).toHaveBeenCalledWith(
         'git',
         expect.arrayContaining([
@@ -586,6 +692,42 @@ describe('WorktreeProvider', () => {
       );
     });
 
+    test('propagates error if branch -f reset fails (protected branch, etc.)', async () => {
+      execSpy.mockImplementation(async (_cmd: string, args: string[]) => {
+        // First worktree add call fails (branch exists)
+        if (args.includes('worktree') && args.includes('add') && args.includes('-b')) {
+          const error = new Error(
+            'fatal: A branch named archon/issue-42 already exists.'
+          ) as Error & { stderr?: string };
+          error.stderr = 'fatal: A branch named archon/issue-42 already exists.';
+          throw error;
+        }
+        // Reset call fails (e.g., branch checked out elsewhere, update hook refused)
+        if (args.includes('branch') && args.includes('-f')) {
+          const error = new Error('fatal: cannot force update the branch') as Error & {
+            stderr?: string;
+          };
+          error.stderr = "fatal: cannot force update the current branch 'archon/issue-42'";
+          throw error;
+        }
+        return { stdout: '', stderr: '' };
+      });
+
+      await expect(provider.create(baseRequest)).rejects.toThrow(/cannot force update/);
+
+      // Verify we did NOT retry the worktree add after reset failure
+      const secondWorktreeAdd = execSpy.mock.calls.filter((call: unknown[]) => {
+        const args = call[1] as string[];
+        return (
+          args.includes('worktree') &&
+          args.includes('add') &&
+          !args.includes('-b') &&
+          args.includes('archon/issue-42')
+        );
+      });
+      expect(secondWorktreeAdd).toHaveLength(0);
+    });
+
     test('throws error if PR fetch fails (same-repo PR)', async () => {
       const request: IsolationRequest = {
         ...baseRequest,
@@ -816,6 +958,158 @@ describe('WorktreeProvider', () => {
         { recursive: true }
       );
     });
+
+    // Helper: make .gitmodules "exist" (access resolves) while other paths
+    // retain the default behavior set in beforeEach.
+    const makeGitmodulesPresent = (): void => {
+      mockAccess.mockImplementation(async () => undefined);
+    };
+
+    const countSubmoduleExecCalls = (): number =>
+      execSpy.mock.calls.filter((call: unknown[]) => {
+        const args = call[1] as string[];
+        return args.includes('submodule') && args.includes('update');
+      }).length;
+
+    const getSubmoduleCallArgs = (): string[] | undefined =>
+      execSpy.mock.calls.find((call: unknown[]) => {
+        const args = call[1] as string[];
+        return args.includes('submodule') && args.includes('update');
+      })?.[1] as string[] | undefined;
+
+    test('initializes submodules by default when .gitmodules exists', async () => {
+      // Default provider has no initSubmodules in config — should run.
+      makeGitmodulesPresent();
+
+      await provider.create(baseRequest);
+
+      expect(countSubmoduleExecCalls()).toBe(1);
+      expect(getSubmoduleCallArgs()).toEqual(
+        expect.arrayContaining([
+          '-C',
+          expect.any(String),
+          'submodule',
+          'update',
+          '--init',
+          '--recursive',
+        ])
+      );
+    });
+
+    test('initializes submodules when explicitly opted in and .gitmodules exists', async () => {
+      const configLoader: RepoConfigLoader = async () => ({
+        baseBranch: 'main',
+        initSubmodules: true,
+      });
+      const submoduleProvider = new WorktreeProvider(configLoader);
+      makeGitmodulesPresent();
+
+      await submoduleProvider.create(baseRequest);
+
+      expect(countSubmoduleExecCalls()).toBe(1);
+      expect(getSubmoduleCallArgs()).toEqual(
+        expect.arrayContaining(['submodule', 'update', '--init', '--recursive'])
+      );
+    });
+
+    test('skips submodule init when initSubmodules is false', async () => {
+      const configLoader: RepoConfigLoader = async () => ({
+        baseBranch: 'main',
+        initSubmodules: false,
+      });
+      const noSubmoduleProvider = new WorktreeProvider(configLoader);
+      // Even when .gitmodules exists, explicit opt-out must win.
+      makeGitmodulesPresent();
+
+      await noSubmoduleProvider.create(baseRequest);
+
+      expect(countSubmoduleExecCalls()).toBe(0);
+    });
+
+    test('skips submodule init when .gitmodules does not exist', async () => {
+      // Default mock from beforeEach already returns ENOENT for .gitmodules.
+      await provider.create(baseRequest);
+
+      expect(countSubmoduleExecCalls()).toBe(0);
+    });
+
+    test('throws classifiable error when submodule init fails (fail-fast)', async () => {
+      const configLoader: RepoConfigLoader = async () => ({
+        baseBranch: 'main',
+        initSubmodules: true,
+      });
+      const submoduleProvider = new WorktreeProvider(configLoader);
+      makeGitmodulesPresent();
+
+      const gitError = Object.assign(new Error('git submodule update failed'), {
+        stderr: 'fatal: could not read from remote repository',
+      });
+      execSpy.mockImplementation(async (_cmd: string, args: string[]) => {
+        if (args.includes('submodule')) {
+          throw gitError;
+        }
+        return { stdout: '', stderr: '' };
+      });
+
+      // A worktree with uninitialized submodules is a silent broken state;
+      // the error must surface rather than be swallowed.
+      await expect(submoduleProvider.create(baseRequest)).rejects.toThrow(
+        /Submodule initialization failed/
+      );
+    });
+
+    test('throws when .gitmodules read fails with EACCES (fail-fast, no silent skip)', async () => {
+      const configLoader: RepoConfigLoader = async () => ({
+        baseBranch: 'main',
+        initSubmodules: true,
+      });
+      const submoduleProvider = new WorktreeProvider(configLoader);
+
+      // .gitmodules read fails with a non-ENOENT error. Silently skipping
+      // would produce a worktree with empty submodule dirs — the exact
+      // silent-broken-state this feature exists to prevent.
+      mockAccess.mockImplementation(async (path: unknown) => {
+        if (typeof path === 'string' && path.endsWith('.gitmodules')) {
+          const err = new Error('EACCES') as NodeJS.ErrnoException;
+          err.code = 'EACCES';
+          throw err;
+        }
+        return undefined;
+      });
+
+      await expect(submoduleProvider.create(baseRequest)).rejects.toThrow(
+        /Submodule initialization failed: cannot read \.gitmodules \(EACCES\)/
+      );
+      // Skipped the git op since we couldn't even read .gitmodules.
+      expect(countSubmoduleExecCalls()).toBe(0);
+    });
+
+    test('throws classifiable error when submodule init times out', async () => {
+      const configLoader: RepoConfigLoader = async () => ({
+        baseBranch: 'main',
+        initSubmodules: true,
+      });
+      const submoduleProvider = new WorktreeProvider(configLoader);
+      makeGitmodulesPresent();
+
+      // Simulate execFileAsync timeout: the error surface matches what node's
+      // child_process produces when a command exceeds its timeout.
+      const timeoutError = Object.assign(new Error('Command failed: git submodule update'), {
+        killed: true,
+        signal: 'SIGTERM',
+        stderr: '',
+      });
+      execSpy.mockImplementation(async (_cmd: string, args: string[]) => {
+        if (args.includes('submodule')) {
+          throw timeoutError;
+        }
+        return { stdout: '', stderr: '' };
+      });
+
+      await expect(submoduleProvider.create(baseRequest)).rejects.toThrow(
+        /Submodule initialization failed/
+      );
+    });
   });
 
   describe('destroy', () => {
@@ -1474,6 +1768,9 @@ describe('WorktreeProvider', () => {
 
     test('does not copy files when adopting existing worktree', async () => {
       worktreeExistsSpy.mockResolvedValue(true);
+      mockReadFile.mockResolvedValue(
+        'gitdir: /.archon/workspaces/owner/repo/.git/worktrees/archon/issue-42\n'
+      );
       const configLoader: RepoConfigLoader = async () => ({
         copyFiles: ['.env.example -> .env'],
       });
@@ -1623,6 +1920,7 @@ describe('WorktreeProvider', () => {
       // Simulate valid worktree: directory exists and IS a valid worktree
       accessSpy.mockResolvedValue(undefined); // Directory exists
       worktreeExistsSpy.mockResolvedValue(true); // And IS a valid worktree (will be adopted)
+      mockReadFile.mockResolvedValue('gitdir: /workspace/repo/.git/worktrees/archon/issue-999\n');
 
       await provider.create(request);
 
@@ -1918,6 +2216,9 @@ describe('WorktreeProvider', () => {
     test('does not sync workspace when adopting existing worktree', async () => {
       // Worktree exists - triggers adoption path (skips createWorktree)
       worktreeExistsSpy.mockResolvedValue(true);
+      mockReadFile.mockResolvedValue(
+        'gitdir: /workspace/owner/repo/.git/worktrees/archon/issue-42\n'
+      );
 
       await provider.create(baseRequest);
 
@@ -2161,6 +2462,93 @@ describe('WorktreeProvider', () => {
     });
   });
 
+  // ---------------------------------------------------------------------------
+  // Per-repo `worktree.path` override (co-located worktrees opt-in) — #1117 successor
+  // ---------------------------------------------------------------------------
+  describe('worktree.path repo-local override', () => {
+    const baseRequest: IsolationRequest = {
+      codebaseId: 'cb-local-1',
+      codebaseName: 'owner/myapp',
+      canonicalRepoPath: '/Users/dev/Projects/myapp',
+      workflowType: 'task',
+      identifier: 'add-feature',
+    };
+
+    test('uses <repoRoot>/<path>/<branch> when worktree.path is set', () => {
+      const branch = provider.generateBranchName(baseRequest);
+      const result = provider.getWorktreePath(baseRequest, branch, { path: '.worktrees' });
+      expect(result).toBe(join('/Users/dev/Projects/myapp', '.worktrees', branch));
+    });
+
+    test('empty / whitespace-only path is ignored and default layout applies', () => {
+      const branch = provider.generateBranchName(baseRequest);
+      const expectedDefault = join(
+        TEST_ARCHON_HOME,
+        'workspaces',
+        'owner',
+        'myapp',
+        'worktrees',
+        branch
+      );
+      expect(provider.getWorktreePath(baseRequest, branch, { path: '' })).toBe(expectedDefault);
+      expect(provider.getWorktreePath(baseRequest, branch, { path: '   ' })).toBe(expectedDefault);
+    });
+
+    test('null / undefined config falls back to workspace-scoped default', () => {
+      const branch = provider.generateBranchName(baseRequest);
+      const expected = join(TEST_ARCHON_HOME, 'workspaces', 'owner', 'myapp', 'worktrees', branch);
+      expect(provider.getWorktreePath(baseRequest, branch, null)).toBe(expected);
+      expect(provider.getWorktreePath(baseRequest, branch, undefined)).toBe(expected);
+      expect(provider.getWorktreePath(baseRequest, branch)).toBe(expected);
+    });
+
+    test('override wins even when repo lives under ~/.archon/workspaces/', () => {
+      // Precedence contract: per-repo `worktree.path` is the highest layer.
+      // A repo that would normally land in workspaces/owner/repo/worktrees/
+      // still gets a repo-local worktree when the config opts in.
+      const request: IsolationRequest = {
+        codebaseId: 'cb-local-2',
+        codebaseName: 'owner/repo',
+        canonicalRepoPath: join(TEST_ARCHON_HOME, 'workspaces', 'owner', 'repo'),
+        workflowType: 'task',
+        identifier: 'my-task',
+      };
+      const branch = provider.generateBranchName(request);
+      const result = provider.getWorktreePath(request, branch, { path: 'worktrees-local' });
+      expect(result).toBe(
+        join(TEST_ARCHON_HOME, 'workspaces', 'owner', 'repo', 'worktrees-local', branch)
+      );
+    });
+
+    test('rejects an absolute worktree.path with a clear error', () => {
+      const branch = provider.generateBranchName(baseRequest);
+      expect(() =>
+        provider.getWorktreePath(baseRequest, branch, { path: '/tmp/worktrees' })
+      ).toThrow(/must be relative to the repo root/);
+    });
+
+    test('rejects a worktree.path that escapes the repo root via `..`', () => {
+      const branch = provider.generateBranchName(baseRequest);
+      expect(() => provider.getWorktreePath(baseRequest, branch, { path: '../worktrees' })).toThrow(
+        /must stay within the repo/
+      );
+      expect(() => provider.getWorktreePath(baseRequest, branch, { path: '..' })).toThrow(
+        /must stay within the repo/
+      );
+      expect(() =>
+        provider.getWorktreePath(baseRequest, branch, { path: 'nested/../../escape' })
+      ).toThrow(/must stay within the repo/);
+    });
+
+    test('accepts a nested relative path without `..`', () => {
+      const branch = provider.generateBranchName(baseRequest);
+      const result = provider.getWorktreePath(baseRequest, branch, {
+        path: '.archon/worktrees',
+      });
+      expect(result).toBe(join('/Users/dev/Projects/myapp', '.archon/worktrees', branch));
+    });
+  });
+
   // ---------------------------------------------------------------------------
   // Additional lifecycle method tests
   // ---------------------------------------------------------------------------
diff --git a/packages/isolation/src/providers/worktree.ts b/packages/isolation/src/providers/worktree.ts
index 912b550fc5..4d76c721a8 100644
--- a/packages/isolation/src/providers/worktree.ts
+++ b/packages/isolation/src/providers/worktree.ts
@@ -6,25 +6,25 @@
 
 import { createHash } from 'crypto';
 import { access, rm } from 'fs/promises';
-import { join } from 'path';
+import { isAbsolute, join, normalize as normalizePath, resolve, sep } from 'path';
 
 import { createLogger } from '@archon/paths';
 import {
   execFileAsync,
-  extractOwnerRepo,
   findWorktreeByBranch,
   getCanonicalRepoPath,
   getWorktreeBase,
-  isProjectScopedWorktreeBase,
   listWorktrees,
   mkdirAsync,
   removeWorktree,
   syncWorkspace,
+  verifyWorktreeOwnership,
   worktreeExists,
   toRepoPath,
   toWorktreePath,
   toBranchName,
 } from '@archon/git';
+import type { WorktreeBaseOverride } from '@archon/git';
 import { getArchonWorkspacesPath } from '@archon/paths';
 import type { RepoPath, WorktreeInfo } from '@archon/git';
 import { copyWorktreeFiles } from '../worktree-copy';
@@ -48,18 +48,101 @@ function getLog(): ReturnType<typeof createLogger> {
   return cachedLog;
 }
 
+/**
+ * Ceiling for a single git subprocess in worktree operations (create/fetch/checkout/remove/branch-delete).
+ * Generous enough for repos with heavy post-checkout hooks (lint/install) while still catching genuine
+ * hangs (e.g. credential prompts in non-TTY, stalled network fetches). See #1119, #1029.
+ */
+const GIT_OPERATION_TIMEOUT_MS = 5 * 60 * 1000;
+
+/**
+ * Validate a user-supplied `worktree.path` from `.archon/config.yaml` and return
+ * it as a safe relative path for `getWorktreeBase()`, or `undefined` to fall
+ * through to default path resolution.
+ *
+ * Rules (Fail Fast — malformed values throw; empty/whitespace values are ignored):
+ * - `undefined` / empty-after-trim → `undefined` (no override; default resolution applies)
+ * - Absolute path                  → throw (users must configure globally, not per-repo)
+ * - Contains `..` segment          → throw (escapes repo root)
+ * - Resolved path escapes repoRoot → throw (covers symlink / nested `../` edge cases)
+ *
+ * The path is returned trimmed. The caller composes it via `join(repoRoot, result)`.
+ */
+function resolveRepoLocalOverride(
+  rawPath: string | undefined,
+  repoRoot: string
+): string | undefined {
+  if (rawPath === undefined) return undefined;
+  const trimmed = rawPath.trim();
+  if (!trimmed) return undefined;
+
+  if (isAbsolute(trimmed)) {
+    throw new Error(
+      `.archon/config.yaml worktree.path must be relative to the repo root (got absolute: ${trimmed}). ` +
+        'For an absolute location, set ~/.archon/config.yaml paths.worktrees instead.'
+    );
+  }
+
+  const normalized = normalizePath(trimmed);
+  // A plain `..` or anything that starts with `../` or contains `/../` escapes the repo.
+  if (
+    normalized === '..' ||
+    normalized.startsWith('../') ||
+    normalized.startsWith('..\\') ||
+    normalized.includes('/../') ||
+    normalized.includes('\\..\\')
+  ) {
+    throw new Error(
+      `.archon/config.yaml worktree.path must stay within the repo (got: ${trimmed}). ` +
+        'Remove any `..` segments.'
+    );
+  }
+
+  // Double-check via resolved absolute paths — catches edge cases like a path that
+  // normalizes clean but still escapes when joined (e.g. leading `./../` on some platforms).
+  // Uses `path.sep` so the "is inside repoRoot" check works on Windows (\\) as well as POSIX (/).
+  const resolved = resolve(repoRoot, normalized);
+  const repoRootResolved = resolve(repoRoot);
+  if (resolved !== repoRootResolved && !resolved.startsWith(repoRootResolved + sep)) {
+    throw new Error(
+      `.archon/config.yaml worktree.path resolves outside the repo root (got: ${trimmed} → ${resolved}).`
+    );
+  }
+
+  return normalized;
+}
+
 export class WorktreeProvider implements IIsolationProvider {
   readonly providerType = 'worktree';
 
   constructor(private loadConfig: RepoConfigLoader = () => Promise.resolve(null)) {}
 
   /**
-   * Create an isolated environment using git worktrees
+   * Create an isolated environment using git worktrees.
+   *
+   * Config is loaded exactly once here and threaded through the rest of the
+   * `create()` call. A malformed `.archon/config.yaml` fails loudly at this
+   * boundary rather than being swallowed — see CLAUDE.md "Fail Fast + Explicit
+   * Errors". Downstream helpers assume they receive either a valid config
+   * object or `null`, never a second chance to reload.
    */
   async create(request: IsolationRequest): Promise<IsolatedEnvironment> {
+    let repoConfig: WorktreeCreateConfig | null;
+    try {
+      repoConfig = await this.loadConfig(request.canonicalRepoPath);
+    } catch (error) {
+      const err = error as Error;
+      getLog().error({ err, repoPath: request.canonicalRepoPath }, 'repo_config_load_failed');
+      throw new Error(`Failed to load config: ${err.message}`);
+    }
+
     const branchName = toBranchName(this.generateBranchName(request));
-    const worktreePath = this.getWorktreePath(request, branchName);
-    const envId = this.generateEnvId(request);
+    const worktreePath = this.getWorktreePath(request, branchName, repoConfig);
+    // envId is, by contract, the worktree filesystem path (see `destroy()` docstring).
+    // Assign directly from the resolved path to keep the invariant in sync with
+    // the actual directory created below — computing it via a separate helper would
+    // risk divergence if resolution rules change.
+    const envId = worktreePath;
 
     // Check for existing worktree (adoption)
     const existing = await this.findExisting(request, branchName, worktreePath);
@@ -67,8 +150,8 @@ export class WorktreeProvider implements IIsolationProvider {
       return existing;
     }
 
-    // Create new worktree
-    const { warnings } = await this.createWorktree(request, worktreePath, branchName);
+    // Create new worktree (re-uses the already-loaded repoConfig — no double load).
+    const { warnings } = await this.createWorktree(request, worktreePath, branchName, repoConfig);
 
     return {
       id: envId,
@@ -149,7 +232,7 @@ export class WorktreeProvider implements IIsolationProvider {
       gitArgs.push(worktreePath);
 
       try {
-        await execFileAsync('git', gitArgs, { timeout: 30000 });
+        await execFileAsync('git', gitArgs, { timeout: GIT_OPERATION_TIMEOUT_MS });
         result.worktreeRemoved = true;
       } catch (error) {
         if (!this.isWorktreeMissingError(error)) {
@@ -180,6 +263,26 @@ export class WorktreeProvider implements IIsolationProvider {
       }
     }
 
+    // Prune stale worktree references — runs even when path is already gone,
+    // because git may still have a stale ref for a manually-deleted worktree
+    try {
+      await execFileAsync('git', ['-C', repoPath, 'worktree', 'prune'], { timeout: 15000 });
+    } catch (_error) {
+      // Best-effort — pruning failure is not critical
+      getLog().debug({ repoPath }, 'worktree_prune_failed');
+    }
+
+    // Post-removal verification: confirm worktree is actually gone from git
+    if (result.worktreeRemoved) {
+      const stillRegistered = await this.isWorktreeRegistered(repoPath, worktreePath);
+      if (stillRegistered) {
+        result.worktreeRemoved = false;
+        const warning = `Worktree at ${worktreePath} was reported removed but is still registered in git`;
+        getLog().warn({ worktreePath, repoPath }, 'worktree_removal_verification_failed');
+        result.warnings.push(warning);
+      }
+    }
+
     // Delete associated branch if provided (best-effort cleanup)
     if (options?.branchName) {
       result.branchDeleted = await this.deleteBranchTracked(repoPath, options.branchName, result);
@@ -211,6 +314,30 @@ export class WorktreeProvider implements IIsolationProvider {
     );
   }
 
+  /**
+   * Check if a worktree path is still registered in `git worktree list`.
+   * Used for post-removal verification.
+   */
+  private async isWorktreeRegistered(repoPath: string, worktreePath: string): Promise<boolean> {
+    try {
+      const { stdout } = await execFileAsync(
+        'git',
+        ['-C', repoPath, 'worktree', 'list', '--porcelain'],
+        { timeout: 15000 }
+      );
+      // Porcelain output has "worktree <path>" lines with resolved absolute paths
+      const normalizedTarget = resolve(worktreePath);
+      return stdout.split('\n').some(line => {
+        if (!line.startsWith('worktree ')) return false;
+        const listed = line.slice('worktree '.length).trim();
+        return resolve(listed) === normalizedTarget;
+      });
+    } catch (_error) {
+      // If we can't verify, assume it's gone (don't block on verification failure)
+      return false;
+    }
+  }
+
   /**
    * Delete a branch and track the result. Never throws - branch deletion is best-effort.
    * Returns true if branch was deleted or already gone, false if deletion failed.
@@ -221,7 +348,9 @@ export class WorktreeProvider implements IIsolationProvider {
     result: DestroyResult
   ): Promise<boolean> {
     try {
-      await execFileAsync('git', ['-C', repoPath, 'branch', '-D', branchName], { timeout: 30000 });
+      await execFileAsync('git', ['-C', repoPath, 'branch', '-D', branchName], {
+        timeout: GIT_OPERATION_TIMEOUT_MS,
+      });
       getLog().debug({ repoPath, branchName }, 'branch_deleted');
       return true;
     } catch (error) {
@@ -256,7 +385,7 @@ export class WorktreeProvider implements IIsolationProvider {
   ): Promise<boolean> {
     try {
       await execFileAsync('git', ['-C', repoPath, 'push', 'origin', '--delete', branchName], {
-        timeout: 30000,
+        timeout: GIT_OPERATION_TIMEOUT_MS,
       });
       getLog().debug({ repoPath, branchName }, 'remote_branch_deleted');
       return true;
@@ -444,34 +573,29 @@ export class WorktreeProvider implements IIsolationProvider {
   }
 
   /**
-   * Generate unique environment ID
-   */
-  generateEnvId(request: IsolationRequest): string {
-    const branchName = this.generateBranchName(request);
-    return this.getWorktreePath(request, branchName);
-  }
-
-  /**
-   * Get worktree path for request.
+   * Get worktree path for a request, honoring the per-repo override if set.
+   *
+   * Layouts (see `getWorktreeBase()` in `@archon/git` for resolution):
+   *   - `repo-local`       → `<repoRoot>/<config.path>/{branch}`              (opt-in)
+   *   - `workspace-scoped` → `~/.archon/workspaces/{owner}/{repo}/worktrees/{branch}`  (default)
    *
-   * Path format depends on the worktree base layout:
-   * - Project-scoped: `~/.archon/workspaces/{owner}/{repo}/worktrees/{branch}`
-   * - Legacy global:  `~/.archon/worktrees/{owner}/{repo}/{branch}`
+   * In both layouts the resolved base already carries full repo context, so the
+   * caller simply appends the branch name — no owner/repo namespacing here.
    *
-   * When the worktree base is project-scoped (under workspaces/owner/repo/worktrees/),
-   * only append the branch name since the base already includes owner/repo.
-   * When using the legacy global worktrees path, append owner/repo/branch to
-   * avoid collisions between repos.
+   * The per-repo `config.path` is validated via `resolveRepoLocalOverride()`;
+   * unsafe values (absolute, `..` segments, escape-from-repoRoot) throw rather
+   * than silently falling back to the default layout.
    */
-  getWorktreePath(request: IsolationRequest, branchName: string): string {
-    const worktreeBase = getWorktreeBase(request.canonicalRepoPath, request.codebaseName);
-
-    if (isProjectScopedWorktreeBase(request.canonicalRepoPath, request.codebaseName)) {
-      return join(worktreeBase, branchName);
-    }
-
-    const { owner, repo } = this.extractOwnerRepo(request.canonicalRepoPath);
-    return join(worktreeBase, owner, repo, branchName);
+  getWorktreePath(
+    request: IsolationRequest,
+    branchName: string,
+    config?: WorktreeCreateConfig | null
+  ): string {
+    const override: WorktreeBaseOverride = {
+      repoLocal: resolveRepoLocalOverride(config?.path, request.canonicalRepoPath),
+    };
+    const { base } = getWorktreeBase(request.canonicalRepoPath, request.codebaseName, override);
+    return join(base, branchName);
   }
 
   /**
@@ -484,6 +608,28 @@ export class WorktreeProvider implements IIsolationProvider {
   ): Promise<WorktreeEnvironment | null> {
     // Check if worktree already exists at expected path
     if (await worktreeExists(toWorktreePath(worktreePath))) {
+      // Verify the existing worktree belongs to the same repo root before
+      // adopting. Two clones of the same remote resolve to the same worktree
+      // base dir, so a worktree created from clone A is visible from clone B.
+      // Throws on cross-checkout or unverifiable state — surfacing the problem
+      // is safer than falling through to createNewBranch (which would report
+      // a confusing "branch already exists" cascade) or silently adopting.
+      try {
+        await verifyWorktreeOwnership(toWorktreePath(worktreePath), request.canonicalRepoPath);
+      } catch (err) {
+        getLog().warn(
+          {
+            worktreePath,
+            branchName,
+            codebaseId: request.codebaseId,
+            canonicalRepoPath: request.canonicalRepoPath,
+            err: (err as Error).message,
+          },
+          'worktree.adoption_refused_cross_checkout'
+        );
+        throw err;
+      }
+
       getLog().info({ worktreePath, branchName }, 'worktree_adopted');
       return this.buildAdoptedEnvironment(worktreePath, branchName, request);
     }
@@ -495,6 +641,25 @@ export class WorktreeProvider implements IIsolationProvider {
         request.prBranch
       );
       if (existingByBranch) {
+        // Same cross-clone guard as the primary adoption path above — a
+        // worktree matching the PR branch might still belong to a different
+        // clone of the same remote.
+        try {
+          await verifyWorktreeOwnership(existingByBranch, request.canonicalRepoPath);
+        } catch (err) {
+          getLog().warn(
+            {
+              worktreePath: existingByBranch,
+              branchName: request.prBranch,
+              codebaseId: request.codebaseId,
+              canonicalRepoPath: request.canonicalRepoPath,
+              err: (err as Error).message,
+            },
+            'worktree.adoption_refused_cross_checkout'
+          );
+          throw err;
+        }
+
         getLog().info(
           { worktreePath: existingByBranch, branchName: request.prBranch },
           'worktree_adopted'
@@ -526,35 +691,30 @@ export class WorktreeProvider implements IIsolationProvider {
   /**
    * Create the actual worktree.
    * Returns warnings that should be surfaced to the user (non-fatal issues).
+   *
+   * `repoConfig` is the already-loaded config from `create()`. Receiving it here
+   * keeps the work of each public entrypoint tied to exactly one config load —
+   * see the "Fail Fast" comment on `create()`.
    */
   private async createWorktree(
     request: IsolationRequest,
     worktreePath: string,
-    branchName: string
+    branchName: string,
+    worktreeConfig: WorktreeCreateConfig | null
   ): Promise<{ warnings: string[] }> {
     const repoPath = request.canonicalRepoPath;
 
-    let worktreeConfig: WorktreeCreateConfig | null;
-    try {
-      worktreeConfig = await this.loadConfig(repoPath);
-    } catch (error) {
-      const err = error as Error;
-      getLog().error({ err, repoPath }, 'repo_config_load_failed');
-      throw new Error(`Failed to load config: ${err.message}`);
-    }
-
     // Sync uses only the configured base branch (or auto-detects via getDefaultBranch).
     // request.fromBranch is the start-point for worktree creation, not a sync target.
     const baseBranch = await this.syncWorkspaceBeforeCreate(repoPath, worktreeConfig?.baseBranch);
 
-    const worktreeBase = getWorktreeBase(repoPath, request.codebaseName);
-
-    if (isProjectScopedWorktreeBase(repoPath, request.codebaseName)) {
-      await mkdirAsync(worktreeBase, { recursive: true });
-    } else {
-      const { owner, repo } = this.extractOwnerRepo(repoPath);
-      await mkdirAsync(join(worktreeBase, owner, repo), { recursive: true });
-    }
+    const override: WorktreeBaseOverride = {
+      repoLocal: resolveRepoLocalOverride(worktreeConfig?.path, repoPath),
+    };
+    const { base: worktreeBase } = getWorktreeBase(repoPath, request.codebaseName, override);
+    // In both layouts the base already carries repo context — creating it
+    // recursively is enough.
+    await mkdirAsync(worktreeBase, { recursive: true });
 
     if (isPRIsolationRequest(request)) {
       // For PRs: fetch and checkout the PR branch (actual or synthetic)
@@ -564,6 +724,14 @@ export class WorktreeProvider implements IIsolationProvider {
       await this.createNewBranch(request, repoPath, worktreePath, branchName, baseBranch);
     }
 
+    // Initialize submodules unless explicitly opted out. The check is free
+    // when `.gitmodules` is absent (access-based short-circuit), so repos
+    // without submodules pay nothing. Default-on matches git's own intent
+    // with `clone --recurse-submodules` / `submodule.recurse`.
+    if (worktreeConfig?.initSubmodules !== false) {
+      await this.initSubmodules(worktreePath);
+    }
+
     // Copy git-ignored files based on repo config
     const { configLoadFailed } = await this.copyConfiguredFiles(
       repoPath,
@@ -756,7 +924,7 @@ export class WorktreeProvider implements IIsolationProvider {
   ): Promise<void> {
     // Fetch the PR's actual branch
     await execFileAsync('git', ['-C', repoPath, 'fetch', 'origin', prBranch], {
-      timeout: 30000,
+      timeout: GIT_OPERATION_TIMEOUT_MS,
     });
 
     // Try to create worktree with the branch
@@ -765,14 +933,14 @@ export class WorktreeProvider implements IIsolationProvider {
       await execFileAsync(
         'git',
         ['-C', repoPath, 'worktree', 'add', worktreePath, '-b', prBranch, `origin/${prBranch}`],
-        { timeout: 30000 }
+        { timeout: GIT_OPERATION_TIMEOUT_MS }
       );
     } catch (error) {
       const err = error as Error & { stderr?: string };
       // Branch already exists locally - use it directly
       if (err.stderr?.includes('already exists')) {
         await execFileAsync('git', ['-C', repoPath, 'worktree', 'add', worktreePath, prBranch], {
-          timeout: 30000,
+          timeout: GIT_OPERATION_TIMEOUT_MS,
         });
       } else {
         throw error;
@@ -784,7 +952,7 @@ export class WorktreeProvider implements IIsolationProvider {
       await execFileAsync(
         'git',
         ['-C', worktreePath, 'branch', '--set-upstream-to', `origin/${prBranch}`],
-        { timeout: 30000 }
+        { timeout: GIT_OPERATION_TIMEOUT_MS }
       );
     } catch (trackingError) {
       getLog().warn({ err: trackingError, worktreePath, prBranch }, 'upstream_tracking_failed');
@@ -809,11 +977,11 @@ export class WorktreeProvider implements IIsolationProvider {
     if (prSha) {
       // SHA provided: create at specific commit for reproducible reviews
       await execFileAsync('git', ['-C', repoPath, 'fetch', 'origin', `pull/${prNumber}/head`], {
-        timeout: 30000,
+        timeout: GIT_OPERATION_TIMEOUT_MS,
       });
 
       await execFileAsync('git', ['-C', repoPath, 'worktree', 'add', worktreePath, prSha], {
-        timeout: 30000,
+        timeout: GIT_OPERATION_TIMEOUT_MS,
       });
 
       // Create a local tracking branch so it's not detached HEAD
@@ -821,7 +989,7 @@ export class WorktreeProvider implements IIsolationProvider {
         repoPath,
         () =>
           execFileAsync('git', ['-C', worktreePath, 'checkout', '-b', reviewBranch, prSha], {
-            timeout: 30000,
+            timeout: GIT_OPERATION_TIMEOUT_MS,
           }),
         reviewBranch
       );
@@ -833,13 +1001,13 @@ export class WorktreeProvider implements IIsolationProvider {
           execFileAsync(
             'git',
             ['-C', repoPath, 'fetch', 'origin', `pull/${prNumber}/head:${reviewBranch}`],
-            { timeout: 30000 }
+            { timeout: GIT_OPERATION_TIMEOUT_MS }
           ),
         reviewBranch
       );
 
       await execFileAsync('git', ['-C', repoPath, 'worktree', 'add', worktreePath, reviewBranch], {
-        timeout: 30000,
+        timeout: GIT_OPERATION_TIMEOUT_MS,
       });
     }
   }
@@ -860,7 +1028,7 @@ export class WorktreeProvider implements IIsolationProvider {
       if (err.stderr?.includes('already exists')) {
         getLog().debug({ repoPath, branchName }, 'stale_branch_retry');
         await execFileAsync('git', ['-C', repoPath, 'branch', '-D', branchName], {
-          timeout: 30000,
+          timeout: GIT_OPERATION_TIMEOUT_MS,
         });
         await createCommand();
       } else {
@@ -894,12 +1062,12 @@ export class WorktreeProvider implements IIsolationProvider {
         'git',
         ['-C', repoPath, 'worktree', 'add', worktreePath, '-b', branchName, startPoint],
         {
-          timeout: 30000,
+          timeout: GIT_OPERATION_TIMEOUT_MS,
         }
       );
     } catch (error) {
       const err = error as Error & { stderr?: string };
-      // Branch already exists - use existing branch
+      // Branch already exists - reset to intended start-point and use it
       if (err.stderr?.includes('already exists')) {
         const taskFromBranch = request.workflowType === 'task' ? request.fromBranch : undefined;
         if (taskFromBranch) {
@@ -910,8 +1078,19 @@ export class WorktreeProvider implements IIsolationProvider {
               'Either choose a different --branch name or omit --from.'
           );
         }
+
+        // Branch exists but no explicit start-point override — reset it to the
+        // intended start-point before checking out, so we don't inherit stale
+        // commits from a previous run or external tool.
+        getLog().warn(
+          { branchName, startPoint, repoPath },
+          'worktree.branch_exists_resetting_to_start_point'
+        );
+        await execFileAsync('git', ['-C', repoPath, 'branch', '-f', branchName, startPoint], {
+          timeout: 10000,
+        });
         await execFileAsync('git', ['-C', repoPath, 'worktree', 'add', worktreePath, branchName], {
-          timeout: 30000,
+          timeout: GIT_OPERATION_TIMEOUT_MS,
         });
       } else {
         throw error;
@@ -919,6 +1098,45 @@ export class WorktreeProvider implements IIsolationProvider {
     }
   }
 
+  /**
+   * Initialize git submodules in a worktree when the repo uses them.
+   *
+   * ENOENT on `.gitmodules` → skip (zero-cost for non-submodule repos).
+   * Any other error (EACCES, EIO, git failure, timeout) → throw. Silent
+   * success on a half-initialized worktree is the exact class of bug this
+   * function exists to prevent; an unreadable `.gitmodules` is materially
+   * the same as a failed git op. The thrown error is classified by
+   * `classifyIsolationError` into an actionable message.
+   */
+  private async initSubmodules(worktreePath: string): Promise<void> {
+    try {
+      await access(join(worktreePath, '.gitmodules'));
+    } catch (error) {
+      const err = error as NodeJS.ErrnoException;
+      if (err.code === 'ENOENT') {
+        return;
+      }
+      getLog().error({ err, worktreePath }, 'worktree.submodule_check_failed');
+      throw new Error(
+        `Submodule initialization failed: cannot read .gitmodules (${err.code ?? 'unknown error'})`
+      );
+    }
+
+    try {
+      await execFileAsync(
+        'git',
+        ['-C', worktreePath, 'submodule', 'update', '--init', '--recursive'],
+        { timeout: 120000 }
+      );
+      getLog().info({ worktreePath }, 'worktree.submodule_init_completed');
+    } catch (error) {
+      const err = error as Error & { stderr?: string };
+      getLog().error({ err, worktreePath }, 'worktree.submodule_init_failed');
+      const detail = err.stderr?.trim() || err.message;
+      throw new Error(`Submodule initialization failed: ${detail}`);
+    }
+  }
+
   /**
    * Check if a directory exists.
    * Returns true if directory exists, false if it doesn't exist (ENOENT).
@@ -988,14 +1206,6 @@ export class WorktreeProvider implements IIsolationProvider {
     }
   }
 
-  /**
-   * Extract owner and repo name from a repository path.
-   * Used for legacy global worktree base layout where owner/repo must be appended.
-   */
-  private extractOwnerRepo(repoPath: string): { owner: string; repo: string } {
-    return extractOwnerRepo(toRepoPath(repoPath));
-  }
-
   /**
    * Generate short hash for thread identifiers
    */
diff --git a/packages/isolation/src/resolver.test.ts b/packages/isolation/src/resolver.test.ts
index ccc250e6dc..2f86d24726 100644
--- a/packages/isolation/src/resolver.test.ts
+++ b/packages/isolation/src/resolver.test.ts
@@ -86,6 +86,7 @@ describe('IsolationResolver', () => {
   let getCanonicalSpy: ReturnType<typeof spyOn>;
   let findWorktreeByBranchSpy: ReturnType<typeof spyOn>;
   let isAncestorOfSpy: ReturnType<typeof spyOn>;
+  let verifyWorktreeOwnershipSpy: ReturnType<typeof spyOn>;
 
   beforeEach(() => {
     worktreeExistsSpy = spyOn(git, 'worktreeExists').mockResolvedValue(true);
@@ -94,6 +95,9 @@ describe('IsolationResolver', () => {
     );
     findWorktreeByBranchSpy = spyOn(git, 'findWorktreeByBranch').mockResolvedValue(null);
     isAncestorOfSpy = spyOn(git, 'isAncestorOf').mockResolvedValue(true);
+    // Default: ownership verification passes. Tests that exercise cross-clone
+    // behavior override this with a rejection.
+    verifyWorktreeOwnershipSpy = spyOn(git, 'verifyWorktreeOwnership').mockResolvedValue(undefined);
   });
 
   afterEach(() => {
@@ -101,6 +105,7 @@ describe('IsolationResolver', () => {
     getCanonicalSpy.mockRestore();
     findWorktreeByBranchSpy.mockRestore();
     isAncestorOfSpy.mockRestore();
+    verifyWorktreeOwnershipSpy.mockRestore();
   });
 
   function createResolver(overrides?: Partial<IsolationResolverDeps>): IsolationResolver {
@@ -792,4 +797,240 @@ describe('IsolationResolver', () => {
 
     expect(isAncestorOfSpy).not.toHaveBeenCalled();
   });
+
+  // -------------------------------------------------------------------------
+  // Cross-checkout ownership guard (#1183, #1188 part 1)
+  //
+  // Two clones of the same remote share codebase_id because identity is
+  // derived from owner/repo. Without these guards, clone B would adopt
+  // worktrees owned by clone A via the DB-driven resolver paths, bypassing
+  // the WorktreeProvider.findExisting guard.
+  // -------------------------------------------------------------------------
+  describe('cross-checkout guard', () => {
+    test('findReusable throws when worktree belongs to a different clone', async () => {
+      const env = makeEnvRow();
+      const updateStatusSpy = mock(() => Promise.resolve());
+      const resolver = createResolver({
+        store: makeMockStore({
+          findActiveByWorkflow: async () => env,
+          updateStatus: updateStatusSpy,
+        }),
+      });
+      // .git file points to a different clone than request.canonicalRepoPath
+      verifyWorktreeOwnershipSpy.mockRejectedValue(
+        new Error(
+          'Worktree at /worktrees/issue-42 belongs to a different clone (/other/clone). ' +
+            'Remove it from that clone or use a different codebase registration.'
+        )
+      );
+
+      await expect(
+        resolver.resolve({
+          existingEnvId: null,
+          codebase: defaultCodebase,
+          hints: { workflowType: 'issue', workflowId: '42' },
+          platformType: 'web',
+        })
+      ).rejects.toThrow(/belongs to a different clone/);
+
+      // DB row is preserved — it legitimately belongs to the other clone
+      expect(updateStatusSpy).not.toHaveBeenCalled();
+    });
+
+    test('findReusable succeeds when worktree belongs to the same clone', async () => {
+      const env = makeEnvRow();
+      const resolver = createResolver({
+        store: makeMockStore({ findActiveByWorkflow: async () => env }),
+      });
+      // Default ownership spy resolves — same-clone match
+
+      const result = await resolver.resolve({
+        existingEnvId: null,
+        codebase: defaultCodebase,
+        hints: { workflowType: 'issue', workflowId: '42' },
+        platformType: 'web',
+      });
+
+      expect(result.status).toBe('resolved');
+      if (result.status === 'resolved') {
+        expect(result.method.type).toBe('workflow_reuse');
+      }
+      expect(verifyWorktreeOwnershipSpy).toHaveBeenCalledWith(
+        '/worktrees/issue-42',
+        '/repos/myrepo'
+      );
+    });
+
+    test('findLinkedIssueEnv throws when linked env belongs to a different clone', async () => {
+      const linkedEnv = makeEnvRow({
+        workflow_type: 'issue',
+        workflow_id: '100',
+        working_path: '/worktrees/issue-100',
+        branch_name: 'issue-100',
+      });
+      const updateStatusSpy = mock(() => Promise.resolve());
+      const resolver = createResolver({
+        store: makeMockStore({
+          // First path (findReusable) misses — no active env for requested workflowId
+          // Second path (findLinkedIssueEnv) returns linkedEnv for issue 100
+          findActiveByWorkflow: async (_c, type, id) =>
+            type === 'issue' && id === '100' ? linkedEnv : null,
+          updateStatus: updateStatusSpy,
+        }),
+      });
+      verifyWorktreeOwnershipSpy.mockRejectedValue(
+        new Error(
+          'Worktree at /worktrees/issue-100 belongs to a different clone (/other/clone). ' +
+            'Remove it from that clone or use a different codebase registration.'
+        )
+      );
+
+      await expect(
+        resolver.resolve({
+          existingEnvId: null,
+          codebase: defaultCodebase,
+          hints: {
+            workflowType: 'thread',
+            workflowId: 'some-thread',
+            linkedIssues: [100],
+          },
+          platformType: 'web',
+        })
+      ).rejects.toThrow(/belongs to a different clone/);
+
+      // Linked DB row preserved — belongs to the other clone
+      expect(updateStatusSpy).not.toHaveBeenCalled();
+    });
+
+    test('findLinkedIssueEnv succeeds when linked env belongs to the same clone', async () => {
+      const linkedEnv = makeEnvRow({
+        workflow_type: 'issue',
+        workflow_id: '100',
+        working_path: '/worktrees/issue-100',
+        branch_name: 'issue-100',
+      });
+      const resolver = createResolver({
+        store: makeMockStore({
+          findActiveByWorkflow: async (_c, type, id) =>
+            type === 'issue' && id === '100' ? linkedEnv : null,
+        }),
+      });
+      // Default ownership spy resolves — same-clone match
+
+      const result = await resolver.resolve({
+        existingEnvId: null,
+        codebase: defaultCodebase,
+        hints: {
+          workflowType: 'thread',
+          workflowId: 'some-thread',
+          linkedIssues: [100],
+        },
+        platformType: 'web',
+      });
+
+      expect(result.status).toBe('resolved');
+      if (result.status === 'resolved') {
+        expect(result.method.type).toBe('linked_issue_reuse');
+      }
+    });
+
+    test('tryBranchAdoption throws when discovered worktree belongs to a different clone', async () => {
+      findWorktreeByBranchSpy.mockResolvedValue('/worktrees/feature-auth');
+      verifyWorktreeOwnershipSpy.mockRejectedValue(
+        new Error(
+          'Worktree at /worktrees/feature-auth belongs to a different clone (/other/clone). ' +
+            'Remove it from that clone or use a different codebase registration.'
+        )
+      );
+      const createSpy = mock(async () => makeEnvRow());
+      const resolver = createResolver({ store: makeMockStore({ create: createSpy }) });
+
+      await expect(
+        resolver.resolve({
+          existingEnvId: null,
+          codebase: defaultCodebase,
+          hints: {
+            workflowType: 'pr',
+            workflowId: 'pr-42',
+            prBranch: git.toBranchName('feature-auth'),
+          },
+          platformType: 'web',
+        })
+      ).rejects.toThrow(/belongs to a different clone/);
+
+      // Symmetry with paths 1+2: no DB mutation on cross-clone rejection.
+      // Here it's create (vs updateStatus) because tryBranchAdoption writes
+      // a new row rather than reusing an existing one.
+      expect(createSpy).not.toHaveBeenCalled();
+    });
+
+    test('tryBranchAdoption succeeds when discovered worktree belongs to the same clone', async () => {
+      findWorktreeByBranchSpy.mockResolvedValue('/worktrees/feature-auth');
+      // Default ownership spy resolves — same-clone match
+
+      const resolver = createResolver();
+
+      const result = await resolver.resolve({
+        existingEnvId: null,
+        codebase: defaultCodebase,
+        hints: {
+          workflowType: 'pr',
+          workflowId: 'pr-42',
+          prBranch: git.toBranchName('feature-auth'),
+        },
+        platformType: 'web',
+      });
+
+      expect(result.status).toBe('resolved');
+      if (result.status === 'resolved') {
+        expect(result.method.type).toBe('branch_adoption');
+      }
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Canonical path resolution failures
+  //
+  // getCanonicalRepoPath() runs early in resolve() (before any adoption path)
+  // because every downstream step needs the canonical repo root. Failures
+  // must mirror createNewEnvironment's contract: known infrastructure errors
+  // become a `blocked` result; unknown errors propagate as crashes.
+  // -------------------------------------------------------------------------
+  describe('canonical path resolution failure handling', () => {
+    test('known infrastructure error returns blocked with classified user message', async () => {
+      const eaccesError = new Error('EACCES: permission denied') as NodeJS.ErrnoException;
+      eaccesError.code = 'EACCES';
+      getCanonicalSpy.mockRejectedValue(eaccesError);
+
+      const resolver = createResolver();
+
+      const result = await resolver.resolve({
+        existingEnvId: null,
+        codebase: defaultCodebase,
+        platformType: 'web',
+      });
+
+      expect(result.status).toBe('blocked');
+      if (result.status === 'blocked') {
+        expect(result.reason).toBe('creation_failed');
+        expect(result.userMessage).toMatch(/Permission denied/);
+        expect(result.userMessage).toMatch(/Execution blocked/);
+      }
+    });
+
+    test('unknown error propagates as crash (programming bug visibility)', async () => {
+      // Deliberately not a known isolation pattern so isKnownIsolationError returns false
+      getCanonicalSpy.mockRejectedValue(new Error('Internal invariant violation: foo'));
+
+      const resolver = createResolver();
+
+      await expect(
+        resolver.resolve({
+          existingEnvId: null,
+          codebase: defaultCodebase,
+          platformType: 'web',
+        })
+      ).rejects.toThrow(/Internal invariant violation/);
+    });
+  });
 });
diff --git a/packages/isolation/src/resolver.ts b/packages/isolation/src/resolver.ts
index 8ed57b07f9..529507dc87 100644
--- a/packages/isolation/src/resolver.ts
+++ b/packages/isolation/src/resolver.ts
@@ -14,8 +14,9 @@ import {
   findWorktreeByBranch,
   toBranchName,
   isAncestorOf,
+  verifyWorktreeOwnership,
 } from '@archon/git';
-import type { RepoPath, BranchName } from '@archon/git';
+import type { RepoPath, BranchName, WorktreePath } from '@archon/git';
 
 import type {
   IIsolationProvider,
@@ -105,8 +106,50 @@ export class IsolationResolver {
     const workflowType: IsolationWorkflowType = hints?.workflowType ?? 'thread';
     const workflowId = hints?.workflowId ?? '';
 
+    // Compute canonical repo path once — paths 3-6 all need it either for
+    // ownership verification (cross-clone guard) or for worktree creation.
+    // Mirror createNewEnvironment's contract: known infrastructure failures
+    // (permission denied, ENOENT, malformed worktree pointer, etc.) become
+    // a `blocked` result with an actionable user message; unknown failures
+    // propagate so they surface as crashes rather than silent isolation
+    // failures.
+    let canonicalPath: RepoPath;
+    try {
+      canonicalPath = await getCanonicalRepoPath(codebase.defaultCwd);
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      getLog().error(
+        {
+          err,
+          errorType: err.constructor.name,
+          codebaseId: codebase.id,
+          defaultCwd: codebase.defaultCwd,
+        },
+        'isolation.canonical_repo_path_resolution_failed'
+      );
+
+      if (!isKnownIsolationError(err)) {
+        throw err;
+      }
+
+      const userMessage = classifyIsolationError(err);
+      return {
+        status: 'blocked',
+        reason: 'creation_failed',
+        userMessage:
+          userMessage +
+          ' Execution blocked to prevent changes to shared codebase. Please resolve the issue and try again.',
+      };
+    }
+
     // 3. Check for existing environment with same workflow
-    const reusable = await this.findReusable(codebase.id, workflowType, workflowId, baseBranch);
+    const reusable = await this.findReusable(
+      codebase.id,
+      canonicalPath,
+      workflowType,
+      workflowId,
+      baseBranch
+    );
     if (reusable) {
       return {
         status: 'resolved',
@@ -119,7 +162,7 @@ export class IsolationResolver {
 
     // 4. Check linked issues for sharing
     if (hints?.linkedIssues?.length) {
-      const linked = await this.findLinkedIssueEnv(codebase.id, hints.linkedIssues);
+      const linked = await this.findLinkedIssueEnv(codebase.id, canonicalPath, hints.linkedIssues);
       if (linked) return linked;
     }
 
@@ -127,6 +170,7 @@ export class IsolationResolver {
     if (hints?.prBranch) {
       const adopted = await this.tryBranchAdoption(
         codebase,
+        canonicalPath,
         hints,
         workflowType,
         workflowId,
@@ -136,7 +180,6 @@ export class IsolationResolver {
     }
 
     // 6. Create new environment
-    const canonicalPath = await getCanonicalRepoPath(codebase.defaultCwd);
     return this.createNewEnvironment(
       codebase,
       workflowType,
@@ -205,11 +248,43 @@ export class IsolationResolver {
     return null;
   }
 
+  /**
+   * Verify that an on-disk worktree belongs to the expected repo before
+   * adopting. Wraps the shared `verifyWorktreeOwnership` with logging that
+   * includes structured fields for incident debugging — the error message
+   * alone is not enough because stack traces and call sites vary.
+   *
+   * Throws on mismatch (re-throws the original error so `classifyIsolationError`
+   * and `isKnownIsolationError` pattern-match against the user-facing message).
+   */
+  private async assertWorktreeOwnership(
+    worktreePath: WorktreePath,
+    canonicalRepoPath: RepoPath,
+    logContext: Record<string, unknown>,
+    logEvent: string
+  ): Promise<void> {
+    try {
+      await verifyWorktreeOwnership(worktreePath, canonicalRepoPath);
+    } catch (err) {
+      getLog().warn(
+        { ...logContext, worktreePath, canonicalRepoPath, err: (err as Error).message },
+        logEvent
+      );
+      throw err;
+    }
+  }
+
   /**
    * Find a reusable environment by workflow identity.
+   *
+   * Verifies that the on-disk worktree belongs to `canonicalRepoPath` before
+   * returning. On cross-clone mismatch, throws — the DB row belongs to the
+   * other clone and we must not adopt it. The other clone's row is preserved
+   * (no markDestroyed) so the other clone's work continues.
    */
   private async findReusable(
     codebaseId: string,
+    canonicalRepoPath: RepoPath,
     workflowType: IsolationWorkflowType,
     workflowId: string,
     baseBranch?: BranchName
@@ -217,7 +292,15 @@ export class IsolationResolver {
     const existing = await this.store.findActiveByWorkflow(codebaseId, workflowType, workflowId);
     if (!existing) return null;
 
-    if (await worktreeExists(toWorktreePath(existing.working_path))) {
+    const worktreePath = toWorktreePath(existing.working_path);
+    if (await worktreeExists(worktreePath)) {
+      await this.assertWorktreeOwnership(
+        worktreePath,
+        canonicalRepoPath,
+        { codebaseId, workflowType, workflowId },
+        'isolation.reuse_refused_cross_checkout'
+      );
+
       getLog().debug({ workflowType, workflowId }, 'isolation_reuse_existing');
       const warnings = await this.collectBaseBranchWarnings(existing, baseBranch, {
         workflowType,
@@ -232,9 +315,17 @@ export class IsolationResolver {
 
   /**
    * Find an environment linked to one of the given issue numbers.
+   *
+   * Verifies each candidate worktree belongs to `canonicalRepoPath` before
+   * adopting. On cross-clone mismatch, throws — this stops iteration over any
+   * remaining linked issues. Intentional: if a linked env is owned by another
+   * clone, the user's machine state is anomalous (two clones of the same
+   * remote) and they should resolve it explicitly rather than have us skip
+   * past the signal. For the 99% single-clone case, this path always succeeds.
    */
   private async findLinkedIssueEnv(
     codebaseId: string,
+    canonicalRepoPath: RepoPath,
     linkedIssues: number[]
   ): Promise<IsolationResolution | null> {
     for (const issueNum of linkedIssues) {
@@ -245,7 +336,15 @@ export class IsolationResolver {
       );
       if (!linkedEnv) continue;
 
-      if (await worktreeExists(toWorktreePath(linkedEnv.working_path))) {
+      const worktreePath = toWorktreePath(linkedEnv.working_path);
+      if (await worktreeExists(worktreePath)) {
+        await this.assertWorktreeOwnership(
+          worktreePath,
+          canonicalRepoPath,
+          { codebaseId, issueNum },
+          'isolation.linked_issue_refused_cross_checkout'
+        );
+
         getLog().debug({ issueNum, codebaseId }, 'isolation_share_linked_issue');
         return {
           status: 'resolved',
@@ -262,9 +361,14 @@ export class IsolationResolver {
 
   /**
    * Try adopting an existing worktree matching a PR branch.
+   *
+   * Verifies ownership of the discovered worktree before recording it in the
+   * DB. On cross-clone mismatch, throws — adopting another clone's worktree
+   * would create a stale DB row pointing at someone else's filesystem state.
    */
   private async tryBranchAdoption(
     codebase: ResolveRequest['codebase'] & object,
+    canonicalRepoPath: RepoPath,
     hints: IsolationHints,
     workflowType: IsolationWorkflowType,
     workflowId: string,
@@ -273,9 +377,15 @@ export class IsolationResolver {
     const prBranch = hints.prBranch;
     if (!prBranch) return null;
 
-    const canonicalPath = await getCanonicalRepoPath(codebase.defaultCwd);
-    const adoptedPath = await findWorktreeByBranch(canonicalPath, prBranch);
+    const adoptedPath = await findWorktreeByBranch(canonicalRepoPath, prBranch);
     if (adoptedPath && (await worktreeExists(adoptedPath))) {
+      await this.assertWorktreeOwnership(
+        adoptedPath,
+        canonicalRepoPath,
+        { codebaseId: codebase.id, prBranch },
+        'isolation.branch_adoption_refused_cross_checkout'
+      );
+
       getLog().info({ adoptedPath, prBranch }, 'isolation_worktree_adopted');
       const env = await this.store.create({
         codebase_id: codebase.id,
diff --git a/packages/isolation/src/types.ts b/packages/isolation/src/types.ts
index 9ff01ec640..b369ffd7ad 100644
--- a/packages/isolation/src/types.ts
+++ b/packages/isolation/src/types.ts
@@ -242,6 +242,25 @@ export interface IsolationEnvironmentRow {
 export interface WorktreeCreateConfig {
   baseBranch?: string;
   copyFiles?: string[];
+  /**
+   * Initialize git submodules in the worktree. Defaults to enabled — a worktree
+   * with uninitialized submodules is a silent broken state for monorepos.
+   * Set to `false` to opt out. No-op when `.gitmodules` is absent.
+   */
+  initSubmodules?: boolean;
+  /**
+   * Per-project relative path (from repo root) where worktrees should be created.
+   * When set, worktrees live at `<repoRoot>/<path>/<branch>` with `repo-local` layout.
+   * Highest priority in path resolution — overrides project-scoped and global defaults.
+   *
+   * Must be a safe relative path: no leading `/`, no `..` segments, non-empty after trim.
+   * Validation is enforced in `WorktreeProvider.getWorktreePath()` (fails fast with a
+   * clear error rather than silently falling back).
+   *
+   * Sourced from `.archon/config.yaml > worktree.path` in the repo.
+   * @example '.worktrees'
+   */
+  path?: string;
 }
 
 export type RepoConfigLoader = (repoPath: string) => Promise<WorktreeCreateConfig | null>;
diff --git a/packages/paths/package.json b/packages/paths/package.json
index 19267ebaed..4fe6345982 100644
--- a/packages/paths/package.json
+++ b/packages/paths/package.json
@@ -1,13 +1,14 @@
 {
   "name": "@archon/paths",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
     "./strip-cwd-env": "./src/strip-cwd-env.ts",
-    "./strip-cwd-env-boot": "./src/strip-cwd-env-boot.ts"
+    "./strip-cwd-env-boot": "./src/strip-cwd-env-boot.ts",
+    "./env-loader": "./src/env-loader.ts"
   },
   "scripts": {
     "test": "bun test src/",
@@ -16,7 +17,8 @@
   "dependencies": {
     "dotenv": "^17",
     "pino": "^9",
-    "pino-pretty": "^13"
+    "pino-pretty": "^13",
+    "posthog-node": "^5.29.2"
   },
   "peerDependencies": {
     "typescript": "^5.0.0"
diff --git a/packages/paths/src/archon-paths.test.ts b/packages/paths/src/archon-paths.test.ts
index 734516375f..b6584810d4 100644
--- a/packages/paths/src/archon-paths.test.ts
+++ b/packages/paths/src/archon-paths.test.ts
@@ -12,6 +12,10 @@ import {
   getArchonWorkspacesPath,
   getArchonWorktreesPath,
   getArchonConfigPath,
+  getHomeWorkflowsPath,
+  getHomeCommandsPath,
+  getHomeScriptsPath,
+  getLegacyHomeWorkflowsPath,
   getCommandFolderSearchPaths,
   getWorkflowFolderSearchPaths,
   expandTilde,
@@ -223,6 +227,87 @@ describe('archon-paths', () => {
     });
   });
 
+  describe('getHomeWorkflowsPath', () => {
+    test('returns ~/.archon/workflows by default (direct child of ~/.archon/)', () => {
+      delete process.env.ARCHON_HOME;
+      delete process.env.ARCHON_DOCKER;
+      expect(getHomeWorkflowsPath()).toBe(join(homedir(), '.archon', 'workflows'));
+    });
+
+    test('returns /.archon/workflows in Docker', () => {
+      process.env.ARCHON_DOCKER = 'true';
+      expect(getHomeWorkflowsPath()).toBe(join('/', '.archon', 'workflows'));
+    });
+
+    test('uses ARCHON_HOME when set', () => {
+      delete process.env.ARCHON_DOCKER;
+      process.env.ARCHON_HOME = '/custom/archon';
+      expect(getHomeWorkflowsPath()).toBe(join('/custom/archon', 'workflows'));
+    });
+
+    test('no double `.archon/` nesting — must sit next to workspaces/ and worktrees/', () => {
+      // Regression guard: the old location was ~/.archon/.archon/workflows/.
+      // New location must NOT reintroduce the double-nested path.
+      delete process.env.ARCHON_HOME;
+      delete process.env.ARCHON_DOCKER;
+      expect(getHomeWorkflowsPath()).not.toContain(join('.archon', '.archon'));
+    });
+  });
+
+  describe('getHomeCommandsPath', () => {
+    test('returns ~/.archon/commands by default', () => {
+      delete process.env.ARCHON_HOME;
+      delete process.env.ARCHON_DOCKER;
+      expect(getHomeCommandsPath()).toBe(join(homedir(), '.archon', 'commands'));
+    });
+
+    test('returns /.archon/commands in Docker', () => {
+      process.env.ARCHON_DOCKER = 'true';
+      expect(getHomeCommandsPath()).toBe(join('/', '.archon', 'commands'));
+    });
+
+    test('uses ARCHON_HOME when set', () => {
+      delete process.env.ARCHON_DOCKER;
+      process.env.ARCHON_HOME = '/custom/archon';
+      expect(getHomeCommandsPath()).toBe(join('/custom/archon', 'commands'));
+    });
+  });
+
+  describe('getHomeScriptsPath', () => {
+    test('returns ~/.archon/scripts by default', () => {
+      delete process.env.ARCHON_HOME;
+      delete process.env.ARCHON_DOCKER;
+      expect(getHomeScriptsPath()).toBe(join(homedir(), '.archon', 'scripts'));
+    });
+
+    test('returns /.archon/scripts in Docker', () => {
+      process.env.ARCHON_DOCKER = 'true';
+      expect(getHomeScriptsPath()).toBe(join('/', '.archon', 'scripts'));
+    });
+
+    test('uses ARCHON_HOME when set', () => {
+      delete process.env.ARCHON_DOCKER;
+      process.env.ARCHON_HOME = '/custom/archon';
+      expect(getHomeScriptsPath()).toBe(join('/custom/archon', 'scripts'));
+    });
+  });
+
+  describe('getLegacyHomeWorkflowsPath', () => {
+    // This helper only exists so discovery can DETECT files at the old location
+    // and emit a deprecation warning. It is not a fallback read path.
+    test('returns ~/.archon/.archon/workflows (the retired location)', () => {
+      delete process.env.ARCHON_HOME;
+      delete process.env.ARCHON_DOCKER;
+      expect(getLegacyHomeWorkflowsPath()).toBe(join(homedir(), '.archon', '.archon', 'workflows'));
+    });
+
+    test('honors ARCHON_HOME so migration detection works in custom setups', () => {
+      delete process.env.ARCHON_DOCKER;
+      process.env.ARCHON_HOME = '/custom/archon';
+      expect(getLegacyHomeWorkflowsPath()).toBe(join('/custom/archon', '.archon', 'workflows'));
+    });
+  });
+
   describe('getAppArchonBasePath', () => {
     test('returns repo root .archon path in local development', () => {
       delete process.env.ARCHON_DOCKER;
diff --git a/packages/paths/src/archon-paths.ts b/packages/paths/src/archon-paths.ts
index ca8ea73774..d6db7cf69a 100644
--- a/packages/paths/src/archon-paths.ts
+++ b/packages/paths/src/archon-paths.ts
@@ -96,6 +96,69 @@ export function getArchonConfigPath(): string {
   return join(getArchonHome(), 'config.yaml');
 }
 
+/**
+ * Get the home-scoped workflows directory (`~/.archon/workflows/`).
+ * Workflows placed here are discovered from every repo and apply globally —
+ * overridden per-filename by the same name under `<repoRoot>/.archon/workflows/`.
+ *
+ * Direct child of `~/.archon/`, matching the convention for `workspaces/`,
+ * `archon.db`, `config.yaml`, etc. Replaces the prior `~/.archon/.archon/workflows/`
+ * location which was an artifact of reusing the repo-relative discovery helper.
+ */
+export function getHomeWorkflowsPath(): string {
+  return join(getArchonHome(), 'workflows');
+}
+
+/**
+ * Get the home-scoped commands directory (`~/.archon/commands/`).
+ * Commands placed here are resolvable from every repo and apply globally —
+ * overridden per-filename by the same name under `<repoRoot>/.archon/commands/`.
+ * Command resolution precedence: repo > home > bundled.
+ */
+export function getHomeCommandsPath(): string {
+  return join(getArchonHome(), 'commands');
+}
+
+/**
+ * Get the home-scoped scripts directory (`~/.archon/scripts/`).
+ * Scripts placed here are available to every workflow's `script:` nodes —
+ * overridden per-name by the same name under `<repoRoot>/.archon/scripts/`.
+ * Script resolution precedence: repo > home.
+ */
+export function getHomeScriptsPath(): string {
+  return join(getArchonHome(), 'scripts');
+}
+
+/**
+ * Legacy home-scoped workflows directory (`~/.archon/.archon/workflows/`).
+ * Retained only so discovery can DETECT files there and emit a one-time
+ * deprecation warning pointing at the migration command. Archon no longer
+ * reads workflows from this path — it's a signal, not a source.
+ */
+export function getLegacyHomeWorkflowsPath(): string {
+  return join(getArchonHome(), '.archon', 'workflows');
+}
+
+/**
+ * Get the home-scope archon env file path (~/.archon/.env).
+ * This is the archon-owned env location loaded by every entry point.
+ */
+export function getArchonEnvPath(): string {
+  return join(getArchonHome(), '.env');
+}
+
+/**
+ * Get the repo-scope archon env file path (<cwd>/.archon/.env).
+ * This is the archon-owned env location loaded with override: true AFTER the home
+ * env, so per-project values win over user-wide defaults.
+ *
+ * Note: <cwd>/.env (without the .archon/ prefix) is the USER's — it is stripped at
+ * boot by stripCwdEnv() and never loaded by Archon.
+ */
+export function getRepoArchonEnvPath(cwd: string): string {
+  return join(cwd, '.archon', '.env');
+}
+
 /**
  * Get command folder search paths for a repository
  * Returns folders in priority order (first match wins)
@@ -133,11 +196,21 @@ export function getWorkflowFolderSearchPaths(): string[] {
 /**
  * Recursively find all .md files in a directory and its subdirectories.
  * Skips hidden directories and node_modules.
+ *
+ * `maxDepth` caps how many folders deep the walk descends. Depth is counted as
+ * the number of folder boundaries between `rootPath` and the file — so at
+ * `maxDepth: 1`, files at `rootPath/file.md` (depth 0) and `rootPath/group/file.md`
+ * (depth 1) are included, but `rootPath/group/sub/file.md` (depth 2) is not.
+ * Default is `Infinity` (no cap) for backwards compatibility with callers that
+ * want to copy arbitrary subtrees (e.g. clone handlers).
  */
 export async function findMarkdownFilesRecursive(
   rootPath: string,
-  relativePath = ''
+  relativePath = '',
+  options?: { maxDepth?: number }
 ): Promise<{ commandName: string; relativePath: string }[]> {
+  const maxDepth = options?.maxDepth ?? Infinity;
+  const currentDepth = relativePath ? relativePath.split(/[/\\]/).filter(Boolean).length : 0;
   const results: { commandName: string; relativePath: string }[] = [];
   const fullPath = join(rootPath, relativePath);
 
@@ -156,7 +229,15 @@ export async function findMarkdownFilesRecursive(
     }
 
     if (entry.isDirectory()) {
-      const subResults = await findMarkdownFilesRecursive(rootPath, join(relativePath, entry.name));
+      // Skip descending if we're already at the depth cap — files at deeper
+      // levels are silently ignored (matches the convention that `.archon/*/`
+      // folders support one level of grouping like `defaults/`).
+      if (currentDepth >= maxDepth) continue;
+      const subResults = await findMarkdownFilesRecursive(
+        rootPath,
+        join(relativePath, entry.name),
+        options
+      );
       results.push(...subResults);
     } else if (entry.isFile() && entry.name.endsWith('.md')) {
       results.push({
diff --git a/packages/paths/src/env-integration.test.ts b/packages/paths/src/env-integration.test.ts
index 0654c1a22e..5bb2dd036b 100644
--- a/packages/paths/src/env-integration.test.ts
+++ b/packages/paths/src/env-integration.test.ts
@@ -20,6 +20,8 @@ const TEST_KEYS = [
   'ANTHROPIC_API_KEY',
   'CLAUDE_API_KEY',
   'CLAUDE_CODE_OAUTH_TOKEN',
+  'CLAUDE_CODE_USE_BEDROCK',
+  'CLAUDE_CODE_USE_VERTEX',
   'CLAUDE_USE_GLOBAL_AUTH',
   'DATABASE_URL',
   'LOG_LEVEL',
@@ -31,6 +33,11 @@ const TEST_KEYS = [
   'CLAUDE_CODE_ENTRYPOINT',
   'NODE_OPTIONS',
   'REDIS_URL',
+  'OPENAI_API_KEY',
+  'ELEVENLABS_API_KEY',
+  'SSH_AUTH_SOCK',
+  'HTTP_PROXY',
+  'MANAGED_SECRET',
 ];
 
 describe('env isolation integration', () => {
@@ -132,9 +139,11 @@ describe('env isolation integration', () => {
     expect(subprocessEnv.ANTHROPIC_API_KEY).toBeUndefined();
     // Archon key present
     expect(subprocessEnv.ARCHON_ONLY_KEY).toBe('trusted');
-    // Shell-inherited keys present
-    expect(subprocessEnv.PATH).toBeDefined();
-    expect(subprocessEnv.HOME).toBeDefined();
+    // Shell-inherited keys present (Windows uses "Path" casing and USERPROFILE instead of HOME)
+    const hasPath = subprocessEnv.PATH ?? subprocessEnv.Path;
+    expect(hasPath).toBeDefined();
+    const hasHome = subprocessEnv.HOME ?? subprocessEnv.USERPROFILE;
+    expect(hasHome).toBeDefined();
   });
 
   it('scenario 4: same key in both CWD and archon env — archon value wins', () => {
@@ -205,4 +214,117 @@ describe('env isolation integration', () => {
     expect(subprocessEnv.CLAUDE_CODE_ENTRYPOINT).toBeUndefined();
     expect(subprocessEnv.CLAUDE_CODE_OAUTH_TOKEN).toBe('sk-ant-oat01-keep-this');
   });
+
+  // ── Multiple .env file variants ────────────────────────────────────────
+
+  /** Simulate Bun auto-loading a specific .env file into process.env. */
+  function simulateBunAutoLoad(filePath: string): void {
+    const parsed = config({ path: filePath, processEnv: {} });
+    if (parsed.parsed) {
+      for (const [key, value] of Object.entries(parsed.parsed)) {
+        process.env[key] = value;
+      }
+    }
+  }
+
+  it('strips keys from .env.local in addition to .env', () => {
+    // Bun auto-loads .env.local too — keys from there must also be stripped
+    writeFileSync(join(cwdDir, '.env.local'), 'OPENAI_API_KEY=sk-local-leaked\n');
+    simulateBunAutoLoad(join(cwdDir, '.env.local'));
+
+    const subprocessEnv = simulateEntryPointFlow(
+      'ANTHROPIC_API_KEY=sk-main-leaked\n',
+      'CLAUDE_USE_GLOBAL_AUTH=true\n'
+    );
+
+    expect(subprocessEnv.ANTHROPIC_API_KEY).toBeUndefined();
+    expect(subprocessEnv.OPENAI_API_KEY).toBeUndefined();
+    expect(subprocessEnv.CLAUDE_USE_GLOBAL_AUTH).toBe('true');
+  });
+
+  it('strips keys from .env.development', () => {
+    writeFileSync(join(cwdDir, '.env.development'), 'ELEVENLABS_API_KEY=el-dev-leaked\n');
+    simulateBunAutoLoad(join(cwdDir, '.env.development'));
+
+    const subprocessEnv = simulateEntryPointFlow('', '');
+
+    expect(subprocessEnv.ELEVENLABS_API_KEY).toBeUndefined();
+  });
+
+  // ── Shell-inherited env preservation ───────────────────────────────────
+
+  it('preserves shell-inherited env that is not in CWD .env', () => {
+    // User has SSH_AUTH_SOCK and HTTP_PROXY in their shell — these must survive
+    // because they are not from the target repo's .env
+    process.env.SSH_AUTH_SOCK = '/tmp/ssh-agent.sock';
+    process.env.HTTP_PROXY = 'http://proxy.corp:8080';
+
+    const subprocessEnv = simulateEntryPointFlow('ANTHROPIC_API_KEY=sk-leaked\n', '');
+
+    // CWD key stripped
+    expect(subprocessEnv.ANTHROPIC_API_KEY).toBeUndefined();
+    // Shell-inherited env preserved (not in any CWD .env file)
+    expect(subprocessEnv.SSH_AUTH_SOCK).toBe('/tmp/ssh-agent.sock');
+    expect(subprocessEnv.HTTP_PROXY).toBe('http://proxy.corp:8080');
+  });
+
+  it('strips shell-inherited env if same key also appears in CWD .env', () => {
+    // If SSH_AUTH_SOCK is in both shell AND CWD .env, the CWD value is what
+    // Bun auto-loaded — stripping removes it. This is correct behavior:
+    // the CWD .env overwrote the shell value during auto-load.
+    process.env.SSH_AUTH_SOCK = '/tmp/ssh-agent.sock';
+
+    const subprocessEnv = simulateEntryPointFlow('SSH_AUTH_SOCK=/tmp/repo-evil-agent.sock\n', '');
+
+    // Key was in CWD .env, so it gets stripped entirely
+    expect(subprocessEnv.SSH_AUTH_SOCK).toBeUndefined();
+  });
+
+  // ── Bedrock/Vertex auth preservation ───────────────────────────────────
+
+  it('preserves CLAUDE_CODE_USE_BEDROCK and CLAUDE_CODE_USE_VERTEX', () => {
+    // These are CLAUDE_CODE_* vars but are auth-related — must survive marker strip
+    process.env.CLAUDECODE = '1';
+    process.env.CLAUDE_CODE_ENTRYPOINT = 'cli';
+
+    const subprocessEnv = simulateEntryPointFlow(
+      '',
+      'CLAUDE_CODE_USE_BEDROCK=1\nCLAUDE_CODE_USE_VERTEX=1\nCLAUDE_CODE_OAUTH_TOKEN=sk-token\n'
+    );
+
+    // Markers stripped
+    expect(subprocessEnv.CLAUDECODE).toBeUndefined();
+    expect(subprocessEnv.CLAUDE_CODE_ENTRYPOINT).toBeUndefined();
+    // Auth vars preserved
+    expect(subprocessEnv.CLAUDE_CODE_USE_BEDROCK).toBe('1');
+    expect(subprocessEnv.CLAUDE_CODE_USE_VERTEX).toBe('1');
+    expect(subprocessEnv.CLAUDE_CODE_OAUTH_TOKEN).toBe('sk-token');
+  });
+
+  // ── Managed execution env (simulated) ──────────────────────────────────
+
+  it('managed execution env merges on top of clean process.env', () => {
+    // After the entry point flow, the workflow executor merges managed env
+    // (from config.yaml env: + DB vars) on top of process.env.
+    // This simulates that final merge.
+    const subprocessEnv = simulateEntryPointFlow(
+      'ANTHROPIC_API_KEY=sk-leaked\nDATABASE_URL=postgres://wrong\n',
+      'CLAUDE_USE_GLOBAL_AUTH=true\n'
+    );
+
+    // Simulate managed env merge (what dag-executor does via requestOptions.env)
+    const managedEnv = { MANAGED_SECRET: 'from-db', ELEVENLABS_API_KEY: 'el-managed' };
+    const finalEnv = { ...subprocessEnv, ...managedEnv };
+
+    // CWD keys still stripped
+    expect(finalEnv.ANTHROPIC_API_KEY).toBeUndefined();
+    expect(finalEnv.DATABASE_URL).toBeUndefined();
+    // Archon auth present
+    expect(finalEnv.CLAUDE_USE_GLOBAL_AUTH).toBe('true');
+    // Managed env present
+    expect(finalEnv.MANAGED_SECRET).toBe('from-db');
+    expect(finalEnv.ELEVENLABS_API_KEY).toBe('el-managed');
+    // OS essentials present
+    expect(finalEnv.PATH ?? finalEnv.Path).toBeDefined();
+  });
 });
diff --git a/packages/paths/src/env-loader.test.ts b/packages/paths/src/env-loader.test.ts
new file mode 100644
index 0000000000..968b4d98d5
--- /dev/null
+++ b/packages/paths/src/env-loader.test.ts
@@ -0,0 +1,140 @@
+import { describe, it, expect, beforeEach, afterEach, spyOn } from 'bun:test';
+import { writeFileSync, mkdirSync, rmSync } from 'fs';
+import { join } from 'path';
+import { loadArchonEnv } from './env-loader';
+
+/**
+ * loadArchonEnv covers the read side of the three-path env model (#1302):
+ *   ~/.archon/.env         → home scope, override: true
+ *   <cwd>/.archon/.env     → repo scope, override: true (wins over home)
+ *
+ * Tests drive the home scope via ARCHON_HOME and the repo scope via the `cwd`
+ * argument. Both are tmpdirs; no real ~/.archon/ is touched.
+ */
+
+const tmpRoot = join(import.meta.dir, '__env-loader-test-tmp__');
+const archonHomeDir = join(tmpRoot, 'archon-home');
+const repoDir = join(tmpRoot, 'repo');
+
+// Keys we set/clear in tests. Using namespaced names to avoid collisions with
+// anything a developer might have in their real shell env.
+const TEST_KEYS = ['TEST_EL_HOME_ONLY', 'TEST_EL_REPO_ONLY', 'TEST_EL_OVERLAP', 'TEST_EL_OTHER'];
+
+let originalArchonHome: string | undefined;
+let stderrSpy: ReturnType<typeof spyOn>;
+let stderrWrites: string[];
+let consoleErrorSpy: ReturnType<typeof spyOn>;
+let consoleErrorMessages: string[];
+
+beforeEach(() => {
+  mkdirSync(archonHomeDir, { recursive: true });
+  mkdirSync(join(repoDir, '.archon'), { recursive: true });
+
+  originalArchonHome = process.env.ARCHON_HOME;
+  process.env.ARCHON_HOME = archonHomeDir;
+
+  for (const k of TEST_KEYS) delete process.env[k];
+
+  stderrWrites = [];
+  stderrSpy = spyOn(process.stderr, 'write').mockImplementation((chunk: unknown) => {
+    stderrWrites.push(typeof chunk === 'string' ? chunk : String(chunk));
+    return true;
+  });
+
+  consoleErrorMessages = [];
+  consoleErrorSpy = spyOn(console, 'error').mockImplementation((msg: unknown) => {
+    consoleErrorMessages.push(String(msg));
+  });
+});
+
+afterEach(() => {
+  stderrSpy.mockRestore();
+  consoleErrorSpy.mockRestore();
+  rmSync(tmpRoot, { recursive: true, force: true });
+
+  if (originalArchonHome === undefined) delete process.env.ARCHON_HOME;
+  else process.env.ARCHON_HOME = originalArchonHome;
+
+  for (const k of TEST_KEYS) delete process.env[k];
+});
+
+describe('loadArchonEnv', () => {
+  it('loads keys from ~/.archon/.env and emits a [archon] loaded line', () => {
+    writeFileSync(join(archonHomeDir, '.env'), 'TEST_EL_HOME_ONLY=from-home\nTEST_EL_OTHER=keep\n');
+
+    loadArchonEnv(repoDir);
+
+    expect(process.env.TEST_EL_HOME_ONLY).toBe('from-home');
+    expect(process.env.TEST_EL_OTHER).toBe('keep');
+    // Tilde-shortening of the rendered path is opportunistic (only when the
+    // tmpdir lives under `homedir()`). On Windows CI the tmpdir is on a
+    // different drive and the path renders absolute, so we match on count and
+    // the archon-home tmpdir segment rather than a literal `~` prefix.
+    const line = stderrWrites.find(s => s.includes('[archon] loaded') && !s.includes('repo scope'));
+    expect(line).toBeDefined();
+    expect(line).toContain('loaded 2 keys');
+    expect(line).toContain(join('archon-home', '.env'));
+  });
+
+  it('loads keys from <cwd>/.archon/.env and marks it as repo scope', () => {
+    writeFileSync(join(repoDir, '.archon', '.env'), 'TEST_EL_REPO_ONLY=from-repo\n');
+
+    loadArchonEnv(repoDir);
+
+    expect(process.env.TEST_EL_REPO_ONLY).toBe('from-repo');
+    const line = stderrWrites.find(s => s.includes('repo scope, overrides user scope'));
+    expect(line).toBeDefined();
+    expect(line).toContain('loaded 1 keys');
+    // Path rendering tildes anything under the user's home directory — assert
+    // on the suffix (the `.archon/.env` segment) rather than the full path,
+    // because the tmpdir may or may not live under $HOME on CI.
+    expect(line).toContain(join('.archon', '.env'));
+  });
+
+  it('repo scope overrides home scope on overlapping keys', () => {
+    writeFileSync(join(archonHomeDir, '.env'), 'TEST_EL_OVERLAP=from-home\n');
+    writeFileSync(join(repoDir, '.archon', '.env'), 'TEST_EL_OVERLAP=from-repo\n');
+
+    loadArchonEnv(repoDir);
+
+    expect(process.env.TEST_EL_OVERLAP).toBe('from-repo');
+  });
+
+  it('emits nothing when neither file exists', () => {
+    loadArchonEnv(repoDir);
+    const anyLoaded = stderrWrites.find(s => s.includes('[archon] loaded'));
+    expect(anyLoaded).toBeUndefined();
+  });
+
+  it('emits no loaded line when a file exists but is empty', () => {
+    writeFileSync(join(archonHomeDir, '.env'), '');
+    writeFileSync(join(repoDir, '.archon', '.env'), '');
+
+    loadArchonEnv(repoDir);
+
+    const anyLoaded = stderrWrites.find(s => s.includes('[archon] loaded'));
+    expect(anyLoaded).toBeUndefined();
+  });
+
+  it('exits with error when env file has a dotenv-unparseable layout', () => {
+    // dotenv.parse is very permissive — lines without `=` are silently ignored,
+    // so syntactic errors that actually surface are rare. We instead simulate
+    // a permission-style failure by writing a path that cannot be read: pass a
+    // directory in place of a file. dotenv.config returns an error for EISDIR.
+    // (Use the home slot since the repo path derives from cwd inside the fn.)
+    rmSync(join(archonHomeDir, '.env'), { force: true });
+    mkdirSync(join(archonHomeDir, '.env'), { recursive: true }); // directory at .env path
+
+    const exitSpy = spyOn(process, 'exit').mockImplementation((() => {
+      throw new Error('process.exit called');
+    }) as never);
+
+    try {
+      expect(() => loadArchonEnv(repoDir)).toThrow('process.exit called');
+      const msg = consoleErrorMessages.find(s => s.startsWith('Error loading .env'));
+      expect(msg).toBeDefined();
+    } finally {
+      exitSpy.mockRestore();
+    }
+  });
+});
diff --git a/packages/paths/src/env-loader.ts b/packages/paths/src/env-loader.ts
new file mode 100644
index 0000000000..d4fb3adfbc
--- /dev/null
+++ b/packages/paths/src/env-loader.ts
@@ -0,0 +1,83 @@
+/**
+ * Archon-owned env loader — runs at every entry point AFTER stripCwdEnv().
+ *
+ * Loads env vars from two archon-owned locations and emits operator-facing log
+ * lines naming the exact paths and key counts. Replaces the misleading
+ * `[dotenv@17.3.1] injecting env (N) from .env` preamble (see #1302).
+ *
+ * Load order (later sources win because `override: true`):
+ *   1. ~/.archon/.env         — user-scope defaults, apply everywhere
+ *   2. <cwd>/.archon/.env     — repo-scope overrides for this project
+ *
+ * `<cwd>/.env` is intentionally NOT loaded — it belongs to the user's target
+ * repo and is stripped by stripCwdEnv() (see #1302 / #1303 three-path model).
+ * Directory ownership (`.archon/`) is the security boundary, not the filename.
+ *
+ * Logging rules:
+ *   - Each `[archon] loaded N keys from …` line prints only when N > 0.
+ *   - Silent in the common case (no archon-owned env files present).
+ *   - Emits to stderr (operator signal) — Pino logger is not yet initialized
+ *     at this point in boot.
+ *   - Passes `{ quiet: true }` to suppress dotenv's own `[dotenv@17.3.1] …`
+ *     output.
+ */
+import { config } from 'dotenv';
+import { existsSync } from 'fs';
+import { homedir } from 'os';
+import { getArchonEnvPath, getRepoArchonEnvPath } from './archon-paths';
+
+/**
+ * Shorten a path with `~` when it lives under the current user's home directory.
+ * Used only for log rendering — never for filesystem operations.
+ */
+function displayPath(p: string): string {
+  const home = homedir();
+  if (p === home) return '~';
+  if (p.startsWith(home + '/') || p.startsWith(home + '\\')) {
+    return '~' + p.slice(home.length);
+  }
+  return p;
+}
+
+/**
+ * Load archon-owned env files. Call once, immediately after
+ * `@archon/paths/strip-cwd-env-boot` at each entry point.
+ *
+ * Both loads use `override: true` so:
+ *   - `~/.archon/.env` wins over shell-inherited vars (archon intent wins).
+ *   - `<cwd>/.archon/.env` wins over `~/.archon/.env` (repo scope wins).
+ *
+ * A malformed env file is fatal — matches the pre-existing CLI behavior at
+ * packages/cli/src/cli.ts:24-30.
+ */
+export function loadArchonEnv(cwd: string = process.cwd()): void {
+  const homePath = getArchonEnvPath();
+  if (existsSync(homePath)) {
+    const result = config({ path: homePath, override: true, quiet: true });
+    if (result.error) {
+      console.error(`Error loading .env from ${homePath}: ${result.error.message}`);
+      console.error('Hint: Check for syntax errors in your .env file.');
+      process.exit(1);
+    }
+    const count = Object.keys(result.parsed ?? {}).length;
+    if (count > 0) {
+      process.stderr.write(`[archon] loaded ${count} keys from ${displayPath(homePath)}\n`);
+    }
+  }
+
+  const repoPath = getRepoArchonEnvPath(cwd);
+  if (existsSync(repoPath)) {
+    const result = config({ path: repoPath, override: true, quiet: true });
+    if (result.error) {
+      console.error(`Error loading .env from ${repoPath}: ${result.error.message}`);
+      console.error('Hint: Check for syntax errors in your .env file.');
+      process.exit(1);
+    }
+    const count = Object.keys(result.parsed ?? {}).length;
+    if (count > 0) {
+      process.stderr.write(
+        `[archon] loaded ${count} keys from ${displayPath(repoPath)} (repo scope, overrides user scope)\n`
+      );
+    }
+  }
+}
diff --git a/packages/paths/src/index.ts b/packages/paths/src/index.ts
index 99a254f4ca..443d55ff90 100644
--- a/packages/paths/src/index.ts
+++ b/packages/paths/src/index.ts
@@ -6,6 +6,12 @@ export {
   getArchonWorkspacesPath,
   getArchonWorktreesPath,
   getArchonConfigPath,
+  getArchonEnvPath,
+  getRepoArchonEnvPath,
+  getHomeWorkflowsPath,
+  getHomeCommandsPath,
+  getHomeScriptsPath,
+  getLegacyHomeWorkflowsPath,
   getCommandFolderSearchPaths,
   getWorkflowFolderSearchPaths,
   getAppArchonBasePath,
@@ -43,3 +49,7 @@ export {
   parseLatestRelease,
 } from './update-check';
 export type { UpdateCheckResult } from './update-check';
+
+// Anonymous telemetry
+export { captureWorkflowInvoked, shutdownTelemetry, isTelemetryDisabled } from './telemetry';
+export type { WorkflowInvokedProperties } from './telemetry';
diff --git a/packages/paths/src/strip-cwd-env.test.ts b/packages/paths/src/strip-cwd-env.test.ts
index 9576f0aa0a..db9ad04399 100644
--- a/packages/paths/src/strip-cwd-env.test.ts
+++ b/packages/paths/src/strip-cwd-env.test.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
+import { describe, it, expect, beforeEach, afterEach, spyOn } from 'bun:test';
 import { writeFileSync, mkdirSync, rmSync } from 'fs';
 import { join } from 'path';
 import { stripCwdEnv } from './strip-cwd-env';
@@ -84,6 +84,65 @@ describe('stripCwdEnv', () => {
   });
 });
 
+describe('stripCwdEnv — operator logging (#1302)', () => {
+  const tmpDir = join(import.meta.dir, '__strip-cwd-env-log-test-tmp__');
+  let stderrSpy: ReturnType<typeof spyOn>;
+  let stderrWrites: string[];
+
+  beforeEach(() => {
+    mkdirSync(tmpDir, { recursive: true });
+    stderrWrites = [];
+    stderrSpy = spyOn(process.stderr, 'write').mockImplementation((chunk: unknown) => {
+      stderrWrites.push(typeof chunk === 'string' ? chunk : String(chunk));
+      return true;
+    });
+  });
+
+  afterEach(() => {
+    stderrSpy.mockRestore();
+    rmSync(tmpDir, { recursive: true, force: true });
+    delete process.env.TEST_STRIP_LOG_A;
+    delete process.env.TEST_STRIP_LOG_B;
+    delete process.env.TEST_STRIP_LOG_C;
+  });
+
+  it('emits [archon] stripped line with count and filename when keys are stripped', () => {
+    writeFileSync(join(tmpDir, '.env'), 'TEST_STRIP_LOG_A=leaked\nTEST_STRIP_LOG_B=leaked\n');
+    process.env.TEST_STRIP_LOG_A = 'leaked';
+    process.env.TEST_STRIP_LOG_B = 'leaked';
+    stripCwdEnv(tmpDir);
+    const line = stderrWrites.find(s => s.startsWith('[archon] stripped'));
+    expect(line).toBeDefined();
+    expect(line).toContain('stripped 2 keys');
+    expect(line).toContain(tmpDir);
+    expect(line).toContain('(.env)');
+  });
+
+  it('lists every contributing filename when keys span multiple .env files', () => {
+    writeFileSync(join(tmpDir, '.env'), 'TEST_STRIP_LOG_A=leaked\n');
+    writeFileSync(join(tmpDir, '.env.local'), 'TEST_STRIP_LOG_B=leaked\n');
+    process.env.TEST_STRIP_LOG_A = 'leaked';
+    process.env.TEST_STRIP_LOG_B = 'leaked';
+    stripCwdEnv(tmpDir);
+    const line = stderrWrites.find(s => s.startsWith('[archon] stripped'));
+    expect(line).toBeDefined();
+    expect(line).toContain('(.env, .env.local)');
+  });
+
+  it('emits no [archon] stripped line when no CWD .env files exist', () => {
+    stripCwdEnv(tmpDir);
+    const line = stderrWrites.find(s => s.startsWith('[archon] stripped'));
+    expect(line).toBeUndefined();
+  });
+
+  it('emits no [archon] stripped line when .env file is empty', () => {
+    writeFileSync(join(tmpDir, '.env'), '');
+    stripCwdEnv(tmpDir);
+    const line = stderrWrites.find(s => s.startsWith('[archon] stripped'));
+    expect(line).toBeUndefined();
+  });
+});
+
 describe('stripCwdEnv — nested Claude Code marker stripping', () => {
   const tmpDir = join(import.meta.dir, '__strip-markers-test-tmp__');
 
diff --git a/packages/paths/src/strip-cwd-env.ts b/packages/paths/src/strip-cwd-env.ts
index 17c4a3c903..178ea4b8f3 100644
--- a/packages/paths/src/strip-cwd-env.ts
+++ b/packages/paths/src/strip-cwd-env.ts
@@ -41,11 +41,15 @@ const CLAUDE_CODE_AUTH_VARS = new Set([
 export function stripCwdEnv(cwd: string = process.cwd()): void {
   // --- Pass 1: CWD .env files ---
   const cwdKeys = new Set<string>();
+  const strippedFiles: string[] = [];
 
   for (const filename of BUN_AUTO_LOADED_ENV_FILES) {
     const filepath = resolve(cwd, filename);
-    // dotenv.config with processEnv:{} parses without writing to process.env
-    const result = config({ path: filepath, processEnv: {} });
+    // dotenv.config with processEnv:{} parses without writing to process.env.
+    // quiet:true suppresses dotenv's `[dotenv@...] injecting env …` tip line —
+    // which always reports (0) here because processEnv:{} is a throwaway object
+    // and would mislead operators into thinking the file was empty (see #1302).
+    const result = config({ path: filepath, processEnv: {}, quiet: true });
     if (result.error) {
       // ENOENT is expected (file simply doesn't exist) — all others are unexpected
       const code = (result.error as NodeJS.ErrnoException).code;
@@ -55,8 +59,12 @@ export function stripCwdEnv(cwd: string = process.cwd()): void {
         );
       }
     } else if (result.parsed) {
-      for (const key of Object.keys(result.parsed)) {
-        cwdKeys.add(key);
+      const parsedKeys = Object.keys(result.parsed);
+      if (parsedKeys.length > 0) {
+        strippedFiles.push(filename);
+        for (const key of parsedKeys) {
+          cwdKeys.add(key);
+        }
       }
     }
   }
@@ -65,6 +73,14 @@ export function stripCwdEnv(cwd: string = process.cwd()): void {
     Reflect.deleteProperty(process.env, key);
   }
 
+  // Tell the operator what we just did — otherwise the delete loop is silent
+  // and users think their env file was loaded (see #1302).
+  if (cwdKeys.size > 0) {
+    process.stderr.write(
+      `[archon] stripped ${cwdKeys.size} keys from ${cwd} (${strippedFiles.join(', ')}) to prevent target repo env from leaking into Archon processes\n`
+    );
+  }
+
   // --- Pass 2: Nested Claude Code session markers ---
   // Pattern-matched (not hardcoded) so new CLAUDE_CODE_* markers added by
   // future Claude Code versions are automatically handled.
diff --git a/packages/paths/src/telemetry.test.ts b/packages/paths/src/telemetry.test.ts
new file mode 100644
index 0000000000..23889fe47d
--- /dev/null
+++ b/packages/paths/src/telemetry.test.ts
@@ -0,0 +1,151 @@
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'fs';
+
+import {
+  isTelemetryDisabled,
+  captureWorkflowInvoked,
+  shutdownTelemetry,
+  resetTelemetryForTests,
+  getOrCreateTelemetryId,
+} from './telemetry';
+
+const ENV_VARS = [
+  'ARCHON_HOME',
+  'ARCHON_TELEMETRY_DISABLED',
+  'DO_NOT_TRACK',
+  'POSTHOG_API_KEY',
+  'POSTHOG_HOST',
+];
+
+function saveEnv(): Record<string, string | undefined> {
+  const saved: Record<string, string | undefined> = {};
+  for (const key of ENV_VARS) saved[key] = process.env[key];
+  return saved;
+}
+
+function restoreEnv(saved: Record<string, string | undefined>): void {
+  for (const key of ENV_VARS) {
+    if (saved[key] === undefined) {
+      delete process.env[key];
+    } else {
+      process.env[key] = saved[key];
+    }
+  }
+}
+
+describe('telemetry opt-out detection', () => {
+  let saved: Record<string, string | undefined>;
+
+  beforeEach(() => {
+    saved = saveEnv();
+    resetTelemetryForTests();
+  });
+
+  afterEach(() => {
+    restoreEnv(saved);
+    resetTelemetryForTests();
+  });
+
+  test('enabled by default when no opt-out env vars set', () => {
+    delete process.env.ARCHON_TELEMETRY_DISABLED;
+    delete process.env.DO_NOT_TRACK;
+    delete process.env.POSTHOG_API_KEY;
+    expect(isTelemetryDisabled()).toBe(false);
+  });
+
+  test('ARCHON_TELEMETRY_DISABLED=1 disables telemetry', () => {
+    process.env.ARCHON_TELEMETRY_DISABLED = '1';
+    expect(isTelemetryDisabled()).toBe(true);
+  });
+
+  test('DO_NOT_TRACK=1 disables telemetry', () => {
+    process.env.DO_NOT_TRACK = '1';
+    expect(isTelemetryDisabled()).toBe(true);
+  });
+
+  test('ARCHON_TELEMETRY_DISABLED=0 does not disable (strict "1" match)', () => {
+    process.env.ARCHON_TELEMETRY_DISABLED = '0';
+    delete process.env.DO_NOT_TRACK;
+    expect(isTelemetryDisabled()).toBe(false);
+  });
+
+  test('empty POSTHOG_API_KEY override disables telemetry', () => {
+    process.env.POSTHOG_API_KEY = '';
+    delete process.env.ARCHON_TELEMETRY_DISABLED;
+    delete process.env.DO_NOT_TRACK;
+    expect(isTelemetryDisabled()).toBe(true);
+  });
+});
+
+describe('captureWorkflowInvoked when disabled', () => {
+  let saved: Record<string, string | undefined>;
+
+  beforeEach(() => {
+    saved = saveEnv();
+    resetTelemetryForTests();
+    process.env.ARCHON_TELEMETRY_DISABLED = '1';
+  });
+
+  afterEach(() => {
+    restoreEnv(saved);
+    resetTelemetryForTests();
+  });
+
+  test('does not throw when telemetry is disabled', () => {
+    expect(() => {
+      captureWorkflowInvoked({
+        workflowName: 'test-workflow',
+        workflowDescription: 'A test',
+        platform: 'cli',
+        archonVersion: 'dev',
+      });
+    }).not.toThrow();
+  });
+
+  test('shutdownTelemetry is a no-op when never initialized', async () => {
+    await expect(shutdownTelemetry()).resolves.toBeUndefined();
+  });
+});
+
+describe('telemetry ID persistence', () => {
+  let saved: Record<string, string | undefined>;
+  let tmpHome: string;
+
+  beforeEach(() => {
+    saved = saveEnv();
+    tmpHome = mkdtempSync(join(tmpdir(), 'archon-telemetry-test-'));
+    process.env.ARCHON_HOME = tmpHome;
+    // Force-disable actual network capture — we only exercise the ID path.
+    process.env.ARCHON_TELEMETRY_DISABLED = '1';
+    resetTelemetryForTests();
+  });
+
+  afterEach(() => {
+    restoreEnv(saved);
+    resetTelemetryForTests();
+    rmSync(tmpHome, { recursive: true, force: true });
+  });
+
+  test('calling capture while disabled does not create a telemetry-id file', () => {
+    captureWorkflowInvoked({ workflowName: 'w' });
+    expect(existsSync(join(tmpHome, 'telemetry-id'))).toBe(false);
+  });
+
+  test('an existing telemetry-id file is preserved (not overwritten)', async () => {
+    const { writeFileSync, mkdirSync } = await import('fs');
+    const existingId = '11111111-1111-4111-8111-111111111111';
+    mkdirSync(tmpHome, { recursive: true });
+    writeFileSync(join(tmpHome, 'telemetry-id'), existingId, 'utf8');
+
+    resetTelemetryForTests();
+
+    // Direct, synchronous call — no network, no fire-and-forget, no timer.
+    const resolved = getOrCreateTelemetryId();
+
+    expect(resolved).toBe(existingId);
+    const stored = readFileSync(join(tmpHome, 'telemetry-id'), 'utf8').trim();
+    expect(stored).toBe(existingId);
+  });
+});
diff --git a/packages/paths/src/telemetry.ts b/packages/paths/src/telemetry.ts
new file mode 100644
index 0000000000..4c68649dab
--- /dev/null
+++ b/packages/paths/src/telemetry.ts
@@ -0,0 +1,246 @@
+/**
+ * Anonymous PostHog telemetry for Archon.
+ *
+ * Emits one event — `workflow_invoked` — each time a workflow starts. No PII,
+ * no user identity. A random UUID is persisted to `${ARCHON_HOME}/telemetry-id`
+ * so we can count distinct installs; `$process_person_profile: false` keeps
+ * events in PostHog's anonymous tier (no person profile ever created).
+ *
+ * Opt-out (any one disables telemetry):
+ *   - ARCHON_TELEMETRY_DISABLED=1
+ *   - DO_NOT_TRACK=1                   (de facto standard)
+ *   - POSTHOG_API_KEY unset *and* no embedded default
+ *
+ * All functions are fire-and-forget: telemetry errors are logged at debug level
+ * and swallowed. Capture must never crash Archon.
+ */
+import { randomUUID } from 'crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import type { PostHog } from 'posthog-node';
+import { getArchonHome } from './archon-paths';
+import { createLogger } from './logger';
+
+// Minimal shape of posthog-node's `fetch` option — copied from @posthog/core
+// (a transitive dep) to avoid pulling it in as a direct dependency.
+interface PostHogFetchOptions {
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH';
+  mode?: 'no-cors';
+  credentials?: 'omit';
+  headers: Record<string, string>;
+  body?: string | Blob;
+  signal?: AbortSignal;
+}
+interface PostHogFetchResponse {
+  status: number;
+  text: () => Promise<string>;
+  json: () => Promise<unknown>;
+  headers?: { get(name: string): string | null };
+}
+
+/**
+ * Embedded write-only PostHog project key. Safe to ship in source: `phc_*`
+ * keys can only write events, never read data. Override with POSTHOG_API_KEY
+ * for self-hosted PostHog or a different project.
+ */
+const EMBEDDED_POSTHOG_API_KEY = 'phc_rR7oacut9mm4upGRbuoMptnyjRium34TTbbqobiQYS7x';
+const DEFAULT_POSTHOG_HOST = 'https://us.i.posthog.com';
+
+/** Max length of workflow description sent to PostHog. Guards against unusually long YAML descriptions. */
+const DESCRIPTION_MAX_LENGTH = 500;
+
+let cachedLog: ReturnType<typeof createLogger> | undefined;
+function getLog(): ReturnType<typeof createLogger> {
+  if (!cachedLog) cachedLog = createLogger('telemetry');
+  return cachedLog;
+}
+
+function getApiKey(): string {
+  return process.env.POSTHOG_API_KEY ?? EMBEDDED_POSTHOG_API_KEY;
+}
+
+function getHost(): string {
+  return process.env.POSTHOG_HOST ?? DEFAULT_POSTHOG_HOST;
+}
+
+/**
+ * Check whether telemetry is disabled via env vars or missing key.
+ * Exported for tests and callers that want to short-circuit early.
+ */
+export function isTelemetryDisabled(): boolean {
+  if (process.env.ARCHON_TELEMETRY_DISABLED === '1') return true;
+  if (process.env.DO_NOT_TRACK === '1') return true;
+  if (!getApiKey()) return true;
+  return false;
+}
+
+/**
+ * Load or create a stable anonymous install UUID at `${ARCHON_HOME}/telemetry-id`.
+ * If the file can't be read or written (permissions, disk full), a fresh UUID
+ * is returned for this session — telemetry still works, just not correlated
+ * across runs.
+ *
+ * Exported so tests can exercise the id-resolution invariants directly
+ * without spinning up the PostHog client.
+ * @internal
+ */
+export function getOrCreateTelemetryId(): string {
+  const idPath = join(getArchonHome(), 'telemetry-id');
+  try {
+    if (existsSync(idPath)) {
+      const existing = readFileSync(idPath, 'utf8').trim();
+      if (existing) return existing;
+    }
+  } catch (error) {
+    getLog().debug({ err: error as Error, idPath }, 'telemetry.id_read_failed');
+  }
+
+  const id = randomUUID();
+  try {
+    mkdirSync(getArchonHome(), { recursive: true });
+    writeFileSync(idPath, id, 'utf8');
+  } catch (error) {
+    getLog().debug({ err: error as Error, idPath }, 'telemetry.id_persist_failed');
+  }
+  return id;
+}
+
+let telemetryIdCache: string | undefined;
+function getTelemetryId(): string {
+  if (!telemetryIdCache) telemetryIdCache = getOrCreateTelemetryId();
+  return telemetryIdCache;
+}
+
+/**
+ * Lazy singleton. `undefined` = not yet initialized; `null` = disabled or
+ * init failed; `PostHog` = live client. Init runs once per process.
+ */
+let clientInit: Promise<PostHog | null> | undefined;
+
+async function getClient(): Promise<PostHog | null> {
+  if (clientInit === undefined) {
+    clientInit = initClient();
+  }
+  return clientInit;
+}
+
+/**
+ * Fetch wrapper that masks all failures as 200 responses. The PostHog SDK's
+ * internal `logFlushError` writes to stderr via `console.error` on any network
+ * or HTTP error, bypassing logger configuration (see `@posthog/core`
+ * `posthog-core-stateless.mjs` `logFlushError`). For a fire-and-forget
+ * telemetry path we want zero user-visible noise when PostHog is unreachable
+ * (offline, firewalled, DNS broken, rate-limited), so we intercept failures
+ * before the SDK sees them. The original error is still recorded at debug
+ * level.
+ */
+const FAKE_OK_RESPONSE: PostHogFetchResponse = {
+  status: 200,
+  text: () => Promise.resolve('{"status":"ok"}'),
+  json: () => Promise.resolve({ status: 'ok' }),
+  headers: { get: () => null },
+};
+
+async function silentFetch(
+  url: string,
+  options: PostHogFetchOptions
+): Promise<PostHogFetchResponse> {
+  try {
+    const res = await fetch(url, options as RequestInit);
+    if (res.status < 200 || res.status >= 400) {
+      getLog().debug({ status: res.status }, 'telemetry.http_non_2xx_suppressed');
+      return FAKE_OK_RESPONSE;
+    }
+    return res;
+  } catch (error) {
+    getLog().debug({ err: error as Error }, 'telemetry.fetch_failed_suppressed');
+    return FAKE_OK_RESPONSE;
+  }
+}
+
+async function initClient(): Promise<PostHog | null> {
+  if (isTelemetryDisabled()) return null;
+  try {
+    const posthogModule = await import('posthog-node');
+    const client = new posthogModule.PostHog(getApiKey(), {
+      host: getHost(),
+      flushAt: 20,
+      flushInterval: 10000,
+      disableGeoip: true,
+      fetch: silentFetch,
+    });
+    // Defensive: also hook the client-level error channel in case a future
+    // posthog-node version routes errors there instead of (or in addition to)
+    // the internal console.error path.
+    client.on('error', (err: Error) => {
+      getLog().debug({ err }, 'telemetry.client_error');
+    });
+    return client;
+  } catch (error) {
+    getLog().debug({ err: error as Error }, 'telemetry.init_failed');
+    return null;
+  }
+}
+
+export interface WorkflowInvokedProperties {
+  workflowName: string;
+  workflowDescription?: string;
+  platform?: string;
+  archonVersion?: string;
+}
+
+/**
+ * Fire-and-forget capture of a `workflow_invoked` event. Never throws, never
+ * awaits — safe to call from hot paths.
+ */
+export function captureWorkflowInvoked(props: WorkflowInvokedProperties): void {
+  if (isTelemetryDisabled()) return;
+  void (async (): Promise<void> => {
+    try {
+      const client = await getClient();
+      if (!client) return;
+      const description = props.workflowDescription?.slice(0, DESCRIPTION_MAX_LENGTH);
+      client.capture({
+        distinctId: getTelemetryId(),
+        event: 'workflow_invoked',
+        properties: {
+          $process_person_profile: false,
+          workflow_name: props.workflowName,
+          ...(description ? { workflow_description: description } : {}),
+          ...(props.platform ? { platform: props.platform } : {}),
+          ...(props.archonVersion ? { archon_version: props.archonVersion } : {}),
+        },
+      });
+    } catch (error) {
+      getLog().debug({ err: error as Error }, 'telemetry.capture_failed');
+    }
+  })();
+}
+
+/**
+ * Flush queued events and close the PostHog client. Call on process exit
+ * (server SIGTERM, end of CLI command) so buffered events aren't lost.
+ * Safe to call when telemetry was never initialized.
+ */
+export async function shutdownTelemetry(): Promise<void> {
+  if (clientInit === undefined) return;
+  try {
+    const client = await clientInit;
+    if (client) {
+      await client.shutdown();
+    }
+  } catch (error) {
+    getLog().debug({ err: error as Error }, 'telemetry.shutdown_failed');
+  } finally {
+    clientInit = undefined;
+  }
+}
+
+/**
+ * Reset internal state for tests. Not part of the public API.
+ * @internal
+ */
+export function resetTelemetryForTests(): void {
+  clientInit = undefined;
+  telemetryIdCache = undefined;
+}
diff --git a/packages/paths/src/update-check.ts b/packages/paths/src/update-check.ts
index 46652eb0d8..1e7da7dd41 100644
--- a/packages/paths/src/update-check.ts
+++ b/packages/paths/src/update-check.ts
@@ -1,5 +1,5 @@
 import { join } from 'path';
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { getArchonHome } from './archon-paths';
 import { createLogger } from './logger';
 
@@ -30,7 +30,6 @@ function getCachePath(): string {
 function readCache(): UpdateCheckCache | null {
   const cachePath = getCachePath();
   try {
-    if (!existsSync(cachePath)) return null;
     const raw = readFileSync(cachePath, 'utf-8');
     const data = JSON.parse(raw) as UpdateCheckCache;
     if (!data.latestVersion || !data.releaseUrl || typeof data.checkedAt !== 'number') {
diff --git a/packages/providers/package.json b/packages/providers/package.json
new file mode 100644
index 0000000000..5937d54658
--- /dev/null
+++ b/packages/providers/package.json
@@ -0,0 +1,38 @@
+{
+  "name": "@archon/providers",
+  "version": "0.3.7",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./types": "./src/types.ts",
+    "./claude/provider": "./src/claude/provider.ts",
+    "./claude/config": "./src/claude/config.ts",
+    "./claude/binary-resolver": "./src/claude/binary-resolver.ts",
+    "./codex/provider": "./src/codex/provider.ts",
+    "./codex/config": "./src/codex/config.ts",
+    "./codex/binary-resolver": "./src/codex/binary-resolver.ts",
+    "./community/pi": "./src/community/pi/index.ts",
+    "./errors": "./src/errors.ts",
+    "./registry": "./src/registry.ts"
+  },
+  "scripts": {
+    "test": "bun test src/claude/provider.test.ts && bun test src/codex/provider.test.ts && bun test src/registry.test.ts && bun test src/codex/binary-guard.test.ts && bun test src/codex/binary-resolver.test.ts && bun test src/codex/binary-resolver-dev.test.ts && bun test src/claude/binary-resolver.test.ts && bun test src/claude/binary-resolver-dev.test.ts && bun test src/community/pi/model-ref.test.ts && bun test src/community/pi/config.test.ts && bun test src/community/pi/event-bridge.test.ts && bun test src/community/pi/options-translator.test.ts && bun test src/community/pi/session-resolver.test.ts && bun test src/community/pi/provider.test.ts",
+    "type-check": "bun x tsc --noEmit"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.89",
+    "@archon/paths": "workspace:*",
+    "@mariozechner/pi-ai": "^0.67.5",
+    "@mariozechner/pi-coding-agent": "^0.67.5",
+    "@openai/codex-sdk": "^0.116.0",
+    "@sinclair/typebox": "^0.34.41"
+  },
+  "devDependencies": {
+    "pino": "^9"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  }
+}
diff --git a/packages/providers/src/claude/binary-resolver-dev.test.ts b/packages/providers/src/claude/binary-resolver-dev.test.ts
new file mode 100644
index 0000000000..2474c76d73
--- /dev/null
+++ b/packages/providers/src/claude/binary-resolver-dev.test.ts
@@ -0,0 +1,40 @@
+/**
+ * Tests for the Claude binary resolver in dev mode (BUNDLED_IS_BINARY=false).
+ * Separate file because binary-mode tests mock BUNDLED_IS_BINARY=true.
+ */
+import { describe, test, expect, mock } from 'bun:test';
+import { createMockLogger } from '../test/mocks/logger';
+
+mock.module('@archon/paths', () => ({
+  createLogger: mock(() => createMockLogger()),
+  BUNDLED_IS_BINARY: false,
+}));
+
+import { resolveClaudeBinaryPath } from './binary-resolver';
+
+describe('resolveClaudeBinaryPath (dev mode)', () => {
+  test('returns undefined when BUNDLED_IS_BINARY is false', async () => {
+    const result = await resolveClaudeBinaryPath();
+    expect(result).toBeUndefined();
+  });
+
+  test('returns undefined even with config path set', async () => {
+    const result = await resolveClaudeBinaryPath('/some/custom/path');
+    expect(result).toBeUndefined();
+  });
+
+  test('returns undefined even with env var set', async () => {
+    const original = process.env.CLAUDE_BIN_PATH;
+    process.env.CLAUDE_BIN_PATH = '/some/env/path';
+    try {
+      const result = await resolveClaudeBinaryPath();
+      expect(result).toBeUndefined();
+    } finally {
+      if (original !== undefined) {
+        process.env.CLAUDE_BIN_PATH = original;
+      } else {
+        delete process.env.CLAUDE_BIN_PATH;
+      }
+    }
+  });
+});
diff --git a/packages/providers/src/claude/binary-resolver.test.ts b/packages/providers/src/claude/binary-resolver.test.ts
new file mode 100644
index 0000000000..f87e78f36d
--- /dev/null
+++ b/packages/providers/src/claude/binary-resolver.test.ts
@@ -0,0 +1,91 @@
+/**
+ * Tests for the Claude binary resolver in binary mode.
+ *
+ * Must run in its own bun test invocation because it mocks @archon/paths
+ * with BUNDLED_IS_BINARY=true, which conflicts with other test files.
+ */
+import { describe, test, expect, mock, beforeEach, afterAll, spyOn } from 'bun:test';
+import { createMockLogger } from '../test/mocks/logger';
+
+const mockLogger = createMockLogger();
+
+// Mock @archon/paths with BUNDLED_IS_BINARY = true (binary mode)
+mock.module('@archon/paths', () => ({
+  createLogger: mock(() => mockLogger),
+  BUNDLED_IS_BINARY: true,
+}));
+
+import * as resolver from './binary-resolver';
+
+describe('resolveClaudeBinaryPath (binary mode)', () => {
+  const originalEnv = process.env.CLAUDE_BIN_PATH;
+  let fileExistsSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(() => {
+    delete process.env.CLAUDE_BIN_PATH;
+    fileExistsSpy?.mockRestore();
+    mockLogger.info.mockClear();
+  });
+
+  afterAll(() => {
+    if (originalEnv !== undefined) {
+      process.env.CLAUDE_BIN_PATH = originalEnv;
+    } else {
+      delete process.env.CLAUDE_BIN_PATH;
+    }
+    fileExistsSpy?.mockRestore();
+  });
+
+  test('uses CLAUDE_BIN_PATH env var when set and file exists', async () => {
+    process.env.CLAUDE_BIN_PATH = '/usr/local/lib/node_modules/@anthropic-ai/claude-code/cli.js';
+    fileExistsSpy = spyOn(resolver, 'fileExists').mockReturnValue(true);
+
+    const result = await resolver.resolveClaudeBinaryPath();
+    expect(result).toBe('/usr/local/lib/node_modules/@anthropic-ai/claude-code/cli.js');
+  });
+
+  test('throws when CLAUDE_BIN_PATH is set but file does not exist', async () => {
+    process.env.CLAUDE_BIN_PATH = '/nonexistent/cli.js';
+    fileExistsSpy = spyOn(resolver, 'fileExists').mockReturnValue(false);
+
+    await expect(resolver.resolveClaudeBinaryPath()).rejects.toThrow(
+      'CLAUDE_BIN_PATH is set to "/nonexistent/cli.js" but the file does not exist'
+    );
+  });
+
+  test('uses config claudeBinaryPath when file exists', async () => {
+    fileExistsSpy = spyOn(resolver, 'fileExists').mockReturnValue(true);
+
+    const result = await resolver.resolveClaudeBinaryPath('/custom/claude/cli.js');
+    expect(result).toBe('/custom/claude/cli.js');
+  });
+
+  test('throws when config claudeBinaryPath file does not exist', async () => {
+    fileExistsSpy = spyOn(resolver, 'fileExists').mockReturnValue(false);
+
+    await expect(resolver.resolveClaudeBinaryPath('/nonexistent/cli.js')).rejects.toThrow(
+      'assistants.claude.claudeBinaryPath is set to "/nonexistent/cli.js" but the file does not exist'
+    );
+  });
+
+  test('env var takes precedence over config path', async () => {
+    process.env.CLAUDE_BIN_PATH = '/env/cli.js';
+    fileExistsSpy = spyOn(resolver, 'fileExists').mockReturnValue(true);
+
+    const result = await resolver.resolveClaudeBinaryPath('/config/cli.js');
+    expect(result).toBe('/env/cli.js');
+  });
+
+  test('throws with install instructions when nothing configured', async () => {
+    fileExistsSpy = spyOn(resolver, 'fileExists').mockReturnValue(false);
+
+    const promise = resolver.resolveClaudeBinaryPath();
+    await expect(promise).rejects.toThrow('Claude Code not found');
+    await expect(promise).rejects.toThrow('CLAUDE_BIN_PATH');
+    // Native curl installer is Anthropic's primary recommendation.
+    await expect(promise).rejects.toThrow('https://claude.ai/install.sh');
+    // npm path is still documented as an alternative.
+    await expect(promise).rejects.toThrow('npm install -g @anthropic-ai/claude-code');
+    await expect(promise).rejects.toThrow('claudeBinaryPath');
+  });
+});
diff --git a/packages/providers/src/claude/binary-resolver.ts b/packages/providers/src/claude/binary-resolver.ts
new file mode 100644
index 0000000000..f236acb277
--- /dev/null
+++ b/packages/providers/src/claude/binary-resolver.ts
@@ -0,0 +1,94 @@
+/**
+ * Claude Code CLI resolver for compiled (bun --compile) archon binaries.
+ *
+ * The @anthropic-ai/claude-agent-sdk spawns a subprocess using
+ * `pathToClaudeCodeExecutable`. In dev mode the SDK resolves this from its
+ * own node_modules location; in compiled binaries that path is frozen to
+ * the build host's filesystem and does not exist on end-user machines.
+ *
+ * Resolution order (binary mode only):
+ * 1. `CLAUDE_BIN_PATH` environment variable
+ * 2. `assistants.claude.claudeBinaryPath` in config
+ * 3. Throw with install instructions
+ *
+ * In dev mode (BUNDLED_IS_BINARY=false), returns undefined so the caller
+ * omits `pathToClaudeCodeExecutable` entirely and the SDK resolves via its
+ * normal node_modules lookup.
+ */
+import { existsSync as _existsSync } from 'node:fs';
+import { BUNDLED_IS_BINARY, createLogger } from '@archon/paths';
+
+/** Wrapper for existsSync — enables spyOn in tests (direct imports can't be spied on). */
+export function fileExists(path: string): boolean {
+  return _existsSync(path);
+}
+
+/** Lazy-initialized logger */
+let cachedLog: ReturnType<typeof createLogger> | undefined;
+function getLog(): ReturnType<typeof createLogger> {
+  if (!cachedLog) cachedLog = createLogger('claude-binary');
+  return cachedLog;
+}
+
+const INSTALL_INSTRUCTIONS =
+  'Claude Code not found. Archon requires the Claude Code executable to be\n' +
+  'reachable at a configured path in compiled builds.\n\n' +
+  'To fix, install Claude Code and point Archon at it:\n\n' +
+  '  macOS / Linux (recommended — native installer):\n' +
+  '    curl -fsSL https://claude.ai/install.sh | bash\n' +
+  '    export CLAUDE_BIN_PATH="$HOME/.local/bin/claude"\n\n' +
+  '  Windows (PowerShell):\n' +
+  '    irm https://claude.ai/install.ps1 | iex\n' +
+  '    $env:CLAUDE_BIN_PATH = "$env:USERPROFILE\\.local\\bin\\claude.exe"\n\n' +
+  '  Or via npm (alternative):\n' +
+  '    npm install -g @anthropic-ai/claude-code\n' +
+  '    export CLAUDE_BIN_PATH="$(npm root -g)/@anthropic-ai/claude-code/cli.js"\n\n' +
+  'Persist the path in ~/.archon/config.yaml instead of the env var:\n' +
+  '    assistants:\n' +
+  '      claude:\n' +
+  '        claudeBinaryPath: /absolute/path/to/claude\n\n' +
+  'See: https://archon.diy/docs/reference/configuration#claude';
+
+/**
+ * Resolve the path to the Claude Code SDK's cli.js.
+ *
+ * In dev mode: returns undefined (let SDK resolve via node_modules).
+ * In binary mode: resolves from env/config, or throws with install instructions.
+ */
+export async function resolveClaudeBinaryPath(
+  configClaudeBinaryPath?: string
+): Promise<string | undefined> {
+  if (!BUNDLED_IS_BINARY) return undefined;
+
+  // 1. Environment variable override
+  const envPath = process.env.CLAUDE_BIN_PATH;
+  if (envPath) {
+    if (!fileExists(envPath)) {
+      throw new Error(
+        `CLAUDE_BIN_PATH is set to "${envPath}" but the file does not exist.\n` +
+          'Please verify the path points to the Claude Code executable (native binary\n' +
+          'from the curl/PowerShell installer, or cli.js from an npm global install).'
+      );
+    }
+    getLog().info({ binaryPath: envPath, source: 'env' }, 'claude.binary_resolved');
+    return envPath;
+  }
+
+  // 2. Config file override
+  if (configClaudeBinaryPath) {
+    if (!fileExists(configClaudeBinaryPath)) {
+      throw new Error(
+        `assistants.claude.claudeBinaryPath is set to "${configClaudeBinaryPath}" but the file does not exist.\n` +
+          'Please verify the path in .archon/config.yaml points to the Claude Code executable.'
+      );
+    }
+    getLog().info(
+      { binaryPath: configClaudeBinaryPath, source: 'config' },
+      'claude.binary_resolved'
+    );
+    return configClaudeBinaryPath;
+  }
+
+  // 3. Not found — throw with install instructions
+  throw new Error(INSTALL_INSTRUCTIONS);
+}
diff --git a/packages/providers/src/claude/capabilities.ts b/packages/providers/src/claude/capabilities.ts
new file mode 100644
index 0000000000..dfb5e7ed08
--- /dev/null
+++ b/packages/providers/src/claude/capabilities.ts
@@ -0,0 +1,17 @@
+import type { ProviderCapabilities } from '../types';
+
+export const CLAUDE_CAPABILITIES: ProviderCapabilities = {
+  sessionResume: true,
+  mcp: true,
+  hooks: true,
+  skills: true,
+  agents: true,
+  toolRestrictions: true,
+  structuredOutput: true,
+  envInjection: true,
+  costControl: true,
+  effortControl: true,
+  thinkingControl: true,
+  fallbackModel: true,
+  sandbox: true,
+};
diff --git a/packages/providers/src/claude/config.ts b/packages/providers/src/claude/config.ts
new file mode 100644
index 0000000000..33b33209ee
--- /dev/null
+++ b/packages/providers/src/claude/config.ts
@@ -0,0 +1,35 @@
+/**
+ * Typed config parsing for Claude provider defaults.
+ * Validates and narrows the opaque assistantConfig to typed fields.
+ */
+import type { ClaudeProviderDefaults } from '../types';
+
+// Re-export so consumers can import the type from either location
+export type { ClaudeProviderDefaults } from '../types';
+
+/**
+ * Parse raw assistantConfig into typed Claude defaults.
+ * Defensive: invalid fields are silently dropped (not thrown).
+ */
+export function parseClaudeConfig(raw: Record<string, unknown>): ClaudeProviderDefaults {
+  const result: ClaudeProviderDefaults = {};
+
+  if (typeof raw.model === 'string') {
+    result.model = raw.model;
+  }
+
+  if (Array.isArray(raw.settingSources)) {
+    const valid = raw.settingSources.filter(
+      (s): s is 'project' | 'user' => s === 'project' || s === 'user'
+    );
+    if (valid.length > 0) {
+      result.settingSources = valid;
+    }
+  }
+
+  if (typeof raw.claudeBinaryPath === 'string') {
+    result.claudeBinaryPath = raw.claudeBinaryPath;
+  }
+
+  return result;
+}
diff --git a/packages/providers/src/claude/index.ts b/packages/providers/src/claude/index.ts
new file mode 100644
index 0000000000..cc540542e4
--- /dev/null
+++ b/packages/providers/src/claude/index.ts
@@ -0,0 +1,8 @@
+export { ClaudeProvider } from './provider';
+export { parseClaudeConfig, type ClaudeProviderDefaults } from './config';
+export {
+  loadMcpConfig,
+  buildSDKHooksFromYAML,
+  withFirstMessageTimeout,
+  getProcessUid,
+} from './provider';
diff --git a/packages/core/src/clients/claude.test.ts b/packages/providers/src/claude/provider.test.ts
similarity index 66%
rename from packages/core/src/clients/claude.test.ts
rename to packages/providers/src/claude/provider.test.ts
index e09c004822..77880128da 100644
--- a/packages/core/src/clients/claude.test.ts
+++ b/packages/providers/src/claude/provider.test.ts
@@ -1,4 +1,4 @@
-import { describe, test, expect, mock, beforeEach, afterEach, spyOn } from 'bun:test';
+import { describe, test, expect, mock, beforeEach, spyOn } from 'bun:test';
 import { createMockLogger } from '../test/mocks/logger';
 
 const mockLogger = createMockLogger();
@@ -16,17 +16,44 @@ mock.module('@anthropic-ai/claude-agent-sdk', () => ({
   query: mockQuery,
 }));
 
-import { ClaudeClient } from './claude';
-import * as claudeModule from './claude';
-import * as codebaseDb from '../db/codebases';
-import * as envLeakScanner from '../utils/env-leak-scanner';
-import * as configLoader from '../config/config-loader';
+import { ClaudeProvider, shouldPassNoEnvFile } from './provider';
+import * as claudeModule from './provider';
 
-describe('ClaudeClient', () => {
-  let client: ClaudeClient;
+describe('shouldPassNoEnvFile', () => {
+  test('returns true when cliPath is undefined (dev mode — SDK spawns cli.js via Bun)', () => {
+    expect(shouldPassNoEnvFile(undefined)).toBe(true);
+  });
+
+  test('returns true for an explicit cli.js path (npm-installed, SDK spawns via Bun/Node)', () => {
+    expect(
+      shouldPassNoEnvFile('/usr/local/lib/node_modules/@anthropic-ai/claude-code/cli.js')
+    ).toBe(true);
+  });
+
+  test('returns false for a native binary path (curl installer, SDK execs directly)', () => {
+    expect(shouldPassNoEnvFile('/Users/test/.local/bin/claude')).toBe(false);
+  });
+
+  test('returns false for a Windows native binary path', () => {
+    expect(shouldPassNoEnvFile('C:\\Users\\test\\.local\\bin\\claude.exe')).toBe(false);
+  });
+
+  test('returns false for a Homebrew symlink path', () => {
+    expect(shouldPassNoEnvFile('/opt/homebrew/bin/claude')).toBe(false);
+  });
+
+  test('extension match is suffix-only (paths ending in cli.js but not literally `.js` extension are still rejected)', () => {
+    // Defensive: only string-suffix matches `.js` count as JS executables.
+    expect(shouldPassNoEnvFile('/path/to/cli.json')).toBe(false);
+    expect(shouldPassNoEnvFile('/path/to/cli.js.bak')).toBe(false);
+  });
+});
+
+describe('ClaudeProvider', () => {
+  let client: ClaudeProvider;
 
   beforeEach(() => {
-    client = new ClaudeClient({ retryBaseDelayMs: 1 });
+    client = new ClaudeProvider({ retryBaseDelayMs: 1 });
     mockQuery.mockClear();
     mockLogger.info.mockClear();
     mockLogger.warn.mockClear();
@@ -37,7 +64,7 @@ describe('ClaudeClient', () => {
   describe('constructor', () => {
     test('throws when running as root (UID 0)', () => {
       const spy = spyOn(claudeModule, 'getProcessUid').mockReturnValue(0);
-      expect(() => new ClaudeClient()).toThrow(
+      expect(() => new ClaudeProvider()).toThrow(
         'does not support bypassPermissions when running as root'
       );
       spy.mockRestore();
@@ -45,13 +72,13 @@ describe('ClaudeClient', () => {
 
     test('does not throw for non-root user', () => {
       const spy = spyOn(claudeModule, 'getProcessUid').mockReturnValue(1000);
-      expect(() => new ClaudeClient()).not.toThrow();
+      expect(() => new ClaudeProvider()).not.toThrow();
       spy.mockRestore();
     });
 
     test('does not throw when process.getuid is unavailable (Windows)', () => {
       const spy = spyOn(claudeModule, 'getProcessUid').mockReturnValue(undefined);
-      expect(() => new ClaudeClient()).not.toThrow();
+      expect(() => new ClaudeProvider()).not.toThrow();
       spy.mockRestore();
     });
   });
@@ -62,6 +89,27 @@ describe('ClaudeClient', () => {
     });
   });
 
+  describe('getCapabilities', () => {
+    test('returns full capability set for Claude provider', () => {
+      const caps = client.getCapabilities();
+      expect(caps).toEqual({
+        sessionResume: true,
+        mcp: true,
+        hooks: true,
+        skills: true,
+        agents: true,
+        toolRestrictions: true,
+        structuredOutput: true,
+        envInjection: true,
+        costControl: true,
+        effortControl: true,
+        thinkingControl: true,
+        fallbackModel: true,
+        sandbox: true,
+      });
+    });
+  });
+
   describe('sendQuery', () => {
     test('yields text events from assistant messages', async () => {
       mockQuery.mockImplementation(async function* () {
@@ -306,7 +354,6 @@ describe('ClaudeClient', () => {
       });
 
       // Consume the generator
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       for await (const _ of client.sendQuery('my prompt', '/my/workspace', undefined, {
         model: 'sonnet',
       })) {
@@ -328,7 +375,6 @@ describe('ClaudeClient', () => {
         // Empty generator
       });
 
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       for await (const _ of client.sendQuery('test', '/workspace')) {
         // consume
       }
@@ -343,7 +389,6 @@ describe('ClaudeClient', () => {
         // Empty generator
       });
 
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       for await (const _ of client.sendQuery('test', '/workspace', undefined, {
         persistSession: true,
       })) {
@@ -363,7 +408,6 @@ describe('ClaudeClient', () => {
         // Empty generator
       });
 
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       for await (const _ of client.sendQuery('prompt', '/workspace', 'session-to-resume')) {
         // consume
       }
@@ -447,9 +491,6 @@ describe('ClaudeClient', () => {
     });
 
     test('subprocess env passes through all process.env keys (no allowlist filtering)', async () => {
-      // With the allowlist removed, buildSubprocessEnv returns { ...process.env }.
-      // CWD .env leakage and CLAUDECODE markers are handled at entry point by
-      // stripCwdEnv(), not by buildSubprocessEnv(). See #1067, #1097.
       const originalKey = process.env.CUSTOM_USER_KEY;
       process.env.CUSTOM_USER_KEY = 'user-trusted-value';
 
@@ -457,15 +498,23 @@ describe('ClaudeClient', () => {
         // Empty generator
       });
 
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       for await (const _ of client.sendQuery('test', '/workspace')) {
         // consume
       }
 
-      const callArgs = mockQuery.mock.calls[0][0] as { options: { env: NodeJS.ProcessEnv } };
+      const callArgs = mockQuery.mock.calls[0][0] as {
+        options: { env: NodeJS.ProcessEnv; executableArgs?: string[] };
+      };
+      // --no-env-file prevents Bun from auto-loading .env in subprocess CWD
+      expect(callArgs.options.executableArgs).toEqual(['--no-env-file']);
       expect(callArgs.options.env.CUSTOM_USER_KEY).toBe('user-trusted-value');
-      expect(callArgs.options.env.PATH).toBe(process.env.PATH);
-      expect(callArgs.options.env.HOME).toBe(process.env.HOME);
+      // Windows uses "Path" casing in spread objects and USERPROFILE instead of HOME
+      const envPath = callArgs.options.env.PATH ?? callArgs.options.env.Path;
+      const processPath = process.env.PATH ?? process.env.Path;
+      expect(envPath).toBe(processPath);
+      const envHome = callArgs.options.env.HOME ?? callArgs.options.env.USERPROFILE;
+      const processHome = process.env.HOME ?? process.env.USERPROFILE;
+      expect(envHome).toBe(processHome);
 
       // Cleanup
       if (originalKey !== undefined) process.env.CUSTOM_USER_KEY = originalKey;
@@ -549,35 +598,29 @@ describe('ClaudeClient', () => {
     });
 
     test('classifies "Operation aborted" errors as crash and retries', async () => {
-      // Simulates the SDK cleanup race: PostToolUse hook writes to a closed pipe
-      // after a DAG node abort. Should be classified as 'crash' (not 'unknown')
-      // so the retry path is taken.
       const error = new Error('Operation aborted');
       mockQuery.mockImplementation(async function* () {
         throw error;
       });
 
       const consumeGenerator = async (): Promise<void> => {
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
         for await (const _ of client.sendQuery('test', '/workspace')) {
           // consume
         }
       };
 
-      // crash classification = retried up to 3 times → 4 total calls
+      // crash classification = retried up to 3 times -> 4 total calls
       await expect(consumeGenerator()).rejects.toThrow(/Claude Code crash/);
       expect(mockQuery).toHaveBeenCalledTimes(4);
     }, 5_000);
 
     test('classifies mixed-case "OPERATION ABORTED" errors as crash', async () => {
-      // Pattern matching uses .toLowerCase() — case must not matter
       const error = new Error('OPERATION ABORTED');
       mockQuery.mockImplementation(async function* () {
         throw error;
       });
 
       const consumeGenerator = async (): Promise<void> => {
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
         for await (const _ of client.sendQuery('test', '/workspace')) {
           // consume
         }
@@ -588,8 +631,6 @@ describe('ClaudeClient', () => {
     }, 5_000);
 
     test('captures all stderr output for diagnostics', async () => {
-      // When the subprocess crashes, the enriched error should include all stderr,
-      // not just lines matching error keywords
       mockQuery.mockImplementation(async function* (args: {
         options: { stderr?: (data: string) => void };
       }) {
@@ -608,7 +649,7 @@ describe('ClaudeClient', () => {
         }
       };
 
-      // Use rejects so assertions always execute — prevents vacuous pass when mock doesn't throw
+      // Use rejects so assertions always execute
       const err = await consumeGenerator().catch((e: unknown) => e as Error);
       expect(err).toBeInstanceOf(Error);
       // The error should contain stderr context from ALL captured lines
@@ -617,14 +658,13 @@ describe('ClaudeClient', () => {
       expect(err.message).toContain('startup diagnostic');
     }, 5_000);
 
-    test('passes settingSources from request options', async () => {
+    test('passes settingSources from assistantConfig', async () => {
       mockQuery.mockImplementation(async function* () {
         yield { type: 'result', session_id: 'test-session' };
       });
 
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       for await (const _ of client.sendQuery('test', '/tmp', undefined, {
-        settingSources: ['project', 'user'],
+        assistantConfig: { settingSources: ['project', 'user'] },
       })) {
         // consume
       }
@@ -639,7 +679,6 @@ describe('ClaudeClient', () => {
         yield { type: 'result', session_id: 'test-session' };
       });
 
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       for await (const _ of client.sendQuery('test', '/tmp')) {
         // consume
       }
@@ -654,7 +693,6 @@ describe('ClaudeClient', () => {
         yield { type: 'result', session_id: 'sid' };
       });
 
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       for await (const _ of client.sendQuery('test', '/tmp', undefined, {
         env: { MY_SECRET: 'abc123' },
       })) {
@@ -675,8 +713,7 @@ describe('ClaudeClient', () => {
         yield { type: 'result', session_id: 'sid' };
       });
 
-      // HOME is always in process.env — override it to verify priority
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      // HOME is always in process.env -- override it to verify priority
       for await (const _ of client.sendQuery('test', '/tmp', undefined, {
         env: { HOME: '/custom/home' },
       })) {
@@ -689,13 +726,14 @@ describe('ClaudeClient', () => {
       expect(env.HOME).toBe('/custom/home');
     });
 
-    test('passes effort to SDK when provided', async () => {
+    test('passes effort to SDK via nodeConfig', async () => {
       mockQuery.mockImplementation(async function* () {
         yield { type: 'result', session_id: 'sid' };
       });
 
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      for await (const _ of client.sendQuery('test', '/tmp', undefined, { effort: 'high' })) {
+      for await (const _ of client.sendQuery('test', '/tmp', undefined, {
+        nodeConfig: { effort: 'high' },
+      })) {
         // consume
       }
 
@@ -704,12 +742,11 @@ describe('ClaudeClient', () => {
       expect(callArgs.options.effort).toBe('high');
     });
 
-    test('omits effort from SDK when not provided', async () => {
+    test('omits effort from SDK when not provided in nodeConfig', async () => {
       mockQuery.mockImplementation(async function* () {
         yield { type: 'result', session_id: 'sid' };
       });
 
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       for await (const _ of client.sendQuery('test', '/tmp')) {
         // consume
       }
@@ -719,14 +756,13 @@ describe('ClaudeClient', () => {
       expect(callArgs.options).not.toHaveProperty('effort');
     });
 
-    test('passes thinking object to SDK', async () => {
+    test('passes thinking object to SDK via nodeConfig', async () => {
       mockQuery.mockImplementation(async function* () {
         yield { type: 'result', session_id: 'sid' };
       });
 
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       for await (const _ of client.sendQuery('test', '/tmp', undefined, {
-        thinking: { type: 'enabled', budgetTokens: 8000 },
+        nodeConfig: { thinking: { type: 'enabled', budgetTokens: 8000 } },
       })) {
         // consume
       }
@@ -741,7 +777,6 @@ describe('ClaudeClient', () => {
         yield { type: 'result', session_id: 'sid' };
       });
 
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       for await (const _ of client.sendQuery('test', '/tmp', undefined, { maxBudgetUsd: 5.0 })) {
         // consume
       }
@@ -756,7 +791,6 @@ describe('ClaudeClient', () => {
         yield { type: 'result', session_id: 'sid' };
       });
 
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       for await (const _ of client.sendQuery('test', '/tmp', undefined, {
         systemPrompt: 'You are a security reviewer',
       })) {
@@ -773,7 +807,6 @@ describe('ClaudeClient', () => {
         yield { type: 'result', session_id: 'sid' };
       });
 
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       for await (const _ of client.sendQuery('test', '/tmp')) {
         // consume
       }
@@ -788,7 +821,6 @@ describe('ClaudeClient', () => {
         yield { type: 'result', session_id: 'sid' };
       });
 
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       for await (const _ of client.sendQuery('test', '/tmp', undefined, {
         fallbackModel: 'claude-haiku-4-5',
       })) {
@@ -800,14 +832,13 @@ describe('ClaudeClient', () => {
       expect(callArgs.options.fallbackModel).toBe('claude-haiku-4-5');
     });
 
-    test('passes betas array to SDK', async () => {
+    test('passes betas array to SDK via nodeConfig', async () => {
       mockQuery.mockImplementation(async function* () {
         yield { type: 'result', session_id: 'sid' };
       });
 
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       for await (const _ of client.sendQuery('test', '/tmp', undefined, {
-        betas: ['context-1m-2025-08-07'],
+        nodeConfig: { betas: ['context-1m-2025-08-07'] },
       })) {
         // consume
       }
@@ -817,15 +848,16 @@ describe('ClaudeClient', () => {
       expect(callArgs.options.betas).toEqual(['context-1m-2025-08-07']);
     });
 
-    test('passes sandbox object to SDK', async () => {
+    test('passes sandbox object to SDK via nodeConfig', async () => {
       mockQuery.mockImplementation(async function* () {
         yield { type: 'result', session_id: 'sid' };
       });
 
       const sandbox = { enabled: true, network: { allowedDomains: [] } };
 
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      for await (const _ of client.sendQuery('test', '/tmp', undefined, { sandbox })) {
+      for await (const _ of client.sendQuery('test', '/tmp', undefined, {
+        nodeConfig: { sandbox },
+      })) {
         // consume
       }
 
@@ -857,157 +889,6 @@ describe('ClaudeClient', () => {
       expect(chunks[0]).toEqual({ type: 'assistant', content: 'Real content' });
     });
   });
-
-  describe('pre-spawn env leak gate', () => {
-    let spyFindByDefaultCwd: ReturnType<typeof spyOn>;
-    let spyFindByPathPrefix: ReturnType<typeof spyOn>;
-    let spyScan: ReturnType<typeof spyOn>;
-
-    beforeEach(() => {
-      spyFindByDefaultCwd = spyOn(codebaseDb, 'findCodebaseByDefaultCwd').mockResolvedValue(null);
-      spyFindByPathPrefix = spyOn(codebaseDb, 'findCodebaseByPathPrefix').mockResolvedValue(null);
-      spyScan = spyOn(envLeakScanner, 'scanPathForSensitiveKeys').mockReturnValue({
-        path: '/workspace',
-        findings: [],
-      });
-      mockQuery.mockImplementation(async function* () {
-        yield { type: 'result', session_id: 'sid-gate' };
-      });
-    });
-
-    afterEach(() => {
-      spyFindByDefaultCwd.mockRestore();
-      spyFindByPathPrefix.mockRestore();
-      spyScan.mockRestore();
-    });
-
-    test('throws EnvLeakError when .env contains sensitive keys and registered codebase has no consent', async () => {
-      spyFindByDefaultCwd.mockResolvedValueOnce({
-        id: 'codebase-1',
-        allow_env_keys: false,
-        default_cwd: '/workspace',
-      });
-      spyScan.mockReturnValueOnce({
-        path: '/workspace',
-        findings: [{ file: '.env', keys: ['ANTHROPIC_API_KEY'] }],
-      });
-
-      await expect(async () => {
-        for await (const _ of client.sendQuery('test', '/workspace')) {
-          // consume
-        }
-      }).toThrow('Cannot run workflow');
-    });
-
-    test('skips scan entirely when cwd is not a registered codebase', async () => {
-      // Both lookups return null (default from beforeEach) → unregistered cwd.
-      // Even if sensitive keys would be present, the pre-spawn check must not run
-      // because the canonical gate is registerRepoAtPath, not sendQuery.
-      spyScan.mockReturnValue({
-        path: '/workspace',
-        findings: [{ file: '.env', keys: ['ANTHROPIC_API_KEY'] }],
-      });
-
-      const chunks = [];
-      for await (const chunk of client.sendQuery('test', '/workspace')) {
-        chunks.push(chunk);
-      }
-
-      expect(spyScan).not.toHaveBeenCalled();
-      expect(chunks).toHaveLength(1);
-    });
-
-    test('skips scan when codebase has allow_env_keys: true', async () => {
-      spyFindByDefaultCwd.mockResolvedValueOnce({
-        id: 'codebase-1',
-        allow_env_keys: true,
-        default_cwd: '/workspace',
-      });
-
-      const chunks = [];
-      for await (const chunk of client.sendQuery('test', '/workspace')) {
-        chunks.push(chunk);
-      }
-
-      expect(spyScan).not.toHaveBeenCalled();
-      expect(chunks).toHaveLength(1);
-    });
-
-    test('proceeds without scanning when cwd has no registered codebase', async () => {
-      // Unregistered cwd — the pre-spawn safety net is out of scope.
-      const chunks = [];
-      for await (const chunk of client.sendQuery('test', '/workspace')) {
-        chunks.push(chunk);
-      }
-
-      expect(spyScan).not.toHaveBeenCalled();
-      expect(chunks).toHaveLength(1);
-    });
-
-    test('skips scan when allowTargetRepoKeys is true in merged config', async () => {
-      spyFindByDefaultCwd.mockResolvedValueOnce({
-        id: 'codebase-1',
-        allow_env_keys: false,
-        default_cwd: '/workspace',
-      });
-      const spyLoadConfig = spyOn(configLoader, 'loadConfig').mockResolvedValueOnce({
-        allowTargetRepoKeys: true,
-      } as Awaited<ReturnType<typeof configLoader.loadConfig>>);
-      // Even though scanner would return a finding, the config bypass must short-circuit
-      spyScan.mockReturnValueOnce({
-        path: '/workspace',
-        findings: [{ file: '.env', keys: ['ANTHROPIC_API_KEY'] }],
-      });
-
-      const chunks = [];
-      for await (const chunk of client.sendQuery('test', '/workspace')) {
-        chunks.push(chunk);
-      }
-
-      expect(spyScan).not.toHaveBeenCalled();
-      expect(chunks).toHaveLength(1);
-      spyLoadConfig.mockRestore();
-    });
-
-    test('falls back to scanner when loadConfig throws (fail-closed)', async () => {
-      spyFindByDefaultCwd.mockResolvedValueOnce({
-        id: 'codebase-1',
-        allow_env_keys: false,
-        default_cwd: '/workspace',
-      });
-      const spyLoadConfig = spyOn(configLoader, 'loadConfig').mockRejectedValueOnce(
-        new Error('YAML parse error')
-      );
-      spyScan.mockReturnValueOnce({
-        path: '/workspace',
-        findings: [{ file: '.env', keys: ['ANTHROPIC_API_KEY'] }],
-      });
-
-      await expect(async () => {
-        for await (const _ of client.sendQuery('test', '/workspace')) {
-          // consume
-        }
-      }).toThrow('Cannot run workflow');
-      expect(spyScan).toHaveBeenCalled();
-      spyLoadConfig.mockRestore();
-    });
-
-    test('uses prefix lookup for worktree paths when exact match returns null', async () => {
-      spyFindByPathPrefix.mockResolvedValueOnce({
-        id: 'codebase-1',
-        allow_env_keys: true,
-        default_cwd: '/workspace/source',
-      });
-
-      const chunks = [];
-      for await (const chunk of client.sendQuery('test', '/workspace/worktrees/feature')) {
-        chunks.push(chunk);
-      }
-
-      expect(spyFindByPathPrefix).toHaveBeenCalledWith('/workspace/worktrees/feature');
-      expect(spyScan).not.toHaveBeenCalled();
-    });
-  });
 });
 
 describe('withFirstMessageTimeout', () => {
@@ -1095,3 +976,318 @@ describe('withFirstMessageTimeout', () => {
     );
   });
 });
+
+// ─── Behavioral regression tests (black-box via sendQuery) ───────────────
+// These cover specific fixes from the sendQuery decomposition review:
+// timeout preservation, one-time warnings, abort forwarding, error enrichment.
+
+describe('sendQuery decomposition behaviors', () => {
+  let client: ClaudeProvider;
+
+  beforeEach(() => {
+    client = new ClaudeProvider({ retryBaseDelayMs: 1 });
+    mockQuery.mockClear();
+    mockLogger.info.mockClear();
+    mockLogger.warn.mockClear();
+    mockLogger.error.mockClear();
+    mockLogger.debug.mockClear();
+  });
+
+  test('preserves first-event timeout error instead of generic abort', async () => {
+    // withFirstMessageTimeout aborts the controller then throws.
+    // classifyAndEnrichError must preserve the timeout message, not "Query aborted".
+    mockQuery.mockImplementation(async function* () {
+      await new Promise(() => {}); // hang forever
+      yield { type: 'result', session_id: 'never' };
+    });
+
+    const consumeGenerator = async (): Promise<void> => {
+      // Use env var to set a short timeout for the test
+      const original = process.env.ARCHON_CLAUDE_FIRST_EVENT_TIMEOUT_MS;
+      process.env.ARCHON_CLAUDE_FIRST_EVENT_TIMEOUT_MS = '50';
+      try {
+        for await (const _ of client.sendQuery('test', '/workspace')) {
+          // consume
+        }
+      } finally {
+        if (original !== undefined) process.env.ARCHON_CLAUDE_FIRST_EVENT_TIMEOUT_MS = original;
+        else delete process.env.ARCHON_CLAUDE_FIRST_EVENT_TIMEOUT_MS;
+      }
+    };
+
+    await expect(consumeGenerator()).rejects.toThrow('produced no output within');
+    // Must NOT be "Query aborted"
+    await expect(consumeGenerator()).rejects.not.toThrow('Query aborted');
+  });
+
+  test('emits nodeConfig warnings only once even when retries occur', async () => {
+    let callCount = 0;
+    mockQuery.mockImplementation(async function* () {
+      callCount++;
+      if (callCount <= 2) {
+        throw new Error('process exited with code 1'); // crash → retried
+      }
+      yield {
+        type: 'assistant',
+        message: { content: [{ type: 'text', text: 'ok' }] },
+      };
+    });
+
+    const chunks = [];
+    for await (const chunk of client.sendQuery('test', '/workspace', undefined, {
+      nodeConfig: { effort: 'high' },
+    })) {
+      chunks.push(chunk);
+    }
+
+    // nodeConfig with effort doesn't produce warnings, but let's verify
+    // no system chunks are duplicated. Use a nodeConfig that doesn't warn.
+    // The point is: zero warning chunks means zero, not zero × 3 retries.
+    const systemChunks = chunks.filter(c => c.type === 'system');
+    expect(systemChunks).toHaveLength(0);
+    expect(callCount).toBe(3); // Confirms retries happened
+  }, 5_000);
+
+  test('abort signal cancels query across retries without listener leak', async () => {
+    const abortController = new AbortController();
+    let callCount = 0;
+
+    mockQuery.mockImplementation(async function* () {
+      callCount++;
+      if (callCount === 1) {
+        // First attempt crashes → triggers retry. Abort during the retry delay
+        // so the next iteration's abortSignal.aborted check catches it.
+        setTimeout(() => abortController.abort(), 0);
+        throw new Error('process exited with code 1');
+      }
+      // Should not reach here — abort fires before retry starts
+      yield {
+        type: 'assistant',
+        message: { content: [{ type: 'text', text: 'should not reach' }] },
+      };
+    });
+
+    const consumeGenerator = async (): Promise<void> => {
+      for await (const _ of client.sendQuery('test', '/workspace', undefined, {
+        abortSignal: abortController.signal,
+      })) {
+        // consume
+      }
+    };
+
+    await expect(consumeGenerator()).rejects.toThrow('Query aborted');
+    // Single abort listener registered (not per-retry)
+    expect(callCount).toBe(1);
+  }, 5_000);
+
+  test('enriched error (with stderr) is thrown at retry exhaustion, not raw error', async () => {
+    mockQuery.mockImplementation(async function* (args: {
+      options: { stderr?: (data: string) => void };
+    }) {
+      if (args.options.stderr) {
+        args.options.stderr('diagnostic: something broke');
+      }
+      throw new Error('process exited with code 1');
+    });
+
+    const consumeGenerator = async (): Promise<void> => {
+      for await (const _ of client.sendQuery('test', '/workspace')) {
+        // consume
+      }
+    };
+
+    const err = await consumeGenerator().catch((e: unknown) => e as Error);
+    expect(err).toBeInstanceOf(Error);
+    // Must contain stderr context, not just the raw error
+    expect(err.message).toContain('stderr:');
+    expect(err.message).toContain('diagnostic: something broke');
+  }, 5_000);
+
+  test('PostToolUse hook handles circular reference without crashing', async () => {
+    mockQuery.mockImplementation(async function* (args: {
+      options: {
+        hooks?: Record<string, Array<{ hooks: Array<(input: unknown) => Promise<unknown>> }>>;
+      };
+    }) {
+      // Simulate a tool use that triggers the PostToolUse hook with circular data
+      const hooks = args.options.hooks?.PostToolUse;
+      if (hooks?.[0]?.hooks?.[0]) {
+        const circular: Record<string, unknown> = { key: 'val' };
+        circular.self = circular; // circular reference
+        await hooks[0].hooks[0]({
+          tool_name: 'TestTool',
+          tool_use_id: 'tc-circ',
+          tool_response: circular,
+        });
+      }
+      yield {
+        type: 'assistant',
+        message: { content: [{ type: 'text', text: 'done' }] },
+      };
+    });
+
+    // Should not throw — the try/catch in PostToolUse should handle the circular ref
+    const chunks = [];
+    for await (const chunk of client.sendQuery('test', '/workspace')) {
+      chunks.push(chunk);
+    }
+
+    // The assistant message should still come through
+    expect(chunks.some(c => c.type === 'assistant')).toBe(true);
+    // The error should be logged
+    expect(mockLogger.error).toHaveBeenCalledWith(
+      expect.objectContaining({ err: expect.any(Error) }),
+      'claude.post_tool_use_hook_error'
+    );
+  });
+
+  test('logs is_error result events at error level', async () => {
+    mockQuery.mockImplementation(async function* () {
+      yield {
+        type: 'result',
+        session_id: 'sid-err',
+        is_error: true,
+        subtype: 'max_turns',
+      };
+    });
+
+    const chunks = [];
+    for await (const chunk of client.sendQuery('test', '/workspace')) {
+      chunks.push(chunk);
+    }
+
+    expect(chunks[0]).toMatchObject({
+      type: 'result',
+      isError: true,
+      errorSubtype: 'max_turns',
+    });
+    expect(mockLogger.error).toHaveBeenCalledWith(
+      expect.objectContaining({ sessionId: 'sid-err', errorSubtype: 'max_turns' }),
+      'claude.result_is_error'
+    );
+  });
+
+  describe('inline agents (nodeConfig.agents)', () => {
+    test('passes inline agents map through to SDK options.agents', async () => {
+      mockQuery.mockImplementation(async function* () {
+        yield { type: 'result', session_id: 'sid' };
+      });
+
+      const agents = {
+        'brief-gen': {
+          description: 'Summarises issues',
+          prompt: 'Be concise.',
+          model: 'haiku',
+          tools: ['Bash', 'Read'],
+        },
+      };
+
+      for await (const _ of client.sendQuery('test', '/workspace', undefined, {
+        nodeConfig: { agents },
+      })) {
+        // consume
+      }
+
+      expect(mockQuery).toHaveBeenCalledTimes(1);
+      const callArgs = mockQuery.mock.calls[0][0] as { options: Record<string, unknown> };
+      expect(callArgs.options.agents).toMatchObject(agents);
+    });
+
+    test('does not set options.agent when only inline agents are present', async () => {
+      mockQuery.mockImplementation(async function* () {
+        yield { type: 'result', session_id: 'sid' };
+      });
+
+      for await (const _ of client.sendQuery('test', '/workspace', undefined, {
+        nodeConfig: {
+          agents: {
+            'sub-a': { description: 'd', prompt: 'p' },
+          },
+        },
+      })) {
+        // consume
+      }
+
+      const callArgs = mockQuery.mock.calls[0][0] as { options: Record<string, unknown> };
+      // agent (singular) is set by skills wrapper; inline-only must leave it unset
+      expect(callArgs.options.agent).toBeUndefined();
+    });
+
+    test('merges inline agents with skills wrapper; user wins on ID collision', async () => {
+      mockQuery.mockImplementation(async function* () {
+        yield { type: 'result', session_id: 'sid' };
+      });
+
+      for await (const _ of client.sendQuery('test', '/workspace', undefined, {
+        nodeConfig: {
+          skills: ['my-skill'],
+          agents: {
+            // Intentionally collides with the internal 'dag-node-skills' wrapper ID
+            'dag-node-skills': {
+              description: 'user override',
+              prompt: 'user-defined prompt',
+            },
+            'extra-sub': { description: 'd', prompt: 'p' },
+          },
+        },
+      })) {
+        // consume
+      }
+
+      const callArgs = mockQuery.mock.calls[0][0] as { options: Record<string, unknown> };
+      const outAgents = callArgs.options.agents as Record<
+        string,
+        { description: string; prompt: string }
+      >;
+      // Both entries present
+      expect(Object.keys(outAgents).sort()).toEqual(['dag-node-skills', 'extra-sub']);
+      // User's definition wins the collision
+      expect(outAgents['dag-node-skills'].description).toBe('user override');
+      expect(outAgents['dag-node-skills'].prompt).toBe('user-defined prompt');
+    });
+
+    test('logs a warning when user-defined dag-node-skills overrides the skills wrapper', async () => {
+      mockQuery.mockImplementation(async function* () {
+        yield { type: 'result', session_id: 'sid' };
+      });
+
+      for await (const _ of client.sendQuery('test', '/workspace', undefined, {
+        nodeConfig: {
+          skills: ['my-skill'],
+          agents: {
+            'dag-node-skills': { description: 'user override', prompt: 'p' },
+          },
+        },
+      })) {
+        // consume
+      }
+
+      expect(mockLogger.warn).toHaveBeenCalledWith(
+        expect.objectContaining({ nodeSkills: ['my-skill'] }),
+        'claude.inline_agents_override_skills_wrapper'
+      );
+    });
+
+    test('does NOT warn when inline agents do not collide with the skills wrapper', async () => {
+      mockQuery.mockImplementation(async function* () {
+        yield { type: 'result', session_id: 'sid' };
+      });
+
+      for await (const _ of client.sendQuery('test', '/workspace', undefined, {
+        nodeConfig: {
+          skills: ['my-skill'],
+          agents: {
+            'brief-gen': { description: 'd', prompt: 'p' },
+          },
+        },
+      })) {
+        // consume
+      }
+
+      const warnCalls = mockLogger.warn.mock.calls.filter(
+        (args: unknown[]) => args[1] === 'claude.inline_agents_override_skills_wrapper'
+      );
+      expect(warnCalls).toHaveLength(0);
+    });
+  });
+});
diff --git a/packages/providers/src/claude/provider.ts b/packages/providers/src/claude/provider.ts
new file mode 100644
index 0000000000..5cbef54079
--- /dev/null
+++ b/packages/providers/src/claude/provider.ts
@@ -0,0 +1,1042 @@
+/**
+ * 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 have strict type checking 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
+ *
+ * Binary resolution:
+ * - In compiled binaries, `pathToClaudeCodeExecutable` is resolved from
+ *   `CLAUDE_BIN_PATH` env or `assistants.claude.claudeBinaryPath` config;
+ *   see ./binary-resolver.ts. In dev mode the SDK resolves cli.js itself
+ *   from node_modules.
+ */
+import {
+  query,
+  type Options,
+  type HookCallback,
+  type HookCallbackMatcher,
+} from '@anthropic-ai/claude-agent-sdk';
+import type {
+  IAgentProvider,
+  SendQueryOptions,
+  MessageChunk,
+  TokenUsage,
+  ProviderCapabilities,
+  NodeConfig,
+} from '../types';
+import { parseClaudeConfig } from './config';
+import { CLAUDE_CAPABILITIES } from './capabilities';
+import { resolveClaudeBinaryPath } from './binary-resolver';
+import { createLogger } from '@archon/paths';
+import { readFile } from 'fs/promises';
+import { resolve, isAbsolute } from 'path';
+
+/** 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('provider.claude');
+  return cachedLog;
+}
+
+/**
+ * Content block type for assistant messages
+ */
+interface ContentBlock {
+  type: 'text' | 'tool_use';
+  text?: string;
+  name?: string;
+  input?: Record<string, unknown>;
+  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.
+ *
+ * process.env is already clean at this point:
+ * - stripCwdEnv() at entry point removed CWD .env keys + CLAUDECODE markers
+ * - ~/.archon/.env loaded with override:true as the trusted source
+ */
+function buildSubprocessEnv(): NodeJS.ProcessEnv {
+  // Using || intentionally: empty string should be treated as missing credential
+  const hasExplicitTokens = Boolean(
+    process.env.CLAUDE_CODE_OAUTH_TOKEN || process.env.CLAUDE_API_KEY
+  );
+  const authMode = hasExplicitTokens ? 'explicit' : 'global';
+  getLog().info(
+    { authMode },
+    authMode === 'global' ? 'using_global_auth' : 'using_explicit_tokens'
+  );
+  return { ...process.env };
+}
+
+/** Max retries for transient subprocess failures */
+const MAX_SUBPROCESS_RETRIES = 3;
+const RETRY_BASE_DELAY_MS = 2000;
+
+const RATE_LIMIT_PATTERNS = ['rate limit', 'too many requests', '429', 'overloaded'];
+const AUTH_PATTERNS = [
+  'credit balance',
+  'unauthorized',
+  'authentication',
+  'invalid token',
+  '401',
+  '403',
+];
+const SUBPROCESS_CRASH_PATTERNS = ['exited with code', 'killed', 'signal', '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';
+}
+
+function getFirstEventTimeoutMs(): number {
+  const raw = process.env.ARCHON_CLAUDE_FIRST_EVENT_TIMEOUT_MS;
+  if (raw) {
+    const parsed = Number(raw);
+    if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  }
+  return 60_000;
+}
+
+function buildFirstEventHangDiagnostics(
+  subprocessEnv: Record<string, string>,
+  model: string | undefined
+): Record<string, unknown> {
+  return {
+    subprocessEnvKeys: Object.keys(subprocessEnv),
+    parentClaudeKeys: Object.keys(process.env).filter(
+      k => k === 'CLAUDECODE' || k.startsWith('CLAUDE_CODE_') || k.startsWith('ANTHROPIC_')
+    ),
+    model,
+    platform: process.platform,
+    uid: getProcessUid(),
+    isTTY: process.stdout.isTTY ?? false,
+    claudeCode: process.env.CLAUDECODE,
+    claudeCodeEntrypoint: process.env.CLAUDE_CODE_ENTRYPOINT,
+  };
+}
+
+class FirstEventTimeoutError extends Error {}
+
+/**
+ * Wraps an async generator so that the first call to .next() must resolve
+ * within `timeoutMs`. If it doesn't, aborts the controller and throws.
+ */
+export async function* withFirstMessageTimeout<T>(
+  gen: AsyncGenerator<T>,
+  controller: AbortController,
+  timeoutMs: number,
+  diagnostics: Record<string, unknown>
+): AsyncGenerator<T> {
+  let timerId: ReturnType<typeof setTimeout> | undefined;
+  let firstValue: IteratorResult<T>;
+  try {
+    firstValue = await Promise.race([
+      gen.next(),
+      new Promise<never>((_, reject) => {
+        timerId = setTimeout(() => {
+          reject(new FirstEventTimeoutError());
+        }, timeoutMs);
+      }),
+    ]);
+  } catch (err) {
+    if (err instanceof FirstEventTimeoutError) {
+      controller.abort();
+      getLog().error({ ...diagnostics, timeoutMs }, 'claude.first_event_timeout');
+      throw new Error(
+        'Claude Code subprocess produced no output within ' +
+          timeoutMs +
+          'ms. ' +
+          'See logs for claude.first_event_timeout diagnostic dump. ' +
+          'Details: https://github.com/coleam00/Archon/issues/1067'
+      );
+    }
+    throw err;
+  } finally {
+    clearTimeout(timerId);
+  }
+
+  if (firstValue.done) return;
+  yield firstValue.value;
+  yield* gen;
+}
+
+/**
+ * Returns the current process UID, or undefined on platforms that don't support it.
+ */
+export function getProcessUid(): number | undefined {
+  return typeof process.getuid === 'function' ? process.getuid() : undefined;
+}
+
+// ─── MCP Config Loading (absorbed from dag-executor) ───────────────────────
+
+/**
+ * Expand $VAR_NAME references in string-valued records from process.env.
+ */
+function expandEnvVarsInRecord(
+  record: Record<string, unknown>,
+  missingVars: string[]
+): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [key, val] of Object.entries(record)) {
+    if (typeof val !== 'string') {
+      getLog().warn({ key, valueType: typeof val }, 'mcp_env_value_coerced_to_string');
+      result[key] = String(val);
+      continue;
+    }
+    result[key] = val.replace(/\$([A-Z_][A-Z0-9_]*)/g, (_, varName: string) => {
+      const envVal = process.env[varName];
+      if (envVal === undefined) {
+        missingVars.push(varName);
+      }
+      return envVal ?? '';
+    });
+  }
+  return result;
+}
+
+function expandEnvVars(config: Record<string, unknown>): {
+  expanded: Record<string, unknown>;
+  missingVars: string[];
+} {
+  const result: Record<string, unknown> = {};
+  const missingVars: string[] = [];
+  for (const [serverName, serverConfig] of Object.entries(config)) {
+    if (typeof serverConfig !== 'object' || serverConfig === null) {
+      getLog().warn({ serverName, valueType: typeof serverConfig }, 'mcp_server_config_not_object');
+      continue;
+    }
+    const server = { ...(serverConfig as Record<string, unknown>) };
+    if (server.env && typeof server.env === 'object') {
+      server.env = expandEnvVarsInRecord(server.env as Record<string, unknown>, missingVars);
+    }
+    if (server.headers && typeof server.headers === 'object') {
+      server.headers = expandEnvVarsInRecord(
+        server.headers as Record<string, unknown>,
+        missingVars
+      );
+    }
+    result[serverName] = server;
+  }
+  return { expanded: result, missingVars };
+}
+
+/**
+ * Load MCP server config from a JSON file and expand environment variables.
+ */
+export async function loadMcpConfig(
+  mcpPath: string,
+  cwd: string
+): Promise<{ servers: Record<string, unknown>; serverNames: string[]; missingVars: string[] }> {
+  const fullPath = isAbsolute(mcpPath) ? mcpPath : resolve(cwd, mcpPath);
+
+  let raw: string;
+  try {
+    raw = await readFile(fullPath, 'utf-8');
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException;
+    if (e.code === 'ENOENT') {
+      throw new Error(`MCP config file not found: ${mcpPath} (resolved to ${fullPath})`);
+    }
+    throw new Error(`Failed to read MCP config file: ${mcpPath} — ${e.message}`);
+  }
+
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(raw) as Record<string, unknown>;
+  } catch (parseErr) {
+    const detail = (parseErr as SyntaxError).message;
+    throw new Error(`MCP config file is not valid JSON: ${mcpPath} — ${detail}`);
+  }
+
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`MCP config must be a JSON object (Record<string, ServerConfig>): ${mcpPath}`);
+  }
+
+  const { expanded, missingVars } = expandEnvVars(parsed);
+  const serverNames = Object.keys(expanded);
+  return { servers: expanded, serverNames, missingVars };
+}
+
+// ─── SDK Hooks Building (absorbed from dag-executor) ───────────────────────
+
+/** YAML hook matcher shape (matches @archon/workflows/schemas/dag-node WorkflowNodeHooks) */
+interface YAMLHookMatcher {
+  matcher?: string;
+  response: unknown;
+  timeout?: number;
+}
+
+type SDKHooksMap = Partial<
+  Record<
+    string,
+    {
+      matcher?: string;
+      hooks: ((
+        input: unknown,
+        toolUseID: string | undefined,
+        options: { signal: AbortSignal }
+      ) => Promise<unknown>)[];
+      timeout?: number;
+    }[]
+  >
+>;
+
+/**
+ * Convert declarative YAML hook definitions to SDK HookCallbackMatcher arrays.
+ */
+export function buildSDKHooksFromYAML(
+  nodeHooks: Record<string, YAMLHookMatcher[] | undefined>
+): SDKHooksMap {
+  const sdkHooks: SDKHooksMap = {};
+
+  for (const [event, matchers] of Object.entries(nodeHooks)) {
+    if (!matchers) continue;
+    sdkHooks[event] = matchers.map(m => ({
+      ...(m.matcher ? { matcher: m.matcher } : {}),
+      hooks: [async (): Promise<unknown> => m.response],
+      ...(m.timeout ? { timeout: m.timeout } : {}),
+    }));
+  }
+
+  if (Object.keys(sdkHooks).length === 0) {
+    getLog().warn(
+      { nodeHooksKeys: Object.keys(nodeHooks) },
+      'claude.hooks_build_produced_empty_map'
+    );
+  }
+
+  return sdkHooks;
+}
+
+// ─── Provider Warning Type ───────────────────────────────────────────────
+
+/**
+ * Structured provider warning. Providers collect these during translation;
+ * callers convert them to system chunks before streaming starts.
+ */
+interface ProviderWarning {
+  code: string;
+  message: string;
+}
+
+// ─── NodeConfig → SDK Options Translation ──────────────────────────────────
+
+/**
+ * Translate nodeConfig into Claude SDK-specific options.
+ * Called inside sendQuery when nodeConfig is present (workflow path).
+ * Returns structured warnings that the caller should yield as system chunks.
+ */
+async function applyNodeConfig(
+  options: Options,
+  nodeConfig: NodeConfig,
+  cwd: string
+): Promise<ProviderWarning[]> {
+  const warnings: ProviderWarning[] = [];
+  // allowed_tools → tools
+  if (nodeConfig.allowed_tools !== undefined) {
+    options.tools = nodeConfig.allowed_tools;
+  }
+
+  // denied_tools → disallowedTools
+  if (nodeConfig.denied_tools !== undefined) {
+    options.disallowedTools = nodeConfig.denied_tools;
+  }
+
+  // hooks → build SDK hooks
+  if (nodeConfig.hooks) {
+    const builtHooks = buildSDKHooksFromYAML(
+      nodeConfig.hooks as Record<string, YAMLHookMatcher[] | undefined>
+    );
+    if (Object.keys(builtHooks).length > 0) {
+      // Merge with existing hooks (PostToolUse capture hook)
+      const existingHooks = options.hooks as SDKHooksMap | undefined;
+      if (!options.hooks) {
+        (options as Record<string, unknown>).hooks = {};
+      }
+      for (const [event, matchers] of Object.entries(builtHooks)) {
+        if (!matchers) continue;
+        const existing = existingHooks?.[event] as HookCallbackMatcher[] | undefined;
+        if (existing) {
+          (options.hooks as Record<string, HookCallbackMatcher[]>)[event] = [
+            ...(matchers as HookCallbackMatcher[]),
+            ...existing,
+          ];
+        } else {
+          (options.hooks as Record<string, HookCallbackMatcher[]>)[event] =
+            matchers as HookCallbackMatcher[];
+        }
+      }
+    }
+  }
+
+  // mcp → load config and set mcpServers + allowedTools wildcards
+  if (nodeConfig.mcp) {
+    const mcpPath = nodeConfig.mcp;
+    const { servers, serverNames, missingVars } = await loadMcpConfig(mcpPath, cwd);
+    options.mcpServers = servers as Options['mcpServers'];
+    const mcpWildcards = serverNames.map(name => `mcp__${name}__*`);
+    options.allowedTools = [...(options.allowedTools ?? []), ...mcpWildcards];
+    getLog().info({ serverNames, mcpPath }, 'claude.mcp_config_loaded');
+    if (missingVars.length > 0) {
+      const uniqueVars = [...new Set(missingVars)];
+      getLog().warn({ missingVars: uniqueVars }, 'claude.mcp_env_vars_missing');
+      warnings.push({
+        code: 'mcp_env_vars_missing',
+        message: `MCP config references undefined env vars: ${uniqueVars.join(', ')}. These will be empty strings — MCP servers may fail to authenticate.`,
+      });
+    }
+    // Haiku models don't support tool search (lazy loading for many tools)
+    if (options.model?.toLowerCase().includes('haiku')) {
+      getLog().warn({ model: options.model }, 'claude.mcp_haiku_tool_search_unsupported');
+      warnings.push({
+        code: 'mcp_haiku_tool_search',
+        message:
+          'Using Haiku model with MCP servers — tool search (lazy loading for many tools) is not supported on Haiku. Consider using Sonnet or Opus.',
+      });
+    }
+  }
+
+  // skills → AgentDefinition wrapping
+  if (nodeConfig.skills) {
+    const skills = nodeConfig.skills;
+    const agentId = 'dag-node-skills';
+    const agentTools = options.tools ? [...(options.tools as string[]), 'Skill'] : ['Skill'];
+    const agentDef: {
+      description: string;
+      prompt: string;
+      skills: string[];
+      tools: string[];
+      model?: string;
+    } = {
+      description: 'DAG node with skills',
+      prompt: `You have preloaded skills: ${skills.join(', ')}. Use them when relevant.`,
+      skills,
+      tools: agentTools,
+    };
+    if (options.model) agentDef.model = options.model;
+    options.agents = { [agentId]: agentDef };
+    options.agent = agentId;
+    if (!options.allowedTools?.includes('Skill')) {
+      options.allowedTools = [...(options.allowedTools ?? []), 'Skill'];
+    }
+    getLog().info({ skills, agentId }, 'claude.skills_agent_created');
+  }
+
+  // agents → inline AgentDefinition pass-through.
+  // Runs AFTER skills: so user-defined agents win on ID collision with
+  // the internal 'dag-node-skills' wrapper.
+  // options.agent is intentionally left alone — inline agents are sub-agents
+  // invokable via the Task tool, not the primary agent for the query.
+  if (nodeConfig.agents) {
+    // Warn loudly when a user-defined agent overrides the internal
+    // 'dag-node-skills' wrapper set by the skills: block above. The
+    // merge is by design (user wins) but silent capability removal
+    // is the exact failure mode we want to avoid.
+    if (
+      Object.hasOwn(nodeConfig.agents, 'dag-node-skills') &&
+      options.agents?.['dag-node-skills'] !== undefined
+    ) {
+      getLog().warn(
+        { nodeSkills: nodeConfig.skills ?? [] },
+        'claude.inline_agents_override_skills_wrapper'
+      );
+    }
+    options.agents = {
+      ...(options.agents ?? {}),
+      ...(nodeConfig.agents as NonNullable<Options['agents']>),
+    };
+    getLog().info({ agentIds: Object.keys(nodeConfig.agents) }, 'claude.inline_agents_registered');
+  }
+
+  // effort
+  if (nodeConfig.effort !== undefined) {
+    options.effort = nodeConfig.effort as Options['effort'];
+  }
+
+  // thinking
+  if (nodeConfig.thinking !== undefined) {
+    options.thinking = nodeConfig.thinking as Options['thinking'];
+  }
+
+  // sandbox
+  if (nodeConfig.sandbox !== undefined) {
+    options.sandbox = nodeConfig.sandbox as Options['sandbox'];
+  }
+
+  // betas
+  if (nodeConfig.betas !== undefined) {
+    options.betas = nodeConfig.betas as Options['betas'];
+  }
+
+  // output_format (from nodeConfig, overrides base outputFormat if present)
+  if (nodeConfig.output_format) {
+    options.outputFormat = {
+      type: 'json_schema',
+      schema: nodeConfig.output_format,
+    } as Options['outputFormat'];
+  }
+
+  // maxBudgetUsd from nodeConfig
+  if (nodeConfig.maxBudgetUsd !== undefined) {
+    options.maxBudgetUsd = nodeConfig.maxBudgetUsd;
+  }
+
+  // systemPrompt from nodeConfig
+  if (nodeConfig.systemPrompt !== undefined) {
+    options.systemPrompt = nodeConfig.systemPrompt;
+  }
+
+  // fallbackModel from nodeConfig
+  if (nodeConfig.fallbackModel !== undefined) {
+    options.fallbackModel = nodeConfig.fallbackModel;
+  }
+
+  return warnings;
+}
+
+// ─── Base Options Builder ────────────────────────────────────────────────
+
+/** Queued tool result from SDK hooks, consumed during stream normalization. */
+interface ToolResultEntry {
+  toolName: string;
+  toolOutput: string;
+  toolCallId?: string;
+}
+
+/**
+ * Decide whether the Claude subprocess should be spawned with `--no-env-file`.
+ *
+ * `--no-env-file` is a Bun flag that prevents auto-loading `.env` from the
+ * target repo cwd into the spawned process. It only applies when the SDK
+ * spawns the executable via Bun/Node — i.e. when the executable is a `.js`
+ * file (dev mode resolves cli.js, npm-installed resolves cli.js). For a
+ * native Claude Code binary (curl/PowerShell installer at
+ * `~/.local/bin/claude`), the SDK execs the binary directly and the flag
+ * gets passed to the native binary, which rejects unknown options and
+ * exits code 1.
+ *
+ * Returning `false` for native binaries is verified safe — the native
+ * binary does not auto-load `.env` from CWD (probed end-to-end with
+ * sentinel `.env` and `.env.local` in the workflow CWD; both arrived
+ * UNSET in the spawned bash tool). The first-layer protection —
+ * `stripCwdEnv()` in `@archon/paths` (#1067) — removes CWD env keys from
+ * the parent process before spawn, so the subprocess inherits a clean
+ * env regardless of executable type.
+ *
+ * Exported so the decision can be unit-tested without needing to mock
+ * `BUNDLED_IS_BINARY` or run the full provider sendQuery pathway.
+ */
+export function shouldPassNoEnvFile(cliPath: string | undefined): boolean {
+  return cliPath === undefined || cliPath.endsWith('.js');
+}
+
+/**
+ * Build base Claude SDK options from cwd, request options, and assistant defaults.
+ * Does not include nodeConfig translation — that is handled by applyNodeConfig.
+ */
+function buildBaseClaudeOptions(
+  cwd: string,
+  requestOptions: SendQueryOptions | undefined,
+  assistantDefaults: ReturnType<typeof parseClaudeConfig>,
+  controller: AbortController,
+  stderrLines: string[],
+  toolResultQueue: ToolResultEntry[],
+  env: NodeJS.ProcessEnv,
+  cliPath: string | undefined
+): Options {
+  const isJsExecutable = shouldPassNoEnvFile(cliPath);
+  getLog().debug(
+    { cliPath: cliPath ?? null, isJsExecutable, passesNoEnvFile: isJsExecutable },
+    'claude.subprocess_env_file_flag'
+  );
+
+  return {
+    cwd,
+    // In compiled binaries, the resolver supplies an absolute executable path;
+    // in dev mode it returns undefined and the SDK resolves from node_modules.
+    ...(cliPath !== undefined ? { pathToClaudeCodeExecutable: cliPath } : {}),
+    ...(isJsExecutable ? { executableArgs: ['--no-env-file'] } : {}),
+    env,
+    model: requestOptions?.model ?? assistantDefaults.model,
+    abortController: controller,
+    ...(requestOptions?.outputFormat !== undefined
+      ? { outputFormat: requestOptions.outputFormat }
+      : {}),
+    ...(requestOptions?.maxBudgetUsd !== undefined
+      ? { maxBudgetUsd: requestOptions.maxBudgetUsd }
+      : {}),
+    ...(requestOptions?.fallbackModel !== undefined
+      ? { fallbackModel: requestOptions.fallbackModel }
+      : {}),
+    ...(requestOptions?.persistSession !== undefined
+      ? { persistSession: requestOptions.persistSession }
+      : {}),
+    ...(requestOptions?.forkSession !== undefined
+      ? { forkSession: requestOptions.forkSession }
+      : {}),
+    permissionMode: 'bypassPermissions',
+    allowDangerouslySkipPermissions: true,
+    systemPrompt: requestOptions?.systemPrompt ?? { type: 'preset', preset: 'claude_code' },
+    settingSources: assistantDefaults.settingSources ?? ['project'],
+    hooks: buildToolCaptureHooks(toolResultQueue),
+    stderr: (data: string): void => {
+      const output = data.trim();
+      if (!output) return;
+      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');
+      }
+    },
+  };
+}
+
+// ─── Tool Capture Hooks ──────────────────────────────────────────────────
+
+/**
+ * Build SDK hooks that capture tool use results into a shared queue.
+ * The queue is drained during stream normalization.
+ */
+function buildToolCaptureHooks(toolResultQueue: ToolResultEntry[]): Options['hooks'] {
+  return {
+    PostToolUse: [
+      {
+        hooks: [
+          (async (input: Record<string, unknown>): Promise<{ continue: true }> => {
+            try {
+              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 ?? '');
+              const maxLen = 10_000;
+              toolResultQueue.push({
+                toolName,
+                toolOutput: output.length > maxLen ? output.slice(0, maxLen) + '...' : output,
+                ...(toolUseId !== undefined ? { toolCallId: toolUseId } : {}),
+              });
+            } catch (e) {
+              getLog().error({ err: e, input }, 'claude.post_tool_use_hook_error');
+            }
+            return { continue: true };
+          }) as HookCallback,
+        ],
+      },
+    ],
+    PostToolUseFailure: [
+      {
+        hooks: [
+          (async (input: Record<string, unknown>): Promise<{ continue: true }> => {
+            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,
+        ],
+      },
+    ],
+  };
+}
+
+// ─── Stream Normalizer ───────────────────────────────────────────────────
+
+/**
+ * Normalize raw Claude SDK events into Archon MessageChunks.
+ * Drains the tool result queue between events (populated by SDK hooks).
+ */
+async function* streamClaudeMessages(
+  events: AsyncGenerator,
+  toolResultQueue: ToolResultEntry[]
+): AsyncGenerator<MessageChunk> {
+  for await (const msg of events) {
+    // Drain tool results captured by hooks before processing the next event
+    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 } : {}),
+        };
+      }
+    }
+
+    const event = msg as { type: string };
+
+    if (event.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 (event.type === 'system') {
+      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 (event.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 (event.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;
+        errors?: string[];
+        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);
+      const sdkErrors = Array.isArray(resultMsg.errors) ? resultMsg.errors : undefined;
+      if (resultMsg.is_error) {
+        getLog().error(
+          {
+            sessionId: resultMsg.session_id,
+            errorSubtype: resultMsg.subtype,
+            stopReason: resultMsg.stop_reason,
+            errors: sdkErrors,
+          },
+          'claude.result_is_error'
+        );
+      }
+      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.is_error && sdkErrors?.length ? { errors: sdkErrors } : {}),
+        ...(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 after the stream ends
+  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 } : {}),
+      };
+    }
+  }
+}
+
+// ─── Error Classification & Retry ────────────────────────────────────────
+
+/**
+ * Classify a subprocess error and enrich with stderr context.
+ * Returns null if the error should be retried (caller handles retry logic).
+ */
+function classifyAndEnrichError(
+  error: Error,
+  stderrLines: string[],
+  controller: AbortController
+): { enrichedError: Error; errorClass: string; shouldRetry: boolean } {
+  // If the controller was aborted by withFirstMessageTimeout, the original
+  // timeout error carries the diagnostic message and #1067 breadcrumb.
+  // Preserve it instead of collapsing into a generic "Query aborted".
+  if (controller.signal.aborted) {
+    if (error.message.includes('produced no output within')) {
+      return { enrichedError: error, errorClass: 'timeout', shouldRetry: false };
+    }
+    return {
+      enrichedError: new Error('Query aborted'),
+      errorClass: 'aborted',
+      shouldRetry: false,
+    };
+  }
+
+  const stderrContext = stderrLines.join('\n');
+  const errorClass = classifySubprocessError(error.message, stderrContext);
+
+  if (errorClass === 'auth') {
+    const enrichedError = new Error(
+      `Claude Code auth error: ${error.message}${stderrContext ? ` (${stderrContext})` : ''}`
+    );
+    enrichedError.cause = error;
+    return { enrichedError, errorClass, shouldRetry: false };
+  }
+
+  const enrichedMessage = stderrContext
+    ? `Claude Code ${errorClass}: ${error.message} (stderr: ${stderrContext})`
+    : `Claude Code ${errorClass}: ${error.message}`;
+  const enrichedError = new Error(enrichedMessage);
+  enrichedError.cause = error;
+  const shouldRetry = errorClass === 'rate_limit' || errorClass === 'crash';
+  return { enrichedError, errorClass, shouldRetry };
+}
+
+// ─── Claude Provider ───────────────────────────────────────────────────────
+
+/**
+ * Claude AI agent provider.
+ * Implements IAgentProvider with full SDK integration.
+ *
+ * sendQuery orchestrates the following internal helpers:
+ * - buildBaseClaudeOptions: SDK option construction
+ * - applyNodeConfig: workflow nodeConfig → SDK option translation + warnings
+ * - streamClaudeMessages: raw SDK event normalization into MessageChunks
+ * - classifyAndEnrichError: error classification for retry decisions
+ */
+export class ClaudeProvider implements IAgentProvider {
+  private readonly retryBaseDelayMs: number;
+
+  constructor(options?: { retryBaseDelayMs?: number }) {
+    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;
+  }
+
+  getCapabilities(): ProviderCapabilities {
+    return CLAUDE_CAPABILITIES;
+  }
+
+  /**
+   * Send a query to Claude and stream responses.
+   * Orchestrates option building, nodeConfig translation, streaming, and retry.
+   */
+  // TODO(#1135): Pre-spawn env-leak gate was removed during provider extraction.
+  // Caller-side enforcement (orchestrator, dag-executor) is tracked in #1135.
+  // Providers must NOT implement security gates — the platform guarantees safety
+  // before a provider runs.
+  async *sendQuery(
+    prompt: string,
+    cwd: string,
+    resumeSessionId?: string,
+    requestOptions?: SendQueryOptions
+  ): AsyncGenerator<MessageChunk> {
+    let lastError: Error | undefined;
+    const assistantDefaults = parseClaudeConfig(requestOptions?.assistantConfig ?? {});
+
+    // Resolve Claude CLI path once before the retry loop. In binary mode this
+    // throws immediately if neither env nor config supplies a valid path, so
+    // the user gets a clean error rather than N retries of "Module not found".
+    const resolvedCliPath = await resolveClaudeBinaryPath(assistantDefaults.claudeBinaryPath);
+
+    // Build subprocess env once (avoids re-logging auth mode per retry)
+    const subprocessEnv = buildSubprocessEnv();
+    const env = requestOptions?.env ? { ...subprocessEnv, ...requestOptions.env } : subprocessEnv;
+
+    // Apply nodeConfig translation once (deterministic, not retry-dependent)
+    // We need a throwaway Options to extract warnings from applyNodeConfig,
+    // then re-apply per attempt. But nodeConfig warnings are deterministic,
+    // so we compute them once and yield them before the first attempt.
+    let nodeConfigWarnings: ProviderWarning[] = [];
+    if (requestOptions?.nodeConfig) {
+      const tempOptions: Options = {} as Options;
+      nodeConfigWarnings = await applyNodeConfig(tempOptions, requestOptions.nodeConfig, cwd);
+    }
+
+    // Yield provider warnings once before retries
+    for (const warning of nodeConfigWarnings) {
+      yield { type: 'system' as const, content: `⚠️ ${warning.message}` };
+    }
+
+    // Track the current attempt's controller so a single abort listener
+    // can forward cancellation without accumulating per-retry listeners.
+    let currentController: AbortController | undefined;
+    const onAbort = (): void => {
+      currentController?.abort();
+    };
+    if (requestOptions?.abortSignal) {
+      requestOptions.abortSignal.addEventListener('abort', onAbort, { once: true });
+    }
+
+    for (let attempt = 0; attempt <= MAX_SUBPROCESS_RETRIES; attempt++) {
+      if (requestOptions?.abortSignal?.aborted) {
+        throw new Error('Query aborted');
+      }
+
+      const stderrLines: string[] = [];
+      const toolResultQueue: ToolResultEntry[] = [];
+      const controller = new AbortController();
+      currentController = controller;
+
+      // 1. Build SDK options (env and cliPath pre-computed above)
+      const options = buildBaseClaudeOptions(
+        cwd,
+        requestOptions,
+        assistantDefaults,
+        controller,
+        stderrLines,
+        toolResultQueue,
+        env,
+        resolvedCliPath
+      );
+
+      // 2. Apply nodeConfig translation (re-applied per attempt since options are fresh)
+      if (requestOptions?.nodeConfig) {
+        await applyNodeConfig(options, requestOptions.nodeConfig, cwd);
+      }
+
+      // 3. Set session resume
+      if (resumeSessionId) {
+        options.resume = resumeSessionId;
+        getLog().debug(
+          { sessionId: resumeSessionId, forkSession: requestOptions?.forkSession },
+          'resuming_session'
+        );
+      } else {
+        getLog().debug({ cwd, attempt }, 'starting_new_session');
+      }
+
+      try {
+        // 4. Run query with first-event timeout protection
+        const rawEvents = query({ prompt, options });
+        const timeoutMs = getFirstEventTimeoutMs();
+        const diagnostics = buildFirstEventHangDiagnostics(
+          options.env as Record<string, string>,
+          options.model
+        );
+        const events = withFirstMessageTimeout(rawEvents, controller, timeoutMs, diagnostics);
+
+        // 5. Stream normalized events
+        yield* streamClaudeMessages(events, toolResultQueue);
+        return;
+      } catch (error) {
+        const err = error as Error;
+        const { enrichedError, errorClass, shouldRetry } = classifyAndEnrichError(
+          err,
+          stderrLines,
+          controller
+        );
+
+        getLog().error(
+          {
+            err,
+            stderrContext: stderrLines.join('\n'),
+            errorClass,
+            attempt,
+            maxRetries: MAX_SUBPROCESS_RETRIES,
+          },
+          'query_error'
+        );
+
+        if (!shouldRetry || attempt >= MAX_SUBPROCESS_RETRIES) {
+          throw enrichedError;
+        }
+
+        const delayMs = this.retryBaseDelayMs * Math.pow(2, attempt);
+        getLog().info({ attempt, delayMs, errorClass }, 'retrying_subprocess');
+        await new Promise(resolve => setTimeout(resolve, delayMs));
+        lastError = enrichedError;
+      }
+    }
+
+    throw lastError ?? new Error('Claude Code query failed after retries');
+  }
+
+  getType(): string {
+    return 'claude';
+  }
+}
diff --git a/packages/core/src/clients/codex-binary-guard.test.ts b/packages/providers/src/codex/binary-guard.test.ts
similarity index 73%
rename from packages/core/src/clients/codex-binary-guard.test.ts
rename to packages/providers/src/codex/binary-guard.test.ts
index c235caf5fd..891262cf47 100644
--- a/packages/core/src/clients/codex-binary-guard.test.ts
+++ b/packages/providers/src/codex/binary-guard.test.ts
@@ -2,7 +2,7 @@
  * Tests for Codex binary resolution in compiled binary mode.
  *
  * Separate file because mock.module('@archon/paths') with BUNDLED_IS_BINARY=true
- * conflicts with codex.test.ts which mocks it without BUNDLED_IS_BINARY.
+ * conflicts with provider.test.ts which mocks it without BUNDLED_IS_BINARY.
  * Must run in its own bun test invocation (see package.json test script).
  */
 import { describe, test, expect, mock, beforeEach } from 'bun:test';
@@ -45,63 +45,35 @@ mock.module('@openai/codex-sdk', () => ({
   Codex: MockCodex,
 }));
 
-// Mock resolver — controls binary resolution behavior per test
+// Mock resolver -- controls binary resolution behavior per test
 const mockResolveCodexBinaryPath = mock(
   (_configPath?: string): Promise<string | undefined> =>
     Promise.resolve('/tmp/test-archon/vendor/codex/codex')
 );
-mock.module('../utils/codex-binary-resolver', () => ({
+mock.module('./binary-resolver', () => ({
   resolveCodexBinaryPath: mockResolveCodexBinaryPath,
 }));
 
-// Config mock with configurable return value
-const mockLoadConfig = mock(() =>
-  Promise.resolve({
-    allowTargetRepoKeys: false,
-    assistants: { codex: {} },
-  })
-);
-
-// Mock db and config dependencies to prevent real DB access
-mock.module('../db/codebases', () => ({
-  findCodebaseByDefaultCwd: mock(() => Promise.resolve(null)),
-  findCodebaseByPathPrefix: mock(() => Promise.resolve(null)),
-}));
-mock.module('../config/config-loader', () => ({
-  loadConfig: mockLoadConfig,
-}));
-mock.module('../utils/env-leak-scanner', () => ({
-  scanPathForSensitiveKeys: mock(() => ({ findings: [] })),
-  EnvLeakError: class extends Error {},
-}));
+import { CodexProvider, resetCodexSingleton } from './provider';
 
-import { CodexClient, resetCodexSingleton } from './codex';
-
-describe('CodexClient binary mode resolution', () => {
+describe('CodexProvider binary mode resolution', () => {
   beforeEach(() => {
     resetCodexSingleton();
     MockCodex.mockClear();
     mockStartThread.mockClear();
     mockResolveCodexBinaryPath.mockClear();
-    mockLoadConfig.mockClear();
     capturedOptions = undefined;
 
     // Restore default mock implementations
     mockResolveCodexBinaryPath.mockImplementation(() =>
       Promise.resolve('/tmp/test-archon/vendor/codex/codex')
     );
-    mockLoadConfig.mockImplementation(() =>
-      Promise.resolve({
-        allowTargetRepoKeys: false,
-        assistants: { codex: {} },
-      })
-    );
   });
 
   test('passes resolved binary path to Codex constructor via codexPathOverride', async () => {
     mockResolveCodexBinaryPath.mockResolvedValueOnce('/custom/path/to/codex');
 
-    const client = new CodexClient();
+    const client = new CodexProvider();
     const generator = client.sendQuery('test prompt', '/tmp/test');
 
     // Consume events to trigger initialization
@@ -118,7 +90,7 @@ describe('CodexClient binary mode resolution', () => {
       new Error('Codex native binary not found at /tmp/test-archon/vendor/codex/codex')
     );
 
-    const client = new CodexClient();
+    const client = new CodexProvider();
     const generator = client.sendQuery('test prompt', '/tmp/test');
 
     await expect(generator.next()).rejects.toThrow('Codex native binary not found');
@@ -129,7 +101,7 @@ describe('CodexClient binary mode resolution', () => {
       .mockRejectedValueOnce(new Error('Codex CLI binary not found'))
       .mockResolvedValueOnce('/tmp/test-archon/vendor/codex/codex');
 
-    const client = new CodexClient();
+    const client = new CodexProvider();
 
     // First call fails
     await expect(client.sendQuery('test prompt', '/tmp/test').next()).rejects.toThrow(
@@ -150,7 +122,7 @@ describe('CodexClient binary mode resolution', () => {
   test('does not pass codexPathOverride when resolver returns undefined', async () => {
     mockResolveCodexBinaryPath.mockResolvedValueOnce(undefined);
 
-    const client = new CodexClient();
+    const client = new CodexProvider();
     const generator = client.sendQuery('test prompt', '/tmp/test');
 
     for await (const _chunk of generator) {
@@ -161,15 +133,12 @@ describe('CodexClient binary mode resolution', () => {
     expect(capturedOptions?.codexPathOverride).toBeUndefined();
   });
 
-  test('passes config codexBinaryPath to resolver', async () => {
-    mockLoadConfig.mockResolvedValueOnce({
-      allowTargetRepoKeys: false,
-      assistants: { codex: { codexBinaryPath: '/user/custom/codex' } },
+  test('passes config codexBinaryPath to resolver via assistantConfig', async () => {
+    const client = new CodexProvider();
+    const generator = client.sendQuery('test prompt', '/tmp/test', undefined, {
+      assistantConfig: { codexBinaryPath: '/user/custom/codex' },
     });
 
-    const client = new CodexClient();
-    const generator = client.sendQuery('test prompt', '/tmp/test');
-
     for await (const _chunk of generator) {
       // drain
     }
diff --git a/packages/core/src/utils/codex-binary-resolver-dev.test.ts b/packages/providers/src/codex/binary-resolver-dev.test.ts
similarity index 92%
rename from packages/core/src/utils/codex-binary-resolver-dev.test.ts
rename to packages/providers/src/codex/binary-resolver-dev.test.ts
index ac8761ee02..9635d8d59c 100644
--- a/packages/core/src/utils/codex-binary-resolver-dev.test.ts
+++ b/packages/providers/src/codex/binary-resolver-dev.test.ts
@@ -11,7 +11,7 @@ mock.module('@archon/paths', () => ({
   getArchonHome: mock(() => '/tmp/test-archon-home'),
 }));
 
-import { resolveCodexBinaryPath } from './codex-binary-resolver';
+import { resolveCodexBinaryPath } from './binary-resolver';
 
 describe('resolveCodexBinaryPath (dev mode)', () => {
   test('returns undefined when BUNDLED_IS_BINARY is false', async () => {
diff --git a/packages/core/src/utils/codex-binary-resolver.test.ts b/packages/providers/src/codex/binary-resolver.test.ts
similarity index 98%
rename from packages/core/src/utils/codex-binary-resolver.test.ts
rename to packages/providers/src/codex/binary-resolver.test.ts
index 3425a6fa17..1df4e7c6f6 100644
--- a/packages/core/src/utils/codex-binary-resolver.test.ts
+++ b/packages/providers/src/codex/binary-resolver.test.ts
@@ -16,7 +16,7 @@ mock.module('@archon/paths', () => ({
   getArchonHome: mock(() => '/tmp/test-archon-home'),
 }));
 
-import * as resolver from './codex-binary-resolver';
+import * as resolver from './binary-resolver';
 
 describe('resolveCodexBinaryPath (binary mode)', () => {
   const originalEnv = process.env.CODEX_BIN_PATH;
diff --git a/packages/core/src/utils/codex-binary-resolver.ts b/packages/providers/src/codex/binary-resolver.ts
similarity index 96%
rename from packages/core/src/utils/codex-binary-resolver.ts
rename to packages/providers/src/codex/binary-resolver.ts
index e927918c95..a1e0f01a5b 100644
--- a/packages/core/src/utils/codex-binary-resolver.ts
+++ b/packages/providers/src/codex/binary-resolver.ts
@@ -5,9 +5,6 @@
  * native Codex CLI binary, which breaks in compiled binaries where
  * `import.meta.url` is frozen to the build host's path.
  *
- * This module resolves an alternative path and passes it to the SDK's
- * `codexPathOverride` constructor option, bypassing the broken resolution.
- *
  * Resolution order:
  * 1. `CODEX_BIN_PATH` environment variable
  * 2. `assistants.codex.codexBinaryPath` in config
diff --git a/packages/providers/src/codex/capabilities.ts b/packages/providers/src/codex/capabilities.ts
new file mode 100644
index 0000000000..9b179e2170
--- /dev/null
+++ b/packages/providers/src/codex/capabilities.ts
@@ -0,0 +1,17 @@
+import type { ProviderCapabilities } from '../types';
+
+export const CODEX_CAPABILITIES: ProviderCapabilities = {
+  sessionResume: true,
+  mcp: false,
+  hooks: false,
+  skills: false,
+  agents: false,
+  toolRestrictions: false,
+  structuredOutput: true,
+  envInjection: true,
+  costControl: false,
+  effortControl: false,
+  thinkingControl: false,
+  fallbackModel: false,
+  sandbox: false,
+};
diff --git a/packages/providers/src/codex/config.ts b/packages/providers/src/codex/config.ts
new file mode 100644
index 0000000000..f8d6f2d7e6
--- /dev/null
+++ b/packages/providers/src/codex/config.ts
@@ -0,0 +1,46 @@
+/**
+ * Typed config parsing for Codex provider defaults.
+ * Validates and narrows the opaque assistantConfig to typed fields.
+ */
+import type { CodexProviderDefaults } from '../types';
+
+// Re-export so consumers can import the type from either location
+export type { CodexProviderDefaults } from '../types';
+
+/**
+ * Parse raw assistantConfig into typed Codex defaults.
+ * Defensive: invalid fields are silently dropped.
+ */
+export function parseCodexConfig(raw: Record<string, unknown>): CodexProviderDefaults {
+  const result: CodexProviderDefaults = {};
+
+  if (typeof raw.model === 'string') {
+    result.model = raw.model;
+  }
+
+  const validEfforts = ['minimal', 'low', 'medium', 'high', 'xhigh'];
+  if (
+    typeof raw.modelReasoningEffort === 'string' &&
+    validEfforts.includes(raw.modelReasoningEffort)
+  ) {
+    result.modelReasoningEffort =
+      raw.modelReasoningEffort as CodexProviderDefaults['modelReasoningEffort'];
+  }
+
+  const validSearchModes = ['disabled', 'cached', 'live'];
+  if (typeof raw.webSearchMode === 'string' && validSearchModes.includes(raw.webSearchMode)) {
+    result.webSearchMode = raw.webSearchMode as CodexProviderDefaults['webSearchMode'];
+  }
+
+  if (Array.isArray(raw.additionalDirectories)) {
+    result.additionalDirectories = raw.additionalDirectories.filter(
+      (d): d is string => typeof d === 'string'
+    );
+  }
+
+  if (typeof raw.codexBinaryPath === 'string') {
+    result.codexBinaryPath = raw.codexBinaryPath;
+  }
+
+  return result;
+}
diff --git a/packages/providers/src/codex/index.ts b/packages/providers/src/codex/index.ts
new file mode 100644
index 0000000000..71302f6884
--- /dev/null
+++ b/packages/providers/src/codex/index.ts
@@ -0,0 +1,3 @@
+export { CodexProvider, resetCodexSingleton } from './provider';
+export { parseCodexConfig, type CodexProviderDefaults } from './config';
+export { resolveCodexBinaryPath, fileExists } from './binary-resolver';
diff --git a/packages/core/src/clients/codex.test.ts b/packages/providers/src/codex/provider.test.ts
similarity index 69%
rename from packages/core/src/clients/codex.test.ts
rename to packages/providers/src/codex/provider.test.ts
index cfa329e7c1..669826ebc3 100644
--- a/packages/core/src/clients/codex.test.ts
+++ b/packages/providers/src/codex/provider.test.ts
@@ -1,4 +1,4 @@
-import { describe, test, expect, mock, beforeEach, afterEach, spyOn } from 'bun:test';
+import { describe, test, expect, mock, beforeEach } from 'bun:test';
 import { createMockLogger } from '../test/mocks/logger';
 
 const mockLogger = createMockLogger();
@@ -39,15 +39,15 @@ mock.module('@openai/codex-sdk', () => ({
   Codex: MockCodex,
 }));
 
-import { CodexClient } from './codex';
-import * as codebaseDb from '../db/codebases';
-import * as envLeakScanner from '../utils/env-leak-scanner';
+import { CodexProvider, resetCodexSingleton } from './provider';
 
-describe('CodexClient', () => {
-  let client: CodexClient;
+describe('CodexProvider', () => {
+  let client: CodexProvider;
 
   beforeEach(() => {
-    client = new CodexClient({ retryBaseDelayMs: 1 });
+    resetCodexSingleton();
+    client = new CodexProvider({ retryBaseDelayMs: 1 });
+    MockCodex.mockClear();
     mockStartThread.mockClear();
     mockResumeThread.mockClear();
     mockRunStreamed.mockClear();
@@ -67,6 +67,27 @@ describe('CodexClient', () => {
     });
   });
 
+  describe('getCapabilities', () => {
+    test('returns limited capability set for Codex provider', () => {
+      const caps = client.getCapabilities();
+      expect(caps).toEqual({
+        sessionResume: true,
+        mcp: false,
+        hooks: false,
+        skills: false,
+        agents: false,
+        toolRestrictions: false,
+        structuredOutput: true,
+        envInjection: true,
+        costControl: false,
+        effortControl: false,
+        thinkingControl: false,
+        fallbackModel: false,
+        sandbox: false,
+      });
+    });
+  });
+
   describe('sendQuery', () => {
     test('yields text events from agent_message items', async () => {
       mockRunStreamed.mockResolvedValue({
@@ -114,8 +135,6 @@ describe('CodexClient', () => {
         chunks.push(chunk);
       }
 
-      // Codex item.completed fires once the command is fully done, so we emit
-      // start + result back-to-back to close the UI tool card immediately.
       expect(chunks[0]).toEqual({ type: 'tool', toolName: 'npm test' });
       expect(chunks[1]).toEqual({
         type: 'tool_result',
@@ -184,10 +203,10 @@ describe('CodexClient', () => {
         chunks.push(chunk);
       }
 
-      expect(chunks[0]).toEqual({ type: 'tool', toolName: '🔍 Searching: codex sdk' });
+      expect(chunks[0]).toEqual({ type: 'tool', toolName: '\u{1F50D} Searching: codex sdk' });
       expect(chunks[1]).toEqual({
         type: 'tool_result',
-        toolName: '🔍 Searching: codex sdk',
+        toolName: '\u{1F50D} Searching: codex sdk',
         toolOutput: '',
       });
     });
@@ -216,7 +235,7 @@ describe('CodexClient', () => {
 
       expect(chunks[0]).toEqual({
         type: 'system',
-        content: '📋 Tasks:\n✅ Scan repo\n⬜ Add tests',
+        content: '\u{1F4CB} Tasks:\n\u2705 Scan repo\n\u2B1C Add tests',
       });
       expect(chunks).toHaveLength(2);
     });
@@ -253,11 +272,11 @@ describe('CodexClient', () => {
       expect(chunks).toHaveLength(3); // todoV1 + todoV2 + result
       expect(chunks[0]).toEqual({
         type: 'system',
-        content: '📋 Tasks:\n⬜ Scan repo\n⬜ Add tests',
+        content: '\u{1F4CB} Tasks:\n\u2B1C Scan repo\n\u2B1C Add tests',
       });
       expect(chunks[1]).toEqual({
         type: 'system',
-        content: '📋 Tasks:\n✅ Scan repo\n⬜ Add tests',
+        content: '\u{1F4CB} Tasks:\n\u2705 Scan repo\n\u2B1C Add tests',
       });
     });
 
@@ -287,7 +306,7 @@ describe('CodexClient', () => {
 
       expect(chunks[0]).toEqual({
         type: 'system',
-        content: '✅ File changes:\n➕ src/new.ts\n📝 src/app.ts\n➖ src/old.ts',
+        content: '\u2705 File changes:\n\u2795 src/new.ts\n\u{1F4DD} src/app.ts\n\u2796 src/old.ts',
       });
     });
 
@@ -314,7 +333,7 @@ describe('CodexClient', () => {
 
       expect(chunks[0]).toEqual({
         type: 'system',
-        content: '❌ File changes:\n📝 src/locked.ts\nPermission denied',
+        content: '\u274C File changes:\n\u{1F4DD} src/locked.ts\nPermission denied',
       });
     });
 
@@ -340,7 +359,7 @@ describe('CodexClient', () => {
 
       expect(chunks[0]).toEqual({
         type: 'system',
-        content: '❌ File change failed: Disk full',
+        content: '\u274C File change failed: Disk full',
       });
       expect(mockLogger.warn).toHaveBeenCalledWith(
         expect.objectContaining({ status: 'failed' }),
@@ -366,7 +385,7 @@ describe('CodexClient', () => {
 
       expect(chunks[0]).toEqual({
         type: 'system',
-        content: '❌ File change failed',
+        content: '\u274C File change failed',
       });
     });
 
@@ -397,18 +416,18 @@ describe('CodexClient', () => {
       }
 
       // First mcp call (in_progress on item.completed): start + empty result
-      expect(chunks[0]).toEqual({ type: 'tool', toolName: '🔌 MCP: fs/readFile' });
+      expect(chunks[0]).toEqual({ type: 'tool', toolName: '\u{1F50C} MCP: fs/readFile' });
       expect(chunks[1]).toEqual({
         type: 'tool_result',
-        toolName: '🔌 MCP: fs/readFile',
+        toolName: '\u{1F50C} MCP: fs/readFile',
         toolOutput: '',
       });
       // Second mcp call (failed): start + error result so the UI card closes
-      expect(chunks[2]).toEqual({ type: 'tool', toolName: '🔌 MCP: fs/readFile' });
+      expect(chunks[2]).toEqual({ type: 'tool', toolName: '\u{1F50C} MCP: fs/readFile' });
       expect(chunks[3]).toEqual({
         type: 'tool_result',
-        toolName: '🔌 MCP: fs/readFile',
-        toolOutput: '❌ Error: Permission denied',
+        toolName: '\u{1F50C} MCP: fs/readFile',
+        toolOutput: '\u274C Error: Permission denied',
       });
       expect(mockLogger.warn).toHaveBeenCalledWith(
         expect.objectContaining({ server: 'fs', tool: 'readFile' }),
@@ -440,19 +459,22 @@ describe('CodexClient', () => {
         chunks.push(chunk);
       }
 
-      // Each item now emits start + empty result so the UI cards always close.
-      expect(chunks[0]).toEqual({ type: 'tool', toolName: '🔌 MCP: readFile' });
+      expect(chunks[0]).toEqual({ type: 'tool', toolName: '\u{1F50C} MCP: readFile' });
       expect(chunks[1]).toEqual({
         type: 'tool_result',
-        toolName: '🔌 MCP: readFile',
+        toolName: '\u{1F50C} MCP: readFile',
+        toolOutput: '',
+      });
+      expect(chunks[2]).toEqual({ type: 'tool', toolName: '\u{1F50C} MCP: fs' });
+      expect(chunks[3]).toEqual({
+        type: 'tool_result',
+        toolName: '\u{1F50C} MCP: fs',
         toolOutput: '',
       });
-      expect(chunks[2]).toEqual({ type: 'tool', toolName: '🔌 MCP: fs' });
-      expect(chunks[3]).toEqual({ type: 'tool_result', toolName: '🔌 MCP: fs', toolOutput: '' });
-      expect(chunks[4]).toEqual({ type: 'tool', toolName: '🔌 MCP: MCP tool' });
+      expect(chunks[4]).toEqual({ type: 'tool', toolName: '\u{1F50C} MCP: MCP tool' });
       expect(chunks[5]).toEqual({
         type: 'tool_result',
-        toolName: '🔌 MCP: MCP tool',
+        toolName: '\u{1F50C} MCP: MCP tool',
         toolOutput: '',
       });
     });
@@ -473,11 +495,11 @@ describe('CodexClient', () => {
         chunks.push(chunk);
       }
 
-      expect(chunks[0]).toEqual({ type: 'tool', toolName: '🔌 MCP: db/query' });
+      expect(chunks[0]).toEqual({ type: 'tool', toolName: '\u{1F50C} MCP: db/query' });
       expect(chunks[1]).toEqual({
         type: 'tool_result',
-        toolName: '🔌 MCP: db/query',
-        toolOutput: '❌ Error: MCP tool failed',
+        toolName: '\u{1F50C} MCP: db/query',
+        toolOutput: '\u274C Error: MCP tool failed',
       });
     });
 
@@ -503,12 +525,11 @@ describe('CodexClient', () => {
         chunks.push(chunk);
       }
 
-      // Completed MCP calls now emit tool + tool_result so the UI card closes.
       expect(chunks).toHaveLength(3);
-      expect(chunks[0]).toEqual({ type: 'tool', toolName: '🔌 MCP: fs/readFile' });
+      expect(chunks[0]).toEqual({ type: 'tool', toolName: '\u{1F50C} MCP: fs/readFile' });
       expect(chunks[1]).toEqual({
         type: 'tool_result',
-        toolName: '🔌 MCP: fs/readFile',
+        toolName: '\u{1F50C} MCP: fs/readFile',
         toolOutput: JSON.stringify([{ type: 'text', text: 'file contents' }]),
       });
       expect(chunks[2]).toEqual({
@@ -525,7 +546,6 @@ describe('CodexClient', () => {
         })(),
       });
 
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       for await (const _ of client.sendQuery('test prompt', '/my/workspace')) {
         // consume
       }
@@ -548,7 +568,6 @@ describe('CodexClient', () => {
         })(),
       });
 
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       for await (const _ of client.sendQuery('test prompt', '/workspace', 'existing-thread')) {
         // consume
       }
@@ -585,7 +604,6 @@ describe('CodexClient', () => {
       }
 
       expect(mockResumeThread).toHaveBeenCalled();
-      // Verify fallback startThread is called with correct config options
       expect(mockStartThread).toHaveBeenCalledWith(
         expect.objectContaining({
           workingDirectory: '/workspace',
@@ -595,7 +613,6 @@ describe('CodexClient', () => {
           approvalPolicy: 'never',
         })
       );
-      // Verify error was logged
       expect(mockLogger.error).toHaveBeenCalledWith(
         { err: resumeError, sessionId: 'bad-thread-id' },
         'resume_thread_failed'
@@ -612,19 +629,20 @@ describe('CodexClient', () => {
       });
     });
 
-    test('passes model and codex options to thread options', async () => {
+    test('passes model and codex options via assistantConfig to thread options', async () => {
       mockRunStreamed.mockResolvedValue({
         events: (async function* () {
           yield { type: 'turn.completed', usage: defaultUsage };
         })(),
       });
 
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       for await (const _ of client.sendQuery('test prompt', '/workspace', undefined, {
         model: 'gpt-5.2-codex',
-        modelReasoningEffort: 'medium',
-        webSearchMode: 'live',
-        additionalDirectories: ['/other/repo'],
+        assistantConfig: {
+          modelReasoningEffort: 'medium',
+          webSearchMode: 'live',
+          additionalDirectories: ['/other/repo'],
+        },
       })) {
         // consume
       }
@@ -702,6 +720,102 @@ describe('CodexClient', () => {
       expect(mockRunStreamed).toHaveBeenCalledWith('test prompt', {});
     });
 
+    test('creates a per-call Codex instance when env is provided', async () => {
+      mockRunStreamed.mockResolvedValue({
+        events: (async function* () {
+          yield { type: 'turn.completed', usage: defaultUsage };
+        })(),
+      });
+
+      for await (const _ of client.sendQuery('test prompt', '/workspace', undefined, {
+        env: { MY_SECRET: 'abc123' },
+      })) {
+        // consume
+      }
+
+      expect(MockCodex).toHaveBeenCalledWith(
+        expect.objectContaining({
+          env: expect.objectContaining({ MY_SECRET: 'abc123' }),
+        })
+      );
+      expect(mockStartThread).toHaveBeenCalledTimes(1);
+    });
+
+    test('builds env by preserving process vars and letting request env win on collisions', async () => {
+      const originalPath = process.env.PATH;
+      const originalArchonEnv = process.env.ARCHON_CODEX_TEST_ENV;
+      process.env.PATH = 'from-process';
+      process.env.ARCHON_CODEX_TEST_ENV = 'kept-from-process';
+
+      try {
+        mockRunStreamed.mockResolvedValue({
+          events: (async function* () {
+            yield { type: 'turn.completed', usage: defaultUsage };
+          })(),
+        });
+
+        for await (const _ of client.sendQuery('test prompt', '/workspace', undefined, {
+          env: { PATH: 'from-request', MY_SECRET: 'abc123' },
+        })) {
+          // consume
+        }
+
+        expect(MockCodex).toHaveBeenCalledWith(
+          expect.objectContaining({
+            env: expect.objectContaining({
+              PATH: 'from-request',
+              ARCHON_CODEX_TEST_ENV: 'kept-from-process',
+              MY_SECRET: 'abc123',
+            }),
+          })
+        );
+      } finally {
+        if (originalPath === undefined) {
+          delete process.env.PATH;
+        } else {
+          process.env.PATH = originalPath;
+        }
+        if (originalArchonEnv === undefined) {
+          delete process.env.ARCHON_CODEX_TEST_ENV;
+        } else {
+          process.env.ARCHON_CODEX_TEST_ENV = originalArchonEnv;
+        }
+      }
+    });
+
+    test('reuses the singleton Codex instance across sequential calls without env', async () => {
+      mockRunStreamed.mockResolvedValue({
+        events: (async function* () {
+          yield { type: 'turn.completed', usage: defaultUsage };
+        })(),
+      });
+
+      for await (const _ of client.sendQuery('first prompt', '/workspace')) {
+        // consume
+      }
+      for await (const _ of client.sendQuery('second prompt', '/workspace')) {
+        // consume
+      }
+
+      expect(MockCodex).toHaveBeenCalledTimes(1);
+    });
+
+    test('wraps per-call Codex constructor failures with provider error context', async () => {
+      MockCodex.mockImplementationOnce(() => {
+        throw new Error('constructor failed');
+      });
+
+      const consumeGenerator = async (): Promise<void> => {
+        for await (const _ of client.sendQuery('test prompt', '/workspace', undefined, {
+          env: { MY_SECRET: 'abc123' },
+        })) {
+          // consume
+        }
+      };
+
+      await expect(consumeGenerator()).rejects.toThrow('Codex query failed: constructor failed');
+    });
+
     test('breaks on turn.completed event', async () => {
       mockRunStreamed.mockResolvedValue({
         events: (async function* () {
@@ -740,13 +854,11 @@ describe('CodexClient', () => {
         chunks.push(chunk);
       }
 
-      // Verify item.started logging with correct format
       expect(mockLogger.debug).toHaveBeenCalledWith(
         { eventType: 'item.started', itemType: 'command_execution', itemId: 'item-1' },
         'item_started'
       );
 
-      // Verify item.completed logging includes command context
       expect(mockLogger.debug).toHaveBeenCalledWith(
         {
           eventType: 'item.completed',
@@ -771,7 +883,7 @@ describe('CodexClient', () => {
         chunks.push(chunk);
       }
 
-      expect(chunks[0]).toEqual({ type: 'system', content: '⚠️ Something went wrong' });
+      expect(chunks[0]).toEqual({ type: 'system', content: '\u26A0\uFE0F Something went wrong' });
       expect(mockLogger.error).toHaveBeenCalledWith(
         { message: 'Something went wrong' },
         'stream_error'
@@ -818,7 +930,10 @@ describe('CodexClient', () => {
         chunks.push(chunk);
       }
 
-      expect(chunks[0]).toEqual({ type: 'system', content: '❌ Turn failed: Rate limit exceeded' });
+      expect(chunks[0]).toEqual({
+        type: 'system',
+        content: '\u274C Turn failed: Rate limit exceeded',
+      });
       expect(mockLogger.error).toHaveBeenCalledWith(
         { errorMessage: 'Rate limit exceeded' },
         'turn_failed'
@@ -837,7 +952,10 @@ describe('CodexClient', () => {
         chunks.push(chunk);
       }
 
-      expect(chunks[0]).toEqual({ type: 'system', content: '❌ Turn failed: Unknown error' });
+      expect(chunks[0]).toEqual({
+        type: 'system',
+        content: '\u274C Turn failed: Unknown error',
+      });
       expect(mockLogger.error).toHaveBeenCalledWith(
         { errorMessage: 'Unknown error' },
         'turn_failed'
@@ -1001,109 +1119,212 @@ describe('CodexClient', () => {
         expect(mockRunStreamed).toHaveBeenCalledTimes(1);
       });
     });
-  });
 
-  describe('pre-spawn env leak gate', () => {
-    let spyFindByDefaultCwd: ReturnType<typeof spyOn>;
-    let spyFindByPathPrefix: ReturnType<typeof spyOn>;
-    let spyScan: ReturnType<typeof spyOn>;
+    describe('structured output normalization', () => {
+      test('populates structuredOutput on result when outputFormat is set and text is valid JSON', async () => {
+        const jsonPayload = { status: 'ok', count: 42 };
+        mockRunStreamed.mockResolvedValueOnce({
+          events: (async function* () {
+            yield {
+              type: 'item.completed',
+              item: { type: 'agent_message', id: 'msg-1', text: JSON.stringify(jsonPayload) },
+            };
+            yield { type: 'turn.completed', usage: defaultUsage };
+          })(),
+        });
 
-    beforeEach(() => {
-      // Restore a working runStreamed default so retry-test bleed doesn't break gate tests
-      mockRunStreamed.mockResolvedValue({
-        events: (async function* () {
-          yield { type: 'turn.completed', usage: defaultUsage };
-        })(),
-      });
-      spyFindByDefaultCwd = spyOn(codebaseDb, 'findCodebaseByDefaultCwd').mockResolvedValue(null);
-      spyFindByPathPrefix = spyOn(codebaseDb, 'findCodebaseByPathPrefix').mockResolvedValue(null);
-      spyScan = spyOn(envLeakScanner, 'scanPathForSensitiveKeys').mockReturnValue({
-        path: '/workspace',
-        findings: [],
+        const chunks = [];
+        for await (const chunk of client.sendQuery('test', '/tmp', undefined, {
+          outputFormat: { type: 'json_schema', schema: { type: 'object' } },
+        })) {
+          chunks.push(chunk);
+        }
+
+        const resultChunk = chunks.find(c => c.type === 'result');
+        expect(resultChunk).toBeDefined();
+        expect(resultChunk!.type === 'result' && resultChunk!.structuredOutput).toEqual(
+          jsonPayload
+        );
       });
-    });
 
-    afterEach(() => {
-      spyFindByDefaultCwd.mockRestore();
-      spyFindByPathPrefix.mockRestore();
-      spyScan.mockRestore();
-    });
+      test('yields system warning when outputFormat is set but text is not valid JSON', async () => {
+        mockRunStreamed.mockResolvedValueOnce({
+          events: (async function* () {
+            yield {
+              type: 'item.completed',
+              item: { type: 'agent_message', id: 'msg-1', text: 'not json at all' },
+            };
+            yield { type: 'turn.completed', usage: defaultUsage };
+          })(),
+        });
+
+        const chunks = [];
+        for await (const chunk of client.sendQuery('test', '/tmp', undefined, {
+          outputFormat: { type: 'json_schema', schema: { type: 'object' } },
+        })) {
+          chunks.push(chunk);
+        }
+
+        const systemChunk = chunks.find(c => c.type === 'system');
+        expect(systemChunk).toBeDefined();
+        expect(systemChunk!.type === 'system' && systemChunk!.content).toContain(
+          'Structured output requested but Codex returned non-JSON'
+        );
 
-    test('throws EnvLeakError when .env contains sensitive keys and registered codebase has no consent', async () => {
-      spyFindByDefaultCwd.mockResolvedValueOnce({
-        id: 'codebase-1',
-        allow_env_keys: false,
-        default_cwd: '/workspace',
+        const resultChunk = chunks.find(c => c.type === 'result');
+        expect(resultChunk).toBeDefined();
+        expect(resultChunk!.type === 'result' && resultChunk!.structuredOutput).toBeUndefined();
       });
-      spyScan.mockReturnValueOnce({
-        path: '/workspace',
-        findings: [{ file: '.env', keys: ['ANTHROPIC_API_KEY'] }],
+
+      test('does not populate structuredOutput when outputFormat is not set', async () => {
+        mockRunStreamed.mockResolvedValueOnce({
+          events: (async function* () {
+            yield {
+              type: 'item.completed',
+              item: { type: 'agent_message', id: 'msg-1', text: '{"valid":"json"}' },
+            };
+            yield { type: 'turn.completed', usage: defaultUsage };
+          })(),
+        });
+
+        const chunks = [];
+        for await (const chunk of client.sendQuery('test', '/tmp')) {
+          chunks.push(chunk);
+        }
+
+        const resultChunk = chunks.find(c => c.type === 'result');
+        expect(resultChunk).toBeDefined();
+        expect(resultChunk!.type === 'result' && resultChunk!.structuredOutput).toBeUndefined();
       });
 
-      const consumeGenerator = async (): Promise<void> => {
-        for await (const _ of client.sendQuery('test', '/workspace')) {
-          // consume
+      test('handles nodeConfig.output_format path', async () => {
+        const jsonPayload = { key: 'value' };
+        mockRunStreamed.mockResolvedValueOnce({
+          events: (async function* () {
+            yield {
+              type: 'item.completed',
+              item: { type: 'agent_message', id: 'msg-1', text: JSON.stringify(jsonPayload) },
+            };
+            yield { type: 'turn.completed', usage: defaultUsage };
+          })(),
+        });
+
+        const chunks = [];
+        for await (const chunk of client.sendQuery('test', '/tmp', undefined, {
+          nodeConfig: { output_format: { type: 'object' } },
+        })) {
+          chunks.push(chunk);
         }
-      };
 
-      await expect(consumeGenerator()).rejects.toThrow('Cannot run workflow');
+        const resultChunk = chunks.find(c => c.type === 'result');
+        expect(resultChunk).toBeDefined();
+        expect(resultChunk!.type === 'result' && resultChunk!.structuredOutput).toEqual(
+          jsonPayload
+        );
+      });
     });
+  });
+});
 
-    test('skips scan entirely when cwd is not a registered codebase', async () => {
-      // Both lookups return null (default from beforeEach). Pre-spawn safety net
-      // is only for registered codebases; unregistered paths go through registerRepoAtPath.
-      spyScan.mockReturnValue({
-        path: '/workspace',
-        findings: [{ file: '.env', keys: ['ANTHROPIC_API_KEY'] }],
-      });
+// ─── Behavioral regression tests (black-box via sendQuery) ───────────────
 
-      const chunks = [];
-      for await (const chunk of client.sendQuery('test', '/workspace')) {
-        chunks.push(chunk);
-      }
+describe('sendQuery decomposition behaviors', () => {
+  let client: CodexProvider;
 
-      expect(spyScan).not.toHaveBeenCalled();
-    });
+  beforeEach(() => {
+    client = new CodexProvider({ retryBaseDelayMs: 1 });
+    mockStartThread.mockClear();
+    mockResumeThread.mockClear();
+    mockRunStreamed.mockClear();
+    mockLogger.info.mockClear();
+    mockLogger.warn.mockClear();
+    mockLogger.error.mockClear();
+    mockLogger.debug.mockClear();
 
-    test('skips scan when codebase has allow_env_keys: true', async () => {
-      spyFindByDefaultCwd.mockResolvedValueOnce({
-        id: 'codebase-1',
-        allow_env_keys: true,
-        default_cwd: '/workspace',
-      });
+    mockStartThread.mockReturnValue(createMockThread('new-thread-id'));
+    mockResumeThread.mockReturnValue(createMockThread('resumed-thread-id'));
+  });
 
-      const chunks = [];
-      for await (const chunk of client.sendQuery('test', '/workspace')) {
-        chunks.push(chunk);
-      }
+  test('abort signal throws instead of silently truncating stream', async () => {
+    const abortController = new AbortController();
 
-      expect(spyScan).not.toHaveBeenCalled();
+    mockRunStreamed.mockResolvedValue({
+      events: (async function* () {
+        yield {
+          type: 'item.completed',
+          item: { type: 'agent_message', text: 'partial', id: '1' },
+        };
+        // Abort mid-stream
+        abortController.abort();
+        yield {
+          type: 'item.completed',
+          item: { type: 'agent_message', text: 'should not appear', id: '2' },
+        };
+        yield { type: 'turn.completed', usage: defaultUsage };
+      })(),
     });
 
-    test('proceeds without scanning when cwd has no registered codebase', async () => {
-      const chunks = [];
-      for await (const chunk of client.sendQuery('test', '/workspace')) {
-        chunks.push(chunk);
+    const consumeGenerator = async (): Promise<void> => {
+      for await (const _ of client.sendQuery('test', '/workspace', undefined, {
+        abortSignal: abortController.signal,
+      })) {
+        // consume
       }
+    };
 
-      expect(spyScan).not.toHaveBeenCalled();
-    });
+    await expect(consumeGenerator()).rejects.toThrow('Query aborted');
+  });
 
-    test('uses prefix lookup for worktree paths when exact match returns null', async () => {
-      spyFindByDefaultCwd.mockResolvedValueOnce(null);
-      spyFindByPathPrefix.mockResolvedValueOnce({
-        id: 'codebase-1',
-        allow_env_keys: true,
-        default_cwd: '/workspace/source',
-      });
+  test('enriched error thrown at retry exhaustion, not raw error', async () => {
+    mockRunStreamed.mockRejectedValue(new Error('codex exec crashed'));
 
-      const chunks = [];
-      for await (const chunk of client.sendQuery('test', '/workspace/worktrees/feature')) {
-        chunks.push(chunk);
+    const consumeGenerator = async (): Promise<void> => {
+      for await (const _ of client.sendQuery('test', '/workspace')) {
+        // consume
       }
-
-      expect(spyFindByPathPrefix).toHaveBeenCalledWith('/workspace/worktrees/feature');
-      expect(spyScan).not.toHaveBeenCalled();
+    };
+
+    const err = await consumeGenerator().catch((e: unknown) => e as Error);
+    expect(err).toBeInstanceOf(Error);
+    // Must contain the enriched classification prefix
+    expect(err.message).toContain('Codex crash');
+  }, 5_000);
+
+  test('todo_list dedup state resets between retry attempts', async () => {
+    const todoItem = {
+      type: 'todo_list',
+      items: [{ text: 'Task 1', completed: false }],
+      id: 'todo-1',
+    };
+
+    let callCount = 0;
+    mockRunStreamed.mockImplementation(() => {
+      callCount++;
+      if (callCount === 1) {
+        return Promise.resolve({
+          events: (async function* () {
+            yield { type: 'item.completed', item: todoItem };
+            throw new Error('codex exec crashed');
+          })(),
+        });
+      }
+      // On retry, same todo should appear again (fresh state)
+      return Promise.resolve({
+        events: (async function* () {
+          yield { type: 'item.completed', item: todoItem };
+          yield { type: 'turn.completed', usage: defaultUsage };
+        })(),
+      });
     });
-  });
+
+    const chunks = [];
+    for await (const chunk of client.sendQuery('test', '/workspace')) {
+      chunks.push(chunk);
+    }
+
+    // The todo should appear on the retry attempt (not suppressed by dedup from attempt 1)
+    const systemChunks = chunks.filter(c => c.type === 'system');
+    expect(systemChunks.length).toBeGreaterThanOrEqual(1);
+    expect(systemChunks.some(c => c.type === 'system' && c.content.includes('Task 1'))).toBe(true);
+  }, 5_000);
 });
diff --git a/packages/providers/src/codex/provider.ts b/packages/providers/src/codex/provider.ts
new file mode 100644
index 0000000000..b9e1d493e9
--- /dev/null
+++ b/packages/providers/src/codex/provider.ts
@@ -0,0 +1,628 @@
+/**
+ * Codex SDK wrapper
+ * Provides async generator interface for streaming Codex responses
+ */
+import {
+  Codex,
+  type ThreadOptions,
+  type TurnOptions,
+  type TurnCompletedEvent,
+} from '@openai/codex-sdk';
+import type {
+  IAgentProvider,
+  SendQueryOptions,
+  MessageChunk,
+  TokenUsage,
+  ProviderCapabilities,
+} from '../types';
+import { parseCodexConfig } from './config';
+import { CODEX_CAPABILITIES } from './capabilities';
+import { resolveCodexBinaryPath } from './binary-resolver';
+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('provider.codex');
+  return cachedLog;
+}
+
+// Singleton Codex instance (async because binary path resolution is async)
+let codexInstance: Codex | null = null;
+let codexInitPromise: Promise<Codex> | null = null;
+
+/** Reset singleton state. Exported for tests only. */
+export function resetCodexSingleton(): void {
+  codexInstance = null;
+  codexInitPromise = null;
+}
+
+/**
+ * Get or create Codex SDK instance.
+ */
+async function getCodex(configCodexBinaryPath?: string): Promise<Codex> {
+  if (codexInstance) return codexInstance;
+
+  if (!codexInitPromise) {
+    codexInitPromise = (async (): Promise<Codex> => {
+      const codexPathOverride = await resolveCodexBinaryPath(configCodexBinaryPath);
+      const instance = new Codex({ codexPathOverride });
+      codexInstance = instance;
+      return instance;
+    })().catch(err => {
+      codexInitPromise = null;
+      throw err;
+    });
+  }
+  return codexInitPromise;
+}
+
+/**
+ * Build thread options for Codex SDK
+ */
+function buildThreadOptions(
+  cwd: string,
+  model?: string,
+  assistantConfig?: Record<string, unknown>
+): ThreadOptions {
+  const config = parseCodexConfig(assistantConfig ?? {});
+  return {
+    workingDirectory: cwd,
+    skipGitRepoCheck: true,
+    sandboxMode: 'danger-full-access',
+    networkAccessEnabled: true,
+    approvalPolicy: 'never',
+    model: model ?? config.model,
+    modelReasoningEffort: config.modelReasoningEffort,
+    webSearchMode: config.webSearchMode,
+    additionalDirectories: config.additionalDirectories,
+  };
+}
+
+function buildCodexEnv(requestEnv: Record<string, string>): Record<string, string> {
+  const baseEnv = Object.fromEntries(
+    Object.entries(process.env).filter((entry): entry is [string, string] => entry[1] !== undefined)
+  );
+  // Managed project env intentionally overrides inherited process env for project-scoped execution.
+  return { ...baseEnv, ...requestEnv };
+}
+
+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}`;
+}
+
+const MAX_SUBPROCESS_RETRIES = 3;
+const RETRY_BASE_DELAY_MS = 2000;
+const RATE_LIMIT_PATTERNS = ['rate limit', 'too many requests', '429', 'overloaded'];
+const AUTH_PATTERNS = [
+  'credit balance',
+  'unauthorized',
+  'authentication',
+  'invalid token',
+  '401',
+  '403',
+];
+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,
+  };
+}
+
+// ─── Turn Options Builder ────────────────────────────────────────────────
+
+/**
+ * Build turn options for a single Codex turn.
+ * Handles output schema from both requestOptions and nodeConfig (workflow path).
+ */
+function buildTurnOptions(requestOptions?: SendQueryOptions): {
+  turnOptions: TurnOptions;
+  hasOutputFormat: boolean;
+} {
+  const turnOptions: TurnOptions = {};
+  const hasOutputFormat = !!(
+    requestOptions?.outputFormat ?? requestOptions?.nodeConfig?.output_format
+  );
+  if (requestOptions?.outputFormat) {
+    turnOptions.outputSchema = requestOptions.outputFormat.schema;
+  }
+  if (requestOptions?.nodeConfig?.output_format && !requestOptions?.outputFormat) {
+    turnOptions.outputSchema = requestOptions.nodeConfig.output_format;
+  }
+  if (requestOptions?.abortSignal) {
+    turnOptions.signal = requestOptions.abortSignal;
+  }
+  return { turnOptions, hasOutputFormat };
+}
+
+// ─── Stream Normalizer ───────────────────────────────────────────────────
+
+/** State maintained across Codex event stream normalization. */
+interface CodexStreamState {
+  lastTodoListSignature?: string;
+}
+
+/**
+ * Normalize raw Codex SDK events into Archon MessageChunks.
+ * Handles structured output normalization (Codex returns JSON inline in text).
+ */
+async function* streamCodexEvents(
+  events: AsyncIterable<Record<string, unknown>>,
+  hasOutputFormat: boolean,
+  threadId: string | null | undefined,
+  abortSignal?: AbortSignal
+): AsyncGenerator<MessageChunk> {
+  const state: CodexStreamState = {};
+  let accumulatedText = '';
+
+  for await (const event of events) {
+    if (abortSignal?.aborted) {
+      getLog().info('query_aborted_between_events');
+      throw new Error('Query aborted');
+    }
+
+    if (event.type === 'item.started') {
+      const item = event.item as { type: string; id: string };
+      getLog().debug(
+        { eventType: event.type, itemType: item.type, itemId: item.id },
+        'item_started'
+      );
+    }
+
+    if (event.type === 'error') {
+      const errorEvent = event as { message: string };
+      getLog().error({ message: errorEvent.message }, 'stream_error');
+      if (!errorEvent.message.includes('MCP client')) {
+        yield { type: 'system', content: `⚠️ ${errorEvent.message}` };
+      }
+      continue;
+    }
+
+    if (event.type === 'turn.failed') {
+      const errorObj = (event as { error?: { message?: string } }).error;
+      const errorMessage = errorObj?.message ?? 'Unknown error';
+      getLog().error({ errorMessage }, 'turn_failed');
+      yield { type: 'system', content: `❌ Turn failed: ${errorMessage}` };
+      break;
+    }
+
+    if (event.type === 'item.completed') {
+      const item = event.item as Record<string, unknown>;
+      const itemType = item.type as string;
+
+      const logContext: Record<string, unknown> = {
+        eventType: event.type,
+        itemType,
+        itemId: item.id,
+      };
+      if (itemType === 'command_execution' && item.command) {
+        logContext.command = item.command;
+      }
+      getLog().debug(logContext, 'item_completed');
+
+      switch (itemType) {
+        case 'agent_message':
+          if (item.text) {
+            if (hasOutputFormat) accumulatedText += item.text as string;
+            yield { type: 'assistant', content: item.text as string };
+          }
+          break;
+
+        case 'command_execution':
+          if (item.command) {
+            const cmd = item.command as string;
+            yield { type: 'tool', toolName: cmd };
+            const exitCode = item.exit_code as number | null | undefined;
+            const exitSuffix =
+              exitCode != null && exitCode !== 0 ? `\n[exit code: ${String(exitCode)}]` : '';
+            yield {
+              type: 'tool_result',
+              toolName: cmd,
+              toolOutput: ((item.aggregated_output as string) ?? '') + exitSuffix,
+            };
+          } else {
+            getLog().warn({ itemId: item.id }, 'command_execution_missing_command');
+          }
+          break;
+
+        case 'reasoning':
+          if (item.text) {
+            yield { type: 'thinking', content: item.text as string };
+          }
+          break;
+
+        case 'web_search':
+          if (item.query) {
+            const searchToolName = `🔍 Searching: ${item.query as string}`;
+            yield { type: 'tool', toolName: searchToolName };
+            yield { type: 'tool_result', toolName: searchToolName, toolOutput: '' };
+          } else {
+            getLog().debug({ itemId: item.id }, 'web_search_missing_query');
+          }
+          break;
+
+        case 'todo_list': {
+          const items = item.items as { text?: string; completed?: boolean }[] | undefined;
+          if (Array.isArray(items) && items.length > 0) {
+            const normalizedItems = items.map(t => ({
+              text: typeof t.text === 'string' ? t.text : '(unnamed task)',
+              completed: t.completed ?? false,
+            }));
+            const signature = JSON.stringify(normalizedItems);
+            if (signature !== state.lastTodoListSignature) {
+              state.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 as string) === '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;
+
+          const changes = item.changes as { kind: string; path?: string }[] | undefined;
+          if (Array.isArray(changes) && changes.length > 0) {
+            const changeList = changes
+              .map(c => {
+                const icon = c.kind === 'add' ? '➕' : c.kind === 'delete' ? '➖' : '📝';
+                return `${icon} ${c.path ?? '(unknown file)'}`;
+              })
+              .join('\n');
+            const errorSuffix =
+              (item.status as string) === 'failed' && fileErrorMessage
+                ? `\n${fileErrorMessage}`
+                : '';
+            yield {
+              type: 'system',
+              content: `${statusIcon} File changes:\n${changeList}${errorSuffix}`,
+            };
+          } else if ((item.status as string) === '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 server = item.server as string | undefined;
+          const tool = item.tool as string | undefined;
+          const toolInfo = server && tool ? `${server}/${tool}` : (tool ?? server ?? 'MCP tool');
+          const mcpToolName = `🔌 MCP: ${toolInfo}`;
+
+          yield { type: 'tool', toolName: mcpToolName };
+
+          if ((item.status as string) === 'failed') {
+            getLog().warn(
+              { server, tool, error: item.error, itemId: item.id },
+              'mcp_tool_call_failed'
+            );
+            const mcpError = item.error as { message?: string } | undefined;
+            const errMsg = mcpError?.message
+              ? `❌ Error: ${mcpError.message}`
+              : '❌ Error: MCP tool failed';
+            yield { type: 'tool_result', toolName: mcpToolName, toolOutput: errMsg };
+          } else {
+            let toolOutput = '';
+            const mcpResult = item.result as { content?: unknown } | undefined;
+            if (mcpResult?.content) {
+              if (Array.isArray(mcpResult.content)) {
+                toolOutput = JSON.stringify(mcpResult.content);
+              } else {
+                getLog().warn(
+                  {
+                    itemId: item.id,
+                    server,
+                    tool,
+                    resultType: typeof mcpResult.content,
+                  },
+                  'mcp_tool_call_unexpected_result_shape'
+                );
+              }
+            }
+            yield { type: 'tool_result', toolName: mcpToolName, toolOutput };
+          }
+          break;
+        }
+      }
+    }
+
+    if (event.type === 'turn.completed') {
+      getLog().debug('turn_completed');
+      const usage = extractUsageFromCodexEvent(event as TurnCompletedEvent);
+
+      // Codex returns structured output inline in agent_message text.
+      // Normalize: parse as JSON and put on structuredOutput so the
+      // dag-executor can handle all providers uniformly.
+      let structuredOutput: unknown;
+      if (hasOutputFormat && accumulatedText) {
+        try {
+          structuredOutput = JSON.parse(accumulatedText);
+          getLog().debug('codex.structured_output_parsed');
+        } catch {
+          getLog().warn(
+            { outputPreview: accumulatedText.slice(0, 200) },
+            'codex.structured_output_not_json'
+          );
+          yield {
+            type: 'system',
+            content:
+              '⚠️ Structured output requested but Codex returned non-JSON text. ' +
+              'Downstream $nodeId.output.field references may not evaluate correctly.',
+          };
+        }
+      }
+
+      yield {
+        type: 'result',
+        sessionId: threadId ?? undefined,
+        tokens: usage,
+        ...(structuredOutput !== undefined ? { structuredOutput } : {}),
+      };
+      break;
+    }
+  }
+}
+
+// ─── Error Classification & Retry ────────────────────────────────────────
+
+/**
+ * Classify a Codex error and determine retry eligibility.
+ */
+function classifyAndEnrichCodexError(
+  error: Error,
+  model?: string
+): { enrichedError: Error; errorClass: string; shouldRetry: boolean } {
+  const errorClass = classifyCodexError(error.message);
+
+  if (errorClass === 'model_access') {
+    return {
+      enrichedError: new Error(buildModelAccessMessage(model)),
+      errorClass,
+      shouldRetry: false,
+    };
+  }
+
+  if (errorClass === 'auth') {
+    const enrichedError = new Error(`Codex auth error: ${error.message}`);
+    enrichedError.cause = error;
+    return { enrichedError, errorClass, shouldRetry: false };
+  }
+
+  const enrichedError = new Error(`Codex ${errorClass}: ${error.message}`);
+  enrichedError.cause = error;
+  const shouldRetry = errorClass === 'rate_limit' || errorClass === 'crash';
+  return { enrichedError, errorClass, shouldRetry };
+}
+
+// ─── Codex Provider ──────────────────────────────────────────────────────
+
+/**
+ * Codex AI agent provider.
+ * Implements IAgentProvider with Codex SDK integration.
+ *
+ * sendQuery orchestrates the following internal helpers:
+ * - buildThreadOptions: SDK thread configuration
+ * - buildTurnOptions: per-turn configuration (output schema, abort signal)
+ * - streamCodexEvents: raw SDK event normalization into MessageChunks
+ * - classifyAndEnrichCodexError: error classification for retry decisions
+ */
+export class CodexProvider implements IAgentProvider {
+  private readonly retryBaseDelayMs: number;
+
+  constructor(options?: { retryBaseDelayMs?: number }) {
+    this.retryBaseDelayMs = options?.retryBaseDelayMs ?? RETRY_BASE_DELAY_MS;
+  }
+
+  private async createCodexClient(
+    configCodexBinaryPath: string | undefined,
+    requestEnv?: Record<string, string>
+  ): Promise<Codex> {
+    if (!requestEnv || Object.keys(requestEnv).length === 0) {
+      return getCodex(configCodexBinaryPath);
+    }
+
+    try {
+      return new Codex({
+        codexPathOverride: await resolveCodexBinaryPath(configCodexBinaryPath),
+        env: buildCodexEnv(requestEnv),
+      });
+    } catch (error) {
+      const err = error as Error;
+      if (isModelAccessError(err.message)) {
+        throw new Error(buildModelAccessMessage());
+      }
+      throw new Error(`Codex query failed: ${err.message}`);
+    }
+  }
+
+  getCapabilities(): ProviderCapabilities {
+    return CODEX_CAPABILITIES;
+  }
+
+  async *sendQuery(
+    prompt: string,
+    cwd: string,
+    resumeSessionId?: string,
+    requestOptions?: SendQueryOptions
+  ): AsyncGenerator<MessageChunk> {
+    const assistantConfig = requestOptions?.assistantConfig ?? {};
+    const codexConfig = parseCodexConfig(assistantConfig);
+
+    // 1. Initialize SDK and build thread options
+    const codex = await this.createCodexClient(codexConfig.codexBinaryPath, requestOptions?.env);
+    const threadOptions = buildThreadOptions(cwd, requestOptions?.model, assistantConfig);
+
+    if (requestOptions?.abortSignal?.aborted) {
+      throw new Error('Query aborted');
+    }
+
+    // 2. Create or resume thread
+    let sessionResumeFailed = false;
+    let thread;
+    if (resumeSessionId) {
+      getLog().debug({ sessionId: resumeSessionId }, 'resuming_thread');
+      try {
+        thread = codex.resumeThread(resumeSessionId, threadOptions);
+      } catch (error) {
+        getLog().error({ err: error, sessionId: resumeSessionId }, 'resume_thread_failed');
+        try {
+          thread = codex.startThread(threadOptions);
+        } catch (startError) {
+          const err = startError as Error;
+          if (isModelAccessError(err.message)) {
+            throw new Error(buildModelAccessMessage(requestOptions?.model));
+          }
+          throw new Error(`Codex query failed: ${err.message}`);
+        }
+        sessionResumeFailed = true;
+      }
+    } else {
+      getLog().debug({ cwd }, 'starting_new_thread');
+      try {
+        thread = codex.startThread(threadOptions);
+      } catch (error) {
+        const err = error as Error;
+        if (isModelAccessError(err.message)) {
+          throw new Error(buildModelAccessMessage(requestOptions?.model));
+        }
+        throw new Error(`Codex query failed: ${err.message}`);
+      }
+    }
+
+    if (sessionResumeFailed) {
+      yield {
+        type: 'system',
+        content: '⚠️ Could not resume previous session. Starting fresh conversation.',
+      };
+    }
+
+    // 3. Build turn options
+    const { turnOptions, hasOutputFormat } = buildTurnOptions(requestOptions);
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt <= MAX_SUBPROCESS_RETRIES; attempt++) {
+      if (requestOptions?.abortSignal?.aborted) {
+        throw new Error('Query aborted');
+      }
+
+      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(requestOptions?.model));
+          }
+          throw new Error(`Codex query failed: ${err.message}`);
+        }
+      }
+
+      try {
+        // 4. Run streamed turn
+        const result = await thread.runStreamed(prompt, turnOptions);
+
+        // 5. Stream normalized events (fresh state per attempt to avoid dedup leaks)
+        yield* streamCodexEvents(
+          result.events as AsyncIterable<Record<string, unknown>>,
+          hasOutputFormat,
+          thread.id,
+          requestOptions?.abortSignal
+        );
+        return;
+      } catch (error) {
+        const err = error as Error;
+
+        if (requestOptions?.abortSignal?.aborted) {
+          throw new Error('Query aborted');
+        }
+
+        const { enrichedError, errorClass, shouldRetry } = classifyAndEnrichCodexError(
+          err,
+          requestOptions?.model
+        );
+
+        getLog().error(
+          { err, errorClass, attempt, maxRetries: MAX_SUBPROCESS_RETRIES },
+          'query_error'
+        );
+
+        if (!shouldRetry || attempt >= MAX_SUBPROCESS_RETRIES) {
+          throw enrichedError;
+        }
+
+        const delayMs = this.retryBaseDelayMs * Math.pow(2, attempt);
+        getLog().info({ attempt, delayMs, errorClass }, 'retrying_query');
+        await new Promise(resolve => setTimeout(resolve, delayMs));
+        lastError = enrichedError;
+      }
+    }
+
+    throw lastError ?? new Error('Codex query failed after retries');
+  }
+
+  getType(): string {
+    return 'codex';
+  }
+}
diff --git a/packages/providers/src/community/pi/capabilities.ts b/packages/providers/src/community/pi/capabilities.ts
new file mode 100644
index 0000000000..335256d0d8
--- /dev/null
+++ b/packages/providers/src/community/pi/capabilities.ts
@@ -0,0 +1,33 @@
+import type { ProviderCapabilities } from '../../types';
+
+/**
+ * Pi capabilities — intentionally conservative. Declared flags must reflect
+ * wired-up behavior, not potential support. The dag-executor uses these to
+ * warn users when a workflow node specifies a feature the provider ignores.
+ *
+ * envInjection covers both auth-key passthrough (setRuntimeApiKey for mapped
+ * provider env vars) and bash tool subprocess env (BashSpawnHook merges the
+ * caller's env over Pi's inherited baseline), matching Claude/Codex semantics.
+ *
+ * structuredOutput is best-effort (not SDK-enforced like Claude/Codex): the
+ * provider appends a "JSON only" instruction + the schema to the prompt and
+ * the event bridge parses the final assistant transcript on agent_end.
+ * Reliable on instruction-following models (GPT-5, Claude, Gemini 2.x,
+ * recent Qwen Coder, DeepSeek V3); parse failures degrade via the
+ * dag-executor's existing dag.structured_output_missing path.
+ */
+export const PI_CAPABILITIES: ProviderCapabilities = {
+  sessionResume: true,
+  mcp: false,
+  hooks: false,
+  skills: true,
+  agents: false,
+  toolRestrictions: true,
+  structuredOutput: true,
+  envInjection: true,
+  costControl: false,
+  effortControl: true,
+  thinkingControl: true,
+  fallbackModel: false,
+  sandbox: false,
+};
diff --git a/packages/providers/src/community/pi/config.test.ts b/packages/providers/src/community/pi/config.test.ts
new file mode 100644
index 0000000000..ab6cde7516
--- /dev/null
+++ b/packages/providers/src/community/pi/config.test.ts
@@ -0,0 +1,163 @@
+import { describe, expect, test } from 'bun:test';
+
+import { parsePiConfig } from './config';
+
+describe('parsePiConfig', () => {
+  test('parses valid model string', () => {
+    expect(parsePiConfig({ model: 'google/gemini-2.5-pro' })).toEqual({
+      model: 'google/gemini-2.5-pro',
+    });
+  });
+
+  test('drops invalid model type silently', () => {
+    expect(parsePiConfig({ model: 123 })).toEqual({});
+  });
+
+  test('ignores unknown keys', () => {
+    expect(parsePiConfig({ futureField: 'x', model: 'google/gemini-2.5-pro' })).toEqual({
+      model: 'google/gemini-2.5-pro',
+    });
+  });
+
+  test('returns empty object for empty input', () => {
+    expect(parsePiConfig({})).toEqual({});
+  });
+
+  test('does not throw on malformed input', () => {
+    expect(() => parsePiConfig({ model: null })).not.toThrow();
+    expect(() => parsePiConfig({ model: [] })).not.toThrow();
+  });
+
+  test('parses enableExtensions: true', () => {
+    expect(parsePiConfig({ enableExtensions: true })).toEqual({
+      enableExtensions: true,
+    });
+  });
+
+  test('parses enableExtensions: false', () => {
+    expect(parsePiConfig({ enableExtensions: false })).toEqual({
+      enableExtensions: false,
+    });
+  });
+
+  test('drops non-boolean enableExtensions silently', () => {
+    expect(parsePiConfig({ enableExtensions: 'yes' })).toEqual({});
+    expect(parsePiConfig({ enableExtensions: 1 })).toEqual({});
+    expect(parsePiConfig({ enableExtensions: null })).toEqual({});
+  });
+
+  test('combines model and enableExtensions', () => {
+    expect(parsePiConfig({ model: 'google/gemini-2.5-pro', enableExtensions: true })).toEqual({
+      model: 'google/gemini-2.5-pro',
+      enableExtensions: true,
+    });
+  });
+
+  test('parses interactive: true', () => {
+    expect(parsePiConfig({ interactive: true })).toEqual({ interactive: true });
+  });
+
+  test('parses interactive: false', () => {
+    expect(parsePiConfig({ interactive: false })).toEqual({ interactive: false });
+  });
+
+  test('drops non-boolean interactive silently', () => {
+    expect(parsePiConfig({ interactive: 'yes' })).toEqual({});
+    expect(parsePiConfig({ interactive: 1 })).toEqual({});
+    expect(parsePiConfig({ interactive: null })).toEqual({});
+  });
+
+  test('combines all three fields', () => {
+    expect(
+      parsePiConfig({
+        model: 'google/gemini-2.5-pro',
+        enableExtensions: true,
+        interactive: true,
+      })
+    ).toEqual({
+      model: 'google/gemini-2.5-pro',
+      enableExtensions: true,
+      interactive: true,
+    });
+  });
+
+  test('parses extensionFlags with boolean and string values', () => {
+    expect(parsePiConfig({ extensionFlags: { plan: true, profile: 'Default' } })).toEqual({
+      extensionFlags: { plan: true, profile: 'Default' },
+    });
+  });
+
+  test('drops non-boolean/string extensionFlags values silently', () => {
+    expect(
+      parsePiConfig({
+        extensionFlags: { plan: true, bogus: 42, nested: { x: 1 }, nullish: null },
+      })
+    ).toEqual({ extensionFlags: { plan: true } });
+  });
+
+  test('drops extensionFlags when all entries are invalid', () => {
+    expect(parsePiConfig({ extensionFlags: { bogus: 42, nested: {} } })).toEqual({});
+  });
+
+  test('drops non-object extensionFlags silently', () => {
+    expect(parsePiConfig({ extensionFlags: 'plan=true' })).toEqual({});
+    expect(parsePiConfig({ extensionFlags: ['plan', 'true'] })).toEqual({});
+    expect(parsePiConfig({ extensionFlags: null })).toEqual({});
+  });
+
+  test('combines extensionFlags with other fields', () => {
+    expect(
+      parsePiConfig({
+        model: 'openai-codex/gpt-5.1-codex-mini',
+        enableExtensions: true,
+        interactive: true,
+        extensionFlags: { plan: true },
+      })
+    ).toEqual({
+      model: 'openai-codex/gpt-5.1-codex-mini',
+      enableExtensions: true,
+      interactive: true,
+      extensionFlags: { plan: true },
+    });
+  });
+
+  test('parses env with string values', () => {
+    expect(parsePiConfig({ env: { PLANNOTATOR_REMOTE: '1', FOO: 'bar' } })).toEqual({
+      env: { PLANNOTATOR_REMOTE: '1', FOO: 'bar' },
+    });
+  });
+
+  test('drops non-string env values silently', () => {
+    expect(
+      parsePiConfig({ env: { GOOD: 'yes', BOOL: true, NUM: 42, NESTED: { x: 1 }, NULLISH: null } })
+    ).toEqual({ env: { GOOD: 'yes' } });
+  });
+
+  test('drops env when all entries are invalid', () => {
+    expect(parsePiConfig({ env: { NUM: 42, NESTED: {} } })).toEqual({});
+  });
+
+  test('drops non-object env silently', () => {
+    expect(parsePiConfig({ env: 'PLANNOTATOR_REMOTE=1' })).toEqual({});
+    expect(parsePiConfig({ env: ['A=1'] })).toEqual({});
+    expect(parsePiConfig({ env: null })).toEqual({});
+  });
+
+  test('combines env with other fields', () => {
+    expect(
+      parsePiConfig({
+        model: 'openai-codex/gpt-5.4-mini',
+        enableExtensions: true,
+        interactive: true,
+        extensionFlags: { plan: true },
+        env: { PLANNOTATOR_REMOTE: '1' },
+      })
+    ).toEqual({
+      model: 'openai-codex/gpt-5.4-mini',
+      enableExtensions: true,
+      interactive: true,
+      extensionFlags: { plan: true },
+      env: { PLANNOTATOR_REMOTE: '1' },
+    });
+  });
+});
diff --git a/packages/providers/src/community/pi/config.ts b/packages/providers/src/community/pi/config.ts
new file mode 100644
index 0000000000..7d4c2b3fb5
--- /dev/null
+++ b/packages/providers/src/community/pi/config.ts
@@ -0,0 +1,55 @@
+import type { PiProviderDefaults } from '../../types';
+
+export type { PiProviderDefaults };
+
+/**
+ * Parse raw YAML-derived config into typed Pi defaults.
+ * Defensive: invalid fields are dropped silently (matches parseClaudeConfig
+ * and parseCodexConfig — never throws, so broken user config can't prevent
+ * provider registration or workflow discovery).
+ */
+export function parsePiConfig(raw: Record<string, unknown>): PiProviderDefaults {
+  const result: PiProviderDefaults = {};
+
+  if (typeof raw.model === 'string') {
+    result.model = raw.model;
+  }
+
+  if (typeof raw.enableExtensions === 'boolean') {
+    result.enableExtensions = raw.enableExtensions;
+  }
+
+  if (typeof raw.interactive === 'boolean') {
+    result.interactive = raw.interactive;
+  }
+
+  if (
+    raw.extensionFlags &&
+    typeof raw.extensionFlags === 'object' &&
+    !Array.isArray(raw.extensionFlags)
+  ) {
+    const flags: Record<string, boolean | string> = {};
+    for (const [key, value] of Object.entries(raw.extensionFlags as Record<string, unknown>)) {
+      if (typeof value === 'boolean' || typeof value === 'string') {
+        flags[key] = value;
+      }
+    }
+    if (Object.keys(flags).length > 0) {
+      result.extensionFlags = flags;
+    }
+  }
+
+  if (raw.env && typeof raw.env === 'object' && !Array.isArray(raw.env)) {
+    const env: Record<string, string> = {};
+    for (const [key, value] of Object.entries(raw.env as Record<string, unknown>)) {
+      if (typeof value === 'string') {
+        env[key] = value;
+      }
+    }
+    if (Object.keys(env).length > 0) {
+      result.env = env;
+    }
+  }
+
+  return result;
+}
diff --git a/packages/providers/src/community/pi/event-bridge.test.ts b/packages/providers/src/community/pi/event-bridge.test.ts
new file mode 100644
index 0000000000..cc176f7943
--- /dev/null
+++ b/packages/providers/src/community/pi/event-bridge.test.ts
@@ -0,0 +1,423 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+  AsyncQueue,
+  buildResultChunk,
+  mapPiEvent,
+  serializeToolResult,
+  tryParseStructuredOutput,
+  usageToTokens,
+} from './event-bridge';
+
+// ─── AsyncQueue ────────────────────────────────────────────────────────────
+
+describe('AsyncQueue', () => {
+  test('buffers pushes before consumer starts', async () => {
+    const q = new AsyncQueue<number>();
+    q.push(1);
+    q.push(2);
+    q.push(3);
+
+    const received: number[] = [];
+    const iter = q[Symbol.asyncIterator]();
+    for (let i = 0; i < 3; i++) {
+      const r = await iter.next();
+      if (!r.done) received.push(r.value);
+    }
+    expect(received).toEqual([1, 2, 3]);
+  });
+
+  test('resolves pending waiter when push arrives later', async () => {
+    const q = new AsyncQueue<string>();
+    const iter = q[Symbol.asyncIterator]();
+    const pending = iter.next();
+    queueMicrotask(() => q.push('hello'));
+    const r = await pending;
+    expect(r.done).toBe(false);
+    if (!r.done) expect(r.value).toBe('hello');
+  });
+
+  test('preserves FIFO order across push and waiter', async () => {
+    const q = new AsyncQueue<number>();
+    const iter = q[Symbol.asyncIterator]();
+    const p1 = iter.next();
+    q.push(10);
+    q.push(20);
+    const r1 = await p1;
+    const r2 = await iter.next();
+    if (!r1.done) expect(r1.value).toBe(10);
+    if (!r2.done) expect(r2.value).toBe(20);
+  });
+
+  test('second iterator call throws (single-consumer invariant)', () => {
+    const q = new AsyncQueue<number>();
+    // First call establishes the consumer; the iterator itself is created
+    // but iteration only starts on `.next()`. Pi's bridge uses this pattern.
+    q[Symbol.asyncIterator]();
+    expect(() => q[Symbol.asyncIterator]()).toThrow(/single-consumer/);
+  });
+
+  test('close() terminates pending waiter so consumer exits loop', async () => {
+    const q = new AsyncQueue<number>();
+    const iter = q[Symbol.asyncIterator]();
+    const pending = iter.next();
+    queueMicrotask(() => q.close());
+    const result = await pending;
+    expect(result.done).toBe(true);
+  });
+
+  test('close() drains buffered items before terminating', async () => {
+    const q = new AsyncQueue<number>();
+    q.push(1);
+    q.push(2);
+    q.close();
+    const received: number[] = [];
+    for await (const n of q) received.push(n);
+    expect(received).toEqual([1, 2]);
+  });
+
+  test('push after close is a no-op (does not leak past close)', async () => {
+    const q = new AsyncQueue<number>();
+    const iter = q[Symbol.asyncIterator]();
+    q.close();
+    q.push(42); // Must not resurrect the closed queue.
+    const r = await iter.next();
+    expect(r.done).toBe(true);
+  });
+
+  test('close() is idempotent', () => {
+    const q = new AsyncQueue<number>();
+    q.close();
+    expect(() => q.close()).not.toThrow();
+  });
+});
+
+// ─── serializeToolResult ───────────────────────────────────────────────────
+
+describe('serializeToolResult', () => {
+  test('returns strings verbatim', () => {
+    expect(serializeToolResult('hello')).toBe('hello');
+  });
+
+  test('JSON-serializes objects', () => {
+    expect(serializeToolResult({ a: 1, b: 'x' })).toBe('{"a":1,"b":"x"}');
+  });
+
+  test('JSON-serializes arrays', () => {
+    expect(serializeToolResult([1, 2, 3])).toBe('[1,2,3]');
+  });
+
+  test('falls back to String() for circular refs', () => {
+    const circular: { self?: unknown } = {};
+    circular.self = circular;
+    const result = serializeToolResult(circular);
+    expect(typeof result).toBe('string');
+    expect(result.length).toBeGreaterThan(0);
+  });
+});
+
+// ─── usageToTokens ─────────────────────────────────────────────────────────
+
+describe('usageToTokens', () => {
+  test('maps Pi Usage to Archon TokenUsage', () => {
+    const usage = {
+      input: 100,
+      output: 50,
+      cacheRead: 0,
+      cacheWrite: 0,
+      totalTokens: 150,
+      cost: { input: 0.001, output: 0.002, cacheRead: 0, cacheWrite: 0, total: 0.003 },
+    };
+    expect(usageToTokens(usage)).toEqual({
+      input: 100,
+      output: 50,
+      total: 150,
+      cost: 0.003,
+    });
+  });
+});
+
+// ─── buildResultChunk ──────────────────────────────────────────────────────
+
+describe('buildResultChunk', () => {
+  const usage = {
+    input: 10,
+    output: 5,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 15,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0.01 },
+  };
+
+  test('flags isError when no assistant message is present', () => {
+    // agent_end with no assistant message in the transcript is anomalous —
+    // must surface as an error so the orchestrator doesn't treat a broken
+    // session as a clean success.
+    const expected = {
+      type: 'result',
+      isError: true,
+      errorSubtype: 'missing_assistant_message',
+    };
+    expect(buildResultChunk([])).toEqual(expected);
+    expect(buildResultChunk([{ role: 'user', content: [] }])).toEqual(expected);
+  });
+
+  test('extracts usage from last assistant message', () => {
+    const chunk = buildResultChunk([
+      { role: 'user', content: [] },
+      { role: 'assistant', usage, stopReason: 'stop', content: [] },
+    ]);
+    expect(chunk.type).toBe('result');
+    if (chunk.type === 'result') {
+      expect(chunk.tokens).toEqual({ input: 10, output: 5, total: 15, cost: 0.01 });
+      expect(chunk.stopReason).toBe('stop');
+      expect(chunk.isError).toBeUndefined();
+      expect(chunk.cost).toBe(0.01);
+    }
+  });
+
+  test('flags isError for stopReason=error', () => {
+    const chunk = buildResultChunk([
+      { role: 'assistant', usage, stopReason: 'error', errorMessage: 'auth', content: [] },
+    ]);
+    if (chunk.type === 'result') {
+      expect(chunk.isError).toBe(true);
+      expect(chunk.errorSubtype).toBe('error');
+    }
+  });
+
+  test('flags isError for stopReason=aborted', () => {
+    const chunk = buildResultChunk([
+      { role: 'assistant', usage, stopReason: 'aborted', content: [] },
+    ]);
+    if (chunk.type === 'result') {
+      expect(chunk.isError).toBe(true);
+    }
+  });
+
+  test('prefers last assistant message when multiple present', () => {
+    const olderUsage = { ...usage, input: 1, totalTokens: 1 };
+    const chunk = buildResultChunk([
+      { role: 'assistant', usage: olderUsage, stopReason: 'stop', content: [] },
+      { role: 'user', content: [] },
+      { role: 'assistant', usage, stopReason: 'stop', content: [] },
+    ]);
+    if (chunk.type === 'result') {
+      expect(chunk.tokens?.input).toBe(10);
+    }
+  });
+});
+
+// ─── mapPiEvent ────────────────────────────────────────────────────────────
+
+describe('mapPiEvent', () => {
+  test('text_delta → assistant chunk', () => {
+    const chunks = mapPiEvent({
+      type: 'message_update',
+      message: { role: 'assistant' } as never,
+      assistantMessageEvent: {
+        type: 'text_delta',
+        contentIndex: 0,
+        delta: 'hi',
+        partial: { role: 'assistant' } as never,
+      },
+    });
+    expect(chunks).toEqual([{ type: 'assistant', content: 'hi' }]);
+  });
+
+  test('thinking_delta → thinking chunk', () => {
+    const chunks = mapPiEvent({
+      type: 'message_update',
+      message: { role: 'assistant' } as never,
+      assistantMessageEvent: {
+        type: 'thinking_delta',
+        contentIndex: 0,
+        delta: 'hmm',
+        partial: { role: 'assistant' } as never,
+      },
+    });
+    expect(chunks).toEqual([{ type: 'thinking', content: 'hmm' }]);
+  });
+
+  test('text_start/end and boundaries are skipped', () => {
+    const chunks = mapPiEvent({
+      type: 'message_update',
+      message: { role: 'assistant' } as never,
+      assistantMessageEvent: {
+        type: 'text_start',
+        contentIndex: 0,
+        partial: { role: 'assistant' } as never,
+      },
+    });
+    expect(chunks).toEqual([]);
+  });
+
+  test('tool_execution_start → tool chunk with toolCallId', () => {
+    const chunks = mapPiEvent({
+      type: 'tool_execution_start',
+      toolCallId: 'call-123',
+      toolName: 'read',
+      args: { path: '/foo' },
+    });
+    expect(chunks).toEqual([
+      {
+        type: 'tool',
+        toolName: 'read',
+        toolInput: { path: '/foo' },
+        toolCallId: 'call-123',
+      },
+    ]);
+  });
+
+  test('tool_execution_start coerces non-object args to empty record', () => {
+    const chunks = mapPiEvent({
+      type: 'tool_execution_start',
+      toolCallId: 'call-1',
+      toolName: 'bash',
+      args: 'just-a-string',
+    });
+    expect(chunks[0]).toMatchObject({ type: 'tool', toolInput: {} });
+  });
+
+  test('tool_execution_end → tool_result chunk with matching id', () => {
+    const chunks = mapPiEvent({
+      type: 'tool_execution_end',
+      toolCallId: 'call-123',
+      toolName: 'read',
+      result: 'file contents',
+      isError: false,
+    });
+    expect(chunks).toEqual([
+      {
+        type: 'tool_result',
+        toolName: 'read',
+        toolOutput: 'file contents',
+        toolCallId: 'call-123',
+      },
+    ]);
+  });
+
+  test('tool_execution_end with isError emits system warning first', () => {
+    const chunks = mapPiEvent({
+      type: 'tool_execution_end',
+      toolCallId: 'call-99',
+      toolName: 'bash',
+      result: 'exit 1',
+      isError: true,
+    });
+    expect(chunks).toHaveLength(2);
+    expect(chunks[0].type).toBe('system');
+    expect(chunks[1].type).toBe('tool_result');
+  });
+
+  test('auto_retry_start → system chunk', () => {
+    const chunks = mapPiEvent({
+      type: 'auto_retry_start',
+      attempt: 1,
+      maxAttempts: 3,
+      delayMs: 1000,
+      errorMessage: 'rate limit',
+    });
+    expect(chunks).toHaveLength(1);
+    expect(chunks[0].type).toBe('system');
+    if (chunks[0].type === 'system') {
+      expect(chunks[0].content).toContain('retry 1/3');
+      expect(chunks[0].content).toContain('rate limit');
+    }
+  });
+
+  test('agent_end → result chunk', () => {
+    const usage = {
+      input: 5,
+      output: 10,
+      cacheRead: 0,
+      cacheWrite: 0,
+      totalTokens: 15,
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0.001 },
+    };
+    const chunks = mapPiEvent({
+      type: 'agent_end',
+      messages: [{ role: 'assistant', usage, stopReason: 'stop', content: [] } as never],
+    });
+    expect(chunks).toHaveLength(1);
+    expect(chunks[0].type).toBe('result');
+  });
+
+  test('skipped event types yield no chunks', () => {
+    expect(mapPiEvent({ type: 'agent_start' })).toEqual([]);
+    expect(mapPiEvent({ type: 'turn_start' })).toEqual([]);
+    expect(
+      mapPiEvent({
+        type: 'turn_end',
+        message: { role: 'assistant' } as never,
+        toolResults: [],
+      })
+    ).toEqual([]);
+    expect(
+      mapPiEvent({
+        type: 'queue_update',
+        steering: [] as readonly string[],
+        followUp: [] as readonly string[],
+      })
+    ).toEqual([]);
+    expect(
+      mapPiEvent({
+        type: 'compaction_start',
+        reason: 'manual',
+      })
+    ).toEqual([]);
+  });
+});
+
+// ─── tryParseStructuredOutput ──────────────────────────────────────────────
+
+describe('tryParseStructuredOutput', () => {
+  test('parses clean JSON object', () => {
+    expect(tryParseStructuredOutput('{"name":"alpha","count":3}')).toEqual({
+      name: 'alpha',
+      count: 3,
+    });
+  });
+
+  test('parses JSON with surrounding whitespace', () => {
+    expect(tryParseStructuredOutput('  \n{"ok":true}\n  ')).toEqual({ ok: true });
+  });
+
+  test('strips ```json fences', () => {
+    const fenced = '```json\n{"area":"web","confidence":0.9}\n```';
+    expect(tryParseStructuredOutput(fenced)).toEqual({ area: 'web', confidence: 0.9 });
+  });
+
+  test('strips bare ``` fences', () => {
+    expect(tryParseStructuredOutput('```\n{"ok":1}\n```')).toEqual({ ok: 1 });
+  });
+
+  test('parses JSON arrays', () => {
+    expect(tryParseStructuredOutput('[1,2,3]')).toEqual([1, 2, 3]);
+  });
+
+  test('returns undefined on empty string', () => {
+    expect(tryParseStructuredOutput('')).toBeUndefined();
+    expect(tryParseStructuredOutput('   ')).toBeUndefined();
+  });
+
+  test('returns undefined when model wraps JSON in prose', () => {
+    // Realistic failure mode — model ignores "JSON only" instruction and adds
+    // explanatory text before/after. Caller degrades via the executor's
+    // missing-structured-output warning path.
+    const prose =
+      'Here is the JSON you requested:\n{"ok":true}\nLet me know if you need anything else.';
+    expect(tryParseStructuredOutput(prose)).toBeUndefined();
+  });
+
+  test('returns undefined on malformed JSON', () => {
+    expect(tryParseStructuredOutput('{not valid}')).toBeUndefined();
+    expect(tryParseStructuredOutput('{"unclosed":')).toBeUndefined();
+  });
+
+  test('preserves backticks inside JSON string values', () => {
+    // Fence stripper matches only at start/end; inner backticks must survive.
+    const withBackticks = '{"code":"run `npm test`"}';
+    expect(tryParseStructuredOutput(withBackticks)).toEqual({ code: 'run `npm test`' });
+  });
+});
diff --git a/packages/providers/src/community/pi/event-bridge.ts b/packages/providers/src/community/pi/event-bridge.ts
new file mode 100644
index 0000000000..aa5363ce86
--- /dev/null
+++ b/packages/providers/src/community/pi/event-bridge.ts
@@ -0,0 +1,387 @@
+import { createLogger } from '@archon/paths';
+import type { AgentSession, AgentSessionEvent } from '@mariozechner/pi-coding-agent';
+import type { AssistantMessage, Usage } from '@mariozechner/pi-ai';
+
+import type { MessageChunk, TokenUsage } from '../../types';
+
+let cachedLog: ReturnType<typeof createLogger> | undefined;
+function getLog(): ReturnType<typeof createLogger> {
+  if (!cachedLog) cachedLog = createLogger('provider.pi.event-bridge');
+  return cachedLog;
+}
+
+/**
+ * Single-producer / single-consumer async queue. Bridges Pi's callback-based
+ * `subscribe()` into an async generator.
+ *
+ * Design:
+ *  - producers call `push(item)` from any synchronous context
+ *  - the consumer awaits `for await (const item of queue)` ONCE
+ *  - sentinel items (in this bridge: `__done` / `__error`) are pushed by the
+ *    caller; the queue itself does not know about them
+ *
+ * Single-consumer is a hard invariant — a second iterator would race with
+ * the first over both the buffer and the waiters list, silently dropping
+ * items. The constructor enforces this: the first `Symbol.asyncIterator`
+ * call sets `consumed=true`; subsequent calls throw so the mistake surfaces
+ * loudly during development rather than being debugged after the fact.
+ */
+export class AsyncQueue<T> implements AsyncIterable<T> {
+  private readonly buffer: T[] = [];
+  private readonly waiters: ((result: IteratorResult<T>) => void)[] = [];
+  private consumed = false;
+  private closed = false;
+
+  push(item: T): void {
+    if (this.closed) return;
+    const waiter = this.waiters.shift();
+    if (waiter) waiter({ value: item, done: false });
+    else this.buffer.push(item);
+  }
+
+  /**
+   * Terminate iteration cleanly. Drains any pending waiters with
+   * `{ done: true }` so the consumer exits the `for await` loop instead of
+   * hanging forever when the producer's finally block fires before a new
+   * item arrives (e.g. consumer abort mid-iteration).
+   */
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    while (this.waiters.length > 0) {
+      const waiter = this.waiters.shift();
+      if (waiter) waiter({ value: undefined, done: true });
+    }
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<T> {
+    if (this.consumed) {
+      // Throw synchronously at the call site (not lazily on first .next())
+      // so the stack trace points at the offending second-consumer caller.
+      throw new Error(
+        'AsyncQueue: a single queue can only be iterated once (single-consumer invariant). Create a new queue for each consumer.'
+      );
+    }
+    this.consumed = true;
+    return this.iterate();
+  }
+
+  private async *iterate(): AsyncGenerator<T> {
+    while (true) {
+      const next = this.buffer.shift();
+      if (next !== undefined) {
+        yield next;
+        continue;
+      }
+      if (this.closed) return;
+      const result = await new Promise<IteratorResult<T>>(resolve => {
+        this.waiters.push(resolve);
+      });
+      if (result.done) return;
+      yield result.value;
+    }
+  }
+}
+
+/**
+ * Serialize a tool-execution `result` payload to a stable string.
+ * Pi tools return arbitrary JS — strings pass through, everything else is
+ * JSON-serialized (with String() fallback for non-serializable objects).
+ */
+export function serializeToolResult(result: unknown): string {
+  if (typeof result === 'string') return result;
+  try {
+    return JSON.stringify(result);
+  } catch {
+    return String(result);
+  }
+}
+
+/**
+ * Extract Archon TokenUsage from Pi's Usage struct.
+ * Pi reports input/output/cacheRead/cacheWrite + cost breakdown.
+ */
+export function usageToTokens(usage: Usage): TokenUsage {
+  return {
+    input: usage.input,
+    output: usage.output,
+    total: usage.totalTokens,
+    cost: usage.cost.total,
+  };
+}
+
+/**
+ * Narrow a single transcript message to AssistantMessage by inspecting
+ * `role` and `usage` structurally. Pi's AgentMessage union includes user,
+ * toolResult, and custom extension messages; we only care about assistant
+ * messages for result-chunk assembly.
+ */
+function isAssistantMessage(m: unknown): m is AssistantMessage {
+  if (m === null || typeof m !== 'object') return false;
+  const obj = m as { role?: unknown; usage?: unknown };
+  return obj.role === 'assistant' && typeof obj.usage === 'object' && obj.usage !== null;
+}
+
+/**
+ * Build the terminal `result` chunk from the final `agent_end` event. Pulls
+ * usage/stopReason/error from the last assistant message in the returned
+ * transcript. When the agent ended in error, surfaces it as `isError: true`.
+ */
+export function buildResultChunk(messages: readonly unknown[]): MessageChunk {
+  const last = [...messages].reverse().find(isAssistantMessage);
+  if (!last) {
+    // agent_end fired with no assistant message in the transcript. This
+    // shouldn't happen in healthy Pi runs — surface it as a loud error
+    // rather than a silent success so orchestrators don't treat a broken
+    // session as a clean completion.
+    getLog().warn('pi.event-bridge.result_missing_assistant_message');
+    return { type: 'result', isError: true, errorSubtype: 'missing_assistant_message' };
+  }
+
+  const tokens = usageToTokens(last.usage);
+  const isError = last.stopReason === 'error' || last.stopReason === 'aborted';
+
+  const chunk: MessageChunk = {
+    type: 'result',
+    tokens,
+    ...(tokens.cost !== undefined ? { cost: tokens.cost } : {}),
+    ...(last.stopReason ? { stopReason: last.stopReason } : {}),
+    ...(isError ? { isError: true, errorSubtype: last.stopReason } : {}),
+  };
+  return chunk;
+}
+
+/**
+ * Attempt to parse a Pi assistant transcript as the structured-output JSON
+ * requested via `outputFormat`. Handles two common model failure modes:
+ *  - trailing/leading whitespace (always stripped)
+ *  - markdown code fences (```json ... ``` or bare ``` ... ```) that models
+ *    emit despite the "no code fences" instruction in the prompt
+ *
+ * Returns the parsed value on success, `undefined` on any failure. Callers
+ * treat `undefined` as "structured output unavailable" and degrade via the
+ * dag-executor's existing missing-structured-output warning.
+ */
+export function tryParseStructuredOutput(text: string): unknown {
+  const trimmed = text.trim();
+  if (trimmed.length === 0) return undefined;
+  // Strip ```json / ``` fences if present. Match only at boundaries so we
+  // don't mangle JSON strings that legitimately contain backticks.
+  const cleaned = trimmed
+    .replace(/^```(?:json)?\s*\n?/i, '')
+    .replace(/\n?\s*```\s*$/, '')
+    .trim();
+  try {
+    return JSON.parse(cleaned);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Pure mapper from Pi's `AgentSessionEvent` → zero-or-more Archon `MessageChunk`s.
+ *
+ * Most Pi events map 1:1 or are skipped. Tool execution is split across
+ * `tool_execution_start` / `tool_execution_end`; the start yields `tool` with
+ * `toolCallId`, the end yields `tool_result` matched by the same id.
+ *
+ * Events deliberately skipped in v1:
+ *  - turn_start / turn_end, message_start / message_end (redundant with deltas)
+ *  - text_start / text_end / thinking_start / thinking_end (boundaries only)
+ *  - compaction_start / compaction_end (auto-compaction opaque to Archon)
+ *  - queue_update (single-prompt sessions only)
+ *  - auto_retry_end (retry_start communicates the retry sufficiently)
+ */
+export function mapPiEvent(event: AgentSessionEvent): MessageChunk[] {
+  switch (event.type) {
+    case 'message_update': {
+      const amEvent = event.assistantMessageEvent;
+      if (amEvent.type === 'text_delta') {
+        return [{ type: 'assistant', content: amEvent.delta }];
+      }
+      if (amEvent.type === 'thinking_delta') {
+        return [{ type: 'thinking', content: amEvent.delta }];
+      }
+      return [];
+    }
+    case 'tool_execution_start':
+      return [
+        {
+          type: 'tool',
+          toolName: event.toolName,
+          toolInput:
+            typeof event.args === 'object' && event.args !== null
+              ? (event.args as Record<string, unknown>)
+              : {},
+          toolCallId: event.toolCallId,
+        },
+      ];
+    case 'tool_execution_end': {
+      const chunks: MessageChunk[] = [];
+      if (event.isError) {
+        chunks.push({
+          type: 'system',
+          content: `⚠️ Tool ${event.toolName} failed`,
+        });
+      }
+      chunks.push({
+        type: 'tool_result',
+        toolName: event.toolName,
+        toolOutput: serializeToolResult(event.result),
+        toolCallId: event.toolCallId,
+      });
+      return chunks;
+    }
+    case 'agent_end':
+      return [buildResultChunk(event.messages)];
+    case 'auto_retry_start':
+      return [
+        {
+          type: 'system',
+          content: `⚠️ retry ${event.attempt}/${event.maxAttempts}: ${event.errorMessage}`,
+        },
+      ];
+    default:
+      return [];
+  }
+}
+
+/**
+ * Bridge a Pi `AgentSession` into Archon's `AsyncGenerator<MessageChunk>` contract.
+ *
+ * Behavior:
+ *  - subscribe before calling prompt, unsubscribe in finally
+ *  - yield mapped events in order
+ *  - complete on successful `session.prompt()` resolution
+ *  - throw on `session.prompt()` rejection or listener-raised errors
+ *  - forward `abortSignal` to `session.abort()` fire-and-forget
+ *  - always `dispose()` the session to avoid listener accumulation
+ */
+/**
+ * Internal queue payload for `bridgeSession`. Exported at module scope
+ * (not inside the generator) so unit tests can exercise each variant
+ * independently without reaching into the generator's closure.
+ */
+export type BridgeQueueItem =
+  | { kind: 'chunk'; chunk: MessageChunk }
+  | { kind: 'done' }
+  | { kind: 'error'; error: Error };
+
+/** Lets the UI stub push notifications into the session's chunk queue. */
+export interface BridgeNotifier {
+  setEmitter(fn: ((chunk: MessageChunk) => void) | undefined): void;
+}
+
+export async function* bridgeSession(
+  session: AgentSession,
+  prompt: string,
+  abortSignal?: AbortSignal,
+  jsonSchema?: Record<string, unknown>,
+  uiBridge?: BridgeNotifier
+): AsyncGenerator<MessageChunk> {
+  const queue = new AsyncQueue<BridgeQueueItem>();
+  uiBridge?.setEmitter(chunk => {
+    queue.push({ kind: 'chunk', chunk });
+  });
+  // Best-effort structured-output buffer. Only accumulates when the caller
+  // requested a JSON schema; otherwise stays empty and the terminal chunk
+  // passes through untouched.
+  const wantsStructured = jsonSchema !== undefined;
+  let assistantBuffer = '';
+
+  const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
+    try {
+      for (const chunk of mapPiEvent(event)) {
+        if (wantsStructured && chunk.type === 'assistant') {
+          assistantBuffer += chunk.content;
+        }
+        queue.push({ kind: 'chunk', chunk });
+      }
+    } catch (err) {
+      queue.push({ kind: 'error', error: err as Error });
+    }
+  });
+
+  const onAbort = (): void => {
+    void session.abort().catch((err: unknown) => {
+      // Abort is best-effort — failures are recoverable via the dispose()
+      // call in the `finally` below. But log at debug so a regression in
+      // Pi's abort path doesn't silently disappear.
+      getLog().debug({ err }, 'pi.event-bridge.abort_failed');
+    });
+  };
+  if (abortSignal) {
+    if (abortSignal.aborted) {
+      onAbort();
+    } else {
+      abortSignal.addEventListener('abort', onAbort, { once: true });
+    }
+  }
+
+  const promptPromise = session.prompt(prompt).then(
+    () => {
+      queue.push({ kind: 'done' });
+    },
+    (err: unknown) => {
+      queue.push({ kind: 'error', error: err as Error });
+    }
+  );
+
+  try {
+    for await (const item of queue) {
+      if (item.kind === 'done') return;
+      if (item.kind === 'error') throw item.error;
+      // Annotate the terminal result chunk with Pi's session UUID so Archon's
+      // orchestrator can pass it back as `resumeSessionId` on the next call.
+      // Pi's session.sessionId is always a UUID (even for in-memory); we emit
+      // it unconditionally and let the caller decide whether resume is
+      // meaningful (capability-gated at the registry level).
+      if (item.chunk.type === 'result') {
+        let terminal: MessageChunk = item.chunk;
+        if (session.sessionId) {
+          terminal = { ...terminal, sessionId: session.sessionId };
+        }
+        // Best-effort structured output: parse the accumulated assistant
+        // transcript as JSON and attach. On parse failure, leave it off —
+        // the dag-executor's existing dag.structured_output_missing path
+        // warns and downstream $node.output.field refs degrade to '' instead
+        // of propagating bogus data.
+        if (wantsStructured) {
+          const parsed = tryParseStructuredOutput(assistantBuffer);
+          if (parsed !== undefined) {
+            terminal = { ...terminal, structuredOutput: parsed };
+          } else {
+            getLog().warn(
+              { bufferLength: assistantBuffer.length },
+              'pi.event-bridge.structured_output_parse_failed'
+            );
+          }
+        }
+        yield terminal;
+      } else {
+        yield item.chunk;
+      }
+    }
+  } finally {
+    // Close the queue first so any producer push() still in flight becomes
+    // a no-op and pending iterate() waiters resolve — otherwise a consumer
+    // abort mid-iteration would leak this generator on the promise forever.
+    queue.close();
+    uiBridge?.setEmitter(undefined);
+    unsubscribe();
+    if (abortSignal) {
+      abortSignal.removeEventListener('abort', onAbort);
+    }
+    try {
+      session.dispose();
+    } catch (err: unknown) {
+      // Dispose is defensive — session may already be torn down. Log at
+      // debug so SDK regressions surface without polluting normal output.
+      getLog().debug({ err }, 'pi.event-bridge.dispose_failed');
+    }
+    // Ensure the prompt promise settles so callers see no dangling work.
+    await promptPromise.catch(() => {
+      /* errors already surfaced through the queue */
+    });
+  }
+}
diff --git a/packages/providers/src/community/pi/index.ts b/packages/providers/src/community/pi/index.ts
new file mode 100644
index 0000000000..5f06e9edaa
--- /dev/null
+++ b/packages/providers/src/community/pi/index.ts
@@ -0,0 +1,5 @@
+export { PI_CAPABILITIES } from './capabilities';
+export { parsePiConfig, type PiProviderDefaults } from './config';
+export { isPiModelCompatible, parsePiModelRef, type PiModelRef } from './model-ref';
+export { PiProvider } from './provider';
+export { registerPiProvider } from './registration';
diff --git a/packages/providers/src/community/pi/model-ref.test.ts b/packages/providers/src/community/pi/model-ref.test.ts
new file mode 100644
index 0000000000..d0001186e2
--- /dev/null
+++ b/packages/providers/src/community/pi/model-ref.test.ts
@@ -0,0 +1,68 @@
+import { describe, expect, test } from 'bun:test';
+
+import { isPiModelCompatible, parsePiModelRef } from './model-ref';
+
+describe('parsePiModelRef', () => {
+  test('parses simple provider/model', () => {
+    expect(parsePiModelRef('google/gemini-2.5-pro')).toEqual({
+      provider: 'google',
+      modelId: 'gemini-2.5-pro',
+    });
+  });
+
+  test('preserves nested slashes in modelId (OpenRouter style)', () => {
+    expect(parsePiModelRef('openrouter/qwen/qwen3-coder')).toEqual({
+      provider: 'openrouter',
+      modelId: 'qwen/qwen3-coder',
+    });
+  });
+
+  test('accepts hyphens and digits in provider slug', () => {
+    expect(parsePiModelRef('google-vertex/gemini-2.5-pro')).toEqual({
+      provider: 'google-vertex',
+      modelId: 'gemini-2.5-pro',
+    });
+  });
+
+  test('rejects empty provider', () => {
+    expect(parsePiModelRef('/model')).toBeUndefined();
+  });
+
+  test('rejects empty modelId', () => {
+    expect(parsePiModelRef('provider/')).toBeUndefined();
+  });
+
+  test('rejects missing slash', () => {
+    expect(parsePiModelRef('sonnet')).toBeUndefined();
+  });
+
+  test('rejects uppercase provider', () => {
+    expect(parsePiModelRef('Google/gemini')).toBeUndefined();
+  });
+
+  test('rejects provider starting with digit', () => {
+    expect(parsePiModelRef('3m/foo')).toBeUndefined();
+  });
+
+  test('rejects empty string', () => {
+    expect(parsePiModelRef('')).toBeUndefined();
+  });
+});
+
+describe('isPiModelCompatible', () => {
+  test('accepts valid provider/model refs', () => {
+    expect(isPiModelCompatible('google/gemini-2.5-pro')).toBe(true);
+    expect(isPiModelCompatible('anthropic/claude-opus-4-5')).toBe(true);
+    expect(isPiModelCompatible('openrouter/qwen/qwen3-coder')).toBe(true);
+  });
+
+  test('rejects Claude aliases', () => {
+    expect(isPiModelCompatible('sonnet')).toBe(false);
+    expect(isPiModelCompatible('opus')).toBe(false);
+    expect(isPiModelCompatible('haiku')).toBe(false);
+  });
+
+  test('rejects claude-prefixed models without provider', () => {
+    expect(isPiModelCompatible('claude-sonnet-4')).toBe(false);
+  });
+});
diff --git a/packages/providers/src/community/pi/model-ref.ts b/packages/providers/src/community/pi/model-ref.ts
new file mode 100644
index 0000000000..2d67c05fec
--- /dev/null
+++ b/packages/providers/src/community/pi/model-ref.ts
@@ -0,0 +1,42 @@
+/**
+ * Shape of a parsed Pi model reference.
+ * Pi's catalog is large and fast-moving, so Archon does syntactic validation
+ * only at registration time and defers catalog lookup to `getModel()` at
+ * query time.
+ */
+export interface PiModelRef {
+  /** Pi provider id, e.g. 'google', 'anthropic', 'openai', 'groq', 'openrouter'. */
+  provider: string;
+  /** Model id (may itself contain slashes, e.g. 'qwen/qwen3-coder' under openrouter). */
+  modelId: string;
+}
+
+/**
+ * Parse a Pi model ref. Splits on the FIRST '/' so that namespaced model ids
+ * under providers like OpenRouter work:
+ *   'openrouter/qwen/qwen3-coder' → { provider: 'openrouter', modelId: 'qwen/qwen3-coder' }
+ *
+ * Returns undefined for malformed refs so callers can surface clear errors.
+ */
+export function parsePiModelRef(raw: string): PiModelRef | undefined {
+  const idx = raw.indexOf('/');
+  if (idx <= 0 || idx === raw.length - 1) return undefined;
+
+  const provider = raw.slice(0, idx);
+  const modelId = raw.slice(idx + 1);
+
+  if (!/^[a-z][a-z0-9-]*$/.test(provider)) return undefined;
+  if (modelId.length === 0) return undefined;
+
+  return { provider, modelId };
+}
+
+/**
+ * Registry-level `isModelCompatible` check.
+ * Syntactic only — Pi's actual model catalog is validated at `sendQuery` time
+ * via `getModel(provider, modelId)`, which is more trustworthy than keeping
+ * an Archon-side allowlist in sync.
+ */
+export function isPiModelCompatible(model: string): boolean {
+  return parsePiModelRef(model) !== undefined;
+}
diff --git a/packages/providers/src/community/pi/options-translator.test.ts b/packages/providers/src/community/pi/options-translator.test.ts
new file mode 100644
index 0000000000..2a32a5368b
--- /dev/null
+++ b/packages/providers/src/community/pi/options-translator.test.ts
@@ -0,0 +1,271 @@
+import { describe, expect, test, beforeAll, afterAll } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import type { NodeConfig } from '../../types';
+import { resolvePiSkills, resolvePiThinkingLevel, resolvePiTools } from './options-translator';
+
+// ─── resolvePiThinkingLevel ─────────────────────────────────────────────
+
+describe('resolvePiThinkingLevel', () => {
+  test('returns undefined when no config provided', () => {
+    expect(resolvePiThinkingLevel(undefined)).toEqual({ level: undefined });
+  });
+
+  test('returns undefined for empty config', () => {
+    expect(resolvePiThinkingLevel({})).toEqual({ level: undefined });
+  });
+
+  test('maps valid thinking string directly', () => {
+    expect(resolvePiThinkingLevel({ thinking: 'high' })).toEqual({ level: 'high' });
+    expect(resolvePiThinkingLevel({ thinking: 'xhigh' })).toEqual({ level: 'xhigh' });
+    expect(resolvePiThinkingLevel({ thinking: 'minimal' })).toEqual({ level: 'minimal' });
+  });
+
+  test('maps valid effort string directly', () => {
+    expect(resolvePiThinkingLevel({ effort: 'medium' })).toEqual({ level: 'medium' });
+    expect(resolvePiThinkingLevel({ effort: 'low' })).toEqual({ level: 'low' });
+  });
+
+  test('thinking takes precedence when both set', () => {
+    expect(resolvePiThinkingLevel({ thinking: 'high', effort: 'low' })).toEqual({ level: 'high' });
+  });
+
+  test("'off' on either field returns undefined", () => {
+    expect(resolvePiThinkingLevel({ thinking: 'off' })).toEqual({ level: undefined });
+    expect(resolvePiThinkingLevel({ effort: 'off' })).toEqual({ level: undefined });
+  });
+
+  test("'max' (Archon EffortLevel enum) translates to Pi 'xhigh'", () => {
+    expect(resolvePiThinkingLevel({ effort: 'max' })).toEqual({ level: 'xhigh' });
+    expect(resolvePiThinkingLevel({ thinking: 'max' })).toEqual({ level: 'xhigh' });
+  });
+
+  test('warns on Claude-shape object thinking config', () => {
+    const result = resolvePiThinkingLevel({
+      thinking: { type: 'enabled', budget_tokens: 4000 },
+    } as NodeConfig);
+    expect(result.level).toBeUndefined();
+    expect(result.warning).toContain('object form is Claude-specific');
+  });
+
+  test('warns on unknown string thinking value', () => {
+    const result = resolvePiThinkingLevel({ thinking: 'ultra' });
+    expect(result.level).toBeUndefined();
+    expect(result.warning).toContain("unknown thinking level 'ultra'");
+  });
+
+  test('warns on unknown string effort value', () => {
+    const result = resolvePiThinkingLevel({ effort: 'crushing' });
+    expect(result.level).toBeUndefined();
+    expect(result.warning).toContain("unknown thinking level 'crushing'");
+  });
+
+  test('no warning when both fields are simply absent', () => {
+    expect(resolvePiThinkingLevel({})).toEqual({ level: undefined });
+    expect(resolvePiThinkingLevel({ thinking: undefined, effort: undefined })).toEqual({
+      level: undefined,
+    });
+  });
+});
+
+// ─── resolvePiTools ─────────────────────────────────────────────────────
+
+describe('resolvePiTools', () => {
+  const cwd = '/tmp/test-cwd';
+
+  test('returns undefined tools when neither allowed_tools nor denied_tools set', () => {
+    expect(resolvePiTools(cwd, undefined)).toEqual({ tools: undefined, unknownTools: [] });
+    expect(resolvePiTools(cwd, {})).toEqual({ tools: undefined, unknownTools: [] });
+  });
+
+  test('allowed_tools: [] returns empty tools array (no-tools idiom)', () => {
+    const result = resolvePiTools(cwd, { allowed_tools: [] });
+    expect(result.tools).toEqual([]);
+    expect(result.unknownTools).toEqual([]);
+  });
+
+  test('allowed_tools: [read, bash] returns exactly those two', () => {
+    const result = resolvePiTools(cwd, { allowed_tools: ['read', 'bash'] });
+    expect(result.tools).toHaveLength(2);
+    expect(result.unknownTools).toEqual([]);
+  });
+
+  test('case-insensitive tool names', () => {
+    const result = resolvePiTools(cwd, { allowed_tools: ['Read', 'BASH', 'Edit'] });
+    expect(result.tools).toHaveLength(3);
+    expect(result.unknownTools).toEqual([]);
+  });
+
+  test('unknown tool names (Claude-specific) collected in unknownTools', () => {
+    const result = resolvePiTools(cwd, { allowed_tools: ['read', 'WebFetch', 'bash'] });
+    expect(result.tools).toHaveLength(2);
+    expect(result.unknownTools).toEqual(['WebFetch']);
+  });
+
+  test('denied_tools subtracts from allowed_tools', () => {
+    const result = resolvePiTools(cwd, {
+      allowed_tools: ['read', 'bash', 'edit'],
+      denied_tools: ['bash'],
+    });
+    expect(result.tools).toHaveLength(2);
+    expect(result.unknownTools).toEqual([]);
+  });
+
+  test('denied_tools alone starts from full built-in set', () => {
+    const result = resolvePiTools(cwd, { denied_tools: ['bash', 'write'] });
+    // Pi has 7 built-in tools, 2 denied → 5 remain
+    expect(result.tools).toHaveLength(5);
+    expect(result.unknownTools).toEqual([]);
+  });
+
+  test('dedupes duplicate tool names', () => {
+    const result = resolvePiTools(cwd, { allowed_tools: ['read', 'read', 'Read'] });
+    expect(result.tools).toHaveLength(1);
+  });
+
+  test('allowed and denied both with unknowns flags each', () => {
+    const result = resolvePiTools(cwd, {
+      allowed_tools: ['read', 'UnknownA'],
+      denied_tools: ['UnknownB'],
+    });
+    expect(result.tools).toHaveLength(1); // only 'read'
+    expect(result.unknownTools).toEqual(['UnknownA', 'UnknownB']);
+  });
+
+  test('no allow/deny with non-empty env → returns Pi default 4-tool set with env-aware bash', () => {
+    const result = resolvePiTools(cwd, undefined, { DATABASE_URL: 'postgres://x' });
+    expect(result.tools).toHaveLength(4); // read/bash/edit/write
+    expect(result.unknownTools).toEqual([]);
+  });
+
+  test('no allow/deny with empty env → still returns undefined (Pi defaults)', () => {
+    expect(resolvePiTools(cwd, undefined, {})).toEqual({ tools: undefined, unknownTools: [] });
+    expect(resolvePiTools(cwd, {}, {})).toEqual({ tools: undefined, unknownTools: [] });
+  });
+
+  test('env passthrough does not affect unknown tool reporting', () => {
+    const result = resolvePiTools(cwd, { allowed_tools: ['read', 'WebFetch'] }, { FOO: 'bar' });
+    expect(result.tools).toHaveLength(1);
+    expect(result.unknownTools).toEqual(['WebFetch']);
+  });
+});
+
+// ─── resolvePiSkills ───────────────────────────────────────────────────────
+//
+// Uses a temp directory to stage synthetic skill layouts — avoids relying on
+// whatever the developer has in ~/.claude/skills/ or ~/.agents/skills/.
+
+describe('resolvePiSkills', () => {
+  let tmpRoot: string;
+  let cwd: string;
+  let originalHome: string | undefined;
+
+  beforeAll(() => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'archon-pi-skills-'));
+    cwd = join(tmpRoot, 'project');
+    const home = join(tmpRoot, 'home');
+
+    // Redirect os.homedir() by setting HOME before imports use it. Our
+    // resolver calls homedir() at function-call time (not module load),
+    // so setting HOME mid-test is safe.
+    originalHome = process.env.HOME;
+    process.env.HOME = home;
+
+    // Staging:
+    //   <cwd>/.agents/skills/alpha/SKILL.md
+    //   <cwd>/.claude/skills/bravo/SKILL.md
+    //   <home>/.agents/skills/charlie/SKILL.md
+    //   <home>/.claude/skills/delta/SKILL.md
+    //   <home>/.claude/skills/shared/SKILL.md  (also in <cwd>/.claude/skills/shared/)
+    //   <cwd>/.claude/skills/shared/SKILL.md
+    const stage = [
+      [join(cwd, '.agents', 'skills', 'alpha'), 'SKILL.md'],
+      [join(cwd, '.claude', 'skills', 'bravo'), 'SKILL.md'],
+      [join(home, '.agents', 'skills', 'charlie'), 'SKILL.md'],
+      [join(home, '.claude', 'skills', 'delta'), 'SKILL.md'],
+      [join(cwd, '.claude', 'skills', 'shared'), 'SKILL.md'],
+      [join(home, '.claude', 'skills', 'shared'), 'SKILL.md'],
+      // A dir without SKILL.md — must not resolve
+      [join(cwd, '.claude', 'skills', 'no-skill-md'), '.keep'],
+    ];
+    for (const [dir, file] of stage) {
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(join(dir, file), '# skill content\n');
+    }
+  });
+
+  afterAll(() => {
+    if (originalHome === undefined) {
+      delete process.env.HOME;
+    } else {
+      process.env.HOME = originalHome;
+    }
+    rmSync(tmpRoot, { recursive: true, force: true });
+  });
+
+  test('returns empty for undefined/empty input', () => {
+    expect(resolvePiSkills(cwd, undefined)).toEqual({ paths: [], missing: [] });
+    expect(resolvePiSkills(cwd, [])).toEqual({ paths: [], missing: [] });
+  });
+
+  test('resolves project-local .agents/skills', () => {
+    const result = resolvePiSkills(cwd, ['alpha']);
+    expect(result.missing).toEqual([]);
+    expect(result.paths).toHaveLength(1);
+    expect(result.paths[0]).toContain(join('.agents', 'skills', 'alpha'));
+  });
+
+  test('resolves project-local .claude/skills', () => {
+    const result = resolvePiSkills(cwd, ['bravo']);
+    expect(result.missing).toEqual([]);
+    expect(result.paths[0]).toContain(join('.claude', 'skills', 'bravo'));
+  });
+
+  test('resolves user-global .agents/skills', () => {
+    const result = resolvePiSkills(cwd, ['charlie']);
+    expect(result.missing).toEqual([]);
+    expect(result.paths[0]).toContain(join('.agents', 'skills', 'charlie'));
+  });
+
+  test('resolves user-global .claude/skills', () => {
+    const result = resolvePiSkills(cwd, ['delta']);
+    expect(result.missing).toEqual([]);
+    expect(result.paths[0]).toContain(join('.claude', 'skills', 'delta'));
+  });
+
+  test('project-local wins over user-global when both present', () => {
+    const result = resolvePiSkills(cwd, ['shared']);
+    expect(result.missing).toEqual([]);
+    expect(result.paths[0]).toContain(join(cwd, '.claude', 'skills', 'shared'));
+  });
+
+  test('dir without SKILL.md does not resolve', () => {
+    const result = resolvePiSkills(cwd, ['no-skill-md']);
+    expect(result.paths).toEqual([]);
+    expect(result.missing).toEqual(['no-skill-md']);
+  });
+
+  test('unknown skill name is reported in missing', () => {
+    const result = resolvePiSkills(cwd, ['does-not-exist']);
+    expect(result.paths).toEqual([]);
+    expect(result.missing).toEqual(['does-not-exist']);
+  });
+
+  test('mixed resolvable + unresolvable returns both', () => {
+    const result = resolvePiSkills(cwd, ['alpha', 'does-not-exist', 'bravo']);
+    expect(result.paths).toHaveLength(2);
+    expect(result.missing).toEqual(['does-not-exist']);
+  });
+
+  test('dedupes duplicate names', () => {
+    const result = resolvePiSkills(cwd, ['alpha', 'alpha']);
+    expect(result.paths).toHaveLength(1);
+  });
+
+  test('ignores empty-string and non-string names', () => {
+    const result = resolvePiSkills(cwd, ['', 'alpha']);
+    expect(result.paths).toHaveLength(1);
+  });
+});
diff --git a/packages/providers/src/community/pi/options-translator.ts b/packages/providers/src/community/pi/options-translator.ts
new file mode 100644
index 0000000000..d970985f4e
--- /dev/null
+++ b/packages/providers/src/community/pi/options-translator.ts
@@ -0,0 +1,327 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  codingTools,
+  createBashTool,
+  createEditTool,
+  createFindTool,
+  createGrepTool,
+  createLsTool,
+  createReadTool,
+  createWriteTool,
+  type BashSpawnContext,
+  type BashSpawnHook,
+} from '@mariozechner/pi-coding-agent';
+import type { ThinkingLevel } from '@mariozechner/pi-ai';
+
+/**
+ * Pi's exported `Tool` type is structurally `AgentTool<TSchema>` and isn't
+ * re-exported at the package root. Deriving it from the `codingTools` aggregate
+ * (which IS re-exported and typed as `Tool[]`) gives us a namespace-free alias
+ * that satisfies TS's portable-type requirement.
+ */
+type PiTool = (typeof codingTools)[number];
+
+import type { NodeConfig } from '../../types';
+
+// ─── Thinking level ────────────────────────────────────────────────────────
+
+/**
+ * Pi's ThinkingLevel = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'.
+ * Archon's common surface includes 'off' (from Codex's modelReasoningEffort)
+ * and 'max' (from Claude's EffortLevel enum). Map into Pi's vocabulary:
+ *  - 'off'    → undefined (no explicit thinkingLevel; Pi's implicit off)
+ *  - 'max'    → 'xhigh'  (Archon's EffortLevel doesn't have xhigh)
+ *  - others pass through if they're already Pi-native
+ *
+ * See packages/workflows/src/schemas/dag-node.ts#effortLevelSchema for
+ * the Archon schema enum (`low | medium | high | max`). Workflow YAML can
+ * only carry Archon-enum values; Pi-native `minimal` / `xhigh` are accepted
+ * here for programmatic callers (orchestrator, tests) that bypass the
+ * schema validator.
+ */
+const PI_NATIVE_LEVELS: ReadonlySet<ThinkingLevel> = new Set<ThinkingLevel>([
+  'minimal',
+  'low',
+  'medium',
+  'high',
+  'xhigh',
+]);
+
+function normalizeToThinkingLevel(v: unknown): ThinkingLevel | undefined {
+  if (typeof v !== 'string') return undefined;
+  if (v === 'max') return 'xhigh';
+  if (PI_NATIVE_LEVELS.has(v as ThinkingLevel)) return v as ThinkingLevel;
+  return undefined;
+}
+
+export interface ResolvedThinkingLevel {
+  /** ThinkingLevel to pass to Pi, or undefined for Pi's default (implicit off) */
+  level: ThinkingLevel | undefined;
+  /** Human-readable warning to surface as a system chunk, if the input shape wasn't usable */
+  warning?: string;
+}
+
+/**
+ * Resolve Archon's `effort` / `thinking` node fields to Pi's `ThinkingLevel`.
+ *
+ * Precedence: `thinking` > `effort` (when both are set and valid).
+ * 'off' on either → `level: undefined` (Pi runs without explicit thinking).
+ * Claude-shape `thinking: { type: 'enabled', budget_tokens: N }` object form →
+ * warning, not applied.
+ */
+export function resolvePiThinkingLevel(nodeConfig?: NodeConfig): ResolvedThinkingLevel {
+  if (!nodeConfig) return { level: undefined };
+
+  const { thinking, effort } = nodeConfig;
+
+  // Explicit off on either field disables thinking entirely.
+  if (thinking === 'off' || effort === 'off') return { level: undefined };
+
+  // thinking takes precedence over effort when both are valid strings.
+  const thinkingLevel = normalizeToThinkingLevel(thinking);
+  if (thinkingLevel) return { level: thinkingLevel };
+
+  const effortLevel = normalizeToThinkingLevel(effort);
+  if (effortLevel) return { level: effortLevel };
+
+  // Claude uses a structured `{ type: 'enabled', budget_tokens: N }` shape —
+  // Pi doesn't understand it. Surface the mismatch so users can fix their YAML.
+  if (thinking !== undefined && thinking !== null && typeof thinking === 'object') {
+    return {
+      level: undefined,
+      warning:
+        'Pi ignored `thinking` (object form is Claude-specific). Use `effort: low|medium|high|max` in YAML (max → xhigh on Pi).',
+    };
+  }
+
+  // String that isn't a known level (e.g. 'ultra') — warn so users fix it.
+  if (typeof thinking === 'string' || typeof effort === 'string') {
+    const offender = typeof thinking === 'string' ? thinking : effort;
+    return {
+      level: undefined,
+      warning: `Pi ignored unknown thinking level '${String(offender)}'. Valid: minimal, low, medium, high, xhigh, max, off.`,
+    };
+  }
+
+  return { level: undefined };
+}
+
+// ─── Tool restrictions ─────────────────────────────────────────────────────
+
+/** Pi's seven built-in coding tools. */
+const PI_TOOL_NAMES = ['read', 'bash', 'edit', 'write', 'grep', 'find', 'ls'] as const;
+export type PiToolName = (typeof PI_TOOL_NAMES)[number];
+
+/**
+ * Build a Pi `spawnHook` that merges managed env vars into every bash
+ * subprocess. Matches Claude/Codex precedence: caller-provided env keys
+ * override Pi's inherited baseline. Returns undefined when `env` is empty
+ * so bash spawns without an unnecessary hook allocation.
+ */
+function buildBashSpawnHook(env: Record<string, string> | undefined): BashSpawnHook | undefined {
+  if (!env || Object.keys(env).length === 0) return undefined;
+  return (context: BashSpawnContext): BashSpawnContext => ({
+    ...context,
+    env: { ...context.env, ...env },
+  });
+}
+
+/** Map a normalized (lowercase) Pi tool name to its Pi-internal factory. */
+function buildPiTool(name: PiToolName, cwd: string, spawnHook: BashSpawnHook | undefined): PiTool {
+  switch (name) {
+    case 'read':
+      return createReadTool(cwd);
+    case 'bash':
+      return spawnHook ? createBashTool(cwd, { spawnHook }) : createBashTool(cwd);
+    case 'edit':
+      return createEditTool(cwd);
+    case 'write':
+      return createWriteTool(cwd);
+    case 'grep':
+      return createGrepTool(cwd);
+    case 'find':
+      return createFindTool(cwd);
+    case 'ls':
+      return createLsTool(cwd);
+  }
+}
+
+export interface ResolvedTools {
+  /**
+   * The tools array to pass to Pi, or `undefined` to leave Pi's default
+   * (read/bash/edit/write) in place. An empty array means "no tools —
+   * LLM-only response" which is a valid explicit setting.
+   */
+  tools: PiTool[] | undefined;
+  /** Unknown tool names in allowed_tools / denied_tools (e.g. Claude-specific like WebFetch). */
+  unknownTools: string[];
+}
+
+/** Pi's default coding-tool set (mirrors `codingTools` export: read/bash/edit/write). */
+const PI_DEFAULT_TOOL_NAMES = [
+  'read',
+  'bash',
+  'edit',
+  'write',
+] as const satisfies readonly PiToolName[];
+
+/**
+ * Filter Pi's built-in tool set against Archon's `allowed_tools` /
+ * `denied_tools` node config, with managed env injected into any bash tool.
+ *
+ * Semantics:
+ *   - neither allow/deny set, no env → return undefined (Pi's default tools)
+ *   - neither allow/deny set, env present → return Pi's default 4 tools with
+ *     an env-aware bash, so codebase env vars reach bash subprocesses
+ *   - allowed_tools: [] → return [] (explicit no-tools; valid Archon idiom)
+ *   - allowed_tools: [X, Y] → only X, Y (normalized to lowercase)
+ *   - denied_tools subtracts from allowed_tools (or full set if allowed_tools absent)
+ *   - tool names not in Pi's built-in set are silently dropped but reported
+ *     via `unknownTools` so the caller can surface a warning.
+ *
+ * The `env` parameter is the caller's `requestOptions.env` merged with any
+ * relevant defaults; when non-empty, it is injected into every bash spawn via
+ * a `BashSpawnHook`, matching Claude's `options.env` and Codex's constructor
+ * `env` behavior so codebase-scoped env vars reach tool subprocesses.
+ */
+export function resolvePiTools(
+  cwd: string,
+  nodeConfig?: NodeConfig,
+  env?: Record<string, string>
+): ResolvedTools {
+  const allowed = nodeConfig?.allowed_tools;
+  const denied = nodeConfig?.denied_tools;
+  const spawnHook = buildBashSpawnHook(env);
+
+  if (allowed === undefined && denied === undefined) {
+    // No restrictions. Match Pi's default tool set unless env injection forces
+    // a custom bash tool (Pi's default bashTool is pre-constructed with no
+    // spawnHook and there's no way to retrofit env onto it).
+    if (!spawnHook) return { tools: undefined, unknownTools: [] };
+    return {
+      tools: PI_DEFAULT_TOOL_NAMES.map(n => buildPiTool(n, cwd, spawnHook)),
+      unknownTools: [],
+    };
+  }
+
+  const knownSet = new Set<PiToolName>(PI_TOOL_NAMES);
+  const unknownTools: string[] = [];
+
+  function classify(name: string): PiToolName | undefined {
+    const lower = name.toLowerCase();
+    if (knownSet.has(lower as PiToolName)) return lower as PiToolName;
+    unknownTools.push(name);
+    return undefined;
+  }
+
+  let selected: PiToolName[];
+  if (allowed !== undefined) {
+    selected = allowed.map(classify).filter((n): n is PiToolName => n !== undefined);
+  } else {
+    selected = [...PI_TOOL_NAMES];
+  }
+
+  if (denied !== undefined) {
+    const deniedSet = new Set<PiToolName>();
+    for (const raw of denied) {
+      const norm = classify(raw);
+      if (norm) deniedSet.add(norm);
+    }
+    selected = selected.filter(n => !deniedSet.has(n));
+  }
+
+  // Dedupe by name (handles allowed_tools: ['read', 'read'])
+  const seen = new Set<PiToolName>();
+  const unique = selected.filter(n => {
+    if (seen.has(n)) return false;
+    seen.add(n);
+    return true;
+  });
+
+  return {
+    tools: unique.map(n => buildPiTool(n, cwd, spawnHook)),
+    unknownTools,
+  };
+}
+
+// ─── Skills ────────────────────────────────────────────────────────────────
+
+export interface ResolvedSkills {
+  /** Absolute paths to resolved skill directories. Each contains a SKILL.md. */
+  paths: string[];
+  /** Skill names that couldn't be resolved in any search location. */
+  missing: string[];
+}
+
+/**
+ * Pi's skill-discovery search order for a named skill. Mirrors the locations
+ * Claude's SDK and Pi's default resource loader both respect, so Archon
+ * workflows that already work under Claude find the same skills under Pi.
+ *
+ * Order (first match wins per name):
+ *   1. `<cwd>/.agents/skills/<name>/`     — project-local, agentskills.io standard
+ *   2. `<cwd>/.claude/skills/<name>/`     — project-local, Claude convention
+ *   3. `~/.agents/skills/<name>/`         — user-global, agentskills.io standard
+ *   4. `~/.claude/skills/<name>/`         — user-global, Claude convention
+ *
+ * Ancestor traversal above cwd is deliberately not done in v2 — matches the
+ * Pi provider's cwd-bound scope and avoids ambiguity about which repo's
+ * skills win when Archon runs out of a subdirectory.
+ */
+function skillSearchRoots(cwd: string): string[] {
+  // Prefer `HOME` env var when set — Bun's os.homedir() bypasses `HOME` and
+  // reads from the system uid lookup, which is correct in production but
+  // makes tests using staged temp homes impossible. The fallback to
+  // homedir() keeps behavior identical in non-test contexts.
+  const home = process.env.HOME ?? homedir();
+  return [
+    join(cwd, '.agents', 'skills'),
+    join(cwd, '.claude', 'skills'),
+    join(home, '.agents', 'skills'),
+    join(home, '.claude', 'skills'),
+  ];
+}
+
+/**
+ * Resolve Archon's name-based `skills:` nodeConfig references to absolute
+ * directory paths Pi's resource loader can consume via `additionalSkillPaths`.
+ *
+ * Each named skill is expected to be a directory containing a `SKILL.md`
+ * file — the agentskills.io standard layout.
+ */
+export function resolvePiSkills(cwd: string, skillNames: string[] | undefined): ResolvedSkills {
+  if (!skillNames || skillNames.length === 0) {
+    return { paths: [], missing: [] };
+  }
+
+  const roots = skillSearchRoots(cwd);
+  const paths: string[] = [];
+  const missing: string[] = [];
+  const seen = new Set<string>();
+
+  for (const rawName of skillNames) {
+    if (typeof rawName !== 'string' || rawName.length === 0) continue;
+    if (seen.has(rawName)) continue;
+    seen.add(rawName);
+
+    let found: string | undefined;
+    for (const root of roots) {
+      const candidate = join(root, rawName);
+      if (existsSync(join(candidate, 'SKILL.md'))) {
+        found = candidate;
+        break;
+      }
+    }
+
+    if (found) {
+      paths.push(found);
+    } else {
+      missing.push(rawName);
+    }
+  }
+
+  return { paths, missing };
+}
diff --git a/packages/providers/src/community/pi/provider.test.ts b/packages/providers/src/community/pi/provider.test.ts
new file mode 100644
index 0000000000..17e6de417d
--- /dev/null
+++ b/packages/providers/src/community/pi/provider.test.ts
@@ -0,0 +1,1427 @@
+import { beforeEach, describe, expect, mock, test } from 'bun:test';
+import type { AgentSessionEvent } from '@mariozechner/pi-coding-agent';
+
+import { createMockLogger } from '../../test/mocks/logger';
+
+// ─── Mock @archon/paths logger so provider instantiation is quiet ───────
+
+const mockLogger = createMockLogger();
+mock.module('@archon/paths', () => ({
+  createLogger: mock(() => mockLogger),
+}));
+
+// ─── Mock Pi SDK surface ────────────────────────────────────────────────
+//
+// Pi's `createAgentSession` returns a session whose `subscribe(listener)`
+// stores a callback, and whose `prompt(text)` drives events through that
+// callback before resolving. We reproduce that shape with a mutable
+// `listener` variable plus `mockPrompt` that replays a scripted event
+// sequence synchronously.
+
+// Typed against Pi's actual event union so tests fail at compile time when
+// Pi renames a field (e.g. `assistantMessageEvent` → `amEvent`) rather than
+// silently passing while production drifts. Using `as AgentSessionEvent` at
+// the call site covers the cases where we construct partial message objects.
+type FakeEvent = AgentSessionEvent;
+let capturedListener: ((event: FakeEvent) => void) | undefined;
+
+const scriptedEvents: FakeEvent[] = [];
+const mockPrompt = mock(async () => {
+  for (const ev of scriptedEvents) capturedListener?.(ev);
+});
+const mockAbort = mock(async () => undefined);
+const mockDispose = mock(() => undefined);
+const mockSubscribe = mock((listener: (event: FakeEvent) => void) => {
+  capturedListener = listener;
+  return () => {
+    capturedListener = undefined;
+  };
+});
+
+const mockBindExtensions = mock(async (_bindings: unknown) => undefined);
+const mockSetFlagValue = mock((_name: string, _value: boolean | string) => undefined);
+const mockExtensionRunner = {
+  setFlagValue: mockSetFlagValue,
+};
+const mockSession = {
+  subscribe: mockSubscribe,
+  prompt: mockPrompt,
+  abort: mockAbort,
+  dispose: mockDispose,
+  bindExtensions: mockBindExtensions,
+  extensionRunner: mockExtensionRunner,
+  isStreaming: false,
+  sessionId: 'mock-session-uuid',
+};
+
+const mockCreateAgentSession = mock(async () => ({
+  session: mockSession,
+  extensionsResult: { extensions: [], errors: [], runtime: {} },
+  modelFallbackMessage: undefined,
+}));
+
+// Per-test state backing the AuthStorage mock. `fileCreds` emulates what's
+// in ~/.pi/agent/auth.json; `runtimeOverrides` emulates env-var passthrough
+// via setRuntimeApiKey. Tests mutate these via helpers.
+let fileCreds: Record<string, { type: 'api_key' | 'oauth'; key?: string }> = {};
+let runtimeOverrides: Record<string, string> = {};
+
+const mockSetRuntimeApiKey = mock((providerId: string, key: string) => {
+  runtimeOverrides[providerId] = key;
+});
+const mockGetApiKey = mock(async (providerId: string): Promise<string | undefined> => {
+  // Mirror Pi's resolution: runtime → file api_key → file oauth → env var
+  if (runtimeOverrides[providerId]) return runtimeOverrides[providerId];
+  const cred = fileCreds[providerId];
+  if (cred?.type === 'api_key') return cred.key;
+  if (cred?.type === 'oauth') return 'oauth-access-token-stub';
+  return undefined;
+});
+const mockAuthCreate = mock(() => ({
+  setRuntimeApiKey: mockSetRuntimeApiKey,
+  getApiKey: mockGetApiKey,
+}));
+const mockModelRegistryInMemory = mock(() => ({}));
+
+// SessionManager mocks. Each returns a tagged session-manager stub so tests
+// can assert whether resume resolved to an existing session or fell through
+// to a fresh one.
+const mockSessionCreate = mock((_cwd: string) => ({ __smKind: 'created' }));
+const mockSessionOpen = mock((_path: string) => ({ __smKind: 'opened' }));
+const mockSessionList = mock(
+  async (_cwd: string) => [] as { id: string; path: string; cwd: string }[]
+);
+
+const mockSettingsManagerInMemory = mock(() => ({}));
+const mockResourceLoaderReload = mock(async () => undefined);
+// Return-style constructor: bun's mock() wraps the function such that the
+// `this`-binding doesn't reliably propagate to `new` call sites. Returning a
+// plain object from the constructor sidesteps this — ES semantics use the
+// returned object when a constructor explicitly returns one.
+const MockDefaultResourceLoader = mock((_opts: unknown) => ({
+  reload: mockResourceLoaderReload,
+}));
+
+// Tool factory mocks — each returns an opaque object tagged with the tool
+// name so assertions can verify which tools the provider selected.
+const mockCreateReadTool = mock((_cwd: string) => ({ __piTool: 'read' }));
+const mockCreateBashTool = mock((_cwd: string, _options?: unknown) => ({ __piTool: 'bash' }));
+const mockCreateEditTool = mock((_cwd: string) => ({ __piTool: 'edit' }));
+const mockCreateWriteTool = mock((_cwd: string) => ({ __piTool: 'write' }));
+const mockCreateGrepTool = mock((_cwd: string) => ({ __piTool: 'grep' }));
+const mockCreateFindTool = mock((_cwd: string) => ({ __piTool: 'find' }));
+const mockCreateLsTool = mock((_cwd: string) => ({ __piTool: 'ls' }));
+
+mock.module('@mariozechner/pi-coding-agent', () => ({
+  createAgentSession: mockCreateAgentSession,
+  AuthStorage: { create: mockAuthCreate },
+  ModelRegistry: { inMemory: mockModelRegistryInMemory },
+  SessionManager: {
+    create: mockSessionCreate,
+    open: mockSessionOpen,
+    list: mockSessionList,
+  },
+  SettingsManager: { inMemory: mockSettingsManagerInMemory },
+  DefaultResourceLoader: MockDefaultResourceLoader,
+  createReadTool: mockCreateReadTool,
+  createBashTool: mockCreateBashTool,
+  createEditTool: mockCreateEditTool,
+  createWriteTool: mockCreateWriteTool,
+  createGrepTool: mockCreateGrepTool,
+  createFindTool: mockCreateFindTool,
+  createLsTool: mockCreateLsTool,
+}));
+
+// getModel is imported from pi-ai. Return a fake model for known refs and
+// undefined for unknown refs so the provider's not-found branch is testable.
+const mockGetModel = mock((provider: string, modelId: string) => {
+  if (provider === 'nonexistent') return undefined;
+  return { id: modelId, provider, name: `${provider}/${modelId}` };
+});
+mock.module('@mariozechner/pi-ai', () => ({
+  getModel: mockGetModel,
+}));
+
+// Import AFTER mocks are set — module resolution freezes the mocks.
+import { PiProvider } from './provider';
+import { PI_CAPABILITIES } from './capabilities';
+
+// ─── Helpers ────────────────────────────────────────────────────────────
+
+async function consume(
+  generator: AsyncGenerator<unknown>
+): Promise<{ chunks: unknown[]; error?: Error }> {
+  const chunks: unknown[] = [];
+  try {
+    for await (const chunk of generator) chunks.push(chunk);
+    return { chunks };
+  } catch (err) {
+    return { chunks, error: err as Error };
+  }
+}
+
+function resetScript(events: FakeEvent[]): void {
+  scriptedEvents.length = 0;
+  scriptedEvents.push(...events);
+}
+
+// ─── Test suite ─────────────────────────────────────────────────────────
+
+describe('PiProvider', () => {
+  beforeEach(() => {
+    mockPrompt.mockClear();
+    mockAbort.mockClear();
+    mockDispose.mockClear();
+    mockSubscribe.mockClear();
+    mockBindExtensions.mockClear();
+    mockSetFlagValue.mockClear();
+    mockResourceLoaderReload.mockClear();
+    mockCreateAgentSession.mockClear();
+    mockGetModel.mockClear();
+    mockAuthCreate.mockClear();
+    mockSetRuntimeApiKey.mockClear();
+    mockGetApiKey.mockClear();
+    MockDefaultResourceLoader.mockClear();
+    mockCreateReadTool.mockClear();
+    mockCreateBashTool.mockClear();
+    mockCreateEditTool.mockClear();
+    mockCreateWriteTool.mockClear();
+    mockCreateGrepTool.mockClear();
+    mockCreateFindTool.mockClear();
+    mockCreateLsTool.mockClear();
+    mockSessionCreate.mockClear();
+    mockSessionOpen.mockClear();
+    mockSessionList.mockClear();
+    mockSessionList.mockImplementation(async () => []);
+    capturedListener = undefined;
+    scriptedEvents.length = 0;
+    fileCreds = {};
+    runtimeOverrides = {};
+    delete process.env.GEMINI_API_KEY;
+    delete process.env.ANTHROPIC_API_KEY;
+  });
+
+  test('getType returns "pi"', () => {
+    expect(new PiProvider().getType()).toBe('pi');
+  });
+
+  test('getCapabilities matches PI_CAPABILITIES constant', () => {
+    expect(new PiProvider().getCapabilities()).toEqual(PI_CAPABILITIES);
+  });
+
+  test('throws when no model is configured', async () => {
+    const { error } = await consume(new PiProvider().sendQuery('hi', '/tmp'));
+    expect(error?.message).toContain('Pi provider requires a model');
+  });
+
+  test('throws when model ref is malformed', async () => {
+    const { error } = await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, { model: 'sonnet' })
+    );
+    expect(error?.message).toContain('Invalid Pi model ref');
+  });
+
+  test('throws when Pi provider id is unknown AND no creds available', async () => {
+    // No env var, no auth.json entry → fail-fast with hint about env-var table
+    const { error } = await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'unknownprovider/some-model',
+      })
+    );
+    expect(error?.message).toContain("no credentials for provider 'unknownprovider'");
+    expect(error?.message).toContain("not in the Archon adapter's env-var table");
+  });
+
+  test('throws when env var missing AND auth.json has no entry', async () => {
+    // GEMINI_API_KEY not set (beforeEach deletes it), fileCreds empty
+    const { error } = await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+      })
+    );
+    expect(error?.message).toContain('no credentials for provider');
+    expect(error?.message).toContain('GEMINI_API_KEY');
+    expect(error?.message).toContain('/login');
+  });
+
+  test('uses OAuth credential from ~/.pi/agent/auth.json when no env var set', async () => {
+    // Simulate user running `pi /login` → auth.json has OAuth entry
+    fileCreds.anthropic = { type: 'oauth' };
+    resetScript([
+      {
+        type: 'agent_end',
+        messages: [
+          {
+            role: 'assistant',
+            usage: {
+              input: 1,
+              output: 1,
+              cacheRead: 0,
+              cacheWrite: 0,
+              totalTokens: 2,
+              cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+            },
+            stopReason: 'stop',
+            content: [],
+          },
+        ],
+      },
+    ]);
+
+    const { error } = await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'anthropic/claude-haiku-4-5',
+      })
+    );
+    expect(error).toBeUndefined();
+    // Runtime override NOT set — no env var present — so Pi's getApiKey
+    // resolves through the OAuth code path.
+    expect(mockSetRuntimeApiKey).not.toHaveBeenCalled();
+    expect(mockGetApiKey).toHaveBeenCalledWith('anthropic');
+  });
+
+  test('throws when getModel returns undefined', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    // 'nonexistent' is handled in mockGetModel to return undefined, but
+    // the adapter rejects unknown providers before getModel. To exercise
+    // the not-found branch, use a known provider but unknown modelId by
+    // temporarily swapping mockGetModel to always return undefined.
+    mockGetModel.mockImplementationOnce(() => undefined);
+    const { error } = await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/unknown-model-id',
+      })
+    );
+    expect(error?.message).toContain('Pi model not found');
+  });
+
+  test('request env (codebase env vars) overrides process.env via setRuntimeApiKey', async () => {
+    process.env.GEMINI_API_KEY = 'from-process-env';
+    resetScript([
+      {
+        type: 'agent_end',
+        messages: [
+          {
+            role: 'assistant',
+            usage: {
+              input: 1,
+              output: 1,
+              cacheRead: 0,
+              cacheWrite: 0,
+              totalTokens: 2,
+              cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+            },
+            stopReason: 'stop',
+            content: [],
+          },
+        ],
+      },
+    ]);
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        env: { GEMINI_API_KEY: 'from-request-env' },
+      })
+    );
+
+    expect(mockSetRuntimeApiKey).toHaveBeenCalledWith('google', 'from-request-env');
+    // Runtime override is priority #1 in Pi's resolution chain, so getApiKey
+    // returns 'from-request-env' (via our mock's runtimeOverrides map).
+    expect(runtimeOverrides.google).toBe('from-request-env');
+  });
+
+  test('env var overrides auth.json api_key entry', async () => {
+    // Both present: env var wins (mirrors Pi's resolution priority)
+    fileCreds.anthropic = { type: 'api_key', key: 'from-auth-json' };
+    process.env.ANTHROPIC_API_KEY = 'from-env';
+    resetScript([
+      {
+        type: 'agent_end',
+        messages: [
+          {
+            role: 'assistant',
+            usage: {
+              input: 1,
+              output: 1,
+              cacheRead: 0,
+              cacheWrite: 0,
+              totalTokens: 2,
+              cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+            },
+            stopReason: 'stop',
+            content: [],
+          },
+        ],
+      },
+    ]);
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'anthropic/claude-haiku-4-5',
+      })
+    );
+    expect(mockSetRuntimeApiKey).toHaveBeenCalledWith('anthropic', 'from-env');
+  });
+
+  test('yields assistant chunks from text_delta events', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript([
+      {
+        type: 'message_update',
+        message: { role: 'assistant' },
+        assistantMessageEvent: { type: 'text_delta', contentIndex: 0, delta: 'Hello', partial: {} },
+      },
+      {
+        type: 'message_update',
+        message: { role: 'assistant' },
+        assistantMessageEvent: {
+          type: 'text_delta',
+          contentIndex: 0,
+          delta: ' world',
+          partial: {},
+        },
+      },
+      {
+        type: 'agent_end',
+        messages: [
+          {
+            role: 'assistant',
+            usage: {
+              input: 1,
+              output: 2,
+              cacheRead: 0,
+              cacheWrite: 0,
+              totalTokens: 3,
+              cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+            },
+            stopReason: 'stop',
+            content: [],
+          },
+        ],
+      },
+    ]);
+
+    const { chunks, error } = await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+      })
+    );
+    expect(error).toBeUndefined();
+    expect(chunks).toEqual([
+      { type: 'assistant', content: 'Hello' },
+      { type: 'assistant', content: ' world' },
+      expect.objectContaining({ type: 'result', stopReason: 'stop' }),
+    ]);
+  });
+
+  test('yields tool + tool_result chunks for tool_execution events', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript([
+      {
+        type: 'tool_execution_start',
+        toolCallId: 'call-1',
+        toolName: 'read',
+        args: { path: '/x' },
+      },
+      {
+        type: 'tool_execution_end',
+        toolCallId: 'call-1',
+        toolName: 'read',
+        result: 'contents',
+        isError: false,
+      },
+      {
+        type: 'agent_end',
+        messages: [
+          {
+            role: 'assistant',
+            usage: {
+              input: 1,
+              output: 1,
+              cacheRead: 0,
+              cacheWrite: 0,
+              totalTokens: 2,
+              cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+            },
+            stopReason: 'stop',
+            content: [],
+          },
+        ],
+      },
+    ]);
+
+    const { chunks } = await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+      })
+    );
+    expect(chunks.length).toBe(3);
+    expect(chunks[0]).toMatchObject({
+      type: 'tool',
+      toolName: 'read',
+      toolInput: { path: '/x' },
+      toolCallId: 'call-1',
+    });
+    expect(chunks[1]).toMatchObject({
+      type: 'tool_result',
+      toolName: 'read',
+      toolOutput: 'contents',
+      toolCallId: 'call-1',
+    });
+    expect(chunks[2]).toMatchObject({ type: 'result' });
+  });
+
+  test('resumeSessionId not found → fresh session + system warning', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    mockSessionList.mockImplementationOnce(async () => []);
+    resetScript([
+      {
+        type: 'agent_end',
+        messages: [
+          {
+            role: 'assistant',
+            usage: {
+              input: 1,
+              output: 1,
+              cacheRead: 0,
+              cacheWrite: 0,
+              totalTokens: 2,
+              cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+            },
+            stopReason: 'stop',
+            content: [],
+          },
+        ],
+      },
+    ]);
+
+    const { chunks, error } = await consume(
+      new PiProvider().sendQuery('hi', '/tmp', 'nonexistent-id', {
+        model: 'google/gemini-2.5-pro',
+      })
+    );
+    expect(error).toBeUndefined();
+    // Resume attempted: list() called; no match → create() called (fresh session)
+    expect(mockSessionList).toHaveBeenCalled();
+    expect(mockSessionCreate).toHaveBeenCalledWith('/tmp');
+    expect(mockSessionOpen).not.toHaveBeenCalled();
+    // Resume failure surfaces as a system warning
+    const systemChunks = chunks.filter(
+      (c): c is { type: 'system'; content: string } =>
+        typeof c === 'object' && c !== null && (c as { type?: string }).type === 'system'
+    );
+    expect(systemChunks.some(c => c.content.includes('Could not resume'))).toBe(true);
+  });
+
+  test('resumeSessionId matches existing session → open by path, no warning', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    mockSessionList.mockImplementationOnce(async () => [
+      { id: 'existing-id', path: '/sessions/existing-id.jsonl', cwd: '/tmp' },
+    ]);
+    resetScript([
+      {
+        type: 'agent_end',
+        messages: [
+          {
+            role: 'assistant',
+            usage: {
+              input: 1,
+              output: 1,
+              cacheRead: 0,
+              cacheWrite: 0,
+              totalTokens: 2,
+              cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+            },
+            stopReason: 'stop',
+            content: [],
+          },
+        ],
+      },
+    ]);
+
+    const { chunks, error } = await consume(
+      new PiProvider().sendQuery('hi', '/tmp', 'existing-id', {
+        model: 'google/gemini-2.5-pro',
+      })
+    );
+    expect(error).toBeUndefined();
+    expect(mockSessionOpen).toHaveBeenCalledWith('/sessions/existing-id.jsonl');
+    expect(mockSessionCreate).not.toHaveBeenCalled();
+    // No resume_failed warning
+    const systemChunks = chunks.filter(
+      (c): c is { type: 'system'; content: string } =>
+        typeof c === 'object' && c !== null && (c as { type?: string }).type === 'system'
+    );
+    expect(systemChunks.some(c => c.content.includes('Could not resume'))).toBe(false);
+  });
+
+  test('result chunk carries Pi sessionId (for Archon to store and reuse)', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    const { chunks } = await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+      })
+    );
+
+    const resultChunk = chunks.find(
+      (c): c is { type: 'result'; sessionId?: string } =>
+        typeof c === 'object' && c !== null && (c as { type?: string }).type === 'result'
+    );
+    expect(resultChunk).toBeDefined();
+    expect(resultChunk?.sessionId).toBe('mock-session-uuid');
+  });
+
+  test('disposes session after completion', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript([
+      {
+        type: 'agent_end',
+        messages: [
+          {
+            role: 'assistant',
+            usage: {
+              input: 1,
+              output: 1,
+              cacheRead: 0,
+              cacheWrite: 0,
+              totalTokens: 2,
+              cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+            },
+            stopReason: 'stop',
+            content: [],
+          },
+        ],
+      },
+    ]);
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+      })
+    );
+    expect(mockDispose).toHaveBeenCalledTimes(1);
+  });
+
+  // ─── v2 wiring: thinking, tools, systemPrompt ─────────────────────────
+
+  function scriptedAgentEnd(): FakeEvent[] {
+    return [
+      {
+        type: 'agent_end',
+        messages: [
+          {
+            role: 'assistant',
+            usage: {
+              input: 1,
+              output: 1,
+              cacheRead: 0,
+              cacheWrite: 0,
+              totalTokens: 2,
+              cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+            },
+            stopReason: 'stop',
+            content: [],
+          },
+        ],
+      },
+    ];
+  }
+
+  test('nodeConfig.thinking=high passes thinkingLevel to createAgentSession', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        nodeConfig: { thinking: 'high' },
+      })
+    );
+
+    const [callArgs] = mockCreateAgentSession.mock.calls[0] as [Record<string, unknown>];
+    expect(callArgs.thinkingLevel).toBe('high');
+  });
+
+  test('nodeConfig.effort=medium passes thinkingLevel when thinking absent', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        nodeConfig: { effort: 'medium' },
+      })
+    );
+
+    const [callArgs] = mockCreateAgentSession.mock.calls[0] as [Record<string, unknown>];
+    expect(callArgs.thinkingLevel).toBe('medium');
+  });
+
+  test('nodeConfig.thinking=off omits thinkingLevel (Pi runs without explicit thinking)', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        nodeConfig: { thinking: 'off' },
+      })
+    );
+
+    const [callArgs] = mockCreateAgentSession.mock.calls[0] as [Record<string, unknown>];
+    expect(callArgs.thinkingLevel).toBeUndefined();
+  });
+
+  test('Claude-shape object thinking yields system warning and is not applied', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    const { chunks } = await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        nodeConfig: { thinking: { type: 'enabled', budget_tokens: 4000 } },
+      })
+    );
+
+    const systemChunks = chunks.filter(
+      (c): c is { type: 'system'; content: string } =>
+        typeof c === 'object' && c !== null && (c as { type?: string }).type === 'system'
+    );
+    expect(systemChunks.some(c => c.content.includes('object form is Claude-specific'))).toBe(true);
+
+    const [callArgs] = mockCreateAgentSession.mock.calls[0] as [Record<string, unknown>];
+    expect(callArgs.thinkingLevel).toBeUndefined();
+  });
+
+  test('nodeConfig.allowed_tools filters Pi built-in tools', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        nodeConfig: { allowed_tools: ['read', 'grep'] },
+      })
+    );
+
+    const [callArgs] = mockCreateAgentSession.mock.calls[0] as [Record<string, unknown>];
+    expect(Array.isArray(callArgs.tools)).toBe(true);
+    const tools = callArgs.tools as Array<{ __piTool: string }>;
+    expect(tools.map(t => t.__piTool).sort()).toEqual(['grep', 'read']);
+  });
+
+  test('nodeConfig.allowed_tools: [] disables all Pi tools (LLM-only)', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        nodeConfig: { allowed_tools: [] },
+      })
+    );
+
+    const [callArgs] = mockCreateAgentSession.mock.calls[0] as [Record<string, unknown>];
+    expect(callArgs.tools).toEqual([]);
+  });
+
+  test('unknown tool names yield system warning', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    const { chunks } = await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        nodeConfig: { allowed_tools: ['read', 'WebFetch'] },
+      })
+    );
+
+    const systemChunks = chunks.filter(
+      (c): c is { type: 'system'; content: string } =>
+        typeof c === 'object' && c !== null && (c as { type?: string }).type === 'system'
+    );
+    expect(systemChunks.some(c => c.content.includes('WebFetch'))).toBe(true);
+  });
+
+  test('denied_tools alone starts from full built-in set', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        nodeConfig: { denied_tools: ['bash', 'write'] },
+      })
+    );
+
+    const [callArgs] = mockCreateAgentSession.mock.calls[0] as [Record<string, unknown>];
+    const tools = callArgs.tools as Array<{ __piTool: string }>;
+    // Pi has 7 built-ins, 2 denied → 5 remain
+    expect(tools).toHaveLength(5);
+    expect(tools.find(t => t.__piTool === 'bash')).toBeUndefined();
+    expect(tools.find(t => t.__piTool === 'write')).toBeUndefined();
+  });
+
+  test('no allowed_tools / denied_tools leaves Pi default tools in place', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+      })
+    );
+
+    const [callArgs] = mockCreateAgentSession.mock.calls[0] as [Record<string, unknown>];
+    // tools key should be absent — Pi uses its default codingTools
+    expect('tools' in callArgs).toBe(false);
+  });
+
+  test('requestOptions.env with no tool restrictions overrides Pi defaults with env-aware bash', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        env: { DATABASE_URL: 'postgres://managed' },
+      })
+    );
+
+    const [callArgs] = mockCreateAgentSession.mock.calls[0] as [Record<string, unknown>];
+    // Env present → we override Pi's built-in codingTools so bash sees the env.
+    const tools = callArgs.tools as Array<{ __piTool: string }>;
+    expect(Array.isArray(tools)).toBe(true);
+    expect(tools.map(t => t.__piTool).sort()).toEqual(['bash', 'edit', 'read', 'write']);
+
+    const bashCall = mockCreateBashTool.mock.calls.find(call => call[1] !== undefined);
+    expect(bashCall).toBeDefined();
+    const bashOptions = bashCall![1] as { spawnHook: (c: unknown) => unknown };
+    expect(typeof bashOptions.spawnHook).toBe('function');
+
+    // The spawnHook must merge caller env OVER Pi's inherited baseline, matching
+    // Claude's { ...subprocessEnv, ...requestOptions.env } and Codex's buildCodexEnv.
+    const merged = bashOptions.spawnHook({
+      command: 'echo',
+      cwd: '/tmp',
+      env: { PATH: '/usr/bin', DATABASE_URL: 'postgres://stale' },
+    }) as { env: Record<string, string> };
+    expect(merged.env.PATH).toBe('/usr/bin');
+    expect(merged.env.DATABASE_URL).toBe('postgres://managed');
+  });
+
+  test('requestOptions.env threads through to bash tool when allowed_tools includes bash', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        nodeConfig: { allowed_tools: ['read', 'bash'] },
+        env: { STRIPE_KEY: 'sk_test_abc' },
+      })
+    );
+
+    const bashCall = mockCreateBashTool.mock.calls.find(call => call[1] !== undefined);
+    expect(bashCall).toBeDefined();
+    const bashOptions = bashCall![1] as { spawnHook: (c: unknown) => unknown };
+    const merged = bashOptions.spawnHook({
+      command: 'echo',
+      cwd: '/tmp',
+      env: { PATH: '/usr/bin' },
+    }) as { env: Record<string, string> };
+    expect(merged.env.STRIPE_KEY).toBe('sk_test_abc');
+    expect(merged.env.PATH).toBe('/usr/bin');
+  });
+
+  test('empty requestOptions.env does NOT construct a spawnHook', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        env: {},
+      })
+    );
+
+    // Every createBashTool call in this test path is either (cwd) or (cwd, undefined).
+    for (const call of mockCreateBashTool.mock.calls) {
+      expect(call[1]).toBeUndefined();
+    }
+  });
+
+  test('requestOptions.systemPrompt threads through to DefaultResourceLoader', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        systemPrompt: 'You are a careful investigator.',
+      })
+    );
+
+    // DefaultResourceLoader constructor received systemPrompt
+    const loaderArgs = MockDefaultResourceLoader.mock.calls[0]?.[0] as
+      | Record<string, unknown>
+      | undefined;
+    expect(loaderArgs?.systemPrompt).toBe('You are a careful investigator.');
+    expect(loaderArgs?.noExtensions).toBe(false);
+    expect(loaderArgs?.noContextFiles).toBe(true);
+  });
+
+  test('nodeConfig.systemPrompt used when requestOptions.systemPrompt absent', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        nodeConfig: { systemPrompt: 'node-level prompt' },
+      })
+    );
+
+    const loaderArgs = MockDefaultResourceLoader.mock.calls[0]?.[0] as
+      | Record<string, unknown>
+      | undefined;
+    expect(loaderArgs?.systemPrompt).toBe('node-level prompt');
+  });
+
+  test('requestOptions.systemPrompt wins over nodeConfig.systemPrompt', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        systemPrompt: 'request-level wins',
+        nodeConfig: { systemPrompt: 'node-level' },
+      })
+    );
+
+    const loaderArgs = MockDefaultResourceLoader.mock.calls[0]?.[0] as
+      | Record<string, unknown>
+      | undefined;
+    expect(loaderArgs?.systemPrompt).toBe('request-level wins');
+  });
+
+  test('capabilities reflect v2 wiring', () => {
+    const caps = new PiProvider().getCapabilities();
+    expect(caps.thinkingControl).toBe(true);
+    expect(caps.effortControl).toBe(true);
+    expect(caps.toolRestrictions).toBe(true);
+    expect(caps.skills).toBe(true);
+    expect(caps.sessionResume).toBe(true);
+    expect(caps.envInjection).toBe(true);
+    // Best-effort structured output via prompt engineering (not SDK-enforced).
+    expect(caps.structuredOutput).toBe(true);
+    // Still false:
+    expect(caps.mcp).toBe(false);
+    expect(caps.hooks).toBe(false);
+  });
+
+  test('extensions are enabled by default (noExtensions: false)', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+      })
+    );
+
+    const loaderArgs = MockDefaultResourceLoader.mock.calls[0]?.[0] as
+      | Record<string, unknown>
+      | undefined;
+    // Extensions (community packages and user-authored) are a core reason
+    // users run Pi; off-by-default silently broke users who installed or
+    // authored one and expected it to fire.
+    expect(loaderArgs?.noExtensions).toBe(false);
+    // Skills/prompts/themes/context stay suppressed — only extensions flip on.
+    expect(loaderArgs?.noSkills).toBe(true);
+    expect(loaderArgs?.noPromptTemplates).toBe(true);
+    expect(loaderArgs?.noThemes).toBe(true);
+    expect(loaderArgs?.noContextFiles).toBe(true);
+  });
+
+  test('assistantConfig.enableExtensions: true flips noExtensions to false', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        assistantConfig: { enableExtensions: true },
+      })
+    );
+
+    const loaderArgs = MockDefaultResourceLoader.mock.calls[0]?.[0] as
+      | Record<string, unknown>
+      | undefined;
+    expect(loaderArgs?.noExtensions).toBe(false);
+    // Skills/prompts/themes/context still suppressed — only extensions opt-in.
+    expect(loaderArgs?.noSkills).toBe(true);
+    expect(loaderArgs?.noPromptTemplates).toBe(true);
+    expect(loaderArgs?.noThemes).toBe(true);
+    expect(loaderArgs?.noContextFiles).toBe(true);
+  });
+
+  test('assistantConfig.enableExtensions: false keeps noExtensions: true', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        assistantConfig: { enableExtensions: false },
+      })
+    );
+
+    const loaderArgs = MockDefaultResourceLoader.mock.calls[0]?.[0] as
+      | Record<string, unknown>
+      | undefined;
+    expect(loaderArgs?.noExtensions).toBe(true);
+  });
+
+  test('nodeConfig.skills with unknown name yields system warning, does not abort', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    const { chunks, error } = await consume(
+      new PiProvider().sendQuery('hi', '/tmp/nonexistent-cwd', undefined, {
+        model: 'google/gemini-2.5-pro',
+        nodeConfig: { skills: ['definitely-does-not-exist'] },
+      })
+    );
+    expect(error).toBeUndefined();
+    const systemChunks = chunks.filter(
+      (c): c is { type: 'system'; content: string } =>
+        typeof c === 'object' && c !== null && (c as { type?: string }).type === 'system'
+    );
+    expect(systemChunks.some(c => c.content.includes('definitely-does-not-exist'))).toBe(true);
+
+    // DefaultResourceLoader instantiated without additionalSkillPaths (all missing)
+    const loaderArgs = MockDefaultResourceLoader.mock.calls[0]?.[0] as
+      | Record<string, unknown>
+      | undefined;
+    expect(loaderArgs?.additionalSkillPaths).toBeUndefined();
+  });
+
+  test('nodeConfig.skills absent → no additionalSkillPaths option passed', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+      })
+    );
+
+    const loaderArgs = MockDefaultResourceLoader.mock.calls[0]?.[0] as
+      | Record<string, unknown>
+      | undefined;
+    expect('additionalSkillPaths' in (loaderArgs ?? {})).toBe(false);
+  });
+
+  // ─── Error + lifecycle paths (review: "zero test coverage") ─────────
+
+  test('session.prompt rejection surfaces as thrown error to consumer', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    const promptError = new Error('pi backend exploded');
+    mockPrompt.mockImplementationOnce(async () => {
+      throw promptError;
+    });
+
+    const { error } = await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+      })
+    );
+    expect(error?.message).toBe('pi backend exploded');
+    // dispose still happens on error path
+    expect(mockDispose).toHaveBeenCalledTimes(1);
+  });
+
+  test('pre-aborted signal triggers session.abort before any yielding', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+    const controller = new AbortController();
+    controller.abort();
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        abortSignal: controller.signal,
+      })
+    );
+    expect(mockAbort).toHaveBeenCalled();
+  });
+
+  test('abort signal mid-stream calls session.abort', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    const controller = new AbortController();
+    // Drive the listener with one chunk, then abort, then agent_end.
+    mockPrompt.mockImplementationOnce(async () => {
+      capturedListener?.({
+        type: 'message_update',
+        message: { role: 'assistant' } as never,
+        assistantMessageEvent: {
+          type: 'text_delta',
+          contentIndex: 0,
+          delta: 'partial',
+          partial: { role: 'assistant' } as never,
+        },
+      });
+      controller.abort();
+      capturedListener?.({
+        type: 'agent_end',
+        messages: [
+          {
+            role: 'assistant',
+            usage: {
+              input: 1,
+              output: 1,
+              cacheRead: 0,
+              cacheWrite: 0,
+              totalTokens: 2,
+              cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+            },
+            stopReason: 'stop',
+            content: [],
+          } as never,
+        ],
+      });
+    });
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        abortSignal: controller.signal,
+      })
+    );
+    expect(mockAbort).toHaveBeenCalled();
+  });
+
+  test('modelFallbackMessage yields a system chunk before the agent runs', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    mockCreateAgentSession.mockImplementationOnce(async () => ({
+      session: mockSession,
+      extensionsResult: { extensions: [], errors: [], runtime: {} },
+      modelFallbackMessage: 'Requested sonnet-5 not available, using haiku.',
+    }));
+    resetScript(scriptedAgentEnd());
+
+    const { chunks } = await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+      })
+    );
+    const systemChunks = chunks.filter(
+      (c): c is { type: 'system'; content: string } =>
+        typeof c === 'object' && c !== null && (c as { type?: string }).type === 'system'
+    );
+    expect(systemChunks.some(c => c.content.includes('sonnet-5 not available'))).toBe(true);
+  });
+
+  // ─── structured output (best-effort JSON via prompt engineering) ──────
+
+  // Script an assistant text_delta followed by agent_end so the bridge has
+  // buffered content to parse when outputFormat is set.
+  function scriptedAssistantThenEnd(text: string): FakeEvent[] {
+    return [
+      {
+        type: 'message_update',
+        message: { role: 'assistant' } as never,
+        assistantMessageEvent: {
+          type: 'text_delta',
+          contentIndex: 0,
+          delta: text,
+          partial: { role: 'assistant' } as never,
+        },
+      },
+      ...scriptedAgentEnd(),
+    ];
+  }
+
+  test('outputFormat: schema is appended to prompt as JSON instruction', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    await consume(
+      new PiProvider().sendQuery('Summarize this bug.', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        outputFormat: {
+          type: 'json_schema',
+          schema: { type: 'object', properties: { area: { type: 'string' } } },
+        },
+      })
+    );
+
+    // Prompt should now contain the original instruction + the schema hint.
+    expect(mockPrompt).toHaveBeenCalled();
+    const [sentPrompt] = mockPrompt.mock.calls[0] as [string];
+    expect(sentPrompt).toContain('Summarize this bug.');
+    expect(sentPrompt).toContain('Respond with ONLY a JSON object');
+    expect(sentPrompt).toContain('"area"');
+  });
+
+  test('outputFormat: absent → prompt passed through unchanged', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    await consume(
+      new PiProvider().sendQuery('do a thing', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+      })
+    );
+
+    const [sentPrompt] = mockPrompt.mock.calls[0] as [string];
+    expect(sentPrompt).toBe('do a thing');
+    expect(sentPrompt).not.toContain('JSON');
+  });
+
+  test('outputFormat: result chunk carries parsed structuredOutput on clean JSON', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAssistantThenEnd('{"area":"web","confidence":0.9}'));
+
+    const { chunks } = await consume(
+      new PiProvider().sendQuery('classify', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        outputFormat: {
+          type: 'json_schema',
+          schema: { type: 'object' },
+        },
+      })
+    );
+
+    const result = chunks.find(
+      (c): c is { type: 'result'; structuredOutput?: unknown } =>
+        typeof c === 'object' && c !== null && (c as { type?: string }).type === 'result'
+    );
+    expect(result).toBeDefined();
+    expect(result?.structuredOutput).toEqual({ area: 'web', confidence: 0.9 });
+  });
+
+  test('outputFormat: fenced JSON (```json ... ```) still parses', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAssistantThenEnd('```json\n{"ok":true}\n```'));
+
+    const { chunks } = await consume(
+      new PiProvider().sendQuery('x', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        outputFormat: { type: 'json_schema', schema: {} },
+      })
+    );
+
+    const result = chunks.find(
+      (c): c is { type: 'result'; structuredOutput?: unknown } =>
+        typeof c === 'object' && c !== null && (c as { type?: string }).type === 'result'
+    );
+    expect(result?.structuredOutput).toEqual({ ok: true });
+  });
+
+  test('outputFormat: prose-wrapped JSON → no structuredOutput, degrades cleanly', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAssistantThenEnd('Here is the JSON:\n{"ok":true}\nHope this helps!'));
+
+    const { chunks, error } = await consume(
+      new PiProvider().sendQuery('x', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        outputFormat: { type: 'json_schema', schema: {} },
+      })
+    );
+
+    // No crash — downstream degradation is the executor's job via its
+    // existing dag.structured_output_missing warning path.
+    expect(error).toBeUndefined();
+    const result = chunks.find(
+      (c): c is { type: 'result'; structuredOutput?: unknown } =>
+        typeof c === 'object' && c !== null && (c as { type?: string }).type === 'result'
+    );
+    expect(result).toBeDefined();
+    expect(result?.structuredOutput).toBeUndefined();
+  });
+
+  test('no outputFormat → structuredOutput never set even if assistant emits JSON', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAssistantThenEnd('{"accidental":"json"}'));
+
+    const { chunks } = await consume(
+      new PiProvider().sendQuery('x', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+      })
+    );
+
+    const result = chunks.find(
+      (c): c is { type: 'result'; structuredOutput?: unknown } =>
+        typeof c === 'object' && c !== null && (c as { type?: string }).type === 'result'
+    );
+    expect(result?.structuredOutput).toBeUndefined();
+  });
+
+  // ─── Interactive ExtensionUIContext binding ───────────────────────────
+
+  test('interactive: true with enableExtensions binds a UIContext to the session', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        assistantConfig: { enableExtensions: true, interactive: true },
+      })
+    );
+
+    expect(mockBindExtensions).toHaveBeenCalledTimes(1);
+    const [bindings] = mockBindExtensions.mock.calls[0] as [{ uiContext?: unknown }];
+    expect(bindings.uiContext).toBeDefined();
+  });
+
+  test('enableExtensions: false disables binding even if interactive: true is set', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        assistantConfig: { enableExtensions: false, interactive: true },
+      })
+    );
+
+    expect(mockBindExtensions).not.toHaveBeenCalled();
+  });
+
+  test('interactive: false with extensions on binds empty (session_start fires, no UIContext)', async () => {
+    // When extensions are loaded, session_start MUST fire so each extension's
+    // startup handler runs (reads flags, registers tools, etc.). Binding with
+    // no uiContext keeps Pi's internal noOpUIContext active so hasUI stays
+    // false — extensions that gate UI flows (like plannotator) will auto-approve
+    // in this mode.
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        assistantConfig: { interactive: false },
+      })
+    );
+
+    expect(mockBindExtensions).toHaveBeenCalledTimes(1);
+    const [bindings] = mockBindExtensions.mock.calls[0] as [{ uiContext?: unknown }];
+    expect(bindings.uiContext).toBeUndefined();
+  });
+
+  test('default (nothing set) binds with UIContext — extensions + interactive both on', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+      })
+    );
+
+    expect(mockBindExtensions).toHaveBeenCalledTimes(1);
+    const [bindings] = mockBindExtensions.mock.calls[0] as [{ uiContext?: unknown }];
+    expect(bindings.uiContext).toBeDefined();
+  });
+
+  // ─── extensionFlags pass-through ──────────────────────────────────────
+
+  test('extensionFlags sets flag values before bindExtensions fires session_start', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    // Track call order: setFlagValue must run BEFORE bindExtensions, else
+    // extensions reading flags in their session_start handler miss them.
+    const callOrder: string[] = [];
+    mockSetFlagValue.mockImplementationOnce(() => {
+      callOrder.push('setFlagValue');
+      return undefined;
+    });
+    mockSetFlagValue.mockImplementationOnce(() => {
+      callOrder.push('setFlagValue');
+      return undefined;
+    });
+    mockBindExtensions.mockImplementationOnce(async () => {
+      callOrder.push('bindExtensions');
+    });
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        assistantConfig: {
+          enableExtensions: true,
+          interactive: true,
+          extensionFlags: { plan: true, 'plan-file': 'PLAN.md' },
+        },
+      })
+    );
+
+    expect(mockSetFlagValue).toHaveBeenCalledTimes(2);
+    expect(mockSetFlagValue).toHaveBeenCalledWith('plan', true);
+    expect(mockSetFlagValue).toHaveBeenCalledWith('plan-file', 'PLAN.md');
+    expect(callOrder).toEqual(['setFlagValue', 'setFlagValue', 'bindExtensions']);
+  });
+
+  test('extensionFlags is a no-op when enableExtensions is explicitly false', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    resetScript(scriptedAgentEnd());
+
+    await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'google/gemini-2.5-pro',
+        assistantConfig: { enableExtensions: false, extensionFlags: { plan: true } },
+      })
+    );
+
+    expect(mockSetFlagValue).not.toHaveBeenCalled();
+    expect(mockBindExtensions).not.toHaveBeenCalled();
+  });
+
+  test('assistantConfig.env applies to process.env when not already set', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    delete process.env.PI_TEST_ONE;
+    delete process.env.PI_TEST_TWO;
+    resetScript(scriptedAgentEnd());
+
+    try {
+      await consume(
+        new PiProvider().sendQuery('hi', '/tmp', undefined, {
+          model: 'google/gemini-2.5-pro',
+          assistantConfig: { env: { PI_TEST_ONE: 'one', PI_TEST_TWO: 'two' } },
+        })
+      );
+
+      expect(process.env.PI_TEST_ONE).toBe('one');
+      expect(process.env.PI_TEST_TWO).toBe('two');
+    } finally {
+      delete process.env.PI_TEST_ONE;
+      delete process.env.PI_TEST_TWO;
+    }
+  });
+
+  test('shell env wins over assistantConfig.env (no override)', async () => {
+    process.env.GEMINI_API_KEY = 'sk-test';
+    process.env.PI_TEST_SHELL_WINS = 'shell-value';
+    resetScript(scriptedAgentEnd());
+
+    try {
+      await consume(
+        new PiProvider().sendQuery('hi', '/tmp', undefined, {
+          model: 'google/gemini-2.5-pro',
+          assistantConfig: { env: { PI_TEST_SHELL_WINS: 'config-value' } },
+        })
+      );
+
+      expect(process.env.PI_TEST_SHELL_WINS).toBe('shell-value');
+    } finally {
+      delete process.env.PI_TEST_SHELL_WINS;
+    }
+  });
+});
diff --git a/packages/providers/src/community/pi/provider.ts b/packages/providers/src/community/pi/provider.ts
new file mode 100644
index 0000000000..f0171df202
--- /dev/null
+++ b/packages/providers/src/community/pi/provider.ts
@@ -0,0 +1,383 @@
+import { createLogger } from '@archon/paths';
+import {
+  AuthStorage,
+  ModelRegistry,
+  SettingsManager,
+  createAgentSession,
+} from '@mariozechner/pi-coding-agent';
+import { getModel, type Api, type Model } from '@mariozechner/pi-ai';
+
+import type {
+  IAgentProvider,
+  MessageChunk,
+  ProviderCapabilities,
+  SendQueryOptions,
+} from '../../types';
+
+import { PI_CAPABILITIES } from './capabilities';
+import { parsePiConfig } from './config';
+import { bridgeSession } from './event-bridge';
+import { parsePiModelRef } from './model-ref';
+import { resolvePiSkills, resolvePiThinkingLevel, resolvePiTools } from './options-translator';
+import { createNoopResourceLoader } from './resource-loader';
+import { resolvePiSession } from './session-resolver';
+import { createArchonUIBridge, createArchonUIContext } from './ui-context-stub';
+
+/**
+ * Map Pi provider id → env var name used by pi-ai's getEnvApiKey().
+ * Kept small and explicit: v1 supports the most common API-key providers.
+ * OAuth flows (Anthropic subscription, Google Gemini CLI, etc.) are out of
+ * scope — Archon is a server-side platform and doesn't drive interactive
+ * login. Extend only when a provider is actually exercised.
+ *
+ * Cross-reference (authoritative mapping maintained upstream in Pi):
+ *   https://github.com/badlogic/pi-mono/blob/main/packages/ai/src/env-api-keys.ts
+ */
+const PI_PROVIDER_ENV_VARS: Record<string, string> = {
+  anthropic: 'ANTHROPIC_API_KEY',
+  openai: 'OPENAI_API_KEY',
+  google: 'GEMINI_API_KEY',
+  groq: 'GROQ_API_KEY',
+  mistral: 'MISTRAL_API_KEY',
+  cerebras: 'CEREBRAS_API_KEY',
+  xai: 'XAI_API_KEY',
+  openrouter: 'OPENROUTER_API_KEY',
+  huggingface: 'HUGGINGFACE_API_KEY',
+};
+
+let cachedLog: ReturnType<typeof createLogger> | undefined;
+function getLog(): ReturnType<typeof createLogger> {
+  if (!cachedLog) cachedLog = createLogger('provider.pi');
+  return cachedLog;
+}
+
+/**
+ * Typed wrapper around Pi's `getModel` for a runtime-string provider/model
+ * pair. Pi's getModel signature constrains `TModelId` to
+ * `keyof MODELS[TProvider]`, which isn't knowable from a runtime string —
+ * the cast through `unknown` is the only way to bypass it. Isolating that
+ * escape hatch behind one searchable name keeps it auditable.
+ */
+function lookupPiModel(provider: string, modelId: string): Model<Api> | undefined {
+  return (getModel as unknown as (p: string, m: string) => Model<Api> | undefined)(
+    provider,
+    modelId
+  );
+}
+
+/**
+ * Append a "respond with JSON matching this schema" instruction to the user
+ * prompt so Pi-backed models produce parseable structured output. Pi's SDK
+ * has no JSON-mode equivalent to Claude's outputFormat or Codex's
+ * outputSchema, so this is a best-effort fallback: the event bridge parses
+ * the assistant transcript on agent_end. Models that reliably follow
+ * instruction (GPT-5, Claude, Gemini 2.x, recent Qwen Coder, DeepSeek V3)
+ * return clean JSON; models that don't produce a parse failure, which the
+ * executor surfaces via the existing dag.structured_output_missing warning.
+ */
+export function augmentPromptForJsonSchema(
+  prompt: string,
+  schema: Record<string, unknown>
+): string {
+  return `${prompt}
+
+---
+
+CRITICAL: Respond with ONLY a JSON object matching the schema below. No prose before or after the JSON. No markdown code fences. Just the raw JSON object as your final message.
+
+Schema:
+${JSON.stringify(schema, null, 2)}`;
+}
+
+/**
+ * Pi community provider — wraps `@mariozechner/pi-coding-agent`'s full
+ * coding-agent harness. Each `sendQuery()` call creates a fresh session
+ * (no reuse) with in-memory auth/session/settings, so the server never
+ * touches `~/.pi/` and concurrent calls don't collide.
+ *
+ * v1 capabilities are all false (see `capabilities.ts`): sessionResume,
+ * thinkingControl, skills, mcp, etc. map to Pi features but require
+ * intentional wiring before they can be declared. Under-declaring is
+ * honest; the dag-executor emits warnings for any nodeConfig field not
+ * supported.
+ */
+export class PiProvider implements IAgentProvider {
+  async *sendQuery(
+    prompt: string,
+    cwd: string,
+    resumeSessionId?: string,
+    requestOptions?: SendQueryOptions
+  ): AsyncGenerator<MessageChunk> {
+    const assistantConfig = requestOptions?.assistantConfig ?? {};
+    const piConfig = parsePiConfig(assistantConfig);
+
+    // 0. Apply config-level env vars to process.env for in-process extensions
+    //    (plannotator reads PLANNOTATOR_REMOTE at session_start, etc.).
+    //    Shell env wins: we only set keys not already present. Request-level
+    //    `requestOptions.env` remains a separate channel — it flows through
+    //    bash spawn hooks for subprocess isolation, not into process.env.
+    if (piConfig.env) {
+      const applied: string[] = [];
+      for (const [key, value] of Object.entries(piConfig.env)) {
+        if (process.env[key] === undefined) {
+          process.env[key] = value;
+          applied.push(key);
+        }
+      }
+      if (applied.length > 0) {
+        getLog().debug({ keys: applied }, 'pi.config_env_applied');
+      }
+    }
+
+    // 1. Resolve model ref: request (workflow node / chat) → config default
+    const modelRef = requestOptions?.model ?? piConfig.model;
+    if (!modelRef) {
+      throw new Error(
+        'Pi provider requires a model. Set `model` on the workflow node or `assistants.pi.model` in .archon/config.yaml. ' +
+          "Format: '<pi-provider-id>/<model-id>' (e.g. 'google/gemini-2.5-pro')."
+      );
+    }
+    const parsed = parsePiModelRef(modelRef);
+    if (!parsed) {
+      throw new Error(
+        `Invalid Pi model ref: '${modelRef}'. Expected format '<pi-provider-id>/<model-id>' (e.g. 'google/gemini-2.5-pro').`
+      );
+    }
+
+    // 2. Look up the Model via Pi's static catalog. `lookupPiModel` returns
+    //    undefined when not found; we guard explicitly below.
+    const model = lookupPiModel(parsed.provider, parsed.modelId);
+    if (!model) {
+      throw new Error(
+        `Pi model not found: provider='${parsed.provider}' model='${parsed.modelId}'. ` +
+          'See https://github.com/badlogic/pi-mono/blob/main/packages/ai/src/models.generated.ts for the Pi model catalog.'
+      );
+    }
+
+    // 3. Build AuthStorage. `AuthStorage.create()` reads ~/.pi/agent/auth.json
+    //    (or $PI_CODING_AGENT_DIR/auth.json), so any credential the user has
+    //    populated via `pi` → `/login` (OAuth subscriptions: Claude Pro/Max,
+    //    ChatGPT Plus, GitHub Copilot, Gemini CLI, Antigravity) or by editing
+    //    the file directly (api_key entries) is picked up transparently.
+    //
+    //    Per-request env vars override the file via setRuntimeApiKey — this
+    //    mirrors Claude's process-env + request-env merge pattern and
+    //    ensures codebase-scoped env vars (from .archon/config.yaml `env:`)
+    //    win over the user's global Pi login.
+    //
+    //    Pi's internal resolution order:
+    //      1. runtime override  (our setRuntimeApiKey below)
+    //      2. auth.json api_key entry
+    //      3. auth.json oauth entry  (auto-refreshes expired tokens)
+    //      4. env var fallback  (Pi's getEnvApiKey, e.g. ANTHROPIC_API_KEY)
+    //
+    //    OAuth refresh note: Pi refreshes expired access tokens against the
+    //    provider's OAuth server and rewrites ~/.pi/agent/auth.json under a
+    //    file lock (same mechanism pi CLI uses — safe for concurrent access).
+    const authStorage = AuthStorage.create();
+
+    const envVarName = PI_PROVIDER_ENV_VARS[parsed.provider];
+    const envOverride = envVarName
+      ? (requestOptions?.env?.[envVarName] ?? process.env[envVarName])
+      : undefined;
+    if (envOverride) {
+      authStorage.setRuntimeApiKey(parsed.provider, envOverride);
+    }
+
+    // Fail-fast: resolve creds synchronously before spinning up a session.
+    // Matches Claude's auth-error fast-fail pattern (no retry on auth failures).
+    const resolvedKey = await authStorage.getApiKey(parsed.provider);
+    if (!resolvedKey) {
+      const envHint = envVarName
+        ? `Set ${envVarName} in the environment or codebase env vars (.archon/config.yaml env: section).`
+        : `Provider '${parsed.provider}' is not in the Archon adapter's env-var table — file an issue if you want a shortcut env var for it.`;
+      const loginHint = `Or run \`pi\` and type \`/login\` locally to authenticate '${parsed.provider}' via OAuth; credentials land in ~/.pi/agent/auth.json and are picked up automatically.`;
+      throw new Error(
+        `Pi auth: no credentials for provider '${parsed.provider}'. ${envHint} ${loginHint}`
+      );
+    }
+
+    // 4. Translate Archon nodeConfig to Pi SDK options. All three translations
+    //    below correspond to capability flags declared `true` in
+    //    PI_CAPABILITIES; nodeConfig fields that don't map cleanly still
+    //    trigger a dag-executor warning upstream.
+    const nodeConfig = requestOptions?.nodeConfig;
+
+    //    4a. thinkingLevel: covers `thinking`/`effort` nodeConfig fields.
+    const { level: thinkingLevel, warning: thinkingWarning } = resolvePiThinkingLevel(nodeConfig);
+    if (thinkingWarning) {
+      yield { type: 'system', content: `⚠️ ${thinkingWarning}` };
+    }
+
+    //    4b. tools: covers allowed_tools / denied_tools. `undefined` leaves Pi
+    //        defaults; an explicit empty array means "no tools" (valid idiom
+    //        matching e2e-claude-smoke's `allowed_tools: []`).
+    //        requestOptions.env (codebase-scoped env vars from .archon/config.yaml)
+    //        is injected into bash subprocesses via a BashSpawnHook, mirroring
+    //        Claude's options.env and Codex's constructor env.
+    const { tools: filteredTools, unknownTools } = resolvePiTools(
+      cwd,
+      nodeConfig,
+      requestOptions?.env
+    );
+    if (unknownTools.length > 0) {
+      yield {
+        type: 'system',
+        content: `⚠️ Pi ignored unknown tool names: ${unknownTools.join(', ')}. Pi's built-in tools: read, bash, edit, write, grep, find, ls.`,
+      };
+    }
+
+    //    4c. systemPrompt: request-level (AgentRequestOptions) wins over
+    //        node-level; either overrides Pi's default.
+    const systemPrompt = requestOptions?.systemPrompt ?? nodeConfig?.systemPrompt;
+
+    //    4d. skills: Archon uses name references (e.g. `skills: [agent-browser]`).
+    //        Resolve each name against .agents/skills and .claude/skills (project
+    //        + user-global). Resolved paths go through Pi's additionalSkillPaths;
+    //        Pi's buildSystemPrompt appends their agentskills.io XML block to
+    //        the system prompt automatically, so the model sees them.
+    const { paths: skillPaths, missing: missingSkills } = resolvePiSkills(cwd, nodeConfig?.skills);
+    if (missingSkills.length > 0) {
+      yield {
+        type: 'system',
+        content: `⚠️ Pi could not resolve skill names: ${missingSkills.join(', ')}. Searched .agents/skills and .claude/skills (project + user-global). Each must be a directory containing SKILL.md.`,
+      };
+    }
+
+    // 5. Session management. Pi stores each session as a JSONL file under
+    //    ~/.pi/agent/sessions/<encoded-cwd>/<uuid>.jsonl. `resolvePiSession`
+    //    returns a SessionManager bound to either a new session (no resume
+    //    id) or an existing session (resume id matches a file); if the id
+    //    was provided but not found, it falls through to a new session and
+    //    the caller surfaces a resume_failed warning (matches the Codex
+    //    provider's fallback pattern for the same condition).
+    const { sessionManager, resumeFailed } = await resolvePiSession(cwd, resumeSessionId);
+    if (resumeFailed) {
+      yield {
+        type: 'system',
+        content: '⚠️ Could not resume Pi session. Starting fresh conversation.',
+      };
+    }
+
+    // ModelRegistry + settings stay in-memory — only sessions persist, to
+    // match Claude/Codex. Resource loader still suppresses filesystem
+    // discovery by default, except for explicitly-passed skill paths and —
+    // when piConfig.enableExtensions is true — Pi's community extension
+    // ecosystem (tools + lifecycle hooks from ~/.pi/agent/extensions/ and
+    // packages installed via `pi install npm:<pkg>`).
+    const modelRegistry = ModelRegistry.inMemory(authStorage);
+    const settingsManager = SettingsManager.inMemory();
+    // Default ON: extensions (community packages like @plannotator/pi-extension
+    // or your own local ones) are a core reason users run Pi. Opt out with
+    // `assistants.pi.enableExtensions: false` (or `interactive: false`) in
+    // `.archon/config.yaml`. Previously default-off, which silently broke
+    // users who installed or built an extension and expected it to fire.
+    const enableExtensions = piConfig.enableExtensions !== false;
+    // Clamp to false without extensions: nothing consumes hasUI without a runner.
+    const interactive = enableExtensions && piConfig.interactive !== false;
+    const resourceLoader = createNoopResourceLoader(cwd, {
+      ...(systemPrompt !== undefined ? { systemPrompt } : {}),
+      ...(skillPaths.length > 0 ? { additionalSkillPaths: skillPaths } : {}),
+      ...(enableExtensions ? { enableExtensions: true } : {}),
+    });
+
+    // Required: without reload(), session.extensionRunner is undefined and
+    // setFlagValue silently no-ops. createAgentSession skips this when a
+    // custom resource loader is supplied.
+    if (enableExtensions) {
+      await resourceLoader.reload();
+    }
+
+    getLog().info(
+      {
+        piProvider: parsed.provider,
+        modelId: parsed.modelId,
+        cwd,
+        thinkingLevel,
+        toolCount: filteredTools?.length,
+        hasSystemPrompt: systemPrompt !== undefined,
+        skillCount: skillPaths.length,
+        missingSkillCount: missingSkills.length,
+        extensionsEnabled: enableExtensions,
+        interactive,
+        resumed: resumeSessionId !== undefined && !resumeFailed,
+      },
+      'pi.session_started'
+    );
+
+    const { session, modelFallbackMessage } = await createAgentSession({
+      cwd,
+      model,
+      authStorage,
+      modelRegistry,
+      sessionManager,
+      settingsManager,
+      resourceLoader,
+      ...(thinkingLevel ? { thinkingLevel } : {}),
+      ...(filteredTools !== undefined ? { tools: filteredTools } : {}),
+    });
+
+    if (modelFallbackMessage) {
+      yield { type: 'system', content: `⚠️ ${modelFallbackMessage}` };
+    }
+
+    // 4e. Extension flag pass-through. Must happen before bindExtensions
+    //     below — extensions read flags inside their session_start handler.
+    if (enableExtensions && piConfig.extensionFlags) {
+      const runner = session.extensionRunner;
+      if (runner) {
+        for (const [name, value] of Object.entries(piConfig.extensionFlags)) {
+          runner.setFlagValue(name, value);
+        }
+      }
+    }
+
+    // 4f. Bind UI context (so ctx.hasUI is true and ctx.ui.notify() forwards
+    //     into the chunk stream) or fire session_start with no UI. Must run
+    //     after flag pass-through above.
+    const uiBridge = interactive ? createArchonUIBridge() : undefined;
+    if (uiBridge) {
+      const uiContext = createArchonUIContext(uiBridge);
+      await session.bindExtensions({ uiContext });
+    } else if (enableExtensions) {
+      await session.bindExtensions({});
+    }
+
+    // 5. Structured output (best-effort). Pi has no SDK-level JSON schema
+    //    mode the way Claude and Codex do, so we implement it via prompt
+    //    engineering: append the schema + "JSON only, no fences" instruction,
+    //    and have the bridge parse the accumulated assistant text on
+    //    agent_end. Parse failures degrade gracefully — the executor's
+    //    existing dag.structured_output_missing warning path handles them.
+    const outputFormat = requestOptions?.outputFormat;
+    const effectivePrompt = outputFormat
+      ? augmentPromptForJsonSchema(prompt, outputFormat.schema)
+      : prompt;
+
+    // 6. Bridge callback-based events to the async generator contract.
+    //    bridgeSession owns dispose() and abort wiring. When `interactive`
+    //    is on, it also binds/unbinds the UI stub's emitter so extension
+    //    notifications land on the same queue as Pi events.
+    try {
+      yield* bridgeSession(
+        session,
+        effectivePrompt,
+        requestOptions?.abortSignal,
+        outputFormat?.schema,
+        uiBridge
+      );
+      getLog().info({ piProvider: parsed.provider }, 'pi.prompt_completed');
+    } catch (err) {
+      getLog().error({ err, piProvider: parsed.provider }, 'pi.prompt_failed');
+      throw err;
+    }
+  }
+
+  getType(): string {
+    return 'pi';
+  }
+
+  getCapabilities(): ProviderCapabilities {
+    return PI_CAPABILITIES;
+  }
+}
diff --git a/packages/providers/src/community/pi/registration.ts b/packages/providers/src/community/pi/registration.ts
new file mode 100644
index 0000000000..01c9e5ea0f
--- /dev/null
+++ b/packages/providers/src/community/pi/registration.ts
@@ -0,0 +1,26 @@
+import { isRegisteredProvider, registerProvider } from '../../registry';
+
+import { PI_CAPABILITIES } from './capabilities';
+import { isPiModelCompatible } from './model-ref';
+import { PiProvider } from './provider';
+
+/**
+ * Register the Pi community provider.
+ *
+ * Idempotent — safe to call multiple times, so process entrypoints (CLI,
+ * server, config-loader) can each call it without coordination. Kept
+ * separate from `registerBuiltinProviders()` because `builtIn: false` is
+ * load-bearing: Pi validates the Phase 2 community-provider seam and must
+ * not be conflated with core providers until it's explicitly promoted.
+ */
+export function registerPiProvider(): void {
+  if (isRegisteredProvider('pi')) return;
+  registerProvider({
+    id: 'pi',
+    displayName: 'Pi (community)',
+    factory: () => new PiProvider(),
+    capabilities: PI_CAPABILITIES,
+    isModelCompatible: isPiModelCompatible,
+    builtIn: false,
+  });
+}
diff --git a/packages/providers/src/community/pi/resource-loader.ts b/packages/providers/src/community/pi/resource-loader.ts
new file mode 100644
index 0000000000..cde9f7d826
--- /dev/null
+++ b/packages/providers/src/community/pi/resource-loader.ts
@@ -0,0 +1,81 @@
+import { DefaultResourceLoader } from '@mariozechner/pi-coding-agent';
+
+export interface NoopResourceLoaderOptions {
+  /**
+   * Override Pi's system prompt entirely. When omitted, Pi uses its default.
+   * Forwarded to `DefaultResourceLoader({ systemPrompt })` — the no* flags
+   * below still suppress all discovery of `AGENTS.md` / `CLAUDE.md` context
+   * files that would otherwise augment or replace the prompt.
+   */
+  systemPrompt?: string;
+
+  /**
+   * Absolute paths to specific skill directories (each containing a SKILL.md)
+   * that Pi should load in addition to its default discovery. Works even with
+   * `noSkills: true` — Pi's loader merges additional paths regardless, per
+   * its internal logic in `DefaultResourceLoader.updateSkillsFromPaths`.
+   *
+   * Used by the Pi provider to thread Archon's name-based `skills:` node
+   * config through to Pi after resolution — see `resolvePiSkills`.
+   */
+  additionalSkillPaths?: string[];
+
+  /**
+   * Opt-in to Pi's extension discovery. When true, `noExtensions` flips to
+   * false and Pi loads:
+   *   - `~/.pi/agent/extensions/*.ts` (global, operator-installed)
+   *   - packages listed in `~/.pi/agent/settings.json` (from `pi install`)
+   *   - `<cwd>/.pi/extensions/*.ts` (project-local — REPO-CONTROLLED, risky)
+   *   - packages listed in `<cwd>/.pi/settings.json`
+   *
+   * This is the switch that opens up the community package ecosystem
+   * (https://shittycodingagent.ai/packages) — ~540 npm packages registering
+   * custom tools and lifecycle hooks via `pi.registerTool()` / `pi.on()`.
+   * Tools and hooks work fully in programmatic sessions; TUI-only features
+   * (renderers, keybindings, slash commands) silently no-op. Extensions that
+   * gate on `ctx.hasUI` additionally need `interactive: true` — see
+   * `PiProviderDefaults.interactive`.
+   *
+   * Trust boundary: enabling this loads arbitrary JS code with the Archon
+   * server's OS permissions. Only flip this on when the operator trusts both
+   * globally-installed extensions AND whatever `.pi/` the workflow's target
+   * repo happens to contain.
+   *
+   * @default false
+   */
+  enableExtensions?: boolean;
+}
+
+/**
+ * Build a Pi ResourceLoader. By default performs no filesystem discovery —
+ * Archon is the source of truth for skills, prompts, themes, and context
+ * files, and Pi should not walk cwd or read `~/.pi/agent/` during server-side
+ * workflow execution. When `enableExtensions: true`, the `noExtensions` gate
+ * is lifted so Pi discovers and loads tools + hooks from the community
+ * ecosystem (see `NoopResourceLoaderOptions.enableExtensions`). Skills and
+ * prompts/themes remain suppressed even when extensions are enabled — skills
+ * are still driven by Archon's explicit `additionalSkillPaths` plumbing.
+ *
+ * Implementation note: we delegate to `DefaultResourceLoader` with the
+ * relevant `no*` flags set, rather than implementing `ResourceLoader`
+ * ourselves. The interface's `getExtensions()` returns a `LoadExtensionsResult`
+ * requiring a real `ExtensionRuntime`, which we can't meaningfully stub.
+ * DefaultResourceLoader honors the flags and returns empty-but-valid results.
+ */
+export function createNoopResourceLoader(
+  cwd: string,
+  options: NoopResourceLoaderOptions = {}
+): DefaultResourceLoader {
+  return new DefaultResourceLoader({
+    cwd,
+    noExtensions: options.enableExtensions !== true,
+    noSkills: true,
+    noPromptTemplates: true,
+    noThemes: true,
+    noContextFiles: true,
+    ...(options.systemPrompt !== undefined ? { systemPrompt: options.systemPrompt } : {}),
+    ...(options.additionalSkillPaths && options.additionalSkillPaths.length > 0
+      ? { additionalSkillPaths: options.additionalSkillPaths }
+      : {}),
+  });
+}
diff --git a/packages/providers/src/community/pi/session-resolver.test.ts b/packages/providers/src/community/pi/session-resolver.test.ts
new file mode 100644
index 0000000000..4b1f6b098e
--- /dev/null
+++ b/packages/providers/src/community/pi/session-resolver.test.ts
@@ -0,0 +1,107 @@
+import { beforeEach, describe, expect, mock, test } from 'bun:test';
+
+// ─── Mock SessionManager before import ─────────────────────────────────────
+
+const mockCreate = mock((_cwd: string) => ({ __kind: 'created' }));
+const mockOpen = mock((_path: string) => ({ __kind: 'opened' }));
+const mockList = mock(async (_cwd: string) => [] as { id: string; path: string; cwd: string }[]);
+
+mock.module('@mariozechner/pi-coding-agent', () => ({
+  SessionManager: {
+    create: mockCreate,
+    open: mockOpen,
+    list: mockList,
+  },
+}));
+
+import { resolvePiSession } from './session-resolver';
+
+describe('resolvePiSession', () => {
+  beforeEach(() => {
+    mockCreate.mockClear();
+    mockOpen.mockClear();
+    mockList.mockClear();
+    mockList.mockImplementation(async () => []);
+  });
+
+  test('no resumeSessionId → create fresh session', async () => {
+    const result = await resolvePiSession('/tmp/proj', undefined);
+    expect(result.resumeFailed).toBe(false);
+    expect(mockCreate).toHaveBeenCalledWith('/tmp/proj');
+    expect(mockOpen).not.toHaveBeenCalled();
+    expect(mockList).not.toHaveBeenCalled();
+  });
+
+  test('resume id matches existing session → open by path', async () => {
+    mockList.mockImplementationOnce(async () => [
+      { id: 'abc-123', path: '/sessions/abc-123.jsonl', cwd: '/tmp/proj' },
+      { id: 'def-456', path: '/sessions/def-456.jsonl', cwd: '/tmp/proj' },
+    ]);
+
+    const result = await resolvePiSession('/tmp/proj', 'def-456');
+    expect(result.resumeFailed).toBe(false);
+    expect(mockOpen).toHaveBeenCalledWith('/sessions/def-456.jsonl');
+    expect(mockCreate).not.toHaveBeenCalled();
+  });
+
+  test('resume id not found → fresh session with resumeFailed=true', async () => {
+    mockList.mockImplementationOnce(async () => [
+      { id: 'abc-123', path: '/sessions/abc-123.jsonl', cwd: '/tmp/proj' },
+    ]);
+
+    const result = await resolvePiSession('/tmp/proj', 'missing-id');
+    expect(result.resumeFailed).toBe(true);
+    expect(mockCreate).toHaveBeenCalledWith('/tmp/proj');
+    expect(mockOpen).not.toHaveBeenCalled();
+  });
+
+  test('list() throws ENOENT → treated as not-found, fresh session', async () => {
+    mockList.mockImplementationOnce(async () => {
+      const err = Object.assign(new Error('no such directory'), { code: 'ENOENT' });
+      throw err;
+    });
+
+    const result = await resolvePiSession('/tmp/proj', 'some-id');
+    expect(result.resumeFailed).toBe(true);
+    expect(mockCreate).toHaveBeenCalledWith('/tmp/proj');
+  });
+
+  test('list() throws ENOTDIR → treated as not-found, fresh session', async () => {
+    mockList.mockImplementationOnce(async () => {
+      const err = Object.assign(new Error('not a directory'), { code: 'ENOTDIR' });
+      throw err;
+    });
+
+    const result = await resolvePiSession('/tmp/proj', 'some-id');
+    expect(result.resumeFailed).toBe(true);
+    expect(mockCreate).toHaveBeenCalledWith('/tmp/proj');
+  });
+
+  test('list() throws unexpected error → propagates (no silent fallback)', async () => {
+    // Permission errors, parse failures, etc. must NOT be swallowed as
+    // "no resume" — that would paper over real config/filesystem problems.
+    mockList.mockImplementationOnce(async () => {
+      const err = Object.assign(new Error('permission denied'), { code: 'EACCES' });
+      throw err;
+    });
+
+    await expect(resolvePiSession('/tmp/proj', 'some-id')).rejects.toThrow(/permission denied/);
+    expect(mockCreate).not.toHaveBeenCalled();
+  });
+
+  test('list() throws plain Error → propagates (no code = not ENOENT)', async () => {
+    mockList.mockImplementationOnce(async () => {
+      throw new Error('some other failure');
+    });
+
+    await expect(resolvePiSession('/tmp/proj', 'some-id')).rejects.toThrow(/some other failure/);
+  });
+
+  test('empty resumeSessionId string → fresh session (no resume attempted)', async () => {
+    // Treated as "no resume requested" by the truthy check in the resolver.
+    const result = await resolvePiSession('/tmp/proj', '');
+    expect(result.resumeFailed).toBe(false);
+    expect(mockList).not.toHaveBeenCalled();
+    expect(mockCreate).toHaveBeenCalled();
+  });
+});
diff --git a/packages/providers/src/community/pi/session-resolver.ts b/packages/providers/src/community/pi/session-resolver.ts
new file mode 100644
index 0000000000..d8a291ddb3
--- /dev/null
+++ b/packages/providers/src/community/pi/session-resolver.ts
@@ -0,0 +1,68 @@
+import { SessionManager } from '@mariozechner/pi-coding-agent';
+
+/**
+ * Result of resolving an Archon `resumeSessionId` against Pi's session store.
+ */
+export interface ResolvedSession {
+  /** SessionManager to hand to createAgentSession. */
+  sessionManager: SessionManager;
+  /**
+   * True when a resumeSessionId was provided but no matching session file
+   * was found — caller should surface a system warning before the new
+   * session starts. Mirrors the `resume_thread_failed` fallback pattern
+   * the Codex provider uses.
+   */
+  resumeFailed: boolean;
+}
+
+/**
+ * Resolve a Pi `SessionManager` for a sendQuery call.
+ *
+ * Behavior:
+ *  - No resumeSessionId → fresh `SessionManager.create(cwd)`.
+ *  - resumeSessionId matches a session file for this cwd → `SessionManager.open(path)`.
+ *  - resumeSessionId provided but not found → fresh session, `resumeFailed: true`.
+ *
+ * Pi stores sessions as JSONL files under `~/.pi/agent/sessions/<encoded-cwd>/`
+ * (or `$PI_CODING_AGENT_DIR/sessions/...`). This mirrors Claude's
+ * `~/.claude/projects/` and Codex's thread store — the provider owns
+ * session persistence; Archon just holds the opaque UUID.
+ *
+ * Lookup uses `SessionManager.list(cwd)` which scans only this cwd's
+ * sessions. Cross-cwd resume (e.g. worktree switch) is deliberately not
+ * supported in this pass — if a workflow moves to a different directory,
+ * a fresh session is created. This matches Pi's own mental model and
+ * avoids ambiguity.
+ */
+export async function resolvePiSession(
+  cwd: string,
+  resumeSessionId: string | undefined
+): Promise<ResolvedSession> {
+  if (!resumeSessionId) {
+    return { sessionManager: SessionManager.create(cwd), resumeFailed: false };
+  }
+
+  try {
+    const sessions = await SessionManager.list(cwd);
+    const match = sessions.find(s => s.id === resumeSessionId);
+    if (match) {
+      return {
+        sessionManager: SessionManager.open(match.path),
+        resumeFailed: false,
+      };
+    }
+  } catch (err: unknown) {
+    // Only swallow "session dir doesn't exist yet" — any other error
+    // (permission denied, corrupt JSONL, etc.) must propagate so failures
+    // aren't papered over as a silent "no resume, fresh session" success.
+    if (!isMissingSessionDirError(err)) throw err;
+  }
+
+  return { sessionManager: SessionManager.create(cwd), resumeFailed: true };
+}
+
+function isMissingSessionDirError(err: unknown): boolean {
+  if (err === null || typeof err !== 'object') return false;
+  const code = (err as { code?: unknown }).code;
+  return code === 'ENOENT' || code === 'ENOTDIR';
+}
diff --git a/packages/providers/src/community/pi/ui-context-stub.test.ts b/packages/providers/src/community/pi/ui-context-stub.test.ts
new file mode 100644
index 0000000000..c15c41d3bc
--- /dev/null
+++ b/packages/providers/src/community/pi/ui-context-stub.test.ts
@@ -0,0 +1,137 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { MessageChunk } from '../../types';
+
+import { createArchonUIBridge, createArchonUIContext } from './ui-context-stub';
+
+describe('createArchonUIBridge', () => {
+  test('drops notifications when no emitter is set', () => {
+    const bridge = createArchonUIBridge();
+    expect(() => bridge.emit({ type: 'system', content: 'x' })).not.toThrow();
+  });
+
+  test('forwards notifications to the configured emitter', () => {
+    const bridge = createArchonUIBridge();
+    const chunks: MessageChunk[] = [];
+    bridge.setEmitter(c => chunks.push(c));
+    bridge.emit({ type: 'system', content: 'hello' });
+    expect(chunks).toEqual([{ type: 'system', content: 'hello' }]);
+  });
+
+  test('detaches emitter when cleared (bridgeSession cleanup path)', () => {
+    const bridge = createArchonUIBridge();
+    const chunks: MessageChunk[] = [];
+    bridge.setEmitter(c => chunks.push(c));
+    bridge.setEmitter(undefined);
+    bridge.emit({ type: 'system', content: 'late' });
+    expect(chunks).toEqual([]);
+  });
+});
+
+describe('createArchonUIContext', () => {
+  function mk() {
+    const bridge = createArchonUIBridge();
+    const chunks: MessageChunk[] = [];
+    bridge.setEmitter(c => chunks.push(c));
+    const ui = createArchonUIContext(bridge);
+    return { ui, chunks };
+  }
+
+  test('notify("info") forwards as assistant chunk with info glyph and flush:true (captured in nodeOutput, surfaces before node blocks)', () => {
+    const { ui, chunks } = mk();
+    ui.notify('Remote session. Open: http://host:8080/', 'info');
+    expect(chunks).toHaveLength(1);
+    expect(chunks[0]).toEqual({
+      type: 'assistant',
+      content: '\n[pi extension ℹ️] Remote session. Open: http://host:8080/\n',
+      flush: true,
+    });
+  });
+
+  test('notify defaults to info when type omitted', () => {
+    const { ui, chunks } = mk();
+    ui.notify('bare message');
+    expect(chunks[0]?.content).toBe('\n[pi extension ℹ️] bare message\n');
+  });
+
+  test('notify("warning") and notify("error") use distinct glyphs', () => {
+    const { ui, chunks } = mk();
+    ui.notify('soft', 'warning');
+    ui.notify('hard', 'error');
+    expect(chunks[0]?.content).toBe('\n[pi extension ⚠️] soft\n');
+    expect(chunks[1]?.content).toBe('\n[pi extension ❌] hard\n');
+  });
+
+  test('select resolves to undefined (no operator to answer)', async () => {
+    const { ui } = mk();
+    await expect(ui.select('pick', ['a', 'b'])).resolves.toBeUndefined();
+  });
+
+  test('confirm resolves to false', async () => {
+    const { ui } = mk();
+    await expect(ui.confirm('are you sure?', 'really')).resolves.toBe(false);
+  });
+
+  test('input and editor resolve to undefined', async () => {
+    const { ui } = mk();
+    await expect(ui.input('title')).resolves.toBeUndefined();
+    await expect(ui.editor('title', 'prefill')).resolves.toBeUndefined();
+  });
+
+  test('custom resolves to undefined-cast', async () => {
+    const { ui } = mk();
+    const res = await ui.custom(() => ({}) as never);
+    expect(res).toBeUndefined();
+  });
+
+  test('getEditorText returns empty string', () => {
+    const { ui } = mk();
+    expect(ui.getEditorText()).toBe('');
+  });
+
+  test('getToolsExpanded returns false', () => {
+    const { ui } = mk();
+    expect(ui.getToolsExpanded()).toBe(false);
+  });
+
+  test('getAllThemes returns empty list and getTheme returns undefined', () => {
+    const { ui } = mk();
+    expect(ui.getAllThemes()).toEqual([]);
+    expect(ui.getTheme('anything')).toBeUndefined();
+  });
+
+  test('setTheme returns failure result without throwing', () => {
+    const { ui } = mk();
+    const result = ui.setTheme('dark');
+    expect(result.success).toBe(false);
+    expect(result.error).toBeDefined();
+  });
+
+  test('theme getter returns a proxy that throws on property access', () => {
+    const { ui } = mk();
+    const themeRef = ui.theme;
+    expect(() => themeRef.fg('accent', 'text')).toThrow(/Archon's remote UI stub/);
+  });
+
+  test('onTerminalInput returns a disposer that is safe to call', () => {
+    const { ui } = mk();
+    const dispose = ui.onTerminalInput(() => undefined);
+    expect(() => dispose()).not.toThrow();
+  });
+
+  test('TUI setters (setStatus/setWidget/setFooter/setHeader/setTitle) are no-ops', () => {
+    const { ui, chunks } = mk();
+    expect(() => ui.setStatus('k', 'v')).not.toThrow();
+    expect(() => ui.setWidget('k', ['line'])).not.toThrow();
+    expect(() => ui.setFooter(undefined)).not.toThrow();
+    expect(() => ui.setHeader(undefined)).not.toThrow();
+    expect(() => ui.setTitle('title')).not.toThrow();
+    expect(() => ui.setWorkingMessage('working')).not.toThrow();
+    expect(() => ui.setHiddenThinkingLabel('label')).not.toThrow();
+    expect(() => ui.pasteToEditor('text')).not.toThrow();
+    expect(() => ui.setEditorText('text')).not.toThrow();
+    expect(() => ui.setEditorComponent(undefined)).not.toThrow();
+    expect(() => ui.setToolsExpanded(true)).not.toThrow();
+    expect(chunks).toEqual([]);
+  });
+});
diff --git a/packages/providers/src/community/pi/ui-context-stub.ts b/packages/providers/src/community/pi/ui-context-stub.ts
new file mode 100644
index 0000000000..99f18c63c5
--- /dev/null
+++ b/packages/providers/src/community/pi/ui-context-stub.ts
@@ -0,0 +1,160 @@
+import type {
+  ExtensionUIContext,
+  ExtensionUIDialogOptions,
+  ExtensionWidgetOptions,
+  TerminalInputHandler,
+} from '@mariozechner/pi-coding-agent';
+import { Theme } from '@mariozechner/pi-coding-agent';
+
+import type { MessageChunk } from '../../types';
+
+/** Pushes UI notifications into Archon's event stream. Set/cleared by bridgeSession. */
+export interface ArchonUIBridge {
+  emit(chunk: MessageChunk): void;
+  setEmitter(fn: ((chunk: MessageChunk) => void) | undefined): void;
+}
+
+export function createArchonUIBridge(): ArchonUIBridge {
+  let emitter: ((chunk: MessageChunk) => void) | undefined;
+  return {
+    emit(chunk: MessageChunk): void {
+      emitter?.(chunk);
+    },
+    setEmitter(fn: ((chunk: MessageChunk) => void) | undefined): void {
+      emitter = fn;
+    },
+  };
+}
+
+const noop = (): void => {
+  /* no-op — TUI-only setter, nothing to paint into */
+};
+
+/**
+ * Minimal ExtensionUIContext for Archon's headless Pi sessions. Binding this
+ * (vs Pi's internal `noOpUIContext`) flips `ctx.hasUI` to true so extensions
+ * like plannotator surface UI flows. `notify()` forwards to the event stream;
+ * interactive prompts resolve to undefined/false; TUI setters no-op; `theme`
+ * returns identity decorators — the styled strings get passed into no-op
+ * setStatus/setWidget sinks anyway, so stripping ANSI styling is safe and
+ * keeps extensions like plannotator from crashing mid-tool-call.
+ */
+export function createArchonUIContext(bridge: ArchonUIBridge): ExtensionUIContext {
+  // Pick the last string argument — handles `fg(color, text)`, `bold(text)`,
+  // `strikethrough(text)`, etc. in a single handler.
+  const lastStringArg = (...args: unknown[]): string => {
+    for (let i = args.length - 1; i >= 0; i--) {
+      if (typeof args[i] === 'string') return args[i] as string;
+    }
+    return '';
+  };
+  const passthroughWrap =
+    (_level: unknown): ((s: string) => string) =>
+    (s: string) =>
+      s;
+  const themeProxy = new Proxy({} as Theme, {
+    get(_target: Theme, prop: string | symbol): unknown {
+      if (prop === 'getColorMode') return () => 'truecolor';
+      if (prop === 'getFgAnsi' || prop === 'getBgAnsi') return () => '';
+      if (prop === 'getThinkingBorderColor' || prop === 'getBashModeBorderColor') {
+        return passthroughWrap;
+      }
+      if (prop === 'name' || prop === 'sourcePath' || prop === 'sourceInfo') return undefined;
+      return lastStringArg;
+    },
+  });
+
+  return {
+    select(
+      _title: string,
+      _options: string[],
+      _opts?: ExtensionUIDialogOptions
+    ): Promise<string | undefined> {
+      return Promise.resolve(undefined);
+    },
+    confirm(_title: string, _message: string, _opts?: ExtensionUIDialogOptions): Promise<boolean> {
+      return Promise.resolve(false);
+    },
+    input(
+      _title: string,
+      _placeholder?: string,
+      _opts?: ExtensionUIDialogOptions
+    ): Promise<string | undefined> {
+      return Promise.resolve(undefined);
+    },
+    notify(message: string, type: 'info' | 'warning' | 'error' = 'info'): void {
+      // Emit as `assistant` (not `system`) so the content is captured into
+      // `$nodeId.output` for downstream bash/script nodes. System chunks are
+      // filtered to ⚠️/MCP-prefix only by the DAG executor.
+      // `flush: true` forces batch-mode adapters to surface this immediately —
+      // extensions like plannotator print review URLs the user must act on
+      // before the node unblocks, so we can't wait for node completion.
+      const icon = type === 'error' ? '❌' : type === 'warning' ? '⚠️' : 'ℹ️';
+      bridge.emit({
+        type: 'assistant',
+        content: `\n[pi extension ${icon}] ${message}\n`,
+        flush: true,
+      });
+    },
+    onTerminalInput(_handler: TerminalInputHandler): () => void {
+      return noop;
+    },
+    setStatus(_key: string, _text: string | undefined): void {
+      noop();
+    },
+    setWorkingMessage(_message?: string): void {
+      noop();
+    },
+    setHiddenThinkingLabel(_label?: string): void {
+      noop();
+    },
+    setWidget(_key: string, _content: unknown, _options?: ExtensionWidgetOptions): void {
+      noop();
+    },
+    setFooter(_factory: Parameters<ExtensionUIContext['setFooter']>[0]): void {
+      noop();
+    },
+    setHeader(_factory: Parameters<ExtensionUIContext['setHeader']>[0]): void {
+      noop();
+    },
+    setTitle(_title: string): void {
+      noop();
+    },
+    custom<T>(): Promise<T> {
+      return Promise.resolve(undefined as unknown as T);
+    },
+    pasteToEditor(_text: string): void {
+      noop();
+    },
+    setEditorText(_text: string): void {
+      noop();
+    },
+    getEditorText(): string {
+      return '';
+    },
+    editor(_title: string, _prefill?: string): Promise<string | undefined> {
+      return Promise.resolve(undefined);
+    },
+    setEditorComponent(_factory: Parameters<ExtensionUIContext['setEditorComponent']>[0]): void {
+      noop();
+    },
+    get theme(): Theme {
+      return themeProxy;
+    },
+    getAllThemes(): ReturnType<ExtensionUIContext['getAllThemes']> {
+      return [];
+    },
+    getTheme(_name: string): Theme | undefined {
+      return undefined;
+    },
+    setTheme(_theme: string | Theme): { success: boolean; error?: string } {
+      return { success: false, error: 'Theme switching not supported in Archon remote UI stub' };
+    },
+    getToolsExpanded(): boolean {
+      return false;
+    },
+    setToolsExpanded(_expanded: boolean): void {
+      noop();
+    },
+  };
+}
diff --git a/packages/providers/src/errors.ts b/packages/providers/src/errors.ts
new file mode 100644
index 0000000000..15849d3c92
--- /dev/null
+++ b/packages/providers/src/errors.ts
@@ -0,0 +1,14 @@
+/**
+ * Standardized error for unknown provider types.
+ * Thrown by getAgentProvider() — all surfaces (CLI, server, orchestrator, workflows)
+ * get the same error shape and message format.
+ */
+export class UnknownProviderError extends Error {
+  constructor(
+    public readonly requestedProvider: string,
+    public readonly registeredProviders: string[]
+  ) {
+    super(`Unknown provider: '${requestedProvider}'. Available: ${registeredProviders.join(', ')}`);
+    this.name = 'UnknownProviderError';
+  }
+}
diff --git a/packages/providers/src/index.ts b/packages/providers/src/index.ts
new file mode 100644
index 0000000000..d430f8d402
--- /dev/null
+++ b/packages/providers/src/index.ts
@@ -0,0 +1,55 @@
+// Types (contract layer — re-exported for convenience)
+export type {
+  IAgentProvider,
+  AgentRequestOptions,
+  SendQueryOptions,
+  NodeConfig,
+  ProviderDefaults,
+  ProviderDefaultsMap,
+  ProviderCapabilities,
+  ProviderRegistration,
+  ProviderInfo,
+  MessageChunk,
+  TokenUsage,
+} from './types';
+
+// Provider config types (canonical definitions in ./types, re-exported via config modules)
+// Import from ./types directly or from the config modules — both work.
+
+// Registry
+export {
+  registerProvider,
+  getAgentProvider,
+  getRegistration,
+  getProviderCapabilities,
+  getRegisteredProviders,
+  getProviderInfoList,
+  isRegisteredProvider,
+  registerBuiltinProviders,
+  registerCommunityProviders,
+  clearRegistry,
+} from './registry';
+
+// Error
+export { UnknownProviderError } from './errors';
+
+// Provider classes
+export { ClaudeProvider } from './claude/provider';
+export { CodexProvider } from './codex/provider';
+
+// Config parsers
+export { parseClaudeConfig, type ClaudeProviderDefaults } from './claude/config';
+export { parseCodexConfig, type CodexProviderDefaults } from './codex/config';
+
+// Utilities (needed by consumers)
+export { resetCodexSingleton } from './codex/provider';
+export { resolveCodexBinaryPath, fileExists as codexFileExists } from './codex/binary-resolver';
+export { resolveClaudeBinaryPath, fileExists as claudeFileExists } from './claude/binary-resolver';
+
+// Community providers
+export {
+  PiProvider,
+  parsePiConfig,
+  registerPiProvider,
+  type PiProviderDefaults,
+} from './community/pi';
diff --git a/packages/providers/src/registry.test.ts b/packages/providers/src/registry.test.ts
new file mode 100644
index 0000000000..64b879a91c
--- /dev/null
+++ b/packages/providers/src/registry.test.ts
@@ -0,0 +1,355 @@
+import { describe, test, expect, beforeEach } from 'bun:test';
+import {
+  getAgentProvider,
+  getProviderCapabilities,
+  registerProvider,
+  getRegistration,
+  getRegisteredProviders,
+  getProviderInfoList,
+  isRegisteredProvider,
+  registerBuiltinProviders,
+  registerCommunityProviders,
+  clearRegistry,
+} from './registry';
+import { registerPiProvider } from './community/pi/registration';
+import { UnknownProviderError } from './errors';
+import type { ProviderRegistration, IAgentProvider, ProviderCapabilities } from './types';
+
+/** Minimal mock provider for testing registration. */
+function makeMockProvider(id: string): IAgentProvider {
+  return {
+    getType: () => id,
+    getCapabilities: () => ({
+      sessionResume: false,
+      mcp: false,
+      hooks: false,
+      skills: false,
+      agents: false,
+      toolRestrictions: false,
+      structuredOutput: false,
+      envInjection: false,
+      costControl: false,
+      effortControl: false,
+      thinkingControl: false,
+      fallbackModel: false,
+      sandbox: false,
+    }),
+    async *sendQuery() {
+      yield { type: 'result' as const };
+    },
+  };
+}
+
+function makeMockRegistration(
+  id: string,
+  overrides?: Partial<ProviderRegistration>
+): ProviderRegistration {
+  return {
+    id,
+    displayName: `Mock ${id}`,
+    factory: () => makeMockProvider(id),
+    capabilities: makeMockProvider(id).getCapabilities(),
+    isModelCompatible: () => true,
+    builtIn: false,
+    ...overrides,
+  };
+}
+
+describe('registry', () => {
+  beforeEach(() => {
+    clearRegistry();
+    registerBuiltinProviders();
+  });
+
+  describe('getAgentProvider', () => {
+    test('returns ClaudeProvider for claude type', () => {
+      const provider = getAgentProvider('claude');
+
+      expect(provider).toBeDefined();
+      expect(provider.getType()).toBe('claude');
+      expect(typeof provider.sendQuery).toBe('function');
+    });
+
+    test('returns CodexProvider for codex type', () => {
+      const provider = getAgentProvider('codex');
+
+      expect(provider).toBeDefined();
+      expect(provider.getType()).toBe('codex');
+      expect(typeof provider.sendQuery).toBe('function');
+    });
+
+    test('throws UnknownProviderError for unknown type', () => {
+      expect(() => getAgentProvider('unknown')).toThrow(UnknownProviderError);
+      expect(() => getAgentProvider('unknown')).toThrow(
+        "Unknown provider: 'unknown'. Available: claude, codex"
+      );
+    });
+
+    test('throws UnknownProviderError for empty string', () => {
+      expect(() => getAgentProvider('')).toThrow(UnknownProviderError);
+      expect(() => getAgentProvider('')).toThrow("Unknown provider: ''");
+    });
+
+    test('is case sensitive - Claude throws', () => {
+      expect(() => getAgentProvider('Claude')).toThrow(UnknownProviderError);
+      expect(() => getAgentProvider('Claude')).toThrow("Unknown provider: 'Claude'");
+    });
+
+    test('each call returns new instance', () => {
+      const provider1 = getAgentProvider('claude');
+      const provider2 = getAgentProvider('claude');
+
+      expect(provider1).not.toBe(provider2);
+    });
+
+    test('providers expose getCapabilities', () => {
+      const claude = getAgentProvider('claude');
+      const codex = getAgentProvider('codex');
+
+      expect(typeof claude.getCapabilities).toBe('function');
+      expect(typeof codex.getCapabilities).toBe('function');
+
+      const claudeCaps = claude.getCapabilities();
+      const codexCaps = codex.getCapabilities();
+
+      expect(claudeCaps.mcp).toBe(true);
+      expect(codexCaps.mcp).toBe(false);
+      expect(claudeCaps.hooks).toBe(true);
+      expect(codexCaps.hooks).toBe(false);
+    });
+  });
+
+  describe('getProviderCapabilities', () => {
+    test('returns Claude capabilities without instantiation', () => {
+      const caps = getProviderCapabilities('claude');
+      expect(caps.mcp).toBe(true);
+      expect(caps.hooks).toBe(true);
+      expect(caps.envInjection).toBe(true);
+    });
+
+    test('returns Codex capabilities without instantiation', () => {
+      const caps = getProviderCapabilities('codex');
+      expect(caps.mcp).toBe(false);
+      expect(caps.hooks).toBe(false);
+      expect(caps.envInjection).toBe(true);
+    });
+
+    test('matches runtime getCapabilities for Claude', () => {
+      const staticCaps = getProviderCapabilities('claude');
+      const runtimeCaps = getAgentProvider('claude').getCapabilities();
+      expect(staticCaps).toEqual(runtimeCaps);
+    });
+
+    test('matches runtime getCapabilities for Codex', () => {
+      const staticCaps = getProviderCapabilities('codex');
+      const runtimeCaps = getAgentProvider('codex').getCapabilities();
+      expect(staticCaps).toEqual(runtimeCaps);
+    });
+
+    test('throws UnknownProviderError for unknown type', () => {
+      expect(() => getProviderCapabilities('unknown')).toThrow(UnknownProviderError);
+    });
+
+    test('throws UnknownProviderError for empty string', () => {
+      expect(() => getProviderCapabilities('')).toThrow(UnknownProviderError);
+    });
+
+    test('is case sensitive - Claude throws', () => {
+      expect(() => getProviderCapabilities('Claude')).toThrow(UnknownProviderError);
+    });
+  });
+
+  describe('registerProvider', () => {
+    test('registers a new provider', () => {
+      const entry = makeMockRegistration('my-llm');
+      registerProvider(entry);
+
+      expect(isRegisteredProvider('my-llm')).toBe(true);
+      const provider = getAgentProvider('my-llm');
+      expect(provider.getType()).toBe('my-llm');
+    });
+
+    test('throws on duplicate registration', () => {
+      expect(() => registerProvider(makeMockRegistration('claude'))).toThrow(
+        "Provider 'claude' is already registered"
+      );
+    });
+  });
+
+  describe('getRegistration', () => {
+    test('returns full registration entry', () => {
+      const reg = getRegistration('claude');
+      expect(reg.id).toBe('claude');
+      expect(reg.displayName).toBe('Claude (Anthropic)');
+      expect(reg.builtIn).toBe(true);
+      expect(typeof reg.factory).toBe('function');
+      expect(typeof reg.isModelCompatible).toBe('function');
+    });
+
+    test('throws for unknown provider', () => {
+      expect(() => getRegistration('nope')).toThrow(UnknownProviderError);
+    });
+  });
+
+  describe('getRegisteredProviders', () => {
+    test('returns all registered providers', () => {
+      const all = getRegisteredProviders();
+      expect(all.length).toBe(2);
+      const ids = all.map(r => r.id);
+      expect(ids).toContain('claude');
+      expect(ids).toContain('codex');
+    });
+
+    test('includes community providers after registration', () => {
+      registerProvider(makeMockRegistration('my-llm'));
+      const all = getRegisteredProviders();
+      expect(all.length).toBe(3);
+    });
+  });
+
+  describe('getProviderInfoList', () => {
+    test('returns API-safe projection without factory', () => {
+      const infos = getProviderInfoList();
+      expect(infos.length).toBe(2);
+      for (const info of infos) {
+        expect(info).toHaveProperty('id');
+        expect(info).toHaveProperty('displayName');
+        expect(info).toHaveProperty('capabilities');
+        expect(info).toHaveProperty('builtIn');
+        expect(info).not.toHaveProperty('factory');
+        expect(info).not.toHaveProperty('isModelCompatible');
+      }
+    });
+  });
+
+  describe('isRegisteredProvider', () => {
+    test('returns true for registered providers', () => {
+      expect(isRegisteredProvider('claude')).toBe(true);
+      expect(isRegisteredProvider('codex')).toBe(true);
+    });
+
+    test('returns false for unknown providers', () => {
+      expect(isRegisteredProvider('unknown')).toBe(false);
+      expect(isRegisteredProvider('')).toBe(false);
+    });
+  });
+
+  describe('registerBuiltinProviders', () => {
+    test('is idempotent', () => {
+      registerBuiltinProviders();
+      registerBuiltinProviders();
+      const all = getRegisteredProviders();
+      expect(all.length).toBe(2);
+    });
+  });
+
+  describe('clearRegistry', () => {
+    test('empties the registry', () => {
+      clearRegistry();
+      expect(getRegisteredProviders()).toEqual([]);
+      expect(isRegisteredProvider('claude')).toBe(false);
+    });
+  });
+
+  describe('built-in model compatibility', () => {
+    test('Claude registration matches Claude model patterns', () => {
+      const reg = getRegistration('claude');
+      expect(reg.isModelCompatible('sonnet')).toBe(true);
+      expect(reg.isModelCompatible('opus')).toBe(true);
+      expect(reg.isModelCompatible('haiku')).toBe(true);
+      expect(reg.isModelCompatible('inherit')).toBe(true);
+      expect(reg.isModelCompatible('claude-3.5-sonnet')).toBe(true);
+      expect(reg.isModelCompatible('gpt-4')).toBe(false);
+    });
+
+    test('Codex registration rejects Claude model patterns', () => {
+      const reg = getRegistration('codex');
+      expect(reg.isModelCompatible('sonnet')).toBe(false);
+      expect(reg.isModelCompatible('claude-3.5-sonnet')).toBe(false);
+      expect(reg.isModelCompatible('inherit')).toBe(false);
+      expect(reg.isModelCompatible('gpt-4')).toBe(true);
+      expect(reg.isModelCompatible('o3-mini')).toBe(true);
+    });
+  });
+
+  describe('registerCommunityProviders (aggregator)', () => {
+    test('registers all bundled community providers', () => {
+      registerCommunityProviders();
+      // Pi is currently the only community provider bundled. When more are
+      // added, they should appear here automatically.
+      expect(isRegisteredProvider('pi')).toBe(true);
+    });
+
+    test('is idempotent', () => {
+      registerCommunityProviders();
+      expect(() => registerCommunityProviders()).not.toThrow();
+      const piCount = getRegisteredProviders().filter(p => p.id === 'pi').length;
+      expect(piCount).toBe(1);
+    });
+  });
+
+  describe('registerPiProvider (community provider)', () => {
+    test('registers pi with builtIn: false', () => {
+      registerPiProvider();
+      const reg = getRegistration('pi');
+      expect(reg.id).toBe('pi');
+      expect(reg.displayName).toBe('Pi (community)');
+      expect(reg.builtIn).toBe(false);
+    });
+
+    test('is idempotent', () => {
+      registerPiProvider();
+      expect(() => registerPiProvider()).not.toThrow();
+      const piEntries = getRegisteredProviders().filter(p => p.id === 'pi');
+      expect(piEntries).toHaveLength(1);
+    });
+
+    test('declares v2 capabilities (thinking, effort, tools, skills, sessionResume, envInjection, structuredOutput supported)', () => {
+      registerPiProvider();
+      const caps = getProviderCapabilities('pi');
+      // Flipped true in v2
+      expect(caps.thinkingControl).toBe(true);
+      expect(caps.effortControl).toBe(true);
+      expect(caps.toolRestrictions).toBe(true);
+      expect(caps.skills).toBe(true);
+      expect(caps.sessionResume).toBe(true);
+      expect(caps.envInjection).toBe(true);
+      // Best-effort structured output via prompt engineering + post-parse —
+      // not SDK-enforced like Claude/Codex, but wired up and tested.
+      expect(caps.structuredOutput).toBe(true);
+      // Still false (out of v2 scope)
+      expect(caps.mcp).toBe(false);
+      expect(caps.hooks).toBe(false);
+      expect(caps.costControl).toBe(false);
+      expect(caps.fallbackModel).toBe(false);
+      expect(caps.sandbox).toBe(false);
+    });
+
+    test('isModelCompatible accepts provider/model refs, rejects aliases', () => {
+      registerPiProvider();
+      const reg = getRegistration('pi');
+      expect(reg.isModelCompatible('google/gemini-2.5-pro')).toBe(true);
+      expect(reg.isModelCompatible('anthropic/claude-opus-4-5')).toBe(true);
+      expect(reg.isModelCompatible('openrouter/qwen/qwen3-coder')).toBe(true);
+      expect(reg.isModelCompatible('sonnet')).toBe(false);
+      expect(reg.isModelCompatible('claude-3.5-sonnet')).toBe(false);
+      expect(reg.isModelCompatible('')).toBe(false);
+    });
+
+    test('appears in getProviderInfoList with builtIn: false', () => {
+      registerPiProvider();
+      const info = getProviderInfoList().find(p => p.id === 'pi');
+      expect(info).toBeDefined();
+      expect(info?.builtIn).toBe(false);
+    });
+
+    test('does not collide with built-ins', () => {
+      // beforeEach already called registerBuiltinProviders + clearRegistry reset
+      registerPiProvider();
+      const ids = getRegisteredProviders()
+        .map(p => p.id)
+        .sort();
+      expect(ids).toEqual(['claude', 'codex', 'pi']);
+    });
+  });
+});
diff --git a/packages/providers/src/registry.ts b/packages/providers/src/registry.ts
new file mode 100644
index 0000000000..1ae16759dc
--- /dev/null
+++ b/packages/providers/src/registry.ts
@@ -0,0 +1,171 @@
+/**
+ * Provider Registry
+ *
+ * Typed registry where each entry is a ProviderRegistration record (factory + metadata).
+ * Replaces the hardcoded factory switch from Phase 1.
+ *
+ * Bootstrap: callers must call registerBuiltinProviders() at process entrypoints
+ * (server startup, CLI init) before any provider lookups.
+ */
+import type {
+  IAgentProvider,
+  ProviderCapabilities,
+  ProviderRegistration,
+  ProviderInfo,
+} from './types';
+import { ClaudeProvider } from './claude/provider';
+import { CodexProvider } from './codex/provider';
+import { CLAUDE_CAPABILITIES } from './claude/capabilities';
+import { CODEX_CAPABILITIES } from './codex/capabilities';
+import { registerPiProvider } from './community/pi/registration';
+import { UnknownProviderError } from './errors';
+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('provider.registry');
+  return cachedLog;
+}
+
+/** Backing store for registered providers. */
+const registry = new Map<string, ProviderRegistration>();
+
+/**
+ * Register a provider. Throws on duplicate registration.
+ */
+export function registerProvider(entry: ProviderRegistration): void {
+  if (registry.has(entry.id)) {
+    throw new Error(`Provider '${entry.id}' is already registered`);
+  }
+  registry.set(entry.id, entry);
+  getLog().debug({ provider: entry.id, builtIn: entry.builtIn }, 'provider.registered');
+}
+
+/**
+ * Get an instantiated agent provider by ID.
+ * @throws UnknownProviderError if not registered
+ */
+export function getAgentProvider(id: string): IAgentProvider {
+  const entry = registry.get(id);
+  if (!entry) {
+    throw new UnknownProviderError(id, [...registry.keys()]);
+  }
+  getLog().debug({ provider: id }, 'provider_selected');
+  return entry.factory();
+}
+
+/**
+ * Get the full registration entry for a provider.
+ * @throws UnknownProviderError if not registered
+ */
+export function getRegistration(id: string): ProviderRegistration {
+  const entry = registry.get(id);
+  if (!entry) {
+    throw new UnknownProviderError(id, [...registry.keys()]);
+  }
+  return entry;
+}
+
+/**
+ * Get provider capabilities without instantiating a provider.
+ * @throws UnknownProviderError if not registered
+ */
+export function getProviderCapabilities(id: string): ProviderCapabilities {
+  return getRegistration(id).capabilities;
+}
+
+/**
+ * Get all registered providers.
+ */
+export function getRegisteredProviders(): ProviderRegistration[] {
+  return [...registry.values()];
+}
+
+/**
+ * Get API-safe provider info (excludes factory and isModelCompatible).
+ */
+export function getProviderInfoList(): ProviderInfo[] {
+  return getRegisteredProviders().map(({ id, displayName, capabilities, builtIn }) => ({
+    id,
+    displayName,
+    capabilities,
+    builtIn,
+  }));
+}
+
+/**
+ * Check if a provider is registered.
+ */
+export function isRegisteredProvider(id: string): boolean {
+  return registry.has(id);
+}
+
+/**
+ * Register built-in providers (Claude, Codex). Idempotent — skips already-registered IDs.
+ * Must be called at process entrypoints (server, CLI) before any provider lookups.
+ */
+export function registerBuiltinProviders(): void {
+  const builtins: ProviderRegistration[] = [
+    {
+      id: 'claude',
+      displayName: 'Claude (Anthropic)',
+      factory: () => new ClaudeProvider(),
+      capabilities: CLAUDE_CAPABILITIES,
+      isModelCompatible: (model: string): boolean => {
+        const aliases = ['sonnet', 'opus', 'haiku'];
+        return aliases.includes(model) || model.startsWith('claude-') || model === 'inherit';
+      },
+      builtIn: true,
+    },
+    {
+      id: 'codex',
+      displayName: 'Codex (OpenAI)',
+      factory: () => new CodexProvider(),
+      capabilities: CODEX_CAPABILITIES,
+      isModelCompatible: (model: string): boolean => {
+        const claudeAliases = ['sonnet', 'opus', 'haiku'];
+        return (
+          !claudeAliases.includes(model) && !model.startsWith('claude-') && model !== 'inherit'
+        );
+      },
+      builtIn: true,
+    },
+  ];
+
+  for (const entry of builtins) {
+    if (!registry.has(entry.id)) {
+      registry.set(entry.id, entry);
+      getLog().debug({ provider: entry.id }, 'builtin_provider.registered');
+    }
+  }
+}
+
+/**
+ * Register all bundled community providers in one call.
+ *
+ * Process entrypoints (server, CLI, config-loader) call this once after
+ * `registerBuiltinProviders()`. Adding a new community provider means:
+ *   1. Drop the implementation under `packages/providers/src/community/<id>/`.
+ *   2. Export a `register<Name>Provider()` function from it.
+ *   3. Import + call it here.
+ *
+ * That's the entire cross-cutting change outside the provider's own
+ * directory. No entrypoint edits, no config-type edits — just add a line
+ * to this function. That's the Phase 2 contract (#1195): community
+ * providers are a localized addition.
+ *
+ * Each `register*Provider` is itself idempotent, so calling this
+ * aggregator multiple times (e.g. from both CLI and config-loader paths)
+ * is safe. Errors during registration are not caught here — a broken
+ * community provider should fail loud at bootstrap, not silently
+ * disappear.
+ */
+export function registerCommunityProviders(): void {
+  registerPiProvider();
+}
+
+/** @internal Test-only — clears the registry. Not for production use. */
+export function clearRegistry(): void {
+  registry.clear();
+}
diff --git a/packages/providers/src/test/mocks/logger.ts b/packages/providers/src/test/mocks/logger.ts
new file mode 100644
index 0000000000..79e1198b8a
--- /dev/null
+++ b/packages/providers/src/test/mocks/logger.ts
@@ -0,0 +1,28 @@
+import { mock } from 'bun:test';
+import type { Logger } from 'pino';
+
+export interface MockLogger extends Logger {
+  fatal: ReturnType<typeof mock>;
+  error: ReturnType<typeof mock>;
+  warn: ReturnType<typeof mock>;
+  info: ReturnType<typeof mock>;
+  debug: ReturnType<typeof mock>;
+  trace: ReturnType<typeof mock>;
+  child: ReturnType<typeof mock>;
+}
+
+export function createMockLogger(): MockLogger {
+  const logger = {
+    fatal: mock(() => undefined),
+    error: mock(() => undefined),
+    warn: mock(() => undefined),
+    info: mock(() => undefined),
+    debug: mock(() => undefined),
+    trace: mock(() => undefined),
+    child: mock(() => logger),
+    bindings: mock(() => ({ module: 'test' })),
+    isLevelEnabled: mock(() => true),
+    level: 'info',
+  } as unknown as MockLogger;
+  return logger;
+}
diff --git a/packages/providers/src/types.ts b/packages/providers/src/types.ts
new file mode 100644
index 0000000000..d6cb8b4a87
--- /dev/null
+++ b/packages/providers/src/types.ts
@@ -0,0 +1,319 @@
+// CONTRACT LAYER — no SDK imports, no runtime deps.
+// @archon/workflows and @archon/core import from this subpath (@archon/providers/types).
+// HARD RULE: This file must never import SDK packages or other @archon/* packages.
+
+// ─── Provider Config Defaults ──────────────────────────────────────────────
+// Canonical definitions — @archon/core/config/config-types.ts imports from here.
+// Single source of truth for provider-specific config shapes.
+
+export interface ClaudeProviderDefaults {
+  [key: string]: unknown;
+  model?: string;
+  /** Claude Code settingSources — controls which CLAUDE.md files are loaded.
+   *  @default ['project']
+   */
+  settingSources?: ('project' | 'user')[];
+  /** Absolute path to the Claude Code SDK's `cli.js`. Required in compiled
+   *  Archon builds when `CLAUDE_BIN_PATH` is not set; optional in dev mode
+   *  (SDK resolves from node_modules). */
+  claudeBinaryPath?: string;
+}
+
+export interface CodexProviderDefaults {
+  [key: string]: unknown;
+  model?: string;
+  /** Structurally matches @archon/workflows ModelReasoningEffort */
+  modelReasoningEffort?: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+  /** Structurally matches @archon/workflows WebSearchMode */
+  webSearchMode?: 'disabled' | 'cached' | 'live';
+  additionalDirectories?: string[];
+  /** Path to the Codex CLI binary. Overrides auto-detection in compiled Archon builds. */
+  codexBinaryPath?: string;
+}
+
+/**
+ * Community provider defaults for Pi (@mariozechner/pi-coding-agent).
+ * v1 minimal shape; extend as capabilities are wired in.
+ */
+export interface PiProviderDefaults {
+  [key: string]: unknown;
+  /** Default model ref in '<pi-provider-id>/<model-id>' format, e.g. 'google/gemini-2.5-pro' */
+  model?: string;
+  /**
+   * Opt-in to Pi's extension discovery (tools + lifecycle hooks from community
+   * packages — see https://shittycodingagent.ai/packages). When true, Pi loads
+   * extensions from `~/.pi/agent/extensions/`, `~/.pi/agent/settings.json`
+   * packages, AND the workflow's cwd (`<cwd>/.pi/extensions/`,
+   * `<cwd>/.pi/settings.json`). The cwd scope is the risky one — a workflow
+   * running against an untrusted repo can auto-load whatever extension code
+   * that repo ships. Disabled by default to preserve the "Archon is source of
+   * truth" trust boundary. Flip to true only on hosts whose workflows run
+   * against repos you trust.
+   * @default false
+   */
+  enableExtensions?: boolean;
+  /**
+   * Bind an `ExtensionUIContext` so extensions see `ctx.hasUI === true` and
+   * `ctx.ui.notify()` forwards into the chunk stream. Ignored unless
+   * `enableExtensions` is true.
+   * @default false
+   */
+  interactive?: boolean;
+  /**
+   * Flag values passed to Pi's ExtensionRunner before `session_start`,
+   * equivalent to `pi --<name>` / `pi --<name>=<value>` on the CLI.
+   * Unknown keys are ignored. Only applied when `enableExtensions` is true.
+   * @default undefined
+   */
+  extensionFlags?: Record<string, boolean | string>;
+  /**
+   * Environment variables injected into `process.env` at session start so
+   * in-process extensions (which read `process.env` directly) pick them up.
+   * Existing `process.env` entries are NOT overridden — shell env wins over
+   * config. Use for extension-config vars like `PLANNOTATOR_REMOTE=1` that
+   * must be present before the extension's `session_start` hook runs.
+   *
+   * Note: this differs from `requestOptions.env` (codebase-scoped env vars),
+   * which is per-request and only injected into bash subprocesses. Use
+   * codebase env vars for secrets that vary per project; use `assistants.pi.env`
+   * for extension wiring that's global to the Pi provider.
+   * @default undefined
+   */
+  env?: Record<string, string>;
+}
+
+/** Generic per-provider defaults bag used by config surfaces and UI. */
+export type ProviderDefaults = Record<string, unknown>;
+
+/** Provider-keyed defaults map. Built-ins may refine individual entries. */
+export type ProviderDefaultsMap = Record<string, ProviderDefaults>;
+
+/**
+ * Token usage statistics from AI provider responses.
+ */
+export interface TokenUsage {
+  input: number;
+  output: number;
+  total?: number;
+  cost?: number;
+}
+
+/**
+ * Message chunk from AI assistant.
+ * Discriminated union with per-type required fields for type safety.
+ */
+export type MessageChunk =
+  | {
+      type: 'assistant';
+      content: string;
+      /** When true, batch-mode adapters flush pending content and this chunk
+       *  to the platform immediately. Used by Pi's `notify()` so URLs the
+       *  user must act on (e.g. plannotator review) surface before the node
+       *  blocks for input. */
+      flush?: boolean;
+    }
+  | { type: 'system'; content: string }
+  | { type: 'thinking'; content: string }
+  | {
+      type: 'result';
+      sessionId?: string;
+      tokens?: TokenUsage;
+      structuredOutput?: unknown;
+      isError?: boolean;
+      errorSubtype?: string;
+      /** SDK-provided error detail strings. Populated when isError is true. */
+      errors?: string[];
+      cost?: number;
+      stopReason?: string;
+      numTurns?: number;
+      modelUsage?: Record<string, unknown>;
+    }
+  | { type: 'rate_limit'; rateLimitInfo: Record<string, unknown> }
+  | {
+      type: 'tool';
+      toolName: string;
+      toolInput?: Record<string, unknown>;
+      /** Stable per-call ID from the underlying SDK (e.g. Claude `tool_use_id`).
+       *  When present, the platform adapter uses it directly instead of generating
+       *  one — guarantees `tool_call`/`tool_result` pair correctly even when
+       *  multiple tools with the same name run concurrently. */
+      toolCallId?: string;
+    }
+  | {
+      type: 'tool_result';
+      toolName: string;
+      toolOutput: string;
+      /** Matching ID for the originating `tool` chunk. See `tool` variant above. */
+      toolCallId?: string;
+    }
+  | { type: 'workflow_dispatch'; workerConversationId: string; workflowName: string };
+
+/**
+ * Universal request options accepted by all providers.
+ * Provider-specific fields go through `nodeConfig` and `assistantConfig` in SendQueryOptions.
+ */
+export interface AgentRequestOptions {
+  model?: string;
+  abortSignal?: AbortSignal;
+  systemPrompt?: string;
+  outputFormat?: { type: 'json_schema'; schema: Record<string, unknown> };
+  env?: Record<string, string>;
+  maxBudgetUsd?: number;
+  fallbackModel?: string;
+  /** Session fork flag — when true, copies prior session history before appending. */
+  forkSession?: boolean;
+  /** When false, skip writing session transcript to disk. */
+  persistSession?: boolean;
+}
+
+/**
+ * Raw node configuration from workflow YAML.
+ * Providers translate fields they understand; unknown fields are ignored.
+ */
+export interface NodeConfig {
+  mcp?: string;
+  hooks?: unknown;
+  skills?: string[];
+  /**
+   * Inline sub-agent definitions (keyed by kebab-case agent ID).
+   *
+   * Intentional hand-written duplicate of `agentDefinitionSchema` (authoritative
+   * source: `@archon/workflows/schemas/dag-node`). Normally we follow the
+   * project rule "derive types from Zod via `z.infer`, never write parallel
+   * interfaces" — broken here on purpose: `@archon/providers/types` is the
+   * contract subpath consumed by `@archon/workflows`, so importing from
+   * `@archon/workflows` would create a circular dependency.
+   *
+   * Drift risk: when the schema gains a field, this shape must be updated
+   * by hand. Follow-up work: extract the agent-definition contract to a
+   * lower-tier package so `z.infer` can be used end-to-end (#1276).
+   */
+  agents?: Record<
+    string,
+    {
+      description: string;
+      prompt: string;
+      model?: string;
+      tools?: string[];
+      disallowedTools?: string[];
+      skills?: string[];
+      maxTurns?: number;
+    }
+  >;
+  allowed_tools?: string[];
+  denied_tools?: string[];
+  effort?: string;
+  thinking?: unknown;
+  sandbox?: unknown;
+  betas?: string[];
+  output_format?: Record<string, unknown>;
+  maxBudgetUsd?: number;
+  systemPrompt?: string;
+  fallbackModel?: string;
+  idle_timeout?: number;
+  [key: string]: unknown;
+}
+
+/**
+ * Extended options for sendQuery, adding workflow-specific context.
+ * The orchestrator path uses base AgentRequestOptions fields only.
+ * The workflow path additionally passes nodeConfig and assistantConfig.
+ */
+export interface SendQueryOptions extends AgentRequestOptions {
+  /** Raw YAML node config — provider translates internally to SDK-specific options. */
+  nodeConfig?: NodeConfig;
+  /** Per-provider defaults from .archon/config.yaml assistants section. */
+  assistantConfig?: Record<string, unknown>;
+}
+
+/**
+ * Provider capability flags. The dag-executor uses these for capability warnings
+ * when a node specifies features the target provider doesn't support.
+ */
+export interface ProviderCapabilities {
+  sessionResume: boolean;
+  mcp: boolean;
+  hooks: boolean;
+  skills: boolean;
+  /** Whether the provider supports inline sub-agent definitions (Claude SDK's options.agents). */
+  agents: boolean;
+  toolRestrictions: boolean;
+  structuredOutput: boolean;
+  envInjection: boolean;
+  costControl: boolean;
+  effortControl: boolean;
+  thinkingControl: boolean;
+  fallbackModel: boolean;
+  sandbox: boolean;
+}
+
+/**
+ * Registration entry for a provider in the provider registry.
+ * Each entry carries metadata, a factory, and model-compatibility logic.
+ * The registry is the source of truth for provider identity, capabilities, and display.
+ */
+export interface ProviderRegistration {
+  /** Unique provider identifier — used in YAML, config, DB */
+  id: string;
+
+  /** Human-readable name for UI display */
+  displayName: string;
+
+  /** Instantiate a provider */
+  factory: () => IAgentProvider;
+
+  /** Static capability declaration — used for dag-executor warnings */
+  capabilities: ProviderCapabilities;
+
+  /**
+   * Model compatibility check. Returns true if the model string
+   * is valid for this provider. Used by workflow validation and
+   * provider inference from model names.
+   */
+  isModelCompatible: (model: string) => boolean;
+
+  /** Whether this is a built-in (maintained by core team) or community provider */
+  builtIn: boolean;
+}
+
+/**
+ * API-safe projection of ProviderRegistration (excludes non-serializable fields).
+ * Used by GET /api/providers and consumed by the Web UI.
+ */
+export interface ProviderInfo {
+  id: string;
+  displayName: string;
+  capabilities: ProviderCapabilities;
+  builtIn: boolean;
+}
+
+/**
+ * Generic agent provider interface.
+ * Allows supporting multiple agent providers (Claude, Codex, etc.)
+ */
+export interface IAgentProvider {
+  /**
+   * Send a message and get streaming response.
+   * @param prompt - User message or prompt
+   * @param cwd - Working directory for the provider
+   * @param resumeSessionId - Optional session ID to resume
+   * @param options - Optional request options (universal + nodeConfig + assistantConfig)
+   */
+  sendQuery(
+    prompt: string,
+    cwd: string,
+    resumeSessionId?: string,
+    options?: SendQueryOptions
+  ): AsyncGenerator<MessageChunk>;
+
+  /**
+   * Get the provider type identifier (e.g. 'claude', 'codex').
+   */
+  getType(): string;
+
+  /**
+   * Get the provider's capability flags.
+   * Used by the dag-executor to warn when nodes specify unsupported features.
+   */
+  getCapabilities(): ProviderCapabilities;
+}
diff --git a/packages/providers/tsconfig.json b/packages/providers/tsconfig.json
new file mode 100644
index 0000000000..144d879a1c
--- /dev/null
+++ b/packages/providers/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}
diff --git a/packages/server/package.json b/packages/server/package.json
index 58fd364c6f..4c99e4f88f 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -1,12 +1,12 @@
 {
   "name": "@archon/server",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "type": "module",
   "main": "./src/index.ts",
   "scripts": {
     "dev": "bun --watch src/index.ts",
     "start": "bun src/index.ts",
-    "test": "bun test src/routes/api.workflows.test.ts && bun test src/routes/api.conversations.test.ts && bun test src/routes/api.codebases.test.ts && bun test src/routes/api.messages.test.ts && bun test src/routes/api.health.test.ts && bun test src/routes/api.workflow-runs.test.ts && bun test src/adapters/web/transport.test.ts && bun test src/adapters/web/persistence.test.ts",
+    "test": "bun test src/routes/api.workflows.test.ts && bun test src/routes/api.conversations.test.ts && bun test src/routes/api.codebases.test.ts && bun test src/routes/api.messages.test.ts && bun test src/routes/api.health.test.ts && bun test src/routes/api.workflow-runs.test.ts && bun test src/routes/api.providers.test.ts && bun test src/adapters/web/transport.test.ts && bun test src/adapters/web/persistence.test.ts",
     "type-check": "bun x tsc --noEmit",
     "setup-auth": "bun src/scripts/setup-auth.ts"
   },
@@ -15,6 +15,7 @@
     "@archon/core": "workspace:*",
     "@archon/git": "workspace:*",
     "@archon/paths": "workspace:*",
+    "@archon/providers": "workspace:*",
     "@archon/workflows": "workspace:*",
     "@hono/zod-openapi": "^0.19.6",
     "dotenv": "^17.2.3",
diff --git a/packages/server/src/adapters/web.ts b/packages/server/src/adapters/web.ts
index 20570824e3..50d3c0e5f3 100644
--- a/packages/server/src/adapters/web.ts
+++ b/packages/server/src/adapters/web.ts
@@ -2,7 +2,8 @@
  * Web platform adapter implementing IPlatformAdapter with SSE stream management.
  * Bridge between the orchestrator and the React frontend via Server-Sent Events.
  */
-import type { IWebPlatformAdapter, MessageChunk, MessageMetadata } from '@archon/core';
+import type { IWebPlatformAdapter, MessageMetadata } from '@archon/core';
+import type { MessageChunk } from '@archon/providers/types';
 import { createLogger } from '@archon/paths';
 import { MessagePersistence } from './web/persistence';
 import { SSETransport, type SSEWriter } from './web/transport';
diff --git a/packages/server/src/index.ts b/packages/server/src/index.ts
index 0b502008d6..c1c76cf549 100644
--- a/packages/server/src/index.ts
+++ b/packages/server/src/index.ts
@@ -13,7 +13,7 @@ import '@archon/paths/strip-cwd-env-boot';
 import { config } from 'dotenv';
 import { resolve } from 'path';
 import { existsSync } from 'fs';
-import { BUNDLED_IS_BINARY } from '@archon/paths';
+import { BUNDLED_IS_BINARY, getArchonEnvPath } from '@archon/paths';
 
 // In dev/source mode, load the repo root .env (platform tokens, API keys, etc.)
 // import.meta.dir is frozen at build time, so skip in compiled binaries.
@@ -28,17 +28,12 @@ if (envPath) {
   }
 }
 
-// Load ~/.archon/.env with override — Archon's config always wins over any
-// Bun-auto-loaded CWD vars. In binary mode this is the single source of truth.
-// In dev mode it overrides CWD vars for keys like DATABASE_URL.
-const globalEnvPath = resolve(process.env.HOME ?? '~', '.archon', '.env');
-if (existsSync(globalEnvPath)) {
-  const globalResult = config({ path: globalEnvPath, override: true });
-  if (globalResult.error) {
-    console.error(`Failed to load .env from ${globalEnvPath}: ${globalResult.error.message}`);
-    console.error('Hint: Check for syntax errors in your ~/.archon/.env file.');
-  }
-}
+// Load archon-owned env from ~/.archon/.env (user scope) and <cwd>/.archon/.env
+// (repo scope, wins over user) with override: true. Keeps the server in sync
+// with the CLI — see packages/paths/src/env-loader.ts and the three-path model
+// (#1302 / #1303).
+import { loadArchonEnv } from '@archon/paths/env-loader';
+loadArchonEnv(process.cwd());
 
 // CLAUDECODE=1 warning is emitted inside stripCwdEnv() (boot import above)
 // BEFORE the marker is deleted from process.env. No duplicate warning here.
@@ -52,6 +47,12 @@ if (
   process.env.CLAUDE_USE_GLOBAL_AUTH = 'true';
 }
 
+import { registerBuiltinProviders, registerCommunityProviders } from '@archon/providers';
+
+// Bootstrap provider registry before any provider lookups
+registerBuiltinProviders();
+registerCommunityProviders();
+
 import { OpenAPIHono } from '@hono/zod-openapi';
 import { validationErrorHook } from './routes/openapi-defaults';
 import { TelegramAdapter, GitHubAdapter, DiscordAdapter, SlackAdapter } from '@archon/adapters';
@@ -72,12 +73,14 @@ import {
   loadConfig,
   logConfig,
   getPort,
-  createWorkflowStore,
-  scanPathForSensitiveKeys,
 } from '@archon/core';
-import * as codebaseDb from '@archon/core/db/codebases';
 import type { IPlatformAdapter } from '@archon/core';
-import { createLogger, logArchonPaths, validateAppDefaultsPaths } from '@archon/paths';
+import {
+  createLogger,
+  logArchonPaths,
+  validateAppDefaultsPaths,
+  shutdownTelemetry,
+} from '@archon/paths';
 
 /** Lazy-initialized logger (deferred so test mocks can intercept createLogger) */
 let cachedLog: ReturnType<typeof createLogger> | undefined;
@@ -170,7 +173,7 @@ export async function startServer(opts: ServerOptions = {}): Promise<void> {
           'Or set CODEX_ID_TOKEN + CODEX_ACCESS_TOKEN in .env',
           'See .env.example for all options',
         ],
-        envFile: BUNDLED_IS_BINARY ? globalEnvPath : envPath,
+        envFile: BUNDLED_IS_BINARY ? getArchonEnvPath() : envPath,
       },
       'no_ai_credentials'
     );
@@ -199,67 +202,23 @@ export async function startServer(opts: ServerOptions = {}): Promise<void> {
     process.exit(1);
   }
 
-  // Load configuration early so the startup env-leak scan can honor the
-  // global bypass. Without this, users who set `allow_target_repo_keys: true`
-  // would get a per-codebase warn spam on every boot even though the gate
-  // is intentionally disabled.
   const config = await loadConfig();
   logConfig(config);
 
-  // Startup env-leak scan: warn for codebases that would be blocked at next
-  // spawn by the env-leak-gate. Skipped entirely when the global bypass is
-  // active. Best-effort — failures are surfaced but never block startup.
-  if (config.allowTargetRepoKeys) {
-    getLog().info('startup_env_leak_scan_skipped — allow_target_repo_keys is true');
-  } else {
-    try {
-      const codebases = await codebaseDb.listCodebases();
-      for (const cb of codebases) {
-        if (cb.allow_env_keys) continue;
-        try {
-          const report = scanPathForSensitiveKeys(cb.default_cwd);
-          if (report.findings.length > 0) {
-            const files = report.findings.map(f => f.file);
-            const keys = Array.from(new Set(report.findings.flatMap(f => f.keys)));
-            getLog().warn(
-              {
-                codebaseId: cb.id,
-                name: cb.name,
-                path: cb.default_cwd,
-                files,
-                keys,
-              },
-              'startup_env_leak_gate_will_block'
-            );
-          }
-        } catch (scanErr) {
-          // Path may no longer exist (codebase moved/deleted on disk) —
-          // log at debug, do not abort the loop. This is the only quiet path.
-          getLog().debug(
-            { err: scanErr, codebaseId: cb.id, path: cb.default_cwd },
-            'startup_env_leak_scan_path_unavailable'
-          );
-        }
-      }
-    } catch (error) {
-      // listCodebases() failed — the entire startup safety net is silently
-      // absent. Surface at error level so operators see it.
-      getLog().error(
-        { err: error },
-        'startup_env_leak_scan_failed — startup migration warnings suppressed'
-      );
-    }
-  }
-
   // Start cleanup scheduler
   startCleanupScheduler();
 
-  // Mark workflow runs orphaned by previous process termination as failed
-  void createWorkflowStore()
-    .failOrphanedRuns()
-    .catch(err => {
-      getLog().error({ err }, 'workflow.fail_orphans_failed');
-    });
+  // Note: orphaned-run cleanup intentionally NOT called at server startup.
+  // Running it here killed parallel workflow runs from other processes
+  // (CLI, adapters) by flipping their `running` rows to `failed` mid-flight.
+  // Same lesson the CLI already learned — see packages/cli/src/cli.ts:256-258.
+  // Per CLAUDE.md "No Autonomous Lifecycle Mutation Across Process Boundaries":
+  // surface ambiguous state to users and provide a one-click action instead.
+  // Users transition a stuck `running` row via the per-row Cancel/Abandon
+  // buttons in the Web UI dashboard, or `archon workflow abandon <run-id>`.
+  // (`archon workflow cleanup` is a separate command that deletes OLD terminal
+  // rows for disk hygiene — it does not handle stuck `running` rows.)
+  // See #1216.
 
   // Log Archon paths configuration
   logArchonPaths();
@@ -293,6 +252,11 @@ export async function startServer(opts: ServerOptions = {}): Promise<void> {
   await webAdapter.start();
   persistence.startPeriodicFlush();
 
+  // Mutable — pushed to as each adapter starts, read by the /api/health endpoint.
+  // Must be a live reference because Telegram starts after the HTTP listener begins
+  // accepting requests, so a snapshot taken at registration time would miss it.
+  const activePlatforms: string[] = ['Web'];
+
   // Platform adapters (skipped in CLI serve mode or when not configured)
   let github: GitHubAdapter | null = null;
   let gitea: GiteaAdapter | null = null;
@@ -325,6 +289,7 @@ export async function startServer(opts: ServerOptions = {}): Promise<void> {
         botMention
       );
       await github.start();
+      activePlatforms.push('GitHub');
     } else {
       getLog().info('github_adapter_skipped');
     }
@@ -341,6 +306,7 @@ export async function startServer(opts: ServerOptions = {}): Promise<void> {
         giteaBotMention
       );
       await gitea.start();
+      activePlatforms.push('Gitea');
     } else {
       getLog().info('gitea_adapter_skipped');
     }
@@ -357,6 +323,7 @@ export async function startServer(opts: ServerOptions = {}): Promise<void> {
         gitlabBotMention
       );
       await gitlab.start();
+      activePlatforms.push('GitLab');
     } else {
       getLog().info('gitlab_adapter_skipped');
     }
@@ -419,6 +386,7 @@ export async function startServer(opts: ServerOptions = {}): Promise<void> {
       });
 
       await discord.start();
+      activePlatforms.push('Discord');
     } else {
       getLog().info('discord_adapter_skipped');
     }
@@ -474,6 +442,7 @@ export async function startServer(opts: ServerOptions = {}): Promise<void> {
       });
 
       await slack.start();
+      activePlatforms.push('Slack');
     } else {
       getLog().info('slack_adapter_skipped');
     }
@@ -492,7 +461,7 @@ export async function startServer(opts: ServerOptions = {}): Promise<void> {
   });
 
   // Register Web UI API routes
-  registerApiRoutes(app, webAdapter, lockManager);
+  registerApiRoutes(app, webAdapter, lockManager, activePlatforms);
 
   // GitHub webhook endpoint
   if (github) {
@@ -648,6 +617,7 @@ export async function startServer(opts: ServerOptions = {}): Promise<void> {
 
     try {
       await telegramAdapter.start();
+      activePlatforms.push('Telegram');
     } catch (err) {
       const error = err instanceof Error ? err : new Error(String(err));
       getLog().error({ err: error, errorType: error.constructor.name }, 'telegram.start_failed');
@@ -682,6 +652,9 @@ export async function startServer(opts: ServerOptions = {}): Promise<void> {
           getLog().error({ err: error }, 'adapter_stop_error');
         }
 
+        // Flush queued telemetry events before pool closes the process.
+        await shutdownTelemetry();
+
         return pool.end();
       })
       .then(() => {
@@ -706,15 +679,6 @@ export async function startServer(opts: ServerOptions = {}): Promise<void> {
   // the try/catch in claude.ts). These are SDK cleanup races, not fatal app errors.
   process.on('unhandledRejection', handleUnhandledRejection);
 
-  // Show active platforms
-  const activePlatforms = ['Web'];
-  if (telegram) activePlatforms.push('Telegram');
-  if (discord) activePlatforms.push('Discord');
-  if (slack) activePlatforms.push('Slack');
-  if (github) activePlatforms.push('GitHub');
-  if (gitea) activePlatforms.push('Gitea');
-  if (gitlab) activePlatforms.push('GitLab');
-
   getLog().info({ activePlatforms, port }, 'server_ready');
 
   // Non-blocking: warn at startup if gh CLI auth is unavailable
diff --git a/packages/server/src/routes/api.codebases.test.ts b/packages/server/src/routes/api.codebases.test.ts
index 0265a359e1..d06615968b 100644
--- a/packages/server/src/routes/api.codebases.test.ts
+++ b/packages/server/src/routes/api.codebases.test.ts
@@ -48,15 +48,6 @@ mock.module('@archon/core', () => ({
       this.name = 'ConversationNotFoundError';
     }
   },
-  scanPathForSensitiveKeys: mock((_p: string) => ({ path: _p, findings: [] })),
-  EnvLeakError: class EnvLeakError extends Error {
-    constructor(public report: { path: string; findings: { file: string; keys: string[] }[] }) {
-      super(
-        `Cannot add codebase — ${report.path} contains keys that will leak into AI subprocesses`
-      );
-      this.name = 'EnvLeakError';
-    }
-  },
   getArchonWorkspacesPath: () => '/tmp/.archon/workspaces',
   generateAndSetTitle: mock(async () => {}),
   createLogger: () => ({
@@ -123,12 +114,10 @@ mock.module('@archon/core/db/conversations', () => ({
   getConversationById: mock(async () => null),
 }));
 
-const mockUpdateCodebaseAllowEnvKeys = mock(async (_id: string, _v: boolean) => {});
 mock.module('@archon/core/db/codebases', () => ({
   listCodebases: mockListCodebases,
   getCodebase: mockGetCodebase,
   deleteCodebase: mockDeleteCodebase,
-  updateCodebaseAllowEnvKeys: mockUpdateCodebaseAllowEnvKeys,
 }));
 
 mock.module('@archon/core/db/isolation-environments', () => ({
@@ -181,7 +170,6 @@ const MOCK_CODEBASE = {
   repository_url: 'https://github.com/user/repo',
   default_cwd: '/home/user/projects/my-project',
   ai_assistant_type: 'claude',
-  allow_env_keys: false,
   commands: {},
   created_at: new Date().toISOString(),
   updated_at: new Date().toISOString(),
@@ -399,7 +387,7 @@ describe('POST /api/codebases', () => {
 
     const body = (await response.json()) as { id: string };
     expect(body.id).toBe('codebase-uuid-1');
-    expect(mockCloneRepository).toHaveBeenCalledWith('https://github.com/user/repo', undefined);
+    expect(mockCloneRepository).toHaveBeenCalledWith('https://github.com/user/repo');
   });
 
   test('registers existing URL codebase with 200', async () => {
@@ -436,7 +424,7 @@ describe('POST /api/codebases', () => {
       body: JSON.stringify({ path: '/home/user/my-repo' }),
     });
     expect(response.status).toBe(201);
-    expect(mockRegisterRepository).toHaveBeenCalledWith('/home/user/my-repo', undefined);
+    expect(mockRegisterRepository).toHaveBeenCalledWith('/home/user/my-repo');
   });
 
   test('returns 400 when both url and path are provided', async () => {
@@ -508,101 +496,6 @@ describe('POST /api/codebases', () => {
     const body = (await response.json()) as { error: string };
     expect(body.error).toContain('authentication required');
   });
-
-  test('returns 422 when cloneRepository throws EnvLeakError', async () => {
-    const { EnvLeakError } = await import('@archon/core');
-    mockCloneRepository.mockImplementationOnce(async () => {
-      throw new EnvLeakError({
-        path: '/repo/path',
-        findings: [{ file: '.env', keys: ['ANTHROPIC_API_KEY'] }],
-      });
-    });
-
-    const app = makeApp();
-    const response = await app.request('/api/codebases', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ url: 'https://github.com/user/repo' }),
-    });
-    expect(response.status).toBe(422);
-
-    const body = (await response.json()) as { error: string };
-    expect(body.error).toContain('Cannot add codebase');
-  });
-
-  test('passes allowEnvKeys=true to cloneRepository when body includes it', async () => {
-    mockCloneRepository.mockImplementationOnce(async () => ({
-      codebaseId: 'clone-uuid-2',
-      alreadyExisted: false,
-    }));
-    mockGetCodebase.mockImplementationOnce(async () => MOCK_CODEBASE);
-
-    const app = makeApp();
-    const response = await app.request('/api/codebases', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ url: 'https://github.com/user/repo', allowEnvKeys: true }),
-    });
-    expect(response.status).toBe(201);
-    expect(mockCloneRepository).toHaveBeenCalledWith('https://github.com/user/repo', true);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Tests: PATCH /api/codebases/:id
-// ---------------------------------------------------------------------------
-
-describe('PATCH /api/codebases/:id', () => {
-  beforeEach(() => {
-    mockGetCodebase.mockReset();
-    mockUpdateCodebaseAllowEnvKeys.mockReset();
-  });
-
-  test('grants consent and returns updated codebase', async () => {
-    mockGetCodebase
-      .mockImplementationOnce(async () => MOCK_CODEBASE)
-      .mockImplementationOnce(async () => ({ ...MOCK_CODEBASE, allow_env_keys: true }));
-    mockUpdateCodebaseAllowEnvKeys.mockImplementationOnce(async () => {});
-
-    const app = makeApp();
-    const response = await app.request('/api/codebases/codebase-uuid-1', {
-      method: 'PATCH',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ allowEnvKeys: true }),
-    });
-    expect(response.status).toBe(200);
-    const body = (await response.json()) as { allow_env_keys: boolean };
-    expect(body.allow_env_keys).toBe(true);
-    expect(mockUpdateCodebaseAllowEnvKeys).toHaveBeenCalledWith('codebase-uuid-1', true);
-  });
-
-  test('revokes consent', async () => {
-    mockGetCodebase
-      .mockImplementationOnce(async () => ({ ...MOCK_CODEBASE, allow_env_keys: true }))
-      .mockImplementationOnce(async () => MOCK_CODEBASE);
-    mockUpdateCodebaseAllowEnvKeys.mockImplementationOnce(async () => {});
-
-    const app = makeApp();
-    const response = await app.request('/api/codebases/codebase-uuid-1', {
-      method: 'PATCH',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ allowEnvKeys: false }),
-    });
-    expect(response.status).toBe(200);
-    expect(mockUpdateCodebaseAllowEnvKeys).toHaveBeenCalledWith('codebase-uuid-1', false);
-  });
-
-  test('returns 404 when codebase not found', async () => {
-    mockGetCodebase.mockImplementationOnce(async () => null);
-
-    const app = makeApp();
-    const response = await app.request('/api/codebases/missing', {
-      method: 'PATCH',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ allowEnvKeys: true }),
-    });
-    expect(response.status).toBe(404);
-  });
 });
 
 // ---------------------------------------------------------------------------
diff --git a/packages/server/src/routes/api.providers.test.ts b/packages/server/src/routes/api.providers.test.ts
new file mode 100644
index 0000000000..bb9b5ebb15
--- /dev/null
+++ b/packages/server/src/routes/api.providers.test.ts
@@ -0,0 +1,224 @@
+import { describe, test, expect, mock, beforeEach } from 'bun:test';
+import { OpenAPIHono } from '@hono/zod-openapi';
+import { registerBuiltinProviders, clearRegistry } from '@archon/providers';
+import type { ConversationLockManager } from '@archon/core';
+import type { WebAdapter } from '../adapters/web';
+import {
+  makeDiscoverWorkflowsMock,
+  makeLoaderMock,
+  makeCommandValidationMock,
+} from '../test/workflow-mock-factories';
+
+// ---------------------------------------------------------------------------
+// Mock setup — must be before dynamic imports
+// ---------------------------------------------------------------------------
+
+const mockLoadConfig = mock(async () => ({
+  assistants: { claude: { model: 'sonnet' } },
+  worktree: { baseBranch: 'main' },
+}));
+const mockGetDatabaseType = mock(() => 'sqlite' as const);
+
+mock.module('@archon/core', () => ({
+  handleMessage: mock(async () => {}),
+  getDatabaseType: mockGetDatabaseType,
+  loadConfig: mockLoadConfig,
+  cloneRepository: mock(async () => ({ codebaseId: 'x', alreadyExisted: false })),
+  registerRepository: mock(async () => ({ codebaseId: 'x', alreadyExisted: false })),
+  ConversationNotFoundError: class ConversationNotFoundError extends Error {
+    constructor(id: string) {
+      super(`Conversation not found: ${id}`);
+      this.name = 'ConversationNotFoundError';
+    }
+  },
+  getArchonWorkspacesPath: () => '/tmp/.archon/workspaces',
+  toSafeConfig: (config: unknown) => config,
+  generateAndSetTitle: mock(async () => {}),
+  updateGlobalConfig: mock(async () => {}),
+  createLogger: () => ({
+    fatal: mock(() => undefined),
+    error: mock(() => undefined),
+    warn: mock(() => undefined),
+    info: mock(() => undefined),
+    debug: mock(() => undefined),
+    trace: mock(() => undefined),
+    child: mock(function (this: unknown) {
+      return this;
+    }),
+    bindings: mock(() => ({ module: 'test' })),
+    isLevelEnabled: mock(() => true),
+    level: 'info',
+  }),
+}));
+
+mock.module('@archon/paths', () => ({
+  createLogger: () => ({
+    fatal: mock(() => undefined),
+    error: mock(() => undefined),
+    warn: mock(() => undefined),
+    info: mock(() => undefined),
+    debug: mock(() => undefined),
+    trace: mock(() => undefined),
+    child: mock(function (this: unknown) {
+      return this;
+    }),
+    bindings: mock(() => ({ module: 'test' })),
+    isLevelEnabled: mock(() => true),
+    level: 'info',
+  }),
+  getWorkflowFolderSearchPaths: mock(() => ['.archon/workflows']),
+  getCommandFolderSearchPaths: mock(() => ['.archon/commands']),
+  getDefaultCommandsPath: mock(() => '/tmp/.archon-test-nonexistent/commands/defaults'),
+  getDefaultWorkflowsPath: mock(() => '/tmp/.archon-test-nonexistent/workflows/defaults'),
+  getArchonWorkspacesPath: () => '/tmp/.archon/workspaces',
+  isDocker: mock(() => false),
+}));
+
+mock.module('@archon/workflows/workflow-discovery', makeDiscoverWorkflowsMock);
+mock.module('@archon/workflows/loader', makeLoaderMock);
+mock.module('@archon/workflows/command-validation', makeCommandValidationMock);
+mock.module('@archon/workflows/defaults', () => ({
+  BUNDLED_WORKFLOWS: {},
+  BUNDLED_COMMANDS: {},
+  isBinaryBuild: mock(() => false),
+}));
+
+mock.module('@archon/git', () => ({
+  removeWorktree: mock(async () => {}),
+  toRepoPath: (p: string) => p,
+  toWorktreePath: (p: string) => p,
+}));
+
+mock.module('@archon/core/db/conversations', () => ({
+  findConversationByPlatformId: mock(async () => null),
+  listConversations: mock(async () => []),
+  getOrCreateConversation: mock(async () => null),
+  softDeleteConversation: mock(async () => {}),
+  updateConversationTitle: mock(async () => {}),
+  getConversationById: mock(async () => null),
+}));
+mock.module('@archon/core/db/codebases', () => ({
+  listCodebases: mock(async () => []),
+  getCodebase: mock(async () => null),
+  deleteCodebase: mock(async () => {}),
+}));
+mock.module('@archon/core/db/isolation-environments', () => ({
+  listByCodebase: mock(async () => []),
+  listByCodebaseWithAge: mock(async () => []),
+  updateStatus: mock(async () => {}),
+}));
+mock.module('@archon/core/db/workflows', () => ({
+  listWorkflowRuns: mock(async () => []),
+  listDashboardRuns: mock(async () => ({ runs: [], total: 0, counts: {} })),
+  getWorkflowRun: mock(async () => null),
+  cancelWorkflowRun: mock(async () => {}),
+  getWorkflowRunByWorkerPlatformId: mock(async () => null),
+  getRunningWorkflows: mock(async () => []),
+}));
+mock.module('@archon/core/db/workflow-events', () => ({
+  listWorkflowEvents: mock(async () => []),
+}));
+mock.module('@archon/core/db/messages', () => ({
+  addMessage: mock(async () => null),
+  listMessages: mock(async () => []),
+}));
+mock.module('@archon/core/db/env-vars', () => ({
+  getEnvVars: mock(async () => []),
+  getEnvVarKeys: mock(async () => []),
+  setEnvVar: mock(async () => {}),
+  deleteEnvVar: mock(async () => {}),
+}));
+mock.module('@archon/core/utils/commands', () => ({
+  findMarkdownFilesRecursive: mock(async () => []),
+}));
+
+// Bootstrap registry after mocks
+clearRegistry();
+registerBuiltinProviders();
+
+import { registerApiRoutes } from './api';
+
+type Hono = InstanceType<typeof OpenAPIHono>;
+
+function makeApp(): Hono {
+  const app = new OpenAPIHono();
+  const mockWebAdapter = {
+    setConversationDbId: mock(() => {}),
+    emitSSE: mock(async () => {}),
+    emitLockEvent: mock(async () => {}),
+  } as unknown as WebAdapter;
+  const mockLockManager = {
+    acquireLock: mock(async (_id: string, fn: () => Promise<void>) => {
+      await fn();
+      return { status: 'started' };
+    }),
+    getStats: mock(() => ({
+      active: 0,
+      queuedTotal: 0,
+      queuedByConversation: [],
+      maxConcurrent: 10,
+      activeConversationIds: [],
+    })),
+  } as unknown as ConversationLockManager;
+  registerApiRoutes(app, mockWebAdapter, mockLockManager);
+  return app;
+}
+
+// ---------------------------------------------------------------------------
+// Tests: GET /api/providers
+// ---------------------------------------------------------------------------
+
+describe('GET /api/providers', () => {
+  let app: Hono;
+
+  beforeEach(() => {
+    app = makeApp();
+  });
+
+  test('returns 200 with provider list', async () => {
+    const response = await app.request('/api/providers');
+    expect(response.status).toBe(200);
+    const body = (await response.json()) as { providers: unknown[] };
+    expect(body.providers).toBeDefined();
+    expect(Array.isArray(body.providers)).toBe(true);
+  });
+
+  test('includes built-in providers', async () => {
+    const response = await app.request('/api/providers');
+    const body = (await response.json()) as {
+      providers: { id: string; builtIn: boolean }[];
+    };
+    const ids = body.providers.map(p => p.id);
+    expect(ids).toContain('claude');
+    expect(ids).toContain('codex');
+    expect(body.providers.every(p => p.builtIn)).toBe(true);
+  });
+
+  test('returns correct shape per provider (no factory or isModelCompatible)', async () => {
+    const response = await app.request('/api/providers');
+    const body = (await response.json()) as {
+      providers: Record<string, unknown>[];
+    };
+    for (const provider of body.providers) {
+      expect(provider).toHaveProperty('id');
+      expect(provider).toHaveProperty('displayName');
+      expect(provider).toHaveProperty('capabilities');
+      expect(provider).toHaveProperty('builtIn');
+      // Non-serializable fields must NOT leak
+      expect(provider).not.toHaveProperty('factory');
+      expect(provider).not.toHaveProperty('isModelCompatible');
+    }
+  });
+
+  test('capabilities have expected boolean fields', async () => {
+    const response = await app.request('/api/providers');
+    const body = (await response.json()) as {
+      providers: { capabilities: Record<string, boolean> }[];
+    };
+    const caps = body.providers[0].capabilities;
+    expect(typeof caps.sessionResume).toBe('boolean');
+    expect(typeof caps.mcp).toBe('boolean');
+    expect(typeof caps.hooks).toBe('boolean');
+    expect(typeof caps.structuredOutput).toBe('boolean');
+  });
+});
diff --git a/packages/server/src/routes/api.ts b/packages/server/src/routes/api.ts
index ed267c1d41..928a8f35cd 100644
--- a/packages/server/src/routes/api.ts
+++ b/packages/server/src/routes/api.ts
@@ -27,8 +27,6 @@ import {
   registerRepository,
   ConversationNotFoundError,
   generateAndSetTitle,
-  EnvLeakError,
-  scanPathForSensitiveKeys,
 } from '@archon/core';
 import { removeWorktree, toRepoPath, toWorktreePath } from '@archon/git';
 import {
@@ -38,6 +36,7 @@ import {
   getDefaultCommandsPath,
   getDefaultWorkflowsPath,
   getArchonWorkspacesPath,
+  getHomeCommandsPath,
   getRunArtifactsPath,
   getArchonHome,
   isDocker,
@@ -53,7 +52,7 @@ import {
   RESUMABLE_WORKFLOW_STATUSES,
   TERMINAL_WORKFLOW_STATUSES,
 } from '@archon/workflows/schemas/workflow-run';
-import type { ApprovalContext } from '@archon/workflows/schemas/workflow-run';
+import type { ApprovalContext, WorkflowRun } from '@archon/workflows/schemas/workflow-run';
 import { findMarkdownFilesRecursive } from '@archon/core/utils/commands';
 
 /** Lazy-initialized logger (deferred so test mocks can intercept createLogger) */
@@ -109,7 +108,6 @@ import {
   codebaseSchema,
   codebaseIdParamsSchema,
   addCodebaseBodySchema,
-  updateCodebaseBodySchema,
   deleteCodebaseResponseSchema,
   codebaseEnvVarsResponseSchema,
   setEnvVarBodySchema,
@@ -122,6 +120,8 @@ import {
   configResponseSchema,
   codebaseEnvironmentsResponseSchema,
 } from './schemas/config.schemas';
+import { providerListResponseSchema } from './schemas/provider.schemas';
+import { getProviderInfoList, isRegisteredProvider } from '@archon/providers';
 
 // Read app version: use build-time constant in binary, package.json in dev
 let appVersion = 'unknown';
@@ -140,7 +140,7 @@ if (BUNDLED_IS_BINARY) {
   }
 }
 
-type WorkflowSource = 'project' | 'bundled';
+type WorkflowSource = 'project' | 'bundled' | 'global';
 
 // =========================================================================
 // OpenAPI route configs (module-scope — pure config, no runtime dependencies)
@@ -467,28 +467,6 @@ const addCodebaseRoute = createRoute({
   },
 });
 
-const updateCodebaseRoute = createRoute({
-  method: 'patch',
-  path: '/api/codebases/{id}',
-  tags: ['Codebases'],
-  summary: 'Update codebase consent flags (e.g. allow_env_keys)',
-  request: {
-    params: codebaseIdParamsSchema,
-    body: {
-      content: { 'application/json': { schema: updateCodebaseBodySchema } },
-      required: true,
-    },
-  },
-  responses: {
-    200: {
-      content: { 'application/json': { schema: codebaseSchema } },
-      description: 'Updated codebase',
-    },
-    404: jsonError('Not found'),
-    500: jsonError('Server error'),
-  },
-});
-
 const deleteCodebaseRoute = createRoute({
   method: 'delete',
   path: '/api/codebases/{id}',
@@ -796,6 +774,19 @@ const patchAssistantConfigRoute = createRoute({
   },
 });
 
+const getProvidersRoute = createRoute({
+  method: 'get',
+  path: '/api/providers',
+  tags: ['System'],
+  summary: 'List registered AI providers',
+  responses: {
+    200: {
+      content: { 'application/json': { schema: providerListResponseSchema } },
+      description: 'List of registered providers',
+    },
+  },
+});
+
 const getCodebaseEnvironmentsRoute = createRoute({
   method: 'get',
   path: '/api/codebases/{id}/environments',
@@ -829,6 +820,7 @@ const getHealthRoute = createRoute({
               runningWorkflows: z.number(),
               version: z.string().optional(),
               is_docker: z.boolean(),
+              activePlatforms: z.array(z.string()).optional(),
             })
             .openapi('HealthResponse'),
         },
@@ -861,7 +853,8 @@ const getUpdateCheckRoute = createRoute({
 export function registerApiRoutes(
   app: OpenAPIHono,
   webAdapter: WebAdapter,
-  lockManager: ConversationLockManager
+  lockManager: ConversationLockManager,
+  activePlatforms?: readonly string[]
 ): void {
   function apiError(
     c: Context,
@@ -1042,6 +1035,95 @@ export function registerApiRoutes(
     return { accepted: true, status: result.status };
   }
 
+  /**
+   * Re-enter the orchestrator after a paused approval gate is resolved, so a
+   * web-dispatched workflow continues (approve) or runs its on_reject prompt
+   * (reject) without the user having to re-run the workflow command. The CLI's
+   * `workflowApproveCommand` / `workflowRejectCommand` already auto-resume via
+   * `workflowRunCommand({ resume: true })`; this is the web-side equivalent.
+   *
+   * Returns `true` when a resume dispatch was initiated, `false` otherwise (no
+   * parent conversation on the run, parent conversation deleted, parent was on
+   * a non-web platform, or dispatch threw). Failures are non-fatal: the gate
+   * decision is recorded regardless; when this returns `false` the response
+   * text instructs the user to re-run the workflow command.
+   *
+   * **Cross-adapter guard**: only web-sourced parents qualify.
+   * `dispatchToOrchestrator` is wired to the web adapter + its lock manager,
+   * so a Slack / Telegram / GitHub / Discord run being approved from the
+   * dashboard must not route through it — the Slack thread would never see
+   * the resumed output. Non-web parents skip auto-resume and the originating
+   * platform's own re-run flow applies.
+   */
+  async function tryAutoResumeAfterGate(
+    run: WorkflowRun,
+    action: 'approve' | 'reject'
+  ): Promise<boolean> {
+    if (!run.parent_conversation_id) return false;
+    // Literal event names per action — greppable for ops tooling. Keeping the
+    // branch explicit rather than templating avoids the earlier 3-segment
+    // `api.workflow_*.dispatched` shape that broke `{domain}.{action}_{state}`.
+    const events =
+      action === 'approve'
+        ? {
+            dispatched: 'api.workflow_approve_auto_resume_dispatched' as const,
+            skippedNoPlatformConv:
+              'api.workflow_approve_auto_resume_skipped_no_platform_conv' as const,
+            skippedNonWebParent: 'api.workflow_approve_auto_resume_skipped_non_web_parent' as const,
+            failed: 'api.workflow_approve_auto_resume_failed' as const,
+          }
+        : {
+            dispatched: 'api.workflow_reject_auto_resume_dispatched' as const,
+            skippedNoPlatformConv:
+              'api.workflow_reject_auto_resume_skipped_no_platform_conv' as const,
+            skippedNonWebParent: 'api.workflow_reject_auto_resume_skipped_non_web_parent' as const,
+            failed: 'api.workflow_reject_auto_resume_failed' as const,
+          };
+    try {
+      const parentConv = await conversationDb.getConversationById(run.parent_conversation_id);
+      const platformConvId = parentConv?.platform_conversation_id;
+      if (!platformConvId) {
+        // parentConv === null is a data-integrity signal (the parent
+        // conversation was deleted while the run was paused) — worth
+        // surfacing at info level so operators notice. Missing
+        // platform_conversation_id on an existing row shouldn't happen and
+        // stays at debug.
+        const logFn =
+          parentConv === null ? getLog().info.bind(getLog()) : getLog().debug.bind(getLog());
+        logFn(
+          {
+            runId: run.id,
+            parentConversationId: run.parent_conversation_id,
+            parentDeleted: parentConv === null,
+          },
+          events.skippedNoPlatformConv
+        );
+        return false;
+      }
+      if (parentConv.platform_type !== 'web') {
+        getLog().debug(
+          {
+            runId: run.id,
+            parentConversationId: run.parent_conversation_id,
+            platformType: parentConv.platform_type,
+          },
+          events.skippedNonWebParent
+        );
+        return false;
+      }
+      const resumeMessage = `/workflow run ${run.workflow_name} ${run.user_message ?? ''}`.trim();
+      await dispatchToOrchestrator(platformConvId, resumeMessage);
+      getLog().info(
+        { runId: run.id, workflowName: run.workflow_name, platformConvId },
+        events.dispatched
+      );
+      return true;
+    } catch (err) {
+      getLog().warn({ err: err as Error, runId: run.id }, events.failed);
+      return false;
+    }
+  }
+
   // GET /api/conversations - List conversations
   registerOpenApiRoute(getConversationsRoute, async c => {
     try {
@@ -1531,8 +1613,8 @@ export function registerApiRoutes(
     try {
       // .refine() guarantees exactly one of url/path is present
       const result = body.url
-        ? await cloneRepository(body.url, body.allowEnvKeys)
-        : await registerRepository(body.path ?? '', body.allowEnvKeys);
+        ? await cloneRepository(body.url)
+        : await registerRepository(body.path ?? '');
 
       // Fetch the full codebase record for a consistent response
       const codebase = await codebaseDb.getCodebase(result.codebaseId);
@@ -1542,12 +1624,6 @@ export function registerApiRoutes(
 
       return c.json(codebase, result.alreadyExisted ? 200 : 201);
     } catch (error) {
-      if (error instanceof EnvLeakError) {
-        const path = body.url ?? body.path ?? '';
-        const files = error.report.findings.map(f => f.file);
-        getLog().warn({ path, files }, 'add_codebase_env_leak_refused');
-        return apiError(c, 422, error.message);
-      }
       getLog().error({ err: error }, 'add_codebase_failed');
       return apiError(
         c,
@@ -1557,71 +1633,6 @@ export function registerApiRoutes(
     }
   });
 
-  // PATCH /api/codebases/:id - Update consent flags
-  registerOpenApiRoute(updateCodebaseRoute, async c => {
-    const id = c.req.param('id') ?? '';
-    const body = getValidatedBody(c, updateCodebaseBodySchema);
-    try {
-      const codebase = await codebaseDb.getCodebase(id);
-      if (!codebase) {
-        return apiError(c, 404, 'Codebase not found');
-      }
-
-      // Capture scanner findings for the audit log (best-effort — path may be gone)
-      let files: string[] = [];
-      let keys: string[] = [];
-      let scanStatus: 'ok' | 'skipped' = 'ok';
-      try {
-        const report = scanPathForSensitiveKeys(codebase.default_cwd);
-        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, codebaseId: id, path: codebase.default_cwd },
-          'env_leak_consent_scan_skipped'
-        );
-      }
-
-      await codebaseDb.updateCodebaseAllowEnvKeys(id, body.allowEnvKeys);
-
-      // Audit log: emitted unconditionally on every grant/revoke. `scanStatus`
-      // distinguishes "scanned and these are the findings" from "could not
-      // scan, files/keys are empty for that reason" — important for later
-      // security review of the audit trail.
-      getLog().warn(
-        {
-          codebaseId: id,
-          name: codebase.name,
-          path: codebase.default_cwd,
-          files,
-          keys,
-          scanStatus,
-          actor: 'user-ui',
-        },
-        body.allowEnvKeys ? 'env_leak_consent_granted' : 'env_leak_consent_revoked'
-      );
-
-      const updated = await codebaseDb.getCodebase(id);
-      if (!updated) {
-        return apiError(c, 500, 'Codebase updated but not found');
-      }
-      let commands = updated.commands;
-      if (typeof commands === 'string') {
-        try {
-          commands = JSON.parse(commands);
-        } catch (parseErr) {
-          getLog().error({ err: parseErr, codebaseId: id }, 'corrupted_commands_json');
-          commands = {};
-        }
-      }
-      return c.json({ ...updated, commands });
-    } catch (error) {
-      getLog().error({ err: error, codebaseId: id }, 'update_codebase_failed');
-      return apiError(c, 500, 'Failed to update codebase');
-    }
-  });
-
   // DELETE /api/codebases/:id - Delete a project and clean up
   registerOpenApiRoute(deleteCodebaseRoute, async c => {
     const id = c.req.param('id') ?? '';
@@ -1972,9 +1983,20 @@ export function registerApiRoutes(
         status: 'failed',
         metadata: metadataUpdate,
       });
+
+      // Auto-resume: dispatch to the orchestrator so the workflow continues
+      // without requiring the user to re-run the workflow command. Mirrors
+      // what `workflowApproveCommand` does in the CLI. Requires
+      // `parent_conversation_id` on the run (set by orchestrator-agent for any
+      // web-dispatched workflow — foreground, interactive, and background via
+      // the pre-created run) and a web-platform parent (guarded in the helper).
+      const autoResumed = await tryAutoResumeAfterGate(run, 'approve');
+
       return c.json({
         success: true,
-        message: `Workflow approved: ${run.workflow_name}. Send a message to continue the workflow.`,
+        message: autoResumed
+          ? `Workflow approved: ${run.workflow_name}. Resuming workflow.`
+          : `Workflow approved: ${run.workflow_name}. Send a message to continue.`,
       });
     } catch (error) {
       getLog().error({ err: error, runId }, 'api.workflow_run_approve_failed');
@@ -2018,9 +2040,18 @@ export function registerApiRoutes(
           status: 'failed',
           metadata: { rejection_reason: reason, rejection_count: currentCount + 1 },
         });
+
+        // Auto-resume: dispatch to the orchestrator so the on_reject prompt runs
+        // without requiring the user to re-run the workflow command. Mirrors
+        // what `workflowRejectCommand` does in the CLI. Same cross-adapter
+        // guard as approve — only web parents auto-resume.
+        const autoResumed = await tryAutoResumeAfterGate(run, 'reject');
+
         return c.json({
           success: true,
-          message: `Workflow rejected: ${run.workflow_name}. On-reject prompt will run on resume.`,
+          message: autoResumed
+            ? `Workflow rejected: ${run.workflow_name}. Running on-reject prompt.`
+            : `Workflow rejected: ${run.workflow_name}. On-reject prompt will run on resume.`,
         });
       }
 
@@ -2379,7 +2410,7 @@ export function registerApiRoutes(
         if (codebases.length > 0) workingDir = codebases[0].default_cwd;
       }
 
-      // Collect commands: project-defined override bundled (same name wins)
+      // Collect commands: precedence bundled < global < project (repo-defined wins).
       const commandMap = new Map<string, WorkflowSource>();
 
       // 1. Seed with bundled defaults
@@ -2387,11 +2418,17 @@ export function registerApiRoutes(
         commandMap.set(name, 'bundled');
       }
 
+      // maxDepth: 1 matches the executor's resolver (resolveCommand /
+      // loadCommandPrompt) — without this cap, the UI palette would surface
+      // commands buried in deep subfolders that the executor silently can't
+      // resolve at runtime.
+      const COMMAND_LIST_DEPTH = { maxDepth: 1 };
+
       // 2. If not binary build, also check filesystem defaults
       if (!isBinaryBuild()) {
         try {
           const defaultsPath = getDefaultCommandsPath();
-          const files = await findMarkdownFilesRecursive(defaultsPath);
+          const files = await findMarkdownFilesRecursive(defaultsPath, '', COMMAND_LIST_DEPTH);
           for (const { commandName } of files) {
             commandMap.set(commandName, 'bundled');
           }
@@ -2403,13 +2440,27 @@ export function registerApiRoutes(
         }
       }
 
-      // 3. Project-defined commands override bundled
+      // 3. Home-scoped commands (~/.archon/commands/) override bundled
+      try {
+        const homeCommandsPath = getHomeCommandsPath();
+        const files = await findMarkdownFilesRecursive(homeCommandsPath, '', COMMAND_LIST_DEPTH);
+        for (const { commandName } of files) {
+          commandMap.set(commandName, 'global');
+        }
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+          getLog().error({ err }, 'commands.list_home_failed');
+        }
+        // ENOENT: home commands dir not created yet — not an error
+      }
+
+      // 4. Project-defined commands override bundled AND global
       if (workingDir) {
         const searchPaths = getCommandFolderSearchPaths();
         for (const folder of searchPaths) {
           const dirPath = join(workingDir, folder);
           try {
-            const files = await findMarkdownFilesRecursive(dirPath);
+            const files = await findMarkdownFilesRecursive(dirPath, '', COMMAND_LIST_DEPTH);
             for (const { commandName } of files) {
               commandMap.set(commandName, 'project');
             }
@@ -2543,13 +2594,31 @@ export function registerApiRoutes(
 
       const updates: Partial<GlobalConfig> = {};
       if (body.assistant !== undefined) {
+        if (!isRegisteredProvider(body.assistant)) {
+          return apiError(
+            c,
+            400,
+            `Unknown provider '${body.assistant}'. Available: ${getProviderInfoList()
+              .map(p => p.id)
+              .join(', ')}`
+          );
+        }
         updates.defaultAssistant = body.assistant;
       }
-      if (body.claude !== undefined || body.codex !== undefined) {
-        updates.assistants = {
-          ...(body.claude ? { claude: body.claude } : {}),
-          ...(body.codex ? { codex: body.codex } : {}),
-        };
+      if (body.assistants !== undefined) {
+        const unknownProviders = Object.keys(body.assistants).filter(
+          id => !isRegisteredProvider(id)
+        );
+        if (unknownProviders.length > 0) {
+          return apiError(
+            c,
+            400,
+            `Unknown provider(s) in assistants: ${unknownProviders.join(', ')}. Available: ${getProviderInfoList()
+              .map(p => p.id)
+              .join(', ')}`
+          );
+        }
+        updates.assistants = body.assistants;
       }
 
       await updateGlobalConfig(updates);
@@ -2565,6 +2634,11 @@ export function registerApiRoutes(
     }
   });
 
+  // GET /api/providers - List registered AI providers
+  registerOpenApiRoute(getProvidersRoute, c => {
+    return c.json({ providers: getProviderInfoList() });
+  });
+
   // GET /api/codebases/:id/environments - List isolation environments for a codebase
   registerOpenApiRoute(getCodebaseEnvironmentsRoute, async c => {
     try {
@@ -2606,6 +2680,7 @@ export function registerApiRoutes(
       runningWorkflows: runningWorkflowRows.length,
       version: appVersion,
       is_docker: isDocker(),
+      activePlatforms: activePlatforms ? [...activePlatforms] : ['Web'],
     });
   });
 
diff --git a/packages/server/src/routes/api.workflow-runs.test.ts b/packages/server/src/routes/api.workflow-runs.test.ts
index 41bee85003..8d837d3623 100644
--- a/packages/server/src/routes/api.workflow-runs.test.ts
+++ b/packages/server/src/routes/api.workflow-runs.test.ts
@@ -22,7 +22,8 @@ const mockGetWorkflowRunByWorkerPlatformId = mock(
 );
 const mockListWorkflowEvents = mock(async (_runId: string) => [] as MockWorkflowEvent[]);
 const mockGetConversationById = mock(
-  async (_id: string) => null as null | { id: string; platform_conversation_id: string }
+  async (_id: string) =>
+    null as null | { id: string; platform_conversation_id: string; platform_type: string }
 );
 const mockFindConversationByPlatformId = mock(
   async (_id: string) =>
@@ -1362,3 +1363,186 @@ describe('POST /api/workflows/runs/:runId/reject', () => {
     expect(mockUpdateWorkflowRun).not.toHaveBeenCalled();
   });
 });
+
+// ---------------------------------------------------------------------------
+// Auto-resume: approve/reject endpoints dispatch to orchestrator when the run
+// has parent_conversation_id set (web-dispatched foreground/interactive
+// workflows). Mirrors what the CLI does in workflowApproveCommand/RejectCommand.
+// ---------------------------------------------------------------------------
+
+describe('approve/reject auto-resume', () => {
+  beforeEach(() => {
+    mockGetWorkflowRun.mockReset();
+    mockUpdateWorkflowRun.mockReset();
+    mockCreateWorkflowEvent.mockReset();
+    mockGetConversationById.mockReset();
+    mockHandleMessage.mockReset();
+    mockCancelWorkflowRun.mockReset();
+  });
+
+  test('approve: dispatches resume when parent_conversation_id is set', async () => {
+    mockGetWorkflowRun.mockResolvedValueOnce({
+      ...MOCK_PAUSED_RUN,
+      id: 'run-auto-resume-approve',
+      parent_conversation_id: 'parent-conv-uuid',
+      user_message: 'Deploy feature X',
+    });
+    mockGetConversationById.mockResolvedValueOnce({
+      id: 'parent-conv-uuid',
+      platform_conversation_id: 'web-plat-abc',
+      platform_type: 'web',
+    });
+
+    const { app } = makeApp();
+    const response = await app.request('/api/workflows/runs/run-auto-resume-approve/approve', {
+      method: 'POST',
+      body: JSON.stringify({ comment: 'LGTM' }),
+      headers: { 'Content-Type': 'application/json' },
+    });
+
+    expect(response.status).toBe(200);
+    const body = (await response.json()) as { message: string };
+    expect(body.message).toContain('Resuming workflow');
+
+    // dispatchToOrchestrator → lockManager → handleMessage
+    expect(mockHandleMessage).toHaveBeenCalled();
+    const [, platformConvId, dispatchedMessage] = mockHandleMessage.mock.calls[0] as [
+      unknown,
+      string,
+      string,
+    ];
+    expect(platformConvId).toBe('web-plat-abc');
+    expect(dispatchedMessage).toBe('/workflow run deploy Deploy feature X');
+  });
+
+  test('approve: skips dispatch when parent_conversation_id is null (CLI-dispatched run)', async () => {
+    mockGetWorkflowRun.mockResolvedValueOnce({
+      ...MOCK_PAUSED_RUN,
+      parent_conversation_id: null,
+    });
+
+    const { app } = makeApp();
+    const response = await app.request('/api/workflows/runs/run-paused-1/approve', {
+      method: 'POST',
+      body: JSON.stringify({ comment: 'LGTM' }),
+      headers: { 'Content-Type': 'application/json' },
+    });
+
+    expect(response.status).toBe(200);
+    const body = (await response.json()) as { message: string };
+    expect(body.message).toContain('Send a message to continue');
+    expect(mockHandleMessage).not.toHaveBeenCalled();
+    expect(mockGetConversationById).not.toHaveBeenCalled();
+  });
+
+  test('approve: skips dispatch when parent conversation no longer exists', async () => {
+    mockGetWorkflowRun.mockResolvedValueOnce({
+      ...MOCK_PAUSED_RUN,
+      parent_conversation_id: 'deleted-conv-uuid',
+    });
+    mockGetConversationById.mockResolvedValueOnce(null); // conversation deleted
+
+    const { app } = makeApp();
+    const response = await app.request('/api/workflows/runs/run-paused-1/approve', {
+      method: 'POST',
+      body: JSON.stringify({}),
+      headers: { 'Content-Type': 'application/json' },
+    });
+
+    expect(response.status).toBe(200);
+    const body = (await response.json()) as { message: string };
+    expect(body.message).toContain('Send a message to continue');
+    expect(mockHandleMessage).not.toHaveBeenCalled();
+  });
+
+  test('approve: skips dispatch when parent conversation is on a non-web platform', async () => {
+    // A Slack/Telegram/GitHub-sourced run being approved via the dashboard
+    // must not route through dispatchToOrchestrator — that helper is wired
+    // to the web adapter + lock manager, so dispatching a Slack thread_ts
+    // or Telegram chat_id would misroute through the wrong adapter.
+    mockGetWorkflowRun.mockResolvedValueOnce({
+      ...MOCK_PAUSED_RUN,
+      parent_conversation_id: 'slack-parent-conv-uuid',
+    });
+    mockGetConversationById.mockResolvedValueOnce({
+      id: 'slack-parent-conv-uuid',
+      platform_conversation_id: '1234567890.123456', // a Slack thread_ts
+      platform_type: 'slack',
+    });
+
+    const { app } = makeApp();
+    const response = await app.request('/api/workflows/runs/run-paused-1/approve', {
+      method: 'POST',
+      body: JSON.stringify({ comment: 'LGTM' }),
+      headers: { 'Content-Type': 'application/json' },
+    });
+
+    expect(response.status).toBe(200);
+    const body = (await response.json()) as { message: string };
+    // Same fallback text as no-parent case — user re-runs from the originating platform.
+    expect(body.message).toContain('Send a message to continue');
+    expect(mockHandleMessage).not.toHaveBeenCalled();
+  });
+
+  test('reject: dispatches resume for on_reject flows when parent is set', async () => {
+    mockGetWorkflowRun.mockResolvedValueOnce({
+      ...MOCK_PAUSED_RUN,
+      id: 'run-auto-resume-reject',
+      parent_conversation_id: 'parent-conv-uuid',
+      user_message: 'Review PR',
+      metadata: {
+        approval: {
+          type: 'approval',
+          nodeId: 'review-gate',
+          message: 'Approve?',
+          onRejectPrompt: 'Fix: $REJECTION_REASON',
+          onRejectMaxAttempts: 3,
+        },
+        rejection_count: 0,
+      },
+    });
+    mockGetConversationById.mockResolvedValueOnce({
+      id: 'parent-conv-uuid',
+      platform_conversation_id: 'web-plat-xyz',
+      platform_type: 'web',
+    });
+
+    const { app } = makeApp();
+    const response = await app.request('/api/workflows/runs/run-auto-resume-reject/reject', {
+      method: 'POST',
+      body: JSON.stringify({ reason: 'tests missing' }),
+      headers: { 'Content-Type': 'application/json' },
+    });
+
+    expect(response.status).toBe(200);
+    const body = (await response.json()) as { message: string };
+    expect(body.message).toContain('Running on-reject prompt');
+    expect(mockHandleMessage).toHaveBeenCalled();
+    const [, platformConvId, dispatchedMessage] = mockHandleMessage.mock.calls[0] as [
+      unknown,
+      string,
+      string,
+    ];
+    expect(platformConvId).toBe('web-plat-xyz');
+    expect(dispatchedMessage).toBe('/workflow run deploy Review PR');
+  });
+
+  test('reject: does NOT dispatch when the run is being cancelled (no on_reject configured)', async () => {
+    mockGetWorkflowRun.mockResolvedValueOnce({
+      ...MOCK_PAUSED_RUN,
+      parent_conversation_id: 'parent-conv-uuid', // set, but doesn't matter — reject cancels
+    });
+
+    const { app } = makeApp();
+    const response = await app.request('/api/workflows/runs/run-paused-1/reject', {
+      method: 'POST',
+      body: JSON.stringify({ reason: 'no' }),
+      headers: { 'Content-Type': 'application/json' },
+    });
+
+    expect(response.status).toBe(200);
+    // Cancellation path doesn't auto-resume — nothing to resume to.
+    expect(mockHandleMessage).not.toHaveBeenCalled();
+    expect(mockCancelWorkflowRun).toHaveBeenCalledWith('run-paused-1');
+  });
+});
diff --git a/packages/server/src/routes/schemas/codebase.schemas.ts b/packages/server/src/routes/schemas/codebase.schemas.ts
index e8a6dea887..d2880a6be1 100644
--- a/packages/server/src/routes/schemas/codebase.schemas.ts
+++ b/packages/server/src/routes/schemas/codebase.schemas.ts
@@ -16,7 +16,6 @@ export const codebaseSchema = z
     repository_url: z.string().nullable(),
     default_cwd: z.string(),
     ai_assistant_type: z.string(),
-    allow_env_keys: z.boolean(),
     commands: z.record(codebaseCommandSchema),
     created_at: z.string(),
     updated_at: z.string(),
@@ -34,20 +33,12 @@ export const addCodebaseBodySchema = z
   .object({
     url: z.string().min(1).optional(),
     path: z.string().min(1).optional(),
-    allowEnvKeys: z.boolean().optional(),
   })
   .refine(b => (b.url !== undefined) !== (b.path !== undefined), {
     message: 'Provide either "url" or "path", not both and not neither',
   })
   .openapi('AddCodebaseBody');
 
-/** PATCH /api/codebases/:id request body. */
-export const updateCodebaseBodySchema = z
-  .object({
-    allowEnvKeys: z.boolean(),
-  })
-  .openapi('UpdateCodebaseBody');
-
 /** DELETE /api/codebases/:id response. */
 export const deleteCodebaseResponseSchema = z
   .object({ success: z.boolean() })
diff --git a/packages/server/src/routes/schemas/config.schemas.ts b/packages/server/src/routes/schemas/config.schemas.ts
index d3ba003366..06cd75ee3f 100644
--- a/packages/server/src/routes/schemas/config.schemas.ts
+++ b/packages/server/src/routes/schemas/config.schemas.ts
@@ -4,18 +4,13 @@
 import { z } from '@hono/zod-openapi';
 
 /** Schema for the safe config subset returned to web clients (mirrors SafeConfig in config-types.ts). */
+const providerDefaultsSchema = z.record(z.string(), z.unknown()).openapi('ProviderDefaults');
+
 export const safeConfigSchema = z
   .object({
     botName: z.string(),
-    assistant: z.enum(['claude', 'codex']),
-    assistants: z.object({
-      claude: z.object({ model: z.string().optional() }),
-      codex: z.object({
-        model: z.string().optional(),
-        modelReasoningEffort: z.enum(['minimal', 'low', 'medium', 'high', 'xhigh']).optional(),
-        webSearchMode: z.enum(['disabled', 'cached', 'live']).optional(),
-      }),
-    }),
+    assistant: z.string().min(1),
+    assistants: z.record(z.string(), providerDefaultsSchema),
     streaming: z.object({
       telegram: z.enum(['stream', 'batch']),
       discord: z.enum(['stream', 'batch']),
@@ -34,19 +29,8 @@ export const safeConfigSchema = z
 /** Body for PATCH /api/config/assistants — all fields optional (partial update). */
 export const updateAssistantConfigBodySchema = z
   .object({
-    assistant: z.enum(['claude', 'codex']).optional(),
-    claude: z
-      .object({
-        model: z.string(),
-      })
-      .optional(),
-    codex: z
-      .object({
-        model: z.string(),
-        modelReasoningEffort: z.enum(['minimal', 'low', 'medium', 'high', 'xhigh']).optional(),
-        webSearchMode: z.enum(['disabled', 'cached', 'live']).optional(),
-      })
-      .optional(),
+    assistant: z.string().min(1).optional(),
+    assistants: z.record(z.string(), providerDefaultsSchema).optional(),
   })
   .openapi('UpdateAssistantConfigBody');
 
diff --git a/packages/server/src/routes/schemas/provider.schemas.ts b/packages/server/src/routes/schemas/provider.schemas.ts
new file mode 100644
index 0000000000..c69e69aa6a
--- /dev/null
+++ b/packages/server/src/routes/schemas/provider.schemas.ts
@@ -0,0 +1,39 @@
+/**
+ * Zod schemas for provider API endpoints.
+ */
+import { z } from '@hono/zod-openapi';
+
+/** Provider capability flags. */
+const providerCapabilitiesSchema = z
+  .object({
+    sessionResume: z.boolean(),
+    mcp: z.boolean(),
+    hooks: z.boolean(),
+    skills: z.boolean(),
+    toolRestrictions: z.boolean(),
+    structuredOutput: z.boolean(),
+    envInjection: z.boolean(),
+    costControl: z.boolean(),
+    effortControl: z.boolean(),
+    thinkingControl: z.boolean(),
+    fallbackModel: z.boolean(),
+    sandbox: z.boolean(),
+  })
+  .openapi('ProviderCapabilities');
+
+/** A single provider info entry (API-safe projection of ProviderRegistration). */
+export const providerInfoSchema = z
+  .object({
+    id: z.string(),
+    displayName: z.string(),
+    capabilities: providerCapabilitiesSchema,
+    builtIn: z.boolean(),
+  })
+  .openapi('ProviderInfo');
+
+/** Response for GET /api/providers. */
+export const providerListResponseSchema = z
+  .object({
+    providers: z.array(providerInfoSchema),
+  })
+  .openapi('ProviderListResponse');
diff --git a/packages/server/src/routes/schemas/workflow.schemas.ts b/packages/server/src/routes/schemas/workflow.schemas.ts
index 40fb9497d1..ef35030e05 100644
--- a/packages/server/src/routes/schemas/workflow.schemas.ts
+++ b/packages/server/src/routes/schemas/workflow.schemas.ts
@@ -17,8 +17,13 @@ export const workflowLoadErrorSchema = z
   })
   .openapi('WorkflowLoadError');
 
-/** Workflow source — project-defined or bundled default. */
-export const workflowSourceSchema = z.enum(['project', 'bundled']).openapi('WorkflowSource');
+/**
+ * Workflow source — project-defined, bundled default, or home-scoped (global).
+ * Precedence for same-named entries: `bundled` < `global` < `project`.
+ */
+export const workflowSourceSchema = z
+  .enum(['project', 'bundled', 'global'])
+  .openapi('WorkflowSource');
 
 /** A workflow entry in the list response, including its source. */
 export const workflowListEntrySchema = z
diff --git a/packages/web/package.json b/packages/web/package.json
index 5b02e1bbe6..2ff34166ff 100644
--- a/packages/web/package.json
+++ b/packages/web/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@archon/web",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "private": true,
   "type": "module",
   "scripts": {
@@ -8,7 +8,7 @@
     "build": "tsc --noEmit && vite build",
     "preview": "vite preview",
     "type-check": "tsc --noEmit",
-    "test": "bun test src/lib/ && bun test src/stores/",
+    "test": "bun test src/lib/ && bun test src/stores/ && bun test src/hooks/",
     "generate:types": "openapi-typescript http://localhost:3090/api/openapi.json -o src/lib/api.generated.d.ts"
   },
   "dependencies": {
diff --git a/packages/web/src/components/chat/ChatInterface.tsx b/packages/web/src/components/chat/ChatInterface.tsx
index fca7698390..58110df726 100644
--- a/packages/web/src/components/chat/ChatInterface.tsx
+++ b/packages/web/src/components/chat/ChatInterface.tsx
@@ -28,6 +28,7 @@ import type {
   ErrorDisplay,
   WorkflowDispatchEvent,
 } from '@/lib/types';
+import { applyOnText } from '@/lib/chat-message-reducer';
 import {
   getCachedMessages,
   setCachedMessages,
@@ -236,7 +237,7 @@ export function ChatInterface({ conversationId }: ChatInterfaceProps): React.Rea
     const latestId = ids[ids.length - 1];
     void getWorkflowRunByWorker(latestId)
       .then(result => {
-        if (!result) return;
+        if (!result?.run) return;
         const run = result.run;
         hydrateWorkflow({
           runId: run.id,
@@ -288,73 +289,7 @@ export function ChatInterface({ conversationId }: ChatInterfaceProps): React.Rea
       // First AI text received — the thinking placeholder is about to gain content,
       // so the hydration merge no longer needs the sendInFlight guard.
       setSendInFlight(false);
-      setMessages(prev => {
-        const last = prev[prev.length - 1];
-        // Workflow status messages (🚀 start, ✅ complete) should always be their own message
-        const isWorkflowStatus = /^[\u{1F680}\u{2705}]/u.test(content);
-
-        // Workflow result messages always start as a new message.
-        // Dedup: SSETransport replays buffered events on reconnect, which can
-        // arrive after the DB-fetch merge has already run — skip if a message
-        // with the same runId is already in state.
-        if (workflowResult) {
-          if (prev.some(m => m.workflowResult?.runId === workflowResult.runId)) {
-            return prev;
-          }
-          const updated =
-            last?.role === 'assistant' && last.isStreaming
-              ? [...prev.slice(0, -1), { ...last, isStreaming: false }]
-              : [...prev];
-          return [
-            ...updated,
-            {
-              id: `msg-${String(Date.now())}`,
-              role: 'assistant' as const,
-              content,
-              timestamp: Date.now(),
-              isStreaming: false,
-              toolCalls: [],
-              workflowResult,
-            },
-          ];
-        }
-
-        if (last?.role === 'assistant' && last.isStreaming) {
-          const lastIsWorkflowStatus = /^[\u{1F680}\u{2705}]/u.test(last.content);
-
-          if ((isWorkflowStatus && last.content) || (lastIsWorkflowStatus && !isWorkflowStatus)) {
-            // Close the current streaming message and start a new one when:
-            // 1. Incoming is a workflow status and current has content
-            // 2. Current is a workflow status and incoming is regular text
-            return [
-              ...prev.slice(0, -1),
-              { ...last, isStreaming: false },
-              {
-                id: `msg-${String(Date.now())}`,
-                role: 'assistant' as const,
-                content,
-                timestamp: Date.now(),
-                isStreaming: true,
-                toolCalls: [],
-              },
-            ];
-          }
-          // Append to existing streaming message (replace thinking placeholder if empty)
-          return [...prev.slice(0, -1), { ...last, content: last.content + content }];
-        }
-        // New assistant message
-        return [
-          ...prev,
-          {
-            id: `msg-${String(Date.now())}`,
-            role: 'assistant' as const,
-            content,
-            timestamp: Date.now(),
-            isStreaming: true,
-            toolCalls: [],
-          },
-        ];
-      });
+      setMessages(prev => applyOnText(prev, content, undefined, undefined, workflowResult));
     },
     []
   );
@@ -525,7 +460,14 @@ export function ChatInterface({ conversationId }: ChatInterfaceProps): React.Rea
               return merged;
             });
           })
-          .catch(() => {
+          .catch((err: unknown) => {
+            console.error(
+              '[Chat] Re-fetch after SSE reconnect failed — clearing stuck placeholder',
+              {
+                conversationId: conversationIdRef.current,
+                error: err instanceof Error ? err.message : err,
+              }
+            );
             // Re-fetch failed — clear stuck placeholder so user can retry
             setMessages(prev =>
               prev.map(m => (m.isStreaming && !m.content ? { ...m, isStreaming: false } : m))
diff --git a/packages/web/src/components/chat/MessageList.tsx b/packages/web/src/components/chat/MessageList.tsx
index 6842ac6b54..2410ba39c1 100644
--- a/packages/web/src/components/chat/MessageList.tsx
+++ b/packages/web/src/components/chat/MessageList.tsx
@@ -182,12 +182,14 @@ function WorkflowResultCard({
   const fetchFailed = isError && !liveState;
 
   // Status-aware header title
-  const headerTitle =
-    status === 'failed'
-      ? 'Workflow failed'
-      : status === 'cancelled'
-        ? 'Workflow cancelled'
-        : 'Workflow complete';
+  let headerTitle: string;
+  if (status === 'failed') {
+    headerTitle = 'Workflow failed';
+  } else if (status === 'cancelled') {
+    headerTitle = 'Workflow cancelled';
+  } else {
+    headerTitle = 'Workflow complete';
+  }
 
   // Expand/collapse for text content
   const lines = content.split('\n');
diff --git a/packages/web/src/components/chat/WorkflowProgressCard.tsx b/packages/web/src/components/chat/WorkflowProgressCard.tsx
index 2dda8e71db..44eb70af74 100644
--- a/packages/web/src/components/chat/WorkflowProgressCard.tsx
+++ b/packages/web/src/components/chat/WorkflowProgressCard.tsx
@@ -5,6 +5,7 @@ import { CheckCircle, ChevronRight, Loader2, Pause, XCircle } from 'lucide-react
 import { cn } from '@/lib/utils';
 import { approveWorkflowRun, getWorkflowRunByWorker, rejectWorkflowRun } from '@/lib/api';
 import { useWorkflowStore } from '@/stores/workflow-store';
+import { ConfirmRunActionDialog } from '@/components/dashboard/ConfirmRunActionDialog';
 import { StatusIcon } from '@/components/workflows/StatusIcon';
 import { formatDurationMs } from '@/lib/format';
 import { isTerminalStatus } from '@/lib/workflow-utils';
@@ -30,14 +31,14 @@ export function WorkflowProgressCard({
     queryKey: ['workflowRunByWorker', workerConversationId],
     queryFn: () => getWorkflowRunByWorker(workerConversationId),
     refetchInterval: (query): number | false => {
-      const status = query.state.data?.run.status;
+      const status = query.state.data?.run?.status;
       if (status === 'completed' || status === 'failed' || status === 'cancelled') return false;
       return 3000;
     },
   });
 
-  const runId = runData?.run.id;
-  const restStatus = runData?.run.status;
+  const runId = runData?.run?.id;
+  const restStatus = runData?.run?.status;
 
   // Live SSE state from Zustand store
   const liveState = useWorkflowStore(state => (runId ? state.workflows.get(runId) : undefined));
@@ -87,7 +88,7 @@ export function WorkflowProgressCard({
     mutationFn: () => approveWorkflowRun(runId ?? ''),
   });
   const rejectMutation = useMutation({
-    mutationFn: () => rejectWorkflowRun(runId ?? ''),
+    mutationFn: (reason?: string) => rejectWorkflowRun(runId ?? '', reason),
   });
   const mutationError = approveMutation.error ?? rejectMutation.error;
 
@@ -220,18 +221,33 @@ export function WorkflowProgressCard({
                   <CheckCircle className="h-3.5 w-3.5" />
                   Approve
                 </button>
-                <button
-                  onClick={() => {
-                    if (window.confirm(`Reject workflow "${workflowName}"?`)) {
-                      rejectMutation.mutate();
-                    }
+                <ConfirmRunActionDialog
+                  trigger={
+                    <button
+                      disabled={!runId || approveMutation.isPending || rejectMutation.isPending}
+                      className="flex items-center gap-1 rounded-md px-2 py-1 text-xs text-error/80 hover:bg-error/10 hover:text-error transition-colors disabled:opacity-50"
+                    >
+                      <XCircle className="h-3.5 w-3.5" />
+                      Reject
+                    </button>
+                  }
+                  title="Reject workflow?"
+                  description={
+                    <>
+                      Reject the paused workflow <strong>{workflowName}</strong>. If the approval
+                      node defines an <code>on_reject</code> prompt, it runs with your reason as{' '}
+                      <code>$REJECTION_REASON</code>; otherwise the run is cancelled.
+                    </>
+                  }
+                  confirmLabel="Reject"
+                  reasonInput={{
+                    label: 'Reason (optional)',
+                    placeholder: 'Why are you rejecting? Visible to the on_reject prompt.',
                   }}
-                  disabled={!runId || approveMutation.isPending || rejectMutation.isPending}
-                  className="flex items-center gap-1 rounded-md px-2 py-1 text-xs text-error/80 hover:bg-error/10 hover:text-error transition-colors disabled:opacity-50"
-                >
-                  <XCircle className="h-3.5 w-3.5" />
-                  Reject
-                </button>
+                  onConfirm={(reason): void => {
+                    rejectMutation.mutate(reason);
+                  }}
+                />
               </div>
               {(approveMutation.isError || rejectMutation.isError) && (
                 <p className="text-xs text-error">
diff --git a/packages/web/src/components/dashboard/ConfirmRunActionDialog.tsx b/packages/web/src/components/dashboard/ConfirmRunActionDialog.tsx
new file mode 100644
index 0000000000..4de85ce2bf
--- /dev/null
+++ b/packages/web/src/components/dashboard/ConfirmRunActionDialog.tsx
@@ -0,0 +1,126 @@
+import { useId, useState, type ReactNode } from 'react';
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from '@/components/ui/alert-dialog';
+
+/**
+ * Optional free-text input rendered below the description. Used for the
+ * reject flow so reviewers can attach a reason that propagates to the
+ * workflow's `on_reject` prompt as `$REJECTION_REASON`.
+ */
+interface ReasonInputConfig {
+  label: string;
+  placeholder?: string;
+}
+
+interface Props {
+  /** The element that opens the dialog when clicked (typically a button). */
+  trigger: ReactNode;
+  /** Dialog title (e.g. "Abandon workflow?"). */
+  title: string;
+  /** Body text — supports rich children (e.g. wrapping the workflow name in <strong>). */
+  description: ReactNode;
+  /** Confirm-button label (e.g. "Abandon", "Delete"). */
+  confirmLabel: string;
+  /**
+   * When provided, renders a textarea below the description. The trimmed
+   * value is passed to `onConfirm` — empty after trim becomes `undefined`
+   * so callers can distinguish "no reason given" from "empty string given".
+   */
+  reasonInput?: ReasonInputConfig;
+  /** Invoked when the user confirms. Fire-and-forget; callers own error
+   *  surfacing. Widen to `Promise<void>` only if a future caller needs to
+   *  await the action. `reason` is only non-`undefined` when `reasonInput`
+   *  is supplied and the user typed something after trimming. */
+  onConfirm: (reason?: string) => void;
+}
+
+/**
+ * Confirmation dialog for destructive workflow-run actions.
+ *
+ * Wraps shadcn's AlertDialog with the trigger included as a slot, so callers
+ * pass their existing action button as the `trigger` prop. The Action button
+ * is destructive-styled by default (per `AlertDialogAction` in
+ * `@/components/ui/alert-dialog`), which is appropriate for every workflow
+ * lifecycle action this is used for (Abandon, Cancel, Delete, Reject).
+ *
+ * For reject flows, pass `reasonInput` to collect a trimmed free-text reason
+ * that propagates to `$REJECTION_REASON` inside the workflow's `on_reject`
+ * prompt.
+ *
+ * Replaces previous use of `window.confirm()` for these actions to match the
+ * codebase-delete UX in `sidebar/ProjectSelector.tsx`.
+ */
+export function ConfirmRunActionDialog({
+  trigger,
+  title,
+  description,
+  confirmLabel,
+  reasonInput,
+  onConfirm,
+}: Props): React.ReactElement {
+  const [reason, setReason] = useState('');
+  // useId() so multiple dialog instances on the same page (e.g. side-by-side
+  // run cards) don't collide on a shared DOM id.
+  const reasonInputId = useId();
+
+  return (
+    <AlertDialog
+      onOpenChange={(open): void => {
+        // Reset the textarea every time the dialog closes so a previous
+        // reason doesn't bleed into the next reject action on the same card.
+        if (!open) setReason('');
+      }}
+    >
+      <AlertDialogTrigger asChild>{trigger}</AlertDialogTrigger>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>{title}</AlertDialogTitle>
+          <AlertDialogDescription asChild>
+            <div>{description}</div>
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        {reasonInput && (
+          <div className="space-y-2">
+            <label htmlFor={reasonInputId} className="text-sm font-medium text-foreground">
+              {reasonInput.label}
+            </label>
+            <textarea
+              id={reasonInputId}
+              value={reason}
+              onChange={(e): void => {
+                setReason(e.target.value);
+              }}
+              placeholder={reasonInput.placeholder}
+              rows={3}
+              className="w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
+            />
+          </div>
+        )}
+        <AlertDialogFooter>
+          <AlertDialogCancel>Cancel</AlertDialogCancel>
+          <AlertDialogAction
+            onClick={(): void => {
+              // Caller's onConfirm is fire-and-forget over a parent-level
+              // runAction helper that surfaces errors via component state.
+              // We do NOT catch here; swallowing would hide failures the
+              // parent is positioned to display.
+              const trimmed = reason.trim();
+              onConfirm(trimmed === '' ? undefined : trimmed);
+            }}
+          >
+            {confirmLabel}
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}
diff --git a/packages/web/src/components/dashboard/WorkflowHistoryTable.tsx b/packages/web/src/components/dashboard/WorkflowHistoryTable.tsx
index 015becb328..eea3bbfe38 100644
--- a/packages/web/src/components/dashboard/WorkflowHistoryTable.tsx
+++ b/packages/web/src/components/dashboard/WorkflowHistoryTable.tsx
@@ -3,6 +3,7 @@ import { Globe, Terminal, Hash, Send, GitBranch, Trash2 } from 'lucide-react';
 import type { DashboardRunResponse } from '@/lib/api';
 import { cn } from '@/lib/utils';
 import { formatDuration, formatStarted } from '@/lib/format';
+import { ConfirmRunActionDialog } from './ConfirmRunActionDialog';
 
 interface WorkflowHistoryTableProps {
   runs: DashboardRunResponse[];
@@ -101,21 +102,27 @@ export function WorkflowHistoryTable({
                     View Logs
                   </Link>
                   {onDelete && (
-                    <button
-                      onClick={(): void => {
-                        if (
-                          window.confirm(
-                            `Delete workflow run "${run.workflow_name}"? This cannot be undone.`
-                          )
-                        ) {
-                          onDelete(run.id);
-                        }
+                    <ConfirmRunActionDialog
+                      trigger={
+                        <button
+                          className="text-text-tertiary hover:text-error transition-colors"
+                          title="Delete run"
+                        >
+                          <Trash2 className="h-3 w-3" />
+                        </button>
+                      }
+                      title="Delete workflow run?"
+                      description={
+                        <>
+                          Permanently delete the run record for <strong>{run.workflow_name}</strong>{' '}
+                          and its events. This cannot be undone.
+                        </>
+                      }
+                      confirmLabel="Delete"
+                      onConfirm={(): void => {
+                        onDelete(run.id);
                       }}
-                      className="text-text-tertiary hover:text-error transition-colors"
-                      title="Delete run"
-                    >
-                      <Trash2 className="h-3 w-3" />
-                    </button>
+                    />
                   )}
                 </div>
               </td>
diff --git a/packages/web/src/components/dashboard/WorkflowRunCard.tsx b/packages/web/src/components/dashboard/WorkflowRunCard.tsx
index 926c31092e..417a2456a0 100644
--- a/packages/web/src/components/dashboard/WorkflowRunCard.tsx
+++ b/packages/web/src/components/dashboard/WorkflowRunCard.tsx
@@ -22,6 +22,7 @@ import { cn } from '@/lib/utils';
 import { formatDuration } from '@/lib/format';
 import { useWorkflowStore } from '@/stores/workflow-store';
 import type { WorkflowState } from '@/lib/types';
+import { ConfirmRunActionDialog } from './ConfirmRunActionDialog';
 
 interface WorkflowRunCardProps {
   run: DashboardRunResponse;
@@ -31,7 +32,7 @@ interface WorkflowRunCardProps {
   onAbandon?: (runId: string) => void;
   onDelete?: (runId: string) => void;
   onApprove?: (runId: string) => void;
-  onReject?: (runId: string) => void;
+  onReject?: (runId: string, reason?: string) => void;
 }
 
 const PLATFORM_ICONS: Record<string, React.ReactElement> = {
@@ -318,17 +319,30 @@ export function WorkflowRunCard({
             </button>
           )}
           {run.status === 'paused' && onReject && (
-            <button
-              onClick={(): void => {
-                if (window.confirm(`Reject workflow "${run.workflow_name}"?`)) {
-                  onReject(run.id);
-                }
+            <ConfirmRunActionDialog
+              trigger={
+                <button className="flex items-center gap-1 rounded-md px-2 py-1 text-xs text-error/80 hover:bg-error/10 hover:text-error transition-colors">
+                  <XCircle className="h-3.5 w-3.5" />
+                  Reject
+                </button>
+              }
+              title="Reject workflow?"
+              description={
+                <>
+                  Reject the paused workflow <strong>{run.workflow_name}</strong>. If the approval
+                  node defines an <code>on_reject</code> prompt, it runs with your reason as{' '}
+                  <code>$REJECTION_REASON</code>; otherwise the run is cancelled.
+                </>
+              }
+              confirmLabel="Reject"
+              reasonInput={{
+                label: 'Reason (optional)',
+                placeholder: 'Why are you rejecting? Visible to the on_reject prompt.',
               }}
-              className="flex items-center gap-1 rounded-md px-2 py-1 text-xs text-error/80 hover:bg-error/10 hover:text-error transition-colors"
-            >
-              <XCircle className="h-3.5 w-3.5" />
-              Reject
-            </button>
+              onConfirm={(reason): void => {
+                onReject(run.id, reason);
+              }}
+            />
           )}
           {run.status === 'failed' && onResume && (
             <button
@@ -342,47 +356,67 @@ export function WorkflowRunCard({
             </button>
           )}
           {run.status === 'running' && onAbandon && (
-            <button
-              onClick={(): void => {
-                if (window.confirm(`Abandon workflow "${run.workflow_name}"?`)) {
-                  onAbandon(run.id);
-                }
+            <ConfirmRunActionDialog
+              trigger={
+                <button className="flex items-center gap-1 rounded-md px-2 py-1 text-xs text-warning/80 hover:bg-warning/10 hover:text-warning transition-colors">
+                  <Ban className="h-3.5 w-3.5" />
+                  Abandon
+                </button>
+              }
+              title="Abandon workflow?"
+              description={
+                <>
+                  Mark <strong>{run.workflow_name}</strong> as cancelled. Already-completed nodes
+                  remain in the database; the run will not continue.
+                </>
+              }
+              confirmLabel="Abandon"
+              onConfirm={(): void => {
+                onAbandon(run.id);
               }}
-              className="flex items-center gap-1 rounded-md px-2 py-1 text-xs text-warning/80 hover:bg-warning/10 hover:text-warning transition-colors"
-            >
-              <Ban className="h-3.5 w-3.5" />
-              Abandon
-            </button>
+            />
           )}
           {(run.status === 'running' || run.status === 'pending') && (
-            <button
-              onClick={(): void => {
-                if (window.confirm(`Cancel workflow "${run.workflow_name}"?`)) {
-                  onCancel(run.id);
-                }
+            <ConfirmRunActionDialog
+              trigger={
+                <button className="flex items-center gap-1 rounded-md px-2 py-1 text-xs text-error/80 hover:bg-error/10 hover:text-error transition-colors">
+                  <XCircle className="h-3.5 w-3.5" />
+                  Cancel
+                </button>
+              }
+              title="Cancel workflow?"
+              description={
+                <>
+                  Cancel <strong>{run.workflow_name}</strong>. The run will be marked as cancelled
+                  and any in-flight subprocess will be terminated.
+                </>
+              }
+              confirmLabel="Cancel workflow"
+              onConfirm={(): void => {
+                onCancel(run.id);
               }}
-              className="flex items-center gap-1 rounded-md px-2 py-1 text-xs text-error/80 hover:bg-error/10 hover:text-error transition-colors"
-            >
-              <XCircle className="h-3.5 w-3.5" />
-              Cancel
-            </button>
+            />
           )}
           {onDelete && run.status !== 'running' && run.status !== 'pending' && (
-            <button
-              onClick={(): void => {
-                if (
-                  window.confirm(
-                    `Delete workflow run "${run.workflow_name}"? This cannot be undone.`
-                  )
-                ) {
-                  onDelete(run.id);
-                }
+            <ConfirmRunActionDialog
+              trigger={
+                <button className="flex items-center gap-1 rounded-md px-2 py-1 text-xs text-text-tertiary hover:bg-error/10 hover:text-error transition-colors">
+                  <Trash2 className="h-3.5 w-3.5" />
+                  Delete
+                </button>
+              }
+              title="Delete workflow run?"
+              description={
+                <>
+                  Permanently delete the run record for <strong>{run.workflow_name}</strong> and its
+                  events. This cannot be undone.
+                </>
+              }
+              confirmLabel="Delete"
+              onConfirm={(): void => {
+                onDelete(run.id);
               }}
-              className="flex items-center gap-1 rounded-md px-2 py-1 text-xs text-text-tertiary hover:bg-error/10 hover:text-error transition-colors"
-            >
-              <Trash2 className="h-3.5 w-3.5" />
-              Delete
-            </button>
+            />
           )}
         </div>
       </div>
diff --git a/packages/web/src/components/dashboard/WorkflowRunGroup.tsx b/packages/web/src/components/dashboard/WorkflowRunGroup.tsx
index c30fc39609..cbd0890b91 100644
--- a/packages/web/src/components/dashboard/WorkflowRunGroup.tsx
+++ b/packages/web/src/components/dashboard/WorkflowRunGroup.tsx
@@ -12,7 +12,7 @@ interface WorkflowRunGroupProps {
   onAbandon?: (runId: string) => void;
   onDelete?: (runId: string) => void;
   onApprove?: (runId: string) => void;
-  onReject?: (runId: string) => void;
+  onReject?: (runId: string, reason?: string) => void;
 }
 
 export function WorkflowRunGroup({
diff --git a/packages/web/src/components/layout/Sidebar.tsx b/packages/web/src/components/layout/Sidebar.tsx
index b4b0e1355d..27e19248d0 100644
--- a/packages/web/src/components/layout/Sidebar.tsx
+++ b/packages/web/src/components/layout/Sidebar.tsx
@@ -11,7 +11,7 @@ import { ProjectDetail } from '@/components/sidebar/ProjectDetail';
 import { AllConversationsView } from '@/components/sidebar/AllConversationsView';
 import { useKeyboardShortcuts } from '@/hooks/useKeyboardShortcuts';
 import { useProject } from '@/contexts/ProjectContext';
-import { addCodebase } from '@/lib/api';
+import { addCodebase, getCodebaseInput } from '@/lib/api';
 
 const SIDEBAR_MIN = 240;
 const SIDEBAR_MAX = 400;
@@ -120,12 +120,7 @@ export function Sidebar(): React.ReactElement {
     setAddLoading(true);
     setAddError(null);
 
-    // Detect: starts with / or ~ or Windows drive letter → local path; otherwise → URL
-    const isLocalPath =
-      trimmed.startsWith('/') || trimmed.startsWith('~') || /^[A-Za-z]:[/\\]/.test(trimmed);
-    const input = isLocalPath ? { path: trimmed } : { url: trimmed };
-
-    void addCodebase(input)
+    void addCodebase(getCodebaseInput(trimmed))
       .then(codebase => {
         void queryClient.invalidateQueries({ queryKey: ['codebases'] });
         handleSelectProject(codebase.id);
diff --git a/packages/web/src/components/layout/TopNav.tsx b/packages/web/src/components/layout/TopNav.tsx
index 45924f5004..ac1feabde5 100644
--- a/packages/web/src/components/layout/TopNav.tsx
+++ b/packages/web/src/components/layout/TopNav.tsx
@@ -1,7 +1,7 @@
 import { NavLink, Link } from 'react-router';
 import { useQuery } from '@tanstack/react-query';
 import { LayoutDashboard, MessageSquare, Workflow, Settings } from 'lucide-react';
-import { listWorkflowRuns, getUpdateCheck } from '@/lib/api';
+import { listDashboardRuns, getUpdateCheck } from '@/lib/api';
 import { cn } from '@/lib/utils';
 
 const tabs = [
@@ -12,12 +12,15 @@ const tabs = [
 ] as const;
 
 export function TopNav(): React.ReactElement {
-  const { data: runningRuns } = useQuery({
-    queryKey: ['workflowRuns', { status: 'running' }],
-    queryFn: () => listWorkflowRuns({ status: 'running', limit: 1 }),
+  // We only need `counts.running` — a server-side aggregate independent of
+  // the `runs` array. `limit: 1` minimises the `runs` payload that the API
+  // returns alongside the counts (we discard it).
+  const { data: dashboardRuns } = useQuery({
+    queryKey: ['dashboardRuns', { status: 'running', forCount: true }],
+    queryFn: () => listDashboardRuns({ status: 'running', limit: 1 }),
     refetchInterval: 10_000,
   });
-  const hasRunning = (runningRuns?.length ?? 0) > 0;
+  const runningCount = dashboardRuns?.counts.running ?? 0;
 
   const { data: updateCheck } = useQuery({
     queryKey: ['update-check'],
@@ -53,8 +56,13 @@ export function TopNav(): React.ReactElement {
         >
           <Icon className="h-4 w-4" />
           {label}
-          {to === '/dashboard' && hasRunning && (
-            <span className="flex h-2 w-2 rounded-full bg-primary animate-pulse" />
+          {to === '/dashboard' && runningCount > 0 && (
+            <span
+              className="ml-1 inline-flex min-w-[1.25rem] items-center justify-center rounded-full bg-primary px-1.5 py-0.5 text-[10px] font-medium text-primary-foreground"
+              aria-label={`${runningCount} workflows running`}
+            >
+              {runningCount}
+            </span>
           )}
         </NavLink>
       ))}
diff --git a/packages/web/src/components/workflows/BuilderToolbar.tsx b/packages/web/src/components/workflows/BuilderToolbar.tsx
index 4be85cea58..1055a7c4b1 100644
--- a/packages/web/src/components/workflows/BuilderToolbar.tsx
+++ b/packages/web/src/components/workflows/BuilderToolbar.tsx
@@ -5,20 +5,21 @@ import { Button } from '@/components/ui/button';
 import { cn } from '@/lib/utils';
 import { listWorkflows } from '@/lib/api';
 import { useProject } from '@/contexts/ProjectContext';
+import { useProviders } from '@/hooks/useProviders';
 
 export type ViewMode = 'hidden' | 'split' | 'full';
 
 export interface BuilderToolbarProps {
   workflowName: string;
   workflowDescription: string;
-  provider: 'claude' | 'codex' | undefined;
+  provider: string | undefined;
   model: string | undefined;
   hasUnsavedChanges: boolean;
   validationErrors: string[];
   viewMode: ViewMode;
   onNameChange: (name: string) => void;
   onDescriptionChange: (desc: string) => void;
-  onProviderChange: (p: 'claude' | 'codex' | undefined) => void;
+  onProviderChange: (p: string | undefined) => void;
   onModelChange: (m: string | undefined) => void;
   onViewModeChange: (mode: ViewMode) => void;
   onValidate: () => void;
@@ -57,6 +58,7 @@ export function BuilderToolbar({
     ? codebases?.find(cb => cb.id === selectedProjectId)?.default_cwd
     : undefined;
 
+  const { providers } = useProviders();
   const [showDescription, setShowDescription] = useState(false);
 
   const { data: workflows, isError: workflowsError } = useQuery({
@@ -158,13 +160,16 @@ export function BuilderToolbar({
           <select
             value={provider ?? ''}
             onChange={(e): void => {
-              onProviderChange((e.target.value || undefined) as 'claude' | 'codex' | undefined);
+              onProviderChange(e.target.value || undefined);
             }}
             className="rounded-md border border-border bg-surface px-1.5 py-1 text-xs text-text-primary focus:outline-none focus:ring-1 focus:ring-accent"
           >
             <option value="">Provider</option>
-            <option value="claude">Claude</option>
-            <option value="codex">Codex</option>
+            {providers.map(p => (
+              <option key={p.id} value={p.id}>
+                {p.displayName}
+              </option>
+            ))}
           </select>
 
           <input
diff --git a/packages/web/src/components/workflows/CommandPicker.tsx b/packages/web/src/components/workflows/CommandPicker.tsx
index 153b3c562f..84fb8aee7c 100644
--- a/packages/web/src/components/workflows/CommandPicker.tsx
+++ b/packages/web/src/components/workflows/CommandPicker.tsx
@@ -119,9 +119,9 @@ export function CommandPicker({
                     <span
                       className={cn(
                         'text-[9px] font-medium px-1.5 py-0.5 rounded shrink-0',
-                        cmd.source === 'project'
-                          ? 'bg-node-command/20 text-node-command'
-                          : 'bg-surface-inset text-text-tertiary'
+                        cmd.source === 'project' && 'bg-node-command/20 text-node-command',
+                        cmd.source === 'global' && 'bg-node-loop/20 text-node-loop',
+                        cmd.source === 'bundled' && 'bg-surface-inset text-text-tertiary'
                       )}
                     >
                       {cmd.source}
diff --git a/packages/web/src/components/workflows/NodeInspector.tsx b/packages/web/src/components/workflows/NodeInspector.tsx
index 927e5edf91..1d4748fecc 100644
--- a/packages/web/src/components/workflows/NodeInspector.tsx
+++ b/packages/web/src/components/workflows/NodeInspector.tsx
@@ -5,6 +5,7 @@ import { ScrollArea } from '@/components/ui/scroll-area';
 import { cn } from '@/lib/utils';
 import type { DagNodeData } from './DagNodeComponent';
 import type { CommandEntry, DagNode } from '@/lib/api';
+import { useProviders } from '@/hooks/useProviders';
 
 // Keep in sync with triggerRuleSchema.options in @archon/workflows/schemas/dag-node.ts
 // (api.generated.d.ts is type-only and cannot export runtime values)
@@ -59,6 +60,36 @@ function Field({
   );
 }
 
+function ProviderField({
+  node,
+  onUpdate,
+  selectClass: cls,
+}: {
+  node: DagNodeData;
+  onUpdate: (updates: Partial<DagNodeData>) => void;
+  selectClass: string;
+}): React.ReactElement {
+  const { providers } = useProviders();
+  return (
+    <Field label="Provider">
+      <select
+        value={node.provider ?? ''}
+        onChange={(e): void => {
+          onUpdate({ provider: e.target.value || undefined });
+        }}
+        className={cls}
+      >
+        <option value="">Inherit</option>
+        {providers.map(p => (
+          <option key={p.id} value={p.id}>
+            {p.displayName}
+          </option>
+        ))}
+      </select>
+    </Field>
+  );
+}
+
 type ToolsMode = 'none' | 'allow' | 'deny';
 
 const TOOLS_MODE_LABELS: Record<ToolsMode, string> = {
@@ -316,21 +347,7 @@ function ExecutionTab({
     <div className="flex flex-col gap-3 p-3">
       {!isBash && (
         <>
-          <Field label="Provider">
-            <select
-              value={node.provider ?? ''}
-              onChange={(e): void => {
-                onUpdate({
-                  provider: (e.target.value || undefined) as 'claude' | 'codex' | undefined,
-                });
-              }}
-              className={selectClass}
-            >
-              <option value="">Inherit</option>
-              <option value="claude">Claude</option>
-              <option value="codex">Codex</option>
-            </select>
-          </Field>
+          <ProviderField node={node} onUpdate={onUpdate} selectClass={selectClass} />
 
           <Field label="Model">
             <input
@@ -625,11 +642,9 @@ function JsonTextareaField({
 function AdvancedTab({
   node,
   onUpdate,
-  onDelete,
 }: {
   node: DagNodeData;
   onUpdate: (updates: Partial<DagNodeData>) => void;
-  onDelete: () => void;
 }): React.ReactElement {
   return (
     <div className="flex flex-col gap-3 p-3">
@@ -679,12 +694,6 @@ function AdvancedTab({
           onUpdate({ hooks: v });
         }}
       />
-
-      <div className="border-t border-border pt-3 mt-2">
-        <Button variant="destructive" size="sm" onClick={onDelete} className="w-full">
-          Delete Node
-        </Button>
-      </div>
     </div>
   );
 }
@@ -701,14 +710,23 @@ function DagInspector({
   return (
     <div key={node.id} className="flex flex-col h-full border-l border-border bg-surface">
       {/* Header */}
-      <div className="flex items-center justify-between px-3 py-2 border-b border-border">
-        <span className="text-xs font-semibold text-text-primary truncate">
+      <div className="flex items-center gap-2 px-3 py-2 border-b border-border">
+        <span className="flex-1 truncate text-xs font-semibold text-text-primary">
           {node.label || node.id}
         </span>
+        <Button
+          variant="destructive"
+          size="sm"
+          onClick={onDelete}
+          className="h-6 shrink-0 px-2 text-[10px]"
+          aria-label="Delete node"
+        >
+          Delete
+        </Button>
         <button
           type="button"
           onClick={onClose}
-          className="text-text-tertiary hover:text-text-primary text-sm leading-none px-1"
+          className="shrink-0 px-1 text-sm leading-none text-text-tertiary hover:text-text-primary"
           title="Close inspector"
         >
           x
@@ -753,7 +771,7 @@ function DagInspector({
 
           {!isBash && (
             <TabsContent value="advanced">
-              <AdvancedTab key={node.id} node={node} onUpdate={onUpdate} onDelete={onDelete} />
+              <AdvancedTab key={node.id} node={node} onUpdate={onUpdate} />
             </TabsContent>
           )}
         </ScrollArea>
diff --git a/packages/web/src/components/workflows/NodePalette.tsx b/packages/web/src/components/workflows/NodePalette.tsx
index d54c81969a..3bec3062e7 100644
--- a/packages/web/src/components/workflows/NodePalette.tsx
+++ b/packages/web/src/components/workflows/NodePalette.tsx
@@ -29,6 +29,7 @@ export function NodePalette(): React.ReactElement {
   };
 
   const bundled = commands?.filter((c: CommandEntry) => c.source === 'bundled') ?? [];
+  const global = commands?.filter((c: CommandEntry) => c.source === 'global') ?? [];
   const project = commands?.filter((c: CommandEntry) => c.source === 'project') ?? [];
 
   return (
@@ -89,6 +90,27 @@ export function NodePalette(): React.ReactElement {
         </>
       )}
 
+      {global.length > 0 && (
+        <>
+          <h4 className="text-[10px] font-medium text-text-tertiary uppercase tracking-wide mt-2 mb-1">
+            Global (~/.archon/commands/)
+          </h4>
+          {global.map((cmd: CommandEntry) => (
+            <div
+              key={cmd.name}
+              draggable
+              onDragStart={(e): void => {
+                onDragStart(e, 'command', cmd.name);
+              }}
+              className="flex items-center gap-2 px-2 py-1.5 rounded-md border border-border hover:border-accent hover:bg-accent/5 cursor-grab text-xs text-text-primary mb-1"
+            >
+              <span className="text-[10px] text-text-tertiary font-medium">CMD</span>
+              <span className="truncate">{cmd.name}</span>
+            </div>
+          ))}
+        </>
+      )}
+
       {bundled.length > 0 && (
         <>
           <h4 className="text-[10px] font-medium text-text-tertiary uppercase tracking-wide mt-2 mb-1">
diff --git a/packages/web/src/components/workflows/WorkflowBuilder.tsx b/packages/web/src/components/workflows/WorkflowBuilder.tsx
index 8a0d8abe3d..674b081d8e 100644
--- a/packages/web/src/components/workflows/WorkflowBuilder.tsx
+++ b/packages/web/src/components/workflows/WorkflowBuilder.tsx
@@ -127,7 +127,7 @@ function WorkflowBuilderInner(): React.ReactElement {
   // Core state
   const [workflowName, setWorkflowName] = useState('');
   const [workflowDescription, setWorkflowDescription] = useState('');
-  const [provider, setProvider] = useState<'claude' | 'codex' | undefined>(undefined);
+  const [provider, setProvider] = useState<string | undefined>(undefined);
   const [model, setModel] = useState<string | undefined>(undefined);
   const [hasUnsavedChanges, setHasUnsavedChanges] = useState(false);
   const [validationErrors, setValidationErrors] = useState<string[]>([]);
@@ -172,11 +172,30 @@ function WorkflowBuilderInner(): React.ReactElement {
     setHasUnsavedChanges(true);
   }, []);
 
+  // Refs mirror the latest nodes/edges so snapshot-taking callbacks don't
+  // close over stale values when events fire in the same tick as a render.
+  const nodesRef = useRef(nodes);
+  const edgesRef = useRef(edges);
+  useEffect(() => {
+    nodesRef.current = nodes;
+    edgesRef.current = edges;
+  }, [nodes, edges]);
+
+  const pushSnapshotLatest = useCallback((): void => {
+    pushSnapshot({ nodes: nodesRef.current, edges: edgesRef.current });
+  }, [pushSnapshot]);
+
   const buildDefinition = useCallback((): WorkflowDefinition => {
     const name = workflowName.trim() || 'untitled';
     const description = workflowDescription;
     const dagNodes = reactFlowToDagNodes(nodes, edges);
-    return { name, description, provider, model, nodes: dagNodes };
+    return {
+      name,
+      description,
+      provider,
+      model,
+      nodes: dagNodes,
+    };
   }, [workflowName, workflowDescription, provider, model, nodes, edges]);
 
   const loadWorkflow = useCallback(
@@ -230,14 +249,21 @@ function WorkflowBuilderInner(): React.ReactElement {
     [selectedNodeId, setNodes, markDirty]
   );
 
+  const handleNodeDeleteById = useCallback(
+    (nodeId: string): void => {
+      pushSnapshotLatest();
+      setNodes(nds => nds.filter(n => n.id !== nodeId));
+      setEdges(eds => eds.filter(e => e.source !== nodeId && e.target !== nodeId));
+      setSelectedNodeId(prev => (prev === nodeId ? null : prev));
+      markDirty();
+    },
+    [setNodes, setEdges, markDirty, pushSnapshotLatest]
+  );
+
   const handleNodeDelete = useCallback((): void => {
     if (!selectedNodeId) return;
-    pushSnapshot({ nodes, edges });
-    setNodes(nds => nds.filter(n => n.id !== selectedNodeId));
-    setEdges(eds => eds.filter(e => e.source !== selectedNodeId && e.target !== selectedNodeId));
-    setSelectedNodeId(null);
-    markDirty();
-  }, [selectedNodeId, setNodes, setEdges, markDirty, pushSnapshot, nodes, edges]);
+    handleNodeDeleteById(selectedNodeId);
+  }, [selectedNodeId, handleNodeDeleteById]);
 
   // Toolbar action handlers
   const handleValidate = useCallback(async (): Promise<void> => {
@@ -355,7 +381,7 @@ function WorkflowBuilderInner(): React.ReactElement {
           position: { x: 200, y: 200 },
           data: { id, label: 'Prompt', nodeType: 'prompt' },
         };
-        pushSnapshot({ nodes, edges });
+        pushSnapshotLatest();
         setNodes(nds => [...nds, newNode]);
         markDirty();
       },
@@ -367,7 +393,7 @@ function WorkflowBuilderInner(): React.ReactElement {
           position: { x: 200, y: 200 },
           data: { id, label: 'Shell', nodeType: 'bash' },
         };
-        pushSnapshot({ nodes, edges });
+        pushSnapshotLatest();
         setNodes(nds => [...nds, newNode]);
         markDirty();
       },
@@ -387,7 +413,7 @@ function WorkflowBuilderInner(): React.ReactElement {
           position: { x: sourceNode.position.x + 30, y: sourceNode.position.y + 30 },
           data: { ...sourceNode.data, id },
         };
-        pushSnapshot({ nodes, edges });
+        pushSnapshotLatest();
         setNodes(nds => [...nds, newNode]);
         markDirty();
       },
@@ -399,9 +425,8 @@ function WorkflowBuilderInner(): React.ReactElement {
       handleToggleValidationPanel,
       handleNodeDelete,
       nodes,
-      edges,
       selectedNodeId,
-      pushSnapshot,
+      pushSnapshotLatest,
       setNodes,
       markDirty,
     ]
@@ -476,10 +501,9 @@ function WorkflowBuilderInner(): React.ReactElement {
                   setNodes={setNodes}
                   setEdges={setEdges}
                   onNodeSelect={setSelectedNodeId}
+                  onNodeDelete={handleNodeDeleteById}
                   onDirty={markDirty}
-                  onPushSnapshot={(): void => {
-                    pushSnapshot({ nodes, edges });
-                  }}
+                  onPushSnapshot={pushSnapshotLatest}
                   commands={commandList}
                 />
               </div>
diff --git a/packages/web/src/components/workflows/WorkflowCanvas.tsx b/packages/web/src/components/workflows/WorkflowCanvas.tsx
index f784c67c4f..e1c6170b16 100644
--- a/packages/web/src/components/workflows/WorkflowCanvas.tsx
+++ b/packages/web/src/components/workflows/WorkflowCanvas.tsx
@@ -82,6 +82,7 @@ interface WorkflowCanvasProps {
   setNodes: React.Dispatch<React.SetStateAction<DagFlowNode[]>>;
   setEdges: React.Dispatch<React.SetStateAction<Edge[]>>;
   onNodeSelect: (nodeId: string | null) => void;
+  onNodeDelete: (nodeId: string) => void;
   onDirty: () => void;
   onPushSnapshot?: () => void;
   commands: CommandEntry[];
@@ -100,12 +101,19 @@ export function WorkflowCanvas({
   setNodes,
   setEdges,
   onNodeSelect,
+  onNodeDelete,
   onDirty,
   onPushSnapshot,
   commands,
 }: WorkflowCanvasProps): React.ReactElement {
   const { screenToFlowPosition } = useReactFlow();
   const [quickAddPosition, setQuickAddPosition] = useState<QuickAddPosition | null>(null);
+  const [contextMenu, setContextMenu] = useState<{
+    x: number;
+    y: number;
+    nodeId: string;
+  } | null>(null);
+  const contextMenuRef = useRef<HTMLDivElement | null>(null);
 
   const nodeTypes: NodeTypes = useMemo(() => ({ dagNode: dagNodeComponent }), []);
 
@@ -164,10 +172,12 @@ export function WorkflowCanvas({
         },
       };
 
+      onPushSnapshot?.();
       setNodes(nds => [...nds, newNode]);
+      onNodeSelect(id);
       onDirty();
     },
-    [screenToFlowPosition, setNodes, onDirty]
+    [screenToFlowPosition, setNodes, onNodeSelect, onDirty, onPushSnapshot]
   );
 
   // Track whether we've already pushed a snapshot for the current drag gesture
@@ -278,17 +288,63 @@ export function WorkflowCanvas({
         },
       };
 
+      onPushSnapshot?.();
       setNodes(nds => [...nds, newNode]);
+      onNodeSelect(id);
       onDirty();
       setQuickAddPosition(null);
     },
-    [quickAddPosition, setNodes, onDirty]
+    [quickAddPosition, setNodes, onNodeSelect, onDirty, onPushSnapshot]
   );
 
   const handleQuickAddClose = useCallback(() => {
     setQuickAddPosition(null);
   }, []);
 
+  // Approximate menu size used for viewport-edge clamping.
+  const CONTEXT_MENU_WIDTH = 160;
+  const CONTEXT_MENU_HEIGHT = 40;
+
+  const handleNodeContextMenu = useCallback(
+    (e: React.MouseEvent, node: DagFlowNode) => {
+      e.preventDefault();
+      onNodeSelect(node.id);
+      const x = Math.min(e.clientX, window.innerWidth - CONTEXT_MENU_WIDTH);
+      const y = Math.min(e.clientY, window.innerHeight - CONTEXT_MENU_HEIGHT);
+      setContextMenu({ x, y, nodeId: node.id });
+    },
+    [onNodeSelect]
+  );
+
+  // Dismiss the context menu on Escape or any click/contextmenu outside it.
+  useEffect(() => {
+    if (!contextMenu) return;
+
+    const onKey = (e: KeyboardEvent): void => {
+      if (e.key === 'Escape') setContextMenu(null);
+    };
+    const onClickOutside = (e: MouseEvent): void => {
+      if (
+        contextMenuRef.current &&
+        e.target instanceof Node &&
+        contextMenuRef.current.contains(e.target)
+      ) {
+        return;
+      }
+      setContextMenu(null);
+    };
+
+    window.addEventListener('keydown', onKey);
+    // Use capture so we beat ReactFlow's own handlers and any stopPropagation.
+    window.addEventListener('mousedown', onClickOutside, true);
+    window.addEventListener('contextmenu', onClickOutside, true);
+    return (): void => {
+      window.removeEventListener('keydown', onKey);
+      window.removeEventListener('mousedown', onClickOutside, true);
+      window.removeEventListener('contextmenu', onClickOutside, true);
+    };
+  }, [contextMenu]);
+
   return (
     <div className="relative w-full h-full">
       <ReactFlow
@@ -302,6 +358,7 @@ export function WorkflowCanvas({
         onNodeClick={(_e, node): void => {
           onNodeSelect(node.id);
         }}
+        onNodeContextMenu={handleNodeContextMenu}
         onPaneClick={handlePaneClick}
         nodeTypes={nodeTypes}
         panOnDrag
@@ -324,6 +381,25 @@ export function WorkflowCanvas({
           commands={commands}
         />
       )}
+
+      {contextMenu && (
+        <div
+          ref={contextMenuRef}
+          className="fixed z-50 min-w-[140px] rounded-md border border-border bg-surface-elevated py-1 shadow-md"
+          style={{ left: contextMenu.x, top: contextMenu.y }}
+        >
+          <button
+            type="button"
+            onClick={(): void => {
+              onNodeDelete(contextMenu.nodeId);
+              setContextMenu(null);
+            }}
+            className="w-full px-3 py-1.5 text-left text-xs text-error hover:bg-surface"
+          >
+            Delete node
+          </button>
+        </div>
+      )}
     </div>
   );
 }
diff --git a/packages/web/src/hooks/useBuilderKeyboard.test.ts b/packages/web/src/hooks/useBuilderKeyboard.test.ts
new file mode 100644
index 0000000000..8239741657
--- /dev/null
+++ b/packages/web/src/hooks/useBuilderKeyboard.test.ts
@@ -0,0 +1,136 @@
+import { describe, test, expect, mock, beforeEach } from 'bun:test';
+import {
+  handleBuilderKeydown,
+  isInputTarget,
+  type BuilderKeyboardActions,
+} from './useBuilderKeyboard';
+
+function makeActions(): BuilderKeyboardActions & {
+  calls: Record<string, number>;
+} {
+  const calls: Record<string, number> = {};
+  const bump = (name: string): (() => void) => {
+    return (): void => {
+      calls[name] = (calls[name] ?? 0) + 1;
+    };
+  };
+  return {
+    calls,
+    onSave: bump('onSave'),
+    onUndo: bump('onUndo'),
+    onRedo: bump('onRedo'),
+    onToggleLibrary: bump('onToggleLibrary'),
+    onToggleYaml: bump('onToggleYaml'),
+    onToggleValidation: bump('onToggleValidation'),
+    onAddPrompt: bump('onAddPrompt'),
+    onAddBash: bump('onAddBash'),
+    onDeleteSelected: bump('onDeleteSelected'),
+    onDuplicateSelected: bump('onDuplicateSelected'),
+    onQuickAdd: bump('onQuickAdd'),
+    onFitView: bump('onFitView'),
+    onSelectAll: bump('onSelectAll'),
+  };
+}
+
+function makeEvent(
+  key: string,
+  target: { tagName?: string; isContentEditable?: boolean; role?: string } | null
+): KeyboardEvent {
+  const el =
+    target === null
+      ? null
+      : ({
+          tagName: target.tagName ?? 'DIV',
+          isContentEditable: target.isContentEditable ?? false,
+          getAttribute: (name: string): string | null =>
+            name === 'role' ? (target.role ?? null) : null,
+        } as unknown as HTMLElement);
+  return {
+    key,
+    target: el,
+    metaKey: false,
+    ctrlKey: false,
+    shiftKey: false,
+    preventDefault: mock(() => {}),
+  } as unknown as KeyboardEvent;
+}
+
+describe('isInputTarget', () => {
+  test('returns true for INPUT, TEXTAREA, SELECT', () => {
+    expect(isInputTarget(makeEvent('a', { tagName: 'INPUT' }))).toBe(true);
+    expect(isInputTarget(makeEvent('a', { tagName: 'TEXTAREA' }))).toBe(true);
+    expect(isInputTarget(makeEvent('a', { tagName: 'SELECT' }))).toBe(true);
+  });
+
+  test('returns true for contentEditable elements', () => {
+    expect(isInputTarget(makeEvent('a', { tagName: 'DIV', isContentEditable: true }))).toBe(true);
+  });
+
+  test('returns true for ARIA editable roles (combobox, textbox, searchbox)', () => {
+    expect(isInputTarget(makeEvent('a', { tagName: 'DIV', role: 'combobox' }))).toBe(true);
+    expect(isInputTarget(makeEvent('a', { tagName: 'DIV', role: 'textbox' }))).toBe(true);
+    expect(isInputTarget(makeEvent('a', { tagName: 'DIV', role: 'searchbox' }))).toBe(true);
+  });
+
+  test('returns false for regular elements without editable role', () => {
+    expect(isInputTarget(makeEvent('a', { tagName: 'DIV' }))).toBe(false);
+    expect(isInputTarget(makeEvent('a', { tagName: 'BUTTON' }))).toBe(false);
+    expect(isInputTarget(makeEvent('a', { tagName: 'DIV', role: 'menu' }))).toBe(false);
+  });
+
+  test('returns false when target is null', () => {
+    expect(isInputTarget(makeEvent('a', null))).toBe(false);
+  });
+});
+
+describe('handleBuilderKeydown — delete invariant', () => {
+  let actions: ReturnType<typeof makeActions>;
+
+  beforeEach(() => {
+    actions = makeActions();
+  });
+
+  test('Delete key on canvas triggers onDeleteSelected', () => {
+    handleBuilderKeydown(makeEvent('Delete', { tagName: 'DIV' }), actions);
+    expect(actions.calls.onDeleteSelected).toBe(1);
+  });
+
+  test('Backspace key on canvas triggers onDeleteSelected', () => {
+    handleBuilderKeydown(makeEvent('Backspace', { tagName: 'DIV' }), actions);
+    expect(actions.calls.onDeleteSelected).toBe(1);
+  });
+
+  test('Backspace in INPUT does NOT trigger onDeleteSelected', () => {
+    handleBuilderKeydown(makeEvent('Backspace', { tagName: 'INPUT' }), actions);
+    expect(actions.calls.onDeleteSelected).toBeUndefined();
+  });
+
+  test('Backspace in TEXTAREA does NOT trigger onDeleteSelected', () => {
+    handleBuilderKeydown(makeEvent('Backspace', { tagName: 'TEXTAREA' }), actions);
+    expect(actions.calls.onDeleteSelected).toBeUndefined();
+  });
+
+  test('Backspace in contentEditable does NOT trigger onDeleteSelected', () => {
+    handleBuilderKeydown(
+      makeEvent('Backspace', { tagName: 'DIV', isContentEditable: true }),
+      actions
+    );
+    expect(actions.calls.onDeleteSelected).toBeUndefined();
+  });
+
+  test('Backspace in ARIA combobox does NOT trigger onDeleteSelected', () => {
+    handleBuilderKeydown(makeEvent('Backspace', { tagName: 'DIV', role: 'combobox' }), actions);
+    expect(actions.calls.onDeleteSelected).toBeUndefined();
+  });
+
+  test('Delete in ARIA textbox does NOT trigger onDeleteSelected', () => {
+    handleBuilderKeydown(makeEvent('Delete', { tagName: 'DIV', role: 'textbox' }), actions);
+    expect(actions.calls.onDeleteSelected).toBeUndefined();
+  });
+
+  test('enabled=false suppresses all shortcuts', () => {
+    handleBuilderKeydown(makeEvent('Delete', { tagName: 'DIV' }), actions, false);
+    handleBuilderKeydown(makeEvent('Backspace', { tagName: 'DIV' }), actions, false);
+    expect(actions.calls.onDeleteSelected).toBeUndefined();
+  });
+});
diff --git a/packages/web/src/hooks/useBuilderKeyboard.ts b/packages/web/src/hooks/useBuilderKeyboard.ts
index 192f29bd2b..89343331bd 100644
--- a/packages/web/src/hooks/useBuilderKeyboard.ts
+++ b/packages/web/src/hooks/useBuilderKeyboard.ts
@@ -1,6 +1,6 @@
 import { useEffect, useCallback } from 'react';
 
-interface BuilderKeyboardActions {
+export interface BuilderKeyboardActions {
   onSave: () => void;
   onUndo: () => void;
   onRedo: () => void;
@@ -16,97 +16,113 @@ interface BuilderKeyboardActions {
   onSelectAll?: () => void;
 }
 
-function isInputTarget(e: KeyboardEvent): boolean {
-  const tag = (e.target as HTMLElement).tagName;
-  return (
-    tag === 'INPUT' ||
-    tag === 'TEXTAREA' ||
-    tag === 'SELECT' ||
-    (e.target as HTMLElement).isContentEditable
-  );
+const EDITABLE_ARIA_ROLES = new Set(['combobox', 'textbox', 'searchbox']);
+
+export function isInputTarget(e: KeyboardEvent): boolean {
+  const target = e.target as HTMLElement | null;
+  if (!target) return false;
+  const tag = target.tagName;
+  if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return true;
+  if (target.isContentEditable) return true;
+  const role = target.getAttribute?.('role');
+  if (role && EDITABLE_ARIA_ROLES.has(role)) return true;
+  return false;
 }
 
-export function useBuilderKeyboard(actions: BuilderKeyboardActions, enabled = true): void {
-  const handleKeyDown = useCallback(
-    (e: KeyboardEvent) => {
-      if (!enabled) return;
+export function handleBuilderKeydown(
+  e: KeyboardEvent,
+  actions: BuilderKeyboardActions,
+  enabled = true
+): void {
+  if (!enabled) return;
 
-      const mod = e.metaKey || e.ctrlKey;
-      const inInput = isInputTarget(e);
+  const mod = e.metaKey || e.ctrlKey;
+  const inInput = isInputTarget(e);
 
-      // --- Always-active shortcuts (even in inputs) ---
-      if (mod) {
-        if (e.key === 's') {
-          e.preventDefault();
-          actions.onSave();
-          return;
-        }
-        if (e.key === 'z' && e.shiftKey) {
-          e.preventDefault();
-          actions.onRedo();
-          return;
-        }
-        if (e.key === 'z') {
-          e.preventDefault();
-          actions.onUndo();
-          return;
-        }
-        if (e.key === '\\') {
-          e.preventDefault();
-          actions.onToggleLibrary();
-          return;
-        }
-        if (e.key === 'j') {
-          e.preventDefault();
-          actions.onToggleYaml();
-          return;
-        }
-        if (e.key === '.') {
-          e.preventDefault();
-          actions.onToggleValidation();
-          return;
-        }
-      }
+  // --- Always-active shortcuts (even in inputs) ---
+  if (mod) {
+    if (e.key === 's') {
+      e.preventDefault();
+      actions.onSave();
+      return;
+    }
+    if (e.key === 'z' && e.shiftKey) {
+      e.preventDefault();
+      actions.onRedo();
+      return;
+    }
+    if (e.key === 'z') {
+      e.preventDefault();
+      actions.onUndo();
+      return;
+    }
+    if (e.key === '\\') {
+      e.preventDefault();
+      actions.onToggleLibrary();
+      return;
+    }
+    if (e.key === 'j') {
+      e.preventDefault();
+      actions.onToggleYaml();
+      return;
+    }
+    if (e.key === '.') {
+      e.preventDefault();
+      actions.onToggleValidation();
+      return;
+    }
+  }
 
-      // --- Only when NOT in input/textarea ---
-      if (inInput) return;
+  // --- Only when NOT in input/textarea ---
+  if (inInput) return;
 
-      if (mod) {
-        if (e.key === 'd') {
-          e.preventDefault();
-          actions.onDuplicateSelected();
-          return;
-        }
-        if (e.key === '0') {
-          e.preventDefault();
-          actions.onFitView?.();
-          return;
-        }
-        if (e.key === 'a') {
-          e.preventDefault();
-          actions.onSelectAll?.();
-          return;
-        }
-      }
+  if (mod) {
+    if (e.key === 'd') {
+      e.preventDefault();
+      actions.onDuplicateSelected();
+      return;
+    }
+    if (e.key === '0') {
+      e.preventDefault();
+      actions.onFitView?.();
+      return;
+    }
+    if (e.key === 'a') {
+      e.preventDefault();
+      actions.onSelectAll?.();
+      return;
+    }
+  }
 
-      // Single-key shortcuts
-      switch (e.key) {
-        case 'n':
-          actions.onQuickAdd?.();
-          break;
-        case 'p':
-          actions.onAddPrompt();
-          break;
-        case 'b':
-          actions.onAddBash();
-          break;
-        case 'Delete':
-          actions.onDeleteSelected();
-          break;
-        case 'f':
-          actions.onFitView?.();
-          break;
-      }
+  // Single-key shortcuts
+  switch (e.key) {
+    case 'n':
+      actions.onQuickAdd?.();
+      break;
+    case 'p':
+      actions.onAddPrompt();
+      break;
+    case 'b':
+      actions.onAddBash();
+      break;
+    case 'Delete':
+    case 'Backspace':
+      // Backspace is the natural delete key on macOS keyboards, which lack
+      // a dedicated Delete key. The isInputTarget() guard above prevents
+      // this from interfering with text fields.
+      e.preventDefault();
+      actions.onDeleteSelected();
+      break;
+    case 'f':
+      actions.onFitView?.();
+      break;
+  }
+}
+
+export function useBuilderKeyboard(actions: BuilderKeyboardActions, enabled = true): void {
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent) => {
+      handleBuilderKeydown(e, actions, enabled);
     },
     [actions, enabled]
   );
diff --git a/packages/web/src/hooks/useProviders.ts b/packages/web/src/hooks/useProviders.ts
new file mode 100644
index 0000000000..2385ba9278
--- /dev/null
+++ b/packages/web/src/hooks/useProviders.ts
@@ -0,0 +1,24 @@
+import { useQuery } from '@tanstack/react-query';
+import { listProviders, type ProviderInfo } from '@/lib/api';
+
+/**
+ * Fetch registered providers from the server.
+ * Cached for the session — provider list rarely changes at runtime.
+ */
+export function useProviders(): {
+  providers: ProviderInfo[];
+  isLoading: boolean;
+  isError: boolean;
+} {
+  const { data, isLoading, isError } = useQuery({
+    queryKey: ['providers'],
+    queryFn: listProviders,
+    staleTime: 5 * 60 * 1000, // 5 min — provider list rarely changes
+  });
+
+  return {
+    providers: data ?? [],
+    isLoading,
+    isError,
+  };
+}
diff --git a/packages/web/src/lib/api.generated.d.ts b/packages/web/src/lib/api.generated.d.ts
index 193c619588..68b4d0a02f 100644
--- a/packages/web/src/lib/api.generated.d.ts
+++ b/packages/web/src/lib/api.generated.d.ts
@@ -549,51 +549,7 @@ export interface paths {
     };
     options?: never;
     head?: never;
-    /** Update codebase consent flags (e.g. allow_env_keys) */
-    patch: {
-      parameters: {
-        query?: never;
-        header?: never;
-        path: {
-          id: string;
-        };
-        cookie?: never;
-      };
-      requestBody: {
-        content: {
-          'application/json': components['schemas']['UpdateCodebaseBody'];
-        };
-      };
-      responses: {
-        /** @description Updated codebase */
-        200: {
-          headers: {
-            [name: string]: unknown;
-          };
-          content: {
-            'application/json': components['schemas']['Codebase'];
-          };
-        };
-        /** @description Not found */
-        404: {
-          headers: {
-            [name: string]: unknown;
-          };
-          content: {
-            'application/json': components['schemas']['Error'];
-          };
-        };
-        /** @description Server error */
-        500: {
-          headers: {
-            [name: string]: unknown;
-          };
-          content: {
-            'application/json': components['schemas']['Error'];
-          };
-        };
-      };
-    };
+    patch?: never;
     trace?: never;
   };
   '/api/codebases/{id}/env': {
@@ -1820,6 +1776,42 @@ export interface paths {
     };
     trace?: never;
   };
+  '/api/providers': {
+    parameters: {
+      query?: never;
+      header?: never;
+      path?: never;
+      cookie?: never;
+    };
+    /** List registered AI providers */
+    get: {
+      parameters: {
+        query?: never;
+        header?: never;
+        path?: never;
+        cookie?: never;
+      };
+      requestBody?: never;
+      responses: {
+        /** @description List of registered providers */
+        200: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content: {
+            'application/json': components['schemas']['ProviderListResponse'];
+          };
+        };
+      };
+    };
+    put?: never;
+    post?: never;
+    delete?: never;
+    options?: never;
+    head?: never;
+    patch?: never;
+    trace?: never;
+  };
   '/api/codebases/{id}/environments': {
     parameters: {
       query?: never;
@@ -2010,7 +2002,6 @@ export interface components {
       repository_url: string | null;
       default_cwd: string;
       ai_assistant_type: string;
-      allow_env_keys: boolean;
       commands: {
         [key: string]: components['schemas']['CodebaseCommand'];
       };
@@ -2021,10 +2012,6 @@ export interface components {
     AddCodebaseBody: {
       url?: string;
       path?: string;
-      allowEnvKeys?: boolean;
-    };
-    UpdateCodebaseBody: {
-      allowEnvKeys: boolean;
     };
     DeleteCodebaseResponse: {
       success: boolean;
@@ -2046,8 +2033,7 @@ export interface components {
       /** @enum {string} */
       trigger_rule?: 'all_success' | 'one_success' | 'none_failed_min_one_success' | 'all_done';
       model?: string;
-      /** @enum {string} */
-      provider?: 'claude' | 'codex';
+      provider?: string;
       /** @enum {string} */
       context?: 'fresh' | 'shared';
       output_format?: {
@@ -2213,6 +2199,17 @@ export interface components {
       };
       mcp?: string;
       skills?: string[];
+      agents?: {
+        [key: string]: {
+          description: string;
+          prompt: string;
+          model?: string;
+          tools?: string[];
+          disallowedTools?: string[];
+          skills?: string[];
+          maxTurns?: number;
+        };
+      };
       /** @enum {string} */
       effort?: 'low' | 'medium' | 'high' | 'max';
       thinking?:
@@ -2293,8 +2290,7 @@ export interface components {
     WorkflowDefinition: {
       name: string;
       description: string;
-      /** @enum {string} */
-      provider?: 'claude' | 'codex';
+      provider?: string;
       model?: string;
       /** @enum {string} */
       modelReasoningEffort?: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
@@ -2352,7 +2348,7 @@ export interface components {
       nodes: components['schemas']['DagNode'][];
     };
     /** @enum {string} */
-    WorkflowSource: 'project' | 'bundled';
+    WorkflowSource: 'project' | 'bundled' | 'global';
     WorkflowListEntry: {
       workflow: components['schemas']['WorkflowDefinition'];
       source: components['schemas']['WorkflowSource'];
@@ -2484,21 +2480,14 @@ export interface components {
     CommandListResponse: {
       commands: components['schemas']['CommandEntry'][];
     };
+    ProviderDefaults: {
+      [key: string]: unknown;
+    };
     SafeConfig: {
       botName: string;
-      /** @enum {string} */
-      assistant: 'claude' | 'codex';
+      assistant: string;
       assistants: {
-        claude: {
-          model?: string;
-        };
-        codex: {
-          model?: string;
-          /** @enum {string} */
-          modelReasoningEffort?: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
-          /** @enum {string} */
-          webSearchMode?: 'disabled' | 'cached' | 'live';
-        };
+        [key: string]: components['schemas']['ProviderDefaults'];
       };
       streaming: {
         /** @enum {string} */
@@ -2522,18 +2511,33 @@ export interface components {
       database: string;
     };
     UpdateAssistantConfigBody: {
-      /** @enum {string} */
-      assistant?: 'claude' | 'codex';
-      claude?: {
-        model: string;
-      };
-      codex?: {
-        model: string;
-        /** @enum {string} */
-        modelReasoningEffort?: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
-        /** @enum {string} */
-        webSearchMode?: 'disabled' | 'cached' | 'live';
-      };
+      assistant?: string;
+      assistants?: {
+        [key: string]: components['schemas']['ProviderDefaults'];
+      };
+    };
+    ProviderCapabilities: {
+      sessionResume: boolean;
+      mcp: boolean;
+      hooks: boolean;
+      skills: boolean;
+      toolRestrictions: boolean;
+      structuredOutput: boolean;
+      envInjection: boolean;
+      costControl: boolean;
+      effortControl: boolean;
+      thinkingControl: boolean;
+      fallbackModel: boolean;
+      sandbox: boolean;
+    };
+    ProviderInfo: {
+      id: string;
+      displayName: string;
+      capabilities: components['schemas']['ProviderCapabilities'];
+      builtIn: boolean;
+    };
+    ProviderListResponse: {
+      providers: components['schemas']['ProviderInfo'][];
     };
     IsolationEnvironment: {
       id: string;
diff --git a/packages/web/src/lib/api.ts b/packages/web/src/lib/api.ts
index 6c81aa66b1..566449e89a 100644
--- a/packages/web/src/lib/api.ts
+++ b/packages/web/src/lib/api.ts
@@ -19,6 +19,8 @@ export const SSE_BASE_URL = import.meta.env.DEV
   ? `http://${window.location.hostname}:${apiPort}`
   : '';
 
+export { getCodebaseInput } from '@/lib/codebase-input';
+
 export interface ConversationResponse {
   id: string;
   platform_type: string;
@@ -38,7 +40,6 @@ export interface CodebaseResponse {
   repository_url: string | null;
   default_cwd: string;
   ai_assistant_type: string;
-  allow_env_keys: boolean;
   commands: Record<string, { path: string; description: string }>;
   created_at: string;
   updated_at: string;
@@ -55,6 +56,7 @@ export interface HealthResponse {
   runningWorkflows: number;
   version?: string;
   is_docker: boolean;
+  activePlatforms?: string[];
 }
 
 async function fetchJSON<T>(url: string, options?: RequestInit): Promise<T> {
@@ -70,6 +72,45 @@ async function fetchJSON<T>(url: string, options?: RequestInit): Promise<T> {
   return res.json() as Promise<T>;
 }
 
+// Providers
+export interface ProviderInfo {
+  id: string;
+  displayName: string;
+  capabilities: Record<string, boolean>;
+  builtIn: boolean;
+}
+
+export type ProviderDefaults = Record<string, unknown>;
+
+export interface SafeConfigResponse {
+  botName: string;
+  assistant: string;
+  assistants: Record<string, ProviderDefaults>;
+  streaming: {
+    telegram: 'stream' | 'batch';
+    discord: 'stream' | 'batch';
+    slack: 'stream' | 'batch';
+  };
+  concurrency: {
+    maxConversations: number;
+  };
+  defaults: {
+    copyDefaults: boolean;
+    loadDefaultCommands: boolean;
+    loadDefaultWorkflows: boolean;
+  };
+}
+
+export interface UpdateAssistantConfigBody {
+  assistant?: string;
+  assistants?: Record<string, ProviderDefaults>;
+}
+
+export async function listProviders(): Promise<ProviderInfo[]> {
+  const data = await fetchJSON<{ providers: ProviderInfo[] }>('/api/providers');
+  return data.providers;
+}
+
 // Conversations
 export async function listConversations(codebaseId?: string): Promise<ConversationResponse[]> {
   const params = new URLSearchParams();
@@ -158,7 +199,7 @@ export async function getCodebase(id: string): Promise<CodebaseResponse> {
 }
 
 export async function addCodebase(
-  input: { url: string; allowEnvKeys?: boolean } | { path: string; allowEnvKeys?: boolean }
+  input: { url: string } | { path: string }
 ): Promise<CodebaseResponse> {
   return fetchJSON<CodebaseResponse>('/api/codebases', {
     method: 'POST',
@@ -167,17 +208,6 @@ export async function addCodebase(
   });
 }
 
-export async function updateCodebase(
-  id: string,
-  input: { allowEnvKeys: boolean }
-): Promise<CodebaseResponse> {
-  return fetchJSON<CodebaseResponse>(`/api/codebases/${id}`, {
-    method: 'PATCH',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(input),
-  });
-}
-
 export async function deleteCodebase(id: string): Promise<{ success: boolean }> {
   return fetchJSON<{ success: boolean }>(`/api/codebases/${id}`, { method: 'DELETE' });
 }
@@ -435,14 +465,10 @@ export async function listCommands(cwd?: string): Promise<CommandEntry[]> {
   return result.commands;
 }
 
-export type SafeConfigResponse = components['schemas']['SafeConfig'];
-
 export async function getConfig(): Promise<{ config: SafeConfigResponse; database: string }> {
   return fetchJSON('/api/config');
 }
 
-export type UpdateAssistantConfigBody = components['schemas']['UpdateAssistantConfigBody'];
-
 export async function updateAssistantConfig(
   body: UpdateAssistantConfigBody
 ): Promise<{ config: SafeConfigResponse; database: string }> {
diff --git a/packages/web/src/lib/chat-message-reducer.test.ts b/packages/web/src/lib/chat-message-reducer.test.ts
new file mode 100644
index 0000000000..0e82f54890
--- /dev/null
+++ b/packages/web/src/lib/chat-message-reducer.test.ts
@@ -0,0 +1,194 @@
+import { describe, test, expect } from 'bun:test';
+import { applyOnText } from './chat-message-reducer';
+import type { ChatMessage, ToolCallDisplay } from './types';
+
+// Helpers
+
+let idCounter = 0;
+function makeId(): string {
+  idCounter++;
+  return `msg-${String(idCounter)}`;
+}
+const NOW = 1000;
+
+function makeAssistant(overrides: Partial<ChatMessage> = {}): ChatMessage {
+  return {
+    id: makeId(),
+    role: 'assistant',
+    content: '',
+    timestamp: NOW,
+    isStreaming: true,
+    toolCalls: [],
+    ...overrides,
+  };
+}
+
+function makeToolCall(id = 'tc1'): ToolCallDisplay {
+  return { id, name: 'read_file', input: {}, startedAt: NOW, isExpanded: false };
+}
+
+// ---------------------------------------------------------------------------
+// Rule 4 — tool-call boundary (the new guard added by PR #1054)
+// ---------------------------------------------------------------------------
+
+describe('applyOnText — tool-call boundary (Rule 4)', () => {
+  test('starts a new segment when last streaming message has tool calls', () => {
+    const prev: ChatMessage[] = [makeAssistant({ toolCalls: [makeToolCall()] })];
+    const result = applyOnText(prev, 'Post-tool text', makeId, NOW);
+
+    expect(result).toHaveLength(2);
+    expect(result[0].isStreaming).toBe(false);
+    expect(result[1].content).toBe('Post-tool text');
+    expect(result[1].toolCalls).toEqual([]);
+    expect(result[1].isStreaming).toBe(true);
+  });
+
+  test('does not split when last streaming message has an empty toolCalls array', () => {
+    const prev: ChatMessage[] = [makeAssistant({ content: 'hello ', toolCalls: [] })];
+    const result = applyOnText(prev, 'world', makeId, NOW);
+
+    expect(result).toHaveLength(1);
+    expect(result[0].content).toBe('hello world');
+  });
+
+  test('treats absent toolCalls the same as empty array (no split)', () => {
+    // toolCalls is optional on ChatMessage
+    const prev: ChatMessage[] = [makeAssistant({ content: 'x', toolCalls: undefined })];
+    const result = applyOnText(prev, 'y', makeId, NOW);
+
+    expect(result).toHaveLength(1);
+    expect(result[0].content).toBe('xy');
+  });
+
+  test('handles multiple tool calls — still splits on any non-empty toolCalls', () => {
+    const prev: ChatMessage[] = [
+      makeAssistant({ toolCalls: [makeToolCall('tc1'), makeToolCall('tc2')] }),
+    ];
+    const result = applyOnText(prev, 'more text', makeId, NOW);
+
+    expect(result).toHaveLength(2);
+    expect(result[1].toolCalls).toEqual([]);
+    expect(result[1].isStreaming).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Rule 5 — append to existing streaming message
+// ---------------------------------------------------------------------------
+
+describe('applyOnText — append (Rule 5)', () => {
+  test('appends to the current streaming message when no boundary condition fires', () => {
+    const prev: ChatMessage[] = [makeAssistant({ content: 'hello ' })];
+    const result = applyOnText(prev, 'world', makeId, NOW);
+
+    expect(result).toHaveLength(1);
+    expect(result[0].content).toBe('hello world');
+    expect(result[0].isStreaming).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Rule 6 — new assistant message when none is streaming
+// ---------------------------------------------------------------------------
+
+describe('applyOnText — new message (Rule 6)', () => {
+  test('creates a new streaming message when prev is empty', () => {
+    const result = applyOnText([], 'hello', makeId, NOW);
+
+    expect(result).toHaveLength(1);
+    expect(result[0].content).toBe('hello');
+    expect(result[0].role).toBe('assistant');
+    expect(result[0].isStreaming).toBe(true);
+    expect(result[0].toolCalls).toEqual([]);
+  });
+
+  test('creates a new streaming message when last message is from a user', () => {
+    const prev: ChatMessage[] = [{ id: 'u1', role: 'user', content: 'hi', timestamp: NOW }];
+    const result = applyOnText(prev, 'response', makeId, NOW);
+
+    expect(result).toHaveLength(2);
+    expect(result[1].role).toBe('assistant');
+    expect(result[1].content).toBe('response');
+  });
+
+  test('creates a new streaming message when last assistant message is not streaming', () => {
+    const prev: ChatMessage[] = [makeAssistant({ isStreaming: false, content: 'done' })];
+    const result = applyOnText(prev, 'new', makeId, NOW);
+
+    expect(result).toHaveLength(2);
+    expect(result[1].isStreaming).toBe(true);
+    expect(result[1].content).toBe('new');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Rules 2 & 3 — workflow-status boundary
+// ---------------------------------------------------------------------------
+
+describe('applyOnText — workflow-status boundary (Rules 2 & 3)', () => {
+  test('starts a new segment when incoming is workflow-status and current has content', () => {
+    const prev: ChatMessage[] = [makeAssistant({ content: 'some existing text' })];
+    const result = applyOnText(prev, '🚀 Workflow started', makeId, NOW);
+
+    expect(result).toHaveLength(2);
+    expect(result[0].isStreaming).toBe(false);
+    expect(result[1].content).toBe('🚀 Workflow started');
+    expect(result[1].isStreaming).toBe(true);
+  });
+
+  test('starts a new segment when current is workflow-status and incoming is regular text', () => {
+    const prev: ChatMessage[] = [makeAssistant({ content: '✅ Workflow done' })];
+    const result = applyOnText(prev, 'Regular text now', makeId, NOW);
+
+    expect(result).toHaveLength(2);
+    expect(result[0].isStreaming).toBe(false);
+    expect(result[1].content).toBe('Regular text now');
+  });
+
+  test('does not start new segment when incoming is workflow-status and current is empty', () => {
+    // Empty content: the status emoji goes into the empty placeholder
+    const prev: ChatMessage[] = [makeAssistant({ content: '' })];
+    const result = applyOnText(prev, '🚀 Starting', makeId, NOW);
+
+    // isWorkflowStatus && last.content evaluates to false because last.content === ''
+    expect(result).toHaveLength(1);
+    expect(result[0].content).toBe('🚀 Starting');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Rule 1 — workflow-result
+// ---------------------------------------------------------------------------
+
+describe('applyOnText — workflow-result (Rule 1)', () => {
+  const wfResult = { workflowName: 'plan', runId: 'run-1' };
+
+  test('creates a non-streaming message for a workflow result', () => {
+    const result = applyOnText([], 'Plan complete', makeId, NOW, wfResult);
+
+    expect(result).toHaveLength(1);
+    expect(result[0].workflowResult).toEqual(wfResult);
+    expect(result[0].isStreaming).toBe(false);
+    expect(result[0].content).toBe('Plan complete');
+  });
+
+  test('closes the current streaming message before adding workflow result', () => {
+    const prev: ChatMessage[] = [makeAssistant({ content: 'partial' })];
+    const result = applyOnText(prev, 'Done', makeId, NOW, wfResult);
+
+    expect(result).toHaveLength(2);
+    expect(result[0].isStreaming).toBe(false);
+    expect(result[1].workflowResult).toEqual(wfResult);
+  });
+
+  test('deduplicates workflow-result messages with the same runId', () => {
+    const prev: ChatMessage[] = [
+      makeAssistant({ content: 'Plan complete', isStreaming: false, workflowResult: wfResult }),
+    ];
+    const result = applyOnText(prev, 'Plan complete', makeId, NOW, wfResult);
+
+    // Same runId already in state — no new message added
+    expect(result).toHaveLength(1);
+    expect(result).toBe(prev); // reference equality: same array returned
+  });
+});
diff --git a/packages/web/src/lib/chat-message-reducer.ts b/packages/web/src/lib/chat-message-reducer.ts
new file mode 100644
index 0000000000..aad1178203
--- /dev/null
+++ b/packages/web/src/lib/chat-message-reducer.ts
@@ -0,0 +1,106 @@
+/**
+ * Pure reducer functions for the ChatInterface `onText` SSE handler.
+ *
+ * Extracted so they can be unit-tested independently of the React component.
+ * All functions are deterministic: given the same inputs they always produce
+ * the same output with no side effects.
+ */
+
+import type { ChatMessage } from './types';
+
+/** Regex that identifies workflow-status messages (🚀 / ✅ prefix). */
+const WORKFLOW_STATUS_RE = /^[\u{1F680}\u{2705}]/u;
+
+/**
+ * Builds a new streaming assistant message.  The `id` is caller-supplied so
+ * that tests can produce stable, deterministic IDs.
+ */
+function makeStreamingMessage(
+  id: string,
+  content: string,
+  timestamp: number,
+  isStreaming: boolean,
+  workflowResult?: { workflowName: string; runId: string }
+): ChatMessage {
+  return {
+    id,
+    role: 'assistant' as const,
+    content,
+    timestamp,
+    isStreaming,
+    toolCalls: [],
+    ...(workflowResult !== undefined ? { workflowResult } : {}),
+  };
+}
+
+/**
+ * Applies a text SSE event to the current message list.
+ *
+ * This mirrors (and is called by) the `setMessages` updater inside the
+ * `onText` callback of `ChatInterface.tsx`.  Segmentation rules:
+ *
+ * 1. Workflow-result text → always a new, non-streaming message (deduped by runId).
+ * 2. Incoming workflow-status when current has content → close current, open new.
+ * 3. Current is workflow-status and incoming is regular text → close current, open new.
+ * 4. Current message has tool calls → close current, open new (mirrors persistence.ts:72).
+ * 5. Otherwise → append to the current streaming message.
+ * 6. No streaming assistant message → create a new one.
+ *
+ * @param prev        Current message list (treated as immutable).
+ * @param content     Text to apply.
+ * @param makeId      Factory for generating a new message ID (injectable for testing).
+ * @param now         Timestamp to use for new messages (injectable for testing).
+ * @param workflowResult  Optional workflow-result metadata carried by the text event.
+ */
+export function applyOnText(
+  prev: ChatMessage[],
+  content: string,
+  makeId: () => string = () => `msg-${String(Date.now())}`,
+  now: number = Date.now(),
+  workflowResult?: { workflowName: string; runId: string }
+): ChatMessage[] {
+  const last = prev[prev.length - 1];
+  const isWorkflowStatus = WORKFLOW_STATUS_RE.test(content);
+
+  // Rule 1: workflow-result messages always start as a new non-streaming message.
+  // Dedup: SSETransport replays buffered events on reconnect, so skip if already present.
+  if (workflowResult !== undefined) {
+    if (prev.some(m => m.workflowResult?.runId === workflowResult.runId)) {
+      return prev;
+    }
+    const updated =
+      last?.role === 'assistant' && last.isStreaming
+        ? [...prev.slice(0, -1), { ...last, isStreaming: false }]
+        : [...prev];
+    return [...updated, makeStreamingMessage(makeId(), content, now, false, workflowResult)];
+  }
+
+  if (last?.role === 'assistant' && last.isStreaming) {
+    const lastIsWorkflowStatus = WORKFLOW_STATUS_RE.test(last.content);
+
+    // Rules 2 & 3: workflow-status boundary.
+    if ((isWorkflowStatus && last.content) || (lastIsWorkflowStatus && !isWorkflowStatus)) {
+      return [
+        ...prev.slice(0, -1),
+        { ...last, isStreaming: false },
+        makeStreamingMessage(makeId(), content, now, true),
+      ];
+    }
+
+    // Rule 4: text after tool calls starts a new message segment, matching
+    // server-side persistence.ts segmentation (persistence.ts:72: lastSeg.toolCalls.length > 0).
+    if ((last.toolCalls?.length ?? 0) > 0) {
+      return [
+        ...prev.slice(0, -1),
+        { ...last, isStreaming: false },
+        makeStreamingMessage(makeId(), content, now, true),
+      ];
+    }
+
+    // Rule 5: append to existing streaming message.
+    return [...prev.slice(0, -1), { ...last, content: last.content + content }];
+  }
+
+  // Rule 6: no active streaming assistant message → create a new one.
+  return [...prev, makeStreamingMessage(makeId(), content, now, true)];
+}
diff --git a/packages/web/src/lib/codebase-input.test.ts b/packages/web/src/lib/codebase-input.test.ts
new file mode 100644
index 0000000000..4909e57add
--- /dev/null
+++ b/packages/web/src/lib/codebase-input.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, test } from 'bun:test';
+import { getCodebaseInput } from '@/lib/codebase-input';
+
+describe('getCodebaseInput', () => {
+  test('treats GitHub repository inputs as urls', () => {
+    expect(getCodebaseInput('https://github.com/coleam00/Archon')).toEqual({
+      url: 'https://github.com/coleam00/Archon',
+    });
+  });
+
+  test('treats SSH git@ shorthand as urls', () => {
+    expect(getCodebaseInput('git@github.com:coleam00/Archon.git')).toEqual({
+      url: 'git@github.com:coleam00/Archon.git',
+    });
+  });
+
+  test('treats ssh:// URLs as urls', () => {
+    expect(getCodebaseInput('ssh://git@github.com/coleam00/Archon.git')).toEqual({
+      url: 'ssh://git@github.com/coleam00/Archon.git',
+    });
+  });
+
+  test('treats git:// URLs as urls', () => {
+    expect(getCodebaseInput('git://github.com/coleam00/Archon.git')).toEqual({
+      url: 'git://github.com/coleam00/Archon.git',
+    });
+  });
+
+  test('trims surrounding whitespace before classifying', () => {
+    expect(getCodebaseInput('  https://github.com/a/b  ')).toEqual({
+      url: 'https://github.com/a/b',
+    });
+  });
+
+  test('treats relative local paths as paths', () => {
+    expect(getCodebaseInput('./repo')).toEqual({ path: './repo' });
+    expect(getCodebaseInput('../repo')).toEqual({ path: '../repo' });
+    expect(getCodebaseInput('repo')).toEqual({ path: 'repo' });
+  });
+
+  test('treats unix local paths as paths', () => {
+    expect(getCodebaseInput('/path/to/repository')).toEqual({
+      path: '/path/to/repository',
+    });
+  });
+
+  test('treats home-relative paths as paths', () => {
+    expect(getCodebaseInput('~/src/archon')).toEqual({
+      path: '~/src/archon',
+    });
+  });
+
+  test('treats windows local paths as paths', () => {
+    expect(getCodebaseInput('C:\\repo\\archon')).toEqual({
+      path: 'C:\\repo\\archon',
+    });
+  });
+
+  test('treats windows UNC paths as paths', () => {
+    expect(getCodebaseInput('\\\\server\\share\\archon')).toEqual({
+      path: '\\\\server\\share\\archon',
+    });
+  });
+});
diff --git a/packages/web/src/lib/codebase-input.ts b/packages/web/src/lib/codebase-input.ts
new file mode 100644
index 0000000000..21052e1fe4
--- /dev/null
+++ b/packages/web/src/lib/codebase-input.ts
@@ -0,0 +1,10 @@
+/**
+ * Classify input for POST /api/codebases. A `url` key signals a remote clone;
+ * a `path` key signals registering a local/relative path (server resolves
+ * tilde/relative). Inputs without an explicit remote prefix fall through to `path`.
+ */
+export function getCodebaseInput(value: string): { path: string } | { url: string } {
+  const trimmed = value.trim();
+  const isRemoteUrl = /^(https?:\/\/|ssh:\/\/|git@|git:\/\/)/i.test(trimmed);
+  return isRemoteUrl ? { url: trimmed } : { path: trimmed };
+}
diff --git a/packages/web/src/routes/ChatPage.tsx b/packages/web/src/routes/ChatPage.tsx
index b1179d75ea..dde3c8c04b 100644
--- a/packages/web/src/routes/ChatPage.tsx
+++ b/packages/web/src/routes/ChatPage.tsx
@@ -7,7 +7,7 @@ import { ConversationItem } from '@/components/conversations/ConversationItem';
 import { ScrollArea } from '@/components/ui/scroll-area';
 import { Separator } from '@/components/ui/separator';
 import { useProject } from '@/contexts/ProjectContext';
-import { listConversations, listWorkflowRuns, addCodebase } from '@/lib/api';
+import { listConversations, listWorkflowRuns, addCodebase, getCodebaseInput } from '@/lib/api';
 import type { CodebaseResponse } from '@/lib/api';
 import { cn } from '@/lib/utils';
 
@@ -146,11 +146,7 @@ export function ChatPage(): React.ReactElement {
     setAddLoading(true);
     setAddError(null);
 
-    const isLocalPath =
-      trimmed.startsWith('/') || trimmed.startsWith('~') || /^[A-Za-z]:[/\\]/.test(trimmed);
-    const input = isLocalPath ? { path: trimmed } : { url: trimmed };
-
-    void addCodebase(input)
+    void addCodebase(getCodebaseInput(trimmed))
       .then(codebase => {
         void queryClient.invalidateQueries({ queryKey: ['codebases'] });
         setSelectedProjectId(codebase.id);
diff --git a/packages/web/src/routes/DashboardPage.tsx b/packages/web/src/routes/DashboardPage.tsx
index eb08cd799b..807263f85a 100644
--- a/packages/web/src/routes/DashboardPage.tsx
+++ b/packages/web/src/routes/DashboardPage.tsx
@@ -293,8 +293,19 @@ export function DashboardPage(): React.ReactElement {
     runAction(deleteWorkflowRun, runId, 'Failed to delete workflow run');
   const handleApprove = (runId: string): Promise<void> =>
     runAction(approveWorkflowRun, runId, 'Failed to approve workflow');
-  const handleReject = (runId: string): Promise<void> =>
-    runAction(rejectWorkflowRun, runId, 'Failed to reject workflow');
+  // Reject differs from the rest of the lifecycle actions because it takes a
+  // second argument (the optional reason). Inline it rather than squeezing
+  // through `runAction`'s `(id) => Promise` signature with a closure — keeps
+  // `runAction` usefully narrow for the single-arg actions above.
+  async function handleReject(runId: string, reason?: string): Promise<void> {
+    try {
+      setActionError(null);
+      await rejectWorkflowRun(runId, reason);
+      void queryClient.invalidateQueries({ queryKey: ['dashboardRuns'] });
+    } catch (err) {
+      setActionError(err instanceof Error ? err.message : 'Failed to reject workflow');
+    }
+  }
 
   const totalPages = Math.ceil(total / pageSize);
   const hasMore = page + 1 < totalPages;
diff --git a/packages/web/src/routes/SettingsPage.tsx b/packages/web/src/routes/SettingsPage.tsx
index 07a07690fc..9add58d245 100644
--- a/packages/web/src/routes/SettingsPage.tsx
+++ b/packages/web/src/routes/SettingsPage.tsx
@@ -9,15 +9,21 @@ import {
   getConfig,
   getHealth,
   listCodebases,
+  listProviders,
   addCodebase,
-  updateCodebase,
+  getCodebaseInput,
   deleteCodebase,
   updateAssistantConfig,
   getCodebaseEnvVars,
   setCodebaseEnvVar,
   deleteCodebaseEnvVar,
 } from '@/lib/api';
-import type { SafeConfigResponse, CodebaseResponse } from '@/lib/api';
+import type {
+  SafeConfigResponse,
+  CodebaseResponse,
+  ProviderDefaults,
+  ProviderInfo,
+} from '@/lib/api';
 
 const selectClass =
   'h-9 rounded-md border border-border bg-surface-elevated text-text-primary px-3 text-sm focus:outline-none focus:ring-1 focus:ring-ring [&>option]:bg-surface-elevated [&>option]:text-text-primary';
@@ -251,22 +257,11 @@ function EnvVarsPanel({ codebaseId }: { codebaseId: string }): React.ReactElemen
   );
 }
 
-function isEnvLeakError(error: unknown): boolean {
-  return (
-    error instanceof Error &&
-    'status' in error &&
-    (error as Error & { status: number }).status === 422 &&
-    error.message.startsWith('Cannot add codebase')
-  );
-}
-
 function ProjectsSection(): React.ReactElement {
   const queryClient = useQueryClient();
-  const [addPath, setAddPath] = useState('');
+  const [addValue, setAddValue] = useState('');
   const [showAdd, setShowAdd] = useState(false);
-  const [allowEnvKeys, setAllowEnvKeys] = useState(false);
   const [expandedEnvVars, setExpandedEnvVars] = useState<string | null>(null);
-  const [toggleError, setToggleError] = useState<string | null>(null);
 
   const { data: codebases } = useQuery({
     queryKey: ['codebases'],
@@ -274,13 +269,11 @@ function ProjectsSection(): React.ReactElement {
   });
 
   const addMutation = useMutation({
-    mutationFn: ({ path, allowEnvKeys }: { path: string; allowEnvKeys?: boolean }) =>
-      addCodebase({ path, allowEnvKeys }),
+    mutationFn: (value: string) => addCodebase(getCodebaseInput(value)),
     onSuccess: () => {
       void queryClient.invalidateQueries({ queryKey: ['codebases'] });
-      setAddPath('');
+      setAddValue('');
       setShowAdd(false);
-      setAllowEnvKeys(false);
     },
   });
 
@@ -291,24 +284,10 @@ function ProjectsSection(): React.ReactElement {
     },
   });
 
-  const toggleEnvKeysMutation = useMutation({
-    mutationFn: ({ id, allowEnvKeys }: { id: string; allowEnvKeys: boolean }) =>
-      updateCodebase(id, { allowEnvKeys }),
-    onSuccess: () => {
-      setToggleError(null);
-      void queryClient.invalidateQueries({ queryKey: ['codebases'] });
-    },
-    onError: (err: Error) => {
-      // Without this the user clicks "Revoke env keys", confirms the
-      // destructive dialog, and gets no feedback if the PATCH fails.
-      setToggleError(err.message);
-    },
-  });
-
   function handleAddSubmit(e: React.FormEvent): void {
     e.preventDefault();
-    if (addPath.trim()) {
-      addMutation.mutate({ path: addPath.trim(), allowEnvKeys: allowEnvKeys || undefined });
+    if (addValue.trim()) {
+      addMutation.mutate(addValue.trim());
     }
   }
 
@@ -318,11 +297,6 @@ function ProjectsSection(): React.ReactElement {
         <CardTitle>Projects</CardTitle>
       </CardHeader>
       <CardContent>
-        {toggleError && (
-          <div className="mb-2 rounded-md border border-error/50 bg-error/10 p-2 text-sm text-error">
-            Failed to update env-key consent: {toggleError}
-          </div>
-        )}
         {!codebases || codebases.length === 0 ? (
           <div className="text-sm text-muted-foreground">No projects registered.</div>
         ) : (
@@ -331,40 +305,10 @@ function ProjectsSection(): React.ReactElement {
               <div key={cb.id} className="rounded-md border border-border p-2 text-sm">
                 <div className="flex items-center justify-between">
                   <div className="min-w-0 flex-1">
-                    <div className="flex items-center gap-2">
-                      <div className="font-medium truncate">{cb.name}</div>
-                      {cb.allow_env_keys && (
-                        <Badge variant="destructive" className="text-[10px]">
-                          env keys allowed
-                        </Badge>
-                      )}
-                    </div>
+                    <div className="font-medium truncate">{cb.name}</div>
                     <div className="text-xs text-muted-foreground truncate">{cb.default_cwd}</div>
                   </div>
                   <div className="flex gap-1">
-                    <Button
-                      variant="ghost"
-                      size="sm"
-                      className="text-xs"
-                      onClick={() => {
-                        if (cb.allow_env_keys) {
-                          if (
-                            !window.confirm(
-                              `Revoke env-key consent for "${cb.name}"? Future workflow runs will be blocked if .env contains sensitive keys.`
-                            )
-                          ) {
-                            return;
-                          }
-                        }
-                        toggleEnvKeysMutation.mutate({
-                          id: cb.id,
-                          allowEnvKeys: !cb.allow_env_keys,
-                        });
-                      }}
-                      disabled={toggleEnvKeysMutation.isPending}
-                    >
-                      {cb.allow_env_keys ? 'Revoke env keys' : 'Allow env keys'}
-                    </Button>
                     <Button
                       variant="ghost"
                       size="sm"
@@ -396,11 +340,11 @@ function ProjectsSection(): React.ReactElement {
         {showAdd ? (
           <form onSubmit={handleAddSubmit} className="mt-3 flex gap-2">
             <Input
-              value={addPath}
+              value={addValue}
               onChange={e => {
-                setAddPath(e.target.value);
+                setAddValue(e.target.value);
               }}
-              placeholder="/path/to/repository"
+              placeholder="GitHub URL or local path"
               className="flex-1"
             />
             <Button type="submit" size="sm" disabled={addMutation.isPending}>
@@ -412,7 +356,7 @@ function ProjectsSection(): React.ReactElement {
               size="sm"
               onClick={() => {
                 setShowAdd(false);
-                setAddPath('');
+                setAddValue('');
               }}
             >
               Cancel
@@ -436,18 +380,6 @@ function ProjectsSection(): React.ReactElement {
             {addMutation.error instanceof Error
               ? addMutation.error.message
               : 'Failed to add project'}
-            {isEnvLeakError(addMutation.error) && (
-              <label className="mt-2 flex items-center gap-2 text-text-secondary">
-                <input
-                  type="checkbox"
-                  checked={allowEnvKeys}
-                  onChange={e => {
-                    setAllowEnvKeys(e.target.checked);
-                  }}
-                />
-                Allow env keys (I understand the risk)
-              </label>
-            )}
           </div>
         )}
       </CardContent>
@@ -457,32 +389,56 @@ function ProjectsSection(): React.ReactElement {
 
 function AssistantConfigSection({ config }: { config: SafeConfigResponse }): React.ReactElement {
   const queryClient = useQueryClient();
-  const [assistant, setAssistant] = useState(config.assistant);
-  const [claudeModel, setClaudeModel] = useState(config.assistants.claude.model ?? 'sonnet');
-  const [codexModel, setCodexModel] = useState(config.assistants.codex.model ?? '');
-  const [reasoning, setReasoning] = useState<'minimal' | 'low' | 'medium' | 'high' | 'xhigh'>(
-    config.assistants.codex.modelReasoningEffort ?? 'medium'
-  );
-  const [webSearch, setWebSearch] = useState<'disabled' | 'cached' | 'live'>(
-    config.assistants.codex.webSearchMode ?? 'disabled'
+  const { data: providers } = useQuery({
+    queryKey: ['providers'],
+    queryFn: listProviders,
+    staleTime: 5 * 60 * 1000,
+  });
+  const [assistant, setAssistant] = useState<string>(config.assistant);
+  const [assistantSettings, setAssistantSettings] = useState<Record<string, ProviderDefaults>>(
+    config.assistants
   );
   const [saveMsg, setSaveMsg] = useState<{ type: 'success' | 'error'; text: string } | null>(null);
 
+  const normalizedConfigSettings = JSON.stringify(config.assistants);
+  const normalizedAssistantSettings = JSON.stringify(assistantSettings);
   const hasChanges =
-    assistant !== config.assistant ||
-    claudeModel !== (config.assistants.claude.model ?? 'sonnet') ||
-    codexModel !== (config.assistants.codex.model ?? '') ||
-    reasoning !== (config.assistants.codex.modelReasoningEffort ?? 'medium') ||
-    webSearch !== (config.assistants.codex.webSearchMode ?? 'disabled');
+    assistant !== config.assistant || normalizedAssistantSettings !== normalizedConfigSettings;
 
   useEffect(() => {
     setAssistant(config.assistant);
-    setClaudeModel(config.assistants.claude.model ?? 'sonnet');
-    setCodexModel(config.assistants.codex.model ?? '');
-    setReasoning(config.assistants.codex.modelReasoningEffort ?? 'medium');
-    setWebSearch(config.assistants.codex.webSearchMode ?? 'disabled');
+    setAssistantSettings(config.assistants);
   }, [config]);
 
+  function getProviderSettings(providerId: string): ProviderDefaults {
+    return assistantSettings[providerId] ?? {};
+  }
+
+  function updateProviderSettings(providerId: string, updates: ProviderDefaults): void {
+    setAssistantSettings(current => ({
+      ...current,
+      [providerId]: {
+        ...(current[providerId] ?? {}),
+        ...updates,
+      },
+    }));
+  }
+
+  const allProviderEntries: ProviderInfo[] = [
+    ...(providers ?? []),
+    ...Object.keys(config.assistants)
+      .filter(providerId => !(providers ?? []).some(provider => provider.id === providerId))
+      .map(
+        providerId =>
+          ({
+            id: providerId,
+            displayName: providerId,
+            capabilities: {},
+            builtIn: false,
+          }) satisfies ProviderInfo
+      ),
+  ];
+
   const mutation = useMutation({
     mutationFn: updateAssistantConfig,
     onSuccess: () => {
@@ -500,14 +456,7 @@ function AssistantConfigSection({ config }: { config: SafeConfigResponse }): Rea
   function handleSave(): void {
     mutation.mutate({
       assistant,
-      claude: { model: claudeModel },
-      // The generated type requires `model` when `codex` is present; omit the codex key
-      // entirely when no model is set so the server treats it as "no codex changes".
-      ...(codexModel
-        ? {
-            codex: { model: codexModel, modelReasoningEffort: reasoning, webSearchMode: webSearch },
-          }
-        : {}),
+      assistants: assistantSettings,
     });
   }
 
@@ -524,67 +473,119 @@ function AssistantConfigSection({ config }: { config: SafeConfigResponse }): Rea
               id="default-assistant"
               value={assistant}
               onChange={e => {
-                setAssistant(e.target.value as 'claude' | 'codex');
+                setAssistant(e.target.value);
               }}
               className={selectClass}
             >
-              <option value="claude">Claude</option>
-              <option value="codex">Codex</option>
+              {allProviderEntries.map(p => (
+                <option key={p.id} value={p.id}>
+                  {p.displayName}
+                </option>
+              ))}
             </select>
+          </div>
 
-            <label htmlFor="claude-model">Claude Model</label>
-            <select
-              id="claude-model"
-              value={claudeModel}
-              onChange={e => {
-                setClaudeModel(e.target.value);
-              }}
-              className={selectClass}
-            >
-              <option value="sonnet">sonnet</option>
-              <option value="opus">opus</option>
-              <option value="haiku">haiku</option>
-            </select>
-
-            <label htmlFor="codex-model">Codex Model</label>
-            <Input
-              id="codex-model"
-              value={codexModel}
-              onChange={e => {
-                setCodexModel(e.target.value);
-              }}
-              placeholder="gpt-5.3-codex"
-            />
-
-            <label htmlFor="reasoning">Reasoning Effort</label>
-            <select
-              id="reasoning"
-              value={reasoning}
-              onChange={e => {
-                setReasoning(e.target.value as 'minimal' | 'low' | 'medium' | 'high' | 'xhigh');
-              }}
-              className={selectClass}
-            >
-              <option value="minimal">minimal</option>
-              <option value="low">low</option>
-              <option value="medium">medium</option>
-              <option value="high">high</option>
-              <option value="xhigh">xhigh</option>
-            </select>
+          <div className="space-y-4 border-t pt-4">
+            {allProviderEntries.map(provider => {
+              const providerSettings = getProviderSettings(provider.id);
 
-            <label htmlFor="web-search">Web Search</label>
-            <select
-              id="web-search"
-              value={webSearch}
-              onChange={e => {
-                setWebSearch(e.target.value as 'disabled' | 'cached' | 'live');
-              }}
-              className={selectClass}
-            >
-              <option value="disabled">disabled</option>
-              <option value="cached">cached</option>
-              <option value="live">live</option>
-            </select>
+              if (provider.id === 'claude') {
+                return (
+                  <div
+                    key={provider.id}
+                    className="grid grid-cols-[140px_1fr] items-center gap-2 text-sm"
+                  >
+                    <div className="font-medium">{provider.displayName}</div>
+                    <div className="text-muted-foreground">Built-in provider settings</div>
+
+                    <label htmlFor="claude-model">Model</label>
+                    <select
+                      id="claude-model"
+                      value={(providerSettings.model as string | undefined) ?? 'sonnet'}
+                      onChange={e => {
+                        updateProviderSettings('claude', { model: e.target.value });
+                      }}
+                      className={selectClass}
+                    >
+                      <option value="sonnet">sonnet</option>
+                      <option value="opus">opus</option>
+                      <option value="haiku">haiku</option>
+                    </select>
+                  </div>
+                );
+              }
+
+              if (provider.id === 'codex') {
+                return (
+                  <div
+                    key={provider.id}
+                    className="grid grid-cols-[140px_1fr] items-center gap-2 text-sm"
+                  >
+                    <div className="font-medium">{provider.displayName}</div>
+                    <div className="text-muted-foreground">Built-in provider settings</div>
+
+                    <label htmlFor="codex-model">Model</label>
+                    <Input
+                      id="codex-model"
+                      value={(providerSettings.model as string | undefined) ?? ''}
+                      onChange={e => {
+                        updateProviderSettings('codex', { model: e.target.value });
+                      }}
+                      placeholder="gpt-5.3-codex"
+                    />
+
+                    <label htmlFor="reasoning">Reasoning Effort</label>
+                    <select
+                      id="reasoning"
+                      value={
+                        (providerSettings.modelReasoningEffort as string | undefined) ?? 'medium'
+                      }
+                      onChange={e => {
+                        updateProviderSettings('codex', {
+                          modelReasoningEffort: e.target.value,
+                        });
+                      }}
+                      className={selectClass}
+                    >
+                      <option value="minimal">minimal</option>
+                      <option value="low">low</option>
+                      <option value="medium">medium</option>
+                      <option value="high">high</option>
+                      <option value="xhigh">xhigh</option>
+                    </select>
+
+                    <label htmlFor="web-search">Web Search</label>
+                    <select
+                      id="web-search"
+                      value={(providerSettings.webSearchMode as string | undefined) ?? 'disabled'}
+                      onChange={e => {
+                        updateProviderSettings('codex', { webSearchMode: e.target.value });
+                      }}
+                      className={selectClass}
+                    >
+                      <option value="disabled">disabled</option>
+                      <option value="cached">cached</option>
+                      <option value="live">live</option>
+                    </select>
+                  </div>
+                );
+              }
+
+              return (
+                <div key={provider.id} className="rounded-md border border-border p-3 text-sm">
+                  <div className="font-medium">{provider.displayName}</div>
+                  <div className="mt-1 text-muted-foreground">
+                    Provider-specific settings are stored generically for Phase 2. This provider
+                    does not have a dedicated editor yet.
+                  </div>
+                  {Object.keys(providerSettings).length > 0 && (
+                    <pre className="mt-2 overflow-x-auto rounded bg-muted p-2 text-xs">
+                      {JSON.stringify(providerSettings, null, 2)}
+                    </pre>
+                  )}
+                </div>
+              );
+            })}
           </div>
 
           <div className="flex items-center gap-3">
@@ -606,16 +607,19 @@ function AssistantConfigSection({ config }: { config: SafeConfigResponse }): Rea
 }
 
 function PlatformConnectionsSection({
-  adapter,
+  activePlatforms,
 }: {
-  adapter: string | undefined;
+  activePlatforms: string[] | undefined;
 }): React.ReactElement {
+  const active = new Set(activePlatforms ?? []);
   const platforms = [
-    { name: 'Web', connected: adapter === 'web' },
-    { name: 'Slack', connected: false },
-    { name: 'Telegram', connected: false },
-    { name: 'Discord', connected: false },
-    { name: 'GitHub', connected: false },
+    { name: 'Web', connected: active.has('Web') },
+    { name: 'Slack', connected: active.has('Slack') },
+    { name: 'Telegram', connected: active.has('Telegram') },
+    { name: 'Discord', connected: active.has('Discord') },
+    { name: 'GitHub', connected: active.has('GitHub') },
+    { name: 'Gitea', connected: active.has('Gitea') },
+    { name: 'GitLab', connected: active.has('GitLab') },
   ];
 
   return (
@@ -716,7 +720,7 @@ export function SettingsPage(): React.ReactElement {
 
           <div className="grid grid-cols-1 gap-6 lg:grid-cols-2">
             {configData && <AssistantConfigSection config={configData.config} />}
-            <PlatformConnectionsSection adapter={health?.adapter} />
+            <PlatformConnectionsSection activePlatforms={health?.activePlatforms} />
           </div>
 
           <ProjectsSection />
diff --git a/packages/workflows/package.json b/packages/workflows/package.json
index 7126c5ffff..18da91fdc8 100644
--- a/packages/workflows/package.json
+++ b/packages/workflows/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@archon/workflows",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "type": "module",
   "exports": {
     "./schemas/*": "./src/schemas/*.ts",
@@ -19,12 +19,13 @@
     "./test-utils": "./src/test-utils.ts"
   },
   "scripts": {
-    "test": "bun test src/dag-executor.test.ts && bun test src/loader.test.ts && bun test src/logger.test.ts && bun test src/condition-evaluator.test.ts && bun test src/event-emitter.test.ts && bun test src/executor-shared.test.ts && bun test src/executor.test.ts && bun test src/executor-preamble.test.ts && bun test src/defaults/ src/model-validation.test.ts src/router.test.ts src/utils/ src/hooks.test.ts && bun test src/validation-parser.test.ts src/schemas.test.ts src/command-validation.test.ts && bun test src/validator.test.ts && bun test src/script-discovery.test.ts && bun test src/runtime-check.test.ts && bun test src/script-node-deps.test.ts",
+    "test": "bun test src/dag-executor.test.ts && bun test src/loader.test.ts && bun test src/logger.test.ts && bun test src/condition-evaluator.test.ts && bun test src/event-emitter.test.ts && bun test src/executor-shared.test.ts && bun test src/load-command-prompt.test.ts && bun test src/executor.test.ts && bun test src/executor-preamble.test.ts && bun test src/defaults/ src/model-validation.test.ts src/router.test.ts src/utils/ src/hooks.test.ts && bun test src/validation-parser.test.ts src/schemas.test.ts src/command-validation.test.ts && bun test src/validator.test.ts && bun test src/script-discovery.test.ts && bun test src/runtime-check.test.ts && bun test src/script-node-deps.test.ts",
     "type-check": "bun x tsc --noEmit"
   },
   "dependencies": {
     "@archon/git": "workspace:*",
     "@archon/paths": "workspace:*",
+    "@archon/providers": "workspace:*",
     "@hono/zod-openapi": "^0.19.6",
     "zod": "^3.25.28"
   },
diff --git a/packages/workflows/src/dag-executor.test.ts b/packages/workflows/src/dag-executor.test.ts
index 150ea4eeb7..b4717e9565 100644
--- a/packages/workflows/src/dag-executor.test.ts
+++ b/packages/workflows/src/dag-executor.test.ts
@@ -1,7 +1,8 @@
-import { describe, it, expect, beforeEach, afterEach, mock, type Mock } from 'bun:test';
+import { describe, it, expect, beforeEach, afterEach, mock, spyOn, type Mock } from 'bun:test';
 import { mkdir, writeFile, rm } from 'fs/promises';
 import { join } from 'path';
 import { tmpdir } from 'os';
+import * as git from '@archon/git';
 
 // --- Mock logger (MUST come before imports of modules under test) ---
 
@@ -25,14 +26,19 @@ mock.module('@archon/paths', () => ({
   getDefaultCommandsPath: () => '/nonexistent/defaults',
 }));
 
+// --- Bootstrap provider registry (after path mocks, before dag-executor import) ---
+import { registerBuiltinProviders, clearRegistry } from '@archon/providers';
+clearRegistry();
+registerBuiltinProviders();
+
 // --- Imports (after mocks) ---
 import {
   buildTopologicalLayers,
   checkTriggerRule,
   substituteNodeOutputRefs,
   executeDagWorkflow,
-  loadMcpConfig,
 } from './dag-executor';
+import { loadMcpConfig } from '@archon/providers/claude/provider';
 import type { DagNode, BashNode, ScriptNode, NodeOutput, WorkflowRun } from './schemas';
 import { discoverWorkflows } from './workflow-discovery';
 import { parseWorkflow } from './loader';
@@ -93,22 +99,56 @@ function createMockStore(): IWorkflowStore {
   };
 }
 
+/** All-true capabilities for Claude mock */
+const mockClaudeCapabilities = () => ({
+  sessionResume: true,
+  mcp: true,
+  hooks: true,
+  skills: true,
+  agents: true,
+  toolRestrictions: true,
+  structuredOutput: true,
+  envInjection: true,
+  costControl: true,
+  effortControl: true,
+  thinkingControl: true,
+  fallbackModel: true,
+  sandbox: true,
+});
+/** Limited capabilities for Codex mock */
+const mockCodexCapabilities = () => ({
+  sessionResume: true,
+  mcp: false,
+  hooks: false,
+  skills: false,
+  agents: false,
+  toolRestrictions: false,
+  structuredOutput: true,
+  envInjection: true,
+  costControl: false,
+  effortControl: false,
+  thinkingControl: false,
+  fallbackModel: false,
+  sandbox: false,
+});
+
 /** Mock AI sendQuery generator */
 const mockSendQueryDag = mock(function* () {
   yield { type: 'assistant', content: 'DAG AI response' };
   yield { type: 'result', sessionId: 'dag-session-id' };
 });
 
-const mockGetAssistantClientDag = mock(() => ({
+const mockGetAgentProviderDag = mock(() => ({
   sendQuery: mockSendQueryDag,
   getType: () => 'claude',
+  getCapabilities: mockClaudeCapabilities,
 }));
 
 function createMockDeps(storeOverride?: IWorkflowStore): WorkflowDeps {
   const store = storeOverride ?? createMockStore();
   return {
     store,
-    getAssistantClient: mockGetAssistantClientDag,
+    getAgentProvider: mockGetAgentProviderDag,
     loadConfig: mock(() =>
       Promise.resolve({
         assistant: 'claude' as const,
@@ -749,7 +789,7 @@ describe('executeDagWorkflow -- tool restrictions', () => {
     await writeFile(join(commandsDir, 'my-cmd.md'), 'My command prompt for $USER_MESSAGE');
 
     mockSendQueryDag.mockClear();
-    mockGetAssistantClientDag.mockClear();
+    mockGetAgentProviderDag.mockClear();
 
     mockSendQueryDag.mockImplementation(function* () {
       yield { type: 'assistant', content: 'DAG AI response' };
@@ -759,9 +799,10 @@ describe('executeDagWorkflow -- tool restrictions', () => {
 
   afterEach(async () => {
     // Restore default claude client
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'claude',
+      getCapabilities: mockClaudeCapabilities,
     }));
     try {
       await rm(testDir, { recursive: true, force: true });
@@ -796,13 +837,15 @@ describe('executeDagWorkflow -- tool restrictions', () => {
 
     expect(mockSendQueryDag.mock.calls.length).toBeGreaterThan(0);
     const optionsArg = mockSendQueryDag.mock.calls[0][3] as Record<string, unknown>;
-    expect(optionsArg?.tools).toEqual(['Read', 'Grep']);
+    const nodeConfig = optionsArg?.nodeConfig as Record<string, unknown>;
+    expect(nodeConfig?.allowed_tools).toEqual(['Read', 'Grep']);
   });
 
   it('warns user when Codex DAG node has denied_tools only', async () => {
-    mockGetAssistantClientDag.mockReturnValue({
+    mockGetAgentProviderDag.mockReturnValue({
       sendQuery: mockSendQueryDag,
       getType: () => 'codex',
+      getCapabilities: mockCodexCapabilities,
     });
 
     const mockDeps = createMockDeps();
@@ -832,7 +875,9 @@ describe('executeDagWorkflow -- tool restrictions', () => {
 
     const sendMessage = platform.sendMessage as ReturnType<typeof mock>;
     const messages = sendMessage.mock.calls.map((call: unknown[]) => call[1] as string);
-    const warning = messages.find(m => m.includes('denied_tools') && m.includes('Codex'));
+    const warning = messages.find(
+      m => m.includes('allowed_tools/denied_tools') && m.includes('codex')
+    );
     expect(warning).toBeDefined();
   });
 
@@ -859,7 +904,8 @@ describe('executeDagWorkflow -- tool restrictions', () => {
 
     expect(mockSendQueryDag.mock.calls.length).toBeGreaterThan(0);
     const optionsArg = mockSendQueryDag.mock.calls[0][3] as Record<string, unknown>;
-    expect(optionsArg?.tools).toEqual([]);
+    const nodeConfig = optionsArg?.nodeConfig as Record<string, unknown>;
+    expect(nodeConfig?.allowed_tools).toEqual([]);
   });
 
   it('passes hooks to sendQuery options for Claude node', async () => {
@@ -896,15 +942,17 @@ describe('executeDagWorkflow -- tool restrictions', () => {
 
     expect(mockSendQueryDag.mock.calls.length).toBeGreaterThan(0);
     const optionsArg = mockSendQueryDag.mock.calls[0][3] as Record<string, unknown>;
-    expect(optionsArg?.hooks).toBeDefined();
-    const hooks = optionsArg?.hooks as Record<string, unknown[]>;
+    const nodeConfig = optionsArg?.nodeConfig as Record<string, unknown>;
+    expect(nodeConfig?.hooks).toBeDefined();
+    const hooks = nodeConfig?.hooks as Record<string, unknown[]>;
     expect(hooks.PreToolUse).toHaveLength(1);
   });
 
   it('warns user when Codex DAG node has hooks', async () => {
-    mockGetAssistantClientDag.mockReturnValue({
+    mockGetAgentProviderDag.mockReturnValue({
       sendQuery: mockSendQueryDag,
       getType: () => 'codex',
+      getCapabilities: mockCodexCapabilities,
     });
 
     const mockDeps = createMockDeps();
@@ -941,7 +989,7 @@ describe('executeDagWorkflow -- tool restrictions', () => {
 
     const sendMessage = platform.sendMessage as ReturnType<typeof mock>;
     const messages = sendMessage.mock.calls.map((call: unknown[]) => call[1] as string);
-    const warning = messages.find(m => m.includes('hooks') && m.includes('Codex'));
+    const warning = messages.find(m => m.includes('hooks') && m.includes('codex'));
     expect(warning).toBeDefined();
   });
 });
@@ -954,16 +1002,17 @@ describe('executeDagWorkflow -- bash nodes', () => {
     await mkdir(testDir, { recursive: true });
 
     mockSendQueryDag.mockClear();
-    mockGetAssistantClientDag.mockClear();
+    mockGetAgentProviderDag.mockClear();
 
     mockSendQueryDag.mockImplementation(function* () {
       yield { type: 'assistant', content: 'DAG AI response' };
       yield { type: 'result', sessionId: 'dag-session-id' };
     });
 
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'claude',
+      getCapabilities: mockClaudeCapabilities,
     }));
   });
 
@@ -1162,6 +1211,38 @@ describe('executeDagWorkflow -- bash nodes', () => {
     expect(mockSendQueryDag.mock.calls.length).toBe(1);
   });
 
+  it('passes config.envVars to bash subprocesses', async () => {
+    const execSpy = spyOn(git, 'execFileAsync').mockResolvedValue({ stdout: 'ok\n', stderr: '' });
+    const mockDeps = createMockDeps();
+    const platform = createMockPlatform();
+    const workflowRun = makeWorkflowRun('bash-env-run-id');
+
+    await executeDagWorkflow(
+      mockDeps,
+      platform,
+      'conv-bash-env',
+      testDir,
+      { name: 'bash-env-test', nodes: [{ id: 'stats', bash: 'echo ok' }] },
+      workflowRun,
+      'claude',
+      undefined,
+      join(testDir, 'artifacts'),
+      join(testDir, 'logs'),
+      'main',
+      'docs/',
+      { ...minimalConfig, envVars: { MY_SECRET: 'abc123' } }
+    );
+
+    expect(execSpy).toHaveBeenCalledWith(
+      'bash',
+      ['-c', 'echo ok'],
+      expect.objectContaining({
+        env: expect.objectContaining({ MY_SECRET: 'abc123' }),
+      })
+    );
+    execSpy.mockRestore();
+  });
+
   it('bash node output with shell metacharacters does not inject into downstream bash script', async () => {
     const mockDeps = createMockDeps();
     const platform = createMockPlatform();
@@ -1221,13 +1302,14 @@ describe('executeDagWorkflow -- output_format structured output', () => {
     await writeFile(join(commandsDir, 'classify.md'), 'Classify this: $USER_MESSAGE');
 
     mockSendQueryDag.mockClear();
-    mockGetAssistantClientDag.mockClear();
+    mockGetAgentProviderDag.mockClear();
   });
 
   afterEach(async () => {
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'claude',
+      getCapabilities: mockClaudeCapabilities,
     }));
     try {
       await rm(testDir, { recursive: true, force: true });
@@ -1393,15 +1475,16 @@ describe('executeDagWorkflow -- output_format structured output', () => {
   });
 
   it('passes outputFormat to Codex nodes and uses inline JSON response', async () => {
-    // Codex returns structured output inline as agent_message text (no structuredOutput field)
+    // Codex provider normalizes inline JSON into structuredOutput on the result chunk
     const classifyJson = { run_code_review: 'true', run_tests: 'false' };
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'codex',
+      getCapabilities: mockCodexCapabilities,
     }));
     mockSendQueryDag.mockImplementation(function* () {
       yield { type: 'assistant', content: JSON.stringify(classifyJson) };
-      yield { type: 'result', sessionId: 'codex-sid-1' };
+      yield { type: 'result', sessionId: 'codex-sid-1', structuredOutput: classifyJson };
     });
 
     const mockDeps = createMockDeps();
@@ -1464,14 +1547,15 @@ describe('executeDagWorkflow -- output_format structured output', () => {
   });
 
   it('does not warn about missing structuredOutput for Codex nodes', async () => {
-    // Codex returns structured output inline — no structuredOutput field on result
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    // Codex provider normalizes inline JSON into structuredOutput on the result chunk
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'codex',
+      getCapabilities: mockCodexCapabilities,
     }));
     mockSendQueryDag.mockImplementation(function* () {
       yield { type: 'assistant', content: '{"status":"ok"}' };
-      yield { type: 'result', sessionId: 'codex-sid-2' };
+      yield { type: 'result', sessionId: 'codex-sid-2', structuredOutput: { status: 'ok' } };
     });
 
     const mockDeps = createMockDeps();
@@ -1524,10 +1608,11 @@ describe('executeDagWorkflow -- when condition parse errors (fail-closed)', () =
     await writeFile(join(commandsDir, 'my-cmd.md'), 'Do something for $USER_MESSAGE');
 
     mockSendQueryDag.mockClear();
-    mockGetAssistantClientDag.mockClear();
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    mockGetAgentProviderDag.mockClear();
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'claude',
+      getCapabilities: mockClaudeCapabilities,
     }));
     mockSendQueryDag.mockImplementation(function* () {
       yield { type: 'assistant', content: 'AI response' };
@@ -1536,9 +1621,10 @@ describe('executeDagWorkflow -- when condition parse errors (fail-closed)', () =
   });
 
   afterEach(async () => {
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'claude',
+      getCapabilities: mockClaudeCapabilities,
     }));
     try {
       await rm(testDir, { recursive: true, force: true });
@@ -1652,10 +1738,11 @@ describe('executeDagWorkflow -- node-level retry for transient errors', () => {
     await writeFile(join(commandsDir, 'my-cmd.md'), 'Do something for $USER_MESSAGE');
 
     mockSendQueryDag.mockClear();
-    mockGetAssistantClientDag.mockClear();
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    mockGetAgentProviderDag.mockClear();
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'claude',
+      getCapabilities: mockClaudeCapabilities,
     }));
     mockSendQueryDag.mockImplementation(function* () {
       yield { type: 'assistant', content: 'DAG AI response' };
@@ -1664,9 +1751,10 @@ describe('executeDagWorkflow -- node-level retry for transient errors', () => {
   });
 
   afterEach(async () => {
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'claude',
+      getCapabilities: mockClaudeCapabilities,
     }));
     try {
       await rm(testDir, { recursive: true, force: true });
@@ -1841,10 +1929,11 @@ describe('executeDagWorkflow -- tool_called event persistence', () => {
     await writeFile(join(commandsDir, 'my-cmd.md'), 'My command prompt for $USER_MESSAGE');
 
     mockSendQueryDag.mockClear();
-    mockGetAssistantClientDag.mockClear();
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    mockGetAgentProviderDag.mockClear();
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'claude',
+      getCapabilities: mockClaudeCapabilities,
     }));
   });
 
@@ -1949,10 +2038,11 @@ describe('executeDagWorkflow -- tool_completed event emission', () => {
     await writeFile(join(commandsDir, 'my-cmd.md'), 'My command prompt for $USER_MESSAGE');
 
     mockSendQueryDag.mockClear();
-    mockGetAssistantClientDag.mockClear();
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    mockGetAgentProviderDag.mockClear();
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'claude',
+      getCapabilities: mockClaudeCapabilities,
     }));
   });
 
@@ -2210,7 +2300,7 @@ describe('executeDagWorkflow -- skills options', () => {
     await writeFile(join(commandsDir, 'my-cmd.md'), 'My command prompt for $USER_MESSAGE');
 
     mockSendQueryDag.mockClear();
-    mockGetAssistantClientDag.mockClear();
+    mockGetAgentProviderDag.mockClear();
 
     mockSendQueryDag.mockImplementation(function* () {
       yield { type: 'assistant', content: 'DAG AI response' };
@@ -2219,9 +2309,10 @@ describe('executeDagWorkflow -- skills options', () => {
   });
 
   afterEach(async () => {
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'claude',
+      getCapabilities: mockClaudeCapabilities,
     }));
     try {
       await rm(testDir, { recursive: true, force: true });
@@ -2256,17 +2347,9 @@ describe('executeDagWorkflow -- skills options', () => {
 
     expect(mockSendQueryDag.mock.calls.length).toBeGreaterThan(0);
     const optionsArg = mockSendQueryDag.mock.calls[0][3] as Record<string, unknown>;
-    // agents contains the agent definition
-    const agents = optionsArg?.agents as Record<string, Record<string, unknown>>;
-    expect(agents).toBeDefined();
-    expect(agents['dag-node-review']).toBeDefined();
-    expect(agents['dag-node-review'].skills).toEqual(['codebase-search', 'test-runner']);
-    // tools always includes 'Skill' explicitly
-    expect(agents['dag-node-review'].tools).toEqual(['Skill']);
-    // agent references the key
-    expect(optionsArg?.agent).toBe('dag-node-review');
-    // allowedTools includes 'Skill' for the parent session
-    expect(optionsArg?.allowedTools).toContain('Skill');
+    const nodeConfig = optionsArg?.nodeConfig as Record<string, unknown>;
+    // skills are passed in nodeConfig — provider translates to agents internally
+    expect(nodeConfig?.skills).toEqual(['codebase-search', 'test-runner']);
   });
 
   it('appends Skill to existing allowed_tools list when node has both', async () => {
@@ -2302,17 +2385,17 @@ describe('executeDagWorkflow -- skills options', () => {
 
     expect(mockSendQueryDag.mock.calls.length).toBeGreaterThan(0);
     const optionsArg = mockSendQueryDag.mock.calls[0][3] as Record<string, unknown>;
-    const agents = optionsArg?.agents as Record<string, Record<string, unknown>>;
-    // Agent tools = allowed_tools + Skill
-    expect(agents['dag-node-review'].tools).toEqual(['Read', 'Grep', 'Skill']);
-    // Parent session also gets Skill
-    expect(optionsArg?.allowedTools).toContain('Skill');
+    const nodeConfig = optionsArg?.nodeConfig as Record<string, unknown>;
+    // skills and allowed_tools are both in nodeConfig — provider merges internally
+    expect(nodeConfig?.skills).toEqual(['codebase-search']);
+    expect(nodeConfig?.allowed_tools).toEqual(['Read', 'Grep']);
   });
 
   it('warns user when Codex DAG node has skills and does not pass agents', async () => {
-    mockGetAssistantClientDag.mockReturnValue({
+    mockGetAgentProviderDag.mockReturnValue({
       sendQuery: mockSendQueryDag,
       getType: () => 'codex',
+      getCapabilities: mockCodexCapabilities,
     });
 
     const mockDeps = createMockDeps();
@@ -2343,15 +2426,92 @@ describe('executeDagWorkflow -- skills options', () => {
     // Warning sent to user
     const sendMessage = platform.sendMessage as ReturnType<typeof mock>;
     const messages = sendMessage.mock.calls.map((call: unknown[]) => call[1] as string);
-    const warning = messages.find(m => m.includes('skills') && m.includes('Codex'));
+    const warning = messages.find(m => m.includes('skills') && m.includes('codex'));
     expect(warning).toBeDefined();
+  });
 
-    // No agents/agent passed to Codex sendQuery
-    if (mockSendQueryDag.mock.calls.length > 0) {
-      const optionsArg = mockSendQueryDag.mock.calls[0][3] as Record<string, unknown>;
-      expect(optionsArg?.agents).toBeUndefined();
-      expect(optionsArg?.agent).toBeUndefined();
-    }
+  it('passes agents to sendQuery nodeConfig when node has inline agents', async () => {
+    const mockDeps = createMockDeps();
+    const platform = createMockPlatform();
+    const workflowRun = makeWorkflowRun();
+
+    const agentsMap = {
+      'brief-gen': {
+        description: 'Summarises an issue',
+        prompt: 'You are concise.',
+        model: 'haiku',
+        tools: ['Bash', 'Read'],
+      },
+    };
+
+    await executeDagWorkflow(
+      mockDeps,
+      platform,
+      'conv-dag',
+      testDir,
+      {
+        name: 'dag-agents',
+        nodes: [{ id: 'review', command: 'my-cmd', agents: agentsMap }],
+      },
+      workflowRun,
+      'claude',
+      undefined,
+      join(testDir, 'artifacts'),
+      join(testDir, 'logs'),
+      'main',
+      'docs/',
+      minimalConfig
+    );
+
+    expect(mockSendQueryDag.mock.calls.length).toBeGreaterThan(0);
+    const optionsArg = mockSendQueryDag.mock.calls[0][3] as Record<string, unknown>;
+    const nodeConfig = optionsArg?.nodeConfig as Record<string, unknown>;
+    expect(nodeConfig?.agents).toEqual(agentsMap);
+  });
+
+  it('warns user when Codex DAG node has inline agents', async () => {
+    mockGetAgentProviderDag.mockReturnValue({
+      sendQuery: mockSendQueryDag,
+      getType: () => 'codex',
+      getCapabilities: mockCodexCapabilities,
+    });
+
+    const mockDeps = createMockDeps();
+    const platform = createMockPlatform();
+    const workflowRun = makeWorkflowRun();
+
+    await executeDagWorkflow(
+      mockDeps,
+      platform,
+      'conv-dag',
+      testDir,
+      {
+        name: 'dag-codex-agents',
+        nodes: [
+          {
+            id: 'review',
+            command: 'my-cmd',
+            provider: 'codex',
+            agents: {
+              'brief-gen': { description: 'd', prompt: 'p' },
+            },
+          },
+        ],
+      },
+      workflowRun,
+      'codex',
+      undefined,
+      join(testDir, 'artifacts'),
+      join(testDir, 'logs'),
+      'main',
+      'docs/',
+      { ...minimalConfig, assistant: 'codex' }
+    );
+
+    const sendMessage = platform.sendMessage as ReturnType<typeof mock>;
+    const messages = sendMessage.mock.calls.map((call: unknown[]) => call[1] as string);
+    const warning = messages.find(m => m.includes('agents') && m.includes('codex'));
+    expect(warning).toBeDefined();
   });
 });
 
@@ -2443,6 +2603,172 @@ nodes:
   });
 });
 
+// ---------------------------------------------------------------------------
+// Inline agents — field validation via parseWorkflow
+// ---------------------------------------------------------------------------
+
+describe('agents field validation via parseWorkflow', () => {
+  it('parses a valid agents map on a DAG node', () => {
+    const yaml = `
+name: test-agents
+description: test
+nodes:
+  - id: triage
+    prompt: "Spawn a brief-gen sub-agent"
+    agents:
+      brief-gen:
+        description: Summarises an issue
+        prompt: "You are concise. Return JSON { summary }."
+        model: haiku
+        tools: [Bash, Read]
+`;
+    const result = parseWorkflow(yaml, 'agents.yaml');
+    expect(result.error).toBeNull();
+    expect(result.workflow).not.toBeNull();
+    const wf = result.workflow!;
+    const node = wf.nodes[0];
+    expect(node.agents).toBeDefined();
+    expect(node.agents!['brief-gen'].description).toBe('Summarises an issue');
+    expect(node.agents!['brief-gen'].model).toBe('haiku');
+    expect(node.agents!['brief-gen'].tools).toEqual(['Bash', 'Read']);
+  });
+
+  it('rejects an agent missing description', () => {
+    const yaml = `
+name: missing-desc
+description: test
+nodes:
+  - id: triage
+    prompt: "p"
+    agents:
+      brief-gen:
+        prompt: "You are concise."
+`;
+    const result = parseWorkflow(yaml, 'missing-desc.yaml');
+    expect(result.error).not.toBeNull();
+    expect(result.error!.error).toContain('agents');
+  });
+
+  it('rejects an agent missing prompt', () => {
+    const yaml = `
+name: missing-prompt
+description: test
+nodes:
+  - id: triage
+    prompt: "p"
+    agents:
+      brief-gen:
+        description: "A brief generator"
+`;
+    const result = parseWorkflow(yaml, 'missing-prompt.yaml');
+    expect(result.error).not.toBeNull();
+    expect(result.error!.error).toContain('agents');
+  });
+
+  it('rejects empty agents map', () => {
+    const yaml = `
+name: empty-agents
+description: test
+nodes:
+  - id: triage
+    prompt: "p"
+    agents: {}
+`;
+    const result = parseWorkflow(yaml, 'empty-agents.yaml');
+    expect(result.error).not.toBeNull();
+    expect(result.error!.error).toContain('agents');
+  });
+
+  it('rejects agent ID that is not kebab-case', () => {
+    const yaml = `
+name: bad-id
+description: test
+nodes:
+  - id: triage
+    prompt: "p"
+    agents:
+      BriefGen:
+        description: "d"
+        prompt: "p"
+`;
+    const result = parseWorkflow(yaml, 'bad-id.yaml');
+    expect(result.error).not.toBeNull();
+    expect(result.error!.error).toContain('kebab-case');
+  });
+
+  it('ignores agents on bash nodes (field stripped, no error)', () => {
+    const yaml = `
+name: bash-agents
+description: test
+nodes:
+  - id: lint
+    bash: "echo lint"
+    agents:
+      helper:
+        description: "d"
+        prompt: "p"
+`;
+    const result = parseWorkflow(yaml, 'bash-agents.yaml');
+    expect(result.error).toBeNull();
+    const wf = result.workflow!;
+    expect(wf.nodes[0].agents).toBeUndefined();
+  });
+
+  it('ignores agents on script nodes (field stripped, no error)', () => {
+    const yaml = `
+name: script-agents
+description: test
+nodes:
+  - id: run
+    script: 'console.log("hi")'
+    runtime: bun
+    agents:
+      helper:
+        description: "d"
+        prompt: "p"
+`;
+    const result = parseWorkflow(yaml, 'script-agents.yaml');
+    expect(result.error).toBeNull();
+    const wf = result.workflow!;
+    expect(wf.nodes[0].agents).toBeUndefined();
+  });
+
+  it('ignores agents on loop nodes (field stripped, no error)', () => {
+    const yaml = `
+name: loop-agents
+description: test
+nodes:
+  - id: iterate
+    loop:
+      prompt: "Do the work"
+      until: "DONE"
+      max_iterations: 2
+    agents:
+      helper:
+        description: "d"
+        prompt: "p"
+`;
+    const result = parseWorkflow(yaml, 'loop-agents.yaml');
+    expect(result.error).toBeNull();
+    const wf = result.workflow!;
+    expect(wf.nodes[0].agents).toBeUndefined();
+  });
+
+  it('node with no agents field is undefined', () => {
+    const yaml = `
+name: no-agents
+description: test
+nodes:
+  - id: basic
+    prompt: "Do something"
+`;
+    const result = parseWorkflow(yaml, 'no-agents.yaml');
+    expect(result.error).toBeNull();
+    const wf = result.workflow!;
+    expect(wf.nodes[0].agents).toBeUndefined();
+  });
+});
+
 describe('executeDagWorkflow -- resume with priorCompletedNodes', () => {
   let testDir: string;
 
@@ -2457,7 +2783,7 @@ describe('executeDagWorkflow -- resume with priorCompletedNodes', () => {
     await writeFile(join(commandsDir, 'step2.md'), 'Step 2 prompt using $step1.output');
 
     mockSendQueryDag.mockClear();
-    mockGetAssistantClientDag.mockClear();
+    mockGetAgentProviderDag.mockClear();
 
     mockSendQueryDag.mockImplementation(function* () {
       yield { type: 'assistant', content: 'AI response' };
@@ -2466,9 +2792,10 @@ describe('executeDagWorkflow -- resume with priorCompletedNodes', () => {
   });
 
   afterEach(async () => {
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'claude',
+      getCapabilities: mockClaudeCapabilities,
     }));
     try {
       await rm(testDir, { recursive: true, force: true });
@@ -2860,6 +3187,75 @@ describe('executeDagWorkflow -- resume with priorCompletedNodes', () => {
       ).toBe(1);
     });
 
+    it('completes on final iteration with XML-wrapped signal (<COMPLETE>SIGNAL</COMPLETE>)', async () => {
+      let callCount = 0;
+      mockSendQueryDag.mockImplementation(function* () {
+        callCount++;
+        if (callCount < 3) {
+          yield { type: 'assistant', content: `Iteration ${String(callCount)} progress` };
+          yield { type: 'result', sessionId: `loop-session-${String(callCount)}` };
+        } else {
+          // Final iteration uses <COMPLETE> tag instead of <promise>
+          yield { type: 'assistant', content: 'All clean! <COMPLETE>ALL_CLEAN</COMPLETE>' };
+          yield { type: 'result', sessionId: `loop-session-${String(callCount)}` };
+        }
+      });
+
+      const mockDeps = createMockDeps();
+      const platform = createMockPlatform();
+      const workflowRun = makeWorkflowRun();
+
+      await executeDagWorkflow(
+        mockDeps,
+        platform,
+        'conv-dag',
+        testDir,
+        {
+          name: 'dag-loop-xml-tag',
+          nodes: [
+            {
+              id: 'fix-and-review',
+              loop: {
+                prompt: 'Fix and review. When done, output <COMPLETE>ALL_CLEAN</COMPLETE>.',
+                until: 'ALL_CLEAN',
+                max_iterations: 3,
+              },
+            },
+          ],
+        },
+        workflowRun,
+        'claude',
+        undefined,
+        join(testDir, 'artifacts'),
+        join(testDir, 'logs'),
+        'main',
+        'docs/',
+        minimalConfig
+      );
+
+      // 3 iterations run, signal found on iteration 3 → completed, NOT failed
+      expect(mockSendQueryDag.mock.calls.length).toBe(3);
+      expect(
+        (
+          mockDeps.store.completeWorkflowRun as Mock<
+            (id: string, metadata?: Record<string, unknown>) => Promise<void>
+          >
+        ).mock.calls.length
+      ).toBe(1);
+      expect(
+        (mockDeps.store.failWorkflowRun as Mock<(id: string, error: string) => Promise<void>>).mock
+          .calls.length
+      ).toBe(0);
+      // Verify stripping: raw XML completion tags must not appear in user-visible output
+      const allSentMessages = (
+        platform.sendMessage as Mock<(...args: unknown[]) => Promise<void>>
+      ).mock.calls
+        .map((call: unknown[]) => call[1] as string)
+        .join('');
+      expect(allSentMessages).not.toContain('<COMPLETE>');
+      expect(allSentMessages).not.toContain('</COMPLETE>');
+    });
+
     it('loop node output available to downstream nodes via $nodeId.output', async () => {
       let loopCallCount = 0;
       mockSendQueryDag.mockImplementation(function* (prompt: string) {
@@ -3519,6 +3915,70 @@ describe('executeDagWorkflow -- resume with priorCompletedNodes', () => {
       expect(sessionArg).toBe('loop-session-1');
     });
 
+    it('loop iteration fails loudly when SDK returns error_during_execution', async () => {
+      // Regression test for #1208: previously the loop silently broke on isError
+      // results and kept iterating with empty output, producing "5-second crashes"
+      // that masqueraded as successful iterations.
+      mockSendQueryDag.mockImplementation(function* () {
+        yield {
+          type: 'result',
+          isError: true,
+          errorSubtype: 'error_during_execution',
+          errors: ['Subprocess crashed mid-turn'],
+          sessionId: 'bad-session',
+        };
+      });
+
+      const store = createMockStore();
+      const mockDeps = createMockDeps(store);
+      const platform = createMockPlatform();
+      const workflowRun = makeWorkflowRun();
+
+      await executeDagWorkflow(
+        mockDeps,
+        platform,
+        'conv-dag',
+        testDir,
+        {
+          name: 'loop-iteration-err',
+          nodes: [
+            {
+              id: 'work',
+              loop: {
+                prompt: 'Do the work. Say DONE.',
+                until: 'DONE',
+                max_iterations: 5,
+              },
+            },
+          ],
+        },
+        workflowRun,
+        'claude',
+        undefined,
+        join(testDir, 'artifacts'),
+        join(testDir, 'logs'),
+        'main',
+        'docs/',
+        minimalConfig
+      );
+
+      // Should fail after one iteration rather than burning through max_iterations
+      expect(mockSendQueryDag.mock.calls.length).toBe(1);
+      // The loop_iteration_failed event should carry the subtype and SDK errors detail
+      const eventCalls = (store.createWorkflowEvent as ReturnType<typeof mock>).mock.calls;
+      const iterFailedEvents = eventCalls.filter(
+        (call: unknown[]) =>
+          (call[0] as Record<string, unknown>).event_type === 'loop_iteration_failed'
+      );
+      expect(iterFailedEvents.length).toBeGreaterThan(0);
+      const failedData = (iterFailedEvents[0][0] as Record<string, unknown>).data as Record<
+        string,
+        unknown
+      >;
+      expect(failedData.error).toContain('error_during_execution');
+      expect(failedData.error).toContain('Subprocess crashed mid-turn');
+    });
+
     it('non-interactive loop is unaffected (no pause)', async () => {
       mockSendQueryDag.mockImplementation(function* () {
         yield { type: 'assistant', content: 'Still working...' };
@@ -3578,11 +4038,12 @@ describe('executeDagWorkflow -- break after result (no hang on subprocess exit)'
     await writeFile(join(commandsDir, 'my-cmd.md'), 'Command prompt $ARGUMENTS');
 
     mockSendQueryDag.mockClear();
-    mockGetAssistantClientDag.mockClear();
+    mockGetAgentProviderDag.mockClear();
 
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'claude',
+      getCapabilities: mockClaudeCapabilities,
     }));
   });
 
@@ -3592,9 +4053,10 @@ describe('executeDagWorkflow -- break after result (no hang on subprocess exit)'
       yield { type: 'assistant', content: 'DAG AI response' };
       yield { type: 'result', sessionId: 'dag-session-id' };
     });
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'claude',
+      getCapabilities: mockClaudeCapabilities,
     }));
     try {
       await rm(testDir, { recursive: true, force: true });
@@ -3700,11 +4162,12 @@ describe('executeDagWorkflow -- terminal node output selection', () => {
     await writeFile(join(commandsDir, 'my-cmd.md'), 'Command prompt $ARGUMENTS');
 
     mockSendQueryDag.mockClear();
-    mockGetAssistantClientDag.mockClear();
+    mockGetAgentProviderDag.mockClear();
 
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'claude',
+      getCapabilities: mockClaudeCapabilities,
     }));
   });
 
@@ -3713,9 +4176,10 @@ describe('executeDagWorkflow -- terminal node output selection', () => {
       yield { type: 'assistant', content: 'DAG AI response' };
       yield { type: 'result', sessionId: 'dag-session-id' };
     });
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'claude',
+      getCapabilities: mockClaudeCapabilities,
     }));
     try {
       await rm(testDir, { recursive: true, force: true });
@@ -3951,13 +4415,14 @@ describe('executeDagWorkflow -- credit exhaustion', () => {
     await mkdir(commandsDir, { recursive: true });
 
     mockSendQueryDag.mockClear();
-    mockGetAssistantClientDag.mockClear();
+    mockGetAgentProviderDag.mockClear();
   });
 
   afterEach(async () => {
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'claude',
+      getCapabilities: mockClaudeCapabilities,
     }));
     mockSendQueryDag.mockImplementation(function* () {
       yield { type: 'assistant', content: 'DAG AI response' };
@@ -3975,9 +4440,10 @@ describe('executeDagWorkflow -- credit exhaustion', () => {
       yield { type: 'assistant', content: "You're out of extra usage · resets in 2h" };
       yield { type: 'result', sessionId: 'dag-session-credit' };
     });
-    mockGetAssistantClientDag.mockReturnValue({
+    mockGetAgentProviderDag.mockReturnValue({
       sendQuery: creditExhaustedQuery,
       getType: () => 'claude',
+      getCapabilities: mockClaudeCapabilities,
     });
 
     const store = createMockStore();
@@ -4025,17 +4491,19 @@ describe('executeDagWorkflow -- approval node', () => {
     );
     await mkdir(join(testDir, '.archon', 'commands'), { recursive: true });
     mockSendQueryDag.mockClear();
-    mockGetAssistantClientDag.mockClear();
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    mockGetAgentProviderDag.mockClear();
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'claude',
+      getCapabilities: mockClaudeCapabilities,
     }));
   });
 
   afterEach(async () => {
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'claude',
+      getCapabilities: mockClaudeCapabilities,
     }));
     try {
       await rm(testDir, { recursive: true, force: true });
@@ -4333,16 +4801,18 @@ describe('executeDagWorkflow -- env var injection', () => {
       await writeFile(join(testDir, '.archon', 'commands', 'my-cmd.md'), '# Test');
     });
     mockSendQueryDag.mockClear();
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'claude',
+      getCapabilities: mockClaudeCapabilities,
     }));
   });
 
   afterEach(async () => {
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'claude',
+      getCapabilities: mockClaudeCapabilities,
     }));
     try {
       await rm(testDir, { recursive: true, force: true });
@@ -4417,16 +4887,17 @@ describe('executeDagWorkflow -- Claude SDK advanced options', () => {
     await writeFile(join(commandsDir, 'my-cmd.md'), 'My command prompt');
 
     mockSendQueryDag.mockClear();
-    mockGetAssistantClientDag.mockClear();
+    mockGetAgentProviderDag.mockClear();
     mockLogFn.mockClear();
 
     mockSendQueryDag.mockImplementation(function* () {
       yield { type: 'assistant', content: 'DAG AI response' };
       yield { type: 'result', sessionId: 'dag-session-id' };
     });
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'claude',
+      getCapabilities: mockClaudeCapabilities,
     }));
   });
 
@@ -4531,6 +5002,58 @@ describe('executeDagWorkflow -- Claude SDK advanced options', () => {
     expect(capMessage).toBeDefined();
   });
 
+  it('fails node when SDK returns error_during_execution result', async () => {
+    // Regression test for #1208: previously we only failed on error_max_budget_usd
+    // and silently broke on all other isError subtypes, letting failed nodes
+    // masquerade as successes with empty output.
+    mockSendQueryDag.mockImplementation(function* () {
+      yield {
+        type: 'result',
+        isError: true,
+        errorSubtype: 'error_during_execution',
+        errors: ['Tool call failed: permission denied'],
+        sessionId: 'sid-err',
+      };
+    });
+
+    const store = createMockStore();
+    const mockDeps = createMockDeps(store);
+    const platform = createMockPlatform();
+    const workflowRun = makeWorkflowRun();
+
+    await executeDagWorkflow(
+      mockDeps,
+      platform,
+      'conv-dag',
+      testDir,
+      {
+        name: 'err-exec-test',
+        nodes: [{ id: 'step1', command: 'my-cmd' }],
+      },
+      workflowRun,
+      'claude',
+      undefined,
+      join(testDir, 'artifacts'),
+      join(testDir, 'logs'),
+      'main',
+      'docs/',
+      minimalConfig
+    );
+
+    // The node_failed event should carry the subtype and SDK errors detail
+    const eventCalls = (store.createWorkflowEvent as ReturnType<typeof mock>).mock.calls;
+    const nodeFailedEvents = eventCalls.filter(
+      (call: unknown[]) => (call[0] as Record<string, unknown>).event_type === 'node_failed'
+    );
+    expect(nodeFailedEvents.length).toBeGreaterThan(0);
+    const failedData = (nodeFailedEvents[0][0] as Record<string, unknown>).data as Record<
+      string,
+      unknown
+    >;
+    expect(failedData.error).toContain('error_during_execution');
+    expect(failedData.error).toContain('permission denied');
+  });
+
   it('forwards workflow-level effort to node when no per-node override', async () => {
     const mockDeps = createMockDeps();
     const platform = createMockPlatform();
@@ -4558,7 +5081,8 @@ describe('executeDagWorkflow -- Claude SDK advanced options', () => {
 
     expect(mockSendQueryDag.mock.calls.length).toBeGreaterThan(0);
     const optionsArg = mockSendQueryDag.mock.calls[0][3] as Record<string, unknown>;
-    expect(optionsArg?.effort).toBe('high');
+    const nodeConfig = optionsArg?.nodeConfig as Record<string, unknown>;
+    expect(nodeConfig?.effort).toBe('high');
   });
 
   it('per-node effort overrides workflow-level effort', async () => {
@@ -4588,13 +5112,15 @@ describe('executeDagWorkflow -- Claude SDK advanced options', () => {
 
     expect(mockSendQueryDag.mock.calls.length).toBeGreaterThan(0);
     const optionsArg = mockSendQueryDag.mock.calls[0][3] as Record<string, unknown>;
-    expect(optionsArg?.effort).toBe('max');
+    const nodeConfig = optionsArg?.nodeConfig as Record<string, unknown>;
+    expect(nodeConfig?.effort).toBe('max');
   });
 
   it('warns user when Codex node has Claude-only options (effort)', async () => {
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'codex',
+      getCapabilities: mockCodexCapabilities,
     }));
 
     const mockDeps = createMockDeps();
@@ -4637,12 +5163,13 @@ describe('executeDagWorkflow -- cost tracking', () => {
     await writeFile(join(commandsDir, 'my-cmd.md'), 'My command prompt');
 
     mockSendQueryDag.mockClear();
-    mockGetAssistantClientDag.mockClear();
+    mockGetAgentProviderDag.mockClear();
     mockLogFn.mockClear();
 
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'claude',
+      getCapabilities: mockClaudeCapabilities,
     }));
   });
 
@@ -4835,16 +5362,17 @@ describe('executeDagWorkflow -- script nodes', () => {
     await mkdir(testDir, { recursive: true });
 
     mockSendQueryDag.mockClear();
-    mockGetAssistantClientDag.mockClear();
+    mockGetAgentProviderDag.mockClear();
 
     mockSendQueryDag.mockImplementation(function* () {
       yield { type: 'assistant', content: 'DAG AI response' };
       yield { type: 'result', sessionId: 'dag-session-id' };
     });
 
-    mockGetAssistantClientDag.mockImplementation(() => ({
+    mockGetAgentProviderDag.mockImplementation(() => ({
       sendQuery: mockSendQueryDag,
       getType: () => 'claude',
+      getCapabilities: mockClaudeCapabilities,
     }));
   });
 
@@ -5209,4 +5737,345 @@ describe('executeDagWorkflow -- script nodes', () => {
     const notFoundMsg = messages.find((m: string) => m.includes('not found in .archon/scripts/'));
     expect(notFoundMsg).toBeDefined();
   });
+
+  it('bun script node does not leak repo .env from execution cwd (#1135)', async () => {
+    // Regression test: place a .env with a marker in the execution cwd.
+    // The bun script must NOT see it because --no-env-file is passed.
+    const mockDeps = createMockDeps();
+    const platform = createMockPlatform();
+    const workflowRun = makeWorkflowRun('env-leak-run-id', {
+      workflow_name: 'env-leak-test',
+      conversation_id: 'conv-env-leak',
+      user_message: 'env leak test',
+    });
+
+    // Write a .env with a marker in the script execution cwd
+    await writeFile(join(testDir, '.env'), 'LEAKED_REPO_SECRET=should_not_appear\n');
+
+    const scriptNode: ScriptNode = {
+      id: 'env-check',
+      script: 'console.log(process.env.LEAKED_REPO_SECRET ?? "CLEAN")',
+      runtime: 'bun',
+    };
+
+    await executeDagWorkflow(
+      mockDeps,
+      platform,
+      'conv-env-leak',
+      testDir,
+      { name: 'env-leak-test', nodes: [scriptNode] },
+      workflowRun,
+      'claude',
+      undefined,
+      join(testDir, 'artifacts'),
+      join(testDir, 'logs'),
+      'main',
+      'docs/',
+      minimalConfig
+    );
+
+    // The node output should be "CLEAN" — the repo .env was not loaded
+    const eventCalls = (mockDeps.store.createWorkflowEvent as ReturnType<typeof mock>).mock.calls;
+    const completedEvent = eventCalls.find(
+      (call: unknown[]) =>
+        (call[0] as { event_type: string }).event_type === 'node_completed' &&
+        (call[0] as { step_name: string }).step_name === 'env-check'
+    );
+    expect(completedEvent).toBeDefined();
+    expect((completedEvent![0] as { data: { node_output: string } }).data.node_output).toBe(
+      'CLEAN'
+    );
+  });
+
+  it('passes config.envVars to script subprocesses', async () => {
+    const execSpy = spyOn(git, 'execFileAsync').mockResolvedValue({ stdout: 'ok\n', stderr: '' });
+    const mockDeps = createMockDeps();
+    const platform = createMockPlatform();
+    const workflowRun = makeWorkflowRun('script-env-run-id');
+
+    await executeDagWorkflow(
+      mockDeps,
+      platform,
+      'conv-script-env',
+      testDir,
+      {
+        name: 'script-env-test',
+        nodes: [{ id: 'inline-bun', script: 'console.log("ok")', runtime: 'bun' }],
+      },
+      workflowRun,
+      'claude',
+      undefined,
+      join(testDir, 'artifacts'),
+      join(testDir, 'logs'),
+      'main',
+      'docs/',
+      { ...minimalConfig, envVars: { MY_SECRET: 'abc123' } }
+    );
+
+    expect(execSpy).toHaveBeenCalledWith(
+      'bun',
+      ['--no-env-file', '-e', 'console.log("ok")'],
+      expect.objectContaining({
+        env: expect.objectContaining({ MY_SECRET: 'abc123' }),
+      })
+    );
+    execSpy.mockRestore();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// MCP plugin-noise filtering helpers
+// ---------------------------------------------------------------------------
+
+describe('parseMcpFailureServerNames', () => {
+  it('extracts entries (name + segment) from a well-formed message', async () => {
+    const { parseMcpFailureServerNames } = await import('./dag-executor');
+    const entries = parseMcpFailureServerNames(
+      'MCP server connection failed: telegram (disconnected), github (timeout)'
+    );
+    expect(entries).toEqual([
+      { name: 'telegram', segment: 'telegram (disconnected)' },
+      { name: 'github', segment: 'github (timeout)' },
+    ]);
+  });
+
+  it('returns empty array for unrelated messages', async () => {
+    const { parseMcpFailureServerNames } = await import('./dag-executor');
+    expect(parseMcpFailureServerNames('⚠️ Something else')).toEqual([]);
+    expect(parseMcpFailureServerNames('')).toEqual([]);
+  });
+
+  it('deduplicates repeated entries (first segment wins)', async () => {
+    const { parseMcpFailureServerNames } = await import('./dag-executor');
+    const entries = parseMcpFailureServerNames(
+      'MCP server connection failed: foo (a), foo (b), bar (c)'
+    );
+    expect(entries).toEqual([
+      { name: 'foo', segment: 'foo (a)' },
+      { name: 'bar', segment: 'bar (c)' },
+    ]);
+  });
+
+  it('handles a single entry without status parens gracefully', async () => {
+    const { parseMcpFailureServerNames } = await import('./dag-executor');
+    expect(parseMcpFailureServerNames('MCP server connection failed: solo')).toEqual([
+      { name: 'solo', segment: 'solo' },
+    ]);
+  });
+
+  it('drops empty segments from trailing/leading commas', async () => {
+    const { parseMcpFailureServerNames } = await import('./dag-executor');
+    expect(parseMcpFailureServerNames('MCP server connection failed: a (x), , b (y)')).toEqual([
+      { name: 'a', segment: 'a (x)' },
+      { name: 'b', segment: 'b (y)' },
+    ]);
+  });
+});
+
+describe('loadConfiguredMcpServerNames', () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `mcp-names-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  it('returns empty set when nodeMcpPath is undefined', async () => {
+    const { loadConfiguredMcpServerNames } = await import('./dag-executor');
+    const names = await loadConfiguredMcpServerNames(undefined, testDir);
+    expect(names.size).toBe(0);
+  });
+
+  it('returns server names for a valid JSON config (relative path)', async () => {
+    const { loadConfiguredMcpServerNames } = await import('./dag-executor');
+    await writeFile(
+      join(testDir, 'mcp.json'),
+      JSON.stringify({ foo: { command: 'x' }, bar: { command: 'y' } })
+    );
+    const names = await loadConfiguredMcpServerNames('mcp.json', testDir);
+    expect([...names].sort()).toEqual(['bar', 'foo']);
+  });
+
+  it('returns server names for an absolute path', async () => {
+    const { loadConfiguredMcpServerNames } = await import('./dag-executor');
+    const absolutePath = join(testDir, 'abs.json');
+    await writeFile(absolutePath, JSON.stringify({ baz: {} }));
+    const names = await loadConfiguredMcpServerNames(absolutePath, '/nonexistent/cwd');
+    expect([...names]).toEqual(['baz']);
+  });
+
+  it('returns empty set when file is missing (no crash)', async () => {
+    const { loadConfiguredMcpServerNames } = await import('./dag-executor');
+    const names = await loadConfiguredMcpServerNames('missing.json', testDir);
+    expect(names.size).toBe(0);
+  });
+
+  it('returns empty set for invalid JSON (provider surfaces its own error)', async () => {
+    const { loadConfiguredMcpServerNames } = await import('./dag-executor');
+    await writeFile(join(testDir, 'broken.json'), '{ not-json');
+    const names = await loadConfiguredMcpServerNames('broken.json', testDir);
+    expect(names.size).toBe(0);
+  });
+
+  it('returns empty set when JSON is an array (not an object of servers)', async () => {
+    const { loadConfiguredMcpServerNames } = await import('./dag-executor');
+    await writeFile(join(testDir, 'arr.json'), '["foo","bar"]');
+    const names = await loadConfiguredMcpServerNames('arr.json', testDir);
+    expect(names.size).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// MCP plugin-noise filtering — end-to-end through executeDagWorkflow
+// ---------------------------------------------------------------------------
+
+describe('executeDagWorkflow -- MCP failure filtering', () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `dag-mcp-filter-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    const commandsDir = join(testDir, '.archon', 'commands');
+    await mkdir(commandsDir, { recursive: true });
+    await writeFile(join(commandsDir, 'my-cmd.md'), 'cmd prompt');
+
+    mockSendQueryDag.mockClear();
+    mockGetAgentProviderDag.mockClear();
+  });
+
+  afterEach(async () => {
+    mockGetAgentProviderDag.mockImplementation(() => ({
+      sendQuery: mockSendQueryDag,
+      getType: () => 'claude',
+      getCapabilities: mockClaudeCapabilities,
+    }));
+    try {
+      await rm(testDir, { recursive: true, force: true });
+    } catch {
+      // ignore cleanup errors
+    }
+  });
+
+  async function runWithSystemChunk(
+    systemContent: string,
+    nodeMcpPath?: string
+  ): Promise<IWorkflowPlatform> {
+    mockSendQueryDag.mockImplementation(function* () {
+      yield { type: 'system', content: systemContent };
+      yield { type: 'assistant', content: 'ok' };
+      yield { type: 'result', sessionId: 'sess' };
+    });
+
+    const platform = createMockPlatform();
+    await executeDagWorkflow(
+      createMockDeps(),
+      platform,
+      'conv-mcp-filter',
+      testDir,
+      {
+        name: 'mcp-filter-test',
+        nodes: [{ id: 'review', command: 'my-cmd', ...(nodeMcpPath ? { mcp: nodeMcpPath } : {}) }],
+      },
+      makeWorkflowRun(),
+      'claude',
+      undefined,
+      join(testDir, 'artifacts'),
+      join(testDir, 'logs'),
+      'main',
+      'docs/',
+      minimalConfig
+    );
+    return platform;
+  }
+
+  function mcpMessages(platform: IWorkflowPlatform): string[] {
+    const calls = (platform.sendMessage as Mock<typeof platform.sendMessage>).mock.calls;
+    return calls
+      .map(c => c[1] as string)
+      .filter(m => m.startsWith('MCP server connection failed:') || m.startsWith('⚠️'));
+  }
+
+  it('forwards only workflow-configured failures and preserves status detail', async () => {
+    await writeFile(join(testDir, 'mcp.json'), JSON.stringify({ 'workflow-server': {} }));
+    const platform = await runWithSystemChunk(
+      'MCP server connection failed: workflow-server (timeout), telegram (disconnected)',
+      'mcp.json'
+    );
+
+    const sent = mcpMessages(platform);
+    expect(sent).toEqual(['MCP server connection failed: workflow-server (timeout)']);
+  });
+
+  it('suppresses MCP message entirely when all failures are user plugins', async () => {
+    await writeFile(join(testDir, 'mcp.json'), JSON.stringify({ 'workflow-server': {} }));
+    const platform = await runWithSystemChunk(
+      'MCP server connection failed: telegram (disconnected), notion (timeout)',
+      'mcp.json'
+    );
+
+    expect(mcpMessages(platform)).toEqual([]);
+  });
+
+  it('suppresses everything when node has no mcp: config (all failures are plugin noise)', async () => {
+    const platform = await runWithSystemChunk(
+      'MCP server connection failed: telegram (disconnected)'
+    );
+
+    expect(mcpMessages(platform)).toEqual([]);
+  });
+
+  it('forwards ⚠️ provider warnings verbatim', async () => {
+    const platform = await runWithSystemChunk('⚠️ Haiku does not support MCP');
+
+    expect(mcpMessages(platform)).toEqual(['⚠️ Haiku does not support MCP']);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Streaming cancel-check policy (during-streaming paused tolerance)
+// ---------------------------------------------------------------------------
+
+describe('shouldContinueStreamingForStatus', () => {
+  it('continues when status is running', async () => {
+    const { shouldContinueStreamingForStatus } = await import('./dag-executor');
+    expect(shouldContinueStreamingForStatus('running')).toBe(true);
+  });
+
+  it('continues when status is paused (sibling approval node in same layer)', async () => {
+    // The key invariant: a concurrent approval node can pause the run while a
+    // streaming AI node is mid-response. The streaming node must finish its
+    // own output — workflow progression is gated by the approval node, not
+    // by tearing down unrelated in-flight streams.
+    const { shouldContinueStreamingForStatus } = await import('./dag-executor');
+    expect(shouldContinueStreamingForStatus('paused')).toBe(true);
+  });
+
+  it('aborts when status is null (run deleted)', async () => {
+    const { shouldContinueStreamingForStatus } = await import('./dag-executor');
+    expect(shouldContinueStreamingForStatus(null)).toBe(false);
+  });
+
+  it('aborts when status is cancelled', async () => {
+    const { shouldContinueStreamingForStatus } = await import('./dag-executor');
+    expect(shouldContinueStreamingForStatus('cancelled')).toBe(false);
+  });
+
+  it('aborts when status is failed', async () => {
+    const { shouldContinueStreamingForStatus } = await import('./dag-executor');
+    expect(shouldContinueStreamingForStatus('failed')).toBe(false);
+  });
+
+  it('aborts when status is completed', async () => {
+    const { shouldContinueStreamingForStatus } = await import('./dag-executor');
+    expect(shouldContinueStreamingForStatus('completed')).toBe(false);
+  });
+
+  it('aborts on any unrecognized state', async () => {
+    const { shouldContinueStreamingForStatus } = await import('./dag-executor');
+    expect(shouldContinueStreamingForStatus('pending')).toBe(false);
+    expect(shouldContinueStreamingForStatus('invalid-status')).toBe(false);
+  });
 });
diff --git a/packages/workflows/src/dag-executor.ts b/packages/workflows/src/dag-executor.ts
index facfbd1068..419a9066f6 100644
--- a/packages/workflows/src/dag-executor.ts
+++ b/packages/workflows/src/dag-executor.ts
@@ -6,17 +6,22 @@
  * Captures all assistant output regardless of streaming mode for $node_id.output substitution.
  */
 import { readFile } from 'fs/promises';
-import { resolve, isAbsolute } from 'path';
+import { isAbsolute, resolve as resolvePath } from 'path';
 import { execFileAsync } from '@archon/git';
-import { discoverScripts } from './script-discovery';
+import { discoverScriptsForCwd } from './script-discovery';
 import type {
-  WorkflowAssistantOptions,
   IWorkflowPlatform,
   WorkflowMessageMetadata,
-  WorkflowTokenUsage,
   WorkflowConfig,
   WorkflowDeps,
 } from './deps';
+import type {
+  SendQueryOptions,
+  NodeConfig,
+  ProviderCapabilities,
+  TokenUsage,
+} from '@archon/providers/types';
+import { getProviderCapabilities } from '@archon/providers';
 import type {
   DagNode,
   ApprovalNode,
@@ -28,7 +33,6 @@ import type {
   NodeOutput,
   TriggerRule,
   WorkflowRun,
-  WorkflowNodeHooks,
   EffortLevel,
   ThinkingConfig,
   SandboxSettings,
@@ -45,7 +49,7 @@ import { formatToolCall } from './utils/tool-formatter';
 import { createLogger } from '@archon/paths';
 import { getWorkflowEventEmitter } from './event-emitter';
 import { evaluateCondition } from './condition-evaluator';
-import { isClaudeModel, isModelCompatible } from './model-validation';
+import { inferProviderFromModel, isModelCompatible } from './model-validation';
 import {
   logNodeStart,
   logNodeComplete,
@@ -75,6 +79,69 @@ function getLog(): ReturnType<typeof createLogger> {
   return cachedLog;
 }
 
+const MCP_FAILURE_PREFIX = 'MCP server connection failed: ';
+
+/** A failed MCP server entry parsed from the SDK message. `segment` is the
+ *  original substring (e.g. `"telegram (disconnected)"`) so callers can
+ *  reconstruct a filtered message without losing the status detail. */
+export interface McpFailureEntry {
+  name: string;
+  segment: string;
+}
+
+/**
+ * Parse the SDK's "MCP server connection failed: a (status), b (status)"
+ * message. Best-effort — malformed or prefix-free messages return `[]`.
+ * Entries are ordered and deduped by name; the segment of the first
+ * occurrence wins.
+ */
+export function parseMcpFailureServerNames(message: string): McpFailureEntry[] {
+  if (!message.startsWith(MCP_FAILURE_PREFIX)) return [];
+  const seen = new Set<string>();
+  const entries: McpFailureEntry[] = [];
+  for (const raw of message.slice(MCP_FAILURE_PREFIX.length).split(', ')) {
+    const segment = raw.trim();
+    const name = segment.split(' (')[0]?.trim();
+    if (name && !seen.has(name)) {
+      seen.add(name);
+      entries.push({ name, segment });
+    }
+  }
+  return entries;
+}
+
+/**
+ * Load the set of MCP server names that a node's `mcp:` config file declares.
+ *
+ * Returns an empty set when no `mcp:` is configured or when the file can't be
+ * read/parsed. Used to distinguish workflow-configured failures (surface to
+ * user) from user-plugin failures (silent debug log). We intentionally do not
+ * validate or env-expand here — the provider owns full loading and will
+ * surface its own parse errors via the warning channel if the file is broken.
+ *
+ * Read failures are debug-logged so a transient I/O error (EMFILE/EBUSY) that
+ * leaves us with an empty set — and silently reclassifies a real workflow-MCP
+ * failure as plugin noise — is at least observable.
+ */
+export async function loadConfiguredMcpServerNames(
+  nodeMcpPath: string | undefined,
+  cwd: string
+): Promise<Set<string>> {
+  if (!nodeMcpPath) return new Set();
+  const fullPath = isAbsolute(nodeMcpPath) ? nodeMcpPath : resolvePath(cwd, nodeMcpPath);
+  try {
+    const raw = await readFile(fullPath, 'utf-8');
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+      return new Set();
+    }
+    return new Set(Object.keys(parsed as Record<string, unknown>));
+  } catch (err) {
+    getLog().debug({ err, nodeMcpPath, fullPath }, 'dag.mcp_filter_config_read_failed');
+    return new Set();
+  }
+}
+
 /** Workflow-level Claude SDK options — per-node overrides take precedence via ?? */
 interface WorkflowLevelOptions {
   effort?: EffortLevel;
@@ -91,6 +158,26 @@ type NodeExecutionResult = NodeOutput & { costUsd?: number };
 const lastNodeCancelCheck = new Map<string, number>();
 const CANCEL_CHECK_INTERVAL_MS = 10_000;
 
+/**
+ * Policy for the during-streaming cancel check: should the currently-streaming
+ * node be allowed to continue for a given observed run status?
+ *
+ * - `running`: the normal case → continue.
+ * - `paused`: a concurrent approval node in the same topological layer has
+ *   transitioned the run to paused. The streaming node should finish its own
+ *   output; workflow progression is gated by the approval node, not by tearing
+ *   down unrelated in-flight streams.
+ * - `null` (run deleted), `cancelled`, `failed`, `completed`, or any other
+ *   state → abort the stream.
+ *
+ * Exported for unit testing; the full streaming-cancel branch in
+ * `executeNodeInternal` only fires once per 10s (CANCEL_CHECK_INTERVAL_MS), so
+ * integration-level coverage of the policy is timing-sensitive and flaky.
+ */
+export function shouldContinueStreamingForStatus(status: string | null): boolean {
+  return status === 'running' || status === 'paused';
+}
+
 /** Throttle state for activity heartbeat writes (only used for stale/zombie detection) */
 const lastNodeActivityUpdate = new Map<string, number>();
 const ACTIVITY_HEARTBEAT_INTERVAL_MS = 60_000;
@@ -228,168 +315,40 @@ export function substituteNodeOutputRefs(
   );
 }
 
-/** SDK-compatible hook structure returned by buildSDKHooksFromYAML */
-type SDKHooksMap = NonNullable<WorkflowAssistantOptions['hooks']>;
-
-/**
- * Convert declarative YAML hook definitions to SDK HookCallbackMatcher arrays.
- * Each YAML matcher's `response` is wrapped in `async () => response`.
- */
-export function buildSDKHooksFromYAML(nodeHooks: WorkflowNodeHooks): SDKHooksMap {
-  const sdkHooks: SDKHooksMap = {};
-
-  for (const [event, matchers] of Object.entries(nodeHooks)) {
-    if (!matchers) continue;
-    sdkHooks[event] = matchers.map(m => ({
-      ...(m.matcher ? { matcher: m.matcher } : {}),
-      hooks: [async (): Promise<unknown> => m.response],
-      ...(m.timeout ? { timeout: m.timeout } : {}),
-    }));
-  }
-
-  if (Object.keys(sdkHooks).length === 0) {
-    getLog().warn({ nodeHooksKeys: Object.keys(nodeHooks) }, 'dag.hooks_build_produced_empty_map');
-  }
-
-  return sdkHooks;
-}
-
-/**
- * Load MCP server config from a JSON file and expand environment variables.
- * Format: Record<string, McpServerConfig> matching the SDK's expected shape.
- * $VAR_NAME references in env/headers values are expanded from process.env.
- * Secrets are NEVER logged.
- */
-export async function loadMcpConfig(
-  mcpPath: string,
-  cwd: string
-): Promise<{ servers: Record<string, unknown>; serverNames: string[]; missingVars: string[] }> {
-  const fullPath = isAbsolute(mcpPath) ? mcpPath : resolve(cwd, mcpPath);
-
-  let raw: string;
-  try {
-    raw = await readFile(fullPath, 'utf-8');
-  } catch (err) {
-    const e = err as NodeJS.ErrnoException;
-    if (e.code === 'ENOENT') {
-      throw new Error(`MCP config file not found: ${mcpPath} (resolved to ${fullPath})`);
-    }
-    throw new Error(`Failed to read MCP config file: ${mcpPath} — ${e.message}`);
-  }
-
-  let parsed: Record<string, unknown>;
-  try {
-    parsed = JSON.parse(raw) as Record<string, unknown>;
-  } catch (parseErr) {
-    const detail = (parseErr as SyntaxError).message;
-    throw new Error(`MCP config file is not valid JSON: ${mcpPath} — ${detail}`);
-  }
-
-  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-    throw new Error(`MCP config must be a JSON object (Record<string, ServerConfig>): ${mcpPath}`);
-  }
-
-  const { expanded, missingVars } = expandEnvVars(parsed);
-  const serverNames = Object.keys(expanded);
-
-  return { servers: expanded, serverNames, missingVars };
-}
-
-/**
- * Expand $VAR_NAME references in a string-valued record from process.env.
- * Undefined env vars are replaced with empty string; their names are collected in missingVars.
- * Non-string values are coerced to string with a warning.
- */
-function expandEnvVarsInRecord(
-  record: Record<string, unknown>,
-  missingVars: string[]
-): Record<string, string> {
-  const result: Record<string, string> = {};
-  for (const [key, val] of Object.entries(record)) {
-    if (typeof val !== 'string') {
-      getLog().warn({ key, valueType: typeof val }, 'dag.mcp_env_value_coerced_to_string');
-      result[key] = String(val);
-      continue;
-    }
-    result[key] = val.replace(/\$([A-Z_][A-Z0-9_]*)/g, (_, varName: string) => {
-      const envVal = process.env[varName];
-      if (envVal === undefined) {
-        missingVars.push(varName);
-      }
-      return envVal ?? '';
-    });
-  }
-  return result;
-}
-
-/**
- * Expand $VAR_NAME references in 'env' and 'headers' string values from process.env.
- * Other fields (command, args, url) are left untouched.
- * Undefined env vars are replaced with empty string and collected in missingVars.
- */
-function expandEnvVars(config: Record<string, unknown>): {
-  expanded: Record<string, unknown>;
-  missingVars: string[];
-} {
-  const result: Record<string, unknown> = {};
-  const missingVars: string[] = [];
-  for (const [serverName, serverConfig] of Object.entries(config)) {
-    if (typeof serverConfig !== 'object' || serverConfig === null) {
-      getLog().warn(
-        { serverName, valueType: typeof serverConfig },
-        'dag.mcp_server_config_not_object'
-      );
-      continue;
-    }
-    const server = { ...(serverConfig as Record<string, unknown>) };
-    if (server.env && typeof server.env === 'object') {
-      server.env = expandEnvVarsInRecord(server.env as Record<string, unknown>, missingVars);
-    }
-    if (server.headers && typeof server.headers === 'object') {
-      server.headers = expandEnvVarsInRecord(
-        server.headers as Record<string, unknown>,
-        missingVars
-      );
-    }
-    result[serverName] = server;
-  }
-  return { expanded: result, missingVars };
-}
+// buildSDKHooksFromYAML moved to @archon/providers/src/claude/provider.ts
+// loadMcpConfig moved to @archon/providers/src/claude/provider.ts
 
 /**
  * Resolve per-node provider and model.
  * Node-level overrides take precedence over workflow defaults.
+ *
+ * Provider-agnostic: builds universal base options + raw nodeConfig.
+ * The provider internally translates nodeConfig to SDK-specific options.
+ * Capability warnings inform users when features are unsupported.
  */
 async function resolveNodeProviderAndModel(
   node: DagNode,
-  workflowProvider: 'claude' | 'codex',
+  workflowProvider: string,
   workflowModel: string | undefined,
   config: WorkflowConfig,
   platform: IWorkflowPlatform,
   conversationId: string,
   workflowRunId: string,
-  cwd: string,
+  _cwd: string,
   workflowLevelOptions: WorkflowLevelOptions
 ): Promise<{
-  provider: 'claude' | 'codex';
+  provider: string;
   model: string | undefined;
-  options: WorkflowAssistantOptions | undefined;
+  options: SendQueryOptions | undefined;
 }> {
-  let provider: 'claude' | 'codex';
-
-  if (node.provider) {
-    provider = node.provider;
-  } else if (node.model && isClaudeModel(node.model)) {
-    provider = 'claude';
-  } else if (node.model) {
-    provider = 'codex';
-  } else {
-    provider = workflowProvider;
-  }
+  const provider: string = node.provider ?? inferProviderFromModel(node.model, workflowProvider);
 
-  const model =
+  const providerAssistantConfig = config.assistants[provider];
+  const model: string | undefined =
     node.model ??
-    (provider === workflowProvider ? workflowModel : config.assistants[provider]?.model);
+    (provider === workflowProvider
+      ? workflowModel
+      : (providerAssistantConfig?.model as string | undefined));
 
   if (!isModelCompatible(provider, model)) {
     throw new Error(
@@ -397,225 +356,109 @@ async function resolveNodeProviderAndModel(
     );
   }
 
-  // Warn if Codex node has allowed_tools or denied_tools (unsupported per-call)
-  if (
-    provider === 'codex' &&
-    (node.allowed_tools !== undefined || node.denied_tools !== undefined)
-  ) {
-    getLog().warn({ nodeId: node.id }, 'dag_node_tool_restrictions_ignored_codex');
-    const delivered = await safeSendMessage(
-      platform,
-      conversationId,
-      `Warning: Node '${node.id}' has allowed_tools/denied_tools set but uses Codex — per-node tool restrictions are not supported for Codex. Configure MCP servers globally in the Codex CLI config instead.`,
-      { workflowId: workflowRunId, nodeName: node.id }
-    );
-    if (!delivered) {
-      getLog().error({ nodeId: node.id, workflowRunId }, 'dag_node_codex_warning_delivery_failed');
+  // Get provider capabilities for capability warnings (static lookup, no instantiation)
+  const caps = getProviderCapabilities(provider);
+
+  // Capability warnings — inform users when features are unsupported
+  const capChecks: [string, keyof ProviderCapabilities, boolean][] = [
+    [
+      'allowed_tools/denied_tools',
+      'toolRestrictions',
+      node.allowed_tools !== undefined || node.denied_tools !== undefined,
+    ],
+    ['hooks', 'hooks', node.hooks !== undefined],
+    ['mcp', 'mcp', node.mcp !== undefined],
+    ['skills', 'skills', node.skills !== undefined && node.skills.length > 0],
+    ['agents', 'agents', node.agents !== undefined],
+    ['effort', 'effortControl', (node.effort ?? workflowLevelOptions.effort) !== undefined],
+    ['thinking', 'thinkingControl', (node.thinking ?? workflowLevelOptions.thinking) !== undefined],
+    ['maxBudgetUsd', 'costControl', node.maxBudgetUsd !== undefined],
+    [
+      'fallbackModel',
+      'fallbackModel',
+      (node.fallbackModel ?? workflowLevelOptions.fallbackModel) !== undefined,
+    ],
+    ['sandbox', 'sandbox', (node.sandbox ?? workflowLevelOptions.sandbox) !== undefined],
+    ['env', 'envInjection', (config.envVars && Object.keys(config.envVars).length > 0) === true],
+  ];
+
+  const unsupported: string[] = [];
+  for (const [field, cap, isSet] of capChecks) {
+    if (isSet && !caps[cap]) {
+      unsupported.push(field);
     }
   }
 
-  // Warn if Codex node has hooks (unsupported)
-  if (provider === 'codex' && node.hooks) {
-    getLog().warn({ nodeId: node.id }, 'dag_node_hooks_ignored_codex');
+  if (unsupported.length > 0) {
+    getLog().warn({ nodeId: node.id, provider, unsupported }, 'dag.unsupported_capabilities');
     const delivered = await safeSendMessage(
       platform,
       conversationId,
-      `Warning: Node '${node.id}' has hooks set but uses Codex provider — hooks are Claude-only and will be ignored.`,
+      `Warning: Node '${node.id}' uses ${unsupported.join(', ')} but ${provider} doesn't support ${unsupported.length === 1 ? 'it' : 'them'} — ${unsupported.length === 1 ? 'this will be' : 'these will be'} ignored.`,
       { workflowId: workflowRunId, nodeName: node.id }
     );
     if (!delivered) {
-      getLog().error({ nodeId: node.id, workflowRunId }, 'dag_node_hooks_warning_delivery_failed');
+      getLog().error({ nodeId: node.id, workflowRunId }, 'dag.capability_warning_delivery_failed');
     }
   }
 
-  // Warn if Codex node has mcp (unsupported per-call)
-  if (provider === 'codex' && node.mcp) {
-    getLog().warn({ nodeId: node.id }, 'dag.mcp_ignored_codex');
-    const delivered = await safeSendMessage(
+  // Surface agents + skills ID collision — user-defined 'dag-node-skills'
+  // silently overrides Archon's skills wrapper. User wins (by design) but
+  // the operator should know they've neutered the wrapper.
+  if (
+    node.agents?.['dag-node-skills'] !== undefined &&
+    node.skills !== undefined &&
+    node.skills.length > 0
+  ) {
+    getLog().warn({ nodeId: node.id }, 'dag.agents_skills_id_collision');
+    await safeSendMessage(
       platform,
       conversationId,
-      `Warning: Node '${node.id}' has mcp config but uses Codex — per-node MCP servers are not supported for Codex. Configure MCP servers globally in the Codex CLI config instead.`,
+      `Warning: Node '${node.id}' defines an agent with reserved ID 'dag-node-skills' AND uses 'skills:'. Your inline agent overrides Archon's automatic skills wrapper — the 'skills:' field will NOT take effect. Rename the agent or remove 'skills:' to fix.`,
       { workflowId: workflowRunId, nodeName: node.id }
     );
-    if (!delivered) {
-      getLog().error({ nodeId: node.id, workflowRunId }, 'dag.mcp_warning_delivery_failed');
-    }
   }
 
-  // Warn if Codex node has skills (unsupported)
-  if (provider === 'codex' && node.skills) {
-    getLog().warn({ nodeId: node.id }, 'dag.skills_ignored_codex');
-    const delivered = await safeSendMessage(
-      platform,
-      conversationId,
-      `Warning: Node '${node.id}' has skills set but uses Codex — per-node skills are not supported for Codex.`,
-      { workflowId: workflowRunId, nodeName: node.id }
-    );
-    if (!delivered) {
-      getLog().error({ nodeId: node.id, workflowRunId }, 'dag.skills_warning_delivery_failed');
-    }
+  // Build universal base options
+  const baseOptions: SendQueryOptions = {};
+  if (model) baseOptions.model = model;
+  if (config.envVars && Object.keys(config.envVars).length > 0) {
+    baseOptions.env = config.envVars;
   }
-
-  // Warn if Codex node has Claude-only SDK options (effort, thinking, maxBudgetUsd, systemPrompt, fallbackModel, betas, sandbox)
-  if (provider === 'codex') {
-    const claudeOnlyFields = [
-      ['effort', node.effort ?? workflowLevelOptions.effort],
-      ['thinking', node.thinking ?? workflowLevelOptions.thinking],
-      ['maxBudgetUsd', node.maxBudgetUsd],
-      ['systemPrompt', node.systemPrompt],
-      ['fallbackModel', node.fallbackModel ?? workflowLevelOptions.fallbackModel],
-      ['betas', node.betas ?? workflowLevelOptions.betas],
-      ['sandbox', node.sandbox ?? workflowLevelOptions.sandbox],
-    ] as const;
-    const present = claudeOnlyFields.filter(([, val]) => val !== undefined).map(([name]) => name);
-    if (present.length > 0) {
-      getLog().warn({ nodeId: node.id, fields: present }, 'dag.claude_options_ignored_codex');
-      const delivered = await safeSendMessage(
-        platform,
-        conversationId,
-        `Warning: Node '${node.id}' has Claude-only options (${present.join(', ')}) but uses Codex — these will be ignored.`,
-        { workflowId: workflowRunId, nodeName: node.id }
-      );
-      if (!delivered) {
-        getLog().error(
-          { nodeId: node.id, workflowRunId },
-          'dag.claude_options_warning_delivery_failed'
-        );
-      }
-    }
+  if (node.systemPrompt !== undefined) baseOptions.systemPrompt = node.systemPrompt;
+  if (node.maxBudgetUsd !== undefined) baseOptions.maxBudgetUsd = node.maxBudgetUsd;
+  const fb = node.fallbackModel ?? workflowLevelOptions.fallbackModel;
+  if (fb) baseOptions.fallbackModel = fb;
+  if (node.output_format) {
+    baseOptions.outputFormat = { type: 'json_schema', schema: node.output_format };
   }
 
-  let options: WorkflowAssistantOptions | undefined;
-  if (provider === 'codex') {
-    options = {
-      model,
-      modelReasoningEffort: config.assistants.codex.modelReasoningEffort,
-      webSearchMode: config.assistants.codex.webSearchMode,
-      additionalDirectories: config.assistants.codex.additionalDirectories,
-    };
-    if (node.output_format) {
-      options.outputFormat = { type: 'json_schema', schema: node.output_format };
-    }
-  } else {
-    const claudeOptions: WorkflowAssistantOptions = {};
-    if (model) claudeOptions.model = model;
-    // Propagate settingSources from config (controls which CLAUDE.md files the SDK loads)
-    if (config.assistants.claude.settingSources) {
-      claudeOptions.settingSources = config.assistants.claude.settingSources;
-    }
-    if (provider === 'claude' && node.output_format) {
-      claudeOptions.outputFormat = {
-        type: 'json_schema',
-        schema: node.output_format,
-      };
-    }
-    if (node.allowed_tools !== undefined) claudeOptions.tools = node.allowed_tools;
-    if (node.denied_tools !== undefined) claudeOptions.disallowedTools = node.denied_tools;
-    if (node.hooks) {
-      const builtHooks = buildSDKHooksFromYAML(node.hooks);
-      if (Object.keys(builtHooks).length > 0) claudeOptions.hooks = builtHooks;
-    }
-    // Load MCP config if specified
-    if (node.mcp) {
-      try {
-        const { servers, serverNames, missingVars } = await loadMcpConfig(node.mcp, cwd);
-        // loadMcpConfig returns Record<string, unknown> from JSON; cast to the structural
-        // union type — the SDK validates server configs at connection time
-        claudeOptions.mcpServers = servers as unknown as WorkflowAssistantOptions['mcpServers'];
-        // Auto-allow all MCP tools via wildcards
-        const mcpWildcards = serverNames.map(name => `mcp__${name}__*`);
-        claudeOptions.allowedTools = [...(claudeOptions.allowedTools ?? []), ...mcpWildcards];
-        getLog().info({ nodeId: node.id, serverNames, mcpPath: node.mcp }, 'dag.mcp_config_loaded');
-        // Warn user about missing env vars (likely secrets that will cause auth failures)
-        if (missingVars.length > 0) {
-          const uniqueVars = [...new Set(missingVars)];
-          getLog().warn({ nodeId: node.id, missingVars: uniqueVars }, 'dag.mcp_env_vars_missing');
-          const delivered = await safeSendMessage(
-            platform,
-            conversationId,
-            `Warning: Node '${node.id}' MCP config references undefined env vars: ${uniqueVars.join(', ')}. These will be empty strings — MCP servers may fail to authenticate.`,
-            { workflowId: workflowRunId, nodeName: node.id }
-          );
-          if (!delivered) {
-            getLog().error(
-              { nodeId: node.id, workflowRunId },
-              'dag.mcp_env_vars_warning_delivery_failed'
-            );
-          }
-        }
-        // Warn if Haiku model is used with MCP (tool search not supported)
-        if (model?.toLowerCase().includes('haiku')) {
-          getLog().warn({ nodeId: node.id, model }, 'dag.mcp_haiku_tool_search_unsupported');
-          const haikuDelivered = await safeSendMessage(
-            platform,
-            conversationId,
-            `Warning: Node '${node.id}' uses Haiku model with MCP servers — tool search (lazy loading for many tools) is not supported on Haiku. Consider using Sonnet or Opus.`,
-            { workflowId: workflowRunId, nodeName: node.id }
-          );
-          if (!haikuDelivered) {
-            getLog().error(
-              { nodeId: node.id, workflowRunId },
-              'dag.mcp_haiku_warning_delivery_failed'
-            );
-          }
-        }
-      } catch (mcpErr) {
-        const errMsg = (mcpErr as Error).message;
-        getLog().error(
-          { nodeId: node.id, mcpPath: node.mcp, error: errMsg },
-          'dag.mcp_config_load_failed'
-        );
-        throw new Error(`Node '${node.id}': ${errMsg}`);
-      }
-    }
-    // Wrap node in AgentDefinition when skills are specified
-    if (node.skills) {
-      const agentId = `dag-node-${node.id}`;
-      // Always include 'Skill' explicitly — SDK behavior for undefined tools is undocumented
-      const agentTools = claudeOptions.tools ? [...claudeOptions.tools, 'Skill'] : ['Skill'];
-      const agentDef: {
-        description: string;
-        prompt: string;
-        skills: string[];
-        tools: string[];
-        model?: string;
-      } = {
-        description: `DAG node '${node.id}'`,
-        prompt: `You have preloaded skills: ${node.skills.join(', ')}. Use them when relevant.`,
-        skills: node.skills,
-        tools: agentTools,
-      };
-      if (claudeOptions.model) agentDef.model = claudeOptions.model;
+  // Build raw nodeConfig — provider translates internally
+  const nodeConfig: NodeConfig = {
+    mcp: node.mcp,
+    hooks: node.hooks,
+    skills: node.skills,
+    agents: node.agents,
+    allowed_tools: node.allowed_tools,
+    denied_tools: node.denied_tools,
+    effort: node.effort ?? workflowLevelOptions.effort,
+    thinking: node.thinking ?? workflowLevelOptions.thinking,
+    sandbox: node.sandbox ?? workflowLevelOptions.sandbox,
+    betas: node.betas ?? workflowLevelOptions.betas,
+    output_format: node.output_format,
+    maxBudgetUsd: node.maxBudgetUsd,
+    systemPrompt: node.systemPrompt,
+    fallbackModel: fb,
+  };
 
-      claudeOptions.agents = { [agentId]: agentDef };
-      claudeOptions.agent = agentId;
-      // Ensure 'Skill' is in allowedTools for the parent session
-      if (!claudeOptions.allowedTools?.includes('Skill')) {
-        claudeOptions.allowedTools = [...(claudeOptions.allowedTools ?? []), 'Skill'];
-      }
-      getLog().info({ nodeId: node.id, skills: node.skills, agentId }, 'dag.skills_agent_created');
-    }
-    // Inject per-project env vars (config file + DB) into subprocess env
-    if (config.envVars && Object.keys(config.envVars).length > 0) {
-      claudeOptions.env = config.envVars;
-    }
+  // Pass assistantConfig from config — provider parses internally
+  const assistantConfig = config.assistants[provider] ?? {};
 
-    // Per-node overrides take precedence over workflow-level defaults; maxBudgetUsd and systemPrompt are per-node only
-    const effort = node.effort ?? workflowLevelOptions.effort;
-    if (effort !== undefined) claudeOptions.effort = effort;
-    const thinking = node.thinking ?? workflowLevelOptions.thinking;
-    if (thinking !== undefined) claudeOptions.thinking = thinking;
-    if (node.maxBudgetUsd !== undefined) claudeOptions.maxBudgetUsd = node.maxBudgetUsd;
-    if (node.systemPrompt !== undefined) claudeOptions.systemPrompt = node.systemPrompt;
-    const fallbackModel = node.fallbackModel ?? workflowLevelOptions.fallbackModel;
-    if (fallbackModel !== undefined) claudeOptions.fallbackModel = fallbackModel;
-    const betas = node.betas ?? workflowLevelOptions.betas;
-    if (betas !== undefined) claudeOptions.betas = betas;
-    const sandbox = node.sandbox ?? workflowLevelOptions.sandbox;
-    if (sandbox !== undefined) claudeOptions.sandbox = sandbox;
-
-    options = Object.keys(claudeOptions).length > 0 ? claudeOptions : undefined;
-  }
+  const options: SendQueryOptions = {
+    ...baseOptions,
+    nodeConfig,
+    assistantConfig,
+  };
 
   return { provider, model, options };
 }
@@ -716,8 +559,8 @@ async function executeNodeInternal(
   cwd: string,
   workflowRun: WorkflowRun,
   node: CommandNode | PromptNode,
-  provider: 'claude' | 'codex',
-  nodeOptions: WorkflowAssistantOptions | undefined,
+  provider: string,
+  nodeOptions: SendQueryOptions | undefined,
   artifactsDir: string,
   logDir: string,
   baseBranch: string,
@@ -730,6 +573,8 @@ async function executeNodeInternal(
   const nodeStartTime = Date.now();
   const nodeContext: SendMessageContext = { workflowId: workflowRun.id, nodeName: node.id };
 
+  const configuredMcpNames = await loadConfiguredMcpServerNames(node.mcp, cwd);
+
   getLog().info({ nodeId: node.id, provider }, 'dag_node_started');
   await logNodeStart(logDir, workflowRun.id, node.id, node.command ?? '<inline>');
 
@@ -819,13 +664,13 @@ async function executeNodeInternal(
   // Substitute upstream node output references
   const finalPrompt = substituteNodeOutputRefs(substitutedPrompt, nodeOutputs);
 
-  const aiClient = deps.getAssistantClient(provider);
+  const aiClient = deps.getAgentProvider(provider);
   const streamingMode = platform.getStreamingMode();
 
   let nodeOutputText = ''; // Always accumulate regardless of streaming mode
   let structuredOutput: unknown;
   let newSessionId: string | undefined;
-  let nodeTokens: WorkflowTokenUsage | undefined;
+  let nodeTokens: TokenUsage | undefined;
   let nodeCostUsd: number | undefined;
   let nodeStopReason: string | undefined;
   let nodeNumTurns: number | undefined;
@@ -836,7 +681,7 @@ async function executeNodeInternal(
   const nodeAbortController = new AbortController();
   // Fork when resuming — leaves the source session untouched so retries are safe.
   const shouldForkSession = resumeSessionId !== undefined;
-  const nodeOptionsWithAbort: WorkflowAssistantOptions | undefined = {
+  const nodeOptionsWithAbort: SendQueryOptions | undefined = {
     ...nodeOptions,
     abortSignal: nodeAbortController.signal,
     ...(shouldForkSession ? { forkSession: true } : {}),
@@ -861,12 +706,19 @@ async function executeNodeInternal(
       const tickNow = Date.now();
       const nodeKey = `${workflowRun.id}:${node.id}`;
 
-      // Cancel/pause check — read-only, no write contention in WAL mode (every 10s)
+      // Cancel/pause check — read-only, no write contention in WAL mode (every 10s).
+      //
+      // `paused` is tolerated here: an approval node can transition the run to
+      // paused while this concurrent node is mid-stream (same topological layer).
+      // The streaming node should be allowed to finish its own output — the
+      // paused gate owns workflow progression, not individual node lifecycles.
+      // Only truly terminal / unknown states (null, cancelled, failed, completed)
+      // abort the in-flight stream.
       if (tickNow - (lastNodeCancelCheck.get(nodeKey) ?? 0) > CANCEL_CHECK_INTERVAL_MS) {
         lastNodeCancelCheck.set(nodeKey, tickNow);
         try {
           const streamStatus = await deps.store.getWorkflowRunStatus(workflowRun.id);
-          if (streamStatus === null || streamStatus !== 'running') {
+          if (!shouldContinueStreamingForStatus(streamStatus)) {
             getLog().info(
               { workflowRunId: workflowRun.id, nodeId: node.id, status: streamStatus ?? 'deleted' },
               'dag.stop_detected_during_streaming'
@@ -897,7 +749,19 @@ async function executeNodeInternal(
 
       if (msg.type === 'assistant' && msg.content) {
         nodeOutputText += msg.content; // ALWAYS capture for $node_id.output
-        if (streamingMode === 'stream') {
+        if (streamingMode === 'stream' || msg.flush) {
+          // `flush` chunks (e.g. Pi notify() emitting a plannotator review URL)
+          // must reach the user before the node blocks. Drain any queued batch
+          // content first so order is preserved.
+          if (streamingMode === 'batch' && batchMessages.length > 0) {
+            await safeSendMessage(
+              platform,
+              conversationId,
+              batchMessages.join('\n\n'),
+              nodeContext
+            );
+            batchMessages.length = 0;
+          }
           await safeSendMessage(platform, conversationId, msg.content, nodeContext);
         } else {
           batchMessages.push(msg.content);
@@ -1024,13 +888,67 @@ async function executeNodeInternal(
             `Node '${node.id}' exceeded cost cap${cap !== undefined ? ` of $${cap.toFixed(2)}` : ''}.`
           );
         }
+        // Fail loudly on any other SDK error result. Previously we broke out of
+        // the stream silently, producing empty/partial output without signaling
+        // failure — which let failed iterations masquerade as successes (#1208).
+        if (msg.isError) {
+          const subtype = msg.errorSubtype ?? 'unknown';
+          const errorsDetail = msg.errors?.length ? ` — ${msg.errors.join('; ')}` : '';
+          getLog().error(
+            {
+              nodeId: node.id,
+              errorSubtype: subtype,
+              errors: msg.errors,
+              sessionId: msg.sessionId,
+              stopReason: msg.stopReason,
+              durationMs: Date.now() - nodeStartTime,
+            },
+            'dag.node_sdk_error_result'
+          );
+          throw new Error(`Node '${node.id}' failed: SDK returned ${subtype}${errorsDetail}`);
+        }
         break; // Result is the "I'm done" signal — don't wait for subprocess to exit
       } else if (msg.type === 'system' && msg.content) {
-        // Surface MCP connection failures to the user
-        if (msg.content.startsWith('MCP server connection failed:')) {
+        // Providers yield system chunks for user-actionable issues (missing env
+        // vars, Haiku+MCP, structured output failures, etc.). MCP-failure
+        // chunks need filtering: user-level plugin MCPs inherited from
+        // `~/.claude/` (e.g. `telegram`) routinely fail to connect inside the
+        // headless subprocess and aren't actionable for the workflow author.
+        // Other warnings (⚠️) are always actionable and surface verbatim.
+        if (msg.content.startsWith(MCP_FAILURE_PREFIX)) {
+          const failedEntries = parseMcpFailureServerNames(msg.content);
+          const workflowFailures = failedEntries.filter(e => configuredMcpNames.has(e.name));
+          const pluginFailures = failedEntries.filter(e => !configuredMcpNames.has(e.name));
+
+          if (workflowFailures.length > 0) {
+            const filteredMsg = `${MCP_FAILURE_PREFIX}${workflowFailures.map(e => e.segment).join(', ')}`;
+            getLog().warn(
+              { nodeId: node.id, systemContent: filteredMsg },
+              'dag.provider_warning_forwarded'
+            );
+            const delivered = await safeSendMessage(
+              platform,
+              conversationId,
+              filteredMsg,
+              nodeContext
+            );
+            if (!delivered) {
+              getLog().error(
+                { nodeId: node.id, workflowRunId: workflowRun.id },
+                'dag.provider_warning_delivery_failed'
+              );
+            }
+          }
+          if (pluginFailures.length > 0) {
+            getLog().debug(
+              { nodeId: node.id, pluginFailures: pluginFailures.map(e => e.name) },
+              'dag.mcp_plugin_connection_suppressed'
+            );
+          }
+        } else if (msg.content.startsWith('⚠️')) {
           getLog().warn(
-            { nodeId: node.id, mcpStatus: msg.content },
-            'dag.mcp_server_connection_failed'
+            { nodeId: node.id, systemContent: msg.content },
+            'dag.provider_warning_forwarded'
           );
           const delivered = await safeSendMessage(
             platform,
@@ -1040,8 +958,8 @@ async function executeNodeInternal(
           );
           if (!delivered) {
             getLog().error(
-              { nodeId: node.id, mcpStatus: msg.content, workflowRunId: workflowRun.id },
-              'dag.mcp_connection_failure_delivery_failed'
+              { nodeId: node.id, workflowRunId: workflowRun.id },
+              'dag.provider_warning_delivery_failed'
             );
           }
         } else {
@@ -1054,8 +972,10 @@ async function executeNodeInternal(
       // rate_limit chunks: already log.warn'd in claude.ts; not surfaced to SSE per design
     }
 
-    // When output_format is set and the SDK returned structured_output,
-    // use it instead of the concatenated assistant text (which includes prose)
+    // When output_format is set and the provider returned structured_output,
+    // use it instead of the concatenated assistant text (which includes prose).
+    // Each provider normalizes its own structured output onto the result chunk —
+    // no provider-specific branching here.
     if (nodeOptions?.outputFormat) {
       if (structuredOutput !== undefined) {
         try {
@@ -1070,26 +990,9 @@ async function executeNodeInternal(
           );
         }
         getLog().debug({ nodeId: node.id, streamingMode }, 'dag.structured_output_override');
-      } else if (provider === 'codex') {
-        // Codex returns structured output inline in agent_message text
-        // (already accumulated in nodeOutputText). Validate it is valid JSON
-        // so downstream $nodeId.output.field references can parse it.
-        try {
-          JSON.parse(nodeOutputText);
-          getLog().debug({ nodeId: node.id }, 'dag.codex_structured_output_valid_json');
-        } catch {
-          getLog().warn(
-            { nodeId: node.id, outputPreview: nodeOutputText.slice(0, 200) },
-            'dag.codex_structured_output_not_json'
-          );
-          await safeSendMessage(
-            platform,
-            conversationId,
-            `Warning: Node '${node.id}' requested output_format but Codex returned non-JSON output. Downstream conditions referencing \`$${node.id}.output.field\` may not evaluate correctly.`,
-            nodeContext
-          );
-        }
       } else {
+        // Provider did not populate structuredOutput — warn the user.
+        // If the provider detected invalid output, it already yielded a system warning.
         getLog().warn(
           { nodeId: node.id, workflowRunId: workflowRun.id },
           'dag.structured_output_missing'
@@ -1097,7 +1000,7 @@ async function executeNodeInternal(
         await safeSendMessage(
           platform,
           conversationId,
-          `Warning: Node '${node.id}' requested output_format but the SDK did not return structured output. Downstream conditions may not evaluate correctly.`,
+          `Warning: Node '${node.id}' requested output_format but the provider did not return structured output. Downstream conditions may not evaluate correctly.`,
           nodeContext
         );
       }
@@ -1314,7 +1217,8 @@ async function executeBashNode(
   baseBranch: string,
   docsDir: string,
   nodeOutputs: Map<string, NodeOutput>,
-  issueContext?: string
+  issueContext?: string,
+  envVars?: Record<string, string>
 ): Promise<NodeOutput> {
   const nodeStartTime = Date.now();
   const nodeContext: SendMessageContext = { workflowId: workflowRun.id, nodeName: node.id };
@@ -1357,11 +1261,14 @@ async function executeBashNode(
   const finalScript = substituteNodeOutputRefs(substitutedScript, nodeOutputs, true);
 
   const timeout = node.timeout ?? SUBPROCESS_DEFAULT_TIMEOUT;
+  const subprocessEnv =
+    envVars && Object.keys(envVars).length > 0 ? { ...process.env, ...envVars } : undefined;
 
   try {
     const { stdout, stderr } = await execFileAsync('bash', ['-c', finalScript], {
       cwd,
       timeout,
+      env: subprocessEnv,
     });
 
     // Trim trailing newline from stdout (common shell behavior)
@@ -1464,7 +1371,8 @@ async function executeScriptNode(
   baseBranch: string,
   docsDir: string,
   nodeOutputs: Map<string, NodeOutput>,
-  issueContext?: string
+  issueContext?: string,
+  envVars?: Record<string, string>
 ): Promise<NodeOutput> {
   const nodeStartTime = Date.now();
   const nodeContext: SendMessageContext = { workflowId: workflowRun.id, nodeName: node.id };
@@ -1507,6 +1415,8 @@ async function executeScriptNode(
   const finalScript = substituteNodeOutputRefs(substitutedScript, nodeOutputs, false);
 
   const timeout = node.timeout ?? SUBPROCESS_DEFAULT_TIMEOUT;
+  const subprocessEnv =
+    envVars && Object.keys(envVars).length > 0 ? { ...process.env, ...envVars } : undefined;
 
   // Build the command and args based on runtime and inline vs named
   let cmd = '';
@@ -1519,7 +1429,10 @@ async function executeScriptNode(
       // Inline code execution
       if (node.runtime === 'bun') {
         cmd = 'bun';
-        args = ['-e', finalScript];
+        // --no-env-file prevents Bun from auto-loading .env from the execution
+        // cwd (the target repo). Without this, repo .env leaks into the script
+        // subprocess despite Archon's parent process cleanup.
+        args = ['--no-env-file', '-e', finalScript];
       } else {
         // uv run --with dep1 --with dep2 python -c <code>
         cmd = 'uv';
@@ -1527,13 +1440,48 @@ async function executeScriptNode(
         args = ['run', ...withFlags, 'python', '-c', finalScript];
       }
     } else {
-      // Named script — look up in .archon/scripts/ directory
-      const scriptsDir = resolve(cwd, '.archon', 'scripts');
-      const scripts = await discoverScripts(scriptsDir);
+      // Named script — look up across repo and home scopes.
+      // Precedence: <cwd>/.archon/scripts/ > ~/.archon/scripts/ (repo wins).
+      // Wrap discovery in its own try/catch so a permission error on ~/.archon/scripts/
+      // isn't mis-attributed by the outer catch's "permission denied (check cwd
+      // permissions)" branch — that branch is for execFileAsync EACCES.
+      let scripts: Awaited<ReturnType<typeof discoverScriptsForCwd>>;
+      try {
+        scripts = await discoverScriptsForCwd(cwd);
+      } catch (discoveryErr) {
+        const err = discoveryErr as Error;
+        const errorMsg = `Script node '${node.id}': failed to discover scripts — ${err.message}`;
+        getLog().error({ err, nodeId: node.id, cwd }, 'script_discovery_failed');
+        await safeSendMessage(platform, conversationId, errorMsg, nodeContext);
+        await logNodeError(logDir, workflowRun.id, node.id, errorMsg);
+
+        emitter.emit({
+          type: 'node_failed',
+          runId: workflowRun.id,
+          nodeId: node.id,
+          nodeName: node.id,
+          error: errorMsg,
+        });
+        deps.store
+          .createWorkflowEvent({
+            workflow_run_id: workflowRun.id,
+            event_type: 'node_failed',
+            step_name: node.id,
+            data: { error: errorMsg, type: 'script' },
+          })
+          .catch((dbErr: Error) => {
+            getLog().error(
+              { err: dbErr, workflowRunId: workflowRun.id, eventType: 'node_failed' },
+              'workflow_event_persist_failed'
+            );
+          });
+
+        return { state: 'failed', output: '', error: errorMsg };
+      }
       const scriptDef = scripts.get(finalScript);
 
       if (!scriptDef) {
-        const errorMsg = `Script node '${node.id}': named script '${finalScript}' not found in .archon/scripts/`;
+        const errorMsg = `Script node '${node.id}': named script '${finalScript}' not found in .archon/scripts/ or ~/.archon/scripts/`;
         getLog().error({ nodeId: node.id, scriptName: finalScript }, 'script_not_found');
         await safeSendMessage(platform, conversationId, errorMsg, nodeContext);
         await logNodeError(logDir, workflowRun.id, node.id, errorMsg);
@@ -1569,13 +1517,14 @@ async function executeScriptNode(
         args = ['run', ...withFlags, scriptDef.path];
       } else {
         cmd = 'bun';
-        args = ['run', scriptDef.path];
+        args = ['--no-env-file', 'run', scriptDef.path];
       }
     }
 
     const { stdout, stderr } = await execFileAsync(cmd, args, {
       cwd,
       timeout,
+      env: subprocessEnv,
     });
 
     // Trim trailing newline from stdout (common shell behavior)
@@ -1663,30 +1612,32 @@ async function executeScriptNode(
 }
 
 /**
- * Build WorkflowAssistantOptions from resolved provider, model, and config.
- * Caller is responsible for resolving per-node overrides before passing model.
+ * Build SendQueryOptions from resolved provider, model, and config.
+ * Uses the same nodeConfig + assistantConfig pattern as resolveNodeProviderAndModel.
  */
 function buildLoopNodeOptions(
-  provider: 'claude' | 'codex',
+  provider: string,
   model: string | undefined,
-  config: WorkflowConfig
-): WorkflowAssistantOptions | undefined {
-  const codexOptions =
-    provider === 'codex'
-      ? {
-          modelReasoningEffort: config.assistants.codex.modelReasoningEffort,
-          webSearchMode: config.assistants.codex.webSearchMode,
-          additionalDirectories: config.assistants.codex.additionalDirectories,
-        }
-      : undefined;
-
-  const claudeOptions =
-    provider === 'claude' && config.assistants.claude.settingSources
-      ? { settingSources: config.assistants.claude.settingSources }
-      : undefined;
-
-  if (!model && !codexOptions && !claudeOptions) return undefined;
-  return { ...(model ? { model } : {}), ...codexOptions, ...claudeOptions };
+  config: WorkflowConfig,
+  workflowLevelOptions?: WorkflowLevelOptions
+): SendQueryOptions {
+  const options: SendQueryOptions = {};
+  if (model) options.model = model;
+  if (config.envVars && Object.keys(config.envVars).length > 0) {
+    options.env = config.envVars;
+  }
+  options.assistantConfig = config.assistants[provider] ?? {};
+  // Pass workflow-level options as nodeConfig so providers can apply them
+  if (workflowLevelOptions) {
+    options.nodeConfig = {
+      effort: workflowLevelOptions.effort,
+      thinking: workflowLevelOptions.thinking,
+      sandbox: workflowLevelOptions.sandbox,
+      betas: workflowLevelOptions.betas,
+      fallbackModel: workflowLevelOptions.fallbackModel,
+    };
+  }
+  return options;
 }
 
 /**
@@ -1704,7 +1655,7 @@ async function executeLoopNode(
   cwd: string,
   workflowRun: WorkflowRun,
   node: LoopNode,
-  workflowProvider: 'claude' | 'codex',
+  workflowProvider: string,
   workflowModel: string | undefined,
   artifactsDir: string,
   logDir: string,
@@ -1712,15 +1663,16 @@ async function executeLoopNode(
   docsDir: string,
   nodeOutputs: Map<string, NodeOutput>,
   config: WorkflowConfig,
-  issueContext?: string
+  issueContext?: string,
+  workflowLevelOptions?: WorkflowLevelOptions
 ): Promise<NodeExecutionResult> {
   const loop = node.loop;
   const msgContext = { workflowId: workflowRun.id, nodeName: node.id };
 
   // Resolve AI client — fail fast with descriptive error
-  let aiClient: ReturnType<typeof deps.getAssistantClient>;
+  let aiClient: ReturnType<typeof deps.getAgentProvider>;
   try {
-    aiClient = deps.getAssistantClient(workflowProvider);
+    aiClient = deps.getAgentProvider(workflowProvider);
   } catch (error) {
     const err = error as Error;
     const errorMsg = `Invalid provider '${workflowProvider}' for loop node '${node.id}'. Check workflow YAML or .archon/config.yaml. Original: ${err.message}`;
@@ -1745,7 +1697,12 @@ async function executeLoopNode(
   let loopTotalCostUsd: number | undefined;
   let loopFinalStopReason: string | undefined;
   let loopTotalNumTurns: number | undefined;
-  const resolvedOptions = buildLoopNodeOptions(workflowProvider, workflowModel, config);
+  const resolvedOptions = buildLoopNodeOptions(
+    workflowProvider,
+    workflowModel,
+    config,
+    workflowLevelOptions
+  );
 
   // Helper to log event store errors consistently
   const logEventStoreError = (err: Error, iteration: number): void => {
@@ -1755,9 +1712,13 @@ async function executeLoopNode(
   for (let i = startIteration; i <= loop.max_iterations; i++) {
     const iterationStart = Date.now();
 
-    // Check for non-running status between iterations (cancellation, deletion, or future: pause)
+    // Check for non-running status between iterations. `paused` is tolerated
+    // here for the same reason as the streaming check: a sibling approval
+    // node in the same topological layer may pause the run while this loop
+    // is between iterations — the loop should continue its own iterations
+    // regardless of unrelated pauses elsewhere in the DAG.
     const runStatus = await deps.store.getWorkflowRunStatus(workflowRun.id);
-    if (runStatus === null || runStatus !== 'running') {
+    if (!shouldContinueStreamingForStatus(runStatus)) {
       const effectiveStatus = runStatus ?? 'deleted';
       getLog().info(
         { workflowRunId: workflowRun.id, nodeId: node.id, iteration: i, status: effectiveStatus },
@@ -1817,7 +1778,7 @@ async function executeLoopNode(
       );
       const finalPrompt = substituteNodeOutputRefs(substitutedPrompt, nodeOutputs);
 
-      const iterationOptions: WorkflowAssistantOptions | undefined = {
+      const iterationOptions: SendQueryOptions | undefined = {
         ...resolvedOptions,
         abortSignal: iterationAbortController.signal,
       };
@@ -1837,7 +1798,7 @@ async function executeLoopNode(
       })) {
         if (msg.type === 'assistant') {
           fullOutput += msg.content;
-          const cleaned = stripCompletionTags(msg.content);
+          const cleaned = stripCompletionTags(msg.content, loop.until);
           cleanOutput += cleaned;
           if (platform.getStreamingMode() === 'stream' && cleaned) {
             await safeSendMessage(platform, conversationId, cleaned, msgContext);
@@ -1877,6 +1838,28 @@ async function executeLoopNode(
           if (msg.numTurns !== undefined) {
             loopTotalNumTurns = (loopTotalNumTurns ?? 0) + msg.numTurns;
           }
+          // Fail the iteration loudly on SDK error results. Previously we broke
+          // silently, producing empty output and continuing to the next iteration —
+          // which made `error_during_execution` on resumed interactive loops look
+          // like a "5-second crash" that kept burning iterations (#1208).
+          if (msg.isError) {
+            const subtype = msg.errorSubtype ?? 'unknown';
+            const errorsDetail = msg.errors?.length ? ` — ${msg.errors.join('; ')}` : '';
+            getLog().error(
+              {
+                nodeId: node.id,
+                iteration: i,
+                errorSubtype: subtype,
+                errors: msg.errors,
+                sessionId: msg.sessionId,
+                stopReason: msg.stopReason,
+              },
+              'loop_node.iteration_sdk_error'
+            );
+            throw new Error(
+              `Loop '${node.id}' iteration ${String(i)} failed: SDK returned ${subtype}${errorsDetail}`
+            );
+          }
           break; // Result is the "I'm done" signal — don't wait for subprocess to exit
         } else if (msg.type === 'tool' && msg.toolName) {
           const now = Date.now();
@@ -2194,7 +2177,7 @@ async function executeApprovalNode(
   deps: WorkflowDeps,
   platform: IWorkflowPlatform,
   conversationId: string,
-  workflowProvider: 'claude' | 'codex',
+  workflowProvider: string,
   workflowModel: string | undefined,
   cwd: string,
   artifactsDir: string,
@@ -2364,7 +2347,7 @@ export async function executeDagWorkflow(
   cwd: string,
   workflow: { name: string; nodes: readonly DagNode[] } & WorkflowLevelOptions,
   workflowRun: WorkflowRun,
-  workflowProvider: 'claude' | 'codex',
+  workflowProvider: string,
   workflowModel: string | undefined,
   artifactsDir: string,
   logDir: string,
@@ -2593,7 +2576,8 @@ export async function executeDagWorkflow(
               baseBranch,
               docsDir,
               nodeOutputs,
-              issueContext
+              issueContext,
+              config.envVars
             );
             return { nodeId: node.id, output };
           }
@@ -2601,21 +2585,14 @@ export async function executeDagWorkflow(
           // 3b. Loop node dispatch — manages its own AI sessions and iteration
           if (isLoopNode(node)) {
             // Resolve per-node provider/model overrides (same logic as other node types)
-            let loopProvider: 'claude' | 'codex';
-            if (node.provider) {
-              loopProvider = node.provider;
-            } else if (node.model && isClaudeModel(node.model)) {
-              loopProvider = 'claude';
-            } else if (node.model) {
-              loopProvider = 'codex';
-            } else {
-              loopProvider = workflowProvider;
-            }
-            const loopModel =
+            const loopProvider: string =
+              node.provider ?? inferProviderFromModel(node.model, workflowProvider);
+            const loopAssistantConfig = config.assistants[loopProvider];
+            const loopModel: string | undefined =
               node.model ??
               (loopProvider === workflowProvider
                 ? workflowModel
-                : config.assistants[loopProvider]?.model);
+                : (loopAssistantConfig?.model as string | undefined));
 
             if (!isModelCompatible(loopProvider, loopModel)) {
               return {
@@ -2643,7 +2620,8 @@ export async function executeDagWorkflow(
               docsDir,
               nodeOutputs,
               config,
-              issueContext
+              issueContext,
+              workflowLevelOptions
             );
             return { nodeId: node.id, output };
           }
@@ -2718,7 +2696,8 @@ export async function executeDagWorkflow(
               baseBranch,
               docsDir,
               nodeOutputs,
-              issueContext
+              issueContext,
+              config.envVars
             );
             return { nodeId: node.id, output };
           }
@@ -2908,15 +2887,24 @@ export async function executeDagWorkflow(
     }
   }
 
-  // Helper: bail out if the run was transitioned externally (cancelled, deleted, etc.)
+  /**
+   * Bail out of the final completion/failure write if the run was transitioned
+   * externally. Strict `!== 'running'` check is correct here because we don't
+   * want to mark a paused run as complete — the approval gate is still live.
+   *
+   * Emitter unregister is conditional: terminal states (cancelled / deleted /
+   * completed / failed) unregister to release subscription resources, but
+   * `paused` keeps the emitter registered so SSE stays connected while the
+   * approval gate awaits the user — crucial for resume observability.
+   */
   async function skipIfStatusChanged(logEvent: string): Promise<boolean> {
     const status = await deps.store.getWorkflowRunStatus(workflowRun.id);
-    if (status === null || status !== 'running') {
-      getLog().info({ workflowRunId: workflowRun.id, status: status ?? 'deleted' }, logEvent);
+    if (status === 'running') return false;
+    getLog().info({ workflowRunId: workflowRun.id, status: status ?? 'deleted' }, logEvent);
+    if (status !== 'paused') {
       getWorkflowEventEmitter().unregisterRun(workflowRun.id);
-      return true;
     }
-    return false;
+    return true;
   }
 
   // Single-pass: compute node outcome counts and derive success/failure booleans
@@ -2966,16 +2954,34 @@ export async function executeDagWorkflow(
   }
 
   if (anyFailed) {
+    if (await skipIfStatusChanged('dag.skip_fail_status_changed')) return;
     const failedNodes = [...nodeOutputs.entries()]
       .filter(([, o]) => o.state === 'failed')
       .map(([id, o]) => `'${id}': ${o.state === 'failed' ? o.error : 'unknown'}`)
       .join('; ');
-    await safeSendMessage(
-      platform,
-      conversationId,
-      `\u26a0\ufe0f Some DAG nodes failed: ${failedNodes}\nSuccessful nodes completed normally.`,
-      { workflowId: workflowRun.id }
-    );
+    const failMsg = `DAG workflow '${workflow.name}' completed with failures: ${failedNodes}`;
+    await deps.store.failWorkflowRun(workflowRun.id, failMsg).catch((dbErr: Error) => {
+      getLog().error({ err: dbErr, workflowRunId: workflowRun.id }, 'dag_db_fail_failed');
+    });
+    await logWorkflowError(logDir, workflowRun.id, failMsg).catch((logErr: Error) => {
+      getLog().error(
+        { err: logErr, workflowRunId: workflowRun.id },
+        'dag.workflow_error_log_write_failed'
+      );
+    });
+    const emitterForFail = getWorkflowEventEmitter();
+    emitterForFail.emit({
+      type: 'workflow_failed',
+      runId: workflowRun.id,
+      workflowName: workflow.name,
+      error: failMsg,
+    });
+    emitterForFail.unregisterRun(workflowRun.id);
+    await safeSendMessage(platform, conversationId, `\u274c ${failMsg}`, {
+      workflowId: workflowRun.id,
+    });
+    // DO NOT throw — outer executor.ts catch would duplicate workflow_failed events
+    return;
   }
 
   // Check if status was changed externally (e.g. cancelled) before marking complete.
diff --git a/packages/workflows/src/defaults/bundled-defaults.generated.ts b/packages/workflows/src/defaults/bundled-defaults.generated.ts
new file mode 100644
index 0000000000..cd430f3d5a
--- /dev/null
+++ b/packages/workflows/src/defaults/bundled-defaults.generated.ts
@@ -0,0 +1,78 @@
+/**
+ * AUTO-GENERATED — DO NOT EDIT.
+ *
+ * Regenerate with: bun run generate:bundled
+ * Verify up-to-date:  bun run check:bundled
+ *
+ * Source of truth:
+ *   .archon/commands/defaults/*.md
+ *   .archon/workflows/defaults/*.{yaml,yml}
+ *
+ * Contents are inlined as plain string literals (JSON-escaped) so this
+ * module loads in both Bun and Node. Previous versions used
+ * `import X from '...' with { type: 'text' }` which is Bun-specific.
+ */
+
+// Bundled default commands (36 total)
+export const BUNDLED_COMMANDS: Record<string, string> = {
+  "archon-assist": "---\ndescription: General assistance - questions, debugging, one-off tasks, exploration\nargument-hint: <any request>\n---\n\n# Assist Mode\n\n**Request**: $ARGUMENTS\n\n---\n\nYou are helping with a request that didn't match a specific workflow.\n\n## Instructions\n\n1. **Understand the request** - What is the user actually asking for?\n2. **Take action** - Use your full Claude Code capabilities to help\n3. **Be helpful** - Answer questions, debug issues, explore code, make changes\n4. **Note the gap** - If this should have been a specific workflow, mention it:\n   \"Note: Using assist mode. Consider creating a workflow for this use case.\"\n\n## Capabilities\n\nYou have full Claude Code capabilities:\n- Read and write files\n- Run commands\n- Search the codebase\n- Make code changes\n- Answer questions\n\n## Request\n\n$ARGUMENTS\n",
+  "archon-auto-fix-review": "---\ndescription: Auto-fix all review findings unless clear YAGNI violations, post fix report\nargument-hint: (none - reads all review artifacts from $ARTIFACTS_DIR/review/)\n---\n\n# Auto-Fix Review Findings\n\n---\n\n## IMPORTANT: Output Behavior\n\n**Your output will be posted as a GitHub comment.** Keep working output minimal:\n- Do NOT narrate each step\n- Do NOT output verbose progress updates\n- Only output the final structured report at the end\n- Use the TodoWrite tool to track progress silently\n\n---\n\n## Your Mission\n\nRead all review artifacts produced in this workflow run and fix everything surfaced — unless a finding is a clear YAGNI violation or speculative over-engineering beyond the scope of the original fix. Validate, commit, push, write an artifact, and post a GitHub comment explaining what was fixed and why anything was skipped.\n\n**Output artifact**: `$ARTIFACTS_DIR/review/fix-report.md`\n**Git action**: Commit AND push fixes to the PR branch\n**GitHub action**: Post fix report as a comment on the PR\n\n---\n\n## Phase 1: LOAD — Get Context\n\n### 1.1 Get PR Number and Branch\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number)\nHEAD_BRANCH=$(gh pr view $PR_NUMBER --json headRefName --jq '.headRefName')\necho \"PR: $PR_NUMBER, Branch: $HEAD_BRANCH\"\n```\n\n### 1.2 Checkout PR Branch\n\n**Always re-checkout to ensure you are on the right branch.**\n\n```bash\ngit fetch origin $HEAD_BRANCH\ngit checkout $HEAD_BRANCH\ngit pull origin $HEAD_BRANCH\n```\n\nVerify:\n\n```bash\ngit branch --show-current\ngit status --porcelain\n```\n\n### 1.3 Read All Review Artifacts\n\nDiscover whatever review artifacts exist — there may be one or many depending on which review agents ran:\n\n```bash\nls $ARTIFACTS_DIR/review/\n```\n\nRead each `.md` file that looks like a findings artifact (e.g. `code-review-findings.md`, `error-handling-findings.md`, `test-coverage-findings.md`, `docs-impact-findings.md`, `consolidated-review.md`). Skip non-findings files like `scope.md` and `fix-report.md`.\n\n```bash\nfor f in $ARTIFACTS_DIR/review/*.md; do\n  echo \"=== $f ===\"; cat \"$f\"; echo\ndone\n```\n\n### 1.4 Extract Findings\n\nFrom all loaded artifacts, compile a unified list of all findings with their severity, location, and suggested fix.\n\n**PHASE_1_CHECKPOINT:**\n- [ ] PR number and branch identified\n- [ ] On correct PR branch\n- [ ] All review artifacts read\n- [ ] All findings extracted\n\n---\n\n## Phase 2: TRIAGE — Decide What to Fix\n\nFor each finding, decide: **FIX** or **SKIP**.\n\n### Fix if:\n- It is a real bug, type error, silent failure, or clear code quality issue\n- The fix is concrete and low-risk\n\n### Skip (YAGNI / out-of-scope) if the finding recommends:\n- Adding something not required to fix the original issue (new config options, new abstractions, speculative fallbacks, \"what if\" edge cases)\n- Refactoring or restructuring code that isn't broken\n- Adding validation for inputs that cannot actually be invalid in this context\n- Extracting utilities or helpers for code that currently has only one caller\n- Architectural changes that touch code well outside the PR's scope\n\nUse judgment — don't be overly restrictive. If it's a legitimate bug the reviewer found, fix it even if it's adjacent to the PR. If it's clearly speculative (\"this might be useful someday\"), skip it.\n\nFor each skipped finding, write down **the specific reason** — this goes in the report.\n\n**PHASE_2_CHECKPOINT:**\n- [ ] Every finding marked FIX or SKIP\n- [ ] Skip reasons documented\n\n---\n\n## Phase 3: IMPLEMENT — Apply Fixes\n\n### 3.1 For Each Finding Marked FIX\n\n1. Read the relevant file(s)\n2. Apply the fix following the suggested approach from the review artifact\n3. Run type-check after each fix: `bun run type-check`\n4. Note exactly what was changed\n\n### 3.2 Handle Unfixable Findings\n\nIf a fix cannot be applied (code changed since review, fix is ambiguous, fix would break other things), mark it as **BLOCKED** and document why. Do not force a broken fix.\n\n### 3.3 Add Tests for Fixed Code\n\nIf the review flagged missing test coverage for something you just fixed, add a targeted test. Run it:\n\n```bash\nbun test {file}\n```\n\n**PHASE_3_CHECKPOINT:**\n- [ ] All FIX findings attempted\n- [ ] Tests added where flagged\n- [ ] BLOCKED findings documented\n\n---\n\n## Phase 4: VALIDATE — Full Check\n\n```bash\nbun run type-check\nbun run lint\nbun test\n```\n\nAll must pass. If something fails after a fix:\n1. Review the error\n2. Adjust the fix or revert it and mark BLOCKED\n3. Re-run until clean\n\n**PHASE_4_CHECKPOINT:**\n- [ ] Type check passes\n- [ ] Lint passes\n- [ ] Tests pass\n\n---\n\n## Phase 5: COMMIT AND PUSH\n\n### 5.1 Stage and Commit\n\nOnly stage files you actually changed:\n\n```bash\ngit add {specific files}\ngit status\ngit commit -m \"fix: address review findings\n\n$(echo \"Fixed:\"; echo \"- {brief list}\")\n$(echo \"\"; echo \"Skipped (YAGNI/out-of-scope):\"; echo \"- {brief list if any}\")\"\n```\n\n### 5.2 Push\n\n```bash\ngit push origin $HEAD_BRANCH\n```\n\nIf push fails due to divergence:\n\n```bash\ngit pull --rebase origin $HEAD_BRANCH\ngit push origin $HEAD_BRANCH\n```\n\n**PHASE_5_CHECKPOINT:**\n- [ ] Changes committed\n- [ ] Pushed to PR branch\n\n---\n\n## Phase 6: GENERATE — Write Fix Report\n\nWrite to `$ARTIFACTS_DIR/review/fix-report.md`:\n\n```markdown\n# Fix Report: PR #{number}\n\n**Date**: {ISO timestamp}\n**Status**: COMPLETE | PARTIAL\n**Branch**: {HEAD_BRANCH}\n**Commit**: {commit hash}\n\n---\n\n## Summary\n\n{2-3 sentences covering what was found, what was fixed, what was skipped and why}\n\n---\n\n## Fixes Applied\n\n| Severity | Finding | Location | What Was Done |\n|----------|---------|----------|---------------|\n| CRITICAL | {title} | `file:line` | {description} |\n| HIGH     | {title} | `file:line` | {description} |\n\n---\n\n## Skipped Findings\n\n| Severity | Finding | Location | Reason Skipped |\n|----------|---------|----------|----------------|\n| HIGH     | {title} | `file:line` | YAGNI: {specific reason} |\n| MEDIUM   | {title} | `file:line` | Out of scope: {reason} |\n\n---\n\n## Tests Added\n\n| File | Test Cases |\n|------|------------|\n| `{file}.test.ts` | `{test description}` |\n\n*(none)* if no tests were added\n\n---\n\n## Blocked (Could Not Fix)\n\n| Severity | Finding | Reason |\n|----------|---------|--------|\n| {sev}    | {title} | {why it could not be applied} |\n\n*(none)* if nothing was blocked\n\n---\n\n## Validation\n\n| Check | Status |\n|-------|--------|\n| Type check | ✅ / ❌ |\n| Lint | ✅ / ❌ |\n| Tests | ✅ {n} passed / ❌ |\n```\n\n**PHASE_6_CHECKPOINT:**\n- [ ] Fix report written\n\n---\n\n## Phase 7: POST — GitHub Comment\n\nPost the fix report as a PR comment:\n\n```bash\ngh pr comment $PR_NUMBER --body \"$(cat <<'EOF'\n## ⚡ Auto-Fix Report\n\n**Status**: {COMPLETE | PARTIAL}\n**Pushed**: ✅ Changes pushed to `{HEAD_BRANCH}`\n\n---\n\n### Fixes Applied\n\n| Severity | Finding | Location |\n|----------|---------|----------|\n| 🔴 CRITICAL | {title} | `file:line` |\n| 🟠 HIGH | {title} | `file:line` |\n\n*(none)* if nothing was fixed\n\n---\n\n### Skipped\n\n| Severity | Finding | Reason |\n|----------|---------|--------|\n| 🟠 HIGH | {title} | {reason — YAGNI, out of scope, blocked} |\n\n*(none)* if nothing was skipped\n\n---\n\n### Tests Added\n\n{List or \"(none)\"}\n\n---\n\n### Validation\n\n✅ Type check | ✅ Lint | ✅ Tests ({n} passed)\n\n---\n\n*Auto-fix by Archon · fixes pushed to `{HEAD_BRANCH}`*\nEOF\n)\"\n```\n\n**PHASE_7_CHECKPOINT:**\n- [ ] GitHub comment posted\n\n---\n\n## Phase 8: OUTPUT — Final Summary\n\nOutput only this:\n\n```\n## ⚡ Auto-Fix Complete\n\n**PR**: #{number}\n**Branch**: {HEAD_BRANCH}\n**Status**: COMPLETE | PARTIAL\n\nFixed: {n}\nSkipped: {n} (YAGNI/out-of-scope)\nBlocked: {n}\n\nValidation: ✅ All checks pass\nPushed: ✅\n\nFix report: $ARTIFACTS_DIR/review/fix-report.md\n```\n\n---\n\n## Error Handling\n\n### Type check fails after a fix\n1. Review the error\n2. Adjust or revert the fix\n3. If still failing after a reasonable attempt, mark BLOCKED\n\n### Tests fail\n1. Check whether the fix caused it or it was pre-existing\n2. Fix the test if the fix is correct\n3. If unclear, mark BLOCKED — do not ship broken tests\n\n### Push fails\n1. `git pull --rebase origin $HEAD_BRANCH`\n2. Resolve conflicts if any\n3. Push again\n\n### No review artifacts found\n```\n❌ No review artifacts found in $ARTIFACTS_DIR/review/\nCannot proceed without findings.\n```\n\n---\n\n## Success Criteria\n\n- **ON_CORRECT_BRANCH**: Working on PR's head branch\n- **ALL_FINDINGS_ADDRESSED**: Every finding is either fixed, skipped (with reason), or blocked (with reason)\n- **VALIDATION_PASSED**: Type check, lint, and tests all pass\n- **COMMITTED_AND_PUSHED**: Changes committed and pushed to PR branch\n- **REPORTED**: Fix report artifact written and GitHub comment posted\n",
+  "archon-code-review-agent": "---\ndescription: Review code quality, CLAUDE.md compliance, and detect bugs\nargument-hint: (none - reads from scope artifact)\n---\n\n# Code Review Agent\n\n---\n\n## Your Mission\n\nReview the PR for code quality, CLAUDE.md compliance, patterns, and bugs. Produce a structured artifact with findings, fix suggestions with multiple options, and reasoning.\n\n**Output artifact**: `$ARTIFACTS_DIR/review/code-review-findings.md`\n\n---\n\n## Phase 1: LOAD - Get Context\n\n### 1.1 Get PR Number from Registry\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number)\n```\n\n### 1.2 Read Scope\n\n```bash\ncat $ARTIFACTS_DIR/review/scope.md\n```\n\nNote:\n- Changed files list\n- CLAUDE.md rules to check\n- Focus areas\n\n**CRITICAL**: Check for \"NOT Building (Scope Limits)\" section. Items listed there are **intentionally excluded** - do NOT flag them as bugs or missing features!\n\n### 1.3 Get PR Diff\n\n```bash\ngh pr diff {number}\n```\n\n### 1.4 Read CLAUDE.md\n\n```bash\ncat CLAUDE.md\n```\n\nNote all coding standards, patterns, and rules.\n\n**PHASE_1_CHECKPOINT:**\n- [ ] PR number identified\n- [ ] Scope loaded\n- [ ] Diff available\n- [ ] CLAUDE.md rules noted\n\n---\n\n## Phase 2: ANALYZE - Review Code\n\n### 2.1 Check CLAUDE.md Compliance\n\nFor each changed file, verify:\n- Import patterns match project style\n- Naming conventions followed\n- Error handling patterns correct\n- Type annotations complete\n- Testing patterns followed\n\n### 2.2 Detect Bugs\n\nLook for:\n- Logic errors\n- Null/undefined handling issues\n- Race conditions\n- Memory leaks\n- Security vulnerabilities\n- Off-by-one errors\n- Missing error handling\n\n### 2.3 Check Code Quality\n\nEvaluate:\n- Code duplication\n- Function complexity\n- Proper abstractions\n- Clear naming\n- Appropriate comments\n\n### 2.4 Pattern Matching\n\nFor each issue found, search codebase for correct patterns:\n\n```bash\n# Find similar patterns in codebase\ngrep -r \"pattern\" src/ --include=\"*.ts\" | head -5\n```\n\n### 2.5 Check for Primitive Duplication\n\nFor each new interface, class, type alias, or utility module introduced in the diff:\n\n1. Search for similar existing abstractions:\n\n```bash\n# Replace {Name} with the new abstraction's name\ngrep -r \"interface {Name}\\|class {Name}\\|type {Name}\" packages/ --include=\"*.ts\" | head -10\n```\n\n2. Flag if the new abstraction duplicates or closely overlaps an existing one.\n3. Flag if a new utility function reimplements logic already available in a shared package.\n4. Note findings in the CLAUDE.md Compliance section with verdict: **EXTENDS** (extends existing primitive) or **DUPLICATE** (redundant with existing) or **NEW** (genuinely new, no existing primitive).\n\n**PHASE_2_CHECKPOINT:**\n- [ ] CLAUDE.md compliance checked\n- [ ] Bugs identified\n- [ ] Quality issues noted\n- [ ] Patterns found for fixes\n- [ ] Primitive duplication checked\n\n---\n\n## Phase 3: GENERATE - Create Artifact\n\nWrite to `$ARTIFACTS_DIR/review/code-review-findings.md`:\n\n```markdown\n# Code Review Findings: PR #{number}\n\n**Reviewer**: code-review-agent\n**Date**: {ISO timestamp}\n**Files Reviewed**: {count}\n\n---\n\n## Summary\n\n{2-3 sentence overview of code quality and main concerns}\n\n**Verdict**: {APPROVE | REQUEST_CHANGES | NEEDS_DISCUSSION}\n\n---\n\n## Findings\n\n### Finding 1: {Descriptive Title}\n\n**Severity**: CRITICAL | HIGH | MEDIUM | LOW\n**Category**: bug | style | performance | security | pattern-violation\n**Location**: `{file}:{line}`\n\n**Issue**:\n{Clear description of what's wrong}\n\n**Evidence**:\n```typescript\n// Current code at {file}:{line}\n{problematic code snippet}\n```\n\n**Why This Matters**:\n{Explain the impact - what could go wrong, why it violates standards}\n\n---\n\n#### Fix Suggestions\n\n| Option | Approach | Pros | Cons |\n|--------|----------|------|------|\n| A | {approach description} | {benefits} | {drawbacks} |\n| B | {alternative approach} | {benefits} | {drawbacks} |\n\n**Recommended**: Option {A/B}\n\n**Reasoning**:\n{Explain why this option is preferred, referencing:\n- Codebase patterns\n- CLAUDE.md rules\n- Best practices\n- Specific project context}\n\n**Recommended Fix**:\n```typescript\n// Suggested fix\n{corrected code}\n```\n\n**Codebase Pattern Reference**:\n```typescript\n// SOURCE: {file}:{lines}\n// This pattern shows how similar code is handled elsewhere\n{existing code from codebase}\n```\n\n---\n\n### Finding 2: {Title}\n\n{Same structure...}\n\n---\n\n## Statistics\n\n| Severity | Count | Auto-fixable |\n|----------|-------|--------------|\n| CRITICAL | {n} | {n} |\n| HIGH | {n} | {n} |\n| MEDIUM | {n} | {n} |\n| LOW | {n} | {n} |\n\n---\n\n## CLAUDE.md Compliance\n\n| Rule | Status | Notes |\n|------|--------|-------|\n| {rule from CLAUDE.md} | PASS/FAIL | {details} |\n| ... | ... | ... |\n\n---\n\n## Patterns Referenced\n\n| File | Lines | Pattern |\n|------|-------|---------|\n| `src/example.ts` | 42-50 | {what this pattern demonstrates} |\n| ... | ... | ... |\n\n---\n\n## Positive Observations\n\n{List things done well - good patterns, clean code, etc.}\n\n---\n\n## Metadata\n\n- **Agent**: code-review-agent\n- **Timestamp**: {ISO timestamp}\n- **Artifact**: `$ARTIFACTS_DIR/review/code-review-findings.md`\n```\n\n**PHASE_3_CHECKPOINT:**\n- [ ] Artifact file created\n- [ ] All findings have severity and location\n- [ ] Fix options provided with reasoning\n- [ ] Codebase patterns referenced\n\n---\n\n## Phase 4: VALIDATE - Check Artifact\n\n### 4.1 Verify File Exists\n\n```bash\ncat $ARTIFACTS_DIR/review/code-review-findings.md | head -20\n```\n\n### 4.2 Check Structure\n\nVerify artifact contains:\n- Summary with verdict\n- At least findings section (even if empty)\n- Statistics table\n- CLAUDE.md compliance table\n\n**PHASE_4_CHECKPOINT:**\n- [ ] Artifact file exists\n- [ ] Structure is complete\n- [ ] No placeholder text remaining\n\n---\n\n## Success Criteria\n\n- **CONTEXT_LOADED**: Scope and diff read successfully\n- **ANALYSIS_COMPLETE**: All changed files reviewed\n- **ARTIFACT_CREATED**: Findings file written\n- **PATTERNS_INCLUDED**: Each finding references codebase patterns\n- **OPTIONS_PROVIDED**: Multiple fix options where applicable\n",
+  "archon-comment-quality-agent": "---\ndescription: Review code comments for accuracy, completeness, and maintainability\nargument-hint: (none - reads from scope artifact)\n---\n\n# Comment Quality Agent\n\n---\n\n## Your Mission\n\nAnalyze code comments for accuracy against actual code, identify comment rot, check documentation completeness, and ensure comments aid long-term maintainability. Produce a structured artifact with findings and recommendations.\n\n**Output artifact**: `$ARTIFACTS_DIR/review/comment-quality-findings.md`\n\n---\n\n## Phase 1: LOAD - Get Context\n\n### 1.1 Get PR Number from Registry\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number)\n```\n\n### 1.2 Read Scope\n\n```bash\ncat $ARTIFACTS_DIR/review/scope.md\n```\n\n**CRITICAL**: Check for \"NOT Building (Scope Limits)\" section. Items listed there are **intentionally excluded** - do NOT flag them as missing documentation or comment issues!\n\n### 1.3 Get PR Diff\n\n```bash\ngh pr diff {number}\n```\n\nFocus on:\n- New comments added\n- Comments near modified code\n- JSDoc/docstrings added or changed\n\n**PHASE_1_CHECKPOINT:**\n- [ ] PR number identified\n- [ ] Changed files with comments identified\n- [ ] Diff available\n\n---\n\n## Phase 2: ANALYZE - Review Comments\n\n### 2.1 Check Comment Accuracy\n\nFor each comment in changed code:\n- Does the comment accurately describe what the code does?\n- Is the comment up-to-date with the implementation?\n- Are parameter descriptions correct?\n- Are return value descriptions accurate?\n- Are edge cases documented correctly?\n\n### 2.2 Identify Comment Rot\n\nLook for:\n- Comments that describe old behavior\n- TODO/FIXME that should have been addressed\n- Outdated references (old file names, removed functions)\n- Comments that contradict the code\n\n### 2.3 Check Documentation Completeness\n\nEvaluate:\n- Are complex functions properly documented?\n- Are public APIs documented?\n- Are non-obvious algorithms explained?\n- Are magic numbers/constants explained?\n- Are important decisions documented?\n\n### 2.4 Assess Maintainability\n\nConsider:\n- Will future developers understand the \"why\"?\n- Are there redundant comments (just restating code)?\n- Is the signal-to-noise ratio good?\n- Are comments in the right places?\n\n**PHASE_2_CHECKPOINT:**\n- [ ] Comment accuracy verified\n- [ ] Comment rot identified\n- [ ] Completeness gaps found\n- [ ] Maintainability assessed\n\n---\n\n## Phase 3: GENERATE - Create Artifact\n\nWrite to `$ARTIFACTS_DIR/review/comment-quality-findings.md`:\n\n```markdown\n# Comment Quality Findings: PR #{number}\n\n**Reviewer**: comment-quality-agent\n**Date**: {ISO timestamp}\n**Comments Reviewed**: {count}\n\n---\n\n## Summary\n\n{2-3 sentence overview of comment quality}\n\n**Verdict**: {APPROVE | REQUEST_CHANGES | NEEDS_DISCUSSION}\n\n---\n\n## Findings\n\n### Finding 1: {Descriptive Title}\n\n**Severity**: CRITICAL | HIGH | MEDIUM | LOW\n**Category**: inaccurate | outdated | missing | redundant | misleading\n**Location**: `{file}:{line}`\n\n**Issue**:\n{Clear description of the comment problem}\n\n**Current Comment**:\n```typescript\n// {the problematic comment}\n{code the comment describes}\n```\n\n**Actual Code Behavior**:\n{What the code actually does vs what comment says}\n\n**Impact**:\n{How this could mislead future developers}\n\n---\n\n#### Fix Suggestions\n\n| Option | Approach | Pros | Cons |\n|--------|----------|------|------|\n| A | {update comment} | {benefits} | {drawbacks} |\n| B | {remove comment} | {benefits} | {drawbacks} |\n| C | {expand comment} | {benefits} | {drawbacks} |\n\n**Recommended**: Option {X}\n\n**Reasoning**:\n{Why this option:\n- Matches documentation standards\n- Provides value without being redundant\n- Will remain accurate over time}\n\n**Recommended Fix**:\n```typescript\n/**\n * {corrected/improved comment}\n *\n * @param {type} param - {accurate description}\n * @returns {type} - {accurate description}\n */\n{code}\n```\n\n**Good Comment Pattern**:\n```typescript\n// SOURCE: {file}:{lines}\n// Example of good documentation in this codebase\n{existing well-documented code}\n```\n\n---\n\n### Finding 2: {Title}\n\n{Same structure...}\n\n---\n\n## Comment Audit\n\n| Location | Type | Accurate | Up-to-date | Useful | Verdict |\n|----------|------|----------|------------|--------|---------|\n| `file:line` | JSDoc | YES/NO | YES/NO | YES/NO | GOOD/UPDATE/REMOVE |\n| ... | ... | ... | ... | ... | ... |\n\n---\n\n## Statistics\n\n| Severity | Count | Auto-fixable |\n|----------|-------|--------------|\n| CRITICAL | {n} | {n} |\n| HIGH | {n} | {n} |\n| MEDIUM | {n} | {n} |\n| LOW | {n} | {n} |\n\n---\n\n## Documentation Gaps\n\n| Code Area | What's Missing | Priority |\n|-----------|----------------|----------|\n| `function xyz()` | Parameter docs, return type | HIGH |\n| `class Abc` | Class purpose, usage example | MEDIUM |\n| ... | ... | ... |\n\n---\n\n## Comment Rot Found\n\n| Location | Comment Says | Code Does | Age |\n|----------|--------------|-----------|-----|\n| `file:line` | \"{old description}\" | {actual behavior} | {when introduced} |\n| ... | ... | ... | ... |\n\n---\n\n## Positive Observations\n\n{Well-documented code, helpful comments, good explanations}\n\n---\n\n## Metadata\n\n- **Agent**: comment-quality-agent\n- **Timestamp**: {ISO timestamp}\n- **Artifact**: `$ARTIFACTS_DIR/review/comment-quality-findings.md`\n```\n\n**PHASE_3_CHECKPOINT:**\n- [ ] Artifact file created\n- [ ] Comment accuracy verified\n- [ ] Comment rot documented\n- [ ] Documentation gaps listed\n\n---\n\n## Success Criteria\n\n- **COMMENTS_AUDITED**: All comments in changed code reviewed\n- **ACCURACY_CHECKED**: Comments verified against actual code\n- **ROT_IDENTIFIED**: Outdated comments found\n- **GAPS_DOCUMENTED**: Missing documentation noted\n",
+  "archon-confirm-plan": "---\ndescription: Verify plan research is still valid - check patterns exist, code hasn't drifted\nargument-hint: (no arguments - reads from workflow artifacts)\n---\n\n# Confirm Plan Research\n\n**Workflow ID**: $WORKFLOW_ID\n\n---\n\n## Your Mission\n\nVerify that the plan's research is still valid before implementation begins.\n\nPlans can become stale:\n- Files may have been renamed or moved\n- Code patterns may have changed\n- APIs may have been updated\n\n**This step does NOT implement anything** - it only validates the plan is still accurate.\n\n---\n\n## Phase 1: LOAD - Read Context Artifact\n\n### 1.1 Load Plan Context\n\n```bash\ncat $ARTIFACTS_DIR/plan-context.md\n```\n\nIf not found, STOP with error:\n```\n❌ Plan context not found at $ARTIFACTS_DIR/plan-context.md\n\nRun archon-plan-setup first.\n```\n\n### 1.2 Extract Verification Targets\n\nFrom the context, identify:\n\n1. **Patterns to Mirror** - Files and line ranges to verify\n2. **Files to Change** - Files that will be created/updated\n3. **Validation Commands** - Commands that should work\n\n**PHASE_1_CHECKPOINT:**\n\n- [ ] Context artifact loaded\n- [ ] Patterns to verify extracted\n- [ ] Files to change identified\n\n---\n\n## Phase 2: VERIFY - Check Patterns Exist\n\n### 2.1 Verify Pattern Files\n\nFor each file in \"Patterns to Mirror\":\n\n1. Check if file exists:\n   ```bash\n   test -f {file-path} && echo \"EXISTS\" || echo \"MISSING\"\n   ```\n\n2. If exists, read the referenced lines:\n   ```bash\n   sed -n '{start},{end}p' {file-path}\n   ```\n\n3. Compare with what the plan expected (if plan included code snippets)\n\n### 2.2 Document Findings\n\nFor each pattern file:\n\n| File | Status | Notes |\n|------|--------|-------|\n| `src/adapters/telegram.ts` | ✅ EXISTS | Lines 11-23 match expected pattern |\n| `src/types/index.ts` | ✅ EXISTS | Interface still present |\n| `src/old-file.ts` | ❌ MISSING | File was renamed/deleted |\n| `src/changed.ts` | ⚠️ DRIFTED | Code structure changed significantly |\n\n### 2.3 Severity Assessment\n\n| Finding | Severity | Action |\n|---------|----------|--------|\n| File exists, code matches | ✅ OK | Proceed |\n| File exists, minor differences | ⚠️ WARNING | Note in artifact, proceed with caution |\n| File exists, major drift | 🟠 CONCERN | Flag for review, may need plan update |\n| File missing | ❌ BLOCKER | Stop, plan needs revision |\n\n**PHASE_2_CHECKPOINT:**\n\n- [ ] All pattern files checked\n- [ ] Findings documented\n- [ ] Severity assessed\n\n---\n\n## Phase 3: VERIFY - Check Target Locations\n\n### 3.1 Check Files to Create\n\nFor each file marked CREATE:\n\n1. Verify it doesn't already exist (would be unexpected):\n   ```bash\n   test -f {file-path} && echo \"ALREADY EXISTS\" || echo \"OK - will create\"\n   ```\n\n2. Verify parent directory exists or can be created:\n   ```bash\n   dirname {file-path} | xargs test -d && echo \"DIR EXISTS\" || echo \"DIR WILL BE CREATED\"\n   ```\n\n### 3.2 Check Files to Update\n\nFor each file marked UPDATE:\n\n1. Verify it exists:\n   ```bash\n   test -f {file-path} && echo \"EXISTS\" || echo \"MISSING\"\n   ```\n\n2. If the plan references specific lines/functions, verify they exist\n\n**PHASE_3_CHECKPOINT:**\n\n- [ ] CREATE targets verified (don't exist yet)\n- [ ] UPDATE targets verified (do exist)\n\n---\n\n## Phase 4: VERIFY - Check Validation Commands\n\n### 4.1 Dry Run Validation Commands\n\nTest that the validation commands work (without expecting them to pass):\n\n```bash\n# Check type-check command exists\nbun run type-check --help 2>/dev/null || echo \"type-check not available\"\n\n# Check lint command exists\nbun run lint --help 2>/dev/null || echo \"lint not available\"\n\n# Check test command exists\nbun test --help 2>/dev/null || echo \"test not available\"\n```\n\n### 4.2 Document Command Availability\n\n| Command | Status |\n|---------|--------|\n| `bun run type-check` | ✅ Available |\n| `bun run lint` | ✅ Available |\n| `bun test` | ✅ Available |\n| `bun run build` | ✅ Available |\n\n**PHASE_4_CHECKPOINT:**\n\n- [ ] Validation commands tested\n- [ ] All required commands available\n\n---\n\n## Phase 5: ARTIFACT - Write Confirmation\n\n### 5.1 Write Confirmation Artifact\n\nWrite to `$ARTIFACTS_DIR/plan-confirmation.md`:\n\n```markdown\n# Plan Confirmation\n\n**Generated**: {YYYY-MM-DD HH:MM}\n**Workflow ID**: $WORKFLOW_ID\n**Status**: {CONFIRMED | WARNINGS | BLOCKED}\n\n---\n\n## Pattern Verification\n\n| Pattern | File | Status | Notes |\n|---------|------|--------|-------|\n| Constructor pattern | `src/adapters/telegram.ts:11-23` | ✅ | Matches expected |\n| Interface definition | `src/types/index.ts:49-74` | ✅ | Present |\n| ... | ... | ... | ... |\n\n**Pattern Summary**: {X} of {Y} patterns verified\n\n---\n\n## Target Files\n\n### Files to Create\n\n| File | Status |\n|------|--------|\n| `src/new-file.ts` | ✅ Does not exist (ready to create) |\n\n### Files to Update\n\n| File | Status |\n|------|--------|\n| `src/existing.ts` | ✅ Exists |\n\n---\n\n## Validation Commands\n\n| Command | Available |\n|---------|-----------|\n| `bun run type-check` | ✅ |\n| `bun run lint` | ✅ |\n| `bun test` | ✅ |\n| `bun run build` | ✅ |\n\n---\n\n## Issues Found\n\n{If no issues:}\nNo issues found. Plan research is valid.\n\n{If issues:}\n### Warnings\n\n- **{file}**: {description of drift or concern}\n\n### Blockers\n\n- **{file}**: {description of missing file or critical issue}\n\n---\n\n## Recommendation\n\n{One of:}\n- ✅ **PROCEED**: Plan research is valid, continue to implementation\n- ⚠️ **PROCEED WITH CAUTION**: Minor drift detected, implementation may need adjustments\n- ❌ **STOP**: Critical issues found, plan needs revision\n\n---\n\n## Next Step\n\n{If PROCEED or PROCEED WITH CAUTION:}\nContinue to `archon-implement-tasks` to execute the plan.\n\n{If STOP:}\nRevise the plan to address blockers, then re-run `archon-plan-setup`.\n```\n\n**PHASE_5_CHECKPOINT:**\n\n- [ ] Confirmation artifact written\n- [ ] Status clearly indicated\n- [ ] Issues documented\n\n---\n\n## Phase 6: OUTPUT - Report to User\n\n### If Confirmed (no blockers):\n\n```markdown\n## Plan Confirmed ✅\n\n**Workflow ID**: `$WORKFLOW_ID`\n**Status**: Ready for implementation\n\n### Verification Summary\n\n| Check | Result |\n|-------|--------|\n| Pattern files | ✅ {X}/{Y} verified |\n| Target files | ✅ Ready |\n| Validation commands | ✅ Available |\n\n{If warnings:}\n### Warnings\n\n- {warning 1}\n- {warning 2}\n\nThese are minor and shouldn't block implementation.\n\n### Artifact\n\nConfirmation written to: `$ARTIFACTS_DIR/plan-confirmation.md`\n\n### Next Step\n\nProceed to `archon-implement-tasks` to execute the plan.\n```\n\n### If Blocked:\n\n```markdown\n## Plan Blocked ❌\n\n**Workflow ID**: `$WORKFLOW_ID`\n**Status**: Cannot proceed\n\n### Blockers Found\n\n1. **{file}**: {description}\n2. **{file}**: {description}\n\n### Required Action\n\nThe plan references files or patterns that no longer exist. Options:\n\n1. **Update the plan** to reflect current codebase state\n2. **Restore missing files** if they were accidentally deleted\n3. **Re-run planning** with `/archon-plan` to generate a fresh plan\n\n### Artifact\n\nDetails written to: `$ARTIFACTS_DIR/plan-confirmation.md`\n```\n\n---\n\n## Success Criteria\n\n- **PATTERNS_VERIFIED**: All pattern files exist and are reasonably similar\n- **TARGETS_VALID**: CREATE files don't exist, UPDATE files do exist\n- **COMMANDS_AVAILABLE**: Validation commands can be run\n- **ARTIFACT_WRITTEN**: Confirmation artifact created with clear status\n",
+  "archon-create-plan": "---\ndescription: Create comprehensive feature implementation plan with codebase analysis and research\nargument-hint: <feature description | path/to/prd.md>\n---\n\n# Create Implementation Plan\n\n**Input**: $ARGUMENTS\n**Workflow ID**: $WORKFLOW_ID\n\n---\n\n## Your Mission\n\nTransform \"$ARGUMENTS\" into a battle-tested implementation plan through systematic codebase exploration, pattern extraction, and strategic research.\n\n**Core Principle**: PLAN ONLY - no code written. Create a context-rich document that enables one-pass implementation success.\n\n**Execution Order**: CODEBASE FIRST, RESEARCH SECOND. Solutions must fit existing patterns before introducing new ones.\n\n**Agent Strategy**: Use Task tool with subagent_type=\"Explore\" for codebase intelligence gathering. This ensures thorough pattern discovery before any external research.\n\n**Output**: `$ARTIFACTS_DIR/plan.md`\n\n---\n\n## Phase 0: DETECT - Input Type Resolution\n\n### 0.1 Determine Input Type\n\n| Input Pattern | Type | Action |\n|---------------|------|--------|\n| Ends with `.prd.md` | PRD file | Parse PRD, select next phase |\n| Ends with `.md` and contains \"Implementation Phases\" | PRD file | Parse PRD, select next phase |\n| File path that exists | Document | Read and extract feature description |\n| Free-form text | Description | Use directly as feature input |\n| Empty/blank | Error | STOP - require input |\n\n### 0.2 If PRD File Detected\n\n1. **Read the PRD file**\n2. **Parse the Implementation Phases table** - find rows with `Status: pending`\n3. **Check dependencies** - only select phases whose dependencies are `complete`\n4. **Select the next actionable phase:**\n   - First pending phase with all dependencies complete\n   - If multiple candidates with same dependencies, note parallelism opportunity\n\n5. **Extract phase context:**\n   ```\n   PHASE: {phase number and name}\n   GOAL: {from phase details}\n   SCOPE: {from phase details}\n   SUCCESS SIGNAL: {from phase details}\n   PRD CONTEXT: {problem statement, user, hypothesis from PRD}\n   ```\n\n6. **Report selection to user:**\n   ```\n   PRD: {prd file path}\n   Selected Phase: #{number} - {name}\n\n   {If parallel phases available:}\n   Note: Phase {X} can also run in parallel (in separate worktree).\n\n   Proceeding with Phase #{number}...\n   ```\n\n### 0.3 If Free-form Description\n\nProceed directly to Phase 1 with the input as feature description.\n\n**PHASE_0_CHECKPOINT:**\n\n- [ ] Input type determined\n- [ ] If PRD: next phase selected and dependencies verified\n- [ ] Feature description ready for Phase 1\n\n---\n\n## Phase 1: PARSE - Feature Understanding\n\n### 1.1 Discover Project Structure\n\n**CRITICAL**: Do NOT assume `src/` exists. Discover actual structure:\n\n```bash\n# List root contents\nls -la\n\n# Find main source directories\nls -la */ 2>/dev/null | head -50\n\n# Identify project type from config files\ncat package.json 2>/dev/null | head -20\ncat pyproject.toml 2>/dev/null | head -20\ncat Cargo.toml 2>/dev/null | head -20\ncat go.mod 2>/dev/null | head -20\n```\n\nCommon alternatives to `src/`:\n- `app/` (Next.js, Rails, Laravel)\n- `lib/` (Ruby gems, Elixir)\n- `packages/` (monorepos)\n- `cmd/`, `internal/`, `pkg/` (Go)\n- Root-level source files (Python, scripts)\n\n### 1.2 Read CLAUDE.md\n\n```bash\ncat CLAUDE.md\n```\n\nNote all coding standards, patterns, and rules that apply to this codebase.\n\n### 1.3 Extract from Input\n\n- Core problem being solved\n- User value and business impact\n- Feature type: NEW_CAPABILITY | ENHANCEMENT | REFACTOR | BUG_FIX\n- Complexity: LOW | MEDIUM | HIGH\n- Affected systems list\n\n### 1.4 Formulate User Story\n\n```\nAs a <user type>\nI want to <action/goal>\nSo that <benefit/value>\n```\n\n**PHASE_1_CHECKPOINT:**\n\n- [ ] Project structure discovered\n- [ ] CLAUDE.md rules noted\n- [ ] Problem statement is specific and testable\n- [ ] User story follows correct format\n- [ ] Complexity assessment has rationale\n- [ ] Affected systems identified\n\n**GATE**: If requirements are AMBIGUOUS → STOP and ASK user for clarification before proceeding.\n\n---\n\n## Phase 2: EXPLORE - Codebase Intelligence\n\n**CRITICAL: Use Task tool with subagent_type=\"Explore\" with thoroughness=\"very thorough\"**\n\n### 2.1 Launch Explore Agent\n\n```\nExplore the codebase to find patterns, conventions, and integration points\nrelevant to implementing: [feature description].\n\nDISCOVER:\n1. Similar implementations - find analogous features with file:line references\n2. Naming conventions - extract actual examples of function/class/file naming\n3. Error handling patterns - how errors are created, thrown, caught\n4. Logging patterns - logger usage, message formats\n5. Type definitions - relevant interfaces and types\n6. Test patterns - test file structure, assertion styles\n7. Integration points - where new code connects to existing\n8. Dependencies - relevant libraries already in use\n\nReturn ACTUAL code snippets from codebase, not generic examples.\n```\n\n### 2.2 Document Discoveries\n\n**Format in table:**\n\n| Category | File:Lines | Pattern Description | Code Snippet |\n|----------|------------|---------------------|--------------|\n| NAMING | `src/features/X/service.ts:10-15` | camelCase functions | `export function createThing()` |\n| ERRORS | `src/features/X/errors.ts:5-20` | Custom error classes | `class ThingNotFoundError` |\n| LOGGING | `src/core/logging/index.ts:1-10` | getLogger pattern | `const logger = getLogger(\"domain\")` |\n| TESTS | `src/features/X/tests/service.test.ts:1-30` | describe/it blocks | `describe(\"service\", () => {` |\n| TYPES | `src/features/X/models.ts:1-20` | Type inference | `type Thing = typeof things.$inferSelect` |\n\n**PHASE_2_CHECKPOINT:**\n\n- [ ] Explore agent launched and completed successfully\n- [ ] At least 3 similar implementations found with file:line refs\n- [ ] Code snippets are ACTUAL (copy-pasted from codebase, not invented)\n- [ ] Integration points mapped with specific file paths\n- [ ] Dependencies cataloged with versions from package.json\n\n---\n\n## Phase 3: RESEARCH - External Documentation\n\n**ONLY AFTER Phase 2 is complete** - solutions must fit existing codebase patterns first.\n\n### 3.1 Search for Documentation\n\nUse WebSearch tool for:\n- Official documentation for involved libraries (match versions from package.json)\n- Known gotchas, breaking changes, deprecations\n- Security considerations and best practices\n- Performance optimization patterns\n\n### 3.2 Format References\n\n```markdown\n- [Library Docs v{version}](https://url#specific-section)\n  - KEY_INSIGHT: {what we learned that affects implementation}\n  - APPLIES_TO: {which task/file this affects}\n  - GOTCHA: {potential pitfall and how to avoid}\n```\n\n**PHASE_3_CHECKPOINT:**\n\n- [ ] Documentation versions match package.json\n- [ ] URLs include specific section anchors (not just homepage)\n- [ ] Gotchas documented with mitigation strategies\n- [ ] No conflicting patterns between external docs and existing codebase\n\n---\n\n## Phase 4: DESIGN - UX Transformation\n\n### 4.1 Create ASCII Diagrams\n\n**Before State:**\n\n```\n╔═══════════════════════════════════════════════════════════════════════════════╗\n║                              BEFORE STATE                                      ║\n╠═══════════════════════════════════════════════════════════════════════════════╣\n║                                                                               ║\n║   ┌─────────────┐         ┌─────────────┐         ┌─────────────┐            ║\n║   │   Screen/   │ ──────► │   Action    │ ──────► │   Result    │            ║\n║   │  Component  │         │   Current   │         │   Current   │            ║\n║   └─────────────┘         └─────────────┘         └─────────────┘            ║\n║                                                                               ║\n║   USER_FLOW: [describe current step-by-step experience]                       ║\n║   PAIN_POINT: [what's missing, broken, or inefficient]                        ║\n║   DATA_FLOW: [how data moves through the system currently]                    ║\n║                                                                               ║\n╚═══════════════════════════════════════════════════════════════════════════════╝\n```\n\n**After State:**\n\n```\n╔═══════════════════════════════════════════════════════════════════════════════╗\n║                               AFTER STATE                                      ║\n╠═══════════════════════════════════════════════════════════════════════════════╣\n║                                                                               ║\n║   ┌─────────────┐         ┌─────────────┐         ┌─────────────┐            ║\n║   │   Screen/   │ ──────► │   Action    │ ──────► │   Result    │            ║\n║   │  Component  │         │    NEW      │         │    NEW      │            ║\n║   └─────────────┘         └─────────────┘         └─────────────┘            ║\n║                                   │                                           ║\n║                                   ▼                                           ║\n║                          ┌─────────────┐                                      ║\n║                          │ NEW_FEATURE │  ◄── [new capability added]          ║\n║                          └─────────────┘                                      ║\n║                                                                               ║\n║   USER_FLOW: [describe new step-by-step experience]                           ║\n║   VALUE_ADD: [what user gains from this change]                               ║\n║   DATA_FLOW: [how data moves through the system after]                        ║\n║                                                                               ║\n╚═══════════════════════════════════════════════════════════════════════════════╝\n```\n\n### 4.2 Document Interaction Changes\n\n| Location | Before | After | User_Action | Impact |\n|----------|--------|-------|-------------|--------|\n| `/route` | State A | State B | Click X | Can now Y |\n| `Component.tsx` | Missing feature | Has feature | Input Z | Gets result W |\n\n**PHASE_4_CHECKPOINT:**\n\n- [ ] Before state accurately reflects current system behavior\n- [ ] After state shows ALL new capabilities\n- [ ] Data flows are traceable from input to output\n- [ ] User value is explicit and measurable\n\n---\n\n## Phase 5: ARCHITECT - Strategic Design\n\n### 5.0 Primitives Inventory\n\nBefore designing the solution, audit existing building blocks:\n\n1. **What primitives already exist?** List the core abstractions in the codebase\n   related to this feature — with file:line references from the Explore agent output.\n2. **Are they complete?** Do the existing primitives cover this use case, or do they\n   have gaps that require extension?\n3. **Extend before adding** — can we extend an existing primitive rather than creating\n   a new one? Prefer `implements ExistingInterface` over `interface NewInterface`.\n4. **Minimum primitive surface** — if new primitives ARE needed, what's the smallest\n   addition that enables this feature and remains useful to future callers?\n5. **Dependency chain** — what must exist first? What does this feature unlock downstream?\n\n| Primitive | File:Lines | Complete? | Role in Feature |\n|-----------|-----------|-----------|----------------|\n| {name} | `path/to/file.ts:10-30` | Yes/Partial/No | {how it's used or extended} |\n\n### 5.1 Deep Analysis\n\nConsider (use extended thinking if needed):\n\n- **ARCHITECTURE_FIT**: How does this integrate with the existing architecture?\n- **EXECUTION_ORDER**: What must happen first → second → third?\n- **FAILURE_MODES**: Edge cases, race conditions, error scenarios?\n- **PERFORMANCE**: Will this scale? Database queries optimized?\n- **SECURITY**: Attack vectors? Data exposure risks? Auth/authz?\n- **MAINTAINABILITY**: Will future devs understand this code?\n\n### 5.2 Document Decisions\n\n```markdown\nAPPROACH_CHOSEN: [description]\nRATIONALE: [why this over alternatives - reference codebase patterns]\n\nALTERNATIVES_REJECTED:\n- [Alternative 1]: Rejected because [specific reason]\n- [Alternative 2]: Rejected because [specific reason]\n\nNOT_BUILDING (explicit scope limits):\n- [Item 1 - explicitly out of scope and why]\n- [Item 2 - explicitly out of scope and why]\n```\n\n**PHASE_5_CHECKPOINT:**\n\n- [ ] Approach aligns with existing architecture and patterns\n- [ ] Dependencies ordered correctly (types → repository → service → routes)\n- [ ] Edge cases identified with specific mitigation strategies\n- [ ] Scope boundaries are explicit and justified\n\n---\n\n## Phase 6: GENERATE - Write Plan File\n\n### 6.1 Create Artifact Directory\n\n```bash\n```\n\n### 6.2 Write Plan\n\nWrite to `$ARTIFACTS_DIR/plan.md`:\n\n```markdown\n# Feature: {Feature Name}\n\n## Summary\n\n{One paragraph: What we're building and high-level approach}\n\n## User Story\n\nAs a {user type}\nI want to {action}\nSo that {benefit}\n\n## Problem Statement\n\n{Specific problem this solves - must be testable}\n\n## Solution Statement\n\n{How we're solving it - architecture overview}\n\n## Metadata\n\n| Field | Value |\n|-------|-------|\n| Type | NEW_CAPABILITY / ENHANCEMENT / REFACTOR / BUG_FIX |\n| Complexity | LOW / MEDIUM / HIGH |\n| Systems Affected | {comma-separated list} |\n| Dependencies | {external libs/services with versions} |\n| Estimated Tasks | {count} |\n\n---\n\n## UX Design\n\n### Before State\n\n{ASCII diagram - current user experience with data flows}\n\n### After State\n\n{ASCII diagram - new user experience with data flows}\n\n### Interaction Changes\n\n| Location | Before | After | User Impact |\n|----------|--------|-------|-------------|\n| {path/component} | {old behavior} | {new behavior} | {what changes for user} |\n\n---\n\n## Mandatory Reading\n\n**CRITICAL: Implementation agent MUST read these files before starting any task:**\n\n| Priority | File | Lines | Why Read This |\n|----------|------|-------|---------------|\n| P0 | `path/to/critical.ts` | 10-50 | Pattern to MIRROR exactly |\n| P1 | `path/to/types.ts` | 1-30 | Types to IMPORT |\n| P2 | `path/to/test.ts` | all | Test pattern to FOLLOW |\n\n**External Documentation:**\n\n| Source | Section | Why Needed |\n|--------|---------|------------|\n| [Lib Docs v{version}](url#anchor) | {section name} | {specific reason} |\n\n---\n\n## Patterns to Mirror\n\n**NAMING_CONVENTION:**\n```typescript\n// SOURCE: {file:lines}\n// COPY THIS PATTERN:\n{actual code snippet from codebase}\n```\n\n**ERROR_HANDLING:**\n```typescript\n// SOURCE: {file:lines}\n// COPY THIS PATTERN:\n{actual code snippet from codebase}\n```\n\n**LOGGING_PATTERN:**\n```typescript\n// SOURCE: {file:lines}\n// COPY THIS PATTERN:\n{actual code snippet from codebase}\n```\n\n**TEST_STRUCTURE:**\n```typescript\n// SOURCE: {file:lines}\n// COPY THIS PATTERN:\n{actual code snippet from codebase}\n```\n\n---\n\n## Files to Change\n\n| File | Action | Justification |\n|------|--------|---------------|\n| `src/features/new/models.ts` | CREATE | Type definitions |\n| `src/features/new/service.ts` | CREATE | Business logic |\n| `src/existing/index.ts` | UPDATE | Add integration |\n\n---\n\n## NOT Building (Scope Limits)\n\nExplicit exclusions to prevent scope creep:\n\n- {Item 1 - explicitly out of scope and why}\n- {Item 2 - explicitly out of scope and why}\n\n---\n\n## Step-by-Step Tasks\n\nExecute in order. Each task is atomic and independently verifiable.\n\n### Task 1: {CREATE/UPDATE} `{file path}`\n\n- **ACTION**: {CREATE new file / UPDATE existing file}\n- **IMPLEMENT**: {specific what to implement}\n- **MIRROR**: `{source-file:lines}` - follow this pattern exactly\n- **IMPORTS**: `{specific imports needed}`\n- **GOTCHA**: {known issue to avoid}\n- **VALIDATE**: `{validation-command}` - must pass before next task\n\n### Task 2: {CREATE/UPDATE} `{file path}`\n\n{... repeat for each task ...}\n\n---\n\n## Testing Strategy\n\n### Unit Tests to Write\n\n| Test File | Test Cases | Validates |\n|-----------|------------|-----------|\n| `src/features/new/tests/service.test.ts` | CRUD ops, edge cases | Business logic |\n\n### Edge Cases Checklist\n\n- [ ] Empty string inputs\n- [ ] Missing required fields\n- [ ] Unauthorized access attempts\n- [ ] Not found scenarios\n- [ ] {feature-specific edge case}\n\n---\n\n## Validation Commands\n\n### Level 1: STATIC_ANALYSIS\n\n```bash\n{runner} run type-check && {runner} run lint\n```\n\n**EXPECT**: Exit 0, no errors or warnings\n\n### Level 2: UNIT_TESTS\n\n```bash\n{runner} test {path/to/feature/tests}\n```\n\n**EXPECT**: All tests pass\n\n### Level 3: FULL_SUITE\n\n```bash\n{runner} run validate\n```\n\n**EXPECT**: All tests pass, build succeeds\n\n---\n\n## Acceptance Criteria\n\n- [ ] All specified functionality implemented per user story\n- [ ] Level 1-3 validation commands pass with exit 0\n- [ ] Code mirrors existing patterns exactly (naming, structure, logging)\n- [ ] No regressions in existing tests\n- [ ] UX matches \"After State\" diagram\n\n---\n\n## Completion Checklist\n\n- [ ] All tasks completed in dependency order\n- [ ] Each task validated immediately after completion\n- [ ] All acceptance criteria met\n\n---\n\n## Risks and Mitigations\n\n| Risk | Likelihood | Impact | Mitigation |\n|------|------------|--------|------------|\n| {Risk description} | LOW/MED/HIGH | LOW/MED/HIGH | {Specific prevention/handling strategy} |\n\n---\n\n## Notes\n\n{Additional context, design decisions, trade-offs, future considerations}\n```\n\n### 6.3 If Input Was PRD\n\nAlso update the PRD file:\n1. Change the phase's Status from `pending` to `in-progress`\n2. Add the plan file path to the PRP Plan column\n\n**PHASE_6_CHECKPOINT:**\n\n- [ ] Plan file written to `$ARTIFACTS_DIR/plan.md`\n- [ ] All sections populated with actual codebase data\n- [ ] If PRD: source file updated\n\n---\n\n## Phase 7: VERIFY - Plan Quality Check\n\n### 7.1 Context Completeness\n\n- [ ] All patterns from Explore agent documented with file:line references\n- [ ] External docs versioned to match package.json\n- [ ] Integration points mapped with specific file paths\n- [ ] Gotchas captured with mitigation strategies\n- [ ] Every task has at least one executable validation command\n\n### 7.2 Implementation Readiness\n\n- [ ] Tasks ordered by dependency (can execute top-to-bottom)\n- [ ] Each task is atomic and independently testable\n- [ ] No placeholders - all content is specific and actionable\n- [ ] Pattern references include actual code snippets (copy-pasted, not invented)\n\n### 7.3 Pattern Faithfulness\n\n- [ ] Every new file mirrors existing codebase style exactly\n- [ ] No unnecessary abstractions introduced\n- [ ] Naming follows discovered conventions\n- [ ] Error/logging patterns match existing\n- [ ] Test structure matches existing tests\n\n### 7.4 No Prior Knowledge Test\n\n**Could an agent unfamiliar with this codebase implement using ONLY the plan?**\n\nIf NO → add missing context to plan.\n\n**PHASE_7_CHECKPOINT:**\n\n- [ ] All verification checks pass\n- [ ] Plan is self-contained\n\n---\n\n## Phase 8: OUTPUT - Report to User\n\n```markdown\n## Plan Created\n\n**File**: `$ARTIFACTS_DIR/plan.md`\n**Workflow ID**: `$WORKFLOW_ID`\n\n{If from PRD:}\n**Source PRD**: `{prd-file-path}`\n**Phase**: #{number} - {phase name}\n**PRD Updated**: Status set to `in-progress`, plan linked\n\n{If parallel phases available:}\n**Parallel Opportunity**: Phase {X} can run concurrently in a separate worktree.\n\n---\n\n### Summary\n\n{2-3 sentence feature overview}\n\n### Metadata\n\n| Field | Value |\n|-------|-------|\n| Complexity | {LOW/MEDIUM/HIGH} |\n| Files to CREATE | {N} |\n| Files to UPDATE | {M} |\n| Total Tasks | {K} |\n\n### Key Patterns Discovered\n\n- {Pattern 1 from Explore agent with file:line}\n- {Pattern 2 from Explore agent with file:line}\n- {Pattern 3 from Explore agent with file:line}\n\n### External Research\n\n- {Key doc 1 with version}\n- {Key doc 2 with version}\n\n### UX Transformation\n\n- **BEFORE**: {one-line current state}\n- **AFTER**: {one-line new state}\n\n### Risks\n\n- {Primary risk}: {mitigation}\n\n### Confidence Score\n\n**{1-10}/10** for one-pass implementation success\n\n{Rationale for score}\n\n---\n\n### Next Step\n\nPlan ready. Proceeding to implementation setup.\n```\n\n---\n\n## Success Criteria\n\n- **CONTEXT_COMPLETE**: All patterns, gotchas, integration points documented from actual codebase via Explore agent\n- **IMPLEMENTATION_READY**: Tasks executable top-to-bottom without questions, research, or clarification\n- **PATTERN_FAITHFUL**: Every new file mirrors existing codebase style exactly\n- **VALIDATION_DEFINED**: Every task has executable verification command\n- **UX_DOCUMENTED**: Before/After transformation is visually clear with data flows\n- **ONE_PASS_TARGET**: Confidence score 8+ indicates high likelihood of first-attempt success\n- **ARTIFACT_WRITTEN**: Plan saved to `$ARTIFACTS_DIR/plan.md`\n",
+  "archon-create-pr": "---\ndescription: Create a PR from current branch with implementation context\nargument-hint: [base-branch] (default: auto-detected from config or repo)\n---\n\n# Create Pull Request\n\n**Base branch override**: $ARGUMENTS\n**Default base branch**: $BASE_BRANCH\n\n> If a base branch was provided as argument above, use it for `--base`. Otherwise use the default base branch.\n\n---\n\n## Pre-flight: Check for Existing PRs\n\nExtract the issue number from the current branch name or context (e.g., `fix/issue-580` → `580`).\n\n```bash\nBRANCH=$(git branch --show-current)\nISSUE_NUM=$(echo \"$BRANCH\" | grep -oE '[0-9]+' | tail -1)\n```\n\nIf an issue number was found, search for open PRs that already reference it:\n\n```bash\ngh pr list \\\n  --search \"Fixes #${ISSUE_NUM} OR Closes #${ISSUE_NUM}\" \\\n  --state open \\\n  --json number,url,headRefName\n```\n\n**If a matching PR is returned**: stop here, report the existing PR URL, and do **not** proceed to Phase 2 or Phase 3.\n\n```\nExisting PR found for issue #${ISSUE_NUM}: [url]\nSkipping PR creation.\n```\n\n**If no match is found** (or no issue number could be extracted): continue to Phase 1.\n\n---\n\n## Phase 1: Gather Context\n\n### 1.1 Check Git State\n\n```bash\ngit branch --show-current\ngit status --short\ngit log origin/$BASE_BRANCH..HEAD --oneline\n```\n\n### 1.2 Check for Implementation Report\n\nLook for the most recent implementation report:\n\n```bash\nls -t $ARTIFACTS_DIR/../reports/*-report.md 2>/dev/null | head -1\n```\n\nIf found, read it to extract:\n- Summary of what was implemented\n- Files changed\n- Validation results\n- Any deviations from plan\n\n### 1.3 Get Commit Summary\n\n```bash\ngit log origin/$BASE_BRANCH..HEAD --pretty=format:\"- %s\"\n```\n\n---\n\n## Phase 2: Prepare Branch\n\n### 2.1 Ensure All Changes Committed\n\nIf uncommitted changes exist:\n\n```bash\ngit status --porcelain\n```\n\n**If dirty**:\n1. Stage changes: `git add -A`\n2. Commit: `git commit -m \"Final changes before PR\"`\n\n### 2.2 Push Branch\n\n```bash\ngit push -u origin HEAD\n```\n\n---\n\n## Phase 3: Create PR\n\n### 3.1 Check for PR Template\n\nLook for the project's PR template at `.github/pull_request_template.md`, `.github/PULL_REQUEST_TEMPLATE.md`, or `docs/PULL_REQUEST_TEMPLATE.md`. Read whichever one exists.\n\n**If template found**: Use it as the structure, fill in **every section** with details from the implementation report and commits. Don't skip sections or leave placeholders.\n\n**If no template**, use this format:\n\n```markdown\n## Summary\n\n[Brief description from implementation report or commits]\n\n## Changes\n\n[List from implementation report \"Files Changed\" section, or from commits]\n- file1.ts - description\n- file2.ts - description\n\n## Validation\n\n[From implementation report \"Validation Results\" section]\n- [x] Type check passes\n- [x] Lint passes\n- [x] Tests pass\n- [x] Build succeeds\n\n## Testing Notes\n\n[Any manual testing done or integration test results]\n\n---\n\n[If from a GitHub issue, add: Closes #XXX]\n```\n\n### 3.2 Determine PR Title\n\n**Title**: Concise, imperative mood\n- From implementation report summary, OR\n- From commit messages\n\n### 3.3 Create the PR\n\n```bash\n# Write body to file to avoid shell escaping\ncat > $ARTIFACTS_DIR/pr-body.md <<'EOF'\n[body from above]\nEOF\n\ngh pr create \\\n  --title \"[title]\" \\\n  --body-file $ARTIFACTS_DIR/pr-body.md \\\n  --base $BASE_BRANCH\n```\n\nOr if the content is simple:\n\n```bash\ngh pr create --fill --base $BASE_BRANCH\n```\n\nAfter creating the PR, capture its identifiers for downstream steps. Only write artifacts if PR creation succeeded — never persist stale data from a pre-existing PR:\n\n```bash\n# After creating the PR, capture and persist the PR number for downstream steps\n# IMPORTANT: Only write artifacts after confirmed successful PR creation\nif gh pr view --json number,url -q '.number,.url' > /dev/null 2>&1; then\n  PR_NUMBER=$(gh pr view --json number -q '.number')\n  PR_URL=$(gh pr view --json url -q '.url')\n  echo \"$PR_NUMBER\" > \"$ARTIFACTS_DIR/.pr-number\"\n  echo \"$PR_URL\" > \"$ARTIFACTS_DIR/.pr-url\"\nelse\n  echo \"WARNING: Could not confirm PR creation; skipping .pr-number/.pr-url artifacts\"\nfi\n```\n\n---\n\n## Phase 4: Output\n\nReport the result:\n\n```markdown\n## PR Created\n\n**URL**: [PR URL]\n**Branch**: [branch-name] → [base-branch]\n**Title**: [PR title]\n\n### Summary\n[Brief summary of what the PR contains]\n\n### Next Steps\n1. Request review if needed\n2. Address any CI failures\n3. Merge when approved\n```\n\n---\n\n## Error Handling\n\n### No Commits to Push\n\n```\nNo commits between origin/$BASE_BRANCH and HEAD.\nNothing to create a PR for.\n```\n\n### Branch Already Has PR\n\n```bash\ngh pr view --web\n```\n\nOpens the existing PR instead of creating a duplicate.\n\n### Push Fails\n\n1. Check if branch exists remotely: `git ls-remote --heads origin [branch]`\n2. If conflicts: `git pull --rebase origin $BASE_BRANCH` then retry push\n3. If permission issues: Check GitHub access\n",
+  "archon-docs-impact-agent": "---\ndescription: Check if PR changes require documentation updates (CLAUDE.md, docs/, agents)\nargument-hint: (none - reads from scope artifact)\n---\n\n# Documentation Impact Agent\n\n---\n\n## Your Mission\n\nAnalyze if the PR changes require updates to project documentation: CLAUDE.md, docs/ folder, agent definitions, or other documentation. Produce a structured artifact with recommendations.\n\n**Output artifact**: `$ARTIFACTS_DIR/review/docs-impact-findings.md`\n\n---\n\n## Phase 1: LOAD - Get Context\n\n### 1.1 Get PR Number from Registry\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number)\n```\n\n### 1.2 Read Scope\n\n```bash\ncat $ARTIFACTS_DIR/review/scope.md\n```\n\n**CRITICAL**: Check for \"NOT Building (Scope Limits)\" section. Items listed there are **intentionally excluded** - do NOT flag them as missing documentation needs!\n\n### 1.3 Get PR Diff\n\n```bash\ngh pr diff {number}\n```\n\n### 1.4 Read Current Documentation\n\n```bash\n# Read CLAUDE.md\ncat CLAUDE.md\n\n# List docs folder\nls -la $DOCS_DIR\n\n# List agent definitions\nls -la .claude/agents/ 2>/dev/null || true\nls -la .archon/commands/ 2>/dev/null || true\n```\n\n**PHASE_1_CHECKPOINT:**\n- [ ] PR number identified\n- [ ] Changes understood\n- [ ] Current docs read\n\n---\n\n## Phase 2: ANALYZE - Check Documentation Impact\n\n### 2.1 CLAUDE.md Impact\n\nCheck if changes affect documented:\n- Commands or slash commands\n- Workflows\n- Development setup\n- Environment variables\n- Database schema\n- API endpoints\n- Testing instructions\n- Code patterns/standards\n\n### 2.2 docs/ Folder Impact\n\nCheck if changes affect:\n- Architecture documentation\n- Getting started guide\n- Configuration documentation\n- API documentation\n- Deployment instructions\n\n### 2.3 Agent/Command Definitions\n\nCheck if changes affect:\n- Agent capabilities\n- Command arguments\n- Workflow steps\n- Tool usage patterns\n\n### 2.4 README Impact\n\nCheck if changes affect:\n- Feature list\n- Installation instructions\n- Usage examples\n- Configuration options\n\n**PHASE_2_CHECKPOINT:**\n- [ ] CLAUDE.md impact assessed\n- [ ] docs/ impact assessed\n- [ ] Agent definitions checked\n- [ ] README checked\n\n---\n\n## Phase 3: GENERATE - Create Artifact\n\nWrite to `$ARTIFACTS_DIR/review/docs-impact-findings.md`:\n\n```markdown\n# Documentation Impact Findings: PR #{number}\n\n**Reviewer**: docs-impact-agent\n**Date**: {ISO timestamp}\n**Docs Checked**: CLAUDE.md, docs/, agents, README\n\n---\n\n## Summary\n\n{2-3 sentence overview of documentation impact}\n\n**Verdict**: {NO_CHANGES_NEEDED | UPDATES_REQUIRED | CRITICAL_UPDATES}\n\n---\n\n## Impact Assessment\n\n| Document | Impact | Required Update |\n|----------|--------|-----------------|\n| CLAUDE.md | NONE/LOW/HIGH | {description or \"None\"} |\n| $DOCS_DIR/architecture.md | NONE/LOW/HIGH | {description or \"None\"} |\n| $DOCS_DIR/configuration.md | NONE/LOW/HIGH | {description or \"None\"} |\n| README.md | NONE/LOW/HIGH | {description or \"None\"} |\n| .claude/agents/*.md | NONE/LOW/HIGH | {description or \"None\"} |\n| .archon/commands/*.md | NONE/LOW/HIGH | {description or \"None\"} |\n\n---\n\n## Findings\n\n### Finding 1: {Descriptive Title}\n\n**Severity**: CRITICAL | HIGH | MEDIUM | LOW\n**Category**: missing-docs | outdated-docs | incomplete-docs | misleading-docs\n**Document**: `{file path}`\n**PR Change**: `{source file}:{line}` - {what changed}\n\n**Issue**:\n{Clear description of why docs need updating}\n\n**Current Documentation**:\n```markdown\n{current text in docs}\n```\n\n**Code Change**:\n```typescript\n// What changed in the PR\n{new code that docs don't reflect}\n```\n\n**Impact if Not Updated**:\n{What happens if docs aren't updated - user confusion, wrong setup, etc.}\n\n---\n\n#### Update Suggestions\n\n| Option | Approach | Scope | Effort |\n|--------|----------|-------|--------|\n| A | {minimal update} | {what it covers} | LOW |\n| B | {comprehensive update} | {what it covers} | MED/HIGH |\n\n**Recommended**: Option {X}\n\n**Reasoning**:\n{Why this update approach:\n- Keeps docs accurate\n- Matches existing documentation style\n- Appropriate level of detail}\n\n**Suggested Documentation Update**:\n```markdown\n{what the docs should say after update}\n```\n\n**Documentation Style Reference**:\n```markdown\n# SOURCE: {doc file}\n# How similar features are documented\n{existing documentation pattern}\n```\n\n---\n\n### Finding 2: {Title}\n\n{Same structure...}\n\n---\n\n## CLAUDE.md Sections to Update\n\n| Section | Current | Needed Update |\n|---------|---------|---------------|\n| {section name} | {current text summary} | {what to add/change} |\n| ... | ... | ... |\n\n---\n\n## Statistics\n\n| Severity | Count | Documents Affected |\n|----------|-------|-------------------|\n| CRITICAL | {n} | {list} |\n| HIGH | {n} | {list} |\n| MEDIUM | {n} | {list} |\n| LOW | {n} | {list} |\n\n---\n\n## New Documentation Needed\n\n| Topic | Suggested Location | Priority |\n|-------|-------------------|----------|\n| {new feature/change} | {where to document} | HIGH/MED/LOW |\n| ... | ... | ... |\n\n---\n\n## Positive Observations\n\n{Documentation already updated in PR, good inline docs, etc.}\n\n---\n\n## Metadata\n\n- **Agent**: docs-impact-agent\n- **Timestamp**: {ISO timestamp}\n- **Artifact**: `$ARTIFACTS_DIR/review/docs-impact-findings.md`\n```\n\n**PHASE_3_CHECKPOINT:**\n- [ ] Artifact file created\n- [ ] All docs checked\n- [ ] Update suggestions provided\n- [ ] Existing doc style referenced\n\n---\n\n## Success Criteria\n\n- **DOCS_ANALYZED**: All relevant docs checked\n- **IMPACT_ASSESSED**: Each doc rated for impact\n- **UPDATES_SPECIFIED**: Clear update suggestions\n- **STYLE_MATCHED**: Suggestions match existing doc style\n",
+  "archon-error-handling-agent": "---\ndescription: Review error handling for silent failures, inadequate catch blocks, and poor fallbacks\nargument-hint: (none - reads from scope artifact)\n---\n\n# Error Handling Agent\n\n---\n\n## Your Mission\n\nHunt for silent failures, inadequate error handling, broad catch blocks, and inappropriate fallback behavior. Produce a structured artifact with findings, fix suggestions with options, and reasoning.\n\n**Output artifact**: `$ARTIFACTS_DIR/review/error-handling-findings.md`\n\n---\n\n## Phase 1: LOAD - Get Context\n\n### 1.1 Get PR Number from Registry\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number)\n```\n\n### 1.2 Read Scope\n\n```bash\ncat $ARTIFACTS_DIR/review/scope.md\n```\n\n**CRITICAL**: Check for \"NOT Building (Scope Limits)\" section. Items listed there are **intentionally excluded** - do NOT flag them as bugs or missing features!\n\n### 1.3 Get PR Diff\n\n```bash\ngh pr diff {number}\n```\n\n### 1.4 Read CLAUDE.md Error Handling Rules\n\n```bash\ncat CLAUDE.md | grep -A 20 -i \"error\"\n```\n\n**PHASE_1_CHECKPOINT:**\n- [ ] PR number identified\n- [ ] Scope loaded\n- [ ] Diff available\n\n---\n\n## Phase 2: ANALYZE - Hunt for Issues\n\n### 2.1 Find All Error Handling Code\n\nSearch for:\n- `try { ... } catch` blocks\n- `.catch(` handlers\n- `|| fallback` patterns\n- `?? defaultValue` patterns\n- `?.` optional chaining that might hide errors\n- Error event handlers\n- Conditional error state handling\n\n### 2.2 Scrutinize Each Handler\n\nFor every error handling location, evaluate:\n\n**Logging Quality:**\n- Is error logged with appropriate severity?\n- Does log include sufficient context?\n- Would this help debugging in 6 months?\n\n**User Feedback:**\n- Does user receive actionable feedback?\n- Is the error message specific and helpful?\n- Are technical details appropriately hidden/shown?\n\n**Catch Block Specificity:**\n- Does it catch only expected error types?\n- Could it accidentally suppress unrelated errors?\n- Should it be multiple catch blocks?\n\n**Fallback Behavior:**\n- Is fallback explicitly documented/intended?\n- Does fallback mask the underlying problem?\n- Is user aware they're seeing fallback behavior?\n\n### 2.3 Find Codebase Error Patterns\n\n```bash\n# Find error handling patterns in codebase\ngrep -r \"catch\" src/ --include=\"*.ts\" -A 3 | head -30\ngrep -r \"console.error\" src/ --include=\"*.ts\" -B 2 -A 2 | head -30\n```\n\n**PHASE_2_CHECKPOINT:**\n- [ ] All error handlers identified\n- [ ] Each handler evaluated\n- [ ] Codebase patterns found\n\n---\n\n## Phase 3: GENERATE - Create Artifact\n\nWrite to `$ARTIFACTS_DIR/review/error-handling-findings.md`:\n\n```markdown\n# Error Handling Findings: PR #{number}\n\n**Reviewer**: error-handling-agent\n**Date**: {ISO timestamp}\n**Error Handlers Reviewed**: {count}\n\n---\n\n## Summary\n\n{2-3 sentence overview of error handling quality}\n\n**Verdict**: {APPROVE | REQUEST_CHANGES | NEEDS_DISCUSSION}\n\n---\n\n## Findings\n\n### Finding 1: {Descriptive Title}\n\n**Severity**: CRITICAL | HIGH | MEDIUM | LOW\n**Category**: silent-failure | broad-catch | missing-logging | poor-user-feedback | unsafe-fallback\n**Location**: `{file}:{line}`\n\n**Issue**:\n{Clear description of the error handling problem}\n\n**Evidence**:\n```typescript\n// Current error handling at {file}:{line}\n{problematic code}\n```\n\n**Hidden Errors**:\nThis catch block could silently hide:\n- {Error type 1}: {scenario when it occurs}\n- {Error type 2}: {scenario when it occurs}\n- {Error type 3}: {scenario when it occurs}\n\n**User Impact**:\n{What happens to the user when this error occurs? Why is it bad?}\n\n---\n\n#### Fix Suggestions\n\n| Option | Approach | Pros | Cons |\n|--------|----------|------|------|\n| A | {e.g., Add specific error types} | {benefits} | {drawbacks} |\n| B | {e.g., Add logging + user message} | {benefits} | {drawbacks} |\n| C | {e.g., Propagate error instead} | {benefits} | {drawbacks} |\n\n**Recommended**: Option {X}\n\n**Reasoning**:\n{Explain why this option is preferred:\n- Aligns with project error handling patterns\n- Provides better debugging experience\n- Gives users actionable feedback\n- Follows CLAUDE.md rules}\n\n**Recommended Fix**:\n```typescript\n// Improved error handling\n{corrected code with proper logging, specific catches, user feedback}\n```\n\n**Codebase Pattern Reference**:\n```typescript\n// SOURCE: {file}:{lines}\n// This is how similar errors are handled elsewhere\n{existing error handling pattern from codebase}\n```\n\n---\n\n### Finding 2: {Title}\n\n{Same structure...}\n\n---\n\n## Error Handler Audit\n\n| Location | Type | Logging | User Feedback | Specificity | Verdict |\n|----------|------|---------|---------------|-------------|---------|\n| `file:line` | try-catch | GOOD/BAD | GOOD/BAD | GOOD/BAD | PASS/FAIL |\n| ... | ... | ... | ... | ... | ... |\n\n---\n\n## Statistics\n\n| Severity | Count | Auto-fixable |\n|----------|-------|--------------|\n| CRITICAL | {n} | {n} |\n| HIGH | {n} | {n} |\n| MEDIUM | {n} | {n} |\n| LOW | {n} | {n} |\n\n---\n\n## Silent Failure Risk Assessment\n\n| Risk | Likelihood | Impact | Mitigation |\n|------|------------|--------|------------|\n| {potential silent failure} | HIGH/MED/LOW | {user impact} | {fix needed} |\n| ... | ... | ... | ... |\n\n---\n\n## Patterns Referenced\n\n| File | Lines | Pattern |\n|------|-------|---------|\n| `src/example.ts` | 42-50 | {error handling pattern} |\n| ... | ... | ... |\n\n---\n\n## Positive Observations\n\n{Error handling done well, good patterns, proper logging}\n\n---\n\n## Metadata\n\n- **Agent**: error-handling-agent\n- **Timestamp**: {ISO timestamp}\n- **Artifact**: `$ARTIFACTS_DIR/review/error-handling-findings.md`\n```\n\n**PHASE_3_CHECKPOINT:**\n- [ ] Artifact file created\n- [ ] All error handlers audited\n- [ ] Hidden errors listed for each finding\n- [ ] Fix options with reasoning provided\n\n---\n\n## Success Criteria\n\n- **ERROR_HANDLERS_FOUND**: All try/catch, .catch, fallbacks identified\n- **EACH_HANDLER_AUDITED**: Logging, feedback, specificity evaluated\n- **HIDDEN_ERRORS_LISTED**: Each finding lists what could be hidden\n- **ARTIFACT_CREATED**: Findings file written with complete structure\n",
+  "archon-finalize-pr": "---\ndescription: Commit changes, create PR with template, mark ready for review\nargument-hint: (no arguments - reads from workflow artifacts)\n---\n\n# Finalize Pull Request\n\n**Workflow ID**: $WORKFLOW_ID\n\n---\n\n## Your Mission\n\nFinalize the implementation and create the PR:\n1. Commit all changes\n2. Push to remote\n3. Create PR using project's template (if exists)\n4. Mark PR as ready for review\n\n---\n\n## Phase 1: LOAD - Gather Context\n\n### 1.1 Load Workflow Artifacts\n\n```bash\ncat $ARTIFACTS_DIR/plan-context.md\ncat $ARTIFACTS_DIR/implementation.md\ncat $ARTIFACTS_DIR/validation.md\n```\n\nExtract:\n- Plan title and summary\n- Branch name\n- Files changed\n- Tests written\n- Validation results\n- Deviations from plan (if any)\n\n### 1.2 Check for PR Template\n\n**IMPORTANT**: Always check for the project's PR template first. Look for it at `.github/pull_request_template.md`, `.github/PULL_REQUEST_TEMPLATE.md`, or `docs/PULL_REQUEST_TEMPLATE.md`. Read whichever one exists.\n\n**If template found**: Use it as the structure, fill in **every section** with implementation details.\n**If no template**: Use the default format defined in Phase 3.\n\n### 1.3 Check for Existing PR\n\n```bash\ngh pr list --head $(git branch --show-current) --json number,url,state\n```\n\n**If PR already exists**: Will update it instead of creating new one.\n**If no PR**: Will create new one.\n\n**PHASE_1_CHECKPOINT:**\n\n- [ ] Artifacts loaded\n- [ ] Template identified (or using default)\n- [ ] Existing PR status known\n\n---\n\n## Phase 2: COMMIT - Stage and Commit Changes\n\n### 2.1 Check Git Status\n\n```bash\ngit status --porcelain\n```\n\n### 2.2 Stage Changes\n\nStage all implementation changes:\n\n```bash\ngit add -A\n```\n\n**Review staged files** - ensure no sensitive files (.env, credentials) are included:\n\n```bash\ngit diff --cached --name-only\n```\n\n### 2.3 Create Commit\n\nCreate a descriptive commit message:\n\n```bash\ngit commit -m \"{summary of implementation}\n\n- {key change 1}\n- {key change 2}\n- {key change 3}\n\n{If from plan/issue: Implements #{number}}\n\"\n```\n\n### 2.4 Push to Remote\n\n```bash\ngit push origin HEAD\n```\n\n**PHASE_2_CHECKPOINT:**\n\n- [ ] All changes staged\n- [ ] No sensitive files included\n- [ ] Commit created\n- [ ] Pushed to remote\n\n---\n\n## Phase 3: CREATE/UPDATE - Pull Request\n\n### 3.1 Prepare PR Body\n\n**If project has PR template**, fill in each section with implementation details:\n- Replace placeholder text with actual content\n- Fill in checkboxes based on what was done\n- Keep the template's structure intact\n\n**If no template**, use this default format:\n\n```markdown\n## Summary\n\n{Brief description from plan summary}\n\n## Changes\n\n{From implementation.md \"Files Changed\" section}\n\n| File | Action | Description |\n|------|--------|-------------|\n| `src/x.ts` | CREATE | {what it does} |\n| `src/y.ts` | UPDATE | {what changed} |\n\n## Tests\n\n{From implementation.md \"Tests Written\" section}\n\n- `src/x.test.ts` - {test descriptions}\n- `src/y.test.ts` - {test descriptions}\n\n## Validation\n\n{From validation.md}\n\n- [x] Type check passes\n- [x] Lint passes\n- [x] Format passes\n- [x] All tests pass ({N} tests)\n- [x] Build succeeds\n\n## Implementation Notes\n\n{If deviations from plan:}\n### Deviations from Plan\n\n{List deviations and reasons}\n\n{If issues encountered:}\n### Issues Resolved\n\n{List issues and resolutions}\n\n---\n\n**Plan**: `{plan-source-path}`\n**Workflow ID**: `$WORKFLOW_ID`\n```\n\n### 3.2 Create or Update PR\n\n**If no PR exists**, create one:\n\n```bash\n# Write prepared body to file to avoid shell escaping\ncat > $ARTIFACTS_DIR/pr-body.md <<'EOF'\n{prepared-body}\nEOF\n\ngh pr create \\\n  --title \"{plan-title}\" \\\n  --body-file $ARTIFACTS_DIR/pr-body.md \\\n  --base $BASE_BRANCH\n```\n\n**If PR already exists**, update it:\n\n```bash\ngh pr edit {pr-number} --body-file $ARTIFACTS_DIR/pr-body.md\n```\n\n### 3.3 Ensure Ready for Review\n\nIf PR was created as draft, mark ready:\n\n```bash\ngh pr ready {pr-number} 2>/dev/null || true\n```\n\n### 3.4 Capture PR Info\n\n```bash\ngh pr view --json number,url,headRefName,baseRefName\n```\n\n### 3.5 Write PR Number Registry\n\nWrite PR number for downstream review steps:\n\n```bash\nPR_NUMBER=$(gh pr view --json number -q '.number')\nPR_URL=$(gh pr view --json url -q '.url')\necho \"$PR_NUMBER\" > $ARTIFACTS_DIR/.pr-number\necho \"$PR_URL\" > $ARTIFACTS_DIR/.pr-url\n```\n\n**PHASE_3_CHECKPOINT:**\n\n- [ ] PR created or updated\n- [ ] PR body uses template (if available)\n- [ ] PR ready for review\n- [ ] PR URL captured\n- [ ] PR number registry written\n\n---\n\n## Phase 4: ARTIFACT - Write PR Ready Status\n\n### 4.1 Write Final Artifact\n\nWrite to `$ARTIFACTS_DIR/pr-ready.md`:\n\n```markdown\n# PR Ready for Review\n\n**Generated**: {YYYY-MM-DD HH:MM}\n**Workflow ID**: $WORKFLOW_ID\n\n---\n\n## Pull Request\n\n| Field | Value |\n|-------|-------|\n| **Number** | #{number} |\n| **URL** | {url} |\n| **Branch** | `{head}` → `{base}` |\n| **Status** | Ready for Review |\n\n---\n\n## Commit\n\n**Hash**: {commit-sha}\n**Message**: {commit-message-first-line}\n\n---\n\n## Files in PR\n\n{From git diff --name-only origin/$BASE_BRANCH}\n\n| File | Status |\n|------|--------|\n| `src/x.ts` | Added |\n| `src/y.ts` | Modified |\n\n---\n\n## PR Description\n\n{Whether template was used or default format}\n\n- Template used: {yes/no}\n- Template path: {path if used}\n\n---\n\n## Next Step\n\nContinue to PR review workflow:\n1. `archon-pr-review-scope`\n2. `archon-sync-pr-with-main`\n3. Review agents (parallel)\n4. `archon-synthesize-review`\n5. `archon-implement-review-fixes`\n```\n\n**PHASE_4_CHECKPOINT:**\n\n- [ ] PR ready artifact written\n\n---\n\n## Phase 5: OUTPUT - Report Status\n\n```markdown\n## PR Ready for Review ✅\n\n**Workflow ID**: `$WORKFLOW_ID`\n\n### Pull Request\n\n| Field | Value |\n|-------|-------|\n| PR | #{number} |\n| URL | {url} |\n| Branch | `{branch}` → `{base}` |\n| Status | 🟢 Ready for Review |\n\n### Commit\n\n```\n{commit-sha-short} {commit-message-first-line}\n```\n\n### Files Changed\n\n- {N} files added\n- {M} files modified\n- {K} files deleted\n\n### Validation Summary\n\n| Check | Status |\n|-------|--------|\n| Type check | ✅ |\n| Lint | ✅ |\n| Tests | ✅ ({N} passed) |\n| Build | ✅ |\n\n### Artifact\n\nStatus written to: `$ARTIFACTS_DIR/pr-ready.md`\n\n### Next Step\n\nProceeding to comprehensive PR review.\n```\n\n---\n\n## Error Handling\n\n### Nothing to Commit\n\nIf no changes to commit:\n\n```markdown\nℹ️ No changes to commit\n\nAll changes were already committed. Proceeding to update PR description.\n```\n\n### Push Fails\n\n```bash\n# Try force push if branch was rebased\ngit push --force-with-lease origin HEAD\n```\n\nIf still fails:\n```\n❌ Push failed\n\nCheck:\n1. Branch protection rules\n2. Push access to repository\n3. Remote branch status: `git fetch origin && git status`\n```\n\n### PR Not Found\n\n```\n❌ PR not found: #{number}\n\nThe draft PR may have been closed or deleted. Create a new one:\n`gh pr create --title \"...\" --body \"...\"`\n```\n\n### Template Parsing\n\nIf template has complex structure that's hard to fill:\n- Use as much of the template as possible\n- Add implementation details in relevant sections\n- Note at bottom: \"Some template sections may need manual completion\"\n\n---\n\n## Success Criteria\n\n- **CHANGES_COMMITTED**: All changes in a commit\n- **PUSHED**: Branch pushed to remote\n- **PR_UPDATED**: PR description reflects implementation\n- **PR_READY**: Draft status removed\n- **ARTIFACT_WRITTEN**: PR ready artifact created\n",
+  "archon-fix-issue": "---\ndescription: Implement a fix from investigation artifact - code changes, validation, and commit (no PR)\nargument-hint: <issue-number|artifact-path>\n---\n\n# Fix Issue\n\n**Input**: $ARGUMENTS\n\n---\n\n## Your Mission\n\nExecute the implementation plan from `/investigate-issue`:\n\n1. Load and validate the artifact\n2. Ensure git state is correct\n3. Discover and install dependencies in the worktree\n4. Implement the changes exactly as specified\n5. Run validation\n6. Commit changes\n7. Write implementation report\n\n**Golden Rule**: Follow the artifact. If something seems wrong, validate it first - don't silently deviate.\n\n---\n\n## Phase 1: LOAD - Get the Artifact\n\n### 1.1 Find Investigation Artifact\n\nLook for the investigation artifact from the previous step:\n\n```bash\n# Check for artifact in workflow runs directory\nls $ARTIFACTS_DIR/investigation.md\n```\n\n**If input is a specific path**, use that path directly.\n\n### 1.2 Load and Parse Artifact\n\n```bash\ncat {artifact-path}\n```\n\n**Extract from artifact:**\n- Issue number and title\n- Type (BUG/ENHANCEMENT/etc)\n- Files to modify (with line numbers)\n- Implementation steps\n- Validation commands\n- Test cases to add\n\n### 1.3 Validate Artifact Exists\n\n**If artifact not found:**\n```\n❌ Investigation artifact not found at $ARTIFACTS_DIR/investigation.md\n\nRun `/investigate-issue {number}` first to create the implementation plan.\n```\n\n**PHASE_1_CHECKPOINT:**\n- [ ] Artifact found and loaded\n- [ ] Key sections parsed (files, steps, validation)\n- [ ] Issue number extracted (if applicable)\n\n---\n\n## Phase 2: VALIDATE - Sanity Check\n\n### 2.1 Verify Plan Accuracy\n\nFor each file mentioned in the artifact:\n- Read the actual current code\n- Compare to what artifact expects\n- Check if the \"current code\" snippets match reality\n\n**If significant drift detected:**\n```\n⚠️ Code has changed since investigation:\n\nFile: src/x.ts:45\n- Artifact expected: {snippet}\n- Actual code: {different snippet}\n\nOptions:\n1. Re-run /investigate-issue to get fresh analysis\n2. Proceed carefully with manual adjustments\n```\n\n### 2.2 Confirm Approach Makes Sense\n\nAsk yourself:\n- Does the proposed fix actually address the root cause?\n- Are there obvious problems with the approach?\n- Has something changed that invalidates the plan?\n\n**If plan seems wrong:**\n- STOP\n- Explain what's wrong\n- Suggest re-investigation\n\n**PHASE_2_CHECKPOINT:**\n- [ ] Artifact matches current codebase state\n- [ ] Approach still makes sense\n- [ ] No blocking issues identified\n\n---\n\n## Phase 3: GIT-CHECK - Ensure Correct State\n\n### 3.1 Check Current Git State\n\n```bash\n# What branch are we on?\ngit branch --show-current\n\n# Are we in a worktree?\ngit rev-parse --show-toplevel\ngit worktree list\n\n# Is working directory clean?\ngit status --porcelain\n\n# Are we up to date with remote?\ngit fetch origin\ngit status\n```\n\n### 3.2 Decision Tree\n\n```text\n┌─ IN WORKTREE?\n│  └─ YES → Use current branch AS-IS. Do NOT switch branches. Do NOT create\n│           new branches. The isolation system has already set up the correct\n│           branch; any deviation operates on the wrong code.\n│           Log: \"Using worktree at {path} on branch {branch}\"\n│\n├─ ON $BASE_BRANCH? (main, master, or configured base branch)\n│  └─ Q: Working directory clean?\n│     ├─ YES → Create branch: fix/issue-{number}-{slug}\n│     │        git checkout -b fix/issue-{number}-{slug}\n│     │        (only applies outside a worktree — e.g., manual CLI usage)\n│     └─ NO  → STOP: \"Uncommitted changes on $BASE_BRANCH.\n│              Please commit or stash before proceeding.\"\n│\n├─ ON OTHER BRANCH?\n│  └─ Use it AS-IS (assume it was set up for this work).\n│     Do NOT switch to another branch (e.g., one shown by `git branch` but\n│     not currently checked out).\n│     If branch name doesn't contain issue number:\n│       Warn: \"Branch '{name}' may not be for issue #{number}\"\n│\n└─ DIRTY STATE?\n   └─ STOP: \"Uncommitted changes. Please commit or stash first.\"\n```\n\n### 3.3 Ensure Up-to-Date\n\n```bash\n# If branch tracks remote\ngit pull --rebase origin $BASE_BRANCH 2>/dev/null || git pull origin $BASE_BRANCH\n```\n\n**PHASE_3_CHECKPOINT:**\n- [ ] Git state is clean and correct\n- [ ] On appropriate branch (created or existing)\n- [ ] Up to date with base branch\n\n---\n\n## Phase 4: DEPENDENCIES - Discover and Install\n\n### 4.1 Detect Install Command\n\nInspect the worktree for lock/config files and choose the install command:\n\n- `package.json` + `bun.lock` → `bun install`\n- `package.json` + `package-lock.json` → `npm install`\n- `package.json` + `yarn.lock` → `yarn install`\n- `package.json` + `pnpm-lock.yaml` → `pnpm install`\n- `requirements.txt` → `pip install -r requirements.txt`\n- `pyproject.toml` + `poetry.lock` → `poetry install`\n- `Cargo.toml` → `cargo build`\n- `go.mod` → `go mod download`\n\n### 4.2 Run Install\n\nRun the chosen install command from the worktree root before any validation or tests.\n\n### 4.3 Failure Handling\n\nIf install fails, STOP and report the error. Do not proceed to validation with missing dependencies.\n\n**PHASE_4_CHECKPOINT:**\n- [ ] Install command discovered\n- [ ] Dependencies installed successfully\n\n---\n\n## Phase 5: IMPLEMENT - Make Changes\n\n### 5.1 Execute Each Step\n\nFor each step in the artifact's Implementation Plan:\n\n1. **Read the target file** - understand current state\n2. **Make the change** - exactly as specified\n3. **Verify types compile** - `bun run type-check`\n\n### 5.2 Implementation Rules\n\n**DO:**\n- Follow artifact steps in order\n- Match existing code style exactly\n- Copy patterns from \"Patterns to Follow\" section\n- Add tests as specified\n\n**DON'T:**\n- Refactor unrelated code\n- Add \"improvements\" not in the plan\n- Change formatting of untouched lines\n- Deviate from the artifact without noting it\n\n### 5.3 Handle Each File Type\n\n**For UPDATE files:**\n- Read current content\n- Find the exact lines mentioned\n- Make the specified change\n- Preserve surrounding code\n\n**For CREATE files:**\n- Use patterns from artifact\n- Follow existing file structure conventions\n- Include all specified content\n\n**For test files:**\n- Add test cases as specified\n- Follow existing test patterns\n- Ensure tests actually test the fix\n\n### 5.4 Track Deviations\n\nIf you must deviate from the artifact:\n- Note what changed and why\n- Include in implementation report\n\n**PHASE_5_CHECKPOINT:**\n- [ ] All steps from artifact executed\n- [ ] Types compile after each change\n- [ ] Tests added as specified\n- [ ] Any deviations documented\n\n---\n\n## Phase 6: VERIFY - Run Validation\n\n### 6.1 Run Artifact Validation Commands\n\nExecute each command from the artifact's Validation section:\n\n```bash\nbun run type-check\nbun test {pattern-from-artifact}\nbun run lint\n```\n\n### 6.2 Check Results\n\n**All must pass before proceeding.**\n\nIf failures:\n1. Analyze what's wrong\n2. Fix the issue\n3. Re-run validation\n4. Note any fixes in implementation report\n\n### 6.3 Manual Verification (if specified)\n\nExecute any manual verification steps from the artifact.\n\n**PHASE_6_CHECKPOINT:**\n- [ ] Type check passes\n- [ ] Tests pass\n- [ ] Lint passes\n- [ ] Manual verification complete (if applicable)\n\n---\n\n## Phase 7: COMMIT - Save Changes\n\n### 7.1 Stage Changes\n\n```bash\ngit add -A\ngit status  # Review what's being committed\n```\n\n### 7.2 Write Commit Message\n\n**Format:**\n```\nFix: {brief description} (#{issue-number})\n\n{Problem statement from artifact - 1-2 sentences}\n\nChanges:\n- {Change 1 from artifact}\n- {Change 2 from artifact}\n- Added test for {case}\n\nFixes #{issue-number}\n```\n\n**Commit:**\n```bash\ngit commit -m \"$(cat <<'EOF'\nFix: {title} (#{number})\n\n{problem statement}\n\nChanges:\n- {change 1}\n- {change 2}\n\nFixes #{number}\nEOF\n)\"\n```\n\n**PHASE_7_CHECKPOINT:**\n- [ ] All changes committed\n- [ ] Commit message references issue\n\n---\n\n## Phase 8: WRITE - Implementation Report\n\n### 8.1 Write Implementation Artifact\n\nWrite to `$ARTIFACTS_DIR/implementation.md`:\n\n```markdown\n# Implementation Report\n\n**Issue**: #{number}\n**Generated**: {YYYY-MM-DD HH:MM}\n**Workflow ID**: $WORKFLOW_ID\n\n---\n\n## Tasks Completed\n\n| # | Task | File | Status |\n|---|------|------|--------|\n| 1 | {task} | `src/x.ts` | ✅ |\n| 2 | {task} | `src/x.test.ts` | ✅ |\n\n---\n\n## Files Changed\n\n| File | Action | Lines |\n|------|--------|-------|\n| `src/x.ts` | UPDATE | +{N}/-{M} |\n| `src/x.test.ts` | CREATE | +{N} |\n\n---\n\n## Deviations from Investigation\n\n{If none: \"Implementation matched the investigation exactly.\"}\n\n{If any:}\n### Deviation 1: {title}\n\n**Expected**: {from investigation}\n**Actual**: {what was done}\n**Reason**: {why}\n\n---\n\n## Validation Results\n\n| Check | Result |\n|-------|--------|\n| Type check | ✅ |\n| Tests | ✅ ({N} passed) |\n| Lint | ✅ |\n```\n\n**PHASE_8_CHECKPOINT:**\n- [ ] Implementation artifact written\n\n---\n\n## Phase 9: OUTPUT - Report to User\n\nSkip archiving - artifacts remain in place for review workflow to access.\n\n---\n\n```markdown\n## Implementation Complete\n\n**Issue**: #{number} - {title}\n**Branch**: `{branch-name}`\n\n### Changes Made\n\n| File | Change |\n|------|--------|\n| `src/x.ts` | {description} |\n| `src/x.test.ts` | Added test |\n\n### Validation\n\n| Check | Result |\n|-------|--------|\n| Type check | ✅ Pass |\n| Tests | ✅ Pass |\n| Lint | ✅ Pass |\n\n### Artifacts\n\n- 📄 Investigation: `$ARTIFACTS_DIR/investigation.md`\n- 📄 Implementation: `$ARTIFACTS_DIR/implementation.md`\n\n### Next Step\n\nProceeding to PR creation...\n```\n\n---\n\n## Handling Edge Cases\n\n### Artifact is outdated\n- Warn user about drift\n- Suggest re-running `/investigate-issue`\n- Can proceed with caution if changes are minor\n\n### Tests fail after implementation\n- Debug the failure\n- Fix the code (not the test, unless test is wrong)\n- Re-run validation\n- Note the additional fix in implementation report\n\n### Merge conflicts during rebase\n- Resolve conflicts\n- Re-run full validation\n- Note conflict resolution in implementation report\n\n### Already on a branch with changes\n- Use the existing branch\n- Warn if branch name doesn't match issue\n- Don't create a new branch\n\n### In a worktree\n- Use it as-is\n- Assume it was created for this purpose\n- Log that worktree is being used\n\n---\n\n## Success Criteria\n\n- **PLAN_EXECUTED**: All investigation steps completed\n- **VALIDATION_PASSED**: All checks green\n- **CHANGES_COMMITTED**: All changes committed to branch\n- **IMPLEMENTATION_ARTIFACT**: Written to $ARTIFACTS_DIR/\n- **READY_FOR_PR**: Workflow continues to PR creation\n",
+  "archon-implement-issue": "---\ndescription: Implement a fix from investigation artifact - code changes, PR, and self-review\nargument-hint: <issue-number|artifact-path>\n---\n\n# Implement Issue\n\n**Input**: $ARGUMENTS\n\n---\n\n## Your Mission\n\nExecute the implementation plan from `/investigate-issue`:\n\n1. Load and validate the artifact\n2. Ensure git state is correct\n3. Discover and install dependencies in the worktree\n4. Implement the changes exactly as specified\n5. Run validation\n6. Create PR linked to issue\n7. Run self-review and post findings\n8. Archive the artifact\n\n**Golden Rule**: Follow the artifact. If something seems wrong, validate it first - don't silently deviate.\n\n---\n\n## Phase 1: LOAD - Get the Artifact\n\n### 1.1 Find Investigation Artifact\n\nLook for the investigation artifact from the previous step:\n\n```bash\n# Check for artifact in workflow runs directory\nls $ARTIFACTS_DIR/investigation.md\n```\n\n**If input is a specific path**, use that path directly.\n\n### 1.2 Load and Parse Artifact\n\n```bash\ncat {artifact-path}\n```\n\n**Extract from artifact:**\n- Issue number and title\n- Type (BUG/ENHANCEMENT/etc)\n- Files to modify (with line numbers)\n- Implementation steps\n- Validation commands\n- Test cases to add\n\n### 1.3 Validate Artifact Exists\n\n**If artifact not found:**\n```\n❌ Investigation artifact not found at $ARTIFACTS_DIR/investigation.md\n\nRun `/investigate-issue {number}` first to create the implementation plan.\n```\n\n**PHASE_1_CHECKPOINT:**\n- [ ] Artifact found and loaded\n- [ ] Key sections parsed (files, steps, validation)\n- [ ] Issue number extracted (if applicable)\n\n---\n\n## Phase 2: VALIDATE - Sanity Check\n\n### 2.1 Verify Plan Accuracy\n\nFor each file mentioned in the artifact:\n- Read the actual current code\n- Compare to what artifact expects\n- Check if the \"current code\" snippets match reality\n\n**If significant drift detected:**\n```\n⚠️ Code has changed since investigation:\n\nFile: src/x.ts:45\n- Artifact expected: {snippet}\n- Actual code: {different snippet}\n\nOptions:\n1. Re-run /investigate-issue to get fresh analysis\n2. Proceed carefully with manual adjustments\n```\n\n### 2.2 Confirm Approach Makes Sense\n\nAsk yourself:\n- Does the proposed fix actually address the root cause?\n- Are there obvious problems with the approach?\n- Has something changed that invalidates the plan?\n\n**If plan seems wrong:**\n- STOP\n- Explain what's wrong\n- Suggest re-investigation\n\n**PHASE_2_CHECKPOINT:**\n- [ ] Artifact matches current codebase state\n- [ ] Approach still makes sense\n- [ ] No blocking issues identified\n\n---\n\n## Phase 3: GIT-CHECK - Ensure Correct State\n\n### 3.1 Check Current Git State\n\n```bash\n# What branch are we on?\ngit branch --show-current\n\n# Are we in a worktree?\ngit rev-parse --show-toplevel\ngit worktree list\n\n# Is working directory clean?\ngit status --porcelain\n\n# Are we up to date with remote?\ngit fetch origin\ngit status\n```\n\n### 3.2 Decision Tree\n\n```text\n┌─ IN WORKTREE?\n│  └─ YES → Use current branch AS-IS. Do NOT switch branches. Do NOT create\n│           new branches. The isolation system has already set up the correct\n│           branch; any deviation operates on the wrong code.\n│           Log: \"Using worktree at {path} on branch {branch}\"\n│\n├─ ON $BASE_BRANCH? (main, master, or configured base branch)\n│  └─ Q: Working directory clean?\n│     ├─ YES → Create branch: fix/issue-{number}-{slug}\n│     │        git checkout -b fix/issue-{number}-{slug}\n│     │        (only applies outside a worktree — e.g., manual CLI usage)\n│     └─ NO  → STOP: \"Uncommitted changes on $BASE_BRANCH.\n│              Please commit or stash before proceeding.\"\n│\n├─ ON OTHER BRANCH?\n│  └─ Use it AS-IS (assume it was set up for this work).\n│     Do NOT switch to another branch (e.g., one shown by `git branch` but\n│     not currently checked out).\n│     If branch name doesn't contain issue number:\n│       Warn: \"Branch '{name}' may not be for issue #{number}\"\n│\n└─ DIRTY STATE?\n   └─ STOP: \"Uncommitted changes. Please commit or stash first.\"\n```\n\n### 3.3 Ensure Up-to-Date\n\n```bash\n# If branch tracks remote\ngit pull --rebase origin $BASE_BRANCH 2>/dev/null || git pull origin $BASE_BRANCH\n```\n\n**PHASE_3_CHECKPOINT:**\n- [ ] Git state is clean and correct\n- [ ] On appropriate branch (created or existing)\n- [ ] Up to date with base branch\n\n---\n\n## Phase 4: DEPENDENCIES - Discover and Install\n\n### 4.1 Detect Install Command\n\nInspect the worktree for lock/config files and choose the install command:\n\n- `package.json` + `bun.lock` → `bun install`\n- `package.json` + `package-lock.json` → `npm install`\n- `package.json` + `yarn.lock` → `yarn install`\n- `package.json` + `pnpm-lock.yaml` → `pnpm install`\n- `requirements.txt` → `pip install -r requirements.txt`\n- `pyproject.toml` + `poetry.lock` → `poetry install`\n- `Cargo.toml` → `cargo build`\n- `go.mod` → `go mod download`\n\n### 4.2 Run Install\n\nRun the chosen install command from the worktree root before any validation or tests.\n\n### 4.3 Failure Handling\n\nIf install fails, STOP and report the error. Do not proceed to validation with missing dependencies.\n\n**PHASE_4_CHECKPOINT:**\n- [ ] Install command discovered\n- [ ] Dependencies installed successfully\n\n---\n\n## Phase 5: IMPLEMENT - Make Changes\n\n### 5.1 Execute Each Step\n\nFor each step in the artifact's Implementation Plan:\n\n1. **Read the target file** - understand current state\n2. **Make the change** - exactly as specified\n3. **Verify types compile** - `bun run type-check`\n\n### 5.2 Implementation Rules\n\n**DO:**\n- Follow artifact steps in order\n- Match existing code style exactly\n- Copy patterns from \"Patterns to Follow\" section\n- Add tests as specified\n\n**DON'T:**\n- Refactor unrelated code\n- Add \"improvements\" not in the plan\n- Change formatting of untouched lines\n- Deviate from the artifact without noting it\n\n### 5.3 Handle Each File Type\n\n**For UPDATE files:**\n- Read current content\n- Find the exact lines mentioned\n- Make the specified change\n- Preserve surrounding code\n\n**For CREATE files:**\n- Use patterns from artifact\n- Follow existing file structure conventions\n- Include all specified content\n\n**For test files:**\n- Add test cases as specified\n- Follow existing test patterns\n- Ensure tests actually test the fix\n\n### 5.4 Track Deviations\n\nIf you must deviate from the artifact:\n- Note what changed and why\n- Include in PR description\n\n**PHASE_5_CHECKPOINT:**\n- [ ] All steps from artifact executed\n- [ ] Types compile after each change\n- [ ] Tests added as specified\n- [ ] Any deviations documented\n\n---\n\n## Phase 6: VERIFY - Run Validation\n\n### 6.1 Run Artifact Validation Commands\n\nExecute each command from the artifact's Validation section:\n\n```bash\nbun run type-check\nbun test {pattern-from-artifact}\nbun run lint\n```\n\n### 6.2 Check Results\n\n**All must pass before proceeding.**\n\nIf failures:\n1. Analyze what's wrong\n2. Fix the issue\n3. Re-run validation\n4. Note any fixes in PR description\n\n### 6.3 Manual Verification (if specified)\n\nExecute any manual verification steps from the artifact.\n\n**PHASE_6_CHECKPOINT:**\n- [ ] Type check passes\n- [ ] Tests pass\n- [ ] Lint passes\n- [ ] Manual verification complete (if applicable)\n\n---\n\n## Phase 7: COMMIT - Save Changes\n\n### 7.1 Stage Changes\n\n```bash\ngit add -A\ngit status  # Review what's being committed\n```\n\n### 7.2 Write Commit Message\n\n**Format:**\n```\nFix: {brief description} (#{issue-number})\n\n{Problem statement from artifact - 1-2 sentences}\n\nChanges:\n- {Change 1 from artifact}\n- {Change 2 from artifact}\n- Added test for {case}\n\nFixes #{issue-number}\n```\n\n**Commit:**\n```bash\ngit commit -m \"$(cat <<'EOF'\nFix: {title} (#{number})\n\n{problem statement}\n\nChanges:\n- {change 1}\n- {change 2}\n\nFixes #{number}\nEOF\n)\"\n```\n\n**PHASE_7_CHECKPOINT:**\n- [ ] All changes committed\n- [ ] Commit message references issue\n\n---\n\n## Phase 8: PR - Create Pull Request\n\n**Before creating a PR**, check if one already exists for this issue or branch using `gh pr list`. If a PR already exists, skip creation and use the existing one.\n\n### 8.1 Push to Remote\n\n```bash\ngit push -u origin HEAD\n```\n\nIf branch was rebased:\n```bash\ngit push -u origin HEAD --force-with-lease\n```\n\n### 8.2 Prepare PR Body\n\nLook for the project's PR template at `.github/pull_request_template.md`, `.github/PULL_REQUEST_TEMPLATE.md`, or `docs/PULL_REQUEST_TEMPLATE.md`. Read whichever one exists.\n\n**If template found**: Use it as the structure, fill in **every section** with details from the artifact (root cause, changes, validation results, etc.). Don't skip sections or leave placeholders. Make sure to include `Fixes #{number}`.\n\n**If no template**, write a body covering: summary, root cause, changes table, validation evidence, and `Fixes #{number}`.\n\n### 8.3 Create PR\n\nWrite the prepared body to `$ARTIFACTS_DIR/pr-body.md`, then:\n\n```bash\ngh pr create --title \"Fix: {title} (#{number})\" \\\n  --body-file $ARTIFACTS_DIR/pr-body.md\n```\n\n### 8.3 Get PR Number\n\n```bash\nPR_URL=$(gh pr view --json url -q '.url')\nPR_NUMBER=$(gh pr view --json number -q '.number')\n```\n\n**PHASE_8_CHECKPOINT:**\n- [ ] Changes pushed to remote\n- [ ] PR created\n- [ ] PR linked to issue with \"Fixes #{number}\"\n\n---\n\n## Phase 9: WRITE - Implementation Report\n\n### 9.1 Write Implementation Artifact\n\nWrite to `$ARTIFACTS_DIR/implementation.md`:\n\n```markdown\n# Implementation Report\n\n**Issue**: #{number}\n**Generated**: {YYYY-MM-DD HH:MM}\n**Workflow ID**: $WORKFLOW_ID\n\n---\n\n## Tasks Completed\n\n| # | Task | File | Status |\n|---|------|------|--------|\n| 1 | {task} | `src/x.ts` | ✅ |\n| 2 | {task} | `src/x.test.ts` | ✅ |\n\n---\n\n## Files Changed\n\n| File | Action | Lines |\n|------|--------|-------|\n| `src/x.ts` | UPDATE | +{N}/-{M} |\n| `src/x.test.ts` | CREATE | +{N} |\n\n---\n\n## Deviations from Investigation\n\n{If none: \"Implementation matched the investigation exactly.\"}\n\n{If any:}\n### Deviation 1: {title}\n\n**Expected**: {from investigation}\n**Actual**: {what was done}\n**Reason**: {why}\n\n---\n\n## Validation Results\n\n| Check | Result |\n|-------|--------|\n| Type check | ✅ |\n| Tests | ✅ ({N} passed) |\n| Lint | ✅ |\n\n---\n\n## PR Created\n\n- **Number**: #{pr-number}\n- **URL**: {pr-url}\n- **Branch**: {branch-name}\n```\n\n**PHASE_9_CHECKPOINT:**\n- [ ] Implementation artifact written\n\n---\n\n## Phase 10: OUTPUT - Report to User\n\nSkip archiving - artifacts remain in place for review workflow to access.\n\n---\n\n```markdown\n## Implementation Complete\n\n**Issue**: #{number} - {title}\n**Branch**: `{branch-name}`\n**PR**: #{pr-number} - {pr-url}\n\n### Changes Made\n\n| File | Change |\n|------|--------|\n| `src/x.ts` | {description} |\n| `src/x.test.ts` | Added test |\n\n### Validation\n\n| Check | Result |\n|-------|--------|\n| Type check | ✅ Pass |\n| Tests | ✅ Pass |\n| Lint | ✅ Pass |\n\n### Artifacts\n\n- 📄 Investigation: `$ARTIFACTS_DIR/investigation.md`\n- 📄 Implementation: `$ARTIFACTS_DIR/implementation.md`\n\n### Next Step\n\nProceeding to comprehensive code review...\n```\n\n---\n\n## Handling Edge Cases\n\n### Artifact is outdated\n- Warn user about drift\n- Suggest re-running `/investigate-issue`\n- Can proceed with caution if changes are minor\n\n### Tests fail after implementation\n- Debug the failure\n- Fix the code (not the test, unless test is wrong)\n- Re-run validation\n- Note the additional fix in PR\n\n### Merge conflicts during rebase\n- Resolve conflicts\n- Re-run full validation\n- Note conflict resolution in PR\n\n### PR creation fails\n- Check if PR already exists for branch\n- Check for permission issues\n- Provide manual gh command\n\n### Already on a branch with changes\n- Use the existing branch\n- Warn if branch name doesn't match issue\n- Don't create a new branch\n\n### In a worktree\n- Use it as-is\n- Assume it was created for this purpose\n- Log that worktree is being used\n\n---\n\n## Success Criteria\n\n- **PLAN_EXECUTED**: All investigation steps completed\n- **VALIDATION_PASSED**: All checks green\n- **PR_CREATED**: PR exists and linked to issue\n- **IMPLEMENTATION_ARTIFACT**: Written to runs/$WORKFLOW_ID/\n- **READY_FOR_REVIEW**: Workflow continues to comprehensive review\n",
+  "archon-implement-review-fixes": "---\ndescription: Implement CRITICAL and HIGH fixes from review, add tests, report remaining issues\nargument-hint: (none - reads from consolidated review artifact)\n---\n\n# Implement Review Fixes\n\n---\n\n## IMPORTANT: Output Behavior\n\n**Your output will be posted as a GitHub comment.** Keep your working output minimal:\n- Do NOT narrate each step (\"Now I'll read the file...\", \"Let me check...\")\n- Do NOT output verbose progress updates\n- Only output the final structured report at the end\n- Use the TodoWrite tool to track progress silently\n\n---\n\n## Your Mission\n\nRead the consolidated review artifact and implement all CRITICAL and HIGH priority fixes. Add tests for fixed code if missing. Commit and push changes. Report what was fixed, what wasn't (and why), and suggest follow-up issues for remaining items.\n\n**Output artifact**: `$ARTIFACTS_DIR/review/fix-report.md`\n**Git action**: Commit AND push fixes to the PR branch\n**GitHub action**: Post fix report comment\n\n---\n\n## Phase 1: LOAD - Get Fix List\n\n### 1.1 Get PR Number from Registry\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number)\n\n# Get the PR's head branch name\nHEAD_BRANCH=$(gh pr view $PR_NUMBER --json headRefName --jq '.headRefName')\necho \"PR: $PR_NUMBER, Branch: $HEAD_BRANCH\"\n```\n\n### 1.2 Checkout the PR Branch\n\n**CRITICAL: Work on the PR's actual branch, not a new branch.**\n\n```bash\n# Fetch and checkout the PR's branch\ngit fetch origin $HEAD_BRANCH\ngit checkout $HEAD_BRANCH\ngit pull origin $HEAD_BRANCH\n```\n\n### 1.3 Read Consolidated Review\n\n```bash\ncat $ARTIFACTS_DIR/review/consolidated-review.md\n```\n\nExtract:\n- All CRITICAL issues with fixes\n- All HIGH issues with fixes\n- MEDIUM issues (for reporting)\n- LOW issues (for reporting)\n\n### 1.4 Read Individual Artifacts for Details\n\nIf consolidated doesn't have full fix code, read original artifacts:\n\n```bash\ncat $ARTIFACTS_DIR/review/code-review-findings.md\ncat $ARTIFACTS_DIR/review/error-handling-findings.md\ncat $ARTIFACTS_DIR/review/test-coverage-findings.md\ncat $ARTIFACTS_DIR/review/docs-impact-findings.md\n```\n\n### 1.5 Check Current Git State\n\n```bash\ngit status --porcelain\ngit branch --show-current\n```\n\nVerify you are on the correct PR branch (should be `$HEAD_BRANCH`).\n\n**PHASE_1_CHECKPOINT:**\n- [ ] PR number identified\n- [ ] On the correct PR branch (NOT base branch, NOT a new branch)\n- [ ] Consolidated review loaded\n- [ ] CRITICAL/HIGH issues extracted\n\n---\n\n## Phase 2: IMPLEMENT - Apply Fixes\n\n### 2.1 For Each CRITICAL Issue\n\n1. **Read the file**\n2. **Apply the recommended fix**\n3. **Verify fix compiles**: `bun run type-check`\n4. **Track**: Note what was changed\n\n### 2.2 For Each HIGH Issue\n\nSame process as CRITICAL.\n\n### 2.3 For Test Coverage Gaps\n\nIf test-coverage-agent identified missing tests for fixed code:\n\n1. **Create/update test file**\n2. **Add tests for the fix**\n3. **Verify tests pass**: `bun test {file}`\n\n### 2.4 Handle Unfixable Issues\n\nIf a fix cannot be applied:\n- **Conflict**: Code has changed since review\n- **Complex**: Requires architectural changes\n- **Unclear**: Recommendation is ambiguous\n- **Risk**: Fix might break other things\n\nDocument the reason clearly.\n\n**PHASE_2_CHECKPOINT:**\n- [ ] All CRITICAL fixes attempted\n- [ ] All HIGH fixes attempted\n- [ ] Tests added for fixes\n- [ ] Unfixable issues documented\n\n---\n\n## Phase 3: VALIDATE - Verify Fixes\n\n### 3.1 Type Check\n\n```bash\nbun run type-check\n```\n\nMust pass. If not, fix type errors.\n\n### 3.2 Lint\n\n```bash\nbun run lint\n```\n\nFix any lint errors introduced.\n\n### 3.3 Run Tests\n\n```bash\nbun test\n```\n\nAll tests must pass. If new tests fail, fix them.\n\n### 3.4 Build Check\n\n```bash\nbun run build\n```\n\nMust succeed.\n\n**PHASE_3_CHECKPOINT:**\n- [ ] Type check passes\n- [ ] Lint passes\n- [ ] All tests pass\n- [ ] Build succeeds\n\n---\n\n## Phase 4: COMMIT AND PUSH - Save and Push Changes\n\n### 4.1 Stage Changes\n\n```bash\ngit add -A\ngit status\n```\n\n### 4.2 Commit\n\n```bash\ngit commit -m \"fix: Address review findings (CRITICAL/HIGH)\n\nFixes applied:\n- {brief list of fixes}\n\nTests added:\n- {list of new tests if any}\n\nSkipped (see review artifacts):\n- {brief list of unfixable if any}\n\nReview artifacts: $ARTIFACTS_DIR/review/\"\n```\n\n### 4.3 Push to PR Branch\n\n**Push the fixes to the PR branch so they appear in the PR.**\n\n```bash\ngit push origin $HEAD_BRANCH\n```\n\nIf push fails due to divergence:\n```bash\ngit pull --rebase origin $HEAD_BRANCH\ngit push origin $HEAD_BRANCH\n```\n\n**PHASE_4_CHECKPOINT:**\n- [ ] Changes committed\n- [ ] Changes pushed to PR branch\n- [ ] PR now shows the fixes\n\n---\n\n## Phase 5: GENERATE - Create Fix Report\n\nWrite to `$ARTIFACTS_DIR/review/fix-report.md`:\n\n```markdown\n# Fix Report: PR #{number}\n\n**Date**: {ISO timestamp}\n**Status**: {COMPLETE | PARTIAL}\n**Branch**: {HEAD_BRANCH}\n\n---\n\n## Summary\n\n{2-3 sentence overview of fixes applied}\n\n---\n\n## Fixes Applied\n\n### CRITICAL Fixes ({n}/{total})\n\n| Issue | Location | Status | Details |\n|-------|----------|--------|---------|\n| {title} | `file:line` | ✅ FIXED | {what was done} |\n| {title} | `file:line` | ❌ SKIPPED | {why} |\n\n---\n\n### HIGH Fixes ({n}/{total})\n\n| Issue | Location | Status | Details |\n|-------|----------|--------|---------|\n| {title} | `file:line` | ✅ FIXED | {what was done} |\n\n---\n\n## Tests Added\n\n| Test File | Test Cases | For Issue |\n|-----------|------------|-----------|\n| `src/x.test.ts` | `it('should...')` | {issue title} |\n\n---\n\n## Not Fixed (Requires Manual Action)\n\n### {Issue Title}\n\n**Severity**: {CRITICAL/HIGH}\n**Location**: `{file}:{line}`\n**Reason Not Fixed**: {reason}\n\n**Suggested Action**:\n{What the user should do}\n\n---\n\n## MEDIUM Issues (User Decision Required)\n\n| Issue | Location | Options |\n|-------|----------|---------|\n| {title} | `file:line` | Fix now / Create issue / Skip |\n\n---\n\n## LOW Issues (For Consideration)\n\n| Issue | Location | Suggestion |\n|-------|----------|------------|\n| {title} | `file:line` | {brief suggestion} |\n\n---\n\n## Suggested Follow-up Issues\n\n| Issue Title | Priority | Related Finding |\n|-------------|----------|-----------------|\n| \"{title}\" | P{1/2/3} | {which finding} |\n\n---\n\n## Validation Results\n\n| Check | Status |\n|-------|--------|\n| Type check | ✅ |\n| Lint | ✅ |\n| Tests | ✅ ({n} passed) |\n| Build | ✅ |\n\n---\n\n## Git Status\n\n- **Branch**: {HEAD_BRANCH}\n- **Commit**: {commit-hash}\n- **Pushed**: ✅ Yes\n```\n\n**PHASE_5_CHECKPOINT:**\n- [ ] Fix report created\n- [ ] All fixes documented\n\n---\n\n## Phase 6: POST - GitHub Comment\n\n### 6.1 Post Fix Report\n\n```bash\ngh pr comment {number} --body \"$(cat <<'EOF'\n# ⚡ Auto-Fix Report\n\n**Status**: {COMPLETE | PARTIAL}\n**Pushed**: ✅ Changes pushed to PR\n\n---\n\n## Fixes Applied\n\n| Severity | Fixed | Skipped |\n|----------|-------|---------|\n| 🔴 CRITICAL | {n} | {n} |\n| 🟠 HIGH | {n} | {n} |\n\n### What Was Fixed\n\n{For each fix:}\n- ✅ **{title}** (`{file}:{line}`) - {brief description}\n\n### Tests Added\n\n{If any:}\n- `{test-file}`: {n} new test cases\n\n---\n\n## ❌ Not Fixed (Manual Action Required)\n\n{If any:}\n- **{title}** (`{file}`) - {reason}\n\n---\n\n## 🟡 MEDIUM Issues (Your Decision)\n\n{If any:}\n| Issue | Options |\n|-------|---------|\n| {title} | Fix now / Create issue / Skip |\n\n---\n\n## 📋 Suggested Follow-up Issues\n\n{If any items should become issues:}\n1. **{Issue Title}** (P{1/2/3}) - {brief description}\n\n---\n\n## Validation\n\n✅ Type check | ✅ Lint | ✅ Tests | ✅ Build\n\n---\n\n*Auto-fixed by Archon comprehensive-pr-review workflow*\n*Fixes pushed to branch `{HEAD_BRANCH}`*\nEOF\n)\"\n```\n\n**PHASE_6_CHECKPOINT:**\n- [ ] GitHub comment posted\n\n---\n\n## Phase 7: OUTPUT - Final Report\n\nOutput only this summary (keep it brief):\n\n```markdown\n## ✅ Fix Implementation Complete\n\n**PR**: #{number}\n**Branch**: {HEAD_BRANCH}\n**Status**: {COMPLETE | PARTIAL}\n\n| Severity | Fixed |\n|----------|-------|\n| CRITICAL | {n}/{total} |\n| HIGH | {n}/{total} |\n\n**Validation**: ✅ All checks pass\n**Pushed**: ✅ Changes pushed to PR\n\nSee fix report: `$ARTIFACTS_DIR/review/fix-report.md`\n```\n\n---\n\n## Error Handling\n\n### Type Check Fails After Fix\n\n1. Review the error\n2. Adjust the fix\n3. Re-run type check\n4. If still failing, mark as \"Not Fixed\" with reason\n\n### Tests Fail\n\n1. Check if fix caused the failure\n2. Either: fix the implementation, or fix the test\n3. If unclear, mark as \"Not Fixed\" for manual review\n\n### Push Fails\n\n1. Pull with rebase: `git pull --rebase origin $HEAD_BRANCH`\n2. Resolve any conflicts\n3. Push again\n\n---\n\n## Success Criteria\n\n- **ON_CORRECT_BRANCH**: Working on PR's head branch, not base branch or new branch\n- **CRITICAL_ADDRESSED**: All CRITICAL issues attempted\n- **HIGH_ADDRESSED**: All HIGH issues attempted\n- **VALIDATION_PASSED**: Type check, lint, tests, build all pass\n- **COMMITTED_AND_PUSHED**: Changes committed AND pushed to PR branch\n- **REPORTED**: Fix report artifact and GitHub comment created\n",
+  "archon-implement-tasks": "---\ndescription: Execute plan tasks with type-checking after each change\nargument-hint: (no arguments - reads from workflow artifacts)\n---\n\n# Implement Tasks\n\n**Workflow ID**: $WORKFLOW_ID\n\n---\n\n## Your Mission\n\nExecute each task from the plan, validating after every change.\n\n**Core Philosophy**:\n- Type-check after EVERY file change\n- Fix issues immediately before moving on\n- Document any deviations from the plan\n\n**This step assumes setup is complete** - branch exists, PR is created, plan is confirmed.\n\n---\n\n## Phase 1: LOAD - Read Context\n\n### 1.1 Load Plan Context\n\n```bash\ncat $ARTIFACTS_DIR/plan-context.md\n```\n\nExtract:\n- Files to change (CREATE/UPDATE list)\n- Validation commands (especially type-check)\n- Patterns to mirror\n\n### 1.2 Load Plan Confirmation\n\n```bash\ncat $ARTIFACTS_DIR/plan-confirmation.md\n```\n\nCheck:\n- Status is CONFIRMED or PROCEED WITH CAUTION\n- Note any warnings to handle during implementation\n\n### 1.3 Load Original Plan\n\nThe plan source path is in `plan-context.md`. Read the full plan for detailed task instructions:\n\n```bash\ncat {plan-source-path}\n```\n\n### 1.4 Identify Package Manager\n\n```bash\ntest -f bun.lockb && echo \"bun\" || \\\ntest -f pnpm-lock.yaml && echo \"pnpm\" || \\\ntest -f yarn.lock && echo \"yarn\" || \\\ntest -f package-lock.json && echo \"npm\" || \\\necho \"unknown\"\n```\n\nStore the runner for validation commands.\n\n**PHASE_1_CHECKPOINT:**\n\n- [ ] Plan context loaded\n- [ ] Confirmation status verified\n- [ ] Original plan loaded\n- [ ] Package manager identified\n\n---\n\n## Phase 2: EXECUTE - Implement Each Task\n\n**For each task in the plan's \"Tasks\" or \"Step-by-Step Tasks\" section:**\n\n### 2.1 Read Task Context\n\nBefore implementing each task:\n\n1. **Read the MIRROR file** referenced in the task\n2. **Understand the pattern** to follow\n3. **Note any GOTCHA warnings**\n4. **Check IMPORTS** needed\n\n### 2.2 Implement the Task\n\nMake the change as specified:\n\n- **CREATE**: Write new file following the pattern\n- **UPDATE**: Modify existing file as described\n- **Follow patterns exactly** - match style, naming, structure\n\n### 2.3 Type-Check Immediately\n\n**After EVERY file change:**\n\n```bash\n{runner} run type-check\n```\n\n**If type-check fails:**\n\n1. Read the error message carefully\n2. Fix the type issue\n3. Re-run type-check\n4. Only proceed when passing\n\n**Do NOT accumulate errors** - fix each one before moving to the next task.\n\n### 2.4 Track Progress\n\nLog each task as completed:\n\n```\nTask 1: CREATE src/features/x/models.ts ✅\nTask 2: CREATE src/features/x/service.ts ✅\nTask 3: UPDATE src/routes/index.ts ✅\n```\n\n### 2.5 Handle Deviations\n\nIf you must deviate from the plan:\n\n1. **Document WHAT** changed\n2. **Document WHY** it changed\n3. **Continue** with the deviation noted\n\nCommon reasons for deviation:\n- Pattern file has changed since plan was created\n- Missing import discovered\n- Type incompatibility requires different approach\n- Better solution discovered during implementation\n\n**PHASE_2_CHECKPOINT (per task):**\n\n- [ ] Task implemented\n- [ ] Type-check passes\n- [ ] Progress logged\n- [ ] Deviations documented (if any)\n\n---\n\n## Phase 3: TESTS - Write Required Tests\n\n### 3.1 Test Requirements\n\nEvery new function/feature needs at least one test:\n\n- **New file created** → Create corresponding test file\n- **New function added** → Add test for that function\n- **Behavior changed** → Update existing tests\n\n### 3.2 Follow Test Patterns\n\nFind existing test files to mirror:\n\n```bash\nfind . -name \"*.test.ts\" -type f | head -5\n```\n\nRead a relevant test file to understand the project's test patterns.\n\n### 3.3 Write Tests\n\nFor each new/changed file, write tests that cover:\n\n1. **Happy path** - Normal expected behavior\n2. **Edge cases** - Boundary conditions from the plan\n3. **Error cases** - What happens with bad input\n\n### 3.4 Run Tests\n\n```bash\n{runner} test\n```\n\n**If tests fail:**\n\n1. Determine: bug in implementation or bug in test?\n2. Fix the actual issue (usually implementation)\n3. Re-run tests\n4. Repeat until green\n\n**PHASE_3_CHECKPOINT:**\n\n- [ ] Tests written for new code\n- [ ] All tests pass\n\n---\n\n## Phase 4: ARTIFACT - Write Implementation Progress\n\n### 4.1 Write Progress Artifact\n\nWrite to `$ARTIFACTS_DIR/implementation.md`:\n\n```markdown\n# Implementation Progress\n\n**Generated**: {YYYY-MM-DD HH:MM}\n**Workflow ID**: $WORKFLOW_ID\n**Status**: {COMPLETE | IN_PROGRESS | BLOCKED}\n\n---\n\n## Tasks Completed\n\n| # | Task | File | Status | Notes |\n|---|------|------|--------|-------|\n| 1 | {description} | `src/x.ts` | ✅ | |\n| 2 | {description} | `src/y.ts` | ✅ | |\n| 3 | {description} | `src/z.ts` | ✅ | Minor deviation - see below |\n\n**Progress**: {X} of {Y} tasks completed\n\n---\n\n## Files Changed\n\n| File | Action | Lines |\n|------|--------|-------|\n| `src/new-file.ts` | CREATE | +{N} |\n| `src/existing.ts` | UPDATE | +{N}/-{M} |\n\n---\n\n## Tests Written\n\n| Test File | Test Cases |\n|-----------|------------|\n| `src/x.test.ts` | `should do X`, `should handle Y` |\n| `src/y.test.ts` | `creates correctly`, `validates input` |\n\n---\n\n## Deviations from Plan\n\n{If none:}\nNo deviations. Implementation matched the plan exactly.\n\n{If any:}\n### Deviation 1: {brief title}\n\n**Task**: {which task}\n**Expected**: {what plan said}\n**Actual**: {what was done}\n**Reason**: {why the change was necessary}\n\n---\n\n## Type-Check Status\n\n- [x] Passes after all changes\n\n---\n\n## Test Status\n\n- [x] All tests pass\n- Tests added: {N}\n- Tests modified: {M}\n\n---\n\n## Issues Encountered\n\n{If none:}\nNo issues encountered.\n\n{If any:}\n### Issue 1: {title}\n\n**Problem**: {description}\n**Resolution**: {how it was fixed}\n\n---\n\n## Next Step\n\nContinue to `archon-validate` for full validation suite.\n```\n\n**PHASE_4_CHECKPOINT:**\n\n- [ ] Implementation artifact written\n- [ ] All tasks documented\n- [ ] Deviations noted\n- [ ] Test status recorded\n\n---\n\n## Phase 5: OUTPUT - Report Progress\n\n```markdown\n## Implementation Complete\n\n**Workflow ID**: `$WORKFLOW_ID`\n**Status**: ✅ All tasks executed\n\n### Progress Summary\n\n| Metric | Count |\n|--------|-------|\n| Tasks completed | {X}/{Y} |\n| Files created | {N} |\n| Files updated | {M} |\n| Tests written | {K} |\n\n### Type-Check\n\n✅ Passes\n\n### Tests\n\n✅ All pass ({N} tests)\n\n{If deviations:}\n### Deviations\n\n{count} deviation(s) from plan documented in artifact.\n\n### Artifact\n\nProgress written to: `$ARTIFACTS_DIR/implementation.md`\n\n### Next Step\n\nProceed to `archon-validate` for full validation (lint, build, integration tests).\n```\n\n---\n\n## Error Handling\n\n### Type-Check Fails\n\nDo NOT proceed to next task. Fix the issue:\n\n1. Read the error carefully\n2. Identify the file and line\n3. Fix the type issue\n4. Re-run type-check\n5. Only continue when green\n\n### Test Fails\n\n1. Read the failure output\n2. Identify: implementation bug or test bug?\n3. Fix the root cause\n4. Re-run tests\n\n### Pattern File Changed\n\nIf a pattern file has changed since the plan was created:\n\n1. Read the current version\n2. Adapt the implementation to match current patterns\n3. Document as a deviation\n4. Continue\n\n### Task Unclear\n\nIf a task description is ambiguous:\n\n1. Check the plan's context sections for clarity\n2. Look at the MIRROR file for guidance\n3. Make a reasonable decision\n4. Document the interpretation as a deviation\n\n---\n\n## Success Criteria\n\n- **TASKS_COMPLETE**: All tasks from plan executed\n- **TYPES_PASS**: Type-check passes after all changes\n- **TESTS_WRITTEN**: New code has tests\n- **TESTS_PASS**: All tests green\n- **DEVIATIONS_DOCUMENTED**: Any plan deviations noted\n- **ARTIFACT_WRITTEN**: Implementation progress artifact created\n",
+  "archon-implement": "---\ndescription: Execute an implementation plan with rigorous validation loops\nargument-hint: <path/to/plan.md or GitHub issue URL>\n---\n\n# Implement Plan\n\n**Plan**: $ARGUMENTS\n\n---\n\n## Your Mission\n\nExecute the plan end-to-end with rigorous self-validation. You are autonomous.\n\n**Core Philosophy**: Validation loops catch mistakes early. Run checks after every change. Fix issues immediately. The goal is a working implementation, not just code that exists.\n\n**Golden Rule**: If a validation fails, fix it before moving on. Never accumulate broken state.\n\n---\n\n## Phase 0: DETECT - Project Environment\n\n### 0.1 Identify Package Manager\n\nCheck for these files to determine the project's toolchain:\n\n| File Found | Package Manager | Runner |\n|------------|-----------------|--------|\n| `bun.lockb` | bun | `bun` / `bun run` |\n| `pnpm-lock.yaml` | pnpm | `pnpm` / `pnpm run` |\n| `yarn.lock` | yarn | `yarn` / `yarn run` |\n| `package-lock.json` | npm | `npm run` |\n| `pyproject.toml` | uv/pip | `uv run` / `python` |\n| `Cargo.toml` | cargo | `cargo` |\n| `go.mod` | go | `go` |\n\n**Store the detected runner** - use it for all subsequent commands.\n\n### 0.2 Identify Validation Scripts\n\nCheck `package.json` (or equivalent) for available scripts:\n- Type checking: `type-check`, `typecheck`, `tsc`\n- Linting: `lint`, `lint:fix`\n- Testing: `test`, `test:unit`, `test:integration`\n- Building: `build`, `compile`\n\n**Use the plan's \"Validation Commands\" section** - it should specify exact commands for this project.\n\n---\n\n## Phase 1: LOAD - Read the Plan\n\n### 1.1 Load Plan File\n\n```bash\ncat $ARGUMENTS\n```\n\nIf `$ARGUMENTS` is a GitHub issue URL or number (e.g., `#123`), fetch the issue body which contains the plan.\n\n### 1.2 Extract Key Sections\n\nLocate and understand:\n\n- **Summary** - What we're building\n- **Patterns to Mirror** - Code to copy from\n- **Files to Change** - CREATE/UPDATE list\n- **Step-by-Step Tasks** - Implementation order\n- **Validation Commands** - How to verify (USE THESE, not hardcoded commands)\n- **Acceptance Criteria** - Definition of done\n\n### 1.3 Validate Plan Exists\n\n**If plan not found:**\n\n```\nError: Plan not found at $ARGUMENTS\n\nProvide a valid plan path or GitHub issue containing the plan.\n```\n\n**PHASE_1_CHECKPOINT:**\n\n- [ ] Plan file loaded\n- [ ] Key sections identified\n- [ ] Tasks list extracted\n\n---\n\n## Phase 2: PREPARE - Git State\n\n### 2.1 Check Current State\n\n```bash\n# What branch are we on?\ngit branch --show-current\n\n# Are we in a worktree?\ngit rev-parse --show-toplevel\ngit worktree list\n\n# Is working directory clean?\ngit status --porcelain\n```\n\n### 2.2 Branch Decision\n\n```text\n┌─ IN WORKTREE?\n│  └─ YES → Use current branch AS-IS. Do NOT switch branches. Do NOT create\n│           new branches. The isolation system has already set up the correct\n│           branch; any deviation operates on the wrong code.\n│           Log: \"Using worktree at {path} on branch {branch}\"\n│\n├─ ON $BASE_BRANCH? (main, master, or configured base branch)\n│  └─ Q: Working directory clean?\n│     ├─ YES → Create branch: git checkout -b feature/{plan-slug}\n│     │        (only applies outside a worktree — e.g., manual CLI usage)\n│     └─ NO  → STOP: \"Stash or commit changes first\"\n│\n├─ ON OTHER BRANCH?\n│  └─ Use it AS-IS. Do NOT switch to another branch (e.g., one shown by\n│     `git branch` but not currently checked out).\n│     Log: \"Using existing branch {name}\"\n│\n└─ DIRTY STATE?\n   └─ STOP: \"Stash or commit changes first\"\n```\n\n### 2.3 Sync with Remote\n\n```bash\ngit fetch origin\ngit pull --rebase origin $BASE_BRANCH 2>/dev/null || true\n```\n\n**PHASE_2_CHECKPOINT:**\n\n- [ ] On correct branch (not $BASE_BRANCH with uncommitted work)\n- [ ] Working directory ready\n- [ ] Up to date with remote\n\n---\n\n## Phase 3: EXECUTE - Implement Tasks\n\n**For each task in the plan's Step-by-Step Tasks section:**\n\n### 3.1 Read Context\n\n1. Read the **MIRROR** file reference from the task\n2. Understand the pattern to follow\n3. Read any **IMPORTS** specified\n\n### 3.2 Implement\n\n1. Make the change exactly as specified\n2. Follow the pattern from MIRROR reference\n3. Handle any **GOTCHA** warnings\n\n### 3.3 Validate Immediately\n\n**After EVERY file change, run the type-check command from the plan's Validation Commands section.**\n\nCommon patterns:\n- `{runner} run type-check` (JS/TS projects)\n- `mypy .` (Python)\n- `cargo check` (Rust)\n- `go build ./...` (Go)\n\n**If types fail:**\n\n1. Read the error\n2. Fix the issue\n3. Re-run type-check\n4. Only proceed when passing\n\n### 3.4 Track Progress\n\nLog each task as you complete it:\n\n```\nTask 1: CREATE src/features/x/models.ts ✅\nTask 2: CREATE src/features/x/service.ts ✅\nTask 3: UPDATE src/routes/index.ts ✅\n```\n\n**Deviation Handling:**\nIf you must deviate from the plan:\n\n- Note WHAT changed\n- Note WHY it changed\n- Continue with the deviation documented\n\n**PHASE_3_CHECKPOINT:**\n\n- [ ] All tasks executed in order\n- [ ] Each task passed type-check\n- [ ] Deviations documented\n\n---\n\n## Phase 4: VALIDATE - Full Verification\n\n### 4.1 Static Analysis\n\n**Run the type-check and lint commands from the plan's Validation Commands section.**\n\nCommon patterns:\n- JS/TS: `{runner} run type-check && {runner} run lint`\n- Python: `ruff check . && mypy .`\n- Rust: `cargo check && cargo clippy`\n- Go: `go vet ./...`\n\n**Must pass with zero errors.**\n\nIf lint errors:\n\n1. Run the lint fix command (e.g., `{runner} run lint:fix`, `ruff check --fix .`)\n2. Re-check\n3. Manual fix remaining issues\n\n### 4.2 Unit Tests\n\n**You MUST write or update tests for new code.** This is not optional.\n\n**Test requirements:**\n\n1. Every new function/feature needs at least one test\n2. Edge cases identified in the plan need tests\n3. Update existing tests if behavior changed\n\n**Write tests**, then run the test command from the plan.\n\nCommon patterns:\n- JS/TS: `{runner} test` or `{runner} run test`\n- Python: `pytest` or `uv run pytest`\n- Rust: `cargo test`\n- Go: `go test ./...`\n\n**If tests fail:**\n\n1. Read failure output\n2. Determine: bug in implementation or bug in test?\n3. Fix the actual issue\n4. Re-run tests\n5. Repeat until green\n\n### 4.3 Build Check\n\n**Run the build command from the plan's Validation Commands section.**\n\nCommon patterns:\n- JS/TS: `{runner} run build`\n- Python: N/A (interpreted) or `uv build`\n- Rust: `cargo build --release`\n- Go: `go build ./...`\n\n**Must complete without errors.**\n\n### 4.4 Integration Testing (if applicable)\n\n**If the plan involves API/server changes, use the integration test commands from the plan.**\n\nExample pattern:\n```bash\n# Start server in background (command varies by project)\n{runner} run dev &\nSERVER_PID=$!\nsleep 3\n\n# Test endpoints (adjust URL/port per project config)\ncurl -s http://localhost:{port}/health | jq\n\n# Stop server\nkill $SERVER_PID\n```\n\n### 4.5 Edge Case Testing\n\nRun any edge case tests specified in the plan.\n\n**PHASE_4_CHECKPOINT:**\n\n- [ ] Type-check passes (command from plan)\n- [ ] Lint passes (0 errors)\n- [ ] Tests pass (all green)\n- [ ] Build succeeds\n- [ ] Integration tests pass (if applicable)\n\n---\n\n## Phase 5: REPORT - Create Implementation Report\n\n### 5.1 Create Report Directory\n\n```bash\nmkdir -p $ARTIFACTS_DIR/../reports\n```\n\n### 5.2 Generate Report\n\n**Path**: `$ARTIFACTS_DIR/../reports/{plan-name}-report.md`\n\n```markdown\n# Implementation Report\n\n**Plan**: `$ARGUMENTS`\n**Source Issue**: #{number} (if applicable)\n**Branch**: `{branch-name}`\n**Date**: {YYYY-MM-DD}\n**Status**: {COMPLETE | PARTIAL}\n\n---\n\n## Summary\n\n{Brief description of what was implemented}\n\n---\n\n## Assessment vs Reality\n\nCompare the original plan's assessment with what actually happened:\n\n| Metric     | Predicted   | Actual   | Reasoning                                                                      |\n| ---------- | ----------- | -------- | ------------------------------------------------------------------------------ |\n| Complexity | {from plan} | {actual} | {Why it matched or differed - e.g., \"discovered additional integration point\"} |\n| Confidence | {from plan} | {actual} | {e.g., \"root cause was correct\" or \"had to pivot because X\"}                   |\n\n**If implementation deviated from the plan, explain why:**\n\n- {What changed and why - based on what you discovered during implementation}\n\n---\n\n## Tasks Completed\n\n| #   | Task               | File       | Status |\n| --- | ------------------ | ---------- | ------ |\n| 1   | {task description} | `src/x.ts` | ✅     |\n| 2   | {task description} | `src/y.ts` | ✅     |\n\n---\n\n## Validation Results\n\n| Check       | Result | Details               |\n| ----------- | ------ | --------------------- |\n| Type check  | ✅     | No errors             |\n| Lint        | ✅     | 0 errors, N warnings  |\n| Unit tests  | ✅     | X passed, 0 failed    |\n| Build       | ✅     | Compiled successfully |\n| Integration | ✅/⏭️  | {result or \"N/A\"}     |\n\n---\n\n## Files Changed\n\n| File       | Action | Lines     |\n| ---------- | ------ | --------- |\n| `src/x.ts` | CREATE | +{N}      |\n| `src/y.ts` | UPDATE | +{N}/-{M} |\n\n---\n\n## Deviations from Plan\n\n{List any deviations with rationale, or \"None\"}\n\n---\n\n## Issues Encountered\n\n{List any issues and how they were resolved, or \"None\"}\n\n---\n\n## Tests Written\n\n| Test File       | Test Cases               |\n| --------------- | ------------------------ |\n| `src/x.test.ts` | {list of test functions} |\n\n---\n\n## Next Steps\n\n- [ ] Review implementation\n- [ ] Create PR (next step in workflow)\n- [ ] Merge when approved\n```\n\n### 5.3 Archive Plan\n\n```bash\nmkdir -p $ARTIFACTS_DIR/../plans/completed\ncp $ARGUMENTS $ARTIFACTS_DIR/../plans/completed/ 2>/dev/null || true\n```\n\n**PHASE_5_CHECKPOINT:**\n\n- [ ] Report created at `$ARTIFACTS_DIR/../reports/`\n- [ ] Plan copied to completed folder (if local file)\n\n---\n\n## Phase 6: OUTPUT - Report to User\n\n```markdown\n## Implementation Complete\n\n**Plan**: `$ARGUMENTS`\n**Source Issue**: #{number} (if applicable)\n**Branch**: `{branch-name}`\n**Status**: ✅ Complete\n\n### Validation Summary\n\n| Check      | Result          |\n| ---------- | --------------- |\n| Type check | ✅              |\n| Lint       | ✅              |\n| Tests      | ✅ ({N} passed) |\n| Build      | ✅              |\n\n### Files Changed\n\n- {N} files created\n- {M} files updated\n- {K} tests written\n\n### Deviations\n\n{If none: \"Implementation matched the plan.\"}\n{If any: Brief summary of what changed and why}\n\n### Artifacts\n\n- Report: `$ARTIFACTS_DIR/../reports/{name}-report.md`\n\n### Next Steps\n\n1. Review the report (especially if deviations noted)\n2. Create PR (next workflow step)\n3. Merge when approved\n```\n\n---\n\n## Handling Failures\n\n### Type Check Fails\n\n1. Read error message carefully\n2. Fix the type issue\n3. Re-run the type-check command\n4. Don't proceed until passing\n\n### Tests Fail\n\n1. Identify which test failed\n2. Determine: implementation bug or test bug?\n3. Fix the root cause (usually implementation)\n4. Re-run tests\n5. Repeat until green\n\n### Lint Fails\n\n1. Run the lint fix command for auto-fixable issues\n2. Manually fix remaining issues\n3. Re-run lint\n4. Proceed when clean\n\n### Build Fails\n\n1. Usually a type or import issue\n2. Check the error output\n3. Fix and re-run\n\n### Integration Test Fails\n\n1. Check if server started correctly\n2. Verify endpoint exists\n3. Check request format\n4. Fix implementation and retry\n\n---\n\n## Success Criteria\n\n- **TASKS_COMPLETE**: All plan tasks executed\n- **TYPES_PASS**: Type-check command exits 0\n- **LINT_PASS**: Lint command exits 0 (warnings OK)\n- **TESTS_PASS**: Test command all green\n- **BUILD_PASS**: Build command succeeds\n- **REPORT_CREATED**: Implementation report exists\n",
+  "archon-investigate-issue": "---\ndescription: Investigate a GitHub issue or problem - analyze codebase, create plan, post to GitHub\nargument-hint: <issue-number|url|\"description\">\n---\n\n# Investigate Issue\n\n**Input**: $ARGUMENTS\n\n---\n\n## Your Mission\n\nInvestigate the issue/problem and produce a comprehensive implementation plan that:\n\n1. Can be executed by `/implement-issue`\n2. Is posted as a GitHub comment (if GH issue provided)\n3. Captures all context needed for one-pass implementation\n\n**Golden Rule**: The artifact you produce IS the specification. The implementing agent should be able to work from it without asking questions.\n\n---\n\n## Phase 1: PARSE - Understand Input\n\n### 1.1 Determine Input Type\n\n**Check the input format:**\n\n- Looks like a number (`123`, `#123`) → GitHub issue number\n- Starts with `http` → GitHub URL (extract issue number)\n- Anything else → Free-form description\n\n```bash\n# If GitHub issue, fetch it:\ngh issue view {number} --json title,body,labels,comments,state,url,author\n```\n\n### 1.2 Extract Context\n\n**If GitHub issue:**\n- Title: What's the reported problem?\n- Body: Details, reproduction steps, expected vs actual\n- Labels: bug? enhancement? documentation?\n- Comments: Additional context from discussion\n- State: Is it still open?\n\n**If free-form:**\n- Parse as problem description\n- Note: No GitHub posting (artifact only)\n\n### 1.3 Classify Issue Type\n\n| Type | Indicators |\n|------|------------|\n| BUG | \"broken\", \"error\", \"crash\", \"doesn't work\", stack trace |\n| ENHANCEMENT | \"add\", \"support\", \"feature\", \"would be nice\" |\n| REFACTOR | \"clean up\", \"improve\", \"simplify\", \"reorganize\" |\n| CHORE | \"update\", \"upgrade\", \"maintenance\", \"dependency\" |\n| DOCUMENTATION | \"docs\", \"readme\", \"clarify\", \"example\" |\n\n### 1.4 Assess Severity/Priority, Complexity, and Confidence\n\nEach assessment requires a **one-sentence reasoning** explaining WHY you chose that value. This reasoning must be based on concrete findings from your investigation (codebase exploration, git history, integration analysis).\n\n**For BUG issues - Severity:**\n\n| Severity | Criteria |\n|----------|----------|\n| CRITICAL | System down, data loss, security vulnerability, no workaround |\n| HIGH | Major feature broken, significant user impact, difficult workaround |\n| MEDIUM | Feature partially broken, moderate impact, workaround exists |\n| LOW | Minor issue, cosmetic, edge case, easy workaround |\n\n**For ENHANCEMENT/REFACTOR/CHORE/DOCUMENTATION - Priority:**\n\n| Priority | Criteria |\n|----------|----------|\n| HIGH | Blocking other work, frequently requested, high user value |\n| MEDIUM | Important but not urgent, moderate user value |\n| LOW | Nice to have, low urgency, minimal user impact |\n\n**Complexity** (based on codebase findings):\n\n| Complexity | Criteria |\n|------------|----------|\n| HIGH | 5+ files, multiple integration points, architectural changes, high risk |\n| MEDIUM | 2-4 files, some integration points, moderate risk |\n| LOW | 1-2 files, isolated change, low risk |\n\n**Confidence** (based on evidence quality):\n\n| Confidence | Criteria |\n|------------|----------|\n| HIGH | Clear root cause, strong evidence, well-understood code path |\n| MEDIUM | Likely root cause, some assumptions, partially understood |\n| LOW | Uncertain root cause, limited evidence, many unknowns |\n\n**PHASE_1_CHECKPOINT:**\n- [ ] Input type identified (GH issue or free-form)\n- [ ] Issue content extracted\n- [ ] Type classified\n- [ ] Severity (bug) or Priority (other) assessed with reasoning\n- [ ] Complexity assessed with reasoning (after Phase 2)\n- [ ] Confidence assessed with reasoning (after Phase 3)\n- [ ] If GH issue: confirmed it's open and not already has PR\n\n---\n\n## Phase 2: EXPLORE - Codebase Intelligence\n\n### 2.1 Search for Relevant Code\n\nUse Task tool with subagent_type=\"Explore\":\n\n```\nExplore the codebase to understand the issue:\n\nISSUE: {title/description}\n\nDISCOVER:\n1. Files directly related to this functionality\n2. How the current implementation works\n3. Integration points - what calls this, what it calls\n4. Similar patterns elsewhere to mirror\n5. Existing test patterns for this area\n6. Error handling patterns used\n\nReturn:\n- File paths with specific line numbers\n- Actual code snippets (not summaries)\n- Dependencies and data flow\n```\n\n### 2.2 Document Findings\n\n| Area | File:Lines | Notes |\n|------|-----------|-------|\n| Core logic | `src/x.ts:10-50` | Main function affected |\n| Callers | `src/y.ts:20-30` | Uses the core function |\n| Types | `src/types/x.ts:5-15` | Relevant interfaces |\n| Tests | `src/x.test.ts:1-100` | Existing test patterns |\n| Similar | `src/z.ts:40-60` | Pattern to mirror |\n\n**PHASE_2_CHECKPOINT:**\n- [ ] Explore agent completed successfully\n- [ ] Core files identified with line numbers\n- [ ] Integration points mapped\n- [ ] Similar patterns found to mirror\n- [ ] Test patterns documented\n\n---\n\n## Phase 3: ANALYZE - Form Approach\n\n### 3.0 First-Principles Analysis\n\nBefore diving into bug analysis or enhancement scoping, identify the primitive:\n\n1. **What primitive is involved?** What is the core abstraction this bug/feature touches?\n   (e.g., the condition evaluator, the approval system, the isolation provider)\n2. **Is the primitive sound?** Does the existing design handle this case, or is the\n   primitive itself incomplete or missing a case?\n3. **Root cause vs symptom** — are we fixing where the error manifests, or where it\n   originates? Trace the data flow back to the source.\n4. **What's the minimal change?** What is the smallest edit that fixes the root cause?\n   Avoid adding new abstractions when extending existing ones works.\n5. **What does this unlock?** If we add/change a primitive, what other improvements\n   become possible?\n\n| Primitive | File:Lines | Sound? | Notes |\n|-----------|-----------|--------|-------|\n| {abstraction name} | `src/x.ts:10-30` | Yes/No/Partial | {if incomplete: what's missing} |\n\n### 3.1 For BUG Issues - Root Cause Analysis\n\nApply the 5 Whys:\n\n```\nWHY 1: Why does [symptom] occur?\n→ Because [cause A]\n→ Evidence: `file.ts:123` - {code snippet}\n\nWHY 2: Why does [cause A] happen?\n→ Because [cause B]\n→ Evidence: {proof}\n\n... continue until you reach fixable code ...\n\nROOT CAUSE: [the specific code/logic to change]\nEvidence: `source.ts:456` - {the problematic code}\n```\n\n**Check git history:**\n```bash\ngit log --oneline -10 -- {affected-file}\ngit blame -L {start},{end} {affected-file}\n```\n\n### 3.2 For ENHANCEMENT/REFACTOR Issues\n\n**Identify:**\n- What needs to be added/changed?\n- Where does it integrate?\n- What are the scope boundaries?\n- What should NOT be changed?\n\n### 3.3 For All Issues\n\n**Determine:**\n- Files to CREATE (new files)\n- Files to UPDATE (existing files)\n- Files to DELETE (if any)\n- Dependencies and order of changes\n- Edge cases and risks\n- Validation strategy\n\n**PHASE_3_CHECKPOINT:**\n- [ ] Root cause identified (for bugs) OR change rationale clear (for enhancements)\n- [ ] All affected files listed with specific changes\n- [ ] Scope boundaries defined (what NOT to change)\n- [ ] Risks and edge cases identified\n- [ ] Validation approach defined\n\n---\n\n## Phase 4: GENERATE - Create Artifact\n\n### 4.1 Artifact Path\n\n```bash\n```\n\n**Path:** `$ARTIFACTS_DIR/investigation.md`\n\nThis unified path allows review agents to find the artifact regardless of workflow type.\n\n### 4.2 Artifact Template\n\nWrite this structure to the artifact file.\n\n**Note on Severity vs Priority:**\n- Use **Severity** for BUG type (CRITICAL, HIGH, MEDIUM, LOW)\n- Use **Priority** for all other types (HIGH, MEDIUM, LOW)\n\n**Important:** Each assessment must include a one-sentence reasoning based on your investigation findings.\n\n```markdown\n# Investigation: {Title}\n\n**Issue**: #{number} ({url})\n**Type**: {BUG|ENHANCEMENT|REFACTOR|CHORE|DOCUMENTATION}\n**Investigated**: {ISO timestamp}\n\n### Assessment\n\n| Metric | Value | Reasoning |\n|--------|-------|-----------|\n| Severity | {CRITICAL\\|HIGH\\|MEDIUM\\|LOW} | {Why this severity? Based on user impact, workarounds, scope of failure} |\n| Complexity | {LOW\\|MEDIUM\\|HIGH} | {Why this complexity? Based on files affected, integration points, risk} |\n| Confidence | {HIGH\\|MEDIUM\\|LOW} | {Why this confidence? Based on evidence quality, unknowns, assumptions} |\n\n<!-- For non-BUG types, replace Severity row with Priority:\n| Priority | {HIGH\\|MEDIUM\\|LOW} | {Why this priority? Based on user value, blocking status, frequency} |\n-->\n\n---\n\n## Problem Statement\n\n{Clear 2-3 sentence description of what's wrong or what's needed}\n\n---\n\n## Analysis\n\n### Root Cause / Change Rationale\n\n{For BUG: The 5 Whys chain with evidence}\n{For ENHANCEMENT: Why this change and what it enables}\n\n### Evidence Chain\n\nWHY: {symptom}\n↓ BECAUSE: {cause 1}\n  Evidence: `file.ts:123` - `{code snippet}`\n\n↓ BECAUSE: {cause 2}\n  Evidence: `file.ts:456` - `{code snippet}`\n\n↓ ROOT CAUSE: {the fixable thing}\n  Evidence: `file.ts:789` - `{problematic code}`\n\n### Affected Files\n\n| File | Lines | Action | Description |\n|------|-------|--------|-------------|\n| `src/x.ts` | 45-60 | UPDATE | {what changes} |\n| `src/x.test.ts` | NEW | CREATE | {test to add} |\n\n### Integration Points\n\n- `src/y.ts:20` calls this function\n- `src/z.ts:30` depends on this behavior\n- {other dependencies}\n\n### Git History\n\n- **Introduced**: {commit} - {date} - \"{message}\"\n- **Last modified**: {commit} - {date}\n- **Implication**: {regression? original bug? long-standing?}\n\n---\n\n## Implementation Plan\n\n### Step 1: {First change description}\n\n**File**: `src/x.ts`\n**Lines**: 45-60\n**Action**: UPDATE\n\n**Current code:**\n```typescript\n// Line 45-50\n{actual current code}\n```\n\n**Required change:**\n```typescript\n// What it should become\n{the fix/change}\n```\n\n**Why**: {brief rationale}\n\n---\n\n### Step 2: {Second change description}\n\n{Same structure...}\n\n---\n\n### Step N: Add/Update Tests\n\n**File**: `src/x.test.ts`\n**Action**: {CREATE|UPDATE}\n\n**Test cases to add:**\n```typescript\ndescribe('{feature}', () => {\n  it('should {expected behavior}', () => {\n    // Test the fix\n  });\n\n  it('should handle {edge case}', () => {\n    // Test edge case\n  });\n});\n```\n\n---\n\n## Patterns to Follow\n\n**From codebase - mirror these exactly:**\n\n```typescript\n// SOURCE: src/similar.ts:20-30\n// Pattern for {what this demonstrates}\n{actual code snippet from codebase}\n```\n\n---\n\n## Edge Cases & Risks\n\n| Risk/Edge Case | Mitigation |\n|----------------|------------|\n| {risk 1} | {how to handle} |\n| {edge case} | {how to handle} |\n\n---\n\n## Validation\n\n### Automated Checks\n\n```bash\nbun run type-check\nbun test {relevant-pattern}\nbun run lint\n```\n\n### Manual Verification\n\n1. {Step to verify the fix/feature works}\n2. {Step to verify no regression}\n\n---\n\n## Scope Boundaries\n\n**IN SCOPE:**\n- {what we're changing}\n\n**OUT OF SCOPE (do not touch):**\n- {what to leave alone}\n- {future improvements to defer}\n\n---\n\n## Metadata\n\n- **Investigated by**: Claude\n- **Timestamp**: {ISO timestamp}\n- **Artifact**: `$ARTIFACTS_DIR/investigation.md`\n```\n\n**PHASE_4_CHECKPOINT:**\n- [ ] Artifact file created\n- [ ] All sections filled with specific content\n- [ ] Code snippets are actual (not invented)\n- [ ] Steps are actionable without clarification\n\n---\n\n## Phase 5: POST - GitHub Comment\n\n**Only if input was a GitHub issue (not free-form):**\n\nFormat the artifact for GitHub and post:\n\n```bash\ngh issue comment {number} --body \"$(cat <<'EOF'\n## 🔍 Investigation: {Title}\n\n**Type**: `{TYPE}`\n\n### Assessment\n\n| Metric | Value | Reasoning |\n|--------|-------|-----------|\n| {Severity or Priority} | `{VALUE}` | {one-sentence why} |\n| Complexity | `{COMPLEXITY}` | {one-sentence why} |\n| Confidence | `{CONFIDENCE}` | {one-sentence why} |\n\n---\n\n### Problem Statement\n\n{problem statement from artifact}\n\n---\n\n### Root Cause Analysis\n\n{evidence chain, formatted for GitHub}\n\n---\n\n### Implementation Plan\n\n| Step | File | Change |\n|------|------|--------|\n| 1 | `src/x.ts:45` | {description} |\n| 2 | `src/x.test.ts` | Add test for {case} |\n\n<details>\n<summary>📋 Detailed Implementation Steps</summary>\n\n{detailed steps from artifact}\n\n</details>\n\n---\n\n### Validation\n\n```bash\nbun run type-check && bun test {pattern} && bun run lint\n```\n\n---\n\n### Next Step\n\nTo implement: `/implement-issue {number}`\n\n---\n*Investigated by Claude • {timestamp}*\nEOF\n)\"\n```\n\n**PHASE_5_CHECKPOINT:**\n- [ ] Comment posted to GitHub (if GH issue)\n- [ ] Formatting renders correctly\n\n---\n\n## Phase 6: REPORT - Output to User\n\n```markdown\n## Investigation Complete\n\n**Issue**: #{number} - {title}\n**Type**: {BUG|ENHANCEMENT|REFACTOR|...}\n\n### Assessment\n\n| Metric | Value | Reasoning |\n|--------|-------|-----------|\n| {Severity or Priority} | {value} | {why - based on investigation} |\n| Complexity | {LOW\\|MEDIUM\\|HIGH} | {why - based on files/integration/risk} |\n| Confidence | {HIGH\\|MEDIUM\\|LOW} | {why - based on evidence/unknowns} |\n\n### Key Findings\n\n- **Root Cause**: {one-line summary}\n- **Files Affected**: {count} files\n- **Estimated Changes**: {brief scope}\n\n### Files to Modify\n\n| File | Action |\n|------|--------|\n| `src/x.ts` | UPDATE |\n| `src/x.test.ts` | CREATE |\n\n### Artifact\n\n📄 `$ARTIFACTS_DIR/investigation.md`\n\n### GitHub\n\n{✅ Posted to issue | ⏭️ Skipped (free-form input)}\n\n### Next Step\n\nRun `/implement-issue {number}` to execute the plan.\n```\n\n---\n\n## Handling Edge Cases\n\n### Issue is already closed\n- Report: \"Issue #{number} is already closed\"\n- Still create artifact if user wants analysis\n\n### Issue already has linked PR\n- Warn: \"PR #{pr} already addresses this issue\"\n- Ask if user wants to continue anyway\n\n### Can't determine root cause\n- Document what you found\n- Set confidence to LOW\n- Note uncertainty in artifact\n- Proceed with best hypothesis\n\n### Very large scope\n- Suggest breaking into smaller issues\n- Focus on core problem first\n- Note deferred items in \"Out of Scope\"\n\n---\n\n## Success Criteria\n\n- **ARTIFACT_COMPLETE**: All sections filled with specific, actionable content\n- **EVIDENCE_BASED**: Every claim has file:line reference or proof\n- **IMPLEMENTABLE**: Another agent can execute without questions\n- **GITHUB_POSTED**: Comment visible on issue (if GH issue)\n- **COMMITTED**: Artifact saved in git\n",
+  "archon-issue-completion-report": "---\ndescription: Post completion report to GitHub issue with results, unaddressed items, and follow-up suggestions\nargument-hint: (none - reads from workflow artifacts)\n---\n\n# Issue Completion Report\n\n**Input**: $ARGUMENTS\n**Workflow ID**: $WORKFLOW_ID\n\n---\n\n## Your Mission\n\nCompile all workflow artifacts into a final report and post it to the original GitHub issue. Summarize what was done, what wasn't addressed (and why), and suggest follow-up issues if needed.\n\n**GitHub action**: Post completion report as a comment on the original issue\n**Output artifact**: `$ARTIFACTS_DIR/completion-report.md`\n\n---\n\n## Phase 1: LOAD — Gather All Artifacts\n\n### 1.1 Get Issue Number\n\nExtract issue number from `$ARGUMENTS`:\n\n```bash\n# $ARGUMENTS should be the issue number or URL\necho \"$ARGUMENTS\"\n```\n\n### 1.2 Get PR Info\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number 2>/dev/null || echo \"unknown\")\nPR_URL=$(cat $ARTIFACTS_DIR/.pr-url 2>/dev/null || echo \"unknown\")\necho \"PR: $PR_NUMBER ($PR_URL)\"\n```\n\n### 1.3 Read All Available Artifacts\n\nCheck for and read each artifact that may exist:\n\n```bash\n# Investigation/Plan\ncat $ARTIFACTS_DIR/investigation.md 2>/dev/null\ncat $ARTIFACTS_DIR/plan.md 2>/dev/null\n\n# Implementation\ncat $ARTIFACTS_DIR/implementation.md 2>/dev/null\n\n# Web research\ncat $ARTIFACTS_DIR/web-research.md 2>/dev/null\n\n# Validation\ncat $ARTIFACTS_DIR/validation.md 2>/dev/null\n\n# Review artifacts\nls $ARTIFACTS_DIR/review/ 2>/dev/null\ncat $ARTIFACTS_DIR/review/consolidated-review.md 2>/dev/null\ncat $ARTIFACTS_DIR/review/fix-report.md 2>/dev/null\n```\n\n### 1.4 Get Git Info\n\n```bash\ngit branch --show-current\ngit log --oneline -5\n```\n\n**PHASE_1_CHECKPOINT:**\n\n- [ ] Issue number identified\n- [ ] PR info loaded\n- [ ] All available artifacts read\n- [ ] Git state captured\n\n---\n\n## Phase 2: COMPILE — Build Report\n\n### 2.1 Summarize What Was Done\n\nFrom the artifacts, compile:\n\n- **Classification**: What type of issue (bug/feature/etc)\n- **Investigation/Plan**: Key findings and approach\n- **Implementation**: What was changed, files modified\n- **Validation**: Test results, lint, type-check\n- **Review**: What was reviewed, findings count\n- **Self-fix**: What review findings were fixed\n\n### 2.2 Identify Unaddressed Items\n\nFrom the fix report and consolidated review:\n\n- Findings that were SKIPPED (with reasons)\n- Findings that were BLOCKED (with reasons)\n- MEDIUM/LOW findings not auto-fixed\n- Any validation issues that persisted\n\n### 2.3 Suggest Follow-up Issues\n\nFor each unaddressed item, determine if it warrants a follow-up issue:\n\n| Item | Warrants Issue? | Why |\n|------|----------------|-----|\n| {skipped finding} | YES/NO | {reason} |\n\n**PHASE_2_CHECKPOINT:**\n\n- [ ] Summary compiled\n- [ ] Unaddressed items identified\n- [ ] Follow-up suggestions prepared\n\n---\n\n## Phase 3: GENERATE — Write Artifact\n\nWrite to `$ARTIFACTS_DIR/completion-report.md`:\n\n```markdown\n# Completion Report: Issue $ARGUMENTS\n\n**Date**: {ISO timestamp}\n**Workflow ID**: $WORKFLOW_ID\n**PR**: #{pr-number} ({pr-url})\n\n---\n\n## Summary\n\n{3-5 sentence overview of the entire workflow execution}\n\n---\n\n## Classification\n\n| Field | Value |\n|-------|-------|\n| Type | {bug/feature/enhancement/...} |\n| Complexity | {LOW/MEDIUM/HIGH} |\n| Confidence | {HIGH/MEDIUM/LOW} |\n\n---\n\n## What Was Done\n\n### Investigation/Planning\n\n{Brief summary of root cause or plan}\n\n### Implementation\n\n| File | Action | Description |\n|------|--------|-------------|\n| `{file}` | {CREATE/UPDATE} | {what changed} |\n\n### Validation\n\n| Check | Result |\n|-------|--------|\n| Type check | ✅ / ❌ |\n| Lint | ✅ / ❌ |\n| Tests | ✅ ({n} passed) / ❌ |\n\n### Review & Self-Fix\n\n- **Findings**: {n} total from review agents\n- **Fixed**: {n} (including tests, docs, simplification)\n- **Skipped**: {n}\n- **Blocked**: {n}\n\n---\n\n## Unaddressed Items\n\n{If none: \"All findings were addressed.\"}\n\n### Skipped\n\n| Finding | Severity | Reason |\n|---------|----------|--------|\n| {title} | {sev} | {reason} |\n\n### Blocked\n\n| Finding | Severity | Reason |\n|---------|----------|--------|\n| {title} | {sev} | {reason} |\n\n---\n\n## Suggested Follow-up Issues\n\n| Title | Priority | Description |\n|-------|----------|-------------|\n| \"{title}\" | {P1/P2/P3} | {brief description} |\n\n*(none)* if everything was addressed\n\n---\n\n## Artifacts\n\n| Artifact | Path |\n|----------|------|\n| Investigation/Plan | `$ARTIFACTS_DIR/{investigation or plan}.md` |\n| Web Research | `$ARTIFACTS_DIR/web-research.md` |\n| Implementation | `$ARTIFACTS_DIR/implementation.md` |\n| Consolidated Review | `$ARTIFACTS_DIR/review/consolidated-review.md` |\n| Fix Report | `$ARTIFACTS_DIR/review/fix-report.md` |\n```\n\n**PHASE_3_CHECKPOINT:**\n\n- [ ] Completion report written\n\n---\n\n## Phase 4: POST — GitHub Issue Comment\n\nPost to the original GitHub issue:\n\n```bash\nISSUE_NUMBER=$(echo \"$ARGUMENTS\" | grep -oE '[0-9]+')\n\ngh issue comment $ISSUE_NUMBER --body \"$(cat <<'EOF'\n## ✅ Issue Resolution Report\n\n**PR**: #{pr-number} ({pr-url})\n**Status**: COMPLETE\n\n---\n\n### Summary\n\n{Brief overview of what was done to resolve this issue}\n\n---\n\n### Changes Made\n\n| File | Change |\n|------|--------|\n| `{file}` | {description} |\n\n---\n\n### Validation\n\n✅ Type check | ✅ Lint | ✅ Tests ({n} passed)\n\n---\n\n### Review & Self-Fix\n\n- **{n}** review findings addressed\n- **{n}** tests added\n- **{n}** docs updated\n- **{n}** code simplifications applied\n\n---\n\n### Unaddressed Items\n\n{If none: \"All review findings were addressed in the PR.\"}\n\n{If any:}\n\n| Finding | Severity | Reason |\n|---------|----------|--------|\n| {title} | {sev} | {why not addressed} |\n\n---\n\n### Suggested Follow-up Issues\n\n{If any:}\n\n1. **{Issue Title}** ({priority}) — {brief description}\n\n{If none: \"No follow-up issues needed.\"}\n\n---\n\n*Resolved by Archon workflow `$WORKFLOW_ID`*\nEOF\n)\"\n```\n\n**PHASE_4_CHECKPOINT:**\n\n- [ ] GitHub comment posted to issue\n\n---\n\n## Phase 5: OUTPUT — Final Summary\n\n```markdown\n## Issue Resolution Complete\n\n**Issue**: $ARGUMENTS\n**PR**: #{pr-number}\n**Workflow**: $WORKFLOW_ID\n\n### Results\n\n- Implementation: ✅\n- Validation: ✅\n- Review: ✅\n- Self-fix: ✅\n\n### Unaddressed: {n} items\n### Follow-up issues suggested: {n}\n\n### Artifacts\n\n- Completion report: `$ARTIFACTS_DIR/completion-report.md`\n- GitHub comment: Posted to issue\n\n### Next Steps\n\n1. Review the PR: #{pr-number}\n2. Create suggested follow-up issues if agreed\n3. Merge when ready\n```\n\n---\n\n## Success Criteria\n\n- **ALL_ARTIFACTS_READ**: All workflow artifacts loaded and parsed\n- **REPORT_COMPILED**: Comprehensive completion report written\n- **GITHUB_POSTED**: Comment posted to original issue\n- **UNADDRESSED_DOCUMENTED**: Clear reasons for anything not fixed\n- **FOLLOWUPS_SUGGESTED**: Actionable follow-up issues recommended where appropriate\n",
+  "archon-plan-setup": "---\ndescription: Setup for plan execution - read plan, ensure branch ready, write context artifact\nargument-hint: <path/to/plan.md>\n---\n\n# Plan Setup\n\n**Plan**: $ARGUMENTS\n**Workflow ID**: $WORKFLOW_ID\n\n---\n\n## Your Mission\n\nPrepare everything needed for plan implementation:\n1. Read and parse the plan (including scope limits)\n2. Ensure we're on the correct branch\n3. Write a comprehensive context artifact for subsequent steps\n\n**This step does NOT implement anything** - it only sets up the environment.\n**This step does NOT create a PR** - that happens in `archon-finalize-pr` after implementation.\n\n---\n\n## Phase 1: LOAD - Read the Plan\n\n### 1.1 Locate Plan File\n\n**Check in order:**\n\n1. **If `$ARGUMENTS` provided**: Use that path\n2. **If plan already in workflow artifacts**: Use `$ARTIFACTS_DIR/plan.md`\n\n```bash\n# Check if plan was created by archon-create-plan in this workflow\nif [ -f \"$ARTIFACTS_DIR/plan.md\" ]; then\n  PLAN_PATH=\"$ARTIFACTS_DIR/plan.md\"\n  echo \"Using plan from workflow: $PLAN_PATH\"\nelif [ -n \"$ARGUMENTS\" ] && [ -f \"$ARGUMENTS\" ]; then\n  PLAN_PATH=\"$ARGUMENTS\"\n  echo \"Using plan from arguments: $PLAN_PATH\"\nelse\n  echo \"ERROR: No plan found\"\n  exit 1\nfi\n```\n\n### 1.2 Load Plan File\n\nRead the plan file:\n\n```bash\ncat $PLAN_PATH\n```\n\nIf `$ARGUMENTS` is a GitHub issue URL or number (e.g., `#123`), fetch the issue body instead.\n\n### 1.3 Extract Key Information\n\nFrom the plan, identify and extract:\n\n| Field | Where to Find | Example |\n|-------|---------------|---------|\n| **Title** | First `#` heading or \"Summary\" section | \"Discord Platform Adapter\" |\n| **Summary** | \"Summary\" or \"Feature Description\" section | 1-2 sentence overview |\n| **Files to Change** | \"Files to Change\" or \"Tasks\" section | List of CREATE/UPDATE files |\n| **Validation Commands** | \"Validation Commands\" or \"Validation Strategy\" | `bun run type-check`, etc. |\n| **Acceptance Criteria** | \"Acceptance Criteria\" section | Checklist items |\n| **NOT Building (Scope Limits)** | \"NOT Building\", \"Scope Limits\", or \"Out of Scope\" section | Explicit exclusions |\n\n**CRITICAL**: The \"NOT Building\" section defines what is **intentionally excluded** from scope. This MUST be captured and passed to review agents so they don't flag intentional exclusions as bugs.\n\n### 1.4 Derive Branch Name\n\nCreate a branch name from the plan title:\n\n```\nfeature/{slug}\n```\n\nWhere `{slug}` is the title lowercased, spaces replaced with hyphens, max 50 chars.\n\nExamples:\n- \"Discord Platform Adapter\" → `feature/discord-platform-adapter`\n- \"ESLint/Prettier Integration\" → `feature/eslint-prettier-integration`\n\n**PHASE_1_CHECKPOINT:**\n\n- [ ] Plan file loaded and readable\n- [ ] Key information extracted\n- [ ] Branch name derived\n\n---\n\n## Phase 2: PREPARE - Git State\n\n### 2.1 Check Current State\n\n```bash\ngit branch --show-current\ngit status --porcelain\ngit remote get-url origin\n```\n\n### 2.2 Determine Repository Info\n\nExtract owner/repo from the remote URL for PR creation:\n\n```bash\ngh repo view --json nameWithOwner -q .nameWithOwner\n```\n\n### 2.3 Branch Decision\n\nEvaluate in order (first matching case wins):\n\n```text\n┌─ IN WORKTREE?\n│  └─ YES → Use current branch AS-IS. Do NOT switch branches. Do NOT create\n│           new branches. The isolation system has already set up the correct\n│           branch; any deviation operates on the wrong code.\n│           Log: \"Using worktree branch: {name}\"\n│\n├─ ON $BASE_BRANCH? (main, master, or configured base branch)\n│  └─ Q: Working directory clean?\n│     ├─ YES → Create and checkout: `git checkout -b {branch-name}`\n│     │        (only applies outside a worktree — e.g., manual CLI usage)\n│     └─ NO  → STOP: \"Uncommitted changes on $BASE_BRANCH. Stash or commit first.\"\n│\n└─ ON OTHER BRANCH?\n   └─ Q: Does it match the expected branch for this plan?\n      ├─ YES → Use it, log \"Using existing branch: {name}\"\n      └─ NO  → STOP: \"On branch {X}, expected {Y}. Switch branches or adjust plan.\"\n```\n\n### 2.4 Sync with Remote\n\n```bash\ngit fetch origin\ngit rebase origin/$BASE_BRANCH || git merge origin/$BASE_BRANCH\n```\n\nIf conflicts occur, STOP with error: \"Merge conflicts with $BASE_BRANCH. Resolve manually.\"\n\n### 2.5 Push Branch (if commits exist)\n\nIf there are commits on the branch:\n```bash\ngit push -u origin HEAD\n```\n\nIf no commits yet (fresh branch), skip push - it will happen after implementation.\n\n**PHASE_2_CHECKPOINT:**\n\n- [ ] On correct branch\n- [ ] No uncommitted changes\n- [ ] Up to date with base branch\n\n---\n\n## Phase 3: ARTIFACT - Write Context File\n\n### 3.1 Create Artifact Directory\n\n```bash\n```\n\n### 3.2 Write Context Artifact\n\nWrite to `$ARTIFACTS_DIR/plan-context.md`:\n\n```markdown\n# Plan Context\n\n**Generated**: {YYYY-MM-DD HH:MM}\n**Workflow ID**: $WORKFLOW_ID\n**Plan Source**: $ARGUMENTS\n\n---\n\n## Branch\n\n| Field | Value |\n|-------|-------|\n| **Branch** | {branch-name} |\n| **Base** | {base-branch} |\n\n---\n\n## Plan Summary\n\n**Title**: {extracted-title}\n\n**Overview**: {1-2 sentence summary from plan}\n\n---\n\n## Files to Change\n\n{Copy the \"Files to Change\" table from the plan, or list extracted files}\n\n| File | Action |\n|------|--------|\n| `src/example.ts` | CREATE |\n| `src/other.ts` | UPDATE |\n\n---\n\n## NOT Building (Scope Limits)\n\n**CRITICAL FOR REVIEWERS**: These items are **intentionally excluded** from scope. Do NOT flag them as bugs or missing features.\n\n{Copy from plan's \"NOT Building\", \"Scope Limits\", or \"Out of Scope\" section}\n\n- {Explicit exclusion 1 with rationale}\n- {Explicit exclusion 2 with rationale}\n\n{If no explicit exclusions in plan: \"No explicit scope limits defined in plan.\"}\n\n---\n\n## Validation Commands\n\n{Copy from plan's \"Validation Commands\" section}\n\n```bash\nbun run type-check\nbun run lint\nbun test\nbun run build\n```\n\n---\n\n## Acceptance Criteria\n\n{Copy from plan's \"Acceptance Criteria\" section}\n\n- [ ] Criterion 1\n- [ ] Criterion 2\n- [ ] ...\n\n---\n\n## Patterns to Mirror\n\n{Copy key file references from plan's \"Patterns to Mirror\" section}\n\n| Pattern | Source File | Lines |\n|---------|-------------|-------|\n| {pattern-name} | `src/example.ts` | 10-50 |\n\n---\n\n## Next Steps\n\n1. `archon-confirm-plan` - Verify patterns still exist\n2. `archon-implement-tasks` - Execute the plan\n3. `archon-validate` - Run full validation\n4. `archon-finalize-pr` - Create PR and mark ready\n```\n\n**PHASE_3_CHECKPOINT:**\n\n- [ ] Artifact directory created\n- [ ] `plan-context.md` written with all sections\n- [ ] \"NOT Building\" section captured (even if empty)\n\n---\n\n## Phase 4: OUTPUT - Report to User\n\n```markdown\n## Plan Setup Complete\n\n**Plan**: `$ARGUMENTS`\n**Workflow ID**: `$WORKFLOW_ID`\n\n### Branch\n\n| Field | Value |\n|-------|-------|\n| Branch | `{branch-name}` |\n| Base | `{base-branch}` |\n\n### Plan Summary\n\n**{plan-title}**\n\n{1-2 sentence overview}\n\n### Scope\n\n- {N} files to create\n- {M} files to update\n- {K} explicit exclusions captured\n\n### Artifact\n\nContext written to: `$ARTIFACTS_DIR/plan-context.md`\n\n### Next Step\n\nProceed to `archon-confirm-plan` to verify the plan's research is still valid.\n```\n\n---\n\n## Error Handling\n\n### Plan File Not Found\n\n```\n❌ Plan not found: $ARGUMENTS\n\nVerify the path exists and try again.\n```\n\n### Uncommitted Changes on Base Branch\n\n```\n❌ Uncommitted changes on base branch\n\nOptions:\n1. Stash changes: `git stash`\n2. Commit changes: `git add . && git commit -m \"WIP\"`\n3. Discard changes: `git checkout .`\n\nThen retry.\n```\n\n### Merge Conflicts\n\n```\n❌ Merge conflicts with $BASE_BRANCH\n\nResolve conflicts manually:\n1. `git status` to see conflicts\n2. Edit conflicting files\n3. `git add <resolved-files>`\n4. `git rebase --continue`\n\nThen retry.\n```\n\n---\n\n## Success Criteria\n\n- **PLAN_LOADED**: Plan file read and parsed\n- **SCOPE_LIMITS_CAPTURED**: \"NOT Building\" section extracted (even if empty)\n- **BRANCH_READY**: On correct branch, synced with base branch\n- **ARTIFACT_WRITTEN**: `plan-context.md` contains all required sections including scope limits\n",
+  "archon-post-review-to-pr": "---\ndescription: Post code review findings as a comment on the PR\nargument-hint: (none - reads from artifacts)\n---\n\n# Post Review to PR\n\n---\n\n## Your Mission\n\nRead the code review findings artifact and post a formatted summary as a comment on the PR.\n\n---\n\n## Phase 1: LOAD - Get Context\n\n### 1.1 Get PR Number\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number)\n```\n\n**If not found:**\n```\n❌ No PR number found at $ARTIFACTS_DIR/.pr-number\nCannot post review without a PR number.\n```\n\n### 1.2 Read Review Findings\n\n```bash\ncat $ARTIFACTS_DIR/review/code-review-findings.md\n```\n\n**If not found:**\n```\n❌ No review findings found at $ARTIFACTS_DIR/review/code-review-findings.md\nRun code review first.\n```\n\n**PHASE_1_CHECKPOINT:**\n- [ ] PR number loaded\n- [ ] Review findings loaded\n\n---\n\n## Phase 2: FORMAT - Build PR Comment\n\n### 2.1 Extract Key Information\n\nFrom the review findings, extract:\n- **Verdict**: APPROVE / REQUEST_CHANGES / NEEDS_DISCUSSION\n- **Summary**: 2-3 sentence overview\n- **Findings**: All findings with severity and location\n- **Statistics**: Finding counts by severity\n\n### 2.2 Build Comment Body\n\nFormat the review as a GitHub-friendly comment:\n\n```markdown\n## 🔍 Code Review\n\n**Verdict**: {APPROVE ✅ | REQUEST_CHANGES ❌ | NEEDS_DISCUSSION 💬}\n\n{Summary from findings}\n\n---\n\n### Findings\n\n{For each finding:}\n\n#### {severity emoji} {title}\n\n**Severity**: {CRITICAL|HIGH|MEDIUM|LOW} · **Category**: {category} · **Location**: `{file}:{line}`\n\n{Issue description}\n\n<details>\n<summary>Suggested Fix</summary>\n\n```typescript\n{recommended fix code}\n```\n\n**Why**: {reasoning}\n\n</details>\n\n---\n\n{End of findings}\n\n### Summary\n\n| Severity | Count |\n|----------|-------|\n| 🔴 Critical | {n} |\n| 🟠 High | {n} |\n| 🟡 Medium | {n} |\n| 🔵 Low | {n} |\n\n{If positive observations exist:}\n\n### What's Done Well\n\n{Positive observations from review}\n\n---\n\n*Automated code review*\n```\n\n**Severity emojis:**\n- CRITICAL → 🔴\n- HIGH → 🟠\n- MEDIUM → 🟡\n- LOW → 🔵\n\n**PHASE_2_CHECKPOINT:**\n- [ ] Comment body formatted\n- [ ] All findings included\n- [ ] Statistics table present\n\n---\n\n## Phase 3: POST - Comment on PR\n\n### 3.1 Post the Comment\n\n```bash\ngh pr comment {PR_NUMBER} --body \"$(cat <<'EOF'\n{formatted comment body}\nEOF\n)\"\n```\n\n### 3.2 Verify\n\n```bash\n# Check the comment was posted\ngh pr view {PR_NUMBER} --comments --json comments --jq '.comments | length'\n```\n\n**PHASE_3_CHECKPOINT:**\n- [ ] Comment posted to PR\n- [ ] Verified comment exists\n\n---\n\n## Phase 4: OUTPUT - Report to User\n\n```markdown\n## Review Posted to PR\n\n**PR**: #{PR_NUMBER}\n**Verdict**: {verdict}\n**Findings**: {total count} ({critical} critical, {high} high, {medium} medium, {low} low)\n\nReview comment has been posted to the pull request.\n```\n\n---\n\n## Error Handling\n\n### PR not found\n- Verify PR number is correct\n- Check if PR is still open\n- Report error to user\n\n### Comment fails to post\n- Check GitHub authentication\n- Try with shorter body if too large\n- Report error with details\n\n### No findings\n- Post a clean review comment: \"No issues found. LGTM!\"\n\n---\n\n## Success Criteria\n\n- **FINDINGS_LOADED**: Review artifact read successfully\n- **COMMENT_FORMATTED**: PR comment built with all findings\n- **COMMENT_POSTED**: Comment visible on the PR\n",
+  "archon-pr-review-scope": "---\ndescription: Gather PR context, verify reviewability, and prepare artifacts directory for comprehensive review\nargument-hint: <pr-number|url>\n---\n\n# PR Review Scope\n\n**Input**: $ARGUMENTS\n\n---\n\n## Your Mission\n\nVerify the PR is in a reviewable state, gather all context needed for the parallel review agents, and prepare the artifacts directory structure.\n\n---\n\n## Phase 1: IDENTIFY - Determine PR\n\n### 1.1 Get PR Number\n\n```bash\nif [ -f \"$ARTIFACTS_DIR/.pr-number\" ]; then\n  PR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number | tr -d '\\n' | tr -d ' ')\n  if ! echo \"$PR_NUMBER\" | grep -qE '^[0-9]+$'; then\n    PR_NUMBER=\"\"\n  fi\nfi\n\n# From arguments (standalone review)\nif [ -z \"$PR_NUMBER\" ] && [ -n \"$ARGUMENTS\" ]; then\n  PR_NUMBER=$(echo \"$ARGUMENTS\" | grep -oE '[0-9]+' | head -1)\nfi\n\n# From current branch\nif [ -z \"$PR_NUMBER\" ]; then\n  PR_NUMBER=$(gh pr view --json number -q '.number' 2>/dev/null)\nfi\n\nif [ -z \"$PR_NUMBER\" ]; then\n  echo \"ERROR: No PR number found\"\n  exit 1\nfi\n\n# Write to registry for downstream steps (if not already there)\necho \"$PR_NUMBER\" > $ARTIFACTS_DIR/.pr-number\n```\n\n### 1.2 Fetch PR Details\n\n```bash\ngh pr view {number} --json number,title,body,url,headRefName,baseRefName,files,additions,deletions,changedFiles,state,author,isDraft,mergeable,mergeStateStatus\n```\n\n**Extract:**\n- PR number and title\n- Branch names (head → base)\n- Changed files list\n- Addition/deletion counts\n- Draft status\n- Mergeable status\n\n**PHASE_1_CHECKPOINT:**\n- [ ] PR number identified\n- [ ] PR is open (not merged/closed)\n- [ ] Basic metadata extracted\n\n---\n\n## Phase 2: VERIFY - Pre-Review Checks\n\n**Before launching review agents, verify the PR is in a reviewable state.**\n\n### 2.1 Check for Merge Conflicts\n\n```bash\ngh pr view {number} --json mergeable,mergeStateStatus --jq '.mergeable, .mergeStateStatus'\n```\n\n| Status | Action |\n|--------|--------|\n| `MERGEABLE` | Continue |\n| `CONFLICTING` | **STOP** - Tell user to resolve conflicts first |\n| `UNKNOWN` | Warn, continue (GitHub still calculating) |\n\n**If conflicts exist:**\n```markdown\n❌ **Cannot review: PR has merge conflicts**\n\nPlease resolve conflicts before requesting a review:\n```bash\ngit fetch origin {base}\ngit rebase origin/{base}\n# Resolve conflicts\ngit push --force-with-lease\n```\n\nThen re-request the review.\n```\n**Exit workflow if conflicts detected.**\n\n### 2.2 Check CI Status\n\n```bash\ngh pr checks {number} --json name,state,conclusion --jq '.[] | \"\\(.name): \\(.state) (\\(.conclusion // \"pending\"))\"'\n```\n\n| Status | Action |\n|--------|--------|\n| All passing | Continue |\n| Some failing | Warn, continue (note in scope) |\n| All failing | Warn strongly, continue (note in scope) |\n| Pending | Note, continue |\n\n**Flag CI status for review report.**\n\n### 2.3 Check Behind Base\n\n```bash\n# Get branch names\nPR_BASE=$(gh pr view {number} --json baseRefName --jq '.baseRefName')\nPR_HEAD=$(gh pr view {number} --json headRefName --jq '.headRefName')\n\n# Fetch and count\ngit fetch origin $PR_BASE --quiet\ngit fetch origin $PR_HEAD --quiet\n\n# Commits behind base branch\nBEHIND=$(git rev-list --count origin/$PR_HEAD..origin/$PR_BASE 2>/dev/null || echo \"0\")\n```\n\n| Commits Behind | Action |\n|----------------|--------|\n| 0-5 | Continue |\n| 6-15 | Warn, suggest rebase, continue |\n| 16+ | Warn strongly, recommend rebase before review |\n\n**If significantly behind:**\n```markdown\n⚠️ **Branch is {N} commits behind {base}**\n\nConsider rebasing before review to ensure you're reviewing against current code:\n```bash\ngit fetch origin {base}\ngit rebase origin/{base}\ngit push --force-with-lease\n```\n```\n\n### 2.4 Check Draft Status\n\n```bash\ngh pr view {number} --json isDraft --jq '.isDraft'\n```\n\n| Status | Action |\n|--------|--------|\n| `false` | Continue normally |\n| `true` | Note in scope, continue (user wants early feedback) |\n\n### 2.5 Check PR Size\n\n| Metric | Warning Threshold | Action |\n|--------|-------------------|--------|\n| Changed files | 20+ | Warn about review thoroughness |\n| Lines changed | 1000+ | Warn about review thoroughness |\n\n**If very large:**\n```markdown\n⚠️ **Large PR: {files} files, +{additions} -{deletions} lines**\n\nLarge PRs are harder to review thoroughly. Consider splitting into smaller PRs for better review quality.\n```\n\n### 2.6 Compile Reviewability Summary\n\n```markdown\n## Pre-Review Status\n\n| Check | Status | Notes |\n|-------|--------|-------|\n| Merge Conflicts | ✅ None / ❌ Has conflicts | {details} |\n| CI Status | ✅ Passing / ⚠️ Failing / ⏳ Pending | {details} |\n| Behind Base | ✅ Up to date / ⚠️ {N} commits behind | {details} |\n| Draft | ✅ Ready / 📝 Draft | {details} |\n| Size | ✅ Normal / ⚠️ Large ({N} files) | {details} |\n```\n\n**PHASE_2_CHECKPOINT:**\n- [ ] No merge conflicts (or workflow stopped)\n- [ ] CI status noted\n- [ ] Behind-base status checked\n- [ ] Draft status noted\n- [ ] Size warnings issued if needed\n\n---\n\n## Phase 3: CONTEXT - Gather Review Context\n\n### 3.1 Get Full Diff\n\n```bash\ngh pr diff {number}\n```\n\nStore this for reference - parallel agents will re-fetch as needed.\n\n### 3.2 List Changed Files by Type\n\n```bash\ngh pr view {number} --json files --jq '.files[].path'\n```\n\n**Categorize files:**\n- Source code (`.ts`, `.js`, `.py`, etc.)\n- Test files (`*.test.ts`, `*.spec.ts`, `test_*.py`)\n- Documentation (`*.md`, `docs/`)\n- Configuration (`.json`, `.yaml`, `.toml`)\n- Types/interfaces\n\n### 3.3 Check for CLAUDE.md\n\n```bash\ncat CLAUDE.md 2>/dev/null | head -100\n```\n\nNote key rules that reviewers should check against.\n\n### 3.4 Identify New Abstractions\n\nScan the diff for new abstractions introduced by this PR:\n\n- New interfaces, types, or abstract classes (search diff for `interface `, `type `, `abstract class`)\n- New utility modules or helper files (new `.ts` files that aren't feature files or tests)\n- New configuration keys or schema fields\n\nFor each new abstraction found, note it in the scope manifest under \"Review Focus Areas\" so the code review agent can verify it doesn't duplicate an existing primitive.\n\n```bash\n# Quick scan for new abstractions in diff\ngh pr diff {number} | grep \"^+\" | sed 's/^+//' | grep -E \"(^interface |^export interface |^type |^abstract class |^export class )\" | head -20\n```\n\n**PHASE_3_CHECKPOINT:**\n- [ ] Diff available\n- [ ] Files categorized by type\n- [ ] CLAUDE.md rules noted\n- [ ] New abstractions scanned\n\n---\n\n## Phase 3.5: PLAN/ISSUE CONTEXT - Check for Workflow Artifacts\n\n**CRITICAL**: If this PR was created by a workflow, there will be artifacts that contain important context for reviewers.\n\n### 3.5.1 Find Workflow Artifacts\n\nCheck for artifacts from EITHER workflow type:\n\n```bash\n# Option 1: Plan-based workflow (archon-plan-to-merge)\nls -t $ARTIFACTS_DIR/../runs/*/plan-context.md 2>/dev/null | head -1\n\n# Option 2: Issue-based workflow (archon-fix-github-issue)\nls -t $ARTIFACTS_DIR/../runs/*/investigation.md 2>/dev/null | head -1\n```\n\n### 3.5.2 Extract Scope Limits\n\n**If plan-context.md exists** (from plan workflow):\n\n```bash\n# Extract the NOT Building section\nsed -n '/## NOT Building/,/^## /p' $ARTIFACTS_DIR/../runs/*/plan-context.md | head -30\n```\n\n**If investigation.md exists** (from issue workflow):\n\n```bash\n# Extract the Scope Boundaries / OUT OF SCOPE section\nsed -n '/## Scope Boundaries/,/^## /p' $ARTIFACTS_DIR/../runs/*/investigation.md | head -30\n```\n\n**These are INTENTIONAL exclusions** - do NOT flag them as bugs or missing features!\n\n### 3.5.3 Check Implementation Report\n\n```bash\n# Look for implementation report (either workflow)\nls -t $ARTIFACTS_DIR/../runs/*/implementation.md 2>/dev/null | head -1\n```\n\n**If implementation.md exists**, note any deviations:\n\n```bash\n# Extract deviations section\nsed -n '/## Deviations/,/^## /p' $ARTIFACTS_DIR/../runs/*/implementation.md | head -20\n```\n\n**PHASE_3.5_CHECKPOINT:**\n- [ ] Workflow artifacts checked (plan-context.md OR investigation.md)\n- [ ] Scope limits extracted (NOT Building OR OUT OF SCOPE)\n- [ ] Implementation deviations noted (if available)\n\n---\n\n## Phase 4: PREPARE - Create Artifacts Directory\n\n### 4.1 Create Directory Structure\n\n```bash\nmkdir -p $ARTIFACTS_DIR/review\n```\n\n### 4.2 Clean Stale Artifacts\n\n```bash\n# Remove review directories older than 7 days\nfind $ARTIFACTS_DIR/../reviews/pr-* -maxdepth 0 -mtime +7 -exec rm -rf {} \\; 2>/dev/null || true\n```\n\n### 4.3 Create Scope Manifest\n\nWrite `$ARTIFACTS_DIR/review/scope.md`:\n\n```markdown\n# PR Review Scope: #{number}\n\n**Title**: {PR title}\n**URL**: {PR URL}\n**Branch**: {head} → {base}\n**Author**: {author}\n**Date**: {ISO timestamp}\n\n---\n\n## Pre-Review Status\n\n| Check | Status | Notes |\n|-------|--------|-------|\n| Merge Conflicts | {status} | {details} |\n| CI Status | {status} | {passing}/{total} checks |\n| Behind Base | {status} | {N} commits behind |\n| Draft | {status} | {Ready/Draft} |\n| Size | {status} | {files} files, +{add}/-{del} |\n\n---\n\n## Changed Files\n\n| File | Type | Additions | Deletions |\n|------|------|-----------|-----------|\n| `src/file.ts` | source | +10 | -5 |\n| `src/file.test.ts` | test | +20 | -0 |\n| ... | ... | ... | ... |\n\n**Total**: {changedFiles} files, +{additions} -{deletions}\n\n---\n\n## File Categories\n\n### Source Files ({count})\n- `src/...`\n\n### Test Files ({count})\n- `src/...test.ts`\n\n### Documentation ({count})\n- `$DOCS_DIR/...`\n- `README.md`\n\n### Configuration ({count})\n- `package.json`\n\n---\n\n## Review Focus Areas\n\nBased on changes, reviewers should focus on:\n\n1. **Code Quality**: {list key source files}\n2. **Error Handling**: {files with try/catch, error handling}\n3. **Test Coverage**: {new functionality needing tests}\n4. **Comments/Docs**: {files with documentation changes}\n5. **Docs Impact**: {check if CLAUDE.md or $DOCS_DIR need updates}\n6. **Primitive Alignment**: {If new abstractions found: list them} — verify no duplication of existing primitives\n\n---\n\n## CLAUDE.md Rules to Check\n\n{Extract key rules from CLAUDE.md that apply to this PR}\n\n---\n\n## Workflow Context (if from automated workflow)\n\n{If plan-context.md OR investigation.md was found:}\n\n### Scope Limits (NOT Building / OUT OF SCOPE)\n\n**CRITICAL FOR REVIEWERS**: These items are **intentionally excluded** from scope. Do NOT flag them as bugs or missing features.\n\n{From plan-context.md \"NOT Building\" section OR investigation.md \"Scope Boundaries/OUT OF SCOPE\" section}\n\n**IN SCOPE:**\n- {what we're changing}\n\n**OUT OF SCOPE (do not touch):**\n- {Explicit exclusion 1 with rationale}\n- {Explicit exclusion 2 with rationale}\n\n### Implementation Deviations\n\n{If implementation.md was found and has deviations:}\n\n{Copy the \"Deviations\" section from implementation.md}\n\n{If no workflow artifacts found:}\n\n_No workflow artifacts found - this appears to be a manual PR._\n\n---\n\n## CI Details\n\n{If CI failing, list which checks failed}\n\n---\n\n## Metadata\n\n- **Scope created**: {ISO timestamp}\n- **Artifact path**: `$ARTIFACTS_DIR/review/`\n```\n\n**PHASE_4_CHECKPOINT:**\n- [ ] Directory created\n- [ ] Stale artifacts cleaned\n- [ ] Scope manifest written with pre-review status\n\n---\n\n## Phase 5: OUTPUT - Report to User\n\n### If Blocked (Conflicts)\n\n```markdown\n## ❌ Review Blocked: Merge Conflicts\n\n**PR**: #{number} - {title}\n\nThis PR has merge conflicts that must be resolved before review.\n\n### To Resolve\n\n```bash\ngit fetch origin {base}\ngit checkout {head}\ngit rebase origin/{base}\n# Resolve conflicts in your editor\ngit add .\ngit rebase --continue\ngit push --force-with-lease\n```\n\nThen re-request the review: `@archon review this PR`\n```\n\n### If Proceeding\n\n```markdown\n## PR Review Scope Complete\n\n**PR**: #{number} - {title}\n**Files**: {count} changed (+{additions} -{deletions})\n\n### Pre-Review Status\n| Check | Status |\n|-------|--------|\n| Conflicts | ✅ None |\n| CI | {✅ Passing / ⚠️ {N} failing} |\n| Behind Base | {✅ Up to date / ⚠️ {N} behind} |\n| Draft | {✅ Ready / 📝 Draft} |\n| Size | {✅ Normal / ⚠️ Large} |\n\n### File Categories\n- Source: {count} files\n- Tests: {count} files\n- Docs: {count} files\n- Config: {count} files\n\n### Artifacts Directory\n`$ARTIFACTS_DIR/review/`\n\n### Next Step\nLaunching 5 parallel review agents...\n```\n\n---\n\n## Success Criteria\n\n- **PR_IDENTIFIED**: Valid open PR found\n- **NO_CONFLICTS**: Merge conflicts block workflow\n- **CONTEXT_GATHERED**: Diff and file list available\n- **ARTIFACTS_DIR_CREATED**: Directory structure exists\n- **SCOPE_MANIFEST_WRITTEN**: `scope.md` file created with pre-review status\n",
+  "archon-ralph-generate": "---\ndescription: Autonomously generate Ralph PRD files (prd.md + prd.json) from an idea or existing PRD\nargument-hint: <feature idea | path/to/existing-prd.md>\n---\n\n# Ralph PRD Generator (Autonomous)\n\n**Input**: $ARGUMENTS\n**Workflow ID**: $WORKFLOW_ID\n\n---\n\n## Your Mission\n\nGenerate production-quality Ralph PRD files — `prd.md` (full context document) and `prd.json` (story tracking) — through systematic codebase exploration and analysis. No interactive questions — make informed decisions autonomously.\n\n**Core Principle**: CODEBASE FIRST. Explore the project before writing anything. Stories must reference real files, real patterns, and real types.\n\n---\n\n## Phase 0: DETECT — Determine Input Type\n\n| Input Pattern | Type | Action |\n|---------------|------|--------|\n| Path to `.md` file that exists | Existing PRD | Read it, generate prd.json stories from it |\n| `.archon/ralph/{slug}/prd.md` exists | Existing PRD in ralph dir | Generate prd.json alongside it |\n| Free-form text | Feature idea | Generate both prd.md and prd.json |\n| Empty/blank | Error | STOP — require input |\n\n### If existing PRD detected:\n\n1. Read the PRD file\n2. Extract: problem statement, goals, user context, scope limits, technical requirements\n3. Skip to Phase 3 (Technical Grounding) — the PRD already covers Phases 1-2\n\n### If feature idea:\n\n1. Store the idea description\n2. Proceed through all phases\n\n---\n\n## Phase 1: UNDERSTAND — Problem & Context\n\n**Autonomously determine:**\n\n1. **Problem**: What pain point does this solve? What happens without it?\n2. **User**: Who benefits? What's their role and daily workflow?\n3. **Goal**: What's the ideal outcome? How will success be measured?\n4. **Scope**: What's MVP? What's explicitly out of scope?\n5. **Success metrics**: What measurable signals indicate this worked?\n\nBase these on the input description and your understanding of the codebase.\n\n**PHASE_1_CHECKPOINT:**\n- [ ] Problem clearly articulated\n- [ ] Target user identified\n- [ ] Goals and success metrics defined\n- [ ] Scope boundaries set\n\n---\n\n## Phase 2: UX & DESIGN — User Journey\n\n**Autonomously determine:**\n\n1. **Trigger**: What event causes the user to need this feature?\n2. **Happy path**: Step-by-step user flow from trigger to success\n3. **States**: Empty, loading, error, success — what does each look like?\n4. **Edge cases**: What can go wrong? How should it be handled?\n5. **Interaction model**: CLI commands, API endpoints, UI components?\n\nIf the feature has a UI component, describe the visual requirements.\nIf it's backend-only, describe the API surface.\n\n**PHASE_2_CHECKPOINT:**\n- [ ] User journey mapped\n- [ ] States enumerated\n- [ ] Edge cases identified\n\n---\n\n## Phase 3: TECHNICAL GROUNDING — Codebase Exploration\n\n**This is the critical phase.** Use the Task tool with `subagent_type=\"Explore\"` to systematically explore the codebase.\n\n### 3.1 Find Similar Implementations\n\n```\nExplore the codebase for patterns relevant to: {feature description}\n\nFIND:\n1. Similar implementations to mirror (with file:line references)\n2. Existing types/interfaces to extend or use\n3. Naming conventions (functions, files, variables)\n4. Error handling patterns\n5. Test patterns (framework, structure, assertion style)\n6. Database schema patterns (if applicable)\n7. Component patterns (if UI involved)\n```\n\n### 3.2 Identify Integration Points\n\n```\nTrace data flow and entry points for: {feature description}\n\nFIND:\n1. Where new code connects to existing code\n2. Which modules/packages are affected\n3. Import patterns to follow\n4. Config/env dependencies\n```\n\n### 3.3 Read Project Rules\n\n```bash\ncat CLAUDE.md\n```\n\nExtract: coding standards, naming conventions, testing requirements, lint rules.\n\n**PHASE_3_CHECKPOINT:**\n- [ ] Similar implementations found with file:line references\n- [ ] Types and interfaces identified\n- [ ] Integration points mapped\n- [ ] CLAUDE.md rules noted\n\n---\n\n## Phase 4: STORY BREAKDOWN — Split Into Iterations\n\n### 4.1 Identify Layers\n\nBreak the feature into implementation layers:\n\n| Layer | Examples | Typical story count |\n|-------|---------|-------------------|\n| Schema/types | DB columns, interfaces, Zod schemas | 1-2 |\n| Backend logic | Services, utilities, API endpoints | 2-4 |\n| UI components | New components, modifications | 1-3 |\n| Integration | Wiring, config, exports | 1-2 |\n| Tests | Dedicated test stories (if complex) | 0-2 |\n\n### 4.2 Sizing Rules\n\nEach story must be completable in ONE iteration (~15-30 min of AI work):\n\n**Right-sized (ONE iteration):**\n- Add a database column + migration\n- Create one utility function + tests\n- Add one UI component\n- Update one API endpoint + tests\n- Write integration tests for one feature\n\n**TOO BIG (must split):**\n- \"Build entire feature\" → split into schema, types, backend, UI\n- \"Add authentication\" → split into schema, middleware, login UI, token handling\n- \"Refactor module\" → split by file or concern\n\n### 4.3 Dependency Ordering\n\n- Stories ordered by dependency (lower priority = runs first)\n- Schema before types before backend before UI before integration\n- `dependsOn` must only reference lower-priority stories\n- Validate: no circular dependencies, no forward references\n\n### 4.4 Acceptance Criteria Rules\n\n**GOOD (verifiable):**\n- \"Add `priority` column with type `'high' | 'medium' | 'low'`\"\n- \"Function returns empty array when input is null\"\n- \"Button shows loading state while submitting\"\n- \"Type-check passes with zero errors\"\n\n**BAD (vague):**\n- \"Works correctly\"\n- \"Good UX\"\n- \"Handles edge cases\"\n\nEvery criterion must be pass/fail testable.\n\n**PHASE_4_CHECKPOINT:**\n- [ ] Stories sized for single iterations\n- [ ] Dependencies form a valid DAG (no cycles)\n- [ ] Acceptance criteria are all verifiable\n- [ ] Technical notes reference real files and patterns\n\n---\n\n## Phase 5: GENERATE — Write PRD Files\n\n### 5.1 Determine Feature Slug\n\nGenerate a kebab-case slug from the feature name:\n- \"Workflow Lifecycle Overhaul\" → `workflow-lifecycle-overhaul`\n- \"Dark Mode Toggle\" → `dark-mode-toggle`\n- Max 50 characters\n\n### 5.2 Create Directory\n\n```bash\nmkdir -p .archon/ralph/{slug}\n```\n\n### 5.3 Write prd.md\n\n**Output path**: `.archon/ralph/{slug}/prd.md`\n\nInclude ALL of the following sections:\n\n```markdown\n# {Feature Name} — Product Requirements\n\n## Overview\n\n**Problem**: {What pain this solves — from Phase 1}\n**Solution**: {What we're building}\n**Branch**: `ralph/{slug}`\n\n---\n\n## Goals & Success\n\n### Primary Goal\n{The main outcome}\n\n### Success Metrics\n| Metric | Target | How Measured |\n|--------|--------|--------------|\n| {metric} | {target} | {method} |\n\n### Non-Goals (Out of Scope)\n- {Item 1} — {why excluded}\n- {Item 2} — {why excluded}\n\n---\n\n## User & Context\n\n### Target User\n- **Who**: {description}\n- **Role**: {their context}\n- **Current Pain**: {what they struggle with}\n\n### User Journey\n1. **Trigger**: {what prompts the need}\n2. **Action**: {what they do}\n3. **Outcome**: {success state}\n\n---\n\n## UX Requirements\n\n### Interaction Model\n{How users interact — CLI commands, API endpoints, UI components}\n\n### States to Handle\n| State | Description | Behavior |\n|-------|-------------|----------|\n| Empty | {when} | {what happens} |\n| Loading | {when} | {what happens} |\n| Error | {when} | {what happens} |\n| Success | {when} | {what happens} |\n\n---\n\n## Technical Context\n\n### Patterns to Follow\n- **Similar implementation**: `{file:lines}` — {what to mirror}\n- **Component pattern**: `{file:lines}` — {pattern description}\n- **Test pattern**: `{file:lines}` — {how to test}\n\n### Types & Interfaces\n```typescript\n// Key types to use or extend\n{relevant type definitions from codebase exploration}\n```\n\n### Architecture Notes\n- {Key technical decisions}\n- {Integration points from Phase 3}\n- {Dependencies}\n\n---\n\n## Implementation Summary\n\n### Story Overview\n| ID | Title | Priority | Dependencies |\n|----|-------|----------|--------------|\n| US-001 | {title} | 1 | — |\n| US-002 | {title} | 2 | US-001 |\n\n### Dependency Graph\n```\nUS-001 (schema/types)\n    ↓\nUS-002 (backend)\n    ↓\nUS-003 (UI) → US-004 (integration)\n```\n\n---\n\n## Validation Requirements\n\nEvery story must pass:\n- [ ] Type-check: `bun run type-check`\n- [ ] Lint: `bun run lint`\n- [ ] Tests: `bun run test`\n- [ ] Format: `bun run format:check`\n\n---\n\n*Generated: {ISO timestamp}*\n```\n\n**If input was an existing PRD**: Incorporate its content into this structure. Don't lose information — merge the existing PRD's goals, context, and requirements into the appropriate sections. Add the technical context from your codebase exploration (Phase 3).\n\n### 5.4 Write prd.json\n\n**Output path**: `.archon/ralph/{slug}/prd.json`\n\n```json\n{\n  \"project\": \"{ProjectName}\",\n  \"branchName\": \"ralph/{slug}\",\n  \"prdFile\": \"prd.md\",\n  \"description\": \"{One line summary}\",\n  \"userStories\": [\n    {\n      \"id\": \"US-001\",\n      \"title\": \"{Short title}\",\n      \"description\": \"As a {user}, I want {capability} so that {benefit}\",\n      \"acceptanceCriteria\": [\n        \"{Specific verifiable criterion 1}\",\n        \"{Specific verifiable criterion 2}\",\n        \"Type-check passes\",\n        \"Tests pass\"\n      ],\n      \"technicalNotes\": \"{Files to modify, patterns to follow, types to use — from Phase 3}\",\n      \"dependsOn\": [],\n      \"priority\": 1,\n      \"passes\": false,\n      \"notes\": \"\"\n    }\n  ]\n}\n```\n\n### 5.5 Commit PRD Files\n\n```bash\ngit add .archon/ralph/{slug}/\ngit commit -m \"docs: add Ralph PRD for {feature name}\"\n```\n\n**PHASE_5_CHECKPOINT:**\n- [ ] `.archon/ralph/{slug}/prd.md` written with all sections\n- [ ] `.archon/ralph/{slug}/prd.json` written with properly sized stories\n- [ ] Stories have verifiable acceptance criteria\n- [ ] Technical notes reference real files from codebase exploration\n- [ ] Files committed\n\n---\n\n## Phase 6: OUTPUT — Report\n\n```\nPRD_DIR=.archon/ralph/{slug}\nSTORIES_TOTAL={count}\nFILES_CREATED=prd.md,prd.json\n\n## Ralph PRD Ready\n\n**Feature**: {name}\n**Directory**: `.archon/ralph/{slug}/`\n**Stories**: {count} user stories\n**Dependencies**: Valid DAG (no cycles)\n\n| # | ID | Title | Dependencies |\n|---|-----|-------|--------------|\n| 1 | US-001 | {title} | — |\n| 2 | US-002 | {title} | US-001 |\n```\n\n---\n\n## Success Criteria\n\n- **CONTEXT_COMPLETE**: prd.md has goals, user context, UX, technical patterns from real codebase exploration\n- **STORIES_SIZED**: Each story completable in one iteration\n- **DEPENDENCIES_VALID**: No circular dependencies, lower priority runs first\n- **CRITERIA_VERIFIABLE**: All acceptance criteria are pass/fail testable\n- **TECHNICAL_GROUNDED**: Technical notes reference real files, types, and patterns from the codebase\n- **FILES_WRITTEN**: Both prd.md and prd.json exist in `.archon/ralph/{slug}/`\n",
+  "archon-ralph-prd": "# Ralph PRD Generator\n\n**Input**: $ARGUMENTS\n\n---\n\n## Your Role\n\nYou are creating a PRD for the Ralph autonomous loop. You generate TWO files:\n1. `prd.md` - Full context document (goals, persona, UX, success criteria)\n2. `prd.json` - Story tracking with passes/fails\n\nEach Ralph iteration receives the FULL prd.md context plus its specific story from prd.json.\n\n**Critical Rules:**\n- Each story must be completable in ONE iteration\n- Stories ordered by dependency (schema → backend → UI)\n- Acceptance criteria must be VERIFIABLE (not vague)\n\n---\n\n## Phase 1: INITIATE\n\n**If no input provided**, ask:\n\n> **What do you want to build?**\n> Describe the feature or capability in a few sentences.\n\n**If input provided**, confirm:\n\n> I understand you want to build: {restated understanding}\n> Is this correct?\n\n**GATE**: Wait for confirmation.\n\n---\n\n## Phase 2: FOUNDATION\n\nAsk these questions together:\n\n> **Foundation Questions:**\n>\n> 1. **Problem**: What pain point does this solve? What happens if we don't build it?\n>\n> 2. **User**: Who is this for? Describe their role and context.\n>\n> 3. **Goal**: What's the ideal outcome if this succeeds?\n>\n> 4. **Scope**: MVP or full implementation? What's explicitly out of scope?\n>\n> 5. **Success**: How will we measure if this worked? What metrics matter?\n\n**GATE**: Wait for answers.\n\n---\n\n## Phase 3: UX & DESIGN\n\nAsk:\n\n> **UX Questions:**\n>\n> 1. **User Journey**: What triggers the user to need this? What's the happy path?\n>\n> 2. **UI Requirements**: Any specific visual requirements? Colors, placement, components?\n>\n> 3. **Interaction Model**: How does the user interact? Clicks, keyboard, API?\n>\n> 4. **Edge Cases**: What error states need handling? Empty states?\n>\n> 5. **Accessibility**: Any a11y requirements?\n\n**GATE**: Wait for answers.\n\n---\n\n## Phase 4: TECHNICAL GROUNDING\n\n**Use Explore agent:**\n\n```\nExplore the codebase for patterns relevant to: {feature}\n\nFIND:\n1. Similar implementations to mirror (with file:line references)\n2. Existing types/interfaces to extend\n3. Component patterns to follow\n4. Test patterns used\n5. Database schema patterns\n```\n\n**Summarize:**\n\n> **Technical Context:**\n> - Similar pattern: {file:lines}\n> - Types to extend: {types}\n> - Components to use: {components}\n> - Test pattern: {pattern}\n>\n> Any additional technical constraints?\n\n**GATE**: Brief pause for input.\n\n---\n\n## Phase 5: STORY BREAKDOWN\n\nAsk:\n\n> **Story Planning:**\n>\n> 1. **Database**: Schema changes needed? New tables/columns?\n>\n> 2. **Types**: New interfaces or type extensions?\n>\n> 3. **Backend**: Server logic, API endpoints, services?\n>\n> 4. **UI Components**: New components or modifications?\n>\n> 5. **Integration**: How do pieces connect?\n\n**GATE**: Wait for answers.\n\n---\n\n## Phase 6: GENERATE FILES\n\n**Naming Convention**: Use the feature name as a kebab-case slug.\n- Feature: \"User Authentication\" → slug: `user-authentication`\n- Feature: \"Dark Mode Toggle\" → slug: `dark-mode-toggle`\n\n**First**, create the ralph directory for this feature:\n```bash\n# Replace {feature-slug} with the actual kebab-case feature name\nmkdir -p .archon/ralph/{feature-slug}\n```\n\n### File 1: prd.md\n\n**Output path**: `.archon/ralph/{feature-slug}/prd.md`\n\n```markdown\n# {Feature Name} - Product Requirements\n\n## Overview\n\n**Problem**: {What pain this solves}\n**Solution**: {What we're building}\n**Branch**: `ralph/{feature-kebab}`\n\n---\n\n## Goals & Success\n\n### Primary Goal\n{The main outcome we want}\n\n### Success Metrics\n| Metric | Target | How Measured |\n|--------|--------|--------------|\n| {metric} | {target} | {method} |\n\n### Non-Goals (Out of Scope)\n- {Item 1} - {why excluded}\n- {Item 2} - {why excluded}\n\n---\n\n## User & Context\n\n### Target User\n- **Who**: {Specific description}\n- **Role**: {Their job/context}\n- **Current Pain**: {What they struggle with today}\n\n### User Journey\n1. **Trigger**: {What prompts the need}\n2. **Action**: {What they do}\n3. **Outcome**: {What success looks like}\n\n### Jobs to Be Done\nWhen {situation}, I want to {motivation}, so I can {outcome}.\n\n---\n\n## UX Requirements\n\n### Visual Design\n- {Color/style requirements}\n- {Component preferences}\n- {Layout requirements}\n\n### Interaction Model\n- {How users interact}\n- {Keyboard shortcuts if any}\n- {Mobile considerations}\n\n### States to Handle\n| State | Description | UI Behavior |\n|-------|-------------|-------------|\n| Empty | {when} | {show what} |\n| Loading | {when} | {show what} |\n| Error | {when} | {show what} |\n| Success | {when} | {show what} |\n\n### Accessibility\n- {A11y requirements}\n\n---\n\n## Technical Context\n\n### Patterns to Follow\n- **Similar implementation**: `{file:lines}` - {what to mirror}\n- **Component pattern**: `{file:lines}` - {pattern description}\n- **Test pattern**: `{file:lines}` - {how to test}\n\n### Types & Interfaces\n```typescript\n// Extend or use these existing types:\n{relevant type definitions}\n```\n\n### Architecture Notes\n- {Key technical decisions}\n- {Integration points}\n- {Dependencies}\n\n---\n\n## Implementation Summary\n\n### Story Overview\n| ID | Title | Priority | Dependencies |\n|----|-------|----------|--------------|\n| US-001 | {title} | 1 | - |\n| US-002 | {title} | 2 | US-001 |\n{...}\n\n### Dependency Graph\n```\nUS-001 (schema)\n    ↓\nUS-002 (types)\n    ↓\nUS-003 (backend) → US-004 (UI components)\n                        ↓\n                   US-005 (integration)\n```\n\n---\n\n## Validation Requirements\n\nEvery story must pass:\n- [ ] Typecheck: `bun run type-check`\n- [ ] Lint: `bun run lint`\n- [ ] Tests: `bun test`\n\n---\n\n*Generated: {ISO timestamp}*\n```\n\n### File 2: prd.json\n\n**Output path**: `.archon/ralph/{feature-slug}/prd.json`\n\n```json\n{\n  \"project\": \"{ProjectName}\",\n  \"branchName\": \"ralph/{feature-kebab}\",\n  \"prdFile\": \"prd.md\",\n  \"description\": \"{One line summary}\",\n  \"userStories\": [\n    {\n      \"id\": \"US-001\",\n      \"title\": \"{Short title}\",\n      \"description\": \"As a {user}, I want {capability} so that {benefit}\",\n      \"acceptanceCriteria\": [\n        \"{Specific verifiable criterion}\",\n        \"Typecheck passes\"\n      ],\n      \"technicalNotes\": \"{Implementation hints from prd.md}\",\n      \"dependsOn\": [],\n      \"priority\": 1,\n      \"passes\": false,\n      \"notes\": \"\"\n    }\n  ]\n}\n```\n\n### Story Sizing Rules\n\n**Right-sized (ONE iteration):**\n- Add a database column + migration\n- Create one utility function + tests\n- Add one UI component\n- Update one API endpoint\n\n**TOO BIG (split):**\n- \"Build entire feature\" → schema, types, backend, UI\n- \"Add authentication\" → schema, middleware, login UI\n\n### Acceptance Criteria Rules\n\n**GOOD (verifiable):**\n- \"Add `priority` column with type 'high' | 'medium' | 'low'\"\n- \"Function returns empty array when input is null\"\n- \"Button shows loading state while submitting\"\n\n**BAD (vague):**\n- \"Works correctly\"\n- \"Good UX\"\n- \"Handles edge cases\"\n\n---\n\n## Phase 7: OUTPUT\n\nAfter generating both files, report:\n\n```markdown\n## Ralph PRD Created\n\n### Files Generated\n\n| File | Purpose |\n|------|---------|\n| `.archon/ralph/{feature-slug}/prd.md` | Full context - goals, UX, technical patterns |\n| `.archon/ralph/{feature-slug}/prd.json` | Story tracking - passes/fails per story |\n\n### Summary\n\n**Feature**: {name}\n**Branch**: `ralph/{feature}`\n**Stories**: {count} user stories\n**Estimated iterations**: {count}\n\n### User Stories\n\n| # | ID | Title | Dependencies |\n|---|-----|-------|--------------|\n| 1 | US-001 | {title} | - |\n| 2 | US-002 | {title} | US-001 |\n{...}\n\n### Context Passed to Each Iteration\n\nEach Ralph iteration receives:\n1. **Full PRD** (`.archon/ralph/{feature-slug}/prd.md`) - Goals, persona, UX, technical patterns\n2. **Current Story** - From `.archon/ralph/{feature-slug}/prd.json` with acceptance criteria\n3. **Previous Learnings** - From `.archon/ralph/{feature-slug}/progress.txt`\n\n### To Start\n\n```bash\n# Create feature branch\ngit checkout -b ralph/{feature-slug}\n\n# Initialize progress\necho \"# Ralph Progress Log\\nStarted: $(date)\\n---\" > .archon/ralph/{feature-slug}/progress.txt\n\n# Run Ralph - specify the feature directory\n@Archon run ralph .archon/ralph/{feature-slug}\n```\n```\n\n---\n\n## Question Flow\n\n```\nINITIATE → FOUNDATION → UX/DESIGN → TECHNICAL → BREAKDOWN → GENERATE\n    ↓           ↓            ↓           ↓           ↓          ↓\n Confirm    Problem,      Journey,   Patterns,   Stories,   prd.md +\n  idea      User,         UI reqs,   Types,      DB/API/    prd.json\n            Goals         States     Tests       UI split\n```\n\n---\n\n## Success Criteria\n\n- **CONTEXT_COMPLETE**: prd.md has goals, persona, UX, technical context\n- **STORIES_SIZED**: Each story completable in one iteration\n- **DEPENDENCIES_VALID**: Lower priority never depends on higher\n- **CRITERIA_VERIFIABLE**: All acceptance criteria are pass/fail\n- **READY_TO_RUN**: User can immediately start Ralph loop\n",
+  "archon-resolve-merge-conflicts": "---\ndescription: Analyze and resolve merge conflicts in a PR\nargument-hint: <pr-number|url>\n---\n\n# Resolve Merge Conflicts\n\n**Input**: $ARGUMENTS\n\n---\n\n## Your Mission\n\nAnalyze merge conflicts in the PR, automatically resolve simple conflicts where intent is clear, present options for complex conflicts, and push the resolution.\n\n---\n\n## Phase 1: IDENTIFY - Get PR and Conflict Info\n\n### 1.1 Parse Input\n\n**Check input format:**\n- Number (`123`, `#123`) → GitHub PR number\n- URL (`https://github.com/...`) → Extract PR number\n- Empty → Check current branch for open PR\n\n```bash\ngh pr view {number} --json number,title,headRefName,baseRefName,mergeable,mergeStateStatus\n```\n\n### 1.2 Verify Conflicts Exist\n\n```bash\ngh pr view {number} --json mergeable,mergeStateStatus --jq '.mergeable, .mergeStateStatus'\n```\n\n| Status | Action |\n|--------|--------|\n| `CONFLICTING` | Continue with resolution |\n| `MERGEABLE` | Report \"No conflicts to resolve\" and exit |\n| `UNKNOWN` | Wait and retry, or proceed with caution |\n\n**If no conflicts:**\n```markdown\n## ✅ No Conflicts\n\nPR #{number} has no merge conflicts. It's ready for review/merge.\n```\n**Exit if no conflicts.**\n\n### 1.3 Setup Local Branch\n\n```bash\n# Get branch info\nPR_HEAD=$(gh pr view {number} --json headRefName --jq '.headRefName')\nPR_BASE=$(gh pr view {number} --json baseRefName --jq '.baseRefName')\n\n# Fetch latest\ngit fetch origin $PR_BASE\ngit fetch origin $PR_HEAD\n\n# Checkout the PR branch\ngit checkout $PR_HEAD\ngit pull origin $PR_HEAD\n```\n\n**PHASE_1_CHECKPOINT:**\n- [ ] PR identified with conflicts\n- [ ] Branches fetched\n- [ ] On PR branch locally\n\n---\n\n## Phase 2: ANALYZE - Understand the Conflicts\n\n### 2.1 Attempt Rebase to Surface Conflicts\n\n```bash\ngit rebase origin/$PR_BASE\n```\n\nThis will stop at the first conflict. Note the output.\n\n### 2.2 Identify Conflicting Files\n\n```bash\ngit diff --name-only --diff-filter=U\n```\n\nList all files with conflicts.\n\n### 2.3 Analyze Each Conflict\n\nFor each conflicting file:\n\n```bash\n# Show the conflict markers\ngit diff --check\ncat {file} | grep -A 10 -B 2 \"<<<<<<<\"\n```\n\n**Categorize each conflict:**\n\n| Type | Description | Auto-resolvable? |\n|------|-------------|------------------|\n| **SIMPLE_ADDITION** | One side added, other didn't change that area | ✅ Yes |\n| **SIMPLE_DELETION** | One side deleted, other didn't change | ⚠️ Maybe (check intent) |\n| **DIFFERENT_AREAS** | Both changed but different lines | ✅ Yes |\n| **SAME_LINES** | Both changed the exact same lines | ❌ No - needs decision |\n| **STRUCTURAL** | File moved/renamed + modified | ❌ No - needs decision |\n\n### 2.4 Read Both Versions\n\nFor complex conflicts, understand what each side was trying to do:\n\n```bash\n# Show base version (common ancestor)\ngit show :1:{file} 2>/dev/null || echo \"File didn't exist in base\"\n\n# Show \"ours\" version (HEAD/current branch)\ngit show :2:{file}\n\n# Show \"theirs\" version (incoming from base branch)\ngit show :3:{file}\n```\n\n**PHASE_2_CHECKPOINT:**\n- [ ] All conflicting files identified\n- [ ] Each conflict categorized\n- [ ] Both sides' intent understood\n\n---\n\n## Phase 3: RESOLVE - Fix the Conflicts\n\n### 3.1 Auto-Resolve Simple Conflicts\n\nFor conflicts where intent is clear:\n\n```bash\n# For each auto-resolvable file\n# Edit to keep both changes (if both are additive)\n# Or keep the appropriate side based on intent\n```\n\n**Auto-resolution rules:**\n1. **Both added different things**: Keep both additions\n2. **One updated, one didn't touch**: Keep the update\n3. **Import additions**: Merge both import lists\n4. **Comment changes**: Prefer the more informative version\n\n### 3.2 Present Options for Complex Conflicts\n\nFor conflicts that need human decision:\n\n```markdown\n## Conflict in `{file}`\n\n**Lines {start}-{end}**\n\n### Option A: Keep PR Changes (HEAD)\n```{language}\n{code from PR branch}\n```\n\n**What this does**: {explanation of PR's intent}\n\n### Option B: Keep Base Branch Changes\n```{language}\n{code from base branch}\n```\n\n**What this does**: {explanation of base branch's intent}\n\n### Option C: Merge Both (Recommended if compatible)\n```{language}\n{merged version if possible}\n```\n\n**Why**: {explanation of why this merge makes sense}\n\n### Option D: Custom Resolution Needed\nThe changes are incompatible. Manual review required.\n\n---\n\n**Recommendation**: Option {X}\n\n**Reasoning**: {why this option based on:\n- Code functionality\n- PR intent from title/description\n- Which change is more recent/complete\n- Impact on other code}\n```\n\n### 3.3 Apply Resolutions\n\nFor each conflict:\n\n1. **If auto-resolvable**: Apply the resolution\n2. **If needs decision**: Use recommended option (or ask user if unclear)\n\n```bash\n# After editing each file\ngit add {file}\n```\n\n### 3.4 Continue Rebase\n\n```bash\n# After resolving all conflicts in current commit\ngit rebase --continue\n```\n\nRepeat for any additional conflicting commits.\n\n**PHASE_3_CHECKPOINT:**\n- [ ] All simple conflicts auto-resolved\n- [ ] Complex conflicts resolved with documented reasoning\n- [ ] All files staged\n- [ ] Rebase completed\n\n---\n\n## Phase 4: VALIDATE - Verify Resolution\n\n### 4.1 Check No Remaining Conflicts\n\n```bash\ngit diff --check\n```\n\nShould return empty (no conflict markers remaining).\n\n### 4.2 Verify Code Compiles\n\n```bash\nbun run type-check\n```\n\nIf type errors related to resolution, fix them.\n\n### 4.3 Run Tests\n\n```bash\nbun test\n```\n\nIf tests fail due to resolution, investigate and fix.\n\n### 4.4 Lint Check\n\n```bash\nbun run lint\n```\n\nFix any lint issues.\n\n**PHASE_4_CHECKPOINT:**\n- [ ] No conflict markers remaining\n- [ ] Type check passes\n- [ ] Tests pass\n- [ ] Lint passes\n\n---\n\n## Phase 5: PUSH - Update the PR\n\n### 5.1 Force Push the Resolved Branch\n\n```bash\ngit push --force-with-lease origin $PR_HEAD\n```\n\n**Note**: `--force-with-lease` is safer than `--force` as it fails if someone else pushed.\n\n### 5.2 Verify PR is Now Mergeable\n\n```bash\ngh pr view {number} --json mergeable,mergeStateStatus\n```\n\nShould show `MERGEABLE`.\n\n**PHASE_5_CHECKPOINT:**\n- [ ] Branch pushed successfully\n- [ ] PR shows as mergeable\n\n---\n\n## Phase 6: REPORT - Document Resolution\n\n### 6.1 Create Resolution Artifact\n\nWrite to `$ARTIFACTS_DIR/../reviews/pr-{number}/conflict-resolution.md` (create dir if needed):\n\n```markdown\n# Conflict Resolution: PR #{number}\n\n**Date**: {ISO timestamp}\n**Branch**: {head} rebased onto {base}\n\n---\n\n## Summary\n\nResolved {N} conflicts in {M} files.\n\n---\n\n## Conflicts Resolved\n\n### File: `{file1}`\n\n**Conflict Type**: {SIMPLE_ADDITION | SAME_LINES | etc.}\n**Resolution**: {Auto-resolved | Option A/B/C chosen}\n\n**Before (conflict)**:\n```{language}\n<<<<<<< HEAD\n{head version}\n=======\n{base version}\n>>>>>>> {base}\n```\n\n**After (resolved)**:\n```{language}\n{final code}\n```\n\n**Reasoning**: {why this resolution}\n\n---\n\n### File: `{file2}`\n\n{Same structure...}\n\n---\n\n## Validation\n\n| Check | Status |\n|-------|--------|\n| No conflict markers | ✅ |\n| Type check | ✅ |\n| Tests | ✅ |\n| Lint | ✅ |\n\n---\n\n## Git Log\n\n```\n{git log --oneline -5}\n```\n\n---\n\n## Metadata\n\n- **Resolved by**: Archon\n- **Timestamp**: {ISO timestamp}\n```\n\n### 6.2 Post GitHub Comment\n\n```bash\ngh pr comment {number} --body \"$(cat <<'EOF'\n## ✅ Conflicts Resolved\n\n**Rebased onto**: `{base}`\n**Conflicts resolved**: {N} in {M} files\n\n### Resolution Summary\n\n| File | Conflict Type | Resolution |\n|------|---------------|------------|\n| `{file1}` | {type} | {resolution approach} |\n| `{file2}` | {type} | {resolution approach} |\n\n### Validation\n✅ Type check | ✅ Tests | ✅ Lint\n\n### Details\nSee `$ARTIFACTS_DIR/../reviews/pr-{number}/conflict-resolution.md` for full resolution details.\n\n---\n*Resolved by Archon resolve-conflicts workflow*\nEOF\n)\"\n```\n\n**PHASE_6_CHECKPOINT:**\n- [ ] Artifact created\n- [ ] GitHub comment posted\n\n---\n\n## Phase 7: OUTPUT - Final Report\n\n```markdown\n## ✅ Conflicts Resolved\n\n**PR**: #{number} - {title}\n**Branch**: `{head}` rebased onto `{base}`\n\n### Summary\n- **Files with conflicts**: {M}\n- **Conflicts resolved**: {N}\n- **Auto-resolved**: {X}\n- **Manual decisions**: {Y}\n\n### Resolution Details\n\n| File | Type | Resolution |\n|------|------|------------|\n| `{file}` | {type} | {approach} |\n\n### Validation\n| Check | Status |\n|-------|--------|\n| Type check | ✅ |\n| Tests | ✅ |\n| Lint | ✅ |\n\n### Artifacts\n- Resolution details: `$ARTIFACTS_DIR/../reviews/pr-{number}/conflict-resolution.md`\n\n### Next Steps\n1. Review the resolution if needed: `git log -p -1`\n2. PR is now ready for review\n3. Request review: `@archon review this PR`\n```\n\n---\n\n## Error Handling\n\n### Rebase Fails Mid-way\n\nIf rebase fails on a commit that can't be resolved:\n\n```bash\n# Check status\ngit status\n\n# If truly stuck, abort and report\ngit rebase --abort\n```\n\nReport the failure with details about which commit and why.\n\n### Push Fails\n\nIf `--force-with-lease` fails (someone else pushed):\n\n1. Fetch latest\n2. Re-analyze conflicts\n3. Start over\n\n### Validation Fails After Resolution\n\nIf type-check/tests fail after resolution:\n\n1. Investigate which resolution caused the issue\n2. Try alternative resolution\n3. If stuck, report and suggest manual review\n\n---\n\n## Success Criteria\n\n- **CONFLICTS_IDENTIFIED**: All conflicting files found\n- **CONFLICTS_RESOLVED**: All conflicts resolved (auto or manual)\n- **VALIDATION_PASSED**: Type check, tests, lint all pass\n- **BRANCH_PUSHED**: PR branch updated with resolution\n- **PR_MERGEABLE**: GitHub shows PR as mergeable\n- **DOCUMENTED**: Resolution artifact and GitHub comment created\n",
+  "archon-self-fix-all": "---\ndescription: Aggressively fix all review findings - lean towards fixing unless clearly a new concern\nargument-hint: (none - reads all review artifacts from $ARTIFACTS_DIR/review/)\n---\n\n# Self-Fix All Review Findings\n\n---\n\n## IMPORTANT: Output Behavior\n\n**Your output will be posted as a GitHub comment.** Keep working output minimal:\n- Do NOT narrate each step\n- Do NOT output verbose progress updates\n- Only output the final structured report at the end\n\n---\n\n## Your Mission\n\nRead all review artifacts and fix EVERYTHING surfaced. Unlike conservative auto-fix, you lean aggressively towards fixing. LLMs are fast at generating code — use that advantage to add tests, fix docs, improve error handling, and address all findings.\n\n**Philosophy**: Fix it unless it's clearly a NEW unrelated concern that deserves its own issue. Adding tests for existing code? Fix it. Updating docs? Fix it. Adding missing error handling? Fix it. The bar for skipping is HIGH — only skip when the fix would introduce a genuinely new feature or concern outside the PR's scope.\n\n**Output artifact**: `$ARTIFACTS_DIR/review/fix-report.md`\n**Git action**: Commit AND push fixes to the PR branch\n**GitHub action**: Post fix report as a comment on the PR\n\n---\n\n## Phase 1: LOAD — Get Context\n\n### 1.1 Get PR Number and Branch\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number)\nHEAD_BRANCH=$(gh pr view $PR_NUMBER --json headRefName --jq '.headRefName')\necho \"PR: $PR_NUMBER, Branch: $HEAD_BRANCH\"\n```\n\n### 1.2 Checkout PR Branch\n\n```bash\ngit fetch origin $HEAD_BRANCH\ngit checkout $HEAD_BRANCH\ngit pull origin $HEAD_BRANCH\n```\n\nVerify:\n\n```bash\ngit branch --show-current\ngit status --porcelain\n```\n\n### 1.3 Read All Review Artifacts\n\n```bash\nls $ARTIFACTS_DIR/review/\n```\n\nRead each `.md` file that contains findings (e.g. `code-review-findings.md`, `error-handling-findings.md`, `test-coverage-findings.md`, `comment-quality-findings.md`, `docs-impact-findings.md`, `consolidated-review.md`). Skip `scope.md` and `fix-report.md`.\n\n```bash\nfor f in $ARTIFACTS_DIR/review/*.md; do\n  echo \"=== $f ===\"; cat \"$f\"; echo\ndone\n```\n\n### 1.4 Extract All Findings\n\nCompile a unified list of ALL findings with severity, location, and suggested fix.\n\n**PHASE_1_CHECKPOINT:**\n\n- [ ] PR number and branch identified\n- [ ] On correct PR branch\n- [ ] All review artifacts read\n- [ ] All findings extracted\n\n---\n\n## Phase 2: TRIAGE — Decide What to Fix\n\nFor each finding, decide: **FIX** or **SKIP**.\n\n### FIX (default — lean towards fixing):\n\n- Real bugs, type errors, silent failures, code quality issues\n- Missing tests for changed or existing code touched by the PR\n- Missing or outdated documentation\n- Error handling gaps\n- Comment quality issues\n- Import organization\n- Naming improvements\n- Any finding where the fix is concrete and the code is within the PR's touched area\n\n### SKIP only if:\n\n- The fix introduces a **genuinely new feature** not related to the PR\n- The fix requires **architectural changes** that affect untouched subsystems\n- The fix is about code **completely unrelated** to the PR's changes\n- The finding is factually wrong or based on a misunderstanding\n\n**Key principle**: If the review agent found it while reviewing THIS PR, it's fair game to fix. Tests, docs, simplification, error handling — all fixable. The only skip reason is \"this is a new concern that deserves its own issue.\"\n\nFor each skipped finding, write down **the specific reason**.\n\n**PHASE_2_CHECKPOINT:**\n\n- [ ] Every finding marked FIX or SKIP\n- [ ] Skip reasons documented (should be very few)\n\n---\n\n## Phase 3: IMPLEMENT — Apply Fixes\n\n### 3.1 For Each Finding Marked FIX\n\n1. Read the relevant file(s)\n2. Apply the fix following the suggested approach\n3. Run type-check after each fix: `bun run type-check`\n4. Note exactly what was changed\n\n### 3.2 Add Tests\n\nFor ANY finding about missing tests:\n\n1. Create or update the test file\n2. Write meaningful tests (not just stubs)\n3. Run them: `bun test {file}`\n\n### 3.3 Fix Documentation\n\nFor ANY finding about docs:\n\n1. Update the relevant documentation\n2. Ensure accuracy with the current code\n\n### 3.4 Handle Blocked Fixes\n\nIf a fix cannot be applied (code changed since review, fix would break other things), mark as **BLOCKED** with reason. Do not force a broken fix.\n\n**PHASE_3_CHECKPOINT:**\n\n- [ ] All FIX findings attempted\n- [ ] Tests added where flagged\n- [ ] Docs updated where flagged\n- [ ] BLOCKED findings documented\n\n---\n\n## Phase 4: VALIDATE — Full Check\n\n```bash\nbun run type-check\nbun run lint\nbun test\n```\n\nAll must pass. If something fails after a fix:\n\n1. Review the error\n2. Adjust the fix or revert it and mark BLOCKED\n3. Re-run until clean\n\n**PHASE_4_CHECKPOINT:**\n\n- [ ] Type check passes\n- [ ] Lint passes\n- [ ] Tests pass\n\n---\n\n## Phase 5: COMMIT AND PUSH\n\n### 5.1 Stage and Commit\n\nOnly stage files you actually changed:\n\n```bash\ngit add {specific files}\ngit status\ngit commit -m \"$(cat <<'EOF'\nfix: address review findings\n\nFixed:\n- {brief list of fixes}\n\nTests added:\n- {brief list if any}\n\nSkipped:\n- {brief list if any, with reasons}\nEOF\n)\"\n```\n\n### 5.2 Push\n\n```bash\ngit push origin $HEAD_BRANCH\n```\n\nIf push fails due to divergence:\n\n```bash\ngit pull --rebase origin $HEAD_BRANCH\ngit push origin $HEAD_BRANCH\n```\n\n**PHASE_5_CHECKPOINT:**\n\n- [ ] Changes committed\n- [ ] Pushed to PR branch\n\n---\n\n## Phase 6: GENERATE — Write Fix Report\n\nWrite to `$ARTIFACTS_DIR/review/fix-report.md`:\n\n```markdown\n# Fix Report: PR #{number}\n\n**Date**: {ISO timestamp}\n**Status**: COMPLETE | PARTIAL\n**Branch**: {HEAD_BRANCH}\n**Commit**: {commit hash}\n**Philosophy**: Aggressive fix — lean towards fixing everything\n\n---\n\n## Summary\n\n{2-3 sentences: what was found, what was fixed, what was skipped and why}\n\n---\n\n## Fixes Applied\n\n| Severity | Finding | Location | What Was Done |\n|----------|---------|----------|---------------|\n| CRITICAL | {title} | `file:line` | {description} |\n| HIGH     | {title} | `file:line` | {description} |\n| MEDIUM   | {title} | `file:line` | {description} |\n| LOW      | {title} | `file:line` | {description} |\n\n---\n\n## Tests Added\n\n| File | Test Cases |\n|------|------------|\n| `{file}.test.ts` | `{test description}` |\n\n*(none)* if no tests were added\n\n---\n\n## Docs Updated\n\n| File | Changes |\n|------|---------|\n| `{file}` | {what was updated} |\n\n*(none)* if no docs were updated\n\n---\n\n## Skipped Findings\n\n| Severity | Finding | Location | Reason Skipped |\n|----------|---------|----------|----------------|\n| {sev}    | {title} | `file:line` | New concern: {specific reason} |\n\n*(none)* if nothing was skipped — ideal outcome\n\n---\n\n## Blocked (Could Not Fix)\n\n| Severity | Finding | Reason |\n|----------|---------|--------|\n| {sev}    | {title} | {why it could not be applied} |\n\n*(none)* if nothing was blocked\n\n---\n\n## Suggested Follow-up Issues\n\n{For any skipped or blocked findings that warrant their own issue:}\n\n| Issue Title | Priority | Reason |\n|-------------|----------|--------|\n| \"{title}\" | {P1/P2/P3} | {why this deserves a separate issue} |\n\n*(none)* if everything was addressed\n\n---\n\n## Validation\n\n| Check | Status |\n|-------|--------|\n| Type check | ✅ / ❌ |\n| Lint | ✅ / ❌ |\n| Tests | ✅ {n} passed / ❌ |\n```\n\n**PHASE_6_CHECKPOINT:**\n\n- [ ] Fix report written\n\n---\n\n## Phase 7: POST — GitHub Comment\n\nPost the fix report as a PR comment:\n\n```bash\ngh pr comment $PR_NUMBER --body \"$(cat <<'EOF'\n## ⚡ Self-Fix Report (Aggressive)\n\n**Status**: {COMPLETE | PARTIAL}\n**Pushed**: ✅ Changes pushed to `{HEAD_BRANCH}`\n**Philosophy**: Fix everything unless clearly a new concern\n\n---\n\n### Fixes Applied ({n} total)\n\n| Severity | Count |\n|----------|-------|\n| 🔴 CRITICAL | {n} |\n| 🟠 HIGH | {n} |\n| 🟡 MEDIUM | {n} |\n| 🟢 LOW | {n} |\n\n<details>\n<summary>View all fixes</summary>\n\n{For each fix:}\n- ✅ **{title}** (`{file}:{line}`) — {brief description}\n\n</details>\n\n---\n\n### Tests Added\n\n{List or \"(none)\"}\n\n---\n\n### Skipped ({n})\n\n{If any:}\n| Finding | Reason |\n|---------|--------|\n| {title} | New concern: {reason} |\n\n*(none — all findings addressed)*\n\n---\n\n### Suggested Follow-up Issues\n\n{If any skipped/blocked items warrant issues:}\n1. **{Issue Title}** — {brief description}\n\n*(none)*\n\n---\n\n### Validation\n\n✅ Type check | ✅ Lint | ✅ Tests ({n} passed)\n\n---\n\n*Self-fix by Archon · aggressive mode · fixes pushed to `{HEAD_BRANCH}`*\nEOF\n)\"\n```\n\n**PHASE_7_CHECKPOINT:**\n\n- [ ] GitHub comment posted\n\n---\n\n## Phase 8: OUTPUT — Final Summary\n\n```\n## ⚡ Self-Fix Complete\n\n**PR**: #{number}\n**Branch**: {HEAD_BRANCH}\n**Status**: COMPLETE | PARTIAL\n\nFixed: {n} (across all severities)\nTests added: {n}\nDocs updated: {n}\nSkipped: {n} (new concerns only)\nBlocked: {n}\n\nValidation: ✅ All checks pass\nPushed: ✅\n\nFix report: $ARTIFACTS_DIR/review/fix-report.md\n```\n\n---\n\n## Success Criteria\n\n- **ON_CORRECT_BRANCH**: Working on PR's head branch\n- **ALL_FINDINGS_ADDRESSED**: Every finding is fixed, skipped (with reason), or blocked (with reason)\n- **AGGRESSIVE_FIXING**: Most findings fixed — skip rate should be very low\n- **TESTS_ADDED**: Missing test coverage addressed\n- **DOCS_UPDATED**: Documentation gaps filled\n- **VALIDATION_PASSED**: Type check, lint, and tests all pass\n- **COMMITTED_AND_PUSHED**: Changes committed and pushed to PR branch\n- **REPORTED**: Fix report artifact written and GitHub comment posted\n",
+  "archon-simplify-changes": "---\ndescription: Simplify code changed in this PR — implements fixes directly, commits, and pushes\nargument-hint: (none - operates on the current branch diff against $BASE_BRANCH)\n---\n\n# Simplify Changed Code\n\n---\n\n## IMPORTANT: Output Behavior\n\n**Your output will be posted as a GitHub comment.** Keep working output minimal:\n- Do NOT narrate each step\n- Do NOT output verbose progress updates\n- Only output the final structured report at the end\n\n---\n\n## Your Mission\n\nReview ALL code changed on this branch and implement simplifications directly. You are not advisory — you edit files, validate, commit, and push.\n\n## Scope\n\n**Only code changed in this PR** — run `git diff $BASE_BRANCH...HEAD --name-only` to get the file list. Do not touch unrelated files.\n\n## What to Simplify\n\n| Opportunity | What to Look For |\n|-------------|------------------|\n| **Unnecessary complexity** | Deep nesting, convoluted logic paths |\n| **Redundant code** | Duplicated logic, unused variables/imports |\n| **Over-abstraction** | Abstractions that obscure rather than clarify |\n| **Poor naming** | Unclear variable/function names |\n| **Nested ternaries** | Multiple conditions in ternary chains — use if/else |\n| **Dense one-liners** | Compact code that sacrifices readability |\n| **Obvious comments** | Comments that describe what code clearly shows |\n| **Inconsistent patterns** | Code that doesn't follow project conventions (read CLAUDE.md) |\n\n## Rules\n\n- **Preserve exact functionality** — simplification must not change behavior\n- **Clarity over brevity** — readable beats compact\n- **No speculative refactors** — only simplify what's obviously improvable\n- **Follow project conventions** — read CLAUDE.md before making changes\n- **Small, obvious changes** — each simplification should be self-evidently correct\n\n## Process\n\n### Phase 1: ANALYZE\n\n1. Read CLAUDE.md for project conventions\n2. Get changed files: `git diff $BASE_BRANCH...HEAD --name-only`\n3. Read each changed file\n4. Identify simplification opportunities per file\n\n### Phase 2: IMPLEMENT\n\nFor each simplification:\n1. Edit the file\n2. Run `bun run type-check` — if it fails, revert that change\n3. Run `bun run lint` — if it fails, fix or revert\n\n### Phase 3: VALIDATE & COMMIT\n\n1. Run full validation: `bun run type-check && bun run lint`\n2. If changes were made:\n   ```bash\n   git add -A\n   git commit -m \"simplify: reduce complexity in changed files\"\n   git push\n   ```\n3. If no simplifications found, skip commit\n\n### Phase 4: REPORT\n\nWrite report to `$ARTIFACTS_DIR/review/simplify-report.md` and output:\n\n```markdown\n## Code Simplification Report\n\n### Changes Made\n\n#### 1. [Brief Title]\n**File**: `path/to/file.ts:45-60`\n**Type**: Reduced nesting / Improved naming / Removed redundancy / etc.\n**Before**: [snippet]\n**After**: [snippet]\n\n---\n\n### Summary\n\n| Metric | Value |\n|--------|-------|\n| Files analyzed | X |\n| Simplifications applied | Y |\n| Net line change | -N lines |\n| Validation | PASS / FAIL |\n\n### No Changes Needed\n(If nothing to simplify, say so — \"Code is already clean. No simplifications applied.\")\n```\n",
+  "archon-sync-pr-with-main": "---\ndescription: Sync PR branch with latest main (rebase if needed, resolve conflicts if any)\nargument-hint: (none - uses PR from scope)\n---\n\n# Sync PR with Main\n\n---\n\n## Your Mission\n\nEnsure the PR branch is up-to-date with the latest main branch before review. Rebase if needed, resolve conflicts if any arise. This step is silent when no action is needed.\n\n**Output artifact**: `$ARTIFACTS_DIR/review/sync-report.md` (only if rebase/conflicts occurred)\n\n---\n\n## Phase 1: CHECK - Determine if Sync Needed\n\n### 1.1 Get PR Number from Registry\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number)\n```\n\n### 1.2 Read Scope\n\n```bash\ncat $ARTIFACTS_DIR/review/scope.md\n```\n\nGet branch names: `PR_HEAD` and `PR_BASE`.\n\n### 1.3 Fetch and Checkout PR Branch\n\n```bash\ngit fetch origin $PR_BASE\ngit fetch origin $PR_HEAD\n```\n\nConfirm you are on the PR's branch (`$PR_HEAD`). If not, checkout it:\n\n```bash\ngit checkout $PR_HEAD\n```\n\n### 1.4 Check if Behind\n\n```bash\n# Count commits PR branch is behind main\nBEHIND=$(git rev-list --count HEAD..origin/$PR_BASE)\necho \"Behind by: $BEHIND commits\"\n```\n\n**Decision:**\n\n| Behind Count | Action |\n|--------------|--------|\n| 0 | Skip - already up to date |\n| 1+ | Rebase needed |\n\n**If already up to date:**\n```markdown\nBranch is up to date with `{base}`. No sync needed.\n```\n**Exit early - no artifact created.**\n\n**PHASE_1_CHECKPOINT:**\n- [ ] PR number identified\n- [ ] Branches fetched\n- [ ] Behind count determined\n\n---\n\n## Phase 2: REBASE - Sync with Main\n\n### 2.1 Attempt Rebase\n\n```bash\ngit rebase origin/$PR_BASE\n```\n\n**Possible outcomes:**\n\n| Result | Next Step |\n|--------|-----------|\n| Success (no conflicts) | Go to Phase 4 (Validate) |\n| Conflicts | Go to Phase 3 (Resolve) |\n| Other error | Report and abort |\n\n### 2.2 Check for Conflicts\n\n```bash\n# If rebase stopped, check for conflicts\ngit diff --name-only --diff-filter=U\n```\n\nIf files listed → conflicts exist, go to Phase 3.\nIf empty → rebase successful, go to Phase 4.\n\n**PHASE_2_CHECKPOINT:**\n- [ ] Rebase attempted\n- [ ] Conflict status determined\n\n---\n\n## Phase 3: RESOLVE - Handle Conflicts (If Any)\n\n### 3.1 Identify Conflicting Files\n\n```bash\ngit diff --name-only --diff-filter=U\n```\n\n### 3.2 Analyze Each Conflict\n\nFor each conflicting file:\n\n```bash\n# Show conflict markers\ncat {file} | grep -A 10 -B 2 \"<<<<<<<\"\n```\n\n**Categorize:**\n- **SIMPLE**: One side added/changed, other didn't touch → Auto-resolve\n- **COMPLEX**: Both sides changed same lines → Need decision\n\n### 3.3 Auto-Resolve Simple Conflicts\n\nFor conflicts where intent is clear:\n- Both added different things → Keep both\n- One updated, other didn't → Keep update\n- Import additions → Merge both\n\n```bash\n# Edit file to resolve\n# Then stage\ngit add {file}\n```\n\n### 3.4 Resolve Complex Conflicts\n\nFor conflicts needing decision:\n\n1. Read both versions to understand intent\n2. Choose resolution based on:\n   - PR intent (what was the change trying to do?)\n   - Base branch updates (what changed in main?)\n   - Code correctness\n3. Apply resolution and stage\n\n```bash\ngit add {file}\n```\n\n### 3.5 Continue Rebase\n\n```bash\ngit rebase --continue\n```\n\nRepeat if more commits have conflicts.\n\n**PHASE_3_CHECKPOINT:**\n- [ ] All conflicts identified\n- [ ] Simple conflicts auto-resolved\n- [ ] Complex conflicts resolved with reasoning\n- [ ] Rebase completed\n\n---\n\n## Phase 4: VALIDATE - Verify Sync\n\n### 4.1 Check No Conflicts Remaining\n\n```bash\ngit diff --check\n```\n\nShould return empty.\n\n### 4.2 Type Check\n\n```bash\nbun run type-check\n```\n\n### 4.3 Run Tests\n\n```bash\nbun test\n```\n\n### 4.4 Lint\n\n```bash\nbun run lint\n```\n\n**If any fail**: Fix issues before proceeding.\n\n**PHASE_4_CHECKPOINT:**\n- [ ] No conflict markers\n- [ ] Type check passes\n- [ ] Tests pass\n- [ ] Lint passes\n\n---\n\n## Phase 5: PUSH - Update Remote\n\n### 5.1 Confirm Branch and Push\n\nConfirm you're on `$PR_HEAD`, then push:\n\n```bash\ngit push --force-with-lease origin $PR_HEAD\n```\n\n**Note**: `--force-with-lease` is safer - fails if someone else pushed.\n\n### 5.2 Verify Push\n\n```bash\ngit log origin/$PR_HEAD --oneline -3\n```\n\nConfirm local and remote match.\n\n**PHASE_5_CHECKPOINT:**\n- [ ] Branch pushed\n- [ ] Remote updated\n\n---\n\n## Phase 6: REPORT - Document Sync (Only if Rebase/Conflicts Occurred)\n\n### 6.1 Create Sync Artifact\n\nWrite to `$ARTIFACTS_DIR/review/sync-report.md`:\n\n```markdown\n# Sync Report: PR #{number}\n\n**Date**: {ISO timestamp}\n**Action**: Rebased onto `{base}`\n\n---\n\n## Summary\n\n- **Commits rebased**: {N}\n- **Conflicts resolved**: {M} (in {X} files)\n- **Status**: ✅ Synced successfully\n\n---\n\n## Conflicts Resolved\n\n{If conflicts were resolved:}\n\n### `{file}`\n\n**Type**: {SIMPLE | COMPLEX}\n**Resolution**: {description}\n\n```{language}\n{resolved code}\n```\n\n---\n\n{If no conflicts:}\n\nNo conflicts encountered during rebase.\n\n---\n\n## Validation\n\n| Check | Status |\n|-------|--------|\n| Type check | ✅ |\n| Tests | ✅ |\n| Lint | ✅ |\n\n---\n\n## Git State\n\n**Before**: {old HEAD commit}\n**After**: {new HEAD commit}\n**Commits ahead of {base}**: {count}\n\n---\n\n## Metadata\n\n- **Synced by**: Archon\n- **Timestamp**: {ISO timestamp}\n```\n\n### 6.2 Update Scope Artifact\n\nAppend to `$ARTIFACTS_DIR/review/scope.md`:\n\n```markdown\n---\n\n## Sync Status\n\n**Synced**: {ISO timestamp}\n**Rebased onto**: `{base}` at {commit}\n**Conflicts resolved**: {N}\n```\n\n**PHASE_6_CHECKPOINT:**\n- [ ] Sync artifact created (if action taken)\n- [ ] Scope artifact updated\n\n---\n\n## Phase 7: OUTPUT - Report Status\n\n### If Rebased (with or without conflicts):\n\n```markdown\n## ✅ PR Synced with Main\n\n**Branch**: `{head}` rebased onto `{base}`\n**Commits rebased**: {N}\n**Conflicts resolved**: {M}\n\nValidation: ✅ Type check | ✅ Tests | ✅ Lint\n\nProceeding to parallel review...\n```\n\n### If Already Up to Date:\n\n```markdown\n## ✅ PR Already Up to Date\n\nBranch `{head}` is current with `{base}`. No sync needed.\n\nProceeding to parallel review...\n```\n\n### If Sync Failed:\n\n```markdown\n## ❌ Sync Failed\n\n**Error**: {description}\n\n**Action Required**: Manual intervention needed.\n\n```bash\n# To abort the failed rebase\ngit rebase --abort\n```\n\n**Recommendation**: Resolve conflicts manually, then re-trigger review.\n```\n\n---\n\n## Error Handling\n\n### Rebase Fails Completely\n\n```bash\ngit rebase --abort\n```\n\nReport failure with specific error.\n\n### Push Rejected\n\nIf `--force-with-lease` fails:\n1. Someone else pushed to the branch\n2. Fetch and re-attempt rebase\n3. Or report for manual handling\n\n### Validation Fails\n\nIf type-check/tests fail after rebase:\n1. Investigate which changes broke\n2. Attempt to fix\n3. If unfixable, abort and report\n\n---\n\n## Success Criteria\n\n- **UP_TO_DATE**: Branch is synced with base (or was already)\n- **NO_CONFLICTS**: All conflicts resolved (if any existed)\n- **VALIDATION_PASSED**: Type check, tests, lint all pass\n- **PUSHED**: Remote branch updated (if rebase occurred)\n",
+  "archon-synthesize-review": "---\ndescription: Synthesize all review agent findings into consolidated report and post to GitHub\nargument-hint: (none - reads from review artifacts)\n---\n\n# Synthesize Review\n\n---\n\n## Your Mission\n\nRead all parallel review agent artifacts, synthesize findings into a consolidated report, create a master artifact, and post a comprehensive review comment to the GitHub PR.\n\n**Output artifact**: `$ARTIFACTS_DIR/review/consolidated-review.md`\n**GitHub action**: Post PR comment with full review\n\n---\n\n## Phase 1: LOAD - Gather All Findings\n\n### 1.1 Get PR Number from Registry\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number)\n```\n\n### 1.2 Read Scope\n\n```bash\ncat $ARTIFACTS_DIR/review/scope.md\n```\n\n### 1.3 Read All Agent Artifacts\n\n```bash\n# Read each agent's findings\ncat $ARTIFACTS_DIR/review/code-review-findings.md\ncat $ARTIFACTS_DIR/review/error-handling-findings.md\ncat $ARTIFACTS_DIR/review/test-coverage-findings.md\ncat $ARTIFACTS_DIR/review/comment-quality-findings.md\ncat $ARTIFACTS_DIR/review/docs-impact-findings.md\n```\n\n**PHASE_1_CHECKPOINT:**\n- [ ] PR number identified\n- [ ] All 5 agent artifacts read\n- [ ] Findings extracted from each\n\n---\n\n## Phase 2: SYNTHESIZE - Combine Findings\n\n### 2.1 Aggregate by Severity\n\nCombine all findings across agents:\n- **CRITICAL**: Must fix before merge\n- **HIGH**: Should fix before merge\n- **MEDIUM**: Consider fixing (options provided)\n- **LOW**: Nice to have (defer or create issue)\n\n### 2.2 Deduplicate\n\nCheck for overlapping findings:\n- Same issue reported by multiple agents\n- Related issues that should be grouped\n- Conflicting recommendations (resolve)\n\n### 2.3 Prioritize\n\nRank findings by:\n1. Severity (CRITICAL > HIGH > MEDIUM > LOW)\n2. User impact\n3. Ease of fix\n4. Risk if not fixed\n\n### 2.4 Compile Statistics\n\n```\nTotal findings: {n}\n- CRITICAL: {n}\n- HIGH: {n}\n- MEDIUM: {n}\n- LOW: {n}\n\nBy agent:\n- code-review: {n} findings\n- error-handling: {n} findings\n- test-coverage: {n} findings\n- comment-quality: {n} findings\n- docs-impact: {n} findings\n```\n\n**PHASE_2_CHECKPOINT:**\n- [ ] Findings aggregated by severity\n- [ ] Duplicates removed\n- [ ] Priority order established\n- [ ] Statistics compiled\n\n---\n\n## Phase 3: GENERATE - Create Consolidated Artifact\n\nWrite to `$ARTIFACTS_DIR/review/consolidated-review.md`:\n\n```markdown\n# Consolidated Review: PR #{number}\n\n**Date**: {ISO timestamp}\n**Agents**: code-review, error-handling, test-coverage, comment-quality, docs-impact\n**Total Findings**: {count}\n\n---\n\n## Executive Summary\n\n{3-5 sentence overview of PR quality and main concerns}\n\n**Overall Verdict**: {APPROVE | REQUEST_CHANGES | NEEDS_DISCUSSION}\n\n**Auto-fix Candidates**: {n} CRITICAL + HIGH issues can be auto-fixed\n**Manual Review Needed**: {n} MEDIUM + LOW issues require decision\n\n---\n\n## Statistics\n\n| Agent | CRITICAL | HIGH | MEDIUM | LOW | Total |\n|-------|----------|------|--------|-----|-------|\n| Code Review | {n} | {n} | {n} | {n} | {n} |\n| Error Handling | {n} | {n} | {n} | {n} | {n} |\n| Test Coverage | {n} | {n} | {n} | {n} | {n} |\n| Comment Quality | {n} | {n} | {n} | {n} | {n} |\n| Docs Impact | {n} | {n} | {n} | {n} | {n} |\n| **Total** | **{n}** | **{n}** | **{n}** | **{n}** | **{n}** |\n\n---\n\n## CRITICAL Issues (Must Fix)\n\n### Issue 1: {Title}\n\n**Source Agent**: {agent-name}\n**Location**: `{file}:{line}`\n**Category**: {category}\n\n**Problem**:\n{description}\n\n**Recommended Fix**:\n```typescript\n{fix code}\n```\n\n**Why Critical**:\n{impact explanation}\n\n---\n\n### Issue 2: {Title}\n\n{Same structure...}\n\n---\n\n## HIGH Issues (Should Fix)\n\n### Issue 1: {Title}\n\n{Same structure as CRITICAL...}\n\n---\n\n## MEDIUM Issues (Options for User)\n\n### Issue 1: {Title}\n\n**Source Agent**: {agent-name}\n**Location**: `{file}:{line}`\n\n**Problem**:\n{description}\n\n**Options**:\n\n| Option | Approach | Effort | Risk if Skipped |\n|--------|----------|--------|-----------------|\n| Fix Now | {approach} | {LOW/MED/HIGH} | {risk} |\n| Create Issue | Defer to separate PR | LOW | {risk} |\n| Skip | Accept as-is | NONE | {risk} |\n\n**Recommendation**: {which option and why}\n\n---\n\n## LOW Issues (For Consideration)\n\n| Issue | Location | Agent | Suggestion |\n|-------|----------|-------|------------|\n| {title} | `file:line` | {agent} | {brief recommendation} |\n| ... | ... | ... | ... |\n\n---\n\n## Positive Observations\n\n{Aggregated good things from all agents:\n- Well-structured code\n- Good error handling in X\n- Comprehensive tests for Y\n- Clear documentation}\n\n---\n\n## Suggested Follow-up Issues\n\nIf not addressing in this PR, create issues for:\n\n| Issue Title | Priority | Related Finding |\n|-------------|----------|-----------------|\n| \"{suggested issue title}\" | {P1/P2/P3} | MEDIUM issue #{n} |\n| ... | ... | ... |\n\n---\n\n## Next Steps\n\n1. **Auto-fix step** will address {n} CRITICAL + HIGH issues\n2. **Review** the MEDIUM issues and decide: fix now, create issue, or skip\n3. **Consider** LOW issues for future improvements\n\n---\n\n## Agent Artifacts\n\n| Agent | Artifact | Findings |\n|-------|----------|----------|\n| Code Review | `code-review-findings.md` | {n} |\n| Error Handling | `error-handling-findings.md` | {n} |\n| Test Coverage | `test-coverage-findings.md` | {n} |\n| Comment Quality | `comment-quality-findings.md` | {n} |\n| Docs Impact | `docs-impact-findings.md` | {n} |\n\n---\n\n## Metadata\n\n- **Synthesized**: {ISO timestamp}\n- **Artifact**: `$ARTIFACTS_DIR/review/consolidated-review.md`\n```\n\n**PHASE_3_CHECKPOINT:**\n- [ ] Consolidated artifact created\n- [ ] All findings included\n- [ ] Severity ordering correct\n- [ ] Options provided for MEDIUM/LOW\n\n---\n\n## Phase 4: POST - GitHub PR Comment\n\n### 4.1 Format for GitHub\n\nCreate a GitHub-friendly version of the review:\n\n```bash\ngh pr comment {number} --body \"$(cat <<'EOF'\n# 🔍 Comprehensive PR Review\n\n**PR**: #{number}\n**Reviewed by**: 5 specialized agents\n**Date**: {date}\n\n---\n\n## Summary\n\n{executive summary}\n\n**Verdict**: `{APPROVE | REQUEST_CHANGES}`\n\n| Severity | Count |\n|----------|-------|\n| 🔴 CRITICAL | {n} |\n| 🟠 HIGH | {n} |\n| 🟡 MEDIUM | {n} |\n| 🟢 LOW | {n} |\n\n---\n\n## 🔴 Critical Issues (Auto-fixing)\n\n{For each CRITICAL issue:}\n\n### {Title}\n📍 `{file}:{line}`\n\n{Brief description}\n\n<details>\n<summary>View fix</summary>\n\n```typescript\n{fix code}\n```\n\n</details>\n\n---\n\n## 🟠 High Issues (Auto-fixing)\n\n{Same format as CRITICAL}\n\n---\n\n## 🟡 Medium Issues (Needs Decision)\n\n{For each MEDIUM issue:}\n\n### {Title}\n📍 `{file}:{line}`\n\n{Brief description}\n\n**Options**: Fix now | Create issue | Skip\n\n<details>\n<summary>View details</summary>\n\n{full details and options table}\n\n</details>\n\n---\n\n## 🟢 Low Issues\n\n<details>\n<summary>View {n} low-priority suggestions</summary>\n\n| Issue | Location | Suggestion |\n|-------|----------|------------|\n| {title} | `file:line` | {suggestion} |\n\n</details>\n\n---\n\n## ✅ What's Good\n\n{Positive observations}\n\n---\n\n## 📋 Suggested Follow-up Issues\n\n{If any MEDIUM/LOW issues should become issues}\n\n---\n\n## Next Steps\n\n1. ⚡ Auto-fix step will address CRITICAL + HIGH issues\n2. 📝 Review MEDIUM issues above\n3. 🎯 Merge when ready\n\n---\n\n*Reviewed by Archon comprehensive-pr-review workflow*\n*Artifacts: `$ARTIFACTS_DIR/review/`*\nEOF\n)\"\n```\n\n**PHASE_4_CHECKPOINT:**\n- [ ] GitHub comment posted\n- [ ] Formatting renders correctly\n- [ ] All severity levels included\n\n---\n\n## Phase 5: OUTPUT - Confirmation\n\nOutput only a brief confirmation (this will be posted as a comment):\n\n```\n✅ Review synthesis complete. Proceeding to auto-fix step...\n```\n\n---\n\n## Success Criteria\n\n- **ALL_ARTIFACTS_READ**: All 5 agent findings loaded\n- **FINDINGS_SYNTHESIZED**: Combined, deduplicated, prioritized\n- **CONSOLIDATED_CREATED**: Master artifact written\n- **GITHUB_POSTED**: PR comment visible\n",
+  "archon-test-coverage-agent": "---\ndescription: Review test coverage quality, identify gaps, and evaluate test effectiveness\nargument-hint: (none - reads from scope artifact)\n---\n\n# Test Coverage Agent\n\n---\n\n## Your Mission\n\nAnalyze test coverage for the PR changes. Identify critical gaps, evaluate test quality, and ensure tests verify behavior (not implementation). Produce a structured artifact with findings and recommendations.\n\n**Output artifact**: `$ARTIFACTS_DIR/review/test-coverage-findings.md`\n\n---\n\n## Phase 1: LOAD - Get Context\n\n### 1.1 Get PR Number from Registry\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number)\n```\n\n### 1.2 Read Scope\n\n```bash\ncat $ARTIFACTS_DIR/review/scope.md\n```\n\nNote which files are source vs test files.\n\n**CRITICAL**: Check for \"NOT Building (Scope Limits)\" section. Items listed there are **intentionally excluded** - do NOT flag them as bugs or missing test coverage!\n\n### 1.3 Get PR Diff\n\n```bash\ngh pr diff {number}\n```\n\n### 1.4 Read Existing Tests\n\nFor each new/modified source file, find corresponding test file:\n\n```bash\n# Find test files\nfind src -name \"*.test.ts\" -o -name \"*.spec.ts\" | head -20\n```\n\n**PHASE_1_CHECKPOINT:**\n- [ ] PR number identified\n- [ ] Source and test files identified\n- [ ] Existing test patterns noted\n\n---\n\n## Phase 2: ANALYZE - Evaluate Coverage\n\n### 2.1 Map Source to Tests\n\nFor each changed source file:\n- Does a corresponding test file exist?\n- Are new functions/features tested?\n- Are modified functions' tests updated?\n\n### 2.2 Identify Critical Gaps\n\nLook for untested:\n- Error handling paths\n- Edge cases (null, empty, boundary values)\n- Critical business logic\n- Security-sensitive code\n- Async/concurrent behavior\n- Integration points\n\n### 2.3 Evaluate Test Quality\n\nFor existing tests, check:\n- Do they test behavior or implementation?\n- Would they catch meaningful regressions?\n- Are they resilient to refactoring?\n- Do they follow DAMP principles?\n- Are assertions meaningful?\n\n### 2.4 Find Test Patterns\n\n```bash\n# Find test patterns in codebase\ngrep -r \"describe\\|it\\|test\\(\" src/ --include=\"*.test.ts\" | head -20\n```\n\n**PHASE_2_CHECKPOINT:**\n- [ ] Source-to-test mapping complete\n- [ ] Critical gaps identified\n- [ ] Test quality evaluated\n- [ ] Codebase test patterns found\n\n---\n\n## Phase 3: GENERATE - Create Artifact\n\nWrite to `$ARTIFACTS_DIR/review/test-coverage-findings.md`:\n\n```markdown\n# Test Coverage Findings: PR #{number}\n\n**Reviewer**: test-coverage-agent\n**Date**: {ISO timestamp}\n**Source Files**: {count}\n**Test Files**: {count}\n\n---\n\n## Summary\n\n{2-3 sentence overview of test coverage quality}\n\n**Verdict**: {APPROVE | REQUEST_CHANGES | NEEDS_DISCUSSION}\n\n---\n\n## Coverage Map\n\n| Source File | Test File | New Code Tested | Modified Code Tested |\n|-------------|-----------|-----------------|---------------------|\n| `src/x.ts` | `src/x.test.ts` | FULL/PARTIAL/NONE | FULL/PARTIAL/NONE |\n| `src/y.ts` | (missing) | N/A | N/A |\n| ... | ... | ... | ... |\n\n---\n\n## Findings\n\n### Finding 1: {Descriptive Title}\n\n**Severity**: CRITICAL | HIGH | MEDIUM | LOW\n**Category**: missing-test | weak-test | implementation-coupled | missing-edge-case\n**Location**: `{file}:{line}` (source) / `{test-file}` (test)\n**Criticality Score**: {1-10}\n\n**Issue**:\n{Clear description of the coverage gap}\n\n**Untested Code**:\n```typescript\n// This code at {file}:{line} is not tested\n{untested code}\n```\n\n**Why This Matters**:\n{Specific bugs or regressions this could miss:\n- \"If {scenario}, users would see {bad outcome}\"\n- \"A future change to {X} could break {Y} without detection\"}\n\n---\n\n#### Test Suggestions\n\n| Option | Approach | Catches | Effort |\n|--------|----------|---------|--------|\n| A | {test approach} | {what it catches} | LOW/MED/HIGH |\n| B | {alternative} | {what it catches} | LOW/MED/HIGH |\n\n**Recommended**: Option {X}\n\n**Reasoning**:\n{Why this test approach:\n- Matches codebase test patterns\n- Tests behavior not implementation\n- Good cost/benefit ratio\n- Catches the most critical failures}\n\n**Recommended Test**:\n```typescript\ndescribe('{feature}', () => {\n  it('should {expected behavior}', () => {\n    // Arrange\n    {setup}\n\n    // Act\n    {action}\n\n    // Assert\n    {assertions}\n  });\n\n  it('should handle {edge case}', () => {\n    // Test edge case\n  });\n});\n```\n\n**Test Pattern Reference**:\n```typescript\n// SOURCE: {test-file}:{lines}\n// This is how similar functionality is tested\n{existing test from codebase}\n```\n\n---\n\n### Finding 2: {Title}\n\n{Same structure...}\n\n---\n\n## Test Quality Audit\n\n| Test | Tests Behavior | Resilient | Meaningful Assertions | Verdict |\n|------|---------------|-----------|----------------------|---------|\n| `it('should...')` | YES/NO | YES/NO | YES/NO | GOOD/NEEDS_WORK |\n| ... | ... | ... | ... | ... |\n\n---\n\n## Statistics\n\n| Severity | Count | Criticality 8-10 | Criticality 5-7 | Criticality 1-4 |\n|----------|-------|------------------|-----------------|-----------------|\n| CRITICAL | {n} | {n} | - | - |\n| HIGH | {n} | {n} | {n} | - |\n| MEDIUM | {n} | - | {n} | {n} |\n| LOW | {n} | - | - | {n} |\n\n---\n\n## Risk Assessment\n\n| Untested Area | Failure Mode | User Impact | Priority |\n|---------------|--------------|-------------|----------|\n| {code area} | {how it could fail} | {user sees} | CRITICAL/HIGH/MED |\n| ... | ... | ... | ... |\n\n---\n\n## Patterns Referenced\n\n| Test File | Lines | Pattern |\n|-----------|-------|---------|\n| `src/x.test.ts` | 10-30 | {testing pattern description} |\n| ... | ... | ... |\n\n---\n\n## Positive Observations\n\n{Good test coverage, well-written tests, proper mocking}\n\n---\n\n## Metadata\n\n- **Agent**: test-coverage-agent\n- **Timestamp**: {ISO timestamp}\n- **Artifact**: `$ARTIFACTS_DIR/review/test-coverage-findings.md`\n```\n\n**PHASE_3_CHECKPOINT:**\n- [ ] Artifact file created\n- [ ] Coverage map complete\n- [ ] Each gap has criticality score\n- [ ] Test suggestions with example code\n\n---\n\n## Success Criteria\n\n- **COVERAGE_MAPPED**: Each source file mapped to tests\n- **GAPS_IDENTIFIED**: Missing tests found with criticality scores\n- **QUALITY_EVALUATED**: Existing tests assessed\n- **TESTS_SUGGESTED**: Example test code provided for gaps\n",
+  "archon-validate-pr-code-review-feature": "---\ndescription: Analyze code on the feature branch to verify the PR's fix is correct and optimal\nargument-hint: (none - reads from artifacts)\n---\n\n# Code Review: Feature Branch (Post-PR State)\n\nAnalyze the code changes in the PR to verify the fix is correct, complete, and implemented in the best way possible.\n\n---\n\n## Phase 1: Load Context\n\n### 1.1 Read PR Details and Main Branch Analysis\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number | tr -d '\\n')\ngh pr view \"$PR_NUMBER\" --json title,body,headRefName,baseRefName,labels\n```\n\n```bash\n# Read the main branch analysis (guaranteed available — this node depends on code-review-main)\ncat $ARTIFACTS_DIR/code-review-main.md\n```\n\n### 1.2 Read Path Information\n\n```bash\ncat $ARTIFACTS_DIR/.worktree-path\ncat $ARTIFACTS_DIR/.feature-branch\n```\n\n---\n\n## Phase 2: Analyze the Diff\n\n### 2.1 Get the Full Diff\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number | tr -d '\\n')\ngh pr diff \"$PR_NUMBER\"\n```\n\n### 2.2 Read Changed Files on Feature Branch\n\nThe current working directory IS the feature branch (worktree). Read each changed file:\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number | tr -d '\\n')\n# List changed files\ngh pr view \"$PR_NUMBER\" --json files -q '.files[].path'\n```\n\nFor each file, read the full file in the current working directory to understand the complete context, not just the diff hunks.\n\n### 2.3 Deep Analysis of Each Change\n\nFor each changed file:\n\n1. **Read the full file** — understand the complete context around the changes\n2. **Compare with main** — read the same file from `$ARTIFACTS_DIR/.canonical-repo` to see the before/after\n3. **Evaluate the fix**:\n   - Does it actually address the bug/gap found on main?\n   - Is it the simplest possible fix? (KISS)\n   - Does it handle edge cases?\n   - Could it introduce new bugs?\n   - Does it follow existing patterns in the codebase?\n4. **Check CLAUDE.md compliance**:\n   ```bash\n   cat CLAUDE.md\n   ```\n   - Import patterns correct?\n   - Type annotations complete?\n   - Error handling appropriate?\n   - No unnecessary complexity?\n\n### 2.4 Look for Issues\n\nCheck for:\n- **Correctness**: Does the fix actually solve the problem?\n- **Completeness**: Are all aspects of the bug addressed?\n- **Side effects**: Could this break something else?\n- **Performance**: Any unnecessary re-renders, expensive operations?\n- **Type safety**: All types correct, no `any` without justification?\n- **Error handling**: Errors caught and handled appropriately?\n- **Overengineering**: More changes than necessary? (YAGNI)\n- **Missing changes**: Files that SHOULD have been changed but weren't?\n\n### 2.5 Compare Alternative Approaches\n\nThink about whether there's a better way to fix this:\n- Could a simpler approach work?\n- Is there an existing utility/pattern that should be used?\n- Would the fix work differently if applied at a different layer?\n\n---\n\n## Phase 3: Write Findings\n\nWrite your analysis to `$ARTIFACTS_DIR/code-review-feature.md`:\n\n```markdown\n# Feature Branch Code Review: PR #{number}\n\n**PR Title**: {title}\n**Feature Branch**: {branch}\n**Files Changed**: {count}\n**Lines**: +{additions} -{deletions}\n\n## Fix Assessment\n\n### Does the Fix Address the Bug?\n**YES / PARTIALLY / NO**\n\n{Explanation with specific code references}\n\n### Fix Quality\n\n| Criterion | Rating (1-5) | Notes |\n|-----------|-------------|-------|\n| Correctness | {n} | {does it fix the bug?} |\n| Completeness | {n} | {all edge cases handled?} |\n| Simplicity | {n} | {minimal changes, KISS?} |\n| Safety | {n} | {no side effects?} |\n| Patterns | {n} | {follows codebase conventions?} |\n\n**Overall Score**: {average}/5\n\n### File-by-File Analysis\n\n#### `{file1}`\n**Change Summary**: {what changed}\n**Assessment**: {good/needs-work/concern}\n```{language}\n// Key change\n{relevant code snippet}\n```\n**Notes**: {specific feedback}\n\n#### `{file2}`\n{Same structure...}\n\n### Issues Found\n\n#### Issue 1: {title}\n**Severity**: CRITICAL / HIGH / MEDIUM / LOW\n**File**: `{file}:{line}`\n**Description**: {what's wrong}\n**Suggested Fix**:\n```{language}\n{how to fix it}\n```\n\n### Alternative Approaches Considered\n{Were there better ways to implement this? If so, describe them and why they might be preferable.\nIf the current approach is optimal, say so and explain why.}\n\n### Missing Changes\n{Files or areas that should have been changed but weren't. If everything is covered, say so.}\n\n## CLAUDE.md Compliance\n\n| Rule | Status | Notes |\n|------|--------|-------|\n| Type annotations | PASS/FAIL | {details} |\n| Import patterns | PASS/FAIL | {details} |\n| Error handling | PASS/FAIL | {details} |\n| No any types | PASS/FAIL | {details} |\n| KISS principle | PASS/FAIL | {details} |\n\n## Verdict\n\n**APPROVE / REQUEST_CHANGES / NEEDS_DISCUSSION**\n\n{2-3 sentence final assessment: Is this fix ready to merge as-is?}\n```\n\n---\n\n## Success Criteria\n\n- **DIFF_ANALYZED**: Full PR diff reviewed\n- **FILES_READ**: All changed files read in full context\n- **MAIN_COMPARED**: Feature code compared against main branch code\n- **CLAUDE_MD_CHECKED**: CLAUDE.md compliance verified\n- **ARTIFACT_WRITTEN**: `$ARTIFACTS_DIR/code-review-feature.md` created\n",
+  "archon-validate-pr-code-review-main": "---\ndescription: Analyze code on the main/base branch to confirm the bug or gap exists before the PR's changes\nargument-hint: (none - reads from artifacts)\n---\n\n# Code Review: Main Branch (Pre-PR State)\n\nAnalyze the codebase on the **main branch** to confirm that the bug, gap, or missing feature described in the PR actually exists.\n\n---\n\n## Phase 1: Load Context\n\n### 1.1 Read PR Details\n\n```bash\ncat $ARTIFACTS_DIR/.pr-number\n```\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number | tr -d '\\n')\ngh pr view \"$PR_NUMBER\" --json title,body,headRefName,baseRefName,labels\n```\n\n### 1.2 Read Path Information\n\n```bash\ncat $ARTIFACTS_DIR/.canonical-repo\ncat $ARTIFACTS_DIR/.worktree-path\ncat $ARTIFACTS_DIR/.pr-base\n```\n\n### 1.3 Understand What the PR Claims to Fix\n\nFrom the PR title, body, and linked issue(s):\n- What bug or gap does the PR claim exists?\n- What is the expected behavior vs actual behavior?\n- Which files/components are involved?\n\nIf the PR body references a GitHub issue, fetch it:\n\n```bash\n# Extract issue number from PR body (looks for \"Fixes #N\", \"Closes #N\", etc.)\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number | tr -d '\\n')\nISSUE_NUMBER=$(gh pr view \"$PR_NUMBER\" --json body -q '.body' | grep -oE '(Fixes|Closes|Resolves)\\s*#[0-9]+' | grep -oE '[0-9]+' | head -1)\nif [ -n \"$ISSUE_NUMBER\" ]; then\n  gh issue view \"$ISSUE_NUMBER\" --json title,body,labels,comments\nfi\n```\n\n---\n\n## Phase 2: Analyze Main Branch Code\n\n### 2.1 Read the Files That the PR Changes\n\nGet the list of changed files from the PR diff, then read those **same files on the main branch** (the canonical repo path).\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number | tr -d '\\n')\ngh pr view \"$PR_NUMBER\" --json files -q '.files[].path'\n```\n\n**CRITICAL**: Read the files from the **canonical repo** (main branch), NOT from the current worktree (feature branch). The canonical repo path is in `$ARTIFACTS_DIR/.canonical-repo`.\n\nFor each changed file, read it from the main branch:\n\n```bash\nCANONICAL_REPO=$(cat $ARTIFACTS_DIR/.canonical-repo | tr -d '\\n')\n# Read each file from the canonical repo (on main branch)\ncat \"$CANONICAL_REPO/<file-path>\"\n```\n\n### 2.2 Trace the Bug or Gap\n\nFor each claim in the PR:\n1. **Find the relevant code** on main — read the specific functions, components, hooks\n2. **Trace the data flow** — where does the data come from? How does it transform?\n3. **Identify the root cause** — can you see the bug in the code?\n4. **Check related code** — are there adjacent issues the PR might miss?\n\n### 2.3 Assess Severity\n\n- How impactful is this bug/gap on main?\n- Is it user-facing or internal?\n- Does it affect core functionality or edge cases?\n- How likely is a user to encounter it?\n\n---\n\n## Phase 3: Write Findings\n\nWrite your analysis to `$ARTIFACTS_DIR/code-review-main.md`:\n\n```markdown\n# Main Branch Code Review: PR #{number}\n\n**PR Title**: {title}\n**Base Branch**: {base}\n**Analyzed Commit**: {main branch HEAD}\n\n## Bug/Gap Assessment\n\n### Claimed Issue\n{What the PR claims to fix}\n\n### Confirmed on Main?\n**YES / NO / PARTIAL**\n\n### Evidence\n\n{For each claim, provide specific code evidence:}\n\n#### Claim 1: {description}\n**Status**: Confirmed / Not Found / Partially Confirmed\n\n**Code Location**: `{file}:{lines}`\n```{language}\n{actual code on main showing the bug/gap}\n```\n\n**Analysis**: {Why this code is buggy/incomplete}\n\n#### Claim 2: {description}\n{Same structure...}\n\n### Related Issues Found\n{Any additional problems discovered in the same code areas}\n\n### Severity Assessment\n| Factor | Rating |\n|--------|--------|\n| User Impact | High / Medium / Low |\n| Frequency | Common / Uncommon / Rare |\n| Core Feature | Yes / No |\n| Data Loss Risk | Yes / No |\n\n## Summary\n{2-3 sentence summary: Is the bug real? How bad is it? Is the PR's scope appropriate?}\n```\n\n---\n\n## Success Criteria\n\n- **PR_CONTEXT_LOADED**: PR details and linked issue read\n- **MAIN_CODE_ANALYZED**: Changed files read from main branch\n- **BUG_ASSESSED**: Each PR claim verified against main branch code\n- **ARTIFACT_WRITTEN**: `$ARTIFACTS_DIR/code-review-main.md` created\n",
+  "archon-validate-pr-e2e-feature": "---\ndescription: Start Archon from the feature branch, use agent-browser to verify the fix works correctly\nargument-hint: (none - reads from artifacts)\n---\n\n# E2E Testing: Feature Branch (Verify Fix)\n\nStart Archon from the **feature branch** (this worktree) and use browser automation to verify that the bug is fixed and the UI/UX is correct. Take screenshots as evidence.\n\n**CRITICAL**: You MUST use the `agent-browser` CLI for ALL browser interactions. Load the `/agent-browser` skill for the full command reference.\n\n**CRITICAL**: You MUST clean up ALL spawned processes before finishing. Record PIDs and kill them in Phase 4. Orphaned processes from previous E2E runs may still be running — check and kill them first.\n\n**CRITICAL — SESSION ISOLATION**: This workflow runs in parallel with other validate-pr instances.\nYou MUST use `--session $WORKFLOW_ID` on EVERY `agent-browser` command to isolate your browser session.\nExample: `agent-browser --session $WORKFLOW_ID open \"http://...\"`, `agent-browser --session $WORKFLOW_ID snapshot -i`, etc.\n\n**ABSOLUTELY FORBIDDEN — NEVER DO ANY OF THESE**:\n- `taskkill //F //IM chrome.exe` or ANY variant that kills chrome by image name — this kills the USER's browser\n- `taskkill //F //IM node.exe` or `taskkill //F //IM bun.exe` — this kills Claude Code, the Archon server, and all other workflows\n- `pkill chrome`, `pkill node`, `pkill bun`, or any broad process-name kill\n- `agent-browser close` without `--session $WORKFLOW_ID` — this kills OTHER workflows' browser sessions\n- Any \"kill everything\" or \"kill all\" escalation pattern — if agent-browser isn't working, SKIP E2E testing and note it in your report\n- If agent-browser fails to connect after 2 attempts, STOP trying and write your findings based on code review only\n\n---\n\n## Phase 0: Kill Orphaned Processes from Previous E2E Run\n\nBefore starting, clean up any leftover processes from the main branch E2E test:\n\n```bash\nBACKEND_PORT=$(cat $ARTIFACTS_DIR/.backend-port | tr -d '\\n')\nFRONTEND_PORT=$(cat $ARTIFACTS_DIR/.frontend-port | tr -d '\\n')\n\n# Kill by PID files from main E2E run\nfor pidfile in \"$ARTIFACTS_DIR/.e2e-main-backend-pid\" \"$ARTIFACTS_DIR/.e2e-main-frontend-pid\"; do\n  if [ -f \"$pidfile\" ]; then\n    PID=$(cat \"$pidfile\" | tr -d '\\n')\n    echo \"Killing leftover main E2E PID $PID\"\n    kill \"$PID\" 2>/dev/null || taskkill //F //T //PID \"$PID\" 2>/dev/null || true\n  fi\ndone\n\n# Kill anything still on our ports\nfor PORT in $BACKEND_PORT $FRONTEND_PORT; do\n  fuser -k \"$PORT/tcp\" 2>/dev/null || true\n  lsof -ti:\"$PORT\" 2>/dev/null | xargs kill -9 2>/dev/null || true\n  netstat -ano 2>/dev/null | grep \":$PORT \" | grep LISTENING | awk '{print $5}' | sort -u | while read pid; do\n    taskkill //F //T //PID \"$pid\" 2>/dev/null || true\n  done\ndone\nsleep 2\necho \"Orphan cleanup complete\"\n```\n\n---\n\n## Phase 1: Load Context\n\n### 1.1 Read Artifacts\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number | tr -d '\\n')\nBACKEND_PORT=$(cat $ARTIFACTS_DIR/.backend-port | tr -d '\\n')\nFRONTEND_PORT=$(cat $ARTIFACTS_DIR/.frontend-port | tr -d '\\n')\nWORKTREE_PATH=$(cat $ARTIFACTS_DIR/.worktree-path | tr -d '\\n')\necho \"PR: #$PR_NUMBER\"\necho \"Backend port: $BACKEND_PORT\"\necho \"Frontend port: $FRONTEND_PORT\"\necho \"Feature branch path: $WORKTREE_PATH\"\n```\n\n### 1.2 Read Main Branch Test Results\n\n```bash\ncat $ARTIFACTS_DIR/e2e-main.md 2>/dev/null || echo \"No main branch E2E results available\"\n```\n\nThis tells you:\n- Which bugs were reproduced on main (you need to verify they're FIXED here)\n- Which test cases to re-run\n- What screenshots to compare against\n\n### 1.3 Read Code Reviews\n\n```bash\ncat $ARTIFACTS_DIR/code-review-main.md 2>/dev/null || echo \"\"\ncat $ARTIFACTS_DIR/code-review-feature.md 2>/dev/null || echo \"\"\n```\n\n---\n\n## Phase 2: Start Archon on Feature Branch\n\n### 2.1 Install Dependencies (if needed)\n\n```bash\nWORKTREE_PATH=$(cat $ARTIFACTS_DIR/.worktree-path | tr -d '\\n')\ncd \"$WORKTREE_PATH\" && bun install --frozen-lockfile 2>/dev/null || bun install\n```\n\n### 2.2 Start Backend on Custom Port\n\n**IMPORTANT**: Record the PID so we can kill it later. Redirect output to /dev/null to prevent terminal spawning.\n\n```bash\nWORKTREE_PATH=$(cat $ARTIFACTS_DIR/.worktree-path | tr -d '\\n')\nBACKEND_PORT=$(cat $ARTIFACTS_DIR/.backend-port | tr -d '\\n')\n\ncd \"$WORKTREE_PATH\" && PORT=$BACKEND_PORT bun run --filter @archon/server dev > \"$ARTIFACTS_DIR/.e2e-feature-backend.log\" 2>&1 &\nBACKEND_PID=$!\necho \"$BACKEND_PID\" > \"$ARTIFACTS_DIR/.e2e-feature-backend-pid\"\necho \"Backend started with PID: $BACKEND_PID\"\n\n# Poll until healthy (max 60s)\nMAX_WAIT=60\nWAITED=0\nuntil curl -sf \"http://localhost:$BACKEND_PORT/api/health\" > /dev/null 2>&1; do\n  if [ $WAITED -ge $MAX_WAIT ]; then\n    echo \"ERROR: Backend did not become healthy within ${MAX_WAIT}s\"\n    echo \"Last log lines:\"\n    tail -20 \"$ARTIFACTS_DIR/.e2e-feature-backend.log\" 2>/dev/null || true\n    exit 1\n  fi\n  sleep 2\n  WAITED=$((WAITED + 2))\ndone\necho \"Backend healthy after ${WAITED}s\"\ncurl -s \"http://localhost:$BACKEND_PORT/api/health\" | head -c 200\necho \"\"\n```\n\n### 2.3 Start Frontend on Custom Port\n\n```bash\nWORKTREE_PATH=$(cat $ARTIFACTS_DIR/.worktree-path | tr -d '\\n')\nBACKEND_PORT=$(cat $ARTIFACTS_DIR/.backend-port | tr -d '\\n')\nFRONTEND_PORT=$(cat $ARTIFACTS_DIR/.frontend-port | tr -d '\\n')\n\ncd \"$WORKTREE_PATH/packages/web\" && PORT=$BACKEND_PORT npx vite --port $FRONTEND_PORT --host > \"$ARTIFACTS_DIR/.e2e-feature-frontend.log\" 2>&1 &\nFRONTEND_PID=$!\necho \"$FRONTEND_PID\" > \"$ARTIFACTS_DIR/.e2e-feature-frontend-pid\"\necho \"Frontend started with PID: $FRONTEND_PID\"\n\n# Poll until serving (max 60s)\nMAX_WAIT=60\nWAITED=0\nuntil curl -sf \"http://localhost:$FRONTEND_PORT\" > /dev/null 2>&1; do\n  if [ $WAITED -ge $MAX_WAIT ]; then\n    echo \"ERROR: Frontend did not become ready within ${MAX_WAIT}s\"\n    echo \"Last log lines:\"\n    tail -20 \"$ARTIFACTS_DIR/.e2e-feature-frontend.log\" 2>/dev/null || true\n    exit 1\n  fi\n  sleep 2\n  WAITED=$((WAITED + 2))\ndone\necho \"Frontend ready after ${WAITED}s\"\ncurl -s \"http://localhost:$FRONTEND_PORT\" | head -c 100\necho \"\"\n```\n\n### 2.4 Seed Test Data (if needed)\n\n```bash\nBACKEND_PORT=$(cat $ARTIFACTS_DIR/.backend-port | tr -d '\\n')\n\n# Check if codebases exist\nCODEBASE_COUNT=$(curl -s \"http://localhost:$BACKEND_PORT/api/codebases\" | grep -c '\"id\"' || echo 0)\n\nif [ \"$CODEBASE_COUNT\" -eq 0 ]; then\n  WORKTREE_PATH=$(cat $ARTIFACTS_DIR/.worktree-path | tr -d '\\n')\n  curl -s -X POST \"http://localhost:$BACKEND_PORT/api/codebases\" \\\n    -H \"Content-Type: application/json\" \\\n    -d \"{\\\"path\\\": \\\"$WORKTREE_PATH\\\"}\"\nfi\n```\n\n---\n\n## Phase 3: Browser Testing (Verify Fix)\n\n### 3.1 Load the Agent-Browser Skill\n\n**YOU MUST LOAD THE AGENT-BROWSER SKILL NOW.** Use `/agent-browser` or invoke the skill. This gives you the full command reference for browser automation.\n\n### 3.2 Core Browser Workflow\n\n```bash\n# 1. Open the Archon UI (ALWAYS use --session)\nFRONTEND_PORT=$(cat $ARTIFACTS_DIR/.frontend-port | tr -d '\\n')\nagent-browser --session $WORKFLOW_ID open \"http://localhost:$FRONTEND_PORT\"\n\n# 2. Wait for the app to load\nagent-browser --session $WORKFLOW_ID wait --load networkidle\n\n# 3. Get interactive elements\nagent-browser --session $WORKFLOW_ID snapshot -i\n\n# 4. Take a screenshot of initial state\nagent-browser --session $WORKFLOW_ID screenshot \"$ARTIFACTS_DIR/e2e-feature-01-initial.png\"\n```\n\n### 3.3 Re-Run All Test Cases from Main\n\nFor EVERY test case that was run on main, re-run it on the feature branch:\n\n1. **Same preconditions** — set up identical starting state\n2. **Same reproduction steps** — follow the exact same actions\n3. **Verify the fix** — the bug should NOT be present now\n4. **Capture evidence** — screenshot at same points as main for side-by-side comparison\n5. **Read each screenshot** — use the Read tool to visually inspect\n6. **Compare with main** — explicitly note what's different\n\n### 3.4 Additional UX Validation\n\nBeyond just checking the bug is fixed, validate the overall experience:\n\n1. **Happy path works** — the normal user flow is smooth\n2. **Edge cases** — try unusual inputs, rapid clicks, page refreshes\n3. **Visual quality** — no layout issues, colors correct, text readable\n4. **Responsiveness** — resize the viewport, check different sizes:\n   ```bash\n   agent-browser --session $WORKFLOW_ID set viewport 1920 1080\n   agent-browser --session $WORKFLOW_ID screenshot \"$ARTIFACTS_DIR/e2e-feature-desktop.png\"\n   agent-browser --session $WORKFLOW_ID set viewport 768 1024\n   agent-browser --session $WORKFLOW_ID screenshot \"$ARTIFACTS_DIR/e2e-feature-tablet.png\"\n   ```\n5. **No regressions** — other features near the fix still work correctly\n\n### 3.5 API Cross-Verification\n\n```bash\nBACKEND_PORT=$(cat $ARTIFACTS_DIR/.backend-port | tr -d '\\n')\n\n# Verify data integrity matches UI\ncurl -s \"http://localhost:$BACKEND_PORT/api/conversations\" | head -c 500\n```\n\n---\n\n## Phase 4: Cleanup and Report\n\n**CRITICAL: You MUST complete cleanup before writing findings. Orphaned processes will accumulate and crash the system.**\n\n### 4.1 Close Browser\n\n```bash\n# ALWAYS use --session to only close YOUR browser, not other workflows'\nagent-browser --session $WORKFLOW_ID close 2>/dev/null || true\n```\n\n### 4.2 Stop Feature Branch Archon (Cross-Platform)\n\nKill processes by PID (recorded in Phase 2) AND by port (fallback). This works on both Windows and Unix.\n\n```bash\nBACKEND_PORT=$(cat $ARTIFACTS_DIR/.backend-port | tr -d '\\n')\nFRONTEND_PORT=$(cat $ARTIFACTS_DIR/.frontend-port | tr -d '\\n')\n\n# Kill by recorded PID (primary method — both main and feature PIDs)\nfor pidfile in \"$ARTIFACTS_DIR/.e2e-feature-backend-pid\" \"$ARTIFACTS_DIR/.e2e-feature-frontend-pid\" \"$ARTIFACTS_DIR/.e2e-main-backend-pid\" \"$ARTIFACTS_DIR/.e2e-main-frontend-pid\"; do\n  if [ -f \"$pidfile\" ]; then\n    PID=$(cat \"$pidfile\" | tr -d '\\n')\n    echo \"Killing PID $PID from $pidfile\"\n    kill \"$PID\" 2>/dev/null || taskkill //F //T //PID \"$PID\" 2>/dev/null || true\n  fi\ndone\n\n# Fallback: kill by port (handles child processes the PID kill might miss)\nfor PORT in $BACKEND_PORT $FRONTEND_PORT; do\n  echo \"Cleaning up port $PORT...\"\n  fuser -k \"$PORT/tcp\" 2>/dev/null || true\n  lsof -ti:\"$PORT\" 2>/dev/null | xargs kill -9 2>/dev/null || true\n  netstat -ano 2>/dev/null | grep \":$PORT \" | grep LISTENING | awk '{print $5}' | sort -u | while read pid; do\n    taskkill //F //T //PID \"$pid\" 2>/dev/null || true\n  done\ndone\n\nsleep 2\necho \"Cleanup complete — verify ports are free:\"\nnetstat -ano 2>/dev/null | grep -E \":($BACKEND_PORT|$FRONTEND_PORT) \" | grep LISTENING || echo \"All ports free\"\n```\n\n### 4.3 Write Findings\n\nWrite to `$ARTIFACTS_DIR/e2e-feature.md`:\n\n```markdown\n# E2E Test Results: Feature Branch\n\n**PR**: #{number}\n**Branch**: {feature-branch} @ {commit}\n**Backend Port**: {port}\n**Frontend Port**: {port}\n**Screenshots**: $ARTIFACTS_DIR/e2e-feature-*.png\n\n## Test Summary\n\n| Test Case | Main Result | Feature Result | Fix Verified? |\n|-----------|-------------|----------------|---------------|\n| {test 1} | BUG REPRODUCED | FIXED | YES / NO |\n| {test 2} | BUG REPRODUCED | FIXED | YES / NO |\n\n## Detailed Findings\n\n### Test 1: {description}\n**Main branch**: {bug behavior — reference e2e-main screenshot}\n**Feature branch**: {fixed behavior — reference e2e-feature screenshot}\n**Fix verified**: YES / NO / PARTIAL\n**Screenshot comparison**: `e2e-main-{N}.png` vs `e2e-feature-{N}.png`\n\n### Test 2: {description}\n{Same structure...}\n\n## UX Quality Assessment\n\n| Aspect | Rating (1-5) | Notes |\n|--------|-------------|-------|\n| Visual correctness | {n} | {details} |\n| Responsiveness | {n} | {details} |\n| Edge case handling | {n} | {details} |\n| Error states | {n} | {details} |\n| Performance feel | {n} | {details} |\n\n## Regressions Found\n{Any new issues introduced by the fix, or NONE}\n\n## Additional Observations\n{Any other UX improvements or issues noticed}\n\n## Fix Confidence\n**HIGH / MEDIUM / LOW**\n\n{Overall confidence that the fix works correctly and completely}\n```\n\n---\n\n## Success Criteria\n\n- **ARCHON_STARTED**: Backend and frontend running on feature branch code\n- **ALL_TESTS_RERUN**: Every test case from main branch E2E re-executed\n- **FIX_VERIFIED**: Each bug confirmed fixed (or documented as still present)\n- **UX_VALIDATED**: Visual quality, responsiveness, edge cases checked\n- **NO_REGRESSIONS**: No new issues introduced\n- **ARCHON_STOPPED**: Processes killed, ports freed — **VERIFY ports are free before finishing**\n- **ARTIFACT_WRITTEN**: `$ARTIFACTS_DIR/e2e-feature.md` created\n",
+  "archon-validate-pr-e2e-main": "---\ndescription: Start Archon from main branch, use agent-browser to reproduce the bug via E2E testing\nargument-hint: (none - reads from artifacts)\n---\n\n# E2E Testing: Main Branch (Reproduce Bug)\n\nStart Archon from the **main branch** code and use browser automation to reproduce the bug or gap described in the PR. Take screenshots as evidence.\n\n**CRITICAL**: You MUST use the `agent-browser` CLI for ALL browser interactions. Load the `/agent-browser` skill for the full command reference.\n\n**CRITICAL**: You MUST clean up ALL spawned processes before finishing. Record PIDs and kill them in Phase 4.\n\n**CRITICAL — SESSION ISOLATION**: This workflow runs in parallel with other validate-pr instances.\nYou MUST use `--session $WORKFLOW_ID` on EVERY `agent-browser` command to isolate your browser session.\nExample: `agent-browser --session $WORKFLOW_ID open \"http://...\"`, `agent-browser --session $WORKFLOW_ID snapshot -i`, etc.\nThe session ID is written to `$ARTIFACTS_DIR/.browser-session` for cleanup.\n\n**ABSOLUTELY FORBIDDEN — NEVER DO ANY OF THESE**:\n- `taskkill //F //IM chrome.exe` or ANY variant that kills chrome by image name — this kills the USER's browser\n- `taskkill //F //IM node.exe` or `taskkill //F //IM bun.exe` — this kills Claude Code, the Archon server, and all other workflows\n- `pkill chrome`, `pkill node`, `pkill bun`, or any broad process-name kill\n- `agent-browser close` without `--session $WORKFLOW_ID` — this kills OTHER workflows' browser sessions\n- Any \"kill everything\" or \"kill all\" escalation pattern — if agent-browser isn't working, SKIP E2E testing and note it in your report\n- If agent-browser fails to connect after 2 attempts, STOP trying and write your findings based on code review only\n\n---\n\n## Phase 1: Load Context\n\n### 1.1 Read Artifacts\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number | tr -d '\\n')\nBACKEND_PORT=$(cat $ARTIFACTS_DIR/.backend-port | tr -d '\\n')\nFRONTEND_PORT=$(cat $ARTIFACTS_DIR/.frontend-port | tr -d '\\n')\nCANONICAL_REPO=$(cat $ARTIFACTS_DIR/.canonical-repo | tr -d '\\n')\necho \"PR: #$PR_NUMBER\"\necho \"Backend port: $BACKEND_PORT\"\necho \"Frontend port: $FRONTEND_PORT\"\necho \"Main repo: $CANONICAL_REPO\"\n```\n\n### 1.2 Read PR and Test Plan\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number | tr -d '\\n')\ngh pr view \"$PR_NUMBER\" --json title,body\n```\n\n```bash\n# Read the main branch code review for context on what to test\ncat $ARTIFACTS_DIR/code-review-main.md 2>/dev/null || echo \"No main branch review available yet\"\n```\n\n### 1.3 Testability Classification\n\nThe testability classifier determined:\n- **Decision**: $classify-testability.output.testable\n- **Reasoning**: $classify-testability.output.reasoning\n- **Test Plan**: $classify-testability.output.test_plan\n\nUse the test plan above combined with the PR description and code review to build your execution plan:\n- What user journeys reproduce the bug?\n- What should the broken behavior look like?\n- What screenshots would prove the bug exists?\n\n---\n\n## Phase 2: Start Archon on Main Branch\n\n### 2.1 Create Isolated Main Branch Worktree\n\n**IMPORTANT**: Use a dedicated worktree instead of mutating the canonical repo. This is safe\nfor concurrent validation runs — each gets its own isolated checkout.\n\n```bash\nCANONICAL_REPO=$(cat $ARTIFACTS_DIR/.canonical-repo | tr -d '\\n')\nPR_BASE=$(cat $ARTIFACTS_DIR/.pr-base | tr -d '\\n')\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number | tr -d '\\n')\n\n# Create an isolated worktree for main branch E2E testing\nMAIN_E2E_PATH=\"$ARTIFACTS_DIR/main-checkout\"\ngit -C \"$CANONICAL_REPO\" fetch origin \"$PR_BASE\" --quiet\ngit -C \"$CANONICAL_REPO\" worktree add \"$MAIN_E2E_PATH\" \"origin/$PR_BASE\" --detach --quiet\necho \"$MAIN_E2E_PATH\" > \"$ARTIFACTS_DIR/.e2e-main-worktree\"\necho \"Main E2E worktree at: $MAIN_E2E_PATH\"\necho \"Base branch: $PR_BASE @ $(git -C \"$MAIN_E2E_PATH\" log --oneline -1)\"\n```\n\n### 2.2 Install Dependencies\n\n```bash\nMAIN_E2E_PATH=$(cat $ARTIFACTS_DIR/.e2e-main-worktree | tr -d '\\n')\ncd \"$MAIN_E2E_PATH\" && bun install --frozen-lockfile 2>/dev/null || bun install\n```\n\n### 2.3 Start Backend on Custom Port\n\n**IMPORTANT**: Record the PID so we can kill it later. Server output is logged for debugging.\n\n```bash\nMAIN_E2E_PATH=$(cat $ARTIFACTS_DIR/.e2e-main-worktree | tr -d '\\n')\nBACKEND_PORT=$(cat $ARTIFACTS_DIR/.backend-port | tr -d '\\n')\n\ncd \"$MAIN_E2E_PATH\" && PORT=$BACKEND_PORT bun run --filter @archon/server dev > \"$ARTIFACTS_DIR/.e2e-main-backend.log\" 2>&1 &\nBACKEND_PID=$!\necho \"$BACKEND_PID\" > \"$ARTIFACTS_DIR/.e2e-main-backend-pid\"\necho \"Backend started with PID: $BACKEND_PID\"\n\n# Poll until healthy (max 60s)\nMAX_WAIT=60\nWAITED=0\nuntil curl -sf \"http://localhost:$BACKEND_PORT/api/health\" > /dev/null 2>&1; do\n  if [ $WAITED -ge $MAX_WAIT ]; then\n    echo \"ERROR: Backend did not become healthy within ${MAX_WAIT}s\"\n    echo \"Last log lines:\"\n    tail -20 \"$ARTIFACTS_DIR/.e2e-main-backend.log\" 2>/dev/null || true\n    exit 1\n  fi\n  sleep 2\n  WAITED=$((WAITED + 2))\ndone\necho \"Backend healthy after ${WAITED}s\"\ncurl -s \"http://localhost:$BACKEND_PORT/api/health\" | head -c 200\necho \"\"\n```\n\n### 2.4 Start Frontend on Custom Port\n\n```bash\nMAIN_E2E_PATH=$(cat $ARTIFACTS_DIR/.e2e-main-worktree | tr -d '\\n')\nBACKEND_PORT=$(cat $ARTIFACTS_DIR/.backend-port | tr -d '\\n')\nFRONTEND_PORT=$(cat $ARTIFACTS_DIR/.frontend-port | tr -d '\\n')\n\ncd \"$MAIN_E2E_PATH/packages/web\" && PORT=$BACKEND_PORT npx vite --port $FRONTEND_PORT --host > \"$ARTIFACTS_DIR/.e2e-main-frontend.log\" 2>&1 &\nFRONTEND_PID=$!\necho \"$FRONTEND_PID\" > \"$ARTIFACTS_DIR/.e2e-main-frontend-pid\"\necho \"Frontend started with PID: $FRONTEND_PID\"\n\n# Poll until serving (max 60s)\nMAX_WAIT=60\nWAITED=0\nuntil curl -sf \"http://localhost:$FRONTEND_PORT\" > /dev/null 2>&1; do\n  if [ $WAITED -ge $MAX_WAIT ]; then\n    echo \"ERROR: Frontend did not become ready within ${MAX_WAIT}s\"\n    echo \"Last log lines:\"\n    tail -20 \"$ARTIFACTS_DIR/.e2e-main-frontend.log\" 2>/dev/null || true\n    exit 1\n  fi\n  sleep 2\n  WAITED=$((WAITED + 2))\ndone\necho \"Frontend ready after ${WAITED}s\"\ncurl -s \"http://localhost:$FRONTEND_PORT\" | head -c 100\necho \"\"\n```\n\n### 2.5 Seed Test Data (if needed)\n\n```bash\nBACKEND_PORT=$(cat $ARTIFACTS_DIR/.backend-port | tr -d '\\n')\n\n# Check if codebases exist\nCODEBASE_COUNT=$(curl -s \"http://localhost:$BACKEND_PORT/api/codebases\" | grep -c '\"id\"' || echo 0)\n\nif [ \"$CODEBASE_COUNT\" -eq 0 ]; then\n  MAIN_E2E_PATH=$(cat $ARTIFACTS_DIR/.e2e-main-worktree | tr -d '\\n')\n  curl -s -X POST \"http://localhost:$BACKEND_PORT/api/codebases\" \\\n    -H \"Content-Type: application/json\" \\\n    -d \"{\\\"path\\\": \\\"$MAIN_E2E_PATH\\\"}\"\nfi\n```\n\n---\n\n## Phase 3: Browser Testing (Reproduce Bug)\n\n### 3.1 Load the Agent-Browser Skill\n\n**YOU MUST LOAD THE AGENT-BROWSER SKILL NOW.** Use `/agent-browser` or invoke the skill. This gives you the full command reference for browser automation.\n\n### 3.2 Core Browser Workflow\n\nFollow this pattern for every interaction:\n\n```bash\n# 0. Store session ID for cleanup\necho \"$WORKFLOW_ID\" > \"$ARTIFACTS_DIR/.browser-session\"\n\n# 1. Open the Archon UI (ALWAYS use --session)\nFRONTEND_PORT=$(cat $ARTIFACTS_DIR/.frontend-port | tr -d '\\n')\nagent-browser --session $WORKFLOW_ID open \"http://localhost:$FRONTEND_PORT\"\n\n# 2. Wait for the app to load\nagent-browser --session $WORKFLOW_ID wait --load networkidle\n\n# 3. Get interactive elements\nagent-browser --session $WORKFLOW_ID snapshot -i\n\n# 4. Take a screenshot of initial state\nagent-browser --session $WORKFLOW_ID screenshot \"$ARTIFACTS_DIR/e2e-main-01-initial.png\"\n\n# 5. Interact using refs from snapshot\n# agent-browser --session $WORKFLOW_ID click @e1\n# agent-browser --session $WORKFLOW_ID fill @e2 \"text\"\n\n# 6. Re-snapshot after DOM changes\n# agent-browser --session $WORKFLOW_ID snapshot -i\n\n# 7. Take screenshots at every significant point\n# agent-browser --session $WORKFLOW_ID screenshot \"$ARTIFACTS_DIR/e2e-main-02-{step}.png\"\n```\n\n### 3.3 Execute Test Plan\n\nFollow the test plan derived from the PR description and code review. For EACH test case:\n\n1. **Set up the preconditions** — navigate to the right page, create conversations/workflows as needed\n2. **Execute the reproduction steps** — exactly as described in the issue/PR\n3. **Capture evidence** — screenshot BEFORE the action, DURING, and AFTER\n4. **Verify the broken behavior** — confirm what you see matches the reported bug\n5. **Read each screenshot** — use the Read tool to visually inspect screenshots\n6. **Document what you see** — note exact error messages, visual glitches, missing elements\n\n### 3.4 API Cross-Verification\n\nFor bugs involving data integrity or SSE, cross-reference the UI with direct API calls:\n\n```bash\nBACKEND_PORT=$(cat $ARTIFACTS_DIR/.backend-port | tr -d '\\n')\n\n# Check conversations\ncurl -s \"http://localhost:$BACKEND_PORT/api/conversations\" | head -c 500\n\n# Check specific conversation messages\n# curl -s \"http://localhost:$BACKEND_PORT/api/conversations/{id}/messages\"\n\n# Check workflow runs\n# curl -s \"http://localhost:$BACKEND_PORT/api/workflows/runs\"\n```\n\n---\n\n## Phase 4: Cleanup and Report\n\n**CRITICAL: You MUST complete cleanup before writing findings. Orphaned processes will accumulate and crash the system.**\n\n### 4.1 Close Browser\n\n```bash\n# ALWAYS use --session to only close YOUR browser, not other workflows'\nagent-browser --session $WORKFLOW_ID close 2>/dev/null || true\n```\n\n### 4.2 Stop Main Branch Archon (Cross-Platform)\n\nKill processes by PID (recorded in Phase 2) AND by port (fallback). This works on both Windows and Unix.\n\n```bash\nBACKEND_PORT=$(cat $ARTIFACTS_DIR/.backend-port | tr -d '\\n')\nFRONTEND_PORT=$(cat $ARTIFACTS_DIR/.frontend-port | tr -d '\\n')\n\n# Kill by recorded PID (primary method)\nfor pidfile in \"$ARTIFACTS_DIR/.e2e-main-backend-pid\" \"$ARTIFACTS_DIR/.e2e-main-frontend-pid\"; do\n  if [ -f \"$pidfile\" ]; then\n    PID=$(cat \"$pidfile\" | tr -d '\\n')\n    echo \"Killing PID $PID from $pidfile\"\n    # Try Unix kill first, then Windows taskkill\n    kill \"$PID\" 2>/dev/null || taskkill //F //T //PID \"$PID\" 2>/dev/null || true\n  fi\ndone\n\n# Fallback: kill by port (handles child processes the PID kill might miss)\n# Unix: fuser/lsof, Windows: netstat + taskkill\nfor PORT in $BACKEND_PORT $FRONTEND_PORT; do\n  echo \"Cleaning up port $PORT...\"\n  # Try fuser (Linux)\n  fuser -k \"$PORT/tcp\" 2>/dev/null || true\n  # Try lsof (macOS/Linux)\n  lsof -ti:\"$PORT\" 2>/dev/null | xargs kill -9 2>/dev/null || true\n  # Try netstat (Windows - Git Bash)\n  netstat -ano 2>/dev/null | grep \":$PORT \" | grep LISTENING | awk '{print $5}' | sort -u | while read pid; do\n    taskkill //F //T //PID \"$pid\" 2>/dev/null || true\n  done\ndone\n\nsleep 2\necho \"Process cleanup complete\"\n```\n\n### 4.3 Remove Main Branch Worktree\n\n```bash\nCANONICAL_REPO=$(cat $ARTIFACTS_DIR/.canonical-repo | tr -d '\\n')\nMAIN_E2E_PATH=$(cat \"$ARTIFACTS_DIR/.e2e-main-worktree\" 2>/dev/null | tr -d '\\n')\nif [ -n \"$MAIN_E2E_PATH\" ] && [ -d \"$MAIN_E2E_PATH\" ]; then\n  echo \"Removing main E2E worktree: $MAIN_E2E_PATH\"\n  git -C \"$CANONICAL_REPO\" worktree remove \"$MAIN_E2E_PATH\" --force 2>/dev/null || rm -rf \"$MAIN_E2E_PATH\"\nfi\necho \"Worktree cleanup complete\"\n```\n\n### 4.4 Write Findings\n\nWrite to `$ARTIFACTS_DIR/e2e-main.md`:\n\n```markdown\n# E2E Test Results: Main Branch\n\n**PR**: #{number}\n**Branch**: main @ {commit}\n**Backend Port**: {port}\n**Frontend Port**: {port}\n**Screenshots**: $ARTIFACTS_DIR/e2e-main-*.png\n\n## Test Summary\n\n| Test Case | Result | Evidence |\n|-----------|--------|----------|\n| {test 1} | BUG REPRODUCED / NOT REPRODUCED | e2e-main-{N}.png |\n| {test 2} | BUG REPRODUCED / NOT REPRODUCED | e2e-main-{N}.png |\n\n## Detailed Findings\n\n### Test 1: {description}\n**Steps**: {what was done}\n**Expected**: {what should happen on a fixed version}\n**Actual**: {what happened on main — the bug}\n**Screenshot**: `$ARTIFACTS_DIR/e2e-main-{N}.png`\n\n### Test 2: {description}\n{Same structure...}\n\n## Additional Issues Discovered\n{Any other bugs or UX issues noticed during testing}\n\n## Reproduction Confidence\n**HIGH / MEDIUM / LOW / NOT REPRODUCIBLE**\n\n{Explain confidence level. If not reproducible, explain what was tried.}\n```\n\n---\n\n## Success Criteria\n\n- **ARCHON_STARTED**: Backend and frontend running on allocated ports\n- **BROWSER_TESTED**: All test cases executed with agent-browser\n- **SCREENSHOTS_TAKEN**: Evidence captured for each test case\n- **BUG_ASSESSED**: Each PR claim tested on main branch\n- **ARCHON_STOPPED**: Processes killed, ports freed — **VERIFY ports are free before finishing**\n- **ARTIFACT_WRITTEN**: `$ARTIFACTS_DIR/e2e-main.md` created\n",
+  "archon-validate-pr-report": "---\ndescription: Synthesize all validation findings into a final PR verdict report\nargument-hint: (none - reads from artifacts)\n---\n\n# PR Validation Report\n\nSynthesize all code review and E2E testing findings into a comprehensive verdict.\n\n---\n\n## Phase 1: Gather All Artifacts\n\nRead every artifact produced by earlier workflow nodes:\n\n```bash\necho \"=== Available artifacts ===\"\nls -la $ARTIFACTS_DIR/\necho \"\"\necho \"=== Code review (main) ===\"\ncat $ARTIFACTS_DIR/code-review-main.md 2>/dev/null || echo \"NOT AVAILABLE\"\necho \"\"\necho \"=== Code review (feature) ===\"\ncat $ARTIFACTS_DIR/code-review-feature.md 2>/dev/null || echo \"NOT AVAILABLE\"\necho \"\"\necho \"=== E2E test (main) ===\"\ncat $ARTIFACTS_DIR/e2e-main.md 2>/dev/null || echo \"NOT AVAILABLE (code-review-only PR)\"\necho \"\"\necho \"=== E2E test (feature) ===\"\ncat $ARTIFACTS_DIR/e2e-feature.md 2>/dev/null || echo \"NOT AVAILABLE (code-review-only PR)\"\n```\n\nAlso read the PR details:\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number | tr -d '\\n')\ngh pr view \"$PR_NUMBER\" --json title,body,url,headRefName,baseRefName,additions,deletions,changedFiles\n```\n\nList all screenshots taken:\n\n```bash\nls $ARTIFACTS_DIR/e2e-*.png 2>/dev/null || echo \"No screenshots\"\n```\n\nIf screenshots exist, read a few key ones to include visual context in the report.\n\n---\n\n## Phase 2: Synthesize Findings\n\n### 2.1 Cross-Reference Code Review with E2E Results\n\nFor each bug/gap identified:\n- **Code review (main)**: Did the code analysis find the bug?\n- **E2E test (main)**: Was the bug visible in the UI?\n- **Code review (feature)**: Does the code fix look correct?\n- **E2E test (feature)**: Is the bug actually fixed in the UI?\n\n### 2.2 Identify Discrepancies\n\nLook for cases where:\n- Code review says it's fixed but E2E shows it's not\n- E2E shows it's fixed but the code fix is fragile/incomplete\n- New issues were found during E2E that code review missed\n- Code review found issues that E2E couldn't test\n\n### 2.3 Determine Final Verdict\n\n| Criteria | Required for APPROVE |\n|----------|---------------------|\n| Bug confirmed on main | Yes (or justified why not) |\n| Fix addresses root cause | Yes |\n| E2E confirms fix works | Yes (if E2E testable) |\n| No regressions | Yes |\n| Code quality acceptable | Yes |\n| CLAUDE.md compliant | Yes |\n\n---\n\n## Phase 3: Write Final Report\n\nWrite to `$ARTIFACTS_DIR/validation-report.md`:\n\n```markdown\n# PR Validation Report: #{number}\n\n**Title**: {PR title}\n**URL**: {PR URL}\n**Branch**: {head} → {base}\n**Files**: {count} changed (+{additions} -{deletions})\n**Validation Date**: {ISO timestamp}\n\n---\n\n## Verdict: {APPROVE / REQUEST_CHANGES / NEEDS_DISCUSSION}\n\n{2-3 sentence executive summary. Be direct: is this PR ready to merge?}\n\n---\n\n## Bug Confirmation\n\n| Claim | Confirmed on Main? | Fixed on Feature? | Evidence |\n|-------|--------------------|--------------------|----------|\n| {claim 1} | YES/NO | YES/NO | {screenshot refs or code refs} |\n| {claim 2} | YES/NO | YES/NO | {screenshot refs or code refs} |\n\n---\n\n## Code Review Summary\n\n### Main Branch (Pre-Fix)\n{Brief summary from code-review-main.md — was the bug evident in code?}\n\n### Feature Branch (Post-Fix)\n{Brief summary from code-review-feature.md — is the fix correct and optimal?}\n\n**Fix Quality Score**: {n}/5\n\n---\n\n## E2E Testing Summary\n\n{If E2E testing was performed:}\n\n### Main Branch (Bug Reproduction)\n{Brief summary from e2e-main.md — was the bug visible in the UI?}\n\n### Feature Branch (Fix Verification)\n{Brief summary from e2e-feature.md — is the fix verified in the UI?}\n\n**Fix Confidence**: HIGH / MEDIUM / LOW\n\n{If code-review-only:}\n\n_E2E testing was skipped — this PR's changes are not UI-visible. Validation based on code review only._\n\n---\n\n## Screenshots\n\n{List key screenshots with descriptions:}\n\n| Screenshot | Description |\n|------------|-------------|\n| `e2e-main-01-initial.png` | {what it shows} |\n| `e2e-feature-01-initial.png` | {what it shows — compare with main} |\n\n---\n\n## Issues Found\n\n### Must Fix Before Merge\n{CRITICAL or HIGH issues from any review stage. If none, say \"None.\"}\n\n### Should Fix (Non-Blocking)\n{MEDIUM issues — recommended but not blocking. If none, say \"None.\"}\n\n### Minor / Suggestions\n{LOW issues — nice to have. If none, say \"None.\"}\n\n---\n\n## Regressions\n{Any new issues introduced by the fix, or \"None found.\"}\n\n---\n\n## What's Done Well\n{Positive observations — good patterns, clean code, thorough fix}\n\n---\n\n## Recommendation\n\n**{APPROVE / REQUEST_CHANGES / NEEDS_DISCUSSION}**\n\n{Final paragraph: clear recommendation with reasoning. If REQUEST_CHANGES, list the specific changes needed. If NEEDS_DISCUSSION, describe what needs to be discussed.}\n```\n\n### 3.1 Post Summary to PR (optional)\n\nIf the verdict is clear, post a condensed summary to the PR as a comment:\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number | tr -d '\\n')\n\n# Create a concise PR comment\ngh pr comment \"$PR_NUMBER\" --body \"$(cat <<'COMMENT'\n## Archon PR Validation Report\n\n**Verdict**: {APPROVE / REQUEST_CHANGES}\n\n### Summary\n{2-3 sentence summary}\n\n### Bug Confirmation\n| Claim | Main | Feature |\n|-------|------|---------|\n| {claim} | {status} | {status} |\n\n### Issues\n{List any must-fix issues, or \"No blocking issues found.\"}\n\n---\n_Validated by archon-validate-pr workflow_\nCOMMENT\n)\"\n```\n\n---\n\n## Success Criteria\n\n- **ALL_ARTIFACTS_READ**: Every available artifact loaded and analyzed\n- **CROSS_REFERENCED**: Code review and E2E results reconciled\n- **VERDICT_DETERMINED**: Clear APPROVE / REQUEST_CHANGES / NEEDS_DISCUSSION\n- **REPORT_WRITTEN**: `$ARTIFACTS_DIR/validation-report.md` created\n- **PR_COMMENTED**: Summary posted to the PR\n",
+  "archon-validate": "---\ndescription: Run full validation suite - type-check, lint, tests, build\nargument-hint: (no arguments - reads from workflow artifacts)\n---\n\n# Validate Implementation\n\n**Workflow ID**: $WORKFLOW_ID\n\n---\n\n## Your Mission\n\nRun the complete validation suite and fix any failures.\n\nThis is a focused step: run checks, fix issues, repeat until green.\n\n---\n\n## Phase 1: LOAD - Get Validation Commands\n\n### 1.1 Load Plan Context\n\n```bash\ncat $ARTIFACTS_DIR/plan-context.md\n```\n\nExtract the \"Validation Commands\" section.\n\n### 1.2 Identify Package Manager\n\n```bash\ntest -f bun.lockb && echo \"bun\" || \\\ntest -f pnpm-lock.yaml && echo \"pnpm\" || \\\ntest -f yarn.lock && echo \"yarn\" || \\\ntest -f package-lock.json && echo \"npm\" || \\\necho \"unknown\"\n```\n\n### 1.3 Determine Available Commands\n\nCheck `package.json` for available scripts:\n\n```bash\ncat package.json | grep -A 20 '\"scripts\"'\n```\n\n**PHASE_1_CHECKPOINT:**\n\n- [ ] Validation commands identified\n- [ ] Package manager known\n\n---\n\n## Phase 2: VALIDATE - Run All Checks\n\nRun each check in order. Fix any failures before proceeding.\n\n### 2.1 Type Check\n\n```bash\n{runner} run type-check\n```\n\n**If fails:**\n1. Read error output\n2. Fix the type issues\n3. Re-run until passing\n\n**Record result**: ✅ Pass / ❌ Fail (fixed)\n\n### 2.2 Lint Check\n\n```bash\n{runner} run lint\n```\n\n**If fails:**\n\n1. Try auto-fix first:\n   ```bash\n   {runner} run lint:fix\n   ```\n\n2. Re-run lint check\n\n3. If still failing, manually fix remaining issues\n\n**Record result**: ✅ Pass / ❌ Fail (fixed)\n\n### 2.3 Format Check\n\n```bash\n{runner} run format:check\n```\n\n**If fails:**\n\n1. Auto-fix:\n   ```bash\n   {runner} run format\n   ```\n\n2. Verify fixed:\n   ```bash\n   {runner} run format:check\n   ```\n\n**Record result**: ✅ Pass / ❌ Fail (fixed)\n\n### 2.4 Test Suite\n\n```bash\n{runner} test\n```\n\n**If fails:**\n\n1. Identify which test(s) failed\n2. Determine: implementation bug or test bug?\n3. Fix the root cause\n4. Re-run tests\n\n**Record result**: ✅ Pass ({N} tests) / ❌ Fail (fixed)\n\n### 2.5 Build Check\n\n```bash\n{runner} run build\n```\n\n**If fails:**\n\n1. Usually a type or import issue\n2. Fix and re-run\n\n**Record result**: ✅ Pass / ❌ Fail (fixed)\n\n**PHASE_2_CHECKPOINT:**\n\n- [ ] Type check passes\n- [ ] Lint passes\n- [ ] Format passes\n- [ ] Tests pass\n- [ ] Build passes\n\n---\n\n## Phase 3: ARTIFACT - Write Validation Results\n\n### 3.1 Write Validation Artifact\n\nWrite to `$ARTIFACTS_DIR/validation.md`:\n\n```markdown\n# Validation Results\n\n**Generated**: {YYYY-MM-DD HH:MM}\n**Workflow ID**: $WORKFLOW_ID\n**Status**: {ALL_PASS | FIXED | BLOCKED}\n\n---\n\n## Summary\n\n| Check | Result | Details |\n|-------|--------|---------|\n| Type check | ✅ | No errors |\n| Lint | ✅ | 0 errors, {N} warnings |\n| Format | ✅ | All files formatted |\n| Tests | ✅ | {N} passed, 0 failed |\n| Build | ✅ | Compiled successfully |\n\n---\n\n## Type Check\n\n**Command**: `{runner} run type-check`\n**Result**: ✅ Pass\n\n{If issues were fixed:}\n### Issues Fixed\n\n- `src/file.ts:42` - Added missing return type\n- `src/other.ts:15` - Fixed generic constraint\n\n---\n\n## Lint\n\n**Command**: `{runner} run lint`\n**Result**: ✅ Pass\n\n{If issues were fixed:}\n### Issues Fixed\n\n- {N} auto-fixed by `lint:fix`\n- {M} manually fixed\n\n### Remaining Warnings\n\n{List any warnings that weren't fixed, with justification}\n\n---\n\n## Format\n\n**Command**: `{runner} run format:check`\n**Result**: ✅ Pass\n\n{If files were formatted:}\n### Files Formatted\n\n- `src/file.ts`\n- `src/other.ts`\n\n---\n\n## Tests\n\n**Command**: `{runner} test`\n**Result**: ✅ Pass\n\n| Metric | Count |\n|--------|-------|\n| Total tests | {N} |\n| Passed | {N} |\n| Failed | 0 |\n| Skipped | {M} |\n\n{If tests were fixed:}\n### Tests Fixed\n\n- `src/x.test.ts` - Fixed assertion to match new behavior\n\n---\n\n## Build\n\n**Command**: `{runner} run build`\n**Result**: ✅ Pass\n\nBuild output: `dist/` (or as configured)\n\n---\n\n## Files Modified During Validation\n\n{If any files were changed to fix issues:}\n\n| File | Changes |\n|------|---------|\n| `src/file.ts` | Fixed type error |\n| `src/other.ts` | Lint auto-fix |\n\n---\n\n## Next Step\n\nContinue to `archon-finalize-pr` to update PR and mark ready for review.\n```\n\n**PHASE_3_CHECKPOINT:**\n\n- [ ] Validation artifact written\n- [ ] All results documented\n\n---\n\n## Phase 4: OUTPUT - Report Results\n\n### If All Pass:\n\n```markdown\n## Validation Complete ✅\n\n**Workflow ID**: `$WORKFLOW_ID`\n\n### Results\n\n| Check | Status |\n|-------|--------|\n| Type check | ✅ |\n| Lint | ✅ |\n| Format | ✅ |\n| Tests | ✅ ({N} passed) |\n| Build | ✅ |\n\n{If issues were fixed:}\n### Issues Fixed\n\n- {N} type errors fixed\n- {M} lint issues fixed\n- {K} format issues fixed\n\n### Artifact\n\nResults written to: `$ARTIFACTS_DIR/validation.md`\n\n### Next Step\n\nProceed to `archon-finalize-pr` to update PR and mark ready for review.\n```\n\n### If Blocked (unfixable issue):\n\n```markdown\n## Validation Blocked ❌\n\n**Workflow ID**: `$WORKFLOW_ID`\n\n### Failed Check\n\n**{check-name}**: {error description}\n\n### Attempts to Fix\n\n1. {what was tried}\n2. {what was tried}\n\n### Required Action\n\nThis issue requires manual intervention:\n\n{description of what needs to be done}\n\n### Artifact\n\nPartial results written to: `$ARTIFACTS_DIR/validation.md`\n```\n\n---\n\n## Success Criteria\n\n- **TYPE_CHECK_PASS**: `{runner} run type-check` exits 0\n- **LINT_PASS**: `{runner} run lint` exits 0\n- **FORMAT_PASS**: `{runner} run format:check` exits 0\n- **TESTS_PASS**: `{runner} test` all green\n- **BUILD_PASS**: `{runner} run build` exits 0\n- **ARTIFACT_WRITTEN**: Validation results documented\n",
+  "archon-web-research": "---\ndescription: Research web sources for context relevant to a GitHub issue or feature\nargument-hint: <issue-number or search context>\n---\n\n# Web Research\n\n**Input**: $ARGUMENTS\n**Workflow ID**: $WORKFLOW_ID\n\n---\n\n## Your Mission\n\nSearch the web for information relevant to the issue or feature being worked on. Find official documentation, known issues, best practices, and solutions that will inform implementation.\n\n**Output**: `$ARTIFACTS_DIR/web-research.md`\n\n**Core Principle**: Search strategically, prioritize authoritative sources, cite everything.\n\n---\n\n## Phase 1: PARSE - Understand What to Research\n\n### 1.1 Get Issue Context\n\nIf input looks like a GitHub issue number:\n\n```bash\ngh issue view $ARGUMENTS --json title,body,labels\n```\n\n### 1.2 Identify Research Targets\n\nFrom the issue context, identify:\n\n- Key technologies, libraries, or APIs mentioned\n- Error messages or stack traces to search for\n- Concepts or patterns that need clarification\n- Version-specific documentation needs\n- Existing primitives in the ecosystem — what built-in or library-level abstractions already solve part of this? (avoids reinventing)\n\n### 1.3 Formulate Search Plan\n\nCreate 3-5 targeted search queries:\n\n| Query | Why | Expected Source |\n|-------|-----|-----------------|\n| \"{library} {feature} documentation\" | Official docs | Library website |\n| \"{error message}\" | Known issues | Stack Overflow, GitHub issues |\n| \"{pattern} best practices {year}\" | Current approaches | Blog posts, docs |\n| \"{library} built-in {primitive/feature}\" | Avoid reinventing | Official docs, changelog, migration guides |\n\n**PHASE_1_CHECKPOINT:**\n\n- [ ] Issue context understood\n- [ ] Research targets identified\n- [ ] Search queries formulated\n\n---\n\n## Phase 2: SEARCH - Execute Research\n\n### 2.1 Check for llms.txt\n\nMany sites publish LLM-optimized documentation:\n\n```\nTry fetching https://{domain}/llms.txt for any known site\nRead the result and fetch relevant sub-pages linked within\n```\n\n### 2.2 Search Official Documentation\n\nFor each technology/library involved:\n\n1. Search for official docs with version constraints\n2. Use `site:` operator for known authoritative sources\n3. Look for changelog/release notes for version info\n\n### 2.3 Search for Known Issues\n\nIf the issue involves errors or bugs:\n\n1. Search exact error messages in quotes\n2. Check GitHub issues for the relevant libraries\n3. Look for Stack Overflow answers\n\n### 2.4 Search for Best Practices\n\nIf the issue involves implementation decisions:\n\n1. Search for recognized patterns and approaches\n2. Cross-reference multiple sources\n3. Look for migration guides if changing approaches\n\n**PHASE_2_CHECKPOINT:**\n\n- [ ] At least 3 searches executed\n- [ ] Authoritative sources found\n- [ ] Relevant content extracted\n\n---\n\n## Phase 3: SYNTHESIZE - Compile Findings\n\n### 3.1 Organize by Relevance\n\nFor each finding:\n\n- **Source**: Name and URL\n- **Authority**: Why this source is credible\n- **Key information**: Direct quotes or specific facts\n- **Applies to**: Which part of the issue this informs\n- **Version/date**: Currency of the information\n\n### 3.2 Identify Conflicts or Gaps\n\n- Note any conflicting information between sources\n- Flag outdated content\n- Document what could NOT be found\n\n**PHASE_3_CHECKPOINT:**\n\n- [ ] Findings organized\n- [ ] Conflicts noted\n- [ ] Gaps documented\n\n---\n\n## Phase 4: GENERATE - Write Artifact\n\nWrite to `$ARTIFACTS_DIR/web-research.md`:\n\n```markdown\n# Web Research: $ARGUMENTS\n\n**Researched**: {ISO timestamp}\n**Workflow ID**: $WORKFLOW_ID\n\n---\n\n## Summary\n\n{2-3 sentence overview of key findings}\n\n---\n\n## Findings\n\n### {Source/Topic 1}\n\n**Source**: [{Name}]({URL})\n**Authority**: {Why credible}\n**Relevant to**: {Which part of the issue}\n\n**Key Information**:\n\n- {Finding 1}\n- {Finding 2}\n- {Version/date context}\n\n---\n\n### {Source/Topic 2}\n\n{Same structure...}\n\n---\n\n## Code Examples\n\n{If applicable — actual code from sources with attribution}\n\n```language\n// From [{source}]({url})\n{code example}\n```\n\n---\n\n## Gaps and Conflicts\n\n- {Information that couldn't be found}\n- {Conflicting claims between sources}\n- {Areas needing further investigation}\n\n---\n\n## Recommendations\n\nBased on research:\n\n1. {Recommendation 1 — what approach to take and why}\n2. {Recommendation 2 — what to avoid and why}\n\n---\n\n## Sources\n\n| # | Source | URL | Relevance |\n|---|--------|-----|-----------|\n| 1 | {name} | {url} | {brief relevance} |\n| 2 | {name} | {url} | {brief relevance} |\n```\n\n**PHASE_4_CHECKPOINT:**\n\n- [ ] Artifact written to `$ARTIFACTS_DIR/web-research.md`\n- [ ] All sources cited with URLs\n- [ ] Recommendations actionable\n\n---\n\n## Phase 5: OUTPUT - Report\n\n```markdown\n## Web Research Complete\n\n**Queries**: {n} searches executed\n**Sources**: {n} relevant sources found\n**Artifact**: `$ARTIFACTS_DIR/web-research.md`\n\n### Key Findings\n\n- {Finding 1}\n- {Finding 2}\n- {Finding 3}\n\n### Gaps\n\n- {What couldn't be found, if any}\n```\n\n---\n\n## Quality Standards\n\n| Standard | Requirement |\n|----------|-------------|\n| **Accuracy** | Quote sources exactly, provide direct links |\n| **Relevance** | Focus on what directly addresses the issue |\n| **Currency** | Note publication dates and versions |\n| **Authority** | Prioritize official docs, recognized experts |\n| **Completeness** | Search multiple angles, note gaps |\n| **Transparency** | Flag outdated, conflicting, or uncertain info |\n\n---\n\n## What NOT To Do\n\n- Don't guess when you can search\n- Don't fetch pages without checking search results first\n- Don't ignore publication dates on technical content\n- Don't present a single source as definitive without corroboration\n- Don't skip the Gaps section — be honest about limitations\n\n---\n\n## Success Criteria\n\n- **RESEARCH_EXECUTED**: At least 3 targeted searches completed\n- **SOURCES_CITED**: All findings have source URLs\n- **ARTIFACT_WRITTEN**: Research saved to `$ARTIFACTS_DIR/web-research.md`\n- **ACTIONABLE**: Findings directly inform implementation decisions\n",
+  "archon-workflow-summary": "---\ndescription: Final workflow summary with decision matrix for follow-up actions\nargument-hint: (no arguments - reads from workflow artifacts)\n---\n\n# Workflow Summary\n\n**Workflow ID**: $WORKFLOW_ID\n\n---\n\n## Your Mission\n\nCreate the final summary report for the workflow run:\n1. Summarize what was implemented vs the plan\n2. List deviations and their rationale\n3. Surface unfixed review findings (MEDIUM/LOW)\n4. Create actionable follow-up recommendations\n5. Post to GitHub PR as a comment\n6. Write artifact for future reference\n\n**Output**: Decision matrix the user can act on quickly.\n\n---\n\n## Phase 1: LOAD - Gather ALL Artifacts\n\n**CRITICAL**: Read EVERY artifact from the workflow run. Miss nothing.\n\n### 1.1 Scan Workflow Artifacts Directory\n\n```bash\n# List all artifacts from this workflow run\nls -la $ARTIFACTS_DIR/\n\n# Read each one\nfor file in $ARTIFACTS_DIR/*.md; do\n  echo \"=== $file ===\"\n  cat \"$file\"\ndone\n```\n\n**Expected artifacts**:\n- `plan-context.md` - Plan summary, scope limits, acceptance criteria\n- `plan-confirmation.md` - Pattern verification results\n- `implementation.md` - Tasks done, deviations, issues encountered\n- `validation.md` - Test/lint/build results\n- `pr-ready.md` - PR number, URL, final commit\n- `.pr-number` - PR number registry file\n- `.pr-url` - PR URL registry file\n\n### 1.2 Scan Review Artifacts\n\n```bash\n# Read review artifacts from workflow-scoped directory\nls -la $ARTIFACTS_DIR/review/\n\n# Read each review finding\nfor file in $ARTIFACTS_DIR/review/*.md; do\n  echo \"=== $file ===\"\n  cat \"$file\"\ndone\n```\n\n**Expected review artifacts** (in `runs/$WORKFLOW_ID/review/`):\n- `scope.md` - Files changed, scope limits, focus areas\n- `code-review-findings.md` - Code quality issues\n- `error-handling-findings.md` - Silent failures, catch blocks\n- `test-coverage-findings.md` - Test gaps\n- `comment-quality-findings.md` - Documentation issues\n- `docs-impact-findings.md` - Doc update needs\n- `consolidated-review.md` - Combined findings, priorities\n- `fix-report.md` - What was fixed\n- `sync-report.md` - Rebase/sync status (if applicable)\n\n### 1.3 Extract Key Data\n\n**From plan-context.md**:\n- Plan title and summary\n- Files expected to change\n- **NOT Building (Scope Limits)** - CRITICAL: these are follow-up candidates\n- Acceptance criteria\n\n**From implementation.md**:\n- Tasks completed vs planned\n- Files actually changed\n- **Deviations from plan** - document these prominently\n- Issues encountered during implementation\n\n**From all review findings**:\n- CRITICAL/HIGH issues (should be fixed)\n- **MEDIUM issues** - follow-up candidates\n- **LOW issues** - optional follow-ups\n- Specific recommendations by category\n\n**From fix-report.md**:\n- What was actually fixed\n- What was NOT fixed (and why)\n\n### 1.4 Cross-Reference\n\nCompare across artifacts:\n- Plan vs Implementation: What matched? What deviated?\n- Review findings vs Fix report: What's still open?\n- NOT Building vs Review findings: Did reviewers flag excluded items? (this is expected, note it)\n\n**PHASE_1_CHECKPOINT:**\n\n- [ ] ALL workflow artifacts read\n- [ ] ALL review artifacts read\n- [ ] Deviations extracted\n- [ ] Unfixed issues identified\n- [ ] NOT Building items noted\n\n---\n\n## Phase 2: ANALYZE - Build Follow-Up Matrix\n\n### 2.1 Categorize Follow-Up Items\n\n**From \"NOT Building\" section** - Future work explicitly deferred:\n\n| Item | Rationale | Suggested Follow-Up |\n|------|-----------|---------------------|\n| {excluded item} | {why excluded} | Create issue / Separate PR / Not needed |\n\n**From Implementation Deviations** - Changes that diverged from plan:\n\n| Deviation | Reason | Impact | Follow-Up Needed? |\n|-----------|--------|--------|-------------------|\n| {what changed} | {why} | {low/medium/high} | {yes/no + action} |\n\n**From Unfixed Review Findings** - MEDIUM/LOW severity items:\n\n| Finding | Severity | Category | Suggested Action |\n|---------|----------|----------|------------------|\n| {issue} | MEDIUM | docs | Update CLAUDE.md |\n| {issue} | LOW | test | Add edge case test |\n| {issue} | MEDIUM | error-handling | Log instead of silent |\n\n### 2.2 Prioritize by Effort vs Value\n\n**Quick Wins** (< 5 min, high value):\n- Documentation updates\n- Simple comment additions\n- Missing log statements\n\n**Worth Doing** (medium effort, clear value):\n- Test coverage gaps\n- Error message improvements\n- Type refinements\n\n**Can Defer** (higher effort or lower urgency):\n- Refactoring suggestions\n- Performance optimizations\n- Style improvements\n\n**PHASE_2_CHECKPOINT:**\n\n- [ ] NOT Building items categorized\n- [ ] Deviations assessed\n- [ ] Unfixed findings prioritized\n- [ ] Quick wins identified\n\n---\n\n## Phase 3: GENERATE - Create Decision Matrix\n\n### 3.1 Build Decision Matrix\n\nStructure the output for easy decision-making:\n\n```markdown\n## Follow-Up Decision Matrix\n\n### 🚀 Quick Wins (Can do now, < 5 min each)\n\n| # | Item | Action | Command |\n|---|------|--------|---------|\n| 1 | Update CLAUDE.md with new column | Docs update | `Run docs agent` |\n| 2 | Add missing JSDoc to deactivateSession | Comment | `Auto-fix` |\n\n**Your choice**:\n- [ ] Do all quick wins before merge\n- [ ] Create issues for later\n- [ ] Skip (not needed)\n\n---\n\n### 📋 Suggested GitHub Issues\n\n| # | Title | Labels | From |\n|---|-------|--------|------|\n| 1 | {issue title} | `enhancement`, `docs` | NOT Building |\n| 2 | {issue title} | `bug`, `low-priority` | Review finding |\n\n**Your choice**:\n- [ ] Create all issues\n- [ ] Create selected: {numbers}\n- [ ] Skip issue creation\n\n---\n\n### 📝 Documentation Gaps\n\n| File | Section | Update Needed |\n|------|---------|---------------|\n| CLAUDE.md | Database Schema | Add ended_reason column |\n| $DOCS_DIR/architecture.md | Sessions | Update deactivateSession signature |\n\n**Your choice**:\n- [ ] Send docs agent to fix all\n- [ ] Fix manually after merge\n- [ ] Skip (acceptable as-is)\n\n---\n\n### ⚠️ Deferred Items (from NOT Building)\n\n| Item | Why Deferred | When to Address |\n|------|--------------|-----------------|\n| {item} | {rationale} | {next sprint / never / if needed} |\n\n**These were intentionally excluded** - no action needed unless priorities change.\n```\n\n**PHASE_3_CHECKPOINT:**\n\n- [ ] Decision matrix structured\n- [ ] Quick wins identified\n- [ ] Issues drafted\n- [ ] Docs gaps listed\n\n---\n\n## Phase 4: POST - GitHub PR Comment\n\n### 4.1 Format for GitHub\n\nCreate a PR comment with the summary:\n\n```markdown\n## 🎯 Workflow Summary\n\n**Plan**: `{plan-path}`\n**Status**: ✅ Implementation complete, PR ready for review\n\n---\n\n### Implementation vs Plan\n\n| Metric | Planned | Actual |\n|--------|---------|--------|\n| Files created | {N} | {N} |\n| Files updated | {M} | {M} |\n| Tests added | {K} | {K} |\n| Deviations | - | {count} |\n\n{If deviations:}\n<details>\n<summary>📋 Deviations from Plan ({count})</summary>\n\n{List each deviation with reason}\n\n</details>\n\n---\n\n### Review Summary\n\n| Severity | Found | Fixed | Remaining |\n|----------|-------|-------|-----------|\n| CRITICAL | {N} | {N} | 0 |\n| HIGH | {N} | {N} | 0 |\n| MEDIUM | {N} | {fixed} | {remaining} |\n| LOW | {N} | {fixed} | {remaining} |\n\n---\n\n### 🚀 Quick Wins Before Merge\n\n{If any quick wins identified:}\n\n| Item | Effort | Action |\n|------|--------|--------|\n| {item} | ~2 min | {action} |\n\n**Reply with**: `@archon do quick wins` to auto-fix these.\n\n---\n\n### 📋 Suggested Follow-Up Issues\n\n{If issues suggested:}\n\n| Title | Labels |\n|-------|--------|\n| {title} | {labels} |\n\n**Reply with**: `@archon create follow-up issues` to create these.\n\n---\n\n### 📝 Documentation Updates\n\n{If doc gaps found:}\n\n| File | Update |\n|------|--------|\n| {file} | {what} |\n\n**Reply with**: `@archon update docs` to send a docs agent.\n\n---\n\n<details>\n<summary>ℹ️ Deferred Items (NOT Building)</summary>\n\nThese were **intentionally excluded** from scope:\n\n{List from NOT Building section}\n\n</details>\n\n---\n\n**Artifacts**: `$ARTIFACTS_DIR/`\n```\n\n### 4.2 Post to GitHub\n\n```bash\ngh pr comment {pr-number} --body \"{formatted-summary}\"\n```\n\n**PHASE_4_CHECKPOINT:**\n\n- [ ] Summary formatted for GitHub\n- [ ] Comment posted to PR\n\n---\n\n## Phase 5: ARTIFACT - Write Summary\n\n### 5.1 Write Summary Artifact\n\nWrite to `$ARTIFACTS_DIR/workflow-summary.md`:\n\n```markdown\n# Workflow Summary\n\n**Generated**: {YYYY-MM-DD HH:MM}\n**Workflow ID**: $WORKFLOW_ID\n**PR**: #{number}\n\n---\n\n## Execution Summary\n\n| Phase | Status | Notes |\n|-------|--------|-------|\n| Setup | ✅ | Branch ready |\n| Confirm | ✅ | Plan validated |\n| Implement | ✅ | {N} tasks completed |\n| Validate | ✅ | All checks pass |\n| PR | ✅ | #{number} created |\n| Review | ✅ | {N} agents ran |\n| Fixes | ✅ | {N} issues fixed |\n\n---\n\n## Implementation vs Plan\n\n{Detailed comparison}\n\n---\n\n## Deviations\n\n{List with rationale}\n\n---\n\n## Unfixed Review Findings\n\n### MEDIUM Severity\n\n{List}\n\n### LOW Severity\n\n{List}\n\n---\n\n## Follow-Up Recommendations\n\n### GitHub Issues to Create\n\n{List with draft titles/bodies}\n\n### Documentation Updates\n\n{List with specific changes}\n\n### Deferred to Future\n\n{List from NOT Building}\n\n---\n\n## Decision Matrix\n\n{Copy of the decision matrix}\n\n---\n\n## GitHub Comment\n\nPosted to: {PR URL}#comment-{id}\n```\n\n**PHASE_5_CHECKPOINT:**\n\n- [ ] Summary artifact written\n- [ ] All sections complete\n\n---\n\n## Phase 5.5: ARCHIVE - Create Backward-Compatible Symlink\n\n### 5.5.1 Create Symlink for PR-Based Lookup\n\nCreate symlink for backward compatibility with PR-based artifact lookup:\n\n```bash\nPR_NUMBER=$(cat $ARTIFACTS_DIR/.pr-number 2>/dev/null)\nif [ -n \"$PR_NUMBER\" ]; then\n  mkdir -p $ARTIFACTS_DIR/../reviews\n  ln -sfn ../runs/$WORKFLOW_ID/review $ARTIFACTS_DIR/../reviews/pr-$PR_NUMBER\nfi\n```\n\nThis allows legacy tools to find review artifacts at `$ARTIFACTS_DIR/../reviews/pr-{number}/`.\n\n**PHASE_5.5_CHECKPOINT:**\n\n- [ ] Symlink created (if PR number available)\n\n---\n\n## Phase 6: OUTPUT - Report to User\n\n```markdown\n## Workflow Complete 🎉\n\n**Workflow ID**: `$WORKFLOW_ID`\n**PR**: #{number} - {title}\n\n### Summary\n\n| Metric | Value |\n|--------|-------|\n| Tasks completed | {N}/{N} |\n| Review findings fixed | {N} |\n| Quick wins available | {N} |\n| Follow-up issues suggested | {N} |\n\n### Posted to GitHub\n\nSummary comment added to PR with:\n- Implementation vs plan comparison\n- Deviations documented\n- Decision matrix for follow-ups\n\n### Your Next Steps\n\n1. **Review the PR**: {url}\n2. **Quick wins**: Reply `@archon do quick wins` on PR (or skip)\n3. **Create issues**: Reply `@archon create follow-up issues` (or skip)\n4. **Merge when ready**\n\n### Artifacts\n\n- Summary: `$ARTIFACTS_DIR/workflow-summary.md`\n- All artifacts: `$ARTIFACTS_DIR/`\n```\n\n---\n\n## Success Criteria\n\n- **ARTIFACTS_LOADED**: All workflow artifacts read\n- **MATRIX_CREATED**: Follow-up items categorized and prioritized\n- **GITHUB_POSTED**: Summary comment on PR\n- **ARTIFACT_WRITTEN**: workflow-summary.md created\n- **ACTIONABLE**: User has clear next steps with minimal cognitive load\n",
+};
+
+// Bundled default workflows (20 total)
+export const BUNDLED_WORKFLOWS: Record<string, string> = {
+  "archon-adversarial-dev": "name: archon-adversarial-dev\ndescription: |\n  Use when: User wants to build a complete application from scratch using adversarial development.\n  Triggers: \"adversarial dev\", \"adversarial development\", \"build with adversarial\", \"gan dev\",\n            \"adversarial build\", \"build app adversarially\", \"adversarial coding\".\n  Does: Three-role GAN-inspired development — Planner creates spec with sprints, then a state-machine\n        loop alternates between Generator (builds code) and Evaluator (attacks it) with hard pass/fail\n        thresholds. The evaluator's job is to BREAK what the generator builds. If any criterion scores\n        below 7/10, the sprint goes back to the generator with adversarial feedback. Stops on sprint\n        failure after max retries.\n  NOT for: Bug fixes, PR reviews, refactoring existing code, simple one-off tasks.\n\n  Based on Anthropic's harness design article for long-running application development.\n  Separates planning, building, and evaluation into distinct roles with adversarial tension.\nprovider: claude\nmodel: sonnet\n\nnodes:\n  # ─── Phase 1: Planning ───────────────────────────────────────────────\n  - id: plan\n    prompt: |\n      You are a product planning expert. Your job is to take a short user prompt and expand it\n      into a comprehensive product specification.\n\n      ## User Request\n\n      $ARGUMENTS\n\n      ## Your Task\n\n      Write a comprehensive product specification to the file `$ARTIFACTS_DIR/spec.md` using the Write tool.\n\n      The spec MUST include ALL of the following sections:\n\n      ### 1. Product Overview\n      What the product does, who it's for, core value proposition.\n\n      ### 2. Tech Stack\n      Specific technologies, frameworks, and libraries. Be opinionated — pick concrete choices,\n      not \"a modern framework.\" Include exact package names and versions where relevant.\n\n      ### 3. Design Language\n      Visual style, specific color hex codes, typography choices, component patterns, spacing system.\n\n      ### 4. Feature List\n      Every feature organized by priority. Be exhaustive.\n\n      ### 5. Sprint Plan\n      Features broken into 3-6 sprints, ordered by dependency and importance:\n      - **Sprint 1** should establish the foundation (project setup, core data models, basic UI shell)\n      - Each subsequent sprint builds on the previous\n      - Label each sprint clearly: \"Sprint 1: Foundation\", \"Sprint 2: Core Features\", etc.\n      - List the specific features/deliverables for each sprint\n\n      Be specific and opinionated. The more concrete the spec (exact API paths, specific color codes,\n      named libraries), the better the generator can build and the evaluator can test.\n\n      IMPORTANT: Write the spec to `$ARTIFACTS_DIR/spec.md` using the Write tool. Do NOT just output\n      it as conversation text.\n    allowed_tools: [Read, Write, Glob, Grep]\n\n  # ─── Phase 2: Workspace Initialization ───────────────────────────────\n  - id: init-workspace\n    depends_on: [plan]\n    bash: |\n      ARTIFACTS=\"$ARTIFACTS_DIR\"\n\n      # Create directory structure for harness communication\n      mkdir -p \"$ARTIFACTS/contracts\"\n      mkdir -p \"$ARTIFACTS/feedback\"\n      mkdir -p \"$ARTIFACTS/app\"\n\n      # Initialize isolated git repo in app directory\n      cd \"$ARTIFACTS/app\"\n      git init -q\n      git commit --allow-empty -m \"Initial commit: adversarial-dev workspace\" -q\n\n      # Extract sprint count from spec (find highest \"Sprint N\" reference)\n      SPEC=\"$ARTIFACTS/spec.md\"\n      SPRINT_COUNT=3\n      if [ -f \"$SPEC\" ]; then\n        FOUND=$(grep -ioE 'sprint\\s+[0-9]+' \"$SPEC\" | grep -oE '[0-9]+' | sort -n | tail -1)\n        if [ -n \"$FOUND\" ] && [ \"$FOUND\" -ge 1 ] 2>/dev/null; then\n          SPRINT_COUNT=$FOUND\n        fi\n        if [ \"$SPRINT_COUNT\" -gt 10 ]; then\n          SPRINT_COUNT=10\n        fi\n      fi\n\n      # Write initial state machine file\n      cat > \"$ARTIFACTS/state.json\" << 'STATEEOF'\n      {\n        \"phase\": \"negotiating\",\n        \"sprint\": 1,\n        \"totalSprints\": SPRINT_COUNT_PLACEHOLDER,\n        \"retry\": 0,\n        \"maxRetries\": 3,\n        \"passThreshold\": 7,\n        \"completedSprints\": [],\n        \"status\": \"running\"\n      }\n      STATEEOF\n      STATE_TMP=\"$ARTIFACTS/state.json.tmp\"\n      sed \"s/SPRINT_COUNT_PLACEHOLDER/$SPRINT_COUNT/\" \"$ARTIFACTS/state.json\" > \"$STATE_TMP\"\n      mv \"$STATE_TMP\" \"$ARTIFACTS/state.json\"\n\n      echo \"{\\\"totalSprints\\\": $SPRINT_COUNT, \\\"appDir\\\": \\\"$ARTIFACTS/app\\\", \\\"artifactsDir\\\": \\\"$ARTIFACTS\\\"}\"\n    timeout: 30000\n\n  # ─── Phase 3: Adversarial Sprint Loop ────────────────────────────────\n  #\n  # State machine driven by $ARTIFACTS_DIR/state.json\n  # Each iteration plays ONE role: negotiator, generator, or evaluator\n  # fresh_context ensures genuine separation between roles\n  #\n  - id: adversarial-sprint\n    depends_on: [init-workspace]\n    idle_timeout: 600000\n    model: claude-opus-4-6[1m]\n    loop:\n      prompt: |\n        # Adversarial Development — Sprint Loop\n\n        You are part of a GAN-inspired adversarial development system with three distinct roles.\n        Each iteration you play ONE role, determined by the current phase in the state file.\n\n        ## FIRST: Read State\n\n        Read `$ARTIFACTS_DIR/state.json` to determine:\n        - `phase` — which role you play this iteration\n        - `sprint` — current sprint number\n        - `totalSprints` — how many sprints total\n        - `retry` — current retry attempt (0 = first try)\n        - `maxRetries` — max retries before hard failure (default 3)\n        - `passThreshold` — minimum score to pass (default 7)\n\n        Then read `$ARTIFACTS_DIR/spec.md` for product context.\n\n        ## Directory Layout\n\n        - App source code: `$ARTIFACTS_DIR/app/`\n        - Sprint contracts: `$ARTIFACTS_DIR/contracts/sprint-{N}.json`\n        - Evaluation feedback: `$ARTIFACTS_DIR/feedback/sprint-{N}-round-{R}.json`\n        - State machine: `$ARTIFACTS_DIR/state.json`\n\n        ---\n\n        ## ROLE: CONTRACT NEGOTIATOR (phase = \"negotiating\")\n\n        You negotiate the success criteria for the current sprint. Play BOTH sides sequentially:\n\n        **Step 1 — Generator's Proposal:**\n        Read the spec carefully. Identify what Sprint {N} should deliver based on the sprint plan.\n        Propose a sprint contract with 5-15 specific, testable criteria.\n\n        Each criterion MUST be concrete and verifiable. Examples:\n        - GOOD: \"GET /api/tasks returns 200 with JSON array; each item has id (number), title (string), status (string), createdAt (ISO date)\"\n        - GOOD: \"Clicking the Add Task button opens a modal with title input, priority dropdown (low/medium/high), and due date picker\"\n        - BAD: \"The API works well\"\n        - BAD: \"Tasks can be managed\"\n\n        **Step 2 — Evaluator's Tightening:**\n        Now review your proposal as an adversary. For EACH criterion ask:\n        - Is it specific enough to test programmatically?\n        - What edge cases are missing? (empty inputs, special characters, concurrent requests)\n        - Is the bar high enough, or would sloppy code pass?\n\n        Tighten vague criteria. Add edge cases. Raise the bar.\n\n        **Write the final contract** to `$ARTIFACTS_DIR/contracts/sprint-{N}.json`:\n        ```json\n        {\n          \"sprintNumber\": <N>,\n          \"features\": [\"feature1\", \"feature2\", ...],\n          \"criteria\": [\n            {\n              \"name\": \"short-kebab-name\",\n              \"description\": \"Specific, testable description of what must be true\",\n              \"threshold\": 7\n            }\n          ]\n        }\n        ```\n\n        **Update state.json**: Set `\"phase\": \"building\"`. Keep all other fields unchanged.\n\n        ---\n\n        ## ROLE: GENERATOR (phase = \"building\")\n\n        You are a software engineer. Build features that MUST survive an adversarial evaluator\n        who will actively try to break your code.\n\n        **Read these files:**\n        1. `$ARTIFACTS_DIR/spec.md` — full product spec (design language, tech stack, all features)\n        2. `$ARTIFACTS_DIR/contracts/sprint-{N}.json` — the contract you must satisfy\n        3. If `retry` > 0: read `$ARTIFACTS_DIR/feedback/sprint-{N}-round-{R-1}.json` for the\n           evaluator's previous feedback\n\n        **If this is a RETRY (retry > 0):**\n        Read the feedback CAREFULLY. Every failed criterion must be addressed.\n        - If scores were close (5-6) and trending up: REFINE your approach\n        - If scores were low (1-4) or the approach is fundamentally broken: PIVOT to a new strategy\n        - Address EVERY feedback item — the evaluator WILL check\n        - Re-verify each fix by running the code before committing\n\n        **Build rules:**\n        - All code goes in `$ARTIFACTS_DIR/app/`\n        - Build ONE feature at a time, verify it works, then commit:\n          ```bash\n          cd $ARTIFACTS_DIR/app && git add -A && git commit -m \"feat: description of what was built\"\n          ```\n        - Install dependencies as needed (npm/bun/pip/etc)\n        - Test your code — start the server, hit the endpoints, verify the UI renders\n        - Think about what the evaluator will attack: edge cases, error handling, input validation\n        - Build defensively — the evaluator's job is to break you\n\n        **Update state.json**: Set `\"phase\": \"evaluating\"`. Keep all other fields unchanged.\n\n        ---\n\n        ## ROLE: EVALUATOR (phase = \"evaluating\")\n\n        You are an ADVERSARIAL QA agent. Your mandate is to BREAK what the generator built.\n        You are not helpful. You are not generous. You are an attacker.\n\n        **CRITICAL CONSTRAINTS:**\n        - You are READ-ONLY for source code. NEVER use Write or Edit on files in `$ARTIFACTS_DIR/app/`.\n        - You MAY use Bash to run the app, curl endpoints, run test scripts, check behavior.\n        - You MUST kill any background processes (servers, watchers) you start BEFORE finishing.\n          Use: `pkill -f \"node\\|bun\\|python\\|npm\" 2>/dev/null || true`\n        - You MUST score EVERY criterion in the contract. No skipping.\n\n        **Scoring guidelines:**\n        - **9-10**: Exceptional. Works perfectly including edge cases the contract didn't mention.\n        - **7-8**: Solid. Meets the criterion as stated. Minor polish issues at most.\n        - **5-6**: Partial. Core functionality exists but fails important edge cases or has bugs.\n        - **3-4**: Weak. Barely functional. Major gaps.\n        - **1-2**: Broken. Does not work or is not implemented.\n\n        Do NOT grade on a curve. Do NOT give benefit of the doubt. A 7 means \"genuinely meets the bar.\"\n        If something is broken, say it's broken.\n\n        **Read**: `$ARTIFACTS_DIR/contracts/sprint-{N}.json` for the criteria.\n\n        **For each criterion:**\n        1. Read the relevant source code\n        2. Run the application (start server, test endpoints, check rendered UI)\n        3. Try to BREAK it — invalid inputs, missing fields, edge cases, error handling gaps\n        4. Score it honestly\n\n        **Write evaluation** to `$ARTIFACTS_DIR/feedback/sprint-{N}-round-{R}.json`:\n        ```json\n        {\n          \"passed\": <true if ALL scores >= passThreshold, false otherwise>,\n          \"scores\": {\n            \"criterion-name\": <score>,\n            ...\n          },\n          \"feedback\": [\n            {\n              \"criterion\": \"criterion-name\",\n              \"score\": <1-10>,\n              \"details\": \"Specific findings. Include file paths, line numbers, exact error messages, curl commands that failed.\"\n            }\n          ],\n          \"overallSummary\": \"What worked, what didn't, what the generator must fix.\"\n        }\n        ```\n\n        **Determine pass/fail** — `passed` is `true` ONLY if every single score >= `passThreshold`.\n\n        **Update state.json based on result:**\n\n        **If PASSED (all criteria >= threshold):**\n        - Add current sprint number to `completedSprints` array\n        - If `sprint` < `totalSprints`: set `\"phase\": \"negotiating\"`, increment `\"sprint\"` by 1, set `\"retry\": 0`\n        - If `sprint` == `totalSprints`: set `\"phase\": \"complete\"`, set `\"status\": \"complete\"`\n\n        **If FAILED:**\n        - If `retry` < `maxRetries`: set `\"phase\": \"building\"`, increment `\"retry\"` by 1\n        - If `retry` >= `maxRetries`: set `\"phase\": \"failed\"`, set `\"status\": \"failed\"`\n\n        **IMPORTANT**: Kill all background processes before finishing:\n        ```bash\n        pkill -f \"node|bun|python|npm|next|vite|webpack\" 2>/dev/null || true\n        ```\n\n        ---\n\n        ## COMPLETION\n\n        After updating state.json, check the `status` field:\n        - If `\"status\": \"complete\"` → all sprints passed! Output: `<promise>ALL_SPRINTS_COMPLETE</promise>`\n        - If `\"status\": \"failed\"` → sprint failed after max retries. Output: `<promise>ALL_SPRINTS_COMPLETE</promise>`\n        - If `\"status\": \"running\"` → more work to do. Do NOT output any completion signal.\n\n      until: ALL_SPRINTS_COMPLETE\n      max_iterations: 60\n      fresh_context: true\n      until_bash: |\n        grep -qE '\"status\"\\s*:\\s*\"(complete|failed)\"' \"$ARTIFACTS_DIR/state.json\"\n\n  # ─── Phase 4: Report ─────────────────────────────────────────────────\n  - id: report\n    depends_on: [adversarial-sprint]\n    trigger_rule: all_done\n    context: fresh\n    model: haiku\n    prompt: |\n      You are a project reporter. Generate a comprehensive summary of the adversarial development run.\n\n      ## Read ALL of these files:\n      1. `$ARTIFACTS_DIR/state.json` — final state (tells you success/failure, sprint count)\n      2. `$ARTIFACTS_DIR/spec.md` — the original product spec\n      3. All files in `$ARTIFACTS_DIR/contracts/` — sprint contracts (use Glob to find them)\n      4. All files in `$ARTIFACTS_DIR/feedback/` — evaluation results (use Glob to find them)\n\n      ## Generate a report covering:\n\n      ### Build Summary\n      - What application was built (from the spec)\n      - Final status: did all sprints pass or did it fail? On which sprint?\n      - Total sprints completed vs planned\n\n      ### Per-Sprint Breakdown\n      For each sprint that was attempted:\n      - What the contract required (features + key criteria)\n      - How many attempts were needed (retry count)\n      - Final scores for each criterion\n      - Key feedback that drove retries and improvements\n\n      ### Quality Metrics\n      - Average score across all final-round criteria\n      - Which criteria required the most retries\n      - Where the adversarial evaluator pushed quality the highest\n\n      ### How to Run\n      - The application code lives in: `$ARTIFACTS_DIR/app/`\n      - Include the tech stack and how to start the app (from the spec)\n      - Include any setup steps (install deps, env vars, etc.)\n\n      Write this report to `$ARTIFACTS_DIR/report.md` AND output it as your response so the user\n      sees it directly.\n    allowed_tools: [Read, Write, Glob, Grep]\n",
+  "archon-architect": "name: archon-architect\ndescription: |\n  Use when: User wants an architectural sweep, complexity reduction, or codebase health improvement.\n  Triggers: \"architect\", \"simplify codebase\", \"reduce complexity\", \"architectural sweep\",\n            \"clean up architecture\", \"codebase health\", \"fix architecture\".\n  Does: Scans codebase metrics -> analyzes architecture with principled lens -> plans targeted\n        simplifications -> executes fixes with self-review loops (hooks) -> validates -> creates PR.\n  NOT for: Single-file fixes, feature development, bug fixes, PR reviews.\n\n  DAG workflow showcasing per-node hooks:\n  - PostToolUse hooks create organic quality loops (lint after write, self-review)\n  - PreToolUse hooks inject architectural principles before changes\n  - Different nodes have different trust levels and steering\n\nprovider: claude\n\nnodes:\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 1: MEASURE\n  # Gather raw metrics — file sizes, complexity hotspots, dependency fan-out\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: scan-metrics\n    bash: |\n      echo \"=== FILE SIZE HOTSPOTS (top 30 largest source files) ===\"\n      find . -name '*.ts' -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' \\\n        -exec wc -l {} + 2>/dev/null | sort -rn | head -30\n\n      echo \"\"\n      echo \"=== IMPORT FAN-OUT (files with most imports) ===\"\n      for f in $(find . -name '*.ts' -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*'); do\n        count=$(grep -c \"^import \" \"$f\" 2>/dev/null) || count=0\n        if [ \"$count\" -gt 8 ]; then\n          echo \"$count imports: $f\"\n        fi\n      done | sort -rn | head -20\n\n      echo \"\"\n      echo \"=== EXPORT FAN-OUT (files with most exports) ===\"\n      for f in $(find . -name '*.ts' -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*'); do\n        count=$(grep -c \"^export \" \"$f\" 2>/dev/null) || count=0\n        if [ \"$count\" -gt 5 ]; then\n          echo \"$count exports: $f\"\n        fi\n      done | sort -rn | head -20\n\n      echo \"\"\n      echo \"=== FUNCTION LENGTH HOTSPOTS (functions over 50 lines) ===\"\n      grep -rn \"^\\(export \\)\\?\\(async \\)\\?function \\|=> {$\" \\\n        --include='*.ts' --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=dist . 2>/dev/null \\\n        | head -30\n\n      echo \"\"\n      echo \"=== TYPE SAFETY GAPS ===\"\n      echo \"any usage:\"\n      grep -rn \": any\\b\\|as any\\b\" --include='*.ts' --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=dist . 2>/dev/null | wc -l\n      echo \"eslint-disable comments:\"\n      grep -rn \"eslint-disable\" --include='*.ts' --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=dist . 2>/dev/null | wc -l\n    timeout: 60000\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 2: ANALYZE\n  # Read through hotspots with an architectural lens\n  # Hooks inject assessment criteria after every file read\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: analyze\n    prompt: |\n      You are a senior software architect performing a codebase health assessment.\n\n      ## Codebase Metrics\n\n      $scan-metrics.output\n\n      ## User Focus\n\n      $ARGUMENTS\n\n      ## Instructions\n\n      1. Read the top 10-15 files flagged by the metrics above (largest, most imports, most exports)\n      2. For each file, assess the criteria injected after you read it (you'll see them)\n      3. Build a running list of architectural concerns\n      4. Focus on:\n         - Modules doing too many things (SRP violations)\n         - Abstractions that don't earn their complexity\n         - Duplicated patterns that should be consolidated (Rule of Three)\n         - God files or god functions\n         - Leaky abstractions or tight coupling between layers\n         - Dead code or unused exports\n      5. Do NOT suggest changes yet — only diagnose\n\n      ## Output\n\n      Write a structured assessment to $ARTIFACTS_DIR/architecture-assessment.md with:\n      - Executive summary (3-5 sentences)\n      - Top findings ranked by impact\n      - For each finding: file, what's wrong, why it matters, estimated effort\n    depends_on: [scan-metrics]\n    context: fresh\n    denied_tools: [Write, Edit, Bash]\n    hooks:\n      PostToolUse:\n        - matcher: \"Read\"\n          response:\n            hookSpecificOutput:\n              hookEventName: PostToolUse\n              additionalContext: >\n                For the file you just read, assess:\n                (1) Single responsibility — does this module do exactly one thing?\n                (2) Cognitive load — could a new team member understand this in 5 minutes?\n                (3) Abstraction value — does every abstraction earn its complexity, or is it premature?\n                (4) Dependency direction — does this file depend on things at its own level or below, not above?\n                Add any concerns to your running list. Be specific — cite line ranges and function names.\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 3: PLAN\n  # Prioritize and scope the changes — pure reasoning, no tools\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: plan\n    prompt: |\n      You are planning targeted architectural improvements.\n\n      ## Assessment\n\n      $analyze.output\n\n      ## Principles\n\n      - KISS: prefer straightforward over clever\n      - YAGNI: remove speculative abstractions\n      - Rule of Three: only extract when a pattern appears 3+ times\n      - Each change must be independently revertable\n      - Do NOT mix refactoring with behavior changes\n      - Scope to what can be done safely in one pass (max 5-7 files)\n\n      ## Instructions\n\n      1. From the assessment, select the top 3-5 highest-impact, lowest-risk improvements\n      2. For each, write a precise plan: which file, what to change, why\n      3. Order them so each change is independent (no cascading dependencies between changes)\n      4. Estimate blast radius — how many other files are affected\n\n      ## Output\n\n      Write the plan as a numbered list. Be specific about exactly what code to change.\n      Keep it concise — the implement node will follow this literally.\n    depends_on: [analyze]\n    allowed_tools: [Read]\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 4: EXECUTE\n  # Make the changes with hooks creating quality feedback loops\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: simplify\n    prompt: |\n      You are implementing targeted architectural simplifications.\n\n      ## Plan\n\n      $plan.output\n\n      ## Rules\n\n      - Follow the plan exactly — do not add extra improvements you notice along the way\n      - Each change must preserve existing behavior (refactor only, no feature changes)\n      - After each file edit, you'll be prompted to validate — follow those instructions\n      - If a change turns out to be harder than expected, skip it and move on\n      - Commit each logical change separately with a clear commit message\n\n      ## Instructions\n\n      1. Work through the plan items in order\n      2. For each item: read the file, make the change, follow the post-edit checklist\n      3. After all changes, do a final `git diff --stat` to verify scope\n    depends_on: [plan]\n    context: fresh\n    hooks:\n      PreToolUse:\n        - matcher: \"Write|Edit\"\n          response:\n            hookSpecificOutput:\n              hookEventName: PreToolUse\n              additionalContext: >\n                Before writing: Is this file in your plan? If not, explain why you're\n                touching it. Check how many files import from this module — changes to\n                widely-imported modules need extra scrutiny.\n      PostToolUse:\n        - matcher: \"Write|Edit\"\n          response:\n            systemMessage: >\n              You just modified a file. Do these things NOW before moving on:\n              1. Run the type checker to verify your change compiles\n              2. Re-read the file you changed — is it ACTUALLY simpler, or did you just move complexity around?\n              3. State in ONE sentence why this change reduces complexity. If you cannot justify it, revert it.\n        - matcher: \"Read\"\n          response:\n            hookSpecificOutput:\n              hookEventName: PostToolUse\n              additionalContext: >\n                Before modifying this file, consider: will your change reduce or increase\n                the number of concepts a reader needs to hold in their head?\n        - matcher: \"Bash\"\n          response:\n            hookSpecificOutput:\n              hookEventName: PostToolUse\n              additionalContext: >\n                Check the exit code. If the command failed, diagnose the root cause\n                before attempting a fix. Do not blindly retry.\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 5: VALIDATE\n  # Run full validation suite — bash only, cannot edit to \"fix\" failures\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: validate\n    bash: |\n      echo \"=== TYPE CHECK ===\"\n      bun run type-check 2>&1\n      TC_EXIT=$?\n\n      echo \"\"\n      echo \"=== LINT ===\"\n      bun run lint 2>&1\n      LINT_EXIT=$?\n\n      echo \"\"\n      echo \"=== TESTS ===\"\n      bun run test 2>&1\n      TEST_EXIT=$?\n\n      echo \"\"\n      echo \"=== RESULTS ===\"\n      echo \"Type check: $([ $TC_EXIT -eq 0 ] && echo 'PASS' || echo 'FAIL')\"\n      echo \"Lint: $([ $LINT_EXIT -eq 0 ] && echo 'PASS' || echo 'FAIL')\"\n      echo \"Tests: $([ $TEST_EXIT -eq 0 ] && echo 'PASS' || echo 'FAIL')\"\n\n      # Always exit 0 so downstream nodes can read output and decide\n      if [ $TC_EXIT -eq 0 ] && [ $LINT_EXIT -eq 0 ] && [ $TEST_EXIT -eq 0 ]; then\n        echo \"VALIDATION_STATUS: PASS\"\n      else\n        echo \"VALIDATION_STATUS: FAIL\"\n      fi\n    depends_on: [simplify]\n    timeout: 300000\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 6: FIX VALIDATION FAILURES (if any)\n  # Only runs if validate failed — focused fix with same quality hooks\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: fix-failures\n    prompt: |\n      Review the validation output below.\n\n      ## Validation Output\n\n      $validate.output\n\n      ## Instructions\n\n      If the output ends with \"VALIDATION_STATUS: PASS\", respond with\n      \"All checks passed — no fixes needed.\" and stop.\n\n      If there are failures:\n\n      1. Read the validation failures carefully\n      2. Fix ONLY what's broken — do not make additional improvements\n      3. If a fix requires changing behavior (not just fixing a type/lint error),\n         revert the original change instead\n      4. Run the specific failing check after each fix to confirm it passes\n      5. After all fixes, run the full validation suite: `bun run validate`\n    depends_on: [validate]\n    context: fresh\n    hooks:\n      PostToolUse:\n        - matcher: \"Write|Edit\"\n          response:\n            systemMessage: >\n              You just made a fix. Run the specific failing validation check NOW\n              to verify your fix works. Do not batch fixes — verify each one.\n      PreToolUse:\n        - matcher: \"Write|Edit\"\n          response:\n            hookSpecificOutput:\n              hookEventName: PreToolUse\n              additionalContext: >\n                You are fixing validation failures only. Do not make any changes\n                beyond what's needed to pass the failing checks. If in doubt, revert\n                the original change that caused the failure.\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 7: CREATE PR\n  # Hooks ensure this node only does git operations\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: create-pr\n    prompt: |\n      Create a pull request for the architectural improvements.\n\n      ## Context\n\n      - Architecture assessment: $analyze.output\n      - Plan: $plan.output\n      - Validation: $validate.output\n\n      ## Instructions\n\n      1. Stage all changes and create a single commit (or verify existing commits)\n      2. Push the branch: `git push -u origin HEAD`\n      3. Check if a PR already exists: `gh pr list --head $(git branch --show-current)`\n      4. Create the PR with:\n         - Title: concise description of what was simplified (under 70 chars)\n         - Body: use the format below\n      5. Save the PR URL to `$ARTIFACTS_DIR/.pr-url`\n\n      ## PR Body Format\n\n      ```markdown\n      ## Architectural Sweep\n\n      **Focus**: $ARGUMENTS\n\n      ### Assessment\n\n      [3-5 sentence summary from the architecture assessment]\n\n      ### Changes\n\n      [For each change: what file, what was simplified, why]\n\n      ### Validation\n\n      - [x] Type check passes\n      - [x] Lint passes\n      - [x] Tests pass\n      - [x] Each change preserves existing behavior\n      ```\n    depends_on: [fix-failures]\n    context: fresh\n    hooks:\n      PreToolUse:\n        - matcher: \"Write|Edit\"\n          response:\n            hookSpecificOutput:\n              hookEventName: PreToolUse\n              permissionDecision: deny\n              permissionDecisionReason: \"PR creation node — do not modify source files. Use only git and gh commands.\"\n      PostToolUse:\n        - matcher: \"Bash\"\n          response:\n            hookSpecificOutput:\n              hookEventName: PostToolUse\n              additionalContext: >\n                Verify this command succeeded. If git push or gh pr create failed,\n                read the error message carefully before retrying.\n",
+  "archon-assist": "name: archon-assist\ndescription: |\n  Use when: No other workflow matches the request.\n  Handles: Questions, debugging, exploration, one-off tasks, explanations, CI failures, general help.\n  Capability: Full Claude Code agent with all tools available.\n  Note: Will inform user when assist mode is used for tracking.\n\nnodes:\n  - id: assist\n    command: archon-assist\n",
+  "archon-comprehensive-pr-review": "name: archon-comprehensive-pr-review\ndescription: |\n  Use when: User wants a comprehensive code review of a pull request with automatic fixes.\n  Triggers: \"review this PR\", \"review PR #123\", \"comprehensive review\", \"full PR review\",\n            \"review and fix\", \"check this PR\", \"code review\".\n  Does: Syncs PR with main (rebase if needed) -> runs 5 specialized review agents in parallel ->\n        synthesizes findings -> auto-fixes CRITICAL/HIGH issues -> reports remaining issues.\n  NOT for: Quick questions about a PR, checking CI status, simple \"what changed\" queries.\n\n  This workflow produces artifacts in $ARTIFACTS_DIR/../reviews/pr-{number}/ and posts\n  a comprehensive review comment to the GitHub PR.\n\nnodes:\n  - id: scope\n    command: archon-pr-review-scope\n\n  - id: sync\n    command: archon-sync-pr-with-main\n    depends_on: [scope]\n\n  - id: code-review\n    command: archon-code-review-agent\n    depends_on: [sync]\n\n  - id: error-handling\n    command: archon-error-handling-agent\n    depends_on: [sync]\n\n  - id: test-coverage\n    command: archon-test-coverage-agent\n    depends_on: [sync]\n\n  - id: comment-quality\n    command: archon-comment-quality-agent\n    depends_on: [sync]\n\n  - id: docs-impact\n    command: archon-docs-impact-agent\n    depends_on: [sync]\n\n  - id: synthesize\n    command: archon-synthesize-review\n    depends_on: [code-review, error-handling, test-coverage, comment-quality, docs-impact]\n    trigger_rule: one_success\n\n  - id: implement-fixes\n    command: archon-implement-review-fixes\n    depends_on: [synthesize]\n",
+  "archon-create-issue": "name: archon-create-issue\ndescription: |\n  Use when: User wants to report a bug or problem as a GitHub issue with automated reproduction.\n  Triggers: \"create issue\", \"file a bug\", \"report this bug\", \"open an issue for\",\n            \"create github issue\", \"report issue\", \"log this bug\".\n  Does: Classifies problem area (haiku) -> gathers context in parallel (templates, git state, duplicates) ->\n        investigates relevant code -> reproduces the issue using area-specific tools (agent-browser, CLI, DB queries) ->\n        gates on reproduction success -> creates issue with full evidence OR reports back if cannot reproduce.\n  NOT for: Feature requests, enhancements, or non-bug work. Only for bugs/problems.\n\n  Reproduction gating: If the issue cannot be reproduced, the workflow does NOT create an issue.\n  Instead, it reports what was tried and suggests next steps to the user.\n\nnodes:\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 1: CLASSIFY — Haiku classification of user's problem\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: classify\n    prompt: |\n      You are a problem classifier for the Archon codebase. Analyze the user's\n      description and determine the issue type and which area of the system is affected.\n\n      ## User's Description\n      $ARGUMENTS\n\n      ## Area Definitions\n      | Area | Packages | Indicators |\n      |------|----------|------------|\n      | web-ui | @archon/web, @archon/server (routes, web adapter) | UI rendering, SSE streaming, React components, browser behavior |\n      | api-server | @archon/server (routes, middleware) | HTTP endpoints, response codes, request handling |\n      | cli | @archon/cli | CLI commands, workflow invocation from terminal, output formatting |\n      | isolation | @archon/isolation, @archon/git | Worktrees, branch operations, cleanup, environment lifecycle |\n      | workflows | @archon/workflows | YAML parsing, DAG execution, variable substitution, node types |\n      | database | @archon/core (db/) | SQLite/PostgreSQL queries, schema, data integrity, migrations |\n      | adapters | @archon/adapters | Slack/Telegram/GitHub/Discord message handling, auth, polling |\n      | core | @archon/core (orchestrator, handlers, clients) | Message routing, session management, AI client streaming |\n      | other | Any package not covered above | Cross-cutting concerns, build tooling, config, unknown area |\n\n      ## Classification Rules\n      - Choose the MOST SPECIFIC area. \"SSE disconnects\" = web-ui (not api-server).\n      - If ambiguous between two areas, pick the one closer to the user-facing symptom.\n      - Use \"other\" only when the problem genuinely doesn't fit any specific area.\n      - needs_server: Set to \"true\" if reproducing requires a running Archon server.\n        Typically true for: web-ui, api-server, core, adapters.\n        Typically false for: cli, isolation, workflows, database.\n        For \"other\": use your judgment based on the description.\n      - repro_hint: Extract the user's reproduction steps into a concise instruction.\n        If no explicit steps given, infer the most likely way to trigger the issue.\n\n      Provide reasoning for your classification.\n    model: haiku\n    allowed_tools: []\n    output_format:\n      type: object\n      properties:\n        type:\n          type: string\n          enum: [\"bug\", \"regression\", \"crash\", \"performance\", \"configuration\"]\n        area:\n          type: string\n          enum: [\"web-ui\", \"api-server\", \"cli\", \"isolation\", \"workflows\", \"database\", \"adapters\", \"core\", \"other\"]\n        title:\n          type: string\n        keywords:\n          type: string\n        repro_hint:\n          type: string\n        needs_server:\n          type: string\n          enum: [\"true\", \"false\"]\n      required: [type, area, title, keywords, repro_hint, needs_server]\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 2: PARALLEL CONTEXT GATHERING\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: fetch-template\n    bash: |\n      # Search for GitHub issue templates in standard locations\n      TEMPLATES_FOUND=0\n\n      # Check for issue template directory (YAML-based templates)\n      if [ -d \".github/ISSUE_TEMPLATE\" ]; then\n        echo \"=== Issue Templates Found ===\"\n        for f in .github/ISSUE_TEMPLATE/*.md .github/ISSUE_TEMPLATE/*.yaml .github/ISSUE_TEMPLATE/*.yml; do\n          if [ -f \"$f\" ]; then\n            TEMPLATES_FOUND=$((TEMPLATES_FOUND + 1))\n            echo \"--- Template: $f ---\"\n            cat \"$f\"\n            echo \"\"\n          fi\n        done\n      fi\n\n      # Check for single issue template\n      for f in .github/ISSUE_TEMPLATE.md docs/ISSUE_TEMPLATE.md; do\n        if [ -f \"$f\" ]; then\n          TEMPLATES_FOUND=$((TEMPLATES_FOUND + 1))\n          echo \"--- Template: $f ---\"\n          cat \"$f\"\n        fi\n      done\n\n      if [ \"$TEMPLATES_FOUND\" -eq 0 ]; then\n        echo \"No issue templates found — will use standard format\"\n      fi\n    depends_on: [classify]\n\n  - id: git-context\n    bash: |\n      echo \"=== Branch ===\"\n      git branch --show-current\n\n      echo \"=== Recent Commits (last 15) ===\"\n      git log --oneline -15\n\n      echo \"=== Working Tree Status ===\"\n      git status --short\n\n      echo \"=== Modified Files (last 3 commits) ===\"\n      git diff --name-only HEAD~3..HEAD 2>/dev/null || echo \"(fewer than 3 commits)\"\n\n      echo \"=== Environment ===\"\n      echo \"Node: $(node --version 2>/dev/null || echo 'N/A')\"\n      echo \"Bun: $(bun --version 2>/dev/null || echo 'N/A')\"\n      echo \"OS: $(uname -s 2>/dev/null || echo 'Windows') $(uname -r 2>/dev/null || ver 2>/dev/null || echo '')\"\n      echo \"Platform: $(uname -m 2>/dev/null || echo 'unknown')\"\n    depends_on: [classify]\n\n  - id: dedup-check\n    bash: |\n      KEYWORDS=$classify.output.keywords\n      echo \"=== Searching for duplicates: $KEYWORDS ===\"\n\n      echo \"--- Open Issues ---\"\n      gh issue list --search \"$KEYWORDS\" --state open --limit 5 --json number,title,url,labels 2>/dev/null || echo \"No open matches\"\n\n      echo \"--- Recently Closed ---\"\n      gh issue list --search \"$KEYWORDS\" --state closed --limit 3 --json number,title,url,labels 2>/dev/null || echo \"No closed matches\"\n    depends_on: [classify]\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 3: INVESTIGATE — Search codebase for related code\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: investigate\n    prompt: |\n      You are a codebase investigator. Search for code related to the reported problem.\n\n      ## Problem\n      - **Area**: $classify.output.area\n      - **Type**: $classify.output.type\n      - **Title**: $classify.output.title\n      - **Reproduction hint**: $classify.output.repro_hint\n\n      ## Git Context\n      $git-context.output\n\n      ## Instructions\n\n      1. Based on the area, search the relevant packages:\n         - web-ui: `packages/web/src/`, `packages/server/src/adapters/web/`, `packages/server/src/routes/`\n         - api-server: `packages/server/src/routes/`, `packages/server/src/`\n         - cli: `packages/cli/src/`\n         - isolation: `packages/isolation/src/`, `packages/git/src/`\n         - workflows: `packages/workflows/src/`\n         - database: `packages/core/src/db/`\n         - adapters: `packages/adapters/src/`\n         - core: `packages/core/src/orchestrator/`, `packages/core/src/handlers/`\n         - other: search broadly based on keywords — check `packages/*/src/`, config files, build scripts\n\n      2. Find: entry points, error handling paths, related type definitions, recent changes\n         to the affected area (check git log for the specific files).\n\n      3. Write your findings to `$ARTIFACTS_DIR/issue-context.md` with this structure:\n         ```\n         # Codebase Investigation\n         ## Relevant Files\n         - `file:line` — description of what's there\n         ## Error Handling\n         - How errors are currently handled in this area\n         ## Recent Changes\n         - Any recent commits touching this code\n         ## Suspected Root Cause\n         - Based on code analysis, where the bug likely is\n         ```\n\n      Be thorough but focused. Only include files directly relevant to the reported problem.\n    depends_on: [classify, git-context]\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 4: REPRODUCE — Area-specific issue reproduction\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: start-server\n    bash: |\n      # Allocate a free port using Bun's OS assignment\n      PORT=$(bun -e \"const s = Bun.serve({port: 0, fetch: () => new Response('')}); console.log(s.port); s.stop()\")\n      echo \"$PORT\" > \"$ARTIFACTS_DIR/.server-port\"\n\n      # Start dev server in background\n      PORT=$PORT bun run dev:server > \"$ARTIFACTS_DIR/.server-log\" 2>&1 &\n      SERVER_PID=$!\n      echo \"$SERVER_PID\" > \"$ARTIFACTS_DIR/.server-pid\"\n\n      # Wait for server to be ready (up to 30s)\n      for i in $(seq 1 30); do\n        if curl -s \"http://localhost:$PORT/api/health\" > /dev/null 2>&1; then\n          echo \"Server ready on port $PORT (PID: $SERVER_PID)\"\n          exit 0\n        fi\n        sleep 1\n      done\n\n      echo \"WARNING: Server may not be fully ready after 30s (port $PORT, PID $SERVER_PID)\"\n      echo \"Continuing anyway — reproduce node will handle connection errors\"\n    depends_on: [classify]\n    when: \"$classify.output.needs_server == 'true'\"\n    timeout: 45000\n\n  - id: reproduce\n    prompt: |\n      You are an issue reproduction specialist. Your job is to reproduce the reported\n      problem and capture evidence (screenshots, command output, error messages).\n\n      ## Problem Context\n      - **Area**: $classify.output.area\n      - **Type**: $classify.output.type\n      - **Title**: $classify.output.title\n      - **Reproduction hint**: $classify.output.repro_hint\n\n      ## Investigation Findings\n      $investigate.output\n\n      ## Server Info\n      If a server was started, read the port from: `cat \"$ARTIFACTS_DIR/.server-port\"`\n      If the file doesn't exist, no server is running (area doesn't need one).\n\n      ---\n\n      ## Reproduction Playbooks\n\n      Follow the playbook matching the area. Capture ALL evidence to `$ARTIFACTS_DIR/`.\n\n      ### web-ui\n      1. Read the server port: `PORT=$(cat \"$ARTIFACTS_DIR/.server-port\" | tr -d '\\n')`\n      2. Open the app: `agent-browser open http://localhost:$PORT`\n      3. Take a baseline screenshot: `agent-browser screenshot \"$ARTIFACTS_DIR/repro-01-baseline.png\"`\n      4. Get interactive elements: `agent-browser snapshot -i`\n      5. Navigate to the area related to the issue (use @refs from snapshot)\n      6. Perform the actions described in the repro_hint\n      7. Screenshot each significant state: `agent-browser screenshot \"$ARTIFACTS_DIR/repro-02-action.png\"`\n      8. If an error appears, capture it: `agent-browser get text @errorElement`\n      9. Check browser console: `agent-browser console`\n      10. Check for JS errors: `agent-browser errors`\n      11. Final screenshot: `agent-browser screenshot \"$ARTIFACTS_DIR/repro-03-result.png\"`\n      12. Close browser: `agent-browser close`\n\n      ### api-server\n      1. Read the server port: `PORT=$(cat \"$ARTIFACTS_DIR/.server-port\" | tr -d '\\n')`\n      2. Create a test conversation: `curl -s -X POST http://localhost:$PORT/api/conversations -H \"Content-Type: application/json\" -d '{}'`\n      3. Hit the problematic endpoint based on the repro_hint\n      4. Capture response codes and bodies: `curl -s -w \"\\nHTTP_CODE: %{http_code}\\n\" ...`\n      5. For SSE issues: `curl -s -N http://localhost:$PORT/api/stream/<id>` (timeout after 10s)\n      6. Check server logs: `cat \"$ARTIFACTS_DIR/.server-log\" | tail -50`\n      7. Save all curl output to `$ARTIFACTS_DIR/repro-api-responses.txt`\n\n      ### cli\n      1. Run the CLI command that should trigger the issue\n      2. Capture stdout and stderr separately:\n         `bun run cli <command> > \"$ARTIFACTS_DIR/repro-cli-stdout.txt\" 2> \"$ARTIFACTS_DIR/repro-cli-stderr.txt\"; echo \"EXIT_CODE: $?\" >> \"$ARTIFACTS_DIR/repro-cli-stdout.txt\"`\n      3. If workflow-related: `bun run cli workflow list --json > \"$ARTIFACTS_DIR/repro-workflow-list.json\" 2>&1`\n      4. If the command hangs, use timeout: `timeout 30 bun run cli <command>`\n      5. Check for error messages in output\n\n      ### isolation\n      1. Check current state: `bun run cli isolation list > \"$ARTIFACTS_DIR/repro-isolation-list.txt\" 2>&1`\n      2. Check git worktrees: `git worktree list > \"$ARTIFACTS_DIR/repro-worktree-list.txt\"`\n      3. Check branches: `git branch -a > \"$ARTIFACTS_DIR/repro-branches.txt\"`\n      4. Try the operation that should fail (based on repro_hint)\n      5. Capture the error output\n      6. Query isolation DB: `sqlite3 ~/.archon/archon.db \"SELECT * FROM remote_agent_isolation_environments ORDER BY created_at DESC LIMIT 10\" > \"$ARTIFACTS_DIR/repro-isolation-db.txt\" 2>&1`\n\n      ### workflows\n      1. List workflows: `bun run cli workflow list --json > \"$ARTIFACTS_DIR/repro-workflow-list.json\" 2>&1`\n      2. If a specific workflow is mentioned, try running it:\n         `bun run cli workflow run <name> --no-worktree \"test input\" > \"$ARTIFACTS_DIR/repro-workflow-run.txt\" 2>&1`\n      3. If YAML parsing is the issue, try loading the definition directly\n      4. Check for error messages in execution output\n\n      ### database\n      1. Check DB exists: `ls -la ~/.archon/archon.db 2>/dev/null`\n      2. Run targeted queries against affected tables:\n         - `sqlite3 ~/.archon/archon.db \".schema <table>\" > \"$ARTIFACTS_DIR/repro-db-schema.txt\"`\n         - `sqlite3 ~/.archon/archon.db \"SELECT COUNT(*) FROM <table>\" > \"$ARTIFACTS_DIR/repro-db-counts.txt\"`\n      3. Check for the specific data condition described in the repro_hint\n      4. If PostgreSQL: use `psql $DATABASE_URL -c \"...\"` instead\n\n      ### adapters\n      1. Read the server port: `PORT=$(cat \"$ARTIFACTS_DIR/.server-port\" | tr -d '\\n')`\n      2. Check adapter configuration: look for relevant env vars in `.env`\n      3. Check server startup logs: `cat \"$ARTIFACTS_DIR/.server-log\" | grep -i \"adapter\\|slack\\|telegram\\|github\\|discord\" | head -20`\n      4. If the adapter fails to initialize, capture the error\n      5. Test message routing via web API as a proxy:\n         `curl -s -X POST http://localhost:$PORT/api/conversations/<id>/message -H \"Content-Type: application/json\" -d '{\"message\":\"/status\"}'`\n\n      ### core\n      1. Read the server port: `PORT=$(cat \"$ARTIFACTS_DIR/.server-port\" | tr -d '\\n')`\n      2. Create a conversation: `curl -s -X POST http://localhost:$PORT/api/conversations -H \"Content-Type: application/json\" -d '{}'`\n      3. Send a message that triggers the issue:\n         `curl -s -X POST http://localhost:$PORT/api/conversations/<id>/message -H \"Content-Type: application/json\" -d '{\"message\":\"<repro_hint>\"}'`\n      4. Poll for responses: `curl -s http://localhost:$PORT/api/conversations/<id>/messages`\n      5. Check session state in DB: `sqlite3 ~/.archon/archon.db \"SELECT * FROM remote_agent_sessions WHERE conversation_id='<id>'\" 2>/dev/null`\n      6. Check server logs: `cat \"$ARTIFACTS_DIR/.server-log\" | tail -50`\n\n      ### other\n      1. Run `bun run validate` to check for any obvious failures — capture output:\n         `bun run validate > \"$ARTIFACTS_DIR/repro-validate.txt\" 2>&1; echo \"EXIT_CODE: $?\" >> \"$ARTIFACTS_DIR/repro-validate.txt\"`\n      2. Search the codebase for keywords from the repro_hint:\n         - Use Grep/Glob to find related files\n         - Check recent git log for relevant changes\n      3. If the description implies a build or config issue:\n         - Check `package.json` scripts, `tsconfig.json`, `.env.example`\n         - Try running the relevant build/dev command\n      4. If the description implies a runtime issue:\n         - Start the server (if `.server-port` file exists) and try to trigger the behavior\n         - Check logs for errors\n      5. Document everything you tried, even if nothing reproduces clearly\n\n      ---\n\n      ## Output\n\n      After following the playbook, write your findings to `$ARTIFACTS_DIR/reproduction-results.md`:\n\n      ```markdown\n      # Reproduction Results\n\n      ## Status: [REPRODUCED | NOT_REPRODUCED | PARTIAL]\n\n      ## Steps Taken\n      1. [step]\n      2. [step]\n\n      ## Expected Behavior\n      [what should happen]\n\n      ## Actual Behavior\n      [what actually happened — or \"could not trigger the reported behavior\"]\n\n      ## Evidence Files\n      - `$ARTIFACTS_DIR/repro-*.png` — screenshots (if web-ui)\n      - `$ARTIFACTS_DIR/repro-*.txt` — command output\n      - `$ARTIFACTS_DIR/repro-*.json` — structured data\n\n      ## Environment\n      [OS, versions, relevant config]\n\n      ## Notes\n      [any additional observations, suspected root cause refinements]\n      ```\n\n      CRITICAL: The Status line MUST be exactly one of: REPRODUCED, NOT_REPRODUCED, PARTIAL.\n      This value is read by a downstream bash node to decide whether to create the issue.\n\n      Even if you cannot fully reproduce the issue, document what you tried\n      and what you observed. Partial reproduction is still valuable evidence.\n    depends_on: [classify, git-context, investigate, start-server]\n    context: fresh\n    skills:\n      - agent-browser\n    trigger_rule: one_success\n    idle_timeout: 300000\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 5: CLEANUP + GATE\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: cleanup-server\n    bash: |\n      SERVER_PID=$(cat \"$ARTIFACTS_DIR/.server-pid\" 2>/dev/null | tr -d '\\n')\n      SERVER_PORT=$(cat \"$ARTIFACTS_DIR/.server-port\" 2>/dev/null | tr -d '\\n')\n\n      if [ -z \"$SERVER_PID\" ]; then\n        echo \"No server was started — skipping cleanup\"\n        exit 0\n      fi\n\n      echo \"Cleaning up server PID $SERVER_PID on port $SERVER_PORT...\"\n\n      # Kill by PID (cross-platform)\n      kill \"$SERVER_PID\" 2>/dev/null || taskkill //F //T //PID \"$SERVER_PID\" 2>/dev/null || true\n\n      # Kill by port (fallback)\n      if [ -n \"$SERVER_PORT\" ]; then\n        fuser -k \"$SERVER_PORT/tcp\" 2>/dev/null || true\n        lsof -ti:\"$SERVER_PORT\" 2>/dev/null | xargs kill -9 2>/dev/null || true\n        netstat -ano 2>/dev/null | grep \":$SERVER_PORT \" | grep LISTENING | awk '{print $5}' | sort -u | while read pid; do\n          taskkill //F //T //PID \"$pid\" 2>/dev/null || true\n        done\n      fi\n\n      # Close any agent-browser session\n      agent-browser close 2>/dev/null || true\n\n      sleep 1\n      echo \"Cleanup complete\"\n    depends_on: [reproduce]\n    trigger_rule: all_done\n\n  - id: check-reproduction\n    bash: |\n      # Read the reproduction status from the results file\n      if [ ! -f \"$ARTIFACTS_DIR/reproduction-results.md\" ]; then\n        echo \"NOT_REPRODUCED\"\n        exit 0\n      fi\n\n      STATUS=$(grep -oE '(NOT_REPRODUCED|REPRODUCED|PARTIAL)' \"$ARTIFACTS_DIR/reproduction-results.md\" | head -1)\n\n      if [ -z \"$STATUS\" ]; then\n        echo \"NOT_REPRODUCED\"\n      else\n        echo \"$STATUS\"\n      fi\n    depends_on: [cleanup-server]\n    trigger_rule: all_done\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 6: BRANCH ON REPRODUCTION RESULT\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: report-failure\n    prompt: |\n      The issue could not be reproduced. Report this to the user with actionable detail.\n\n      ## Problem Description\n      - **Title**: $classify.output.title\n      - **Area**: $classify.output.area\n      - **Type**: $classify.output.type\n      - **Reproduction hint**: $classify.output.repro_hint\n\n      ## What Was Tried\n      $reproduce.output\n\n      ## Investigation Findings\n      $investigate.output\n\n      ## Instructions\n\n      Report to the user clearly:\n\n      1. **State upfront**: \"Could not reproduce the reported issue. No GitHub issue was created.\"\n\n      2. **Summarize what was tried**: List the specific steps the reproduce node took,\n         based on the area playbook. Be concrete — \"Started server on port X, navigated to Y,\n         clicked Z — no error appeared.\"\n\n      3. **Share what was found**: Include relevant findings from the investigation\n         (code references, recent changes, suspected areas).\n\n      4. **Suggest next steps**:\n         - Ask the user to provide more specific reproduction steps\n         - Mention any environment-specific factors that might matter\n           (OS, browser, database state, specific data conditions)\n         - If the investigation found suspicious code, mention it as a lead\n         - Suggest running with debug logging: `LOG_LEVEL=debug bun run dev`\n\n      5. **Offer to retry**: \"If you can provide more specific steps, run the workflow\n         again with those details.\"\n\n      Do NOT create a GitHub issue. The purpose of this node is to communicate back to the\n      user so they can provide better information or investigate manually.\n    depends_on: [check-reproduction]\n    when: \"$check-reproduction.output == 'NOT_REPRODUCED'\"\n    context: fresh\n\n  - id: draft-issue\n    prompt: |\n      You are a technical writer drafting a GitHub issue. Assemble all gathered\n      context into a clear, well-structured issue body.\n\n      ## Classification\n      - **Type**: $classify.output.type\n      - **Area**: $classify.output.area\n      - **Title**: $classify.output.title\n\n      ## Issue Template\n      If templates were found, use the most appropriate one as the structure:\n      $fetch-template.output\n\n      ## Duplicate Check Results\n      $dedup-check.output\n\n      ## Codebase Investigation\n      $investigate.output\n\n      ## Reproduction Results\n      $reproduce.output\n\n      ## Instructions\n\n      1. **Check duplicates first**: If the dedup-check found a clearly matching open issue,\n         note this prominently at the top. Still draft the issue but add a note suggesting\n         it may be a duplicate of #XYZ.\n\n      2. **Use the template** if one was found for bug reports. Fill every section with real data.\n\n      3. **Structure** (if no template):\n         ```markdown\n         ## Description\n         [Clear 1-2 sentence description]\n\n         ## Steps to Reproduce\n         [Numbered steps from reproduction results]\n\n         ## Expected Behavior\n         [What should happen]\n\n         ## Actual Behavior\n         [What actually happened, with evidence]\n\n         ## Environment\n         - OS: [from git-context]\n         - Bun: [version]\n         - Node: [version]\n         - Branch: [current branch]\n\n         ## Relevant Code\n         [Key file:line references from investigation]\n\n         ## Additional Context\n         [Screenshots, logs, database state — reference artifact files]\n         ```\n\n      4. **Include reproduction evidence**:\n         - If REPRODUCED: include full steps and all evidence\n         - If PARTIAL: include what was observed, note incomplete reproduction\n\n      5. **Suggest labels** based on classification:\n         - Area label: `area: web`, `area: cli`, `area: workflows`, etc.\n         - Type label: `bug`, `regression`, `performance`, etc.\n\n      6. Write the complete issue body to `$ARTIFACTS_DIR/issue-draft.md`\n\n      7. Write a one-line suggested title to `$ARTIFACTS_DIR/.issue-title`\n\n      8. Write suggested labels (comma-separated) to `$ARTIFACTS_DIR/.issue-labels`\n    depends_on: [check-reproduction, fetch-template, dedup-check, investigate]\n    when: \"$check-reproduction.output != 'NOT_REPRODUCED'\"\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 7: CREATE ISSUE\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: create-issue\n    prompt: |\n      Create the GitHub issue using the drafted content.\n\n      ## Instructions\n\n      1. Read the draft: `cat \"$ARTIFACTS_DIR/issue-draft.md\"`\n      2. Read the title: `cat \"$ARTIFACTS_DIR/.issue-title\"`\n      3. Read suggested labels: `cat \"$ARTIFACTS_DIR/.issue-labels\"`\n\n      4. Check which labels actually exist in the repo:\n         ```bash\n         gh label list --json name -q '.[].name' | head -50\n         ```\n         Only use labels that exist. Skip any suggested label that doesn't match.\n\n      5. Create the issue:\n         ```bash\n         gh issue create \\\n           --title \"$(cat \"$ARTIFACTS_DIR/.issue-title\")\" \\\n           --body-file \"$ARTIFACTS_DIR/issue-draft.md\" \\\n           --label \"label1,label2\"\n         ```\n\n      6. Capture the result:\n         ```bash\n         ISSUE_URL=$(gh issue list --limit 1 --json url -q '.[0].url')\n         echo \"$ISSUE_URL\" > \"$ARTIFACTS_DIR/.issue-url\"\n         ```\n\n      7. Report to the user:\n         - Issue URL\n         - Title\n         - Labels applied\n         - Whether duplicates were found\n         - Summary of reproduction results (reproduced/partial)\n    depends_on: [draft-issue]\n    context: fresh\n",
+  "archon-feature-development": "name: archon-feature-development\ndescription: |\n  Use when: Implementing a feature from an existing plan.\n  Input: Path to a plan file ($ARTIFACTS_DIR/plan.md) or GitHub issue containing a plan.\n  Does: Implements the plan with validation loops -> creates pull request.\n  NOT for: Creating plans (plans should be created separately), bug fixes, code reviews.\n\nnodes:\n  - id: implement\n    command: archon-implement\n    model: claude-opus-4-6[1m]\n\n  - id: create-pr\n    command: archon-create-pr\n    depends_on: [implement]\n    context: fresh\n",
+  "archon-fix-github-issue": "name: archon-fix-github-issue\ndescription: |\n  Use when: User wants to FIX, RESOLVE, or IMPLEMENT a solution for a GitHub issue.\n  Triggers: \"fix this issue\", \"implement issue #123\", \"resolve this bug\", \"fix it\",\n            \"fix issue\", \"resolve issue\", \"fix #123\".\n  NOT for: Comprehensive multi-agent reviews (use archon-issue-review-full),\n           questions about issues, CI failures, PR reviews, general exploration.\n\n  DAG workflow that:\n  1. Classifies the issue (bug/feature/enhancement/etc)\n  2. Researches context (web research + codebase exploration via investigate/plan)\n  3. Routes to investigate (bugs) or plan (features) based on classification\n  4. Implements the fix/feature with validation\n  5. Creates a draft PR using the repo's PR template\n  6. Runs smart review (always code review + CLAUDE.md check, conditional additional agents)\n  7. Aggressively self-fixes all findings (tests, docs, error handling)\n  8. Simplifies changed code (implements fixes directly, not just reports)\n  9. Reports results back to the GitHub issue with follow-up suggestions\n\nprovider: claude\nmodel: sonnet\n\nnodes:\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 1: FETCH & CLASSIFY\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: extract-issue-number\n    prompt: |\n      Find the GitHub issue number for this request.\n\n      Request: $ARGUMENTS\n\n      Rules:\n      - If the message contains an explicit issue number (e.g., \"#709\", \"issue 709\", \"709\"), extract that number.\n      - If the message is ambiguous (e.g., \"fix the SQLite timestamp bug\"), use `gh issue list` to search for matching issues and pick the best match.\n\n      CRITICAL: Your final output must be ONLY the bare number with no quotes, no markdown, no explanation. Example correct output: 709\n\n  - id: fetch-issue\n    bash: |\n      # Strip quotes, whitespace, markdown backticks from AI output\n      ISSUE_NUM=$(echo \"$extract-issue-number.output\" | tr -d \"'\\\"\\`\\n \" | grep -oE '[0-9]+' | head -1)\n      if [ -z \"$ISSUE_NUM\" ]; then\n        echo \"Failed to extract issue number from: $extract-issue-number.output\" >&2\n        exit 1\n      fi\n      gh issue view \"$ISSUE_NUM\" --json title,body,labels,comments,state,url,author\n    depends_on: [extract-issue-number]\n\n  - id: classify\n    prompt: |\n      You are an issue classifier. Analyze the GitHub issue below and determine its type.\n\n      ## Issue Content\n\n      $fetch-issue.output\n\n      ## Classification Rules\n\n      | Type | Indicators |\n      |------|------------|\n      | bug | \"broken\", \"error\", \"crash\", \"doesn't work\", stack traces, regression |\n      | feature | \"add\", \"new\", \"support\", \"would be nice\", net-new capability |\n      | enhancement | \"improve\", \"better\", \"update existing\", \"extend\", incremental improvement |\n      | refactor | \"clean up\", \"simplify\", \"reorganize\", \"restructure\" |\n      | chore | \"update deps\", \"upgrade\", \"maintenance\", \"CI/CD\" |\n      | documentation | \"docs\", \"readme\", \"clarify\", \"examples\" |\n\n      Provide reasoning for your classification.\n    depends_on: [fetch-issue]\n    model: haiku\n    allowed_tools: []\n    output_format:\n      type: object\n      properties:\n        issue_type:\n          type: string\n          enum: [\"bug\", \"feature\", \"enhancement\", \"refactor\", \"chore\", \"documentation\"]\n        title:\n          type: string\n        reasoning:\n          type: string\n      required: [issue_type, title, reasoning]\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 2: RESEARCH (parallel with PR template fetch)\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: web-research\n    command: archon-web-research\n    depends_on: [classify]\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 3: INVESTIGATE (bugs) / PLAN (features)\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: investigate\n    command: archon-investigate-issue\n    depends_on: [classify, web-research]\n    when: \"$classify.output.issue_type == 'bug'\"\n    context: fresh\n\n  - id: plan\n    command: archon-create-plan\n    depends_on: [classify, web-research]\n    when: \"$classify.output.issue_type != 'bug'\"\n    context: fresh\n\n  # Bridge: ensure investigation.md exists for the implement step\n  # archon-fix-issue reads from $ARTIFACTS_DIR/investigation.md\n  # archon-create-plan writes to $ARTIFACTS_DIR/plan.md\n  # This node copies plan.md → investigation.md when the plan path was taken\n  - id: bridge-artifacts\n    bash: |\n      if [ -f \"$ARTIFACTS_DIR/plan.md\" ] && [ ! -f \"$ARTIFACTS_DIR/investigation.md\" ]; then\n        cp \"$ARTIFACTS_DIR/plan.md\" \"$ARTIFACTS_DIR/investigation.md\"\n        echo \"Bridged plan.md to investigation.md for implement step\"\n      elif [ -f \"$ARTIFACTS_DIR/investigation.md\" ]; then\n        echo \"investigation.md exists from investigate step\"\n      else\n        echo \"WARNING: No investigation.md or plan.md found — implement may fail\"\n      fi\n    depends_on: [investigate, plan]\n    trigger_rule: one_success\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 4: IMPLEMENT\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: implement\n    command: archon-fix-issue\n    depends_on: [bridge-artifacts]\n    context: fresh\n    model: claude-opus-4-6[1m]\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 5: VALIDATE\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: validate\n    command: archon-validate\n    depends_on: [implement]\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 6: CREATE DRAFT PR\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: create-pr\n    prompt: |\n      Create a draft pull request for the current branch.\n\n      ## Context\n\n      - **Issue**: $ARGUMENTS\n      - **Classification**: $classify.output\n      - **Issue title**: $classify.output.title\n\n      ## Instructions\n\n      1. Check git status — ensure all changes are committed. If uncommitted changes exist, stage and commit them.\n      2. Push the branch: `git push -u origin HEAD`\n      3. Read implementation artifacts from `$ARTIFACTS_DIR/` for context:\n         - `$ARTIFACTS_DIR/investigation.md` or `$ARTIFACTS_DIR/plan.md`\n         - `$ARTIFACTS_DIR/implementation.md`\n         - `$ARTIFACTS_DIR/validation.md`\n      4. Check if a PR already exists for this branch: `gh pr list --head $(git branch --show-current)`\n         - If PR exists, skip creation and capture its number\n      5. Look for the project's PR template at `.github/pull_request_template.md`, `.github/PULL_REQUEST_TEMPLATE.md`, or `docs/PULL_REQUEST_TEMPLATE.md`. Read whichever one exists.\n      6. Create a DRAFT PR: `gh pr create --draft --base $BASE_BRANCH`\n         - Title: concise, imperative mood, under 70 chars\n         - Body: if a PR template was found, fill in **every section** with details from the artifacts. Don't skip sections or leave placeholders. If no template, write a body with summary, changes, validation evidence, and `Fixes #...`.\n         - Link to issue: include `Fixes #...` or `Closes #...`\n      7. Capture PR identifiers:\n         ```bash\n         PR_NUMBER=$(gh pr view --json number -q '.number')\n         echo \"$PR_NUMBER\" > \"$ARTIFACTS_DIR/.pr-number\"\n         PR_URL=$(gh pr view --json url -q '.url')\n         echo \"$PR_URL\" > \"$ARTIFACTS_DIR/.pr-url\"\n         ```\n    depends_on: [validate]\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 7: REVIEW\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: review-scope\n    command: archon-pr-review-scope\n    depends_on: [create-pr]\n    context: fresh\n\n  - id: review-classify\n    prompt: |\n      You are a PR review classifier. Analyze the PR scope and determine\n      which review agents should run.\n\n      ## PR Scope\n\n      $review-scope.output\n\n      ## Rules\n\n      - **Code review**: ALWAYS run. This is mandatory for every PR. It also checks\n        the PR against CLAUDE.md rules and project conventions.\n      - **Error handling**: Run if the diff touches code with try/catch, error handling,\n        async/await, or adds new failure paths.\n      - **Test coverage**: Run if the diff touches source code (not just tests, docs, or config).\n      - **Comment quality**: Run if the diff adds or modifies comments, docstrings, JSDoc,\n        or significant documentation within code files.\n      - **Docs impact**: Run if the diff adds/removes/renames public APIs, commands, CLI flags,\n        environment variables, or user-facing features.\n\n      Provide your reasoning for each decision.\n    depends_on: [review-scope]\n    model: haiku\n    allowed_tools: []\n    context: fresh\n    output_format:\n      type: object\n      properties:\n        run_code_review:\n          type: string\n          enum: [\"true\", \"false\"]\n        run_error_handling:\n          type: string\n          enum: [\"true\", \"false\"]\n        run_test_coverage:\n          type: string\n          enum: [\"true\", \"false\"]\n        run_comment_quality:\n          type: string\n          enum: [\"true\", \"false\"]\n        run_docs_impact:\n          type: string\n          enum: [\"true\", \"false\"]\n        reasoning:\n          type: string\n      required:\n        - run_code_review\n        - run_error_handling\n        - run_test_coverage\n        - run_comment_quality\n        - run_docs_impact\n        - reasoning\n\n  # Code review always runs — mandatory\n  - id: code-review\n    command: archon-code-review-agent\n    depends_on: [review-classify]\n    context: fresh\n\n  - id: error-handling\n    command: archon-error-handling-agent\n    depends_on: [review-classify]\n    when: \"$review-classify.output.run_error_handling == 'true'\"\n    context: fresh\n\n  - id: test-coverage\n    command: archon-test-coverage-agent\n    depends_on: [review-classify]\n    when: \"$review-classify.output.run_test_coverage == 'true'\"\n    context: fresh\n\n  - id: comment-quality\n    command: archon-comment-quality-agent\n    depends_on: [review-classify]\n    when: \"$review-classify.output.run_comment_quality == 'true'\"\n    context: fresh\n\n  - id: docs-impact\n    command: archon-docs-impact-agent\n    depends_on: [review-classify]\n    when: \"$review-classify.output.run_docs_impact == 'true'\"\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 8: SYNTHESIZE + SELF-FIX\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: synthesize\n    command: archon-synthesize-review\n    depends_on: [code-review, error-handling, test-coverage, comment-quality, docs-impact]\n    trigger_rule: one_success\n    context: fresh\n\n  - id: self-fix\n    command: archon-self-fix-all\n    depends_on: [synthesize]\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 9: SIMPLIFY\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: simplify\n    command: archon-simplify-changes\n    depends_on: [self-fix]\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 10: REPORT\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: report\n    command: archon-issue-completion-report\n    depends_on: [simplify]\n    context: fresh\n",
+  "archon-idea-to-pr": "name: archon-idea-to-pr\ndescription: |\n  Use when: You have a feature idea or description and want end-to-end development.\n  Input: Feature description in natural language, or path to a PRD file\n  Output: PR ready for merge with comprehensive review completed\n\n  Full workflow:\n  1. Create comprehensive implementation plan with codebase analysis\n  2. Setup branch and extract scope limits\n  3. Verify plan research is still valid\n  4. Implement all tasks with type-checking\n  5. Run full validation suite\n  6. Create PR with template, mark ready\n  7. Comprehensive code review (5 parallel agents with scope limit awareness)\n  8. Synthesize and fix review findings\n  9. Final summary with decision matrix -> GitHub comment + follow-up recommendations\n\n  NOT for: Executing existing plans (use archon-plan-to-pr), quick fixes, standalone reviews.\n\nnodes:\n  # ═══════════════════════════════════════════════════════════════════\n  # PHASE 0: CREATE PLAN\n  # ═══════════════════════════════════════════════════════════════════\n\n  - id: create-plan\n    command: archon-create-plan\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════════\n  # PHASE 1: SETUP\n  # ═══════════════════════════════════════════════════════════════════\n\n  - id: plan-setup\n    command: archon-plan-setup\n    depends_on: [create-plan]\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════════\n  # PHASE 2: CONFIRM PLAN\n  # ═══════════════════════════════════════════════════════════════════\n\n  - id: confirm-plan\n    command: archon-confirm-plan\n    depends_on: [plan-setup]\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════════\n  # PHASE 3: IMPLEMENT\n  # ═══════════════════════════════════════════════════════════════════\n\n  - id: implement-tasks\n    command: archon-implement-tasks\n    depends_on: [confirm-plan]\n    context: fresh\n    model: claude-opus-4-6[1m]\n\n  # ═══════════════════════════════════════════════════════════════════\n  # PHASE 4: VALIDATE\n  # ═══════════════════════════════════════════════════════════════════\n\n  - id: validate\n    command: archon-validate\n    depends_on: [implement-tasks]\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════════\n  # PHASE 5: FINALIZE PR\n  # ═══════════════════════════════════════════════════════════════════\n\n  - id: finalize-pr\n    command: archon-finalize-pr\n    depends_on: [validate]\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════════\n  # PHASE 6: CODE REVIEW\n  # ═══════════════════════════════════════════════════════════════════\n\n  - id: review-scope\n    command: archon-pr-review-scope\n    depends_on: [finalize-pr]\n    context: fresh\n\n  - id: sync\n    command: archon-sync-pr-with-main\n    depends_on: [review-scope]\n    context: fresh\n\n  - id: code-review\n    command: archon-code-review-agent\n    depends_on: [sync]\n    context: fresh\n\n  - id: error-handling\n    command: archon-error-handling-agent\n    depends_on: [sync]\n    context: fresh\n\n  - id: test-coverage\n    command: archon-test-coverage-agent\n    depends_on: [sync]\n    context: fresh\n\n  - id: comment-quality\n    command: archon-comment-quality-agent\n    depends_on: [sync]\n    context: fresh\n\n  - id: docs-impact\n    command: archon-docs-impact-agent\n    depends_on: [sync]\n    context: fresh\n\n  - id: synthesize\n    command: archon-synthesize-review\n    depends_on: [code-review, error-handling, test-coverage, comment-quality, docs-impact]\n    trigger_rule: one_success\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════════\n  # PHASE 7: FIX REVIEW ISSUES\n  # ═══════════════════════════════════════════════════════════════════\n\n  - id: implement-fixes\n    command: archon-implement-review-fixes\n    depends_on: [synthesize]\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════════\n  # PHASE 8: FINAL SUMMARY & FOLLOW-UP\n  # ═══════════════════════════════════════════════════════════════════\n\n  - id: workflow-summary\n    command: archon-workflow-summary\n    depends_on: [implement-fixes]\n    context: fresh\n",
+  "archon-interactive-prd": "name: archon-interactive-prd\ndescription: |\n  Use when: User wants to create a PRD through guided conversation.\n  Triggers: \"create a prd\", \"new prd\", \"interactive prd\", \"plan a feature\",\n            \"product requirements\", \"write a prd\".\n  NOT for: Autonomous PRD generation without human input (use archon-ralph-generate).\n\n  Interactive workflow that guides the user through problem-first PRD creation:\n  1. Understand the idea → ask foundation questions → wait for answers\n  2. Research market & codebase → ask deep dive questions → wait for answers\n  3. Assess technical feasibility → ask scope questions → wait for answers\n  4. Generate PRD → validate technical claims against codebase → output\n\nprovider: claude\ninteractive: true\n\nnodes:\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 1: INITIATE — Understand the idea\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: initiate\n    model: sonnet\n    prompt: |\n      You are a sharp product manager starting a PRD creation process.\n      You think from first principles — start with primitives, not features.\n\n      The user wants to build: $ARGUMENTS\n\n      If the input is clear, restate your understanding in 2-3 sentences and confirm:\n      \"I understand you want to build: {restated understanding}. Is this correct?\"\n\n      If the input is vague or empty, ask:\n      \"What do you want to build? Describe the product, feature, or capability.\"\n\n      Then present the Foundation Questions (all at once — the user will answer in the next step):\n\n      **Foundation Questions:**\n\n      1. **Who** has this problem? Be specific — not just \"users\" but what type of person/role?\n      2. **What** problem are they facing? Describe the observable pain, not the assumed need.\n      3. **Why** can't they solve it today? What alternatives exist and why do they fail?\n      4. **Why now?** What changed that makes this worth building?\n      5. **How** will you know if you solved it? What would success look like?\n\n      Keep it conversational. Don't generate any PRD content yet.\n\n  # ═══════════════════════════════════════════════════════════════\n  # GATE 1: User answers foundation questions\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: foundation-gate\n    approval:\n      message: \"Answer the foundation questions above. Your answers will guide the research phase.\"\n      capture_response: true\n    depends_on: [initiate]\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 2: GROUNDING — Research market & codebase\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: research\n    model: sonnet\n    prompt: |\n      You are researching context for a PRD. Think from first principles —\n      what already exists before proposing anything new.\n\n      **The idea**: $ARGUMENTS\n\n      **User's foundation answers**:\n      $foundation-gate.output\n\n      Research the landscape:\n\n      1. Search the web for similar products, competitors, and how others solve this problem\n      2. **Explore the codebase deeply** — find related existing functionality, APIs, UI components,\n         database tables, and patterns. Read actual files, don't assume. Note exact file paths and\n         what each file does.\n      3. Look for common patterns, anti-patterns, and recent trends\n\n      **First principles rule**: Before suggesting anything new, verify what already exists.\n      If there's an existing API endpoint, UI page, or component that partially solves the\n      problem, note it explicitly. The best solution extends what exists, not replaces it.\n\n      Present a summary to the user:\n\n      **What I found:**\n      - {Market insights — similar products, competitor approaches}\n      - {What already exists in the codebase — specific files, endpoints, components}\n      - {Key insight that might change the approach}\n\n      Then ask the **Deep Dive Questions**:\n\n      1. **Vision**: In one sentence, what's the ideal end state if this succeeds wildly?\n      2. **Primary User**: Describe your most important user — their role, context, and what triggers their need.\n      3. **Job to Be Done**: Complete this: \"When [situation], I want to [motivation], so I can [outcome].\"\n      4. **Non-Users**: Who is explicitly NOT the target?\n      5. **Constraints**: What limitations exist? (time, budget, technical, regulatory)\n\n      Does the research change or refine your thinking? Answer the deep dive questions.\n    depends_on: [foundation-gate]\n\n  # ═══════════════════════════════════════════════════════════════\n  # GATE 2: User answers deep dive questions\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: deepdive-gate\n    approval:\n      message: \"Answer the deep dive questions above (vision, primary user, JTBD, constraints). Add any adjustments from the research.\"\n      capture_response: true\n    depends_on: [research]\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 3: TECHNICAL GROUNDING — Feasibility from what exists\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: technical\n    model: sonnet\n    prompt: |\n      You are assessing technical feasibility for a PRD.\n      Think from first principles — start with what exists, not what you'd build from scratch.\n\n      **The idea**: $ARGUMENTS\n      **Foundation answers**: $foundation-gate.output\n      **Deep dive answers**: $deepdive-gate.output\n\n      **CRITICAL**: Explore the codebase by READING actual files. Do not guess or assume.\n      For every claim you make about the codebase, cite the exact file and line.\n\n      1. **What already exists** that partially solves this problem?\n         - Read existing API endpoints, DB queries, UI components\n         - Note exact function names, table schemas, component names\n         - What data is already being collected/stored?\n      2. **What's the smallest change** to the existing system that solves the core problem?\n         - Prefer extending existing files over creating new ones\n         - Prefer using existing endpoints over creating new ones\n         - Prefer adding to existing UI pages over new pages\n      3. **What are the actual primitives** we need?\n         - A new DB query? An existing one that needs a parameter?\n         - A new component? Or an existing component that needs a prop?\n         - A new endpoint? Or an existing endpoint that already returns the data?\n      4. **What's the risk?**\n         - Where could this go wrong?\n         - What assumptions need validation?\n\n      Present a summary:\n\n      **What Already Exists (verified by reading code):**\n      - {endpoint/component/query} at `{file:line}` — {what it does}\n      - {endpoint/component/query} at `{file:line}` — {what it does}\n\n      **Smallest Change to Solve the Problem:**\n      - {change 1}: {extend/modify} `{file}` — {what to do}\n      - {change 2}: {extend/modify} `{file}` — {what to do}\n\n      **Technical Context:**\n      - Feasibility: {HIGH/MEDIUM/LOW} because {reason}\n      - Key risk: {main concern}\n      - Estimated phases: {rough breakdown}\n\n      Then ask the **Scope Questions**:\n\n      1. **MVP Definition**: What's the absolute minimum to test if this works?\n      2. **Must Have vs Nice to Have**: What 2-3 things MUST be in v1? What can wait?\n      3. **Key Hypothesis**: Complete this: \"We believe [capability] will [solve problem] for [users]. We'll know we're right when [measurable outcome].\"\n      4. **Out of Scope**: What are you explicitly NOT building?\n      5. **Open Questions**: What uncertainties could change the approach?\n    depends_on: [deepdive-gate]\n\n  # ═══════════════════════════════════════════════════════════════\n  # GATE 3: User answers scope questions\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: scope-gate\n    approval:\n      message: \"Answer the scope questions above (MVP, must-haves, hypothesis, exclusions). This is the final input before PRD generation.\"\n      capture_response: true\n    depends_on: [technical]\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 4: GENERATE — Write the PRD\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: generate\n    model: sonnet\n    prompt: |\n      You are generating a PRD from the user's guided inputs.\n\n      **The idea**: $ARGUMENTS\n      **Foundation answers**: $foundation-gate.output\n      **Deep dive answers**: $deepdive-gate.output\n      **Scope answers**: $scope-gate.output\n\n      Generate a complete PRD file at `$ARTIFACTS_DIR/prds/{kebab-case-name}.prd.md`.\n\n      First create the directory:\n      ```bash\n      mkdir -p $ARTIFACTS_DIR/prds\n      ```\n\n      **First principles rule**: Before writing the Technical Approach section, READ the\n      actual codebase files you're referencing. Verify:\n      - File paths exist\n      - Function/component names are correct\n      - API endpoints you reference actually exist (or note they need to be created)\n      - DB table and column names match the schema\n      - Event type names match the constants in the code\n\n      The PRD must include ALL of these sections, filled from the user's answers:\n\n      1. **Problem Statement** — from foundation answers (who/what/why)\n      2. **Evidence** — from research findings and user's evidence\n      3. **Proposed Solution** — synthesized from all inputs. Prefer extending existing\n         primitives over creating new ones.\n      4. **Key Hypothesis** — from scope answers\n      5. **What We're NOT Building** — from scope answers\n      6. **Success Metrics** — from foundation \"how will you know\" + scope\n      7. **Open Questions** — from scope answers\n      8. **Users & Context** — from deep dive (primary user, JTBD, non-users)\n      9. **Solution Detail** — MoSCoW table from scope must-haves, MVP definition\n      10. **Technical Approach** — from technical feasibility. MUST reference actual\n          verified file paths, function names, and schemas. Mark anything unverified\n          as \"needs verification\".\n      11. **Implementation Phases** — from technical breakdown, with status table\n          and parallel opportunities\n      12. **Decisions Log** — key decisions made during the conversation\n\n      **Rules:**\n      - If info is missing, write \"TBD — needs research\" not filler\n      - Be specific and concrete, not generic\n      - Every file path in Technical Approach must be verified by reading the file\n      - Prefer \"extend X\" over \"create new Y\" in implementation phases\n\n      After writing the file, output the file path only — the validator will check it.\n    depends_on: [scope-gate]\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 5: VALIDATE — Check technical claims against codebase\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: validate\n    model: sonnet\n    prompt: |\n      You are a technical validator checking a PRD for accuracy.\n\n      Read the PRD file that was just generated. The generate node output the file path:\n      $generate.output\n\n      Find the PRD file — check `$ARTIFACTS_DIR/prds/` for the most recently created `.prd.md` file:\n      ```bash\n      ls -t $ARTIFACTS_DIR/prds/*.prd.md | head -1\n      ```\n\n      Read the entire PRD, then verify EVERY technical claim against the actual codebase:\n\n      **Check 1: File paths** — For every file referenced in \"Technical Approach\" and\n      \"Implementation Phases\", verify it exists. If it doesn't, note the correction.\n\n      **Check 2: API endpoints** — For every endpoint mentioned, check if it already exists\n      in `packages/server/src/routes/api.ts`. If it does, the PRD should say \"extend\" not \"create\".\n      If the PRD proposes a new endpoint for data that an existing endpoint already returns,\n      flag it.\n\n      **Check 3: DB schemas** — For every table/column referenced, verify the actual names\n      in the migration files or schema code. Check event type names against the\n      `WORKFLOW_EVENT_TYPES` constant.\n\n      **Check 4: UI components** — For every component referenced, verify it exists.\n      If the PRD proposes a new page but an existing page already serves a similar purpose,\n      flag it.\n\n      **Check 5: Function/type names** — Verify function names, type names, and interface\n      names are correct.\n\n      After checking, if there are ANY corrections needed:\n      1. Edit the PRD file directly — fix incorrect names, paths, and references\n      2. Add a `## Validation Notes` section at the bottom documenting what was corrected\n\n      If everything checks out, add:\n      ```\n      ## Validation Notes\n\n      All technical references verified against codebase. No corrections needed.\n      ```\n\n      Output a summary of what was checked and corrected:\n\n      ```\n      ## PRD Validated\n\n      **File**: `{prd-path}`\n      **Checks**: {N} file paths, {N} endpoints, {N} DB references, {N} components\n      **Corrections**: {count}\n      {list corrections if any}\n\n      To start implementation: `/prp-plan {prd-path}`\n      ```\n    depends_on: [generate]\n",
+  "archon-issue-review-full": "name: archon-issue-review-full\ndescription: |\n  Use when: User wants a FULL, COMPREHENSIVE fix + review pipeline for a GitHub issue.\n  Triggers: \"full review\", \"comprehensive fix\", \"fix with full review\", \"deep review\", \"issue review full\".\n  NOT for: Simple issue fixes (use archon-fix-github-issue instead),\n           questions about issues, CI failures, PR reviews, general exploration.\n\n  Full workflow:\n  1. Investigate issue -> root cause analysis, implementation plan\n  2. Implement fix -> code changes, tests, PR creation\n  3. Comprehensive review -> 5 parallel agents with scope awareness\n  4. Fix review issues -> address CRITICAL/HIGH findings\n  5. Final summary -> decision matrix, follow-up recommendations\n\nnodes:\n  # ═══════════════════════════════════════════════════════════════════\n  # PHASE 1: INVESTIGATE\n  # ═══════════════════════════════════════════════════════════════════\n\n  - id: investigate\n    command: archon-investigate-issue\n\n  # ═══════════════════════════════════════════════════════════════════\n  # PHASE 2: IMPLEMENT\n  # ═══════════════════════════════════════════════════════════════════\n\n  - id: implement\n    command: archon-implement-issue\n    depends_on: [investigate]\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════════\n  # PHASE 3: CODE REVIEW\n  # ═══════════════════════════════════════════════════════════════════\n\n  - id: review-scope\n    command: archon-pr-review-scope\n    depends_on: [implement]\n    context: fresh\n\n  - id: sync\n    command: archon-sync-pr-with-main\n    depends_on: [review-scope]\n    context: fresh\n\n  - id: code-review\n    command: archon-code-review-agent\n    depends_on: [sync]\n    context: fresh\n\n  - id: error-handling\n    command: archon-error-handling-agent\n    depends_on: [sync]\n    context: fresh\n\n  - id: test-coverage\n    command: archon-test-coverage-agent\n    depends_on: [sync]\n    context: fresh\n\n  - id: comment-quality\n    command: archon-comment-quality-agent\n    depends_on: [sync]\n    context: fresh\n\n  - id: docs-impact\n    command: archon-docs-impact-agent\n    depends_on: [sync]\n    context: fresh\n\n  - id: synthesize\n    command: archon-synthesize-review\n    depends_on: [code-review, error-handling, test-coverage, comment-quality, docs-impact]\n    trigger_rule: one_success\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════════\n  # PHASE 4: FIX REVIEW ISSUES\n  # ═══════════════════════════════════════════════════════════════════\n\n  - id: implement-fixes\n    command: archon-implement-review-fixes\n    depends_on: [synthesize]\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════════\n  # PHASE 5: FINAL SUMMARY\n  # ═══════════════════════════════════════════════════════════════════\n\n  - id: summary\n    command: archon-workflow-summary\n    depends_on: [implement-fixes]\n    context: fresh\n",
+  "archon-piv-loop": "name: archon-piv-loop\ndescription: |\n  Use when: User wants guided Plan-Implement-Validate development with human-in-the-loop.\n  Triggers: \"piv\", \"piv loop\", \"plan implement validate\", \"guided development\",\n            \"structured development\", \"build a feature\", \"develop with review\".\n  NOT for: Autonomous implementation without planning (use archon-feature-development).\n  NOT for: PRD creation (use archon-interactive-prd).\n  NOT for: Ralph story-based implementation (use archon-ralph-dag).\n\n  Interactive PIV loop workflow — the foundational AI coding methodology:\n  1. EXPLORE: Iterative conversation with human to understand the problem (arbitrary rounds)\n  2. PLAN: Create structured plan -> iterative review & revision (arbitrary rounds)\n  3. IMPLEMENT: Autonomous task-by-task implementation from plan (Ralph loop)\n  4. VALIDATE: Automated code review -> iterative human feedback & fixes (arbitrary rounds)\n\n  The PIV loop comes AFTER a PRD exists. Each PIV loop focuses on ONE granular feature or bug fix.\n  Input: A description of what to build, a path to an existing plan, or a GitHub issue number.\n\nprovider: claude\ninteractive: true\n\nnodes:\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 1: EXPLORE — Iterative exploration with human\n  # Understand the idea, explore the codebase, converge on approach\n  # Loops until the user says they're ready to create the plan.\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: explore\n    loop:\n      prompt: |\n        # PIV Loop — Exploration\n\n        You are a senior engineering partner in an iterative exploration session.\n        Your goal: DEEPLY UNDERSTAND what to build before any code is written.\n\n        **User's request**: $ARGUMENTS\n        **User's latest input**: $LOOP_USER_INPUT\n\n        ---\n\n        ## If this is the FIRST iteration (no user input yet):\n\n        ### Step 1: Parse the Input\n\n        Determine what the user provided:\n\n        **If it's a file path** (ends in `.md`, `.plan.md`, or `.prd.md`):\n        - Read the file\n        - If it's an existing plan → summarize it and ask if they want to refine or proceed\n        - If it's a PRD → identify the specific phase/feature to focus on\n\n        **If it's a GitHub issue** (`#123` format):\n        - Fetch it: `gh issue view {number} --json title,body,labels,comments`\n        - Summarize the issue context\n\n        **If it's free text**:\n        - This is a feature idea or bug description. Use it directly.\n\n        ### Step 2: Explore the Codebase\n\n        Before asking questions, DO YOUR HOMEWORK:\n\n        1. **Read CLAUDE.md** — understand project conventions, architecture, and constraints\n        2. **Search for related code** — find existing implementations similar to what the user wants\n        3. **Read key files** — understand the current state of code the user wants to change\n        4. **Check recent git history** — `git log --oneline -20` for recent changes in the area\n\n        ### Step 3: Present Your Understanding\n\n        ```\n        ## What I Understand\n\n        You want to: {restated understanding in 2-3 sentences}\n\n        ## What Already Exists\n\n        - {file:line} — {what it does and how it relates}\n        - {file:line} — {what it does and how it relates}\n        - {pattern/component} — {how it could be extended or reused}\n\n        ## Initial Architecture Thoughts\n\n        Based on what exists, I'm thinking:\n        - {approach 1 — extend existing X}\n        - {approach 2 — if approach 1 doesn't work}\n        - {key architectural decision that needs your input}\n        ```\n\n        ### Step 4: Ask Targeted Questions\n\n        Ask 4-6 questions focused on DECISIONS, not information gathering:\n        - Scope boundaries, architecture preferences, tech decisions\n        - Constraints, existing code extension vs fresh build, testing expectations\n        - Reference actual code you found — don't ask generic questions\n\n        ---\n\n        ## If the user has provided input (subsequent iterations):\n\n        ### Step 1: Process Their Response\n\n        Read their answers carefully. Identify:\n        - Decisions they've made\n        - Areas they want you to explore further\n        - Questions they asked YOU back (answer these with evidence!)\n\n        ### Step 2: Do Targeted Research\n\n        Based on their response:\n        - If they mentioned specific technologies → research best practices\n        - If they pointed you to specific code → read it thoroughly\n        - If they asked you to explore an area → do a thorough investigation\n        - If they made architecture decisions → validate against the codebase\n\n        ### Step 3: Present Updated Understanding\n\n        Show what you learned, answer their questions with file:line references,\n        and present your refined architecture recommendation.\n\n        ### Step 4: Converge or Continue\n\n        **If there are still important open questions:**\n        Ask 2-4 focused questions about remaining ambiguities.\n\n        **If the picture is clear and you have enough to create a plan:**\n        Present a final implementation summary:\n\n        ```\n        ## Implementation Summary\n\n        ### What We're Building\n        {Clear, specific description}\n\n        ### Scope Boundary\n        - IN: {what's included}\n        - OUT: {what's explicitly excluded}\n\n        ### Architecture\n        - {key decisions}\n\n        ### Files That Will Change\n        - `{file}` — {what changes and why}\n\n        ### Success Criteria\n        - [ ] {specific, testable criterion}\n        - [ ] All validation passes\n\n        ### Key Risks\n        - {risk — and mitigation}\n        ```\n\n        Then tell the user: \"I have a clear picture. Say **ready** and I'll create\n        the structured implementation plan, or share any final thoughts.\"\n\n        **CRITICAL — READ THIS CAREFULLY**:\n        - NEVER output <promise>PLAN_READY</promise> unless the user's LATEST message contains\n          an EXPLICIT phrase like \"ready\", \"create the plan\", \"let's go\", \"proceed\", or \"I'm done\".\n        - If the user asked a question → do NOT emit the signal. Answer the question.\n        - If the user gave feedback or requested changes → do NOT emit the signal. Address it.\n        - If the user said \"also check X\" or \"one more thing\" → do NOT emit the signal. Explore it.\n        - If you are unsure whether the user is approving → do NOT emit the signal. Ask them.\n        - The ONLY correct time to emit the signal is when the user's message CLEARLY means\n          \"stop exploring, I'm ready for you to create the plan.\"\n      until: PLAN_READY\n      max_iterations: 15\n      interactive: true\n      gate_message: |\n        Answer the questions above, ask me to explore specific areas,\n        or say \"ready\" when you're satisfied with the exploration.\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 2: PLAN — Create the structured implementation plan\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: create-plan\n    model: sonnet\n    depends_on: [explore]\n    context: fresh\n    prompt: |\n      # PIV Loop — Create Structured Plan\n\n      You are creating a structured implementation plan from a completed exploration phase.\n      This plan will be the SOLE GUIDE for the implementation agent — it must be complete,\n      specific, and actionable.\n\n      **Original request**: $ARGUMENTS\n      **Final exploration summary**: $explore.output\n\n      ---\n\n      ## Step 1: Read the Codebase (Again)\n\n      Before writing the plan, verify your understanding is current:\n\n      1. **Read CLAUDE.md** — capture all relevant conventions\n      2. **Read every file you plan to change** — note exact current state\n      3. **Read example test files** — understand testing patterns\n      4. **Check for any recent changes** — `git log --oneline -10`\n\n      ## Step 2: Determine Plan Location\n\n      Generate a kebab-case slug from the feature name.\n      Save to `.claude/archon/plans/{slug}.plan.md`.\n\n      ```bash\n      mkdir -p .claude/archon/plans\n      ```\n\n      ## Step 3: Write the Plan\n\n      Use this template. Fill EVERY section with specific, verified information.\n\n      ```markdown\n      # Feature: {Title}\n\n      ## Summary\n      {1-2 sentences: what changes and why}\n\n      ## Mission\n      {The core goal in one clear statement}\n\n      ## Success Criteria\n      - [ ] {Specific, testable criterion}\n      - [ ] All validation passes (`bun run validate` or equivalent)\n      - [ ] No regressions in existing tests\n\n      ## Scope\n      ### In Scope\n      - {What we ARE building}\n      ### Out of Scope\n      - {What we are NOT building — and why}\n\n      ## Codebase Context\n      ### Key Files\n      | File | Role | Action |\n      |------|------|--------|\n      | `{path}` | {what it does} | CREATE / UPDATE |\n\n      ### Patterns to Follow\n      {Actual code snippets from the codebase to mirror}\n\n      ## Architecture\n      - {Decision 1 — with rationale}\n      - {Decision 2 — with rationale}\n\n      ## Task List\n      Execute in order. Each task is atomic and independently verifiable.\n\n      ### Task 1: {ACTION} `{file path}`\n      **Action**: CREATE / UPDATE\n      **Details**: {Exact changes — specific enough for an agent with no context}\n      **Pattern**: Follow `{source file}:{lines}`\n      **Validate**: `{command to verify this task}`\n\n      ## Testing Strategy\n      | Test File | Test Cases | Validates |\n      |-----------|-----------|-----------|\n      | `{path}` | {cases} | {what it validates} |\n\n      ## Validation Commands\n      1. Type check: `{command}`\n      2. Lint: `{command}`\n      3. Tests: `{command}`\n      4. Full validation: `{command}`\n\n      ## Risks\n      | Risk | Impact | Mitigation |\n      |------|--------|------------|\n      | {risk} | {HIGH/MED/LOW} | {specific mitigation} |\n      ```\n\n      ## Step 4: Verify the Plan\n\n      1. Check every file path referenced — verify they exist\n      2. Check every pattern cited — verify the code matches\n      3. Check task ordering — ensure dependencies are respected\n      4. Check completeness — could an agent with NO context implement this?\n\n      ## Step 5: Report\n\n      ```\n      ## Plan Created\n\n      **File**: `.claude/archon/plans/{slug}.plan.md`\n      **Tasks**: {count}\n      **Files to change**: {count}\n\n      Key decisions:\n      - {decision 1}\n      - {decision 2}\n\n      Please review the plan and provide feedback.\n      ```\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 2b: PLAN — Iterative plan refinement\n  # Review and revise the plan as many times as needed.\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: refine-plan\n    depends_on: [create-plan]\n    loop:\n      prompt: |\n        # PIV Loop — Plan Refinement\n\n        The user is reviewing the implementation plan and providing feedback.\n\n        **User's feedback**: $LOOP_USER_INPUT\n\n        ---\n\n        ## Step 1: Find and Read the Plan\n\n        ```bash\n        ls -t .claude/archon/plans/*.plan.md 2>/dev/null | head -1\n        ```\n\n        Read the entire plan file. Also read CLAUDE.md for conventions.\n\n        ## Step 2: Process Feedback\n\n        **If there is no user feedback yet** (first iteration, $LOOP_USER_INPUT is empty):\n        - Read the plan carefully\n        - Present a summary of the plan's key decisions and task list\n        - Ask the user to review and provide feedback\n        - Do NOT emit the completion signal on the first iteration\n\n        **If the user EXPLICITLY approved** (said \"approved\", \"looks good\", \"let's go\", etc.):\n        - Make no changes\n        - Output: \"Plan approved. Proceeding to implementation.\"\n        - Signal completion: <promise>PLAN_APPROVED</promise>\n\n        **If the user provided specific feedback:**\n        - Parse each piece of feedback\n        - Edit the plan file directly:\n          - Add/remove/modify tasks as requested\n          - Update success criteria if needed\n          - Adjust testing strategy if needed\n          - Re-verify file paths and patterns after changes\n\n        **CRITICAL**: NEVER emit <promise>PLAN_APPROVED</promise> unless the user's latest\n        message EXPLICITLY says \"approved\", \"looks good\", \"ship it\", or similar approval.\n        Questions, feedback, and requests for changes are NOT approval.\n\n        ## Step 3: Show Changes\n\n        ```\n        ## Plan Revised\n\n        Changes made:\n        - {change 1}\n        - {change 2}\n\n        Updated stats:\n        - Tasks: {count}\n        - Files to change: {count}\n\n        Review the updated plan and provide more feedback, or say \"approved\" to proceed.\n        ```\n      until: PLAN_APPROVED\n      max_iterations: 10\n      interactive: true\n      gate_message: |\n        Review the plan document. Provide specific feedback on what to change,\n        or say \"approved\" to begin implementation.\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 3: IMPLEMENT — Setup\n  # Read the plan, prepare the environment\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: implement-setup\n    depends_on: [refine-plan]\n    bash: |\n      set -e\n\n      PLAN_FILE=$(ls -t .claude/archon/plans/*.plan.md 2>/dev/null | head -1)\n\n      if [ -z \"$PLAN_FILE\" ]; then\n        echo \"ERROR: No plan file found in .claude/archon/plans/\"\n        exit 1\n      fi\n\n      # Install dependencies if needed\n      if [ -f \"bun.lock\" ] || [ -f \"bun.lockb\" ]; then\n        echo \"Installing dependencies...\"\n        bun install --frozen-lockfile 2>&1 | tail -3\n      elif [ -f \"package-lock.json\" ]; then\n        npm ci 2>&1 | tail -3\n      elif [ -f \"yarn.lock\" ]; then\n        yarn install --frozen-lockfile 2>&1 | tail -3\n      elif [ -f \"pnpm-lock.yaml\" ]; then\n        pnpm install --frozen-lockfile 2>&1 | tail -3\n      fi\n\n      echo \"BRANCH=$(git branch --show-current)\"\n      echo \"GIT_ROOT=$(git rev-parse --show-toplevel)\"\n      echo \"PLAN_FILE=$PLAN_FILE\"\n\n      echo \"=== PLAN_START ===\"\n      cat \"$PLAN_FILE\"\n      echo \"\"\n      echo \"=== PLAN_END ===\"\n\n      TASK_COUNT=$(grep -c \"^### Task [0-9]\" \"$PLAN_FILE\" || true)\n      echo \"TASK_COUNT=${TASK_COUNT:-0}\"\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 3b: IMPLEMENT — Task-by-Task Loop (Ralph pattern)\n  # Fresh context each iteration. Reads plan from disk.\n  # One task per iteration. Validates before committing.\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: implement\n    depends_on: [implement-setup]\n    idle_timeout: 600000\n    model: claude-opus-4-6[1m]\n    loop:\n      prompt: |\n        # PIV Loop — Implementation Agent\n\n        You are an autonomous coding agent in a FRESH session — no memory of previous iterations.\n        Your job: Read the plan from disk, implement ONE task, validate, commit, update tracking, exit.\n\n        **Golden Rule**: If validation fails, fix it before committing. Never commit broken code.\n\n        ---\n\n        ## Phase 0: CONTEXT — Load State\n\n        The setup node produced this context:\n\n        $implement-setup.output\n\n        **User's original request**: $USER_MESSAGE\n\n        ---\n\n        ### 0.1 Parse Plan File\n\n        Extract the `PLAN_FILE=...` line from the context above.\n\n        ### 0.2 Read Current State (from disk — not from context above)\n\n        The context above is a snapshot from before the loop started. Previous iterations\n        may have changed things. **You MUST re-read from disk:**\n\n        1. **Read the plan file** — your implementation guide\n        2. **Read progress tracking** — check if `.claude/archon/plans/progress.txt` exists\n        3. **Read CLAUDE.md** — project conventions and constraints\n\n        ### 0.3 Check Git State\n\n        ```bash\n        git log --oneline -10\n        git status\n        ```\n\n        ---\n\n        ## Phase 1: SELECT — Pick Next Task\n\n        From the plan file, identify tasks by `### Task N:` headers.\n        Cross-reference with commits from previous iterations and progress tracking.\n\n        **If ALL tasks are complete** → Skip to Phase 5 (Completion).\n\n        ### Announce Selection\n\n        ```\n        -- Task Selected ------------------------------------------------\n        Task: {N} — {task title}\n        Action: {CREATE / UPDATE}\n        File: {file path}\n        -----------------------------------------------------------------\n        ```\n\n        ---\n\n        ## Phase 2: IMPLEMENT — Execute the Task\n\n        1. Read the file you're about to change (if it exists)\n        2. Read the pattern file referenced in the plan\n        3. Make changes following the plan EXACTLY\n        4. Type-check after each file: `bun run type-check 2>&1 || true`\n\n        ---\n\n        ## Phase 3: VALIDATE — Verify the Task\n\n        ```bash\n        bun run type-check && bun run lint && bun run test && bun run format:check\n        ```\n\n        If validation fails: fix, re-run (up to 3 attempts). If unfixable, note in progress\n        tracking and do NOT commit broken code.\n\n        ---\n\n        ## Phase 4: COMMIT — Save Changes\n\n        ```bash\n        git add -A\n        git diff --cached --stat\n        git commit -m \"$(cat <<'EOF'\n        {type}: {task description}\n\n        PIV Task {N}: {brief details}\n        EOF\n        )\"\n        ```\n\n        Track progress in `.claude/archon/plans/progress.txt`:\n        ```\n        ## Task {N}: {title} — COMPLETED\n        Date: {ISO date}\n        Files: {list}\n        Commit: {short hash}\n        ---\n        ```\n\n        ---\n\n        ## Phase 5: COMPLETE — Check All Tasks\n\n        If ALL tasks are done:\n        1. Run full validation: `bun run validate 2>&1`\n        2. Push: `git push -u origin HEAD`\n        3. Signal: `<promise>COMPLETE</promise>`\n\n        If tasks remain, report status and end normally. The loop engine starts a fresh iteration.\n      until: COMPLETE\n      max_iterations: 15\n      fresh_context: true\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 4: VALIDATE — Automated code review\n  # Review all changes against the plan\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: code-review\n    model: sonnet\n    depends_on: [implement]\n    context: fresh\n    prompt: |\n      # PIV Loop — Automated Code Review\n\n      The implementation phase is complete. Review ALL changes against the plan.\n\n      **Implementation output**: $implement.output\n\n      ---\n\n      ## Step 1: Find and Read the Plan\n\n      ```bash\n      ls -t .claude/archon/plans/*.plan.md 2>/dev/null | head -1\n      ```\n\n      ## Step 2: Review All Changes\n\n      ```bash\n      git log --oneline --no-merges $(git merge-base HEAD $BASE_BRANCH)..HEAD\n      git diff $BASE_BRANCH..HEAD --stat\n      git diff $BASE_BRANCH..HEAD\n      ```\n\n      ## Step 3: Check Against Plan\n\n      For EACH task: was it implemented correctly? Do success criteria hold?\n      For EACH file: check quality, security, patterns, CLAUDE.md compliance.\n\n      ## Step 4: Run Validation\n\n      ```bash\n      bun run validate 2>&1 || (bun run type-check && bun run lint && bun run test && bun run format:check)\n      ```\n\n      ## Step 5: Fix Obvious Issues\n\n      Fix type errors, lint warnings, missing imports, formatting. Commit any fixes:\n      ```bash\n      git add -A && git commit -m \"fix: address code review findings\" 2>/dev/null || true\n      ```\n\n      ## Step 6: Present Review\n\n      ```\n      ## Code Review Complete\n\n      ### Implementation Status\n      | Task | Status | Notes |\n      |------|--------|-------|\n      | {task} | DONE / PARTIAL / MISSING | {notes} |\n\n      ### Validation Results\n      - Type-check: PASS / FAIL\n      - Lint: PASS / FAIL\n      - Tests: PASS / FAIL\n      - Format: PASS / FAIL\n\n      ### Code Quality Findings\n      {Issues found, or \"No issues found.\"}\n\n      ### Recommendation\n      {READY FOR REVIEW / NEEDS FIXES}\n      ```\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 4b: VALIDATE — Iterative human feedback & fixes\n  # The user tests the implementation and provides feedback.\n  # Loops until the user approves.\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: fix-feedback\n    depends_on: [code-review]\n    loop:\n      prompt: |\n        # PIV Loop — Address Validation Feedback\n\n        The human has reviewed the implementation and provided feedback.\n\n        **Human's feedback**: $LOOP_USER_INPUT\n\n        ---\n\n        ## Step 1: Read Context\n\n        ```bash\n        ls -t .claude/archon/plans/*.plan.md 2>/dev/null | head -1\n        ```\n\n        Read the plan file and CLAUDE.md for conventions.\n\n        ## Step 2: Process Feedback\n\n        **If there is no user feedback yet** (first iteration, $LOOP_USER_INPUT is empty):\n        - Present the code review results and ask the user to test the implementation\n        - Do NOT emit the completion signal on the first iteration\n\n        **If the user EXPLICITLY approved** (said \"approved\", \"looks good\", \"ship it\", etc.):\n        - Output: \"Implementation approved!\"\n        - Signal: <promise>VALIDATED</promise>\n\n        **CRITICAL**: NEVER emit <promise>VALIDATED</promise> unless the user's latest\n        message EXPLICITLY says \"approved\", \"looks good\", \"ship it\", or similar approval.\n\n        **If the user provided specific feedback:**\n        1. Read the relevant files\n        2. Understand each issue\n        3. Make the fixes\n        4. Type-check after each change\n\n        ## Step 3: Full Validation\n\n        ```bash\n        bun run validate 2>&1 || (bun run type-check && bun run lint && bun run test && bun run format:check)\n        ```\n\n        ## Step 4: Commit Fixes\n\n        ```bash\n        git add -A\n        git commit -m \"$(cat <<'EOF'\n        fix: address review feedback\n\n        Changes:\n        - {fix 1}\n        - {fix 2}\n        EOF\n        )\"\n        ```\n\n        ## Step 5: Report\n\n        ```\n        ## Feedback Addressed\n\n        Changes made:\n        - {fix 1}\n        - {fix 2}\n\n        Validation: {PASS / FAIL with details}\n\n        Review again, or say \"approved\" to finalize.\n        ```\n      until: VALIDATED\n      max_iterations: 10\n      interactive: true\n      gate_message: |\n        Test the implementation yourself and review the code changes.\n        Provide specific feedback on what needs fixing, or say \"approved\" to finalize.\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 5: FINALIZE — Push, create PR, generate summary\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: finalize\n    model: sonnet\n    depends_on: [fix-feedback]\n    context: fresh\n    prompt: |\n      # PIV Loop — Finalize\n\n      The implementation has been approved. Push changes and create a PR.\n\n      ---\n\n      ## Step 1: Push Changes\n\n      ```bash\n      git push -u origin HEAD 2>&1 || true\n      ```\n\n      ## Step 2: Generate Summary\n\n      ```bash\n      git log --oneline --no-merges $(git merge-base HEAD $BASE_BRANCH)..HEAD\n      git diff --stat $(git merge-base HEAD $BASE_BRANCH)..HEAD\n      ```\n\n      Read the plan file and progress tracking for context.\n\n      ## Step 3: Create PR (if not already created)\n\n      ```bash\n      gh pr view HEAD --json url 2>/dev/null || echo \"NO_PR\"\n      ```\n\n      If no PR exists:\n\n      ```bash\n      cat .github/pull_request_template.md 2>/dev/null || echo \"NO_TEMPLATE\"\n      ```\n\n      Create with `gh pr create --draft --base $BASE_BRANCH`:\n      - Title from the plan's feature name\n      - Body summarizing the implementation\n      - Use a HEREDOC for the body\n\n      ## Step 4: Output Summary\n\n      ```\n      ===============================================================\n      PIV LOOP — COMPLETE\n      ===============================================================\n\n      Feature: {from plan}\n      Plan: {plan file path}\n      Branch: {branch name}\n      PR: {url}\n\n      -- Tasks Completed -----------------------------------------------\n      {list from progress tracking}\n\n      -- Commits -------------------------------------------------------\n      {git log output}\n\n      -- Files Changed -------------------------------------------------\n      {git diff --stat output}\n\n      -- Validation ----------------------------------------------------\n      All checks passed.\n      ===============================================================\n      ```\n",
+  "archon-plan-to-pr": "name: archon-plan-to-pr\ndescription: |\n  Use when: You have an existing implementation plan and want to execute it end-to-end.\n  Input: Path to a plan file ($ARTIFACTS_DIR/plan.md or .agents/plans/*.md)\n  Output: PR ready for merge with comprehensive review completed\n\n  Full workflow:\n  1. Read plan, setup branch, extract scope limits\n  2. Verify plan research is still valid\n  3. Implement all tasks with type-checking\n  4. Run full validation suite\n  5. Create PR with template, mark ready\n  6. Comprehensive code review (5 parallel agents with scope limit awareness)\n  7. Synthesize and fix review findings\n  8. Final summary with decision matrix -> GitHub comment + follow-up recommendations\n\n  NOT for: Creating plans from scratch (use archon-idea-to-pr), quick fixes, standalone reviews.\n\nnodes:\n  # ═══════════════════════════════════════════════════════════════════\n  # PHASE 1: SETUP\n  # ═══════════════════════════════════════════════════════════════════\n\n  - id: plan-setup\n    command: archon-plan-setup\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════════\n  # PHASE 2: CONFIRM PLAN\n  # ═══════════════════════════════════════════════════════════════════\n\n  - id: confirm-plan\n    command: archon-confirm-plan\n    depends_on: [plan-setup]\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════════\n  # PHASE 3: IMPLEMENT\n  # ═══════════════════════════════════════════════════════════════════\n\n  - id: implement-tasks\n    command: archon-implement-tasks\n    depends_on: [confirm-plan]\n    context: fresh\n    model: claude-opus-4-6[1m]\n\n  # ═══════════════════════════════════════════════════════════════════\n  # PHASE 4: VALIDATE\n  # ═══════════════════════════════════════════════════════════════════\n\n  - id: validate\n    command: archon-validate\n    depends_on: [implement-tasks]\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════════\n  # PHASE 5: FINALIZE PR\n  # ═══════════════════════════════════════════════════════════════════\n\n  - id: finalize-pr\n    command: archon-finalize-pr\n    depends_on: [validate]\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════════\n  # PHASE 6: CODE REVIEW\n  # ═══════════════════════════════════════════════════════════════════\n\n  - id: review-scope\n    command: archon-pr-review-scope\n    depends_on: [finalize-pr]\n    context: fresh\n\n  - id: sync\n    command: archon-sync-pr-with-main\n    depends_on: [review-scope]\n    context: fresh\n\n  - id: code-review\n    command: archon-code-review-agent\n    depends_on: [sync]\n    context: fresh\n\n  - id: error-handling\n    command: archon-error-handling-agent\n    depends_on: [sync]\n    context: fresh\n\n  - id: test-coverage\n    command: archon-test-coverage-agent\n    depends_on: [sync]\n    context: fresh\n\n  - id: comment-quality\n    command: archon-comment-quality-agent\n    depends_on: [sync]\n    context: fresh\n\n  - id: docs-impact\n    command: archon-docs-impact-agent\n    depends_on: [sync]\n    context: fresh\n\n  - id: synthesize\n    command: archon-synthesize-review\n    depends_on: [code-review, error-handling, test-coverage, comment-quality, docs-impact]\n    trigger_rule: one_success\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════════\n  # PHASE 7: FIX REVIEW ISSUES\n  # ═══════════════════════════════════════════════════════════════════\n\n  - id: implement-fixes\n    command: archon-implement-review-fixes\n    depends_on: [synthesize]\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════════\n  # PHASE 8: FINAL SUMMARY & FOLLOW-UP\n  # ═══════════════════════════════════════════════════════════════════\n\n  - id: workflow-summary\n    command: archon-workflow-summary\n    depends_on: [implement-fixes]\n    context: fresh\n",
+  "archon-ralph-dag": "name: archon-ralph-dag\ndescription: |\n  Use when: User wants to run a Ralph implementation loop.\n  Triggers: \"ralph\", \"run ralph\", \"ralph dag\", \"run ralph dag\".\n\n  DAG workflow that:\n  1. Detects input: existing prd.json, existing prd.md (needs stories), or raw idea\n  2. Generates prd.md + prd.json if needed (explores codebase, breaks into stories)\n  3. Validates PRD files, reads project context, installs dependencies\n  4. Runs Ralph loop (fresh context per iteration) implementing one story per iteration\n  5. Creates PR and reports completion\n\n  Accepts: An idea description, a path to an existing prd.md, or a directory with prd.md + prd.json\n\nprovider: claude\n\nnodes:\n  # ═══════════════════════════════════════════════════════════════\n  # NODE 1: DETECT INPUT\n  # Determines what the user provided: full PRD, partial PRD, or idea\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: detect-input\n    model: haiku\n    prompt: |\n      # Detect Ralph Input\n\n      **User input**: $ARGUMENTS\n\n      Determine what the user provided and prepare the PRD directory. Follow these steps exactly:\n\n      ## Step 1: Detect worktree\n\n      Run `git worktree list --porcelain` to check if you're in a worktree.\n      If you see multiple entries, you ARE in a worktree. The first entry (the one without \"branch\" pointing to your current branch) is the **main repo root**. Save it — you'll need it to find files.\n\n      ## Step 2: Classify the input\n\n      Look at the user input above. It's one of three things:\n\n      **Case A — Ralph directory path** (contains `.archon/ralph/`):\n      Extract the directory. Check if both `prd.json` and `prd.md` exist there (try locally first, then in the main repo root if in a worktree).\n\n      **Case B — File path** (ends in `.md`):\n      This is an external PRD file. Find it:\n      1. Try the path as-is (relative to cwd)\n      2. Try it as an absolute path\n      3. If in a worktree, try it relative to the **main repo root** from Step 1\n      Once found, read the file to confirm it's a PRD.\n\n      **Case C — Free text**:\n      Not a file path — it's a feature idea.\n\n      ## Step 3: Auto-discover existing ralph PRDs\n\n      If the input didn't point to a specific path, check if `.archon/ralph/` contains any `prd.json` files:\n      ```bash\n      find .archon/ralph -name \"prd.json\" -type f 2>/dev/null\n      ```\n\n      ## Step 4: Take action based on classification\n\n      **If Case A and both files exist** → output `ready` (no further action needed)\n\n      **If Case B (external PRD found)**:\n      1. Derive a kebab-case slug from the PRD filename or title (e.g., `workflow-lifecycle-overhaul`)\n      2. Create the ralph directory: `mkdir -p .archon/ralph/{slug}`\n      3. Copy the PRD content to `.archon/ralph/{slug}/prd.md`\n      4. Output `external_prd` with the new prd_dir\n\n      **If Case C or auto-discovered ralph dir has prd.md but no prd.json** → output `needs_generation`\n\n      ## Output\n\n      Your final output MUST be exactly one JSON object:\n      ```json\n      {\"input_type\": \"ready|external_prd|needs_generation\", \"prd_dir\": \".archon/ralph/{slug}\"}\n      ```\n    output_format:\n      type: object\n      properties:\n        input_type:\n          type: string\n          enum: [ready, external_prd, needs_generation]\n        prd_dir:\n          type: string\n      required: [input_type, prd_dir]\n\n  # ═══════════════════════════════════════════════════════════════\n  # NODE 2: GENERATE PRD\n  # Scenario 1: User has an idea → generate prd.md + prd.json\n  # Scenario 2: User has prd.md → generate prd.json with stories\n  # Skipped if prd.json already exists\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: generate-prd\n    depends_on: [detect-input]\n    when: \"$detect-input.output.input_type != 'ready'\"\n    command: archon-ralph-generate\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════\n  # NODE 3: VALIDATE & SETUP\n  # Finds PRD directory, reads all state files, installs deps,\n  # verifies the environment is ready for implementation.\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: validate-prd\n    depends_on: [detect-input, generate-prd]\n    trigger_rule: one_success\n    bash: |\n      set -e\n\n      # ── 1. Find PRD directory (passed from detect-input) ──────\n      PRD_DIR=$detect-input.output.prd_dir\n\n      # If detect-input didn't know the PRD dir (generated from scratch), discover it\n      if [ -z \"$PRD_DIR\" ] || [ ! -f \"$PRD_DIR/prd.json\" ]; then\n        FOUND=$(find .archon/ralph -name \"prd.json\" -type f 2>/dev/null | head -1)\n        if [ -n \"$FOUND\" ]; then\n          PRD_DIR=$(dirname \"$FOUND\")\n        fi\n      fi\n\n      if [ -z \"$PRD_DIR\" ] || [ ! -f \"$PRD_DIR/prd.json\" ]; then\n        echo \"ERROR: No prd.json found after generation step.\"\n        echo \"Check the generate-prd node output for errors.\"\n        exit 1\n      fi\n\n      if [ ! -f \"$PRD_DIR/prd.md\" ]; then\n        echo \"ERROR: prd.md not found in $PRD_DIR\"\n        exit 1\n      fi\n\n      # ── 2. Install dependencies (worktrees lack node_modules) ──\n      if [ -f \"bun.lock\" ] || [ -f \"bun.lockb\" ]; then\n        echo \"Installing dependencies (bun)...\"\n        bun install --frozen-lockfile 2>&1 | tail -3\n      elif [ -f \"package-lock.json\" ]; then\n        echo \"Installing dependencies (npm)...\"\n        npm ci 2>&1 | tail -3\n      elif [ -f \"yarn.lock\" ]; then\n        echo \"Installing dependencies (yarn)...\"\n        yarn install --frozen-lockfile 2>&1 | tail -3\n      elif [ -f \"pnpm-lock.yaml\" ]; then\n        echo \"Installing dependencies (pnpm)...\"\n        pnpm install --frozen-lockfile 2>&1 | tail -3\n      fi\n\n      # ── 3. Git state ──────────────────────────────────────────\n      echo \"BRANCH=$(git branch --show-current)\"\n      echo \"GIT_ROOT=$(git rev-parse --show-toplevel)\"\n\n      # ── 4. Output PRD context ─────────────────────────────────\n      echo \"PRD_DIR=$PRD_DIR\"\n      echo \"=== PRD_JSON_START ===\"\n      cat \"$PRD_DIR/prd.json\"\n      echo \"\"\n      echo \"=== PRD_JSON_END ===\"\n      echo \"=== PRD_MD_START ===\"\n      cat \"$PRD_DIR/prd.md\"\n      echo \"\"\n      echo \"=== PRD_MD_END ===\"\n      echo \"=== PROGRESS_START ===\"\n      if [ -f \"$PRD_DIR/progress.txt\" ]; then\n        cat \"$PRD_DIR/progress.txt\"\n      else\n        echo \"(no progress yet)\"\n      fi\n      echo \"\"\n      echo \"=== PROGRESS_END ===\"\n\n      # ── 5. Summary ────────────────────────────────────────────\n      TOTAL=$(grep -c '\"passes\"' \"$PRD_DIR/prd.json\" || true)\n      DONE=$(grep -c '\"passes\": true' \"$PRD_DIR/prd.json\" || true)\n      TOTAL=${TOTAL:-0}\n      DONE=${DONE:-0}\n      echo \"STORIES_TOTAL=$TOTAL\"\n      echo \"STORIES_DONE=$DONE\"\n      echo \"STORIES_REMAINING=$(( TOTAL - DONE ))\"\n\n  # ═══════════════════════════════════════════════════════════════\n  # NODE 4: RALPH IMPLEMENTATION LOOP\n  # Fresh context each iteration. Reads PRD state from disk.\n  # One story per iteration. Validates before committing.\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: implement\n    depends_on: [validate-prd]\n    idle_timeout: 600000\n    model: claude-opus-4-6[1m]\n    loop:\n      prompt: |\n        # Ralph Agent — Autonomous Story Implementation\n\n        You are an autonomous coding agent in a FRESH session — you have no memory of previous iterations.\n        Your job: Read state from disk, implement ONE story, validate, commit, update tracking, exit.\n\n        **Golden Rule**: If validation fails, fix it before committing. Never commit broken code. Never skip validation.\n\n        ---\n\n        ## Phase 0: CONTEXT — Load Project State\n\n        The upstream setup node produced this context:\n\n        $validate-prd.output\n\n        **User message**: $USER_MESSAGE\n\n        ---\n\n        ### 0.1 Parse PRD Directory\n\n        Extract the `PRD_DIR=...` line from the context above. This is the directory containing your PRD files.\n        Store this path — use it for ALL file operations below.\n\n        ### 0.2 Read Current State (from disk, not from context above)\n\n        The context above is a snapshot from before the loop started. Previous iterations may have changed files.\n        **You MUST re-read from disk to get the current state:**\n\n        1. **Read `{prd-dir}/progress.txt`** — your only link to previous iterations\n           - Check the `## Codebase Patterns` section FIRST for learnings from prior iterations\n           - Check recent entries for gotchas to avoid\n        2. **Read `{prd-dir}/prd.json`** — the source of truth for story completion state\n        3. **Read `{prd-dir}/prd.md`** — full requirements, technical patterns, acceptance criteria\n\n        ### 0.3 Read Project Rules\n\n        ```bash\n        cat CLAUDE.md\n        ```\n\n        Note all coding standards, patterns, and rules. Follow them exactly.\n\n        **PHASE_0_CHECKPOINT:**\n        - [ ] PRD directory identified\n        - [ ] progress.txt read (or noted as absent)\n        - [ ] prd.json read — know which stories pass/fail\n        - [ ] prd.md read — understand requirements\n        - [ ] CLAUDE.md rules noted\n\n        ---\n\n        ## Phase 1: SELECT — Pick Next Story\n\n        ### 1.1 Find Eligible Story\n\n        From `prd.json`, find the **highest priority** story where:\n        - `passes` is `false`\n        - ALL stories in `dependsOn` have `passes: true`\n\n        **If ALL stories have `passes: true`** → Skip to Phase 6 (Completion).\n\n        **If no eligible stories exist** (all remaining are blocked):\n        ```\n        BLOCKED: No eligible stories. Remaining stories and their blockers:\n        - {story-id}: blocked by {dep-id} (passes: false)\n        ```\n        End normally. The loop will terminate on max_iterations.\n\n        ### 1.2 Announce Selection\n\n        ```\n        ── Story Selected ──────────────────────────────────\n        ID: {story-id}\n        Title: {story-title}\n        Priority: {priority}\n        Dependencies: {deps or \"none\"}\n\n        Acceptance Criteria:\n        - {criterion 1}\n        - {criterion 2}\n        - ...\n        ────────────────────────────────────────────────────\n        ```\n\n        After announcing the selected story, emit the story started event:\n        ```bash\n        bun run cli workflow event emit --run-id $WORKFLOW_ID --type ralph_story_started --data '{\"story_id\":\"{story-id}\",\"title\":\"{story-title}\"}' || true\n        ```\n\n        **PHASE_1_CHECKPOINT:**\n        - [ ] Eligible story found (or all complete / all blocked)\n        - [ ] Acceptance criteria understood\n        - [ ] Dependencies verified as complete\n\n        ---\n\n        ## Phase 2: IMPLEMENT — Code the Story\n\n        ### 2.1 Explore Before Coding\n\n        Before writing any code:\n        1. Read all files you plan to modify — understand current state\n        2. Check `## Codebase Patterns` in progress.txt for discovered patterns\n        3. Look for similar implementations in the codebase to mirror\n        4. Read the `technicalNotes` field from the story in prd.json\n\n        ### 2.2 Implementation Rules\n\n        **DO:**\n        - Implement ONLY the selected story — one story per iteration\n        - Follow existing code patterns exactly (naming, structure, imports, error handling)\n        - Match the project's coding standards from CLAUDE.md\n        - Write or update tests as required by acceptance criteria\n        - Keep changes minimal and focused\n\n        **DON'T:**\n        - Refactor unrelated code\n        - Add improvements not in the acceptance criteria\n        - Change formatting of lines you didn't modify\n        - Install new dependencies without justification from prd.md\n        - Touch files unrelated to this story\n        - Over-engineer — do the simplest thing that satisfies the criteria\n\n        ### 2.3 Verify Types After Each File\n\n        After modifying each file, run:\n        ```bash\n        bun run type-check\n        ```\n\n        **If types fail:**\n        1. Read the error carefully\n        2. Fix the type issue in your code\n        3. Re-run type-check\n        4. Do NOT proceed to the next file until types pass\n\n        **PHASE_2_CHECKPOINT:**\n        - [ ] Only the selected story was implemented\n        - [ ] Types compile after each file change\n        - [ ] Tests written/updated as needed\n        - [ ] No unrelated changes\n\n        ---\n\n        ## Phase 3: VALIDATE — Full Verification\n\n        ### 3.1 Static Analysis\n\n        ```bash\n        bun run type-check && bun run lint\n        ```\n\n        **Must pass with zero errors and zero warnings.**\n\n        **If lint fails:**\n        1. Run `bun run lint:fix` for auto-fixable issues\n        2. Manually fix remaining issues\n        3. Re-run lint\n        4. Proceed only when clean\n\n        ### 3.2 Tests\n\n        ```bash\n        bun run test\n        ```\n\n        **All tests must pass.**\n\n        **If tests fail:**\n        1. Read the failure output\n        2. Determine: bug in your implementation or pre-existing failure?\n        3. If your bug → fix the implementation (not the test)\n        4. If pre-existing → note it but don't fix unrelated tests\n        5. Re-run tests\n        6. Repeat until green\n\n        ### 3.3 Format Check\n\n        ```bash\n        bun run format:check\n        ```\n\n        **If formatting fails:**\n        ```bash\n        bun run format\n        ```\n\n        ### 3.4 Verify Acceptance Criteria\n\n        Go through EACH acceptance criterion from the story:\n        - Is it satisfied by your implementation?\n        - Can you verify it (read the code, run a command, check a file)?\n\n        If a criterion is NOT met, go back to Phase 2 and fix it.\n\n        **PHASE_3_CHECKPOINT:**\n        - [ ] Type-check passes\n        - [ ] Lint passes (0 errors, 0 warnings)\n        - [ ] All tests pass\n        - [ ] Format is clean\n        - [ ] Every acceptance criterion verified\n\n        ---\n\n        ## Phase 4: COMMIT — Save Changes\n\n        ### 4.1 Review Staged Changes\n\n        ```bash\n        git add -A\n        git status\n        git diff --cached --stat\n        ```\n\n        Verify only expected files are staged. If unexpected files appear, investigate before committing.\n\n        ### 4.2 Write Commit Message\n\n        ```bash\n        git commit -m \"$(cat <<'EOF'\n        feat: {story-title}\n\n        Implements {story-id} from PRD.\n\n        Changes:\n        - {change 1}\n        - {change 2}\n        - {change 3}\n        EOF\n        )\"\n        ```\n\n        **Commit message rules:**\n        - Prefix: `feat:` for features, `fix:` for bugs, `refactor:` for refactors\n        - Title: the story title (not the PRD name)\n        - Body: list the actual changes made\n        - Do NOT include AI attribution\n\n        **PHASE_4_CHECKPOINT:**\n        - [ ] Only expected files committed\n        - [ ] Commit message is clear and accurate\n        - [ ] Working directory is clean after commit\n\n        ---\n\n        ## Phase 5: TRACK — Update Progress Files\n\n        ### 5.1 Update prd.json\n\n        Set `passes: true` and add a note for the completed story:\n\n        ```json\n        {\n          \"id\": \"{story-id}\",\n          \"passes\": true,\n          \"notes\": \"Implemented in iteration {N}. Files: {list}.\"\n        }\n        ```\n\n        After updating prd.json, emit the story completed event:\n        ```bash\n        bun run cli workflow event emit --run-id $WORKFLOW_ID --type ralph_story_completed --data '{\"story_id\":\"{story-id}\",\"title\":\"{story-title}\"}' || true\n        ```\n\n        ### 5.2 Update progress.txt\n\n        **Append** to `{prd-dir}/progress.txt`:\n\n        ```\n        ## {ISO Date} — {story-id}: {story-title}\n\n        **Status**: PASSED\n        **Files changed**:\n        - {file1} — {what changed}\n        - {file2} — {what changed}\n\n        **Acceptance criteria verified**:\n        - [x] {criterion 1}\n        - [x] {criterion 2}\n\n        **Learnings**:\n        - {Any pattern discovered}\n        - {Any gotcha encountered}\n        - {Any deviation from expected approach}\n\n        ---\n        ```\n\n        ### 5.3 Update Codebase Patterns (if applicable)\n\n        If you discovered a **reusable pattern** that future iterations should know about, **prepend** it to the `## Codebase Patterns` section at the TOP of progress.txt.\n\n        Format:\n        ```\n        ## Codebase Patterns\n\n        ### {Pattern Name}\n        - **Where**: `{file:lines}`\n        - **Pattern**: {description}\n        - **Example**: `{code snippet}`\n        ```\n\n        If the `## Codebase Patterns` section doesn't exist yet, create it at the top of the file.\n\n        **PHASE_5_CHECKPOINT:**\n        - [ ] prd.json updated with `passes: true`\n        - [ ] progress.txt appended with iteration details\n        - [ ] Codebase patterns updated (if applicable)\n\n        ---\n\n        ## Phase 6: COMPLETE — Check All Stories\n\n        ### 6.1 Re-read prd.json\n\n        ```bash\n        cat {prd-dir}/prd.json\n        ```\n\n        Count stories where `passes: false`.\n\n        ### 6.2 If ALL Stories Pass\n\n        1. **Push the branch:**\n           ```bash\n           git push -u origin HEAD\n           ```\n\n        2. **Read the PR template:**\n           Look for a PR template in the repo — check `.github/pull_request_template.md`, `.github/PULL_REQUEST_TEMPLATE.md`, and `docs/pull_request_template.md`. Read whichever one exists.\n\n           If a template was found, fill in **every section** using the context from this implementation. Don't skip sections or leave placeholders — fill them honestly based on the actual changes (summary, architecture, validation evidence, security, compatibility, rollback, etc.).\n\n           If no template was found, write a summary with: problem, what changed, stories table, and validation evidence.\n\n        3. **Create a draft PR** using `gh pr create --draft --base $BASE_BRANCH --title \"feat: {PRD feature name}\"` with the filled-in template as the body. Use a HEREDOC for the body.\n\n        4. **Output completion signal:**\n           ```\n           <promise>COMPLETE</promise>\n           ```\n\n        ### 6.3 If Stories Remain\n\n        Report status and end normally:\n        ```\n        ── Iteration Complete ──────────────────────────────\n        Story completed: {story-id} — {story-title}\n        Stories remaining: {count}\n        Next eligible: {next-story-id} — {next-story-title}\n        ────────────────────────────────────────────────────\n        ```\n\n        The loop engine will start the next iteration with a fresh context.\n\n        ---\n\n        ## Handling Edge Cases\n\n        ### Validation fails repeatedly\n        - If type-check or tests fail 3+ times on the same error, step back\n        - Re-read the acceptance criteria — you may be misunderstanding the requirement\n        - Check if the story is too large (needs breaking down)\n        - Note the blocker in progress.txt and end the iteration\n\n        ### Story is too large for one iteration\n        - Implement the minimum viable subset that satisfies the most critical acceptance criteria\n        - Set `passes: true` only if ALL criteria are met\n        - If you can't meet all criteria, leave `passes: false` and note what's done in progress.txt\n        - The next iteration will pick it up and continue\n\n        ### Pre-existing test failures\n        - If tests were failing BEFORE your changes, note them but don't fix unrelated code\n        - Run only the test files related to your changes if the full suite has pre-existing issues\n        - Document pre-existing failures in progress.txt\n\n        ### Dependency install fails\n        - Check if `bun.lock` or equivalent exists\n        - Try `bun install` without `--frozen-lockfile`\n        - Note the issue in progress.txt\n\n        ### Git state is dirty at iteration start\n        - This shouldn't happen (fresh worktree), but if it does:\n        - Run `git status` to understand what's dirty\n        - If it's leftover from a failed previous iteration, commit or stash\n        - Never discard changes silently\n\n        ### Blocked stories — all remaining have unmet dependencies\n        - Report the dependency chain in your output\n        - Check if a dependency was incorrectly left as `passes: false`\n        - If a dependency should be `passes: true` (the code exists and works), fix prd.json\n        - Otherwise, end the iteration — the loop will exhaust max_iterations\n\n        ---\n\n        ## File Format Reference\n\n        ### prd.json Schema\n\n        ```json\n        {\n          \"feature\": \"Feature Name\",\n          \"issueNumber\": 123,\n          \"userStories\": [\n            {\n              \"id\": \"US-001\",\n              \"title\": \"Short title\",\n              \"description\": \"As a..., I want..., so that...\",\n              \"acceptanceCriteria\": [\"criterion 1\", \"criterion 2\"],\n              \"technicalNotes\": \"Implementation hints\",\n              \"dependsOn\": [\"US-000\"],\n              \"priority\": 1,\n              \"passes\": false,\n              \"notes\": \"\"\n            }\n          ]\n        }\n        ```\n\n        ### progress.txt Format\n\n        ```\n        ## Codebase Patterns\n\n        ### {Pattern Name}\n        - Where: `file:lines`\n        - Pattern: description\n        - Example: `code`\n\n        ---\n\n        ## {Date} — {story-id}: {title}\n\n        **Status**: PASSED\n        **Files changed**: ...\n        **Acceptance criteria verified**: ...\n        **Learnings**: ...\n\n        ---\n        ```\n\n        ---\n\n        ## Success Criteria\n\n        - **ONE_STORY**: Exactly one story implemented per iteration\n        - **VALIDATED**: Type-check + lint + tests + format all pass before commit\n        - **COMMITTED**: Changes committed with clear message\n        - **TRACKED**: prd.json and progress.txt updated accurately\n        - **PATTERNS_SHARED**: Discovered patterns added to progress.txt for future iterations\n        - **NO_SCOPE_CREEP**: No unrelated changes, no refactoring, no \"improvements\"\n      until: COMPLETE\n      max_iterations: 15\n      fresh_context: true\n\n  # ═══════════════════════════════════════════════════════════════\n  # NODE 5: COMPLETION REPORT\n  # Reads final state and produces a summary.\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: report\n    depends_on: [implement]\n    prompt: |\n      # Completion Report\n\n      The Ralph implementation loop has finished. Generate a completion report.\n\n      ## Context\n\n      **Loop output (last iteration):**\n\n      $implement.output\n\n      **Setup context:**\n\n      $validate-prd.output\n\n      ---\n\n      ## Instructions\n\n      ### 1. Read Final State\n\n      Extract the `PRD_DIR=...` from the setup context above.\n      Read the CURRENT files from disk:\n\n      ```bash\n      cat {prd-dir}/prd.json\n      cat {prd-dir}/progress.txt\n      ```\n\n      ### 2. Gather Git Info\n\n      ```bash\n      git log --oneline --no-merges $(git merge-base HEAD $BASE_BRANCH)..HEAD\n      git diff --stat $(git merge-base HEAD $BASE_BRANCH)..HEAD\n      ```\n\n      ### 3. Check PR Status\n\n      ```bash\n      gh pr view HEAD --json url,number,state 2>/dev/null || echo \"No PR found\"\n      ```\n\n      ### 4. Generate Report\n\n      Output this format:\n\n      ```\n      ═══════════════════════════════════════════════════════\n      RALPH DAG — COMPLETION REPORT\n      ═══════════════════════════════════════════════════════\n\n      Feature: {feature name from prd.json}\n      PRD: {prd-dir}\n      Branch: {branch name}\n      PR: {url or \"not created\"}\n\n      ── Stories ─────────────────────────────────────────\n\n      | ID | Title | Status |\n      |----|-------|--------|\n      {for each story from prd.json}\n\n      Total: {N}/{M} stories passing\n\n      ── Commits ─────────────────────────────────────────\n\n      {git log output}\n\n      ── Files Changed ─────────────────────────────────\n\n      {git diff --stat output}\n\n      ── Patterns Discovered ─────────────────────────────\n\n      {from ## Codebase Patterns in progress.txt, or \"None\"}\n\n      ═══════════════════════════════════════════════════════\n      ```\n\n      Keep it factual. No commentary — just the data.\n",
+  "archon-refactor-safely": "name: archon-refactor-safely\ndescription: |\n  Use when: User wants to refactor code safely with continuous validation and behavior preservation.\n  Triggers: \"refactor\", \"refactor safely\", \"split this file\", \"extract module\", \"break up\",\n            \"decompose\", \"safe refactor\", \"split file\", \"extract into modules\".\n  Does: Scans refactoring scope -> analyzes impact (read-only) -> plans ordered task list ->\n        executes with type-check hooks after every edit -> validates full suite ->\n        verifies behavior preservation (read-only) -> creates PR with before/after comparison.\n  NOT for: Bug fixes (use archon-fix-github-issue), feature development (use archon-feature-development),\n           general architecture sweeps (use archon-architect), PR reviews.\n\n  Key safety features:\n  - Analysis and verification nodes are read-only (denied_tools: [Write, Edit, Bash])\n  - PreToolUse hooks check if each edit is in the plan\n  - PostToolUse hooks force type-check after every file change\n  - Behavior verification confirms no logic changes after refactoring\n\nprovider: claude\n\nnodes:\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 1: SCAN — Find files matching the refactoring target\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: scan-scope\n    bash: |\n      echo \"=== REFACTORING TARGET ===\"\n      echo \"User request: $ARGUMENTS\"\n      echo \"\"\n\n      echo \"=== FILE SIZE ANALYSIS (source files by size) ===\"\n      find . -name '*.ts' -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -name '*.test.ts' -not -name '*.d.ts' \\\n        -exec wc -l {} + 2>/dev/null | sort -rn | head -30\n      echo \"\"\n\n      echo \"=== FILES OVER 500 LINES ===\"\n      find . -name '*.ts' -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -name '*.test.ts' -not -name '*.d.ts' \\\n        -exec sh -c 'lines=$(wc -l < \"$1\"); if [ \"$lines\" -gt 500 ]; then echo \"$lines $1\"; fi' _ {} \\; 2>/dev/null | sort -rn\n      echo \"\"\n\n      echo \"=== FUNCTION COUNT PER FILE (top 20) ===\"\n      for f in $(find . -name '*.ts' -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -name '*.test.ts' -not -name '*.d.ts'); do\n        count=$(grep -cE '^\\s*(export\\s+)?(async\\s+)?function\\s|=>\\s*\\{' \"$f\" 2>/dev/null) || count=0\n        if [ \"$count\" -gt 5 ]; then\n          echo \"$count functions: $f\"\n        fi\n      done | sort -rn | head -20\n      echo \"\"\n\n      echo \"=== EXPORT ANALYSIS (files with many exports) ===\"\n      for f in $(find . -name '*.ts' -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -name '*.test.ts' -not -name '*.d.ts'); do\n        count=$(grep -c \"^export \" \"$f\" 2>/dev/null) || count=0\n        if [ \"$count\" -gt 5 ]; then\n          echo \"$count exports: $f\"\n        fi\n      done | sort -rn | head -20\n    timeout: 60000\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 2: ANALYZE IMPACT — Read-only deep analysis\n  # Maps call sites, identifies risk areas, understands dependencies\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: analyze-impact\n    prompt: |\n      You are a senior software engineer analyzing code for a safe refactoring.\n\n      ## Refactoring Request\n\n      $ARGUMENTS\n\n      ## Codebase Scan Results\n\n      $scan-scope.output\n\n      ## Instructions\n\n      1. Identify the PRIMARY file(s) targeted for refactoring based on the user's request\n         and the scan results above\n      2. Read each target file thoroughly — understand every function, type, and export\n      3. For each target file, map ALL call sites:\n         - Use Grep to find every import of the target file across the codebase\n         - Track which specific exports are used and where\n         - Note any dynamic imports or re-exports through index files\n      4. Identify risk areas:\n         - Functions with complex internal dependencies (shared closures, module-level state)\n         - Circular dependencies between functions in the file\n         - Any module-level side effects (top-level `const`, initialization code)\n         - Exports that are part of the public API vs internal-only\n      5. Check for existing tests:\n         - Find test files for the target module(s)\n         - Note what's tested and what isn't\n\n      ## Output\n\n      Write a thorough impact analysis to `$ARTIFACTS_DIR/impact-analysis.md` with:\n\n      ### Target Files\n      - File path, line count, function count\n      - List of all exported symbols with brief descriptions\n\n      ### Dependency Map\n      - Which files import from the target (with specific imports used)\n      - Which files the target imports from\n\n      ### Risk Assessment\n      - Module-level state or side effects\n      - Complex internal dependencies between functions\n      - Public API surface that must be preserved exactly\n\n      ### Test Coverage\n      - Existing test files and what they cover\n      - Critical paths that must remain tested\n\n      ### Recommended Decomposition Strategy\n      - Suggested module boundaries (which functions group together)\n      - Rationale for each grouping (cohesion, shared dependencies)\n    depends_on: [scan-scope]\n    context: fresh\n    denied_tools: [Write, Edit, Bash]\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 3: PLAN REFACTOR — Ordered task list with rollback strategy\n  # Read-only: produces the plan, does not execute it\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: plan-refactor\n    prompt: |\n      You are planning a safe refactoring. You must produce a precise, ordered plan\n      that another agent will follow literally.\n\n      ## Impact Analysis\n\n      $analyze-impact.output\n\n      ## Refactoring Goal\n\n      $ARGUMENTS\n\n      ## Principles\n\n      - **Behavior preservation**: The refactoring must NOT change any behavior — only structure\n      - **Incremental**: Each step must leave the codebase in a compilable state\n      - **Reversible**: Each step can be independently reverted\n      - **No mixed concerns**: Do not combine refactoring with bug fixes or improvements\n      - **Preserve public API**: All existing exports must remain accessible from the same import paths\n      - **Maximum file size**: Target 500 lines or fewer per file after refactoring\n\n      ## Instructions\n\n      1. Read the impact analysis from `$ARTIFACTS_DIR/impact-analysis.md`\n      2. Read the target file(s) to understand the current structure\n      3. Design the decomposition:\n         - Group related functions into cohesive modules\n         - Identify shared utilities, types, and constants\n         - Plan the new file structure with descriptive names\n      4. Write an ordered task list where each task is:\n         - Independent and leaves code compilable after completion\n         - Specific about what to extract and where\n         - Clear about import updates needed\n\n      ## Output\n\n      Write the plan to `$ARTIFACTS_DIR/refactor-plan.md` with:\n\n      ### File Structure (Before)\n      ```\n      [current structure with line counts]\n      ```\n\n      ### File Structure (After)\n      ```\n      [planned structure with estimated line counts]\n      ```\n\n      ### Ordered Tasks\n\n      For each task:\n      ```\n      ## Task N: [brief description]\n\n      **Action**: CREATE | EXTRACT | UPDATE\n      **Source**: [source file]\n      **Target**: [target file]\n      **What moves**:\n      - function functionName (lines X-Y)\n      - type TypeName (lines X-Y)\n\n      **Import updates needed**:\n      - [file]: change import from [old] to [new]\n\n      **Rollback**: [how to undo this specific step]\n      ```\n\n      ### Validation Commands\n      - Type check: `bun run type-check`\n      - Lint: `bun run lint`\n      - Tests: `bun run test`\n      - Format: `bun run format:check`\n    depends_on: [analyze-impact]\n    context: fresh\n    denied_tools: [Write, Edit, Bash]\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 4: EXECUTE REFACTOR — Implements the plan with guardrails\n  # Hooks enforce type-check after every edit and plan adherence\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: execute-refactor\n    model: claude-opus-4-6[1m]\n    prompt: |\n      You are executing a refactoring plan with strict safety guardrails.\n\n      ## Plan\n\n      Read the full plan from `$ARTIFACTS_DIR/refactor-plan.md` — follow it LITERALLY.\n\n      ## Rules\n\n      - **Follow the plan exactly** — do not add extra improvements or cleanups\n      - **One task at a time** — complete each task fully before starting the next\n      - **Type-check after every file change** — you'll be prompted to do this after each edit\n      - **Preserve all behavior** — refactoring means moving code, not changing it\n      - **Preserve the public API** — if the original file exported something, it must still be\n        importable from the same path (use re-exports in the original file if needed)\n      - **Update all import sites** — every file that imported from the original must be updated\n      - **Commit after each logical task** — one commit per plan task with a clear message\n\n      ## Process for Each Task\n\n      1. Read the plan task\n      2. Read the source file to understand current state\n      3. Create the new file (if extracting) with the functions/types being moved\n      4. Update the source file to remove the moved code and add imports from the new file\n      5. Update the original file's exports to re-export from the new module (API preservation)\n      6. Use Grep to find and update ALL import sites across the codebase\n      7. Run `bun run type-check` to verify (you'll be reminded by hooks)\n      8. Commit: `git add -A && git commit -m \"refactor: [task description]\"`\n      9. Move to next task\n\n      ## Handling Problems\n\n      - If type-check fails after a change: fix it immediately before proceeding\n      - If a task is more complex than planned: complete it anyway, note the deviation\n      - If you discover the plan missed an import site: update it and note it\n      - NEVER skip a task — complete them in order\n    depends_on: [plan-refactor]\n    context: fresh\n    hooks:\n      PreToolUse:\n        - matcher: \"Write|Edit\"\n          response:\n            hookSpecificOutput:\n              hookEventName: PreToolUse\n              additionalContext: >\n                Before modifying this file: Is this file in your refactoring plan\n                ($ARTIFACTS_DIR/refactor-plan.md)? If it's not a planned target file\n                AND not a file that imports from the target, explain why you're touching it.\n                Unplanned changes increase risk.\n      PostToolUse:\n        - matcher: \"Write|Edit\"\n          response:\n            systemMessage: >\n              You just modified a file. STOP and do these things NOW before making any\n              other changes:\n              1. Run `bun run type-check` to verify the change compiles\n              2. If type-check fails, fix the error immediately\n              3. Verify you preserved the exact same behavior — no logic changes, only structural moves\n              Only proceed to the next change after type-check passes.\n        - matcher: \"Bash\"\n          response:\n            hookSpecificOutput:\n              hookEventName: PostToolUse\n              additionalContext: >\n                Check the exit code. If type-check or any validation failed, fix the issue\n                before continuing. Do not accumulate broken state.\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 5: VALIDATE — Full test suite (bash, no AI escape hatch)\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: validate\n    bash: |\n      echo \"=== TYPE CHECK ===\"\n      bun run type-check 2>&1\n      TC_EXIT=$?\n\n      echo \"\"\n      echo \"=== LINT ===\"\n      bun run lint 2>&1\n      LINT_EXIT=$?\n\n      echo \"\"\n      echo \"=== FORMAT CHECK ===\"\n      bun run format:check 2>&1\n      FMT_EXIT=$?\n\n      echo \"\"\n      echo \"=== TESTS ===\"\n      bun run test 2>&1\n      TEST_EXIT=$?\n\n      echo \"\"\n      echo \"=== FILE SIZE CHECK ===\"\n      echo \"Files still over 500 lines:\"\n      find . -name '*.ts' -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -name '*.test.ts' -not -name '*.d.ts' \\\n        -exec sh -c 'lines=$(wc -l < \"$1\"); if [ \"$lines\" -gt 500 ]; then echo \"$lines $1\"; fi' _ {} \\; 2>/dev/null | sort -rn\n      echo \"\"\n\n      echo \"=== RESULTS ===\"\n      echo \"Type check: $([ $TC_EXIT -eq 0 ] && echo 'PASS' || echo 'FAIL')\"\n      echo \"Lint: $([ $LINT_EXIT -eq 0 ] && echo 'PASS' || echo 'FAIL')\"\n      echo \"Format: $([ $FMT_EXIT -eq 0 ] && echo 'PASS' || echo 'FAIL')\"\n      echo \"Tests: $([ $TEST_EXIT -eq 0 ] && echo 'PASS' || echo 'FAIL')\"\n\n      if [ $TC_EXIT -eq 0 ] && [ $LINT_EXIT -eq 0 ] && [ $FMT_EXIT -eq 0 ] && [ $TEST_EXIT -eq 0 ]; then\n        echo \"VALIDATION_STATUS: PASS\"\n      else\n        echo \"VALIDATION_STATUS: FAIL\"\n      fi\n    depends_on: [execute-refactor]\n    timeout: 300000\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 6: FIX VALIDATION FAILURES (if any)\n  # Only does real work if validation failed\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: fix-failures\n    prompt: |\n      Review the validation output below.\n\n      ## Validation Output\n\n      $validate.output\n\n      ## Instructions\n\n      If the output ends with \"VALIDATION_STATUS: PASS\", respond with\n      \"All checks passed — no fixes needed.\" and stop.\n\n      If there are failures:\n\n      1. Read the validation failures carefully\n      2. Fix ONLY what's broken — do not make additional improvements\n      3. If a fix requires changing behavior (not just fixing a type/lint error),\n         revert the original change instead\n      4. Run the specific failing check after each fix to confirm it passes\n      5. After all fixes, run the full validation suite: `bun run validate`\n\n      If there are files still over 500 lines, note them but do NOT attempt further\n      splitting in this node — that would require a new plan cycle.\n    depends_on: [validate]\n    context: fresh\n    hooks:\n      PostToolUse:\n        - matcher: \"Write|Edit\"\n          response:\n            systemMessage: >\n              You just made a fix. Run the specific failing validation check NOW\n              to verify your fix works. Do not batch fixes — verify each one.\n      PreToolUse:\n        - matcher: \"Write|Edit\"\n          response:\n            hookSpecificOutput:\n              hookEventName: PreToolUse\n              additionalContext: >\n                You are fixing validation failures only. Do not make any changes\n                beyond what's needed to pass the failing checks. If in doubt, revert\n                the original change that caused the failure.\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 7: VERIFY BEHAVIOR — Read-only confirmation\n  # Ensures the refactoring preserved behavior by tracing call paths\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: verify-behavior\n    prompt: |\n      You are a code reviewer verifying that a refactoring preserved exact behavior.\n      You can ONLY read files — you cannot make any changes.\n\n      ## Refactoring Plan\n\n      Read the plan from `$ARTIFACTS_DIR/refactor-plan.md` to understand what was intended.\n\n      ## Instructions\n\n      1. Use Grep and Glob to find all files in the new module locations listed in\n         the plan, then Read each one. (Note: Bash is denied in this read-only node,\n         so use Grep/Glob/Read to discover changes instead of git commands.)\n      2. For each new file created by the refactoring:\n         - Verify the extracted functions match the originals exactly (no logic changes)\n         - Check that all types and interfaces are preserved\n      3. For the original file(s):\n         - Verify re-exports exist for all symbols that were previously exported\n         - Confirm no function bodies were changed (only moved)\n      4. For all import sites updated:\n         - Verify imports resolve to the correct new locations\n         - Check that no import was missed\n      5. Verify the public API is preserved:\n         - Any code that imported from the original file should still work unchanged\n         - Re-exports in the original file should cover all moved symbols\n\n      ## Output\n\n      Write your verification report to `$ARTIFACTS_DIR/behavior-verification.md`:\n\n      ### Verdict: PASS | FAIL\n\n      ### Functions Verified\n      | Function | Original Location | New Location | Behavior Preserved |\n      |----------|------------------|--------------|-------------------|\n      | funcName | file.ts:42 | new-file.ts:10 | Yes/No |\n\n      ### Public API Check\n      - [ ] All original exports still accessible from original import path\n      - [ ] Re-exports correctly configured\n\n      ### Import Sites Updated\n      - [ ] All N import sites verified\n\n      ### Issues Found\n      [List any behavior changes detected, or \"None — refactoring is behavior-preserving\"]\n    depends_on: [fix-failures]\n    context: fresh\n    denied_tools: [Write, Edit, Bash]\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 8: CREATE PR — Detailed description with before/after\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: create-pr\n    prompt: |\n      Create a pull request for the refactoring.\n\n      ## Context\n\n      - **Refactoring goal**: $ARGUMENTS\n      - **Impact analysis**: Read `$ARTIFACTS_DIR/impact-analysis.md`\n      - **Refactoring plan**: Read `$ARTIFACTS_DIR/refactor-plan.md`\n      - **Validation**: $validate.output\n      - **Behavior verification**: Read `$ARTIFACTS_DIR/behavior-verification.md`\n\n      ## Instructions\n\n      1. Stage all changes and create a final commit if there are uncommitted changes\n      2. Push the branch: `git push -u origin HEAD`\n      3. Check if a PR already exists: `gh pr list --head $(git branch --show-current)`\n      4. Create the PR with the format below\n      5. Save the PR URL to `$ARTIFACTS_DIR/.pr-url`\n\n      ## PR Format\n\n      - **Title**: `refactor: [concise description]` (under 70 chars)\n      - **Body**:\n\n      ```markdown\n      ## Refactoring: [goal]\n\n      ### Motivation\n\n      [Why this refactoring was needed — file sizes, complexity, maintainability]\n\n      ### Before\n\n      ```\n      [Original file structure with line counts from the plan]\n      ```\n\n      ### After\n\n      ```\n      [New file structure with line counts]\n      ```\n\n      ### Changes\n\n      [For each new module: what was extracted and why it's a cohesive unit]\n\n      ### Safety\n\n      - [x] Type check passes\n      - [x] Lint passes\n      - [x] Tests pass (all existing tests still green)\n      - [x] Public API preserved (re-exports maintain backward compatibility)\n      - [x] Behavior verification passed (read-only audit confirmed no logic changes)\n      - [x] Each task committed separately for easy review/revert\n\n      ### Review Guide\n\n      Each commit represents one extraction step. Review commits individually for easiest review.\n      All commits are behavior-preserving structural moves.\n      ```\n    depends_on: [verify-behavior]\n    context: fresh\n    hooks:\n      PreToolUse:\n        - matcher: \"Write|Edit\"\n          response:\n            hookSpecificOutput:\n              hookEventName: PreToolUse\n              permissionDecision: deny\n              permissionDecisionReason: \"PR creation node — do not modify source files. Use only git and gh commands.\"\n      PostToolUse:\n        - matcher: \"Bash\"\n          response:\n            hookSpecificOutput:\n              hookEventName: PostToolUse\n              additionalContext: >\n                Verify this command succeeded. If git push or gh pr create failed,\n                read the error message carefully before retrying.\n",
+  "archon-remotion-generate": "name: archon-remotion-generate\ndescription: |\n  Use when: User wants to generate or modify a Remotion video composition using AI.\n  Triggers: \"create a video\", \"generate video\", \"remotion\", \"make an animation\",\n            \"video about\", \"animate\".\n  Does: AI writes Remotion React code -> renders preview stills -> renders full video ->\n        summarizes the output.\n  Requires: A Remotion project in the working directory (src/index.ts, src/Root.tsx).\n  Optional: Install the remotion-best-practices skill for higher quality output:\n            npx skills add remotion-dev/skills\n\nnodes:\n  # ── Layer 0: Check project structure ──────────────────────────────────\n  - id: check-project\n    bash: |\n      if [ ! -f \"src/index.ts\" ] || [ ! -f \"src/Root.tsx\" ]; then\n        echo \"ERROR: Not a Remotion project. Expected src/index.ts and src/Root.tsx.\"\n        echo \"Run 'npx create-video@latest' first, then run this workflow from that directory.\"\n        exit 1\n      fi\n      echo \"Remotion project detected.\"\n      npx remotion compositions src/index.ts 2>&1 | tail -5\n      echo \"\"\n      echo \"PROJECT_READY\"\n    timeout: 60000\n\n  # ── Layer 1: Generate composition code ────────────────────────────────\n  - id: generate\n    prompt: |\n      You are working in a Remotion video project. The project root is the current directory.\n\n      Find and read the existing composition files to understand the project structure.\n      Look in src/ for Root.tsx and any composition components.\n\n      Now create or modify the composition to match this request:\n\n      $ARGUMENTS\n\n      Rules:\n      - Use useCurrentFrame() and interpolate()/spring() for ALL animations\n      - Never use CSS transitions, Math.random(), setTimeout, or Date.now()\n      - Use AbsoluteFill for layout, Sequence for scene timing\n      - Use the <Img> component from 'remotion' (not native <img>) for images\n      - Keep dimensions 1920x1080 at 30 fps unless the user specifies otherwise\n      - Update the Zod schema and defaultProps in Root.tsx if you change props\n      - Use even numbers for width/height (required for MP4)\n      - Always clamp interpolations: extrapolateLeft: 'clamp', extrapolateRight: 'clamp'\n\n      After writing the code, read it back to verify it looks correct.\n    depends_on: [check-project]\n    skills:\n      - remotion-best-practices\n    allowed_tools:\n      - Read\n      - Write\n      - Edit\n      - Glob\n\n  # ── Layer 2: Render preview stills ────────────────────────────────────\n  - id: render-preview\n    bash: |\n      mkdir -p out\n      COMP_ID=$(npx remotion compositions src/index.ts 2>&1 | grep -E '^\\S' | head -1 | awk '{print $1}')\n      if [ -z \"$COMP_ID\" ]; then\n        echo \"RENDER_FAILED: Could not detect composition ID\"\n        exit 1\n      fi\n      echo \"Composition: $COMP_ID\"\n\n      DURATION=$(npx remotion compositions src/index.ts 2>&1 | grep -E '^\\S' | head -1 | awk '{print $4}')\n      MID_FRAME=$(( ${DURATION:-150} / 2 ))\n      LATE_FRAME=$(( ${DURATION:-150} * 3 / 4 ))\n\n      echo \"Rendering preview stills at frames 1, $MID_FRAME, $LATE_FRAME...\"\n      npx remotion still src/index.ts \"$COMP_ID\" out/preview-early.png --frame=1 2>&1 | tail -2\n      npx remotion still src/index.ts \"$COMP_ID\" out/preview-mid.png --frame=$MID_FRAME 2>&1 | tail -2\n      npx remotion still src/index.ts \"$COMP_ID\" out/preview-late.png --frame=$LATE_FRAME 2>&1 | tail -2\n      RESULT=$?\n\n      if [ $RESULT -eq 0 ]; then\n        echo \"\"\n        echo \"RENDER_SUCCESS\"\n        ls -la out/preview-*.png\n      else\n        echo \"RENDER_FAILED\"\n      fi\n    depends_on: [generate]\n    timeout: 120000\n\n  # ── Layer 3: Render full video ────────────────────────────────────────\n  - id: render-video\n    bash: |\n      COMP_ID=$(npx remotion compositions src/index.ts 2>&1 | grep -E '^\\S' | head -1 | awk '{print $1}')\n      echo \"Rendering full video: $COMP_ID\"\n      npx remotion render src/index.ts \"$COMP_ID\" out/video.mp4 --codec=h264 --crf=18 2>&1 | tail -10\n      RESULT=$?\n\n      if [ $RESULT -eq 0 ]; then\n        echo \"\"\n        echo \"VIDEO_RENDER_SUCCESS\"\n        ls -la out/video.mp4\n      else\n        echo \"VIDEO_RENDER_FAILED\"\n      fi\n    depends_on: [render-preview]\n    timeout: 300000\n\n  # ── Layer 4: Summary ──────────────────────────────────────────────────\n  - id: summary\n    prompt: |\n      A Remotion video was generated and rendered.\n\n      Original request: $ARGUMENTS\n\n      Preview render: $render-preview.output\n      Video render: $render-video.output\n\n      Read the generated composition code and the preview stills (out/preview-early.png,\n      out/preview-mid.png, out/preview-late.png) to verify the output.\n\n      Summarize:\n      1. What the video contains (based on code and stills)\n      2. Whether the renders succeeded\n      3. Where the output file is (out/video.mp4)\n    depends_on: [render-video]\n    allowed_tools:\n      - Read\n    model: haiku\n",
+  "archon-resolve-conflicts": "name: archon-resolve-conflicts\ndescription: |\n  Use when: PR has merge conflicts that need resolution.\n  Triggers: \"resolve conflicts\", \"fix merge conflicts\", \"rebase this PR\", \"resolve this\",\n            \"fix conflicts\", \"merge conflicts\", \"rebase and fix\".\n  Does: Fetches latest base branch -> analyzes conflicts -> auto-resolves simple conflicts ->\n        presents options for complex conflicts -> commits and pushes resolution.\n  NOT for: PRs without conflicts, general rebasing without conflicts, squashing commits.\n\n  This workflow helps resolve merge conflicts by analyzing the conflicting changes,\n  automatically resolving where intent is clear, and presenting options for complex conflicts.\n\nnodes:\n  - id: resolve\n    command: archon-resolve-merge-conflicts\n",
+  "archon-smart-pr-review": "name: archon-smart-pr-review\ndescription: |\n  Use when: User wants a smart, efficient PR review that adapts to PR complexity.\n  Triggers: \"smart review\", \"review this PR\", \"review PR #123\", \"efficient review\",\n            \"smart PR review\", \"quick review\".\n  Does: Gathers PR scope -> classifies complexity -> routes to only relevant review agents ->\n        synthesizes findings -> auto-fixes CRITICAL/HIGH issues.\n  NOT for: When you explicitly want ALL review agents (use archon-comprehensive-pr-review instead).\n\n  Unlike the comprehensive review, this workflow classifies the PR first and only runs\n  the review agents that are relevant. A 3-line typo fix skips test-coverage and docs-impact.\n\nnodes:\n  - id: scope\n    command: archon-pr-review-scope\n\n  - id: sync\n    command: archon-sync-pr-with-main\n    depends_on: [scope]\n\n  - id: classify\n    prompt: |\n      You are a PR complexity classifier. Analyze the PR scope below and determine\n      which review agents should run.\n\n      ## PR Scope\n      $scope.output\n\n      ## Rules\n      - **Code review**: Always run unless the diff is empty or only touches non-code files\n        (e.g. README-only, config-only, or .yaml-only changes).\n      - **Error handling**: Run if the diff touches code with try/catch, error handling,\n        async/await, or adds new failure paths.\n      - **Test coverage**: Run if the diff touches source code (not just tests, docs, or config).\n      - **Comment quality**: Run if the diff adds or modifies comments, docstrings, JSDoc,\n        or significant documentation within code files.\n      - **Docs impact**: Run if the diff adds/removes/renames public APIs, commands, CLI flags,\n        environment variables, or user-facing features.\n\n      Classify the PR complexity:\n      - **trivial**: Typo fixes, formatting, single-line changes, version bumps\n      - **small**: 1-3 files, straightforward logic, no architectural changes\n      - **medium**: 4-10 files, moderate logic changes, some cross-cutting concerns\n      - **large**: 10+ files, architectural changes, new subsystems, complex refactors\n\n      Provide your reasoning for each decision.\n    depends_on: [scope]\n    model: haiku\n    allowed_tools: []\n    output_format:\n      type: object\n      properties:\n        run_code_review:\n          type: string\n          enum: [\"true\", \"false\"]\n        run_error_handling:\n          type: string\n          enum: [\"true\", \"false\"]\n        run_test_coverage:\n          type: string\n          enum: [\"true\", \"false\"]\n        run_comment_quality:\n          type: string\n          enum: [\"true\", \"false\"]\n        run_docs_impact:\n          type: string\n          enum: [\"true\", \"false\"]\n        complexity:\n          type: string\n          enum: [\"trivial\", \"small\", \"medium\", \"large\"]\n        reasoning:\n          type: string\n      required:\n        - run_code_review\n        - run_error_handling\n        - run_test_coverage\n        - run_comment_quality\n        - run_docs_impact\n        - complexity\n        - reasoning\n\n  - id: code-review\n    command: archon-code-review-agent\n    depends_on: [classify, sync]\n    when: \"$classify.output.run_code_review == 'true'\"\n\n  - id: error-handling\n    command: archon-error-handling-agent\n    depends_on: [classify, sync]\n    when: \"$classify.output.run_error_handling == 'true'\"\n\n  - id: test-coverage\n    command: archon-test-coverage-agent\n    depends_on: [classify, sync]\n    when: \"$classify.output.run_test_coverage == 'true'\"\n\n  - id: comment-quality\n    command: archon-comment-quality-agent\n    depends_on: [classify, sync]\n    when: \"$classify.output.run_comment_quality == 'true'\"\n\n  - id: docs-impact\n    command: archon-docs-impact-agent\n    depends_on: [classify, sync]\n    when: \"$classify.output.run_docs_impact == 'true'\"\n\n  - id: synthesize\n    command: archon-synthesize-review\n    depends_on: [code-review, error-handling, test-coverage, comment-quality, docs-impact]\n    trigger_rule: one_success\n\n  - id: implement-fixes\n    command: archon-implement-review-fixes\n    depends_on: [synthesize]\n\n  # Optional: push notification when review completes.\n  # To enable, create .archon/mcp/ntfy.json — see docs/mcp-servers.md\n  - id: check-ntfy\n    bash: \"test -f .archon/mcp/ntfy.json && echo 'true' || echo 'false'\"\n    depends_on: [implement-fixes]\n\n  - id: notify\n    depends_on: [check-ntfy, synthesize, implement-fixes]\n    when: \"$check-ntfy.output == 'true'\"\n    trigger_rule: all_success\n    mcp: .archon/mcp/ntfy.json\n    allowed_tools: []\n    prompt: |\n      Send a push notification summarizing the PR review results.\n\n      Review synthesis:\n      $synthesize.output\n\n      Fix results:\n      $implement-fixes.output\n\n      Send with:\n      - title: \"PR Review Complete\"\n      - message: 1-2 sentence summary — verdict and issue count. Short enough for a lock screen.\n      - priority: 3 if ready to merge, 4 if needs fixes, 5 if critical issues remain\n",
+  "archon-test-loop-dag": "name: archon-test-loop-dag\ndescription: |\n  Use when: User explicitly says \"test-loop-dag\" or \"run test-loop-dag\".\n  IMPORTANT: This is a DAG workflow with a loop node that iterates until completion.\n  NOT for: General testing questions or debugging.\n  Does: Initializes a counter, iterates until it reaches 3, then reports completion.\n\nnodes:\n  - id: setup\n    bash: |\n      echo \"0\" > .archon/test-loop-dag-counter.txt\n      echo \"Counter initialized to 0\"\n\n  - id: loop-counter\n    depends_on: [setup]\n    loop:\n      prompt: |\n        You are testing the loop node functionality within a DAG workflow.\n\n        ## Your Task\n\n        1. Read the file `.archon/test-loop-dag-counter.txt`\n        2. Parse the current counter value\n        3. Increment it by 1\n        4. Write the new value back to the file\n        5. Report the current iteration\n\n        ## User Intent\n\n        $USER_MESSAGE\n\n        ## Completion Criteria\n\n        - If the counter reaches 3 or higher, output: <promise>COMPLETE</promise>\n        - Otherwise, just report your progress and end normally\n\n        ## Important\n\n        Be concise. Just do the task and report the counter value.\n      until: COMPLETE\n      max_iterations: 5\n      fresh_context: false\n\n  - id: report\n    depends_on: [loop-counter]\n    prompt: |\n      The loop counter test has completed. The loop node output was:\n\n      $loop-counter.output\n\n      Read `.archon/test-loop-dag-counter.txt` and confirm the final counter value.\n      Report: \"Test loop DAG completed successfully. Final counter: {value}\"\n",
+  "archon-validate-pr": "name: archon-validate-pr\ndescription: |\n  Use when: User wants a thorough PR validation that tests both main (bug present) and feature branch (bug fixed).\n  Triggers: \"validate PR\", \"validate pr #123\", \"test this PR\", \"verify PR\", \"full PR validation\",\n            \"validate pull request\", \"test PR end-to-end\".\n  Does: Fetches PR info -> finds free ports -> parallel code review (main vs feature) ->\n        E2E test on main (reproduce bug) -> E2E test on feature (verify fix) -> final verdict report.\n  NOT for: Quick code-only reviews (use archon-smart-pr-review), fixing issues, general exploration.\n\n  This workflow is designed for running in parallel — each instance finds its own free ports\n  to avoid conflicts. Produces artifacts in $ARTIFACTS_DIR/ and posts a validation report.\n\nprovider: claude\nmodel: opus\n\nnodes:\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 1: SETUP — Fetch PR info and allocate ports\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: fetch-pr\n    bash: |\n      # Extract PR number from arguments\n      PR_NUMBER=$(echo \"$ARGUMENTS\" | grep -oE '/pull/[0-9]+' | grep -oE '[0-9]+' | head -1)\n      # Fallback: extract first number if no URL path found (e.g., \"validate PR 42\")\n      if [ -z \"$PR_NUMBER\" ]; then\n        PR_NUMBER=$(echo \"$ARGUMENTS\" | grep -oE '[0-9]+' | head -1)\n      fi\n      if [ -z \"$PR_NUMBER\" ]; then\n        # Try getting PR from current branch\n        PR_NUMBER=$(gh pr view --json number -q '.number' 2>/dev/null)\n      fi\n\n      if [ -z \"$PR_NUMBER\" ]; then\n        echo \"ERROR: No PR number found in arguments: $ARGUMENTS\"\n        exit 1\n      fi\n\n      echo \"$PR_NUMBER\" > \"$ARTIFACTS_DIR/.pr-number\"\n\n      # Fetch full PR details\n      gh pr view \"$PR_NUMBER\" --json number,title,body,url,headRefName,baseRefName,files,additions,deletions,changedFiles,state,author,labels,isDraft\n\n  - id: find-ports\n    bash: |\n      # Use Bun to let the OS pick truly free ports (cross-platform: Linux, macOS, Windows)\n      BACKEND_PORT=$(bun -e \"const s = Bun.serve({port: 0, fetch: () => new Response('')}); console.log(s.port); s.stop()\")\n      FRONTEND_PORT=$(bun -e \"const s = Bun.serve({port: 0, fetch: () => new Response('')}); console.log(s.port); s.stop()\")\n\n      echo \"$BACKEND_PORT\" > \"$ARTIFACTS_DIR/.backend-port\"\n      echo \"$FRONTEND_PORT\" > \"$ARTIFACTS_DIR/.frontend-port\"\n\n      echo \"BACKEND_PORT=$BACKEND_PORT\"\n      echo \"FRONTEND_PORT=$FRONTEND_PORT\"\n\n  - id: resolve-paths\n    bash: |\n      # Resolve canonical repo path (main branch) vs worktree path (feature branch)\n      CANONICAL_REPO=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null | sed 's|/\\.git$||')\n      WORKTREE_PATH=$(pwd)\n      FEATURE_BRANCH=$(git branch --show-current)\n\n      # Get PR branch info\n      PR_NUMBER=$(cat \"$ARTIFACTS_DIR/.pr-number\")\n      PR_HEAD=$(gh pr view \"$PR_NUMBER\" --json headRefName -q '.headRefName')\n      PR_BASE=$(gh pr view \"$PR_NUMBER\" --json baseRefName -q '.baseRefName')\n\n      echo \"$CANONICAL_REPO\" > \"$ARTIFACTS_DIR/.canonical-repo\"\n      echo \"$WORKTREE_PATH\" > \"$ARTIFACTS_DIR/.worktree-path\"\n      echo \"$FEATURE_BRANCH\" > \"$ARTIFACTS_DIR/.feature-branch\"\n      echo \"$PR_HEAD\" > \"$ARTIFACTS_DIR/.pr-head\"\n      echo \"$PR_BASE\" > \"$ARTIFACTS_DIR/.pr-base\"\n\n      echo \"CANONICAL_REPO=$CANONICAL_REPO\"\n      echo \"WORKTREE_PATH=$WORKTREE_PATH\"\n      echo \"FEATURE_BRANCH=$FEATURE_BRANCH\"\n      echo \"PR_HEAD=$PR_HEAD\"\n      echo \"PR_BASE=$PR_BASE\"\n    depends_on: [fetch-pr]\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 2: CODE REVIEW — Parallel analysis of main vs feature\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: code-review-main\n    command: archon-validate-pr-code-review-main\n    depends_on: [fetch-pr, resolve-paths]\n    context: fresh\n\n  - id: code-review-feature\n    command: archon-validate-pr-code-review-feature\n    depends_on: [fetch-pr, resolve-paths, code-review-main]\n    context: fresh\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 3: E2E TESTING — Sequential (after code reviews finish)\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: classify-testability\n    prompt: |\n      You are a PR testability classifier. Determine whether this PR's changes can be\n      validated via browser E2E testing, or if it requires code-review-only validation.\n\n      ## PR Details\n\n      $fetch-pr.output\n\n      ## Rules\n\n      - **e2e_testable**: Changes affect the Web UI (components, hooks, styles, API routes\n        that serve the frontend, SSE streaming, layout, user-visible behavior). These can be\n        validated by starting Archon and using agent-browser to interact with the UI.\n      - **code_review_only**: Changes are purely backend logic, CLI-only, workflow engine,\n        database schemas, git operations, build tooling, tests, documentation, or other\n        non-UI code. No visual validation possible.\n\n      Consider: even if a change is backend, if it affects what the frontend displays\n      (e.g., API response format changes, SSE event changes), it IS e2e_testable.\n    depends_on: [fetch-pr]\n    model: haiku\n    allowed_tools: []\n    output_format:\n      type: object\n      properties:\n        testable:\n          type: string\n          enum: [\"e2e_testable\", \"code_review_only\"]\n        reasoning:\n          type: string\n        test_plan:\n          type: string\n      required: [testable, reasoning, test_plan]\n\n  - id: e2e-test-main\n    command: archon-validate-pr-e2e-main\n    depends_on: [classify-testability, find-ports, resolve-paths, code-review-main, code-review-feature]\n    when: \"$classify-testability.output.testable == 'e2e_testable'\"\n    context: fresh\n    idle_timeout: 1800000\n\n  - id: e2e-test-feature\n    command: archon-validate-pr-e2e-feature\n    depends_on: [e2e-test-main, find-ports, resolve-paths]\n    when: \"$classify-testability.output.testable == 'e2e_testable'\"\n    context: fresh\n    idle_timeout: 1800000\n\n  # ═══════════════════════════════════════════════════════════════\n  # PHASE 4: FINAL REPORT — Synthesize all findings\n  # ═══════════════════════════════════════════════════════════════\n\n  - id: cleanup-processes\n    bash: |\n      # Safety net: kill any orphaned processes from E2E testing\n      # This runs after E2E nodes complete (or timeout/fail) to prevent process accumulation\n      BACKEND_PORT=$(cat \"$ARTIFACTS_DIR/.backend-port\" 2>/dev/null | tr -d '\\n')\n      FRONTEND_PORT=$(cat \"$ARTIFACTS_DIR/.frontend-port\" 2>/dev/null | tr -d '\\n')\n\n      if [ -z \"$BACKEND_PORT\" ] || [ -z \"$FRONTEND_PORT\" ]; then\n        echo \"No port files found — skipping cleanup\"\n        exit 0\n      fi\n\n      echo \"Cleaning up ports $BACKEND_PORT and $FRONTEND_PORT...\"\n\n      # Kill by all recorded PID files\n      for pidfile in \"$ARTIFACTS_DIR\"/.e2e-*-pid; do\n        if [ -f \"$pidfile\" ]; then\n          PID=$(cat \"$pidfile\" | tr -d '\\n')\n          echo \"Killing PID $PID from $pidfile\"\n          kill \"$PID\" 2>/dev/null || taskkill //F //T //PID \"$PID\" 2>/dev/null || true\n        fi\n      done\n\n      # Kill by port (cross-platform fallback)\n      for PORT in $BACKEND_PORT $FRONTEND_PORT; do\n        fuser -k \"$PORT/tcp\" 2>/dev/null || true\n        lsof -ti:\"$PORT\" 2>/dev/null | xargs kill -9 2>/dev/null || true\n        netstat -ano 2>/dev/null | grep \":$PORT \" | grep LISTENING | awk '{print $5}' | sort -u | while read pid; do\n          taskkill //F //T //PID \"$pid\" 2>/dev/null || true\n        done\n      done\n\n      # pkill fallback: catch processes that escaped PID/port cleanup\n      pkill -f \"PORT=$BACKEND_PORT.*bun\" 2>/dev/null || true\n      pkill -f \"vite.*port.*$FRONTEND_PORT\" 2>/dev/null || true\n\n      # Close this workflow's browser session only (scoped by session ID)\n      BROWSER_SESSION=$(cat \"$ARTIFACTS_DIR/.browser-session\" 2>/dev/null | tr -d '\\n')\n      if [ -n \"$BROWSER_SESSION\" ]; then\n        agent-browser --session \"$BROWSER_SESSION\" close 2>/dev/null || true\n      fi\n\n      # Remove main E2E worktree if it still exists (safety net)\n      CANONICAL_REPO=$(cat \"$ARTIFACTS_DIR/.canonical-repo\" 2>/dev/null | tr -d '\\n')\n      MAIN_E2E_PATH=$(cat \"$ARTIFACTS_DIR/.e2e-main-worktree\" 2>/dev/null | tr -d '\\n')\n      if [ -n \"$MAIN_E2E_PATH\" ] && [ -n \"$CANONICAL_REPO\" ] && [ -d \"$MAIN_E2E_PATH\" ]; then\n        echo \"Removing leftover main E2E worktree: $MAIN_E2E_PATH\"\n        git -C \"$CANONICAL_REPO\" worktree remove \"$MAIN_E2E_PATH\" --force 2>/dev/null || rm -rf \"$MAIN_E2E_PATH\"\n      fi\n\n      sleep 1\n      echo \"Process cleanup complete\"\n    depends_on: [e2e-test-main, e2e-test-feature]\n    trigger_rule: all_done\n\n  - id: final-report\n    command: archon-validate-pr-report\n    depends_on: [code-review-main, code-review-feature, e2e-test-main, e2e-test-feature, classify-testability, cleanup-processes]\n    trigger_rule: all_done\n    context: fresh\n",
+  "archon-workflow-builder": "name: archon-workflow-builder\ndescription: |\n  Use when: User wants to create a new custom workflow for their project.\n  Triggers: \"build me a workflow\", \"create a workflow\", \"generate a workflow\",\n            \"new workflow\", \"make a workflow for\", \"workflow builder\".\n  Does: Scans codebase -> extracts intent (JSON) -> generates YAML -> validates -> saves.\n  NOT for: Editing existing workflows or creating non-workflow files.\n\nnodes:\n  - id: scan-codebase\n    bash: |\n      echo \"=== Existing Commands ===\"\n      if [ -d \".archon/commands\" ]; then\n        find .archon/commands -type f -name \"*.md\" 2>/dev/null | head -30\n      else\n        echo \"(no .archon/commands/ directory)\"\n      fi\n\n      echo \"\"\n      echo \"=== Existing Workflows ===\"\n      if [ -d \".archon/workflows\" ]; then\n        find .archon/workflows -type f \\( -name \"*.yaml\" -o -name \"*.yml\" \\) 2>/dev/null | head -30\n      else\n        echo \"(no .archon/workflows/ directory)\"\n      fi\n\n      echo \"\"\n      echo \"=== Package Info ===\"\n      if [ -f \"package.json\" ]; then\n        grep -E '\"name\"|\"scripts\"' package.json | head -10\n      else\n        echo \"(no package.json)\"\n      fi\n\n      echo \"\"\n      echo \"=== Project Context (CLAUDE.md first 50 lines) ===\"\n      if [ -f \"CLAUDE.md\" ]; then\n        head -50 CLAUDE.md\n      else\n        echo \"(no CLAUDE.md)\"\n      fi\n\n  - id: extract-intent\n    prompt: |\n      You are a workflow design classifier. Given a user's description of what they want\n      a workflow to do, extract structured intent.\n\n      ## User's Request\n      $ARGUMENTS\n\n      ## Codebase Context\n      $scan-codebase.output\n\n      ## Instructions\n\n      Analyze the user's request and the existing codebase to determine:\n      1. A kebab-case workflow name (e.g., \"lint-and-test\", \"deploy-staging\")\n      2. A description following the Archon pattern (Use when / Triggers / Does / NOT for)\n      3. Trigger phrases the router should match\n      4. A list of proposed nodes with their types and purposes\n      5. Whether this should be a simple DAG or include a loop node\n\n      Be specific and concrete. Each proposed node should have a clear type\n      (bash, prompt, command, or loop) and a one-line description of what it does.\n    model: haiku\n    allowed_tools: []\n    output_format:\n      type: object\n      properties:\n        workflow_name:\n          type: string\n        description:\n          type: string\n        trigger_phrases:\n          type: string\n        proposed_nodes:\n          type: string\n        execution_mode:\n          type: string\n          enum: [\"dag\", \"loop\"]\n      required: [workflow_name, description, trigger_phrases, proposed_nodes, execution_mode]\n    depends_on: [scan-codebase]\n\n  - id: generate-yaml\n    prompt: |\n      You are an Archon workflow author. Generate a complete, valid workflow YAML file\n      based on the structured intent provided.\n\n      ## Intent\n      - **Name**: $extract-intent.output.workflow_name\n      - **Description**: $extract-intent.output.description\n      - **Trigger Phrases**: $extract-intent.output.trigger_phrases\n      - **Proposed Nodes**: $extract-intent.output.proposed_nodes\n      - **Execution Mode**: $extract-intent.output.execution_mode\n\n      ## Original User Request\n      $ARGUMENTS\n\n      ## Archon Workflow YAML Schema Reference\n\n      A workflow YAML file has this structure:\n\n      ```yaml\n      name: workflow-name\n      description: |\n        Use when: ...\n        Triggers: ...\n        Does: ...\n        NOT for: ...\n\n      # Optional top-level settings:\n      # provider: claude    (or codex)\n      # model: sonnet       (or haiku, opus, etc.)\n      # interactive: true   (forces foreground execution in web UI)\n\n      nodes:\n        - id: node-id-kebab-case\n          # Choose ONE of: prompt, bash, command, loop\n\n          # --- prompt node (AI-executed) ---\n          prompt: |\n            Instructions for the AI...\n          # Optional: model, allowed_tools, denied_tools, output_format, context, idle_timeout\n\n          # --- bash node (shell script, no AI, stdout = $<nodeId>.output) ---\n          bash: |\n            #!/bin/bash\n            set -e\n            echo \"result\"\n\n          # --- command node (references a .archon/commands/ file) ---\n          command: command-name\n\n          # --- loop node (iterative AI execution) ---\n          loop:\n            prompt: |\n              Instructions repeated each iteration...\n            until: COMPLETION_SIGNAL\n            max_iterations: 10\n            fresh_context: true  # optional: reset context each iteration\n\n          # Common options for all node types:\n          depends_on: [other-node-id]       # DAG edges\n          when: \"$<other-node>.output == 'value'\"  # conditional execution\n          trigger_rule: all_success          # all_success | one_success | all_done\n          timeout: 120000                    # ms, for bash nodes\n      ```\n\n      ## Variable Reference\n      - `$ARGUMENTS` — user's input text\n      - `$ARTIFACTS_DIR` — pre-created directory for workflow artifacts\n      - `$<nodeId>.output` — stdout from a bash node or AI response from a prompt node\n      - `$<nodeId>.output.field` — JSON field from a node with output_format\n      - `$BASE_BRANCH` — base git branch\n\n      ## Rules\n      1. The `name:` field MUST match: $extract-intent.output.workflow_name\n      2. The `description:` MUST follow the \"Use when / Triggers / Does / NOT for\" pattern\n      3. Every node MUST have a unique kebab-case `id`\n      4. Use `depends_on` to define execution order\n      5. Use `bash` nodes for deterministic operations (file checks, git commands, installs)\n      6. Use `prompt` nodes for AI reasoning tasks\n      7. Use `output_format` on prompt nodes when downstream nodes need structured data\n      8. Use `allowed_tools: []` on classification/analysis nodes that don't need tools\n      9. Use `denied_tools: [Edit, Bash]` when a node should only use Write (not edit existing files)\n      10. Prefer `model: haiku` for simple classification tasks to save cost\n\n      ## Output\n\n      Write the complete workflow YAML to: `$ARTIFACTS_DIR/generated-workflow.yaml`\n\n      Use the Write tool. Do NOT use Edit or Bash. The file must be valid YAML and follow\n      all the patterns above.\n    denied_tools: [Edit, Bash]\n    depends_on: [extract-intent]\n\n  - id: validate-yaml\n    bash: |\n      FILE=\"$ARTIFACTS_DIR/generated-workflow.yaml\"\n\n      if [ ! -f \"$FILE\" ]; then\n        echo \"ERROR: generated-workflow.yaml not found at $FILE\"\n        exit 1\n      fi\n\n      if [ ! -s \"$FILE\" ]; then\n        echo \"ERROR: generated-workflow.yaml is empty\"\n        exit 1\n      fi\n\n      if ! grep -q \"^name:\" \"$FILE\"; then\n        echo \"ERROR: missing 'name:' field\"\n        exit 1\n      fi\n\n      if ! grep -q \"^nodes:\" \"$FILE\"; then\n        echo \"ERROR: missing 'nodes:' field\"\n        exit 1\n      fi\n\n      echo \"VALID\"\n    depends_on: [generate-yaml]\n\n  - id: save-or-report\n    prompt: |\n      You are a workflow installer. Save the generated workflow and report to the user.\n\n      ## Workflow Details\n      - **Name**: $extract-intent.output.workflow_name\n      - **Trigger Phrases**: $extract-intent.output.trigger_phrases\n\n      ## Instructions\n\n      1. Read the generated workflow from `$ARTIFACTS_DIR/generated-workflow.yaml`\n      2. Create the directory `.archon/workflows/` if it doesn't exist (use Bash: `mkdir -p .archon/workflows/`)\n      3. Save the workflow to `.archon/workflows/$extract-intent.output.workflow_name.yaml`\n         Use the Write tool to write the file.\n      4. Report to the user:\n         - Workflow name and file location\n         - Trigger phrases that will invoke it\n         - How to run it: `bun run cli workflow run $extract-intent.output.workflow_name \"your input\"`\n         - How to test it: `bun run cli validate workflows $extract-intent.output.workflow_name`\n    depends_on: [validate-yaml]\n",
+};
diff --git a/packages/workflows/src/defaults/bundled-defaults.test.ts b/packages/workflows/src/defaults/bundled-defaults.test.ts
index e1e1cb5a30..ef8887072d 100644
--- a/packages/workflows/src/defaults/bundled-defaults.test.ts
+++ b/packages/workflows/src/defaults/bundled-defaults.test.ts
@@ -1,6 +1,15 @@
 import { describe, it, expect } from 'bun:test';
+import { readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
 import { isBinaryBuild, BUNDLED_COMMANDS, BUNDLED_WORKFLOWS } from './bundled-defaults';
 
+// Resolve the on-disk defaults directories relative to this test file so the
+// tests work regardless of cwd. From packages/workflows/src/defaults go up
+// four levels to the repo root, then into .archon/.
+const REPO_ROOT = join(import.meta.dir, '..', '..', '..', '..');
+const COMMANDS_DIR = join(REPO_ROOT, '.archon/commands/defaults');
+const WORKFLOWS_DIR = join(REPO_ROOT, '.archon/workflows/defaults');
+
 describe('bundled-defaults', () => {
   describe('isBinaryBuild', () => {
     it('should return false in dev/test mode', () => {
@@ -12,54 +21,55 @@ describe('bundled-defaults', () => {
     });
   });
 
-  describe('BUNDLED_COMMANDS', () => {
-    it('should have all expected default commands', () => {
-      const expectedCommands = [
-        'archon-assist',
-        'archon-code-review-agent',
-        'archon-comment-quality-agent',
-        'archon-create-pr',
-        'archon-docs-impact-agent',
-        'archon-error-handling-agent',
-        'archon-implement-issue',
-        'archon-implement-review-fixes',
-        'archon-implement',
-        'archon-investigate-issue',
-        'archon-pr-review-scope',
-        'archon-ralph-prd',
-        'archon-resolve-merge-conflicts',
-        'archon-sync-pr-with-main',
-        'archon-synthesize-review',
-        'archon-test-coverage-agent',
-        'archon-validate-pr-code-review-feature',
-        'archon-validate-pr-code-review-main',
-        'archon-validate-pr-e2e-feature',
-        'archon-validate-pr-e2e-main',
-        'archon-validate-pr-report',
-      ];
+  describe('bundle completeness', () => {
+    // These assertions are the canary for bundle drift: if someone adds a
+    // default file without regenerating bundled-defaults.generated.ts, the
+    // bundle would be missing in compiled binaries (see #979 context). The
+    // generator is `scripts/generate-bundled-defaults.ts`, and
+    // `bun run check:bundled` verifies the generated file is up to date.
 
-      for (const cmd of expectedCommands) {
-        expect(BUNDLED_COMMANDS).toHaveProperty(cmd);
-      }
+    it('BUNDLED_COMMANDS contains every .md file in .archon/commands/defaults/', () => {
+      const onDisk = readdirSync(COMMANDS_DIR)
+        .filter(f => f.endsWith('.md'))
+        .map(f => f.slice(0, -'.md'.length))
+        .sort();
+      expect(Object.keys(BUNDLED_COMMANDS).sort()).toEqual(onDisk);
+    });
 
-      expect(Object.keys(BUNDLED_COMMANDS)).toHaveLength(21);
+    it('BUNDLED_WORKFLOWS contains every .yaml/.yml file in .archon/workflows/defaults/', () => {
+      const onDisk = readdirSync(WORKFLOWS_DIR)
+        .filter(f => f.endsWith('.yaml') || f.endsWith('.yml'))
+        .map(f => f.replace(/\.ya?ml$/, ''))
+        .sort();
+      expect(Object.keys(BUNDLED_WORKFLOWS).sort()).toEqual(onDisk);
     });
 
-    it('should have non-empty content for all commands', () => {
+    it('bundled content matches on-disk file content (defense against generator corruption)', () => {
+      // Bundled content is LF-normalized by the generator so it stays identical
+      // regardless of the checkout's line-ending policy. Match that here.
+      const readLF = (path: string): string => readFileSync(path, 'utf-8').replace(/\r\n/g, '\n');
+
       for (const [name, content] of Object.entries(BUNDLED_COMMANDS)) {
-        expect(content).toBeDefined();
-        expect(typeof content).toBe('string');
-        expect(content.length).toBeGreaterThan(0);
-        // Commands should have meaningful content (at least some markdown)
-        expect(content.length).toBeGreaterThan(50);
+        const diskContent = readLF(join(COMMANDS_DIR, `${name}.md`));
+        expect(content).toBe(diskContent);
+      }
+      for (const [name, content] of Object.entries(BUNDLED_WORKFLOWS)) {
+        // Workflows may be .yaml or .yml — prefer .yaml, fall back.
+        let diskContent: string;
+        try {
+          diskContent = readLF(join(WORKFLOWS_DIR, `${name}.yaml`));
+        } catch {
+          diskContent = readLF(join(WORKFLOWS_DIR, `${name}.yml`));
+        }
+        expect(content).toBe(diskContent);
       }
     });
+  });
 
-    it('should have markdown content format', () => {
-      // Commands are markdown files, should have typical markdown patterns
-      for (const [name, content] of Object.entries(BUNDLED_COMMANDS)) {
-        // Should contain some text (not just whitespace)
-        expect(content.trim().length).toBeGreaterThan(0);
+  describe('BUNDLED_COMMANDS', () => {
+    it('every command has meaningful content (>50 chars)', () => {
+      for (const content of Object.values(BUNDLED_COMMANDS)) {
+        expect(content.length).toBeGreaterThan(50);
       }
     });
 
@@ -76,36 +86,8 @@ describe('bundled-defaults', () => {
   });
 
   describe('BUNDLED_WORKFLOWS', () => {
-    it('should have all expected default workflows', () => {
-      const expectedWorkflows = [
-        'archon-assist',
-        'archon-comprehensive-pr-review',
-        'archon-create-issue',
-        'archon-feature-development',
-        'archon-fix-github-issue',
-        'archon-resolve-conflicts',
-        'archon-smart-pr-review',
-        'archon-validate-pr',
-        'archon-remotion-generate',
-        'archon-interactive-prd',
-        'archon-piv-loop',
-        'archon-adversarial-dev',
-        'archon-workflow-builder',
-      ];
-
-      for (const wf of expectedWorkflows) {
-        expect(BUNDLED_WORKFLOWS).toHaveProperty(wf);
-      }
-
-      expect(Object.keys(BUNDLED_WORKFLOWS)).toHaveLength(13);
-    });
-
-    it('should have non-empty content for all workflows', () => {
-      for (const [name, content] of Object.entries(BUNDLED_WORKFLOWS)) {
-        expect(content).toBeDefined();
-        expect(typeof content).toBe('string');
-        expect(content.length).toBeGreaterThan(0);
-        // Workflows should have meaningful YAML content
+    it('every workflow has meaningful content (>50 chars)', () => {
+      for (const content of Object.values(BUNDLED_WORKFLOWS)) {
         expect(content.length).toBeGreaterThan(50);
       }
     });
@@ -119,16 +101,20 @@ describe('bundled-defaults', () => {
       expect(content).toContain('workflow_name');
     });
 
+    it('archon-adversarial-dev init-workspace should avoid non-portable sed -i', () => {
+      const content = BUNDLED_WORKFLOWS['archon-adversarial-dev'];
+      expect(content).toContain('STATE_TMP="$ARTIFACTS/state.json.tmp"');
+      expect(content).toContain(
+        'sed "s/SPRINT_COUNT_PLACEHOLDER/$SPRINT_COUNT/" "$ARTIFACTS/state.json" > "$STATE_TMP"'
+      );
+      expect(content).not.toContain('sed -i "s/SPRINT_COUNT_PLACEHOLDER/$SPRINT_COUNT/"');
+    });
+
     it('should have valid YAML structure', () => {
-      // Workflows are YAML files, should parse without error
-      for (const [name, content] of Object.entries(BUNDLED_WORKFLOWS)) {
-        // Should contain 'name:' as all workflows require a name field
+      for (const content of Object.values(BUNDLED_WORKFLOWS)) {
         expect(content).toContain('name:');
-        // Should contain 'description:' as all workflows require description
         expect(content).toContain('description:');
-        // Should contain nodes: (with optional loop: inside nodes)
-        const hasNodes = content.includes('nodes:');
-        expect(hasNodes).toBe(true);
+        expect(content.includes('nodes:')).toBe(true);
       }
     });
   });
diff --git a/packages/workflows/src/defaults/bundled-defaults.ts b/packages/workflows/src/defaults/bundled-defaults.ts
index a921171b9e..bbfcfae7a6 100644
--- a/packages/workflows/src/defaults/bundled-defaults.ts
+++ b/packages/workflows/src/defaults/bundled-defaults.ts
@@ -1,108 +1,28 @@
 /**
- * Bundled default commands and workflows for binary distribution
+ * Bundled default commands and workflows for binary distribution.
  *
- * These static imports are resolved at compile time and embedded into the binary.
- * When running as a standalone binary (without Bun), these provide the default
- * commands and workflows without needing filesystem access to the source repo.
+ * Content lives in `bundled-defaults.generated.ts`, which is regenerated from
+ * `.archon/{commands,workflows}/defaults/` by `scripts/generate-bundled-defaults.ts`.
+ * This file is the hand-written facade: it re-exports the records and defines
+ * the binary-detection helper.
  *
- * Import syntax uses `with { type: 'text' }` to import file contents as strings.
+ * Why two files:
+ *   - Generated file is pure data — never hand-edited, diff on PRs shows
+ *     exactly which defaults changed.
+ *   - Facade keeps the documented `isBinaryBuild()` wrapper in a file that
+ *     humans own.
+ *
+ * Why inline strings (and not `import X from '...file.md' with { type: 'text' }`)?
+ *   - Node cannot load `type: 'text'` import attributes — it's Bun-specific.
+ *     Using plain string literals keeps `@archon/workflows` importable from
+ *     both runtimes, which removes SDK blocker #2.
+ *   - Bun still embeds the data at compile time when building the CLI binary,
+ *     so runtime behavior is unchanged.
  */
 
 import { BUNDLED_IS_BINARY } from '@archon/paths';
 
-// =============================================================================
-// Default Commands (21 total)
-// =============================================================================
-
-import archonAssistCmd from '../../../../.archon/commands/defaults/archon-assist.md' with { type: 'text' };
-import archonCodeReviewAgentCmd from '../../../../.archon/commands/defaults/archon-code-review-agent.md' with { type: 'text' };
-import archonCommentQualityAgentCmd from '../../../../.archon/commands/defaults/archon-comment-quality-agent.md' with { type: 'text' };
-import archonCreatePrCmd from '../../../../.archon/commands/defaults/archon-create-pr.md' with { type: 'text' };
-import archonDocsImpactAgentCmd from '../../../../.archon/commands/defaults/archon-docs-impact-agent.md' with { type: 'text' };
-import archonErrorHandlingAgentCmd from '../../../../.archon/commands/defaults/archon-error-handling-agent.md' with { type: 'text' };
-import archonImplementIssueCmd from '../../../../.archon/commands/defaults/archon-implement-issue.md' with { type: 'text' };
-import archonImplementReviewFixesCmd from '../../../../.archon/commands/defaults/archon-implement-review-fixes.md' with { type: 'text' };
-import archonImplementCmd from '../../../../.archon/commands/defaults/archon-implement.md' with { type: 'text' };
-import archonInvestigateIssueCmd from '../../../../.archon/commands/defaults/archon-investigate-issue.md' with { type: 'text' };
-import archonPrReviewScopeCmd from '../../../../.archon/commands/defaults/archon-pr-review-scope.md' with { type: 'text' };
-import archonRalphPrdCmd from '../../../../.archon/commands/defaults/archon-ralph-prd.md' with { type: 'text' };
-import archonResolveMergeConflictsCmd from '../../../../.archon/commands/defaults/archon-resolve-merge-conflicts.md' with { type: 'text' };
-import archonSyncPrWithMainCmd from '../../../../.archon/commands/defaults/archon-sync-pr-with-main.md' with { type: 'text' };
-import archonSynthesizeReviewCmd from '../../../../.archon/commands/defaults/archon-synthesize-review.md' with { type: 'text' };
-import archonTestCoverageAgentCmd from '../../../../.archon/commands/defaults/archon-test-coverage-agent.md' with { type: 'text' };
-import archonValidatePrCodeReviewFeatureCmd from '../../../../.archon/commands/defaults/archon-validate-pr-code-review-feature.md' with { type: 'text' };
-import archonValidatePrCodeReviewMainCmd from '../../../../.archon/commands/defaults/archon-validate-pr-code-review-main.md' with { type: 'text' };
-import archonValidatePrE2eFeatureCmd from '../../../../.archon/commands/defaults/archon-validate-pr-e2e-feature.md' with { type: 'text' };
-import archonValidatePrE2eMainCmd from '../../../../.archon/commands/defaults/archon-validate-pr-e2e-main.md' with { type: 'text' };
-import archonValidatePrReportCmd from '../../../../.archon/commands/defaults/archon-validate-pr-report.md' with { type: 'text' };
-
-// =============================================================================
-// Default Workflows (13 total)
-// =============================================================================
-
-import archonAssistWf from '../../../../.archon/workflows/defaults/archon-assist.yaml' with { type: 'text' };
-import archonComprehensivePrReviewWf from '../../../../.archon/workflows/defaults/archon-comprehensive-pr-review.yaml' with { type: 'text' };
-import archonCreateIssueWf from '../../../../.archon/workflows/defaults/archon-create-issue.yaml' with { type: 'text' };
-import archonFeatureDevelopmentWf from '../../../../.archon/workflows/defaults/archon-feature-development.yaml' with { type: 'text' };
-import archonFixGithubIssueWf from '../../../../.archon/workflows/defaults/archon-fix-github-issue.yaml' with { type: 'text' };
-import archonResolveConflictsWf from '../../../../.archon/workflows/defaults/archon-resolve-conflicts.yaml' with { type: 'text' };
-import archonSmartPrReviewWf from '../../../../.archon/workflows/defaults/archon-smart-pr-review.yaml' with { type: 'text' };
-import archonValidatePrWf from '../../../../.archon/workflows/defaults/archon-validate-pr.yaml' with { type: 'text' };
-import archonRemotionGenerateWf from '../../../../.archon/workflows/defaults/archon-remotion-generate.yaml' with { type: 'text' };
-import archonInteractivePrdWf from '../../../../.archon/workflows/defaults/archon-interactive-prd.yaml' with { type: 'text' };
-import archonPivLoopWf from '../../../../.archon/workflows/defaults/archon-piv-loop.yaml' with { type: 'text' };
-import archonAdversarialDevWf from '../../../../.archon/workflows/defaults/archon-adversarial-dev.yaml' with { type: 'text' };
-import archonWorkflowBuilderWf from '../../../../.archon/workflows/defaults/archon-workflow-builder.yaml' with { type: 'text' };
-
-// =============================================================================
-// Exports
-// =============================================================================
-
-/**
- * Bundled default commands - filename (without extension) -> content
- */
-export const BUNDLED_COMMANDS: Record<string, string> = {
-  'archon-assist': archonAssistCmd,
-  'archon-code-review-agent': archonCodeReviewAgentCmd,
-  'archon-comment-quality-agent': archonCommentQualityAgentCmd,
-  'archon-create-pr': archonCreatePrCmd,
-  'archon-docs-impact-agent': archonDocsImpactAgentCmd,
-  'archon-error-handling-agent': archonErrorHandlingAgentCmd,
-  'archon-implement-issue': archonImplementIssueCmd,
-  'archon-implement-review-fixes': archonImplementReviewFixesCmd,
-  'archon-implement': archonImplementCmd,
-  'archon-investigate-issue': archonInvestigateIssueCmd,
-  'archon-pr-review-scope': archonPrReviewScopeCmd,
-  'archon-ralph-prd': archonRalphPrdCmd,
-  'archon-resolve-merge-conflicts': archonResolveMergeConflictsCmd,
-  'archon-sync-pr-with-main': archonSyncPrWithMainCmd,
-  'archon-synthesize-review': archonSynthesizeReviewCmd,
-  'archon-test-coverage-agent': archonTestCoverageAgentCmd,
-  'archon-validate-pr-code-review-feature': archonValidatePrCodeReviewFeatureCmd,
-  'archon-validate-pr-code-review-main': archonValidatePrCodeReviewMainCmd,
-  'archon-validate-pr-e2e-feature': archonValidatePrE2eFeatureCmd,
-  'archon-validate-pr-e2e-main': archonValidatePrE2eMainCmd,
-  'archon-validate-pr-report': archonValidatePrReportCmd,
-};
-
-/**
- * Bundled default workflows - filename (without extension) -> content
- */
-export const BUNDLED_WORKFLOWS: Record<string, string> = {
-  'archon-assist': archonAssistWf,
-  'archon-comprehensive-pr-review': archonComprehensivePrReviewWf,
-  'archon-create-issue': archonCreateIssueWf,
-  'archon-feature-development': archonFeatureDevelopmentWf,
-  'archon-fix-github-issue': archonFixGithubIssueWf,
-  'archon-resolve-conflicts': archonResolveConflictsWf,
-  'archon-smart-pr-review': archonSmartPrReviewWf,
-  'archon-validate-pr': archonValidatePrWf,
-  'archon-remotion-generate': archonRemotionGenerateWf,
-  'archon-interactive-prd': archonInteractivePrdWf,
-  'archon-piv-loop': archonPivLoopWf,
-  'archon-adversarial-dev': archonAdversarialDevWf,
-  'archon-workflow-builder': archonWorkflowBuilderWf,
-};
+export { BUNDLED_COMMANDS, BUNDLED_WORKFLOWS } from './bundled-defaults.generated';
 
 /**
  * Check if the current process is running as a compiled binary (not via Bun CLI).
@@ -115,7 +35,7 @@ export const BUNDLED_WORKFLOWS: Record<string, string> = {
  * so tests can use `spyOn(bundledDefaults, 'isBinaryBuild').mockReturnValue(...)`
  * without resorting to `mock.module('@archon/paths', ...)` — which is
  * process-global and irreversible in Bun and would pollute other test files.
- * See `.claude/rules/dx-quirks.md` and `loader.test.ts` for context.
+ * See `loader.test.ts` for context.
  */
 export function isBinaryBuild(): boolean {
   return BUNDLED_IS_BINARY;
diff --git a/packages/workflows/src/deps.ts b/packages/workflows/src/deps.ts
index ce586a177b..e8fccfca41 100644
--- a/packages/workflows/src/deps.ts
+++ b/packages/workflows/src/deps.ts
@@ -3,50 +3,39 @@
  *
  * Defines narrow interfaces for what the workflow engine needs from external systems.
  * Callers in @archon/core satisfy these structurally — no adapter wrappers needed.
+ *
+ * Provider types are imported directly from @archon/providers/types (contract layer).
+ * No more mirror copies — single source of truth for IAgentProvider, MessageChunk, etc.
  */
 import type { IWorkflowStore } from './store';
+import type { ModelReasoningEffort, WebSearchMode } from './schemas';
 import type {
-  ModelReasoningEffort,
-  WebSearchMode,
-  EffortLevel,
-  ThinkingConfig,
-  SandboxSettings,
-} from './schemas';
+  IAgentProvider,
+  MessageChunk,
+  TokenUsage,
+  SendQueryOptions,
+  NodeConfig,
+  ProviderDefaultsMap,
+  ProviderCapabilities,
+} from '@archon/providers/types';
 
-// ---------------------------------------------------------------------------
-// Workflow-local type copies — structurally identical to the originals in
-// @archon/core/types, but duplicated here to avoid a circular dependency
-// (@archon/workflows must not depend on @archon/core).
-// Keep these in sync with their counterparts if the originals change.
-// ---------------------------------------------------------------------------
+// Re-export provider types so existing workflow engine consumers don't break
+export type {
+  IAgentProvider,
+  MessageChunk,
+  TokenUsage,
+  SendQueryOptions,
+  NodeConfig,
+  ProviderDefaultsMap,
+  ProviderCapabilities,
+};
 
-export interface WorkflowTokenUsage {
-  input: number;
-  output: number;
-  total?: number;
-  cost?: number;
-}
+// Backwards compat alias — deprecated, prefer direct import from @archon/providers/types
+export type WorkflowTokenUsage = TokenUsage;
 
-export type WorkflowMessageChunk =
-  | { type: 'assistant'; content: string }
-  | { type: 'system'; content: string }
-  | { type: 'thinking'; content: string }
-  | {
-      type: 'result';
-      sessionId?: string;
-      tokens?: WorkflowTokenUsage;
-      structuredOutput?: unknown;
-      isError?: boolean;
-      errorSubtype?: string;
-      cost?: number;
-      stopReason?: string;
-      numTurns?: number;
-      modelUsage?: Record<string, unknown>;
-    }
-  | { type: 'rate_limit'; rateLimitInfo: Record<string, unknown> }
-  | { type: 'tool'; toolName: string; toolInput?: Record<string, unknown> }
-  | { type: 'tool_result'; toolName: string; toolOutput: string }
-  | { type: 'workflow_dispatch'; workerConversationId: string; workflowName: string };
+// ---------------------------------------------------------------------------
+// Platform-specific types (NOT mirrors — unique to workflow engine)
+// ---------------------------------------------------------------------------
 
 export interface WorkflowMessageMetadata {
   category?:
@@ -60,144 +49,8 @@ export interface WorkflowMessageMetadata {
   workflowResult?: { workflowName: string; runId: string };
 }
 
-export interface WorkflowAssistantOptions {
-  model?: string;
-  modelReasoningEffort?: ModelReasoningEffort;
-  webSearchMode?: WebSearchMode;
-  additionalDirectories?: string[];
-  /**
-   * Controls which CLAUDE.md files the SDK loads.
-   * Mirrors Claude Agent SDK Options.settingSources.
-   * Claude only — ignored for Codex.
-   */
-  settingSources?: ('project' | 'user')[];
-  tools?: string[];
-  disallowedTools?: string[];
-  outputFormat?: { type: 'json_schema'; schema: Record<string, unknown> };
-  /**
-   * SDK hooks callbacks. Structural match for Partial<Record<HookEvent, HookCallbackMatcher[]>>.
-   * Inline type avoids @archon/workflows depending on @anthropic-ai/claude-agent-sdk.
-   * Claude only — ignored for Codex.
-   */
-  hooks?: Partial<
-    Record<
-      string,
-      {
-        matcher?: string;
-        hooks: ((
-          input: unknown,
-          toolUseID: string | undefined,
-          options: { signal: AbortSignal }
-        ) => Promise<unknown>)[];
-        timeout?: number;
-      }[]
-    >
-  >;
-  /**
-   * MCP server configuration. Structural match for Record<string, McpServerConfig>.
-   * Discriminated union mirrors the SDK types so that WorkflowAssistantOptions is
-   * assignable to AssistantRequestOptions without casts.
-   * @archon/workflows must not depend on @anthropic-ai/claude-agent-sdk.
-   * Claude only — ignored for Codex.
-   */
-  mcpServers?: Record<
-    string,
-    | { type?: 'stdio'; command: string; args?: string[]; env?: Record<string, string> }
-    | { type: 'sse'; url: string; headers?: Record<string, string> }
-    | { type: 'http'; url: string; headers?: Record<string, string> }
-  >;
-  /**
-   * Tools to auto-allow without permission prompts.
-   * Used for MCP tool wildcards (e.g., 'mcp__github__*').
-   * Claude only — ignored for Codex.
-   */
-  allowedTools?: string[];
-  /**
-   * Custom subagent definitions. Structural match for Record<string, AgentDefinition>.
-   * Used when a DAG node has skills — the node is wrapped in an AgentDefinition.
-   * @archon/workflows must not depend on @anthropic-ai/claude-agent-sdk.
-   * Claude only — ignored for Codex.
-   */
-  agents?: Record<
-    string,
-    {
-      description: string;
-      prompt: string;
-      tools?: string[];
-      model?: string;
-      skills?: string[];
-    }
-  >;
-  /**
-   * Name of the agent definition to use for the main thread.
-   * References a key in `agents`. Claude only.
-   */
-  agent?: string;
-  /**
-   * Additional env vars to merge into the Claude subprocess environment.
-   * Merged after buildSubprocessEnv() (auth tokens conditionally filtered): { ...buildSubprocessEnv(), ...env }.
-   * Claude only — ignored for Codex (Codex SDK does not expose env injection).
-   */
-  env?: Record<string, string>;
-  abortSignal?: AbortSignal;
-  /**
-   * When false (default), skips writing session transcript to ~/.claude/projects/.
-   * Claude Agent SDK v0.2.74+. The SDK default is true, but Archon overrides it to false
-   * to avoid disk pollution. Set to true only when session persistence is explicitly needed.
-   */
-  persistSession?: boolean;
-  /**
-   * When true, the SDK copies the prior session's history into a new session file
-   * before appending, leaving the original untouched. Use with `resume` to safely
-   * preserve conversation context without risk of corrupting the source session.
-   * Claude only — ignored for Codex.
-   */
-  forkSession?: boolean;
-  /**
-   * Controls reasoning depth for Claude. Claude only — ignored for Codex.
-   * Maps to SDK Options.effort.
-   */
-  effort?: EffortLevel;
-  /**
-   * Controls Claude's thinking/reasoning behavior. Claude only — ignored for Codex.
-   * Maps to SDK Options.thinking (ThinkingConfig).
-   * String shorthand is resolved at the schema level before reaching here.
-   */
-  thinking?: ThinkingConfig;
-  /**
-   * Maximum USD cost for this node. SDK returns error_max_budget_usd if exceeded.
-   * Claude only — ignored for Codex.
-   */
-  maxBudgetUsd?: number;
-  /**
-   * Per-node system prompt override. Replaces the default claude_code preset.
-   * Claude only — ignored for Codex.
-   */
-  systemPrompt?: string;
-  /**
-   * Fallback model if primary model fails. Claude only — ignored for Codex.
-   */
-  fallbackModel?: string;
-  /**
-   * SDK beta features to enable (e.g., 'context-1m-2025-08-07').
-   * Claude only — ignored for Codex.
-   */
-  betas?: string[];
-  /**
-   * OS-level sandbox restrictions for the Claude subprocess.
-   * Layers on top of worktree isolation — NOT a replacement for it.
-   * Claude only — ignored for Codex.
-   * Structural match for SDK SandboxSettings.
-   */
-  sandbox?: SandboxSettings;
-}
-
 // ---------------------------------------------------------------------------
 // Narrow platform interface (subset of IPlatformAdapter)
-//
-// Intentionally excludes ensureThread(), start(), and stop() — the workflow
-// engine operates within an already-established conversation context and
-// never manages platform lifecycle or threading itself.
 // ---------------------------------------------------------------------------
 
 export interface IWorkflowPlatform {
@@ -208,53 +61,32 @@ export interface IWorkflowPlatform {
   ): Promise<void>;
   getStreamingMode(): 'stream' | 'batch';
   getPlatformType(): string;
-  sendStructuredEvent?(conversationId: string, event: WorkflowMessageChunk): Promise<void>;
+  sendStructuredEvent?(conversationId: string, event: MessageChunk): Promise<void>;
   emitRetract?(conversationId: string): Promise<void>;
 }
 
-// ---------------------------------------------------------------------------
-// Narrow assistant client interface (subset of IAssistantClient)
-// ---------------------------------------------------------------------------
-
-export interface IWorkflowAssistantClient {
-  sendQuery(
-    prompt: string,
-    cwd: string,
-    resumeSessionId?: string,
-    options?: WorkflowAssistantOptions
-  ): AsyncGenerator<WorkflowMessageChunk>;
-  getType(): string;
-}
-
-export type AssistantClientFactory = (provider: 'claude' | 'codex') => IWorkflowAssistantClient;
-
 // ---------------------------------------------------------------------------
 // Narrow config interface (subset of MergedConfig)
-//
-// Only includes fields the workflow engine actually reads. Platform-level
-// concerns (streaming modes, concurrency, botName, paths, copyDefaults) are
-// deliberately excluded — those are @archon/core's responsibility.
 // ---------------------------------------------------------------------------
 
 export interface WorkflowConfig {
-  /** Default assistant provider ('claude' | 'codex') */
-  assistant: 'claude' | 'codex';
+  /** Default assistant provider (validated against provider registry at runtime) */
+  assistant: string;
   baseBranch?: string;
   docsPath?: string;
-  /**
-   * Merged per-project env vars (config file + DB). Injected into Options.env on Claude SDK calls.
-   * Populated by executeWorkflow — loadConfig returns file-based vars; DB vars merged on top after.
-   */
   envVars?: Record<string, string>;
   commands: { folder?: string };
   defaults?: {
     loadDefaultWorkflows?: boolean;
     loadDefaultCommands?: boolean;
   };
-  assistants: {
+  // Intersection: generic map for community providers + typed built-in entries.
+  // Built-ins are typed so executor/dag-executor get type-safe config access for
+  // Claude settingSources, Codex reasoningEffort, etc. without casts.
+  // Community providers use the generic [string] index signature.
+  assistants: ProviderDefaultsMap & {
     claude: {
       model?: string;
-      /** Controls which CLAUDE.md files are loaded by the SDK. Claude only. */
       settingSources?: ('project' | 'user')[];
     };
     codex: {
@@ -266,12 +98,18 @@ export interface WorkflowConfig {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Agent provider factory type
+// ---------------------------------------------------------------------------
+
+export type AgentProviderFactory = (provider: string) => IAgentProvider;
+
 // ---------------------------------------------------------------------------
 // WorkflowDeps — the single injection point
 // ---------------------------------------------------------------------------
 
 export interface WorkflowDeps {
   store: IWorkflowStore;
-  getAssistantClient: AssistantClientFactory;
+  getAgentProvider: AgentProviderFactory;
   loadConfig: (cwd: string) => Promise<WorkflowConfig>;
 }
diff --git a/packages/workflows/src/executor-preamble.test.ts b/packages/workflows/src/executor-preamble.test.ts
index fd2b44ec3b..4739770940 100644
--- a/packages/workflows/src/executor-preamble.test.ts
+++ b/packages/workflows/src/executor-preamble.test.ts
@@ -114,7 +114,7 @@ function makeDeps(store?: IWorkflowStore): WorkflowDeps {
         commands: { folder: '' },
       })
     ),
-    createAssistantClient: mock(() => ({
+    getAgentProvider: mock(() => ({
       run: mock(async () => {}),
     })),
   } as unknown as WorkflowDeps;
@@ -177,8 +177,10 @@ describe('executeWorkflow preamble', () => {
         started_at: recentTime,
         status: 'running',
       });
+      const updateSpy = mock(async () => {});
       const store = makeStore({
         getActiveWorkflowRunByPath: mock(async () => activeRun),
+        updateWorkflowRun: updateSpy,
       });
       const deps = makeDeps(store);
       const platform = makePlatform();
@@ -194,14 +196,25 @@ describe('executeWorkflow preamble', () => {
       );
 
       expect(result.success).toBe(false);
-      expect(result.error).toContain('already running');
-
-      // Rejection message was sent
-      const blockMsg = findMessage(platform, 'Workflow already running');
-      expect(blockMsg).toBeDefined();
-
-      // No new workflow was created
-      expect((store.createWorkflowRun as ReturnType<typeof mock>).mock.calls.length).toBe(0);
+      expect(result.error).toContain('already active');
+
+      // Actionable rejection message was sent (mentions worktree-in-use,
+      // workflow name, and concrete next-action commands)
+      const blockCall = findMessage(platform, 'in use');
+      expect(blockCall).toBeDefined();
+      const blockMsg = blockCall?.[1] as string;
+      expect(blockMsg).toContain('active-workflow');
+      expect(blockMsg).toContain('/workflow cancel');
+
+      // The guard now runs AFTER the row is created (so it always has a
+      // self-ID to exclude). On guard fire, the just-created row is marked
+      // cancelled — preventing zombie pending rows that would block future
+      // dispatches.
+      expect((store.createWorkflowRun as ReturnType<typeof mock>).mock.calls.length).toBe(1);
+      const cancelCall = updateSpy.mock.calls.find(
+        (call: unknown[]) => (call[1] as { status?: string })?.status === 'cancelled'
+      );
+      expect(cancelCall).toBeDefined();
     });
   });
 
@@ -278,8 +291,10 @@ describe('executeWorkflow preamble', () => {
       expect(result.success).toBe(false);
       expect(result.error).toContain('Database error');
 
-      // No new workflow was created
-      expect((store.createWorkflowRun as ReturnType<typeof mock>).mock.calls.length).toBe(0);
+      // The row is created BEFORE the guard runs (so the guard can exclude
+      // self). When the lock query throws, we abort early — the just-created
+      // row stays as 'pending' and falls out via the 5-min stale window.
+      expect((store.createWorkflowRun as ReturnType<typeof mock>).mock.calls.length).toBe(1);
 
       // Error message was sent
       const errorMsg =
diff --git a/packages/workflows/src/executor-shared.test.ts b/packages/workflows/src/executor-shared.test.ts
index 84346f131e..17c93cc605 100644
--- a/packages/workflows/src/executor-shared.test.ts
+++ b/packages/workflows/src/executor-shared.test.ts
@@ -22,6 +22,8 @@ import {
   substituteWorkflowVariables,
   buildPromptWithContext,
   detectCreditExhaustion,
+  detectCompletionSignal,
+  stripCompletionTags,
   isInlineScript,
 } from './executor-shared';
 
@@ -167,6 +169,50 @@ describe('substituteWorkflowVariables', () => {
     expect(prompt).toBe('Issue: context-data. External: context-data');
   });
 
+  it('does not treat context variables as prefixes of longer identifiers', () => {
+    const { prompt, contextSubstituted } = substituteWorkflowVariables(
+      'Context: $CONTEXT. File: $CONTEXT_FILE. External path: $EXTERNAL_CONTEXT_PATH. IssueId: $ISSUE_CONTEXT_ID',
+      'run-1',
+      'msg',
+      '/tmp',
+      'main',
+      'docs/',
+      'context-data'
+    );
+    expect(prompt).toBe(
+      'Context: context-data. File: $CONTEXT_FILE. External path: $EXTERNAL_CONTEXT_PATH. IssueId: $ISSUE_CONTEXT_ID'
+    );
+    expect(contextSubstituted).toBe(true);
+  });
+
+  it('does not substitute $ISSUE_CONTEXT when followed by identifier characters', () => {
+    const { prompt } = substituteWorkflowVariables(
+      'Issue: $ISSUE_CONTEXT. ID: $ISSUE_CONTEXT_ID. Type: $ISSUE_CONTEXT_TYPE',
+      'run-1',
+      'msg',
+      '/tmp',
+      'main',
+      'docs/',
+      'context-data'
+    );
+    expect(prompt).toBe('Issue: context-data. ID: $ISSUE_CONTEXT_ID. Type: $ISSUE_CONTEXT_TYPE');
+  });
+
+  it('does not set contextSubstituted when only suffix-extended context vars are present', () => {
+    const { prompt, contextSubstituted } = substituteWorkflowVariables(
+      'Path: $CONTEXT_FILE',
+      'run-1',
+      'msg',
+      '/tmp',
+      'main',
+      'docs/',
+      'context-data'
+    );
+    // $CONTEXT_FILE is not a context variable — should be left untouched
+    expect(prompt).toBe('Path: $CONTEXT_FILE');
+    expect(contextSubstituted).toBe(false);
+  });
+
   it('clears context variables when issueContext is undefined', () => {
     const { prompt, contextSubstituted } = substituteWorkflowVariables(
       'Context: $CONTEXT here',
@@ -330,3 +376,65 @@ describe('isInlineScript', () => {
     expect(isInlineScript('')).toBe(false);
   });
 });
+
+describe('detectCompletionSignal', () => {
+  it('detects <promise>SIGNAL</promise> format', () => {
+    expect(detectCompletionSignal('<promise>COMPLETE</promise>', 'COMPLETE')).toBe(true);
+  });
+
+  it('detects signal in custom XML tags: <COMPLETE>SIGNAL</COMPLETE>', () => {
+    expect(detectCompletionSignal('<COMPLETE>ALL_CLEAN</COMPLETE>', 'ALL_CLEAN')).toBe(true);
+  });
+
+  it('detects signal in other XML tag names', () => {
+    expect(detectCompletionSignal('<done>COMPLETE</done>', 'COMPLETE')).toBe(true);
+    expect(detectCompletionSignal('<status>DONE</status>', 'DONE')).toBe(true);
+  });
+
+  it('detects plain signal at end of output', () => {
+    expect(detectCompletionSignal('Work done. COMPLETE', 'COMPLETE')).toBe(true);
+  });
+
+  it('detects plain signal on its own line', () => {
+    expect(detectCompletionSignal('Work done.\nCOMPLETE\nExtra text', 'COMPLETE')).toBe(true);
+  });
+
+  it('does not detect signal embedded in prose', () => {
+    expect(detectCompletionSignal('The status is not COMPLETE yet.', 'COMPLETE')).toBe(false);
+  });
+
+  it('does not detect signal when wrong value is in tags', () => {
+    expect(detectCompletionSignal('<COMPLETE>WRONG</COMPLETE>', 'ALL_CLEAN')).toBe(false);
+  });
+
+  it('does NOT detect signal when XML tag names do not match (strict)', () => {
+    // Open/close tag names must agree — guards against AI prose that
+    // interleaves tags (e.g. "<COMPLETE>ALL_CLEAN</other-tag>") being
+    // treated as a completion.
+    expect(detectCompletionSignal('<COMPLETE>ALL_CLEAN</done>', 'ALL_CLEAN')).toBe(false);
+  });
+
+  it('detects signal when tag names match case-insensitively', () => {
+    expect(detectCompletionSignal('<Complete>ALL_CLEAN</complete>', 'ALL_CLEAN')).toBe(true);
+  });
+});
+
+describe('stripCompletionTags', () => {
+  it('strips <promise> tags', () => {
+    expect(stripCompletionTags('Done. <promise>COMPLETE</promise>')).toBe('Done.');
+  });
+
+  it('strips XML-wrapped signal when until is provided', () => {
+    expect(stripCompletionTags('Done. <COMPLETE>ALL_CLEAN</COMPLETE>', 'ALL_CLEAN')).toBe('Done.');
+  });
+
+  it('does not strip XML tags when until is not provided', () => {
+    const input = 'Done. <COMPLETE>ALL_CLEAN</COMPLETE>';
+    expect(stripCompletionTags(input)).toBe(input.trim());
+  });
+
+  it('strips both <promise> and XML-tagged signal when until is provided', () => {
+    const input = 'Done. <promise>ALL_CLEAN</promise> <COMPLETE>ALL_CLEAN</COMPLETE>';
+    expect(stripCompletionTags(input, 'ALL_CLEAN')).toBe('Done.');
+  });
+});
diff --git a/packages/workflows/src/executor-shared.ts b/packages/workflows/src/executor-shared.ts
index 0537609417..e88700d9cb 100644
--- a/packages/workflows/src/executor-shared.ts
+++ b/packages/workflows/src/executor-shared.ts
@@ -67,13 +67,8 @@ export function matchesPattern(message: string, patterns: string[]): boolean {
  * Classify an error to determine if it's transient (can retry) or fatal (should fail).
  * FATAL patterns take priority over TRANSIENT patterns to prevent an error message
  * containing both (e.g. "unauthorized: process exited with code 1") from being retried.
- *
- * First-party named error types are checked by name (immune to message rewording).
  */
 export function classifyError(error: Error): ErrorType {
-  // Named first-party errors checked by name — immune to message rewording
-  if (error.name === 'EnvLeakError') return 'FATAL';
-
   const message = error.message.toLowerCase();
 
   if (matchesPattern(message, FATAL_PATTERNS)) {
@@ -154,12 +149,22 @@ export async function loadCommandPrompt(
     config = { defaults: { loadDefaultCommands: true } };
   }
 
-  // Use command folder paths with optional configured folder
+  // Use command folder paths with optional configured folder.
+  // Each scope is walked 1 subfolder deep so `triage/review.md` resolves as
+  // `review` — matching the workflows/scripts convention. Resolution
+  // precedence: repo > home (~/.archon/commands/) > bundled/app defaults.
   const searchPaths = archonPaths.getCommandFolderSearchPaths(configuredFolder);
+  const resolvedSearchPaths: string[] = [
+    ...searchPaths.map(folder => join(cwd, folder)),
+    archonPaths.getHomeCommandsPath(),
+  ];
+
+  for (const dir of resolvedSearchPaths) {
+    const entries = await archonPaths.findMarkdownFilesRecursive(dir, '', { maxDepth: 1 });
+    const match = entries.find(e => e.commandName === commandName);
+    if (!match) continue;
 
-  // Search repo paths first
-  for (const folder of searchPaths) {
-    const filePath = join(cwd, folder, `${commandName}.md`);
+    const filePath = join(dir, match.relativePath);
     try {
       const content = await readFile(filePath, 'utf-8');
       if (!content.trim()) {
@@ -170,13 +175,10 @@ export async function loadCommandPrompt(
           message: `Command file is empty: ${commandName}.md`,
         };
       }
-      getLog().debug({ commandName, folder }, 'command_loaded');
+      getLog().debug({ commandName, filePath }, 'command_loaded');
       return { success: true, content };
     } catch (error) {
       const err = error as NodeJS.ErrnoException;
-      if (err.code === 'ENOENT') {
-        continue;
-      }
       if (err.code === 'EACCES') {
         getLog().error({ commandName, filePath }, 'command_file_permission_denied');
         return {
@@ -185,7 +187,9 @@ export async function loadCommandPrompt(
           message: `Permission denied reading command: ${commandName}.md`,
         };
       }
-      // Other unexpected errors
+      // Other unexpected errors (ENOENT shouldn't happen since the walk just found it,
+      // but if the file was deleted between walk and read we fall through to 'not found'
+      // with a log.)
       getLog().error({ err, commandName, filePath }, 'command_file_read_error');
       return {
         success: false,
@@ -195,7 +199,7 @@ export async function loadCommandPrompt(
     }
   }
 
-  // If not found in repo and app defaults enabled, search app defaults
+  // If not found in repo/home and app defaults enabled, search app defaults
   const loadDefaultCommands = config.defaults?.loadDefaultCommands ?? true;
   if (loadDefaultCommands) {
     if (isBinaryBuild()) {
@@ -207,29 +211,37 @@ export async function loadCommandPrompt(
       }
       getLog().debug({ commandName }, 'command_bundled_not_found');
     } else {
-      // Bun: load from filesystem
+      // Bun: load from filesystem (walk 1 level deep so `defaults/archon-*.md` resolves)
       const appDefaultsPath = archonPaths.getDefaultCommandsPath();
-      const filePath = join(appDefaultsPath, `${commandName}.md`);
-      try {
-        const content = await readFile(filePath, 'utf-8');
-        if (!content.trim()) {
-          getLog().error({ commandName }, 'command_app_default_empty');
-          return {
-            success: false,
-            reason: 'empty_file',
-            message: `App default command file is empty: ${commandName}.md`,
-          };
-        }
-        getLog().debug({ commandName }, 'command_loaded_app_defaults');
-        return { success: true, content };
-      } catch (error) {
-        const err = error as NodeJS.ErrnoException;
-        if (err.code !== 'ENOENT') {
-          getLog().warn({ err, commandName }, 'command_app_default_read_error');
-        } else {
-          getLog().debug({ commandName }, 'command_app_default_not_found');
+      const entries = await archonPaths.findMarkdownFilesRecursive(appDefaultsPath, '', {
+        maxDepth: 1,
+      });
+      const match = entries.find(e => e.commandName === commandName);
+      if (match) {
+        const filePath = join(appDefaultsPath, match.relativePath);
+        try {
+          const content = await readFile(filePath, 'utf-8');
+          if (!content.trim()) {
+            getLog().error({ commandName }, 'command_app_default_empty');
+            return {
+              success: false,
+              reason: 'empty_file',
+              message: `App default command file is empty: ${commandName}.md`,
+            };
+          }
+          getLog().debug({ commandName }, 'command_loaded_app_defaults');
+          return { success: true, content };
+        } catch (error) {
+          const err = error as NodeJS.ErrnoException;
+          if (err.code !== 'ENOENT') {
+            getLog().warn({ err, commandName }, 'command_app_default_read_error');
+          } else {
+            getLog().debug({ commandName }, 'command_app_default_not_found');
+          }
+          // Fall through to not found
         }
-        // Fall through to not found
+      } else {
+        getLog().debug({ commandName }, 'command_app_default_not_found');
       }
     }
   }
@@ -247,7 +259,8 @@ export async function loadCommandPrompt(
 // ─── Variable Substitution ───────────────────────────────────────────────────
 
 /** Pattern string for context variables - used to create fresh regex instances */
-export const CONTEXT_VAR_PATTERN_STR = '\\$(?:CONTEXT|EXTERNAL_CONTEXT|ISSUE_CONTEXT)';
+export const CONTEXT_VAR_PATTERN_STR =
+  '\\$(?:CONTEXT|EXTERNAL_CONTEXT|ISSUE_CONTEXT)(?![A-Za-z0-9_])';
 
 /**
  * Substitute workflow variables in a prompt.
@@ -375,18 +388,26 @@ function escapeRegExp(str: string): string {
 /**
  * Detect whether the AI output contains a completion signal.
  *
- * Supports two formats:
+ * Supports three formats, checked in order:
  * 1. <promise>SIGNAL</promise> - Recommended; prevents false positives in prose
- * 2. Plain SIGNAL - Backwards compatibility; only at end of output or on own line
+ * 2. <anytag>SIGNAL</anytag> - Any XML-wrapped tag; case-insensitive on tag names
+ * 3. Plain SIGNAL - Backwards compatibility; only at end of output or on own line
+ *
+ * Tag matching uses a backreference (\1) so opening and closing tag names must
+ * agree — `<COMPLETE>X</done>` is not treated as a completion, which avoids
+ * false positives when the AI interleaves tags in prose.
  *
- * The <promise> tag format uses case-insensitive matching for the tags.
- * Plain signal detection is restrictive to prevent false positives.
+ * Plain signal detection is restrictive to prevent false positives like "not SIGNAL yet".
  */
 export function detectCompletionSignal(output: string, signal: string): boolean {
-  // Check for <promise>SIGNAL</promise> format (recommended - prevents false positives)
-  // Case-insensitive for tags
-  const promisePattern = new RegExp(`<promise>\\s*${escapeRegExp(signal)}\\s*</promise>`, 'i');
-  if (promisePattern.test(output)) {
+  // Check for XML-like tag wrapping with matching open/close names: <tag>SIGNAL</tag>.
+  // Catches <promise>COMPLETE</promise>, <COMPLETE>ALL_CLEAN</COMPLETE>, <done>X</done>.
+  // The `([a-zA-Z][\w-]*)` capture plus `</\1>` backreference requires tag names to match.
+  const xmlWrappedPattern = new RegExp(
+    `<([a-zA-Z][\\w-]*)[^>]*>\\s*${escapeRegExp(signal)}\\s*</\\1>`,
+    'i'
+  );
+  if (xmlWrappedPattern.test(output)) {
     return true;
   }
   // Plain signal detection - restrictive to prevent false positives like "not COMPLETE yet"
@@ -398,9 +419,24 @@ export function detectCompletionSignal(output: string, signal: string): boolean
   return endPattern.test(output) || ownLinePattern.test(output);
 }
 
-/** Strip internal completion signal tags before sending to user-facing output. */
-export function stripCompletionTags(content: string): string {
-  return content.replace(/<promise>[\s\S]*?<\/promise>/gi, '').trim();
+/**
+ * Strip internal completion signal tags before sending to user-facing output.
+ * Always strips `<promise>…</promise>` (any content). When `until` is provided,
+ * also strips any XML-wrapped form of that signal with matching tag names
+ * (e.g. `<COMPLETE>ALL_CLEAN</COMPLETE>`). Mismatched tag names are left alone
+ * so regular prose (`<note>ALL_CLEAN</warning>`) isn't accidentally rewritten.
+ */
+export function stripCompletionTags(content: string, until?: string): string {
+  let result = content.replace(/<promise>[\s\S]*?<\/promise>/gi, '');
+  if (until) {
+    // Strip XML-tagged completion signals with matching open/close tag names.
+    const escapedSignal = escapeRegExp(until);
+    result = result.replace(
+      new RegExp(`<([a-zA-Z][\\w-]*)[^>]*>\\s*${escapedSignal}\\s*</\\1>`, 'gi'),
+      ''
+    );
+  }
+  return result.trim();
 }
 
 /**
diff --git a/packages/workflows/src/executor.test.ts b/packages/workflows/src/executor.test.ts
index 0a91ac8299..0c8b626d5a 100644
--- a/packages/workflows/src/executor.test.ts
+++ b/packages/workflows/src/executor.test.ts
@@ -54,6 +54,11 @@ mock.module('./event-emitter', () => ({
   getWorkflowEventEmitter: mock(() => mockEmitter),
 }));
 
+// --- Bootstrap provider registry (after path mocks) ---
+import { registerBuiltinProviders, clearRegistry } from '@archon/providers';
+clearRegistry();
+registerBuiltinProviders();
+
 // --- Import after mocks ---
 import { executeWorkflow } from './executor';
 import type { WorkflowDeps, IWorkflowPlatform, WorkflowConfig } from './deps';
@@ -101,7 +106,7 @@ function makeDeps(store?: IWorkflowStore): WorkflowDeps {
         commands: { folder: '' },
       })
     ),
-    createAssistantClient: mock(() => ({
+    getAgentProvider: mock(() => ({
       run: mock(async () => {}),
     })),
   } as unknown as WorkflowDeps;
@@ -180,6 +185,7 @@ describe('executeWorkflow', () => {
 
     it('blocks workflow when another is actively running', async () => {
       const activeRun = makeRun({
+        id: 'other-run-456',
         status: 'running',
         started_at: new Date().toISOString(), // Recent — not stale
       });
@@ -197,7 +203,210 @@ describe('executeWorkflow', () => {
         'db-conv-1'
       );
       expect(result.success).toBe(false);
-      expect(result.error).toContain('already running');
+      expect(result.error).toContain('already active');
+    });
+
+    it('passes self-id and started_at to the lock query so self is excluded', async () => {
+      // The guard runs AFTER workflowRun is finalized so we always have
+      // a self-ID. Without these args, the dispatch's own row would match
+      // and falsely trigger the guard.
+      const selfRun = makeRun({ id: 'self-run-789', started_at: '2026-04-14T10:00:00.000Z' });
+      const getActiveSpy = mock(async () => null);
+      const store = makeStore({
+        createWorkflowRun: mock(async () => selfRun),
+        getActiveWorkflowRunByPath: getActiveSpy,
+      });
+      const deps = makeDeps(store);
+
+      await executeWorkflow(
+        deps,
+        makePlatform(),
+        'conv-1',
+        '/tmp',
+        makeWorkflow(),
+        'test message',
+        'db-conv-1'
+      );
+
+      expect(getActiveSpy).toHaveBeenCalledWith(
+        '/tmp',
+        expect.objectContaining({ id: 'self-run-789', startedAt: expect.any(Date) })
+      );
+    });
+
+    it('marks self as cancelled when guard fires (no zombie pending row)', async () => {
+      const selfRun = makeRun({ id: 'self-run-789' });
+      const otherRun = makeRun({ id: 'other-run-456', status: 'running' });
+      const updateSpy = mock(async () => {});
+      const store = makeStore({
+        createWorkflowRun: mock(async () => selfRun),
+        getActiveWorkflowRunByPath: mock(async () => otherRun),
+        updateWorkflowRun: updateSpy,
+      });
+      const deps = makeDeps(store);
+
+      await executeWorkflow(
+        deps,
+        makePlatform(),
+        'conv-1',
+        '/tmp',
+        makeWorkflow(),
+        'test message',
+        'db-conv-1'
+      );
+
+      // Without this, every guard-blocked dispatch would leak a `pending`
+      // row that briefly blocks future dispatches via the lock query.
+      expect(updateSpy).toHaveBeenCalledWith('self-run-789', { status: 'cancelled' });
+    });
+
+    it('uses the actionable "in use" message format with workflow name, duration, and short id', async () => {
+      const otherRun = makeRun({
+        id: 'abc12345-rest-of-uuid',
+        workflow_name: 'archon-implement',
+        status: 'running',
+        started_at: new Date(Date.now() - 125000).toISOString(), // 2m 5s ago
+      });
+      const sendMessageSpy = mock(async () => {});
+      const platform = {
+        sendMessage: sendMessageSpy,
+        getPlatformType: mock(() => 'test' as const),
+      } as unknown as IWorkflowPlatform;
+      const store = makeStore({
+        getActiveWorkflowRunByPath: mock(async () => otherRun),
+      });
+      const deps = makeDeps(store);
+
+      await executeWorkflow(
+        deps,
+        platform,
+        'conv-1',
+        '/tmp',
+        makeWorkflow(),
+        'test message',
+        'db-conv-1'
+      );
+
+      expect(sendMessageSpy).toHaveBeenCalled();
+      const sentMessage = (sendMessageSpy.mock.calls[0] as [string, string])[1];
+      expect(sentMessage).toContain('archon-implement');
+      expect(sentMessage).toContain('abc12345');
+      expect(sentMessage).toContain('2m 5s');
+      // Concrete next actions — every line tells the user something to do.
+      expect(sentMessage).toContain('/workflow status');
+      expect(sentMessage).toContain('/workflow cancel abc12345');
+      expect(sentMessage).toContain('--branch');
+    });
+
+    it('still returns failure when guard self-cancel update throws (best-effort)', async () => {
+      const selfRun = makeRun({ id: 'self-run', status: 'pending' });
+      const otherRun = makeRun({ id: 'other-run', status: 'running' });
+      const updateSpy = mock(async (id: string) => {
+        // Self-cancel attempt fails — must not crash, must still surface
+        // the "in use" failure to the user.
+        if (id === 'self-run') throw new Error('Update failed');
+      });
+      const store = makeStore({
+        createWorkflowRun: mock(async () => selfRun),
+        getActiveWorkflowRunByPath: mock(async () => otherRun),
+        updateWorkflowRun: updateSpy,
+      });
+      const deps = makeDeps(store);
+
+      const result = await executeWorkflow(
+        deps,
+        makePlatform(),
+        'conv-1',
+        '/tmp',
+        makeWorkflow(),
+        'test',
+        'db-conv-1'
+      );
+
+      // Cleanup failure must not mask the "in use" outcome.
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('already active');
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Resume orphan cleanup
+  // -------------------------------------------------------------------------
+
+  describe('resume orphan cleanup', () => {
+    it('cancels orphaned pre-created row when resume activates', async () => {
+      // Orchestrator dispatched and pre-created this row before resume
+      // detection ran. Once resume takes over (using resumableRun instead),
+      // the pre-created row is a stale lock-token that would block the
+      // user's next back-to-back resume.
+      const preCreated = makeRun({ id: 'pre-created-orphan', status: 'pending' });
+      const resumable = makeRun({ id: 'failed-prior-run', status: 'failed' });
+      const updateSpy = mock(async () => {});
+      const store = makeStore({
+        findResumableRun: mock(async () => resumable),
+        getCompletedDagNodeOutputs: mock(async () => new Map([['node1', 'output1']])),
+        resumeWorkflowRun: mock(async () => makeRun({ id: 'failed-prior-run', status: 'running' })),
+        updateWorkflowRun: updateSpy,
+      });
+      const deps = makeDeps(store);
+
+      await executeWorkflow(
+        deps,
+        makePlatform(),
+        'conv-1',
+        '/tmp',
+        makeWorkflow(),
+        'test message',
+        'db-conv-1',
+        undefined,
+        undefined,
+        undefined,
+        undefined,
+        preCreated
+      );
+
+      // Find the orphan-cancellation call (there may be other updateWorkflowRun
+      // calls during normal execution flow, e.g., status transitions).
+      const orphanCancelCall = updateSpy.mock.calls.find(
+        (call: unknown[]) =>
+          call[0] === 'pre-created-orphan' &&
+          (call[1] as { status?: string })?.status === 'cancelled'
+      );
+      expect(orphanCancelCall).toBeDefined();
+    });
+
+    it('proceeds with resume even if orphan cancellation fails (best-effort)', async () => {
+      const preCreated = makeRun({ id: 'pre-created-orphan', status: 'pending' });
+      const resumable = makeRun({ id: 'failed-prior-run', status: 'failed' });
+      const updateSpy = mock(async (id: string) => {
+        if (id === 'pre-created-orphan') throw new Error('DB busy');
+      });
+      const store = makeStore({
+        findResumableRun: mock(async () => resumable),
+        getCompletedDagNodeOutputs: mock(async () => new Map([['node1', 'output1']])),
+        resumeWorkflowRun: mock(async () => makeRun({ id: 'failed-prior-run', status: 'running' })),
+        updateWorkflowRun: updateSpy,
+      });
+      const deps = makeDeps(store);
+
+      const result = await executeWorkflow(
+        deps,
+        makePlatform(),
+        'conv-1',
+        '/tmp',
+        makeWorkflow(),
+        'test message',
+        'db-conv-1',
+        undefined,
+        undefined,
+        undefined,
+        undefined,
+        preCreated
+      );
+
+      // Resume must still complete — the 5-min stale-pending window is the
+      // safety net for cleanup failures here.
+      expect(result.workflowRunId).toBe('failed-prior-run');
     });
   });
 
@@ -291,7 +500,7 @@ describe('executeWorkflow', () => {
             docsPath: 'packages/docs-web/src/content/docs',
           })
         ),
-        createAssistantClient: mock(() => ({
+        getAgentProvider: mock(() => ({
           run: mock(async () => {}),
         })),
       } as unknown as WorkflowDeps;
@@ -531,4 +740,158 @@ describe('executeWorkflow', () => {
       expect(store.getCodebaseEnvVars).not.toHaveBeenCalled();
     });
   });
+
+  // -------------------------------------------------------------------------
+  // Lock-token cleanup on pre-DAG failure paths (review #1)
+  //
+  // Any failure between row creation and DAG start that returns early must
+  // release the lock token. Without this, ghost pending/running rows block
+  // the path until the 5-min stale window or manual intervention.
+  // -------------------------------------------------------------------------
+
+  describe('lock cleanup on failure paths', () => {
+    it('cancels pre-created row when resumeWorkflowRun throws', async () => {
+      const preCreated = makeRun({ id: 'pre-created-orphan', status: 'pending' });
+      const resumable = makeRun({ id: 'failed-prior-run', status: 'failed' });
+      const updateSpy = mock(async () => {});
+      const store = makeStore({
+        findResumableRun: mock(async () => resumable),
+        getCompletedDagNodeOutputs: mock(async () => new Map([['node1', 'out1']])),
+        resumeWorkflowRun: mock(async () => {
+          throw new Error('DB blew up during resume activation');
+        }),
+        updateWorkflowRun: updateSpy,
+      });
+      const deps = makeDeps(store);
+
+      const result = await executeWorkflow(
+        deps,
+        makePlatform(),
+        'conv-1',
+        '/tmp',
+        makeWorkflow(),
+        'test',
+        'db-conv-1',
+        undefined,
+        undefined,
+        undefined,
+        undefined,
+        preCreated
+      );
+
+      expect(result.success).toBe(false);
+      const cancelCall = updateSpy.mock.calls.find(
+        (call: unknown[]) =>
+          call[0] === 'pre-created-orphan' &&
+          (call[1] as { status?: string })?.status === 'cancelled'
+      );
+      expect(cancelCall).toBeDefined();
+    });
+
+    it('cancels workflowRun when guard query throws (no zombie row)', async () => {
+      const updateSpy = mock(async () => {});
+      const store = makeStore({
+        getActiveWorkflowRunByPath: mock(async () => {
+          throw new Error('DB connection lost during guard');
+        }),
+        updateWorkflowRun: updateSpy,
+      });
+      const deps = makeDeps(store);
+
+      const result = await executeWorkflow(
+        deps,
+        makePlatform(),
+        'conv-1',
+        '/tmp',
+        makeWorkflow(),
+        'test',
+        'db-conv-1'
+      );
+
+      expect(result.success).toBe(false);
+      const cancelCall = updateSpy.mock.calls.find(
+        (call: unknown[]) => (call[1] as { status?: string })?.status === 'cancelled'
+      );
+      expect(cancelCall).toBeDefined();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Status-aware blocking message (review #3)
+  //
+  // The lock query returns running, paused, AND fresh-pending rows.
+  // Telling a user to "wait" when the holder is `paused` is misleading —
+  // they need to approve/reject to unblock it.
+  // -------------------------------------------------------------------------
+
+  describe('blocking message status awareness', () => {
+    it('uses paused-specific copy when blocker is paused', async () => {
+      const pausedRun = makeRun({
+        id: 'paused-run-id',
+        workflow_name: 'archon-implement',
+        status: 'paused',
+        started_at: new Date(Date.now() - 10000).toISOString(),
+      });
+      const sendMessageSpy = mock(async () => {});
+      const platform = {
+        sendMessage: sendMessageSpy,
+        getPlatformType: mock(() => 'test' as const),
+      } as unknown as IWorkflowPlatform;
+      const store = makeStore({ getActiveWorkflowRunByPath: mock(async () => pausedRun) });
+      const deps = makeDeps(store);
+
+      await executeWorkflow(deps, platform, 'conv-1', '/tmp', makeWorkflow(), 'test', 'db-conv-1');
+
+      const msg = (sendMessageSpy.mock.calls[0] as [string, string])[1];
+      // Wrong action ("wait for it to finish") would let users sit forever
+      // on a workflow waiting for their own approval.
+      expect(msg).toContain('paused');
+      expect(msg).toContain('/workflow approve');
+      expect(msg).toContain('/workflow reject');
+      expect(msg).not.toContain('Wait for it to finish');
+    });
+
+    it('uses pending-specific copy when blocker is just starting', async () => {
+      const pendingRun = makeRun({
+        id: 'pending-run',
+        workflow_name: 'archon-implement',
+        status: 'pending',
+        started_at: new Date(Date.now() - 500).toISOString(),
+      });
+      const sendMessageSpy = mock(async () => {});
+      const platform = {
+        sendMessage: sendMessageSpy,
+        getPlatformType: mock(() => 'test' as const),
+      } as unknown as IWorkflowPlatform;
+      const store = makeStore({ getActiveWorkflowRunByPath: mock(async () => pendingRun) });
+      const deps = makeDeps(store);
+
+      await executeWorkflow(deps, platform, 'conv-1', '/tmp', makeWorkflow(), 'test', 'db-conv-1');
+
+      const msg = (sendMessageSpy.mock.calls[0] as [string, string])[1];
+      expect(msg).toContain('starting');
+    });
+
+    it('uses running copy by default', async () => {
+      const runningRun = makeRun({
+        id: 'running-run',
+        workflow_name: 'archon-implement',
+        status: 'running',
+        started_at: new Date(Date.now() - 60000).toISOString(),
+      });
+      const sendMessageSpy = mock(async () => {});
+      const platform = {
+        sendMessage: sendMessageSpy,
+        getPlatformType: mock(() => 'test' as const),
+      } as unknown as IWorkflowPlatform;
+      const store = makeStore({ getActiveWorkflowRunByPath: mock(async () => runningRun) });
+      const deps = makeDeps(store);
+
+      await executeWorkflow(deps, platform, 'conv-1', '/tmp', makeWorkflow(), 'test', 'db-conv-1');
+
+      const msg = (sendMessageSpy.mock.calls[0] as [string, string])[1];
+      expect(msg).toContain('running 1m');
+      expect(msg).toContain('Wait for it to finish');
+    });
+  });
 });
diff --git a/packages/workflows/src/executor.ts b/packages/workflows/src/executor.ts
index e87ea9065b..39b75e00c7 100644
--- a/packages/workflows/src/executor.ts
+++ b/packages/workflows/src/executor.ts
@@ -6,13 +6,14 @@ import { join } from 'path';
 import type { IWorkflowPlatform, WorkflowMessageMetadata } from './deps';
 import type { WorkflowDeps, WorkflowConfig } from './deps';
 import * as archonPaths from '@archon/paths';
-import { createLogger } from '@archon/paths';
+import { createLogger, captureWorkflowInvoked, BUNDLED_VERSION } from '@archon/paths';
 import { getDefaultBranch, toRepoPath } from '@archon/git';
 import type { WorkflowDefinition, WorkflowRun, WorkflowExecutionResult } from './schemas';
 import { executeDagWorkflow } from './dag-executor';
 import { logWorkflowStart, logWorkflowError } from './logger';
+import { formatDuration, parseDbTimestamp } from './utils/duration';
 import { getWorkflowEventEmitter } from './event-emitter';
-import { isClaudeModel, isModelCompatible } from './model-validation';
+import { inferProviderFromModel, isModelCompatible } from './model-validation';
 import { classifyError } from './executor-shared';
 
 /** Lazy-initialized logger (deferred so test mocks can intercept createLogger) */
@@ -278,22 +279,20 @@ export async function executeWorkflow(
   // Resolve provider and model once (used by all nodes)
   // When workflow sets a model but not a provider, infer provider from the model.
   // e.g. model: sonnet → provider: claude, even if config.assistant is codex.
-  let resolvedProvider: 'claude' | 'codex';
+  let resolvedProvider: string;
   let providerSource: string;
   if (workflow.provider) {
     resolvedProvider = workflow.provider;
     providerSource = 'workflow definition';
-  } else if (workflow.model && isClaudeModel(workflow.model)) {
-    resolvedProvider = 'claude';
-    providerSource = 'inferred from workflow model';
   } else if (workflow.model) {
-    resolvedProvider = 'codex';
+    resolvedProvider = inferProviderFromModel(workflow.model, config.assistant);
     providerSource = 'inferred from workflow model';
   } else {
     resolvedProvider = config.assistant;
     providerSource = 'config';
   }
-  const resolvedModel = workflow.model ?? config.assistants[resolvedProvider]?.model;
+  const assistantDefaults = config.assistants[resolvedProvider];
+  const resolvedModel = workflow.model ?? (assistantDefaults?.model as string | undefined);
   if (!isModelCompatible(resolvedProvider, resolvedModel)) {
     throw new Error(
       `Model "${resolvedModel}" is not compatible with provider "${resolvedProvider}". ` +
@@ -319,29 +318,6 @@ export async function executeWorkflow(
   let dagPriorCompletedNodes: Map<string, string> | undefined;
   let workflowRun: WorkflowRun | undefined = preCreatedRun;
 
-  // Check for concurrent workflow execution on the same path
-  try {
-    const activeWorkflow = await deps.store.getActiveWorkflowRunByPath(cwd);
-    if (activeWorkflow) {
-      const startedAt = new Date(activeWorkflow.started_at).toLocaleString();
-      await sendCriticalMessage(
-        platform,
-        conversationId,
-        `❌ **Workflow already running**: \`${activeWorkflow.workflow_name}\` has been running since ${startedAt}. Please wait for it to complete or use \`/workflow cancel\` to stop it.`
-      );
-      return { success: false, error: `Workflow already running: ${activeWorkflow.workflow_name}` };
-    }
-  } catch (error) {
-    const err = error as Error;
-    getLog().error({ err, conversationId }, 'db_active_workflow_check_failed');
-    await sendCriticalMessage(
-      platform,
-      conversationId,
-      '❌ **Workflow blocked**: Unable to verify if another workflow is running (database error). Please try again in a moment.'
-    );
-    return { success: false, error: 'Database error checking for active workflow' };
-  }
-
   // Resume detection: check for prior failed run on same workflow + worktree
   {
     // Step 1: Find prior failed run — non-critical, fall through on DB error
@@ -396,8 +372,34 @@ export async function executeWorkflow(
         (resumableRun.metadata.approval as Record<string, unknown>).type === 'interactive_loop';
       if (priorNodes.size > 0 || hasInteractiveLoopState) {
         try {
+          // Capture the orphan BEFORE replacing workflowRun. The orchestrator's
+          // pre-created row was a lock-token claim on this path; once resume
+          // takes over, that claim is redundant. Without releasing it, a
+          // back-to-back resume would block on its own ghost lock until the
+          // 5-minute stale-pending window in getActiveWorkflowRunByPath.
+          const orphanPreCreated =
+            preCreatedRun && preCreatedRun.id !== resumableRun.id ? preCreatedRun : null;
+
           workflowRun = await deps.store.resumeWorkflowRun(resumableRun.id);
           dagPriorCompletedNodes = priorNodes;
+
+          if (orphanPreCreated) {
+            await deps.store
+              .updateWorkflowRun(orphanPreCreated.id, { status: 'cancelled' })
+              .catch((cleanupErr: Error) => {
+                // Best-effort: log and continue. The 5-min stale-pending
+                // window is the safety net if this fails.
+                getLog().warn(
+                  {
+                    err: cleanupErr,
+                    orphanId: orphanPreCreated.id,
+                    resumedRunId: workflowRun?.id,
+                  },
+                  'workflow.resume_orphan_cleanup_failed'
+                );
+              });
+          }
+
           getLog().info(
             {
               workflowRunId: workflowRun.id,
@@ -416,6 +418,19 @@ export async function executeWorkflow(
             { err, workflowName: workflow.name, resumableRunId: resumableRun.id },
             'workflow_resume_activate_failed'
           );
+          // Release the pre-created lock token. Without this, preCreatedRun
+          // sits as `pending` and blocks the path until the 5-min stale
+          // window — the user would see "in use by self" on retry.
+          if (preCreatedRun) {
+            await deps.store
+              .updateWorkflowRun(preCreatedRun.id, { status: 'cancelled' })
+              .catch((cleanupErr: Error) => {
+                getLog().warn(
+                  { err: cleanupErr, preCreatedRunId: preCreatedRun.id },
+                  'workflow.resume_failure_cleanup_failed'
+                );
+              });
+          }
           await sendCriticalMessage(
             platform,
             conversationId,
@@ -460,6 +475,96 @@ export async function executeWorkflow(
     }
   }
 
+  // Path-lock guard: ensure no other workflow run holds this working_path.
+  //
+  // Runs after workflowRun is finalized (pre-created, resumed, or freshly
+  // created) so we always have self-ID + started_at for the deterministic
+  // older-wins tiebreaker. The query treats `pending` rows older than 5 min
+  // as orphaned, so leaks from crashed dispatches or resume orphans don't
+  // permanently block the path.
+  try {
+    const activeWorkflow = await deps.store.getActiveWorkflowRunByPath(cwd, {
+      id: workflowRun.id,
+      startedAt: new Date(parseDbTimestamp(workflowRun.started_at)),
+    });
+    if (activeWorkflow) {
+      // The lock query found another active row that wins the older-wins
+      // tiebreaker. Mark our own row terminal so it falls out of the
+      // active set immediately — without this, our row sits as
+      // pending/running and blocks the path until the 5-min stale window
+      // (or never, if we'd already promoted it to running via resume).
+      await deps.store
+        .updateWorkflowRun(workflowRun.id, { status: 'cancelled' })
+        .catch((cleanupErr: Error) => {
+          getLog().warn(
+            { err: cleanupErr, workflowRunId: workflowRun?.id, cwd },
+            'workflow.guard_self_cancel_failed'
+          );
+        });
+
+      const elapsedMs = Date.now() - parseDbTimestamp(activeWorkflow.started_at);
+      const duration = formatDuration(elapsedMs);
+      const shortId = activeWorkflow.id.slice(0, 8);
+
+      // Status-aware copy. The lock query returns running, paused, and
+      // fresh-pending rows — telling the user to "wait for it to finish"
+      // is wrong for `paused` (waiting on user action via approve/reject).
+      let stateLine: string;
+      let actionLines: string;
+      if (activeWorkflow.status === 'paused') {
+        stateLine = `paused waiting for user input (${duration} since started, run \`${shortId}\`)`;
+        actionLines =
+          `• Approve it: \`/workflow approve ${shortId}\`\n` +
+          `• Reject it: \`/workflow reject ${shortId}\`\n` +
+          `• Cancel it: \`/workflow cancel ${shortId}\`\n` +
+          '• Use a different branch: `--branch <other>`';
+      } else {
+        const verb = activeWorkflow.status === 'pending' ? 'starting' : 'running';
+        stateLine = `${verb} ${duration}, run \`${shortId}\``;
+        actionLines =
+          '• Wait for it to finish: `/workflow status`\n' +
+          `• Cancel it: \`/workflow cancel ${shortId}\`\n` +
+          '• Use a different branch: `--branch <other>`';
+      }
+      await sendCriticalMessage(
+        platform,
+        conversationId,
+        `❌ **This worktree is in use** by \`${activeWorkflow.workflow_name}\` ` +
+          `(${stateLine}).\n${actionLines}`
+      );
+      return {
+        success: false,
+        error: `Workflow already active on this path (${activeWorkflow.status}): ${activeWorkflow.workflow_name}`,
+      };
+    }
+  } catch (error) {
+    const err = error as Error;
+    getLog().error(
+      { err, conversationId, cwd, pendingRunId: workflowRun.id },
+      'db_active_workflow_check_failed'
+    );
+    // Release the lock token. workflowRun is finalized at this point
+    // (pre-created or resumed or freshly created) and would otherwise sit
+    // as pending/running, blocking the path. For pending the 5-min stale
+    // window would clear it eventually; for a row already promoted to
+    // running (e.g., resumed), nothing would clear it without manual
+    // intervention.
+    await deps.store
+      .updateWorkflowRun(workflowRun.id, { status: 'cancelled' })
+      .catch((cleanupErr: Error) => {
+        getLog().warn(
+          { err: cleanupErr, workflowRunId: workflowRun?.id },
+          'workflow.guard_query_failure_cleanup_failed'
+        );
+      });
+    await sendCriticalMessage(
+      platform,
+      conversationId,
+      '❌ **Workflow blocked**: Unable to verify if another workflow is running (database error). Please try again in a moment.'
+    );
+    return { success: false, error: 'Database error checking for active workflow' };
+  }
+
   // Resolve external artifact and log directories
   const { artifactsDir, logDir } = await resolveProjectPaths(deps, cwd, workflowRun.id, codebaseId);
 
@@ -516,6 +621,16 @@ export async function executeWorkflow(
       workflowName: workflow.name,
       conversationId: conversationDbId,
     });
+
+    // Fire-and-forget anonymous usage telemetry. No PII: only workflow name +
+    // description (authored by the user in their YAML) + platform + version.
+    // Opt out via ARCHON_TELEMETRY_DISABLED=1 or DO_NOT_TRACK=1.
+    captureWorkflowInvoked({
+      workflowName: workflow.name,
+      workflowDescription: workflow.description,
+      platform: platform.getPlatformType(),
+      archonVersion: BUNDLED_VERSION,
+    });
     deps.store
       .createWorkflowEvent({
         workflow_run_id: workflowRun.id,
diff --git a/packages/workflows/src/hooks.test.ts b/packages/workflows/src/hooks.test.ts
index 6bdaa6085a..eac6076bac 100644
--- a/packages/workflows/src/hooks.test.ts
+++ b/packages/workflows/src/hooks.test.ts
@@ -1,6 +1,6 @@
 import { describe, test, expect } from 'bun:test';
 import { parseNodeHooks } from './loader';
-import { buildSDKHooksFromYAML } from './dag-executor';
+import { buildSDKHooksFromYAML } from '@archon/providers/claude/provider';
 import type { WorkflowNodeHooks } from './schemas';
 import { parseWorkflow } from './loader';
 
diff --git a/packages/workflows/src/load-command-prompt.test.ts b/packages/workflows/src/load-command-prompt.test.ts
new file mode 100644
index 0000000000..75fc092814
--- /dev/null
+++ b/packages/workflows/src/load-command-prompt.test.ts
@@ -0,0 +1,115 @@
+import { describe, it, expect, mock, beforeEach, afterEach } from 'bun:test';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import * as realPaths from '@archon/paths';
+
+// Mock only the logger so test output stays clean. All other @archon/paths
+// exports (findMarkdownFilesRecursive, getHomeCommandsPath, etc.) use real
+// implementations — loadCommandPrompt exercises them against a tmp dir set
+// via ARCHON_HOME below.
+const mockLogFn = mock(() => {});
+const mockLogger = {
+  info: mockLogFn,
+  warn: mockLogFn,
+  error: mockLogFn,
+  debug: mockLogFn,
+  trace: mockLogFn,
+  fatal: mockLogFn,
+  child: mock(() => mockLogger),
+  bindings: mock(() => ({ module: 'test' })),
+  isLevelEnabled: mock(() => true),
+  level: 'info',
+};
+mock.module('@archon/paths', () => ({
+  ...realPaths,
+  createLogger: mock(() => mockLogger),
+}));
+
+import { loadCommandPrompt } from './executor-shared';
+import type { WorkflowDeps } from './deps';
+
+// Minimal deps stub — loadCommandPrompt only calls loadConfig.
+function makeDeps(loadDefaultCommands = true): WorkflowDeps {
+  return {
+    loadConfig: async () => ({ defaults: { loadDefaultCommands } }),
+  } as unknown as WorkflowDeps;
+}
+
+describe('loadCommandPrompt — home-scope resolution', () => {
+  let archonHome: string;
+  let repoRoot: string;
+  let prevArchonHome: string | undefined;
+
+  beforeEach(() => {
+    prevArchonHome = process.env.ARCHON_HOME;
+    // Separate tmp dirs for home and repo so they don't collide.
+    archonHome = mkdtempSync(join(tmpdir(), 'archon-home-'));
+    repoRoot = mkdtempSync(join(tmpdir(), 'archon-repo-'));
+    process.env.ARCHON_HOME = archonHome;
+    mkdirSync(join(archonHome, 'commands'), { recursive: true });
+    mkdirSync(join(repoRoot, '.archon', 'commands'), { recursive: true });
+  });
+
+  afterEach(() => {
+    if (prevArchonHome === undefined) delete process.env.ARCHON_HOME;
+    else process.env.ARCHON_HOME = prevArchonHome;
+    rmSync(archonHome, { recursive: true, force: true });
+    rmSync(repoRoot, { recursive: true, force: true });
+  });
+
+  it('resolves a command from ~/.archon/commands/ when repo has none', async () => {
+    writeFileSync(join(archonHome, 'commands', 'personal-helper.md'), 'Personal helper body');
+
+    const result = await loadCommandPrompt(makeDeps(false), repoRoot, 'personal-helper');
+
+    expect(result.success).toBe(true);
+    if (result.success) expect(result.content).toBe('Personal helper body');
+  });
+
+  it('repo command shadows home command with the same name', async () => {
+    writeFileSync(join(archonHome, 'commands', 'shared.md'), 'HOME version');
+    writeFileSync(join(repoRoot, '.archon', 'commands', 'shared.md'), 'REPO version');
+
+    const result = await loadCommandPrompt(makeDeps(false), repoRoot, 'shared');
+
+    expect(result.success).toBe(true);
+    if (result.success) expect(result.content).toBe('REPO version');
+  });
+
+  it('resolves a home command inside a 1-level subfolder by basename', async () => {
+    mkdirSync(join(archonHome, 'commands', 'triage'), { recursive: true });
+    writeFileSync(join(archonHome, 'commands', 'triage', 'review.md'), 'Review body');
+
+    const result = await loadCommandPrompt(makeDeps(false), repoRoot, 'review');
+
+    expect(result.success).toBe(true);
+    if (result.success) expect(result.content).toBe('Review body');
+  });
+
+  it('does NOT resolve home commands buried >1 level deep', async () => {
+    mkdirSync(join(archonHome, 'commands', 'a', 'b'), { recursive: true });
+    writeFileSync(join(archonHome, 'commands', 'a', 'b', 'too-deep.md'), 'too deep');
+
+    const result = await loadCommandPrompt(makeDeps(false), repoRoot, 'too-deep');
+
+    expect(result.success).toBe(false);
+    if (!result.success) expect(result.reason).toBe('not_found');
+  });
+
+  it('returns not_found when neither repo nor home has the command (defaults off)', async () => {
+    const result = await loadCommandPrompt(makeDeps(false), repoRoot, 'missing');
+
+    expect(result.success).toBe(false);
+    if (!result.success) expect(result.reason).toBe('not_found');
+  });
+
+  it('surfaces empty_file for a zero-byte home command', async () => {
+    writeFileSync(join(archonHome, 'commands', 'blank.md'), '');
+
+    const result = await loadCommandPrompt(makeDeps(false), repoRoot, 'blank');
+
+    expect(result.success).toBe(false);
+    if (!result.success) expect(result.reason).toBe('empty_file');
+  });
+});
diff --git a/packages/workflows/src/loader.test.ts b/packages/workflows/src/loader.test.ts
index 74b86a5977..127b2690b7 100644
--- a/packages/workflows/src/loader.test.ts
+++ b/packages/workflows/src/loader.test.ts
@@ -28,6 +28,11 @@ mock.module('@archon/paths', () => ({
   createLogger: mock(() => mockLogger),
 }));
 
+// Bootstrap provider registry (needed by isModelCompatible in dag-node schema)
+import { registerBuiltinProviders, clearRegistry } from '@archon/providers';
+clearRegistry();
+registerBuiltinProviders();
+
 import { discoverWorkflows } from './workflow-discovery';
 import { isBashNode, isCancelNode, isLoopNode } from './schemas';
 import * as bundledDefaults from './defaults/bundled-defaults';
@@ -88,6 +93,33 @@ describe('Workflow Loader', () => {
       expect(result.workflows[0].workflow.interactive).toBeUndefined();
     });
 
+    it('should parse worktree.enabled: false', async () => {
+      const workflowDir = join(testDir, '.archon', 'workflows');
+      await mkdir(workflowDir, { recursive: true });
+      const yaml = `name: triage\ndescription: read-only\nworktree:\n  enabled: false\nnodes:\n  - id: n\n    prompt: p\n`;
+      await writeFile(join(workflowDir, 'triage.yaml'), yaml);
+      const result = await discoverWorkflows(testDir, { loadDefaults: false });
+      expect(result.workflows[0].workflow.worktree).toEqual({ enabled: false });
+    });
+
+    it('should parse worktree.enabled: true', async () => {
+      const workflowDir = join(testDir, '.archon', 'workflows');
+      await mkdir(workflowDir, { recursive: true });
+      const yaml = `name: build\ndescription: needs worktree\nworktree:\n  enabled: true\nnodes:\n  - id: n\n    prompt: p\n`;
+      await writeFile(join(workflowDir, 'build.yaml'), yaml);
+      const result = await discoverWorkflows(testDir, { loadDefaults: false });
+      expect(result.workflows[0].workflow.worktree).toEqual({ enabled: true });
+    });
+
+    it('should omit worktree block when not present (policy is caller-decides)', async () => {
+      const workflowDir = join(testDir, '.archon', 'workflows');
+      await mkdir(workflowDir, { recursive: true });
+      const yaml = `name: normal\ndescription: no policy\nnodes:\n  - id: n\n    prompt: p\n`;
+      await writeFile(join(workflowDir, 'normal.yaml'), yaml);
+      const result = await discoverWorkflows(testDir, { loadDefaults: false });
+      expect(result.workflows[0].workflow.worktree).toBeUndefined();
+    });
+
     it('should parse valid DAG workflow YAML', async () => {
       const workflowDir = join(testDir, '.archon', 'workflows');
       await mkdir(workflowDir, { recursive: true });
@@ -206,9 +238,9 @@ nodes:
       const result = await discoverWorkflows(testDir, { loadDefaults: false });
       const workflows = result.workflows.map(ws => ws.workflow);
 
-      // Invalid provider treated as undefined - executor will fall back to config
+      // Unknown providers are accepted (validated against registry at execution time)
       expect(workflows).toHaveLength(1);
-      expect(workflows[0].provider).toBeUndefined();
+      expect(workflows[0].provider).toBe('invalid');
     });
 
     it('should reject claude model with codex provider at load time', async () => {
@@ -593,81 +625,223 @@ nodes:
     });
   });
 
-  describe('globalSearchPath loading', () => {
-    it('should load workflows from globalSearchPath and merge with local', async () => {
-      const globalDir = join(
-        tmpdir(),
-        `global-test-${Date.now()}-${Math.random().toString(36).slice(2)}`
-      );
-      const globalWorkflowDir = join(globalDir, '.archon', 'workflows');
-      const localWorkflowDir = join(testDir, '.archon', 'workflows');
+  describe('home-scoped workflows (~/.archon/workflows/)', () => {
+    // Home-scope is read unconditionally by discovery — no caller option. Tests
+    // redirect `getArchonHome()` to a temp dir via the `ARCHON_HOME` env var so
+    // they don't touch the user's real `~/.archon/`.
+    let homeDir: string;
+    const originalArchonHome = process.env.ARCHON_HOME;
+    const originalArchonDocker = process.env.ARCHON_DOCKER;
+
+    beforeEach(async () => {
+      homeDir = join(tmpdir(), `home-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+      await mkdir(homeDir, { recursive: true });
+      process.env.ARCHON_HOME = homeDir;
+      delete process.env.ARCHON_DOCKER;
+      // The deprecation warning uses a module-scoped flag; reset between tests
+      // so each case is independent.
+      const { resetLegacyHomeWarningForTests } = await import('./workflow-discovery');
+      resetLegacyHomeWarningForTests();
+      mockLogger.warn.mockClear();
+    });
+
+    afterEach(async () => {
+      try {
+        await rm(homeDir, { recursive: true, force: true });
+      } catch {
+        // ignore
+      }
+      if (originalArchonHome === undefined) {
+        delete process.env.ARCHON_HOME;
+      } else {
+        process.env.ARCHON_HOME = originalArchonHome;
+      }
+      if (originalArchonDocker === undefined) {
+        delete process.env.ARCHON_DOCKER;
+      } else {
+        process.env.ARCHON_DOCKER = originalArchonDocker;
+      }
+    });
 
-      await mkdir(globalWorkflowDir, { recursive: true });
-      await mkdir(localWorkflowDir, { recursive: true });
+    it('loads home-scoped workflows from ~/.archon/workflows/ and merges with repo', async () => {
+      const homeWorkflowDir = join(homeDir, 'workflows');
+      const repoWorkflowDir = join(testDir, '.archon', 'workflows');
+      await mkdir(homeWorkflowDir, { recursive: true });
+      await mkdir(repoWorkflowDir, { recursive: true });
 
       await writeFile(
-        join(globalWorkflowDir, 'global-wf.yaml'),
-        'name: global-workflow\ndescription: From global\nnodes:\n  - id: foo\n    command: foo\n'
+        join(homeWorkflowDir, 'home-wf.yaml'),
+        'name: home-workflow\ndescription: From home\nnodes:\n  - id: foo\n    command: foo\n'
       );
       await writeFile(
-        join(localWorkflowDir, 'local-wf.yaml'),
-        'name: local-workflow\ndescription: From local\nnodes:\n  - id: bar\n    command: bar\n'
+        join(repoWorkflowDir, 'repo-wf.yaml'),
+        'name: repo-workflow\ndescription: From repo\nnodes:\n  - id: bar\n    command: bar\n'
       );
 
-      const result = await discoverWorkflows(testDir, {
-        loadDefaults: false,
-        globalSearchPath: globalDir,
-      });
-
+      const result = await discoverWorkflows(testDir, { loadDefaults: false });
       const names = result.workflows.map(w => w.workflow.name);
-      expect(names).toContain('global-workflow');
-      expect(names).toContain('local-workflow');
+      expect(names).toContain('home-workflow');
+      expect(names).toContain('repo-workflow');
+    });
+
+    it("classifies home-scoped workflows as source: 'global'", async () => {
+      const homeWorkflowDir = join(homeDir, 'workflows');
+      await mkdir(homeWorkflowDir, { recursive: true });
+      await writeFile(
+        join(homeWorkflowDir, 'only-home.yaml'),
+        'name: only-home\ndescription: From home\nnodes:\n  - id: n\n    command: c\n'
+      );
 
-      await rm(globalDir, { recursive: true, force: true });
+      const result = await discoverWorkflows(testDir, { loadDefaults: false });
+      const entry = result.workflows.find(w => w.workflow.name === 'only-home');
+      expect(entry?.source).toBe('global');
     });
 
-    it('should allow local workflows to override global by filename', async () => {
-      const globalDir = join(
-        tmpdir(),
-        `global-test-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    it('repo workflow overrides home workflow with the same filename', async () => {
+      const homeWorkflowDir = join(homeDir, 'workflows');
+      const repoWorkflowDir = join(testDir, '.archon', 'workflows');
+      await mkdir(homeWorkflowDir, { recursive: true });
+      await mkdir(repoWorkflowDir, { recursive: true });
+
+      await writeFile(
+        join(homeWorkflowDir, 'shared.yaml'),
+        'name: home-version\ndescription: Home version\nnodes:\n  - id: h\n    command: c\n'
+      );
+      await writeFile(
+        join(repoWorkflowDir, 'shared.yaml'),
+        'name: repo-version\ndescription: Repo override\nnodes:\n  - id: r\n    command: c\n'
       );
-      const globalWorkflowDir = join(globalDir, '.archon', 'workflows');
-      const localWorkflowDir = join(testDir, '.archon', 'workflows');
 
-      await mkdir(globalWorkflowDir, { recursive: true });
-      await mkdir(localWorkflowDir, { recursive: true });
+      const result = await discoverWorkflows(testDir, { loadDefaults: false });
+      const shared = result.workflows.find(
+        w => w.workflow.name === 'home-version' || w.workflow.name === 'repo-version'
+      );
+      expect(shared?.workflow.name).toBe('repo-version');
+      expect(shared?.source).toBe('project');
+    });
+
+    it('silently skips when ~/.archon/workflows/ does not exist', async () => {
+      // homeDir exists but no workflows/ subdirectory — should not error.
+      const result = await discoverWorkflows(testDir, { loadDefaults: false });
+      expect(result.errors).toEqual([]);
+    });
 
+    it('supports 1-level subfolders under ~/.archon/workflows/ (e.g. triage/foo.yaml)', async () => {
+      const homeWorkflowDir = join(homeDir, 'workflows', 'triage');
+      await mkdir(homeWorkflowDir, { recursive: true });
       await writeFile(
-        join(globalWorkflowDir, 'shared.yaml'),
-        'name: global-version\ndescription: Global version\nnodes:\n  - id: global\n    command: global\n'
+        join(homeWorkflowDir, 'grouped.yaml'),
+        'name: grouped-workflow\ndescription: In a subfolder\nnodes:\n  - id: n\n    command: c\n'
       );
+
+      const result = await discoverWorkflows(testDir, { loadDefaults: false });
+      const entry = result.workflows.find(w => w.workflow.name === 'grouped-workflow');
+      expect(entry).toBeDefined();
+      expect(entry?.source).toBe('global');
+    });
+
+    it('does NOT descend past 1 level of subfolders (rejects workflows/a/b/foo.yaml)', async () => {
+      const nestedDir = join(homeDir, 'workflows', 'a', 'b');
+      await mkdir(nestedDir, { recursive: true });
       await writeFile(
-        join(localWorkflowDir, 'shared.yaml'),
-        'name: local-version\ndescription: Local override\nnodes:\n  - id: local\n    command: local\n'
+        join(nestedDir, 'too-deep.yaml'),
+        'name: too-deep\ndescription: Nested too deep\nnodes:\n  - id: n\n    command: c\n'
       );
 
-      const result = await discoverWorkflows(testDir, {
-        loadDefaults: false,
-        globalSearchPath: globalDir,
+      const result = await discoverWorkflows(testDir, { loadDefaults: false });
+      const entry = result.workflows.find(w => w.workflow.name === 'too-deep');
+      expect(entry).toBeUndefined();
+    });
+  });
+
+  describe('legacy ~/.archon/.archon/workflows/ deprecation warning', () => {
+    let homeDir: string;
+    const originalArchonHome = process.env.ARCHON_HOME;
+    const originalArchonDocker = process.env.ARCHON_DOCKER;
+
+    beforeEach(async () => {
+      homeDir = join(tmpdir(), `legacy-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+      await mkdir(homeDir, { recursive: true });
+      process.env.ARCHON_HOME = homeDir;
+      delete process.env.ARCHON_DOCKER;
+      const { resetLegacyHomeWarningForTests } = await import('./workflow-discovery');
+      resetLegacyHomeWarningForTests();
+      mockLogger.warn.mockClear();
+    });
+
+    afterEach(async () => {
+      try {
+        await rm(homeDir, { recursive: true, force: true });
+      } catch {
+        // ignore
+      }
+      if (originalArchonHome === undefined) {
+        delete process.env.ARCHON_HOME;
+      } else {
+        process.env.ARCHON_HOME = originalArchonHome;
+      }
+      if (originalArchonDocker === undefined) {
+        delete process.env.ARCHON_DOCKER;
+      } else {
+        process.env.ARCHON_DOCKER = originalArchonDocker;
+      }
+    });
+
+    it('emits a WARN with the migration command when the legacy path exists', async () => {
+      const legacyDir = join(homeDir, '.archon', 'workflows');
+      await mkdir(legacyDir, { recursive: true });
+      await writeFile(
+        join(legacyDir, 'stranded.yaml'),
+        'name: stranded\ndescription: At the old path\nnodes:\n  - id: n\n    command: c\n'
+      );
+
+      await discoverWorkflows(testDir, { loadDefaults: false });
+
+      const warnCalls = mockLogger.warn.mock.calls;
+      const legacyWarn = warnCalls.find(call => call[1] === 'workflow.legacy_home_path_detected');
+      expect(legacyWarn).toBeDefined();
+      expect(legacyWarn?.[0]).toMatchObject({
+        legacyPath: legacyDir,
+        newPath: join(homeDir, 'workflows'),
+        moveCommand: expect.stringContaining('mv'),
       });
+    });
 
-      // Local should override global by filename
-      const shared = result.workflows.find(
-        w => w.workflow.name === 'global-version' || w.workflow.name === 'local-version'
+    it('does NOT load workflows from the legacy path (clean cut)', async () => {
+      const legacyDir = join(homeDir, '.archon', 'workflows');
+      await mkdir(legacyDir, { recursive: true });
+      await writeFile(
+        join(legacyDir, 'stranded.yaml'),
+        'name: stranded\ndescription: At the old path\nnodes:\n  - id: n\n    command: c\n'
       );
-      expect(shared?.workflow.name).toBe('local-version');
 
-      await rm(globalDir, { recursive: true, force: true });
+      const result = await discoverWorkflows(testDir, { loadDefaults: false });
+      const stranded = result.workflows.find(w => w.workflow.name === 'stranded');
+      expect(stranded).toBeUndefined();
     });
 
-    it('should handle missing globalSearchPath gracefully', async () => {
-      const result = await discoverWorkflows(testDir, {
-        loadDefaults: false,
-        globalSearchPath: '/nonexistent/path',
-      });
+    it('warns exactly once per process, even across multiple discovery calls', async () => {
+      const legacyDir = join(homeDir, '.archon', 'workflows');
+      await mkdir(legacyDir, { recursive: true });
 
-      // Should not throw, just return whatever local workflows exist
-      expect(result.errors).toEqual([]);
+      await discoverWorkflows(testDir, { loadDefaults: false });
+      await discoverWorkflows(testDir, { loadDefaults: false });
+      await discoverWorkflows(testDir, { loadDefaults: false });
+
+      const warnCalls = mockLogger.warn.mock.calls.filter(
+        call => call[1] === 'workflow.legacy_home_path_detected'
+      );
+      expect(warnCalls).toHaveLength(1);
+    });
+
+    it('does not emit the warning when the legacy path is absent', async () => {
+      // No legacy directory created — warning should not fire.
+      await discoverWorkflows(testDir, { loadDefaults: false });
+
+      const warnCalls = mockLogger.warn.mock.calls.filter(
+        call => call[1] === 'workflow.legacy_home_path_detected'
+      );
+      expect(warnCalls).toHaveLength(0);
     });
   });
 
@@ -699,31 +873,48 @@ nodes:
       expect(archonWorkflow).toBeDefined();
     });
 
-    it('should pass globalSearchPath through to discoverWorkflows', async () => {
-      const { discoverWorkflowsWithConfig } = await import('./workflow-discovery');
-      const globalDir = join(
+    it('surfaces home-scoped workflows without any option — discovery reads ~/.archon/workflows/ internally', async () => {
+      const { discoverWorkflowsWithConfig, resetLegacyHomeWarningForTests } =
+        await import('./workflow-discovery');
+      resetLegacyHomeWarningForTests();
+
+      const homeDir = join(
         tmpdir(),
-        `global-test-${Date.now()}-${Math.random().toString(36).slice(2)}`
+        `home-test-${Date.now()}-${Math.random().toString(36).slice(2)}`
       );
-      const globalWorkflowDir = join(globalDir, '.archon', 'workflows');
-      await mkdir(globalWorkflowDir, { recursive: true });
+      const homeWorkflowDir = join(homeDir, 'workflows');
+      await mkdir(homeWorkflowDir, { recursive: true });
       await writeFile(
-        join(globalWorkflowDir, 'global-only.yaml'),
-        'name: global-only\ndescription: From global\nnodes:\n  - id: foo\n    command: foo\n'
+        join(homeWorkflowDir, 'home-only.yaml'),
+        'name: home-only\ndescription: From home\nnodes:\n  - id: foo\n    command: foo\n'
       );
 
-      const mockLoadConfig = mock(async () => ({
-        defaults: { loadDefaultWorkflows: false },
-      }));
-
-      const result = await discoverWorkflowsWithConfig(testDir, mockLoadConfig, {
-        globalSearchPath: globalDir,
-      });
-
-      const names = result.workflows.map(w => w.workflow.name);
-      expect(names).toContain('global-only');
-
-      await rm(globalDir, { recursive: true, force: true });
+      const originalArchonHome = process.env.ARCHON_HOME;
+      const originalArchonDocker = process.env.ARCHON_DOCKER;
+      process.env.ARCHON_HOME = homeDir;
+      delete process.env.ARCHON_DOCKER;
+      try {
+        const mockLoadConfig = mock(async () => ({
+          defaults: { loadDefaultWorkflows: false },
+        }));
+
+        const result = await discoverWorkflowsWithConfig(testDir, mockLoadConfig);
+        const entry = result.workflows.find(w => w.workflow.name === 'home-only');
+        expect(entry).toBeDefined();
+        expect(entry?.source).toBe('global');
+      } finally {
+        if (originalArchonHome === undefined) {
+          delete process.env.ARCHON_HOME;
+        } else {
+          process.env.ARCHON_HOME = originalArchonHome;
+        }
+        if (originalArchonDocker === undefined) {
+          delete process.env.ARCHON_DOCKER;
+        } else {
+          process.env.ARCHON_DOCKER = originalArchonDocker;
+        }
+        await rm(homeDir, { recursive: true, force: true });
+      }
     });
   });
 
@@ -1277,6 +1468,82 @@ nodes:
       expect(node.provider).toBeUndefined();
       expect(node.model).toBeUndefined();
     });
+
+    it('should NOT warn about model/provider on loop nodes (they are supported)', async () => {
+      const workflowDir = join(testDir, '.archon', 'workflows');
+      await mkdir(workflowDir, { recursive: true });
+
+      await writeFile(
+        join(workflowDir, 'loop-model.yaml'),
+        `
+name: loop-model
+description: Loop with model override
+nodes:
+  - id: iterate
+    loop:
+      prompt: "Do something"
+      until: "COMPLETE"
+      max_iterations: 3
+    provider: claude
+    model: claude-opus-4-6
+`
+      );
+
+      (mockLogger.warn as Mock<() => undefined>).mockClear();
+      const result = await discoverWorkflows(testDir, { loadDefaults: false });
+      expect(result.errors).toHaveLength(0);
+      expect(result.workflows).toHaveLength(1);
+
+      const node = result.workflows[0].workflow.nodes[0];
+      expect(isLoopNode(node)).toBe(true);
+
+      // model and provider should NOT trigger a warning
+      const warnCalls = (mockLogger.warn as Mock<() => undefined>).mock.calls;
+      const aiFieldWarnings = warnCalls.filter(
+        call => typeof call[1] === 'string' && call[1].includes('ai_fields_ignored')
+      );
+      expect(aiFieldWarnings).toHaveLength(0);
+    });
+
+    it('should warn about unsupported AI fields on loop nodes (not model/provider)', async () => {
+      const workflowDir = join(testDir, '.archon', 'workflows');
+      await mkdir(workflowDir, { recursive: true });
+
+      await writeFile(
+        join(workflowDir, 'loop-unsupported.yaml'),
+        `
+name: loop-unsupported
+description: Loop with unsupported AI fields
+nodes:
+  - id: iterate
+    loop:
+      prompt: "Do something"
+      until: "COMPLETE"
+      max_iterations: 3
+    model: claude-opus-4-6
+    output_format:
+      type: object
+      properties:
+        status:
+          type: string
+`
+      );
+
+      (mockLogger.warn as Mock<() => undefined>).mockClear();
+      const result = await discoverWorkflows(testDir, { loadDefaults: false });
+      expect(result.errors).toHaveLength(0);
+
+      // Should warn about output_format but NOT about model
+      const warnCalls = (mockLogger.warn as Mock<() => undefined>).mock.calls;
+      const aiFieldWarnings = warnCalls.filter(
+        call => typeof call[1] === 'string' && call[1].includes('ai_fields_ignored')
+      );
+      expect(aiFieldWarnings).toHaveLength(1);
+      const warnedFields = (aiFieldWarnings[0][0] as { fields: string[] }).fields;
+      expect(warnedFields).toContain('output_format');
+      expect(warnedFields).not.toContain('model');
+      expect(warnedFields).not.toContain('provider');
+    });
   });
 
   describe('DAG output ref validation', () => {
diff --git a/packages/workflows/src/loader.ts b/packages/workflows/src/loader.ts
index 0fd93cce1f..e4d53bfdc2 100644
--- a/packages/workflows/src/loader.ts
+++ b/packages/workflows/src/loader.ts
@@ -5,7 +5,12 @@ import type { WorkflowDefinition, WorkflowLoadError, DagNode, WorkflowNodeHooks
 import { isLoopNode, isApprovalNode, isCancelNode, isScriptNode } from './schemas';
 import { createLogger } from '@archon/paths';
 import { isModelCompatible } from './model-validation';
-import { dagNodeSchema, BASH_NODE_AI_FIELDS, SCRIPT_NODE_AI_FIELDS } from './schemas/dag-node';
+import {
+  dagNodeSchema,
+  BASH_NODE_AI_FIELDS,
+  SCRIPT_NODE_AI_FIELDS,
+  LOOP_NODE_AI_FIELDS,
+} from './schemas/dag-node';
 import { modelReasoningEffortSchema, webSearchModeSchema } from './schemas/workflow';
 import { workflowNodeHooksSchema } from './schemas/hooks';
 import { z } from '@hono/zod-openapi';
@@ -56,26 +61,25 @@ function parseDagNode(raw: unknown, index: number, errors: string[]): DagNode |
   const node = result.data;
 
   // Warn about AI-specific fields on non-AI nodes (runtime behavior, not schema errors)
-  const isNonAiNode =
-    ('bash' in node && typeof node.bash === 'string') ||
-    isScriptNode(node) ||
-    isLoopNode(node) ||
-    isApprovalNode(node) ||
-    isCancelNode(node);
-  if (isNonAiNode) {
-    let nodeType: string;
-    if (isCancelNode(node)) {
-      nodeType = 'cancel';
-    } else if (isApprovalNode(node)) {
-      nodeType = 'approval';
-    } else if (isLoopNode(node)) {
-      nodeType = 'loop';
-    } else if (isScriptNode(node)) {
-      nodeType = 'script';
-    } else {
-      nodeType = 'bash';
-    }
-    const aiFields = isScriptNode(node) ? SCRIPT_NODE_AI_FIELDS : BASH_NODE_AI_FIELDS;
+  let nodeType: string | undefined;
+  let aiFields: readonly string[] | undefined;
+  if (isCancelNode(node)) {
+    nodeType = 'cancel';
+    aiFields = BASH_NODE_AI_FIELDS;
+  } else if (isApprovalNode(node)) {
+    nodeType = 'approval';
+    aiFields = BASH_NODE_AI_FIELDS;
+  } else if (isLoopNode(node)) {
+    nodeType = 'loop';
+    aiFields = LOOP_NODE_AI_FIELDS;
+  } else if (isScriptNode(node)) {
+    nodeType = 'script';
+    aiFields = SCRIPT_NODE_AI_FIELDS;
+  } else if ('bash' in node && typeof node.bash === 'string') {
+    nodeType = 'bash';
+    aiFields = BASH_NODE_AI_FIELDS;
+  }
+  if (nodeType !== undefined && aiFields !== undefined) {
     const presentAiFields = aiFields.filter(f => (raw as Record<string, unknown>)[f] !== undefined);
     if (presentAiFields.length > 0) {
       getLog().warn({ id: node.id, fields: presentAiFields }, `${nodeType}_node_ai_fields_ignored`);
@@ -271,7 +275,7 @@ export function parseWorkflow(content: string, filename: string): ParseResult {
     // Note: modelReasoningEffort and webSearchMode use warn-and-ignore for invalid values
     // (consistent with original behavior) rather than schema-level rejection.
     const provider =
-      raw.provider === 'claude' || raw.provider === 'codex' ? raw.provider : undefined;
+      typeof raw.provider === 'string' && raw.provider.length > 0 ? raw.provider : undefined;
     const model = typeof raw.model === 'string' ? raw.model : undefined;
 
     // Validate model/provider compatibility at workflow level
@@ -335,6 +339,28 @@ export function parseWorkflow(content: string, filename: string): ParseResult {
       }
     }
 
+    // Parse workflow-level worktree policy. Same warn-and-ignore pattern used
+    // for `interactive` / `modelReasoningEffort` — invalid values are dropped
+    // rather than rejected, so a typo in one workflow doesn't nuke the whole
+    // discovery pass. Only `worktree.enabled` is recognised today.
+    let worktreePolicy: { enabled?: boolean } | undefined;
+    if (raw.worktree !== undefined) {
+      if (
+        typeof raw.worktree === 'object' &&
+        raw.worktree !== null &&
+        !Array.isArray(raw.worktree)
+      ) {
+        const rawEnabled = (raw.worktree as Record<string, unknown>).enabled;
+        if (typeof rawEnabled === 'boolean') {
+          worktreePolicy = { enabled: rawEnabled };
+        } else if (rawEnabled !== undefined) {
+          getLog().warn({ filename, value: rawEnabled }, 'invalid_worktree_enabled_value_ignored');
+        }
+      } else {
+        getLog().warn({ filename, value: raw.worktree }, 'invalid_worktree_block_ignored');
+      }
+    }
+
     return {
       workflow: {
         name: raw.name,
@@ -346,6 +372,7 @@ export function parseWorkflow(content: string, filename: string): ParseResult {
         additionalDirectories,
         interactive,
         nodes: dagNodes,
+        ...(worktreePolicy ? { worktree: worktreePolicy } : {}),
       },
       error: null,
     };
diff --git a/packages/workflows/src/model-validation.test.ts b/packages/workflows/src/model-validation.test.ts
index a73b7586aa..2247fd7c05 100644
--- a/packages/workflows/src/model-validation.test.ts
+++ b/packages/workflows/src/model-validation.test.ts
@@ -1,33 +1,14 @@
-import { describe, it, expect } from 'bun:test';
-import { isClaudeModel, isModelCompatible } from './model-validation';
+import { describe, it, expect, beforeAll } from 'bun:test';
+import { registerBuiltinProviders, clearRegistry } from '@archon/providers';
+import { isModelCompatible, inferProviderFromModel } from './model-validation';
 
-describe('model-validation', () => {
-  describe('isClaudeModel', () => {
-    it('should recognize Claude aliases', () => {
-      expect(isClaudeModel('sonnet')).toBe(true);
-      expect(isClaudeModel('opus')).toBe(true);
-      expect(isClaudeModel('haiku')).toBe(true);
-      expect(isClaudeModel('inherit')).toBe(true);
-    });
-
-    it('should recognize claude- prefixed models', () => {
-      expect(isClaudeModel('claude-sonnet-4-5-20250929')).toBe(true);
-      expect(isClaudeModel('claude-opus-4-6')).toBe(true);
-      expect(isClaudeModel('claude-3-5-sonnet-20241022')).toBe(true);
-    });
-
-    it('should reject non-Claude models', () => {
-      expect(isClaudeModel('gpt-5.3-codex')).toBe(false);
-      expect(isClaudeModel('gpt-5.2-codex')).toBe(false);
-      expect(isClaudeModel('gpt-4')).toBe(false);
-      expect(isClaudeModel('o1-mini')).toBe(false);
-    });
-
-    it('should reject empty string', () => {
-      expect(isClaudeModel('')).toBe(false);
-    });
-  });
+// Bootstrap registry once for all tests (idempotent)
+beforeAll(() => {
+  clearRegistry();
+  registerBuiltinProviders();
+});
 
+describe('model-validation (registry-driven)', () => {
   describe('isModelCompatible', () => {
     it('should accept any model when model is undefined', () => {
       expect(isModelCompatible('claude')).toBe(true);
@@ -65,5 +46,35 @@ describe('model-validation', () => {
       expect(isModelCompatible('claude', '')).toBe(true);
       expect(isModelCompatible('codex', '')).toBe(true);
     });
+
+    it('should throw on unknown providers (fail-fast)', () => {
+      expect(() => isModelCompatible('my-llm', 'any-model')).toThrow(/Unknown provider 'my-llm'/);
+    });
+  });
+
+  describe('inferProviderFromModel', () => {
+    it('should return default when model is undefined', () => {
+      expect(inferProviderFromModel(undefined, 'claude')).toBe('claude');
+      expect(inferProviderFromModel(undefined, 'codex')).toBe('codex');
+    });
+
+    it('should return default when model is empty string', () => {
+      expect(inferProviderFromModel('', 'claude')).toBe('claude');
+      expect(inferProviderFromModel('', 'codex')).toBe('codex');
+    });
+
+    it('should infer claude from Claude model names', () => {
+      expect(inferProviderFromModel('sonnet', 'codex')).toBe('claude');
+      expect(inferProviderFromModel('opus', 'codex')).toBe('claude');
+      expect(inferProviderFromModel('haiku', 'codex')).toBe('claude');
+      expect(inferProviderFromModel('inherit', 'codex')).toBe('claude');
+      expect(inferProviderFromModel('claude-opus-4-6', 'codex')).toBe('claude');
+    });
+
+    it('should infer codex from non-Claude model names', () => {
+      expect(inferProviderFromModel('gpt-5.3-codex', 'claude')).toBe('codex');
+      expect(inferProviderFromModel('gpt-4', 'claude')).toBe('codex');
+      expect(inferProviderFromModel('o1-mini', 'claude')).toBe('codex');
+    });
   });
 });
diff --git a/packages/workflows/src/model-validation.ts b/packages/workflows/src/model-validation.ts
index b035582717..0140defce5 100644
--- a/packages/workflows/src/model-validation.ts
+++ b/packages/workflows/src/model-validation.ts
@@ -1,16 +1,41 @@
-export function isClaudeModel(model: string): boolean {
-  return (
-    model === 'sonnet' ||
-    model === 'opus' ||
-    model === 'haiku' ||
-    model === 'inherit' ||
-    model.startsWith('claude-')
-  );
+/**
+ * Registry-driven model validation.
+ *
+ * All provider/model compatibility checks delegate to ProviderRegistration entries
+ * in the provider registry. No hardcoded provider knowledge lives here.
+ */
+import { getRegistration, getRegisteredProviders, isRegisteredProvider } from '@archon/providers';
+
+/**
+ * Infer provider from a model name by iterating BUILT-IN registrations only.
+ * Community providers must be selected explicitly via `provider:` in YAML.
+ *
+ * Returns undefined if no built-in provider matches (caller falls back to config default).
+ */
+export function inferProviderFromModel(model: string | undefined, defaultProvider: string): string {
+  if (!model) return defaultProvider;
+
+  for (const reg of getRegisteredProviders()) {
+    if (reg.builtIn && reg.isModelCompatible(model)) return reg.id;
+  }
+
+  // No built-in matched — fall back to default
+  return defaultProvider;
 }
 
-export function isModelCompatible(provider: 'claude' | 'codex', model?: string): boolean {
+/**
+ * Check if a model is compatible with a provider using the registry.
+ * Returns true if no model is specified (any provider accepts no-model).
+ * Throws on unknown providers (fail-fast — matches getProviderCapabilities behavior).
+ */
+export function isModelCompatible(provider: string, model?: string): boolean {
   if (!model) return true;
-  if (provider === 'claude') return isClaudeModel(model);
-  // Codex: accept most models, but reject obvious Claude aliases/prefixes
-  return !isClaudeModel(model);
+  if (!isRegisteredProvider(provider)) {
+    throw new Error(
+      `Unknown provider '${provider}'. Registered providers: ${getRegisteredProviders()
+        .map(p => p.id)
+        .join(', ')}`
+    );
+  }
+  return getRegistration(provider).isModelCompatible(model);
 }
diff --git a/packages/workflows/src/schemas.test.ts b/packages/workflows/src/schemas.test.ts
index 9e1e343723..3d0332bd16 100644
--- a/packages/workflows/src/schemas.test.ts
+++ b/packages/workflows/src/schemas.test.ts
@@ -6,6 +6,7 @@ import {
   isTriggerRule,
   TRIGGER_RULES,
   SCRIPT_NODE_AI_FIELDS,
+  LOOP_NODE_AI_FIELDS,
   approvalOnRejectSchema,
   dagNodeSchema,
 } from './schemas';
@@ -661,3 +662,36 @@ describe('SCRIPT_NODE_AI_FIELDS', () => {
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// LOOP_NODE_AI_FIELDS constant
+// ---------------------------------------------------------------------------
+
+describe('LOOP_NODE_AI_FIELDS', () => {
+  test('excludes model and provider (loop nodes support them)', () => {
+    expect(LOOP_NODE_AI_FIELDS).not.toContain('model');
+    expect(LOOP_NODE_AI_FIELDS).not.toContain('provider');
+  });
+
+  test('contains all other AI-specific fields from BASH_NODE_AI_FIELDS', () => {
+    const expectedFields = [
+      'context',
+      'output_format',
+      'allowed_tools',
+      'denied_tools',
+      'hooks',
+      'mcp',
+      'skills',
+      'effort',
+      'thinking',
+      'maxBudgetUsd',
+      'systemPrompt',
+      'fallbackModel',
+      'betas',
+      'sandbox',
+    ];
+    for (const field of expectedFields) {
+      expect(LOOP_NODE_AI_FIELDS).toContain(field);
+    }
+  });
+});
diff --git a/packages/workflows/src/schemas/dag-node.ts b/packages/workflows/src/schemas/dag-node.ts
index 82bd90ac86..d41c6270c3 100644
--- a/packages/workflows/src/schemas/dag-node.ts
+++ b/packages/workflows/src/schemas/dag-node.ts
@@ -106,6 +106,26 @@ export const sandboxSettingsSchema = z
 
 export type SandboxSettings = z.infer<typeof sandboxSettingsSchema>;
 
+/**
+ * Claude Agent SDK AgentDefinition — inline sub-agent available via the Task tool.
+ * Mirrors the SDK's AgentDefinition type (sdk.d.ts), minus mcpServers and the
+ * experimental critical-reminder field.
+ */
+export const agentDefinitionSchema = z.object({
+  description: z.string().min(1, "'description' is required"),
+  prompt: z.string().min(1, "'prompt' is required"),
+  model: z.string().min(1).optional(),
+  tools: z.array(z.string().min(1)).optional(),
+  disallowedTools: z.array(z.string().min(1)).optional(),
+  skills: z.array(z.string().min(1)).optional(),
+  maxTurns: z.number().int().positive().optional(),
+});
+
+export type AgentDefinition = z.infer<typeof agentDefinitionSchema>;
+
+// Kebab-case: no leading/trailing/double hyphens (e.g. `brief-gen`, not `-brief`, `brief-`, `brief--gen`).
+const AGENT_ID_REGEX = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
 // ---------------------------------------------------------------------------
 // DagNodeBase — common fields shared by all node types
 // ---------------------------------------------------------------------------
@@ -116,7 +136,7 @@ export const dagNodeBaseSchema = z.object({
   when: z.string().optional(),
   trigger_rule: triggerRuleSchema.optional(),
   model: z.string().optional(),
-  provider: z.enum(['claude', 'codex']).optional(),
+  provider: z.string().trim().min(1).optional(),
   context: z.enum(['fresh', 'shared']).optional(),
   output_format: z.record(z.unknown()).optional(),
   allowed_tools: z.array(z.string()).optional(),
@@ -129,6 +149,13 @@ export const dagNodeBaseSchema = z.object({
     .array(z.string().min(1, 'each skill must be a non-empty string'))
     .nonempty("'skills' must be a non-empty array")
     .optional(),
+  agents: z
+    .record(
+      z.string().regex(AGENT_ID_REGEX, 'agent IDs must be kebab-case (a-z, 0-9, hyphen)'),
+      agentDefinitionSchema
+    )
+    .refine(map => Object.keys(map).length > 0, "'agents' must have at least one entry")
+    .optional(),
   effort: effortLevelSchema.optional(),
   thinking: thinkingConfigSchema.optional(),
   maxBudgetUsd: z.number().positive().optional(),
@@ -291,10 +318,10 @@ export type DagNode =
   | ScriptNode;
 
 // ---------------------------------------------------------------------------
-// AI-specific fields that are meaningless on bash/loop nodes
+// AI-specific fields that are meaningless on non-AI nodes
 // ---------------------------------------------------------------------------
 
-/** AI-specific fields that are meaningless on bash/loop nodes — exported for loader warnings */
+/** AI-specific fields that are meaningless on bash nodes — exported for loader warnings */
 export const BASH_NODE_AI_FIELDS: readonly string[] = [
   'provider',
   'model',
@@ -305,6 +332,7 @@ export const BASH_NODE_AI_FIELDS: readonly string[] = [
   'hooks',
   'mcp',
   'skills',
+  'agents',
   'effort',
   'thinking',
   'maxBudgetUsd',
@@ -317,6 +345,15 @@ export const BASH_NODE_AI_FIELDS: readonly string[] = [
 /** AI-specific fields that are meaningless on script nodes — same as bash nodes */
 export const SCRIPT_NODE_AI_FIELDS: readonly string[] = BASH_NODE_AI_FIELDS;
 
+/**
+ * AI-specific fields that are unsupported on loop nodes.
+ * `model` and `provider` are excluded because the DAG executor resolves and
+ * forwards them to each iteration's AI call (see dag-executor.ts:2602-2648).
+ */
+export const LOOP_NODE_AI_FIELDS: readonly string[] = BASH_NODE_AI_FIELDS.filter(
+  f => f !== 'model' && f !== 'provider'
+);
+
 // ---------------------------------------------------------------------------
 // dagNodeSchema — flat validation schema with transform to DagNode
 // ---------------------------------------------------------------------------
@@ -488,10 +525,18 @@ export const dagNodeSchema = dagNodeBaseSchema
 
     // Provider/model compatibility (AI nodes only)
     if (!hasBash && !hasLoop && !hasScript && data.provider && data.model) {
-      if (!isModelCompatible(data.provider, data.model)) {
+      try {
+        if (!isModelCompatible(data.provider, data.model)) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `model "${data.model}" is not compatible with provider "${data.provider}"`,
+          });
+        }
+      } catch (e) {
+        // isModelCompatible throws on unknown providers — surface as a validation issue
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
-          message: `model "${data.model}" is not compatible with provider "${data.provider}"`,
+          message: (e as Error).message,
         });
       }
     }
@@ -526,6 +571,7 @@ export const dagNodeSchema = dagNodeBaseSchema
       ...(data.hooks !== undefined ? { hooks: data.hooks } : {}),
       ...(data.mcp !== undefined ? { mcp: data.mcp.trim() } : {}),
       ...(data.skills !== undefined ? { skills: data.skills.map(s => s.trim()) } : {}),
+      ...(data.agents !== undefined ? { agents: data.agents } : {}),
       ...(data.effort !== undefined ? { effort: data.effort } : {}),
       ...(data.thinking !== undefined ? { thinking: data.thinking } : {}),
       ...(data.maxBudgetUsd !== undefined ? { maxBudgetUsd: data.maxBudgetUsd } : {}),
diff --git a/packages/workflows/src/schemas/index.ts b/packages/workflows/src/schemas/index.ts
index 3fe10b562d..ec44084ac9 100644
--- a/packages/workflows/src/schemas/index.ts
+++ b/packages/workflows/src/schemas/index.ts
@@ -47,9 +47,11 @@ export {
   isTriggerRule,
   BASH_NODE_AI_FIELDS,
   SCRIPT_NODE_AI_FIELDS,
+  LOOP_NODE_AI_FIELDS,
   effortLevelSchema,
   thinkingConfigSchema,
   sandboxSettingsSchema,
+  agentDefinitionSchema,
 } from './dag-node';
 export type {
   TriggerRule,
@@ -66,6 +68,7 @@ export type {
   EffortLevel,
   ThinkingConfig,
   SandboxSettings,
+  AgentDefinition,
 } from './dag-node';
 
 // Workflow definition
diff --git a/packages/workflows/src/schemas/workflow.ts b/packages/workflows/src/schemas/workflow.ts
index 008ef19a8f..40771af578 100644
--- a/packages/workflows/src/schemas/workflow.ts
+++ b/packages/workflows/src/schemas/workflow.ts
@@ -22,6 +22,33 @@ export const webSearchModeSchema = z.enum(['disabled', 'cached', 'live']);
 
 export type WebSearchMode = z.infer<typeof webSearchModeSchema>;
 
+// ---------------------------------------------------------------------------
+// Workflow-level worktree policy
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-workflow worktree policy. Pins whether a run uses isolation regardless of
+ * how it was invoked (CLI flags, web UI, chat). When the field is omitted the
+ * caller's default applies — worktree for task/issue/pr, etc.
+ *
+ * Currently one field (`enabled`). Other worktree-shaped settings (copyFiles,
+ * initSubmodules, path, baseBranch) live in repo-level `.archon/config.yaml`
+ * because they are repo-wide, not per-workflow. This block is deliberately
+ * narrow to avoid re-expressing the repo-level knobs here.
+ */
+export const workflowWorktreePolicySchema = z.object({
+  /**
+   * Pin worktree isolation on or off for this workflow.
+   * - `true`  — always run inside a worktree; CLI `--no-worktree` hard-errors
+   * - `false` — always run in the live checkout; CLI `--branch` / `--from`
+   *             hard-error, orchestrator skips isolation resolution
+   * - omitted — caller decides (current default = worktree for most types)
+   */
+  enabled: z.boolean().optional(),
+});
+
+export type WorkflowWorktreePolicy = z.infer<typeof workflowWorktreePolicySchema>;
+
 // ---------------------------------------------------------------------------
 // WorkflowBase — common fields shared by all workflow types
 // ---------------------------------------------------------------------------
@@ -29,7 +56,7 @@ export type WebSearchMode = z.infer<typeof webSearchModeSchema>;
 export const workflowBaseSchema = z.object({
   name: z.string().min(1),
   description: z.string().min(1),
-  provider: z.enum(['claude', 'codex']).optional(),
+  provider: z.string().trim().min(1).optional(),
   model: z.string().optional(),
   modelReasoningEffort: modelReasoningEffortSchema.optional(),
   webSearchMode: webSearchModeSchema.optional(),
@@ -40,6 +67,7 @@ export const workflowBaseSchema = z.object({
   fallbackModel: z.string().min(1).optional(),
   betas: z.array(z.string().min(1)).nonempty("'betas' must be a non-empty array").optional(),
   sandbox: sandboxSettingsSchema.optional(),
+  worktree: workflowWorktreePolicySchema.optional(),
 });
 
 export type WorkflowBase = z.infer<typeof workflowBaseSchema>;
@@ -92,8 +120,15 @@ export type WorkflowExecutionResult =
 // WorkflowLoadError / WorkflowLoadResult — workflow discovery results
 // ---------------------------------------------------------------------------
 
-/** Workflow origin — bundled default or project-defined. */
-export type WorkflowSource = 'bundled' | 'project';
+/**
+ * Workflow origin:
+ * - `bundled` — embedded in the Archon binary / bundled defaults
+ * - `global`  — user-level, discovered at `~/.archon/workflows/` (applies to every repo)
+ * - `project` — repo-local, discovered at `<repoRoot>/.archon/workflows/`
+ *
+ * Precedence for same-named files: `bundled` < `global` < `project`.
+ */
+export type WorkflowSource = 'bundled' | 'global' | 'project';
 
 /** A workflow definition paired with its discovery source. */
 export interface WorkflowWithSource {
diff --git a/packages/workflows/src/script-discovery.test.ts b/packages/workflows/src/script-discovery.test.ts
index 18bc9c58ef..2171d0a948 100644
--- a/packages/workflows/src/script-discovery.test.ts
+++ b/packages/workflows/src/script-discovery.test.ts
@@ -18,9 +18,19 @@ const mockLogger = {
   debug: mock(() => undefined),
   trace: mock(() => undefined),
 };
-mock.module('@archon/paths', () => ({ createLogger: mock(() => mockLogger) }));
+let mockHomeScriptsPath = '/home/scripts';
+mock.module('@archon/paths', () => ({
+  createLogger: mock(() => mockLogger),
+  getHomeScriptsPath: mock(() => mockHomeScriptsPath),
+}));
+
+import { discoverScripts, discoverScriptsForCwd, getDefaultScripts } from './script-discovery';
 
-import { discoverScripts, getDefaultScripts } from './script-discovery';
+// On Windows, path.join produces backslashes (e.g. `\scripts\triage`). The
+// mocks below key on forward-slash paths for readability, so normalize before
+// comparing. Production paths are stored via normalizeSep(), so assertions on
+// stored paths remain forward-slash on every OS.
+const norm = (p: string): string => p.replaceAll('\\', '/');
 
 describe('discoverScripts', () => {
   beforeEach(() => {
@@ -159,6 +169,106 @@ describe('discoverScripts', () => {
   });
 });
 
+describe('scanScriptDir depth cap', () => {
+  // Scripts are discovered 1 level deep (matches the workflows/commands
+  // convention). `defaults/` style subfolders are fine; nested subfolders are not.
+  beforeEach(() => {
+    mockReaddir.mockReset();
+    mockStat.mockReset();
+  });
+
+  test('allows files in a 1-level subfolder', async () => {
+    mockReaddir.mockImplementation(async (path: string) => {
+      const p = norm(path);
+      if (p === '/scripts') return ['triage', 'top.ts'];
+      if (p === '/scripts/triage') return ['helper.py'];
+      return [];
+    });
+    mockStat.mockImplementation(async (path: string) => ({
+      isDirectory: () => norm(path) === '/scripts/triage',
+    }));
+
+    const result = await discoverScripts('/scripts');
+    expect(result.has('top')).toBe(true);
+    expect(result.has('helper')).toBe(true);
+  });
+
+  test('does NOT descend into nested subfolders (cap at depth 1)', async () => {
+    mockReaddir.mockImplementation(async (path: string) => {
+      const p = norm(path);
+      if (p === '/scripts') return ['level-one'];
+      if (p === '/scripts/level-one') return ['level-two'];
+      if (p === '/scripts/level-one/level-two') return ['too-deep.ts'];
+      return [];
+    });
+    mockStat.mockImplementation(async (path: string) => {
+      const p = norm(path);
+      return {
+        isDirectory: () => p === '/scripts/level-one' || p === '/scripts/level-one/level-two',
+      };
+    });
+
+    const result = await discoverScripts('/scripts');
+    expect(result.has('too-deep')).toBe(false);
+    expect(result.size).toBe(0);
+  });
+});
+
+describe('discoverScriptsForCwd — merge repo + home with repo winning', () => {
+  beforeEach(() => {
+    mockReaddir.mockReset();
+    mockStat.mockReset();
+    mockHomeScriptsPath = '/home/scripts';
+  });
+
+  test('merges scripts from ~/.archon/scripts and <cwd>/.archon/scripts', async () => {
+    mockReaddir.mockImplementation(async (path: string) => {
+      const p = norm(path);
+      if (p === '/home/scripts') return ['home-only.ts'];
+      if (p === '/repo/.archon/scripts') return ['repo-only.py'];
+      return [];
+    });
+    mockStat.mockResolvedValue({ isDirectory: () => false });
+
+    const result = await discoverScriptsForCwd('/repo');
+    expect(result.has('home-only')).toBe(true);
+    expect(result.has('repo-only')).toBe(true);
+    expect(result.size).toBe(2);
+  });
+
+  test('repo-scoped script overrides same-named home script', async () => {
+    mockReaddir.mockImplementation(async (path: string) => {
+      const p = norm(path);
+      if (p === '/home/scripts') return ['shared.ts'];
+      if (p === '/repo/.archon/scripts') return ['shared.ts'];
+      return [];
+    });
+    mockStat.mockResolvedValue({ isDirectory: () => false });
+
+    const result = await discoverScriptsForCwd('/repo');
+    expect(result.size).toBe(1);
+    // Stored paths are normalized to forward slashes via normalizeSep() in
+    // script-discovery.ts, so this assertion is OS-independent.
+    expect(result.get('shared')!.path).toBe('/repo/.archon/scripts/shared.ts');
+  });
+
+  test('tolerates missing home dir (new user, no personal scripts yet)', async () => {
+    mockReaddir.mockImplementation(async (path: string) => {
+      const p = norm(path);
+      if (p === '/home/scripts') {
+        throw Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+      }
+      if (p === '/repo/.archon/scripts') return ['only-repo.ts'];
+      return [];
+    });
+    mockStat.mockResolvedValue({ isDirectory: () => false });
+
+    const result = await discoverScriptsForCwd('/repo');
+    expect(result.size).toBe(1);
+    expect(result.has('only-repo')).toBe(true);
+  });
+});
+
 describe('getDefaultScripts', () => {
   test('returns an empty Map', () => {
     const defaults = getDefaultScripts();
diff --git a/packages/workflows/src/script-discovery.ts b/packages/workflows/src/script-discovery.ts
index ce74b1a3bb..7ba8be056d 100644
--- a/packages/workflows/src/script-discovery.ts
+++ b/packages/workflows/src/script-discovery.ts
@@ -6,7 +6,7 @@
  */
 import { readdir, stat } from 'fs/promises';
 import { join, basename, extname } from 'path';
-import { createLogger } from '@archon/paths';
+import { createLogger, getHomeScriptsPath } from '@archon/paths';
 
 /** Normalize path separators to forward slashes for cross-platform consistency */
 function normalizeSep(p: string): string {
@@ -46,12 +46,24 @@ function getRuntimeForExtension(ext: string): ScriptRuntime | undefined {
 }
 
 /**
- * Recursively scan a directory and return all script files with their names, paths, and runtimes.
- * Skips files with unknown extensions. Throws on duplicate script names.
+ * Maximum subfolder depth we descend into when scanning scripts.
+ *
+ * `1` matches the workflows/commands convention: allow one level of
+ * grouping (e.g. `.archon/scripts/triage/foo.ts`) but no nested folders.
+ * We stop at 1 deliberately — deeper nesting has never been part of the
+ * documented convention and adds no organizational value, just routing
+ * ambiguity when two basenames collide across folders.
+ */
+const MAX_SCRIPT_DISCOVERY_DEPTH = 1;
+
+/**
+ * Scan a directory for script files, descending at most `MAX_SCRIPT_DISCOVERY_DEPTH`
+ * folders deep. Skips files with unknown extensions. Throws on duplicate script names.
  */
 async function scanScriptDir(
   dirPath: string,
-  scripts: Map<string, ScriptDefinition>
+  scripts: Map<string, ScriptDefinition>,
+  depth = 0
 ): Promise<void> {
   let entries: string[];
   try {
@@ -79,7 +91,10 @@ async function scanScriptDir(
     }
 
     if (entryStat.isDirectory()) {
-      await scanScriptDir(entryPath, scripts);
+      // 1-depth cap: allow one level of grouping (e.g. `.archon/scripts/triage/foo.ts`)
+      // but stop there. Matches the workflows/commands convention — no nested folders.
+      if (depth >= MAX_SCRIPT_DISCOVERY_DEPTH) continue;
+      await scanScriptDir(entryPath, scripts, depth + 1);
       continue;
     }
 
@@ -109,7 +124,7 @@ async function scanScriptDir(
 /**
  * Discover scripts from a directory (expected to be .archon/scripts/ or equivalent).
  * Returns a Map of script name -> ScriptDefinition.
- * Throws if duplicate script names are found across different extensions.
+ * Throws if duplicate script names are found across different extensions within the directory.
  * Returns an empty Map if the directory does not exist.
  */
 export async function discoverScripts(dir: string): Promise<Map<string, ScriptDefinition>> {
@@ -119,6 +134,33 @@ export async function discoverScripts(dir: string): Promise<Map<string, ScriptDe
   return scripts;
 }
 
+/**
+ * Discover scripts across all scopes for a given repo cwd.
+ *
+ * Resolution order (repo wins on same-name collision — matches the
+ * workflows/commands precedence):
+ *   1. `<cwd>/.archon/scripts/` — repo-scoped (`source: 'project'` equivalent)
+ *   2. `~/.archon/scripts/`    — home-scoped (`source: 'global'` equivalent)
+ *
+ * Within a single scope, duplicate basenames across extensions still throw
+ * (matches `discoverScripts` behavior). Across scopes, the repo-level entry
+ * silently overrides the home-level one.
+ */
+export async function discoverScriptsForCwd(cwd: string): Promise<Map<string, ScriptDefinition>> {
+  const homeScripts = await discoverScripts(getHomeScriptsPath());
+  const repoScripts = await discoverScripts(join(cwd, '.archon', 'scripts'));
+
+  // Start with home, overlay repo (repo wins)
+  const merged = new Map<string, ScriptDefinition>(homeScripts);
+  for (const [name, def] of repoScripts) {
+    if (merged.has(name)) {
+      getLog().debug({ name }, 'script.repo_overrides_home');
+    }
+    merged.set(name, def);
+  }
+  return merged;
+}
+
 /**
  * Returns bundled default scripts (empty — no bundled scripts for now).
  * Follows the bundled-defaults.ts pattern for future extensibility.
diff --git a/packages/workflows/src/script-node-deps.test.ts b/packages/workflows/src/script-node-deps.test.ts
index 5387daf029..1c1fbf5a81 100644
--- a/packages/workflows/src/script-node-deps.test.ts
+++ b/packages/workflows/src/script-node-deps.test.ts
@@ -109,7 +109,7 @@ const mockSendQuery = mock(function* () {
   yield { type: 'result', sessionId: 'session-id' };
 });
 
-const mockGetAssistantClient = mock(() => ({
+const mockGetAgentProvider = mock(() => ({
   sendQuery: mockSendQuery,
   getType: () => 'claude',
 }));
@@ -117,7 +117,7 @@ const mockGetAssistantClient = mock(() => ({
 function createMockDeps(): WorkflowDeps {
   return {
     store: createMockStore(),
-    getAssistantClient: mockGetAssistantClient,
+    getAgentProvider: mockGetAgentProvider,
     loadConfig: mock(() =>
       Promise.resolve({
         assistant: 'claude' as const,
@@ -173,7 +173,7 @@ describe('script node deps field — command construction', () => {
     await mkdir(testDir, { recursive: true });
     mockExecFileAsync.mockClear();
     mockSendQuery.mockClear();
-    mockGetAssistantClient.mockClear();
+    mockGetAgentProvider.mockClear();
   });
 
   afterEach(async () => {
@@ -287,7 +287,7 @@ describe('script node deps field — command construction', () => {
     expect(args).toEqual(['run', 'python', '-c', 'print("no deps")']);
   });
 
-  it('bun inline with deps uses bun -e (no extra flags — bun auto-installs)', async () => {
+  it('bun inline with deps uses bun --no-env-file -e (no extra dep flags — bun auto-installs)', async () => {
     const node: ScriptNode = {
       id: 'bun-with-deps',
       script: 'import { z } from "zod"; console.log(z.string().parse("hello"))',
@@ -316,13 +316,13 @@ describe('script node deps field — command construction', () => {
     expect(scriptCall).toBeDefined();
     const [cmd, args] = scriptCall as [string, string[]];
     expect(cmd).toBe('bun');
-    // No --packages or extra flags — bun auto-installs at runtime
-    expect(args).toEqual(['-e', node.script]);
+    // --no-env-file prevents repo .env auto-load; no dep flags — bun auto-installs
+    expect(args).toEqual(['--no-env-file', '-e', node.script]);
     expect(args).not.toContain('--packages');
     expect(args).not.toContain('--with');
   });
 
-  it('bun inline without deps uses bun -e (no extra flags)', async () => {
+  it('bun inline without deps uses bun --no-env-file -e', async () => {
     const node: ScriptNode = {
       id: 'bun-no-deps',
       script: 'console.log("hello")',
@@ -350,7 +350,7 @@ describe('script node deps field — command construction', () => {
     expect(scriptCall).toBeDefined();
     const [cmd, args] = scriptCall as [string, string[]];
     expect(cmd).toBe('bun');
-    expect(args).toEqual(['-e', 'console.log("hello")']);
+    expect(args).toEqual(['--no-env-file', '-e', 'console.log("hello")']);
   });
 
   it('uv named script with deps uses uv run --with flags', async () => {
diff --git a/packages/workflows/src/store.ts b/packages/workflows/src/store.ts
index 9d9a85e275..16d9e39826 100644
--- a/packages/workflows/src/store.ts
+++ b/packages/workflows/src/store.ts
@@ -43,7 +43,26 @@ export interface IWorkflowStore {
     parent_conversation_id?: string;
   }): Promise<WorkflowRun>;
   getWorkflowRun(id: string): Promise<WorkflowRun | null>;
-  getActiveWorkflowRunByPath(workingPath: string): Promise<WorkflowRun | null>;
+  /**
+   * Find the workflow run currently holding the lock on `workingPath`.
+   *
+   * Pass `self` from the calling dispatch so:
+   *   1. Self is never returned (excluded by `id != self.id`).
+   *   2. Two near-simultaneous dispatches deterministically agree on which
+   *      is "first" via the `(started_at, id)` tiebreaker — newer aborts.
+   *
+   * `id` and `startedAt` must travel together — the tiebreaker requires
+   * both. Bundling them as a single optional struct makes the
+   * paired-or-nothing invariant structural rather than a doc-only contract.
+   *
+   * Stale `pending` rows (older than ~5 minutes) are treated as orphaned
+   * and ignored, so leaks from crashed dispatches don't permanently block
+   * a path.
+   */
+  getActiveWorkflowRunByPath(
+    workingPath: string,
+    self?: { id: string; startedAt: Date }
+  ): Promise<WorkflowRun | null>;
   findResumableRun(workflowName: string, workingPath: string): Promise<WorkflowRun | null>;
   failOrphanedRuns(): Promise<{ count: number }>;
   resumeWorkflowRun(id: string): Promise<WorkflowRun>;
diff --git a/packages/workflows/src/utils/duration.test.ts b/packages/workflows/src/utils/duration.test.ts
new file mode 100644
index 0000000000..9d51ace51a
--- /dev/null
+++ b/packages/workflows/src/utils/duration.test.ts
@@ -0,0 +1,74 @@
+import { describe, test, expect } from 'bun:test';
+import { formatDuration, parseDbTimestamp } from './duration';
+
+describe('formatDuration', () => {
+  test('rounds 0ms up to "1s" — a run that just started should not display "0s"', () => {
+    // 0ms in practice means started_at and now are in the same DB second.
+    // Display should show "1s" (active, just started), not the misleading "0s".
+    expect(formatDuration(0)).toBe('1s');
+  });
+
+  test('rounds sub-second to "1s" so display never reads "0s" for an active run', () => {
+    expect(formatDuration(500)).toBe('1s');
+    expect(formatDuration(999)).toBe('1s');
+  });
+
+  test('formats whole seconds', () => {
+    expect(formatDuration(1000)).toBe('1s');
+    expect(formatDuration(45000)).toBe('45s');
+  });
+
+  test('formats minutes with seconds remainder', () => {
+    expect(formatDuration(60000)).toBe('1m');
+    expect(formatDuration(65000)).toBe('1m 5s');
+    expect(formatDuration(125000)).toBe('2m 5s');
+  });
+
+  test('formats hours with minutes remainder', () => {
+    expect(formatDuration(3600000)).toBe('1h');
+    expect(formatDuration(3660000)).toBe('1h 1m');
+    expect(formatDuration(7320000)).toBe('2h 2m');
+  });
+
+  test('drops seconds at the hour level so display stays compact', () => {
+    expect(formatDuration(3661000)).toBe('1h 1m'); // not "1h 1m 1s"
+  });
+
+  test('clamps negative values to "0s"', () => {
+    expect(formatDuration(-1)).toBe('0s');
+    expect(formatDuration(-10000)).toBe('0s');
+  });
+
+  test('clamps non-finite values to "0s"', () => {
+    expect(formatDuration(NaN)).toBe('0s');
+    expect(formatDuration(Infinity)).toBe('0s');
+  });
+});
+
+describe('parseDbTimestamp', () => {
+  test('returns Date.getTime() unchanged for Date inputs (PG driver path)', () => {
+    const date = new Date('2026-04-14T10:00:00.000Z');
+    expect(parseDbTimestamp(date)).toBe(date.getTime());
+  });
+
+  test('treats SQLite "YYYY-MM-DD HH:MM:SS" as UTC, not local', () => {
+    // Reproduces the live bug — SQLite returns datetimes without `Z`,
+    // and `new Date('2026-04-14 10:00:00')` parses as local time, making
+    // the duration display hours off depending on the user's TZ.
+    const sqliteFormat = '2026-04-14 10:00:00';
+    expect(parseDbTimestamp(sqliteFormat)).toBe(new Date('2026-04-14T10:00:00Z').getTime());
+  });
+
+  test('respects explicit Z suffix (ISO UTC)', () => {
+    expect(parseDbTimestamp('2026-04-14T10:00:00.000Z')).toBe(
+      new Date('2026-04-14T10:00:00Z').getTime()
+    );
+  });
+
+  test('respects explicit timezone offset (+/-HH:MM)', () => {
+    // 10:00 UTC = 12:00+02:00
+    expect(parseDbTimestamp('2026-04-14T12:00:00+02:00')).toBe(
+      new Date('2026-04-14T10:00:00Z').getTime()
+    );
+  });
+});
diff --git a/packages/workflows/src/utils/duration.ts b/packages/workflows/src/utils/duration.ts
new file mode 100644
index 0000000000..d0be3ddc47
--- /dev/null
+++ b/packages/workflows/src/utils/duration.ts
@@ -0,0 +1,47 @@
+/**
+ * Parse a timestamp value that may be either a Date (PG driver) or a string
+ * (SQLite returns datetimes as strings without timezone). SQLite's CURRENT_TIMESTAMP
+ * stores UTC but the returned string has no `Z` suffix, so plain `new Date(str)`
+ * would parse it as local time — appearing hours off depending on the user's TZ.
+ *
+ * Returns ms since epoch.
+ */
+export function parseDbTimestamp(value: Date | string): number {
+  if (value instanceof Date) return value.getTime();
+  // Heuristic: if the string already encodes a timezone (Z, +HH:MM, -HH:MM
+  // after the time portion), trust it. Otherwise treat as UTC.
+  const hasTimezone = /[zZ]$|[+-]\d{2}:?\d{2}$/.test(value);
+  return new Date(hasTimezone ? value : `${value.replace(' ', 'T')}Z`).getTime();
+}
+
+/**
+ * Format a millisecond duration as a short human-readable string.
+ *
+ * Examples:
+ *   500 → "1s" (sub-second rounded up to avoid showing "0s")
+ *   1500 → "1s"
+ *   65000 → "1m 5s"
+ *   3700000 → "1h 1m"
+ *
+ * Negative values are clamped to 0 ("0s"). Designed for UI display, not
+ * precise time deltas — drops sub-second precision and seconds at the
+ * hour-level.
+ */
+export function formatDuration(ms: number): string {
+  if (!Number.isFinite(ms) || ms < 0) return '0s';
+
+  // Round sub-second (including ms === 0 — treated as a just-started run
+  // rather than literal zero) up to 1s so an active run never displays "0s".
+  const totalSeconds = Math.max(1, Math.floor(ms / 1000));
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+
+  if (hours > 0) {
+    return minutes > 0 ? `${String(hours)}h ${String(minutes)}m` : `${String(hours)}h`;
+  }
+  if (minutes > 0) {
+    return seconds > 0 ? `${String(minutes)}m ${String(seconds)}s` : `${String(minutes)}m`;
+  }
+  return `${String(seconds)}s`;
+}
diff --git a/packages/workflows/src/validator.test.ts b/packages/workflows/src/validator.test.ts
index 9a8c8979ba..bd2b418e17 100644
--- a/packages/workflows/src/validator.test.ts
+++ b/packages/workflows/src/validator.test.ts
@@ -2,6 +2,12 @@ import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
 import { mkdtemp, mkdir, writeFile, rm } from 'fs/promises';
 import { join } from 'path';
 import { tmpdir } from 'os';
+import { registerBuiltinProviders, clearRegistry } from '@archon/providers';
+
+// Bootstrap provider registry (needed by capability-driven warnings in validator)
+clearRegistry();
+registerBuiltinProviders();
+
 import {
   levenshtein,
   findSimilar,
@@ -25,11 +31,7 @@ afterEach(async () => {
   await rm(tmpDir, { recursive: true, force: true });
 });
 
-function makeWorkflow(
-  name: string,
-  nodes: DagNode[],
-  provider?: 'claude' | 'codex'
-): WorkflowDefinition {
+function makeWorkflow(name: string, nodes: DagNode[], provider?: string): WorkflowDefinition {
   return {
     name,
     description: 'test workflow',
@@ -221,7 +223,7 @@ describe('validateWorkflowResources — MCP validation', () => {
     const issues = await validateWorkflowResources(workflow, tmpDir);
     const mcpWarnings = issues.filter(i => i.field === 'mcp' && i.level === 'warning');
     expect(mcpWarnings).toHaveLength(1);
-    expect(mcpWarnings[0].message).toContain('Claude-only');
+    expect(mcpWarnings[0].message).toContain('not supported by provider');
   });
 });
 
@@ -288,6 +290,61 @@ describe('discoverAvailableCommands', () => {
     const without = await discoverAvailableCommands(tmpDir, { loadDefaultCommands: false });
     expect(withDefaults.length).toBeGreaterThanOrEqual(without.length);
   });
+
+  // --- Home-scoped commands (~/.archon/commands/) — new capability
+  describe('home-scoped commands', () => {
+    let homeDir: string;
+    const originalArchonHome = process.env.ARCHON_HOME;
+    const originalArchonDocker = process.env.ARCHON_DOCKER;
+
+    beforeEach(async () => {
+      homeDir = await mkdtemp(join(tmpdir(), 'validator-home-'));
+      process.env.ARCHON_HOME = homeDir;
+      delete process.env.ARCHON_DOCKER;
+    });
+
+    afterEach(async () => {
+      await rm(homeDir, { recursive: true, force: true });
+      if (originalArchonHome === undefined) {
+        delete process.env.ARCHON_HOME;
+      } else {
+        process.env.ARCHON_HOME = originalArchonHome;
+      }
+      if (originalArchonDocker === undefined) {
+        delete process.env.ARCHON_DOCKER;
+      } else {
+        process.env.ARCHON_DOCKER = originalArchonDocker;
+      }
+    });
+
+    async function createHomeCommand(name: string, content = '# Home helper'): Promise<void> {
+      const dir = join(homeDir, 'commands');
+      await mkdir(dir, { recursive: true });
+      await writeFile(join(dir, `${name}.md`), content);
+    }
+
+    test('discovers commands placed at ~/.archon/commands/', async () => {
+      await createHomeCommand('my-personal-helper');
+      const commands = await discoverAvailableCommands(tmpDir, { loadDefaultCommands: false });
+      expect(commands).toContain('my-personal-helper');
+    });
+
+    test('resolveCommand (via validateCommand) finds home-scoped commands when repo has none', async () => {
+      await createHomeCommand('only-in-home');
+      const result = await validateCommand('only-in-home', tmpDir, { loadDefaultCommands: false });
+      expect(result.valid).toBe(true);
+    });
+
+    test('repo command overrides home command with the same name', async () => {
+      await createHomeCommand('shared', '# Home version');
+      await createCommandFile('shared', '# Repo version');
+      // Both resolve but the repo wins — validator only asserts existence, so the
+      // strong behavioral assertion lives in the executor-shared loadCommand tests.
+      // Here we just confirm that having both doesn't error.
+      const result = await validateCommand('shared', tmpDir, { loadDefaultCommands: false });
+      expect(result.valid).toBe(true);
+    });
+  });
 });
 
 // =============================================================================
@@ -342,3 +399,48 @@ describe('validateWorkflowResources — script nodes', () => {
     expect(scriptErrors).toHaveLength(0);
   });
 });
+
+// =============================================================================
+// validateWorkflowResources — inline agents capability warning
+// =============================================================================
+
+describe('validateWorkflowResources — agents capability', () => {
+  const agentsField = {
+    'brief-gen': { description: 'd', prompt: 'p' },
+  };
+
+  test('warns when provider does not support inline agents (codex)', async () => {
+    const workflow = makeWorkflow(
+      'test',
+      [{ id: 'step1', prompt: 'p', agents: agentsField } as unknown as DagNode],
+      'codex'
+    );
+    const issues = await validateWorkflowResources(workflow, tmpDir);
+    const warning = issues.find(i => i.level === 'warning' && i.field === 'agents');
+    expect(warning).toBeDefined();
+    expect(warning!.message).toContain("not supported by provider 'codex'");
+    expect(warning!.hint).toContain('claude');
+  });
+
+  test('no agents-capability warning when provider is claude', async () => {
+    const workflow = makeWorkflow(
+      'test',
+      [{ id: 'step1', prompt: 'p', agents: agentsField } as unknown as DagNode],
+      'claude'
+    );
+    const issues = await validateWorkflowResources(workflow, tmpDir);
+    const warning = issues.find(i => i.level === 'warning' && i.field === 'agents');
+    expect(warning).toBeUndefined();
+  });
+
+  test('no warning when node has no agents field', async () => {
+    const workflow = makeWorkflow(
+      'test',
+      [{ id: 'step1', prompt: 'p' } as unknown as DagNode],
+      'codex'
+    );
+    const issues = await validateWorkflowResources(workflow, tmpDir);
+    const warning = issues.find(i => i.level === 'warning' && i.field === 'agents');
+    expect(warning).toBeUndefined();
+  });
+});
diff --git a/packages/workflows/src/validator.ts b/packages/workflows/src/validator.ts
index be0011763c..88cebeef84 100644
--- a/packages/workflows/src/validator.ts
+++ b/packages/workflows/src/validator.ts
@@ -16,11 +16,13 @@ import {
   createLogger,
   getCommandFolderSearchPaths,
   getDefaultCommandsPath,
+  getHomeCommandsPath,
   findMarkdownFilesRecursive,
 } from '@archon/paths';
 import { execFileAsync } from '@archon/git';
 import { BUNDLED_COMMANDS, isBinaryBuild } from './defaults/bundled-defaults';
 import { isValidCommandName } from './command-validation';
+import { getProviderCapabilities, isRegisteredProvider } from '@archon/providers';
 
 /** Lazy-initialized logger */
 let cachedLog: ReturnType<typeof createLogger> | undefined;
@@ -31,7 +33,7 @@ function getLog(): ReturnType<typeof createLogger> {
 import { isScriptNode } from './schemas';
 import type { WorkflowDefinition, DagNode } from './schemas';
 import type { ScriptRuntime } from './script-discovery';
-import { discoverScripts } from './script-discovery';
+import { discoverScriptsForCwd } from './script-discovery';
 import { isInlineScript } from './executor-shared';
 
 // =============================================================================
@@ -140,17 +142,33 @@ export async function discoverAvailableCommands(
 ): Promise<string[]> {
   const names = new Set<string>();
 
-  // Repo search paths (findMarkdownFilesRecursive returns [] for ENOENT)
+  // Each scope is walked 1 subfolder deep (matches the workflows/scripts
+  // discovery convention — supports `defaults/` grouping, rejects deeper nesting).
+
+  // 1. Repo search paths
   const searchPaths = getCommandFolderSearchPaths(config?.commandFolder);
   for (const folder of searchPaths) {
     const dirPath = join(cwd, folder);
-    const files = await findMarkdownFilesRecursive(dirPath);
+    const files = await findMarkdownFilesRecursive(dirPath, '', { maxDepth: 1 });
     for (const { commandName } of files) {
       names.add(commandName);
     }
   }
 
-  // Bundled defaults
+  // 2. Home-scoped commands (~/.archon/commands/) — personal helpers reusable across repos.
+  // ENOENT already returns []; we only catch other errors (EACCES/EPERM/EIO) so a broken
+  // home-scope doesn't take down repo/bundled discovery.
+  const homePath = getHomeCommandsPath();
+  try {
+    const homeCommands = await findMarkdownFilesRecursive(homePath, '', { maxDepth: 1 });
+    for (const { commandName } of homeCommands) {
+      names.add(commandName);
+    }
+  } catch (err) {
+    getLog().warn({ err, path: homePath }, 'commands.home_discovery_failed');
+  }
+
+  // 3. Bundled defaults
   const loadDefaults = config?.loadDefaultCommands !== false;
   if (loadDefaults) {
     if (isBinaryBuild()) {
@@ -159,7 +177,7 @@ export async function discoverAvailableCommands(
       }
     } else {
       const defaultsPath = getDefaultCommandsPath();
-      const files = await findMarkdownFilesRecursive(defaultsPath);
+      const files = await findMarkdownFilesRecursive(defaultsPath, '', { maxDepth: 1 });
       for (const { commandName } of files) {
         names.add(commandName);
       }
@@ -169,25 +187,58 @@ export async function discoverAvailableCommands(
   return [...names].sort();
 }
 
+/**
+ * Resolve a command name to a file path within a single directory, walking at
+ * most 1 subfolder deep. Returns the first `.md` file whose basename matches
+ * `commandName`, or `null` if nothing matches.
+ *
+ * Within a single scope, if two files in different subfolders share a basename
+ * (e.g. `triage/review.md` and `team/review.md`), the earlier match by the
+ * deterministic walk order wins — duplicates within a scope are a user error.
+ */
+async function resolveCommandInDir(rootDir: string, commandName: string): Promise<string | null> {
+  const entries = await findMarkdownFilesRecursive(rootDir, '', { maxDepth: 1 });
+  const match = entries.find(e => e.commandName === commandName);
+  return match ? join(rootDir, match.relativePath) : null;
+}
+
 /**
  * Check if a command file can be resolved via the standard search paths.
  * Returns the resolved path if found, null otherwise.
+ *
+ * Resolution precedence (first hit wins):
+ *   1. Repo-local — `<cwd>/.archon/commands/` and configured folders
+ *   2. Home-scoped — `~/.archon/commands/` (personal helpers, reusable across repos)
+ *   3. Bundled defaults — embedded in the binary or the app's defaults folder
  */
 async function resolveCommand(
   commandName: string,
   cwd: string,
   config?: ValidationConfig
 ): Promise<string | null> {
-  // Repo search paths
+  // Each scope is walked 1 subfolder deep by basename — so `triage/review.md`
+  // is resolvable as `review`. This matches the workflows/scripts discovery
+  // convention and makes the listed commands in `discoverAvailableCommands`
+  // actually resolvable.
+
+  // 1. Repo search paths
   const searchPaths = getCommandFolderSearchPaths(config?.commandFolder);
   for (const folder of searchPaths) {
-    const filePath = join(cwd, folder, `${commandName}.md`);
-    if (await fileExists(filePath)) {
-      return filePath;
-    }
+    const resolved = await resolveCommandInDir(join(cwd, folder), commandName);
+    if (resolved) return resolved;
   }
 
-  // Bundled defaults
+  // 2. Home-scoped commands (~/.archon/commands/).
+  // ENOENT on the home dir already returns null; only wrap for other errors so a
+  // broken home-scope doesn't prevent bundled-default resolution.
+  try {
+    const homeResolved = await resolveCommandInDir(getHomeCommandsPath(), commandName);
+    if (homeResolved) return homeResolved;
+  } catch (err) {
+    getLog().warn({ err, commandName }, 'commands.home_resolve_failed');
+  }
+
+  // 3. Bundled defaults
   const loadDefaults = config?.loadDefaultCommands !== false;
   if (loadDefaults) {
     if (isBinaryBuild()) {
@@ -195,10 +246,8 @@ async function resolveCommand(
         return `[bundled:${commandName}]`;
       }
     } else {
-      const defaultsPath = join(getDefaultCommandsPath(), `${commandName}.md`);
-      if (await fileExists(defaultsPath)) {
-        return defaultsPath;
-      }
+      const defaultsResolved = await resolveCommandInDir(getDefaultCommandsPath(), commandName);
+      if (defaultsResolved) return defaultsResolved;
     }
   }
 
@@ -243,10 +292,15 @@ export async function checkRuntimeAvailable(runtime: ScriptRuntime): Promise<boo
 // Workflow resource validation (Level 3)
 // =============================================================================
 
-/** Get the resolved provider for a node (node-level > workflow-level) */
-function resolveProvider(node: DagNode, workflowProvider?: string): string {
+/** Get the resolved provider for a node (node-level > workflow-level > config default).
+ *  Returns undefined only when no provider is set at any level. */
+function resolveProvider(
+  node: DagNode,
+  workflowProvider?: string,
+  defaultProvider?: string
+): string | undefined {
   if ('provider' in node && node.provider) return node.provider;
-  return workflowProvider ?? 'claude';
+  return workflowProvider ?? defaultProvider;
 }
 
 /**
@@ -258,13 +312,14 @@ function resolveProvider(node: DagNode, workflowProvider?: string): string {
 export async function validateWorkflowResources(
   workflow: WorkflowDefinition,
   cwd: string,
-  config?: ValidationConfig
+  config?: ValidationConfig,
+  defaultProvider?: string
 ): Promise<ValidationIssue[]> {
   const issues: ValidationIssue[] = [];
   const availableCommands = await discoverAvailableCommands(cwd, config);
 
   for (const node of workflow.nodes) {
-    const provider = resolveProvider(node, workflow.provider);
+    const provider = resolveProvider(node, workflow.provider, defaultProvider);
 
     // --- Command nodes: check file exists ---
     if ('command' in node && typeof node.command === 'string') {
@@ -335,15 +390,18 @@ export async function validateWorkflowResources(
         }
       }
 
-      // Warn if using MCP with Codex
-      if (provider === 'codex') {
-        issues.push({
-          level: 'warning',
-          nodeId: node.id,
-          field: 'mcp',
-          message: 'MCP servers are Claude-only per-node — this will be ignored on Codex',
-          hint: 'For Codex, configure MCP servers globally in ~/.codex/config.toml instead',
-        });
+      // Warn if using MCP with a provider that doesn't support it
+      if (provider && isRegisteredProvider(provider)) {
+        const caps = getProviderCapabilities(provider);
+        if (!caps.mcp) {
+          issues.push({
+            level: 'warning',
+            nodeId: node.id,
+            field: 'mcp',
+            message: `MCP servers are not supported by provider '${provider}' — this will be ignored`,
+            hint: 'Remove the mcp field or switch to a provider that supports MCP',
+          });
+        }
       }
     }
 
@@ -367,65 +425,82 @@ export async function validateWorkflowResources(
         }
       }
 
-      // Warn if using skills with Codex
-      if (provider === 'codex') {
+      // Warn if using skills with a provider that doesn't support them
+      if (provider && isRegisteredProvider(provider)) {
+        const caps = getProviderCapabilities(provider);
+        if (!caps.skills) {
+          issues.push({
+            level: 'warning',
+            nodeId: node.id,
+            field: 'skills',
+            message: `Skills are not supported by provider '${provider}' — this will be ignored`,
+            hint: 'Remove the skills field or switch to a provider that supports skills',
+          });
+        }
+      }
+    }
+
+    // --- Capability-driven warnings for hooks and tool restrictions ---
+    if (provider && isRegisteredProvider(provider)) {
+      const caps = getProviderCapabilities(provider);
+
+      if ('hooks' in node && node.hooks && !caps.hooks) {
         issues.push({
           level: 'warning',
           nodeId: node.id,
-          field: 'skills',
-          message: 'Skills are Claude-only per-node — this will be ignored on Codex',
-          hint: 'For Codex, place skills in ~/.agents/skills/ for global discovery instead',
+          field: 'hooks',
+          message: `Hooks are not supported by provider '${provider}' — this will be ignored`,
+          hint: 'Remove the hooks field or switch to a provider that supports hooks',
         });
       }
-    }
-
-    // --- Hooks with Codex warning ---
-    if ('hooks' in node && node.hooks && provider === 'codex') {
-      issues.push({
-        level: 'warning',
-        nodeId: node.id,
-        field: 'hooks',
-        message: 'Hooks are Claude-only — this will be ignored on Codex',
-        hint: 'Hooks have no Codex equivalent. Remove them or switch to provider: claude',
-      });
-    }
 
-    // --- Tool restrictions with Codex warning ---
-    if (provider === 'codex') {
-      if (
-        ('allowed_tools' in node && node.allowed_tools !== undefined) ||
-        ('denied_tools' in node && node.denied_tools !== undefined)
-      ) {
+      if ('agents' in node && node.agents && !caps.agents) {
         issues.push({
           level: 'warning',
           nodeId: node.id,
-          field: 'allowed_tools/denied_tools',
-          message: 'Tool restrictions are Claude-only — this will be ignored on Codex',
-          hint: 'For Codex, configure tool restrictions per MCP server in ~/.codex/config.toml',
+          field: 'agents',
+          message: `Inline agents are not supported by provider '${provider}' — this will be ignored`,
+          hint: 'Remove the agents field or switch to a provider that supports inline agents (e.g. claude)',
         });
       }
+
+      if (!caps.toolRestrictions) {
+        if (
+          ('allowed_tools' in node && node.allowed_tools !== undefined) ||
+          ('denied_tools' in node && node.denied_tools !== undefined)
+        ) {
+          issues.push({
+            level: 'warning',
+            nodeId: node.id,
+            field: 'allowed_tools/denied_tools',
+            message: `Tool restrictions are not supported by provider '${provider}' — this will be ignored`,
+            hint: 'Remove tool restriction fields or switch to a provider that supports them',
+          });
+        }
+      }
     }
 
     // --- Script nodes: check named script file exists + runtime available ---
     if (isScriptNode(node)) {
       const script = node.script;
 
-      // Named script: validate file exists in .archon/scripts/
+      // Named script: validate file exists in repo or home scope.
+      // Precedence mirrors dag-executor: repo > home. Subfolders up to 1 level deep
+      // are searched by discoverScriptsForCwd, matching the workflows/commands convention.
       if (!isInlineScript(script)) {
-        const scriptsDir = resolve(cwd, '.archon', 'scripts');
-        const extensions = node.runtime === 'uv' ? ['.py'] : ['.ts', '.js'];
-        const existsResults = await Promise.all(
-          extensions.map(ext => fileExists(join(scriptsDir, `${script}${ext}`)))
-        );
-        const scriptExists = existsResults.some(Boolean);
+        const scripts = await discoverScriptsForCwd(cwd);
+        const entry = scripts.get(script);
+        const scriptExists =
+          entry !== undefined &&
+          (node.runtime === 'uv' ? entry.runtime === 'uv' : entry.runtime === 'bun');
 
         if (!scriptExists) {
           issues.push({
             level: 'error',
             nodeId: node.id,
             field: 'script',
-            message: `Named script '${script}' not found in .archon/scripts/`,
-            hint: `Create .archon/scripts/${script}.${node.runtime === 'uv' ? 'py' : 'ts'} with your script code`,
+            message: `Named script '${script}' not found in .archon/scripts/ or ~/.archon/scripts/`,
+            hint: `Create .archon/scripts/${script}.${node.runtime === 'uv' ? 'py' : 'ts'} with your script code (or place at ~/.archon/scripts/ to share across repos)`,
           });
         }
       }
@@ -542,19 +617,19 @@ export interface ScriptValidationResult {
 }
 
 /**
- * Discover all script names from .archon/scripts/ in the given cwd.
- * Returns a list of { name, path, runtime } entries.
+ * Discover all script names from the repo and home scopes.
+ * Returns a list of { name, path, runtime } entries. Repo-scoped scripts
+ * silently override same-named home-scoped entries.
  */
 export async function discoverAvailableScripts(
   cwd: string
 ): Promise<{ name: string; path: string; runtime: ScriptRuntime }[]> {
-  const scriptsDir = resolve(cwd, '.archon', 'scripts');
   try {
-    const scripts = await discoverScripts(scriptsDir);
+    const scripts = await discoverScriptsForCwd(cwd);
     return [...scripts.values()].map(s => ({ name: s.name, path: s.path, runtime: s.runtime }));
   } catch (error) {
     const err = error as Error;
-    getLog().warn({ err, scriptsDir }, 'script_discovery_failed');
+    getLog().warn({ err, cwd }, 'script_discovery_failed');
     return [];
   }
 }
@@ -567,28 +642,21 @@ export async function validateScript(
   cwd: string
 ): Promise<ScriptValidationResult> {
   const issues: ValidationIssue[] = [];
-  const scriptsDir = resolve(cwd, '.archon', 'scripts');
-
-  // Find the script file (any supported extension)
-  const allExtensions = ['.ts', '.js', '.py'];
-  let foundPath: string | null = null;
-  let detectedRuntime: ScriptRuntime | null = null;
-
-  for (const ext of allExtensions) {
-    const candidate = join(scriptsDir, `${scriptName}${ext}`);
-    if (await fileExists(candidate)) {
-      foundPath = candidate;
-      detectedRuntime = ext === '.py' ? 'uv' : 'bun';
-      break;
-    }
-  }
+
+  // Look up across repo + home scopes (repo wins). discoverScriptsForCwd handles
+  // both 1-depth subfolders and the repo/home precedence.
+  const scripts = await discoverScriptsForCwd(cwd);
+  const entry = scripts.get(scriptName);
+
+  const foundPath = entry?.path ?? null;
+  const detectedRuntime = entry?.runtime ?? null;
 
   if (!foundPath || !detectedRuntime) {
     issues.push({
       level: 'error',
       field: 'file',
-      message: `Script '${scriptName}' not found in .archon/scripts/`,
-      hint: `Create .archon/scripts/${scriptName}.ts (bun) or .archon/scripts/${scriptName}.py (uv)`,
+      message: `Script '${scriptName}' not found in .archon/scripts/ or ~/.archon/scripts/`,
+      hint: `Create .archon/scripts/${scriptName}.ts (bun) or .archon/scripts/${scriptName}.py (uv). Place at ~/.archon/scripts/ to share across repos.`,
     });
     return { scriptName, valid: false, issues };
   }
diff --git a/packages/workflows/src/workflow-discovery.ts b/packages/workflows/src/workflow-discovery.ts
index bcd5d531ce..188ca9d751 100644
--- a/packages/workflows/src/workflow-discovery.ts
+++ b/packages/workflows/src/workflow-discovery.ts
@@ -6,6 +6,15 @@
  * full discoverWorkflows entry point.
  *
  * Imports parseWorkflow from loader.ts (parsing concern stays there).
+ *
+ * Scopes (precedence lowest → highest):
+ *   1. `bundled` — embedded in the Archon binary (or read from the app's
+ *      defaults folder in source mode).
+ *   2. `global`  — home-scoped at `~/.archon/workflows/`. Applies to every
+ *      repo; discovered automatically (no caller option needed).
+ *   3. `project` — repo-local at `<cwd>/.archon/workflows/`.
+ *
+ * Same-named files at a higher scope override those at lower scopes.
  */
 import { readFile, readdir, access, stat } from 'fs/promises';
 import { join } from 'path';
@@ -27,16 +36,64 @@ function getLog(): ReturnType<typeof createLogger> {
   return cachedLog;
 }
 
+/**
+ * One-time deprecation warning for the pre-refactor `~/.archon/.archon/workflows/`
+ * location. Scoped to the process so the warning fires exactly once regardless
+ * of how many times discovery runs.
+ *
+ * The legacy path is ONLY probed for detection — workflows placed there are not
+ * read. Users migrate manually via the `mv` command printed in the warning.
+ * Exported so tests can reset it between cases.
+ */
+let hasWarnedLegacyHomePath = false;
+export function resetLegacyHomeWarningForTests(): void {
+  hasWarnedLegacyHomePath = false;
+}
+
+async function maybeWarnLegacyHomePath(): Promise<void> {
+  if (hasWarnedLegacyHomePath) return;
+  // Set the flag eagerly so concurrent discovery calls (e.g. parallel codebase
+  // resolution at server startup) can't both pass the guard and double-warn.
+  hasWarnedLegacyHomePath = true;
+
+  const legacyPath = archonPaths.getLegacyHomeWorkflowsPath();
+  const newPath = archonPaths.getHomeWorkflowsPath();
+  try {
+    await access(legacyPath);
+  } catch (error) {
+    const err = error as NodeJS.ErrnoException;
+    if (err.code === 'ENOENT') return; // happy path — legacy location not in use
+    // EACCES/EPERM/EIO: directory exists but we can't read it. Surface at WARN
+    // so the user sees it — silent debug would hide a real permission issue.
+    getLog().warn({ err, legacyPath }, 'workflow.legacy_home_path_probe_error');
+    return;
+  }
+  // Legacy directory exists — surface an actionable migration hint exactly once.
+  const moveCommand = `mv "${legacyPath}" "${newPath}" && rmdir "${join(archonPaths.getArchonHome(), '.archon')}"`;
+  getLog().warn({ legacyPath, newPath, moveCommand }, 'workflow.legacy_home_path_detected');
+}
+
 interface DirLoadResult {
   workflows: Map<string, WorkflowDefinition>;
   errors: WorkflowLoadError[];
 }
 
 /**
- * Load workflows from a directory (recursively includes subdirectories).
+ * Maximum subfolder depth we descend into when discovering workflows/commands/scripts.
+ *
+ * `1` allows one level of grouping (e.g. `.archon/workflows/defaults/foo.yaml`);
+ * `0` would mean only files at the root. We stop at 1 deliberately — deeper
+ * nesting has never been part of the documented convention and adds no
+ * organizational value, just routing ambiguity.
+ */
+const MAX_DISCOVERY_DEPTH = 1;
+
+/**
+ * Load workflows from a directory, descending at most `MAX_DISCOVERY_DEPTH`
+ * folders deep. Files deeper than the cap are silently skipped.
  * Failures are per-file: one broken file does not abort loading the rest.
  */
-async function loadWorkflowsFromDir(dirPath: string): Promise<DirLoadResult> {
+async function loadWorkflowsFromDir(dirPath: string, depth = 0): Promise<DirLoadResult> {
   const workflows = new Map<string, WorkflowDefinition>();
   const errors: WorkflowLoadError[] = [];
 
@@ -50,8 +107,11 @@ async function loadWorkflowsFromDir(dirPath: string): Promise<DirLoadResult> {
         const entryStat = await stat(entryPath);
 
         if (entryStat.isDirectory()) {
-          // Recursively load from subdirectories
-          const subResult = await loadWorkflowsFromDir(entryPath);
+          // Only descend if we're still within the depth cap. Past the cap,
+          // subdirectories are ignored (same convention as the paths-package
+          // `findMarkdownFilesRecursive` depth cap).
+          if (depth >= MAX_DISCOVERY_DEPTH) continue;
+          const subResult = await loadWorkflowsFromDir(entryPath, depth + 1);
           for (const [filename, workflow] of subResult.workflows) {
             workflows.set(filename, workflow);
           }
@@ -125,17 +185,24 @@ function loadBundledWorkflows(): DirLoadResult {
 }
 
 /**
- * Discover and load workflows from codebase
- * Loads from both app's bundled defaults and repo's workflow folder.
- * Repo workflows override app defaults by exact filename match.
+ * Discover and load workflows from codebase.
  *
- * When running as a compiled binary, defaults are loaded from the bundled
- * content embedded at compile time. When running with Bun, defaults are
- * loaded from the filesystem.
+ * Loads three scopes in order (later overrides earlier by filename):
+ *   1. Bundled defaults (unless `options.loadDefaults === false`).
+ *   2. Home-scoped `~/.archon/workflows/` — classified as `source: 'global'`.
+ *      No caller option: every caller gets home-scoped discovery for free.
+ *   3. Repo-scoped `<cwd>/.archon/workflows/` — classified as `source: 'project'`.
+ *
+ * When running as a compiled binary, bundled defaults are loaded from embedded
+ * content. In source/dev mode they're loaded from the filesystem.
+ *
+ * Migration: if the retired `~/.archon/.archon/workflows/` path exists, the
+ * first call per process logs a WARN with the exact `mv` command. The legacy
+ * location is not read — users must migrate manually.
  */
 export async function discoverWorkflows(
   cwd: string,
-  options?: { globalSearchPath?: string; loadDefaults?: boolean }
+  options?: { loadDefaults?: boolean }
 ): Promise<WorkflowLoadResult> {
   // Map of filename -> workflow+source for deduplication
   const workflowsByFile = new Map<string, WorkflowWithSource>();
@@ -182,36 +249,32 @@ export async function discoverWorkflows(
     }
   }
 
-  // 2. Load from global search path (e.g., ~/.archon/.archon/workflows/ for orchestrator)
-  if (options?.globalSearchPath) {
-    const [globalWorkflowFolder] = archonPaths.getWorkflowFolderSearchPaths();
-    const globalWorkflowPath = join(options.globalSearchPath, globalWorkflowFolder);
-    getLog().debug({ globalWorkflowPath }, 'searching_global_workflows');
-    try {
-      await access(globalWorkflowPath);
-      const globalResult = await loadWorkflowsFromDir(globalWorkflowPath);
-      for (const [filename, workflow] of globalResult.workflows) {
-        if (workflowsByFile.has(filename)) {
-          getLog().debug({ filename }, 'global_workflow_overrides_default');
-        }
-        // NOTE: Global workflows (~/.archon/.archon/workflows/) are classified as 'project'
-        // rather than a separate 'global' source. This is an intentional scope decision for
-        // the initial source badge feature — a 'global' source variant can be added later.
-        workflowsByFile.set(filename, { workflow, source: 'project' });
-      }
-      allErrors.push(...globalResult.errors);
-      getLog().info({ count: globalResult.workflows.size }, 'global_workflows_loaded');
-    } catch (error) {
-      const err = error as NodeJS.ErrnoException;
-      if (err.code !== 'ENOENT') {
-        getLog().warn({ err, globalWorkflowPath }, 'global_workflows_access_error');
-      } else {
-        getLog().debug({ globalWorkflowPath }, 'global_workflows_not_found');
+  // 2. Load home-scoped workflows from ~/.archon/workflows/. No caller option —
+  // discovery is responsible for surfacing home-scoped content everywhere.
+  await maybeWarnLegacyHomePath();
+  const homeWorkflowPath = archonPaths.getHomeWorkflowsPath();
+  getLog().debug({ homeWorkflowPath }, 'searching_home_workflows');
+  try {
+    await access(homeWorkflowPath);
+    const homeResult = await loadWorkflowsFromDir(homeWorkflowPath);
+    for (const [filename, workflow] of homeResult.workflows) {
+      if (workflowsByFile.has(filename)) {
+        getLog().debug({ filename }, 'home_workflow_overrides_bundled');
       }
+      workflowsByFile.set(filename, { workflow, source: 'global' });
+    }
+    allErrors.push(...homeResult.errors);
+    getLog().info({ count: homeResult.workflows.size }, 'home_workflows_loaded');
+  } catch (error) {
+    const err = error as NodeJS.ErrnoException;
+    if (err.code !== 'ENOENT') {
+      getLog().warn({ err, homeWorkflowPath }, 'home_workflows_access_error');
+    } else {
+      getLog().debug({ homeWorkflowPath }, 'home_workflows_not_found');
     }
   }
 
-  // 3. Load from repo's workflow folder (overrides app defaults by exact filename)
+  // 3. Load from repo's workflow folder (overrides app defaults AND home scope by exact filename)
   const [workflowFolder] = archonPaths.getWorkflowFolderSearchPaths();
   const workflowPath = join(cwd, workflowFolder);
 
@@ -221,7 +284,7 @@ export async function discoverWorkflows(
     await access(workflowPath);
     const repoResult = await loadWorkflowsFromDir(workflowPath);
 
-    // Repo workflows override app defaults by exact filename match.
+    // Repo workflows override bundled AND home scope by exact filename match.
     // Preserve 'bundled' source for workflows loaded from the defaults/ subdirectory
     // that were already registered as bundled in step 1.
     for (const [filename, workflow] of repoResult.workflows) {
@@ -233,7 +296,10 @@ export async function discoverWorkflows(
         workflowsByFile.set(filename, { workflow, source: 'bundled' });
       } else {
         if (existing) {
-          getLog().debug({ filename }, 'repo_workflow_overrides_default');
+          getLog().debug(
+            { filename, overriddenSource: existing.source },
+            'repo_workflow_overrides_lower_scope'
+          );
         }
         workflowsByFile.set(filename, { workflow, source: 'project' });
       }
@@ -290,8 +356,7 @@ export async function discoverWorkflows(
  */
 export async function discoverWorkflowsWithConfig(
   cwd: string,
-  loadConfig: (cwd: string) => Promise<{ defaults?: { loadDefaultWorkflows?: boolean } }>,
-  options?: { globalSearchPath?: string }
+  loadConfig: (cwd: string) => Promise<{ defaults?: { loadDefaultWorkflows?: boolean } }>
 ): Promise<WorkflowLoadResult> {
   let loadDefaults = true;
   try {
@@ -303,5 +368,5 @@ export async function discoverWorkflowsWithConfig(
       'config_load_failed_using_default_workflow_discovery'
     );
   }
-  return discoverWorkflows(cwd, { ...options, loadDefaults });
+  return discoverWorkflows(cwd, { loadDefaults });
 }
diff --git a/scripts/build-binaries.sh b/scripts/build-binaries.sh
index c683c47ac7..8b9cd086b1 100755
--- a/scripts/build-binaries.sh
+++ b/scripts/build-binaries.sh
@@ -21,6 +21,12 @@ OUTFILE="${OUTFILE:-}"
 
 echo "Building Archon CLI v${VERSION} (commit: ${GIT_COMMIT})"
 
+# Regenerate bundled defaults from .archon/{commands,workflows}/defaults/ so the
+# compiled binary always embeds the current on-disk contents. CI also runs
+# `bun run check:bundled` to catch committed drift.
+echo "Regenerating bundled defaults..."
+bun run scripts/generate-bundled-defaults.ts
+
 # Update build-time constants in source before compiling.
 # The file is restored via an EXIT trap so the dev tree is never left dirty,
 # even if `bun build --compile` fails mid-way. See GitHub issue #979.
diff --git a/scripts/generate-bundled-defaults.ts b/scripts/generate-bundled-defaults.ts
new file mode 100644
index 0000000000..1abcea74f9
--- /dev/null
+++ b/scripts/generate-bundled-defaults.ts
@@ -0,0 +1,178 @@
+#!/usr/bin/env bun
+/**
+ * Regenerates packages/workflows/src/defaults/bundled-defaults.generated.ts from
+ * the on-disk defaults in .archon/commands/defaults/ and .archon/workflows/defaults/.
+ *
+ * Emits inline string literals (via JSON.stringify) rather than Bun's
+ * `import X from '...' with { type: 'text' }` attributes so the module loads
+ * in Node too. This fixes two problems at once:
+ *   - bundle drift (hand-maintained import list in bundled-defaults.ts)
+ *   - SDK blocker #2 (type: 'text' import attributes are Bun-specific)
+ *
+ * Determinism: filenames are sorted before emission so `bun run check:bundled`
+ * (which regenerates into memory and compares to the committed file) catches
+ * unregenerated changes. Wired into `bun run validate` and CI.
+ *
+ * Usage:
+ *   bun run scripts/generate-bundled-defaults.ts           # write
+ *   bun run scripts/generate-bundled-defaults.ts --check   # verify (exit 2 if stale)
+ *
+ * Exit codes:
+ *   0  file generated (and unchanged, if --check)
+ *   1  unexpected error (missing dir, unreadable source, invalid filename, etc.)
+ *   2  --check was passed and the file would change
+ */
+import { access, readFile, readdir, writeFile } from 'fs/promises';
+import { join, resolve } from 'path';
+
+const REPO_ROOT = resolve(import.meta.dir, '..');
+const COMMANDS_DIR = join(REPO_ROOT, '.archon/commands/defaults');
+const WORKFLOWS_DIR = join(REPO_ROOT, '.archon/workflows/defaults');
+const OUTPUT_PATH = join(
+  REPO_ROOT,
+  'packages/workflows/src/defaults/bundled-defaults.generated.ts'
+);
+
+const CHECK_ONLY = process.argv.includes('--check');
+
+interface BundledFile {
+  name: string;
+  content: string;
+}
+
+async function ensureDir(dir: string, label: string): Promise<void> {
+  try {
+    await access(dir);
+  } catch {
+    throw new Error(
+      `${label} directory not found: ${dir}\n` +
+        `Run this script from the repo root (cwd was ${process.cwd()}), ` +
+        'or verify the .archon/ tree exists.'
+    );
+  }
+}
+
+async function collectFiles(dir: string, extensions: readonly string[]): Promise<BundledFile[]> {
+  const entries = await readdir(dir);
+  const matched = entries
+    .map(entry => {
+      const ext = extensions.find(e => entry.endsWith(e));
+      return ext ? { entry, ext } : undefined;
+    })
+    .filter((m): m is { entry: string; ext: string } => m !== undefined)
+    .sort((a, b) => a.entry.localeCompare(b.entry));
+
+  const files: BundledFile[] = [];
+  const seen = new Set<string>();
+  for (const { entry, ext } of matched) {
+    const name = entry.slice(0, -ext.length);
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(name)) {
+      throw new Error(
+        `Bundled default has invalid filename "${entry}" in ${dir}. ` +
+          'Names must be kebab-case (lowercase letters, digits, hyphens).'
+      );
+    }
+    if (seen.has(name)) {
+      throw new Error(
+        `Bundled default name collision: "${name}" appears with multiple extensions in ${dir}. ` +
+          'Keep a single file per name (remove either the .yaml or .yml variant).'
+      );
+    }
+    seen.add(name);
+    const raw = await readFile(join(dir, entry), 'utf-8');
+    // Normalize to LF so output is identical regardless of the checkout's
+    // line-ending policy (e.g. Windows `core.autocrlf=true` yields CRLF).
+    const content = raw.replace(/\r\n/g, '\n');
+    if (!content.trim()) {
+      throw new Error(`Bundled default "${entry}" in ${dir} is empty.`);
+    }
+    files.push({ name, content });
+  }
+  return files;
+}
+
+function renderRecord(comment: string, exportName: string, files: BundledFile[]): string {
+  const entries = files
+    .map(f => `  ${JSON.stringify(f.name)}: ${JSON.stringify(f.content)},`)
+    .join('\n');
+  return [
+    `// ${comment} (${files.length} total)`,
+    `export const ${exportName}: Record<string, string> = {`,
+    entries,
+    '};',
+  ].join('\n');
+}
+
+function renderFile(commands: BundledFile[], workflows: BundledFile[]): string {
+  const header = [
+    '/**',
+    ' * AUTO-GENERATED — DO NOT EDIT.',
+    ' *',
+    ' * Regenerate with: bun run generate:bundled',
+    ' * Verify up-to-date:  bun run check:bundled',
+    ' *',
+    ' * Source of truth:',
+    ' *   .archon/commands/defaults/*.md',
+    ' *   .archon/workflows/defaults/*.{yaml,yml}',
+    ' *',
+    ' * Contents are inlined as plain string literals (JSON-escaped) so this',
+    ' * module loads in both Bun and Node. Previous versions used',
+    " * `import X from '...' with { type: 'text' }` which is Bun-specific.",
+    ' */',
+    '',
+  ].join('\n');
+
+  return [
+    header,
+    renderRecord('Bundled default commands', 'BUNDLED_COMMANDS', commands),
+    '',
+    renderRecord('Bundled default workflows', 'BUNDLED_WORKFLOWS', workflows),
+    '',
+  ].join('\n');
+}
+
+async function main(): Promise<void> {
+  await Promise.all([
+    ensureDir(COMMANDS_DIR, 'Commands defaults'),
+    ensureDir(WORKFLOWS_DIR, 'Workflows defaults'),
+  ]);
+
+  const [commands, workflows] = await Promise.all([
+    collectFiles(COMMANDS_DIR, ['.md']),
+    collectFiles(WORKFLOWS_DIR, ['.yaml', '.yml']),
+  ]);
+
+  const contents = renderFile(commands, workflows);
+
+  if (CHECK_ONLY) {
+    let existing = '';
+    try {
+      const raw = await readFile(OUTPUT_PATH, 'utf-8');
+      // Same LF normalization as collectFiles — the .ts itself may be
+      // checked out with CRLF line endings on Windows.
+      existing = raw.replace(/\r\n/g, '\n');
+    } catch (e) {
+      const err = e as NodeJS.ErrnoException;
+      if (err.code !== 'ENOENT') throw err;
+    }
+    if (existing !== contents) {
+      console.error('bundled-defaults.generated.ts is stale.\n' + 'Run: bun run generate:bundled');
+      process.exit(2);
+    }
+    console.log(
+      `bundled-defaults.generated.ts is up to date (${commands.length} commands, ${workflows.length} workflows).`
+    );
+    return;
+  }
+
+  await writeFile(OUTPUT_PATH, contents, 'utf-8');
+  console.log(
+    `Wrote ${OUTPUT_PATH}\n  ${commands.length} commands, ${workflows.length} workflows.`
+  );
+}
+
+main().catch((err: unknown) => {
+  const msg = err instanceof Error ? err.message : String(err);
+  console.error(msg);
+  process.exit(1);
+});
diff --git a/scripts/tsconfig.json b/scripts/tsconfig.json
new file mode 100644
index 0000000000..09b9d05bcd
--- /dev/null
+++ b/scripts/tsconfig.json
@@ -0,0 +1,11 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "declaration": false,
+    "declarationMap": false,
+    "sourceMap": false,
+    "types": ["bun-types"]
+  },
+  "include": ["*.ts"]
+}