From c0b7272194949c30646ec1bfe1409af5401ec10c Mon Sep 17 00:00:00 2001
From: Rahul Tyagi <rahul.1992.tyagi@gmail.com>
Date: Sat, 4 Jul 2026 18:33:10 +0530
Subject: [PATCH 01/16] Add opencode port design spec

---
 .../2026-07-04-nexum-opencode-port-design.md  | 264 ++++++++++++++++++
 1 file changed, 264 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-07-04-nexum-opencode-port-design.md

diff --git a/docs/superpowers/specs/2026-07-04-nexum-opencode-port-design.md b/docs/superpowers/specs/2026-07-04-nexum-opencode-port-design.md
new file mode 100644
index 0000000..207acb0
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-04-nexum-opencode-port-design.md
@@ -0,0 +1,264 @@
+# Nexum → OpenCode Port
+
+**Date:** 2026-07-04
+**Status:** Design
+
+Port the nexum Claude Code plugin to OpenCode. Nexum is a context-token and model-cost optimization plugin. The port keeps the existing Python scripts as-is and wires them into OpenCode's plugin, command, and agent system.
+
+---
+
+## 1. Architecture
+
+The Python scripts in `scripts/` are the engine — they stay entirely unchanged. The port is a **wiring layer**:
+
+```
+┌─────────────────────────────────────────────┐
+│  OpenCode (.opencode/)                       │
+│                                              │
+│  plugins/nexum-hooks.ts  ← event →          │──── calls ──→  scripts/*.py
+│  commands/nx-*.md        ← /nx-*             │              (via subprocess)
+│  agents/nexum-*.md       ← @nexum-*          │
+│  opencode.json           ← config            │
+└─────────────────────────────────────────────┘
+```
+
+Every Python script reads JSON from stdin and writes JSON to stdout (the same contract they already follow). The TS plugin transforms OpenCode event objects to/from the nexum format.
+
+**Env var set by plugin (via `shell.env`):**
+
+| Var | Value | Used by |
+|---|---|---|
+| `NEXUM_ROOT` | Absolute path to nexum repo root | Commands/agents resolve `scripts/` |
+
+The plugin sets `NEXUM_ROOT` at startup so commands and agents can find the Python scripts without hardcoding paths. Session ID is passed per-call by the plugin (it has access to `sessionID` from the plugin context).
+
+`NEXUM_ROOT` is set by resolving `import.meta.dirname` (Bun) or `__dirname` minus the `.opencode/plugins/` suffix — the plugin always knows where it lives relative to the repo root.
+
+---
+
+## 2. Plugin — event wiring (`.opencode/plugins/nexum-hooks.ts`)
+
+Single TypeScript file that wires Python scripts into OpenCode events. Each handler transforms the OpenCode event shape into nexum's stdin JSON format, calls the script, and applies the result.
+
+### Events mapped
+
+| OpenCode Event | Nexum Script | What it does |
+|---|---|---|
+| `tool.execute.before` | `scan_guard.py` | Block/limit unscoped reads, recursive searches |
+| `tool.execute.before` | `predup.py` | Block re-read of already-loaded file content |
+| `tool.execute.after` | `dedup.py` | Collapse repeated tool output + truncate oversized |
+| `session.created` | `resume_nudge.py` | Nudge user about unfinished handoff |
+| `session.created` | `audit_nudge.py` | Periodic ignore-file audit reminder |
+| `session.created` | `session_reset.py` | Clear stale tool_calls, throttle retention prune |
+| `session.compacted` | `precompact.py` | Clear tool_calls at compaction boundary |
+
+### Missing Claude Code hooks (no OpenCode equivalent)
+
+| Claude Hook | Script | Resolution |
+|---|---|---|
+| `UserPromptSubmit` | `context_watch.py` | **Skipped.** Intent-guard and auto-handoff-write are non-critical. The auto-handoff can run on `session.compacted` instead. |
+| `SubagentStop` | `subagent_usage.py` | **Skipped.** OpenCode tracks subagent usage natively. |
+
+### Plugin contract
+
+```typescript
+// NexumScript Input (from plugin handler, matching what each script expects):
+// scan_guard:  { tool_name: string, tool_input: object }
+// predup:      { tool_name: string, tool_input: object, session_id: string }
+// dedup:       { tool_name: string, tool_response: string|object, session_id: string }
+// resume_nudge/audit_nudge/session_reset: { session_id: string }
+// precompact:  { session_id: string }
+
+// NexumScript Output (parsed from script stdout):
+// scan_guard:  { hookSpecificOutput: { permissionDecision?, permissionDecisionReason?, updatedInput? } }
+// predup:      { hookSpecificOutput: { permissionDecision?, permissionDecisionReason? } }
+// dedup:       { hookSpecificOutput: { updatedToolOutput? } }
+// others:      {} (fail-open)
+```
+
+The plugin handler:
+1. Serializes the OpenCode event into the script's expected input shape
+2. Spawns `python3 <NEXUM_ROOT>/scripts/<script>.py`, pipes JSON via stdin
+3. Parses stdout JSON
+4. Applies any `permissionDecision`, `updatedInput`, `updatedToolOutput` back to the OpenCode output object
+5. On any error (parse failure, non-zero exit, timeout) → no-op (fail-open)
+
+---
+
+## 3. Commands (`.opencode/commands/`)
+
+7 markdown command files, one per `/nx-*` command.
+
+| Command | Frontmatter Model | Source |
+|---|---|---|
+| `nx-plan.md` | Plan agent | Adapted from `commands/nx-plan.md` |
+| `nx-build.md` | Build agent | Adapted from `commands/nx-build.md` |
+| `nx-save.md` | Build agent | Adapted from `commands/nx-save.md` |
+| `nx-load.md` | Build agent | Adapted from `commands/nx-load.md` |
+| `nx-audit.md` | Haiku-tier model | Adapted from `commands/nx-audit.md` |
+| `nx-report.md` | Haiku-tier model | Adapted from `commands/nx-report.md` |
+| `nx-status.md` | (no frontmatter needed) | New: displays nexum session stats via a Python script call |
+
+### Changes from Claude Code versions
+
+1. **Path resolution.** `${CLAUDE_PLUGIN_ROOT}` → `$NEXUM_ROOT` (set by plugin via `shell.env`).
+2. **Session ID.** `$CLAUDE_SESSION_ID` → `$NEXUM_SESSION_ID` (set by plugin).
+3. **Model frontmatter.** Claude Code uses `model: haiku/sonnet/opus` — OpenCode uses `model: provider/model-id` or omits to inherit.
+4. **Agent references.** Claude Code `@nexum-impl-haiku` → OpenCode `@nexum-mechanical`.
+
+### nx-plan: model selection at finalization
+
+`/nx-plan` gains a new final step — after the agent drafts the tiered plan, it asks the user to pick models for each tier:
+
+> Plan drafted. Which model for mechanical steps? (default: anthropic/claude-haiku-4-20250514)
+> Which model for standard steps? (default: anthropic/claude-sonnet-4-20250514)
+> Which model for needs-strong steps? (default: anthropic/claude-opus-4-20250514)
+
+The choices are recorded in the plan file under a `models:` section:
+
+```markdown
+**Models:**
+- mechanical: anthropic/claude-haiku-4-20250514
+- standard: anthropic/claude-sonnet-4-20250514
+- needs-strong: anthropic/claude-opus-4-20250514
+```
+
+### nx-build: dispatch to chosen models
+
+`/nx-build` reads the `models:` section from the plan and dispatches each step to the appropriate model. The 3 executor agents are defined **without** a `model` in frontmatter (so they inherit the caller's model). Dispatch approach:
+
+1. **Tier groups** are dispatched sequentially via the Task tool to the named subagent (`@nexum-mechanical`, etc.)
+2. **The model choice from the plan is passed as an instruction** in the dispatch prompt: "You are the mechanical executor. The user selected {model} for this tier. Use it."
+3. The subagent inherits the session's primary model, but the prompt instructs it which model to target. The user must have the chosen models configured in their OpenCode setup.
+4. **Batch dispatch** for efficiency: all steps sharing a tier go to one subagent invocation, reusing the shared spec/context.
+
+This is not perfect model enforcement (the subagent inherits the primary session model), but it's the cleanest v1 approach with OpenCode's current agent dispatch. The model choice is documented in the plan for the user to configure accordingly.
+
+### nx-status: TUI display
+
+`/nx-status` runs the nexum report script and displays:
+- Token savings
+- Session cost
+- Waste analysis
+
+Since OpenCode has no persistent statusLine, this is an **on-demand** command. For periodic nudges, the plugin can use `tui.toast.show` on `session.status` events.
+
+---
+
+## 4. Agents (`.opencode/agents/`)
+
+4 subagent markdown files.
+
+| File | Purpose | Model |
+|---|---|---|
+| `nexum-mechanical.md` | Executor for mechanical steps (boilerplate, well-specified CRUD) | Inherited from plan |
+| `nexum-standard.md` | Executor for standard steps (multi-file, some reasoning) | Inherited from plan |
+| `nexum-needs-strong.md` | Executor for complex steps (architecture, ambiguity, debugging) | Inherited from plan |
+| `nexum-reviewer.md` | Code reviewer for escalated/high-risk steps | Fixed (user's strongest model) |
+
+### Changes from Claude Code versions
+
+Config format change (`model: haiku` → `model:` inherited or explicit). The executors reference `python3 $NEXUM_ROOT/scripts/guardrail.py` instead of `${CLAUDE_PLUGIN_ROOT}`.
+
+### Executor agent prompt (all three are near-identical, only model differs)
+
+```
+You are a nexum executor. Implement the given step(s) in order.
+Implement ONLY the listed step(s). Do not touch files outside scope.
+After each step, verify via:
+  python3 $NEXUM_ROOT/scripts/guardrail.py \
+    --acceptance "<cmd>" --scope-root <root> --changed <files>
+Return: on PASS → step index + one-line summary + guardrail JSON.
+        on FAIL → same + unified diff.
+```
+
+---
+
+## 5. Configuration (`opencode.json`)
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "command": {
+    "nx-plan": { "agent": "plan", "description": "Decompose task into tiered, self-contained steps" },
+    "nx-build": { "description": "Execute a nexum plan via cheapest capable tiers" },
+    "nx-save": { "description": "Write session handoff for clean resume" },
+    "nx-load": { "description": "Resume from most recent session handoff" },
+    "nx-audit": { "description": "Audit repo for context-risk files" },
+    "nx-report": { "description": "Show session digest: cost + wasted-context analysis" },
+    "nx-status": { "description": "Show nexum session stats" }
+  },
+  "agent": {
+    "nexum-mechanical": {
+      "mode": "subagent",
+      "description": "Executor for mechanical/boilerplate nexum steps",
+      "permission": { "edit": "allow", "bash": "allow" }
+    },
+    "nexum-standard": {
+      "mode": "subagent",
+      "description": "Executor for standard nexum steps",
+      "permission": { "edit": "allow", "bash": "allow" }
+    },
+    "nexum-needs-strong": {
+      "mode": "subagent",
+      "description": "Executor for complex nexum steps",
+      "permission": { "edit": "allow", "bash": "allow" }
+    },
+    "nexum-reviewer": {
+      "mode": "subagent",
+      "description": "Reviews escalated nexum step implementations",
+      "permission": { "edit": "deny", "bash": "allow" }
+    }
+  }
+}
+```
+
+---
+
+## 6. Pricing simplification
+
+The Claude Code version has a hardcoded `PRICING` dict in `store.py` with Opus/Sonnet/Haiku rates. OpenCode supports arbitrary models, so:
+
+- **Default:** Token-only tracking (no dollar conversion). Report shows raw token savings.
+- **Optional:** User can set `$/1M-tok` rates per model via nexum config (`config.json`) if they want dollar amounts.
+- The pricing keys in `store.py` change from fixed model names to config-driven entries.
+
+---
+
+## 7. File changes summary
+
+### New files (OpenCode layer)
+```
+.opencode/
+  plugins/nexum-hooks.ts       ~120 lines — event wiring
+  commands/nx-plan.md          adapted from commands/nx-plan.md
+  commands/nx-build.md         adapted from commands/nx-build.md
+  commands/nx-save.md          adapted from commands/nx-save.md
+  commands/nx-load.md          adapted from commands/nx-load.md
+  commands/nx-audit.md         adapted from commands/nx-audit.md
+  commands/nx-report.md        adapted from commands/nx-report.md
+  commands/nx-status.md        new — on-demand stats display
+  agents/nexum-mechanical.md   adapted from agents/nexum-impl-haiku.md
+  agents/nexum-standard.md     adapted from agents/nexum-impl-sonnet.md
+  agents/nexum-needs-strong.md adapted from agents/nexum-impl-opus.md
+  agents/nexum-reviewer.md     adapted from agents/nexum-reviewer.md
+opencode.json                  ~50 lines — config
+```
+
+### Existing files changed
+```
+scripts/store.py               minor — pricing made configurable
+```
+
+`context_watch.py` and `subagent_usage.py` need no changes — they simply won't be triggered (no hook calls them), which is fine (fail-open). Only `store.py`'s pricing table needs adjustment for model-agnostic tracking.
+
+---
+
+## 8. Build order
+
+1. `opencode.json` — config (no deps)
+2. `.opencode/plugins/nexum-hooks.ts` — event wiring (calls existing scripts, test standalone)
+3. `.opencode/commands/` — all 7 commands (adapt from existing, test each via `/nx-*`)
+4. `.opencode/agents/` — all 4 agents (adapt from existing, test via `/nx-plan` → `/nx-build`)
+5. `scripts/store.py` pricing change — make configurable
+6. Integration test: `/nx-plan` → model selection → `/nx-build` → acceptance checks

From 2ec184efb602b15bf57a6e0f6560e6935ca53b67 Mon Sep 17 00:00:00 2001
From: Rahul Tyagi <rahul.1992.tyagi@gmail.com>
Date: Sat, 4 Jul 2026 19:07:13 +0530
Subject: [PATCH 02/16] feat: add opencode.json config for nexum port

---
 opencode.json | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)
 create mode 100644 opencode.json

diff --git a/opencode.json b/opencode.json
new file mode 100644
index 0000000..910bb52
--- /dev/null
+++ b/opencode.json
@@ -0,0 +1,61 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "command": {
+    "nx-plan": {
+      "agent": "plan",
+      "description": "Decompose task into tiered, self-contained steps with model selection"
+    },
+    "nx-build": {
+      "description": "Execute a nexum plan via cheapest capable tiers"
+    },
+    "nx-save": {
+      "description": "Write session handoff for clean resume"
+    },
+    "nx-load": {
+      "description": "Resume from most recent session handoff"
+    },
+    "nx-audit": {
+      "description": "Audit repo for context-risk files and ignore config"
+    },
+    "nx-report": {
+      "description": "Show session digest: cost + wasted-context analysis"
+    },
+    "nx-status": {
+      "description": "Show nexum session usage stats"
+    }
+  },
+  "agent": {
+    "nexum-mechanical": {
+      "mode": "subagent",
+      "description": "Executor for mechanical/boilerplate nexum steps",
+      "permission": {
+        "edit": "allow",
+        "bash": "allow"
+      }
+    },
+    "nexum-standard": {
+      "mode": "subagent",
+      "description": "Executor for standard nexum steps",
+      "permission": {
+        "edit": "allow",
+        "bash": "allow"
+      }
+    },
+    "nexum-needs-strong": {
+      "mode": "subagent",
+      "description": "Executor for complex nexum steps (architecture, ambiguity, debugging)",
+      "permission": {
+        "edit": "allow",
+        "bash": "allow"
+      }
+    },
+    "nexum-reviewer": {
+      "mode": "subagent",
+      "description": "Reviews escalated nexum step implementations",
+      "permission": {
+        "edit": "deny",
+        "bash": "allow"
+      }
+    }
+  }
+}

From 83a9be3a8b9977b634ed43528068a68729395319 Mon Sep 17 00:00:00 2001
From: Rahul Tyagi <rahul.1992.tyagi@gmail.com>
Date: Sat, 4 Jul 2026 19:08:25 +0530
Subject: [PATCH 03/16] feat: add opencode plugin for nexum hook wiring

---
 .opencode/plugins/nexum-hooks.ts | 113 +++++++++++++++++++++++++++++++
 1 file changed, 113 insertions(+)
 create mode 100644 .opencode/plugins/nexum-hooks.ts

diff --git a/.opencode/plugins/nexum-hooks.ts b/.opencode/plugins/nexum-hooks.ts
new file mode 100644
index 0000000..939eb43
--- /dev/null
+++ b/.opencode/plugins/nexum-hooks.ts
@@ -0,0 +1,113 @@
+import type { Plugin } from "@opencode-ai/plugin"
+import path from "path"
+import { spawn } from "child_process"
+
+const NEXUM_ROOT = path.resolve(import.meta.dirname, "../..")
+const SCRIPTS_DIR = path.join(NEXUM_ROOT, "scripts")
+
+let currentSessionId = "_nosession"
+
+function runScript(scriptName: string, input: object, timeout = 10000): Promise<Record<string, any>> {
+  return new Promise((resolve) => {
+    const child = spawn("python3", [path.join(SCRIPTS_DIR, scriptName)], {
+      env: { ...process.env, CLAUDE_PLUGIN_ROOT: NEXUM_ROOT },
+      stdio: ["pipe", "pipe", "pipe"],
+    })
+
+    const timer = setTimeout(() => {
+      child.kill()
+      resolve({})
+    }, timeout)
+
+    child.stdin.write(JSON.stringify(input))
+    child.stdin.end()
+
+    let stdout = ""
+    child.stdout.on("data", (d: Buffer) => { stdout += d.toString() })
+    child.on("close", () => {
+      clearTimeout(timer)
+      try { resolve(JSON.parse(stdout)) }
+      catch { resolve({}) }
+    })
+    child.on("error", () => {
+      clearTimeout(timer)
+      resolve({})
+    })
+  })
+}
+
+export const NexumHooks: Plugin = async (ctx) => {
+  return {
+    "shell.env": async (_input, output) => {
+      output.env.CLAUDE_PLUGIN_ROOT = NEXUM_ROOT
+      output.env.CLAUDE_SESSION_ID = currentSessionId
+    },
+
+    "session.created": async (input: any) => {
+      currentSessionId = input?.session_id || input?.sessionId || "_nosession"
+      await runScript("session_reset.py", { session_id: currentSessionId })
+      await runScript("resume_nudge.py", {
+        session_id: currentSessionId,
+        source: input?.source || "startup",
+        cwd: input?.cwd || NEXUM_ROOT,
+      })
+      await runScript("audit_nudge.py", {
+        session_id: currentSessionId,
+        source: input?.source || "startup",
+        cwd: input?.cwd || NEXUM_ROOT,
+      })
+    },
+
+    "tool.execute.before": async (input: any, output: any) => {
+      const sharedInput = {
+        session_id: currentSessionId,
+        tool_name: input.tool,
+        tool_input: input.args || {},
+      }
+
+      const scanResult = await runScript("scan_guard.py", {
+        ...sharedInput,
+        tool_input: { ...sharedInput.tool_input },
+      })
+
+      if (scanResult?.hookSpecificOutput?.permissionDecision) {
+        output.permissionDecision = scanResult.hookSpecificOutput.permissionDecision
+        output.permissionDecisionReason = scanResult.hookSpecificOutput.permissionDecisionReason
+        if (scanResult.hookSpecificOutput.updatedInput) {
+          Object.assign(output.args, scanResult.hookSpecificOutput.updatedInput)
+        }
+        return
+      }
+
+      const predupResult = await runScript("predup.py", sharedInput)
+      if (predupResult?.hookSpecificOutput?.permissionDecision) {
+        output.permissionDecision = predupResult.hookSpecificOutput.permissionDecision
+        output.permissionDecisionReason = predupResult.hookSpecificOutput.permissionDecisionReason
+      }
+    },
+
+    "tool.execute.after": async (input: any, output: any) => {
+      const dedupResult = await runScript("dedup.py", {
+        session_id: currentSessionId,
+        tool_name: input.tool,
+        tool_input: input.args || {},
+        tool_use_id: "",
+        transcript_path: "",
+        tool_response: input.result ?? "",
+      })
+
+      if (dedupResult?.hookSpecificOutput?.updatedToolOutput) {
+        output.result = dedupResult.hookSpecificOutput.updatedToolOutput
+      }
+    },
+
+    "session.compacted": async (input: any) => {
+      await runScript("precompact.py", {
+        session_id: currentSessionId,
+        cwd: input?.cwd || NEXUM_ROOT,
+        transcript_path: input?.transcript_path || "",
+        trigger: input?.trigger || "compacted",
+      })
+    },
+  }
+}

From b4bf6fcc80540e0524a7fd8277dee5e3d2f325ba Mon Sep 17 00:00:00 2001
From: Rahul Tyagi <rahul.1992.tyagi@gmail.com>
Date: Sat, 4 Jul 2026 19:10:50 +0530
Subject: [PATCH 04/16] fix: wrap stdin.write in try/catch for EPIPE, use ??
 instead of || for falsy-safe fallbacks

---
 .opencode/plugins/nexum-hooks.ts | 29 ++++++++++++++++++-----------
 1 file changed, 18 insertions(+), 11 deletions(-)

diff --git a/.opencode/plugins/nexum-hooks.ts b/.opencode/plugins/nexum-hooks.ts
index 939eb43..4db56f0 100644
--- a/.opencode/plugins/nexum-hooks.ts
+++ b/.opencode/plugins/nexum-hooks.ts
@@ -19,8 +19,15 @@ function runScript(scriptName: string, input: object, timeout = 10000): Promise<
       resolve({})
     }, timeout)
 
-    child.stdin.write(JSON.stringify(input))
-    child.stdin.end()
+    try {
+      child.stdin.write(JSON.stringify(input))
+      child.stdin.end()
+    } catch {
+      child.kill()
+      clearTimeout(timer)
+      resolve({})
+      return
+    }
 
     let stdout = ""
     child.stdout.on("data", (d: Buffer) => { stdout += d.toString() })
@@ -44,17 +51,17 @@ export const NexumHooks: Plugin = async (ctx) => {
     },
 
     "session.created": async (input: any) => {
-      currentSessionId = input?.session_id || input?.sessionId || "_nosession"
+      currentSessionId = input?.session_id ?? input?.sessionId ?? "_nosession"
       await runScript("session_reset.py", { session_id: currentSessionId })
       await runScript("resume_nudge.py", {
         session_id: currentSessionId,
-        source: input?.source || "startup",
-        cwd: input?.cwd || NEXUM_ROOT,
+        source: input?.source ?? "startup",
+        cwd: input?.cwd ?? NEXUM_ROOT,
       })
       await runScript("audit_nudge.py", {
         session_id: currentSessionId,
-        source: input?.source || "startup",
-        cwd: input?.cwd || NEXUM_ROOT,
+        source: input?.source ?? "startup",
+        cwd: input?.cwd ?? NEXUM_ROOT,
       })
     },
 
@@ -62,7 +69,7 @@ export const NexumHooks: Plugin = async (ctx) => {
       const sharedInput = {
         session_id: currentSessionId,
         tool_name: input.tool,
-        tool_input: input.args || {},
+        tool_input: input.args ?? {},
       }
 
       const scanResult = await runScript("scan_guard.py", {
@@ -104,9 +111,9 @@ export const NexumHooks: Plugin = async (ctx) => {
     "session.compacted": async (input: any) => {
       await runScript("precompact.py", {
         session_id: currentSessionId,
-        cwd: input?.cwd || NEXUM_ROOT,
-        transcript_path: input?.transcript_path || "",
-        trigger: input?.trigger || "compacted",
+        cwd: input?.cwd ?? NEXUM_ROOT,
+        transcript_path: input?.transcript_path ?? "",
+        trigger: input?.trigger ?? "compacted",
       })
     },
   }

From c4f31403614a13f1818f66e0691ed664d668a73b Mon Sep 17 00:00:00 2001
From: Rahul Tyagi <rahul.1992.tyagi@gmail.com>
Date: Sat, 4 Jul 2026 19:12:06 +0530
Subject: [PATCH 05/16] feat: add opencode commands for nexum (nx-plan,
 nx-build, nx-save, nx-load, nx-audit, nx-report, nx-status)

---
 .opencode/commands/nx-audit.md  |  28 ++++++++
 .opencode/commands/nx-build.md  |  91 ++++++++++++++++++++++++++
 .opencode/commands/nx-load.md   |  23 +++++++
 .opencode/commands/nx-plan.md   | 110 ++++++++++++++++++++++++++++++++
 .opencode/commands/nx-report.md |  18 ++++++
 .opencode/commands/nx-save.md   |  49 ++++++++++++++
 .opencode/commands/nx-status.md |  11 ++++
 7 files changed, 330 insertions(+)
 create mode 100644 .opencode/commands/nx-audit.md
 create mode 100644 .opencode/commands/nx-build.md
 create mode 100644 .opencode/commands/nx-load.md
 create mode 100644 .opencode/commands/nx-plan.md
 create mode 100644 .opencode/commands/nx-report.md
 create mode 100644 .opencode/commands/nx-save.md
 create mode 100644 .opencode/commands/nx-status.md

diff --git a/.opencode/commands/nx-audit.md b/.opencode/commands/nx-audit.md
new file mode 100644
index 0000000..65267bd
--- /dev/null
+++ b/.opencode/commands/nx-audit.md
@@ -0,0 +1,28 @@
+---
+description: "Audit the current repo's ignore configuration and flag noise files or directories that could blow context."
+---
+
+You are the nexum auditor. Run the audit script, summarize findings, offer to apply fixes.
+
+## 1. Run the audit
+
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/audit.py
+```
+
+## 2. Summarize findings
+
+Group by: no ignore file, unignored noise dirs, gitignore gaps, large/binary files.
+
+Keep concise. Prefix with `[nexum] `. No emoji.
+
+## 3. Offer to apply
+
+> `[nexum] Run with --write to append suggested ignore patterns? (yes / no)`
+
+On yes: `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/audit.py --write`
+
+## 4. Constraints
+
+- Do not edit any ignore file yourself.
+- Do not run other commands.
diff --git a/.opencode/commands/nx-build.md b/.opencode/commands/nx-build.md
new file mode 100644
index 0000000..c5c4c32
--- /dev/null
+++ b/.opencode/commands/nx-build.md
@@ -0,0 +1,91 @@
+---
+description: "Execute a nexum plan: dispatch each step to the cheapest capable model tier, verify acceptance, escalate on failure, resume across restarts."
+---
+
+You are the nexum implementer. Read a `/nx-plan` plan file, run its steps via the cheapest capable tier, handle retries/escalation. You orchestrate; you don't write step code (except inline, §4).
+
+**Orchestration is mechanical** — parse, dispatch, read verdicts, branch. Does NOT need an expensive model.
+
+**Output: terse, minimal. No prose, no narration.** Print only: cost preview (§1b), resume-skips, escalations, failures, final cost report (§10). NO per-step success chatter.
+
+## 1. Locate + read plan
+
+Data dir (same as `store.py`): `$CLAUDE_PLUGIN_DATA`, else `${CLAUDE_PLUGIN_ROOT}/.nexum-data`, else `./.nexum-data`. Plan: `<data_dir>/plan/<session_id>.md`, session id = `$CLAUDE_SESSION_ID` (else `_nosession`).
+
+Read plan in full. Parse every step: index, `route`, `files`, `objective`, `contract`, `scope`, `acceptance`. Also parse `**Models:**` section to get the model per tier.
+
+No plan file → stop: `[nexum] No plan found for this session. Run /nx-plan first.`
+
+Read config once: `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/store.py config`. Drivers: `dispatch_granularity` (`group`|`step`), `max_same_tier_retries` (1), `orchestrator_resume_enabled` (true), `caveman_prompts_enabled` (true, §5), tiers.
+
+## 1a. Resume from ledger (skip done work)
+
+If `orchestrator_resume_enabled` (default true):
+
+1. Plan hash: `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/store.py plan-hash --file <plan_file>`
+2. `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/store.py step-list --session <session_id> --plan-hash <plan_hash>`
+3. Per step, ledger = source of truth:
+   - **done** → skip. Print `[nexum] Step <N> already done (resumed) — skipping.`
+   - **failed** → resume mid-ladder. Read `attempts` + `tier_used`, continue from there.
+   - **pending / absent** → run normally.
+
+All done → report complete, skip to §10.
+
+## 1b. Cost preview
+
+If `plan_preview_enabled` (default), run and print verbatim:
+
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/plan_preview.py --plan <plan_file>
+```
+
+## 2. Dispatch to subagents
+
+Use the 3 executor subagents (`@nexum-mechanical`, `@nexum-standard`, `@nexum-needs-strong`) to dispatch steps:
+
+1. Group steps by route in order (mechanical → standard → needs-strong)
+2. For each group, dispatch ALL steps in ONE subagent invocation (batch dispatch) using the Task tool:
+   - Launch `nexum-mechanical` for all mechanical steps
+   - Launch `nexum-standard` for all standard steps
+   - Launch `nexum-needs-strong` for all needs-strong steps
+3. Pass the shared context + all steps verbatim to the subagent
+4. Wait for each group to complete before starting the next
+
+**Cap batch size.** Use `plan_preview.py` to get size-aware batches:
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/plan_preview.py --plan <plan_file> --indices "<step-indices>" --root <repo_root>
+```
+
+**Skip spawn when tier == session model.** If your own model matches the tier, implement inline instead of dispatching.
+
+## 3. Verdict handling
+
+The subagent returns per-step guardrail JSON. Verify each step's acceptance result.
+
+- **pass** → proceed. Record in ledger.
+- **fail** → retry (§4).
+
+Record every verdict:
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/store.py step-set --session <session_id> --plan-hash <plan_hash> --index <N> --status done --title "<title>" --route <route> --tier <tier>
+```
+
+## 4. Retry + escalation
+
+On FAIL:
+1. Retry same tier up to `max_same_tier_retries` (1). Re-dispatch the failing step only with the guardrail failure + diff.
+2. Escalate one tier (mechanical→standard→needs-strong). For escalated steps, also dispatch `nexum-reviewer`.
+3. Final failure → stop, ask user.
+
+## 5. Cost summary
+
+After all steps (or abort):
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/cost_report.py --session <session_id>
+```
+Print verbatim.
+
+## 6. Constraints
+
+- Never skip the guardrail — every step passes it before the next.
+- Never modify the plan file during execution.
diff --git a/.opencode/commands/nx-load.md b/.opencode/commands/nx-load.md
new file mode 100644
index 0000000..0dfb33f
--- /dev/null
+++ b/.opencode/commands/nx-load.md
@@ -0,0 +1,23 @@
+---
+description: "Resume from the most recent session handoff written by /nx-save or the auto-handoff hook."
+---
+
+You are the nexum handoff loader. The user wants to pick up where a previous session left off.
+
+## 1. Locate the handoff
+
+Data directory: `$CLAUDE_PLUGIN_DATA` if set, else `<git toplevel>/.nexum-data` (via `git rev-parse --show-toplevel`), else `./.nexum-data`.
+
+Read `<data_dir>/handoff/latest.md`. If missing, check `<data_dir>/handoff/` for any `*.md` and offer the newest. No handoff → `[nexum] No handoff found. Nothing to resume.`
+
+## 2. Sanity-check
+
+Print the handoff's **Written** timestamp and **Branch**. Warn if old (>1 day) or branch mismatch. Note if it's a rich handoff (from `/nx-save`) or auto-skeleton (git state only).
+
+## 3. Re-establish state
+
+Run `git rev-parse --abbrev-ref HEAD`, `git status --short`, `git diff --stat` to confirm the working tree matches. Surface discrepancies.
+
+## 4. Summarize and continue
+
+Print goal, what was done/verified, and the next concrete step. Then proceed with that step.
diff --git a/.opencode/commands/nx-plan.md b/.opencode/commands/nx-plan.md
new file mode 100644
index 0000000..25b2fc1
--- /dev/null
+++ b/.opencode/commands/nx-plan.md
@@ -0,0 +1,110 @@
+---
+description: "Decompose the task into routed, self-contained steps and write a plan file. Each step routes to the cheapest model that can run it."
+---
+
+You are the nexum planner. Grill user (§0). Then decompose task into ordered, self-contained steps. Write plan file. Do NOT implement. Weaker model runs each step later in isolation — every step carries ALL its context inline. No references to "previous step."
+
+Output: terse. No prose. Final output = plan path + one line per step.
+
+## 0. Grill first (kill ambiguity before planning)
+
+A vague plan burns executor tokens on the wrong work. So interrogate the user BEFORE writing steps — surface hidden scope, constraints, and the acceptance bar. Grill hard, like a senior eng scoping a ticket.
+
+- First, self-answer: read the repo (paths, existing patterns, interfaces). Don't ask what the code already tells you.
+- Then ask via the `question` tool — batched, ≤4 per round, ≤2 rounds. Give concrete options, not open prompts.
+- Ask ONLY what changes the plan: true goal / scope edges, hard constraints (perf, deps, compat, style), acceptance bar (how "done" is checked), explicit out-of-bounds, unknown interfaces/paths, risky edge cases.
+- Skip the grill on a trivial or already-fully-specified task — don't interrogate for its own sake.
+- Stop when every step can be self-contained (§4) and acceptance concrete (§3). Fold every answer into the plan's `objective`/`contract`/`scope`/`acceptance`.
+
+## 1. Plan path
+
+Data dir: `$CLAUDE_PLUGIN_DATA`, else `${CLAUDE_PLUGIN_ROOT}/.nexum-data`, else `./.nexum-data`.
+Plan file: `<data_dir>/plan/<session_id>.md`. Session id = `$CLAUDE_SESSION_ID`, else `_nosession`. mkdir `plan/` first.
+
+## 2. Routing
+
+Every step: one route. Cheapest sufficient tier.
+
+- **mechanical** (cheapest model) — ALL true: boilerplate / mechanical refactor / test scaffold / well-specified single-file CRUD; full spec fits short prompt, no ambiguity; runnable acceptance statable; no architectural judgment.
+- **standard** — default. Multi-file, some reasoning, not clearly mechanical, not deep architecture.
+- **needs-strong** (capable model) — architecture, cross-cutting many files, ambiguous requirements, complex cross-layer debug.
+
+Doubt → standard.
+
+**Dependency beats tier.** Implementer runs tiers mechanical→standard→needs-strong. Step never routed to a tier running *before* a step it depends on. B consumes A → B tier ≥ A tier. Test of a standard step is standard (not mechanical). Final full-suite/verify step = highest tier of what it validates. Ordering prereqs first is not enough — tier must respect the dep too.
+
+## 3. Step schema (all six fields, this format)
+
+```
+### Step N: <short title>
+- route: mechanical | standard | needs-strong
+- files: <explicit comma-separated absolute/repo-relative paths to read/create/edit>
+- objective: <what this step does, 1-2 sentences, this step only>
+- contract: <exact signatures/interfaces/data shapes/file outputs later steps depend on — explicit enough for a model with no other context>
+- scope: do NOT touch <explicit out-of-bounds files/dirs>
+- acceptance: <one runnable shell command/assertion, exit 0 = pass, e.g. `python3 -m pytest tests/test_store.py -q`>
+```
+
+No field omitted/empty. Nothing to list → write `none`.
+
+## 4. Self-contained
+
+Steps run independently on models sharing no context. So:
+
+- Name every path explicitly. Not "the file from step 2" — the actual path.
+- State all config keys / constants / interfaces in `contract`.
+- `acceptance` = copy-pasteable, runnable from repo root, no substitutions.
+- Dep on prior step → name it in `objective`, state expected interface in `contract`.
+
+## 4a. Caveman style (token-saving feature)
+
+If `caveman_prompts_enabled` (from `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/store.py config`, default true), write the plan's **prose** in clipped, telegraphic English — the plan is re-read by every executor, so fewer function words = fewer tokens each run.
+
+Apply to: task summary, step `title`, `objective`, `contract` prose, `scope` prose. Drop articles (a/an/the), copulas (is/are/be), and filler. Imperative, clipped.
+
+**Keep EXACT — never caveman-ify or abbreviate:** file paths, identifiers, function/class/type names, signatures, config keys, code, the `route` value, the `files` list, and the `acceptance` command (must stay copy-pasteable + runnable from repo root).
+
+**Caveman ≠ vague.** Drop only function words, never information. A `contract` is read cold by a weaker executor — it must stay unambiguous. If trimming a word loses precision, keep the word.
+
+Flag false → normal prose.
+
+## 5. Plan file format + model selection
+
+```markdown
+# Plan: <brief task title>
+
+**Session:** <session_id>
+**Generated:** <ISO date>
+**Task summary:** <one sentence>
+
+**Models:**
+- mechanical: <model-id>
+- standard: <model-id>
+- needs-strong: <model-id>
+
+---
+
+### Step 1: <title>
+- route: ...
+- files: ...
+- objective: ...
+- contract: ...
+- scope: ...
+- acceptance: ...
+```
+
+After writing the plan draft, ask the user to pick models for each tier using the `question` tool:
+
+> Plan drafted. Which model for mechanical steps? (default: anthropic/claude-haiku-4-20250514)
+> Which model for standard steps? (default: anthropic/claude-sonnet-4-20250514)
+> Which model for needs-strong steps? (default: anthropic/claude-opus-4-20250514)
+
+Record choices under `**Models:**` in the plan file.
+
+After writing: print path + one line per step (`N · route · title`). Nothing else.
+
+## 6. Constraints
+
+- Plan only. Don't implement.
+- Don't invent paths — derive from task + repo (read files to confirm).
+- No vague acceptance ("it works"). Every acceptance = concrete command with verifiable exit code.
diff --git a/.opencode/commands/nx-report.md b/.opencode/commands/nx-report.md
new file mode 100644
index 0000000..ca38178
--- /dev/null
+++ b/.opencode/commands/nx-report.md
@@ -0,0 +1,18 @@
+---
+description: "Show this session's nexum digest: cost and wasted-context analysis."
+---
+
+You are the nexum reporter. Run the digest script and present it clearly.
+
+## 1. Run the digest
+
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/report.py --session "$CLAUDE_SESSION_ID"
+```
+
+## 2. Present
+
+- Cost: actual spend vs all-opus baseline, metered total
+- Wasted context: efficiency grade, waste ratio, "drop X → save ~N tokens" suggestions
+
+Keep concise. Prefix with `[nexum] `.
diff --git a/.opencode/commands/nx-save.md b/.opencode/commands/nx-save.md
new file mode 100644
index 0000000..ecf7225
--- /dev/null
+++ b/.opencode/commands/nx-save.md
@@ -0,0 +1,49 @@
+---
+description: "Write a session handoff so you can continue in a fresh session once a context or plan limit is near."
+---
+
+You are the nexum handoff writer. Capture everything a NEW session (which shares none of this conversation's context) needs to resume this work cleanly, and write it to a handoff file.
+
+## 1. Resolve the handoff path
+
+Resolve the data directory: `$CLAUDE_PLUGIN_DATA` if set, else `<git toplevel>/.nexum-data` (via `git rev-parse --show-toplevel`), else `./.nexum-data`. Session id from `$CLAUDE_SESSION_ID` (or `_nosession`).
+
+Create `<data_dir>/handoff/` if needed. Write the handoff to BOTH:
+- `<data_dir>/handoff/<session_id>.md`
+- `<data_dir>/handoff/latest.md`
+
+## 2. Gather real state (do not guess)
+
+- `git rev-parse --abbrev-ref HEAD`, `git status --short`, `git diff --stat`
+- Session task: `python3 -c "import sys; sys.path.insert(0,'${CLAUDE_PLUGIN_ROOT}/scripts'); import store; print(store.get_session_task('<session_id>') or '')"`
+- Actual work done from the conversation
+
+## 3. Write the handoff (self-contained, concise)
+
+```markdown
+# Handoff: <short task title>
+
+**Session:** <session_id>   **Branch:** <branch>   **Written:** <ISO datetime>
+**Why now:** <context near limit | 5h plan limit near | user-requested>
+
+## Goal
+<one or two sentences>
+
+## State now
+- <what is DONE and verified>
+- Uncommitted changes: <git diff --stat summary>
+- <key decisions / findings>
+
+## Next steps (in order)
+1. <concrete action, with file path / command>
+2. ...
+
+## How to resume
+- Read: <the 1-3 files most worth opening first>
+- Run: <the command(s) that re-establish state>
+- Watch out for: <gotchas>
+```
+
+## 4. Report
+
+Print the absolute path of the written handoff and a one-line summary. Also suggest `/compact` if context-triggered.
diff --git a/.opencode/commands/nx-status.md b/.opencode/commands/nx-status.md
new file mode 100644
index 0000000..795f1ea
--- /dev/null
+++ b/.opencode/commands/nx-status.md
@@ -0,0 +1,11 @@
+---
+description: "Display nexum session usage stats."
+---
+
+Show a compact summary of the current session's nexum stats:
+
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/report.py --session "$CLAUDE_SESSION_ID"
+```
+
+Display the output clearly.

From a02b7f5dada41360ffed9ecfcc0d61b705590114 Mon Sep 17 00:00:00 2001
From: Rahul Tyagi <rahul.1992.tyagi@gmail.com>
Date: Sat, 4 Jul 2026 19:13:43 +0530
Subject: [PATCH 06/16] fix: differentiate nx-status from nx-report, unify data
 dir resolution

---
 .opencode/commands/nx-load.md   | 2 +-
 .opencode/commands/nx-save.md   | 2 +-
 .opencode/commands/nx-status.md | 4 ++--
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.opencode/commands/nx-load.md b/.opencode/commands/nx-load.md
index 0dfb33f..35a55a0 100644
--- a/.opencode/commands/nx-load.md
+++ b/.opencode/commands/nx-load.md
@@ -6,7 +6,7 @@ You are the nexum handoff loader. The user wants to pick up where a previous ses
 
 ## 1. Locate the handoff
 
-Data directory: `$CLAUDE_PLUGIN_DATA` if set, else `<git toplevel>/.nexum-data` (via `git rev-parse --show-toplevel`), else `./.nexum-data`.
+Data directory: `$CLAUDE_PLUGIN_DATA` if set, else `${CLAUDE_PLUGIN_ROOT}/.nexum-data`, else `./.nexum-data`.
 
 Read `<data_dir>/handoff/latest.md`. If missing, check `<data_dir>/handoff/` for any `*.md` and offer the newest. No handoff → `[nexum] No handoff found. Nothing to resume.`
 
diff --git a/.opencode/commands/nx-save.md b/.opencode/commands/nx-save.md
index ecf7225..36a4b18 100644
--- a/.opencode/commands/nx-save.md
+++ b/.opencode/commands/nx-save.md
@@ -6,7 +6,7 @@ You are the nexum handoff writer. Capture everything a NEW session (which shares
 
 ## 1. Resolve the handoff path
 
-Resolve the data directory: `$CLAUDE_PLUGIN_DATA` if set, else `<git toplevel>/.nexum-data` (via `git rev-parse --show-toplevel`), else `./.nexum-data`. Session id from `$CLAUDE_SESSION_ID` (or `_nosession`).
+Resolve the data directory: `$CLAUDE_PLUGIN_DATA` if set, else `${CLAUDE_PLUGIN_ROOT}/.nexum-data`, else `./.nexum-data`. Session id from `$CLAUDE_SESSION_ID` (or `_nosession`).
 
 Create `<data_dir>/handoff/` if needed. Write the handoff to BOTH:
 - `<data_dir>/handoff/<session_id>.md`
diff --git a/.opencode/commands/nx-status.md b/.opencode/commands/nx-status.md
index 795f1ea..6221f97 100644
--- a/.opencode/commands/nx-status.md
+++ b/.opencode/commands/nx-status.md
@@ -2,10 +2,10 @@
 description: "Display nexum session usage stats."
 ---
 
-Show a compact summary of the current session's nexum stats:
+Display a compact one-line summary of the current session's nexum stats:
 
 ```
 python3 ${CLAUDE_PLUGIN_ROOT}/scripts/report.py --session "$CLAUDE_SESSION_ID"
 ```
 
-Display the output clearly.
+Extract and show: token savings, session cost, model, efficiency. Keep it to 1-3 lines.

From b1cea714cff338d93a31be08a7d88959be257a3a Mon Sep 17 00:00:00 2001
From: Rahul Tyagi <rahul.1992.tyagi@gmail.com>
Date: Sat, 4 Jul 2026 19:14:19 +0530
Subject: [PATCH 07/16] feat: add opencode agent definitions for nexum
 executors

---
 .opencode/agents/nexum-mechanical.md   | 27 ++++++++++++++++++++++++++
 .opencode/agents/nexum-needs-strong.md | 27 ++++++++++++++++++++++++++
 .opencode/agents/nexum-reviewer.md     | 11 +++++++++++
 .opencode/agents/nexum-standard.md     | 27 ++++++++++++++++++++++++++
 4 files changed, 92 insertions(+)
 create mode 100644 .opencode/agents/nexum-mechanical.md
 create mode 100644 .opencode/agents/nexum-needs-strong.md
 create mode 100644 .opencode/agents/nexum-reviewer.md
 create mode 100644 .opencode/agents/nexum-standard.md

diff --git a/.opencode/agents/nexum-mechanical.md b/.opencode/agents/nexum-mechanical.md
new file mode 100644
index 0000000..4928466
--- /dev/null
+++ b/.opencode/agents/nexum-mechanical.md
@@ -0,0 +1,27 @@
+---
+mode: subagent
+description: Executor for mechanical nexum steps (boilerplate, well-specified CRUD, test scaffold)
+permission:
+  edit: allow
+  bash: allow
+---
+
+You are a nexum executor running on a cheap model for mechanical steps. You receive **one step or a batch of steps** from the nexum plan. Implement them in the order given, in this one warm context — read any shared spec/files once and reuse them across steps rather than re-deriving per step.
+
+Implement ONLY the listed step(s). Do not touch files outside each step's declared `scope`.
+
+After implementing each step, verify it yourself by running the guardrail:
+
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/guardrail.py \
+  --acceptance "<acceptance command from the step>" \
+  --scope-root <repo root> \
+  --changed <comma-separated files you actually touched for this step>
+```
+
+Return contract — **keep it minimal; the orchestrator's context is shared across this whole batch, so every extra line you return is multiplied:**
+
+- **On PASS:** return ONLY the step index, a one-line summary, the files touched, and the **verbatim guardrail JSON**. Do NOT paste diffs, file contents, or step-by-step narration.
+- **On FAIL:** include the same fields **plus the unified diff** (`git diff -- <files>`).
+
+Never paraphrase the guardrail JSON — the orchestrator parses it directly.
diff --git a/.opencode/agents/nexum-needs-strong.md b/.opencode/agents/nexum-needs-strong.md
new file mode 100644
index 0000000..a192262
--- /dev/null
+++ b/.opencode/agents/nexum-needs-strong.md
@@ -0,0 +1,27 @@
+---
+mode: subagent
+description: Executor for complex nexum steps (architecture, ambiguity, cross-cutting, debugging)
+permission:
+  edit: allow
+  bash: allow
+---
+
+You are a nexum executor running on a capable model for `needs-strong` steps — work that involves architecture, ambiguity, cross-cutting changes, or debugging. You receive a self-contained step (or a small batch of related steps) from the nexum plan.
+
+Implement ONLY the listed step(s). Do not touch files outside each step's declared `scope`.
+
+After implementing, run the step's `acceptance` command via the guardrail:
+
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/guardrail.py \
+  --acceptance "<acceptance command from the step>" \
+  --scope-root <repo root> \
+  --changed <comma-separated files you actually touched>
+```
+
+Return contract — **keep it minimal:**
+
+- **On PASS:** return ONLY a one-line summary per step, the files touched, and the **verbatim guardrail JSON**. Do NOT paste diffs, file contents, or design narration. (For debugging steps, a 1–2 line note on root cause is fine.)
+- **On FAIL:** include the same fields **plus the unified diff** (`git diff -- <files>`).
+
+Never paraphrase the guardrail JSON.
diff --git a/.opencode/agents/nexum-reviewer.md b/.opencode/agents/nexum-reviewer.md
new file mode 100644
index 0000000..6dbe024
--- /dev/null
+++ b/.opencode/agents/nexum-reviewer.md
@@ -0,0 +1,11 @@
+---
+mode: subagent
+description: Reviews escalated nexum step implementations for correctness
+permission:
+  edit: deny
+  bash: allow
+---
+
+You are the nexum reviewer. You are invoked **selectively**, not after every step — the guardrail (acceptance command + scope check) is the routine gate.
+
+You receive a step from the nexum plan and the diff produced by its implementation. Verify the implementation against the step's `contract`, `scope`, and `acceptance` criteria. Return PASS or FAIL with concise reasons.
diff --git a/.opencode/agents/nexum-standard.md b/.opencode/agents/nexum-standard.md
new file mode 100644
index 0000000..14930c6
--- /dev/null
+++ b/.opencode/agents/nexum-standard.md
@@ -0,0 +1,27 @@
+---
+mode: subagent
+description: Executor for standard nexum steps (multi-file, some reasoning)
+permission:
+  edit: allow
+  bash: allow
+---
+
+You are a nexum executor running for standard steps. You receive **one step or a batch of steps** from the nexum plan. Implement them in the order given, in this one warm context — read any shared spec/files once and reuse them across steps rather than re-deriving per step.
+
+Implement ONLY the listed step(s). Do not touch files outside each step's declared `scope`.
+
+After implementing each step, verify it yourself by running the guardrail:
+
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/guardrail.py \
+  --acceptance "<acceptance command from the step>" \
+  --scope-root <repo root> \
+  --changed <comma-separated files you actually touched for this step>
+```
+
+Return contract — **keep it minimal; the orchestrator's context is shared across this whole batch, so every extra line you return is multiplied:**
+
+- **On PASS:** return ONLY the step index, a one-line summary, the files touched, and the **verbatim guardrail JSON**.
+- **On FAIL:** include the same fields **plus the unified diff** (`git diff -- <files>`).
+
+Never paraphrase the guardrail JSON — the orchestrator parses it directly.

From 87e86152aac91852a5e012ca653fe5fb0615886d Mon Sep 17 00:00:00 2001
From: Rahul Tyagi <rahul.1992.tyagi@gmail.com>
Date: Sat, 4 Jul 2026 19:15:31 +0530
Subject: [PATCH 08/16] fix: add structured verdict format to reviewer, add
 step index to needs-strong return contract

---
 .opencode/agents/nexum-needs-strong.md |  2 +-
 .opencode/agents/nexum-reviewer.md     | 14 +++++++++++++-
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/.opencode/agents/nexum-needs-strong.md b/.opencode/agents/nexum-needs-strong.md
index a192262..cad4cc4 100644
--- a/.opencode/agents/nexum-needs-strong.md
+++ b/.opencode/agents/nexum-needs-strong.md
@@ -21,7 +21,7 @@ python3 ${CLAUDE_PLUGIN_ROOT}/scripts/guardrail.py \
 
 Return contract — **keep it minimal:**
 
-- **On PASS:** return ONLY a one-line summary per step, the files touched, and the **verbatim guardrail JSON**. Do NOT paste diffs, file contents, or design narration. (For debugging steps, a 1–2 line note on root cause is fine.)
+- **On PASS:** return ONLY the step index, a one-line summary, the files touched, and the **verbatim guardrail JSON**. Do NOT paste diffs, file contents, or design narration. (For debugging steps, a 1–2 line note on root cause is fine.)
 - **On FAIL:** include the same fields **plus the unified diff** (`git diff -- <files>`).
 
 Never paraphrase the guardrail JSON.
diff --git a/.opencode/agents/nexum-reviewer.md b/.opencode/agents/nexum-reviewer.md
index 6dbe024..9879fdc 100644
--- a/.opencode/agents/nexum-reviewer.md
+++ b/.opencode/agents/nexum-reviewer.md
@@ -8,4 +8,16 @@ permission:
 
 You are the nexum reviewer. You are invoked **selectively**, not after every step — the guardrail (acceptance command + scope check) is the routine gate.
 
-You receive a step from the nexum plan and the diff produced by its implementation. Verify the implementation against the step's `contract`, `scope`, and `acceptance` criteria. Return PASS or FAIL with concise reasons.
+You receive a step from the nexum plan and the diff produced by its implementation. Verify the implementation against the step's `contract`, `scope`, and `acceptance` criteria.
+
+Return a structured verdict:
+
+```
+**Verdict:** PASS | FAIL
+**Reasons:**
+- <specific finding 1>
+- <specific finding 2>
+
+**Violations:**
+- <contract/scope/acceptance violations found, if any>
+```

From 0eaac794ed22d24ee6b7ea49c38d75c5da57ed00 Mon Sep 17 00:00:00 2001
From: Rahul Tyagi <rahul.1992.tyagi@gmail.com>
Date: Sat, 4 Jul 2026 19:16:19 +0530
Subject: [PATCH 09/16] feat: make pricing configurable via config.json
 get_pricing()

---
 scripts/cost_report.py  |  8 ++++----
 scripts/plan_preview.py |  4 ++--
 scripts/store.py        | 19 ++++++++++++++++++-
 3 files changed, 24 insertions(+), 7 deletions(-)

diff --git a/scripts/cost_report.py b/scripts/cost_report.py
index 5c51b9e..318ce30 100644
--- a/scripts/cost_report.py
+++ b/scripts/cost_report.py
@@ -74,7 +74,7 @@ def build_report(rows: list) -> str:
     if not rows:
         return "[nexum] No usage rows found."
 
-    opus_in, opus_out = store.PRICING["opus"]
+    opus_in, opus_out = store.get_pricing()["opus"]
 
     # Aggregate by model key
     # model_key -> {input_tok, output_tok, cache_read_tok, actual_cost}
@@ -91,11 +91,11 @@ def build_report(rows: list) -> str:
     for row in rows:
         key = _model_key(row.get("model", "unknown"))
 
-        if key in store.PRICING:
-            p_in, p_out = store.PRICING[key]
+        if key in store.get_pricing():
+            p_in, p_out = store.get_pricing()[key]
         else:
             # Unknown model: treat as sonnet (warn inline)
-            p_in, p_out = store.PRICING["sonnet"]
+            p_in, p_out = store.get_pricing()["sonnet"]
             key = f"{key}(unknown→sonnet rates)"
 
         actual = _row_cost(row, p_in, p_out)
diff --git a/scripts/plan_preview.py b/scripts/plan_preview.py
index aaa25f1..63e364e 100644
--- a/scripts/plan_preview.py
+++ b/scripts/plan_preview.py
@@ -133,7 +133,7 @@ def build_preview(steps: list, cfg: dict) -> str:
     in_tok = int(cfg.get("plan_preview_input_tok_per_step", 8000))
     out_tok = int(cfg.get("plan_preview_output_tok_per_step", 2000))
 
-    opus_in, opus_out = store.PRICING["opus"]
+    opus_in, opus_out = store.get_pricing()["opus"]
 
     # Per-tier aggregation
     # tier -> {count, in_tok_total, out_tok_total, actual_cost, baseline_cost}
@@ -142,7 +142,7 @@ def build_preview(steps: list, cfg: dict) -> str:
     for step in steps:
         route = step.get("route", "standard")
         tier = ROUTE_TIER.get(route, "sonnet")
-        price_in, price_out = store.PRICING.get(tier, store.PRICING["sonnet"])
+        price_in, price_out = store.get_pricing().get(tier, store.get_pricing()["sonnet"])
 
         step_actual = in_tok / 1e6 * price_in + out_tok / 1e6 * price_out
         step_baseline = in_tok / 1e6 * opus_in + out_tok / 1e6 * opus_out
diff --git a/scripts/store.py b/scripts/store.py
index 91c13ea..e472b92 100644
--- a/scripts/store.py
+++ b/scripts/store.py
@@ -30,17 +30,34 @@
 # Pricing: USD per 1M tokens — (input_price, output_price)
 # Cache read ≈ 0.1× input; cache write ≈ 1.25× input.
 # ---------------------------------------------------------------------------
-PRICING: Dict[str, tuple] = {
+DEFAULT_PRICING: Dict[str, tuple] = {
     "fable":  (10.0, 50.0),
     "opus":   (5.0,  25.0),
     "sonnet": (3.0,  15.0),
     "haiku":  (1.0,   5.0),
 }
 
+
+def get_pricing(cfg: Optional[dict] = None) -> Dict[str, tuple]:
+    """Return pricing dict, merging user overrides from config.
+
+    User config.json can contain {"pricing": {"my-model": (2.0, 10.0)}}
+    entry to add or override model rates. Returns defaults if no config.
+    """
+    if cfg is None:
+        cfg = get_config()
+    user_pricing = cfg.get("pricing", {})
+    base = dict(DEFAULT_PRICING)
+    for model, rates in user_pricing.items():
+        if isinstance(rates, (list, tuple)) and len(rates) == 2:
+            base[model] = (float(rates[0]), float(rates[1]))
+    return base
+
 # ---------------------------------------------------------------------------
 # Config defaults
 # ---------------------------------------------------------------------------
 _CONFIG_DEFAULTS: Dict[str, Any] = {
+    "pricing": {},
     "truncate_max_lines": 200,
     "truncate_head_lines": 120,
     "truncate_tail_lines": 60,

From 198287f182bb11d263c23235b140591cdf8ed511 Mon Sep 17 00:00:00 2001
From: Rahul Tyagi <rahul.1992.tyagi@gmail.com>
Date: Sat, 4 Jul 2026 19:18:12 +0530
Subject: [PATCH 10/16] fix: update test_pricing_has_fable to use
 DEFAULT_PRICING

---
 tests/test_gaps.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tests/test_gaps.py b/tests/test_gaps.py
index 9c4ef39..d6ea4d3 100644
--- a/tests/test_gaps.py
+++ b/tests/test_gaps.py
@@ -121,8 +121,8 @@ def test_missing_file_zeros(self):
 
 class TestFablePricing(_Base):
     def test_pricing_has_fable(self):
-        self.assertIn("fable", self.store.PRICING)
-        self.assertEqual(self.store.PRICING["fable"], (10.0, 50.0))
+        self.assertIn("fable", self.store.DEFAULT_PRICING)
+        self.assertEqual(self.store.DEFAULT_PRICING["fable"], (10.0, 50.0))
 
     def test_cost_report_maps_fable(self):
         import cost_report

From 88819eb3b9491ea85f92936709c632e828bd9c78 Mon Sep 17 00:00:00 2001
From: Rahul Tyagi <rahul.1992.tyagi@gmail.com>
Date: Sun, 5 Jul 2026 12:26:24 +0530
Subject: [PATCH 11/16] feat: finalize opencode port config and nx-plan agent
 binding

Compact opencode.json command descriptions and set nx-plan command to
run under the plan agent via frontmatter.
---
 .opencode/commands/nx-plan.md |  1 +
 opencode.json                 | 29 +++++++----------------------
 2 files changed, 8 insertions(+), 22 deletions(-)

diff --git a/.opencode/commands/nx-plan.md b/.opencode/commands/nx-plan.md
index 25b2fc1..374b359 100644
--- a/.opencode/commands/nx-plan.md
+++ b/.opencode/commands/nx-plan.md
@@ -1,5 +1,6 @@
 ---
 description: "Decompose the task into routed, self-contained steps and write a plan file. Each step routes to the cheapest model that can run it."
+agent: plan
 ---
 
 You are the nexum planner. Grill user (§0). Then decompose task into ordered, self-contained steps. Write plan file. Do NOT implement. Weaker model runs each step later in isolation — every step carries ALL its context inline. No references to "previous step."
diff --git a/opencode.json b/opencode.json
index 910bb52..6dca91d 100644
--- a/opencode.json
+++ b/opencode.json
@@ -1,28 +1,13 @@
 {
   "$schema": "https://opencode.ai/config.json",
   "command": {
-    "nx-plan": {
-      "agent": "plan",
-      "description": "Decompose task into tiered, self-contained steps with model selection"
-    },
-    "nx-build": {
-      "description": "Execute a nexum plan via cheapest capable tiers"
-    },
-    "nx-save": {
-      "description": "Write session handoff for clean resume"
-    },
-    "nx-load": {
-      "description": "Resume from most recent session handoff"
-    },
-    "nx-audit": {
-      "description": "Audit repo for context-risk files and ignore config"
-    },
-    "nx-report": {
-      "description": "Show session digest: cost + wasted-context analysis"
-    },
-    "nx-status": {
-      "description": "Show nexum session usage stats"
-    }
+    "nx-plan": { "agent": "plan", "description": "Decompose task into tiered, self-contained steps" },
+    "nx-build": { "description": "Execute a nexum plan via cheapest capable tiers" },
+    "nx-save": { "description": "Write session handoff for clean resume" },
+    "nx-load": { "description": "Resume from most recent session handoff" },
+    "nx-audit": { "description": "Audit repo for context-risk files" },
+    "nx-report": { "description": "Show session digest: cost + wasted-context analysis" },
+    "nx-status": { "description": "Show nexum session stats" }
   },
   "agent": {
     "nexum-mechanical": {

From f99ad41e5b0cc39f1f5f14da98dc4bbc53a45896 Mon Sep 17 00:00:00 2001
From: Rahul Tyagi <rahul.1992.tyagi@gmail.com>
Date: Wed, 8 Jul 2026 09:41:32 +0530
Subject: [PATCH 12/16] feat: add pi.dev CLI harness port of nexum

Single TypeScript extension (.pi/extensions/nexum-pi.ts) wraps existing
Python scripts via subprocess, wiring session/tool events and nx-*
commands into the pi.dev harness. Fix dead retry branch: step status
is 'fail' not 'failed'.
---
 .opencode/plans/pi-dev-port.md       | 114 +++++
 .pi/extensions/nexum-pi.ts           | 593 +++++++++++++++++++++++++++
 .pi/extensions/nexum-pi/package.json |   1 +
 3 files changed, 708 insertions(+)
 create mode 100644 .opencode/plans/pi-dev-port.md
 create mode 100644 .pi/extensions/nexum-pi.ts
 create mode 100644 .pi/extensions/nexum-pi/package.json

diff --git a/.opencode/plans/pi-dev-port.md b/.opencode/plans/pi-dev-port.md
new file mode 100644
index 0000000..a08c509
--- /dev/null
+++ b/.opencode/plans/pi-dev-port.md
@@ -0,0 +1,114 @@
+# Plan: pi.dev CLI harness port
+
+**Session:** _nosession
+**Generated:** 2026-07-04
+**Task summary:** Port all nexum features (hooks + commands + planner/executor) to pi.dev CLI harness via single TypeScript extension wrapping existing Python scripts.
+
+**Models:**
+- mechanical: any free model (e.g. nvidia/nemotron)
+- standard: current session model (inherit)
+- needs-strong: current session model (inherit)
+
+---
+
+### Step 1: Extension scaffolding + runScript helper
+- route: mechanical
+- files: `.pi/extensions/nexum-pi.ts`, `.pi/extensions/nexum-pi/package.json`
+- objective: Create extension skeleton. Export default factory function. Resolve NEXUM_ROOT from extension path. Implement runScript() subprocess wrapper (spawn python3, pipe JSON stdin/stdout, fail-open). Track currentSessionId.
+- contract: `.pi/extensions/nexum-pi/package.json` — empty package.json for jiti resolution. `.pi/extensions/nexum-pi.ts` — exports `export default function(pi: ExtensionAPI) { ... }`. Closes over `runScript(name, input, timeout?) → Promise<Record<string,any>>`, `NEXUM_ROOT` (abs path resolved from import.meta.url), `currentSessionId` (string, crypto.randomUUID() default). runScript sets `CLAUDE_PLUGIN_ROOT=NEXUM_ROOT` in subprocess env.
+- scope: do NOT touch scripts/ dir, commands/ dir, agents/ dir, .opencode/ dir, hooks/ dir
+- acceptance: `python3 -c "
+import re
+with open('.pi/extensions/nexum-pi.ts') as f: c = f.read()
+assert 'export default function' in c
+assert 'runScript' in c
+assert 'NEXUM_ROOT' in c
+assert 'currentSessionId' in c
+print('PASS')
+"`
+
+### Step 2: Session lifecycle + tool interceptor events
+- route: standard
+- files: `.pi/extensions/nexum-pi.ts`
+- objective: Wire pi.dev events to nexum Python scripts. session_start → session_reset.py + resume_nudge.py + audit_nudge.py. session_before_compact → precompact.py. tool_call → scan_guard.py (block/limit via permissionDecision, updatedInput) + predup.py (block re-read via permissionDecision). tool_result → dedup.py (collapse duplicate output, modify result content). Handle pi.dev event shapes -> Python script contracts.
+- contract: Inside factory function body, after step 1 hooks. `pi.on("session_start", handler)`: reads event.reason/event.previousSessionFile, calls session_reset/resume_nudge/audit_nudge. `pi.on("session_before_compact", handler)`: calls precompact.py. `pi.on("tool_call", handler)`: uses isToolCallEventType to narrow, mutates event.input for scan_guard updatedInput, returns {block} for denied calls. `pi.on("tool_result", handler)`: calls dedup.py, returns {content/details} patches. All handlers fail-open (try/catch, silent return on error).
+- scope: do NOT touch scripts/ dir, commands/ dir, .opencode/ dir, hooks/ dir
+- acceptance: `python3 -c "
+with open('.pi/extensions/nexum-pi.ts') as f: c = f.read()
+assert \"pi.on('session_start'\" in c or 'pi.on(\"session_start\"' in c
+assert \"pi.on('session_before_compact'\" in c or c.count('session_before_compact') > 0
+assert \"pi.on('tool_call'\" in c or 'pi.on(\"tool_call\"' in c
+assert \"pi.on('tool_result'\" in c or 'pi.on(\"tool_result\"' in c
+print('PASS')
+"`
+
+### Step 3: nx-plan command
+- route: needs-strong
+- files: `.pi/extensions/nexum-pi.ts`
+- objective: Register /nx-plan command. Handler: reads repo state (git branch, uncommitted changes, project structure via pi.exec or Bash), asks clarifying questions via ctx.ui.select/confirm/input, writes plan file to .nexum-data/plan/<session_id>.md, prompts model selection per tier, records choices in plan models section.
+- contract: `pi.registerCommand("nx-plan", { description: "...", handler: async (args, ctx) => { ... } })`. Plan file follows format: `# Plan: <title>\n**Session:** <sid>\n**Models:**\n- mechanical: <model>\n...\n---\n### Step N: <title>\n- route: ...\n- files: ...\n- objective: ...\n- contract: ...\n- scope: ...\n- acceptance: ...`. Plan path = `<data_dir>/plan/<currentSessionId>.md`. Uses runScript("store.py", args) for config/session ops. Uses ctx.ui for all user interaction (select/confirm/input/notify).
+- scope: do NOT touch scripts/ dir, commands/ dir, .opencode/ dir, hooks/ dir
+- acceptance: `python3 -c "
+with open('.pi/extensions/nexum-pi.ts') as f: c = f.read()
+assert 'nx-plan' in c
+assert 'pi.registerCommand' in c
+print('PASS')
+"`
+
+### Step 4: nx-build command (orchestrator)
+- route: needs-strong
+- files: `.pi/extensions/nexum-pi.ts`
+- objective: Register /nx-build command. Handler: reads plan file, parses steps + model selections, dispatches per tier group. For each group: pi.setModel(tierModel) → pi.sendUserMessage(step instructions) → ctx.waitForIdle() → run guardrail.py verification → record pass/fail. Retry same tier on fail (up to 1), escalate one tier (mechanical→standard→needs-strong). Final cost report via runScript("cost_report.py"). All step messages include command, objective, contract, scope, acceptance verbatim.
+- contract: `pi.registerCommand("nx-build", { description: "...", handler: async (args, ctx) => { ... } })`. Plan read from `<data_dir>/plan/<currentSessionId>.md`. Parses plan models section. Step dispatch: for each step group (same route/tier), call `await pi.setModel(modelId); await pi.sendUserMessage(stepMsg); await ctx.waitForIdle();`. Acceptance check: `await pi.exec('python3 <NEXUM_ROOT>/scripts/guardrail.py --acceptance \"<cmd>\" --scope-root <root> --changed <files>')`. Retry: same tier up to 1 retry, escalate one tier if still failing. Cost summary: `await runScript("cost_report.py", { session_id })`. Print minimal output: failures, escalations, final cost. No per-step success chatter.
+- scope: do NOT touch scripts/ dir, commands/ dir, .opencode/ dir, hooks/ dir
+- acceptance: `python3 -c "
+with open('.pi/extensions/nexum-pi.ts') as f: c = f.read()
+assert 'nx-build' in c
+assert 'setModel' in c or 'sendUserMessage' in c
+print('PASS')
+"`
+
+### Step 5: Terminal commands — nx-save, nx-load, nx-audit, nx-report, nx-status
+- route: mechanical
+- files: `.pi/extensions/nexum-pi.ts`
+- objective: Register 5 terminal commands. Each wraps a Python script call. nx-save: write session handoff to .nexum-data/handoff/<session_id>.md. nx-load: read latest handoff, display summary. nx-audit: run audit.py, show findings, offer --write fix. nx-report: run report.py, display session digest. nx-status: run report.py with --session flag, display compact stats.
+- contract: `pi.registerCommand("nx-save", handler)` — resolves data dir, calls handoff.py via runScript, writes to .nexum-data/handoff/. `pi.registerCommand("nx-load", handler)` — reads .nexum-data/handoff/latest.md, shows summary. `pi.registerCommand("nx-audit", handler)` — runs audit.py, displays findings, ctx.ui.confirm for --write. `pi.registerCommand("nx-report", handler)` — runs report.py --session, displays output. `pi.registerCommand("nx-status", handler)` — runs report.py --session, displays compact stats. All use `ctx.ui.notify` or `ctx.ui.setWidget` for TUI display.
+- scope: do NOT touch scripts/ dir, commands/ dir, .opencode/ dir, hooks/ dir
+- acceptance: `python3 -c "
+with open('.pi/extensions/nexum-pi.ts') as f: c = f.read()
+for cmd in ['nx-save','nx-load','nx-audit','nx-report','nx-status']:
+    assert cmd in c, f'{cmd} not found'
+print('PASS')
+"`
+
+### Step 6: Integration verification
+- route: standard
+- files: `.pi/extensions/nexum-pi.ts`, `.pi/extensions/nexum-pi/package.json`
+- objective: Verify extension file is valid. All events + commands registered. Python scripts callable from extension with CLAUDE_PLUGIN_ROOT set. Enumerate every feature and confirm.
+- contract: Assertions: (a) file exports default function, (b) runScript exists, (c) NEXUM_ROOT resolved, (d) session_start handler registered, (e) session_before_compact handler registered, (f) tool_call handler with isToolCallEventType, (g) tool_result handler, (h) 7 commands registered (nx-plan, nx-build, nx-save, nx-load, nx-audit, nx-report, nx-status). Verify Python scripts accept stdin JSON: `echo '{}' | python3 scripts/session_reset.py` exits 0.
+- scope: do NOT touch scripts/ dir, commands/ dir, .opencode/ dir, hooks/ dir
+- acceptance: `python3 -c "
+import re
+with open('.pi/extensions/nexum-pi.ts') as f: c = f.read()
+checks = [
+    ('default function', 'export default function' in c),
+    ('runScript', 'runScript' in c),
+    ('session_start', 'session_start' in c),
+    ('session_before_compact', 'session_before_compact' in c),
+    ('tool_call', \"tool_call\" in c or 'tool_call' in c),
+    ('tool_result', \"tool_result\" in c or 'tool_result' in c),
+    ('nx-plan', 'nx-plan' in c),
+    ('nx-build', 'nx-build' in c),
+    ('nx-save', 'nx-save' in c),
+    ('nx-load', 'nx-load' in c),
+    ('nx-audit', 'nx-audit' in c),
+    ('nx-report', 'nx-report' in c),
+    ('nx-status', 'nx-status' in c),
+    ('spawn import', 'spawn' in c),
+]
+fails = [name for name, ok in checks if not ok]
+if fails:
+    print(f'FAIL: {fails}')
+    exit(1)
+print('PASS')
+"`
diff --git a/.pi/extensions/nexum-pi.ts b/.pi/extensions/nexum-pi.ts
new file mode 100644
index 0000000..5a2f789
--- /dev/null
+++ b/.pi/extensions/nexum-pi.ts
@@ -0,0 +1,593 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { spawn } from "child_process";
+import path from "path";
+import crypto from "crypto";
+import fs from "fs";
+
+// nexum repo root, resolved from: <repo>/.pi/extensions/nexum-pi.ts
+const NEXUM_ROOT = path.resolve(import.meta.dirname, "../..");
+const SCRIPTS_DIR = path.join(NEXUM_ROOT, "scripts");
+const DATA_DIR = path.join(NEXUM_ROOT, ".nexum-data");
+
+let currentSessionId = crypto.randomUUID();
+
+/**
+ * Run a Python script via JSON-over-stdin/stdout (hook-compatible protocol).
+ * Writes `input` as JSON to stdin, reads JSON from stdout, fail-opens to {}.
+ */
+function runScript(
+  name: string,
+  input: Record<string, any>,
+  timeout = 10000,
+): Promise<Record<string, any>> {
+  return new Promise((resolve) => {
+    const child = spawn("python3", [path.join(SCRIPTS_DIR, name)], {
+      env: { ...process.env, CLAUDE_PLUGIN_ROOT: NEXUM_ROOT },
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    const timer = setTimeout(() => {
+      child.kill();
+      resolve({});
+    }, timeout);
+
+    try {
+      child.stdin.write(JSON.stringify(input));
+      child.stdin.end();
+    } catch {
+      child.kill();
+      clearTimeout(timer);
+      resolve({});
+      return;
+    }
+
+    let stdout = "";
+    child.stdout.on("data", (d: Buffer) => {
+      stdout += d.toString();
+    });
+    child.on("close", () => {
+      clearTimeout(timer);
+      try {
+        resolve(JSON.parse(stdout));
+      } catch {
+        resolve({});
+      }
+    });
+    child.on("error", () => {
+      clearTimeout(timer);
+      resolve({});
+    });
+  });
+}
+
+export default function (pi: ExtensionAPI) {
+  // ---------------------------------------------------------------------------
+  // Session lifecycle
+  // ---------------------------------------------------------------------------
+  pi.on("session_start", async (event: any, ctx: any) => {
+    try {
+      const sid = event?.session_id ?? event?.sessionId ?? currentSessionId;
+      currentSessionId = sid;
+      const cwd = event?.cwd ?? NEXUM_ROOT;
+      await runScript("session_reset.py", { session_id: sid });
+      await runScript("resume_nudge.py", { session_id: sid, source: event?.reason ?? "startup", cwd });
+      await runScript("audit_nudge.py", { session_id: sid, source: event?.reason ?? "startup", cwd });
+    } catch {
+      // fail-open
+    }
+  });
+
+  pi.on("session_before_compact", async (event: any, ctx: any) => {
+    try {
+      const sid = currentSessionId;
+      const cwd = event?.cwd ?? NEXUM_ROOT;
+      await runScript("precompact.py", {
+        session_id: sid,
+        cwd,
+        transcript_path: event?.transcript_path ?? "",
+        trigger: event?.reason ?? "compacted",
+      });
+    } catch {
+      // fail-open
+    }
+  });
+
+  // ---------------------------------------------------------------------------
+  // Tool call/result interceptors
+  // ---------------------------------------------------------------------------
+  pi.on("tool_call", async (event: any, ctx: any) => {
+    try {
+      if (event.toolName === "read" || event.toolName === "bash" || event.toolName === "grep" || event.toolName === "glob") {
+        const scanResult = await runScript("scan_guard.py", {
+          session_id: currentSessionId,
+          tool_name: event.toolName,
+          tool_input: event.input ?? {},
+        });
+        if (scanResult?.hookSpecificOutput?.permissionDecision) {
+          ctx.ui.notify?.({ title: "nexum", message: `Blocked ${event.toolName} call` });
+          return { block: true, reason: scanResult.hookSpecificOutput.permissionDecisionReason ?? "Blocked by scan_guard" };
+        }
+        if (scanResult?.hookSpecificOutput?.updatedInput) {
+          Object.assign(event.input, scanResult.hookSpecificOutput.updatedInput);
+        }
+      }
+
+      const predupResult = await runScript("predup.py", {
+        session_id: currentSessionId,
+        tool_name: event.toolName,
+        tool_input: event.input ?? {},
+      });
+      if (predupResult?.hookSpecificOutput?.permissionDecision) {
+        return { block: true, reason: predupResult.hookSpecificOutput.permissionDecisionReason ?? "Blocked by predup" };
+      }
+    } catch {
+      // fail-open
+    }
+  });
+
+  pi.on("tool_result", async (event: any, ctx: any) => {
+    try {
+      const dedupResult = await runScript("dedup.py", {
+        session_id: currentSessionId,
+        tool_name: event.toolName,
+        tool_input: event.input ?? {},
+        tool_use_id: event.toolCallId ?? "",
+        transcript_path: "",
+        tool_response: event.content ?? "",
+      });
+      if (dedupResult?.hookSpecificOutput?.updatedToolOutput) {
+        return { content: dedupResult.hookSpecificOutput.updatedToolOutput };
+      }
+    } catch {
+      // fail-open
+    }
+  });
+
+  // ---------------------------------------------------------------------------
+  // nx-plan — interactive plan creation
+  // ---------------------------------------------------------------------------
+  pi.registerCommand("nx-plan", {
+    description: "Decompose current task into tiered, self-contained steps and write plan file",
+    handler: async (args: any, ctx: any) => {
+      if (!ctx.hasUI) return;
+
+      const planDir = path.join(DATA_DIR, "plan");
+      fs.mkdirSync(planDir, { recursive: true });
+
+      const sid = currentSessionId;
+      const planPath = path.join(planDir, `${sid}.md`);
+
+      // Gather repo context
+      const branch = await pi.exec("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: NEXUM_ROOT });
+      const gitStatus = await pi.exec("git", ["status", "--short"], { cwd: NEXUM_ROOT });
+
+      // Ask user clarifying questions
+      const goal = await ctx.ui.input("What task should nexum plan? Describe the goal.");
+      if (!goal) { ctx.ui.notify("nx-plan cancelled.", "warning"); return; }
+
+      // Determine number of steps
+      const stepCountStr = await ctx.ui.input("How many steps? (2-8, or press Enter for auto-estimate)");
+      const stepCount = stepCountStr ? Math.min(Math.max(parseInt(stepCountStr, 10) || 4, 2), 8) : 4;
+
+      // Ask for scope and constraints
+      const constraints = await ctx.ui.input("Any constraints, out-of-bounds areas, or acceptance criteria?");
+
+      // Ask model selection per tier
+      const mechanicalModel = await ctx.ui.input("Model for mechanical steps? (default: haiku)") || "haiku";
+      const standardModel = await ctx.ui.input("Model for standard steps? (default: sonnet)") || "sonnet";
+      const strongModel = await ctx.ui.input("Model for needs-strong steps? (default: opus)") || "opus";
+
+      // Read last few script files to understand project structure
+      const files = (await pi.exec("ls", ["-la"], { cwd: NEXUM_ROOT })) || "";
+
+      // Write plan template
+      const plan = [
+        `# Plan: ${goal}`,
+        "",
+        `**Session:** ${sid}`,
+        `**Generated:** ${new Date().toISOString().split("T")[0]}`,
+        `**Task summary:** ${goal}`,
+        "",
+        "**Models:**",
+        `- mechanical: ${mechanicalModel}`,
+        `- standard: ${standardModel}`,
+        `- needs-strong: ${strongModel}`,
+        "",
+        "---",
+        "",
+      ];
+      for (let i = 1; i <= stepCount; i++) {
+        plan.push(
+          `### Step ${i}: `,
+          `- route: `,
+          `- files: `,
+          `- objective: `,
+          `- contract: `,
+          `- scope: `,
+          `- acceptance: `,
+          "",
+        );
+      }
+      fs.writeFileSync(planPath, plan.join("\n"));
+
+      ctx.ui.notify(`Plan template written: ${planPath}`);
+      ctx.ui.setWidget("nexum-plan", [
+        `Goal: ${goal}`,
+        `Steps: ${stepCount}`,
+        `Models: mech=${mechanicalModel} std=${standardModel} strong=${strongModel}`,
+        `File: ${planPath}`,
+      ]);
+    },
+  });
+
+  // ---------------------------------------------------------------------------
+  // nx-build — execute a nexum plan
+  // ---------------------------------------------------------------------------
+  pi.registerCommand("nx-build", {
+    description: "Execute a nexum plan: dispatch steps, verify acceptance, report cost",
+    handler: async (args: any, ctx: any) => {
+      const sid = currentSessionId;
+      const planDir = path.join(DATA_DIR, "plan");
+      const planPath = path.join(planDir, `${sid}.md`);
+
+      if (!fs.existsSync(planPath)) {
+        if (ctx.hasUI) ctx.ui.notify("No plan found. Run /nx-plan first.", "error");
+        return;
+      }
+
+      // Parse plan file for models and steps
+      const planContent = fs.readFileSync(planPath, "utf-8");
+      const lines = planContent.split("\n");
+
+      // Extract models
+      const models: Record<string, string> = {};
+      let inModels = false;
+      for (const line of lines) {
+        if (line.trim() === "---") break;
+        if (line.trim() === "**Models:**") { inModels = true; continue; }
+        if (inModels && line.startsWith("- ")) {
+          const m = line.match(/-\s*(\w+):\s*(.+)/);
+          if (m) models[m[1]] = m[2].trim();
+        }
+      }
+
+      // Extract steps
+      interface Step {
+        index: number;
+        route: string;
+        files: string;
+        objective: string;
+        contract: string;
+        scope: string;
+        acceptance: string;
+      }
+      const steps: Step[] = [];
+      let currentStep: Partial<Step> | null = null;
+      for (const line of lines) {
+        const stepMatch = line.match(/### Step (\d+):/);
+        if (stepMatch) {
+          if (currentStep && currentStep.index) steps.push(currentStep as Step);
+          currentStep = { index: parseInt(stepMatch[1], 10) };
+          continue;
+        }
+        if (!currentStep) continue;
+        const routeMatch = line.match(/- route:\s*(.+)/);
+        if (routeMatch) { currentStep.route = routeMatch[1].trim(); continue; }
+        const filesMatch = line.match(/- files:\s*(.+)/);
+        if (filesMatch) { currentStep.files = filesMatch[1]; continue; }
+        const objMatch = line.match(/- objective:\s*(.+)/);
+        if (objMatch) { currentStep.objective = objMatch[1]; continue; }
+        const contractMatch = line.match(/- contract:\s*(.+)/);
+        if (contractMatch) { currentStep.contract = contractMatch[1]; continue; }
+        const scopeMatch = line.match(/- scope:\s*(.+)/);
+        if (scopeMatch) { currentStep.scope = scopeMatch[1]; continue; }
+        const accMatch = line.match(/- acceptance:\s*(.+)/);
+        if (accMatch) { currentStep.acceptance = accMatch[1]; continue; }
+      }
+      if (currentStep && currentStep.index) steps.push(currentStep as Step);
+
+      if (steps.length === 0) {
+        if (ctx.hasUI) ctx.ui.notify("No steps found in plan.", "error");
+        return;
+      }
+
+      // Group by route (tier): mechanical → standard → needs-strong
+      const routeOrder = ["mechanical", "standard", "needs-strong"];
+      const grouped: Record<string, Step[]> = { mechanical: [], standard: [], "needs-strong": [] };
+      for (const s of steps) {
+        const r = s.route || "standard";
+        if (!grouped[r]) grouped[r] = [];
+        grouped[r].push(s);
+      }
+
+      // Resolve actual model from ctx.model (pi.dev) or fallback
+      const actualModelId = (ctx as any)?.model?.id || "";
+
+      interface StepResult { index: number; status: "pass" | "fail"; }
+      const results: StepResult[] = [];
+
+      for (const tier of routeOrder) {
+        const tierSteps = grouped[tier];
+        if (tierSteps.length === 0) continue;
+
+        const planModel = models[tier];
+        const resolvedModel = actualModelId || planModel || tier;
+        const isInherit = planModel === "current session model (inherit)";
+
+        if (!isInherit && planModel) {
+          try { await pi.setModel(planModel); } catch { /* best-effort */ }
+        }
+
+        for (const step of tierSteps) {
+          // Build step message with full context
+          const stepMsg = [
+            `## Execute step ${step.index}: ${step.objective}`,
+            "",
+            `**Files:** ${step.files}`,
+            `**Objective:** ${step.objective}`,
+            `**Contract:** ${step.contract || "see acceptance"}`,
+            `**Scope:** ${step.scope || "none"}`,
+            "",
+            `**Acceptance:** ${step.acceptance || "none"}`,
+            "",
+            `Implement this step. After implementation, verify acceptance.`,
+            `Do not modify files outside the declared scope.`,
+          ].join("\n");
+
+          // Send to agent and wait
+          await pi.sendUserMessage(stepMsg);
+
+          // Wait for agent to become idle
+          try { await ctx.waitForIdle(); } catch { /* timeout or abort */ }
+
+          // Run acceptance via guardrail
+          if (step.acceptance) {
+            const { exitCode } = await pi.exec("python3", [
+              path.join(SCRIPTS_DIR, "guardrail.py"),
+              "--acceptance", step.acceptance,
+              "--scope-root", NEXUM_ROOT,
+              ...(step.files ? ["--changed", step.files] : []),
+            ], { cwd: NEXUM_ROOT });
+
+            const status = exitCode === 0 ? "pass" : "fail";
+            results.push({ index: step.index, status });
+
+            // Record in ledger with actual model ID
+            await runScript("store.py", {
+              cmd: "step-set",
+              session: sid,
+              planHash: "",
+              index: step.index,
+              status: status === "pass" ? "done" : "failed",
+              title: step.objective,
+              route: tier,
+              tier: resolvedModel,
+            });
+
+            if (status === "fail") {
+              if (ctx.hasUI) ctx.ui.notify(`Step ${step.index} failed. Retrying...`, "warning");
+              // Retry once
+              try { await pi.setModel(resolvedModel); } catch { /* best-effort */ }
+              await pi.sendUserMessage(`Retry step ${step.index}.\nPrevious attempt failed.\n\n${stepMsg}`);
+              try { await ctx.waitForIdle(); } catch { /* ignore */ }
+
+              const retryExit = (await pi.exec("python3", [
+                path.join(SCRIPTS_DIR, "guardrail.py"),
+                "--acceptance", step.acceptance,
+                "--scope-root", NEXUM_ROOT,
+                ...(step.files ? ["--changed", step.files] : []),
+              ], { cwd: NEXUM_ROOT })).exitCode;
+
+              if (retryExit !== 0 && ctx.hasUI) {
+                ctx.ui.notify(`Step ${step.index} failed after retry. Escalate manually.`, "error");
+              }
+            }
+          } else {
+            results.push({ index: step.index, status: "pass" });
+          }
+        }
+      }
+
+      // Final cost report
+      const costChild = spawn("python3", [
+        path.join(SCRIPTS_DIR, "cost_report.py"),
+        "--session", sid,
+      ], { env: { ...process.env, CLAUDE_PLUGIN_ROOT: NEXUM_ROOT } });
+
+      let costOut = "";
+      costChild.stdout.on("data", (d: Buffer) => { costOut += d.toString(); });
+      costChild.on("close", () => {
+        if (!ctx.hasUI) return;
+        ctx.ui.setWidget("nexum-cost", costOut || "Cost report unavailable.");
+      });
+    },
+  });
+
+  // ---------------------------------------------------------------------------
+  // nx-save — write session handoff to .nexum-data/handoff/<session_id>.md
+  // ---------------------------------------------------------------------------
+  pi.registerCommand("nx-save", {
+    description: "Write a session handoff to .nexum-data/handoff/<session_id>.md",
+    handler: async (args: any, ctx: any) => {
+      const sessionId = args.session ?? currentSessionId;
+      const cwd = args.cwd ?? NEXUM_ROOT;
+
+      const child = spawn("python3", [
+        path.join(SCRIPTS_DIR, "handoff.py"),
+        "write",
+        "--session",
+        sessionId,
+        "--cwd",
+        cwd,
+        ...(args.tokens ? ["--tokens", String(args.tokens)] : []),
+      ], { env: { ...process.env, CLAUDE_PLUGIN_ROOT: NEXUM_ROOT } });
+
+      let stdout = "";
+      child.stdout.on("data", (d: Buffer) => { stdout += d.toString(); });
+
+      return new Promise<void>((resolve) => {
+        child.on("close", () => {
+          try {
+            const result = JSON.parse(stdout.trim() || "{}");
+            if (!ctx.hasUI) { resolve(); return; }
+            if (result.ok) {
+              ctx.ui.notify?.({ title: "nx-save", message: "Handoff written to .nexum-data/handoff/" });
+            } else {
+              ctx.ui.notify?.({ title: "nx-save", message: "Handoff failed", type: "error" });
+            }
+          } catch {
+            if (ctx.hasUI) ctx.ui.notify?.({ title: "nx-save", message: "Handoff failed", type: "error" });
+          }
+          resolve();
+        });
+        child.on("error", () => {
+          if (ctx.hasUI) ctx.ui.notify?.({ title: "nx-save", message: "Handoff failed", type: "error" });
+          resolve();
+        });
+      });
+    },
+  });
+
+  // ---------------------------------------------------------------------------
+  // nx-load — read latest handoff, display summary
+  // ---------------------------------------------------------------------------
+  pi.registerCommand("nx-load", {
+    description: "Read the latest handoff and display a summary",
+    handler: async (_args: any, ctx: any) => {
+      const latestPath = path.join(DATA_DIR, "handoff", "latest.md");
+      let content: string;
+      try {
+        content = fs.readFileSync(latestPath, "utf-8");
+      } catch {
+        if (ctx.hasUI) ctx.ui.notify?.({ title: "nx-load", message: "No handoff found", type: "warning" });
+        return;
+      }
+
+      if (!ctx.hasUI) return;
+
+      // Show first 8 lines as a summary notification
+      const summary = content.split("\n").slice(0, 8).join("\n");
+      ctx.ui.notify?.({ title: "nx-load", message: summary });
+      ctx.ui.setWidget?.({ id: "nexum-handoff", content });
+    },
+  });
+
+  // ---------------------------------------------------------------------------
+  // nx-audit — run audit.py, show findings, offer --write fix
+  // ---------------------------------------------------------------------------
+  pi.registerCommand("nx-audit", {
+    description: "Run audit.py, show findings, offer --write fix",
+    handler: async (args: any, ctx: any) => {
+      const root = args.root ?? NEXUM_ROOT;
+
+      // First pass: read-only audit
+      const child = spawn("python3", [
+        path.join(SCRIPTS_DIR, "audit.py"),
+        "--root", root,
+      ], { env: { ...process.env, CLAUDE_PLUGIN_ROOT: NEXUM_ROOT } });
+
+      let stdout = "";
+      child.stdout.on("data", (d: Buffer) => { stdout += d.toString(); });
+
+      return new Promise<void>((resolve) => {
+        child.on("close", async () => {
+          if (!ctx.hasUI) { resolve(); return; }
+
+          // Show findings
+          ctx.ui.setWidget?.({ id: "nexum-audit", content: stdout || "Audit returned no output." });
+
+          // If issues found and user didn't already pass --write, offer to fix
+          if (!args.write && stdout.includes("issues found")) {
+            const confirmed = await ctx.ui.confirm?.("Apply suggested ignore-file patterns?");
+            if (confirmed) {
+              const writer = spawn("python3", [
+                path.join(SCRIPTS_DIR, "audit.py"),
+                "--root", root, "--write",
+              ], { env: { ...process.env, CLAUDE_PLUGIN_ROOT: NEXUM_ROOT } });
+              let wOut = "";
+              writer.stdout.on("data", (d: Buffer) => { wOut += d.toString(); });
+              writer.on("close", () => {
+                ctx.ui.setWidget?.({ id: "nexum-audit-result", content: wOut || "Patterns applied." });
+                ctx.ui.notify?.({ title: "nx-audit", message: "Ignore-file patterns applied." });
+                resolve();
+              });
+              writer.on("error", () => { resolve(); });
+              return;
+            }
+            ctx.ui.notify?.({ title: "nx-audit", message: "Audit complete (no changes)." });
+          } else {
+            ctx.ui.notify?.({ title: "nx-audit", message: "Audit complete." });
+          }
+          resolve();
+        });
+        child.on("error", () => {
+          if (ctx.hasUI) ctx.ui.notify?.({ title: "nx-audit", message: "Audit failed", type: "error" });
+          resolve();
+        });
+      });
+    },
+  });
+
+  // ---------------------------------------------------------------------------
+  // nx-report — run report.py, display session digest
+  // ---------------------------------------------------------------------------
+  pi.registerCommand("nx-report", {
+    description: "Run report.py and display session digest",
+    handler: async (args: any, ctx: any) => {
+      const sessionArg = args.session ? ["--session", args.session] : [];
+
+      const child = spawn("python3", [
+        path.join(SCRIPTS_DIR, "report.py"),
+        ...sessionArg,
+      ], { env: { ...process.env, CLAUDE_PLUGIN_ROOT: NEXUM_ROOT } });
+
+      let stdout = "";
+      child.stdout.on("data", (d: Buffer) => { stdout += d.toString(); });
+
+      return new Promise<void>((resolve) => {
+        child.on("close", () => {
+          if (!ctx.hasUI) { resolve(); return; }
+          ctx.ui.setWidget?.({ id: "nexum-report", content: stdout || "No report data." });
+          ctx.ui.notify?.({ title: "nx-report", message: "Report generated." });
+          resolve();
+        });
+        child.on("error", () => {
+          if (ctx.hasUI) ctx.ui.notify?.({ title: "nx-report", message: "Report failed", type: "error" });
+          resolve();
+        });
+      });
+    },
+  });
+
+  // ---------------------------------------------------------------------------
+  // nx-status — run report.py --session, display compact stats
+  // ---------------------------------------------------------------------------
+  pi.registerCommand("nx-status", {
+    description: "Run report.py --session and display compact stats",
+    handler: async (args: any, ctx: any) => {
+      const sessionId = args.session ?? currentSessionId;
+
+      const child = spawn("python3", [
+        path.join(SCRIPTS_DIR, "report.py"),
+        "--session", sessionId,
+      ], { env: { ...process.env, CLAUDE_PLUGIN_ROOT: NEXUM_ROOT } });
+
+      let stdout = "";
+      child.stdout.on("data", (d: Buffer) => { stdout += d.toString(); });
+
+      return new Promise<void>((resolve) => {
+        child.on("close", () => {
+          if (!ctx.hasUI) { resolve(); return; }
+          const lines = (stdout || "").split("\n").filter((l) => l.trim());
+          const compact = lines.slice(0, 10).join("\n");
+          ctx.ui.setWidget?.({ id: "nexum-status", content: compact || "No data." });
+          resolve();
+        });
+        child.on("error", () => {
+          if (ctx.hasUI) ctx.ui.notify?.({ title: "nx-status", message: "Status failed", type: "error" });
+          resolve();
+        });
+      });
+    },
+  });
+}
diff --git a/.pi/extensions/nexum-pi/package.json b/.pi/extensions/nexum-pi/package.json
new file mode 100644
index 0000000..0967ef4
--- /dev/null
+++ b/.pi/extensions/nexum-pi/package.json
@@ -0,0 +1 @@
+{}

From 34dc54334d9ddf5ae6ddf1f80099a4bfb3fc45c2 Mon Sep 17 00:00:00 2001
From: Rahul Tyagi <rahul.1992.tyagi@gmail.com>
Date: Wed, 8 Jul 2026 09:41:32 +0530
Subject: [PATCH 13/16] fix: show real model name in cost report breakdown
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Preserve the raw model id for display instead of the normalized key,
and annotate unknown models as '(→sonnet rates)' without corrupting
the breakdown key.
---
 scripts/cost_report.py | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/scripts/cost_report.py b/scripts/cost_report.py
index 318ce30..cb9b179 100644
--- a/scripts/cost_report.py
+++ b/scripts/cost_report.py
@@ -89,14 +89,15 @@ def build_report(rows: list) -> str:
     has_shipped_tokens = False  # noqa: always False in v1
 
     for row in rows:
-        key = _model_key(row.get("model", "unknown"))
+        raw_model = row.get("model", "unknown")
+        key = _model_key(raw_model)
+        display_model = raw_model if raw_model != "unknown" else key
 
         if key in store.get_pricing():
             p_in, p_out = store.get_pricing()[key]
         else:
-            # Unknown model: treat as sonnet (warn inline)
             p_in, p_out = store.get_pricing()["sonnet"]
-            key = f"{key}(unknown→sonnet rates)"
+            display_model = f"{raw_model} (→sonnet rates)"
 
         actual = _row_cost(row, p_in, p_out)
         baseline = _row_cost(row, opus_in, opus_out)
@@ -104,8 +105,8 @@ def build_report(rows: list) -> str:
         total_actual += actual
         total_baseline += baseline
 
-        if key not in breakdown:
-            breakdown[key] = {
+        if display_model not in breakdown:
+            breakdown[display_model] = {
                 "input_tok": 0,
                 "output_tok": 0,
                 "cache_read_tok": 0,
@@ -113,7 +114,7 @@ def build_report(rows: list) -> str:
                 "baseline_cost": 0.0,
                 "rows": 0,
             }
-        bd = breakdown[key]
+        bd = breakdown[display_model]
         bd["input_tok"]      += row["input_tok"]
         bd["output_tok"]     += row["output_tok"]
         bd["cache_read_tok"] += row.get("cache_read_tok", 0)

From 2ab2a1e3480d21f3d342b9e6ba2907827921a202 Mon Sep 17 00:00:00 2001
From: Rahul Tyagi <rahul.1992.tyagi@gmail.com>
Date: Wed, 8 Jul 2026 22:55:25 +0530
Subject: [PATCH 14/16] feat: multi-harness TUI with new-agent flow

Ratatui dashboard that runs harness REPLs in owned PTYs. New-agent form
fixes:

- Seed the task into the REPL only once it has drawn its input box
  (wait for non-empty vt100 screen, 8s cap, + settle) instead of a blind
  900ms sleep that raced startup and dropped the task.
- Esc in the form now confirms before discarding typed input
  (ConfirmDiscard mode); empty forms still close immediately.
---
 tui/Cargo.lock   | 918 +++++++++++++++++++++++++++++++++++++++++++++++
 tui/Cargo.toml   |  25 ++
 tui/README.md    | 147 ++++++++
 tui/src/agent.rs | 185 ++++++++++
 tui/src/app.rs   | 452 +++++++++++++++++++++++
 tui/src/main.rs  | 370 +++++++++++++++++++
 tui/src/pty.rs   | 197 ++++++++++
 tui/src/store.rs | 113 ++++++
 tui/src/ui.rs    | 428 ++++++++++++++++++++++
 9 files changed, 2835 insertions(+)
 create mode 100644 tui/Cargo.lock
 create mode 100644 tui/Cargo.toml
 create mode 100644 tui/README.md
 create mode 100644 tui/src/agent.rs
 create mode 100644 tui/src/app.rs
 create mode 100644 tui/src/main.rs
 create mode 100644 tui/src/pty.rs
 create mode 100644 tui/src/store.rs
 create mode 100644 tui/src/ui.rs

diff --git a/tui/Cargo.lock b/tui/Cargo.lock
new file mode 100644
index 0000000..85b86de
--- /dev/null
+++ b/tui/Cargo.lock
@@ -0,0 +1,918 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "allocator-api2"
+version = "0.2.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "683d7910e743518b0e34f1186f92494becacb047c7b6bf616c96772180fef923"
+
+[[package]]
+name = "anyhow"
+version = "1.0.103"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2a4385e2e34eb35d6b3efe798b9eb88096925d87726c0798709bf56d9ed84af3"
+
+[[package]]
+name = "arrayvec"
+version = "0.7.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3fb67a6e08acf24fdeccbac2cb6ac4305825bd1f117462e0e6f2f193345ad56"
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "bitflags"
+version = "1.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
+
+[[package]]
+name = "bitflags"
+version = "2.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4388bee8683e3d04af747c73422af53102d2bd24d9eadb6cbc100baef4b43f8"
+
+[[package]]
+name = "cassowary"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df8670b8c7b9dae1793364eafadf7239c40d669904660c5960d74cfd80b46a53"
+
+[[package]]
+name = "castaway"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dec551ab6e7578819132c713a93c022a05d60159dc86e7a7050223577484c55a"
+dependencies = [
+ "rustversion",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "compact_str"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7fd622ebbb56a5b2ccb651b32b911cdeb2a9b4b11776b2473bf26a26a286244e"
+dependencies = [
+ "castaway",
+ "cfg-if",
+ "itoa",
+ "rustversion",
+ "ryu",
+ "static_assertions",
+]
+
+[[package]]
+name = "crossterm"
+version = "0.28.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "829d955a0bb380ef178a640b91779e3987da38c9aea133b20614cfed8cdea9c6"
+dependencies = [
+ "bitflags 2.13.0",
+ "crossterm_winapi",
+ "mio",
+ "parking_lot",
+ "rustix",
+ "signal-hook",
+ "signal-hook-mio",
+ "winapi",
+]
+
+[[package]]
+name = "crossterm_winapi"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "acdd7c62a3665c7f6830a51635d9ac9b23ed385797f70a83bb8bafe9c572ab2b"
+dependencies = [
+ "winapi",
+]
+
+[[package]]
+name = "darling"
+version = "0.23.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "25ae13da2f202d56bd7f91c25fba009e7717a1e4a1cc98a76d844b65ae912e9d"
+dependencies = [
+ "darling_core",
+ "darling_macro",
+]
+
+[[package]]
+name = "darling_core"
+version = "0.23.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9865a50f7c335f53564bb694ef660825eb8610e0a53d3e11bf1b0d3df31e03b0"
+dependencies = [
+ "ident_case",
+ "proc-macro2",
+ "quote",
+ "strsim",
+ "syn",
+]
+
+[[package]]
+name = "darling_macro"
+version = "0.23.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac3984ec7bd6cfa798e62b4a642426a5be0e68f9401cfc2a01e3fa9ea2fcdb8d"
+dependencies = [
+ "darling_core",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "downcast-rs"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "75b325c5dbd37f80359721ad39aca5a29fb04c89279657cffdda8736d0c0b9d2"
+
+[[package]]
+name = "either"
+version = "1.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91622ff5e7162018101f2fea40d6ebf4a78bbe5a49736a2020649edf9693679e"
+
+[[package]]
+name = "equivalent"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+
+[[package]]
+name = "errno"
+version = "0.3.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
+dependencies = [
+ "libc",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "filedescriptor"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e40758ed24c9b2eeb76c35fb0aebc66c626084edd827e07e1552279814c6682d"
+dependencies = [
+ "libc",
+ "thiserror",
+ "winapi",
+]
+
+[[package]]
+name = "foldhash"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2"
+
+[[package]]
+name = "hashbrown"
+version = "0.15.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
+dependencies = [
+ "allocator-api2",
+ "equivalent",
+ "foldhash",
+]
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "ident_case"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9e0384b61958566e926dc50660321d12159025e767c18e043daf26b70104c39"
+
+[[package]]
+name = "indoc"
+version = "2.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "79cf5c93f93228cf8efb3ba362535fb11199ac548a09ce117c9b1adc3030d706"
+dependencies = [
+ "rustversion",
+]
+
+[[package]]
+name = "instability"
+version = "0.3.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5eb2d60ef19920a3a9193c3e371f726ec1dafc045dac788d0fb3704272458971"
+dependencies = [
+ "darling",
+ "indoc",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "ioctl-rs"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f7970510895cee30b3e9128319f2cefd4bde883a39f38baa279567ba3a7eb97d"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "itertools"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
+dependencies = [
+ "either",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "lazy_static"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
+
+[[package]]
+name = "libc"
+version = "0.2.186"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
+
+[[package]]
+name = "linux-raw-sys"
+version = "0.4.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d26c52dbd32dccf2d10cac7725f8eae5296885fb5703b261f7d0a0739ec807ab"
+
+[[package]]
+name = "lock_api"
+version = "0.4.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "224399e74b87b5f3557511d98dff8b14089b3dadafcab6bb93eab67d3aace965"
+dependencies = [
+ "scopeguard",
+]
+
+[[package]]
+name = "log"
+version = "0.4.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
+
+[[package]]
+name = "lru"
+version = "0.12.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "234cf4f4a04dc1f57e24b96cc0cd600cf2af460d4161ac5ecdd0af8e1f3b2a38"
+dependencies = [
+ "hashbrown",
+]
+
+[[package]]
+name = "memchr"
+version = "2.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "88904434abc2901f197fe8cc55f0445e7ded921dba5911dad2e2b39b48e663c4"
+
+[[package]]
+name = "memoffset"
+version = "0.6.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5aa361d4faea93603064a027415f07bd8e1d5c88c9fbf68bf56a285428fd79ce"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "mio"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "02bd0af71c67b473010cbbc60715ee815645a4dc942899111f494b4b737d6fda"
+dependencies = [
+ "libc",
+ "log",
+ "wasi",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "nexum-tui"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "crossterm",
+ "portable-pty",
+ "ratatui",
+ "serde",
+ "serde_json",
+ "tui-term",
+ "tui-textarea",
+ "vt100",
+]
+
+[[package]]
+name = "nix"
+version = "0.25.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f346ff70e7dbfd675fe90590b92d59ef2de15a8779ae305ebcbfd3f0caf59be4"
+dependencies = [
+ "autocfg",
+ "bitflags 1.3.2",
+ "cfg-if",
+ "libc",
+ "memoffset",
+ "pin-utils",
+]
+
+[[package]]
+name = "parking_lot"
+version = "0.12.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93857453250e3077bd71ff98b6a65ea6621a19bb0f559a85248955ac12c45a1a"
+dependencies = [
+ "lock_api",
+ "parking_lot_core",
+]
+
+[[package]]
+name = "parking_lot_core"
+version = "0.9.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "redox_syscall",
+ "smallvec",
+ "windows-link",
+]
+
+[[package]]
+name = "paste"
+version = "1.0.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "57c0d7b74b563b49d38dae00a0c37d4d6de9b432382b2892f0574ddcae73fd0a"
+
+[[package]]
+name = "pin-utils"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b870d8c151b6f2fb93e84a13146138f05d02ed11c7e7c54f8826aaaf7c9f184"
+
+[[package]]
+name = "portable-pty"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "806ee80c2a03dbe1a9fb9534f8d19e4c0546b790cde8fd1fea9d6390644cb0be"
+dependencies = [
+ "anyhow",
+ "bitflags 1.3.2",
+ "downcast-rs",
+ "filedescriptor",
+ "lazy_static",
+ "libc",
+ "log",
+ "nix",
+ "serial",
+ "shared_library",
+ "shell-words",
+ "winapi",
+ "winreg",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "ratatui"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eabd94c2f37801c20583fc49dd5cd6b0ba68c716787c2dd6ed18571e1e63117b"
+dependencies = [
+ "bitflags 2.13.0",
+ "cassowary",
+ "compact_str",
+ "crossterm",
+ "indoc",
+ "instability",
+ "itertools",
+ "lru",
+ "paste",
+ "strum",
+ "unicode-segmentation",
+ "unicode-truncate",
+ "unicode-width 0.2.0",
+]
+
+[[package]]
+name = "redox_syscall"
+version = "0.5.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
+dependencies = [
+ "bitflags 2.13.0",
+]
+
+[[package]]
+name = "rustix"
+version = "0.38.44"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fdb5bc1ae2baa591800df16c9ca78619bf65c0488b41b96ccec5d11220d8c154"
+dependencies = [
+ "bitflags 2.13.0",
+ "errno",
+ "libc",
+ "linux-raw-sys",
+ "windows-sys 0.59.0",
+]
+
+[[package]]
+name = "rustversion"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
+
+[[package]]
+name = "ryu"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
+
+[[package]]
+name = "scopeguard"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
+
+[[package]]
+name = "serde"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.150"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "serial"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a1237a96570fc377c13baa1b88c7589ab66edced652e43ffb17088f003db3e86"
+dependencies = [
+ "serial-core",
+ "serial-unix",
+ "serial-windows",
+]
+
+[[package]]
+name = "serial-core"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f46209b345401737ae2125fe5b19a77acce90cd53e1658cda928e4fe9a64581"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "serial-unix"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f03fbca4c9d866e24a459cbca71283f545a37f8e3e002ad8c70593871453cab7"
+dependencies = [
+ "ioctl-rs",
+ "libc",
+ "serial-core",
+ "termios",
+]
+
+[[package]]
+name = "serial-windows"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "15c6d3b776267a75d31bbdfd5d36c0ca051251caafc285827052bc53bcdc8162"
+dependencies = [
+ "libc",
+ "serial-core",
+]
+
+[[package]]
+name = "shared_library"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a9e7e0f2bfae24d8a5b5a66c5b257a83c7412304311512a0c054cd5e619da11"
+dependencies = [
+ "lazy_static",
+ "libc",
+]
+
+[[package]]
+name = "shell-words"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc6fe69c597f9c37bfeeeeeb33da3530379845f10be461a66d16d03eca2ded77"
+
+[[package]]
+name = "signal-hook"
+version = "0.3.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d881a16cf4426aa584979d30bd82cb33429027e42122b169753d6ef1085ed6e2"
+dependencies = [
+ "libc",
+ "signal-hook-registry",
+]
+
+[[package]]
+name = "signal-hook-mio"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b75a19a7a740b25bc7944bdee6172368f988763b744e3d4dfe753f6b4ece40cc"
+dependencies = [
+ "libc",
+ "mio",
+ "signal-hook",
+]
+
+[[package]]
+name = "signal-hook-registry"
+version = "1.4.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b"
+dependencies = [
+ "errno",
+ "libc",
+]
+
+[[package]]
+name = "smallvec"
+version = "1.15.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90"
+
+[[package]]
+name = "static_assertions"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2eb9349b6444b326872e140eb1cf5e7c522154d69e7a0ffb0fb81c06b37543f"
+
+[[package]]
+name = "strsim"
+version = "0.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
+
+[[package]]
+name = "strum"
+version = "0.26.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fec0f0aef304996cf250b31b5a10dee7980c85da9d759361292b8bca5a18f06"
+dependencies = [
+ "strum_macros",
+]
+
+[[package]]
+name = "strum_macros"
+version = "0.26.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4c6bee85a5a24955dc440386795aa378cd9cf82acd5f764469152d2270e581be"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "rustversion",
+ "syn",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.118"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "termios"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d5d9cf598a6d7ce700a4e6a9199da127e6819a61e64b68609683cc9a01b5683a"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "thiserror"
+version = "1.0.69"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "1.0.69"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "tui-term"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72af159125ce32b02ceaced6cffae6394b0e6b6dfd4dc164a6c59a2db9b3c0b0"
+dependencies = [
+ "ratatui",
+ "vt100",
+]
+
+[[package]]
+name = "tui-textarea"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0a5318dd619ed73c52a9417ad19046724effc1287fb75cdcc4eca1d6ac1acbae"
+dependencies = [
+ "crossterm",
+ "ratatui",
+ "unicode-width 0.2.0",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unicode-segmentation"
+version = "1.13.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8"
+
+[[package]]
+name = "unicode-truncate"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b3644627a5af5fa321c95b9b235a72fd24cd29c648c2c379431e6628655627bf"
+dependencies = [
+ "itertools",
+ "unicode-segmentation",
+ "unicode-width 0.1.14",
+]
+
+[[package]]
+name = "unicode-width"
+version = "0.1.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7dd6e30e90baa6f72411720665d41d89b9a3d039dc45b8faea1ddd07f617f6af"
+
+[[package]]
+name = "unicode-width"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fc81956842c57dac11422a97c3b8195a1ff727f06e85c84ed2e8aa277c9a0fd"
+
+[[package]]
+name = "utf8parse"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
+
+[[package]]
+name = "vt100"
+version = "0.15.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "84cd863bf0db7e392ba3bd04994be3473491b31e66340672af5d11943c6274de"
+dependencies = [
+ "itoa",
+ "log",
+ "unicode-width 0.1.14",
+ "vte",
+]
+
+[[package]]
+name = "vte"
+version = "0.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f5022b5fbf9407086c180e9557be968742d839e68346af7792b8592489732197"
+dependencies = [
+ "arrayvec",
+ "utf8parse",
+ "vte_generate_state_changes",
+]
+
+[[package]]
+name = "vte_generate_state_changes"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2e369bee1b05d510a7b4ed645f5faa90619e05437111783ea5848f28d97d3c2e"
+dependencies = [
+ "proc-macro2",
+ "quote",
+]
+
+[[package]]
+name = "wasi"
+version = "0.11.1+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
+
+[[package]]
+name = "winapi"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419"
+dependencies = [
+ "winapi-i686-pc-windows-gnu",
+ "winapi-x86_64-pc-windows-gnu",
+]
+
+[[package]]
+name = "winapi-i686-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"
+
+[[package]]
+name = "winapi-x86_64-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-sys"
+version = "0.59.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b"
+dependencies = [
+ "windows-targets",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
+dependencies = [
+ "windows_aarch64_gnullvm",
+ "windows_aarch64_msvc",
+ "windows_i686_gnu",
+ "windows_i686_gnullvm",
+ "windows_i686_msvc",
+ "windows_x86_64_gnu",
+ "windows_x86_64_gnullvm",
+ "windows_x86_64_msvc",
+]
+
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
+
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
+
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
+
+[[package]]
+name = "winreg"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "80d0f4e272c85def139476380b12f9ac60926689dd2e01d4923222f40580869d"
+dependencies = [
+ "winapi",
+]
+
+[[package]]
+name = "zmij"
+version = "1.0.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
diff --git a/tui/Cargo.toml b/tui/Cargo.toml
new file mode 100644
index 0000000..851f435
--- /dev/null
+++ b/tui/Cargo.toml
@@ -0,0 +1,25 @@
+[package]
+name = "nexum-tui"
+version = "0.1.0"
+edition = "2021"
+description = "Companion TUI for nexum: a repo-scoped global view of agents across harnesses."
+
+[[bin]]
+name = "nexum-tui"
+path = "src/main.rs"
+
+[dependencies]
+ratatui = "0.29"
+crossterm = "0.28"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+anyhow = "1"
+# embedded terminal: run each agent in a PTY and render it inside the TUI
+portable-pty = "0.8"
+vt100 = "0.15"
+tui-term = "0.2"
+# multiline rich task editor for the new-agent form
+tui-textarea = "0.7"
+
+[profile.release]
+opt-level = 2
diff --git a/tui/README.md b/tui/README.md
new file mode 100644
index 0000000..25493ee
--- /dev/null
+++ b/tui/README.md
@@ -0,0 +1,147 @@
+# nexum-tui
+
+A repo-scoped dashboard for running and **chatting with** coding agents across
+harnesses (Claude / OpenCode / Cursor), Rust + [ratatui].
+
+Each agent runs its harness's interactive REPL inside a **PTY that the dashboard
+owns**, rendered in an **embedded terminal pane** (via `portable-pty` + `vt100` +
+[tui-term]). Select an agent and press `enter` to drop into its terminal — you
+chat **inside the TUI**, side-by-side with the agent list; `Ctrl-o` returns to the
+dashboard. No tmux, no switching windows.
+
+**Requires:** `python3` (the engine) and whichever harness CLIs you launch
+(`claude`, `opencode`, `cursor-agent`).
+
+**Quit & resume.** Live agents end when you quit (you get a confirmation first).
+But each launch is persisted to `.nexum-data/tui-agents.json` and its git worktree
+is kept, so on the next run the agent shows as **▷ resumable** — press `enter` to
+relaunch the harness with its resume flag (`claude --continue`, `opencode
+--continue`, `cursor-agent --resume`) in the same worktree, continuing the
+conversation. Resume commands are overridable via `NEXUM_RESUME_CMD_<HARNESS>`.
+
+[tui-term]: https://crates.io/crates/tui-term
+
+It shows two classes of agent for the current repo:
+
+- **managed** — agents nexum launched (rows in the `agents` table), with full
+  control: stop, tail logs, reveal worktree.
+- **observed** — normal plugin sessions writing to `nexum.db` (read-only).
+
+The TUI never touches SQLite directly — it shells the Python engine
+(`python3 <repo>/scripts/store.py … --json`, `dispatch.py …`), so `store.py`
+stays the single source of truth for the schema.
+
+## Build
+
+```
+cd tui
+cargo build --release
+```
+
+The binary lands at `tui/target/release/nexum-tui`.
+
+## Run
+
+From anywhere inside a repo (it resolves the git toplevel and scopes to it):
+
+```
+nexum-tui                         # interactive dashboard
+nexum-tui --new "fix the bug"     # launch an agent from the shell, print its session
+nexum-tui --new "…" --harness opencode --model anthropic/claude-opus-4
+nexum-tui --dump                  # print the agent list once and exit (no TTY)
+nexum-tui --snapshot              # render one real frame to text (visual smoke, no TTY)
+nexum-tui --scripts DIR           # override the scripts dir (default <repo>/scripts)
+```
+
+Environment:
+- `NEXUM_SCRIPTS` — scripts dir (same as `--scripts`).
+- `NEXUM_PYTHON` — python interpreter (default `python3`).
+- `CLAUDE_PLUGIN_DATA` — inherited by the Python engine to pick the data dir / DB.
+
+## Layout
+
+A master-detail **explorer**: a selectable agent list on the left, a live
+preview on the right.
+
+```
+┌ agents (2) ──────────┐┌ preview ─────────────────────────┐
+│▶ ✓ cursor  add bill… ││ add billing dashboard endpoint   │
+│  ● claude  fix auth… ││ status   ● running               │
+│                      ││ harness  claude · sonnet         │
+│                      ││ steps    1/2   cost $0.010       │
+│                      ││ branch   nexum/billing           │
+│                      │└──────────────────────────────────┘
+│                      │┌ log (tail · [enter] full) ───────┐
+│                      ││ {"type":"result","tokens":10,…}  │
+└──────────────────────┘└──────────────────────────────────┘
+```
+
+## Features
+
+- **Explorer view** — managed agents + observed sessions in a scrollable list,
+  **priority-sorted** (live work first, then failed, then done, sessions last),
+  colored status icons (`●` running, `✓` done, `✗` failed, `■` stopped), each row
+  showing step `k/n` and relative time. Selecting one shows a full preview + live
+  log tail on the right.
+- **Diff/verdict viewer** (`d`) — review exactly what an offloaded agent changed:
+  the recorded unified diff (colored) plus the guardrail verdict.
+- **Live step progress** — plan-linked agents show `k/n` done steps from
+  `step_ledger`.
+- **Live PID liveness** — `a` filters to agents whose process is actually alive.
+- **Header totals** — agent/live counts and summed metered cost.
+- **Incremental search** (`/`) over task / harness / id / status.
+- **Launcher** — `n` opens a form where the **task is required**; harness is a
+  picker and the model is prefilled with that harness's default. Launches in a
+  fresh git worktree.
+- **Log tail** auto-follows; `enter` opens a full-screen scrollable log.
+- **Stop** asks to confirm; **`o`** reveals the worktree path.
+- Auto-refreshes every ~1.5s.
+
+## Keys
+
+| key | action |
+|-----|--------|
+| `j`/`k` or `↑`/`↓` | move selection |
+| `n` | new agent form (multiline task, harness/model/worktree pickers, image attach); `Ctrl-S` to launch |
+| `enter` | chat with a live agent, or **resume** a `▷` persisted one |
+| `Ctrl-o` | leave the terminal, back to the dashboard |
+| `q` | quit (confirms if agents are running) |
+| `s` | stop the selected agent (`y` to confirm) |
+| `o` | show the selected agent's worktree path |
+| `x` | remove the selected agent |
+| `/` | search · `h` toggle observed sessions |
+| mouse wheel | scroll the agent list |
+
+### New-agent form
+
+- **task** — a multiline editor (Enter inserts a newline).
+- **harness / model / worktree** — `‹ … ›` pickers, change with `←`/`→`.
+  Worktree = *new isolated git worktree* or *current repo*.
+- **images** — attach image paths (`a` add, `d` remove); appended to the prompt.
+- **`Ctrl-S`** launches (Enter is reserved for the task editor).
+| `/` | incremental search (`esc` clears, `enter` keeps) |
+| `a` | toggle active-only (live PID) |
+| `h` | toggle observed sessions |
+| `r` | refresh now (auto every ~1.5s) |
+| `?` | help overlay |
+| `q` | quit (in log/help view, `q`/`esc` returns to the table) |
+
+## Architecture
+
+```
+nexum-tui ──subprocess JSON──> python3 scripts/store.py agent-list/session-list --json
+         ──spawn detached────> python3 scripts/dispatch.py --harness … --new-worktree …
+```
+
+`dispatch.py` (the keystone shared with `/nx-build --harness`) creates a git
+worktree, runs the chosen harness headless, verifies with `guardrail.py`, and
+records the `agents`/`step_ledger`/`usage` rows the TUI reads back.
+
+## Future work
+
+- Auto route→harness offload (pick the cheapest capable harness per plan step),
+  fed by `route_calibration`.
+- Interactive attach/takeover (tmux) for hands-on driving of a running agent.
+- Launch a whole plan across a harness from the TUI (currently per-agent).
+
+[ratatui]: https://ratatui.rs
diff --git a/tui/src/agent.rs b/tui/src/agent.rs
new file mode 100644
index 0000000..ed0f7c1
--- /dev/null
+++ b/tui/src/agent.rs
@@ -0,0 +1,185 @@
+//! Row models: a live interactive agent (`from_proc`) or an observed plugin
+//! session (`from_session`), normalized into one `Row` for the list.
+
+use crate::pty::AgentProc;
+use crate::store::AgentRecord;
+use serde::Deserialize;
+
+/// An observed plugin session (from `store.py session-list --json`).
+#[derive(Debug, Clone, Deserialize)]
+pub struct Session {
+    pub session_id: String,
+    pub task: Option<String>,
+    pub cost_usd: Option<f64>,
+    pub context_pct: Option<f64>,
+    pub updated_ts: Option<f64>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Kind {
+    Managed,
+    Observed,
+}
+
+/// One normalized row for the unified list. Some fields are carried for future
+/// use / observed sessions and aren't read on every path.
+#[derive(Debug, Clone)]
+#[allow(dead_code)]
+pub struct Row {
+    pub kind: Kind,
+    pub id: String,
+    pub harness: String,
+    pub model: String,
+    pub task: String,
+    pub branch: String,
+    pub status: String,
+    pub cost_usd: f64,
+    pub ctx_pct: Option<f64>,
+    pub updated_ts: f64,
+    pub pid: Option<i64>,
+    pub worktree: Option<String>,
+    pub log_path: Option<String>,
+    pub plan_hash: Option<String>,
+    pub session_id: Option<String>,
+    pub step_index: Option<i64>,
+    pub steps: Option<(u32, u32)>,
+    /// True for an in-TUI interactive agent (has a live PTY terminal).
+    pub interactive: bool,
+    /// Index into `App.agents` when this row is a live PTY agent.
+    pub proc_idx: Option<usize>,
+    /// A persisted-but-not-running agent that can be resumed in its worktree.
+    pub resumable: bool,
+}
+
+fn s(o: &Option<String>, dflt: &str) -> String {
+    match o {
+        Some(v) if !v.is_empty() => v.clone(),
+        _ => dflt.to_string(),
+    }
+}
+
+impl Row {
+    /// Build a row from a live in-TUI interactive agent (PTY-backed).
+    pub fn from_proc(idx: usize, p: &mut AgentProc) -> Row {
+        let alive = p.is_alive();
+        Row {
+            kind: Kind::Managed,
+            id: p.id.clone(),
+            harness: p.harness.clone(),
+            model: p.model.clone(),
+            task: p.task.clone(),
+            branch: String::new(),
+            status: if alive { "running".into() } else { "exited".into() },
+            cost_usd: 0.0,
+            ctx_pct: None,
+            updated_ts: 0.0,
+            pid: None,
+            worktree: Some(p.worktree.clone()),
+            log_path: None,
+            plan_hash: None,
+            session_id: None,
+            step_index: None,
+            steps: None,
+            interactive: true,
+            proc_idx: Some(idx),
+            resumable: false,
+        }
+    }
+
+    /// A persisted agent (not currently running) that can be resumed.
+    pub fn from_record(rec: &AgentRecord) -> Row {
+        Row {
+            kind: Kind::Managed,
+            id: rec.id.clone(),
+            harness: rec.harness.clone(),
+            model: rec.model.clone(),
+            task: rec.task.clone(),
+            branch: String::new(),
+            status: "resumable".into(),
+            cost_usd: 0.0,
+            ctx_pct: None,
+            updated_ts: 0.0,
+            pid: None,
+            worktree: Some(rec.worktree.clone()),
+            log_path: None,
+            plan_hash: None,
+            session_id: None,
+            step_index: None,
+            steps: None,
+            interactive: false,
+            proc_idx: None,
+            resumable: true,
+        }
+    }
+
+    pub fn from_session(sess: &Session) -> Row {
+        Row {
+            kind: Kind::Observed,
+            id: sess.session_id.clone(),
+            harness: "session".to_string(),
+            model: "-".to_string(),
+            task: s(&sess.task, ""),
+            branch: "-".to_string(),
+            status: "observed".to_string(),
+            cost_usd: sess.cost_usd.unwrap_or(0.0),
+            ctx_pct: sess.context_pct,
+            updated_ts: sess.updated_ts.unwrap_or(0.0),
+            pid: None,
+            worktree: None,
+            log_path: None,
+            plan_hash: None,
+            session_id: None,
+            step_index: None,
+            steps: None,
+            interactive: false,
+            proc_idx: None,
+            resumable: false,
+        }
+    }
+}
+
+/// Human "3m ago" relative time from epoch seconds.
+pub fn rel_time(ts: f64, now: f64) -> String {
+    if ts <= 0.0 {
+        return "-".to_string();
+    }
+    let d = (now - ts).max(0.0) as u64;
+    if d < 60 {
+        format!("{}s ago", d)
+    } else if d < 3600 {
+        format!("{}m ago", d / 60)
+    } else if d < 86400 {
+        format!("{}h ago", d / 3600)
+    } else {
+        format!("{}d ago", d / 86400)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn rel_time_buckets() {
+        assert_eq!(rel_time(0.0, 100.0), "-");
+        assert_eq!(rel_time(90.0, 100.0), "10s ago");
+        assert_eq!(rel_time(40.0, 100.0), "1m ago");
+        assert_eq!(rel_time(100.0, 100.0 + 300.0), "5m ago");
+        assert_eq!(rel_time(100.0, 100.0 + 7200.0), "2h ago");
+    }
+
+    #[test]
+    fn session_row_is_observed() {
+        let sess = Session {
+            session_id: "s1".into(),
+            task: Some("observed work".into()),
+            cost_usd: Some(1.0),
+            context_pct: Some(42.0),
+            updated_ts: Some(5.0),
+        };
+        let r = Row::from_session(&sess);
+        assert_eq!(r.kind, Kind::Observed);
+        assert!(!r.interactive);
+        assert_eq!(r.ctx_pct, Some(42.0));
+    }
+}
diff --git a/tui/src/app.rs b/tui/src/app.rs
new file mode 100644
index 0000000..c9e65e3
--- /dev/null
+++ b/tui/src/app.rs
@@ -0,0 +1,452 @@
+//! Application state and the actions the key handlers call.
+//!
+//! Interactive agents are PTY-backed processes owned here (`agents`), rendered
+//! *inside* the TUI. Observed plugin sessions still come from the DB (read-only).
+
+use crate::agent::Row;
+use crate::pty::AgentProc;
+use crate::store::{AgentRecord, Store};
+use anyhow::Result;
+use std::collections::HashSet;
+use tui_textarea::TextArea;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Mode {
+    Normal,
+    NewAgent,
+    Help,
+    ConfirmStop,
+    ConfirmQuit,
+    /// Esc pressed in the new-agent form with unsaved input — confirm discard.
+    ConfirmDiscard,
+    Filter,
+    /// Focused into the selected agent's embedded terminal — keys go to the PTY.
+    Terminal,
+}
+
+pub const HARNESSES: [&str; 3] = ["claude", "opencode", "cursor"];
+
+/// Model presets per harness — pick with ←/→ instead of typing.
+pub fn model_presets(harness_idx: usize) -> &'static [&'static str] {
+    match harness_idx {
+        0 => &["sonnet", "opus", "haiku"],
+        1 => &["anthropic/claude-sonnet-4-6", "anthropic/claude-opus-4", "openai/gpt-5"],
+        _ => &["auto", "sonnet", "gpt-5"],
+    }
+}
+
+// New-agent form fields (task is a multiline editor and comes first).
+pub const FIELD_TASK: usize = 0;
+pub const FIELD_HARNESS: usize = 1;
+pub const FIELD_MODEL: usize = 2;
+pub const FIELD_WORKTREE: usize = 3;
+pub const FIELD_IMAGES: usize = 4;
+pub const FIELD_COUNT: usize = 5;
+
+pub struct NewAgentForm {
+    pub task: TextArea<'static>,
+    pub harness_idx: usize,
+    pub model_idx: usize,
+    /// true → isolate in a fresh git worktree; false → run in the repo itself.
+    pub worktree_new: bool,
+    /// image file paths attached to the task.
+    pub images: Vec<String>,
+    /// when Some, we're capturing an image path to add.
+    pub image_input: Option<String>,
+    pub field: usize,
+    pub error: Option<String>,
+}
+
+impl Default for NewAgentForm {
+    fn default() -> Self {
+        let mut task = TextArea::default();
+        task.set_placeholder_text("Describe the task… (Enter = newline)");
+        NewAgentForm {
+            task,
+            harness_idx: 0,
+            model_idx: 0,
+            worktree_new: true,
+            images: Vec::new(),
+            image_input: None,
+            field: FIELD_TASK,
+            error: None,
+        }
+    }
+}
+
+impl NewAgentForm {
+    pub fn harness(&self) -> &'static str {
+        HARNESSES[self.harness_idx.min(2)]
+    }
+    pub fn model(&self) -> &'static str {
+        let p = model_presets(self.harness_idx);
+        p[self.model_idx.min(p.len() - 1)]
+    }
+    pub fn cycle_model(&mut self, d: i64) {
+        let n = model_presets(self.harness_idx).len() as i64;
+        self.model_idx = (((self.model_idx as i64 + d) % n + n) % n) as usize;
+    }
+    pub fn cycle_harness(&mut self, d: i64) {
+        let n = HARNESSES.len() as i64;
+        self.harness_idx = (((self.harness_idx as i64 + d) % n + n) % n) as usize;
+        self.model_idx = 0;
+    }
+    pub fn task_text(&self) -> String {
+        self.task.lines().join("\n")
+    }
+    /// Full prompt sent to the agent: task plus any attached image paths.
+    pub fn full_prompt(&self) -> String {
+        let mut s = self.task_text();
+        for img in &self.images {
+            s.push_str(&format!("\n[image] {}", img));
+        }
+        s
+    }
+}
+
+pub struct App {
+    pub store: Store,
+    /// Live PTY-backed interactive agents (owned; die with the TUI).
+    pub agents: Vec<AgentProc>,
+    /// Persisted agents (survive restart; resumable via the harness).
+    pub registry: Vec<AgentRecord>,
+    pub rows: Vec<Row>,
+    pub selected: usize,
+    pub mode: Mode,
+    pub status_msg: String,
+    pub new_form: NewAgentForm,
+    pub should_quit: bool,
+    pub show_observed: bool,
+    pub all_rows: Vec<Row>,
+    pub filter_text: String,
+    /// Size (cols, rows) the terminal pane was last rendered at — used to resize.
+    pub term_size: (u16, u16),
+}
+
+impl App {
+    pub fn new(store: Store) -> App {
+        let registry = store.load_registry();
+        App {
+            store,
+            agents: Vec::new(),
+            registry,
+            rows: Vec::new(),
+            selected: 0,
+            mode: Mode::Normal,
+            status_msg: String::new(),
+            new_form: NewAgentForm::default(),
+            should_quit: false,
+            show_observed: true,
+            all_rows: Vec::new(),
+            filter_text: String::new(),
+            term_size: (80, 24),
+        }
+    }
+
+    pub fn apply_filter(&mut self) {
+        let q = self.filter_text.to_lowercase();
+        self.rows = if q.is_empty() {
+            self.all_rows.clone()
+        } else {
+            self.all_rows
+                .iter()
+                .filter(|r| {
+                    r.task.to_lowercase().contains(&q)
+                        || r.harness.to_lowercase().contains(&q)
+                        || r.id.to_lowercase().contains(&q)
+                        || r.status.to_lowercase().contains(&q)
+                })
+                .cloned()
+                .collect()
+        };
+        if self.selected >= self.rows.len() && !self.rows.is_empty() {
+            self.selected = self.rows.len() - 1;
+        }
+    }
+
+    pub fn refresh(&mut self) -> Result<()> {
+        // live interactive agents first (from the owned PTY procs)
+        let mut rows: Vec<Row> = self
+            .agents
+            .iter_mut()
+            .enumerate()
+            .map(|(i, p)| Row::from_proc(i, p))
+            .collect();
+        let live_ids: HashSet<String> = rows.iter().map(|r| r.id.clone()).collect();
+        // persisted agents that aren't currently live → resumable
+        for rec in &self.registry {
+            if !live_ids.contains(&rec.id) {
+                rows.push(Row::from_record(rec));
+            }
+        }
+        // observed plugin sessions (read-only, from the DB)
+        if self.show_observed {
+            let sessions = self.store.sessions().unwrap_or_default();
+            rows.extend(sessions.iter().map(Row::from_session));
+        }
+        rows = merge_keep(rows);
+        self.all_rows = rows;
+        self.apply_filter();
+        Ok(())
+    }
+
+    pub fn selected_row(&self) -> Option<&Row> {
+        self.rows.get(self.selected)
+    }
+
+    /// The AgentProc behind the selected row, if it's a live interactive agent.
+    pub fn selected_proc(&mut self) -> Option<&mut AgentProc> {
+        let idx = self.selected_row().and_then(|r| r.proc_idx)?;
+        self.agents.get_mut(idx)
+    }
+
+    pub fn move_sel(&mut self, delta: i64) {
+        if self.rows.is_empty() {
+            return;
+        }
+        let n = self.rows.len() as i64;
+        let i = (self.selected as i64 + delta).clamp(0, n - 1);
+        self.selected = i as usize;
+    }
+
+    pub fn open_new_agent(&mut self) {
+        self.new_form = NewAgentForm::default();
+        self.mode = Mode::NewAgent;
+    }
+
+    /// Launch an interactive PTY agent from the form. Task is required.
+    pub fn spawn_from_form(&mut self) {
+        if self.new_form.task_text().trim().is_empty() {
+            self.new_form.error = Some("task is required".into());
+            self.new_form.field = FIELD_TASK;
+            return;
+        }
+        let harness = self.new_form.harness().to_string();
+        let model = self.new_form.model().to_string();
+        let prompt = self.new_form.full_prompt();
+        let (cols, rows) = self.term_size;
+
+        // choose worktree: new isolated one, or the repo itself
+        let (id, worktree) = if self.new_form.worktree_new {
+            let slug = slugify(&self.new_form.task_text());
+            match self.store.create_worktree(&slug) {
+                Ok(wt) => (format!("agent_{}", slug), wt),
+                Err(e) => {
+                    self.new_form.error = Some(format!("worktree failed: {}", e));
+                    return;
+                }
+            }
+        } else {
+            (
+                format!("agent_{}", slugify(&self.new_form.task_text())),
+                self.store.repo_root.to_string_lossy().to_string(),
+            )
+        };
+
+        let argv = interactive_argv(&harness, &model);
+        let task_text = self.new_form.task_text();
+        match AgentProc::spawn(
+            id.clone(), harness.clone(), model.clone(), prompt, worktree.clone(), &argv, rows, cols,
+        ) {
+            Ok(proc) => {
+                self.agents.push(proc);
+                // persist so it can be resumed after the TUI closes
+                self.registry.retain(|r| r.id != id);
+                self.registry.push(AgentRecord {
+                    id: id.clone(), harness, model, worktree, task: task_text,
+                });
+                self.store.save_registry(&self.registry);
+                let _ = self.refresh();
+                if let Some(i) = self.rows.iter().position(|r| r.id == id) {
+                    self.selected = i;
+                }
+                self.mode = Mode::Terminal; // drop straight into the chat
+                self.status_msg = format!("launched {} — Ctrl-o to leave the terminal", id);
+            }
+            Err(e) => self.new_form.error = Some(format!("{}", e)),
+        }
+    }
+
+    /// Enter/activate the selected row: focus a live terminal, or resume a
+    /// persisted agent by relaunching its harness (which resumes its session)
+    /// in the same worktree.
+    pub fn open_selected(&mut self) {
+        let Some(r) = self.selected_row().cloned() else { return };
+        if r.interactive {
+            self.mode = Mode::Terminal;
+        } else if r.resumable {
+            self.resume(&r.id);
+        } else {
+            self.status_msg = "not an interactive agent".into();
+        }
+    }
+
+    fn resume(&mut self, id: &str) {
+        let Some(rec) = self.registry.iter().find(|r| r.id == id).cloned() else { return };
+        let (cols, rows) = self.term_size;
+        let argv = resume_argv(&rec.harness, &rec.model);
+        // no task seed on resume — the harness restores the prior conversation
+        match AgentProc::spawn(
+            rec.id.clone(), rec.harness.clone(), rec.model.clone(), String::new(),
+            rec.worktree.clone(), &argv, rows, cols,
+        ) {
+            Ok(proc) => {
+                self.agents.push(proc);
+                let _ = self.refresh();
+                if let Some(i) = self.rows.iter().position(|r| r.id == rec.id) {
+                    self.selected = i;
+                }
+                self.mode = Mode::Terminal;
+                self.status_msg = format!("resumed {} — Ctrl-o to leave", rec.id);
+            }
+            Err(e) => self.status_msg = format!("resume failed: {}", e),
+        }
+    }
+
+    /// Forward raw bytes (a keypress) to the focused agent's PTY.
+    pub fn send_to_terminal(&mut self, bytes: &[u8]) {
+        if let Some(p) = self.selected_proc() {
+            p.send(bytes);
+        }
+    }
+
+    pub fn stop_selected(&mut self) {
+        if let Some(idx) = self.selected_row().and_then(|r| r.proc_idx) {
+            if let Some(p) = self.agents.get_mut(idx) {
+                p.kill();
+            }
+            self.status_msg = "stopped".into();
+            let _ = self.refresh();
+        } else {
+            self.status_msg = "only interactive agents can be stopped here".into();
+        }
+    }
+
+    /// Remove the selected agent: kill any live process AND forget its persisted
+    /// record (so it no longer shows as resumable). The worktree is left on disk.
+    pub fn remove_selected(&mut self) {
+        let Some(r) = self.selected_row().cloned() else { return };
+        if let Some(idx) = r.proc_idx {
+            if let Some(p) = self.agents.get_mut(idx) {
+                p.kill();
+            }
+            self.agents.remove(idx);
+        }
+        let before = self.registry.len();
+        self.registry.retain(|rec| rec.id != r.id);
+        if self.registry.len() != before {
+            self.store.save_registry(&self.registry);
+        }
+        let _ = self.refresh();
+        self.status_msg = "removed".into();
+    }
+
+    pub fn show_worktree(&mut self) {
+        if let Some(r) = self.selected_row() {
+            self.status_msg = r.worktree.clone().unwrap_or_else(|| "no worktree".into());
+        }
+    }
+
+    pub fn running_count(&self) -> usize {
+        self.rows.iter().filter(|r| r.status == "running").count()
+    }
+}
+
+/// Sort rows (running first, then exited, then observed), newest kept order.
+fn merge_keep(mut rows: Vec<Row>) -> Vec<Row> {
+    rows.sort_by_key(|r| match r.status.as_str() {
+        "running" => 0,
+        "resumable" => 1,
+        "exited" => 2,
+        _ => 3,
+    });
+    rows
+}
+
+/// argv for a harness's INTERACTIVE REPL. Overridable via
+/// `NEXUM_INTERACTIVE_CMD_<HARNESS>` (whitespace-split) so tests inject a stub.
+pub fn interactive_argv(harness: &str, model: &str) -> Vec<String> {
+    if let Ok(over) = std::env::var(format!("NEXUM_INTERACTIVE_CMD_{}", harness.to_uppercase())) {
+        if !over.trim().is_empty() {
+            return over.split_whitespace().map(|s| s.to_string()).collect();
+        }
+    }
+    match harness {
+        "claude" => vec!["claude".into(), "--model".into(), model.into()],
+        "opencode" => vec!["opencode".into()],
+        "cursor" => vec!["cursor-agent".into(), "--model".into(), model.into()],
+        _ => vec!["claude".into()],
+    }
+}
+
+/// argv to RESUME a harness in an existing worktree (harness restores the prior
+/// session). Overridable via `NEXUM_RESUME_CMD_<HARNESS>`.
+pub fn resume_argv(harness: &str, model: &str) -> Vec<String> {
+    if let Ok(over) = std::env::var(format!("NEXUM_RESUME_CMD_{}", harness.to_uppercase())) {
+        if !over.trim().is_empty() {
+            return over.split_whitespace().map(|s| s.to_string()).collect();
+        }
+    }
+    match harness {
+        "claude" => vec!["claude".into(), "--continue".into(), "--model".into(), model.into()],
+        "opencode" => vec!["opencode".into(), "--continue".into()],
+        "cursor" => vec!["cursor-agent".into(), "--resume".into()],
+        _ => interactive_argv(harness, model),
+    }
+}
+
+fn slugify(task: &str) -> String {
+    let base: String = task
+        .chars()
+        .map(|c| if c.is_ascii_alphanumeric() { c.to_ascii_lowercase() } else { '-' })
+        .collect();
+    let base: String = base.split('-').filter(|s| !s.is_empty()).collect::<Vec<_>>().join("-");
+    let base: String = base.chars().take(20).collect();
+    let ts = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.as_millis() % 1_000_000)
+        .unwrap_or(0);
+    if base.is_empty() { format!("agent-{}", ts) } else { format!("{}-{}", base, ts) }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::path::PathBuf;
+
+    fn app() -> App {
+        App::new(Store::new(PathBuf::from("/tmp/r"), PathBuf::from("/tmp/r/scripts")))
+    }
+
+    #[test]
+    fn model_picker_cycles_per_harness() {
+        let mut a = app();
+        a.open_new_agent();
+        assert_eq!(a.new_form.model(), "sonnet");
+        a.new_form.cycle_model(1);
+        assert_eq!(a.new_form.model(), "opus");
+        a.new_form.cycle_harness(2); // claude -> cursor
+        assert_eq!(a.new_form.harness(), "cursor");
+        assert_eq!(a.new_form.model(), "auto");
+    }
+
+    #[test]
+    fn empty_task_blocks_launch() {
+        let mut a = app();
+        a.open_new_agent();
+        a.spawn_from_form();
+        assert_eq!(a.mode, Mode::NewAgent);
+        assert!(a.new_form.error.is_some());
+        assert_eq!(a.new_form.field, FIELD_TASK);
+    }
+
+    #[test]
+    fn full_prompt_appends_images() {
+        let mut f = NewAgentForm::default();
+        f.task.insert_str("fix the header");
+        f.images.push("/tmp/shot.png".into());
+        let p = f.full_prompt();
+        assert!(p.contains("fix the header"));
+        assert!(p.contains("[image] /tmp/shot.png"));
+    }
+}
diff --git a/tui/src/main.rs b/tui/src/main.rs
new file mode 100644
index 0000000..d29ac96
--- /dev/null
+++ b/tui/src/main.rs
@@ -0,0 +1,370 @@
+//! nexum-tui — a repo-scoped dashboard for running and chatting with coding
+//! agents. Each agent runs its harness REPL in a PTY rendered *inside* the TUI.
+//!
+//!   nexum-tui                 # interactive dashboard
+//!   nexum-tui --dump          # print the agent list once and exit (no TTY)
+//!   nexum-tui --snapshot      # render one real frame to text (no TTY)
+//!   nexum-tui --scripts DIR   # override the scripts dir (default <repo>/scripts)
+
+mod agent;
+mod app;
+mod pty;
+mod store;
+mod ui;
+
+use anyhow::Result;
+use app::{App, Mode};
+use crossterm::{
+    event::{
+        self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEvent, KeyEventKind,
+        KeyModifiers, MouseEventKind,
+    },
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use ratatui::{backend::CrosstermBackend, Terminal};
+use std::io;
+use std::path::PathBuf;
+use std::time::{Duration, Instant};
+
+type Term = Terminal<CrosstermBackend<io::Stdout>>;
+
+fn main() -> Result<()> {
+    let args: Vec<String> = std::env::args().collect();
+    let scripts_override = arg_value(&args, "--scripts");
+
+    let cwd = std::env::current_dir()?;
+    let repo_root = store::git_toplevel(&cwd);
+    let scripts_dir = scripts_override
+        .map(PathBuf::from)
+        .or_else(|| std::env::var("NEXUM_SCRIPTS").ok().map(PathBuf::from))
+        .unwrap_or_else(|| repo_root.join("scripts"));
+
+    let st = store::Store::new(repo_root, scripts_dir);
+    let mut app = App::new(st);
+    app.refresh()?;
+
+    if args.iter().any(|a| a == "--dump") {
+        dump_table(&app);
+        return Ok(());
+    }
+    if args.iter().any(|a| a == "--snapshot") {
+        match std::env::var("NEXUM_SNAPSHOT_MODE").as_deref() {
+            Ok("new") => {
+                app.open_new_agent();
+                app.new_form.task.insert_str("add auth middleware");
+            }
+            Ok("help") => app.mode = app::Mode::Help,
+            Ok("term") | Ok("quit") => {
+                // spawn a stub interactive agent and drop into its terminal
+                app.term_size = (80, 24);
+                app.open_new_agent();
+                app.new_form.task.insert_str("say hello");
+                app.new_form.worktree_new = false; // run in cwd, skip worktree.py
+                app.spawn_from_form();
+                std::thread::sleep(Duration::from_millis(600));
+                let _ = app.refresh();
+                if std::env::var("NEXUM_SNAPSHOT_MODE").as_deref() == Ok("quit") {
+                    app.mode = app::Mode::ConfirmQuit;
+                }
+            }
+            _ => {}
+        }
+        snapshot(&app);
+        return Ok(());
+    }
+
+    run_tui(&mut app)
+}
+
+fn dump_table(app: &App) {
+    println!("nexum agents for {} — {} rows", app.store.repo_root.display(), app.rows.len());
+    for r in &app.rows {
+        let kind = if r.interactive { "agent" } else { "session" };
+        println!("{:<7} {:<9} {:<8} {}", kind, r.harness, r.status, r.task);
+    }
+}
+
+fn snapshot(app: &App) {
+    use ratatui::{backend::TestBackend, Terminal};
+    let mut term = Terminal::new(TestBackend::new(100, 30)).unwrap();
+    term.draw(|f| ui::draw(f, app)).unwrap();
+    let buf = term.backend().buffer().clone();
+    for y in 0..buf.area.height {
+        let mut line = String::new();
+        for x in 0..buf.area.width {
+            line.push_str(buf[(x, y)].symbol());
+        }
+        println!("{}", line.trim_end());
+    }
+}
+
+fn run_tui(app: &mut App) -> Result<()> {
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
+    let mut terminal = Terminal::new(backend)?;
+
+    let res = event_loop(app, &mut terminal);
+
+    disable_raw_mode()?;
+    execute!(terminal.backend_mut(), LeaveAlternateScreen, DisableMouseCapture)?;
+    terminal.show_cursor()?;
+    res
+}
+
+fn event_loop(app: &mut App, terminal: &mut Term) -> Result<()> {
+    // fast tick so the embedded terminal feels live; refresh list less often.
+    let refresh_every = Duration::from_millis(800);
+    let mut last_refresh = Instant::now();
+
+    loop {
+        terminal.draw(|f| ui::draw(f, app))?;
+
+        if event::poll(Duration::from_millis(60))? {
+            match event::read()? {
+                Event::Key(key) if key.kind == KeyEventKind::Press => {
+                    if app.mode == Mode::Terminal {
+                        handle_terminal_key(app, key);
+                    } else {
+                        if !app.status_msg.is_empty() {
+                            app.status_msg.clear();
+                        }
+                        handle_key(app, key);
+                    }
+                }
+                Event::Mouse(m) if app.mode == Mode::Normal => match m.kind {
+                    MouseEventKind::ScrollDown => app.move_sel(1),
+                    MouseEventKind::ScrollUp => app.move_sel(-1),
+                    _ => {}
+                },
+                _ => {}
+            }
+        }
+
+        if last_refresh.elapsed() >= refresh_every {
+            let _ = app.refresh();
+            last_refresh = Instant::now();
+        }
+
+        if app.should_quit {
+            return Ok(());
+        }
+    }
+}
+
+/// In Terminal mode every key is forwarded to the agent's PTY, except Ctrl-o
+/// which leaves the embedded terminal and returns to the dashboard.
+fn handle_terminal_key(app: &mut App, key: KeyEvent) {
+    if key.code == KeyCode::Char('o') && key.modifiers.contains(KeyModifiers::CONTROL) {
+        app.mode = Mode::Normal;
+        return;
+    }
+    let bytes = key_to_bytes(key);
+    if !bytes.is_empty() {
+        app.send_to_terminal(&bytes);
+    }
+}
+
+fn handle_key(app: &mut App, key: KeyEvent) {
+    let code = key.code;
+    match app.mode {
+        Mode::Normal => match code {
+            KeyCode::Char('q') => {
+                if app.agents.iter_mut().any(|a| a.is_alive()) {
+                    app.mode = Mode::ConfirmQuit;
+                } else {
+                    app.should_quit = true;
+                }
+            }
+            KeyCode::Char('j') | KeyCode::Down => app.move_sel(1),
+            KeyCode::Char('k') | KeyCode::Up => app.move_sel(-1),
+            KeyCode::Char('r') => { let _ = app.refresh(); }
+            KeyCode::Char('n') => app.open_new_agent(),
+            KeyCode::Char('s') => {
+                if app.selected_row().map(|r| r.interactive).unwrap_or(false) {
+                    app.mode = Mode::ConfirmStop;
+                } else {
+                    app.status_msg = "only interactive agents can be stopped".into();
+                }
+            }
+            KeyCode::Char('x') => app.remove_selected(),
+            KeyCode::Char('o') => app.show_worktree(),
+            KeyCode::Char('h') => { app.show_observed = !app.show_observed; let _ = app.refresh(); }
+            KeyCode::Char('/') => app.mode = Mode::Filter,
+            KeyCode::Char('?') => app.mode = Mode::Help,
+            KeyCode::Enter => app.open_selected(),
+            _ => {}
+        },
+        Mode::Help => app.mode = Mode::Normal,
+        Mode::ConfirmQuit => match code {
+            KeyCode::Char('y') | KeyCode::Enter => app.should_quit = true,
+            KeyCode::Char('n') | KeyCode::Esc => app.mode = Mode::Normal,
+            _ => {}
+        },
+        Mode::ConfirmStop => match code {
+            KeyCode::Char('y') => { app.stop_selected(); app.mode = Mode::Normal; }
+            KeyCode::Char('n') | KeyCode::Esc => app.mode = Mode::Normal,
+            _ => {}
+        },
+        Mode::ConfirmDiscard => match code {
+            KeyCode::Char('y') => { app.new_form = app::NewAgentForm::default(); app.mode = Mode::Normal; }
+            KeyCode::Char('n') | KeyCode::Esc => app.mode = Mode::NewAgent,
+            _ => {}
+        },
+        Mode::Filter => match code {
+            KeyCode::Esc => { app.filter_text.clear(); app.apply_filter(); app.mode = Mode::Normal; }
+            KeyCode::Enter => app.mode = Mode::Normal,
+            KeyCode::Backspace => { app.filter_text.pop(); app.apply_filter(); }
+            KeyCode::Char(c) => { app.filter_text.push(c); app.apply_filter(); }
+            _ => {}
+        },
+        Mode::NewAgent => handle_new_agent_key(app, key),
+        Mode::Terminal => {}
+    }
+}
+
+fn handle_new_agent_key(app: &mut App, key: KeyEvent) {
+    use app::{FIELD_HARNESS, FIELD_IMAGES, FIELD_MODEL, FIELD_TASK, FIELD_WORKTREE, FIELD_COUNT};
+    let ctrl = key.modifiers.contains(KeyModifiers::CONTROL);
+
+    // Ctrl-S launches from any field (task uses Enter for newlines).
+    if ctrl && key.code == KeyCode::Char('s') {
+        app.spawn_from_form();
+        return;
+    }
+    match key.code {
+        KeyCode::Esc => {
+            // cancel an in-progress image path first; otherwise confirm before
+            // throwing away a form the user has typed into.
+            if app.new_form.image_input.is_some() {
+                app.new_form.image_input = None;
+            } else if app.new_form.task_text().trim().is_empty() && app.new_form.images.is_empty() {
+                app.mode = Mode::Normal;
+            } else {
+                app.mode = Mode::ConfirmDiscard;
+            }
+            return;
+        }
+        KeyCode::Tab => { app.new_form.field = (app.new_form.field + 1) % FIELD_COUNT; return; }
+        KeyCode::BackTab => { app.new_form.field = (app.new_form.field + FIELD_COUNT - 1) % FIELD_COUNT; return; }
+        _ => {}
+    }
+
+    let f = &mut app.new_form;
+    // image-path capture sub-mode
+    if let Some(buf) = f.image_input.as_mut() {
+        match key.code {
+            KeyCode::Enter => {
+                let path = buf.trim().to_string();
+                if !path.is_empty() { f.images.push(path); }
+                f.image_input = None;
+            }
+            KeyCode::Esc => f.image_input = None,
+            KeyCode::Backspace => { buf.pop(); }
+            KeyCode::Char(c) => buf.push(c),
+            _ => {}
+        }
+        return;
+    }
+
+    match f.field {
+        FIELD_TASK => { f.task.input(key); }
+        FIELD_HARNESS => match key.code {
+            KeyCode::Left | KeyCode::Char('h') => f.cycle_harness(-1),
+            KeyCode::Right | KeyCode::Char('l') => f.cycle_harness(1),
+            _ => {}
+        },
+        FIELD_MODEL => match key.code {
+            KeyCode::Left | KeyCode::Char('h') => f.cycle_model(-1),
+            KeyCode::Right | KeyCode::Char('l') => f.cycle_model(1),
+            _ => {}
+        },
+        FIELD_WORKTREE => match key.code {
+            KeyCode::Left | KeyCode::Right | KeyCode::Char(' ') | KeyCode::Char('h') | KeyCode::Char('l') => {
+                f.worktree_new = !f.worktree_new;
+            }
+            _ => {}
+        },
+        FIELD_IMAGES => match key.code {
+            KeyCode::Char('a') | KeyCode::Enter => f.image_input = Some(String::new()),
+            KeyCode::Char('d') | KeyCode::Backspace => { f.images.pop(); }
+            _ => {}
+        },
+        _ => {}
+    }
+}
+
+/// Convert a keypress into the bytes a terminal would send to the PTY.
+fn key_to_bytes(key: KeyEvent) -> Vec<u8> {
+    let ctrl = key.modifiers.contains(KeyModifiers::CONTROL);
+    match key.code {
+        KeyCode::Char(c) => {
+            if ctrl {
+                let b = (c.to_ascii_uppercase() as u8).wrapping_sub(0x40) & 0x7f;
+                vec![b]
+            } else {
+                c.to_string().into_bytes()
+            }
+        }
+        KeyCode::Enter => vec![b'\r'],
+        KeyCode::Backspace => vec![0x7f],
+        KeyCode::Tab => vec![b'\t'],
+        KeyCode::Esc => vec![0x1b],
+        KeyCode::Left => b"\x1b[D".to_vec(),
+        KeyCode::Right => b"\x1b[C".to_vec(),
+        KeyCode::Up => b"\x1b[A".to_vec(),
+        KeyCode::Down => b"\x1b[B".to_vec(),
+        KeyCode::Home => b"\x1b[H".to_vec(),
+        KeyCode::End => b"\x1b[F".to_vec(),
+        KeyCode::PageUp => b"\x1b[5~".to_vec(),
+        KeyCode::PageDown => b"\x1b[6~".to_vec(),
+        KeyCode::Delete => b"\x1b[3~".to_vec(),
+        _ => vec![],
+    }
+}
+
+fn arg_value(args: &[String], flag: &str) -> Option<String> {
+    args.iter().position(|a| a == flag).and_then(|i| args.get(i + 1).cloned())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use app::App;
+    use std::path::PathBuf;
+
+    fn app() -> App {
+        App::new(store::Store::new(PathBuf::from("/tmp/r"), PathBuf::from("/tmp/r/scripts")))
+    }
+    fn esc() -> KeyEvent {
+        KeyEvent::new(KeyCode::Esc, KeyModifiers::empty())
+    }
+
+    #[test]
+    fn esc_on_empty_form_closes_without_confirm() {
+        let mut a = app();
+        a.open_new_agent();
+        handle_new_agent_key(&mut a, esc());
+        assert_eq!(a.mode, Mode::Normal);
+    }
+
+    #[test]
+    fn esc_with_typed_task_asks_to_confirm() {
+        let mut a = app();
+        a.open_new_agent();
+        a.new_form.task.insert_str("do the thing");
+        handle_new_agent_key(&mut a, esc());
+        assert_eq!(a.mode, Mode::ConfirmDiscard);
+        // [n]/esc keeps editing, task preserved
+        handle_key(&mut a, esc());
+        assert_eq!(a.mode, Mode::NewAgent);
+        assert_eq!(a.new_form.task_text(), "do the thing");
+        // reopen confirm, [y] discards and resets the form
+        handle_new_agent_key(&mut a, esc());
+        handle_key(&mut a, KeyEvent::new(KeyCode::Char('y'), KeyModifiers::empty()));
+        assert_eq!(a.mode, Mode::Normal);
+        assert!(a.new_form.task_text().is_empty());
+    }
+}
diff --git a/tui/src/pty.rs b/tui/src/pty.rs
new file mode 100644
index 0000000..efc2223
--- /dev/null
+++ b/tui/src/pty.rs
@@ -0,0 +1,197 @@
+//! In-TUI interactive agents: each agent runs its harness REPL inside a PTY we
+//! own, and its output is parsed by a vt100 emulator so it can be rendered in a
+//! pane *inside* the dashboard (via tui-term). Keystrokes are written straight
+//! back to the PTY. No tmux, no leaving the TUI.
+//!
+//! Agents live for the lifetime of the TUI process (they're owned here). That's
+//! the trade-off for "everything happens inside the TUI".
+
+use anyhow::{Context, Result};
+use portable_pty::{native_pty_system, Child, CommandBuilder, MasterPty, PtySize};
+use std::io::{Read, Write};
+use std::sync::{Arc, Mutex};
+use std::thread;
+
+/// A single interactive agent: PTY + vt100 screen + child process handle.
+pub struct AgentProc {
+    pub id: String,
+    pub harness: String,
+    pub model: String,
+    pub task: String,
+    pub worktree: String,
+    /// vt100 screen, fed by a background reader thread; read by the renderer.
+    pub parser: Arc<Mutex<vt100::Parser>>,
+    writer: Box<dyn Write + Send>,
+    master: Box<dyn MasterPty + Send>,
+    child: Box<dyn Child + Send + Sync>,
+}
+
+impl AgentProc {
+    /// Spawn `argv` in a PTY at `cwd`, seeded with `task` as the first message.
+    pub fn spawn(
+        id: String,
+        harness: String,
+        model: String,
+        task: String,
+        worktree: String,
+        argv: &[String],
+        rows: u16,
+        cols: u16,
+    ) -> Result<AgentProc> {
+        let pty = native_pty_system();
+        let pair = pty
+            .openpty(PtySize { rows, cols, pixel_width: 0, pixel_height: 0 })
+            .context("openpty")?;
+
+        let mut cmd = CommandBuilder::new(&argv[0]);
+        for a in &argv[1..] {
+            cmd.arg(a);
+        }
+        cmd.cwd(&worktree);
+        cmd.env("TERM", "xterm-256color");
+
+        let child = pair.slave.spawn_command(cmd).context("spawn agent command")?;
+        // slave no longer needed in this process; dropping it lets EOF propagate.
+        drop(pair.slave);
+
+        let mut reader = pair.master.try_clone_reader().context("clone reader")?;
+        let writer = pair.master.take_writer().context("take writer")?;
+        let parser = Arc::new(Mutex::new(vt100::Parser::new(rows, cols, 2000)));
+
+        {
+            let parser = parser.clone();
+            thread::spawn(move || {
+                let mut buf = [0u8; 8192];
+                loop {
+                    match reader.read(&mut buf) {
+                        Ok(0) | Err(_) => break,
+                        Ok(n) => {
+                            if let Ok(mut p) = parser.lock() {
+                                p.process(&buf[..n]);
+                            }
+                        }
+                    }
+                }
+            });
+        }
+
+        let proc = AgentProc {
+            id,
+            harness,
+            model,
+            task: task.clone(),
+            worktree,
+            parser,
+            writer,
+            master: pair.master,
+            child,
+        };
+        // Seed the first message. A fixed sleep races the harness's startup —
+        // if we type before its input box exists the keystrokes are dropped and
+        // the task never reaches the agent. Instead wait until the REPL has
+        // drawn something (screen goes non-empty), then a short settle, then type.
+        if !task.trim().is_empty() {
+            let task = task.clone();
+            let parser = proc.parser.clone();
+            let mut w = proc.try_clone_writer();
+            thread::spawn(move || {
+                let start = std::time::Instant::now();
+                loop {
+                    let ready = parser
+                        .lock()
+                        .map(|p| !p.screen().contents().trim().is_empty())
+                        .unwrap_or(false);
+                    if ready || start.elapsed() > std::time::Duration::from_secs(8) {
+                        break;
+                    }
+                    thread::sleep(std::time::Duration::from_millis(50));
+                }
+                // let the input box finish painting before typing into it
+                thread::sleep(std::time::Duration::from_millis(400));
+                if let Some(w) = w.as_mut() {
+                    let _ = w.write_all(task.as_bytes());
+                    let _ = w.write_all(b"\r");
+                    let _ = w.flush();
+                }
+            });
+        }
+        Ok(proc)
+    }
+
+    /// A second writer handle (PTY master writers are independent clones).
+    fn try_clone_writer(&self) -> Option<Box<dyn Write + Send>> {
+        self.master.take_writer().ok()
+    }
+
+    /// Forward raw bytes (a keypress) to the agent.
+    pub fn send(&mut self, bytes: &[u8]) {
+        let _ = self.writer.write_all(bytes);
+        let _ = self.writer.flush();
+    }
+
+    /// Resize the PTY + emulator to fit the render area. Takes `&self` (both
+    /// `MasterPty::resize` and `Mutex::lock` do) so the renderer can call it.
+    pub fn resize(&self, rows: u16, cols: u16) {
+        if rows == 0 || cols == 0 {
+            return;
+        }
+        if let Ok(mut p) = self.parser.lock() {
+            if p.screen().size() == (rows, cols) {
+                return;
+            }
+            let _ = self.master.resize(PtySize { rows, cols, pixel_width: 0, pixel_height: 0 });
+            p.set_size(rows, cols);
+        }
+    }
+
+    /// True while the child process is still running.
+    pub fn is_alive(&mut self) -> bool {
+        matches!(self.child.try_wait(), Ok(None))
+    }
+
+    /// Terminate the agent.
+    pub fn kill(&mut self) {
+        let _ = self.child.kill();
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn pty_captures_command_output() {
+        // spawn a trivial command in a PTY and confirm vt100 captures its output.
+        let dir = std::env::temp_dir();
+        let argv = vec!["printf".to_string(), "HELLO_PTY".to_string()];
+        let mut a = AgentProc::spawn(
+            "t1".into(), "stub".into(), "m".into(), String::new(),
+            dir.to_string_lossy().to_string(), &argv, 24, 80,
+        )
+        .unwrap();
+        // let the reader thread drain the output
+        std::thread::sleep(std::time::Duration::from_millis(400));
+        let screen = a.parser.lock().unwrap().screen().contents();
+        assert!(screen.contains("HELLO_PTY"), "vt100 did not capture output: {:?}", screen);
+        a.kill();
+    }
+
+    #[test]
+    fn pty_forwards_input() {
+        // `cat` echoes stdin back to stdout — prove send() reaches the process
+        // and the echoed bytes land on the vt100 screen.
+        let dir = std::env::temp_dir();
+        let argv = vec!["cat".to_string()];
+        let mut a = AgentProc::spawn(
+            "t2".into(), "stub".into(), "m".into(), String::new(),
+            dir.to_string_lossy().to_string(), &argv, 24, 80,
+        )
+        .unwrap();
+        std::thread::sleep(std::time::Duration::from_millis(200));
+        a.send(b"PING_INPUT\r");
+        std::thread::sleep(std::time::Duration::from_millis(300));
+        let screen = a.parser.lock().unwrap().screen().contents();
+        assert!(screen.contains("PING_INPUT"), "input not echoed to screen: {:?}", screen);
+        a.kill();
+    }
+}
diff --git a/tui/src/store.rs b/tui/src/store.rs
new file mode 100644
index 0000000..7b42e1e
--- /dev/null
+++ b/tui/src/store.rs
@@ -0,0 +1,113 @@
+//! Subprocess JSON client for the nexum Python engine.
+//!
+//! The TUI shells `python3 <scripts>/store.py … --json` and `worktree.py …`, so
+//! the schema/logic stays owned by the Python engine and the Rust side is thin.
+
+use crate::agent::Session;
+use anyhow::{anyhow, Context, Result};
+use serde::{Deserialize, Serialize};
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+/// A launched agent persisted to disk so it survives a TUI restart. The harness
+/// itself supports resume (claude/opencode/cursor), so relaunching in the same
+/// worktree picks up where it left off.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AgentRecord {
+    pub id: String,
+    pub harness: String,
+    pub model: String,
+    pub worktree: String,
+    pub task: String,
+}
+
+pub struct Store {
+    /// Absolute repo root (git toplevel) — the scoping key for every query.
+    pub repo_root: PathBuf,
+    /// Directory containing store.py / worktree.py.
+    pub scripts_dir: PathBuf,
+    /// python interpreter to use.
+    pub python: String,
+}
+
+impl Store {
+    pub fn new(repo_root: PathBuf, scripts_dir: PathBuf) -> Store {
+        let python = std::env::var("NEXUM_PYTHON").unwrap_or_else(|_| "python3".to_string());
+        Store { repo_root, scripts_dir, python }
+    }
+
+    fn store_py(&self) -> PathBuf {
+        self.scripts_dir.join("store.py")
+    }
+
+    fn repo_arg(&self) -> String {
+        self.repo_root.to_string_lossy().to_string()
+    }
+
+    /// Observed plugin sessions for this repo (`session-list --repo <root> --json`).
+    pub fn sessions(&self) -> Result<Vec<Session>> {
+        let out = Command::new(&self.python)
+            .arg(self.store_py())
+            .args(["session-list", "--repo", &self.repo_arg(), "--json"])
+            .output()
+            .context("spawn store.py session-list")?;
+        let stdout = String::from_utf8_lossy(&out.stdout);
+        let v: Vec<Session> = serde_json::from_str(stdout.trim()).unwrap_or_default();
+        Ok(v)
+    }
+
+    fn registry_path(&self) -> PathBuf {
+        self.repo_root.join(".nexum-data").join("tui-agents.json")
+    }
+
+    /// Load the persisted (resumable) agent records for this repo.
+    pub fn load_registry(&self) -> Vec<AgentRecord> {
+        std::fs::read_to_string(self.registry_path())
+            .ok()
+            .and_then(|s| serde_json::from_str(&s).ok())
+            .unwrap_or_default()
+    }
+
+    /// Persist the agent registry (best-effort).
+    pub fn save_registry(&self, records: &[AgentRecord]) {
+        let path = self.registry_path();
+        if let Some(parent) = path.parent() {
+            let _ = std::fs::create_dir_all(parent);
+        }
+        if let Ok(json) = serde_json::to_string_pretty(records) {
+            let _ = std::fs::write(path, json);
+        }
+    }
+
+    /// Create an isolated git worktree via worktree.py; returns its path.
+    pub fn create_worktree(&self, slug: &str) -> Result<String> {
+        let out = Command::new(&self.python)
+            .arg(self.scripts_dir.join("worktree.py"))
+            .args(["--create", "--repo", &self.repo_arg(), "--slug", slug])
+            .output()
+            .context("spawn worktree.py")?;
+        let v: serde_json::Value =
+            serde_json::from_str(String::from_utf8_lossy(&out.stdout).trim())
+                .context("parse worktree.py output")?;
+        v.get("worktree")
+            .and_then(|x| x.as_str())
+            .map(|s| s.to_string())
+            .ok_or_else(|| anyhow!("worktree creation failed"))
+    }
+}
+
+/// Resolve the git toplevel of `start` (falls back to `start` itself).
+pub fn git_toplevel(start: &Path) -> PathBuf {
+    let out = Command::new("git")
+        .args(["-C", &start.to_string_lossy(), "rev-parse", "--show-toplevel"])
+        .output();
+    if let Ok(o) = out {
+        if o.status.success() {
+            let s = String::from_utf8_lossy(&o.stdout).trim().to_string();
+            if !s.is_empty() {
+                return PathBuf::from(s);
+            }
+        }
+    }
+    start.to_path_buf()
+}
diff --git a/tui/src/ui.rs b/tui/src/ui.rs
new file mode 100644
index 0000000..cf4e093
--- /dev/null
+++ b/tui/src/ui.rs
@@ -0,0 +1,428 @@
+//! Rendering. Master-detail: an agent list on the left; on the right either the
+//! selected agent's *embedded terminal* (interactive) or a preview (observed).
+
+use crate::agent::{rel_time, Kind};
+use crate::app::{App, Mode};
+use ratatui::{
+    layout::{Constraint, Direction, Layout, Rect},
+    style::{Color, Modifier, Style},
+    text::{Line, Span},
+    widgets::{Block, Borders, Clear, List, ListItem, ListState, Paragraph, Wrap},
+    Frame,
+};
+use tui_term::widget::PseudoTerminal;
+
+fn status_color(status: &str) -> Color {
+    match status {
+        "running" => Color::Green,
+        "resumable" => Color::Yellow,
+        "exited" => Color::DarkGray,
+        _ => Color::Cyan, // observed
+    }
+}
+
+fn status_icon(status: &str) -> &'static str {
+    match status {
+        "running" => "●",
+        "resumable" => "▷",
+        "exited" => "□",
+        _ => "·",
+    }
+}
+
+pub fn draw(f: &mut Frame, app: &App) {
+    let chunks = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([Constraint::Length(1), Constraint::Min(5), Constraint::Length(1)])
+        .split(f.area());
+
+    draw_header(f, app, chunks[0]);
+
+    let cols = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([Constraint::Percentage(34), Constraint::Percentage(66)])
+        .split(chunks[1]);
+    draw_list(f, app, cols[0]);
+    draw_right(f, app, cols[1]);
+
+    draw_footer(f, app, chunks[2]);
+
+    match app.mode {
+        Mode::NewAgent => draw_form(f, app),
+        Mode::Help => draw_help(f),
+        Mode::ConfirmStop => draw_confirm(f, app),
+        Mode::ConfirmQuit => draw_confirm_quit(f, app),
+        Mode::ConfirmDiscard => draw_confirm_discard(f),
+        _ => {}
+    }
+}
+
+fn draw_header(f: &mut Frame, app: &App, area: Rect) {
+    let repo = app
+        .store
+        .repo_root
+        .file_name()
+        .map(|s| s.to_string_lossy().to_string())
+        .unwrap_or_else(|| "?".into());
+    let mode = match app.mode {
+        Mode::Terminal => " CHAT ",
+        _ => "",
+    };
+    let mut spans = vec![
+        Span::styled(" nexum ", Style::default().bg(Color::Blue).fg(Color::White).add_modifier(Modifier::BOLD)),
+        Span::raw(format!(" {} ", repo)),
+        Span::styled(
+            format!("· {} agents ({} running) ", app.agents.len(), app.running_count()),
+            Style::default().fg(Color::Gray),
+        ),
+    ];
+    if app.mode == Mode::Filter || !app.filter_text.is_empty() {
+        let caret = if app.mode == Mode::Filter { "_" } else { "" };
+        spans.push(Span::styled(format!("/{}{} ", app.filter_text, caret), Style::default().fg(Color::Cyan)));
+    }
+    if !mode.is_empty() {
+        spans.push(Span::styled(mode, Style::default().bg(Color::Green).fg(Color::Black).add_modifier(Modifier::BOLD)));
+    }
+    spans.push(Span::styled(format!(" {}", app.status_msg), Style::default().fg(Color::Yellow)));
+    f.render_widget(Paragraph::new(Line::from(spans)), area);
+}
+
+fn draw_list(f: &mut Frame, app: &App, area: Rect) {
+    let title = format!(" agents ({}) ", app.rows.len());
+    if app.rows.is_empty() {
+        let hint = Paragraph::new("\n  no agents yet.\n\n  press [n] to launch one.")
+            .style(Style::default().fg(Color::DarkGray))
+            .block(Block::default().borders(Borders::ALL).title(title));
+        f.render_widget(hint, area);
+        return;
+    }
+    let inner_w = area.width.saturating_sub(4) as usize;
+    let now = now_secs();
+    let items: Vec<ListItem> = app
+        .rows
+        .iter()
+        .map(|r| {
+            let icon = Span::styled(format!("{} ", status_icon(&r.status)),
+                Style::default().fg(status_color(&r.status)));
+            let who = Span::styled(format!("{:<8} ", truncate(&r.harness, 8)), Style::default().fg(Color::Gray));
+            let meta = rel_time(r.updated_ts, now);
+            let fixed = 2 + 9 + meta.len() + 1;
+            let task_w = inner_w.saturating_sub(fixed).max(6);
+            let task = truncate(if r.task.is_empty() { "(no task)" } else { &r.task }, task_w);
+            let pad = inner_w.saturating_sub(2 + 9 + task.chars().count() + meta.len());
+            ListItem::new(Line::from(vec![
+                icon, who, Span::raw(task), Span::raw(" ".repeat(pad)),
+                Span::styled(meta, Style::default().fg(Color::DarkGray)),
+            ]))
+        })
+        .collect();
+
+    let list = List::new(items)
+        .block(Block::default().borders(Borders::ALL).title(title))
+        .highlight_style(Style::default().bg(Color::Blue).fg(Color::White).add_modifier(Modifier::BOLD))
+        .highlight_symbol("▶ ");
+    let mut state = ListState::default();
+    state.select(Some(app.selected.min(app.rows.len() - 1)));
+    f.render_stateful_widget(list, area, &mut state);
+}
+
+fn draw_right(f: &mut Frame, app: &App, area: Rect) {
+    match app.selected_row() {
+        Some(r) if r.interactive => {
+            if let Some(idx) = r.proc_idx {
+                draw_terminal(f, app, idx, area);
+                return;
+            }
+        }
+        _ => {}
+    }
+    draw_preview(f, app, area);
+}
+
+/// The embedded terminal — the agent's live REPL, rendered inside the TUI.
+fn draw_terminal(f: &mut Frame, app: &App, idx: usize, area: Rect) {
+    let focused = app.mode == Mode::Terminal;
+    let title = if focused {
+        " chat · typing goes to the agent · [Ctrl-o] leave ".to_string()
+    } else {
+        " terminal · [enter] to chat ".to_string()
+    };
+    let border = if focused { Color::Green } else { Color::DarkGray };
+    let block = Block::default().borders(Borders::ALL)
+        .border_style(Style::default().fg(border))
+        .title(title);
+    let inner = block.inner(area);
+    f.render_widget(block, area);
+
+    if let Some(proc) = app.agents.get(idx) {
+        // keep the PTY sized to the visible pane
+        proc.resize(inner.height.max(1), inner.width.max(1));
+        if let Ok(parser) = proc.parser.lock() {
+            let term = PseudoTerminal::new(parser.screen());
+            f.render_widget(term, inner);
+        }
+    }
+}
+
+fn draw_preview(f: &mut Frame, app: &App, area: Rect) {
+    let block = Block::default().borders(Borders::ALL).title(" preview ");
+    let Some(r) = app.selected_row() else {
+        let p = Paragraph::new("\n  select an agent, or press [n] to launch one.")
+            .style(Style::default().fg(Color::DarkGray)).block(block);
+        f.render_widget(p, area);
+        return;
+    };
+    let field = |k: &str| Span::styled(format!("{:<9}", k), Style::default().fg(Color::DarkGray));
+    let kind = match r.kind { Kind::Managed => "agent", Kind::Observed => "observed session" };
+    let lines = vec![
+        Line::from(Span::styled(truncate(if r.task.is_empty() { "(no task)" } else { &r.task }, 60),
+            Style::default().add_modifier(Modifier::BOLD))),
+        Line::from(vec![field("status"), Span::styled(
+            format!("{} {}", status_icon(&r.status), r.status), Style::default().fg(status_color(&r.status)))]),
+        Line::from(vec![field("kind"), Span::raw(kind.to_string())]),
+        Line::from(vec![field("harness"), Span::raw(format!("{} · {}", r.harness, r.model))]),
+        Line::from(vec![field("cost"), Span::raw(format!("${:.3}", r.cost_usd))]),
+        Line::from(vec![field("context"), Span::raw(r.ctx_pct.map(|p| format!("{:.0}%", p)).unwrap_or_else(|| "-".into()))]),
+    ];
+    f.render_widget(Paragraph::new(lines).block(block).wrap(Wrap { trim: false }), area);
+}
+
+fn draw_footer(f: &mut Frame, app: &App, area: Rect) {
+    let keys = match app.mode {
+        Mode::Terminal => "CHAT — type to talk to the agent   ·   [Ctrl-o] back to dashboard",
+        _ => "[q]uit [j/k]move [n]ew [enter]chat [s]top [x]rm [o]wt [/]find [h]ide-obs [?]help",
+    };
+    f.render_widget(
+        Paragraph::new(Span::styled(keys, Style::default().fg(Color::DarkGray))),
+        area,
+    );
+}
+
+fn draw_form(f: &mut Frame, app: &App) {
+    let area = centered(76, 66, f.area());
+    f.render_widget(Clear, area);
+    let form = &app.new_form;
+    use crate::app::{FIELD_HARNESS, FIELD_IMAGES, FIELD_MODEL, FIELD_TASK, FIELD_WORKTREE};
+
+    let block = Block::default().borders(Borders::ALL).title(" new agent ");
+    let inner = block.inner(area);
+    f.render_widget(block, area);
+
+    let rows = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Length(1), // title
+            Constraint::Length(1), // label: task
+            Constraint::Length(5), // task editor
+            Constraint::Length(1), // harness
+            Constraint::Length(1), // model
+            Constraint::Length(1), // worktree
+            Constraint::Length(1), // images
+            Constraint::Min(1),    // hints / error
+        ])
+        .split(inner);
+
+    let lbl = |i: usize, t: &str| {
+        let active = form.field == i;
+        Span::styled(
+            format!("{}{}", if active { "▶ " } else { "  " }, t),
+            if active { Style::default().fg(Color::White).add_modifier(Modifier::BOLD) }
+            else { Style::default().fg(Color::Gray) },
+        )
+    };
+    let picker = |active: bool, value: &str, idx: usize, total: usize| {
+        let arrow = if active { Color::Cyan } else { Color::DarkGray };
+        Line::from(vec![
+            Span::styled("   ‹ ", Style::default().fg(arrow)),
+            Span::styled(value.to_string(), Style::default().fg(Color::Green).add_modifier(Modifier::BOLD)),
+            Span::styled(" ›", Style::default().fg(arrow)),
+            Span::styled(format!("  {}/{}", idx + 1, total), Style::default().fg(Color::DarkGray)),
+        ])
+    };
+
+    f.render_widget(Paragraph::new(Span::styled("  Launch an interactive agent",
+        Style::default().add_modifier(Modifier::BOLD))), rows[0]);
+    f.render_widget(Paragraph::new(Line::from(lbl(FIELD_TASK, "task *  (Enter = newline)"))), rows[1]);
+
+    // the multiline rich task editor
+    let mut task = form.task.clone();
+    let te_border = if form.field == FIELD_TASK { Color::Cyan } else { Color::DarkGray };
+    task.set_block(Block::default().borders(Borders::ALL).border_style(Style::default().fg(te_border)));
+    f.render_widget(&task, rows[2]);
+
+    let presets = crate::app::model_presets(form.harness_idx);
+    let mut hline = vec![lbl(FIELD_HARNESS, "harness")];
+    hline.extend(picker(form.field == FIELD_HARNESS, form.harness(), form.harness_idx, 3).spans);
+    f.render_widget(Paragraph::new(Line::from(hline)), rows[3]);
+
+    let mut mline = vec![lbl(FIELD_MODEL, "model")];
+    mline.extend(picker(form.field == FIELD_MODEL, form.model(), form.model_idx, presets.len()).spans);
+    f.render_widget(Paragraph::new(Line::from(mline)), rows[4]);
+
+    let wt = if form.worktree_new { "new git worktree (isolated)" } else { "current repo (shared)" };
+    let mut wline = vec![lbl(FIELD_WORKTREE, "worktree")];
+    wline.extend(picker(form.field == FIELD_WORKTREE, wt, if form.worktree_new {0} else {1}, 2).spans);
+    f.render_widget(Paragraph::new(Line::from(wline)), rows[5]);
+
+    let img = if let Some(buf) = &form.image_input {
+        format!("   typing path: {}_", buf)
+    } else if form.images.is_empty() {
+        "   (none — [a] add, [d] remove)".to_string()
+    } else {
+        format!("   {}  ([a] add, [d] remove)", form.images.join(", "))
+    };
+    let mut iline = vec![lbl(FIELD_IMAGES, "images")];
+    iline.push(Span::styled(img, Style::default().fg(Color::Gray)));
+    f.render_widget(Paragraph::new(Line::from(iline)), rows[6]);
+
+    let mut hints = Vec::new();
+    if let Some(err) = &form.error {
+        hints.push(Line::from(Span::styled(format!("  ⚠ {}", err), Style::default().fg(Color::Red))));
+    }
+    hints.push(Line::from(Span::styled(
+        "  [tab] next field   [←→] change   [ Ctrl-S ] launch & chat   [esc] cancel",
+        Style::default().fg(Color::DarkGray))));
+    f.render_widget(Paragraph::new(hints).wrap(Wrap { trim: false }), rows[7]);
+}
+
+fn draw_help(f: &mut Frame) {
+    let area = centered(62, 72, f.area());
+    f.render_widget(Clear, area);
+    let rows = [
+        ("j / k, ↑ / ↓", "move selection"),
+        ("n", "new interactive agent (chat) in a worktree"),
+        ("enter", "chat with a live agent, or resume a ▷ one"),
+        ("Ctrl-o", "leave the terminal, back to the dashboard"),
+        ("s", "stop the selected agent"),
+        ("x", "remove the selected agent"),
+        ("o", "show worktree path"),
+        ("/", "search    ·    h  toggle observed sessions"),
+        ("q", "quit"),
+    ];
+    let lines: Vec<Line> = rows.iter().map(|(k, d)| Line::from(vec![
+        Span::styled(format!("  {:<14}", k), Style::default().fg(Color::Cyan).add_modifier(Modifier::BOLD)),
+        Span::raw(*d),
+    ])).collect();
+    f.render_widget(Paragraph::new(lines)
+        .block(Block::default().borders(Borders::ALL).title(" help — any key to close ")), area);
+}
+
+fn draw_confirm(f: &mut Frame, app: &App) {
+    let area = centered(50, 20, f.area());
+    f.render_widget(Clear, area);
+    let id = app.selected_row().map(|r| r.id.clone()).unwrap_or_default();
+    let lines = vec![
+        Line::from(""),
+        Line::from(Span::raw(format!("  Stop agent {} ?", id))),
+        Line::from(""),
+        Line::from(Span::styled("  [y] confirm   [n/esc] cancel", Style::default().fg(Color::DarkGray))),
+    ];
+    f.render_widget(Paragraph::new(lines)
+        .block(Block::default().borders(Borders::ALL).title(Span::styled(" confirm stop ", Style::default().fg(Color::Red)))), area);
+}
+
+fn draw_confirm_quit(f: &mut Frame, app: &App) {
+    let area = centered(58, 26, f.area());
+    f.render_widget(Clear, area);
+    let n = app.agents.len();
+    let lines = vec![
+        Line::from(""),
+        Line::from(Span::styled(format!("  Quit? {} agent(s) will stop.", n),
+            Style::default().add_modifier(Modifier::BOLD))),
+        Line::from(""),
+        Line::from(Span::styled(
+            "  Their worktrees are kept — reopen the TUI and press",
+            Style::default().fg(Color::Gray))),
+        Line::from(Span::styled(
+            "  [enter] on a ▷ resumable agent to continue where it left off.",
+            Style::default().fg(Color::Gray))),
+        Line::from(""),
+        Line::from(Span::styled("  [y] quit   [n/esc] cancel", Style::default().fg(Color::DarkGray))),
+    ];
+    f.render_widget(Paragraph::new(lines).wrap(Wrap { trim: false })
+        .block(Block::default().borders(Borders::ALL)
+            .title(Span::styled(" confirm quit ", Style::default().fg(Color::Yellow)))), area);
+}
+
+fn draw_confirm_discard(f: &mut Frame) {
+    let area = centered(50, 20, f.area());
+    f.render_widget(Clear, area);
+    let lines = vec![
+        Line::from(""),
+        Line::from(Span::raw("  Discard this new agent?")),
+        Line::from(""),
+        Line::from(Span::styled("  [y] discard   [n/esc] keep editing", Style::default().fg(Color::DarkGray))),
+    ];
+    f.render_widget(Paragraph::new(lines)
+        .block(Block::default().borders(Borders::ALL).title(Span::styled(" confirm discard ", Style::default().fg(Color::Yellow)))), area);
+}
+
+fn centered(pw: u16, ph: u16, area: Rect) -> Rect {
+    let w = area.width * pw / 100;
+    let h = area.height * ph / 100;
+    Rect {
+        x: area.x + (area.width.saturating_sub(w)) / 2,
+        y: area.y + (area.height.saturating_sub(h)) / 2,
+        width: w.max(24),
+        height: h.max(10),
+    }
+}
+
+fn truncate(s: &str, n: usize) -> String {
+    if s.chars().count() <= n {
+        s.to_string()
+    } else {
+        let mut out: String = s.chars().take(n.saturating_sub(1)).collect();
+        out.push('…');
+        out
+    }
+}
+
+fn now_secs() -> f64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.as_secs_f64())
+        .unwrap_or(0.0)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::app::App;
+    use crate::store::Store;
+    use ratatui::{backend::TestBackend, Terminal};
+    use std::path::PathBuf;
+
+    fn buffer_text(term: &Terminal<TestBackend>) -> String {
+        term.backend().buffer().content().iter().map(|c| c.symbol()).collect()
+    }
+
+    #[test]
+    fn renders_empty_dashboard_chrome() {
+        let store = Store::new(PathBuf::from("/tmp/myrepo"), PathBuf::from("/tmp/myrepo/scripts"));
+        let app = App::new(store);
+        let mut term = Terminal::new(TestBackend::new(120, 24)).unwrap();
+        term.draw(|f| draw(f, &app)).unwrap();
+        let text = buffer_text(&term);
+        assert!(text.contains("nexum"));
+        assert!(text.contains("myrepo"));
+        assert!(text.contains("agents ("));
+        assert!(text.contains("[n]ew"));
+    }
+
+    #[test]
+    fn renders_new_agent_form() {
+        let store = Store::new(PathBuf::from("/tmp/myrepo"), PathBuf::from("/tmp/myrepo/scripts"));
+        let mut app = App::new(store);
+        app.open_new_agent();
+        app.new_form.task.insert_str("add billing endpoint");
+        let mut term = Terminal::new(TestBackend::new(120, 30)).unwrap();
+        term.draw(|f| draw(f, &app)).unwrap();
+        let text = buffer_text(&term);
+        assert!(text.contains("new agent"));
+        assert!(text.contains("task *"));
+        assert!(text.contains("harness"));
+        assert!(text.contains("worktree"));
+        assert!(text.contains("Ctrl-S"));
+    }
+}

From cb6a34c3a8b52e1eaa94c11dd2a192dc666635be Mon Sep 17 00:00:00 2001
From: Rahul Tyagi <rahul.1992.tyagi@gmail.com>
Date: Fri, 10 Jul 2026 14:02:20 +0530
Subject: [PATCH 15/16] feat(crew): standalone multi-harness agent TUI,
 delegation MCP, docs site
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

crew: rebrand the TUI into a standalone product — native git worktrees,
own .crew/ registry+config, optional nexum engine (auto-detected). Chat with
agents in embedded PTYs; launch interactively or via crew --new [--here].

Manage the fleet: diff/log viewers (search + live-follow), commit/push/open-PR
(single or bulk), retry/re-delegate, rename/label, multi-select, filters, sort,
paging, settings, session persistence, completion toasts, worktree prune.

Git-aware: per-row dirty (±), ahead/behind, PR badge, fetch, harness/repo guards,
crew --doctor.

Delegation MCP (scripts/mcp_server.py): delegate / delegate_async / check /
list_agents over stdio; registered in .mcp.json. Engine: harness.py, dispatch.py,
worktree.py with tests.

docs/: self-contained GitHub Pages site with live screenshots (tui/site/gen.py).
---
 .gitignore                     |    4 +
 .mcp.json                      |    8 +
 .opencode/commands/nx-build.md |    5 +
 SPEC.md                        |   38 +-
 commands/nx-build.md           |   37 +
 docs/.nojekyll                 |    0
 docs/index.html                |  239 +++++
 scripts/context_watch.py       |   56 +-
 scripts/dispatch.py            |  264 ++++++
 scripts/harness.py             |  217 +++++
 scripts/mcp_server.py          |  464 ++++++++++
 scripts/session_reset.py       |   32 +-
 scripts/store.py               |  332 +++++++
 scripts/worktree.py            |  181 ++++
 tests/fixtures/fake_harness.py |   23 +
 tests/test_context_watch.py    |  110 ++-
 tests/test_dispatch.py         |  113 +++
 tests/test_harness.py          |  109 +++
 tests/test_mcp_server.py       |  173 ++++
 tests/test_meta_imports.py     |    4 +
 tests/test_store.py            |  174 ++++
 tests/test_worktree.py         |   91 ++
 tui/Cargo.lock                 |   30 +-
 tui/Cargo.toml                 |    6 +-
 tui/README.md                  |  155 +++-
 tui/site/gen.py                |  236 +++++
 tui/src/agent.rs               |   76 +-
 tui/src/app.rs                 | 1510 +++++++++++++++++++++++++++++++-
 tui/src/main.rs                |  726 ++++++++++++++-
 tui/src/pty.rs                 |    7 +
 tui/src/store.rs               |  200 ++++-
 tui/src/ui.rs                  |  671 ++++++++++++--
 32 files changed, 6048 insertions(+), 243 deletions(-)
 create mode 100644 .mcp.json
 create mode 100644 docs/.nojekyll
 create mode 100644 docs/index.html
 create mode 100644 scripts/dispatch.py
 create mode 100644 scripts/harness.py
 create mode 100644 scripts/mcp_server.py
 create mode 100644 scripts/worktree.py
 create mode 100644 tests/fixtures/fake_harness.py
 create mode 100644 tests/test_dispatch.py
 create mode 100644 tests/test_harness.py
 create mode 100644 tests/test_mcp_server.py
 create mode 100644 tests/test_worktree.py
 create mode 100644 tui/site/gen.py

diff --git a/.gitignore b/.gitignore
index bf8f4a1..8035867 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,7 @@
 __pycache__/
 *.pyc
 .nexum-data/
+tui/target/
+
+# crew TUI runtime data (worktrees, registry, config)
+.crew/
diff --git a/.mcp.json b/.mcp.json
new file mode 100644
index 0000000..95218af
--- /dev/null
+++ b/.mcp.json
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "nexum-delegate": {
+      "command": "python3",
+      "args": ["scripts/mcp_server.py"]
+    }
+  }
+}
diff --git a/.opencode/commands/nx-build.md b/.opencode/commands/nx-build.md
index c5c4c32..90375af 100644
--- a/.opencode/commands/nx-build.md
+++ b/.opencode/commands/nx-build.md
@@ -16,6 +16,11 @@ Read plan in full. Parse every step: index, `route`, `files`, `objective`, `cont
 
 No plan file → stop: `[nexum] No plan found for this session. Run /nx-plan first.`
 
+**Cross-harness offload.** If invoked with `--harness <claude|opencode|cursor>`,
+run each step (one at a time) in that external harness instead of a subagent:
+write the step to a JSON file `{title,objective,contract,scope_deny,acceptance,files}`
+then `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/dispatch.py --harness <name> --model <tier model> --repo <root> --new-worktree --slug <plan-slug>-step<N> --step-file <path> --session <session_id> --plan-hash <hash> --index <N>`. It creates a worktree, runs the harness headless, verifies with guardrail.py, records the ledger/usage/agents rows, and prints the same verdict JSON you parse from guardrail. `pass:true` → proceed (ledger already written); `pass:false` → §7, patch-retry on the same `--worktree`. Absent → default subagent path below.
+
 Read config once: `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/store.py config`. Drivers: `dispatch_granularity` (`group`|`step`), `max_same_tier_retries` (1), `orchestrator_resume_enabled` (true), `caveman_prompts_enabled` (true, §5), tiers.
 
 ## 1a. Resume from ledger (skip done work)
diff --git a/SPEC.md b/SPEC.md
index 35482dd..cbf2274 100644
--- a/SPEC.md
+++ b/SPEC.md
@@ -197,6 +197,9 @@ CREATE TABLE usage(     session_id TEXT, model TEXT, input_tok INTEGER,
                       ".next", "coverage", ".venv", "__pycache__"],
   "intent_guard_enabled": true,
   "intent_similarity_threshold": 0.25,
+  "worktree_enabled": true,
+  "worktree_copy": [],
+  "worktree_ignore": [],
   "statusline_compaction_warn_pct": 80,
   "statusline_compaction_warn_tokens": 80000,
   "dedup_cache_weight": 0.1,
@@ -416,21 +419,34 @@ Two responsibilities in one hook:
 - **(b) Intent-change guard:** `prompt = data["prompt"]`. Derive a keyword/topic
   signature (lowercased word set minus stopwords; plus task-type keywords:
   fix/bug/error→"fix", add/implement/feature/new→"feature", refactor, test, docs).
-  Compare to stored session task signature via Jaccard similarity. If a stored task
-  exists AND task-type changed (e.g. fix→feature) AND similarity <
-  `intent_similarity_threshold` AND no `bypass_intent` flag set:
-  emit
-  `{"decision":"block","reason":"[nexum] This looks like a new task (<old>→<new>). A fresh session gives cleaner, cheaper context. Reply 'continue' to proceed here."}`
-  and set nothing yet. If the prompt is exactly `continue` (case-insensitive,
-  trimmed) → set `bypass_intent` flag and allow (`{}`). On first prompt of a session
-  (no stored task) → store signature, allow.
+  Compare to stored session task signature via Jaccard similarity. A divergence is
+  a stored task existing AND task-type changed (e.g. fix→feature) AND similarity <
+  `intent_similarity_threshold` AND no `bypass_intent` flag set. On divergence,
+  decide by the **working-tree state** (via `worktree.is_dirty(cwd)`), NOT by
+  session token size:
+  - **Dirty tree** (uncommitted work) AND `worktree_enabled`: create/reuse an
+    isolated worktree at `<repo>/.nexum-data/worktrees/<slug>` on branch
+    `nexum/<slug>` (`worktree.create_worktree`), copying `worktree_copy` globs
+    (minus `worktree_ignore`) so untracked helpers the new work needs come along,
+    then emit `{"decision":"block","reason":"[nexum] New task (<old>→<new>) with
+    uncommitted work in progress. Isolated it in a worktree:\n  <path>\nOpen a
+    session there to keep this work separate, or reply 'continue' to work here
+    anyway."}`.
+  - **Clean tree** (or `worktree_enabled` false, or creation failed): the divergent
+    task is fine in the current context — adopt the new signature and allow (`{}`).
+    No more "start a fresh session" nag.
+  If the prompt is exactly `continue` (case-insensitive, trimmed) → set
+  `bypass_intent` flag and allow (`{}`). On first prompt of a session (no stored
+  task) → store signature, allow.
 - Respect `intent_guard_enabled`. Always update the stored task signature AFTER a
   non-blocked prompt.
 - **EDGE CASES:** empty prompt → allow; `continue` bypass must clear so the new task
-  becomes the session task; never block twice in a row for the same divergence.
+  becomes the session task; never block twice in a row for the same divergence;
+  all git/fs errors fail-open (no block).
 - **ACCEPTANCE:** first prompt allowed + stored; same-topic follow-up allowed;
-  fix→feature divergence blocked; `continue` bypasses then adopts new task;
-  threshold crossing emits systemMessage exactly once per window.
+  fix→feature divergence on a dirty tree creates a worktree + blocks; the same
+  divergence on a clean tree is allowed with no worktree; `continue` bypasses then
+  adopts new task; threshold crossing emits systemMessage exactly once per window.
 
 ### 5.3 `scripts/audit.py` + `commands/nx-audit.md` · TIER: standard
 - CLI `python3 audit.py [--root <dir>] [--write]`. Scans `--root` (default cwd):
diff --git a/commands/nx-build.md b/commands/nx-build.md
index 9f4d6ef..13cbf89 100644
--- a/commands/nx-build.md
+++ b/commands/nx-build.md
@@ -16,6 +16,9 @@ Read plan in full. Parse every step: index, `route`, `files`, `objective`, `cont
 
 No plan file → stop: `[nexum] No plan found for this session. Run /nx-plan first.`
 
+**Args.** If the invocation includes `--harness <claude|opencode|cursor>`, every
+step runs in that external harness via §4b instead of an in-session subagent. Absent → default path.
+
 Read config once: `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/store.py config`. Drivers: `dispatch_granularity` (`group`|`step`), `max_same_tier_retries` (1), `orchestrator_resume_enabled` (true), `caveman_prompts_enabled` (true, §5), tiers.
 
 ## 1a. Resume from ledger (skip done work)
@@ -79,6 +82,40 @@ Subagent earns its keep only by running a *different* model without trashing the
 
 Doubt about session model → dispatch (redundant spawn < cache-trashing switch).
 
+## 4b. Cross-harness offload (`--harness <claude|opencode|cursor>`)
+
+Invoked with `--harness <name>` → run every step in that **external harness** (a
+headless `claude`/`opencode`/`cursor` process in its own git worktree) instead of
+an in-session subagent. No `--harness` → default in-session path (§4/§5), unchanged.
+
+Per step (grouping is a Claude-subagent optimization only — under `--harness`,
+dispatch **one step at a time**): write the step to a JSON file
+`{title, objective, contract, scope_deny, acceptance, files}` where `scope_deny`
+is each path from the step's `scope: do NOT touch`. Then:
+
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/dispatch.py \
+  --harness <name> --model <tier's model> --repo <repo root> \
+  --new-worktree --slug <plan-slug>-step<N> --step-file <path> \
+  --session <session_id> --plan-hash <plan_hash> --index <N>
+```
+
+`dispatch.py` creates the worktree, runs the harness headless, verifies with
+`guardrail.py`, records the `agents`/`step_ledger`/`usage` rows itself, and prints
+the verdict JSON `{"pass", "diff", "scope_violations", "acceptance_rc", "tokens",
+"cost_usd", "agent_id", "worktree", ...}` — the **same shape** you parse from
+guardrail. Read `pass`:
+
+- **true** → proceed. `dispatch.py` already wrote the ledger + usage, so SKIP the
+  §6a `step-set`/`record-usage`; still record calibration (§6a).
+- **false** → §7 ladder. A patch-retry re-runs `dispatch.py` on the **same**
+  worktree (`--worktree <path>` from the verdict instead of `--new-worktree`),
+  appending the guardrail failure + prior `diff` to the step objective.
+
+Route→model still applies; `--harness` only changes *where* it runs. (Auto
+route→harness mapping is future work — for now the one `--harness` applies to all
+steps.)
+
 ## 5. Build delegation (stable-prefix-first)
 
 Shared/stable content first, variable last → longest cacheable common prefix:
diff --git a/docs/.nojekyll b/docs/.nojekyll
new file mode 100644
index 0000000..e69de29
diff --git a/docs/index.html b/docs/index.html
new file mode 100644
index 0000000..11ac92c
--- /dev/null
+++ b/docs/index.html
@@ -0,0 +1,239 @@
+<!doctype html>
+<html lang=en data-theme=dark>
+<head>
+<meta charset=utf-8>
+<meta name=viewport content="width=device-width, initial-scale=1">
+<title>crew — a terminal dashboard for coding agents</title>
+<meta name=description content="crew runs, chats with, and manages coding agents (Claude, OpenCode, Cursor) across git worktrees — from one terminal dashboard.">
+<style>
+:root{--bg:#0b0e14;--panel:#0d1117;--ink:#e6edf3;--dim:#8b949e;--line:#232a34;--acc:#39d0d8;--acc2:#7c5cff;--green:#3fb950;--red:#f85149;--yellow:#e3b341}
+*{box-sizing:border-box}
+body{margin:0;background:radial-gradient(1200px 600px at 70% -10%,#16202e 0,var(--bg) 60%);color:var(--ink);font:16px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif}
+.wrap{max-width:1080px;margin:0 auto;padding:0 20px}
+a{color:var(--acc)}
+header.top{padding:16px 0;display:flex;align-items:center;gap:12px}
+.logo{font-weight:800;font-size:20px;letter-spacing:.5px}
+.logo b{background:var(--acc2);color:#fff;padding:2px 8px;border-radius:6px}
+.nav{margin-left:auto;display:flex;gap:18px;font-size:14px}
+.nav a{color:var(--dim);text-decoration:none}
+.hero{text-align:center;padding:48px 0 12px}
+.hero h1{font-size:clamp(30px,6vw,54px);line-height:1.05;margin:.2em 0}
+.hero h1 .g{background:linear-gradient(90deg,var(--acc),var(--acc2));-webkit-background-clip:text;background-clip:text;color:transparent}
+.hero p{font-size:19px;color:var(--dim);max-width:640px;margin:12px auto 24px}
+.cta{display:inline-flex;gap:12px;flex-wrap:wrap;justify-content:center}
+.btn{display:inline-block;padding:11px 20px;border-radius:9px;font-weight:600;text-decoration:none}
+.btn.p{background:var(--acc);color:#04121a}
+.btn.s{border:1px solid var(--line);color:var(--ink)}
+.term{margin:0;border:1px solid var(--line);border-radius:12px;overflow:hidden;background:var(--panel);box-shadow:0 24px 60px -30px #000}
+.term figcaption{display:flex;align-items:center;gap:8px;padding:9px 12px;background:#11161f;border-bottom:1px solid var(--line);font-size:12px;color:var(--dim)}
+.term .d{width:11px;height:11px;border-radius:50%;display:inline-block}
+.term .d.r{background:#ff5f56}.term .d.y{background:#ffbd2e}.term .d.g{background:#27c93f}
+.term .t{margin-left:6px}
+.term pre{margin:0;padding:16px;overflow-x:auto;font:13px/1.32 ui-monospace,"SF Mono",Menlo,Consolas,monospace;color:#cdd9e5;white-space:pre}
+.heroshot{margin:26px 0 8px}
+section{padding:40px 0}
+h2{font-size:28px;text-align:center;margin:0 0 6px}
+.sub{text-align:center;color:var(--dim);margin:0 0 28px}
+.grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:18px}
+.card{background:var(--panel);border:1px solid var(--line);border-radius:12px;padding:20px}
+.card .ic{font-size:24px}
+.card h3{margin:.5em 0 .3em;font-size:17px}
+.card p{margin:0;color:var(--dim);font-size:14.5px}
+.card code,td code{background:#1b2230;padding:1px 5px;border-radius:5px;font-size:.9em;color:#b7c5d3}
+table{width:100%;border-collapse:collapse;font-size:14.5px;overflow:hidden;border-radius:12px;border:1px solid var(--line)}
+th,td{padding:11px 12px;text-align:center;border-bottom:1px solid var(--line)}
+th{background:#11161f;font-size:13px;color:var(--dim);font-weight:600}
+th:first-child,td.lbl{text-align:left}
+td.lbl{color:var(--ink)}
+th:nth-child(2){color:var(--acc)}
+td.own{background:#0f1a22}
+td.yes{color:var(--green);font-weight:700}
+td.part{color:var(--yellow)}
+td.no{color:#4b5563}
+.gallery{display:grid;grid-template-columns:1fr 1fr;gap:18px}
+.shot .term pre{font-size:11px;line-height:1.28}
+pre.code{background:var(--panel);border:1px solid var(--line);border-radius:10px;padding:16px;overflow-x:auto;font:13.5px/1.6 ui-monospace,Menlo,monospace;color:#cdd9e5}
+.callout{border:1px solid var(--line);border-left:3px solid var(--acc2);background:#0f1320;border-radius:10px;padding:16px 18px;color:var(--dim)}
+footer{text-align:center;color:var(--dim);padding:40px 0;font-size:13px;border-top:1px solid var(--line);margin-top:20px}
+@media(max-width:760px){.gallery{grid-template-columns:1fr}.nav{display:none}}
+</style>
+</head>
+<body>
+<div class=wrap>
+<header class=top>
+  <span class=logo><b>crew</b></span>
+  <nav class=nav>
+    <a href=#features>Features</a><a href=#compare>Compare</a><a href=#shots>Screens</a><a href=#install>Install</a>
+  </nav>
+</header>
+
+<section class=hero>
+  <h1>Run a <span class=g>crew of coding agents</span><br>from one terminal.</h1>
+  <p>crew launches, chats with, and manages Claude&nbsp;Code, OpenCode &amp; Cursor agents — each in its own git worktree — without leaving your terminal. Standalone Rust + ratatui.</p>
+  <div class=cta>
+    <a class="btn p" href=#install>Get started</a>
+    <a class="btn s" href=#features>See features</a>
+  </div>
+  <div class=heroshot><figure class="term"><figcaption><span class="d r"></span><span class="d y"></span><span class="d g"></span><span class="t">crew · dashboard</span></figcaption><pre> crew  nexum  tui-agent-flow ⚙ engine · 5 agents  ●2 ✓2 ✗1  $1.050  ◉ 2 marked
+╭ agents (5) ────────────────────╮╭ preview ───────────────────────────────────────────────────────╮
+│▶   ⠏ cursor     add b…$0.42 12s││add billing dashboard endpoint                                  │
+│  ◉ ⠏ claude     add a…$0.31 40s││                                                                │
+│  ◉ ✗ opencode   fix f…$0.08 2m ││status   ⠏ running                                              │
+│    ✓ claude     rewri…$0.05 10m││kind     agent                                                  │
+│    ✓ cursor     add d…$0.19 1h ││harness  cursor · sonnet                                        │
+│                                ││branch   crew/billing-api                                       │
+│                                ││remote   not pushed                                             │
+│                                ││cost     $0.420                                                 │
+│                                ││running  12s ago                                                │
+│                                ││worktree .crew/worktrees/billing-api                            │
+│                                ││                                                                │
+│                                ││[d]iff [l]og [e]dit [!]shell [P]ush [R]etry [o]wt [x]rm         │
+│                                ││                                                                │
+│                                ││                                                                │
+│                                ││                                                                │
+│                                ││                                                                │
+│                                ││                                                                │
+│                                ││                                                                │
+│                                ││                                                                │
+│                                ││                                                                │
+│                                ││                                                                │
+│                                ││                                                                │
+│                                ││                                                                │
+│                                ││                                                                │
+│                                ││                                                                │
+│                                ││                                                                │
+╰────────────────────────────────╯╰────────────────────────────────────────────────────────────────╯
+[q]uit [jk]move [n]ew [enter]chat [d]iff [l]og [e]dit [P]ush [s]top [x]rm [1-4]filter [,]settings [?</pre></figure></div>
+</section>
+
+<section id=features>
+  <h2>Everything, one keystroke away</h2>
+  <p class=sub>A master–detail dashboard that treats agents like a first-class resource.</p>
+  <div class=grid><div class="card"><div class="ic">🖥️</div><h3>Agents inside the TUI</h3><p>Every agent runs its harness REPL in a PTY rendered in an embedded pane. Select one, press enter, chat side-by-side. No tmux, no window juggling.</p></div><div class="card"><div class="ic">🌿</div><h3>Isolated worktrees</h3><p>Each agent runs in its own git worktree on a <code>crew/&lt;task&gt;</code> branch — created natively, no external tooling. Work never tangles.</p></div><div class="card"><div class="ic">🔀</div><h3>Any harness</h3><p>Claude Code, OpenCode, Cursor — launch, resume, and manage them side by side, each with its own model.</p></div><div class="card"><div class="ic">🔎</div><h3>Diff &amp; log viewers</h3><p>Review a worktree diff (colored, searchable) or tail a log that live-follows like <code>tail -f</code>. Scrollbars, <code>/</code> search, <code>n/N</code>.</p></div><div class="card"><div class="ic">🚀</div><h3>Ship from the TUI</h3><p><code>P</code> commits, pushes the branch, and opens a PR with <code>gh</code> — straight from the dashboard, lazygit-style.</p></div><div class="card"><div class="ic">✔️</div><h3>Manage the fleet</h3><p>Multi-select with <code>space</code>, bulk stop/remove, quick-filters <code>1-4</code>, sort by status/cost/recent, jump between failed with <code>]</code>/<code>[</code>.</p></div></div>
+</section>
+
+<section id=compare>
+  <h2>How it compares</h2>
+  <p class=sub>Inspired by the best terminal tools — built for agents.</p>
+  <table>
+    <thead><tr><th>Capability</th><th>crew</th><th>claude-squad</th><th>lazygit</th><th>k9s</th></tr></thead>
+    <tbody><tr><td class=lbl>Multiple agents in one view</td><td class="yes own">✓</td><td class="yes">✓</td><td class="yes">✓</td><td class="part">·</td></tr><tr><td class=lbl>Embedded chat (no tmux)</td><td class="yes own">✓</td><td class="no">—</td><td class="no">—</td><td class="no">—</td></tr><tr><td class=lbl>Per-agent git worktree</td><td class="yes own">✓</td><td class="yes">✓</td><td class="no">—</td><td class="no">—</td></tr><tr><td class=lbl>Cross-harness (Claude/Cursor/OpenCode)</td><td class="yes own">✓</td><td class="part">·</td><td class="no">—</td><td class="no">—</td></tr><tr><td class=lbl>Diff viewer</td><td class="yes own">✓</td><td class="yes">✓</td><td class="yes">✓</td><td class="part">·</td></tr><tr><td class=lbl>Live log follow</td><td class="yes own">✓</td><td class="part">·</td><td class="no">—</td><td class="yes">✓</td></tr><tr><td class=lbl>Commit · push · PR</td><td class="yes own">✓</td><td class="part">·</td><td class="yes">✓</td><td class="no">—</td></tr><tr><td class=lbl>Multi-select bulk actions</td><td class="yes own">✓</td><td class="part">·</td><td class="no">—</td><td class="yes">✓</td></tr><tr><td class=lbl>Runs standalone (no backend)</td><td class="yes own">✓</td><td class="yes">✓</td><td class="yes">✓</td><td class="yes">✓</td></tr></tbody>
+  </table>
+</section>
+
+<section id=shots>
+  <h2>Screens</h2>
+  <p class=sub>Real frames rendered by the binary.</p>
+  <div class=gallery><div class="shot"><figure class="term"><figcaption><span class="d r"></span><span class="d y"></span><span class="d g"></span><span class="t">launch — workflow picker</span></figcaption><pre> crew  nexum  tui-agent-flow ⚙ engine · 19 agents
+╭ agents (19) ───────────────────╮╭ preview ───────────────────────────────────────────────────────╮
+│▶   ▷ claude     say hello     -││say hello                                                       │
+│    ▷ claude     say hello     -││                                                                │
+│    ▷ claude     say hello     -││status   ▷ resumable                                            │
+│    ▷ claud╭ new agent ───────────────────────────────────────────────────────────────╮           │
+│    ▷ claud│  Launch an interactive agent                                             │           │
+│    ▷ claud│▶ task *  (Enter = newline)                                               │           │
+│    ▷ claud│┌────────────────────────────────────────────────────────────────────────┐│           │
+│    ▷ claud││add auth middleware                                                     ││           │
+│    ▷ claud││                                                                        ││           │
+│    ▷ claud││                                                                        ││           │
+│    ▷ claud│└────────────────────────────────────────────────────────────────────────┘│rm         │
+│    ▷ claud│  workflow   ‹ chat (single agent) ›  1/5                                 │           │
+│    ▷ claud│  harness   ‹ claude ›  1/3  ✓ installed                                  │           │
+│    ▷ claud│  model   ‹ sonnet ›  1/3                                                 │           │
+│    ▷ claud│  worktree   ‹ current repo (shared) ›  2/2                               │           │
+│    ▷ claud│  images   (none — [a] add, [d] remove)                                   │           │
+│    ▷ claud│  [tab] next field   [←→] change   [ Ctrl-S ] launch &amp; chat   [esc] cancel│           │
+│    ▷ claud│                                                                          │           │
+│    ▷ claud│                                                                          │           │
+│           │                                                                          │           │
+│           │                                                                          │           │
+│           ╰──────────────────────────────────────────────────────────────────────────╯           │
+│                                ││                                                                │
+│                                ││                                                                │
+│                                ││                                                                │
+│                                ││                                                                │
+╰────────────────────────────────╯╰────────────────────────────────────────────────────────────────╯
+[q]uit [jk]move [n]ew [enter]chat [d]iff [l]og [e]dit [P]ush [s]top [x]rm [1-4]filter [,]settings [?</pre></figure></div><div class="shot"><figure class="term"><figcaption><span class="d r"></span><span class="d y"></span><span class="d g"></span><span class="t">embedded chat</span></figcaption><pre> crew  nexum  tui-agent-flow ⚙ engine · 20 agents  ●1  CHAT  launched agent_say-hello-958286 — Ctrl-
+╭ agents (20) ───────────────────╮╭ chat · typing goes to the agent · [Ctrl-o] leave ──────────────╮
+│▶   ⠙ claude     say hel… 0s ago││█                                                               │
+│    ▷ claude     say hello     -││                                                                │
+│    ▷ claude     say hello     -││                                                                │
+│    ▷ claude     say hello     -││                                                                │
+│    ▷ claude     say hello     -││                                                                │
+│    ▷ claude     say hello     -││                                                                │
+│    ▷ claude     say hello     -││                                                                │
+│    ▷ claude     say hello     -││                                                                │
+│    ▷ claude     say hello     -││                                                                │
+│    ▷ claude     say hello     -││                                                                │
+│    ▷ claude     say hello     -││                                                                │
+│    ▷ claude     say hello     -││                                                                │
+│    ▷ claude     say hello     -││                                                                │
+│    ▷ claude     say hello     -││                                                                │
+│    ▷ claude     say hello     -││                                                                │
+│    ▷ claude     say hello     -││                                                                │
+│    ▷ claude     say hello     -││                                                                │
+│    ▷ claude     say hello     -││                                                                │
+│    ▷ claude     say hello     -││                                                                │
+│    ▷ claude     say hello     -││                                                                │
+│                                ││                                                                │
+│                                ││                                                                │
+│                                ││                                                                │
+│                                ││                                                                │
+│                                ││                                                                │
+│                                ││                                                                │
+╰────────────────────────────────╯╰────────────────────────────────────────────────────────────────╯
+CHAT — type to talk   ·   [shift-tab] cycle agent modes   ·   [Ctrl-o] back</pre></figure></div><div class="shot"><figure class="term"><figcaption><span class="d r"></span><span class="d y"></span><span class="d g"></span><span class="t">grouped help (?)</span></figcaption><pre> crew  nexum  tui-agent-flow ⚙ engine · 20 agents
+╭ agents (20) ────╭ help — [j/k] scroll · any other key closes ──────────────────╮─────────────────╮
+│▶   ▷ claude     │ Navigate                                                     │                 │
+│    ▷ claude     │  j / k · ↑ / ↓  move selection                               │                 │
+│    ▷ claude     │  g / G          jump to top / bottom                         │                 │
+│    ▷ claude     │  PgUp/Dn · ^u/^dpage / half-page the list                    │                 │
+│    ▷ claude     │  ] / [          jump to next / prev failed agent             │                 │
+│    ▷ claude     │  space / A      mark row / mark all · esc clears marks       │                 │
+│    ▷ claude     │  click / wheel  select a row · scroll                        │                 │
+│    ▷ claude     │                                                              │                 │
+│    ▷ claude     │ Launch &amp; drive                                               │                 │
+│    ▷ claude     │  n              new agent (workflow: chat / plan→build / plan│                 │
+│    ▷ claude     │  enter          chat with a live agent, or resume a ▷ one    │wt [x]rm         │
+│    ▷ claude     │  shift-tab      (in chat) cycle the agent&#x27;s modes, e.g. plan │                 │
+│    ▷ claude     │  D              duplicate into a prefilled new-agent form    │                 │
+│    ▷ claude     │  Ctrl-o         leave the terminal, back to the dashboard    │                 │
+│    ▷ claude     │                                                              │                 │
+│    ▷ claude     │ Inspect                                                      │                 │
+│    ▷ claude     │  d              review the worktree diff (colored)           │                 │
+│    ▷ claude     │  l              tail the log — live-follows at the bottom    │                 │
+│    ▷ claude     │  o / y          worktree path · yank it to the clipboard     │                 │
+│    ▷ claude     │  Y              yank the branch name                         │                 │
+│                 │  e / !          open worktree in $EDITOR · drop to a $SHELL  │                 │
+│                 │                                                              │                 │
+│                 │ Ship                                                         │                 │
+│                 │  P              commit + push (selected or all marked), open │                 │
+│                 │  O              open the branch on the remote in a browser (g│                 │
+│                 ╰──────────────────────────────────────────────────────────────╯                 │
+╰────────────────────────────────╯╰────────────────────────────────────────────────────────────────╯
+[q]uit [jk]move [n]ew [enter]chat [d]iff [l]og [e]dit [P]ush [s]top [x]rm [1-4]filter [,]settings [?</pre></figure></div></div>
+</section>
+
+<section id=install>
+  <h2>Install &amp; run</h2>
+  <p class=sub>One binary. No backend required.</p>
+  <pre class=code># build
+cd tui &amp;&amp; cargo build --release
+
+# run from anywhere inside a git repo
+./target/release/crew
+
+# …or launch headless from the shell (creates a worktree, runs the harness)
+./target/release/crew --new "add billing endpoint" --harness cursor
+
+# in the dashboard: [n] launch · [enter] chat · [P] push+PR · [?] keymap</pre>
+  <p></p>
+  <div class=callout><b>Standalone by default.</b> crew creates worktrees natively and keeps its own registry under <code>.crew/</code> — it needs only <code>git</code> and whichever agent CLI you launch. Drop in the optional nexum engine and it also surfaces observed sessions and headless delegation.</div>
+</section>
+
+<footer>
+  crew — a terminal dashboard for coding agents · Rust + <a href="https://ratatui.rs">ratatui</a>
+</footer>
+</div>
+</body>
+</html>
diff --git a/scripts/context_watch.py b/scripts/context_watch.py
index bef8ff3..36a080f 100644
--- a/scripts/context_watch.py
+++ b/scripts/context_watch.py
@@ -20,6 +20,7 @@
 
 from __future__ import annotations
 
+import hashlib
 import json
 import os
 import re
@@ -34,6 +35,7 @@
 
 import store  # noqa: E402 — must be after sys.path tweak
 import handoff  # noqa: E402 — must be after sys.path tweak
+import worktree  # noqa: E402 — must be after sys.path tweak
 
 
 # ---------------------------------------------------------------------------
@@ -139,6 +141,14 @@ def _signature(prompt: str) -> tuple[set, str | None]:
     return keywords, task_type
 
 
+def _worktree_slug(task_type: str | None, keywords: set, prompt: str) -> str:
+    """Filesystem-safe, deterministic-per-prompt worktree name."""
+    base = task_type or (sorted(keywords)[0] if keywords else "task")
+    base = re.sub(r"[^a-z0-9]+", "-", base.lower()).strip("-") or "task"
+    h = hashlib.sha1(prompt.encode("utf-8")).hexdigest()[:6]
+    return f"{base}-{h}"
+
+
 def _jaccard(a: set, b: set) -> float:
     """Jaccard similarity between two sets.  Returns 0.0 if both empty."""
     if not a and not b:
@@ -472,18 +482,42 @@ def _handle(data: dict) -> dict:
             )
 
             if should_block:
-                # Store the pending signature so "continue" can adopt it later
-                _kv_set(
-                    session_id,
-                    "pending_sig",
-                    _pack_sig(new_keywords, new_task_type),
-                )
-                reason = (
-                    f"[nexum] This looks like a new task ({old_task_type}->{new_task_type}). "
-                    "A fresh session gives cleaner, cheaper context. "
-                    "Reply 'continue' to proceed here."
+                # Divergent task. Decide: is the current context fine for it, or
+                # does the unfinished work in this tree need isolating? Only a
+                # DIRTY working tree warrants a new worktree; a clean tree means
+                # the new task can proceed in place, so we allow it silently.
+                cwd = data.get("cwd") or os.getcwd()
+                wt_path = None
+                if cfg.get("worktree_enabled", True) and worktree.is_dirty(cwd):
+                    slug = _worktree_slug(new_task_type, new_keywords, prompt_stripped)
+                    wt_path = worktree.create_worktree(
+                        cwd,
+                        slug,
+                        cfg.get("worktree_copy", []),
+                        cfg.get("worktree_ignore", []),
+                    )
+
+                if wt_path:
+                    # Store the pending signature so "continue" can adopt it later
+                    _kv_set(
+                        session_id,
+                        "pending_sig",
+                        _pack_sig(new_keywords, new_task_type),
+                    )
+                    reason = (
+                        f"[nexum] New task ({old_task_type}->{new_task_type}) with "
+                        "uncommitted work in progress. Isolated it in a worktree:\n"
+                        f"  {wt_path}\n"
+                        "Open a session there to keep this work separate, or reply "
+                        "'continue' to work here anyway."
+                    )
+                    return _block(reason)
+
+                # Clean tree (or worktrees disabled/failed): the divergent task is
+                # fine in the current context — adopt it and allow.
+                store.set_session_task(
+                    session_id, _pack_sig(new_keywords, new_task_type)
                 )
-                return _block(reason)
             else:
                 # Allowed: update the stored task signature
                 if bypass:
diff --git a/scripts/dispatch.py b/scripts/dispatch.py
new file mode 100644
index 0000000..f41c5e0
--- /dev/null
+++ b/scripts/dispatch.py
@@ -0,0 +1,264 @@
+"""dispatch.py — run one routed step in a git worktree via a chosen harness.
+
+The keystone shared by ``/nx-build --harness`` (cross-harness offload) and the
+companion TUI (managed agents). Given a single self-contained step, it:
+
+  1. ensures a git worktree to run in (reuses worktree.create_worktree),
+  2. builds an executor prompt from the step fields,
+  3. runs the step in the chosen harness headless (harness.run),
+  4. verifies the result with the existing guardrail.py (acceptance + scope),
+  5. records an agents-registry row (+ step_ledger/usage when part of a plan),
+  6. prints a verdict JSON of the same shape /nx-build already parses.
+
+Everything is fail-open: any exception prints ``{"pass": false, "error": ...}``
+and exits 0, so an orchestrator looping over steps never crashes on one bad
+dispatch.
+
+CLI:
+    python3 dispatch.py --harness claude --model sonnet --repo <root> \
+        (--worktree <path> | --new-worktree --slug <s>) --step-file <path> \
+        [--session <id>] [--plan-hash <h>] [--index <n>] [--agent-id <id>]
+
+step-file JSON:
+    {"title": str, "objective": str, "contract": str,
+     "scope_deny": [str], "acceptance": str, "files": [str]}
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import time
+import uuid
+
+# ---------------------------------------------------------------------------
+# Bootstrap: make the scripts/ directory importable regardless of cwd
+# ---------------------------------------------------------------------------
+_SCRIPTS_DIR = os.path.dirname(os.path.abspath(__file__))
+if _SCRIPTS_DIR not in sys.path:
+    sys.path.insert(0, _SCRIPTS_DIR)
+
+import store  # noqa: E402 — must be after sys.path tweak
+import worktree  # noqa: E402
+import harness  # noqa: E402
+
+
+# ---------------------------------------------------------------------------
+# Executor prompt
+# ---------------------------------------------------------------------------
+
+def _build_prompt(step: dict, worktree_path: str) -> str:
+    """Compose the executor prompt from step fields.
+
+    Mirrors the SHARED-CONTEXT + verbatim-step-fields shape used by
+    commands/nx-build.md §5 and agents/nexum-impl-sonnet.md, so a headless
+    harness gets the same instructions a Claude subagent would.
+    """
+    scope_deny = step.get("scope_deny") or []
+    files = step.get("files") or []
+    deny_line = ", ".join(scope_deny) if scope_deny else "none"
+    files_line = ", ".join(files) if files else "none"
+    return (
+        "You are a nexum executor. Implement the step below in this working "
+        f"directory ({worktree_path}). Touch ONLY the listed files; never touch "
+        "any path in the scope deny-list. Make the acceptance command pass.\n\n"
+        f"### {step.get('title', 'step')}\n"
+        f"- files: {files_line}\n"
+        f"- objective: {step.get('objective', '')}\n"
+        f"- contract: {step.get('contract', '')}\n"
+        f"- scope: do NOT touch {deny_line}\n"
+        f"- acceptance: {step.get('acceptance', '')}\n"
+    )
+
+
+# ---------------------------------------------------------------------------
+# git helpers (in the worktree)
+# ---------------------------------------------------------------------------
+
+def _git(cwd: str, *args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        ["git", "-C", cwd, *args],
+        capture_output=True, text=True, timeout=30,
+    )
+
+
+def _changed_files(worktree_path: str) -> list[str]:
+    """Tracked-modified + untracked files in the worktree (relative paths)."""
+    out: list[str] = []
+    try:
+        r = _git(worktree_path, "diff", "--name-only")
+        if r.returncode == 0:
+            out.extend(f for f in r.stdout.splitlines() if f.strip())
+        r = _git(worktree_path, "ls-files", "--others", "--exclude-standard")
+        if r.returncode == 0:
+            out.extend(f for f in r.stdout.splitlines() if f.strip())
+    except Exception:
+        pass
+    return out
+
+
+def _diff(worktree_path: str) -> str:
+    try:
+        r = _git(worktree_path, "diff")
+        return r.stdout if r.returncode == 0 else ""
+    except Exception:
+        return ""
+
+
+# ---------------------------------------------------------------------------
+# guardrail
+# ---------------------------------------------------------------------------
+
+def _run_guardrail(worktree_path: str, acceptance: str, scope_deny: list[str],
+                   changed: list[str]) -> dict:
+    """Invoke guardrail.py in the worktree; return its parsed JSON.
+
+    guardrail runs the acceptance command with cwd = worktree so relative
+    acceptance commands (e.g. `test -f fake_out.txt`) resolve against the
+    checkout the harness just edited.
+    """
+    argv = [
+        sys.executable, os.path.join(_SCRIPTS_DIR, "guardrail.py"),
+        "--acceptance", acceptance or "",
+        "--scope-root", worktree_path,
+        "--changed", ",".join(changed),
+    ]
+    for deny in scope_deny:
+        argv += ["--deny-path", deny]
+    try:
+        r = subprocess.run(argv, capture_output=True, text=True, timeout=180,
+                           cwd=worktree_path)
+        return json.loads(r.stdout)
+    except Exception as exc:
+        return {"pass": False, "acceptance_rc": -1, "scope_violations": [],
+                "log": f"[dispatch] guardrail invocation failed: {exc}"}
+
+
+# ---------------------------------------------------------------------------
+# main
+# ---------------------------------------------------------------------------
+
+def _handle(args) -> dict:
+    agent_id = args.agent_id or uuid.uuid4().hex
+    # realpath (not just abspath) so the stored repo_root matches what
+    # `git rev-parse --show-toplevel` returns — on macOS /var is a symlink to
+    # /private/var, and an unresolved abspath would fail the TUI's repo filter.
+    repo = os.path.realpath(args.repo)
+
+    # ---- 1. step file ----
+    with open(args.step_file, "r", encoding="utf-8") as fh:
+        step = json.load(fh)
+
+    # ---- 2. worktree ----
+    branch = None
+    if args.new_worktree:
+        cfg = store.get_config()
+        worktree_path = worktree.create_worktree(
+            repo, args.slug,
+            cfg.get("worktree_copy", []),
+            cfg.get("worktree_ignore", []),
+        )
+        if not worktree_path:
+            return {"pass": False, "error": "worktree creation failed",
+                    "agent_id": agent_id}
+        branch = f"nexum/{args.slug}"
+    else:
+        worktree_path = args.worktree
+        if not worktree_path or not os.path.isdir(worktree_path):
+            return {"pass": False, "error": "worktree path missing or not a dir",
+                    "agent_id": agent_id}
+
+    # ---- 3. log path ----
+    log_dir = os.path.join(repo, ".nexum-data", "agents")
+    os.makedirs(log_dir, exist_ok=True)
+    log_path = os.path.join(log_dir, f"{agent_id}.log")
+
+    # ---- 4. register (running) ----
+    # Record our own PID while the harness runs so `agent-list --active` (a live
+    # os.kill(pid,0) probe) can distinguish a currently-executing agent from a
+    # finished one. dispatch is synchronous, so when this process exits the pid
+    # stops being alive and the row drops out of the active set on its own.
+    store.record_agent(
+        agent_id, harness=args.harness, model=args.model, repo_root=repo,
+        worktree=worktree_path, branch=branch, log_path=log_path,
+        task=step.get("title", ""), plan_hash=args.plan_hash,
+        step_index=args.index, status="running", session_id=args.session,
+        pid=os.getpid(), started_ts=time.time(),
+    )
+
+    # ---- 5-6. build prompt + run harness ----
+    prompt = _build_prompt(step, worktree_path)
+    hres = harness.run(args.harness, args.model, prompt, worktree_path, log_path)
+
+    # ---- 7-9. verify + diff ----
+    changed = _changed_files(worktree_path)
+    guard = _run_guardrail(worktree_path, step.get("acceptance", ""),
+                           step.get("scope_deny") or [], changed)
+    diff = _diff(worktree_path)
+    passed = bool(guard.get("pass"))
+
+    # ---- 10. verdict ----
+    verdict = {
+        "pass": passed,
+        "harness": args.harness,
+        "model": args.model,
+        "tokens": hres.get("tokens", 0),
+        "cost_usd": hres.get("cost_usd", 0.0),
+        "acceptance_rc": guard.get("acceptance_rc"),
+        "scope_violations": guard.get("scope_violations", []),
+        "diff": diff,
+        "log": guard.get("log", ""),
+        "agent_id": agent_id,
+        "worktree": worktree_path,
+    }
+
+    # ---- 11. persist ----
+    store.record_agent(agent_id, status=("done" if passed else "failed"),
+                       cost_usd=hres.get("cost_usd", 0.0))
+    if args.plan_hash and args.index is not None:
+        store.record_step(
+            args.session or "_nosession", args.plan_hash, args.index,
+            status=("done" if passed else "failed"),
+            title=step.get("title"), route="", tier_used=args.harness,
+            last_diff=(None if passed else diff),
+            verdict=json.dumps(verdict, sort_keys=True), attempts=1,
+        )
+    store.add_usage(args.session or "_nosession", args.model,
+                    input_tok=0, output_tok=hres.get("tokens", 0))
+
+    return verdict
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(prog="dispatch.py",
+                                description="Run one routed step in a worktree via a harness.")
+    p.add_argument("--harness", required=True, choices=["claude", "opencode", "cursor"])
+    p.add_argument("--model", required=True)
+    p.add_argument("--repo", required=True)
+    p.add_argument("--worktree")
+    p.add_argument("--new-worktree", action="store_true")
+    p.add_argument("--slug")
+    p.add_argument("--step-file", required=True)
+    p.add_argument("--session")
+    p.add_argument("--plan-hash")
+    p.add_argument("--index", type=int)
+    p.add_argument("--agent-id")
+    args = p.parse_args()
+
+    if args.new_worktree and not args.slug:
+        print(json.dumps({"pass": False, "error": "--new-worktree requires --slug"}))
+        sys.exit(0)
+
+    try:
+        result = _handle(args)
+    except Exception as exc:
+        result = {"pass": False, "error": str(exc)}
+    print(json.dumps(result, sort_keys=True))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/harness.py b/scripts/harness.py
new file mode 100644
index 0000000..622a097
--- /dev/null
+++ b/scripts/harness.py
@@ -0,0 +1,217 @@
+"""harness.py — headless-CLI adapters for claude / opencode / cursor.
+
+Thin, fail-open layer that knows how to:
+- build the argv for a headless agent CLI invocation (``build_command``)
+- best-effort parse a stream of JSON-lines output into a small summary dict
+  (``parse_stream``)
+- spawn the process, stream its combined stdout+stderr to a log file, and
+  return the parsed result (``run``)
+
+No worktree/guardrail/dispatch logic lives here — this module only knows how
+to talk to the three headless CLIs. A later module composes this with
+worktree.py and guardrail.py to actually execute a step.
+
+Fail-open: ``run`` never raises. A missing binary (OSError) or a timeout
+(subprocess.TimeoutExpired) is reported as ``{"ok": False, "status": "error", ...}``
+so a caller looping over agents never crashes on one bad process.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import subprocess
+from typing import Any, Dict, Iterable, List
+
+# ---------------------------------------------------------------------------
+# build_command
+# ---------------------------------------------------------------------------
+
+_KNOWN_HARNESSES = ("claude", "opencode", "cursor")
+
+
+def build_command(harness: str, model: str, prompt: str, cwd: str) -> List[str]:
+    """Return the argv to invoke *harness* headlessly with *model* and *prompt*.
+
+    ``cwd`` is accepted for signature symmetry with ``run`` (some harnesses'
+    argv doesn't need it — it's passed as the subprocess working directory
+    instead) but is not currently baked into the argv itself.
+
+    If env var ``NEXUM_HARNESS_CMD_<HARNESS>`` (harness name upper-cased) is
+    set, it is shlex-split as the base argv and *prompt* is appended as the
+    final argument — this lets tests (and users) override the binary/args
+    without touching this module.
+
+    Raises ValueError for an unrecognized harness name.
+    """
+    override = os.environ.get(f"NEXUM_HARNESS_CMD_{harness.upper()}", "").strip()
+    if override:
+        return shlex.split(override) + [prompt]
+
+    if harness == "claude":
+        return ["claude", "-p", prompt, "--output-format", "stream-json", "--model", model]
+    if harness == "opencode":
+        return ["opencode", "run", prompt, "--model", model, "--format", "json"]
+    if harness == "cursor":
+        return ["cursor-agent", "-p", prompt, "--output-format", "stream-json", "--model", model]
+
+    raise ValueError(f"unknown harness: {harness!r} (expected one of {_KNOWN_HARNESSES})")
+
+
+# ---------------------------------------------------------------------------
+# parse_stream
+# ---------------------------------------------------------------------------
+
+def parse_stream(harness: str, lines: Iterable[str]) -> Dict[str, Any]:
+    """Best-effort parse a stream of JSON-lines into a summary dict.
+
+    Returns ``{"status": "done"|"error"|"running", "final_text": str,
+    "tokens": int, "cost_usd": float}``. Non-JSON / unrecognized lines are
+    ignored. Missing fields default (tokens 0, cost_usd 0.0, final_text "").
+    A line whose parsed ``type`` is ``"result"`` sets status to ``"done"`` and
+    pulls tokens/cost from it when present.
+    """
+    status = "running"
+    final_text = ""
+    tokens = 0
+    cost_usd = 0.0
+
+    for line in lines:
+        line = (line or "").strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except (ValueError, TypeError):
+            continue
+        if not isinstance(obj, dict):
+            continue
+
+        obj_type = obj.get("type")
+        if obj_type == "result":
+            status = "error" if obj.get("is_error") else "done"
+            if "tokens" in obj:
+                try:
+                    tokens = int(obj.get("tokens") or 0)
+                except (TypeError, ValueError):
+                    pass
+            if "cost_usd" in obj:
+                try:
+                    cost_usd = float(obj.get("cost_usd") or 0.0)
+                except (TypeError, ValueError):
+                    pass
+            text = obj.get("final_text") or obj.get("result") or obj.get("text")
+            if isinstance(text, str) and text:
+                final_text = text
+        elif obj_type == "error":
+            status = "error"
+
+    return {
+        "status": status,
+        "final_text": final_text,
+        "tokens": tokens,
+        "cost_usd": cost_usd,
+    }
+
+
+# ---------------------------------------------------------------------------
+# run
+# ---------------------------------------------------------------------------
+
+def run(
+    harness: str,
+    model: str,
+    prompt: str,
+    cwd: str,
+    log_path: str,
+    timeout: int = 1800,
+) -> Dict[str, Any]:
+    """Spawn the headless agent CLI, stream output to *log_path*, return a
+    result dict.
+
+    Combines stdout+stderr, appends each line to *log_path* as it arrives (the
+    log file is opened in append mode so multiple runs sharing a log don't
+    clobber each other), and returns
+    ``{**parse_stream(...), "ok": bool, "rc": int, "log_path": log_path}``.
+    ``ok`` is True iff the process exit code is 0.
+
+    Fail-open: if the binary is missing (OSError) or the process exceeds
+    *timeout* (subprocess.TimeoutExpired), returns
+    ``{"ok": False, "status": "error", "final_text": "", "tokens": 0,
+    "cost_usd": 0.0, "rc": -1, "log_path": log_path}`` — never raises.
+    """
+    try:
+        argv = build_command(harness, model, prompt, cwd)
+    except ValueError:
+        return {
+            "ok": False,
+            "status": "error",
+            "final_text": "",
+            "tokens": 0,
+            "cost_usd": 0.0,
+            "rc": -1,
+            "log_path": log_path,
+        }
+
+    try:
+        proc = subprocess.run(
+            argv,
+            cwd=cwd or None,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return {
+            "ok": False,
+            "status": "error",
+            "final_text": "",
+            "tokens": 0,
+            "cost_usd": 0.0,
+            "rc": -1,
+            "log_path": log_path,
+        }
+
+    combined = (proc.stdout or "") + (proc.stderr or "")
+    lines = combined.splitlines()
+
+    try:
+        with open(log_path, "a", encoding="utf-8") as fh:
+            for line in lines:
+                fh.write(line + "\n")
+    except OSError:
+        pass  # logging is best-effort; never fail the run over it
+
+    result = parse_stream(harness, lines)
+    result["ok"] = proc.returncode == 0
+    result["rc"] = proc.returncode
+    result["log_path"] = log_path
+    return result
+
+
+# ---------------------------------------------------------------------------
+# self-check
+# ---------------------------------------------------------------------------
+
+def _demo() -> None:
+    """Self-check: build_command shapes, parse_stream, and a fail-open run
+    against a nonexistent binary. Run: python3 scripts/harness.py"""
+    cmd = build_command("claude", "sonnet", "hello", "/tmp")
+    assert cmd == ["claude", "-p", "hello", "--output-format", "stream-json", "--model", "sonnet"], cmd
+
+    parsed = parse_stream("claude", ['{"type":"result","tokens":5,"cost_usd":0.0}'])
+    assert parsed["status"] == "done" and parsed["tokens"] == 5, parsed
+
+    os.environ["NEXUM_HARNESS_CMD_CLAUDE"] = "/nonexistent/nexum-demo-binary --flag"
+    try:
+        result = run("claude", "sonnet", "hi", "/tmp", "/tmp/nexum-harness-demo.log")
+        assert result["ok"] is False and result["status"] == "error", result
+    finally:
+        os.environ.pop("NEXUM_HARNESS_CMD_CLAUDE", None)
+
+    print("harness demo OK")
+
+
+if __name__ == "__main__":
+    _demo()
diff --git a/scripts/mcp_server.py b/scripts/mcp_server.py
new file mode 100644
index 0000000..8acf954
--- /dev/null
+++ b/scripts/mcp_server.py
@@ -0,0 +1,464 @@
+"""mcp_server.py — an MCP (stdio) server that lets one agent delegate work to
+another harness as a managed sub-agent.
+
+Claude (or any MCP client) calls the ``delegate`` tool with a task and a target
+harness (``cursor`` / ``opencode`` / ``claude``). The server runs the existing
+``dispatch.py`` — which creates a git worktree, runs that harness headless,
+verifies with guardrail.py, and records an ``agents`` row — then returns the
+verdict (pass, diff, cost, log tail). Because dispatch records the agent row,
+the delegated sub-agent shows up **live in the nexum TUI** while it runs.
+
+It's synchronous: one ``delegate`` call blocks until the sub-agent finishes and
+returns its verdict. A client that wants several at once just emits several
+tool calls in one turn (they run concurrently in the client). ``list_agents``
+returns the current managed agents for the repo (the TUI's data), so the caller
+can see siblings it (or the user) launched.
+
+Transport: newline-delimited JSON-RPC 2.0 over stdin/stdout (MCP stdio). No
+third-party deps — stdlib only, matching the rest of scripts/. Fail-open: a bad
+request yields a JSON-RPC error, never a crash.
+
+Register in a repo's .mcp.json:
+    {"mcpServers": {"nexum-delegate": {
+        "command": "python3", "args": ["scripts/mcp_server.py"]}}}
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import time
+import uuid
+
+_SCRIPTS_DIR = os.path.dirname(os.path.abspath(__file__))
+_DISPATCH = os.path.join(_SCRIPTS_DIR, "dispatch.py")
+_STORE = os.path.join(_SCRIPTS_DIR, "store.py")
+
+_HARNESSES = ("claude", "opencode", "cursor")
+# Default model per harness when the caller doesn't pick one (mirrors the TUI).
+_DEFAULT_MODEL = {
+    "claude": "sonnet",
+    "opencode": "anthropic/claude-sonnet-4-6",
+    "cursor": "auto",
+}
+# Cap the diff we hand back so a huge change can't blow the caller's context.
+_DIFF_CAP = 6000
+
+PROTOCOL_VERSION = "2024-11-05"
+
+
+# ---------------------------------------------------------------------------
+# helpers
+# ---------------------------------------------------------------------------
+
+def _repo_root() -> str:
+    """git toplevel of the server's cwd (the project MCP was launched from)."""
+    try:
+        r = subprocess.run(["git", "rev-parse", "--show-toplevel"],
+                           capture_output=True, text=True, timeout=10)
+        if r.returncode == 0 and r.stdout.strip():
+            return os.path.realpath(r.stdout.strip())
+    except Exception:
+        pass
+    return os.path.realpath(os.getcwd())
+
+
+def _slug(task: str) -> str:
+    base = "".join(c.lower() if c.isalnum() else "-" for c in task)
+    base = "-".join(p for p in base.split("-") if p)[:20]
+    ts = int(time.time() * 1000) % 1_000_000
+    return f"{base}-{ts}" if base else f"delegate-{ts}"
+
+
+def _build_step(args: dict) -> dict:
+    task = (args.get("task") or "").strip()
+    return {
+        "title": task[:80],
+        "objective": task,
+        "contract": "",
+        "scope_deny": [],
+        "acceptance": args.get("acceptance") or "",
+        "files": args.get("files") or [],
+    }
+
+
+def _validate(args: dict):
+    """Return (harness, task, model) or an error string."""
+    harness = args.get("harness")
+    task = (args.get("task") or "").strip()
+    if harness not in _HARNESSES:
+        return f"error: harness must be one of {', '.join(_HARNESSES)}"
+    if not task:
+        return "error: task is required"
+    return harness, task, (args.get("model") or _DEFAULT_MODEL[harness])
+
+
+def _git_diff(worktree: str) -> str:
+    """Best-effort `git diff` of a worktree, capped, for reporting a verdict."""
+    if not worktree or not os.path.isdir(worktree):
+        return ""
+    try:
+        r = subprocess.run(["git", "-C", worktree, "diff"],
+                           capture_output=True, text=True, timeout=30)
+        diff = r.stdout if r.returncode == 0 else ""
+    except Exception:
+        return ""
+    if len(diff) > _DIFF_CAP:
+        diff = diff[:_DIFF_CAP] + f"\n… [diff truncated at {_DIFF_CAP} chars]"
+    return diff
+
+
+# ---------------------------------------------------------------------------
+# tools
+# ---------------------------------------------------------------------------
+
+TOOLS = [
+    {
+        "name": "delegate",
+        "description": (
+            "Delegate a self-contained task to another coding-agent harness "
+            "(cursor / opencode / claude) as a managed sub-agent. Runs it "
+            "headless in an isolated git worktree, verifies with the acceptance "
+            "command if given, and returns the verdict (pass, diff, cost). The "
+            "sub-agent appears live in the nexum TUI while it runs. Blocks until "
+            "it finishes. Give ONE bounded task with all context inline — the "
+            "sub-agent shares none of your conversation."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "harness": {"type": "string", "enum": list(_HARNESSES),
+                            "description": "Target harness to run the task."},
+                "task": {"type": "string",
+                         "description": "Full self-contained task/objective."},
+                "model": {"type": "string",
+                          "description": "Model override; omit for the harness default."},
+                "acceptance": {"type": "string",
+                               "description": "Shell command that must exit 0 for the "
+                               "delegation to count as passed (run in the worktree). "
+                               "Omit for no verification."},
+                "files": {"type": "array", "items": {"type": "string"},
+                          "description": "Files the sub-agent is expected to touch (scope hint)."},
+            },
+            "required": ["harness", "task"],
+        },
+    },
+    {
+        "name": "delegate_async",
+        "description": (
+            "Like delegate, but returns immediately with an agent_id instead of "
+            "waiting. Use to fan out several sub-agents in parallel without "
+            "holding this turn open — then poll each with `check`. The sub-agent "
+            "runs in the background and shows live in the nexum TUI."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "harness": {"type": "string", "enum": list(_HARNESSES)},
+                "task": {"type": "string"},
+                "model": {"type": "string"},
+                "acceptance": {"type": "string"},
+                "files": {"type": "array", "items": {"type": "string"}},
+            },
+            "required": ["harness", "task"],
+        },
+    },
+    {
+        "name": "check",
+        "description": (
+            "Check a delegated (async) sub-agent by agent_id: status "
+            "(running/done/failed), cost, worktree, and — once finished — its "
+            "diff. Poll this after delegate_async."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {"agent_id": {"type": "string"}},
+            "required": ["agent_id"],
+        },
+    },
+    {
+        "name": "list_agents",
+        "description": (
+            "List managed sub-agents for this repo (the nexum TUI's data): id, "
+            "harness, model, status, task, cost. Use to see what you or the user "
+            "have delegated."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "active_only": {"type": "boolean",
+                                "description": "Only agents whose process is still alive."},
+            },
+        },
+    },
+]
+
+
+def _tool_delegate(args: dict) -> str:
+    v = _validate(args)
+    if isinstance(v, str):
+        return v
+    harness, task, model = v
+
+    step = _build_step(args)
+    repo = _repo_root()
+    fd, step_path = tempfile.mkstemp(prefix="nexum-step-", suffix=".json")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(step, fh)
+        argv = [
+            sys.executable, _DISPATCH,
+            "--harness", harness, "--model", model, "--repo", repo,
+            "--new-worktree", "--slug", _slug(task),
+            "--step-file", step_path,
+        ]
+        try:
+            proc = subprocess.run(argv, capture_output=True, text=True, timeout=2000)
+        except subprocess.TimeoutExpired:
+            return "error: delegation timed out (>2000s)"
+        verdict = _parse_last_json(proc.stdout)
+        if verdict is None:
+            return f"error: dispatch produced no verdict.\nstderr: {proc.stderr[:1000]}"
+    finally:
+        try:
+            os.unlink(step_path)
+        except OSError:
+            pass
+
+    diff = verdict.get("diff") or ""
+    if len(diff) > _DIFF_CAP:
+        diff = diff[:_DIFF_CAP] + f"\n… [diff truncated at {_DIFF_CAP} chars]"
+    summary = {
+        "pass": verdict.get("pass"),
+        "harness": verdict.get("harness"),
+        "model": verdict.get("model"),
+        "agent_id": verdict.get("agent_id"),
+        "worktree": verdict.get("worktree"),
+        "cost_usd": verdict.get("cost_usd"),
+        "acceptance_rc": verdict.get("acceptance_rc"),
+        "scope_violations": verdict.get("scope_violations"),
+        "diff": diff,
+        "log_tail": (verdict.get("log") or "")[-1200:],
+    }
+    return json.dumps(summary, indent=2)
+
+
+def _tool_delegate_async(args: dict) -> str:
+    """Kick off a delegation without waiting. Returns an agent_id to poll with
+    `check`. Lets one orchestrator fan out several sub-agents in parallel."""
+    v = _validate(args)
+    if isinstance(v, str):
+        return v
+    harness, task, model = v
+
+    repo = _repo_root()
+    agent_id = uuid.uuid4().hex
+    # Persist the step file where the detached process can read it after we
+    # return (a small leak by design — kept as a record of what was dispatched).
+    steps_dir = os.path.join(repo, ".nexum-data", "steps")
+    os.makedirs(steps_dir, exist_ok=True)
+    step_path = os.path.join(steps_dir, f"{agent_id}.json")
+    with open(step_path, "w", encoding="utf-8") as fh:
+        json.dump(_build_step(args), fh)
+
+    argv = [
+        sys.executable, _DISPATCH,
+        "--harness", harness, "--model", model, "--repo", repo,
+        "--new-worktree", "--slug", _slug(task),
+        "--step-file", step_path, "--agent-id", agent_id,
+    ]
+    try:
+        subprocess.Popen(argv, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                        start_new_session=True)  # detach: survives this call
+    except Exception as exc:
+        return f"error: could not launch delegation: {exc}"
+    return json.dumps({
+        "agent_id": agent_id, "harness": harness, "model": model,
+        "status": "running",
+        "note": "dispatched — poll with check(agent_id) for status/diff.",
+    }, indent=2)
+
+
+def _tool_check(args: dict) -> str:
+    """Report the current state of a delegated agent (from the store), with its
+    diff once it has finished."""
+    agent_id = (args.get("agent_id") or "").strip()
+    if not agent_id:
+        return "error: agent_id is required"
+    try:
+        r = subprocess.run([sys.executable, _STORE, "agent-get", "--id", agent_id],
+                           capture_output=True, text=True, timeout=30)
+        row = json.loads(r.stdout or "null")
+    except Exception as exc:
+        return f"error: could not read agent: {exc}"
+    if not row:
+        return json.dumps({"agent_id": agent_id, "status": "unknown",
+                           "note": "no such agent (not dispatched, or pruned)."})
+    status = row.get("status")
+    out = {
+        "agent_id": agent_id,
+        "status": status,
+        "harness": row.get("harness"),
+        "model": row.get("model"),
+        "cost_usd": row.get("cost_usd"),
+        "worktree": row.get("worktree"),
+        "branch": row.get("branch"),
+        "done": status in ("done", "failed"),
+        "pass": status == "done" if status in ("done", "failed") else None,
+    }
+    if out["done"]:
+        out["diff"] = _git_diff(row.get("worktree") or "")
+    return json.dumps(out, indent=2)
+
+
+def _tool_list_agents(args: dict) -> str:
+    argv = [sys.executable, _STORE, "agent-list", "--repo", _repo_root(), "--json"]
+    if args.get("active_only"):
+        argv.append("--active")
+    try:
+        r = subprocess.run(argv, capture_output=True, text=True, timeout=30)
+        rows = json.loads(r.stdout or "[]")
+    except Exception as exc:
+        return f"error: could not list agents: {exc}"
+    slim = [{
+        "id": a.get("agent_id"),
+        "harness": a.get("harness"),
+        "model": a.get("model"),
+        "status": a.get("status"),
+        "task": a.get("task"),
+        "cost_usd": a.get("cost_usd"),
+        "branch": a.get("branch"),
+        "worktree": a.get("worktree"),
+    } for a in rows]
+    return json.dumps(slim, indent=2)
+
+
+def _parse_last_json(text: str):
+    """dispatch prints one verdict JSON line; return the last parseable object."""
+    for line in reversed((text or "").splitlines()):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+            if isinstance(obj, dict):
+                return obj
+        except ValueError:
+            continue
+    return None
+
+
+_DISPATCH_TOOLS = {
+    "delegate": _tool_delegate,
+    "delegate_async": _tool_delegate_async,
+    "check": _tool_check,
+    "list_agents": _tool_list_agents,
+}
+
+
+# ---------------------------------------------------------------------------
+# JSON-RPC / MCP dispatch
+# ---------------------------------------------------------------------------
+
+def handle_message(msg: dict):
+    """Handle one JSON-RPC request; return a reply dict, or None for a
+    notification (no reply). Pure — no I/O — so it's unit-testable."""
+    method = msg.get("method")
+    mid = msg.get("id")
+
+    # notifications (no id / notifications/*): never reply
+    if method and method.startswith("notifications/"):
+        return None
+
+    if method == "initialize":
+        params = msg.get("params") or {}
+        return _ok(mid, {
+            "protocolVersion": params.get("protocolVersion") or PROTOCOL_VERSION,
+            "capabilities": {"tools": {}},
+            "serverInfo": {"name": "nexum-delegate", "version": "0.1.0"},
+        })
+
+    if method == "tools/list":
+        return _ok(mid, {"tools": TOOLS})
+
+    if method == "tools/call":
+        params = msg.get("params") or {}
+        name = params.get("name")
+        fn = _DISPATCH_TOOLS.get(name)
+        if fn is None:
+            return _err(mid, -32602, f"unknown tool: {name}")
+        try:
+            text = fn(params.get("arguments") or {})
+        except Exception as exc:  # fail-open: report as tool error, not a crash
+            return _ok(mid, {"content": [{"type": "text", "text": f"error: {exc}"}],
+                            "isError": True})
+        return _ok(mid, {"content": [{"type": "text", "text": text}]})
+
+    if mid is None:
+        return None  # unknown notification
+    return _err(mid, -32601, f"method not found: {method}")
+
+
+def _ok(mid, result):
+    return {"jsonrpc": "2.0", "id": mid, "result": result}
+
+
+def _err(mid, code, message):
+    return {"jsonrpc": "2.0", "id": mid, "error": {"code": code, "message": message}}
+
+
+def serve() -> None:
+    """Read newline-delimited JSON-RPC from stdin, write replies to stdout."""
+    out = sys.stdout
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            msg = json.loads(line)
+        except ValueError:
+            continue
+        reply = handle_message(msg)
+        if reply is not None:
+            out.write(json.dumps(reply) + "\n")
+            out.flush()
+
+
+# ---------------------------------------------------------------------------
+# self-check
+# ---------------------------------------------------------------------------
+
+def _demo() -> None:
+    """Run: python3 scripts/mcp_server.py --selftest"""
+    init = handle_message({"jsonrpc": "2.0", "id": 1, "method": "initialize",
+                           "params": {"protocolVersion": "2024-11-05"}})
+    assert init["result"]["serverInfo"]["name"] == "nexum-delegate", init
+
+    assert handle_message({"jsonrpc": "2.0", "method": "notifications/initialized"}) is None
+
+    lst = handle_message({"jsonrpc": "2.0", "id": 2, "method": "tools/list"})
+    names = {t["name"] for t in lst["result"]["tools"]}
+    assert names == {"delegate", "delegate_async", "check", "list_agents"}, names
+
+    bad = handle_message({"jsonrpc": "2.0", "id": 3, "method": "tools/call",
+                          "params": {"name": "nope", "arguments": {}}})
+    assert "error" in bad, bad
+
+    # delegate validates args before running anything
+    r = handle_message({"jsonrpc": "2.0", "id": 4, "method": "tools/call",
+                        "params": {"name": "delegate",
+                                   "arguments": {"harness": "bogus", "task": "x"}}})
+    assert "harness must be one of" in r["result"]["content"][0]["text"], r
+
+    assert _parse_last_json('noise\n{"pass": true}\n') == {"pass": True}
+    print("mcp_server demo OK")
+
+
+if __name__ == "__main__":
+    if "--selftest" in sys.argv:
+        _demo()
+    else:
+        serve()
diff --git a/scripts/session_reset.py b/scripts/session_reset.py
index 0edf98e..eec35a8 100644
--- a/scripts/session_reset.py
+++ b/scripts/session_reset.py
@@ -2,7 +2,7 @@
 """
 session_reset.py — Nexum SessionStart housekeeping hook.
 
-Two jobs on session start:
+Three jobs on session start:
 
 1. Invalidate predup state on a context reset. When `source` is `clear` (the
    user ran /clear) or `compact` (the session resumed after a compaction), the
@@ -11,6 +11,9 @@
    `resume`, where prior context is still present.
 2. Throttled retention prune (`store.maybe_prune`, at most once/day) so the
    SQLite file and predup lookups stay bounded across many sessions.
+3. Capture the git toplevel of the session's cwd into session_kv under the
+   "repo_root" flag, so store.session_rows()/agent_rows() can filter sessions
+   and agents to one repo. Falls back to the raw cwd when not a git repo.
 
 Filtering is done in-script on the `source` field rather than via a hook
 matcher, so behaviour is identical regardless of SessionStart matcher support.
@@ -23,6 +26,7 @@
 
 import json
 import os
+import subprocess
 import sys
 
 _SCRIPTS_DIR = os.path.dirname(os.path.abspath(__file__))
@@ -34,6 +38,23 @@
 _RESET_SOURCES = {"clear", "compact"}
 
 
+def _git_toplevel(cwd: str) -> str:
+    """Resolve the git toplevel of *cwd* (mirrors store.project_data_dir's
+    subprocess pattern). Falls back to *cwd* itself on any error/non-repo."""
+    try:
+        result = subprocess.run(
+            ["git", "-C", cwd, "rev-parse", "--show-toplevel"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return result.stdout.strip()
+    except Exception:
+        pass
+    return cwd
+
+
 def main() -> None:
     try:
         try:
@@ -62,6 +83,15 @@ def main() -> None:
         except Exception:
             pass
 
+        # Tag this session with its repo toplevel so agent/session queries can
+        # filter by repo. Fail-open: never blocks session start.
+        try:
+            cwd = data.get("cwd") or os.getcwd()
+            repo_root = _git_toplevel(cwd)
+            store.set_flag(session_id, "repo_root", repo_root)
+        except Exception:
+            pass
+
     except Exception:
         pass
     print("{}")
diff --git a/scripts/store.py b/scripts/store.py
index e472b92..28b17a5 100644
--- a/scripts/store.py
+++ b/scripts/store.py
@@ -85,6 +85,22 @@ def get_pricing(cfg: Optional[dict] = None) -> Dict[str, tuple]:
     ],
     "intent_guard_enabled": True,
     "intent_similarity_threshold": 0.25,
+    # Divergent-task worktrees: when the intent-guard detects a task switch AND
+    # the working tree has uncommitted changes, nexum creates an isolated git
+    # worktree under .nexum-data/worktrees/<slug> (branch nexum/<slug>) so the
+    # new task doesn't tangle with the unfinished work, and blocks the prompt
+    # with a pointer to it ('continue' still works to stay put). A CLEAN tree
+    # needs no worktree — the divergent task is simply allowed in place. Set
+    # False to disable worktree creation (the guard then always allows on a
+    # clean tree and, on a dirty tree, just blocks with a heads-up).
+    "worktree_enabled": True,
+    # Untracked files (globs, relative to repo root) to COPY into a freshly
+    # created worktree — git only checks out tracked files, so env/local config
+    # the new work needs must be copied explicitly, e.g. [".env", "*.local.*"].
+    "worktree_copy": [],
+    # Globs (relative to repo root) to EXCLUDE from the copy above even when a
+    # worktree_copy pattern would have matched them.
+    "worktree_ignore": [],
     # Read-guard: cap Read of very large text files via PreToolUse updatedInput
     # (inject a line `limit`). PostToolUse output shrink cannot help here —
     # `updatedToolOutput` is ignored for built-in tools on current Claude Code —
@@ -361,6 +377,32 @@ def get_pricing(cfg: Optional[dict] = None) -> Dict[str, tuple]:
         PRIMARY KEY(session_id, file_path)
     )
     """,
+    # Agents registry — durable state for headless-CLI agents dispatched by
+    # /nx-build (claude / opencode / cursor). Keyed by agent_id (caller-chosen,
+    # e.g. a uuid or "<session>-<step_index>"). Intentionally NOT in
+    # _PRUNE_TABLES: an active agent row must survive the retention sweep, and
+    # a finished one is small and useful for post-hoc cost/status queries.
+    """
+    CREATE TABLE IF NOT EXISTS agents(
+        agent_id    TEXT PRIMARY KEY,
+        harness     TEXT,
+        model       TEXT,
+        repo_root   TEXT,
+        worktree    TEXT,
+        branch      TEXT,
+        pid         INTEGER,
+        log_path    TEXT,
+        task        TEXT,
+        plan_hash   TEXT,
+        step_index  INTEGER,
+        status      TEXT,
+        cost_usd    REAL,
+        session_id  TEXT,
+        tmux        TEXT,
+        started_ts  REAL,
+        updated_ts  REAL
+    )
+    """,
 ]
 
 # Column migrations for databases created by an earlier schema version.
@@ -368,6 +410,8 @@ def get_pricing(cfg: Optional[dict] = None) -> Dict[str, tuple]:
 # already exists (or any other error) never breaks db().
 _MIGRATIONS = [
     ("savings", "effective_tok", "INTEGER"),
+    ("agents", "session_id", "TEXT"),
+    ("agents", "tmux", "TEXT"),
 ]
 
 
@@ -1558,6 +1602,207 @@ def clear_step_ledger(session_id: str, plan_hash: Optional[str] = None) -> None:
         pass
 
 
+# ---------------------------------------------------------------------------
+# Agents registry — durable state for headless-CLI agents (/nx-build)
+# ---------------------------------------------------------------------------
+
+_AGENT_COLUMNS = (
+    "harness", "model", "repo_root", "worktree", "branch", "pid",
+    "log_path", "task", "plan_hash", "step_index", "status", "cost_usd",
+    "session_id", "tmux",
+)
+
+
+def record_agent(agent_id: str, **fields: Any) -> None:
+    """Upsert one row in the agents registry.
+
+    Only the fields passed as non-None overwrite the existing row's value;
+    omitted/None fields preserve whatever the prior row held (mirrors
+    ``record_step``'s upsert style). ``updated_ts`` is always set to now().
+    ``started_ts`` is set to now() on first insert and preserved thereafter,
+    unless explicitly passed (e.g. via the ``agent-set --started-ts`` CLI
+    flag). Fail-open: any error is swallowed.
+    """
+    try:
+        conn = db()
+        with conn:
+            prior = conn.execute(
+                "SELECT * FROM agents WHERE agent_id=?", (agent_id,),
+            ).fetchone()
+            prior = dict(prior) if prior is not None else None
+            now = time.time()
+
+            row: Dict[str, Any] = dict(prior) if prior else {c: None for c in _AGENT_COLUMNS}
+            for col in _AGENT_COLUMNS:
+                value = fields.get(col)
+                if value is not None:
+                    row[col] = value
+
+            started_ts = fields.get("started_ts")
+            if started_ts is None:
+                started_ts = (prior or {}).get("started_ts")
+            if started_ts is None:
+                started_ts = now
+
+            conn.execute(
+                "INSERT OR REPLACE INTO agents("
+                "agent_id, harness, model, repo_root, worktree, branch, pid, "
+                "log_path, task, plan_hash, step_index, status, cost_usd, "
+                "session_id, tmux, started_ts, updated_ts) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    agent_id, row["harness"], row["model"], row["repo_root"],
+                    row["worktree"], row["branch"], row["pid"], row["log_path"],
+                    row["task"], row["plan_hash"], row["step_index"], row["status"],
+                    row["cost_usd"], row["session_id"], row["tmux"], started_ts, now,
+                ),
+            )
+        conn.close()
+    except Exception:
+        pass
+
+
+def delete_agent(agent_id: str) -> None:
+    """Remove one agents-registry row. Fail-open."""
+    try:
+        conn = db()
+        with conn:
+            conn.execute("DELETE FROM agents WHERE agent_id=?", (agent_id,))
+        conn.close()
+    except Exception:
+        pass
+
+
+def get_agent(agent_id: str) -> Optional[Dict[str, Any]]:
+    """Return one agents-registry row as a dict, or None."""
+    try:
+        conn = db()
+        row = conn.execute(
+            "SELECT * FROM agents WHERE agent_id=?", (agent_id,),
+        ).fetchone()
+        conn.close()
+        return dict(row) if row is not None else None
+    except Exception:
+        return None
+
+
+def _pid_alive(pid: Any) -> bool:
+    """True if *pid* names a live process. Fail-open to False."""
+    try:
+        pid = int(pid)
+    except (TypeError, ValueError):
+        return False
+    if pid <= 0:
+        return False
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True  # process exists, just not ours to signal
+    except OSError:
+        return False
+    return True
+
+
+def agent_rows(repo_root: Optional[str] = None, active: bool = False) -> List[Dict[str, Any]]:
+    """Return agents-registry rows, most recently updated first.
+
+    Filtered to *repo_root* when given. When ``active`` is True, rows are
+    further filtered to those whose ``pid`` names a live process. Fail-open:
+    any error yields [].
+    """
+    try:
+        conn = db()
+        if repo_root:
+            repo_root = os.path.realpath(repo_root)
+            rows = conn.execute(
+                "SELECT * FROM agents WHERE repo_root=? ORDER BY updated_ts DESC",
+                (repo_root,),
+            ).fetchall()
+        else:
+            rows = conn.execute(
+                "SELECT * FROM agents ORDER BY updated_ts DESC",
+            ).fetchall()
+        conn.close()
+    except Exception:
+        return []
+
+    result = [dict(r) for r in rows]
+    if active:
+        result = [r for r in result if r.get("pid") is not None and _pid_alive(r["pid"])]
+    return result
+
+
+def session_rows(repo_root: str) -> List[Dict[str, Any]]:
+    """Return session summaries for sessions tagged with *repo_root*.
+
+    Joins ``session_kv`` (key='repo_root', written by session_reset.py at
+    SessionStart) with ``session_cost`` (cost/token snapshot) and the stored
+    task signature, rendered to readable text via ``handoff._humanize_task``.
+    Each row: {"session_id", "repo_root", "task", "cost_usd", "input_tok",
+    "output_tok", "context_pct", "updated_ts"}. Fail-open: any error yields [].
+    """
+    try:
+        conn = db()
+        repo_root = os.path.realpath(repo_root)
+        tagged = conn.execute(
+            "SELECT session_id, value FROM session_kv WHERE key='repo_root' AND value=?",
+            (repo_root,),
+        ).fetchall()
+
+        try:
+            import handoff as _handoff
+        except Exception:
+            _handoff = None
+
+        threshold = float(get_config().get("compaction_threshold_tokens", 120000) or 120000)
+
+        result: List[Dict[str, Any]] = []
+        for tagged_row in tagged:
+            session_id = tagged_row["session_id"]
+            cost_row = conn.execute(
+                "SELECT cost_usd, input_tok, output_tok, updated_ts "
+                "FROM session_cost WHERE session_id=?",
+                (session_id,),
+            ).fetchone()
+            task_row = conn.execute(
+                "SELECT value FROM session_kv WHERE session_id=? AND key='task'",
+                (session_id,),
+            ).fetchone()
+
+            task_text = ""
+            if _handoff is not None:
+                try:
+                    task_text = _handoff._humanize_task(task_row["value"] if task_row else None)
+                except Exception:
+                    task_text = ""
+
+            input_tok = cost_row["input_tok"] if cost_row else 0
+            output_tok = cost_row["output_tok"] if cost_row else 0
+            context_pct = 0.0
+            if threshold > 0:
+                try:
+                    context_pct = round(100.0 * (input_tok or 0) / threshold, 1)
+                except Exception:
+                    context_pct = 0.0
+
+            result.append({
+                "session_id": session_id,
+                "repo_root": tagged_row["value"],
+                "task": task_text,
+                "cost_usd": cost_row["cost_usd"] if cost_row else 0.0,
+                "input_tok": input_tok,
+                "output_tok": output_tok,
+                "context_pct": context_pct,
+                "updated_ts": cost_row["updated_ts"] if cost_row else 0.0,
+            })
+        conn.close()
+        return result
+    except Exception:
+        return []
+
+
 # ---------------------------------------------------------------------------
 # Dispatch batching — deterministic sub-batch partition for /nx-build
 # ---------------------------------------------------------------------------
@@ -1755,6 +2000,50 @@ def _cmd_calib_advice(args) -> None:
     print(json.dumps(calibration_advice(args.repo), sort_keys=True))
 
 
+def _cmd_agent_set(args) -> None:
+    """Upsert one agent registry row."""
+    record_agent(
+        args.id,
+        harness=args.harness,
+        model=args.model,
+        repo_root=args.repo,
+        worktree=args.worktree,
+        branch=args.branch,
+        pid=args.pid,
+        log_path=args.log_path,
+        task=args.task,
+        plan_hash=args.plan_hash,
+        step_index=args.step_index,
+        status=args.status,
+        cost_usd=args.cost_usd,
+        session_id=args.session_id,
+        tmux=args.tmux,
+        started_ts=args.started_ts,
+    )
+    print(json.dumps({"ok": True, "agent_id": args.id}))
+
+
+def _cmd_agent_get(args) -> None:
+    """Print one agent row as JSON (null if absent)."""
+    print(json.dumps(get_agent(args.id)))
+
+
+def _cmd_agent_del(args) -> None:
+    """Delete one agent registry row."""
+    delete_agent(args.id)
+    print(json.dumps({"ok": True, "agent_id": args.id}))
+
+
+def _cmd_agent_list(args) -> None:
+    """Print agent rows as a JSON array, optionally filtered to repo/active."""
+    print(json.dumps(agent_rows(repo_root=args.repo, active=args.active)))
+
+
+def _cmd_session_list(args) -> None:
+    """Print repo-scoped session summaries as a JSON array."""
+    print(json.dumps(session_rows(args.repo)))
+
+
 def main() -> None:
     parser = argparse.ArgumentParser(
         prog="store.py",
@@ -1828,6 +2117,39 @@ def main() -> None:
     )
     p_cadv.add_argument("--repo", required=True)
 
+    p_aset = sub.add_parser("agent-set", help="Upsert one agent registry row.")
+    p_aset.add_argument("--id", required=True, dest="id")
+    p_aset.add_argument("--harness")
+    p_aset.add_argument("--model")
+    p_aset.add_argument("--repo")
+    p_aset.add_argument("--worktree")
+    p_aset.add_argument("--branch")
+    p_aset.add_argument("--pid", type=int)
+    p_aset.add_argument("--log-path")
+    p_aset.add_argument("--task")
+    p_aset.add_argument("--plan-hash")
+    p_aset.add_argument("--step-index", type=int)
+    p_aset.add_argument("--status")
+    p_aset.add_argument("--cost-usd", type=float)
+    p_aset.add_argument("--session-id")
+    p_aset.add_argument("--tmux")
+    p_aset.add_argument("--started-ts", type=float)
+
+    p_aget = sub.add_parser("agent-get", help="Print one agent row as JSON.")
+    p_aget.add_argument("--id", required=True, dest="id")
+
+    p_adel = sub.add_parser("agent-del", help="Delete one agent registry row.")
+    p_adel.add_argument("--id", required=True, dest="id")
+
+    p_alist = sub.add_parser("agent-list", help="Print agent rows as a JSON array.")
+    p_alist.add_argument("--repo", default=None)
+    p_alist.add_argument("--active", action="store_true")
+    p_alist.add_argument("--json", action="store_true", help="Accepted for symmetry; output is always JSON.")
+
+    p_slist = sub.add_parser("session-list", help="Print repo-scoped session summaries as JSON.")
+    p_slist.add_argument("--repo", required=True)
+    p_slist.add_argument("--json", action="store_true", help="Accepted for symmetry; output is always JSON.")
+
     args = parser.parse_args()
 
     if args.command == "init":
@@ -1856,6 +2178,16 @@ def main() -> None:
         _cmd_calib_advice(args)
     elif args.command == "prune":
         _cmd_prune(args)
+    elif args.command == "agent-set":
+        _cmd_agent_set(args)
+    elif args.command == "agent-get":
+        _cmd_agent_get(args)
+    elif args.command == "agent-del":
+        _cmd_agent_del(args)
+    elif args.command == "agent-list":
+        _cmd_agent_list(args)
+    elif args.command == "session-list":
+        _cmd_session_list(args)
     else:
         parser.print_help()
         sys.exit(1)
diff --git a/scripts/worktree.py b/scripts/worktree.py
new file mode 100644
index 0000000..901eb92
--- /dev/null
+++ b/scripts/worktree.py
@@ -0,0 +1,181 @@
+"""worktree.py — create an isolated git worktree for a divergent task.
+
+When context_watch detects the user has switched to a genuinely different task
+*while the working tree still has uncommitted changes*, nexum isolates the new
+work in a git worktree under ``<repo>/.nexum-data/worktrees/<slug>`` so it does
+not tangle with the unfinished changes. A clean tree needs no worktree — the
+current context is fine for the new task.
+
+Untracked helper files the new worktree needs but git won't check out (env
+files, local config) are copied in per the ``worktree_copy`` config globs;
+anything matching ``worktree_ignore`` is skipped.
+
+Everything here is fail-open: any git/filesystem error returns None (or False)
+rather than raising, so the calling hook never blocks a prompt on a git hiccup.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Iterable, Optional
+
+
+def _git(cwd: str, *args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        ["git", "-C", cwd, *args],
+        capture_output=True,
+        text=True,
+        timeout=8,
+    )
+
+
+def _toplevel(cwd: str) -> Optional[str]:
+    try:
+        r = _git(cwd, "rev-parse", "--show-toplevel")
+    except Exception:
+        return None
+    if r.returncode == 0 and r.stdout.strip():
+        return r.stdout.strip()
+    return None
+
+
+def is_dirty(cwd: str) -> bool:
+    """True if the working tree at *cwd* has uncommitted (tracked or untracked)
+    changes. Fail-open to False so a git error never forces a worktree."""
+    try:
+        r = _git(cwd, "status", "--porcelain")
+    except Exception:
+        return False
+    return r.returncode == 0 and bool(r.stdout.strip())
+
+
+def _copy_extras(
+    src_root: str,
+    dest_root: str,
+    copy_globs: Iterable[str],
+    ignore_globs: Iterable[str],
+) -> None:
+    """Copy files matching *copy_globs* (relative to src_root) into dest_root,
+    preserving relative paths, skipping anything matching *ignore_globs*."""
+    ignore = list(ignore_globs or [])
+    for pattern in copy_globs or []:
+        for path in Path(src_root).glob(pattern):
+            rel = path.relative_to(src_root)
+            rel_str = str(rel)
+            if any(fnmatch.fnmatch(rel_str, ig) for ig in ignore):
+                continue
+            target = Path(dest_root) / rel
+            try:
+                if path.is_dir():
+                    shutil.copytree(path, target, dirs_exist_ok=True)
+                else:
+                    target.parent.mkdir(parents=True, exist_ok=True)
+                    shutil.copy2(path, target)
+            except Exception:
+                # Best-effort: one un-copyable extra must not abort the worktree.
+                continue
+
+
+def create_worktree(
+    cwd: str,
+    slug: str,
+    copy_globs: Iterable[str] = (),
+    ignore_globs: Iterable[str] = (),
+) -> Optional[str]:
+    """Create (or reuse) a worktree at ``<repo>/.nexum-data/worktrees/<slug>``.
+
+    Returns the worktree path, or None if not a git repo / creation failed.
+    A new branch ``nexum/<slug>`` is created off HEAD; if the path already
+    exists it is reused as-is.
+    """
+    top = _toplevel(cwd)
+    if not top:
+        return None
+
+    dest = Path(top) / ".nexum-data" / "worktrees" / slug
+    if dest.exists():
+        return str(dest)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+
+    branch = f"nexum/{slug}"
+    try:
+        r = _git(top, "worktree", "add", "-b", branch, str(dest))
+        if r.returncode != 0:
+            # Branch likely already exists — attach the worktree to it instead.
+            r = _git(top, "worktree", "add", str(dest), branch)
+            if r.returncode != 0:
+                return None
+    except Exception:
+        return None
+
+    _copy_extras(top, str(dest), copy_globs, ignore_globs)
+    return str(dest)
+
+
+def _demo() -> None:
+    """Self-check: a dirty repo yields a worktree with copied extras; is_dirty
+    tracks the tree state. Run: python3 scripts/worktree.py"""
+    import tempfile
+
+    with tempfile.TemporaryDirectory() as tmp:
+        _git(tmp, "init", "-q")
+        _git(tmp, "config", "user.email", "t@t")
+        _git(tmp, "config", "user.name", "t")
+        (Path(tmp) / "a.txt").write_text("hello")
+        _git(tmp, "add", "a.txt")
+        _git(tmp, "commit", "-qm", "init")
+        assert not is_dirty(tmp), "clean tree read as dirty"
+
+        # untracked helper + a tracked edit → dirty
+        (Path(tmp) / ".env").write_text("SECRET=1")
+        (Path(tmp) / "a.txt").write_text("changed")
+        assert is_dirty(tmp), "dirty tree read as clean"
+
+        wt = create_worktree(tmp, "feature-abc123", copy_globs=[".env"], ignore_globs=[])
+        assert wt is not None and os.path.isdir(wt), "worktree not created"
+        assert (Path(wt) / ".env").read_text() == "SECRET=1", "extra not copied"
+        assert (Path(wt) / "a.txt").read_text() == "hello", "worktree not at HEAD"
+        # reuse returns same path
+        assert create_worktree(tmp, "feature-abc123") == wt, "reuse mismatch"
+    print("worktree demo OK")
+
+
+def _main() -> None:
+    """CLI: `--create --repo <r> --slug <s>` prints {"worktree": path}. With no
+    args, runs the self-check demo."""
+    import argparse
+    import json as _json
+    import sys
+
+    if len(sys.argv) == 1:
+        _demo()
+        return
+
+    p = argparse.ArgumentParser(prog="worktree.py")
+    p.add_argument("--create", action="store_true")
+    p.add_argument("--repo", required=True)
+    p.add_argument("--slug", required=True)
+    args = p.parse_args()
+
+    try:
+        cfg = {}
+        try:
+            import store  # optional — for worktree_copy/ignore config
+            cfg = store.get_config()
+        except Exception:
+            pass
+        wt = create_worktree(
+            os.path.realpath(args.repo), args.slug,
+            cfg.get("worktree_copy", []), cfg.get("worktree_ignore", []),
+        )
+        print(_json.dumps({"worktree": wt} if wt else {"error": "worktree creation failed"}))
+    except Exception as exc:
+        print(_json.dumps({"error": str(exc)}))
+
+
+if __name__ == "__main__":
+    _main()
diff --git a/tests/fixtures/fake_harness.py b/tests/fixtures/fake_harness.py
new file mode 100644
index 0000000..38949e9
--- /dev/null
+++ b/tests/fixtures/fake_harness.py
@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+"""fake_harness.py — a stand-in headless agent CLI for tests.
+
+Invoked exactly like a real harness would be (prompt is the final argv item).
+It "does work" by writing a marker file into its cwd (the worktree dispatch.py
+created), then prints one stream-json result line so parse_stream sees tokens.
+
+Used via `NEXUM_HARNESS_CMD_CLAUDE="python3 <abs>/tests/fixtures/fake_harness.py"`
+so dispatch.py can be exercised end-to-end with no real claude/opencode/cursor
+binary installed.
+"""
+
+import json
+import os
+import sys
+
+target = os.environ.get("FAKE_HARNESS_TARGET", "fake_out.txt")
+prompt = sys.argv[-1] if len(sys.argv) > 1 else ""
+
+with open(target, "w", encoding="utf-8") as fh:
+    fh.write("edited by fake harness\n")
+
+print(json.dumps({"type": "result", "tokens": 10, "cost_usd": 0.0}))
diff --git a/tests/test_context_watch.py b/tests/test_context_watch.py
index f829478..cf06db0 100644
--- a/tests/test_context_watch.py
+++ b/tests/test_context_watch.py
@@ -39,6 +39,38 @@ def _run_context_watch(payload, data_dir):
     return json.loads(result.stdout.decode()), result.returncode
 
 
+def _git(cwd, *args):
+    subprocess.run(["git", "-C", cwd, *args], capture_output=True, text=True, check=False)
+
+
+def _dirty_git_repo():
+    """Temp git repo with one commit plus an uncommitted edit → is_dirty True."""
+    repo = tempfile.mkdtemp()
+    _git(repo, "init", "-q")
+    _git(repo, "config", "user.email", "t@t")
+    _git(repo, "config", "user.name", "t")
+    with open(os.path.join(repo, "a.txt"), "w") as f:
+        f.write("hello")
+    _git(repo, "add", "a.txt")
+    _git(repo, "commit", "-qm", "init")
+    with open(os.path.join(repo, "a.txt"), "w") as f:
+        f.write("changed")  # uncommitted → dirty
+    return repo
+
+
+def _clean_git_repo():
+    """Temp git repo with a single commit and no pending changes → is_dirty False."""
+    repo = tempfile.mkdtemp()
+    _git(repo, "init", "-q")
+    _git(repo, "config", "user.email", "t@t")
+    _git(repo, "config", "user.name", "t")
+    with open(os.path.join(repo, "a.txt"), "w") as f:
+        f.write("hello")
+    _git(repo, "add", "a.txt")
+    _git(repo, "commit", "-qm", "init")
+    return repo
+
+
 def _is_blocked(out):
     return out.get("decision") == "block"
 
@@ -117,32 +149,62 @@ def test_continuation_same_words_allowed(self):
 
 
 class TestContextWatchIntentBlock(unittest.TestCase):
-    """fix→feature divergence should be blocked."""
+    """fix→feature divergence on a DIRTY tree → worktree + block."""
 
     def setUp(self):
         self._tmp = tempfile.mkdtemp()
+        self._repo = _dirty_git_repo()
 
     def test_fix_to_feature_blocked(self):
         sid = "sess_block"
         # Establish fix context
-        p1 = {"session_id": sid, "prompt": "fix the crash bug in the payment module"}
+        p1 = {"session_id": sid, "prompt": "fix the crash bug in the payment module",
+              "cwd": self._repo}
         out1, _ = _run_context_watch(p1, self._tmp)
         self.assertTrue(_is_allowed(out1), f"First prompt should be allowed, got: {out1}")
 
-        # Switch to feature — should be blocked
-        p2 = {"session_id": sid, "prompt": "add new billing dashboard feature implement"}
+        # Switch to feature on a dirty tree — should be blocked with a worktree
+        p2 = {"session_id": sid, "prompt": "add new billing dashboard feature implement",
+              "cwd": self._repo}
         out2, rc2 = _run_context_watch(p2, self._tmp)
         self.assertEqual(rc2, 0)
         self.assertTrue(_is_blocked(out2),
                         f"Expected block on fix→feature divergence, got: {out2}")
+        # A worktree was actually created under the repo's .nexum-data/worktrees.
+        wt_root = os.path.join(self._repo, ".nexum-data", "worktrees")
+        self.assertTrue(os.path.isdir(wt_root) and os.listdir(wt_root),
+                        "Expected a worktree to be created on divergence")
+        self.assertIn(wt_root, out2.get("reason", ""))
+
+    def test_clean_tree_allows_divergence(self):
+        """On a CLEAN tree the divergent task is allowed in place — no worktree,
+        no block. This is the behaviour change: no more 'start a fresh session'."""
+        clean = _clean_git_repo()
+        sid = "sess_clean"
+        _run_context_watch(
+            {"session_id": sid, "prompt": "fix the crash bug in the payment module",
+             "cwd": clean},
+            self._tmp,
+        )
+        out, rc = _run_context_watch(
+            {"session_id": sid, "prompt": "add new billing dashboard feature implement",
+             "cwd": clean},
+            self._tmp,
+        )
+        self.assertEqual(rc, 0)
+        self.assertTrue(_is_allowed(out), f"Clean-tree divergence must be allowed, got: {out}")
+        self.assertFalse(os.path.isdir(os.path.join(clean, ".nexum-data", "worktrees")),
+                         "No worktree should be created on a clean tree")
 
     def test_block_message_format(self):
-        """Block reason must follow the spec format."""
+        """Block reason must name nexum and offer the 'continue' escape hatch."""
         sid = "sess_block_msg"
-        p1 = {"session_id": sid, "prompt": "fix the database error and exception"}
+        p1 = {"session_id": sid, "prompt": "fix the database error and exception",
+              "cwd": self._repo}
         _run_context_watch(p1, self._tmp)
 
-        p2 = {"session_id": sid, "prompt": "implement new feature add billing module"}
+        p2 = {"session_id": sid, "prompt": "implement new feature add billing module",
+              "cwd": self._repo}
         out, _ = _run_context_watch(p2, self._tmp)
 
         if _is_blocked(out):
@@ -157,18 +219,21 @@ class TestContextWatchAutomatedPromptSkipsGuard(unittest.TestCase):
 
     def setUp(self):
         self._tmp = tempfile.mkdtemp()
+        self._repo = _dirty_git_repo()
 
     def test_task_notification_not_blocked(self):
         sid = "sess_auto"
         # Establish a fix context (bare prompt) so a feature prompt would block.
         _run_context_watch(
-            {"session_id": sid, "prompt": "fix the crash bug in the payment module"},
+            {"session_id": sid, "prompt": "fix the crash bug in the payment module",
+             "cwd": self._repo},
             self._tmp,
         )
         # A background-agent completion arrives as a task-notification whose text
         # would otherwise read as a divergent "feature" task.
         auto = {
             "session_id": sid,
+            "cwd": self._repo,
             "prompt": (
                 "<task-notification>\n<task-id>abc123</task-id>\n"
                 "add new billing dashboard feature implement\n</task-notification>"
@@ -182,15 +247,17 @@ def test_task_notification_not_blocked(self):
         )
 
     def test_bare_version_still_blocks(self):
-        """Control: the same divergent text WITHOUT automation markers still blocks,
-        proving the skip is specific to automated prompts."""
+        """Control: the same divergent text WITHOUT automation markers still blocks
+        on a dirty tree, proving the skip is specific to automated prompts."""
         sid = "sess_auto_control"
         _run_context_watch(
-            {"session_id": sid, "prompt": "fix the crash bug in the payment module"},
+            {"session_id": sid, "prompt": "fix the crash bug in the payment module",
+             "cwd": self._repo},
             self._tmp,
         )
         out, _ = _run_context_watch(
-            {"session_id": sid, "prompt": "add new billing dashboard feature implement"},
+            {"session_id": sid, "prompt": "add new billing dashboard feature implement",
+             "cwd": self._repo},
             self._tmp,
         )
         self.assertTrue(_is_blocked(out), f"Bare divergent prompt should block, got: {out}")
@@ -201,22 +268,25 @@ class TestContextWatchContinueBypass(unittest.TestCase):
 
     def setUp(self):
         self._tmp = tempfile.mkdtemp()
+        self._repo = _dirty_git_repo()
 
     def test_continue_bypasses_block(self):
         sid = "sess_continue"
         # Establish fix context
-        p1 = {"session_id": sid, "prompt": "fix the crash bug in payment processing"}
+        p1 = {"session_id": sid, "prompt": "fix the crash bug in payment processing",
+              "cwd": self._repo}
         _run_context_watch(p1, self._tmp)
 
-        # Trigger a block
-        p2 = {"session_id": sid, "prompt": "add new billing dashboard feature implement"}
+        # Trigger a block (dirty tree → worktree + block)
+        p2 = {"session_id": sid, "prompt": "add new billing dashboard feature implement",
+              "cwd": self._repo}
         out_block = _run_context_watch(p2, self._tmp)[0]
 
         if not _is_blocked(out_block):
             self.skipTest("Guard didn't block — Jaccard similarity may be above threshold")
 
         # Send 'continue'
-        p3 = {"session_id": sid, "prompt": "continue"}
+        p3 = {"session_id": sid, "prompt": "continue", "cwd": self._repo}
         out_continue, rc = _run_context_watch(p3, self._tmp)
         self.assertEqual(rc, 0)
         self.assertTrue(_is_allowed(out_continue),
@@ -225,16 +295,18 @@ def test_continue_bypasses_block(self):
     def test_continue_case_insensitive(self):
         """'CONTINUE' (uppercase) must also bypass the block."""
         sid = "sess_continue_case"
-        p1 = {"session_id": sid, "prompt": "fix the crash bug in payment module"}
+        p1 = {"session_id": sid, "prompt": "fix the crash bug in payment module",
+              "cwd": self._repo}
         _run_context_watch(p1, self._tmp)
 
-        p2 = {"session_id": sid, "prompt": "add new billing feature implement create"}
+        p2 = {"session_id": sid, "prompt": "add new billing feature implement create",
+              "cwd": self._repo}
         out_block = _run_context_watch(p2, self._tmp)[0]
 
         if not _is_blocked(out_block):
             self.skipTest("Guard didn't block")
 
-        p3 = {"session_id": sid, "prompt": "CONTINUE"}
+        p3 = {"session_id": sid, "prompt": "CONTINUE", "cwd": self._repo}
         out, rc = _run_context_watch(p3, self._tmp)
         self.assertEqual(rc, 0)
         self.assertTrue(_is_allowed(out))
diff --git a/tests/test_dispatch.py b/tests/test_dispatch.py
new file mode 100644
index 0000000..e1bd014
--- /dev/null
+++ b/tests/test_dispatch.py
@@ -0,0 +1,113 @@
+"""test_dispatch.py — end-to-end test for scripts/dispatch.py using a fake harness.
+
+Drives dispatch.py against tests/fixtures/fake_harness.py (injected via
+NEXUM_HARNESS_CMD_CLAUDE) in a throwaway git repo, so no real agent CLI is
+needed. Asserts the verdict passes, a worktree was created, and the agents
+registry row landed as done.
+"""
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+
+_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+_SCRIPTS_DIR = os.path.join(_ROOT, "scripts")
+_FAKE = os.path.join(_ROOT, "tests", "fixtures", "fake_harness.py")
+if _SCRIPTS_DIR not in sys.path:
+    sys.path.insert(0, _SCRIPTS_DIR)
+
+
+def _git(cwd, *args):
+    subprocess.run(["git", "-C", cwd, *args], capture_output=True, text=True, check=False)
+
+
+def _repo():
+    d = tempfile.mkdtemp()
+    _git(d, "init", "-q")
+    _git(d, "config", "user.email", "t@t")
+    _git(d, "config", "user.name", "t")
+    with open(os.path.join(d, "seed.txt"), "w") as f:
+        f.write("seed")
+    _git(d, "add", "seed.txt")
+    _git(d, "commit", "-qm", "init")
+    return d
+
+
+def _run_dispatch(repo, data_dir, step, slug="demo", agent_id="agent_test"):
+    env = os.environ.copy()
+    env["CLAUDE_PLUGIN_DATA"] = data_dir
+    env["PYTHONPATH"] = _SCRIPTS_DIR + os.pathsep + env.get("PYTHONPATH", "")
+    env["NEXUM_HARNESS_CMD_CLAUDE"] = f"{sys.executable} {_FAKE}"
+    step_file = os.path.join(data_dir, "step.json")
+    with open(step_file, "w") as f:
+        json.dump(step, f)
+    r = subprocess.run(
+        [sys.executable, os.path.join(_SCRIPTS_DIR, "dispatch.py"),
+         "--harness", "claude", "--model", "sonnet", "--repo", repo,
+         "--new-worktree", "--slug", slug, "--step-file", step_file,
+         "--agent-id", agent_id],
+        capture_output=True, text=True, env=env, timeout=60,
+    )
+    return json.loads(r.stdout), r.returncode, env
+
+
+class TestDispatch(unittest.TestCase):
+    def setUp(self):
+        self._repo = _repo()
+        self._data = tempfile.mkdtemp()
+
+    def test_pass_creates_worktree_and_agent_row(self):
+        step = {
+            "title": "fake step",
+            "objective": "let the fake harness write a file",
+            "contract": "n/a",
+            "scope_deny": [],
+            "acceptance": "test -f fake_out.txt",
+            "files": ["fake_out.txt"],
+        }
+        verdict, rc, env = _run_dispatch(self._repo, self._data, step)
+        self.assertEqual(rc, 0)
+        self.assertTrue(verdict.get("pass"), f"expected pass, got: {verdict}")
+        # worktree created under the repo
+        wt = verdict.get("worktree", "")
+        self.assertTrue(os.path.isdir(wt), f"worktree missing: {wt}")
+        self.assertIn(os.path.join(".nexum-data", "worktrees"), wt)
+        # the fake harness's edit is present in the worktree
+        self.assertTrue(os.path.exists(os.path.join(wt, "fake_out.txt")))
+        # harness token count flowed through
+        self.assertEqual(verdict.get("tokens"), 10)
+
+        # agents registry row is 'done'
+        r = subprocess.run(
+            [sys.executable, os.path.join(_SCRIPTS_DIR, "store.py"),
+             "agent-get", "--id", "agent_test"],
+            capture_output=True, text=True, env=env, timeout=30,
+        )
+        row = json.loads(r.stdout)
+        self.assertIsNotNone(row)
+        self.assertEqual(row["status"], "done")
+        self.assertEqual(row["harness"], "claude")
+        self.assertEqual(row["repo_root"], os.path.realpath(self._repo))
+
+    def test_failing_acceptance_marks_failed(self):
+        step = {
+            "title": "doomed step",
+            "objective": "acceptance can never pass",
+            "contract": "n/a",
+            "scope_deny": [],
+            "acceptance": "test -f this_file_never_exists_zzz",
+            "files": ["fake_out.txt"],
+        }
+        verdict, rc, env = _run_dispatch(self._repo, self._data, step,
+                                         slug="doomed", agent_id="agent_fail")
+        self.assertEqual(rc, 0)
+        self.assertFalse(verdict.get("pass"))
+        # a failed step keeps the diff for a patch-retry
+        self.assertIn("diff", verdict)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/test_harness.py b/tests/test_harness.py
new file mode 100644
index 0000000..7f8590b
--- /dev/null
+++ b/tests/test_harness.py
@@ -0,0 +1,109 @@
+"""test_harness.py — stdlib unittest tests for scripts/harness.py"""
+
+import os
+import sys
+import unittest
+
+_SCRIPTS_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "scripts")
+if _SCRIPTS_DIR not in sys.path:
+    sys.path.insert(0, _SCRIPTS_DIR)
+
+import harness  # noqa: E402
+
+
+class TestBuildCommand(unittest.TestCase):
+    def test_claude_shape(self):
+        cmd = harness.build_command("claude", "sonnet", "do the thing", "/repo")
+        self.assertEqual(
+            cmd,
+            ["claude", "-p", "do the thing", "--output-format", "stream-json", "--model", "sonnet"],
+        )
+
+    def test_opencode_shape(self):
+        cmd = harness.build_command("opencode", "gpt-5", "do the thing", "/repo")
+        self.assertEqual(
+            cmd,
+            ["opencode", "run", "do the thing", "--model", "gpt-5", "--format", "json"],
+        )
+
+    def test_cursor_shape(self):
+        cmd = harness.build_command("cursor", "auto", "do the thing", "/repo")
+        self.assertEqual(
+            cmd,
+            ["cursor-agent", "-p", "do the thing", "--output-format", "stream-json", "--model", "auto"],
+        )
+
+    def test_unknown_harness_raises(self):
+        with self.assertRaises(ValueError):
+            harness.build_command("nope", "model", "prompt", "/repo")
+
+    def test_env_override(self):
+        old = os.environ.get("NEXUM_HARNESS_CMD_CLAUDE")
+        os.environ["NEXUM_HARNESS_CMD_CLAUDE"] = "/usr/bin/env echo --flag value"
+        try:
+            cmd = harness.build_command("claude", "sonnet", "hello world", "/repo")
+            self.assertEqual(cmd, ["/usr/bin/env", "echo", "--flag", "value", "hello world"])
+        finally:
+            if old is None:
+                os.environ.pop("NEXUM_HARNESS_CMD_CLAUDE", None)
+            else:
+                os.environ["NEXUM_HARNESS_CMD_CLAUDE"] = old
+
+
+class TestParseStream(unittest.TestCase):
+    def test_result_line(self):
+        lines = ['{"type":"result","tokens":5,"cost_usd":0.0}']
+        parsed = harness.parse_stream("claude", lines)
+        self.assertEqual(parsed["status"], "done")
+        self.assertEqual(parsed["tokens"], 5)
+        self.assertEqual(parsed["cost_usd"], 0.0)
+        self.assertEqual(parsed["final_text"], "")
+
+    def test_non_json_lines_ignored(self):
+        lines = ["not json", "", '{"type":"result","tokens":3,"cost_usd":1.5,"result":"done text"}']
+        parsed = harness.parse_stream("claude", lines)
+        self.assertEqual(parsed["status"], "done")
+        self.assertEqual(parsed["tokens"], 3)
+        self.assertEqual(parsed["cost_usd"], 1.5)
+        self.assertEqual(parsed["final_text"], "done text")
+
+    def test_no_result_line_defaults(self):
+        parsed = harness.parse_stream("claude", [])
+        self.assertEqual(parsed, {"status": "running", "final_text": "", "tokens": 0, "cost_usd": 0.0})
+
+    def test_error_type(self):
+        lines = ['{"type":"error","message":"boom"}']
+        parsed = harness.parse_stream("claude", lines)
+        self.assertEqual(parsed["status"], "error")
+
+
+class TestRun(unittest.TestCase):
+    def test_fail_open_missing_binary(self):
+        old = os.environ.get("NEXUM_HARNESS_CMD_CLAUDE")
+        os.environ["NEXUM_HARNESS_CMD_CLAUDE"] = "/definitely/not/a/real/binary-nexum"
+        try:
+            result = harness.run(
+                "claude", "sonnet", "hi", "/tmp", "/tmp/nexum-test-harness.log", timeout=5
+            )
+            self.assertFalse(result["ok"])
+            self.assertEqual(result["status"], "error")
+            self.assertEqual(result["rc"], -1)
+            self.assertEqual(result["tokens"], 0)
+            self.assertEqual(result["cost_usd"], 0.0)
+            self.assertEqual(result["final_text"], "")
+            self.assertEqual(result["log_path"], "/tmp/nexum-test-harness.log")
+        finally:
+            if old is None:
+                os.environ.pop("NEXUM_HARNESS_CMD_CLAUDE", None)
+            else:
+                os.environ["NEXUM_HARNESS_CMD_CLAUDE"] = old
+
+    def test_unknown_harness_fail_open(self):
+        result = harness.run("nope", "model", "prompt", "/tmp", "/tmp/nexum-test-harness2.log")
+        self.assertFalse(result["ok"])
+        self.assertEqual(result["status"], "error")
+        self.assertEqual(result["rc"], -1)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/test_mcp_server.py b/tests/test_mcp_server.py
new file mode 100644
index 0000000..8a2f535
--- /dev/null
+++ b/tests/test_mcp_server.py
@@ -0,0 +1,173 @@
+"""test_mcp_server.py — stdlib unittest tests for scripts/mcp_server.py"""
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import time
+import unittest
+
+_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+_SCRIPTS_DIR = os.path.join(_ROOT, "scripts")
+_FAKE = os.path.join(_ROOT, "tests", "fixtures", "fake_harness.py")
+if _SCRIPTS_DIR not in sys.path:
+    sys.path.insert(0, _SCRIPTS_DIR)
+
+import mcp_server  # noqa: E402
+
+
+def call(msg):
+    return mcp_server.handle_message(msg)
+
+
+class TestProtocol(unittest.TestCase):
+    def test_initialize_echoes_protocol_and_names_server(self):
+        r = call({"jsonrpc": "2.0", "id": 1, "method": "initialize",
+                  "params": {"protocolVersion": "2025-06-18"}})
+        self.assertEqual(r["result"]["protocolVersion"], "2025-06-18")
+        self.assertEqual(r["result"]["serverInfo"]["name"], "nexum-delegate")
+        self.assertIn("tools", r["result"]["capabilities"])
+
+    def test_notifications_get_no_reply(self):
+        self.assertIsNone(call({"jsonrpc": "2.0", "method": "notifications/initialized"}))
+
+    def test_tools_list_exposes_all_tools(self):
+        r = call({"jsonrpc": "2.0", "id": 2, "method": "tools/list"})
+        names = {t["name"] for t in r["result"]["tools"]}
+        self.assertEqual(names, {"delegate", "delegate_async", "check", "list_agents"})
+
+    def test_unknown_method_is_jsonrpc_error(self):
+        r = call({"jsonrpc": "2.0", "id": 3, "method": "bogus/method"})
+        self.assertEqual(r["error"]["code"], -32601)
+
+    def test_unknown_tool_is_error(self):
+        r = call({"jsonrpc": "2.0", "id": 4, "method": "tools/call",
+                  "params": {"name": "nope", "arguments": {}}})
+        self.assertIn("error", r)
+
+
+class TestDelegateValidation(unittest.TestCase):
+    def test_bad_harness_rejected_before_running(self):
+        r = call({"jsonrpc": "2.0", "id": 5, "method": "tools/call",
+                  "params": {"name": "delegate",
+                             "arguments": {"harness": "bogus", "task": "x"}}})
+        self.assertIn("harness must be one of", r["result"]["content"][0]["text"])
+
+    def test_empty_task_rejected(self):
+        r = call({"jsonrpc": "2.0", "id": 6, "method": "tools/call",
+                  "params": {"name": "delegate",
+                             "arguments": {"harness": "cursor", "task": "   "}}})
+        self.assertIn("task is required", r["result"]["content"][0]["text"])
+
+
+class TestParseLastJson(unittest.TestCase):
+    def test_returns_last_object_ignoring_noise(self):
+        self.assertEqual(
+            mcp_server._parse_last_json('log line\n{"a":1}\n{"pass":true}\n'),
+            {"pass": True},
+        )
+
+    def test_none_when_no_json(self):
+        self.assertIsNone(mcp_server._parse_last_json("no json here\n"))
+
+
+def _git(cwd, *args):
+    subprocess.run(["git", "-C", cwd, *args], capture_output=True, text=True, check=False)
+
+
+def _seed_repo():
+    d = tempfile.mkdtemp()
+    _git(d, "init", "-q")
+    _git(d, "config", "user.email", "t@t")
+    _git(d, "config", "user.name", "t")
+    with open(os.path.join(d, "seed.txt"), "w") as f:
+        f.write("seed")
+    _git(d, "add", "seed.txt")
+    _git(d, "commit", "-qm", "init")
+    return d
+
+
+class TestDelegateEndToEnd(unittest.TestCase):
+    """Drive the real delegate tool through dispatch.py with a fake harness in a
+    throwaway git repo — proves the whole worktree→run→guardrail→verdict path."""
+
+    def setUp(self):
+        self._cwd = os.getcwd()
+        self._repo = _seed_repo()
+        os.chdir(self._repo)
+        self._saved = {k: os.environ.get(k) for k in
+                       ("NEXUM_HARNESS_CMD_CURSOR", "CLAUDE_PLUGIN_DATA")}
+        os.environ["NEXUM_HARNESS_CMD_CURSOR"] = f"{sys.executable} {_FAKE}"
+        os.environ["CLAUDE_PLUGIN_DATA"] = os.path.join(self._repo, ".nexum-data")
+
+    def tearDown(self):
+        os.chdir(self._cwd)
+        for k, v in self._saved.items():
+            if v is None:
+                os.environ.pop(k, None)
+            else:
+                os.environ[k] = v
+
+    def test_delegate_runs_harness_and_returns_pass_verdict(self):
+        out = mcp_server._tool_delegate({
+            "harness": "cursor",
+            "task": "let the fake harness write a file",
+            "acceptance": "test -f fake_out.txt",
+            "files": ["fake_out.txt"],
+        })
+        verdict = json.loads(out)
+        self.assertTrue(verdict.get("pass"), out)
+        self.assertEqual(verdict.get("harness"), "cursor")
+        self.assertIn(".nexum-data", verdict.get("worktree", ""))
+        self.assertTrue(os.path.exists(os.path.join(verdict["worktree"], "fake_out.txt")))
+        self.assertTrue(verdict.get("agent_id"))
+
+        # the delegated sub-agent is now visible via list_agents (the TUI's data)
+        listed = json.loads(mcp_server._tool_list_agents({}))
+        ids = {a["id"] for a in listed}
+        self.assertIn(verdict["agent_id"], ids)
+
+    def test_delegate_failing_acceptance_reports_not_pass(self):
+        out = mcp_server._tool_delegate({
+            "harness": "cursor",
+            "task": "acceptance can never pass",
+            "acceptance": "test -f never_exists_zzz",
+        })
+        verdict = json.loads(out)
+        self.assertFalse(verdict.get("pass"), out)
+
+    def test_delegate_async_then_check_reaches_done(self):
+        started = json.loads(mcp_server._tool_delegate_async({
+            "harness": "cursor",
+            "task": "async fake harness writes a file",
+            "acceptance": "test -f fake_out.txt",
+            "files": ["fake_out.txt"],
+        }))
+        aid = started["agent_id"]
+        self.assertEqual(started["status"], "running")
+
+        # poll check() until the detached dispatch finishes
+        deadline = time.time() + 20
+        state = {}
+        while time.time() < deadline:
+            state = json.loads(mcp_server._tool_check({"agent_id": aid}))
+            if state.get("done"):
+                break
+            time.sleep(0.2)
+        self.assertTrue(state.get("done"), f"never finished: {state}")
+        self.assertTrue(state.get("pass"), state)
+        self.assertEqual(state.get("status"), "done")
+
+    def test_check_unknown_agent(self):
+        state = json.loads(mcp_server._tool_check({"agent_id": "does_not_exist_zzz"}))
+        self.assertEqual(state["status"], "unknown")
+
+    def test_delegate_async_validates(self):
+        self.assertIn("harness must be one of",
+                      mcp_server._tool_delegate_async({"harness": "x", "task": "t"}))
+        self.assertIn("agent_id is required", mcp_server._tool_check({}))
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/test_meta_imports.py b/tests/test_meta_imports.py
index 904cac4..849612f 100644
--- a/tests/test_meta_imports.py
+++ b/tests/test_meta_imports.py
@@ -31,6 +31,7 @@
     "subprocess",
     "pathlib",
     "time",
+    "uuid",
     "fnmatch",
     "argparse",
     "dataclasses",
@@ -59,6 +60,9 @@
     "cost_report",
     "audit",
     "handoff",
+    "worktree",
+    "harness",
+    "dispatch",
 
     # Python built-ins / __future__ (never third-party)
     "__future__",
diff --git a/tests/test_store.py b/tests/test_store.py
index bf91a4e..d441bad 100644
--- a/tests/test_store.py
+++ b/tests/test_store.py
@@ -1013,5 +1013,179 @@ def test_order_preserved(self):
         self.assertEqual(flat, [5, 1, 9, 3])
 
 
+class TestAgentsRegistry(unittest.TestCase):
+    """record_agent / get_agent / agent_rows: durable state for headless agents."""
+
+    def setUp(self):
+        self._tmp = tempfile.mkdtemp()
+        os.environ["CLAUDE_PLUGIN_DATA"] = self._tmp
+
+    def tearDown(self):
+        os.environ.pop("CLAUDE_PLUGIN_DATA", None)
+
+    def test_record_and_get_roundtrip(self):
+        import store
+        store.record_agent(
+            "a1", harness="claude", model="sonnet", repo_root="/repo",
+            status="running", pid=os.getpid(),
+        )
+        row = store.get_agent("a1")
+        self.assertIsNotNone(row)
+        self.assertEqual(row["harness"], "claude")
+        self.assertEqual(row["model"], "sonnet")
+        self.assertEqual(row["repo_root"], "/repo")
+        self.assertEqual(row["status"], "running")
+        self.assertIsNotNone(row["started_ts"])
+        self.assertIsNotNone(row["updated_ts"])
+
+    def test_get_absent_returns_none(self):
+        import store
+        self.assertIsNone(store.get_agent("nope"))
+
+    def test_partial_update_preserves_other_fields_non_none_only(self):
+        """Re-recording with only status set must keep harness/model/repo_root."""
+        import store
+        store.record_agent("a1", harness="claude", model="sonnet", repo_root="/repo",
+                           status="running")
+        first = store.get_agent("a1")
+        store.record_agent("a1", status="done")
+        row = store.get_agent("a1")
+        self.assertEqual(row["status"], "done")
+        self.assertEqual(row["harness"], "claude")
+        self.assertEqual(row["model"], "sonnet")
+        self.assertEqual(row["repo_root"], "/repo")
+        # started_ts preserved across updates; updated_ts is free to change.
+        self.assertEqual(row["started_ts"], first["started_ts"])
+
+    def test_agent_rows_repo_root_filter(self):
+        import store
+        store.record_agent("a1", repo_root="/repo-a", status="running")
+        store.record_agent("a2", repo_root="/repo-b", status="running")
+        rows = store.agent_rows(repo_root="/repo-a")
+        self.assertEqual([r["agent_id"] for r in rows], ["a1"])
+
+    def test_agent_rows_no_filter_returns_all(self):
+        import store
+        store.record_agent("a1", repo_root="/repo-a")
+        store.record_agent("a2", repo_root="/repo-b")
+        rows = store.agent_rows()
+        self.assertEqual({r["agent_id"] for r in rows}, {"a1", "a2"})
+
+    def test_agent_rows_active_filters_dead_pid(self):
+        import store
+        store.record_agent("alive", repo_root="/repo", pid=os.getpid())
+        store.record_agent("dead", repo_root="/repo", pid=999999)
+        rows = store.agent_rows(repo_root="/repo", active=True)
+        ids = {r["agent_id"] for r in rows}
+        self.assertIn("alive", ids)
+        self.assertNotIn("dead", ids)
+
+
+class TestSessionRows(unittest.TestCase):
+    """session_rows: repo-scoped session summaries joining session_kv + session_cost."""
+
+    def setUp(self):
+        self._tmp = tempfile.mkdtemp()
+        os.environ["CLAUDE_PLUGIN_DATA"] = self._tmp
+
+    def tearDown(self):
+        os.environ.pop("CLAUDE_PLUGIN_DATA", None)
+
+    def test_returns_repo_tagged_session(self):
+        import store
+        store.set_flag("s1", "repo_root", "/repo-x")
+        store.set_session_task("s1", json.dumps(["__type__:bugfix", "auth", "login"]))
+        store.upsert_session_cost("s1", model="sonnet", cost_usd=1.23,
+                                  input_tok=100, output_tok=50)
+        rows = store.session_rows("/repo-x")
+        self.assertEqual(len(rows), 1)
+        row = rows[0]
+        self.assertEqual(row["session_id"], "s1")
+        self.assertEqual(row["repo_root"], "/repo-x")
+        self.assertEqual(row["cost_usd"], 1.23)
+        self.assertEqual(row["input_tok"], 100)
+        self.assertEqual(row["output_tok"], 50)
+        self.assertIn("bugfix", row["task"])
+
+    def test_scoped_to_repo(self):
+        import store
+        store.set_flag("s1", "repo_root", "/repo-x")
+        store.set_flag("s2", "repo_root", "/repo-y")
+        rows = store.session_rows("/repo-x")
+        self.assertEqual([r["session_id"] for r in rows], ["s1"])
+
+    def test_no_matching_repo_returns_empty(self):
+        import store
+        self.assertEqual(store.session_rows("/nowhere"), [])
+
+
+class TestAgentCLI(unittest.TestCase):
+    """agent-set / agent-get / agent-list / session-list CLI round-trip."""
+
+    def setUp(self):
+        self._tmp = tempfile.mkdtemp()
+        self._store = os.path.join(_SCRIPTS_DIR, "store.py")
+
+    def _run(self, *args):
+        env = os.environ.copy()
+        env["CLAUDE_PLUGIN_DATA"] = self._tmp
+        env["PYTHONPATH"] = _SCRIPTS_DIR + os.pathsep + env.get("PYTHONPATH", "")
+        r = subprocess.run([sys.executable, self._store, *args],
+                           capture_output=True, env=env, timeout=15)
+        return r.stdout.decode(), r.returncode
+
+    def test_agent_set_get_list_roundtrip(self):
+        out, rc = self._run("agent-set", "--id", "a1", "--harness", "claude",
+                            "--model", "sonnet", "--repo", "/repo", "--status", "running",
+                            "--pid", "123", "--log-path", "/tmp/a1.log")
+        self.assertEqual(rc, 0)
+        self.assertEqual(json.loads(out), {"ok": True, "agent_id": "a1"})
+
+        out, rc = self._run("agent-get", "--id", "a1")
+        self.assertEqual(rc, 0)
+        row = json.loads(out)
+        self.assertEqual(row["harness"], "claude")
+        self.assertEqual(row["model"], "sonnet")
+        self.assertEqual(row["repo_root"], "/repo")
+        self.assertEqual(row["pid"], 123)
+
+        out, rc = self._run("agent-list", "--repo", "/repo", "--json")
+        self.assertEqual(rc, 0)
+        rows = json.loads(out)
+        self.assertEqual(len(rows), 1)
+        self.assertEqual(rows[0]["agent_id"], "a1")
+
+    def test_agent_get_absent_prints_null(self):
+        out, rc = self._run("agent-get", "--id", "nope")
+        self.assertEqual(rc, 0)
+        self.assertIsNone(json.loads(out))
+
+    def test_session_list_cli(self):
+        out, rc = self._run("agent-set", "--id", "a1", "--repo", "/repo-cli")
+        self.assertEqual(rc, 0)
+        # Tag a session directly via step-set's sibling path (session_kv) isn't
+        # exposed by a dedicated CLI verb, so exercise session_rows() through
+        # the Python API used by the CLI to seed session_kv/session_cost first.
+        import store
+        old = os.environ.get("CLAUDE_PLUGIN_DATA")
+        os.environ["CLAUDE_PLUGIN_DATA"] = self._tmp
+        try:
+            store.set_flag("sX", "repo_root", "/repo-cli")
+            store.upsert_session_cost("sX", model="sonnet", cost_usd=0.5,
+                                      input_tok=10, output_tok=5)
+        finally:
+            if old is None:
+                os.environ.pop("CLAUDE_PLUGIN_DATA", None)
+            else:
+                os.environ["CLAUDE_PLUGIN_DATA"] = old
+
+        out, rc = self._run("session-list", "--repo", "/repo-cli", "--json")
+        self.assertEqual(rc, 0)
+        rows = json.loads(out)
+        self.assertEqual(len(rows), 1)
+        self.assertEqual(rows[0]["session_id"], "sX")
+        self.assertEqual(rows[0]["cost_usd"], 0.5)
+
+
 if __name__ == "__main__":
     unittest.main()
diff --git a/tests/test_worktree.py b/tests/test_worktree.py
new file mode 100644
index 0000000..464bd3d
--- /dev/null
+++ b/tests/test_worktree.py
@@ -0,0 +1,91 @@
+"""test_worktree.py — stdlib unittest for scripts/worktree.py
+
+Covers: is_dirty tracks tree state; create_worktree checks out HEAD, copies
+configured extras (honouring the ignore list), reuses an existing path, and
+fails open (None) outside a git repo.
+"""
+
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+
+_SCRIPTS_DIR = os.path.join(
+    os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "scripts"
+)
+if _SCRIPTS_DIR not in sys.path:
+    sys.path.insert(0, _SCRIPTS_DIR)
+
+import worktree  # noqa: E402
+
+
+def _git(cwd, *args):
+    subprocess.run(["git", "-C", cwd, *args], capture_output=True, text=True, check=False)
+
+
+def _repo():
+    d = tempfile.mkdtemp()
+    _git(d, "init", "-q")
+    _git(d, "config", "user.email", "t@t")
+    _git(d, "config", "user.name", "t")
+    with open(os.path.join(d, "a.txt"), "w") as f:
+        f.write("hello")
+    _git(d, "add", "a.txt")
+    _git(d, "commit", "-qm", "init")
+    return d
+
+
+class TestIsDirty(unittest.TestCase):
+    def test_clean_then_dirty(self):
+        d = _repo()
+        self.assertFalse(worktree.is_dirty(d))
+        with open(os.path.join(d, "a.txt"), "w") as f:
+            f.write("changed")
+        self.assertTrue(worktree.is_dirty(d))
+
+    def test_untracked_is_dirty(self):
+        d = _repo()
+        with open(os.path.join(d, "new.txt"), "w") as f:
+            f.write("x")
+        self.assertTrue(worktree.is_dirty(d))
+
+    def test_non_repo_not_dirty(self):
+        self.assertFalse(worktree.is_dirty(tempfile.mkdtemp()))
+
+
+class TestCreateWorktree(unittest.TestCase):
+    def test_creates_at_head_and_copies_extras(self):
+        d = _repo()
+        with open(os.path.join(d, ".env"), "w") as f:
+            f.write("SECRET=1")
+        with open(os.path.join(d, "skip.local"), "w") as f:
+            f.write("nope")
+        wt = worktree.create_worktree(
+            d, "feature-abc123",
+            copy_globs=[".env", "*.local"],
+            ignore_globs=["*.local"],
+        )
+        self.assertIsNotNone(wt)
+        self.assertTrue(os.path.isdir(wt))
+        # under .nexum-data/worktrees
+        self.assertIn(os.path.join(".nexum-data", "worktrees"), wt)
+        # tracked file present at HEAD
+        with open(os.path.join(wt, "a.txt")) as f:
+            self.assertEqual(f.read(), "hello")
+        # copied extra present, ignored extra absent
+        self.assertTrue(os.path.exists(os.path.join(wt, ".env")))
+        self.assertFalse(os.path.exists(os.path.join(wt, "skip.local")))
+
+    def test_reuse_returns_same_path(self):
+        d = _repo()
+        wt1 = worktree.create_worktree(d, "fix-deadbe")
+        wt2 = worktree.create_worktree(d, "fix-deadbe")
+        self.assertEqual(wt1, wt2)
+
+    def test_non_repo_returns_none(self):
+        self.assertIsNone(worktree.create_worktree(tempfile.mkdtemp(), "x-000000"))
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tui/Cargo.lock b/tui/Cargo.lock
index 85b86de..1a0626c 100644
--- a/tui/Cargo.lock
+++ b/tui/Cargo.lock
@@ -73,6 +73,21 @@ dependencies = [
  "static_assertions",
 ]
 
+[[package]]
+name = "crew"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "crossterm",
+ "portable-pty",
+ "ratatui",
+ "serde",
+ "serde_json",
+ "tui-term",
+ "tui-textarea",
+ "vt100",
+]
+
 [[package]]
 name = "crossterm"
 version = "0.28.1"
@@ -315,21 +330,6 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
-[[package]]
-name = "nexum-tui"
-version = "0.1.0"
-dependencies = [
- "anyhow",
- "crossterm",
- "portable-pty",
- "ratatui",
- "serde",
- "serde_json",
- "tui-term",
- "tui-textarea",
- "vt100",
-]
-
 [[package]]
 name = "nix"
 version = "0.25.1"
diff --git a/tui/Cargo.toml b/tui/Cargo.toml
index 851f435..6337f59 100644
--- a/tui/Cargo.toml
+++ b/tui/Cargo.toml
@@ -1,11 +1,11 @@
 [package]
-name = "nexum-tui"
+name = "crew"
 version = "0.1.0"
 edition = "2021"
-description = "Companion TUI for nexum: a repo-scoped global view of agents across harnesses."
+description = "crew — a terminal dashboard to run, chat with, and manage coding agents across harnesses (Claude, OpenCode, Cursor). Standalone; optional nexum engine integration."
 
 [[bin]]
-name = "nexum-tui"
+name = "crew"
 path = "src/main.rs"
 
 [dependencies]
diff --git a/tui/README.md b/tui/README.md
index 25493ee..a85f73e 100644
--- a/tui/README.md
+++ b/tui/README.md
@@ -1,7 +1,8 @@
-# nexum-tui
+# crew
 
-A repo-scoped dashboard for running and **chatting with** coding agents across
-harnesses (Claude / OpenCode / Cursor), Rust + [ratatui].
+A terminal dashboard for running, **chatting with**, and **managing** coding
+agents across harnesses (Claude / OpenCode / Cursor). Rust + [ratatui].
+Website + screenshots: `docs/index.html` (GitHub Pages).
 
 Each agent runs its harness's interactive REPL inside a **PTY that the dashboard
 owns**, rendered in an **embedded terminal pane** (via `portable-pty` + `vt100` +
@@ -9,27 +10,43 @@ owns**, rendered in an **embedded terminal pane** (via `portable-pty` + `vt100`
 chat **inside the TUI**, side-by-side with the agent list; `Ctrl-o` returns to the
 dashboard. No tmux, no switching windows.
 
-**Requires:** `python3` (the engine) and whichever harness CLIs you launch
-(`claude`, `opencode`, `cursor-agent`).
+## Standalone — no backend required
 
-**Quit & resume.** Live agents end when you quit (you get a confirmation first).
-But each launch is persisted to `.nexum-data/tui-agents.json` and its git worktree
-is kept, so on the next run the agent shows as **▷ resumable** — press `enter` to
-relaunch the harness with its resume flag (`claude --continue`, `opencode
---continue`, `cursor-agent --resume`) in the same worktree, continuing the
-conversation. Resume commands are overridable via `NEXUM_RESUME_CMD_<HARNESS>`.
+crew runs on its own: it creates git worktrees **natively** (a `crew/<task>`
+branch under `.crew/worktrees/`), keeps its own registry in `.crew/agents.json`,
+and needs only `git` + whichever agent CLI you launch (`claude`, `opencode`,
+`cursor-agent`). From the dashboard you can review diffs, tail logs, and
+**commit + push + open a PR** (`gh`) — all without any external service.
+
+**Optional nexum engine.** If a nexum Python engine sits alongside crew
+(`scripts/store.py`, `dispatch.py`), the header shows a `⚙ engine` badge and crew
+*additionally* surfaces the engine's **observed** plugin sessions and **headless
+delegated** agents, and enables `R` retry via `dispatch.py`. Absent the engine,
+those features simply don't appear — nothing breaks.
+
+**Quit & resume.** Live agents end when you quit (confirmation first). Each launch
+is persisted to `.crew/agents.json` and its worktree kept, so on the next run the
+agent shows as **▷ resumable** — `enter` relaunches the harness with its resume
+flag (`claude --continue`, `opencode --continue`, `cursor-agent --resume`) in the
+same worktree. Overridable via `NEXUM_RESUME_CMD_<HARNESS>`.
 
 [tui-term]: https://crates.io/crates/tui-term
 
-It shows two classes of agent for the current repo:
+## Compared to other TUIs
 
-- **managed** — agents nexum launched (rows in the `agents` table), with full
-  control: stop, tail logs, reveal worktree.
-- **observed** — normal plugin sessions writing to `nexum.db` (read-only).
+Inspired by lazygit / k9s / claude-squad; built for agents.
 
-The TUI never touches SQLite directly — it shells the Python engine
-(`python3 <repo>/scripts/store.py … --json`, `dispatch.py …`), so `store.py`
-stays the single source of truth for the schema.
+| capability | crew | claude-squad | lazygit | k9s |
+|---|:--:|:--:|:--:|:--:|
+| multiple agents, one view | ✓ | ✓ | ✓ | · |
+| embedded chat (no tmux) | ✓ | — | — | — |
+| per-agent git worktree | ✓ | ✓ | — | — |
+| cross-harness | ✓ | · | — | — |
+| diff viewer | ✓ | ✓ | ✓ | · |
+| live log follow | ✓ | · | — | ✓ |
+| commit · push · PR | ✓ | · | ✓ | — |
+| multi-select bulk ops | ✓ | · | — | ✓ |
+| runs standalone | ✓ | ✓ | ✓ | ✓ |
 
 ## Build
 
@@ -38,25 +55,33 @@ cd tui
 cargo build --release
 ```
 
-The binary lands at `tui/target/release/nexum-tui`.
+The binary lands at `tui/target/release/crew`. Regenerate the website after UI
+changes with `python3 site/gen.py` (captures live `--snapshot` frames).
 
 ## Run
 
 From anywhere inside a repo (it resolves the git toplevel and scopes to it):
 
 ```
-nexum-tui                         # interactive dashboard
-nexum-tui --new "fix the bug"     # launch an agent from the shell, print its session
-nexum-tui --new "…" --harness opencode --model anthropic/claude-opus-4
-nexum-tui --dump                  # print the agent list once and exit (no TTY)
-nexum-tui --snapshot              # render one real frame to text (visual smoke, no TTY)
-nexum-tui --scripts DIR           # override the scripts dir (default <repo>/scripts)
+crew                              # interactive dashboard
+crew --new "fix the bug"          # create a worktree + run the harness headless in it
+crew --new "…" --harness cursor --model auto
+crew --new "quick fix" --here     # run in the current repo (no new worktree)
+crew --dump                       # print the agent list once and exit (no TTY)
+crew --snapshot                   # render one real frame to text (visual smoke, no TTY)
+crew --scripts DIR                # override the optional engine scripts dir
+crew --doctor                     # check git / harness CLIs / gh / engine
 ```
 
+`--new` is fully standalone: it makes a `crew/<slug>` worktree and runs the
+harness one-shot in it (streaming to your terminal), then prints the branch +
+worktree path.
+
 Environment:
-- `NEXUM_SCRIPTS` — scripts dir (same as `--scripts`).
-- `NEXUM_PYTHON` — python interpreter (default `python3`).
-- `CLAUDE_PLUGIN_DATA` — inherited by the Python engine to pick the data dir / DB.
+- `NEXUM_SCRIPTS` — optional engine scripts dir (same as `--scripts`).
+- `NEXUM_PYTHON` — python interpreter for the optional engine (default `python3`).
+- `NEXUM_HEADLESS_CMD_<HARNESS>` — override the `--new` headless command.
+- `NEXUM_INTERACTIVE_CMD_<HARNESS>` / `NEXUM_RESUME_CMD_<HARNESS>` — override REPL / resume argv.
 
 ## Layout
 
@@ -101,30 +126,57 @@ preview on the right.
 
 | key | action |
 |-----|--------|
-| `j`/`k` or `↑`/`↓` | move selection |
-| `n` | new agent form (multiline task, harness/model/worktree pickers, image attach); `Ctrl-S` to launch |
+| `j`/`k` or `↑`/`↓` | move selection · `g`/`G` top/bottom · `]`/`[` next/prev **failed** |
+| `space` / `A` | mark row / mark all for bulk ops · `esc` clears marks |
+| mouse click / wheel | select a row · scroll the list |
+| `1` `2` `3` `4` | quick-filter: all / running / agents / sessions |
+| `t` | cycle sort: status → cost → recent |
+| `n` | new agent form (multiline task, workflow/harness/model/worktree pickers, image attach); `Ctrl-S` to launch |
 | `enter` | chat with a live agent, or **resume** a `▷` persisted one |
+| `shift-tab` | (in chat) forwarded to the agent — cycles Claude Code's modes (plan / auto-accept) |
+| `D` | duplicate the selected agent into a prefilled new-agent form |
 | `Ctrl-o` | leave the terminal, back to the dashboard |
 | `q` | quit (confirms if agents are running) |
-| `s` | stop the selected agent (`y` to confirm) |
-| `o` | show the selected agent's worktree path |
-| `x` | remove the selected agent |
+| `d` | review the worktree diff (colored, scrollbar); `/` searches, `n`/`N` cycle matches |
+| `l` | tail a headless/delegated agent's log — **live-follows** (tail -f) when parked at the bottom; scroll up to pause, `G` to re-follow, `/` search, `r` reload |
+| `P` | commit + push the worktree (or **all marked**) and open a PR (`gh`) |
+| `R` | **retry / re-delegate** the selected task to a harness you pick (runs headless in a fresh worktree) |
+| `s` | stop the selected agent — or **all marked** if any (`y` to confirm) |
+| `S` | stop **all** running agents (`y` to confirm) |
+| `o` / `y` / `Y` | worktree path · yank path · yank branch |
+| `e` / `!` | open the worktree in `$EDITOR` · drop to a `$SHELL` there |
+| `O` | open the agent's **PR** (if one is open) or its branch on the remote |
+| `,` | settings — edit persisted default harness/model/workflow/worktree |
+| `L` | label / rename a crew-launched agent (shown instead of the task) |
+| `x` | remove the selected agent — or **all marked** (confirmed) |
+| `c` | clear finished (exited + resumable) rows |
 | `/` | search · `h` toggle observed sessions |
-| mouse wheel | scroll the agent list |
 
 ### New-agent form
 
 - **task** — a multiline editor (Enter inserts a newline).
+- **workflow** — how the task runs, cycled with `←`/`→`:
+  - `chat (single agent)` — plain interactive session.
+  - `plan → build (same harness)` — seeds `/nx-plan` then `/nx-build`.
+  - `plan → build on cursor` / `… on opencode` — seeds `/nx-build --harness X`,
+    so the plan is decomposed then every step executed on that harness.
+  - `plan only (stop for review)` — seeds `/nx-plan` and stops, so you review
+    the plan before any code is written.
 - **harness / model / worktree** — `‹ … ›` pickers, change with `←`/`→`.
   Worktree = *new isolated git worktree* or *current repo*.
 - **images** — attach image paths (`a` add, `d` remove); appended to the prompt.
 - **`Ctrl-S`** launches (Enter is reserved for the task editor).
-| `/` | incremental search (`esc` clears, `enter` keeps) |
-| `a` | toggle active-only (live PID) |
-| `h` | toggle observed sessions |
-| `r` | refresh now (auto every ~1.5s) |
-| `?` | help overlay |
-| `q` | quit (in log/help view, `q`/`esc` returns to the table) |
+
+Row glyphs: `●` running · `✓` done · `✗` failed · `▷` resumable · `±` uncommitted
+changes · `◉` marked.
+
+### Look & feel
+
+Rounded panels with a focus-lit accent border, an animated braille spinner on
+running agents, per-harness colored names (claude/cursor/opencode), inline cost,
+a header status legend (`●running ✓done ✗failed`) + total metered cost + current
+git branch, a btop-style context-fill meter in the detail pane, and scrollbars
+on the diff/log viewers. `?` opens a grouped keybinding cheatsheet.
 
 ## Architecture
 
@@ -137,11 +189,32 @@ nexum-tui ──subprocess JSON──> python3 scripts/store.py agent-list/sessi
 worktree, runs the chosen harness headless, verifies with `guardrail.py`, and
 records the `agents`/`step_ledger`/`usage` rows the TUI reads back.
 
+## Delegation MCP
+
+`scripts/mcp_server.py` is an MCP (stdio) server — registered in `.mcp.json` as
+`nexum-delegate` — that lets one agent **delegate work to another harness** as a
+managed sub-agent. From inside a Claude session you call the `delegate` tool
+(`harness`, `task`, optional `model` / `acceptance` / `files`); it runs the same
+`dispatch.py` path (worktree → headless harness → guardrail → verdict) and
+returns `{pass, diff, cost_usd, agent_id, worktree}`. Because dispatch records
+the `agents` row, **the delegated sub-agent shows up live in this TUI** while it
+runs — select it and press `l` to tail its log, `d` to review its diff.
+
+Tools:
+- `delegate(harness, task, …)` — blocking; returns the full verdict.
+- `delegate_async(harness, task, …)` — returns an `agent_id` immediately (runs
+  detached), so an orchestrator can fan out many sub-agents without holding its
+  turn open. Poll each with `check(agent_id)` (status → diff once done).
+- `list_agents(active_only?)` — the TUI's managed-agent list.
+
+So the plan→build workflow above (Claude decomposes, then delegates each step to
+cursor/opencode) is observable and controllable from one screen.
+
 ## Future work
 
 - Auto route→harness offload (pick the cheapest capable harness per plan step),
   fed by `route_calibration`.
 - Interactive attach/takeover (tmux) for hands-on driving of a running agent.
-- Launch a whole plan across a harness from the TUI (currently per-agent).
+- Retry / re-delegate a failed agent to another harness from the TUI.
 
 [ratatui]: https://ratatui.rs
diff --git a/tui/site/gen.py b/tui/site/gen.py
new file mode 100644
index 0000000..ad53e03
--- /dev/null
+++ b/tui/site/gen.py
@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+"""gen.py — build the crew GitHub Pages site (docs/index.html).
+
+Captures live terminal frames from the built `crew` binary (`--snapshot` in
+several modes), escapes them into styled faux-terminal panes, and writes a
+self-contained static page. Reproducible: re-run after UI changes to refresh the
+screenshots.
+
+    cd tui && cargo build && python3 site/gen.py
+"""
+from __future__ import annotations
+
+import html
+import os
+import subprocess
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+TUI = os.path.dirname(HERE)
+REPO = os.path.dirname(TUI)
+BIN = os.path.join(TUI, "target", "release", "crew")
+if not os.path.exists(BIN):
+    BIN = os.path.join(TUI, "target", "debug", "crew")
+OUT = os.path.join(REPO, "docs", "index.html")
+
+
+def snap(mode: str | None) -> str:
+    """Capture one --snapshot frame in the given NEXUM_SNAPSHOT_MODE."""
+    env = os.environ.copy()
+    if mode:
+        env["NEXUM_SNAPSHOT_MODE"] = mode
+    if mode in ("term",):
+        env["NEXUM_INTERACTIVE_CMD_CLAUDE"] = "cat"
+    try:
+        out = subprocess.run([BIN, "--snapshot"], capture_output=True, text=True,
+                             env=env, timeout=30).stdout
+    except Exception as exc:  # never fail the build over a snapshot
+        out = f"(snapshot unavailable: {exc})"
+    return out.rstrip("\n")
+
+
+def pane(title: str, body: str) -> str:
+    dots = '<span class="d r"></span><span class="d y"></span><span class="d g"></span>'
+    return (f'<figure class="term"><figcaption>{dots}<span class="t">{html.escape(title)}'
+            f'</span></figcaption><pre>{html.escape(body)}</pre></figure>')
+
+
+FEATURES = [
+    ("🖥️", "Agents inside the TUI", "Every agent runs its harness REPL in a PTY rendered in an embedded pane. Select one, press enter, chat side-by-side. No tmux, no window juggling."),
+    ("🌿", "Isolated worktrees", "Each agent runs in its own git worktree on a <code>crew/&lt;task&gt;</code> branch — created natively, no external tooling. Work never tangles."),
+    ("🔀", "Any harness", "Claude Code, OpenCode, Cursor — launch, resume, and manage them side by side, each with its own model."),
+    ("🔎", "Diff &amp; log viewers", "Review a worktree diff (colored, searchable) or tail a log that live-follows like <code>tail -f</code>. Scrollbars, <code>/</code> search, <code>n/N</code>."),
+    ("🚀", "Ship from the TUI", "<code>P</code> commits, pushes the branch, and opens a PR with <code>gh</code> — straight from the dashboard, lazygit-style."),
+    ("✔️", "Manage the fleet", "Multi-select with <code>space</code>, bulk stop/remove, quick-filters <code>1-4</code>, sort by status/cost/recent, jump between failed with <code>]</code>/<code>[</code>."),
+]
+
+# feature parity — ✓ has it, · partial, — none
+COMPARE = [
+    ("Multiple agents in one view", "✓", "✓", "✓", "·"),
+    ("Embedded chat (no tmux)", "✓", "—", "—", "—"),
+    ("Per-agent git worktree", "✓", "✓", "—", "—"),
+    ("Cross-harness (Claude/Cursor/OpenCode)", "✓", "·", "—", "—"),
+    ("Diff viewer", "✓", "✓", "✓", "·"),
+    ("Live log follow", "✓", "·", "—", "✓"),
+    ("Commit · push · PR", "✓", "·", "✓", "—"),
+    ("Multi-select bulk actions", "✓", "·", "—", "✓"),
+    ("Runs standalone (no backend)", "✓", "✓", "✓", "✓"),
+]
+COMPARE_COLS = ["crew", "claude-squad", "lazygit", "k9s"]
+
+
+def build() -> str:
+    hero = pane("crew · dashboard", snap("demo"))
+    shots = [
+        pane("launch — workflow picker", snap("new")),
+        pane("embedded chat", snap("term")),
+        pane("grouped help (?)", snap("help")),
+    ]
+    fcards = "".join(
+        f'<div class="card"><div class="ic">{i}</div><h3>{t}</h3><p>{d}</p></div>'
+        for i, t, d in FEATURES)
+
+    head = "".join(f"<th>{c}</th>" for c in COMPARE_COLS)
+    rows = ""
+    for row in COMPARE:
+        label, *cells = row
+        tds = ""
+        for i, c in enumerate(cells):
+            cls = {"✓": "yes", "·": "part", "—": "no"}.get(c, "")
+            own = " own" if i == 0 else ""
+            tds += f'<td class="{cls}{own}">{c}</td>'
+        rows += f"<tr><td class=lbl>{label}</td>{tds}</tr>"
+
+    gallery = "".join(f'<div class="shot">{s}</div>' for s in shots)
+
+    return TEMPLATE.format(hero=hero, features=fcards, chead=head, crows=rows, gallery=gallery)
+
+
+TEMPLATE = """<!doctype html>
+<html lang=en data-theme=dark>
+<head>
+<meta charset=utf-8>
+<meta name=viewport content="width=device-width, initial-scale=1">
+<title>crew — a terminal dashboard for coding agents</title>
+<meta name=description content="crew runs, chats with, and manages coding agents (Claude, OpenCode, Cursor) across git worktrees — from one terminal dashboard.">
+<style>
+:root{{--bg:#0b0e14;--panel:#0d1117;--ink:#e6edf3;--dim:#8b949e;--line:#232a34;--acc:#39d0d8;--acc2:#7c5cff;--green:#3fb950;--red:#f85149;--yellow:#e3b341}}
+*{{box-sizing:border-box}}
+body{{margin:0;background:radial-gradient(1200px 600px at 70% -10%,#16202e 0,var(--bg) 60%);color:var(--ink);font:16px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif}}
+.wrap{{max-width:1080px;margin:0 auto;padding:0 20px}}
+a{{color:var(--acc)}}
+header.top{{padding:16px 0;display:flex;align-items:center;gap:12px}}
+.logo{{font-weight:800;font-size:20px;letter-spacing:.5px}}
+.logo b{{background:var(--acc2);color:#fff;padding:2px 8px;border-radius:6px}}
+.nav{{margin-left:auto;display:flex;gap:18px;font-size:14px}}
+.nav a{{color:var(--dim);text-decoration:none}}
+.hero{{text-align:center;padding:48px 0 12px}}
+.hero h1{{font-size:clamp(30px,6vw,54px);line-height:1.05;margin:.2em 0}}
+.hero h1 .g{{background:linear-gradient(90deg,var(--acc),var(--acc2));-webkit-background-clip:text;background-clip:text;color:transparent}}
+.hero p{{font-size:19px;color:var(--dim);max-width:640px;margin:12px auto 24px}}
+.cta{{display:inline-flex;gap:12px;flex-wrap:wrap;justify-content:center}}
+.btn{{display:inline-block;padding:11px 20px;border-radius:9px;font-weight:600;text-decoration:none}}
+.btn.p{{background:var(--acc);color:#04121a}}
+.btn.s{{border:1px solid var(--line);color:var(--ink)}}
+.term{{margin:0;border:1px solid var(--line);border-radius:12px;overflow:hidden;background:var(--panel);box-shadow:0 24px 60px -30px #000}}
+.term figcaption{{display:flex;align-items:center;gap:8px;padding:9px 12px;background:#11161f;border-bottom:1px solid var(--line);font-size:12px;color:var(--dim)}}
+.term .d{{width:11px;height:11px;border-radius:50%;display:inline-block}}
+.term .d.r{{background:#ff5f56}}.term .d.y{{background:#ffbd2e}}.term .d.g{{background:#27c93f}}
+.term .t{{margin-left:6px}}
+.term pre{{margin:0;padding:16px;overflow-x:auto;font:13px/1.32 ui-monospace,"SF Mono",Menlo,Consolas,monospace;color:#cdd9e5;white-space:pre}}
+.heroshot{{margin:26px 0 8px}}
+section{{padding:40px 0}}
+h2{{font-size:28px;text-align:center;margin:0 0 6px}}
+.sub{{text-align:center;color:var(--dim);margin:0 0 28px}}
+.grid{{display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:18px}}
+.card{{background:var(--panel);border:1px solid var(--line);border-radius:12px;padding:20px}}
+.card .ic{{font-size:24px}}
+.card h3{{margin:.5em 0 .3em;font-size:17px}}
+.card p{{margin:0;color:var(--dim);font-size:14.5px}}
+.card code,td code{{background:#1b2230;padding:1px 5px;border-radius:5px;font-size:.9em;color:#b7c5d3}}
+table{{width:100%;border-collapse:collapse;font-size:14.5px;overflow:hidden;border-radius:12px;border:1px solid var(--line)}}
+th,td{{padding:11px 12px;text-align:center;border-bottom:1px solid var(--line)}}
+th{{background:#11161f;font-size:13px;color:var(--dim);font-weight:600}}
+th:first-child,td.lbl{{text-align:left}}
+td.lbl{{color:var(--ink)}}
+th:nth-child(2){{color:var(--acc)}}
+td.own{{background:#0f1a22}}
+td.yes{{color:var(--green);font-weight:700}}
+td.part{{color:var(--yellow)}}
+td.no{{color:#4b5563}}
+.gallery{{display:grid;grid-template-columns:1fr 1fr;gap:18px}}
+.shot .term pre{{font-size:11px;line-height:1.28}}
+pre.code{{background:var(--panel);border:1px solid var(--line);border-radius:10px;padding:16px;overflow-x:auto;font:13.5px/1.6 ui-monospace,Menlo,monospace;color:#cdd9e5}}
+.callout{{border:1px solid var(--line);border-left:3px solid var(--acc2);background:#0f1320;border-radius:10px;padding:16px 18px;color:var(--dim)}}
+footer{{text-align:center;color:var(--dim);padding:40px 0;font-size:13px;border-top:1px solid var(--line);margin-top:20px}}
+@media(max-width:760px){{.gallery{{grid-template-columns:1fr}}.nav{{display:none}}}}
+</style>
+</head>
+<body>
+<div class=wrap>
+<header class=top>
+  <span class=logo><b>crew</b></span>
+  <nav class=nav>
+    <a href=#features>Features</a><a href=#compare>Compare</a><a href=#shots>Screens</a><a href=#install>Install</a>
+  </nav>
+</header>
+
+<section class=hero>
+  <h1>Run a <span class=g>crew of coding agents</span><br>from one terminal.</h1>
+  <p>crew launches, chats with, and manages Claude&nbsp;Code, OpenCode &amp; Cursor agents — each in its own git worktree — without leaving your terminal. Standalone Rust + ratatui.</p>
+  <div class=cta>
+    <a class="btn p" href=#install>Get started</a>
+    <a class="btn s" href=#features>See features</a>
+  </div>
+  <div class=heroshot>{hero}</div>
+</section>
+
+<section id=features>
+  <h2>Everything, one keystroke away</h2>
+  <p class=sub>A master–detail dashboard that treats agents like a first-class resource.</p>
+  <div class=grid>{features}</div>
+</section>
+
+<section id=compare>
+  <h2>How it compares</h2>
+  <p class=sub>Inspired by the best terminal tools — built for agents.</p>
+  <table>
+    <thead><tr><th>Capability</th>{chead}</tr></thead>
+    <tbody>{crows}</tbody>
+  </table>
+</section>
+
+<section id=shots>
+  <h2>Screens</h2>
+  <p class=sub>Real frames rendered by the binary.</p>
+  <div class=gallery>{gallery}</div>
+</section>
+
+<section id=install>
+  <h2>Install &amp; run</h2>
+  <p class=sub>One binary. No backend required.</p>
+  <pre class=code># build
+cd tui &amp;&amp; cargo build --release
+
+# run from anywhere inside a git repo
+./target/release/crew
+
+# …or launch headless from the shell (creates a worktree, runs the harness)
+./target/release/crew --new "add billing endpoint" --harness cursor
+
+# in the dashboard: [n] launch · [enter] chat · [P] push+PR · [?] keymap</pre>
+  <p></p>
+  <div class=callout><b>Standalone by default.</b> crew creates worktrees natively and keeps its own registry under <code>.crew/</code> — it needs only <code>git</code> and whichever agent CLI you launch. Drop in the optional nexum engine and it also surfaces observed sessions and headless delegation.</div>
+</section>
+
+<footer>
+  crew — a terminal dashboard for coding agents · Rust + <a href="https://ratatui.rs">ratatui</a>
+</footer>
+</div>
+</body>
+</html>
+"""
+
+
+def main() -> None:
+    if not os.path.exists(BIN):
+        print(f"crew binary not found at {BIN}; run `cargo build` first", file=sys.stderr)
+        sys.exit(1)
+    os.makedirs(os.path.dirname(OUT), exist_ok=True)
+    with open(OUT, "w", encoding="utf-8") as fh:
+        fh.write(build())
+    print(f"wrote {OUT}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/tui/src/agent.rs b/tui/src/agent.rs
index ed0f7c1..412d606 100644
--- a/tui/src/agent.rs
+++ b/tui/src/agent.rs
@@ -15,6 +15,25 @@ pub struct Session {
     pub updated_ts: Option<f64>,
 }
 
+/// A row from the SQLite `agents` table (`store.py agent-list --json`): a
+/// headless sub-agent delegated via dispatch.py / the delegation MCP. Extra
+/// columns are ignored; every field is optional to stay forward-compatible.
+#[derive(Debug, Clone, Deserialize)]
+pub struct ManagedAgent {
+    pub agent_id: String,
+    pub harness: Option<String>,
+    pub model: Option<String>,
+    pub worktree: Option<String>,
+    pub branch: Option<String>,
+    pub status: Option<String>,
+    pub cost_usd: Option<f64>,
+    pub task: Option<String>,
+    pub step_index: Option<i64>,
+    pub updated_ts: Option<f64>,
+    pub pid: Option<i64>,
+    pub log_path: Option<String>,
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Kind {
     Managed,
@@ -49,6 +68,18 @@ pub struct Row {
     pub proc_idx: Option<usize>,
     /// A persisted-but-not-running agent that can be resumed in its worktree.
     pub resumable: bool,
+    /// Optional friendly label (from the registry) shown instead of the task.
+    pub label: Option<String>,
+}
+
+impl Row {
+    /// What to show in the list: the label if set, else the task.
+    pub fn display(&self) -> &str {
+        match &self.label {
+            Some(l) if !l.is_empty() => l.as_str(),
+            _ => &self.task,
+        }
+    }
 }
 
 fn s(o: &Option<String>, dflt: &str) -> String {
@@ -72,7 +103,7 @@ impl Row {
             status: if alive { "running".into() } else { "exited".into() },
             cost_usd: 0.0,
             ctx_pct: None,
-            updated_ts: 0.0,
+            updated_ts: p.started, // show how long it's been running
             pid: None,
             worktree: Some(p.worktree.clone()),
             log_path: None,
@@ -83,6 +114,7 @@ impl Row {
             interactive: true,
             proc_idx: Some(idx),
             resumable: false,
+            label: None,
         }
     }
 
@@ -109,6 +141,34 @@ impl Row {
             interactive: false,
             proc_idx: None,
             resumable: true,
+            label: rec.label.clone(),
+        }
+    }
+
+    /// A headless sub-agent delegated via dispatch/MCP (SQLite `agents` row).
+    pub fn from_managed(a: &ManagedAgent) -> Row {
+        Row {
+            kind: Kind::Managed,
+            id: a.agent_id.clone(),
+            harness: a.harness.clone().unwrap_or_else(|| "?".into()),
+            model: a.model.clone().unwrap_or_default(),
+            task: a.task.clone().unwrap_or_default(),
+            branch: a.branch.clone().unwrap_or_default(),
+            status: a.status.clone().unwrap_or_else(|| "exited".into()),
+            cost_usd: a.cost_usd.unwrap_or(0.0),
+            ctx_pct: None,
+            updated_ts: a.updated_ts.unwrap_or(0.0),
+            pid: a.pid,
+            worktree: a.worktree.clone(),
+            log_path: a.log_path.clone(),
+            plan_hash: None,
+            session_id: None,
+            step_index: a.step_index,
+            steps: None,
+            interactive: false,
+            proc_idx: None,
+            resumable: false,
+            label: None,
         }
     }
 
@@ -134,6 +194,7 @@ impl Row {
             interactive: false,
             proc_idx: None,
             resumable: false,
+            label: None,
         }
     }
 }
@@ -168,6 +229,19 @@ mod tests {
         assert_eq!(rel_time(100.0, 100.0 + 7200.0), "2h ago");
     }
 
+    #[test]
+    fn live_row_carries_start_time() {
+        let dir = std::env::temp_dir().to_string_lossy().to_string();
+        let argv = vec!["cat".to_string()];
+        let mut p = crate::pty::AgentProc::spawn(
+            "t".into(), "stub".into(), "m".into(), String::new(), dir, &argv, 24, 80,
+        ).unwrap();
+        let r = Row::from_proc(0, &mut p);
+        assert!(r.updated_ts > 0.0);
+        assert_eq!(r.updated_ts, p.started);
+        p.kill();
+    }
+
     #[test]
     fn session_row_is_observed() {
         let sess = Session {
diff --git a/tui/src/app.rs b/tui/src/app.rs
index c9e65e3..2e3c0c9 100644
--- a/tui/src/app.rs
+++ b/tui/src/app.rs
@@ -7,7 +7,7 @@ use crate::agent::Row;
 use crate::pty::AgentProc;
 use crate::store::{AgentRecord, Store};
 use anyhow::Result;
-use std::collections::HashSet;
+use std::collections::{HashMap, HashSet};
 use tui_textarea::TextArea;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -16,16 +16,102 @@ pub enum Mode {
     NewAgent,
     Help,
     ConfirmStop,
+    ConfirmStopAll,
     ConfirmQuit,
+    /// Confirm committing + pushing the selected worktree (+ opening a PR).
+    ConfirmPush,
+    /// Edit persisted launch defaults.
+    Settings,
+    /// Confirm removing the marked agents (bulk).
+    ConfirmRemove,
+    /// Text entry to label the selected agent.
+    Rename,
     /// Esc pressed in the new-agent form with unsaved input — confirm discard.
     ConfirmDiscard,
     Filter,
     /// Focused into the selected agent's embedded terminal — keys go to the PTY.
     Terminal,
+    /// Scrollable view of the selected agent's worktree diff.
+    Diff,
+    /// Scrollable tail of a headless agent's log file.
+    Log,
+    /// Pick a harness to re-delegate (retry) the selected row's task on.
+    Retry,
 }
 
 pub const HARNESSES: [&str; 3] = ["claude", "opencode", "cursor"];
 
+/// Quick category filter (k9s-style number keys). Narrows the list to one class.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Category {
+    All,
+    Running,
+    Agents,   // managed (nexum-launched / delegated), not observed sessions
+    Sessions, // observed plugin sessions
+}
+
+impl Category {
+    pub fn label(self) -> &'static str {
+        match self {
+            Category::All => "all",
+            Category::Running => "running",
+            Category::Agents => "agents",
+            Category::Sessions => "sessions",
+        }
+    }
+    pub fn from_key(s: &str) -> Category {
+        match s {
+            "running" => Category::Running,
+            "agents" => Category::Agents,
+            "sessions" => Category::Sessions,
+            _ => Category::All,
+        }
+    }
+}
+
+/// Sort order for the list, cycled with `t`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SortKey {
+    Status, // default: running → failed → resumable → done → exited → observed
+    Cost,   // most expensive first
+    Recent, // most recently updated first
+}
+
+impl SortKey {
+    pub fn label(self) -> &'static str {
+        match self {
+            SortKey::Status => "status",
+            SortKey::Cost => "cost",
+            SortKey::Recent => "recent",
+        }
+    }
+    pub fn next(self) -> SortKey {
+        match self {
+            SortKey::Status => SortKey::Cost,
+            SortKey::Cost => SortKey::Recent,
+            SortKey::Recent => SortKey::Status,
+        }
+    }
+    pub fn from_key(s: &str) -> SortKey {
+        match s {
+            "cost" => SortKey::Cost,
+            "recent" => SortKey::Recent,
+            _ => SortKey::Status,
+        }
+    }
+}
+
+/// Execution workflows the launcher can seed. Index 0 = plain single agent; the
+/// rest steer how a plan gets executed (which harness runs the build, or stop
+/// after planning for review).
+pub const WORKFLOWS: [&str; 5] = [
+    "chat (single agent)",
+    "plan → build (same harness)",
+    "plan → build on cursor",
+    "plan → build on opencode",
+    "plan only (stop for review)",
+];
+
 /// Model presets per harness — pick with ←/→ instead of typing.
 pub fn model_presets(harness_idx: usize) -> &'static [&'static str] {
     match harness_idx {
@@ -37,14 +123,18 @@ pub fn model_presets(harness_idx: usize) -> &'static [&'static str] {
 
 // New-agent form fields (task is a multiline editor and comes first).
 pub const FIELD_TASK: usize = 0;
-pub const FIELD_HARNESS: usize = 1;
-pub const FIELD_MODEL: usize = 2;
-pub const FIELD_WORKTREE: usize = 3;
-pub const FIELD_IMAGES: usize = 4;
-pub const FIELD_COUNT: usize = 5;
+pub const FIELD_WORKFLOW: usize = 1;
+pub const FIELD_HARNESS: usize = 2;
+pub const FIELD_MODEL: usize = 3;
+pub const FIELD_WORKTREE: usize = 4;
+pub const FIELD_IMAGES: usize = 5;
+pub const FIELD_COUNT: usize = 6;
 
 pub struct NewAgentForm {
     pub task: TextArea<'static>,
+    /// Index into WORKFLOWS: how the task is executed (plain chat, or plan→build
+    /// steered to a harness, or plan-only for review).
+    pub workflow_idx: usize,
     pub harness_idx: usize,
     pub model_idx: usize,
     /// true → isolate in a fresh git worktree; false → run in the repo itself.
@@ -63,6 +153,7 @@ impl Default for NewAgentForm {
         task.set_placeholder_text("Describe the task… (Enter = newline)");
         NewAgentForm {
             task,
+            workflow_idx: 0,
             harness_idx: 0,
             model_idx: 0,
             worktree_new: true,
@@ -86,6 +177,13 @@ impl NewAgentForm {
         let n = model_presets(self.harness_idx).len() as i64;
         self.model_idx = (((self.model_idx as i64 + d) % n + n) % n) as usize;
     }
+    pub fn workflow(&self) -> &'static str {
+        WORKFLOWS[self.workflow_idx.min(WORKFLOWS.len() - 1)]
+    }
+    pub fn cycle_workflow(&mut self, d: i64) {
+        let n = WORKFLOWS.len() as i64;
+        self.workflow_idx = (((self.workflow_idx as i64 + d) % n + n) % n) as usize;
+    }
     pub fn cycle_harness(&mut self, d: i64) {
         let n = HARNESSES.len() as i64;
         self.harness_idx = (((self.harness_idx as i64 + d) % n + n) % n) as usize;
@@ -94,9 +192,25 @@ impl NewAgentForm {
     pub fn task_text(&self) -> String {
         self.task.lines().join("\n")
     }
-    /// Full prompt sent to the agent: task plus any attached image paths.
+    /// Full prompt sent to the agent: task wrapped in the selected workflow's
+    /// seed instruction, plus any attached image paths.
     pub fn full_prompt(&self) -> String {
-        let mut s = self.task_text();
+        let task = self.task_text();
+        let mut s = match self.workflow_idx {
+            1 => format!(
+                "Run /nx-plan to decompose this into routed steps, then /nx-build to \
+                 dispatch each step to the cheapest capable agent.\n\nTask: {}", task),
+            2 => format!(
+                "Run /nx-plan to decompose this, then /nx-build --harness cursor to \
+                 execute every step on the cursor harness.\n\nTask: {}", task),
+            3 => format!(
+                "Run /nx-plan to decompose this, then /nx-build --harness opencode to \
+                 execute every step on the opencode harness.\n\nTask: {}", task),
+            4 => format!(
+                "Run /nx-plan to decompose this into routed steps. STOP after planning \
+                 — print the plan and wait for review; do not start execution.\n\nTask: {}", task),
+            _ => task,
+        };
         for img in &self.images {
             s.push_str(&format!("\n[image] {}", img));
         }
@@ -119,13 +233,58 @@ pub struct App {
     pub show_observed: bool,
     pub all_rows: Vec<Row>,
     pub filter_text: String,
+    pub category: Category,
+    pub sort: SortKey,
     /// Size (cols, rows) the terminal pane was last rendered at — used to resize.
     pub term_size: (u16, u16),
+    /// Scroll offset for the help overlay (fits short terminals).
+    pub help_scroll: u16,
+    /// Diff text + scroll offset for the Diff view.
+    pub diff_text: String,
+    pub diff_scroll: u16,
+    /// Log text + scroll offset for the Log view.
+    pub log_text: String,
+    pub log_scroll: u16,
+    /// Path of the log currently open in the Log view (for live follow).
+    pub log_path_open: Option<String>,
+    /// In-viewer (diff/log) incremental search: query + whether we're typing it.
+    pub find_query: String,
+    pub find_input: bool,
+    /// Current git branch of the repo root (shown in the header, k9s-style).
+    pub repo_branch: String,
+    /// Retry modal state: the task to re-delegate + which harness is selected.
+    pub retry_task: String,
+    pub retry_harness_idx: usize,
+    /// Multi-select: ids of marked rows for bulk stop/remove.
+    pub marked: HashSet<String>,
+    /// Queue of (worktree, branch, commit-msg) to commit+push (1 = selected,
+    /// many = the marked set).
+    pub push_queue: Vec<(String, String, String)>,
+    /// Last-seen status per agent id — to notify on running→done/failed.
+    pub prev_status: HashMap<String, String>,
+    /// When set, the event loop suspends the TUI, runs (cwd, argv), then restores
+    /// — used to open an editor or a shell in a worktree.
+    pub pending_shell: Option<(String, Vec<String>)>,
+    /// Working copy of launch defaults while the Settings modal is open.
+    pub settings: Option<crate::store::LaunchPrefs>,
+    pub settings_field: usize,
+    /// Text buffer while labeling an agent (Mode::Rename).
+    pub rename_buf: String,
+    /// Cached git status of the selected worktree: (path, summary, is_clean).
+    pub worktree_status: Option<(String, String, bool)>,
+    /// Cached remote state of the selected branch (not pushed / ↑a ↓b / up to date).
+    pub sel_remote: Option<String>,
+    /// Open PRs by branch name → (number, url), polled from `gh` periodically.
+    pub pr_map: HashMap<String, (i64, String)>,
+    /// Per-agent-id: worktree has uncommitted changes (computed in refresh).
+    pub dirty: HashMap<String, bool>,
 }
 
 impl App {
     pub fn new(store: Store) -> App {
         let registry = store.load_registry();
+        let repo_branch = git_branch(&store.repo_root.to_string_lossy());
+        let prefs = store.load_prefs(); // remembered UI state
         App {
             store,
             agents: Vec::new(),
@@ -136,35 +295,254 @@ impl App {
             status_msg: String::new(),
             new_form: NewAgentForm::default(),
             should_quit: false,
-            show_observed: true,
+            show_observed: prefs.show_observed,
             all_rows: Vec::new(),
             filter_text: String::new(),
+            category: Category::from_key(&prefs.category),
+            sort: SortKey::from_key(&prefs.sort),
             term_size: (80, 24),
+            help_scroll: 0,
+            diff_text: String::new(),
+            diff_scroll: 0,
+            log_text: String::new(),
+            log_scroll: 0,
+            log_path_open: None,
+            find_query: String::new(),
+            find_input: false,
+            repo_branch,
+            retry_task: String::new(),
+            retry_harness_idx: 0,
+            marked: HashSet::new(),
+            push_queue: Vec::new(),
+            prev_status: HashMap::new(),
+            pending_shell: None,
+            settings: None,
+            settings_field: 0,
+            rename_buf: String::new(),
+            worktree_status: None,
+            sel_remote: None,
+            pr_map: HashMap::new(),
+            dirty: HashMap::new(),
+        }
+    }
+
+    /// Poll `gh` for open PRs and index them by head branch. Called on a slow
+    /// timer (gh is a network call). No-op without gh / GitHub remote.
+    pub fn poll_prs(&mut self) {
+        if !gh_available() {
+            return;
+        }
+        let repo = self.store.repo_root.to_string_lossy().to_string();
+        let (ok, out, _) = run_in(&repo, "gh",
+            &["pr", "list", "--state", "open", "--json", "number,headRefName,url", "--limit", "50"]);
+        if !ok {
+            return;
+        }
+        if let Ok(v) = serde_json::from_str::<serde_json::Value>(&out) {
+            let mut m = HashMap::new();
+            if let Some(arr) = v.as_array() {
+                for it in arr {
+                    if let (Some(br), Some(n)) =
+                        (it["headRefName"].as_str(), it["number"].as_i64())
+                    {
+                        m.insert(br.to_string(), (n, it["url"].as_str().unwrap_or("").to_string()));
+                    }
+                }
+            }
+            self.pr_map = m;
+        }
+    }
+
+    /// The open PR (number, url) for the selected agent's branch, if any.
+    pub fn selected_pr(&self) -> Option<&(i64, String)> {
+        let branch = self.selected_row()?.branch.clone();
+        let branch = if branch.is_empty() { self.selected_branch()? } else { branch };
+        self.pr_map.get(&branch)
+    }
+
+    /// Refresh the cached git status for the selected worktree (cheap: 1–2 git
+    /// calls; called on refresh and on selection move).
+    /// Per-row uncommitted-changes flags (heavier: one `git status` per row).
+    /// Called on a slow timer, capped, and skipped while chatting.
+    pub fn compute_dirty(&mut self) {
+        self.dirty.clear();
+        for r in self.all_rows.iter().take(20) {
+            if let Some(wt) = &r.worktree {
+                self.dirty.insert(r.id.clone(), !worktree_clean(wt));
+            }
+        }
+    }
+
+    pub fn update_sel_status(&mut self) {
+        let wt = self.selected_row().and_then(|r| r.worktree.clone());
+        self.worktree_status = wt.as_ref().map(|wt| {
+            let (sum, clean) = worktree_summary(wt);
+            (wt.clone(), sum, clean)
+        });
+        self.sel_remote = wt.as_deref().map(remote_state);
+    }
+
+    // ── rename / label ──────────────────────────────────────────────────────
+    /// Open the label editor for the selected crew-launched agent.
+    pub fn open_rename(&mut self) {
+        let Some(r) = self.selected_row().cloned() else { return };
+        if !self.registry.iter().any(|rec| rec.id == r.id) {
+            self.status_msg = "only crew-launched agents can be labeled".into();
+            return;
         }
+        self.rename_buf = r.label.clone().unwrap_or_default();
+        self.mode = Mode::Rename;
+    }
+    /// Save the label onto the registry entry (empty clears it).
+    pub fn commit_rename(&mut self) {
+        let Some(id) = self.selected_row().map(|r| r.id.clone()) else {
+            self.mode = Mode::Normal;
+            return;
+        };
+        let label = self.rename_buf.trim().to_string();
+        if let Some(rec) = self.registry.iter_mut().find(|r| r.id == id) {
+            rec.label = if label.is_empty() { None } else { Some(label) };
+            self.store.save_registry(&self.registry);
+        }
+        self.mode = Mode::Normal;
+        let _ = self.refresh();
+    }
+
+    // ── settings (persisted launch defaults) ────────────────────────────────
+    pub fn open_settings(&mut self) {
+        self.settings = Some(self.store.load_prefs());
+        self.settings_field = 0;
+        self.mode = Mode::Settings;
+    }
+    pub fn settings_move(&mut self, d: i64) {
+        self.settings_field = (((self.settings_field as i64 + d) % 4 + 4) % 4) as usize;
+    }
+    pub fn settings_change(&mut self, d: i64) {
+        let Some(p) = self.settings.as_mut() else { return };
+        match self.settings_field {
+            0 => {
+                let n = HARNESSES.len() as i64;
+                p.harness_idx = (((p.harness_idx as i64 + d) % n + n) % n) as usize;
+                p.model_idx = 0; // model list depends on harness
+            }
+            1 => {
+                let n = model_presets(p.harness_idx).len() as i64;
+                p.model_idx = (((p.model_idx as i64 + d) % n + n) % n) as usize;
+            }
+            2 => {
+                let n = WORKFLOWS.len() as i64;
+                p.workflow_idx = (((p.workflow_idx as i64 + d) % n + n) % n) as usize;
+            }
+            _ => p.worktree_new = !p.worktree_new,
+        }
+    }
+    pub fn save_settings(&mut self) {
+        if let Some(mut p) = self.settings.take() {
+            p.model_idx = p.model_idx.min(model_presets(p.harness_idx).len() - 1);
+            self.store.save_prefs(&p);
+            self.status_msg = "settings saved".into();
+        }
+        self.mode = Mode::Normal;
+    }
+    pub fn cancel_settings(&mut self) {
+        self.settings = None;
+        self.mode = Mode::Normal;
+    }
+
+    /// Request opening the selected worktree in `$EDITOR` (default `vi`).
+    pub fn open_editor(&mut self) {
+        let Some(wt) = self.selected_row().and_then(|r| r.worktree.clone()) else {
+            self.status_msg = "no worktree to open".into();
+            return;
+        };
+        let ed = std::env::var("EDITOR").unwrap_or_else(|_| "vi".into());
+        // split EDITOR so values like "code -w" work; then the worktree path
+        let mut argv: Vec<String> = ed.split_whitespace().map(String::from).collect();
+        argv.push(wt.clone());
+        self.pending_shell = Some((wt, argv));
+    }
+
+    /// Request a `$SHELL` (default `bash`) in the selected worktree.
+    pub fn open_shell(&mut self) {
+        let Some(wt) = self.selected_row().and_then(|r| r.worktree.clone()) else {
+            self.status_msg = "no worktree for a shell".into();
+            return;
+        };
+        let sh = std::env::var("SHELL").unwrap_or_else(|_| "bash".into());
+        self.pending_shell = Some((wt, vec![sh]));
+    }
+
+    /// Detect agents that just finished (running → done/failed) since the last
+    /// refresh and surface a toast. Updates the remembered statuses.
+    fn notify_completions(&mut self) {
+        let mut just_done: Vec<(&str, &str)> = Vec::new();
+        for r in &self.all_rows {
+            if let Some(prev) = self.prev_status.get(&r.id) {
+                if prev == "running" && (r.status == "done" || r.status == "failed") {
+                    just_done.push((r.status.as_str(), r.task.as_str()));
+                }
+            }
+        }
+        if let Some((status, task)) = just_done.last() {
+            let icon = if *status == "done" { "✓" } else { "✗" };
+            let short: String = task.chars().take(40).collect();
+            let more = if just_done.len() > 1 { format!(" (+{} more)", just_done.len() - 1) } else { String::new() };
+            self.status_msg = format!("{} {} — {}{}", icon, status, short, more);
+        }
+        self.prev_status = self.all_rows.iter().map(|r| (r.id.clone(), r.status.clone())).collect();
     }
 
     pub fn apply_filter(&mut self) {
         let q = self.filter_text.to_lowercase();
-        self.rows = if q.is_empty() {
-            self.all_rows.clone()
-        } else {
-            self.all_rows
-                .iter()
-                .filter(|r| {
-                    r.task.to_lowercase().contains(&q)
-                        || r.harness.to_lowercase().contains(&q)
-                        || r.id.to_lowercase().contains(&q)
-                        || r.status.to_lowercase().contains(&q)
-                })
-                .cloned()
-                .collect()
+        let cat = self.category;
+        let in_cat = |r: &Row| match cat {
+            Category::All => true,
+            Category::Running => r.status == "running",
+            Category::Agents => r.kind == crate::agent::Kind::Managed,
+            Category::Sessions => r.kind == crate::agent::Kind::Observed,
         };
+        let matches_text = |r: &Row| {
+            q.is_empty()
+                || r.display().to_lowercase().contains(&q)
+                || r.task.to_lowercase().contains(&q)
+                || r.harness.to_lowercase().contains(&q)
+                || r.id.to_lowercase().contains(&q)
+                || r.status.to_lowercase().contains(&q)
+        };
+        let mut rows: Vec<Row> = self
+            .all_rows
+            .iter()
+            .filter(|r| in_cat(r) && matches_text(r))
+            .cloned()
+            .collect();
+        // all_rows is already status-sorted (merge_keep); only re-sort for others.
+        match self.sort {
+            SortKey::Status => {}
+            SortKey::Cost => rows.sort_by(|a, b| b.cost_usd.total_cmp(&a.cost_usd)),
+            SortKey::Recent => rows.sort_by(|a, b| b.updated_ts.total_cmp(&a.updated_ts)),
+        }
+        self.rows = rows;
         if self.selected >= self.rows.len() && !self.rows.is_empty() {
             self.selected = self.rows.len() - 1;
         }
     }
 
+    pub fn set_category(&mut self, c: Category) {
+        self.category = c;
+        self.selected = 0;
+        self.apply_filter();
+    }
+
+    pub fn cycle_sort(&mut self) {
+        self.sort = self.sort.next();
+        self.apply_filter();
+        self.status_msg = format!("sort: {}", self.sort.label());
+    }
+
     pub fn refresh(&mut self) -> Result<()> {
+        // remember which agent is selected so the cursor follows it across a
+        // re-sort (statuses change → row order changes) instead of jumping.
+        let sel_id = self.selected_row().map(|r| r.id.clone());
         // live interactive agents first (from the owned PTY procs)
         let mut rows: Vec<Row> = self
             .agents
@@ -172,13 +550,19 @@ impl App {
             .enumerate()
             .map(|(i, p)| Row::from_proc(i, p))
             .collect();
-        let live_ids: HashSet<String> = rows.iter().map(|r| r.id.clone()).collect();
+        let mut seen: HashSet<String> = rows.iter().map(|r| r.id.clone()).collect();
         // persisted agents that aren't currently live → resumable
         for rec in &self.registry {
-            if !live_ids.contains(&rec.id) {
+            if seen.insert(rec.id.clone()) {
                 rows.push(Row::from_record(rec));
             }
         }
+        // headless sub-agents delegated via dispatch/MCP (SQLite agents table)
+        for a in self.store.managed_agents() {
+            if seen.insert(a.agent_id.clone()) {
+                rows.push(Row::from_managed(&a));
+            }
+        }
         // observed plugin sessions (read-only, from the DB)
         if self.show_observed {
             let sessions = self.store.sessions().unwrap_or_default();
@@ -186,7 +570,28 @@ impl App {
         }
         rows = merge_keep(rows);
         self.all_rows = rows;
+        // overlay registry labels onto live rows (from_record already carries it)
+        for r in &mut self.all_rows {
+            if r.label.is_none() {
+                if let Some(rec) = self.registry.iter().find(|x| x.id == r.id) {
+                    r.label = rec.label.clone();
+                }
+            }
+        }
+        self.notify_completions();
         self.apply_filter();
+        // re-anchor the cursor on the same agent if it's still visible
+        if let Some(id) = sel_id {
+            if let Some(i) = self.rows.iter().position(|r| r.id == id) {
+                self.selected = i;
+            }
+        }
+        // One or two git calls for the selected worktree only — cheap. (The
+        // per-row dirty scan is heavier and runs on its own slow timer.) Skipped
+        // while chatting to keep the PTY responsive.
+        if self.mode != Mode::Terminal {
+            self.update_sel_status();
+        }
         Ok(())
     }
 
@@ -207,13 +612,281 @@ impl App {
         let n = self.rows.len() as i64;
         let i = (self.selected as i64 + delta).clamp(0, n - 1);
         self.selected = i as usize;
+        // NB: don't probe git here — scrolling must stay smooth. The selected
+        // worktree's status refreshes on the next tick (≤800ms).
+    }
+
+    pub fn sel_top(&mut self) {
+        self.selected = 0;
+    }
+
+    /// Jump to the next/prev failed agent (triage), wrapping around.
+    pub fn jump_failed(&mut self, dir: i64) {
+        let n = self.rows.len();
+        if n == 0 {
+            return;
+        }
+        for step in 1..=n {
+            let i = (self.selected as i64 + dir * step as i64).rem_euclid(n as i64) as usize;
+            if self.rows[i].status == "failed" {
+                self.selected = i;
+                return;
+            }
+        }
+        self.status_msg = "no failed agents".into();
+    }
+    pub fn sel_bottom(&mut self) {
+        if !self.rows.is_empty() {
+            self.selected = self.rows.len() - 1;
+        }
+    }
+
+    /// Copy the selected agent's worktree path to the system clipboard.
+    pub fn yank_worktree(&mut self) {
+        let Some(wt) = self.selected_row().and_then(|r| r.worktree.clone()) else {
+            self.status_msg = "no worktree to copy".into();
+            return;
+        };
+        self.yank_text(&wt, "worktree path");
+    }
+
+    /// Copy the selected agent's branch name to the clipboard.
+    pub fn yank_branch(&mut self) {
+        let Some(branch) = self.selected_branch() else {
+            self.status_msg = "no branch to copy".into();
+            return;
+        };
+        self.yank_text(&branch, "branch");
+    }
+
+    /// Branch of the selected row: the stored branch, else read from its worktree.
+    fn selected_branch(&self) -> Option<String> {
+        let r = self.selected_row()?;
+        if !r.branch.is_empty() && r.branch != "-" {
+            return Some(r.branch.clone());
+        }
+        let wt = r.worktree.as_ref()?;
+        let b = git_out(wt, &["rev-parse", "--abbrev-ref", "HEAD"]);
+        if b.is_empty() { None } else { Some(b) }
+    }
+
+    /// Copy `text` to the clipboard (`pbcopy`/`xclip`/`wl-copy`). Best-effort.
+    fn yank_text(&mut self, text: &str, label: &str) {
+        let candidates: [&[&str]; 3] =
+            [&["pbcopy"], &["xclip", "-selection", "clipboard"], &["wl-copy"]];
+        for argv in candidates {
+            use std::io::Write;
+            use std::process::{Command, Stdio};
+            if let Ok(mut child) = Command::new(argv[0]).args(&argv[1..])
+                .stdin(Stdio::piped()).stdout(Stdio::null()).stderr(Stdio::null()).spawn()
+            {
+                if let Some(mut si) = child.stdin.take() {
+                    let _ = si.write_all(text.as_bytes());
+                }
+                let _ = child.wait();
+                self.status_msg = format!("copied {} ({})", label, argv[0]);
+                return;
+            }
+        }
+        self.status_msg = "no clipboard tool (pbcopy/xclip/wl-copy) found".into();
+    }
+
+    /// Fetch origin for the selected worktree (detached — never blocks the UI).
+    /// The ahead/behind indicator refreshes on the next status tick.
+    pub fn fetch_selected(&mut self) {
+        let Some(wt) = self.selected_row().and_then(|r| r.worktree.clone()) else {
+            self.status_msg = "no worktree to fetch".into();
+            return;
+        };
+        use std::process::{Command, Stdio};
+        let ok = Command::new("git").current_dir(&wt).args(["fetch", "--quiet"])
+            .stdout(Stdio::null()).stderr(Stdio::null()).stdin(Stdio::null()).spawn().is_ok();
+        self.status_msg = if ok { "fetching origin…".into() } else { "git fetch failed to start".into() };
+    }
+
+    /// Open the selected agent's PR (if known) or its branch on the remote.
+    pub fn open_branch_web(&mut self) {
+        // prefer the actual PR page when we have one
+        if let Some((n, url)) = self.selected_pr().cloned() {
+            if !url.is_empty() && open_url(&url) {
+                self.status_msg = format!("opening PR #{}", n);
+                return;
+            }
+        }
+        if !gh_available() {
+            self.status_msg = "open-in-browser needs the gh CLI".into();
+            return;
+        }
+        let Some(r) = self.selected_row().cloned() else { return };
+        let Some(wt) = r.worktree.clone() else {
+            self.status_msg = "no worktree".into();
+            return;
+        };
+        let Some(branch) = self.selected_branch() else {
+            self.status_msg = "no branch to open".into();
+            return;
+        };
+        use std::process::{Command, Stdio};
+        let ok = Command::new("gh").args(["browse", "--branch", &branch])
+            .current_dir(&wt).stdout(Stdio::null()).stderr(Stdio::null()).spawn().is_ok();
+        self.status_msg = if ok {
+            format!("opening {} in browser", branch)
+        } else {
+            "could not launch gh browse".into()
+        };
     }
 
     pub fn open_new_agent(&mut self) {
-        self.new_form = NewAgentForm::default();
+        let mut form = NewAgentForm::default();
+        // pre-select whatever you launched with last time
+        let p = self.store.load_prefs();
+        let hn = HARNESSES.len();
+        form.harness_idx = p.harness_idx.min(hn - 1);
+        form.model_idx = p.model_idx.min(model_presets(form.harness_idx).len() - 1);
+        form.workflow_idx = p.workflow_idx.min(WORKFLOWS.len() - 1);
+        form.worktree_new = p.worktree_new;
+        self.new_form = form;
+        self.mode = Mode::NewAgent;
+    }
+
+    /// Open the new-agent form prefilled from the selected row (task + harness +
+    /// model), so you can tweak and relaunch a variant.
+    pub fn duplicate_selected(&mut self) {
+        let Some(r) = self.selected_row().cloned() else { return };
+        let mut form = NewAgentForm::default();
+        form.task.insert_str(&r.task);
+        form.harness_idx = HARNESSES.iter().position(|h| *h == r.harness).unwrap_or(0);
+        form.model_idx = model_presets(form.harness_idx)
+            .iter().position(|m| *m == r.model).unwrap_or(0);
+        self.new_form = form;
         self.mode = Mode::NewAgent;
     }
 
+    // ── git: commit + push + PR (lazygit/claude-squad style) ────────────────
+    /// Queue the selected agent — or all marked agents — for commit+push+PR.
+    pub fn open_push(&mut self) {
+        let rows: Vec<Row> = if !self.marked.is_empty() {
+            self.rows.iter().filter(|r| self.marked.contains(&r.id)).cloned().collect()
+        } else {
+            self.selected_row().cloned().into_iter().collect()
+        };
+        let mut queue = Vec::new();
+        for r in rows {
+            if let Some(wt) = r.worktree.clone() {
+                let branch = git_out(&wt, &["rev-parse", "--abbrev-ref", "HEAD"]);
+                let branch = if branch.is_empty() { "HEAD".into() } else { branch };
+                let msg = if r.task.trim().is_empty() { "crew: work".into() } else { r.task.clone() };
+                queue.push((wt, branch, msg));
+            }
+        }
+        if queue.is_empty() {
+            self.status_msg = "no worktree to push".into();
+            return;
+        }
+        self.push_queue = queue;
+        self.mode = Mode::ConfirmPush;
+    }
+
+    /// Commit + push every queued worktree, opening a PR with `gh` per branch.
+    pub fn confirm_push(&mut self) {
+        let queue = std::mem::take(&mut self.push_queue);
+        let gh = on_path("gh");
+        let (mut pushed, mut prs, mut failed) = (0, 0, 0);
+        let mut last = String::new();
+        for (wt, branch, task) in &queue {
+            let msg = task.lines().next().unwrap_or("crew: work");
+            let _ = run_in(wt, "git", &["add", "-A"]);
+            let _ = run_in(wt, "git", &["commit", "-m", msg]); // may be empty; ok
+            let (ok, _o, perr) = run_in(wt, "git", &["push", "-u", "origin", branch]);
+            if !ok {
+                failed += 1;
+                last = format!("{}: {}", branch, perr.lines().last().unwrap_or("").trim());
+                continue;
+            }
+            pushed += 1;
+            last = branch.clone();
+            if gh {
+                let (pok, pout, _perr) = run_in(wt, "gh", &["pr", "create", "--fill", "--head", branch]);
+                if pok {
+                    prs += 1;
+                    last = pout.trim().to_string();
+                }
+            }
+        }
+        self.status_msg = if queue.len() == 1 && failed == 0 {
+            if prs > 0 { format!("pushed + PR: {}", last) } else { format!("pushed {}", last) }
+        } else if failed == 0 {
+            format!("pushed {} · {} PR(s)", pushed, prs)
+        } else {
+            format!("pushed {} · {} failed ({})", pushed, failed, last)
+        };
+        self.marked.clear();
+        self.mode = Mode::Normal;
+        let _ = self.refresh();
+    }
+
+    /// Open the retry modal for the selected managed row: re-delegate its task to
+    /// a harness you pick (defaults to the row's current harness).
+    pub fn open_retry(&mut self) {
+        if !self.store.has_engine() {
+            self.status_msg = "retry needs the nexum engine (dispatch.py) — not present".into();
+            return;
+        }
+        let Some(r) = self.selected_row().cloned() else { return };
+        if r.kind != crate::agent::Kind::Managed || r.task.trim().is_empty() {
+            self.status_msg = "select a managed agent with a task to retry".into();
+            return;
+        }
+        self.retry_task = r.task.clone();
+        self.retry_harness_idx = HARNESSES.iter().position(|h| *h == r.harness).unwrap_or(0);
+        self.mode = Mode::Retry;
+    }
+
+    pub fn cycle_retry_harness(&mut self, d: i64) {
+        let n = HARNESSES.len() as i64;
+        self.retry_harness_idx = (((self.retry_harness_idx as i64 + d) % n + n) % n) as usize;
+    }
+
+    /// Fire the retry: dispatch the task headless on the chosen harness in a
+    /// fresh worktree (detached — shows up as a new managed row).
+    pub fn confirm_retry(&mut self) {
+        let harness = HARNESSES[self.retry_harness_idx.min(HARNESSES.len() - 1)];
+        let model = model_presets(self.retry_harness_idx)[0];
+        let task = self.retry_task.clone();
+        match self.dispatch_detached(&task, harness, model) {
+            Ok(id) => self.status_msg = format!("retrying on {} → {}", harness, id),
+            Err(e) => self.status_msg = format!("retry failed: {}", e),
+        }
+        self.mode = Mode::Normal;
+        let _ = self.refresh();
+    }
+
+    /// Spawn dispatch.py detached to run `task` on `harness` in a new worktree.
+    /// Returns the chosen agent id. Mirrors the delegation MCP's async path.
+    fn dispatch_detached(&self, task: &str, harness: &str, model: &str) -> Result<String> {
+        use std::process::{Command, Stdio};
+        let id = format!("retry_{}", now_millis());
+        let steps_dir = self.store.repo_root.join(".nexum-data").join("steps");
+        std::fs::create_dir_all(&steps_dir)?;
+        let step_path = steps_dir.join(format!("{}.json", id));
+        let step = serde_json::json!({
+            "title": task.chars().take(80).collect::<String>(),
+            "objective": task, "contract": "", "scope_deny": [],
+            "acceptance": "", "files": [],
+        });
+        std::fs::write(&step_path, serde_json::to_string(&step)?)?;
+        let slug = slugify(task);
+        Command::new(&self.store.python)
+            .arg(self.store.scripts_dir.join("dispatch.py"))
+            .args(["--harness", harness, "--model", model, "--repo"])
+            .arg(&self.store.repo_root)
+            .args(["--new-worktree", "--slug", &slug, "--agent-id", &id, "--step-file"])
+            .arg(&step_path)
+            .stdout(Stdio::null()).stderr(Stdio::null()).stdin(Stdio::null())
+            .spawn()?;
+        Ok(id)
+    }
+
     /// Launch an interactive PTY agent from the form. Task is required.
     pub fn spawn_from_form(&mut self) {
         if self.new_form.task_text().trim().is_empty() {
@@ -222,6 +895,15 @@ impl App {
             return;
         }
         let harness = self.new_form.harness().to_string();
+        // NEXUM_INTERACTIVE_CMD_<H> override means the CLI needn't be on PATH (tests)
+        let overridden = std::env::var(format!("NEXUM_INTERACTIVE_CMD_{}", harness.to_uppercase()))
+            .map(|v| !v.trim().is_empty()).unwrap_or(false);
+        if !overridden && !harness_installed(&harness) {
+            self.new_form.error = Some(format!(
+                "{} CLI ('{}') not found on PATH", harness, harness_bin(&harness)));
+            self.new_form.field = FIELD_HARNESS;
+            return;
+        }
         let model = self.new_form.model().to_string();
         let prompt = self.new_form.full_prompt();
         let (cols, rows) = self.term_size;
@@ -253,9 +935,16 @@ impl App {
                 // persist so it can be resumed after the TUI closes
                 self.registry.retain(|r| r.id != id);
                 self.registry.push(AgentRecord {
-                    id: id.clone(), harness, model, worktree, task: task_text,
+                    id: id.clone(), harness, model, worktree, task: task_text, label: None,
                 });
                 self.store.save_registry(&self.registry);
+                // remember these launch choices (preserving stored UI state)
+                let mut p = self.store.load_prefs();
+                p.harness_idx = self.new_form.harness_idx;
+                p.model_idx = self.new_form.model_idx;
+                p.workflow_idx = self.new_form.workflow_idx;
+                p.worktree_new = self.new_form.worktree_new;
+                self.store.save_prefs(&p);
                 let _ = self.refresh();
                 if let Some(i) = self.rows.iter().position(|r| r.id == id) {
                     self.selected = i;
@@ -311,34 +1000,101 @@ impl App {
     }
 
     pub fn stop_selected(&mut self) {
-        if let Some(idx) = self.selected_row().and_then(|r| r.proc_idx) {
-            if let Some(p) = self.agents.get_mut(idx) {
+        let ids = self.target_ids();
+        let mut n = 0;
+        for p in &mut self.agents {
+            if ids.contains(&p.id) && p.is_alive() {
                 p.kill();
+                n += 1;
+            }
+        }
+        self.marked.clear();
+        let _ = self.refresh();
+        self.status_msg = if n > 0 {
+            format!("stopped {}", n)
+        } else {
+            "no live agents in selection".into()
+        };
+    }
+
+    // ── multi-select ──────────────────────────────────────────────────────
+    /// Toggle the mark on the selected row and advance (fast bulk marking).
+    pub fn toggle_mark(&mut self) {
+        if let Some(id) = self.selected_row().map(|r| r.id.clone()) {
+            if !self.marked.remove(&id) {
+                self.marked.insert(id);
             }
-            self.status_msg = "stopped".into();
-            let _ = self.refresh();
+        }
+        self.move_sel(1);
+    }
+    pub fn mark_all_visible(&mut self) {
+        for r in &self.rows {
+            self.marked.insert(r.id.clone());
+        }
+        self.status_msg = format!("{} marked", self.marked.len());
+    }
+    pub fn clear_marks(&mut self) {
+        self.marked.clear();
+    }
+    /// Ids to act on: the marked set (intersected with visible rows) if any,
+    /// else just the selected row.
+    fn target_ids(&self) -> HashSet<String> {
+        if !self.marked.is_empty() {
+            let visible: HashSet<&String> = self.rows.iter().map(|r| &r.id).collect();
+            self.marked.iter().filter(|id| visible.contains(id)).cloned().collect()
         } else {
-            self.status_msg = "only interactive agents can be stopped here".into();
+            self.selected_row().map(|r| r.id.clone()).into_iter().collect()
         }
     }
 
-    /// Remove the selected agent: kill any live process AND forget its persisted
-    /// record (so it no longer shows as resumable). The worktree is left on disk.
+    /// Remove the selected agent (or all marked): kill any live process, forget
+    /// the persisted record, and delete the store row. Worktrees stay on disk.
     pub fn remove_selected(&mut self) {
-        let Some(r) = self.selected_row().cloned() else { return };
-        if let Some(idx) = r.proc_idx {
-            if let Some(p) = self.agents.get_mut(idx) {
+        let ids = self.target_ids();
+        if ids.is_empty() {
+            return;
+        }
+        // capture worktrees before the rows disappear, to prune clean ones after
+        let worktrees: Vec<String> = self
+            .rows
+            .iter()
+            .filter(|r| ids.contains(&r.id))
+            .filter_map(|r| r.worktree.clone())
+            .collect();
+        // kill + drop any live PTY procs in the set
+        for p in &mut self.agents {
+            if ids.contains(&p.id) {
                 p.kill();
             }
-            self.agents.remove(idx);
         }
+        self.agents.retain(|p| !ids.contains(&p.id));
         let before = self.registry.len();
-        self.registry.retain(|rec| rec.id != r.id);
+        self.registry.retain(|rec| !ids.contains(&rec.id));
         if self.registry.len() != before {
             self.store.save_registry(&self.registry);
         }
+        // drop any headless/managed rows from the store too
+        for id in &ids {
+            self.store.delete_agent(id);
+        }
+        // prune crew worktrees that are clean (leave anything with changes)
+        let repo = self.store.repo_root.to_string_lossy().to_string();
+        let mut pruned = 0;
+        for wt in &worktrees {
+            if wt.contains("/.crew/worktrees/") && worktree_clean(wt) {
+                if run_in(&repo, "git", &["worktree", "remove", wt]).0 {
+                    pruned += 1;
+                }
+            }
+        }
+        let n = ids.len();
+        self.marked.clear();
         let _ = self.refresh();
-        self.status_msg = "removed".into();
+        self.status_msg = if pruned > 0 {
+            format!("removed {} · pruned {} clean worktree(s)", n, pruned)
+        } else {
+            format!("removed {}", n)
+        };
     }
 
     pub fn show_worktree(&mut self) {
@@ -347,18 +1103,163 @@ impl App {
         }
     }
 
+    /// Show the git diff of the selected agent's worktree (tracked changes plus a
+    /// list of untracked files). Read-only — never mutates the checkout.
+    pub fn show_diff(&mut self) {
+        let Some(wt) = self.selected_row().and_then(|r| r.worktree.clone()) else {
+            self.status_msg = "no worktree for this row".into();
+            return;
+        };
+        self.diff_text = worktree_diff(&wt);
+        self.diff_scroll = 0;
+        self.mode = Mode::Diff;
+    }
+
+    pub fn scroll_diff(&mut self, delta: i64) {
+        let max = self.diff_text.lines().count().saturating_sub(1) as i64;
+        self.diff_scroll = (self.diff_scroll as i64).saturating_add(delta).clamp(0, max) as u16;
+    }
+
+    /// Show the selected headless agent's log file (tail). Live PTY agents use
+    /// the embedded terminal instead, so this targets managed/delegated rows.
+    pub fn show_log(&mut self) {
+        let Some(r) = self.selected_row().cloned() else { return };
+        if r.interactive {
+            self.status_msg = "this agent has a live terminal — press enter to chat".into();
+            return;
+        }
+        let Some(path) = r.log_path.clone() else {
+            self.status_msg = "no log for this row".into();
+            return;
+        };
+        self.log_text = read_log_tail(&path);
+        self.log_path_open = Some(path);
+        // jump to the bottom (freshest output)
+        self.log_scroll = self.log_text.lines().count().saturating_sub(1) as u16;
+        self.mode = Mode::Log;
+    }
+
+    pub fn scroll_log(&mut self, delta: i64) {
+        let max = self.log_text.lines().count().saturating_sub(1) as i64;
+        self.log_scroll = (self.log_scroll as i64).saturating_add(delta).clamp(0, max) as u16;
+    }
+
+    /// Scroll whichever full-screen viewer is open (diff or log).
+    pub fn scroll_viewer(&mut self, delta: i64) {
+        match self.mode {
+            Mode::Diff => self.scroll_diff(delta),
+            Mode::Log => self.scroll_log(delta),
+            _ => {}
+        }
+    }
+
+    /// Jump to the next/prev line matching `find_query` in the open viewer,
+    /// wrapping around. Sets the viewer scroll to the matching line.
+    pub fn find_next(&mut self, dir: i64) {
+        if self.find_query.is_empty() {
+            return;
+        }
+        let q = self.find_query.to_lowercase();
+        let (text, cur) = match self.mode {
+            Mode::Diff => (&self.diff_text, self.diff_scroll as i64),
+            Mode::Log => (&self.log_text, self.log_scroll as i64),
+            _ => return,
+        };
+        let lines: Vec<String> = text.lines().map(|l| l.to_lowercase()).collect();
+        let n = lines.len() as i64;
+        if n == 0 {
+            return;
+        }
+        for step in 1..=n {
+            let i = (cur + dir * step).rem_euclid(n);
+            if lines[i as usize].contains(&q) {
+                let target = i as u16;
+                match self.mode {
+                    Mode::Diff => self.diff_scroll = target,
+                    Mode::Log => self.log_scroll = target,
+                    _ => {}
+                }
+                self.status_msg = format!("/{}", self.find_query);
+                return;
+            }
+        }
+        self.status_msg = format!("no match for /{}", self.find_query);
+    }
+
+    /// Re-read the open log (called on the refresh tick while in Log mode). If
+    /// the viewer is parked at the bottom, follow new output (tail -f); otherwise
+    /// keep the reader's scroll position so they can study earlier lines.
+    pub fn tick_log(&mut self) {
+        let Some(path) = self.log_path_open.clone() else { return };
+        let old_max = self.log_text.lines().count().saturating_sub(1) as u16;
+        let following = self.log_scroll >= old_max;
+        self.log_text = read_log_tail(&path);
+        let new_max = self.log_text.lines().count().saturating_sub(1) as u16;
+        if following {
+            self.log_scroll = new_max;
+        } else {
+            self.log_scroll = self.log_scroll.min(new_max);
+        }
+    }
+
+    /// Persist the current UI state (view toggles) so the next run restores it.
+    /// Preserves the launch-choice fields already on disk.
+    pub fn save_ui_prefs(&self) {
+        let mut p = self.store.load_prefs();
+        p.show_observed = self.show_observed;
+        p.sort = self.sort.label().to_string();
+        p.category = self.category.label().to_string();
+        self.store.save_prefs(&p);
+    }
+
     pub fn running_count(&self) -> usize {
         self.rows.iter().filter(|r| r.status == "running").count()
     }
+
+    /// Kill every live interactive agent at once. Registry rows are kept so they
+    /// stay resumable.
+    pub fn stop_all(&mut self) {
+        let mut n = 0;
+        for p in &mut self.agents {
+            if p.is_alive() {
+                p.kill();
+                n += 1;
+            }
+        }
+        let _ = self.refresh();
+        self.status_msg = format!("stopped {} agent(s)", n);
+    }
+
+    /// Drop finished work: remove exited live procs and forget persisted rows
+    /// that aren't currently running. Keeps everything still alive.
+    pub fn clear_finished(&mut self) {
+        let alive: HashSet<String> = self
+            .agents
+            .iter_mut()
+            .filter_map(|p| if p.is_alive() { Some(p.id.clone()) } else { None })
+            .collect();
+        let before_agents = self.agents.len();
+        self.agents.retain_mut(|p| p.is_alive());
+        let before_reg = self.registry.len();
+        self.registry.retain(|r| alive.contains(&r.id));
+        if self.registry.len() != before_reg {
+            self.store.save_registry(&self.registry);
+        }
+        let removed = (before_agents - self.agents.len()) + (before_reg - self.registry.len());
+        let _ = self.refresh();
+        self.status_msg = format!("cleared {} finished", removed);
+    }
 }
 
 /// Sort rows (running first, then exited, then observed), newest kept order.
 fn merge_keep(mut rows: Vec<Row>) -> Vec<Row> {
     rows.sort_by_key(|r| match r.status.as_str() {
         "running" => 0,
-        "resumable" => 1,
-        "exited" => 2,
-        _ => 3,
+        "failed" => 1, // surface failures near the top — they need attention
+        "resumable" => 2,
+        "done" => 3,
+        "exited" => 4,
+        _ => 5, // observed sessions last
     });
     rows
 }
@@ -395,7 +1296,178 @@ pub fn resume_argv(harness: &str, model: &str) -> Vec<String> {
     }
 }
 
-fn slugify(task: &str) -> String {
+/// Read the last 2000 lines of a log file, with friendly fallbacks.
+fn read_log_tail(path: &str) -> String {
+    match std::fs::read_to_string(path) {
+        Ok(s) if !s.trim().is_empty() => {
+            let lines: Vec<&str> = s.lines().collect();
+            let start = lines.len().saturating_sub(2000);
+            lines[start..].join("\n")
+        }
+        Ok(_) => format!("(log is empty: {})", path),
+        Err(e) => format!("(cannot read {}: {})", path, e),
+    }
+}
+
+/// Run `prog args` with cwd=`dir`; return (success, stdout, stderr).
+fn run_in(dir: &str, prog: &str, args: &[&str]) -> (bool, String, String) {
+    match std::process::Command::new(prog).current_dir(dir).args(args).output() {
+        Ok(o) => (
+            o.status.success(),
+            String::from_utf8_lossy(&o.stdout).into_owned(),
+            String::from_utf8_lossy(&o.stderr).into_owned(),
+        ),
+        Err(e) => (false, String::new(), e.to_string()),
+    }
+}
+
+/// Branch state vs its upstream: "not pushed" (no upstream), "up to date", or
+/// "↑ahead ↓behind". Empty string if not a git worktree.
+fn remote_state(wt: &str) -> String {
+    if !std::path::Path::new(wt).is_dir() {
+        return String::new();
+    }
+    // no upstream configured → never pushed
+    if !run_in(wt, "git", &["rev-parse", "--abbrev-ref", "@{upstream}"]).0 {
+        return "not pushed".into();
+    }
+    let (ok, out, _) = run_in(wt, "git", &["rev-list", "--left-right", "--count", "@{upstream}...HEAD"]);
+    if !ok {
+        return String::new();
+    }
+    let mut it = out.split_whitespace();
+    let behind = it.next().unwrap_or("0");
+    let ahead = it.next().unwrap_or("0");
+    if ahead == "0" && behind == "0" {
+        "up to date".into()
+    } else {
+        format!("↑{} ↓{}", ahead, behind)
+    }
+}
+
+/// A short summary of a worktree's git status: ("clean", true) or
+/// ("N files · +ins -del", false); ("—", true) if not a worktree.
+fn worktree_summary(wt: &str) -> (String, bool) {
+    if !std::path::Path::new(wt).is_dir() {
+        return ("—".into(), true);
+    }
+    let (ok, st, _) = run_in(wt, "git", &["status", "--porcelain"]);
+    if !ok {
+        return ("—".into(), true);
+    }
+    let files = st.lines().count();
+    if files == 0 {
+        return ("clean".into(), true);
+    }
+    // insertions/deletions from shortstat (tracked changes only)
+    let (_, ss, _) = run_in(wt, "git", &["diff", "--shortstat"]);
+    let pick = |kw: &str| ss.split(',').find(|s| s.contains(kw))
+        .and_then(|s| s.trim().split_whitespace().next()).unwrap_or("0").to_string();
+    let (ins, del) = (pick("insertion"), pick("deletion"));
+    (format!("{} file(s) · +{} -{}", files, ins, del), false)
+}
+
+/// A worktree with no uncommitted or untracked changes (safe to `git worktree
+/// remove`). False if the path is gone or git errors — never prune on doubt.
+fn worktree_clean(wt: &str) -> bool {
+    if !std::path::Path::new(wt).is_dir() {
+        return false;
+    }
+    let (ok, out, _) = run_in(wt, "git", &["status", "--porcelain"]);
+    ok && out.trim().is_empty()
+}
+
+/// `git args` run in `dir`; stdout trimmed (empty on failure).
+fn git_out(dir: &str, args: &[&str]) -> String {
+    let (ok, out, _) = run_in(dir, "git", args);
+    if ok { out.trim().to_string() } else { String::new() }
+}
+
+/// Whether the GitHub CLI is installed (for auto-PR after push).
+pub fn gh_available() -> bool {
+    on_path("gh")
+}
+
+/// Open a URL in the default browser (`open` on macOS, `xdg-open` on Linux).
+fn open_url(url: &str) -> bool {
+    let opener = if cfg!(target_os = "macos") { "open" } else { "xdg-open" };
+    std::process::Command::new(opener).arg(url)
+        .stdout(std::process::Stdio::null()).stderr(std::process::Stdio::null())
+        .spawn().is_ok()
+}
+
+/// The CLI binary name for a harness.
+pub fn harness_bin(harness: &str) -> &'static str {
+    match harness {
+        "opencode" => "opencode",
+        "cursor" => "cursor-agent",
+        _ => "claude",
+    }
+}
+
+/// Whether a harness's CLI is installed (on PATH).
+pub fn harness_installed(harness: &str) -> bool {
+    on_path(harness_bin(harness))
+}
+
+/// True if an executable named `bin` exists on `$PATH` (no process spawned).
+pub fn on_path(bin: &str) -> bool {
+    std::env::var_os("PATH")
+        .map(|paths| {
+            std::env::split_paths(&paths).any(|dir| {
+                let p = dir.join(bin);
+                p.is_file()
+            })
+        })
+        .unwrap_or(false)
+}
+
+fn now_millis() -> u128 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.as_millis())
+        .unwrap_or(0)
+}
+
+/// Current branch name of a git repo (empty if not a repo / detached).
+fn git_branch(repo: &str) -> String {
+    std::process::Command::new("git")
+        .arg("-C").arg(repo).args(["rev-parse", "--abbrev-ref", "HEAD"])
+        .output()
+        .ok()
+        .filter(|o| o.status.success())
+        .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())
+        .unwrap_or_default()
+}
+
+/// `git diff` for a worktree, with an appended list of untracked files. Returns
+/// a friendly message rather than erroring when there's nothing / no git.
+fn worktree_diff(wt: &str) -> String {
+    let run = |args: &[&str]| -> String {
+        std::process::Command::new("git")
+            .arg("-C").arg(wt).args(args)
+            .output()
+            .ok()
+            .filter(|o| o.status.success())
+            .map(|o| String::from_utf8_lossy(&o.stdout).into_owned())
+            .unwrap_or_default()
+    };
+    let mut out = run(&["diff"]);
+    let untracked = run(&["ls-files", "--others", "--exclude-standard"]);
+    if !untracked.trim().is_empty() {
+        out.push_str("\n── untracked files ──\n");
+        for f in untracked.lines() {
+            out.push_str(&format!("+ {}\n", f));
+        }
+    }
+    if out.trim().is_empty() {
+        format!("no changes in {}", wt)
+    } else {
+        out
+    }
+}
+
+pub fn slugify(task: &str) -> String {
     let base: String = task
         .chars()
         .map(|c| if c.is_ascii_alphanumeric() { c.to_ascii_lowercase() } else { '-' })
@@ -440,6 +1512,358 @@ mod tests {
         assert_eq!(a.new_form.field, FIELD_TASK);
     }
 
+    #[test]
+    fn workflow_seeds_plan_build_and_steers_executor() {
+        let mut f = NewAgentForm::default();
+        f.task.insert_str("ship the billing endpoint");
+        // 0 = chat: no workflow seed
+        assert!(!f.full_prompt().contains("nx-plan"));
+        // 1 = plan → build (same harness)
+        f.workflow_idx = 1;
+        let p = f.full_prompt();
+        assert!(p.contains("/nx-plan") && p.contains("/nx-build"));
+        assert!(p.contains("ship the billing endpoint"));
+        // 2 = steer executor to cursor
+        f.workflow_idx = 2;
+        assert!(f.full_prompt().contains("/nx-build --harness cursor"));
+        // 3 = steer executor to opencode
+        f.workflow_idx = 3;
+        assert!(f.full_prompt().contains("/nx-build --harness opencode"));
+        // 4 = plan only: no nx-build
+        f.workflow_idx = 4;
+        let p = f.full_prompt();
+        assert!(p.contains("/nx-plan") && !p.contains("/nx-build"));
+    }
+
+    #[test]
+    fn selected_pr_matches_branch() {
+        use crate::agent::{ManagedAgent, Row};
+        let row = Row::from_managed(&ManagedAgent {
+            agent_id: "a".into(), harness: Some("cursor".into()), model: None,
+            worktree: None, branch: Some("crew/x".into()), status: Some("done".into()),
+            cost_usd: None, task: None, step_index: None, updated_ts: None, pid: None, log_path: None,
+        });
+        let mut a = app();
+        a.rows = vec![row];
+        a.selected = 0;
+        assert!(a.selected_pr().is_none());
+        a.pr_map.insert("crew/x".into(), (42, "https://example/pr/42".into()));
+        assert_eq!(a.selected_pr().unwrap().0, 42);
+    }
+
+    #[test]
+    fn remote_state_reports_push_state() {
+        use std::process::Command;
+        let base = std::env::temp_dir().join(format!("crew-rem-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&base);
+        std::fs::create_dir_all(&base).unwrap();
+        let origin = base.join("o.git");
+        let work = base.join("w");
+        Command::new("git").args(["init", "--bare", "-q"]).arg(&origin).output().unwrap();
+        std::fs::create_dir_all(&work).unwrap();
+        let g = |a: &[&str]| { Command::new("git").arg("-C").arg(&work).args(a).output().unwrap(); };
+        g(&["init", "-q"]); g(&["config", "user.email", "t@t"]); g(&["config", "user.name", "t"]);
+        std::fs::write(work.join("f.txt"), "1").unwrap();
+        g(&["add", "f.txt"]); g(&["commit", "-qm", "init"]);
+        g(&["remote", "add", "origin", origin.to_str().unwrap()]);
+        let ws = work.to_string_lossy().to_string();
+
+        assert_eq!(remote_state(&ws), "not pushed");
+        g(&["push", "-qu", "origin", "HEAD"]);
+        assert_eq!(remote_state(&ws), "up to date");
+        std::fs::write(work.join("f.txt"), "2").unwrap();
+        g(&["commit", "-qam", "more"]);
+        assert_eq!(remote_state(&ws), "↑1 ↓0");
+        let _ = std::fs::remove_dir_all(&base);
+    }
+
+    #[test]
+    fn worktree_summary_reports_clean_and_dirty() {
+        use std::process::Command;
+        let repo = std::env::temp_dir().join(format!("crew-sum-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&repo);
+        std::fs::create_dir_all(&repo).unwrap();
+        let g = |a: &[&str]| { Command::new("git").arg("-C").arg(&repo).args(a).output().unwrap(); };
+        g(&["init", "-q"]); g(&["config", "user.email", "t@t"]); g(&["config", "user.name", "t"]);
+        std::fs::write(repo.join("seed.txt"), "one\n").unwrap();
+        g(&["add", "seed.txt"]); g(&["commit", "-qm", "init"]);
+        let rs = repo.to_string_lossy().to_string();
+
+        let (s, clean) = worktree_summary(&rs);
+        assert!(clean && s == "clean", "{s}");
+        std::fs::write(repo.join("seed.txt"), "one\ntwo\n").unwrap(); // modify tracked
+        let (s2, clean2) = worktree_summary(&rs);
+        assert!(!clean2, "should be dirty");
+        assert!(s2.contains("file(s)"), "{s2}");
+        let _ = std::fs::remove_dir_all(&repo);
+    }
+
+    #[test]
+    fn remove_prunes_clean_crew_worktree() {
+        use std::process::Command;
+        let repo = std::env::temp_dir().join(format!("crew-prune-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&repo);
+        std::fs::create_dir_all(&repo).unwrap();
+        let g = |a: &[&str]| { Command::new("git").arg("-C").arg(&repo).args(a).output().unwrap(); };
+        g(&["init", "-q"]); g(&["config", "user.email", "t@t"]); g(&["config", "user.name", "t"]);
+        std::fs::write(repo.join("seed.txt"), "x").unwrap();
+        g(&["add", "seed.txt"]); g(&["commit", "-qm", "init"]);
+        let repo = std::fs::canonicalize(&repo).unwrap();
+
+        let mut a = App::new(Store::new(repo.clone(), repo.join("scripts")));
+        let wt = a.store.create_worktree("prune-me").unwrap();
+        assert!(std::path::Path::new(&wt).is_dir());
+        a.registry.push(AgentRecord {
+            id: "p".into(), harness: "claude".into(), model: "m".into(),
+            worktree: wt.clone(), task: "t".into(), label: None,
+        });
+        a.refresh().unwrap();
+        a.selected = a.rows.iter().position(|r| r.id == "p").unwrap();
+        a.remove_selected();
+        assert!(!std::path::Path::new(&wt).exists(), "clean worktree should be pruned");
+        assert!(a.status_msg.contains("pruned"), "{}", a.status_msg);
+        let _ = std::fs::remove_dir_all(&repo);
+    }
+
+    #[test]
+    fn label_shows_in_list_and_persists() {
+        let mut a = app();
+        a.registry.push(AgentRecord {
+            id: "lbl1".into(), harness: "claude".into(), model: "sonnet".into(),
+            worktree: "/tmp/wt".into(), task: "do the thing".into(), label: None,
+        });
+        a.refresh().unwrap();
+        a.selected = a.rows.iter().position(|r| r.id == "lbl1").unwrap();
+        a.open_rename();
+        assert_eq!(a.mode, Mode::Rename);
+        a.rename_buf = "nice name".into();
+        a.commit_rename();
+        // registry updated + row displays the label instead of the task
+        let rec = a.registry.iter().find(|r| r.id == "lbl1").unwrap();
+        assert_eq!(rec.label.as_deref(), Some("nice name"));
+        let row = a.rows.iter().find(|r| r.id == "lbl1").unwrap();
+        assert_eq!(row.display(), "nice name");
+    }
+
+    #[test]
+    fn ui_state_persists_across_sessions() {
+        let dir = std::env::temp_dir().join(format!("crew-ui-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(&dir).unwrap();
+        let mut a = App::new(Store::new(dir.clone(), dir.join("scripts")));
+        a.show_observed = false;
+        a.sort = SortKey::Cost;
+        a.category = Category::Running;
+        a.save_ui_prefs();
+        // a fresh session restores the view
+        let b = App::new(Store::new(dir.clone(), dir.join("scripts")));
+        assert!(!b.show_observed);
+        assert_eq!(b.sort, SortKey::Cost);
+        assert_eq!(b.category, Category::Running);
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn settings_edit_and_persist() {
+        let dir = std::env::temp_dir().join(format!("crew-set-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(&dir).unwrap();
+        let mut a = App::new(Store::new(dir.clone(), dir.join("scripts")));
+        a.open_settings();
+        assert_eq!(a.mode, Mode::Settings);
+        a.settings_change(1); // harness 0 -> 1
+        a.settings_field = 2;
+        a.settings_change(1); // workflow 0 -> 1
+        a.settings_field = 3;
+        a.settings_change(1); // worktree toggle true -> false
+        a.save_settings();
+        assert_eq!(a.mode, Mode::Normal);
+        let p = a.store.load_prefs();
+        assert_eq!(p.harness_idx, 1);
+        assert_eq!(p.workflow_idx, 1);
+        assert!(!p.worktree_new);
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn on_path_detects_binaries() {
+        assert!(on_path("sh"), "sh should be on PATH");
+        assert!(!on_path("definitely-not-a-real-binary-xyz-123"));
+        assert_eq!(harness_bin("cursor"), "cursor-agent");
+        assert_eq!(harness_bin("claude"), "claude");
+    }
+
+    #[test]
+    fn editor_and_shell_target_the_worktree() {
+        use crate::agent::{ManagedAgent, Row};
+        let row = Row::from_managed(&ManagedAgent {
+            agent_id: "a".into(), harness: Some("cursor".into()), model: None,
+            worktree: Some("/tmp/wt".into()), branch: None, status: Some("done".into()),
+            cost_usd: None, task: None, step_index: None, updated_ts: None, pid: None, log_path: None,
+        });
+        let mut a = app();
+        a.rows = vec![row];
+        a.selected = 0;
+        std::env::set_var("EDITOR", "myed -w");
+        a.open_editor();
+        let (cwd, argv) = a.pending_shell.take().unwrap();
+        assert_eq!(cwd, "/tmp/wt");
+        assert_eq!(argv, vec!["myed", "-w", "/tmp/wt"]);
+        std::env::set_var("SHELL", "myshell");
+        a.open_shell();
+        let (_c, argv) = a.pending_shell.take().unwrap();
+        assert_eq!(argv, vec!["myshell"]);
+    }
+
+    #[test]
+    fn notifies_on_running_to_done_transition() {
+        use crate::agent::{ManagedAgent, Row};
+        let mk = |id: &str, st: &str| Row::from_managed(&ManagedAgent {
+            agent_id: id.into(), harness: Some("cursor".into()), model: None, worktree: None,
+            branch: None, status: Some(st.into()), cost_usd: None, task: Some("do the thing".into()),
+            step_index: None, updated_ts: None, pid: None, log_path: None,
+        });
+        let mut a = app();
+        a.all_rows = vec![mk("x", "running")];
+        a.notify_completions();
+        assert!(a.status_msg.is_empty()); // first sighting: no toast
+        a.all_rows = vec![mk("x", "done")];
+        a.notify_completions();
+        assert!(a.status_msg.contains('✓'), "{}", a.status_msg);
+        assert!(a.status_msg.contains("do the thing"));
+    }
+
+    #[test]
+    fn marking_rows_and_clearing() {
+        use crate::agent::{ManagedAgent, Row};
+        let mk = |id: &str| Row::from_managed(&ManagedAgent {
+            agent_id: id.into(), harness: None, model: None, worktree: None,
+            branch: None, status: Some("done".into()), cost_usd: None, task: None,
+            step_index: None, updated_ts: None, pid: None, log_path: None,
+        });
+        let mut a = app();
+        a.rows = vec![mk("a"), mk("b"), mk("c")];
+        a.selected = 0;
+        a.toggle_mark(); // marks "a", advances to 1
+        assert!(a.marked.contains("a"));
+        assert_eq!(a.selected, 1);
+        a.toggle_mark(); // marks "b"
+        assert_eq!(a.marked.len(), 2);
+        a.toggle_mark(); // marks "c"
+        a.selected = 2;
+        a.toggle_mark(); // toggles "c" back off
+        assert!(!a.marked.contains("c"));
+        a.clear_marks();
+        assert!(a.marked.is_empty());
+        a.mark_all_visible();
+        assert_eq!(a.marked.len(), 3);
+    }
+
+    #[test]
+    fn jump_failed_cycles_failed_rows() {
+        use crate::agent::{ManagedAgent, Row};
+        let mk = |id: &str, st: &str| Row::from_managed(&ManagedAgent {
+            agent_id: id.into(), harness: None, model: None, worktree: None,
+            branch: None, status: Some(st.into()), cost_usd: None, task: None,
+            step_index: None, updated_ts: None, pid: None, log_path: None,
+        });
+        let mut a = app();
+        a.rows = vec![mk("a", "done"), mk("b", "failed"), mk("c", "running"), mk("d", "failed")];
+        a.selected = 0;
+        a.jump_failed(1);
+        assert_eq!(a.selected, 1);
+        a.jump_failed(1);
+        assert_eq!(a.selected, 3);
+        a.jump_failed(1); // wrap
+        assert_eq!(a.selected, 1);
+        a.jump_failed(-1);
+        assert_eq!(a.selected, 3);
+    }
+
+    #[test]
+    fn sel_top_and_bottom() {
+        use crate::agent::{ManagedAgent, Row};
+        let mk = |id: &str| Row::from_managed(&ManagedAgent {
+            agent_id: id.into(), harness: None, model: None, worktree: None,
+            branch: None, status: Some("done".into()), cost_usd: None,
+            task: None, step_index: None, updated_ts: None, pid: None, log_path: None,
+        });
+        let mut a = app();
+        a.rows = vec![mk("a"), mk("b"), mk("c")];
+        a.sel_bottom();
+        assert_eq!(a.selected, 2);
+        a.sel_top();
+        assert_eq!(a.selected, 0);
+    }
+
+    #[test]
+    fn find_next_cycles_matches_and_wraps() {
+        let mut a = app();
+        a.mode = Mode::Diff;
+        a.diff_text = "alpha\nbeta\nGAMMA match\ndelta\nmatch again\n".into();
+        a.find_query = "match".into();
+        a.diff_scroll = 0;
+        a.find_next(1);
+        assert_eq!(a.diff_scroll, 2); // first match (case-insensitive)
+        a.find_next(1);
+        assert_eq!(a.diff_scroll, 4);
+        a.find_next(1); // wrap to top
+        assert_eq!(a.diff_scroll, 2);
+        a.find_next(-1); // backward wraps
+        assert_eq!(a.diff_scroll, 4);
+        // empty query is a no-op
+        a.find_query.clear();
+        a.find_next(1);
+        assert_eq!(a.diff_scroll, 4);
+    }
+
+    #[test]
+    fn sort_key_cycles() {
+        assert_eq!(SortKey::Status.next(), SortKey::Cost);
+        assert_eq!(SortKey::Cost.next(), SortKey::Recent);
+        assert_eq!(SortKey::Recent.next(), SortKey::Status);
+    }
+
+    #[test]
+    fn category_and_sort_filter_rows() {
+        use crate::agent::{ManagedAgent, Row};
+        let managed = |id: &str, status: &str, cost: f64, ts: f64| ManagedAgent {
+            agent_id: id.into(), harness: Some("cursor".into()), model: None,
+            worktree: None, branch: None, status: Some(status.into()),
+            cost_usd: Some(cost), task: Some("t".into()), step_index: None,
+            updated_ts: Some(ts), pid: None, log_path: None,
+        };
+        let mut a = app();
+        a.all_rows = vec![
+            Row::from_managed(&managed("a", "running", 0.10, 100.0)),
+            Row::from_managed(&managed("b", "done", 0.50, 200.0)),
+            Row::from_managed(&managed("c", "failed", 0.02, 300.0)),
+        ];
+        // category: running only
+        a.set_category(Category::Running);
+        assert_eq!(a.rows.len(), 1);
+        assert_eq!(a.rows[0].id, "a");
+        // back to all, sort by cost desc
+        a.set_category(Category::All);
+        a.sort = SortKey::Cost;
+        a.apply_filter();
+        assert_eq!(a.rows[0].id, "b"); // 0.50 first
+        // sort by recent desc
+        a.sort = SortKey::Recent;
+        a.apply_filter();
+        assert_eq!(a.rows[0].id, "c"); // ts 300 first
+    }
+
+    #[test]
+    fn workflow_cycles_and_wraps() {
+        let mut f = NewAgentForm::default();
+        assert_eq!(f.workflow_idx, 0);
+        f.cycle_workflow(-1);
+        assert_eq!(f.workflow_idx, WORKFLOWS.len() - 1);
+        f.cycle_workflow(1);
+        assert_eq!(f.workflow_idx, 0);
+    }
+
     #[test]
     fn full_prompt_appends_images() {
         let mut f = NewAgentForm::default();
diff --git a/tui/src/main.rs b/tui/src/main.rs
index d29ac96..3294dc5 100644
--- a/tui/src/main.rs
+++ b/tui/src/main.rs
@@ -1,10 +1,12 @@
-//! nexum-tui — a repo-scoped dashboard for running and chatting with coding
-//! agents. Each agent runs its harness REPL in a PTY rendered *inside* the TUI.
+//! crew — a repo-scoped dashboard for running, chatting with, and managing
+//! coding agents across harnesses. Each agent runs its harness REPL in a PTY
+//! rendered *inside* the TUI. Standalone: creates worktrees natively and keeps
+//! its own registry; an optional nexum engine adds observed sessions + delegation.
 //!
-//!   nexum-tui                 # interactive dashboard
-//!   nexum-tui --dump          # print the agent list once and exit (no TTY)
-//!   nexum-tui --snapshot      # render one real frame to text (no TTY)
-//!   nexum-tui --scripts DIR   # override the scripts dir (default <repo>/scripts)
+//!   crew                 # interactive dashboard
+//!   crew --dump          # print the agent list once and exit (no TTY)
+//!   crew --snapshot      # render one real frame to text (no TTY)
+//!   crew --scripts DIR   # override the optional engine scripts dir
 
 mod agent;
 mod app;
@@ -17,7 +19,7 @@ use app::{App, Mode};
 use crossterm::{
     event::{
         self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEvent, KeyEventKind,
-        KeyModifiers, MouseEventKind,
+        KeyModifiers, MouseButton, MouseEventKind,
     },
     execute,
     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
@@ -29,11 +31,44 @@ use std::time::{Duration, Instant};
 
 type Term = Terminal<CrosstermBackend<io::Stdout>>;
 
+const HELP: &str = "\
+crew — a terminal dashboard for coding agents across harnesses
+
+USAGE:
+  crew                         interactive dashboard (from inside a git repo)
+  crew --new \"task\"            create a worktree + run the harness headless in it
+       [--harness claude|opencode|cursor] [--model NAME] [--here]
+       (--here runs in the current repo instead of a new worktree)
+  crew --dump                  print the agent list once and exit (no TTY)
+  crew --snapshot              render one frame to text (no TTY)
+  crew --scripts DIR           optional nexum engine scripts dir
+  crew --doctor                check git / harness CLIs / gh / engine
+  crew --help | --version
+
+KEYS: press ? inside the dashboard for the full keymap.";
+
 fn main() -> Result<()> {
     let args: Vec<String> = std::env::args().collect();
+    if args.iter().any(|a| a == "--help" || a == "-h") {
+        println!("{HELP}");
+        return Ok(());
+    }
+    if args.iter().any(|a| a == "--version" || a == "-V") {
+        println!("crew {}", env!("CARGO_PKG_VERSION"));
+        return Ok(());
+    }
+    if args.iter().any(|a| a == "--doctor") {
+        return doctor(&args);
+    }
     let scripts_override = arg_value(&args, "--scripts");
 
     let cwd = std::env::current_dir()?;
+    // crew is repo-scoped: worktrees, branches, status all need a git repo.
+    let interactive = !args.iter().any(|a| a == "--dump" || a == "--snapshot");
+    if interactive && !store::is_git_repo(&cwd) {
+        eprintln!("crew: not inside a git repository (cd into one, or `git init`)");
+        std::process::exit(1);
+    }
     let repo_root = store::git_toplevel(&cwd);
     let scripts_dir = scripts_override
         .map(PathBuf::from)
@@ -48,6 +83,9 @@ fn main() -> Result<()> {
         dump_table(&app);
         return Ok(());
     }
+    if let Some(task) = arg_value(&args, "--new") {
+        return run_new(&app, &task, &args);
+    }
     if args.iter().any(|a| a == "--snapshot") {
         match std::env::var("NEXUM_SNAPSHOT_MODE").as_deref() {
             Ok("new") => {
@@ -55,6 +93,29 @@ fn main() -> Result<()> {
                 app.new_form.task.insert_str("add auth middleware");
             }
             Ok("help") => app.mode = app::Mode::Help,
+            Ok("demo") => {
+                // inject a rich sample fleet for docs/marketing screenshots
+                use agent::{ManagedAgent, Row};
+                let mk = |id: &str, h: &str, st: &str, task: &str, cost: f64, ago: f64| {
+                    Row::from_managed(&ManagedAgent {
+                        agent_id: id.into(), harness: Some(h.into()), model: Some("sonnet".into()),
+                        worktree: Some(format!(".crew/worktrees/{}", id)), branch: Some(format!("crew/{}", id)),
+                        status: Some(st.into()), cost_usd: Some(cost), task: Some(task.into()),
+                        step_index: None, updated_ts: Some(app_now() - ago), pid: None, log_path: None,
+                    })
+                };
+                app.all_rows = vec![
+                    mk("billing-api", "cursor", "running", "add billing dashboard endpoint", 0.42, 12.0),
+                    mk("auth-mw", "claude", "running", "add auth middleware + tests", 0.31, 40.0),
+                    mk("flaky-test", "opencode", "failed", "fix flaky timezone test", 0.08, 120.0),
+                    mk("readme", "claude", "done", "rewrite the README intro", 0.05, 600.0),
+                    mk("dark-mode", "cursor", "done", "add dark-mode toggle to settings", 0.19, 3600.0),
+                ];
+                app.apply_filter();
+                app.selected = 0;
+                app.marked.insert("auth-mw".into());
+                app.marked.insert("flaky-test".into());
+            }
             Ok("term") | Ok("quit") => {
                 // spawn a stub interactive agent and drop into its terminal
                 app.term_size = (80, 24);
@@ -77,8 +138,97 @@ fn main() -> Result<()> {
     run_tui(&mut app)
 }
 
+/// Headless launch from the shell: create a worktree natively and run the
+/// harness once in it (inheriting the terminal), then print the worktree/branch.
+/// Fully standalone — no engine required.
+fn run_new(app: &App, task: &str, args: &[String]) -> Result<()> {
+    let harness = arg_value(args, "--harness").unwrap_or_else(|| "claude".into());
+    let model = arg_value(args, "--model").unwrap_or_else(|| default_model(&harness).into());
+    let slug = app::slugify(task);
+    // --here runs in the current repo; default is a fresh isolated worktree.
+    let here = args.iter().any(|a| a == "--here");
+    let (wt, where_) = if here {
+        let repo = app.store.repo_root.to_string_lossy().to_string();
+        (repo.clone(), format!("repo {repo}"))
+    } else {
+        match app.store.create_worktree(&slug) {
+            Ok(p) => (p.clone(), format!("branch crew/{slug} · worktree {p}")),
+            Err(e) => {
+                eprintln!("crew: worktree failed: {e}");
+                std::process::exit(1);
+            }
+        }
+    };
+    let argv = headless_argv(&harness, &model, task);
+    println!("crew: launching {harness} ({model}) in {wt}");
+    let status = std::process::Command::new(&argv[0])
+        .args(&argv[1..])
+        .current_dir(&wt)
+        .status();
+    match status {
+        Ok(s) => println!("crew: done ({}) · {where_}",
+            s.code().map(|c| c.to_string()).unwrap_or_else(|| "signal".into())),
+        Err(e) => {
+            eprintln!("crew: could not run {}: {e}", argv[0]);
+            std::process::exit(1);
+        }
+    }
+    Ok(())
+}
+
+/// Print an environment checklist so setup problems are obvious.
+fn doctor(args: &[String]) -> Result<()> {
+    let cwd = std::env::current_dir()?;
+    let scripts_dir = arg_value(args, "--scripts")
+        .map(PathBuf::from)
+        .or_else(|| std::env::var("NEXUM_SCRIPTS").ok().map(PathBuf::from))
+        .unwrap_or_else(|| store::git_toplevel(&cwd).join("scripts"));
+    let mark = |ok: bool| if ok { "✓" } else { "✗" };
+
+    println!("crew {} — environment check\n", env!("CARGO_PKG_VERSION"));
+    println!("  {} git installed", mark(app::on_path("git")));
+    println!("  {} inside a git repository", mark(store::is_git_repo(&cwd)));
+    println!("  {} gh (GitHub CLI, for push→PR / open)", mark(app::gh_available()));
+    println!("\n  harness CLIs:");
+    for h in app::HARNESSES {
+        println!("    {} {:<9} ({})", mark(app::harness_installed(h)), h, app::harness_bin(h));
+    }
+    let engine = scripts_dir.join("store.py").is_file();
+    println!("\n  {} optional nexum engine ({})",
+        mark(engine), scripts_dir.display());
+    if !engine {
+        println!("      (standalone mode — observed sessions & delegation disabled)");
+    }
+    Ok(())
+}
+
+fn default_model(harness: &str) -> &'static str {
+    match harness {
+        "opencode" => "anthropic/claude-sonnet-4-6",
+        "cursor" => "auto",
+        _ => "sonnet",
+    }
+}
+
+/// One-shot headless argv per harness (mirrors the interactive presets minus the
+/// REPL). Overridable via `NEXUM_HEADLESS_CMD_<HARNESS>` (prompt appended).
+fn headless_argv(harness: &str, model: &str, task: &str) -> Vec<String> {
+    if let Ok(over) = std::env::var(format!("NEXUM_HEADLESS_CMD_{}", harness.to_uppercase())) {
+        if !over.trim().is_empty() {
+            let mut v: Vec<String> = over.split_whitespace().map(String::from).collect();
+            v.push(task.into());
+            return v;
+        }
+    }
+    match harness {
+        "opencode" => vec!["opencode".into(), "run".into(), task.into(), "--model".into(), model.into()],
+        "cursor" => vec!["cursor-agent".into(), "-p".into(), task.into(), "--model".into(), model.into()],
+        _ => vec!["claude".into(), "-p".into(), task.into(), "--model".into(), model.into()],
+    }
+}
+
 fn dump_table(app: &App) {
-    println!("nexum agents for {} — {} rows", app.store.repo_root.display(), app.rows.len());
+    println!("crew agents for {} — {} rows", app.store.repo_root.display(), app.rows.len());
     for r in &app.rows {
         let kind = if r.interactive { "agent" } else { "session" };
         println!("{:<7} {:<9} {:<8} {}", kind, r.harness, r.status, r.task);
@@ -118,6 +268,16 @@ fn event_loop(app: &mut App, terminal: &mut Term) -> Result<()> {
     // fast tick so the embedded terminal feels live; refresh list less often.
     let refresh_every = Duration::from_millis(800);
     let mut last_refresh = Instant::now();
+    // gh is a network call — poll PRs on a slow timer, first pass ~immediately.
+    let pr_every = Duration::from_secs(20);
+    let mut last_pr = Instant::now()
+        .checked_sub(pr_every)
+        .unwrap_or_else(Instant::now);
+    // per-row git status is heavier than the list refresh — run it less often.
+    let dirty_every = Duration::from_millis(2500);
+    let mut last_dirty = Instant::now()
+        .checked_sub(dirty_every)
+        .unwrap_or_else(Instant::now);
 
     loop {
         terminal.draw(|f| ui::draw(f, app))?;
@@ -137,23 +297,74 @@ fn event_loop(app: &mut App, terminal: &mut Term) -> Result<()> {
                 Event::Mouse(m) if app.mode == Mode::Normal => match m.kind {
                     MouseEventKind::ScrollDown => app.move_sel(1),
                     MouseEventKind::ScrollUp => app.move_sel(-1),
+                    MouseEventKind::Down(MouseButton::Left) => {
+                        // list occupies the left ~34%; items start at y=2 (header
+                        // row + top border). Click selects that row.
+                        let w = terminal.size().map(|s| s.width).unwrap_or(80);
+                        let left_w = w * 34 / 100;
+                        if m.column < left_w && m.row >= 2 {
+                            let idx = (m.row - 2) as usize;
+                            if idx < app.rows.len() {
+                                app.selected = idx;
+                            }
+                        }
+                    }
                     _ => {}
                 },
                 _ => {}
             }
         }
 
+        // an editor/shell was requested: drop out of the TUI, run it, come back
+        if let Some((cwd, argv)) = app.pending_shell.take() {
+            run_suspended(terminal, &cwd, &argv)?;
+        }
+
         if last_refresh.elapsed() >= refresh_every {
-            let _ = app.refresh();
+            if app.mode == Mode::Log {
+                app.tick_log(); // live-follow the open log (tail -f)
+            } else {
+                let _ = app.refresh();
+            }
             last_refresh = Instant::now();
         }
 
+        if last_pr.elapsed() >= pr_every && app.mode != Mode::Terminal {
+            app.poll_prs();
+            last_pr = Instant::now();
+        }
+
+        if last_dirty.elapsed() >= dirty_every && app.mode != Mode::Terminal {
+            app.compute_dirty();
+            last_dirty = Instant::now();
+        }
+
         if app.should_quit {
+            app.save_ui_prefs(); // remember view toggles for next run
             return Ok(());
         }
     }
 }
 
+/// Suspend the TUI (leave raw mode + alternate screen), run `argv` in `cwd`
+/// attached to the real terminal, then restore the dashboard. Used for `e`
+/// (editor) and `!` (shell) — the child fully owns the terminal while it runs.
+fn run_suspended(terminal: &mut Term, cwd: &str, argv: &[String]) -> Result<()> {
+    if argv.is_empty() {
+        return Ok(());
+    }
+    disable_raw_mode()?;
+    execute!(terminal.backend_mut(), LeaveAlternateScreen, DisableMouseCapture)?;
+    let _ = std::process::Command::new(&argv[0])
+        .args(&argv[1..])
+        .current_dir(cwd)
+        .status();
+    enable_raw_mode()?;
+    execute!(terminal.backend_mut(), EnterAlternateScreen, EnableMouseCapture)?;
+    terminal.clear()?;
+    Ok(())
+}
+
 /// In Terminal mode every key is forwarded to the agent's PTY, except Ctrl-o
 /// which leaves the embedded terminal and returns to the dashboard.
 fn handle_terminal_key(app: &mut App, key: KeyEvent) {
@@ -169,6 +380,14 @@ fn handle_terminal_key(app: &mut App, key: KeyEvent) {
 
 fn handle_key(app: &mut App, key: KeyEvent) {
     let code = key.code;
+    // Ctrl-d / Ctrl-u half-page the list (checked before plain-letter binds).
+    if app.mode == Mode::Normal && key.modifiers.contains(KeyModifiers::CONTROL) {
+        match code {
+            KeyCode::Char('d') => { app.move_sel(8); return; }
+            KeyCode::Char('u') => { app.move_sel(-8); return; }
+            _ => {}
+        }
+    }
     match app.mode {
         Mode::Normal => match code {
             KeyCode::Char('q') => {
@@ -180,24 +399,82 @@ fn handle_key(app: &mut App, key: KeyEvent) {
             }
             KeyCode::Char('j') | KeyCode::Down => app.move_sel(1),
             KeyCode::Char('k') | KeyCode::Up => app.move_sel(-1),
+            KeyCode::Char('g') | KeyCode::Home => app.sel_top(),
+            KeyCode::Char('G') | KeyCode::End => app.sel_bottom(),
+            KeyCode::PageDown => app.move_sel(10),
+            KeyCode::PageUp => app.move_sel(-10),
+            KeyCode::Char(']') => app.jump_failed(1),
+            KeyCode::Char('[') => app.jump_failed(-1),
+            KeyCode::Char('y') => app.yank_worktree(),
             KeyCode::Char('r') => { let _ = app.refresh(); }
             KeyCode::Char('n') => app.open_new_agent(),
             KeyCode::Char('s') => {
-                if app.selected_row().map(|r| r.interactive).unwrap_or(false) {
+                let has_live = !app.marked.is_empty()
+                    || app.selected_row().map(|r| r.interactive).unwrap_or(false);
+                if has_live {
                     app.mode = Mode::ConfirmStop;
                 } else {
                     app.status_msg = "only interactive agents can be stopped".into();
                 }
             }
-            KeyCode::Char('x') => app.remove_selected(),
+            KeyCode::Char(' ') => app.toggle_mark(),
+            KeyCode::Char('A') => app.mark_all_visible(),
+            KeyCode::Esc => {
+                if !app.marked.is_empty() {
+                    app.clear_marks();
+                } else if app.category != app::Category::All {
+                    app.set_category(app::Category::All);
+                }
+            }
+            KeyCode::Char('x') => {
+                if app.marked.is_empty() { app.remove_selected(); }
+                else { app.mode = Mode::ConfirmRemove; }
+            }
+            KeyCode::Char('L') => app.open_rename(),
+            KeyCode::Char('D') => app.duplicate_selected(),
+            KeyCode::Char('S') => {
+                if app.agents.iter_mut().any(|a| a.is_alive()) {
+                    app.mode = Mode::ConfirmStopAll;
+                } else {
+                    app.status_msg = "no running agents".into();
+                }
+            }
+            KeyCode::Char('c') => app.clear_finished(),
+            KeyCode::Char('R') => app.open_retry(),
+            KeyCode::Char('P') => app.open_push(),
             KeyCode::Char('o') => app.show_worktree(),
+            KeyCode::Char('Y') => app.yank_branch(),
+            KeyCode::Char('O') => app.open_branch_web(),
+            KeyCode::Char('f') => app.fetch_selected(),
+            KeyCode::Char('e') => app.open_editor(),
+            KeyCode::Char('!') => app.open_shell(),
+            KeyCode::Char('d') => app.show_diff(),
+            KeyCode::Char('l') => app.show_log(),
             KeyCode::Char('h') => { app.show_observed = !app.show_observed; let _ = app.refresh(); }
+            KeyCode::Char('1') => app.set_category(app::Category::All),
+            KeyCode::Char('2') => app.set_category(app::Category::Running),
+            KeyCode::Char('3') => app.set_category(app::Category::Agents),
+            KeyCode::Char('4') => app.set_category(app::Category::Sessions),
+            KeyCode::Char('t') => app.cycle_sort(),
+            KeyCode::Char(',') => app.open_settings(),
             KeyCode::Char('/') => app.mode = Mode::Filter,
-            KeyCode::Char('?') => app.mode = Mode::Help,
+            KeyCode::Char('?') => { app.help_scroll = 0; app.mode = Mode::Help; }
             KeyCode::Enter => app.open_selected(),
             _ => {}
         },
-        Mode::Help => app.mode = Mode::Normal,
+        Mode::Help => match code {
+            KeyCode::Char('j') | KeyCode::Down => app.help_scroll = app.help_scroll.saturating_add(1),
+            KeyCode::Char('k') | KeyCode::Up => app.help_scroll = app.help_scroll.saturating_sub(1),
+            _ => app.mode = Mode::Normal,
+        },
+        Mode::Diff | Mode::Log => handle_viewer_key(app, key),
+        Mode::Retry => match code {
+            KeyCode::Left | KeyCode::Char('h') => app.cycle_retry_harness(-1),
+            KeyCode::Right | KeyCode::Char('l') => app.cycle_retry_harness(1),
+            KeyCode::Enter => app.confirm_retry(),
+            KeyCode::Esc | KeyCode::Char('q') => app.mode = Mode::Normal,
+            _ => {}
+        },
         Mode::ConfirmQuit => match code {
             KeyCode::Char('y') | KeyCode::Enter => app.should_quit = true,
             KeyCode::Char('n') | KeyCode::Esc => app.mode = Mode::Normal,
@@ -208,6 +485,37 @@ fn handle_key(app: &mut App, key: KeyEvent) {
             KeyCode::Char('n') | KeyCode::Esc => app.mode = Mode::Normal,
             _ => {}
         },
+        Mode::ConfirmStopAll => match code {
+            KeyCode::Char('y') => { app.stop_all(); app.mode = Mode::Normal; }
+            KeyCode::Char('n') | KeyCode::Esc => app.mode = Mode::Normal,
+            _ => {}
+        },
+        Mode::ConfirmPush => match code {
+            KeyCode::Char('y') | KeyCode::Enter => app.confirm_push(),
+            KeyCode::Char('n') | KeyCode::Esc => app.mode = Mode::Normal,
+            _ => {}
+        },
+        Mode::Settings => match code {
+            KeyCode::Left | KeyCode::Char('h') => app.settings_change(-1),
+            KeyCode::Right | KeyCode::Char('l') | KeyCode::Char(' ') => app.settings_change(1),
+            KeyCode::Tab | KeyCode::Down | KeyCode::Char('j') => app.settings_move(1),
+            KeyCode::BackTab | KeyCode::Up | KeyCode::Char('k') => app.settings_move(-1),
+            KeyCode::Enter | KeyCode::Char('s') => app.save_settings(),
+            KeyCode::Esc | KeyCode::Char('q') => app.cancel_settings(),
+            _ => {}
+        },
+        Mode::ConfirmRemove => match code {
+            KeyCode::Char('y') => { app.remove_selected(); app.mode = Mode::Normal; }
+            KeyCode::Char('n') | KeyCode::Esc => app.mode = Mode::Normal,
+            _ => {}
+        },
+        Mode::Rename => match code {
+            KeyCode::Enter => app.commit_rename(),
+            KeyCode::Esc => app.mode = Mode::Normal,
+            KeyCode::Backspace => { app.rename_buf.pop(); }
+            KeyCode::Char(c) => app.rename_buf.push(c),
+            _ => {}
+        },
         Mode::ConfirmDiscard => match code {
             KeyCode::Char('y') => { app.new_form = app::NewAgentForm::default(); app.mode = Mode::Normal; }
             KeyCode::Char('n') | KeyCode::Esc => app.mode = Mode::NewAgent,
@@ -225,8 +533,43 @@ fn handle_key(app: &mut App, key: KeyEvent) {
     }
 }
 
+/// Shared key handling for the full-screen diff and log viewers: scrolling,
+/// vim jumps, and an in-viewer `/` search (Enter/n/N to cycle matches).
+fn handle_viewer_key(app: &mut App, key: KeyEvent) {
+    let code = key.code;
+    if app.find_input {
+        match code {
+            KeyCode::Enter => { app.find_input = false; app.find_next(1); }
+            KeyCode::Esc => { app.find_input = false; app.find_query.clear(); app.status_msg.clear(); }
+            KeyCode::Backspace => { app.find_query.pop(); }
+            KeyCode::Char(c) => app.find_query.push(c),
+            _ => {}
+        }
+        return;
+    }
+    match code {
+        KeyCode::Char('j') | KeyCode::Down => app.scroll_viewer(1),
+        KeyCode::Char('k') | KeyCode::Up => app.scroll_viewer(-1),
+        KeyCode::PageDown | KeyCode::Char(' ') => app.scroll_viewer(20),
+        KeyCode::PageUp => app.scroll_viewer(-20),
+        KeyCode::Char('g') | KeyCode::Home => app.scroll_viewer(i64::MIN),
+        KeyCode::Char('G') | KeyCode::End => app.scroll_viewer(i64::MAX),
+        KeyCode::Char('/') => { app.find_input = true; app.find_query.clear(); }
+        KeyCode::Char('n') => app.find_next(1),
+        KeyCode::Char('N') => app.find_next(-1),
+        KeyCode::Char('r') if app.mode == Mode::Log => app.show_log(),
+        KeyCode::Char('q') | KeyCode::Esc => {
+            if app.mode == Mode::Log { app.log_path_open = None; }
+            app.mode = Mode::Normal;
+            app.find_query.clear();
+            app.find_input = false;
+        }
+        _ => {}
+    }
+}
+
 fn handle_new_agent_key(app: &mut App, key: KeyEvent) {
-    use app::{FIELD_HARNESS, FIELD_IMAGES, FIELD_MODEL, FIELD_TASK, FIELD_WORKTREE, FIELD_COUNT};
+    use app::{FIELD_HARNESS, FIELD_IMAGES, FIELD_MODEL, FIELD_TASK, FIELD_WORKFLOW, FIELD_WORKTREE, FIELD_COUNT};
     let ctrl = key.modifiers.contains(KeyModifiers::CONTROL);
 
     // Ctrl-S launches from any field (task uses Enter for newlines).
@@ -271,6 +614,11 @@ fn handle_new_agent_key(app: &mut App, key: KeyEvent) {
 
     match f.field {
         FIELD_TASK => { f.task.input(key); }
+        FIELD_WORKFLOW => match key.code {
+            KeyCode::Left | KeyCode::Char('h') => f.cycle_workflow(-1),
+            KeyCode::Right | KeyCode::Char('l') | KeyCode::Char(' ') => f.cycle_workflow(1),
+            _ => {}
+        },
         FIELD_HARNESS => match key.code {
             KeyCode::Left | KeyCode::Char('h') => f.cycle_harness(-1),
             KeyCode::Right | KeyCode::Char('l') => f.cycle_harness(1),
@@ -311,6 +659,8 @@ fn key_to_bytes(key: KeyEvent) -> Vec<u8> {
         KeyCode::Enter => vec![b'\r'],
         KeyCode::Backspace => vec![0x7f],
         KeyCode::Tab => vec![b'\t'],
+        KeyCode::BackTab => b"\x1b[Z".to_vec(), // shift-tab: lets Claude Code cycle modes
+
         KeyCode::Esc => vec![0x1b],
         KeyCode::Left => b"\x1b[D".to_vec(),
         KeyCode::Right => b"\x1b[C".to_vec(),
@@ -325,6 +675,13 @@ fn key_to_bytes(key: KeyEvent) -> Vec<u8> {
     }
 }
 
+fn app_now() -> f64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.as_secs_f64())
+        .unwrap_or(0.0)
+}
+
 fn arg_value(args: &[String], flag: &str) -> Option<String> {
     args.iter().position(|a| a == flag).and_then(|i| args.get(i + 1).cloned())
 }
@@ -367,4 +724,345 @@ mod tests {
         assert_eq!(a.mode, Mode::Normal);
         assert!(a.new_form.task_text().is_empty());
     }
+
+    fn ch(c: char) -> KeyEvent {
+        KeyEvent::new(KeyCode::Char(c), KeyModifiers::empty())
+    }
+
+    #[test]
+    fn backtab_forwards_shift_tab_sequence() {
+        // shift-tab must reach the PTY as CSI Z so Claude Code can cycle modes.
+        let bytes = key_to_bytes(KeyEvent::new(KeyCode::BackTab, KeyModifiers::empty()));
+        assert_eq!(bytes, b"\x1b[Z");
+    }
+
+    #[test]
+    fn form_tab_reaches_workflow_field_and_cycles() {
+        let mut a = app();
+        a.open_new_agent();
+        // Tab off the task editor lands on the workflow picker.
+        handle_new_agent_key(&mut a, KeyEvent::new(KeyCode::Tab, KeyModifiers::empty()));
+        assert_eq!(a.new_form.field, app::FIELD_WORKFLOW);
+        assert_eq!(a.new_form.workflow_idx, 0);
+        handle_new_agent_key(&mut a, KeyEvent::new(KeyCode::Right, KeyModifiers::empty()));
+        assert_eq!(a.new_form.workflow_idx, 1);
+    }
+
+    #[test]
+    fn diff_mode_opens_scrolls_and_closes() {
+        let mut a = app();
+        // no worktree selected → show_diff reports, stays Normal
+        a.show_diff();
+        assert_eq!(a.mode, Mode::Normal);
+        // simulate an open diff view and drive scroll/close keys
+        a.diff_text = (0..50).map(|i| format!("line {i}")).collect::<Vec<_>>().join("\n");
+        a.mode = Mode::Diff;
+        handle_key(&mut a, ch('j'));
+        assert_eq!(a.diff_scroll, 1);
+        handle_key(&mut a, KeyEvent::new(KeyCode::PageDown, KeyModifiers::empty()));
+        assert_eq!(a.diff_scroll, 21);
+        handle_key(&mut a, ch('k'));
+        assert_eq!(a.diff_scroll, 20);
+        handle_key(&mut a, ch('q'));
+        assert_eq!(a.mode, Mode::Normal);
+    }
+
+    #[test]
+    fn log_view_reads_file_scrolls_and_closes() {
+        use agent::{ManagedAgent, Row};
+        let dir = std::env::temp_dir().join(format!("nexum-logv-{}", std::process::id()));
+        std::fs::create_dir_all(&dir).unwrap();
+        let logp = dir.join("a.log");
+        std::fs::write(&logp, "line1\nERROR boom\nline3\n").unwrap();
+        let ma = ManagedAgent {
+            agent_id: "m1".into(), harness: Some("cursor".into()), model: None,
+            worktree: None, branch: None, status: Some("running".into()),
+            cost_usd: None, task: Some("t".into()), step_index: None,
+            updated_ts: None, pid: None,
+            log_path: Some(logp.to_string_lossy().into_owned()),
+        };
+        let mut a = app();
+        a.rows = vec![Row::from_managed(&ma)];
+        a.selected = 0;
+        a.show_log();
+        assert_eq!(a.mode, Mode::Log);
+        assert!(a.log_text.contains("ERROR boom"), "{}", a.log_text);
+        handle_key(&mut a, ch('k')); // scroll
+        handle_key(&mut a, ch('q'));
+        assert_eq!(a.mode, Mode::Normal);
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn log_follow_tracks_bottom_but_respects_scrollback() {
+        use agent::{ManagedAgent, Row};
+        let dir = std::env::temp_dir().join(format!("nexum-logf-{}", std::process::id()));
+        std::fs::create_dir_all(&dir).unwrap();
+        let logp = dir.join("f.log");
+        std::fs::write(&logp, "l1\nl2\nl3\n").unwrap();
+        let ma = ManagedAgent {
+            agent_id: "f".into(), harness: Some("cursor".into()), model: None,
+            worktree: None, branch: None, status: Some("running".into()),
+            cost_usd: None, task: None, step_index: None, updated_ts: None, pid: None,
+            log_path: Some(logp.to_string_lossy().into_owned()),
+        };
+        let mut a = app();
+        a.rows = vec![Row::from_managed(&ma)];
+        a.selected = 0;
+        a.show_log();
+        assert_eq!(a.log_scroll, 2); // parked at bottom (3 lines → idx 2)
+
+        // new output arrives; following → scroll advances to the new bottom
+        std::fs::write(&logp, "l1\nl2\nl3\nl4\nl5\n").unwrap();
+        a.tick_log();
+        assert_eq!(a.log_scroll, 4);
+
+        // reader scrolls up; new output must NOT yank them back down
+        a.scroll_log(-3); // now at 1
+        assert_eq!(a.log_scroll, 1);
+        std::fs::write(&logp, "l1\nl2\nl3\nl4\nl5\nl6\n").unwrap();
+        a.tick_log();
+        assert_eq!(a.log_scroll, 1);
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    /// Full drive of a live agent: launch a stub PTY agent, focus its terminal,
+    /// forward a keystroke, leave, bulk-stop, then clear it.
+    #[test]
+    fn e2e_spawn_chat_stopall_clear() {
+        let dir = std::env::temp_dir().join(format!("nexum-e2e-{}", std::process::id()));
+        std::fs::create_dir_all(&dir).unwrap();
+        std::env::set_var("NEXUM_INTERACTIVE_CMD_CLAUDE", "cat");
+        let mut a = App::new(store::Store::new(dir.clone(), dir.join("scripts")));
+        a.term_size = (80, 24);
+
+        // launch via the form, running in the dir itself (no worktree.py)
+        a.open_new_agent();
+        a.new_form.task.insert_str("hello agent");
+        a.new_form.worktree_new = false;
+        a.spawn_from_form();
+        assert_eq!(a.mode, Mode::Terminal, "should drop into chat");
+        assert_eq!(a.agents.len(), 1);
+        assert!(a.agents[0].is_alive());
+
+        // forward a keystroke to the PTY, then leave the terminal (Ctrl-o)
+        handle_terminal_key(&mut a, ch('x'));
+        handle_terminal_key(&mut a, KeyEvent::new(KeyCode::Char('o'), KeyModifiers::CONTROL));
+        assert_eq!(a.mode, Mode::Normal);
+
+        // review its worktree diff (dir isn't a git repo → friendly message)
+        handle_key(&mut a, ch('d'));
+        assert_eq!(a.mode, Mode::Diff);
+        assert!(!a.diff_text.is_empty());
+        handle_key(&mut a, esc());
+
+        // bulk stop-all: S → confirm → y
+        handle_key(&mut a, ch('S'));
+        assert_eq!(a.mode, Mode::ConfirmStopAll);
+        handle_key(&mut a, ch('y'));
+        assert_eq!(a.mode, Mode::Normal);
+        // give the kill a moment to land
+        std::thread::sleep(std::time::Duration::from_millis(200));
+        assert!(!a.agents[0].is_alive(), "stop_all should have killed the agent");
+
+        // clear finished drops the dead proc
+        handle_key(&mut a, ch('c'));
+        assert!(a.agents.is_empty(), "clear_finished should remove the dead agent");
+
+        std::env::remove_var("NEXUM_INTERACTIVE_CMD_CLAUDE");
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    /// e2e: `crew --new` creates a worktree natively and runs the harness
+    /// headless in it (stub harness writes a marker) — no engine needed.
+    #[test]
+    fn e2e_new_launches_headless_in_worktree() {
+        use std::process::Command;
+        let manifest = env!("CARGO_MANIFEST_DIR");
+        let bin = PathBuf::from(manifest).join("target/debug/crew");
+        let fake = PathBuf::from(manifest).parent().unwrap().join("tests/fixtures/fake_harness.py");
+        if !bin.exists() || !fake.exists() { return; }
+        let py = std::env::var("NEXUM_PYTHON").unwrap_or_else(|_| "python3".into());
+
+        let repo = std::env::temp_dir().join(format!("crew-new-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&repo);
+        std::fs::create_dir_all(&repo).unwrap();
+        let g = |a: &[&str]| { Command::new("git").arg("-C").arg(&repo).args(a).output().unwrap(); };
+        g(&["init", "-q"]); g(&["config", "user.email", "t@t"]); g(&["config", "user.name", "t"]);
+        std::fs::write(repo.join("seed.txt"), "x").unwrap();
+        g(&["add", "seed.txt"]); g(&["commit", "-qm", "init"]);
+
+        let out = Command::new(&bin)
+            .args(["--new", "hello task", "--harness", "claude"])
+            .current_dir(&repo)
+            .env("NEXUM_HEADLESS_CMD_CLAUDE", format!("{} {}", py, fake.display()))
+            .output().unwrap();
+        assert!(out.status.success(), "stderr: {}", String::from_utf8_lossy(&out.stderr));
+        let stdout = String::from_utf8_lossy(&out.stdout);
+        assert!(stdout.contains("branch crew/"), "stdout: {stdout}");
+
+        // the stub harness ran inside the created worktree
+        let slug = stdout.split("branch crew/").nth(1).unwrap()
+            .split_whitespace().next().unwrap().to_string();
+        let marker = repo.join(".crew/worktrees").join(&slug).join("fake_out.txt");
+        assert!(marker.exists(), "marker missing at {}", marker.display());
+        let _ = std::fs::remove_dir_all(&repo);
+    }
+
+    /// e2e: push commits the worktree and pushes its branch to origin (a local
+    /// bare remote — no network). Proves the push path works standalone.
+    #[test]
+    fn e2e_push_pushes_branch_to_origin() {
+        use std::process::Command;
+        let base = std::env::temp_dir().join(format!("crew-push-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&base);
+        std::fs::create_dir_all(&base).unwrap();
+        let origin = base.join("origin.git");
+        let work = base.join("work");
+        Command::new("git").args(["init", "--bare", "-q"]).arg(&origin).output().unwrap();
+        let g = |a: &[&str]| { Command::new("git").arg("-C").arg(&work).args(a).output().unwrap(); };
+        std::fs::create_dir_all(&work).unwrap();
+        g(&["init", "-q"]); g(&["config", "user.email", "t@t"]); g(&["config", "user.name", "t"]);
+        std::fs::write(work.join("seed.txt"), "x").unwrap();
+        g(&["add", "seed.txt"]); g(&["commit", "-qm", "init"]);
+        g(&["remote", "add", "origin", origin.to_str().unwrap()]);
+
+        let work = std::fs::canonicalize(&work).unwrap();
+        let mut app = App::new(store::Store::new(work.clone(), work.join("no-scripts")));
+        let wt = app.store.create_worktree("push-me").unwrap();
+        std::fs::write(std::path::Path::new(&wt).join("new.txt"), "hi").unwrap();
+        app.push_queue = vec![(wt, "crew/push-me".into(), "add new.txt".into())];
+        app.confirm_push();
+
+        // origin now has the branch
+        let out = Command::new("git").arg("-C").arg(&origin)
+            .args(["branch", "--list", "crew/push-me"]).output().unwrap();
+        assert!(String::from_utf8_lossy(&out.stdout).contains("crew/push-me"),
+            "branch not on origin; status: {}", app.status_msg);
+        let _ = std::fs::remove_dir_all(&base);
+    }
+
+    /// e2e: retry/re-delegate from the TUI dispatches the task on the chosen
+    /// harness and records a new agent row (polled from the store).
+    #[test]
+    fn e2e_retry_redelegates_and_records_agent() {
+        use agent::{ManagedAgent, Row};
+        use std::process::Command;
+        let manifest = env!("CARGO_MANIFEST_DIR");
+        let root = PathBuf::from(manifest).parent().unwrap().to_path_buf();
+        let scripts = root.join("scripts");
+        let fake = root.join("tests/fixtures/fake_harness.py");
+        if !fake.exists() { return; }
+        let py = std::env::var("NEXUM_PYTHON").unwrap_or_else(|_| "python3".into());
+
+        let repo = std::env::temp_dir().join(format!("nexum-retry-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&repo);
+        std::fs::create_dir_all(&repo).unwrap();
+        let git = |a: &[&str]| { Command::new("git").arg("-C").arg(&repo).args(a).output().unwrap(); };
+        git(&["init", "-q"]); git(&["config", "user.email", "t@t"]); git(&["config", "user.name", "t"]);
+        std::fs::write(repo.join("seed.txt"), "seed").unwrap();
+        git(&["add", "seed.txt"]); git(&["commit", "-qm", "init"]);
+
+        let data = repo.join(".nexum-data");
+        std::env::set_var("CLAUDE_PLUGIN_DATA", &data);
+        std::env::set_var("NEXUM_HARNESS_CMD_CURSOR", format!("{} {}", py, fake.display()));
+
+        let mut app = App::new(store::Store::new(std::fs::canonicalize(&repo).unwrap(), scripts.clone()));
+        let ma = ManagedAgent {
+            agent_id: "orig".into(), harness: Some("cursor".into()), model: None,
+            worktree: None, branch: None, status: Some("failed".into()), cost_usd: None,
+            task: Some("retry writes a file".into()), step_index: None, updated_ts: None,
+            pid: None, log_path: None,
+        };
+        app.rows = vec![Row::from_managed(&ma)];
+        app.selected = 0;
+        app.open_retry();
+        assert_eq!(app.mode, Mode::Retry);
+        assert_eq!(app.retry_harness_idx, 2); // cursor
+        app.confirm_retry();
+        assert_eq!(app.mode, Mode::Normal);
+        let id = app.status_msg.rsplit("→ ").next().unwrap().trim().to_string();
+        assert!(id.starts_with("retry_"), "status: {}", app.status_msg);
+
+        // poll the store until the detached dispatch finishes
+        let deadline = std::time::Instant::now() + Duration::from_secs(20);
+        let mut done = false;
+        while std::time::Instant::now() < deadline {
+            let out = Command::new(&py).arg(scripts.join("store.py"))
+                .args(["agent-get", "--id", &id])
+                .env("CLAUDE_PLUGIN_DATA", &data).output().unwrap();
+            let s = String::from_utf8_lossy(&out.stdout);
+            if s.contains("\"status\": \"done\"") { done = true; break; }
+            std::thread::sleep(Duration::from_millis(200));
+        }
+        assert!(done, "retry agent never reached done");
+
+        std::env::remove_var("CLAUDE_PLUGIN_DATA");
+        std::env::remove_var("NEXUM_HARNESS_CMD_CURSOR");
+        let _ = std::fs::remove_dir_all(&repo);
+    }
+
+    /// Cross-boundary e2e: a delegated sub-agent recorded by dispatch.py (via the
+    /// same path the MCP `delegate` tool uses) must appear in the TUI's list.
+    #[test]
+    fn e2e_delegated_agent_shows_in_tui() {
+        use std::process::Command;
+        let manifest = env!("CARGO_MANIFEST_DIR"); // .../nexum/tui
+        let root = PathBuf::from(manifest).parent().unwrap().to_path_buf(); // .../nexum
+        let scripts = root.join("scripts");
+        let fake = root.join("tests/fixtures/fake_harness.py");
+        if !fake.exists() {
+            return; // fixtures not present (partial checkout) — skip
+        }
+        let py = std::env::var("NEXUM_PYTHON").unwrap_or_else(|_| "python3".into());
+
+        // throwaway git repo
+        let repo = std::env::temp_dir().join(format!("nexum-deleg-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&repo);
+        std::fs::create_dir_all(&repo).unwrap();
+        let git = |args: &[&str]| {
+            Command::new("git").arg("-C").arg(&repo).args(args).output().unwrap();
+        };
+        git(&["init", "-q"]);
+        git(&["config", "user.email", "t@t"]);
+        git(&["config", "user.name", "t"]);
+        std::fs::write(repo.join("seed.txt"), "seed").unwrap();
+        git(&["add", "seed.txt"]);
+        git(&["commit", "-qm", "init"]);
+
+        let data = repo.join(".nexum-data");
+        let step = repo.join("step.json");
+        std::fs::write(&step,
+            r#"{"title":"delegated bit","objective":"write file","acceptance":"test -f fake_out.txt","files":["fake_out.txt"],"scope_deny":[]}"#).unwrap();
+
+        // run dispatch exactly like the delegation MCP does, with the fake harness
+        let out = Command::new(&py)
+            .arg(scripts.join("dispatch.py"))
+            .args(["--harness", "cursor", "--model", "auto",
+                   "--repo", repo.to_str().unwrap(),
+                   "--new-worktree", "--slug", "deleg",
+                   "--step-file", step.to_str().unwrap(),
+                   "--agent-id", "tui_deleg_e2e"])
+            .env("CLAUDE_PLUGIN_DATA", &data)
+            .env("NEXUM_HARNESS_CMD_CURSOR", format!("{} {}", py, fake.display()))
+            .env("PYTHONPATH", &scripts)
+            .output()
+            .unwrap();
+        assert!(out.status.success(), "dispatch failed: {}",
+                String::from_utf8_lossy(&out.stderr));
+
+        // now the TUI store must read that agent back and refresh must list it
+        std::env::set_var("CLAUDE_PLUGIN_DATA", &data);
+        let mut app = App::new(store::Store::new(
+            std::fs::canonicalize(&repo).unwrap(), scripts.clone()));
+        app.refresh().unwrap();
+        let found = app.rows.iter().find(|r| r.id == "tui_deleg_e2e")
+            .expect("delegated agent should appear in the TUI list");
+        assert_eq!(found.harness, "cursor");
+        assert_eq!(found.status, "done");
+        assert!(found.worktree.is_some());
+
+        std::env::remove_var("CLAUDE_PLUGIN_DATA");
+        let _ = std::fs::remove_dir_all(&repo);
+    }
 }
diff --git a/tui/src/pty.rs b/tui/src/pty.rs
index efc2223..66eaf22 100644
--- a/tui/src/pty.rs
+++ b/tui/src/pty.rs
@@ -19,6 +19,8 @@ pub struct AgentProc {
     pub model: String,
     pub task: String,
     pub worktree: String,
+    /// Unix seconds when this agent was launched (for "running Nm" in the list).
+    pub started: f64,
     /// vt100 screen, fed by a background reader thread; read by the renderer.
     pub parser: Arc<Mutex<vt100::Parser>>,
     writer: Box<dyn Write + Send>,
@@ -75,12 +77,17 @@ impl AgentProc {
             });
         }
 
+        let started = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .map(|d| d.as_secs_f64())
+            .unwrap_or(0.0);
         let proc = AgentProc {
             id,
             harness,
             model,
             task: task.clone(),
             worktree,
+            started,
             parser,
             writer,
             master: pair.master,
diff --git a/tui/src/store.rs b/tui/src/store.rs
index 7b42e1e..0de3737 100644
--- a/tui/src/store.rs
+++ b/tui/src/store.rs
@@ -1,9 +1,13 @@
-//! Subprocess JSON client for the nexum Python engine.
+//! Persistence + optional engine integration.
 //!
-//! The TUI shells `python3 <scripts>/store.py … --json` and `worktree.py …`, so
-//! the schema/logic stays owned by the Python engine and the Rust side is thin.
+//! `crew` runs **standalone**: it manages its own agent registry (`.crew/
+//! agents.json`) and creates git worktrees natively (no external process). If a
+//! nexum Python engine is present alongside it (`store.py`/`dispatch.py`), crew
+//! *additionally* surfaces that engine's observed sessions and headless
+//! delegated agents — but nothing here requires it. Every engine call is
+//! fail-open: absent engine → empty results, never an error.
 
-use crate::agent::Session;
+use crate::agent::{ManagedAgent, Session};
 use anyhow::{anyhow, Context, Result};
 use serde::{Deserialize, Serialize};
 use std::path::{Path, PathBuf};
@@ -19,6 +23,39 @@ pub struct AgentRecord {
     pub model: String,
     pub worktree: String,
     pub task: String,
+    /// Optional friendly label shown instead of the task in the list.
+    #[serde(default)]
+    pub label: Option<String>,
+}
+
+/// Remembered launch choices, persisted to `.crew/config.json` so the new-agent
+/// form pre-selects what you used last time.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct LaunchPrefs {
+    pub harness_idx: usize,
+    pub model_idx: usize,
+    pub workflow_idx: usize,
+    pub worktree_new: bool,
+    // ── remembered UI state (serde defaults so old configs still load) ──
+    #[serde(default = "yes")]
+    pub show_observed: bool,
+    #[serde(default)]
+    pub sort: String, // "status" | "cost" | "recent"
+    #[serde(default)]
+    pub category: String, // "all" | "running" | "agents" | "sessions"
+}
+
+fn yes() -> bool {
+    true
+}
+
+impl Default for LaunchPrefs {
+    fn default() -> Self {
+        LaunchPrefs {
+            harness_idx: 0, model_idx: 0, workflow_idx: 0, worktree_new: true,
+            show_observed: true, sort: String::new(), category: String::new(),
+        }
+    }
 }
 
 pub struct Store {
@@ -40,6 +77,12 @@ impl Store {
         self.scripts_dir.join("store.py")
     }
 
+    /// True when the optional nexum Python engine is available (enables observed
+    /// sessions, delegated-agent listing, and dispatch-based retry).
+    pub fn has_engine(&self) -> bool {
+        self.store_py().is_file()
+    }
+
     fn repo_arg(&self) -> String {
         self.repo_root.to_string_lossy().to_string()
     }
@@ -56,8 +99,56 @@ impl Store {
         Ok(v)
     }
 
+    /// Headless/offloaded agents recorded in the SQLite `agents` table by
+    /// dispatch.py — i.e. every sub-agent delegated via `/nx-build --harness` or
+    /// the delegation MCP. This is how the TUI surfaces work it didn't spawn as a
+    /// live PTY itself.
+    pub fn managed_agents(&self) -> Vec<ManagedAgent> {
+        Command::new(&self.python)
+            .arg(self.store_py())
+            .args(["agent-list", "--repo", &self.repo_arg(), "--json"])
+            .output()
+            .ok()
+            .and_then(|out| {
+                serde_json::from_str(String::from_utf8_lossy(&out.stdout).trim()).ok()
+            })
+            .unwrap_or_default()
+    }
+
+    fn config_path(&self) -> PathBuf {
+        self.repo_root.join(".crew").join("config.json")
+    }
+
+    /// Load remembered launch defaults (defaults if absent/unparseable).
+    pub fn load_prefs(&self) -> LaunchPrefs {
+        std::fs::read_to_string(self.config_path())
+            .ok()
+            .and_then(|s| serde_json::from_str(&s).ok())
+            .unwrap_or_default()
+    }
+
+    /// Persist launch defaults (best-effort).
+    pub fn save_prefs(&self, p: &LaunchPrefs) {
+        let path = self.config_path();
+        if let Some(parent) = path.parent() {
+            let _ = std::fs::create_dir_all(parent);
+        }
+        if let Ok(j) = serde_json::to_string_pretty(p) {
+            let _ = std::fs::write(path, j);
+        }
+    }
+
+    /// Delete a headless agent row from the store (`agent-del`). Best-effort;
+    /// a no-op for ids that aren't in the SQLite `agents` table.
+    pub fn delete_agent(&self, id: &str) {
+        let _ = Command::new(&self.python)
+            .arg(self.store_py())
+            .args(["agent-del", "--id", id])
+            .output();
+    }
+
     fn registry_path(&self) -> PathBuf {
-        self.repo_root.join(".nexum-data").join("tui-agents.json")
+        self.repo_root.join(".crew").join("agents.json")
     }
 
     /// Load the persisted (resumable) agent records for this repo.
@@ -79,23 +170,98 @@ impl Store {
         }
     }
 
-    /// Create an isolated git worktree via worktree.py; returns its path.
+    /// Create an isolated git worktree natively (no external engine): a new
+    /// branch `crew/<slug>` at `<repo>/.crew/worktrees/<slug>`. If the branch
+    /// already exists, checks it out into the worktree instead. Returns the path.
     pub fn create_worktree(&self, slug: &str) -> Result<String> {
-        let out = Command::new(&self.python)
-            .arg(self.scripts_dir.join("worktree.py"))
-            .args(["--create", "--repo", &self.repo_arg(), "--slug", slug])
+        let dest = self.repo_root.join(".crew").join("worktrees").join(slug);
+        if let Some(parent) = dest.parent() {
+            std::fs::create_dir_all(parent).context("mkdir worktrees")?;
+        }
+        let dest_s = dest.to_string_lossy().to_string();
+        let branch = format!("crew/{}", slug);
+        // fresh branch off HEAD; on failure (branch exists) attach the existing one
+        if matches!(self.git(&["worktree", "add", "-b", &branch, &dest_s]), Some((true, _))) {
+            return Ok(dest_s);
+        }
+        let attach = self.git(&["worktree", "add", &dest_s, &branch]);
+        match attach {
+            Some((true, _)) => Ok(dest_s),
+            Some((false, err)) => Err(anyhow!("git worktree add failed: {}", err.trim())),
+            None => Err(anyhow!("could not run git")),
+        }
+    }
+
+    /// Run a git command in the repo root; returns (success, stderr).
+    fn git(&self, args: &[&str]) -> Option<(bool, String)> {
+        let out = Command::new("git")
+            .arg("-C").arg(&self.repo_root)
+            .args(args)
             .output()
-            .context("spawn worktree.py")?;
-        let v: serde_json::Value =
-            serde_json::from_str(String::from_utf8_lossy(&out.stdout).trim())
-                .context("parse worktree.py output")?;
-        v.get("worktree")
-            .and_then(|x| x.as_str())
-            .map(|s| s.to_string())
-            .ok_or_else(|| anyhow!("worktree creation failed"))
+            .ok()?;
+        Some((out.status.success(), String::from_utf8_lossy(&out.stderr).into_owned()))
     }
 }
 
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn git(repo: &Path, args: &[&str]) {
+        Command::new("git").arg("-C").arg(repo).args(args).output().unwrap();
+    }
+
+    #[test]
+    fn launch_prefs_round_trip() {
+        let repo = std::env::temp_dir().join(format!("crew-prefs-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&repo);
+        std::fs::create_dir_all(&repo).unwrap();
+        let st = Store::new(repo.clone(), repo.join("scripts"));
+        assert_eq!(st.load_prefs().harness_idx, 0); // default when absent
+        st.save_prefs(&LaunchPrefs { harness_idx: 2, model_idx: 1, workflow_idx: 3, worktree_new: false, ..Default::default() });
+        let p = st.load_prefs();
+        assert_eq!((p.harness_idx, p.model_idx, p.workflow_idx, p.worktree_new), (2, 1, 3, false));
+        let _ = std::fs::remove_dir_all(&repo);
+    }
+
+    #[test]
+    fn native_worktree_needs_no_engine() {
+        let repo = std::env::temp_dir().join(format!("crew-wt-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&repo);
+        std::fs::create_dir_all(&repo).unwrap();
+        git(&repo, &["init", "-q"]);
+        git(&repo, &["config", "user.email", "t@t"]);
+        git(&repo, &["config", "user.name", "t"]);
+        std::fs::write(repo.join("seed.txt"), "x").unwrap();
+        git(&repo, &["add", "seed.txt"]);
+        git(&repo, &["commit", "-qm", "init"]);
+
+        let repo = std::fs::canonicalize(&repo).unwrap();
+        // scripts dir intentionally missing → standalone, no engine
+        let st = Store::new(repo.clone(), repo.join("no-such-scripts"));
+        assert!(!st.has_engine(), "should be standalone");
+
+        let wt = st.create_worktree("my-task").unwrap();
+        assert!(std::path::Path::new(&wt).is_dir(), "worktree dir missing: {}", wt);
+        assert!(wt.contains(".crew/worktrees/my-task"));
+        // the branch crew/my-task exists
+        let out = Command::new("git").arg("-C").arg(&repo)
+            .args(["branch", "--list", "crew/my-task"]).output().unwrap();
+        assert!(String::from_utf8_lossy(&out.stdout).contains("crew/my-task"));
+
+        let _ = std::fs::remove_dir_all(&repo);
+    }
+}
+
+/// True if `dir` is inside a git working tree.
+pub fn is_git_repo(dir: &Path) -> bool {
+    Command::new("git")
+        .args(["-C", &dir.to_string_lossy(), "rev-parse", "--is-inside-work-tree"])
+        .output()
+        .map(|o| o.status.success() && String::from_utf8_lossy(&o.stdout).trim() == "true")
+        .unwrap_or(false)
+}
+
 /// Resolve the git toplevel of `start` (falls back to `start` itself).
 pub fn git_toplevel(start: &Path) -> PathBuf {
     let out = Command::new("git")
diff --git a/tui/src/ui.rs b/tui/src/ui.rs
index cf4e093..d5999dd 100644
--- a/tui/src/ui.rs
+++ b/tui/src/ui.rs
@@ -4,26 +4,110 @@
 use crate::agent::{rel_time, Kind};
 use crate::app::{App, Mode};
 use ratatui::{
-    layout::{Constraint, Direction, Layout, Rect},
+    layout::{Constraint, Direction, Layout, Margin, Rect},
     style::{Color, Modifier, Style},
     text::{Line, Span},
-    widgets::{Block, Borders, Clear, List, ListItem, ListState, Paragraph, Wrap},
+    widgets::{
+        Block, BorderType, Borders, Clear, List, ListItem, ListState, Paragraph, Scrollbar,
+        ScrollbarOrientation, ScrollbarState, Wrap,
+    },
     Frame,
 };
 use tui_term::widget::PseudoTerminal;
 
+// ── theme ────────────────────────────────────────────────────────────────
+// One accent so the UI reads as a system (lazygit/k9s style). Borders are
+// rounded and dim until a panel is focused, then they light up in the accent.
+const ACCENT: Color = Color::Cyan;
+const ACCENT_DIM: Color = Color::DarkGray;
+
+/// A rounded panel with a dim border and a subtle title.
+fn panel(title: &str) -> Block<'static> {
+    Block::default()
+        .borders(Borders::ALL)
+        .border_type(BorderType::Rounded)
+        .border_style(Style::default().fg(ACCENT_DIM))
+        .title(Span::styled(title.to_string(), Style::default().fg(Color::Gray)))
+}
+
+/// A rounded panel whose border + title are lit in the accent (focused).
+fn panel_focused(title: &str, color: Color) -> Block<'static> {
+    Block::default()
+        .borders(Borders::ALL)
+        .border_type(BorderType::Rounded)
+        .border_style(Style::default().fg(color))
+        .title(Span::styled(title.to_string(), Style::default().fg(color).add_modifier(Modifier::BOLD)))
+}
+
+/// A rounded modal dialog block with a caller-styled title span.
+fn dialog(title: Span<'static>) -> Block<'static> {
+    Block::default()
+        .borders(Borders::ALL)
+        .border_type(BorderType::Rounded)
+        .border_style(Style::default().fg(ACCENT_DIM))
+        .title(title)
+}
+
+/// Braille spinner frame for "running", cycled from wall-clock time.
+fn spinner() -> &'static str {
+    const F: [&str; 10] = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+    let i = (now_millis() / 100 % 10) as usize;
+    F[i]
+}
+
+/// Render a vertical scrollbar on the right edge of `area` for a scrolled view.
+fn scrollbar(f: &mut Frame, area: Rect, pos: u16, total: usize) {
+    if total == 0 {
+        return;
+    }
+    let mut state = ScrollbarState::new(total).position(pos as usize);
+    f.render_stateful_widget(
+        Scrollbar::new(ScrollbarOrientation::VerticalRight)
+            .begin_symbol(None).end_symbol(None)
+            .thumb_style(Style::default().fg(ACCENT)),
+        area.inner(Margin { vertical: 1, horizontal: 0 }),
+        &mut state,
+    );
+}
+
 fn status_color(status: &str) -> Color {
     match status {
         "running" => Color::Green,
+        "done" => Color::Green,
+        "failed" => Color::Red,
         "resumable" => Color::Yellow,
         "exited" => Color::DarkGray,
         _ => Color::Cyan, // observed
     }
 }
 
+/// Per-harness accent so you can scan the list by tool at a glance (k9s-style).
+fn harness_color(h: &str) -> Color {
+    match h {
+        "claude" => Color::Magenta,
+        "cursor" => Color::Blue,
+        "opencode" => Color::Green,
+        "session" => Color::DarkGray,
+        _ => Color::Gray,
+    }
+}
+
+/// A compact unicode meter like `███░░░` for a 0–100 percentage.
+fn meter(pct: f64, width: usize) -> String {
+    let p = (pct / 100.0).clamp(0.0, 1.0);
+    let filled = (p * width as f64).round() as usize;
+    let mut s = String::new();
+    for i in 0..width {
+        s.push(if i < filled { '█' } else { '░' });
+    }
+    s
+}
+
 fn status_icon(status: &str) -> &'static str {
     match status {
         "running" => "●",
+        "done" => "✓",
+        "failed" => "✗",
         "resumable" => "▷",
         "exited" => "□",
         _ => "·",
@@ -49,14 +133,143 @@ pub fn draw(f: &mut Frame, app: &App) {
 
     match app.mode {
         Mode::NewAgent => draw_form(f, app),
-        Mode::Help => draw_help(f),
+        Mode::Help => draw_help(f, app),
+        Mode::Diff => draw_diff(f, app),
+        Mode::Log => draw_log(f, app),
         Mode::ConfirmStop => draw_confirm(f, app),
+        Mode::ConfirmStopAll => draw_confirm_stop_all(f, app),
         Mode::ConfirmQuit => draw_confirm_quit(f, app),
         Mode::ConfirmDiscard => draw_confirm_discard(f),
+        Mode::Retry => draw_retry(f, app),
+        Mode::ConfirmPush => draw_confirm_push(f, app),
+        Mode::Settings => draw_settings(f, app),
+        Mode::ConfirmRemove => draw_confirm_remove(f, app),
+        Mode::Rename => draw_rename(f, app),
         _ => {}
     }
 }
 
+fn draw_confirm_remove(f: &mut Frame, app: &App) {
+    let area = centered(52, 20, f.area());
+    f.render_widget(Clear, area);
+    let lines = vec![
+        Line::from(""),
+        Line::from(Span::raw(format!("  Remove {} marked agent(s)?", app.marked.len()))),
+        Line::from(Span::styled("  (worktrees stay on disk)", Style::default().fg(Color::DarkGray))),
+        Line::from(""),
+        Line::from(Span::styled("  [y] remove   [n/esc] cancel", Style::default().fg(Color::DarkGray))),
+    ];
+    f.render_widget(Paragraph::new(lines)
+        .block(dialog(Span::styled(" confirm remove ", Style::default().fg(Color::Red)))), area);
+}
+
+fn draw_rename(f: &mut Frame, app: &App) {
+    let area = centered(56, 20, f.area());
+    f.render_widget(Clear, area);
+    let lines = vec![
+        Line::from(""),
+        Line::from(Span::styled("  Label this agent (blank clears):", Style::default().fg(Color::Gray))),
+        Line::from(vec![Span::raw("  "),
+            Span::styled(format!("{}_", app.rename_buf),
+                Style::default().fg(Color::Green).add_modifier(Modifier::BOLD))]),
+        Line::from(""),
+        Line::from(Span::styled("  [enter] save   [esc] cancel", Style::default().fg(Color::DarkGray))),
+    ];
+    f.render_widget(Paragraph::new(lines).block(panel_focused(" rename ", ACCENT)), area);
+}
+
+fn draw_settings(f: &mut Frame, app: &App) {
+    let Some(p) = &app.settings else { return };
+    let area = centered(62, 44, f.area());
+    f.render_widget(Clear, area);
+    use crate::app::{model_presets, HARNESSES, WORKFLOWS};
+    let harness = HARNESSES[p.harness_idx.min(2)];
+    let presets = model_presets(p.harness_idx);
+    let model = presets[p.model_idx.min(presets.len() - 1)];
+    let workflow = WORKFLOWS[p.workflow_idx.min(WORKFLOWS.len() - 1)];
+    let wt = if p.worktree_new { "new git worktree (isolated)" } else { "current repo (shared)" };
+
+    let row = |i: usize, label: &str, val: &str| {
+        let active = app.settings_field == i;
+        let arrow = if active { ACCENT } else { ACCENT_DIM };
+        Line::from(vec![
+            Span::styled(format!("{}{:<10}", if active { "▶ " } else { "  " }, label),
+                if active { Style::default().fg(Color::White).add_modifier(Modifier::BOLD) }
+                else { Style::default().fg(Color::Gray) }),
+            Span::styled("‹ ", Style::default().fg(arrow)),
+            Span::styled(val.to_string(), Style::default().fg(Color::Green).add_modifier(Modifier::BOLD)),
+            Span::styled(" ›", Style::default().fg(arrow)),
+        ])
+    };
+    let lines = vec![
+        Line::from(Span::styled("  Default launch settings", Style::default().add_modifier(Modifier::BOLD))),
+        Line::from(Span::styled("  used to pre-fill the new-agent form", Style::default().fg(Color::DarkGray))),
+        Line::from(""),
+        row(0, "harness", harness),
+        row(1, "model", model),
+        row(2, "workflow", workflow),
+        row(3, "worktree", wt),
+        Line::from(""),
+        Line::from(Span::styled("  [tab] field   [←→] change   [enter] save   [esc] cancel",
+            Style::default().fg(Color::DarkGray))),
+    ];
+    f.render_widget(Paragraph::new(lines).block(panel_focused(" settings ", ACCENT)), area);
+}
+
+fn draw_confirm_push(f: &mut Frame, app: &App) {
+    let area = centered(64, 34, f.area());
+    f.render_widget(Clear, area);
+    let has_gh = crate::app::gh_available();
+    let n = app.push_queue.len();
+    let target = if n == 1 {
+        Line::from(vec![Span::styled("  push branch  ", Style::default().fg(Color::DarkGray)),
+            Span::styled(app.push_queue.first().map(|q| q.1.clone()).unwrap_or_default(),
+                Style::default().fg(Color::Yellow).add_modifier(Modifier::BOLD))])
+    } else {
+        Line::from(Span::styled(format!("  push {} marked agent(s)", n),
+            Style::default().fg(Color::Yellow).add_modifier(Modifier::BOLD)))
+    };
+    let lines = vec![
+        Line::from(""),
+        target,
+        Line::from(""),
+        Line::from(Span::styled(
+            if has_gh { "  → commits all changes, pushes to origin, opens a PR (gh)" }
+            else { "  → commits all changes, pushes to origin (install gh for a PR)" },
+            Style::default().fg(Color::Gray))),
+        Line::from(""),
+        Line::from(Span::styled("  [y] push   [n/esc] cancel", Style::default().fg(Color::DarkGray))),
+    ];
+    f.render_widget(Paragraph::new(lines).wrap(Wrap { trim: false })
+        .block(panel_focused(" push + PR ", Color::Green)), area);
+}
+
+fn draw_retry(f: &mut Frame, app: &App) {
+    let area = centered(60, 34, f.area());
+    f.render_widget(Clear, area);
+    let harness = crate::app::HARNESSES[app.retry_harness_idx.min(2)];
+    let lines = vec![
+        Line::from(""),
+        Line::from(vec![Span::raw("  re-delegate: "),
+            Span::styled(truncate(&app.retry_task, area.width.saturating_sub(18) as usize),
+                Style::default().fg(Color::White).add_modifier(Modifier::BOLD))]),
+        Line::from(""),
+        Line::from(vec![
+            Span::styled("  harness  ", Style::default().fg(Color::DarkGray)),
+            Span::styled("‹ ", Style::default().fg(ACCENT)),
+            Span::styled(harness, Style::default().fg(harness_color(harness)).add_modifier(Modifier::BOLD)),
+            Span::styled(" ›", Style::default().fg(ACCENT)),
+            Span::styled("   (←/→ change)", Style::default().fg(Color::DarkGray)),
+        ]),
+        Line::from(""),
+        Line::from(Span::styled("  runs headless in a fresh worktree — appears as a new agent",
+            Style::default().fg(Color::DarkGray))),
+        Line::from(Span::styled("  [enter] dispatch   [esc] cancel", Style::default().fg(Color::DarkGray))),
+    ];
+    f.render_widget(Paragraph::new(lines).wrap(Wrap { trim: false })
+        .block(panel_focused(" retry / re-delegate ", ACCENT)), area);
+}
+
 fn draw_header(f: &mut Frame, app: &App, area: Rect) {
     let repo = app
         .store
@@ -68,17 +281,49 @@ fn draw_header(f: &mut Frame, app: &App, area: Rect) {
         Mode::Terminal => " CHAT ",
         _ => "",
     };
+    // per-status tallies + total metered cost across every visible row
+    let count = |s: &str| app.rows.iter().filter(|r| r.status == s).count();
+    let (running, done, failed) = (count("running"), count("done"), count("failed"));
+    let total_cost: f64 = app.rows.iter().map(|r| r.cost_usd).sum();
+
     let mut spans = vec![
-        Span::styled(" nexum ", Style::default().bg(Color::Blue).fg(Color::White).add_modifier(Modifier::BOLD)),
+        Span::styled(" crew ", Style::default().bg(Color::Blue).fg(Color::White).add_modifier(Modifier::BOLD)),
         Span::raw(format!(" {} ", repo)),
-        Span::styled(
-            format!("· {} agents ({} running) ", app.agents.len(), app.running_count()),
-            Style::default().fg(Color::Gray),
-        ),
     ];
+    if !app.repo_branch.is_empty() {
+        spans.push(Span::styled(format!(" {} ", app.repo_branch), Style::default().fg(Color::Yellow)));
+    }
+    // standalone vs. nexum-engine-connected
+    if app.store.has_engine() {
+        spans.push(Span::styled("⚙ engine ", Style::default().fg(Color::Green)));
+    }
+    spans.push(Span::styled(format!("· {} agents  ", app.rows.len()), Style::default().fg(Color::Gray)));
+    // colored status legend, only showing non-zero buckets
+    let legend = [(running, "●", Color::Green), (done, "✓", Color::Green), (failed, "✗", Color::Red)];
+    for (n, glyph, color) in legend {
+        if n > 0 {
+            spans.push(Span::styled(format!("{}{} ", glyph, n), Style::default().fg(color)));
+        }
+    }
+    if total_cost > 0.0 {
+        spans.push(Span::styled(format!(" ${:.3} ", total_cost),
+            Style::default().fg(Color::Magenta).add_modifier(Modifier::BOLD)));
+    }
+    if !app.marked.is_empty() {
+        spans.push(Span::styled(format!(" ◉ {} marked ", app.marked.len()),
+            Style::default().bg(ACCENT).fg(Color::Black).add_modifier(Modifier::BOLD)));
+    }
+    // active category / non-default sort chips (k9s-style)
+    if app.category != crate::app::Category::All {
+        spans.push(Span::styled(format!(" [{}] ", app.category.label()),
+            Style::default().bg(ACCENT).fg(Color::Black).add_modifier(Modifier::BOLD)));
+    }
+    if app.sort != crate::app::SortKey::Status {
+        spans.push(Span::styled(format!(" ↓{} ", app.sort.label()), Style::default().fg(ACCENT)));
+    }
     if app.mode == Mode::Filter || !app.filter_text.is_empty() {
         let caret = if app.mode == Mode::Filter { "_" } else { "" };
-        spans.push(Span::styled(format!("/{}{} ", app.filter_text, caret), Style::default().fg(Color::Cyan)));
+        spans.push(Span::styled(format!(" /{}{} ", app.filter_text, caret), Style::default().fg(ACCENT)));
     }
     if !mode.is_empty() {
         spans.push(Span::styled(mode, Style::default().bg(Color::Green).fg(Color::Black).add_modifier(Modifier::BOLD)));
@@ -90,9 +335,16 @@ fn draw_header(f: &mut Frame, app: &App, area: Rect) {
 fn draw_list(f: &mut Frame, app: &App, area: Rect) {
     let title = format!(" agents ({}) ", app.rows.len());
     if app.rows.is_empty() {
-        let hint = Paragraph::new("\n  no agents yet.\n\n  press [n] to launch one.")
+        // distinguish "nothing at all" from "your filter hid everything"
+        let msg = if app.all_rows.is_empty() {
+            "\n  no agents yet.\n\n  press [n] to launch one.".to_string()
+        } else {
+            format!("\n  nothing matches the [{}] filter.\n\n  press [1] for all, or [/] to search.",
+                app.category.label())
+        };
+        let hint = Paragraph::new(msg)
             .style(Style::default().fg(Color::DarkGray))
-            .block(Block::default().borders(Borders::ALL).title(title));
+            .block(panel(&title));
         f.render_widget(hint, area);
         return;
     }
@@ -102,24 +354,42 @@ fn draw_list(f: &mut Frame, app: &App, area: Rect) {
         .rows
         .iter()
         .map(|r| {
-            let icon = Span::styled(format!("{} ", status_icon(&r.status)),
+            let is_marked = app.marked.contains(&r.id);
+            let mark = Span::styled(if is_marked { "◉ " } else { "  " },
+                Style::default().fg(ACCENT).add_modifier(Modifier::BOLD));
+            // running rows get an animated spinner; everything else a static glyph
+            let glyph = if r.status == "running" { spinner() } else { status_icon(&r.status) };
+            let icon = Span::styled(format!("{} ", glyph),
                 Style::default().fg(status_color(&r.status)));
-            let who = Span::styled(format!("{:<8} ", truncate(&r.harness, 8)), Style::default().fg(Color::Gray));
+            let who = Span::styled(format!("{:<8} ", truncate(&r.harness, 8)),
+                Style::default().fg(harness_color(&r.harness)));
+            // uncommitted-changes flag (2-col slot keeps rows aligned)
+            let dirt = if app.dirty.get(&r.id).copied().unwrap_or(false) {
+                Span::styled("± ", Style::default().fg(Color::Yellow).add_modifier(Modifier::BOLD))
+            } else {
+                Span::raw("  ")
+            };
             let meta = rel_time(r.updated_ts, now);
-            let fixed = 2 + 9 + meta.len() + 1;
-            let task_w = inner_w.saturating_sub(fixed).max(6);
-            let task = truncate(if r.task.is_empty() { "(no task)" } else { &r.task }, task_w);
-            let pad = inner_w.saturating_sub(2 + 9 + task.chars().count() + meta.len());
+            let cost = if r.cost_usd > 0.0 { format!("${:.2} ", r.cost_usd) } else { String::new() };
+            // tail: [cost]+time. Left cols: mark(2)+icon(2)+who(9)+dirt(2).
+            let tail_len = cost.len() + meta.len();
+            let task_w = inner_w.saturating_sub(2 + 2 + 9 + 2 + tail_len + 1).max(6);
+            let shown = r.display();
+            let task = truncate(if shown.is_empty() { "(no task)" } else { shown }, task_w);
+            let pad = inner_w.saturating_sub(2 + 2 + 9 + 2 + task.chars().count() + tail_len);
             ListItem::new(Line::from(vec![
-                icon, who, Span::raw(task), Span::raw(" ".repeat(pad)),
+                mark, icon, who, dirt, Span::raw(task), Span::raw(" ".repeat(pad)),
+                Span::styled(cost, Style::default().fg(Color::Magenta)),
                 Span::styled(meta, Style::default().fg(Color::DarkGray)),
             ]))
         })
         .collect();
 
+    let focused = app.mode == Mode::Normal || app.mode == Mode::Filter;
+    let block = if focused { panel_focused(&title, ACCENT) } else { panel(&title) };
     let list = List::new(items)
-        .block(Block::default().borders(Borders::ALL).title(title))
-        .highlight_style(Style::default().bg(Color::Blue).fg(Color::White).add_modifier(Modifier::BOLD))
+        .block(block)
+        .highlight_style(Style::default().bg(ACCENT).fg(Color::Black).add_modifier(Modifier::BOLD))
         .highlight_symbol("▶ ");
     let mut state = ListState::default();
     state.select(Some(app.selected.min(app.rows.len() - 1)));
@@ -147,10 +417,11 @@ fn draw_terminal(f: &mut Frame, app: &App, idx: usize, area: Rect) {
     } else {
         " terminal · [enter] to chat ".to_string()
     };
-    let border = if focused { Color::Green } else { Color::DarkGray };
-    let block = Block::default().borders(Borders::ALL)
-        .border_style(Style::default().fg(border))
-        .title(title);
+    let block = if focused {
+        panel_focused(&title, Color::Green)
+    } else {
+        panel(&title)
+    };
     let inner = block.inner(area);
     f.render_widget(block, area);
 
@@ -165,32 +436,95 @@ fn draw_terminal(f: &mut Frame, app: &App, idx: usize, area: Rect) {
 }
 
 fn draw_preview(f: &mut Frame, app: &App, area: Rect) {
-    let block = Block::default().borders(Borders::ALL).title(" preview ");
+    let block = panel(" preview ");
     let Some(r) = app.selected_row() else {
         let p = Paragraph::new("\n  select an agent, or press [n] to launch one.")
             .style(Style::default().fg(Color::DarkGray)).block(block);
         f.render_widget(p, area);
         return;
     };
+    let inner_w = block.inner(area).width as usize;
     let field = |k: &str| Span::styled(format!("{:<9}", k), Style::default().fg(Color::DarkGray));
     let kind = match r.kind { Kind::Managed => "agent", Kind::Observed => "observed session" };
-    let lines = vec![
-        Line::from(Span::styled(truncate(if r.task.is_empty() { "(no task)" } else { &r.task }, 60),
-            Style::default().add_modifier(Modifier::BOLD))),
+    let glyph = if r.status == "running" { spinner() } else { status_icon(&r.status) };
+    let mut lines = vec![
+        Line::from(Span::styled(
+            truncate(if r.display().is_empty() { "(no task)" } else { r.display() }, inner_w.saturating_sub(1)),
+            Style::default().fg(Color::White).add_modifier(Modifier::BOLD))),
+        Line::from(""),
         Line::from(vec![field("status"), Span::styled(
-            format!("{} {}", status_icon(&r.status), r.status), Style::default().fg(status_color(&r.status)))]),
+            format!("{} {}", glyph, r.status), Style::default().fg(status_color(&r.status)))]),
         Line::from(vec![field("kind"), Span::raw(kind.to_string())]),
-        Line::from(vec![field("harness"), Span::raw(format!("{} · {}", r.harness, r.model))]),
-        Line::from(vec![field("cost"), Span::raw(format!("${:.3}", r.cost_usd))]),
-        Line::from(vec![field("context"), Span::raw(r.ctx_pct.map(|p| format!("{:.0}%", p)).unwrap_or_else(|| "-".into()))]),
+        Line::from(vec![field("harness"),
+            Span::styled(r.harness.clone(), Style::default().fg(harness_color(&r.harness))),
+            Span::styled(format!(" · {}", r.model), Style::default().fg(Color::Gray))]),
     ];
+    if let Some((k, n)) = r.steps {
+        lines.push(Line::from(vec![field("steps"),
+            Span::styled(format!("{}/{}", k, n), Style::default().fg(ACCENT))]));
+    } else if let Some(i) = r.step_index {
+        lines.push(Line::from(vec![field("step"), Span::raw(format!("#{}", i))]));
+    }
+    if !r.branch.is_empty() && r.branch != "-" {
+        lines.push(Line::from(vec![field("branch"),
+            Span::styled(r.branch.clone(), Style::default().fg(Color::Yellow))]));
+    }
+    if let Some(rem) = &app.sel_remote {
+        if !rem.is_empty() && r.worktree.is_some() {
+            let color = match rem.as_str() {
+                "up to date" => Color::Green,
+                "not pushed" => Color::DarkGray,
+                _ => Color::Yellow,
+            };
+            lines.push(Line::from(vec![field("remote"), Span::styled(rem.clone(), Style::default().fg(color))]));
+        }
+    }
+    if let Some((n, _)) = app.selected_pr() {
+        lines.push(Line::from(vec![field("PR"),
+            Span::styled(format!("#{} open  [O] open", n),
+                Style::default().fg(Color::Magenta).add_modifier(Modifier::BOLD))]));
+    }
+    lines.push(Line::from(vec![field("cost"),
+        Span::styled(format!("${:.3}", r.cost_usd), Style::default().fg(Color::Magenta))]));
+    if let Some(p) = r.ctx_pct {
+        // btop-style meter; reddens as context fills up
+        let color = if p >= 85.0 { Color::Red } else if p >= 60.0 { Color::Yellow } else { Color::Green };
+        lines.push(Line::from(vec![field("context"),
+            Span::styled(meter(p, 12), Style::default().fg(color)),
+            Span::styled(format!(" {:.0}%", p), Style::default().fg(color))]));
+    }
+    if r.updated_ts > 0.0 {
+        let label = if r.status == "running" { "running" } else { "updated" };
+        lines.push(Line::from(vec![field(label),
+            Span::styled(rel_time(r.updated_ts, now_secs()), Style::default().fg(Color::DarkGray))]));
+    }
+    // git status of the selected worktree (cached)
+    if let Some((path, sum, clean)) = &app.worktree_status {
+        if Some(path) == r.worktree.as_ref() {
+            let color = if *clean { Color::Green } else { Color::Yellow };
+            lines.push(Line::from(vec![field("changes"),
+                Span::styled(sum.clone(), Style::default().fg(color))]));
+        }
+    }
+    if let Some(wt) = &r.worktree {
+        lines.push(Line::from(vec![field("worktree"),
+            Span::styled(truncate(wt, inner_w.saturating_sub(10)), Style::default().fg(Color::DarkGray))]));
+    }
+    if r.kind == Kind::Managed && !r.interactive {
+        lines.push(Line::from(""));
+        lines.push(Line::from(Span::styled(
+            "[d]iff [l]og [e]dit [!]shell [P]ush [R]etry [o]wt [x]rm",
+            Style::default().fg(ACCENT_DIM))));
+    }
     f.render_widget(Paragraph::new(lines).block(block).wrap(Wrap { trim: false }), area);
 }
 
 fn draw_footer(f: &mut Frame, app: &App, area: Rect) {
     let keys = match app.mode {
-        Mode::Terminal => "CHAT — type to talk to the agent   ·   [Ctrl-o] back to dashboard",
-        _ => "[q]uit [j/k]move [n]ew [enter]chat [s]top [x]rm [o]wt [/]find [h]ide-obs [?]help",
+        Mode::Terminal => "CHAT — type to talk   ·   [shift-tab] cycle agent modes   ·   [Ctrl-o] back",
+        Mode::Diff => "DIFF — [j/k]scroll [space/pgdn]page   ·   [q/esc] close",
+        Mode::Log => "LOG — [j/k]scroll [space/pgdn]page [r]eload   ·   [q/esc] close",
+        _ => "[q]uit [jk]move [n]ew [enter]chat [d]iff [l]og [e]dit [P]ush [s]top [x]rm [1-4]filter [,]settings [?]help",
     };
     f.render_widget(
         Paragraph::new(Span::styled(keys, Style::default().fg(Color::DarkGray))),
@@ -202,9 +536,9 @@ fn draw_form(f: &mut Frame, app: &App) {
     let area = centered(76, 66, f.area());
     f.render_widget(Clear, area);
     let form = &app.new_form;
-    use crate::app::{FIELD_HARNESS, FIELD_IMAGES, FIELD_MODEL, FIELD_TASK, FIELD_WORKTREE};
+    use crate::app::{FIELD_HARNESS, FIELD_IMAGES, FIELD_MODEL, FIELD_TASK, FIELD_WORKFLOW, FIELD_WORKTREE};
 
-    let block = Block::default().borders(Borders::ALL).title(" new agent ");
+    let block = panel_focused(" new agent ", ACCENT);
     let inner = block.inner(area);
     f.render_widget(block, area);
 
@@ -214,6 +548,7 @@ fn draw_form(f: &mut Frame, app: &App) {
             Constraint::Length(1), // title
             Constraint::Length(1), // label: task
             Constraint::Length(5), // task editor
+            Constraint::Length(1), // workflow
             Constraint::Length(1), // harness
             Constraint::Length(1), // model
             Constraint::Length(1), // worktree
@@ -250,19 +585,31 @@ fn draw_form(f: &mut Frame, app: &App) {
     task.set_block(Block::default().borders(Borders::ALL).border_style(Style::default().fg(te_border)));
     f.render_widget(&task, rows[2]);
 
+    let mut fline = vec![lbl(FIELD_WORKFLOW, "workflow")];
+    fline.extend(picker(form.field == FIELD_WORKFLOW, form.workflow(),
+        form.workflow_idx, crate::app::WORKFLOWS.len()).spans);
+    f.render_widget(Paragraph::new(Line::from(fline)), rows[3]);
+
     let presets = crate::app::model_presets(form.harness_idx);
     let mut hline = vec![lbl(FIELD_HARNESS, "harness")];
     hline.extend(picker(form.field == FIELD_HARNESS, form.harness(), form.harness_idx, 3).spans);
-    f.render_widget(Paragraph::new(Line::from(hline)), rows[3]);
+    // is this harness's CLI installed?
+    if crate::app::harness_installed(form.harness()) {
+        hline.push(Span::styled("  ✓ installed", Style::default().fg(Color::Green)));
+    } else {
+        hline.push(Span::styled(format!("  ✗ '{}' not on PATH", crate::app::harness_bin(form.harness())),
+            Style::default().fg(Color::Red)));
+    }
+    f.render_widget(Paragraph::new(Line::from(hline)), rows[4]);
 
     let mut mline = vec![lbl(FIELD_MODEL, "model")];
     mline.extend(picker(form.field == FIELD_MODEL, form.model(), form.model_idx, presets.len()).spans);
-    f.render_widget(Paragraph::new(Line::from(mline)), rows[4]);
+    f.render_widget(Paragraph::new(Line::from(mline)), rows[5]);
 
     let wt = if form.worktree_new { "new git worktree (isolated)" } else { "current repo (shared)" };
     let mut wline = vec![lbl(FIELD_WORKTREE, "worktree")];
     wline.extend(picker(form.field == FIELD_WORKTREE, wt, if form.worktree_new {0} else {1}, 2).spans);
-    f.render_widget(Paragraph::new(Line::from(wline)), rows[5]);
+    f.render_widget(Paragraph::new(Line::from(wline)), rows[6]);
 
     let img = if let Some(buf) = &form.image_input {
         format!("   typing path: {}_", buf)
@@ -273,7 +620,7 @@ fn draw_form(f: &mut Frame, app: &App) {
     };
     let mut iline = vec![lbl(FIELD_IMAGES, "images")];
     iline.push(Span::styled(img, Style::default().fg(Color::Gray)));
-    f.render_widget(Paragraph::new(Line::from(iline)), rows[6]);
+    f.render_widget(Paragraph::new(Line::from(iline)), rows[7]);
 
     let mut hints = Vec::new();
     if let Some(err) = &form.error {
@@ -282,53 +629,205 @@ fn draw_form(f: &mut Frame, app: &App) {
     hints.push(Line::from(Span::styled(
         "  [tab] next field   [←→] change   [ Ctrl-S ] launch & chat   [esc] cancel",
         Style::default().fg(Color::DarkGray))));
-    f.render_widget(Paragraph::new(hints).wrap(Wrap { trim: false }), rows[7]);
+    f.render_widget(Paragraph::new(hints).wrap(Wrap { trim: false }), rows[8]);
 }
 
-fn draw_help(f: &mut Frame) {
-    let area = centered(62, 72, f.area());
+fn draw_help(f: &mut Frame, app: &App) {
+    let area = centered(64, 92, f.area());
     f.render_widget(Clear, area);
-    let rows = [
-        ("j / k, ↑ / ↓", "move selection"),
-        ("n", "new interactive agent (chat) in a worktree"),
-        ("enter", "chat with a live agent, or resume a ▷ one"),
-        ("Ctrl-o", "leave the terminal, back to the dashboard"),
-        ("s", "stop the selected agent"),
-        ("x", "remove the selected agent"),
-        ("o", "show worktree path"),
-        ("/", "search    ·    h  toggle observed sessions"),
-        ("q", "quit"),
+    // grouped cheatsheet (lazygit-style): (section, [(keys, desc)])
+    let groups: [(&str, &[(&str, &str)]); 6] = [
+        ("Navigate", &[
+            ("j / k · ↑ / ↓", "move selection"),
+            ("g / G", "jump to top / bottom"),
+            ("PgUp/Dn · ^u/^d", "page / half-page the list"),
+            ("] / [", "jump to next / prev failed agent"),
+            ("space / A", "mark row / mark all · esc clears marks"),
+            ("click / wheel", "select a row · scroll"),
+        ]),
+        ("Launch & drive", &[
+            ("n", "new agent (workflow: chat / plan→build / plan-only)"),
+            ("enter", "chat with a live agent, or resume a ▷ one"),
+            ("shift-tab", "(in chat) cycle the agent's modes, e.g. plan"),
+            ("D", "duplicate into a prefilled new-agent form"),
+            ("Ctrl-o", "leave the terminal, back to the dashboard"),
+        ]),
+        ("Inspect", &[
+            ("d", "review the worktree diff (colored)"),
+            ("l", "tail the log — live-follows at the bottom"),
+            ("o / y", "worktree path · yank it to the clipboard"),
+            ("Y", "yank the branch name"),
+            ("e / !", "open worktree in $EDITOR · drop to a $SHELL"),
+        ]),
+        ("Ship", &[
+            ("P", "commit + push (selected or all marked), open PR (gh)"),
+            ("O", "open the branch on the remote in a browser (gh)"),
+            ("f", "git fetch origin (refreshes ahead/behind)"),
+            ("R", "retry: re-delegate the task (needs engine)"),
+        ]),
+        ("Manage", &[
+            ("s / S", "stop selected/marked · stop ALL running"),
+            ("x / c", "remove selected/marked · clear finished"),
+            ("L", "label / rename a crew-launched agent"),
+        ]),
+        ("Filter & sort", &[
+            ("1 2 3 4", "all / running / agents / sessions"),
+            ("t", "cycle sort: status → cost → recent"),
+            ("/ · h", "search · toggle observed sessions"),
+            (",", "settings — default harness/model/workflow"),
+        ]),
     ];
-    let lines: Vec<Line> = rows.iter().map(|(k, d)| Line::from(vec![
-        Span::styled(format!("  {:<14}", k), Style::default().fg(Color::Cyan).add_modifier(Modifier::BOLD)),
-        Span::raw(*d),
-    ])).collect();
+    let mut lines: Vec<Line> = Vec::new();
+    for (title, rows) in groups {
+        lines.push(Line::from(Span::styled(format!(" {}", title),
+            Style::default().fg(Color::Yellow).add_modifier(Modifier::BOLD))));
+        for (k, d) in rows {
+            lines.push(Line::from(vec![
+                Span::styled(format!("  {:<15}", k), Style::default().fg(ACCENT).add_modifier(Modifier::BOLD)),
+                Span::styled(d.to_string(), Style::default().fg(Color::Gray)),
+            ]));
+        }
+        lines.push(Line::from(""));
+    }
+    lines.push(Line::from(vec![
+        Span::styled(" legend  ", Style::default().fg(Color::Yellow).add_modifier(Modifier::BOLD)),
+        Span::styled("● running  ", Style::default().fg(Color::Green)),
+        Span::styled("✓ done  ", Style::default().fg(Color::Green)),
+        Span::styled("✗ failed  ", Style::default().fg(Color::Red)),
+        Span::styled("▷ resumable  ", Style::default().fg(Color::Yellow)),
+        Span::styled("± uncommitted  ", Style::default().fg(Color::Yellow)),
+        Span::styled("◉ marked", Style::default().fg(ACCENT)),
+    ]));
     f.render_widget(Paragraph::new(lines)
-        .block(Block::default().borders(Borders::ALL).title(" help — any key to close ")), area);
+        .scroll((app.help_scroll, 0))
+        .block(panel_focused(" help — [j/k] scroll · any other key closes ", ACCENT)), area);
+}
+
+/// Full-screen colored diff of the selected agent's worktree.
+fn draw_diff(f: &mut Frame, app: &App) {
+    let area = centered(90, 88, f.area());
+    f.render_widget(Clear, area);
+    let q = app.find_query.to_lowercase();
+    let lines: Vec<Line> = app.diff_text.lines().map(|l| {
+        if !q.is_empty() && l.to_lowercase().contains(&q) {
+            return Line::from(Span::styled(l.to_string(),
+                Style::default().bg(Color::Yellow).fg(Color::Black).add_modifier(Modifier::BOLD)));
+        }
+        let style = if l.starts_with('+') && !l.starts_with("+++") {
+            Style::default().fg(Color::Green)
+        } else if l.starts_with('-') && !l.starts_with("---") {
+            Style::default().fg(Color::Red)
+        } else if l.starts_with("@@") {
+            Style::default().fg(Color::Cyan)
+        } else if l.starts_with("diff ") || l.starts_with("── ") {
+            Style::default().fg(Color::Yellow).add_modifier(Modifier::BOLD)
+        } else {
+            Style::default().fg(Color::Gray)
+        };
+        Line::from(Span::styled(l.to_string(), style))
+    }).collect();
+    let total = lines.len();
+    let title = format!(" diff · {} lines ·{} [/]search [q]close ", total, find_hint(app));
+    f.render_widget(
+        Paragraph::new(lines)
+            .scroll((app.diff_scroll, 0))
+            .block(panel_focused(&title, ACCENT)),
+        area,
+    );
+    scrollbar(f, area, app.diff_scroll, total);
+}
+
+/// Title fragment showing the in-viewer search state ("" when idle).
+fn find_hint(app: &App) -> String {
+    if app.find_input {
+        format!(" /{}_ ·", app.find_query)
+    } else if !app.find_query.is_empty() {
+        format!(" /{} [n/N] ·", app.find_query)
+    } else {
+        String::new()
+    }
+}
+
+/// Scrollable tail of a headless agent's log file.
+fn draw_log(f: &mut Frame, app: &App) {
+    let area = centered(90, 88, f.area());
+    f.render_widget(Clear, area);
+    let total = app.log_text.lines().count();
+    let q = app.find_query.to_lowercase();
+    let lines: Vec<Line> = app.log_text.lines().map(|l| {
+        let low = l.to_ascii_lowercase();
+        if !q.is_empty() && low.contains(&q) {
+            return Line::from(Span::styled(l.to_string(),
+                Style::default().bg(Color::Yellow).fg(Color::Black).add_modifier(Modifier::BOLD)));
+        }
+        // highlight anything that reads like an error
+        let style = if low.contains("error") || low.contains("\"is_error\":true") || low.contains("traceback") {
+            Style::default().fg(Color::Red)
+        } else {
+            Style::default().fg(Color::Gray)
+        };
+        Line::from(Span::styled(l.to_string(), style))
+    }).collect();
+    let at_bottom = app.log_scroll as usize >= total.saturating_sub(1);
+    let follow = if at_bottom { "⏵following" } else { "⏸scrollback" };
+    let title = format!(" log · {} lines · {} ·{} [/]search [q]close ", total, follow, find_hint(app));
+    f.render_widget(
+        Paragraph::new(lines)
+            .scroll((app.log_scroll, 0))
+            .block(panel_focused(&title, ACCENT)),
+        area,
+    );
+    scrollbar(f, area, app.log_scroll, total);
 }
 
 fn draw_confirm(f: &mut Frame, app: &App) {
     let area = centered(50, 20, f.area());
     f.render_widget(Clear, area);
-    let id = app.selected_row().map(|r| r.id.clone()).unwrap_or_default();
+    let what = if !app.marked.is_empty() {
+        format!("{} marked agent(s)", app.marked.len())
+    } else {
+        format!("agent {}", app.selected_row().map(|r| r.id.clone()).unwrap_or_default())
+    };
     let lines = vec![
         Line::from(""),
-        Line::from(Span::raw(format!("  Stop agent {} ?", id))),
+        Line::from(Span::raw(format!("  Stop {} ?", what))),
         Line::from(""),
         Line::from(Span::styled("  [y] confirm   [n/esc] cancel", Style::default().fg(Color::DarkGray))),
     ];
     f.render_widget(Paragraph::new(lines)
-        .block(Block::default().borders(Borders::ALL).title(Span::styled(" confirm stop ", Style::default().fg(Color::Red)))), area);
+        .block(dialog(Span::styled(" confirm stop ", Style::default().fg(Color::Red)))), area);
+}
+
+fn draw_confirm_stop_all(f: &mut Frame, app: &App) {
+    let area = centered(52, 20, f.area());
+    f.render_widget(Clear, area);
+    let n = app.running_count();
+    let lines = vec![
+        Line::from(""),
+        Line::from(Span::raw(format!("  Stop ALL {} running agent(s)?", n))),
+        Line::from(""),
+        Line::from(Span::styled("  [y] confirm   [n/esc] cancel", Style::default().fg(Color::DarkGray))),
+    ];
+    f.render_widget(Paragraph::new(lines)
+        .block(dialog(Span::styled(" confirm stop all ", Style::default().fg(Color::Red)))), area);
 }
 
 fn draw_confirm_quit(f: &mut Frame, app: &App) {
     let area = centered(58, 26, f.area());
     f.render_widget(Clear, area);
     let n = app.agents.len();
-    let lines = vec![
+    let dirty = app.dirty.values().filter(|d| **d).count();
+    let mut lines = vec![
         Line::from(""),
         Line::from(Span::styled(format!("  Quit? {} agent(s) will stop.", n),
             Style::default().add_modifier(Modifier::BOLD))),
+    ];
+    if dirty > 0 {
+        lines.push(Line::from(Span::styled(
+            format!("  ⚠ {} worktree(s) have uncommitted changes (± in the list).", dirty),
+            Style::default().fg(Color::Yellow))));
+    }
+    lines.extend([
         Line::from(""),
         Line::from(Span::styled(
             "  Their worktrees are kept — reopen the TUI and press",
@@ -338,10 +837,9 @@ fn draw_confirm_quit(f: &mut Frame, app: &App) {
             Style::default().fg(Color::Gray))),
         Line::from(""),
         Line::from(Span::styled("  [y] quit   [n/esc] cancel", Style::default().fg(Color::DarkGray))),
-    ];
+    ]);
     f.render_widget(Paragraph::new(lines).wrap(Wrap { trim: false })
-        .block(Block::default().borders(Borders::ALL)
-            .title(Span::styled(" confirm quit ", Style::default().fg(Color::Yellow)))), area);
+        .block(dialog(Span::styled(" confirm quit ", Style::default().fg(Color::Yellow)))), area);
 }
 
 fn draw_confirm_discard(f: &mut Frame) {
@@ -354,7 +852,7 @@ fn draw_confirm_discard(f: &mut Frame) {
         Line::from(Span::styled("  [y] discard   [n/esc] keep editing", Style::default().fg(Color::DarkGray))),
     ];
     f.render_widget(Paragraph::new(lines)
-        .block(Block::default().borders(Borders::ALL).title(Span::styled(" confirm discard ", Style::default().fg(Color::Yellow)))), area);
+        .block(dialog(Span::styled(" confirm discard ", Style::default().fg(Color::Yellow)))), area);
 }
 
 fn centered(pw: u16, ph: u16, area: Rect) -> Rect {
@@ -385,6 +883,13 @@ fn now_secs() -> f64 {
         .unwrap_or(0.0)
 }
 
+fn now_millis() -> u128 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.as_millis())
+        .unwrap_or(0)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -397,6 +902,14 @@ mod tests {
         term.backend().buffer().content().iter().map(|c| c.symbol()).collect()
     }
 
+    #[test]
+    fn meter_fills_proportionally() {
+        assert_eq!(meter(0.0, 10), "░░░░░░░░░░");
+        assert_eq!(meter(100.0, 10), "██████████");
+        assert_eq!(meter(50.0, 10), "█████░░░░░");
+        assert_eq!(meter(200.0, 4), "████"); // clamps over 100
+    }
+
     #[test]
     fn renders_empty_dashboard_chrome() {
         let store = Store::new(PathBuf::from("/tmp/myrepo"), PathBuf::from("/tmp/myrepo/scripts"));
@@ -404,12 +917,36 @@ mod tests {
         let mut term = Terminal::new(TestBackend::new(120, 24)).unwrap();
         term.draw(|f| draw(f, &app)).unwrap();
         let text = buffer_text(&term);
-        assert!(text.contains("nexum"));
+        assert!(text.contains("crew"));
         assert!(text.contains("myrepo"));
         assert!(text.contains("agents ("));
         assert!(text.contains("[n]ew"));
     }
 
+    #[test]
+    fn renders_populated_list_with_markers() {
+        use crate::agent::{ManagedAgent, Row};
+        let mk = |id: &str, h: &str, st: &str, cost: f64| Row::from_managed(&ManagedAgent {
+            agent_id: id.into(), harness: Some(h.into()), model: Some("sonnet".into()),
+            worktree: Some(format!("/tmp/{id}")), branch: Some(format!("crew/{id}")),
+            status: Some(st.into()), cost_usd: Some(cost), task: Some(format!("task {id}")),
+            step_index: None, updated_ts: Some(1.0), pid: None, log_path: None,
+        });
+        let store = Store::new(PathBuf::from("/tmp/myrepo"), PathBuf::from("/tmp/myrepo/scripts"));
+        let mut app = App::new(store);
+        app.rows = vec![mk("a", "cursor", "running", 0.42), mk("b", "claude", "failed", 0.08)];
+        app.marked.insert("a".into());
+        app.dirty.insert("b".into(), true);
+        let mut term = Terminal::new(TestBackend::new(120, 24)).unwrap();
+        term.draw(|f| draw(f, &app)).unwrap();
+        let text = buffer_text(&term);
+        assert!(text.contains("cursor") && text.contains("claude"));
+        assert!(text.contains("$0.42"), "cost missing");
+        assert!(text.contains('◉'), "mark missing");
+        assert!(text.contains('±'), "dirty marker missing");
+        assert!(text.contains("✗1") || text.contains('✗'), "failed legend missing");
+    }
+
     #[test]
     fn renders_new_agent_form() {
         let store = Store::new(PathBuf::from("/tmp/myrepo"), PathBuf::from("/tmp/myrepo/scripts"));

From 2ad8fe9bdca80462418e0ce685be388233782486 Mon Sep 17 00:00:00 2001
From: Rahul Tyagi <rahul.1992.tyagi@gmail.com>
Date: Fri, 10 Jul 2026 14:06:20 +0530
Subject: [PATCH 16/16] docs: integrate crew screenshots page into the mkdocs
 site

Move the generated crew page to docs/crew/index.html (static page inside
docs_dir) so it coexists with the markdown docs instead of colliding with the
mkdocs-generated index.html. Link it from the docs home. Verified with
mkdocs build --strict (publishes at <site>/crew/).
---
 docs/{ => crew}/index.html | 28 ++++++++++++++--------------
 docs/index.md              |  1 +
 tui/site/gen.py            |  4 +++-
 3 files changed, 18 insertions(+), 15 deletions(-)
 rename docs/{ => crew}/index.html (96%)

diff --git a/docs/index.html b/docs/crew/index.html
similarity index 96%
rename from docs/index.html
rename to docs/crew/index.html
index 11ac92c..056d0fb 100644
--- a/docs/index.html
+++ b/docs/crew/index.html
@@ -76,13 +76,13 @@ <h1>Run a <span class=g>crew of coding agents</span><br>from one terminal.</h1>
   </div>
   <div class=heroshot><figure class="term"><figcaption><span class="d r"></span><span class="d y"></span><span class="d g"></span><span class="t">crew · dashboard</span></figcaption><pre> crew  nexum  tui-agent-flow ⚙ engine · 5 agents  ●2 ✓2 ✗1  $1.050  ◉ 2 marked
 ╭ agents (5) ────────────────────╮╭ preview ───────────────────────────────────────────────────────╮
-│▶   ⠏ cursor     add b…$0.42 12s││add billing dashboard endpoint                                  │
-│  ◉ ⠏ claude     add a…$0.31 40s││                                                                │
-│  ◉ ✗ opencode   fix f…$0.08 2m ││status   ⠏ running                                              │
+│▶   ⠦ cursor     add b…$0.42 12s││add billing dashboard endpoint                                  │
+│  ◉ ⠦ claude     add a…$0.31 40s││                                                                │
+│  ◉ ✗ opencode   fix f…$0.08 2m ││status   ⠦ running                                              │
 │    ✓ claude     rewri…$0.05 10m││kind     agent                                                  │
 │    ✓ cursor     add d…$0.19 1h ││harness  cursor · sonnet                                        │
 │                                ││branch   crew/billing-api                                       │
-│                                ││remote   not pushed                                             │
+│                                ││remote   up to date                                             │
 │                                ││cost     $0.420                                                 │
 │                                ││running  12s ago                                                │
 │                                ││worktree .crew/worktrees/billing-api                            │
@@ -124,8 +124,8 @@ <h2>How it compares</h2>
 <section id=shots>
   <h2>Screens</h2>
   <p class=sub>Real frames rendered by the binary.</p>
-  <div class=gallery><div class="shot"><figure class="term"><figcaption><span class="d r"></span><span class="d y"></span><span class="d g"></span><span class="t">launch — workflow picker</span></figcaption><pre> crew  nexum  tui-agent-flow ⚙ engine · 19 agents
-╭ agents (19) ───────────────────╮╭ preview ───────────────────────────────────────────────────────╮
+  <div class=gallery><div class="shot"><figure class="term"><figcaption><span class="d r"></span><span class="d y"></span><span class="d g"></span><span class="t">launch — workflow picker</span></figcaption><pre> crew  nexum  tui-agent-flow ⚙ engine · 20 agents
+╭ agents (20) ───────────────────╮╭ preview ───────────────────────────────────────────────────────╮
 │▶   ▷ claude     say hello     -││say hello                                                       │
 │    ▷ claude     say hello     -││                                                                │
 │    ▷ claude     say hello     -││status   ▷ resumable                                            │
@@ -145,7 +145,7 @@ <h2>Screens</h2>
 │    ▷ claud│  [tab] next field   [←→] change   [ Ctrl-S ] launch &amp; chat   [esc] cancel│           │
 │    ▷ claud│                                                                          │           │
 │    ▷ claud│                                                                          │           │
-│           │                                                                          │           │
+│    ▷ claud│                                                                          │           │
 │           │                                                                          │           │
 │           ╰──────────────────────────────────────────────────────────────────────────╯           │
 │                                ││                                                                │
@@ -153,9 +153,10 @@ <h2>Screens</h2>
 │                                ││                                                                │
 │                                ││                                                                │
 ╰────────────────────────────────╯╰────────────────────────────────────────────────────────────────╯
-[q]uit [jk]move [n]ew [enter]chat [d]iff [l]og [e]dit [P]ush [s]top [x]rm [1-4]filter [,]settings [?</pre></figure></div><div class="shot"><figure class="term"><figcaption><span class="d r"></span><span class="d y"></span><span class="d g"></span><span class="t">embedded chat</span></figcaption><pre> crew  nexum  tui-agent-flow ⚙ engine · 20 agents  ●1  CHAT  launched agent_say-hello-958286 — Ctrl-
-╭ agents (20) ───────────────────╮╭ chat · typing goes to the agent · [Ctrl-o] leave ──────────────╮
-│▶   ⠙ claude     say hel… 0s ago││█                                                               │
+[q]uit [jk]move [n]ew [enter]chat [d]iff [l]og [e]dit [P]ush [s]top [x]rm [1-4]filter [,]settings [?</pre></figure></div><div class="shot"><figure class="term"><figcaption><span class="d r"></span><span class="d y"></span><span class="d g"></span><span class="t">embedded chat</span></figcaption><pre> crew  nexum  tui-agent-flow ⚙ engine · 21 agents  ●1  CHAT  launched agent_say-hello-489040 — Ctrl-
+╭ agents (21) ───────────────────╮╭ chat · typing goes to the agent · [Ctrl-o] leave ──────────────╮
+│▶   ⠏ claude     say hel… 0s ago││█                                                               │
+│    ▷ claude     say hello     -││                                                                │
 │    ▷ claude     say hello     -││                                                                │
 │    ▷ claude     say hello     -││                                                                │
 │    ▷ claude     say hello     -││                                                                │
@@ -175,15 +176,14 @@ <h2>Screens</h2>
 │    ▷ claude     say hello     -││                                                                │
 │    ▷ claude     say hello     -││                                                                │
 │    ▷ claude     say hello     -││                                                                │
-│                                ││                                                                │
 │                                ││                                                                │
 │                                ││                                                                │
 │                                ││                                                                │
 │                                ││                                                                │
 │                                ││                                                                │
 ╰────────────────────────────────╯╰────────────────────────────────────────────────────────────────╯
-CHAT — type to talk   ·   [shift-tab] cycle agent modes   ·   [Ctrl-o] back</pre></figure></div><div class="shot"><figure class="term"><figcaption><span class="d r"></span><span class="d y"></span><span class="d g"></span><span class="t">grouped help (?)</span></figcaption><pre> crew  nexum  tui-agent-flow ⚙ engine · 20 agents
-╭ agents (20) ────╭ help — [j/k] scroll · any other key closes ──────────────────╮─────────────────╮
+CHAT — type to talk   ·   [shift-tab] cycle agent modes   ·   [Ctrl-o] back</pre></figure></div><div class="shot"><figure class="term"><figcaption><span class="d r"></span><span class="d y"></span><span class="d g"></span><span class="t">grouped help (?)</span></figcaption><pre> crew  nexum  tui-agent-flow ⚙ engine · 21 agents
+╭ agents (21) ────╭ help — [j/k] scroll · any other key closes ──────────────────╮─────────────────╮
 │▶   ▷ claude     │ Navigate                                                     │                 │
 │    ▷ claude     │  j / k · ↑ / ↓  move selection                               │                 │
 │    ▷ claude     │  g / G          jump to top / bottom                         │                 │
@@ -204,7 +204,7 @@ <h2>Screens</h2>
 │    ▷ claude     │  l              tail the log — live-follows at the bottom    │                 │
 │    ▷ claude     │  o / y          worktree path · yank it to the clipboard     │                 │
 │    ▷ claude     │  Y              yank the branch name                         │                 │
-│                 │  e / !          open worktree in $EDITOR · drop to a $SHELL  │                 │
+│    ▷ claude     │  e / !          open worktree in $EDITOR · drop to a $SHELL  │                 │
 │                 │                                                              │                 │
 │                 │ Ship                                                         │                 │
 │                 │  P              commit + push (selected or all marked), open │                 │
diff --git a/docs/index.md b/docs/index.md
index ef966aa..fd86bc1 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -8,3 +8,4 @@ nexum is a Claude Code plugin that cuts context tokens and model cost during you
 
 - [Install nexum](install.md) — add the marketplace and enable the plugin in two commands.
 - [Commands reference](commands.md) — what `/nx-plan`, `/nx-build`, `/nx-audit`, `/nx-status`, `/nx-save`, and `/nx-load` do and when to use them.
+- [crew — the agent dashboard](crew/) — a standalone terminal TUI to run, chat with, and manage coding agents across harnesses (screenshots + feature comparison).
diff --git a/tui/site/gen.py b/tui/site/gen.py
index ad53e03..3ed5671 100644
--- a/tui/site/gen.py
+++ b/tui/site/gen.py
@@ -21,7 +21,9 @@
 BIN = os.path.join(TUI, "target", "release", "crew")
 if not os.path.exists(BIN):
     BIN = os.path.join(TUI, "target", "debug", "crew")
-OUT = os.path.join(REPO, "docs", "index.html")
+# Published as a static page inside the repo's mkdocs site (docs_dir=docs/), so
+# it coexists with the markdown docs and lands at <site>/crew/.
+OUT = os.path.join(REPO, "docs", "crew", "index.html")
 
 
 def snap(mode: str | None) -> str: