v2.0.3: CLI client + human inbox + cost tracking + Boomerang new_task

Phase 7 of v2.0. BooCoder gains a terminal-driven UX and subagent
isolation primitive.

CLI (src/cli.ts): standalone entry point for terminal use.
- boocode run "task" [--agent x] [--model y] — create + stream output
- boocode ls [--state x] — formatted task table
- boocode attach <id> — WS stream of running task
- boocode send <id> "msg" — follow-up message to task session
Connects to BOOCODER_URL (default http://100.114.205.53:9502).

Human inbox (routes/inbox.ts): GET /api/inbox (failed/blocked tasks),
POST /api/inbox/:id/retry (reset to pending for re-dispatch).

Cost tracking: dispatcher aggregates tokens_used from all messages in
the task's session after completion, stores in tasks.cost_tokens.
GET /api/stats/costs?group_by=project|agent|day for aggregation.

Boomerang subagent isolation (3 new tools):
- new_task: creates child task with parent_task_id linkage, runs in
  fresh isolated session. Orchestrator sees only output_summary.
- list_tasks: query child tasks of current parent
- check_task_status: read task state + output_summary

The orchestrator pattern: an agent with tools: [new_task, list_tasks,
check_task_status] can ONLY dispatch — can't read files or MCP. This
is the Roo Code Boomerang Tasks capability-restriction principle.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -69,6 +69,14 @@ Key services:
 
 Route registration: all routes registered in `index.ts` via `register*Routes(app, sql, ...)` functions. Routes are in `routes/*.ts`.
 
+### BooCoder (`apps/coder/src/`)
+
+- Write-capable coding agent. Separate Fastify server at port 9502, same docker network (`boocode_net`).
+- **Workspace dependency on `@boocode/server`**: imports `createInferenceRunner`, `createBroker`, `ALL_TOOLS`, `appendMcpTools` from the server's compiled `dist/`. apps/server's `package.json` has an `exports` map with `types` conditions for NodeNext resolution. apps/server must build FIRST (Dockerfile builds server → coder).
+- `apps/server/tsconfig.json` has `declaration: true` so `.d.ts` files exist for workspace consumers.
+- Write tools (`edit_file`, `create_file`, `delete_file`, `apply_pending`, `rewind`) queue in `pending_changes` table. Nothing hits disk until `apply_pending` is called. `write_guard.ts` validates paths (resolve + prefix-check, no realpath since files may not exist for creates).
+- Frontend: NOT a separate SPA. BooCoder is a `'coder'` pane type within BooChat's SPA (`apps/web/`). `CoderPane.tsx` in `apps/web/src/components/panes/`. API requests go through `/api/coder/*` proxy (Vite dev + Fastify production) which rewrites to `http://boocoder:3000/api/*`. WS connects directly to `:9502`.
+
 ### Frontend (`apps/web/src/`)
 
 - **React 18** + React Router v6 + **Tailwind v4** + shadcn/radix-ui primitives.
@@ -105,14 +113,16 @@ Sessions hold 1–5 panes (chat / empty / placeholder terminal+agent). v1.12.1 m
 
 ## Database
 
-PostgreSQL 16. Tables: `projects`, `sessions`, `chats`, `messages`, `settings`, `message_parts` (v1.13.0). Views: `messages_with_parts` (v1.13.1-B parts-merge read path), `tool_cost_stats` (v1.13.10 per-tool 100-call rolling window). (`session_panes` was dropped in v1.12.1; workspace pane state lives in `sessions.workspace_panes jsonb`.) Schema applied idempotently on startup via `applySchema()`. Use `clock_timestamp()` (not `NOW()`) inside transactions. CHECK constraints in place: `projects_status_chk` ('open'|'archived'), `sessions_status_chk` (same), `chats_status_chk` (same), `messages_role_chk`, `messages_status_chk` — keep in sync with the `*_STATUSES` const arrays in `apps/server/src/types/api.ts`. The older anonymous `messages_status_check` (without 'cancelled') and `messages_role_check` (without 'system') were dropped in v1.12.1; only the `_chk` variants remain.
+PostgreSQL 16. Database name: `boochat` (renamed from `boocode` in v2.0.0-alpha; Docker service name stays `boocode_db`). Tables: `projects`, `sessions`, `chats`, `messages`, `settings`, `message_parts` (v1.13.0), `pending_changes` (v2.0.0), `tasks` (v2.0.0), `available_agents` (v2.0.0). Views: `messages_with_parts` (v1.13.1-B parts-merge read path), `tool_cost_stats` (v1.13.10 per-tool 100-call rolling window), `human_inbox` (v2.0.0 — tasks WHERE state IN blocked/failed). (`session_panes` was dropped in v1.12.1; workspace pane state lives in `sessions.workspace_panes jsonb`.) Schema applied idempotently on startup via `applySchema()`. Use `clock_timestamp()` (not `NOW()`) inside transactions. CHECK constraints in place: `projects_status_chk` ('open'|'archived'), `sessions_status_chk` (same), `chats_status_chk` (same), `messages_role_chk`, `messages_status_chk` — keep in sync with the `*_STATUSES` const arrays in `apps/server/src/types/api.ts`. The older anonymous `messages_status_check` (without 'cancelled') and `messages_role_check` (without 'system') were dropped in v1.12.1; only the `_chk` variants remain.
 
 Schema CHECK migration order when renaming allowed values: (1) `ALTER TABLE ... DROP CONSTRAINT IF EXISTS <system_name>` (inline `CREATE TABLE` checks get `<table>_<column>_check`), (2) `UPDATE` rows to new values, (3) wrap new constraint ADD in `DO $$ ... pg_constraint` guard — that block is the only way to get `ADD CONSTRAINT IF NOT EXISTS`.
 
 
 ## Environment
 
-Required: `DATABASE_URL`, `LLAMA_SWAP_URL`. Optional: `PORT` (3000), `HOST` (0.0.0.0), `PROJECT_ROOT_WHITELIST` (/opt, read-only scope for add-existing path resolution), `BOOTSTRAP_ROOT` (/opt/projects, writable scope for create-new-project bootstrap mkdir target — host must `mkdir -p /opt/projects` before container start), `DEFAULT_MODEL`, `LOG_LEVEL`, `SEARXNG_URL` (default `http://100.114.205.53:8888` — internal Tailscale Fathom; the public `search.indifferentketchup.com` is behind Authelia and unusable from server context), `BOOCODE_TOOLS` (`core` | `standard` | `all`, default `all`; v1.13.15-tools tier filter — ceiling, never expands an agent's whitelist).
+Required: `DATABASE_URL`, `LLAMA_SWAP_URL`. Optional: `PORT` (3000), `HOST` (0.0.0.0), `PROJECT_ROOT_WHITELIST` (/opt, read-only scope for add-existing path resolution), `BOOTSTRAP_ROOT` (/opt/projects, writable scope for create-new-project bootstrap mkdir target — host must `mkdir -p /opt/projects` before container start), `DEFAULT_MODEL`, `LOG_LEVEL`, `SEARXNG_URL` (default `http://100.114.205.53:8888` — internal Tailscale Fathom; the public `search.indifferentketchup.com` is behind Authelia and unusable from server context), `BOOCODE_TOOLS` (`core` | `standard` | `all`, default `all`; v1.13.15-tools tier filter — ceiling, never expands an agent's whitelist), `MCP_CONFIG_PATH` (optional; default `/data/mcp.json` — JSON config for MCP servers matching opencode's `mcpServers` shape; file missing = no MCP).
+
+BooCoder at port 9502: `curl http://100.114.205.53:9502/api/health`. Same Tailscale IP binding as BooChat. Health reports tool count: `{"ok":true,"db":true,"tools":30}`.
 
 ## Workflow
 
@@ -134,6 +144,8 @@ Required: `DATABASE_URL`, `LLAMA_SWAP_URL`. Optional: `PORT` (3000), `HOST` (0.0
 - `/opt/boolab` hosts a working sibling BooCode terminal at `boocode.indifferentketchup.com`. Useful for visual side-by-side comparison on the same iPhone when debugging booterm rendering. Boolab uses Tailwind v3 (`@tailwind base`); boocode uses v4 — many subtle build differences. Don't assume parity.
 - booterm SSHs to the host as `samkintop@100.114.205.53` (the Tailscale IP). The hostname `ubuntu-homelab` (shown in the bash prompt after login) does NOT resolve from inside the container — only the host's `/etc/hosts` knows it. Override via `BOOTERM_SSH_HOST` / `BOOTERM_SSH_USER` env vars in docker-compose if you ever move the shell to a different machine.
 - codecontext sidecar lives at `/opt/boocode/codecontext/`. Sidecar HTTP API at `http://codecontext:8080/v1/<tool_name>` over the `boocode_net` bridge (no host port). BooCode wrappers in `apps/server/src/services/tools/codecontext/`. The `.codecontextignore.template` documents recommended ignore patterns; users copy and adapt to project root manually.
+- codecontext fork at `/opt/forks/codecontext/` — separate git repo (branch `boocode-ts`), pushed via the same boocode_gitea SSH key to `indifferentketchup/codecontext`. Build: `go build ./...`. Test: `go test ./...`. Docker rebuild: `docker compose build --no-cache codecontext`.
+- Go binary: `/snap/go/current/bin/go` (not on PATH by default). Use `export PATH=$PATH:/snap/go/current/bin` or full path for Go commands.
 - `os/exec` child supervisors must explicitly call `child.Wait()` in a goroutine and `os.Exit` on child death. `Signal(0)` returns nil on zombies and is NOT a liveness check. Without `Wait()`, docker's `restart: unless-stopped` policy never fires because the parent stays alive. The `codecontext/shim.go` implementation is the reference pattern.
 
 ## Conventions
@@ -156,3 +168,5 @@ Required: `DATABASE_URL`, `LLAMA_SWAP_URL`. Optional: `PORT` (3000), `HOST` (0.0
 - Tool-name whitelists must derive from `ALL_TOOLS` in `services/tools.ts`, never hardcoded. `services/agents.ts` `ALL_TOOL_NAMES` had this drift class until v1.12 — same pattern applies to any future tool-aware code.
 - Agent registry lives at `data/AGENTS.md` (global, bind-mounted at `/data/AGENTS.md`). No per-project `AGENTS.md` in this repo — removed in v1.12 to eliminate the two-files-must-stay-in-sync drift. The `getAgentsForProject` per-project override mechanism remains for *other* projects.
 - MCP stdio transport uses newline-delimited JSON (NDJSON), NOT LSP-style `Content-Length` headers. The `codecontext/shim.go` framing implementation is the reference; per the MCP spec (modelcontextprotocol.io/specification/server/transports).
+- **Workspace dependency pattern** (`apps/coder` → `@boocode/server`): the consuming package adds `"@boocode/server": "workspace:*"` in `package.json`. The provider's `package.json` needs `exports` with `types` + `default` conditions per subpath: `"./inference": { "types": "./dist/.../index.d.ts", "default": "./dist/.../index.js" }`. Without the `types` condition, NodeNext resolution can't find `.d.ts` files and tsc fails with "Cannot find module" in the consumer.
+- **Docker build order for workspace deps**: the Dockerfile must `COPY` + `RUN pnpm build` the provider app BEFORE the consumer app. `apps/coder/Dockerfile` builds `apps/server` first, then `apps/coder`.

apps/coder/Dockerfile

@@ -23,7 +23,7 @@ RUN pnpm deploy --filter=@boocode/coder --prod --legacy /out/coder
 
 
 FROM node:20-bookworm-slim AS runtime
-RUN apt-get update && apt-get install -y --no-install-recommends ripgrep git && rm -rf /var/lib/apt/lists/*
+RUN apt-get update && apt-get install -y --no-install-recommends ripgrep git openssh-client && rm -rf /var/lib/apt/lists/*
 WORKDIR /app
 
 COPY --from=builder /out/coder ./

apps/coder/package.json

@@ -8,19 +8,24 @@
     "dev": "tsx watch src/index.ts",
     "build": "tsc && node -e \"import('node:fs').then(fs=>fs.copyFileSync('src/schema.sql','dist/schema.sql'))\"",
     "start": "node dist/index.js",
+    "cli": "tsx src/cli.ts",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },
   "dependencies": {
+    "@agentclientprotocol/sdk": "^0.22.1",
     "@boocode/server": "workspace:*",
     "@fastify/static": "^7.0.4",
     "@fastify/websocket": "^10.0.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "fastify": "^4.28.1",
     "postgres": "^3.4.4",
+    "ws": "^8.18.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {
     "@types/node": "^20.14.10",
+    "@types/ws": "^8.5.10",
     "tsx": "^4.16.2",
     "typescript": "^5.5.0",
     "vitest": "^3.0.0"

apps/coder/src/cli.ts

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+/**
+ * BooCoder CLI client.
+ *
+ * Usage:
+ *   boocode run "task description" [--agent opencode] [--model claude-opus-4-7] [--project <id>]
+ *   boocode ls [--state pending|running|completed|failed]
+ *   boocode attach <task-id>
+ *   boocode send <task-id> "message"
+ */
+import { WebSocket } from 'ws';
+
+const BASE_URL = process.env.BOOCODER_URL ?? 'http://100.114.205.53:9502';
+
+// ─── Arg parsing ─────────────────────────────────────────────────────────────
+
+function getFlag(args: string[], name: string): string | undefined {
+  const idx = args.indexOf(name);
+  if (idx === -1 || idx + 1 >= args.length) return undefined;
+  return args[idx + 1];
+}
+
+function hasFlag(args: string[], name: string): boolean {
+  return args.includes(name);
+}
+
+// ─── HTTP helpers ────────────────────────────────────────────────────────────
+
+async function api(method: string, path: string, body?: unknown): Promise<unknown> {
+  const url = `${BASE_URL}${path}`;
+  const res = await fetch(url, {
+    method,
+    headers: body ? { 'Content-Type': 'application/json' } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`${method} ${path} → ${res.status}: ${text}`);
+  }
+  return res.json();
+}
+
+// ─── WS streaming ────────────────────────────────────────────────────────────
+
+function streamSession(sessionId: string): void {
+  const wsUrl = BASE_URL.replace(/^http/, 'ws') + `/api/ws/sessions/${sessionId}`;
+  const ws = new WebSocket(wsUrl);
+
+  ws.on('message', (data) => {
+    try {
+      const frame = JSON.parse(data.toString()) as { type: string; content?: string; name?: string; arguments?: string };
+      if (frame.type === 'delta' && frame.content) {
+        process.stdout.write(frame.content);
+      } else if (frame.type === 'tool_call') {
+        process.stdout.write(`\n[tool: ${frame.name ?? '?'}(${(frame.arguments ?? '').slice(0, 80)})]\n`);
+      } else if (frame.type === 'tool_result') {
+        process.stdout.write(`[tool_result]\n`);
+      } else if (frame.type === 'status' || frame.type === 'chat_status') {
+        // Silent
+      }
+    } catch {
+      // Non-JSON frame, ignore
+    }
+  });
+
+  ws.on('error', (err) => {
+    process.stderr.write(`WS error: ${err.message}\n`);
+  });
+
+  ws.on('close', () => {
+    process.stdout.write('\n');
+    process.exit(0);
+  });
+
+  process.on('SIGINT', () => {
+    ws.close();
+    process.exit(0);
+  });
+}
+
+// ─── Commands ────────────────────────────────────────────────────────────────
+
+async function cmdRun(args: string[]): Promise<void> {
+  const input = args.find((a) => !a.startsWith('--'));
+  if (!input) {
+    process.stderr.write('Usage: boocode run "task description" [--agent X] [--model X] [--project X]\n');
+    process.exit(1);
+  }
+
+  const agent = getFlag(args, '--agent');
+  const model = getFlag(args, '--model');
+  const project_id = getFlag(args, '--project');
+
+  if (!project_id) {
+    process.stderr.write('Error: --project <uuid> is required\n');
+    process.exit(1);
+  }
+
+  const result = (await api('POST', '/api/tasks', {
+    project_id,
+    input,
+    ...(agent && { agent }),
+    ...(model && { model }),
+  })) as { id: string; state: string };
+
+  process.stdout.write(`Task created: ${result.id} (state: ${result.state})\n`);
+
+  // Poll until task has session_id, then stream; or poll until terminal state
+  const POLL_MS = 2000;
+  for (;;) {
+    await sleep(POLL_MS);
+    const task = (await api('GET', `/api/tasks/${result.id}`)) as {
+      id: string; state: string; session_id?: string; output_summary?: string;
+    };
+
+    if (task.session_id) {
+      process.stdout.write(`Streaming session ${task.session_id}...\n`);
+      streamSession(task.session_id);
+      return; // streamSession handles exit
+    }
+
+    if (task.state === 'completed') {
+      process.stdout.write(`\nCompleted: ${task.output_summary ?? '(no summary)'}\n`);
+      return;
+    }
+    if (task.state === 'failed') {
+      process.stderr.write(`\nFailed: ${task.output_summary ?? '(no summary)'}\n`);
+      process.exit(1);
+    }
+    if (task.state === 'cancelled') {
+      process.stderr.write(`\nCancelled.\n`);
+      process.exit(1);
+    }
+  }
+}
+
+async function cmdLs(args: string[]): Promise<void> {
+  const state = getFlag(args, '--state');
+  const query = state ? `?state=${state}` : '';
+  const tasks = (await api('GET', `/api/tasks${query}`)) as Array<{
+    id: string; state: string; agent: string | null; input: string; created_at: string;
+  }>;
+
+  if (tasks.length === 0) {
+    process.stdout.write('No tasks.\n');
+    return;
+  }
+
+  // Table header
+  process.stdout.write(
+    pad('ID', 38) + pad('STATE', 12) + pad('AGENT', 14) + pad('INPUT', 52) + 'CREATED\n',
+  );
+  process.stdout.write('-'.repeat(120) + '\n');
+
+  for (const t of tasks) {
+    process.stdout.write(
+      pad(t.id, 38) +
+      pad(t.state, 12) +
+      pad(t.agent ?? '-', 14) +
+      pad(t.input.slice(0, 50), 52) +
+      (t.created_at?.slice(0, 19) ?? '') + '\n',
+    );
+  }
+}
+
+async function cmdAttach(args: string[]): Promise<void> {
+  const taskId = args[0];
+  if (!taskId) {
+    process.stderr.write('Usage: boocode attach <task-id>\n');
+    process.exit(1);
+  }
+
+  const task = (await api('GET', `/api/tasks/${taskId}`)) as { session_id?: string };
+  if (!task.session_id) {
+    process.stderr.write('Task has no session yet (still pending?).\n');
+    process.exit(1);
+  }
+
+  streamSession(task.session_id);
+}
+
+async function cmdSend(args: string[]): Promise<void> {
+  const taskId = args[0];
+  const message = args[1];
+  if (!taskId || !message) {
+    process.stderr.write('Usage: boocode send <task-id> "message"\n');
+    process.exit(1);
+  }
+
+  const task = (await api('GET', `/api/tasks/${taskId}`)) as { session_id?: string };
+  if (!task.session_id) {
+    process.stderr.write('Task has no session yet.\n');
+    process.exit(1);
+  }
+
+  // Find active chat
+  const sessionId = task.session_id;
+  // POST message to the session's chat (the messages route expects session_id in path)
+  await api('POST', `/api/sessions/${sessionId}/messages`, { content: message });
+
+  // Then attach to stream the response
+  streamSession(sessionId);
+}
+
+// ─── Utils ───────────────────────────────────────────────────────────────────
+
+function pad(s: string, width: number): string {
+  return s.length >= width ? s.slice(0, width) : s + ' '.repeat(width - s.length);
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+const [cmd, ...rest] = process.argv.slice(2);
+
+switch (cmd) {
+  case 'run':
+    cmdRun(rest).catch(fatal);
+    break;
+  case 'ls':
+    cmdLs(rest).catch(fatal);
+    break;
+  case 'attach':
+    cmdAttach(rest).catch(fatal);
+    break;
+  case 'send':
+    cmdSend(rest).catch(fatal);
+    break;
+  default:
+    process.stdout.write(
+      'BooCoder CLI\n\n' +
+      'Commands:\n' +
+      '  run "task"  [--agent X] [--model X] [--project <id>]   Create and stream a task\n' +
+      '  ls          [--state pending|running|completed|failed]   List tasks\n' +
+      '  attach      <task-id>                                    Stream a running task\n' +
+      '  send        <task-id> "message"                          Send input to a task\n' +
+      '\n' +
+      `Base URL: ${BASE_URL} (set BOOCODER_URL to override)\n`,
+    );
+    if (cmd && cmd !== '--help' && cmd !== '-h') process.exit(1);
+}
+
+function fatal(err: unknown): void {
+  process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(1);
+}

apps/coder/src/config.ts

@@ -23,6 +23,9 @@ const ConfigSchema = z.object({
   GITEA_TOKEN: z.string().optional(),
   GITEA_SSH_HOST: z.string().default('100.114.205.53:2222'),
   MCP_CONFIG_PATH: z.string().optional(),
+  // SSH access to the host for external agent dispatch (Phase 5)
+  BOOCODER_SSH_HOST: z.string().default('100.114.205.53'),
+  BOOCODER_SSH_USER: z.string().default('samkintop'),
 });
 
 export type Config = z.infer<typeof ConfigSchema>;

apps/coder/src/index.ts

@@ -9,6 +9,7 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 import { loadConfig } from './config.js';
 import { getSql, applySchema, pingDb, closeDb } from './db.js';
+import { startMcpServer } from './services/mcp-server.js';
 // v2.0.0 Phase 2B: workspace dependency on @boocode/server — reuse the
 // inference loop, broker, and tool registry without duplication.
 import { createInferenceRunner } from '@boocode/server/inference';
@@ -23,9 +24,24 @@ import { setInferenceContext, clearInferenceContext } from './services/tools/inf
 // Routes
 import { registerMessageRoutes } from './routes/messages.js';
 import { registerPendingRoutes } from './routes/pending.js';
+import { registerTaskRoutes } from './routes/tasks.js';
+import { registerInboxRoutes } from './routes/inbox.js';
+import { registerStatsRoutes } from './routes/stats.js';
 import { registerWebSocket } from './routes/ws.js';
+// Phase 4: dispatcher + agent probe
+import { createDispatcher } from './services/dispatcher.js';
+import { probeAgents } from './services/agent-probe.js';
 
 async function main() {
+  // MCP mode: stdio transport, no HTTP server
+  if (process.argv.includes('--mcp')) {
+    const config = loadConfig();
+    const sql = getSql(config);
+    await applySchema(sql);
+    await startMcpServer(sql);
+    return;
+  }
+
   const config = loadConfig();
 
   const app = Fastify({
@@ -113,9 +129,20 @@ async function main() {
     });
   });
 
+  // Phase 4: probe available agents on startup
+  await probeAgents(sql, app.log);
+
+  // Phase 4: dispatcher — polls tasks table and runs inference
+  const dispatcher = createDispatcher({ sql, inference: inferenceApi, broker, log: app.log, config });
+  dispatcher.start();
+  app.addHook('onClose', () => dispatcher.stop());
+
   // Register routes
   registerMessageRoutes(app, sql, broker, inferenceApi);
   registerPendingRoutes(app, sql);
+  registerTaskRoutes(app, sql, inferenceApi);
+  registerInboxRoutes(app, sql);
+  registerStatsRoutes(app, sql);
   registerWebSocket(app, sql, broker);
 
   // Serve static frontend (built web app). In production, the dist/ is

apps/coder/src/routes/inbox.ts

@@ -0,0 +1,33 @@
+import type { FastifyInstance } from 'fastify';
+import type { Sql } from '../db.js';
+
+export function registerInboxRoutes(app: FastifyInstance, sql: Sql): void {
+  // GET /api/inbox — tasks needing human attention (blocked or failed)
+  app.get('/api/inbox', async () => {
+    return sql`
+      SELECT id, project_id, parent_task_id, state, input, output_summary, agent, model, session_id, started_at, ended_at, created_at
+      FROM human_inbox
+      ORDER BY created_at DESC
+      LIMIT 100
+    `;
+  });
+
+  // POST /api/inbox/:id/retry — reset a blocked/failed task to pending for re-dispatch
+  app.post<{ Params: { id: string } }>('/api/inbox/:id/retry', async (req, reply) => {
+    const taskId = req.params.id;
+
+    const result = await sql`
+      UPDATE tasks
+      SET state = 'pending', started_at = NULL, ended_at = NULL, output_summary = NULL
+      WHERE id = ${taskId} AND state IN ('blocked', 'failed')
+      RETURNING id, state
+    `;
+
+    if (result.length === 0) {
+      reply.code(404);
+      return { error: 'task not found or not in retryable state' };
+    }
+
+    return { id: result[0]!.id, state: result[0]!.state };
+  });
+}

apps/coder/src/routes/stats.ts

@@ -0,0 +1,48 @@
+import type { FastifyInstance } from 'fastify';
+import { z } from 'zod';
+import type { Sql } from '../db.js';
+
+const CostQuery = z.object({
+  group_by: z.enum(['project', 'agent', 'day']).default('project'),
+});
+
+export function registerStatsRoutes(app: FastifyInstance, sql: Sql): void {
+  // GET /api/stats/costs — aggregate cost_tokens by project, agent, or day
+  app.get('/api/stats/costs', async (req, reply) => {
+    const parsed = CostQuery.safeParse(req.query);
+    if (!parsed.success) {
+      reply.code(400);
+      return { error: 'invalid query', details: parsed.error.flatten() };
+    }
+
+    const { group_by } = parsed.data;
+
+    switch (group_by) {
+      case 'project':
+        return sql`
+          SELECT project_id, COUNT(*)::int AS task_count, COALESCE(SUM(cost_tokens), 0)::int AS total_tokens
+          FROM tasks
+          WHERE cost_tokens IS NOT NULL
+          GROUP BY project_id
+          ORDER BY total_tokens DESC
+        `;
+      case 'agent':
+        return sql`
+          SELECT COALESCE(agent, 'native') AS agent, COUNT(*)::int AS task_count, COALESCE(SUM(cost_tokens), 0)::int AS total_tokens
+          FROM tasks
+          WHERE cost_tokens IS NOT NULL
+          GROUP BY agent
+          ORDER BY total_tokens DESC
+        `;
+      case 'day':
+        return sql`
+          SELECT DATE(created_at) AS day, COUNT(*)::int AS task_count, COALESCE(SUM(cost_tokens), 0)::int AS total_tokens
+          FROM tasks
+          WHERE cost_tokens IS NOT NULL
+          GROUP BY DATE(created_at)
+          ORDER BY day DESC
+          LIMIT 90
+        `;
+    }
+  });
+}

apps/coder/src/routes/tasks.ts

@@ -0,0 +1,138 @@
+import type { FastifyInstance } from 'fastify';
+import { z } from 'zod';
+import type { Sql } from '../db.js';
+
+interface InferenceApi {
+  cancel: (sessionId: string, chatId: string) => Promise<boolean>;
+}
+
+const CreateBody = z.object({
+  project_id: z.string().uuid(),
+  input: z.string().min(1).max(64_000),
+  agent: z.string().max(100).optional(),
+  model: z.string().max(200).optional(),
+});
+
+const ListQuery = z.object({
+  state: z.enum(['pending', 'running', 'completed', 'failed', 'blocked', 'cancelled']).optional(),
+  project_id: z.string().uuid().optional(),
+});
+
+export function registerTaskRoutes(app: FastifyInstance, sql: Sql, inference: InferenceApi): void {
+  // POST /api/tasks — create a new task
+  app.post('/api/tasks', async (req, reply) => {
+    const parsed = CreateBody.safeParse(req.body);
+    if (!parsed.success) {
+      reply.code(400);
+      return { error: 'invalid body', details: parsed.error.flatten() };
+    }
+
+    const { project_id, input, agent, model } = parsed.data;
+
+    const [task] = await sql<{ id: string; state: string }[]>`
+      INSERT INTO tasks (project_id, input, agent, model)
+      VALUES (${project_id}, ${input}, ${agent ?? null}, ${model ?? null})
+      RETURNING id, state
+    `;
+
+    reply.code(201);
+    return { id: task!.id, state: task!.state };
+  });
+
+  // GET /api/tasks — list tasks with optional filters
+  app.get('/api/tasks', async (req, _reply) => {
+    const parsed = ListQuery.safeParse(req.query);
+    if (!parsed.success) {
+      return { error: 'invalid query', details: parsed.error.flatten() };
+    }
+
+    const { state, project_id } = parsed.data;
+
+    // Build query with optional filters
+    if (state && project_id) {
+      return sql`
+        SELECT id, project_id, state, input, output_summary, agent, model, execution_path, session_id, started_at, ended_at, created_at
+        FROM tasks
+        WHERE state = ${state} AND project_id = ${project_id}
+        ORDER BY created_at DESC
+        LIMIT 100
+      `;
+    } else if (state) {
+      return sql`
+        SELECT id, project_id, state, input, output_summary, agent, model, execution_path, session_id, started_at, ended_at, created_at
+        FROM tasks
+        WHERE state = ${state}
+        ORDER BY created_at DESC
+        LIMIT 100
+      `;
+    } else if (project_id) {
+      return sql`
+        SELECT id, project_id, state, input, output_summary, agent, model, execution_path, session_id, started_at, ended_at, created_at
+        FROM tasks
+        WHERE project_id = ${project_id}
+        ORDER BY created_at DESC
+        LIMIT 100
+      `;
+    } else {
+      return sql`
+        SELECT id, project_id, state, input, output_summary, agent, model, execution_path, session_id, started_at, ended_at, created_at
+        FROM tasks
+        ORDER BY created_at DESC
+        LIMIT 100
+      `;
+    }
+  });
+
+  // GET /api/tasks/:id — single task detail
+  app.get<{ Params: { id: string } }>('/api/tasks/:id', async (req, reply) => {
+    const rows = await sql`
+      SELECT id, project_id, parent_task_id, state, input, output_summary, agent, model, execution_path, worktree_path, session_id, cost_tokens, started_at, ended_at, created_at
+      FROM tasks
+      WHERE id = ${req.params.id}
+    `;
+    if (rows.length === 0) {
+      reply.code(404);
+      return { error: 'task not found' };
+    }
+    return rows[0];
+  });
+
+  // POST /api/tasks/:id/cancel — cancel a pending or running task
+  app.post<{ Params: { id: string } }>('/api/tasks/:id/cancel', async (req, reply) => {
+    const taskId = req.params.id;
+
+    // Get current task state + session info
+    const rows = await sql<{ id: string; state: string; session_id: string | null }[]>`
+      SELECT id, state, session_id FROM tasks WHERE id = ${taskId}
+    `;
+    if (rows.length === 0) {
+      reply.code(404);
+      return { error: 'task not found' };
+    }
+
+    const task = rows[0]!;
+    if (task.state !== 'pending' && task.state !== 'running') {
+      reply.code(409);
+      return { error: `cannot cancel task in state '${task.state}'` };
+    }
+
+    // If running, try to cancel inference
+    if (task.state === 'running' && task.session_id) {
+      // Find active chat in the task's session
+      const chats = await sql<{ id: string }[]>`
+        SELECT id FROM chats WHERE session_id = ${task.session_id} AND status = 'open'
+      `;
+      for (const chat of chats) {
+        await inference.cancel(task.session_id, chat.id);
+      }
+    }
+
+    await sql`
+      UPDATE tasks
+      SET state = 'cancelled', ended_at = clock_timestamp()
+      WHERE id = ${taskId} AND state IN ('pending', 'running')
+    `;
+
+    return { cancelled: true };
+  });
+}

apps/coder/src/schema.sql

@@ -43,6 +43,9 @@ CREATE TABLE IF NOT EXISTS available_agents (
   last_probed_at TIMESTAMPTZ
 );
 
+-- v2.0.0 Phase 4: link tasks to their inference sessions.
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS session_id UUID REFERENCES sessions(id);
+
 -- Human inbox: tasks needing attention
 CREATE OR REPLACE VIEW human_inbox AS
   SELECT * FROM tasks WHERE state IN ('blocked', 'failed');

apps/coder/src/services/acp-dispatch.ts

@@ -0,0 +1,271 @@
+/**
+ * ACP dispatch — runs ACP-capable agents (opencode, goose) on the host via SSH.
+ *
+ * Uses the @agentclientprotocol/sdk to establish a structured JSON-RPC session
+ * with the agent subprocess. The SSH tunnel provides stdio transport.
+ *
+ * Flow:
+ * 1. SSH to host, start `opencode acp` (or `goose acp`) in the worktree
+ * 2. Wrap SSH child's stdin/stdout into NDJSON streams
+ * 3. Create a ClientSideConnection from the SDK
+ * 4. Initialize → newSession → prompt(task)
+ * 5. Collect session updates (tool calls, text output)
+ * 6. On prompt completion → return collected output
+ */
+import type { FastifyBaseLogger } from 'fastify';
+import { Readable, Writable } from 'node:stream';
+import {
+  ClientSideConnection,
+  ndJsonStream,
+  type Client,
+  type SessionNotification,
+  type RequestPermissionRequest,
+  type RequestPermissionResponse,
+  type ReadTextFileRequest,
+  type ReadTextFileResponse,
+  type WriteTextFileRequest,
+  type WriteTextFileResponse,
+  type CreateTerminalRequest,
+  type CreateTerminalResponse,
+} from '@agentclientprotocol/sdk';
+import { sshSpawn } from './ssh.js';
+
+export interface AcpDispatchResult {
+  exitCode: number;
+  output: string;
+  toolCalls: Array<{ title: string; input: unknown; output?: unknown }>;
+  stopReason: string;
+}
+
+export interface AcpDispatchOpts {
+  agent: string;
+  task: string;
+  worktreePath: string;
+  model?: string;
+  signal?: AbortSignal;
+  log: FastifyBaseLogger;
+}
+
+/** Map agent name to the ACP command it exposes. */
+function acpCommand(agent: string): string | null {
+  switch (agent) {
+    case 'opencode':
+      return 'opencode acp';
+    case 'goose':
+      return 'goose acp';
+    default:
+      return null;
+  }
+}
+
+/**
+ * Convert a Node.js Readable stream to a web ReadableStream<Uint8Array>.
+ */
+function nodeReadableToWeb(nodeStream: NodeJS.ReadableStream): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      nodeStream.on('data', (chunk: Buffer) => {
+        controller.enqueue(new Uint8Array(chunk));
+      });
+      nodeStream.on('end', () => {
+        controller.close();
+      });
+      nodeStream.on('error', (err) => {
+        controller.error(err);
+      });
+    },
+    cancel() {
+      if ('destroy' in nodeStream && typeof (nodeStream as Readable).destroy === 'function') {
+        (nodeStream as Readable).destroy();
+      }
+    },
+  });
+}
+
+/**
+ * Convert a Node.js Writable stream to a web WritableStream<Uint8Array>.
+ */
+function nodeWritableToWeb(nodeStream: NodeJS.WritableStream): WritableStream<Uint8Array> {
+  return new WritableStream<Uint8Array>({
+    write(chunk) {
+      return new Promise<void>((resolve, reject) => {
+        const ok = (nodeStream as Writable).write(chunk, (err) => {
+          if (err) reject(err);
+        });
+        if (ok) resolve();
+        else (nodeStream as Writable).once('drain', resolve);
+      });
+    },
+    close() {
+      return new Promise<void>((resolve) => {
+        (nodeStream as Writable).end(resolve);
+      });
+    },
+    abort() {
+      (nodeStream as Writable).destroy();
+    },
+  });
+}
+
+/**
+ * Dispatch a task to an ACP-capable agent via SSH.
+ *
+ * Opens a structured ACP session, sends the task as a prompt, and collects
+ * all session updates. Returns the collected output and tool calls.
+ */
+export async function dispatchViaAcp(opts: AcpDispatchOpts): Promise<AcpDispatchResult> {
+  const { agent, task, worktreePath, signal, log } = opts;
+
+  const cmd = acpCommand(agent);
+  if (!cmd) {
+    return {
+      exitCode: 1,
+      output: `Agent '${agent}' does not support ACP.`,
+      toolCalls: [],
+      stopReason: 'error',
+    };
+  }
+
+  // Spawn SSH with the ACP command running in the worktree
+  const escapedPath = worktreePath.replace(/'/g, "'\\''");
+  const fullCommand = `cd '${escapedPath}' && ${cmd}`;
+
+  log.info({ agent, worktreePath }, 'acp-dispatch: spawning');
+  const child = sshSpawn(fullCommand);
+
+  // Wire up abort
+  let killed = false;
+  const cleanup = () => {
+    if (!killed) {
+      killed = true;
+      child.kill('SIGTERM');
+      setTimeout(() => child.kill('SIGKILL'), 5_000);
+    }
+  };
+
+  if (signal) {
+    if (signal.aborted) {
+      cleanup();
+      return { exitCode: 130, output: 'Aborted before start', toolCalls: [], stopReason: 'cancelled' };
+    }
+    signal.addEventListener('abort', cleanup, { once: true });
+  }
+
+  try {
+    // Create web streams from the child process stdio
+    const inputStream = nodeReadableToWeb(child.stdout!);
+    const outputStream = nodeWritableToWeb(child.stdin!);
+
+    // Create the NDJSON ACP stream
+    const stream = ndJsonStream(outputStream, inputStream);
+
+    // Collected session updates
+    const textChunks: string[] = [];
+    const toolCalls: Array<{ title: string; input: unknown; output?: unknown }> = [];
+
+    // Create client-side connection — we are the "client" (editor), the agent is remote
+    const connection = new ClientSideConnection(
+      (_agentInterface): Client => ({
+        // Handle session updates from the agent
+        async sessionUpdate(params: SessionNotification): Promise<void> {
+          const update = params.update;
+          if (update.sessionUpdate === 'agent_message_chunk') {
+            // ContentChunk with content: ContentBlock
+            const content = update.content;
+            if (content.type === 'text' && 'text' in content) {
+              textChunks.push((content as { text: string }).text);
+            }
+          } else if (update.sessionUpdate === 'tool_call') {
+            toolCalls.push({
+              title: update.title,
+              input: update.rawInput,
+            });
+          } else if (update.sessionUpdate === 'tool_call_update') {
+            const last = toolCalls[toolCalls.length - 1];
+            if (last && update.rawOutput !== undefined) {
+              last.output = update.rawOutput;
+            }
+          }
+        },
+
+        // Permission requests — auto-approve by selecting the first option (worktree is isolated)
+        async requestPermission(params: RequestPermissionRequest): Promise<RequestPermissionResponse> {
+          // Select the first available option to auto-approve
+          const firstOption = params.options[0];
+          if (firstOption) {
+            return {
+              outcome: { outcome: 'selected', optionId: firstOption.optionId },
+            };
+          }
+          // No options available — cancel
+          return { outcome: { outcome: 'cancelled' } };
+        },
+
+        // File system operations — let the agent handle them directly in the worktree
+        async readTextFile(_params: ReadTextFileRequest): Promise<ReadTextFileResponse> {
+          return { content: '' };
+        },
+        async writeTextFile(_params: WriteTextFileRequest): Promise<WriteTextFileResponse> {
+          return {};
+        },
+        async createTerminal(_params: CreateTerminalRequest): Promise<CreateTerminalResponse> {
+          return { terminalId: 'noop' };
+        },
+      }),
+      stream,
+    );
+
+    // Initialize the connection
+    // ProtocolVersion is a number in this SDK version
+    const initResult = await connection.initialize({
+      protocolVersion: 1,
+      clientInfo: { name: 'boocoder', version: '2.0.1' },
+      clientCapabilities: {},
+    });
+    log.info({ agentInfo: initResult.agentInfo }, 'acp-dispatch: initialized');
+
+    // Create a new session
+    const session = await connection.newSession({
+      cwd: worktreePath,
+      mcpServers: [],
+    });
+    log.info({ sessionId: session.sessionId }, 'acp-dispatch: session created');
+
+    // Send the prompt
+    const promptResult = await connection.prompt({
+      sessionId: session.sessionId,
+      prompt: [{ type: 'text', text: task }],
+    });
+
+    const stopReason = promptResult.stopReason ?? 'end_turn';
+    log.info({ agent, stopReason, toolCallCount: toolCalls.length }, 'acp-dispatch: prompt completed');
+
+    // Clean shutdown
+    await connection.closeSession({ sessionId: session.sessionId }).catch(() => {});
+
+    return {
+      exitCode: 0,
+      output: textChunks.join(''),
+      toolCalls,
+      stopReason,
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error({ agent, err: message }, 'acp-dispatch: error');
+    return {
+      exitCode: 1,
+      output: message,
+      toolCalls: [],
+      stopReason: 'error',
+    };
+  } finally {
+    if (signal) signal.removeEventListener('abort', cleanup);
+    cleanup();
+
+    // Wait for child to exit
+    await new Promise<void>((resolve) => {
+      child.on('close', resolve);
+      setTimeout(resolve, 3_000);
+    });
+  }
+}

apps/coder/src/services/agent-probe.ts

@@ -0,0 +1,70 @@
+import type { Sql } from '../db.js';
+import type { FastifyBaseLogger } from 'fastify';
+import { sshExec } from './ssh.js';
+
+const KNOWN_AGENTS: Array<{ name: string; supportsAcp: boolean }> = [
+  { name: 'opencode', supportsAcp: true },
+  { name: 'goose', supportsAcp: true },
+  { name: 'claude', supportsAcp: false },
+  { name: 'pi', supportsAcp: false },
+];
+
+/**
+ * Probe for available agents on the HOST via SSH.
+ *
+ * The boocoder container can't run agents locally — they live on the host.
+ * We SSH to the host (same mechanism BooTerm uses) and check which agent
+ * binaries are on PATH.
+ */
+export async function probeAgents(sql: Sql, log: FastifyBaseLogger): Promise<void> {
+  log.info('agent-probe: scanning HOST for known agents via SSH');
+
+  for (const agent of KNOWN_AGENTS) {
+    try {
+      // Check if the agent binary is on the host's PATH
+      const whichResult = await sshExec(`which ${agent.name}`, { timeoutMs: 10_000 });
+      const installPath = whichResult.stdout.trim();
+      if (whichResult.exitCode !== 0 || !installPath) continue;
+
+      // Get version
+      let version: string | null = null;
+      try {
+        const verResult = await sshExec(`${agent.name} --version`, { timeoutMs: 15_000 });
+        if (verResult.exitCode === 0) {
+          version = verResult.stdout.trim().slice(0, 100);
+        }
+      } catch {
+        // Some agents may not support --version — that's fine
+      }
+
+      // For ACP-capable agents, verify ACP mode actually works
+      let supportsAcp = agent.supportsAcp;
+      if (supportsAcp) {
+        try {
+          const acpCheck = await sshExec(`${agent.name} acp --help`, { timeoutMs: 10_000 });
+          supportsAcp = acpCheck.exitCode === 0;
+        } catch {
+          supportsAcp = false;
+        }
+      }
+
+      // UPSERT into available_agents
+      await sql`
+        INSERT INTO available_agents (name, install_path, version, supports_acp, last_probed_at)
+        VALUES (${agent.name}, ${installPath}, ${version}, ${supportsAcp}, clock_timestamp())
+        ON CONFLICT (name) DO UPDATE SET
+          install_path = EXCLUDED.install_path,
+          version = EXCLUDED.version,
+          supports_acp = EXCLUDED.supports_acp,
+          last_probed_at = EXCLUDED.last_probed_at
+      `;
+      log.info({ agent: agent.name, version, installPath, supportsAcp }, 'agent-probe: found on host');
+    } catch (err) {
+      // SSH failed or agent not found — skip silently
+      const msg = err instanceof Error ? err.message : String(err);
+      log.debug({ agent: agent.name, err: msg }, 'agent-probe: not found or SSH failed');
+    }
+  }
+
+  log.info('agent-probe: scan complete');
+}

apps/coder/src/services/dispatcher.ts

@@ -0,0 +1,384 @@
+import type { Sql } from '../db.js';
+import type { FastifyBaseLogger } from 'fastify';
+import type { Broker } from '@boocode/server/broker';
+import type { Config } from '../config.js';
+import { createWorktree, diffWorktree, cleanupWorktree } from './worktrees.js';
+import { dispatchViaAcp } from './acp-dispatch.js';
+import { dispatchViaPty } from './pty-dispatch.js';
+
+interface InferenceRunner {
+  enqueue: (sessionId: string, chatId: string, assistantId: string, user: string) => void;
+  cancel: (sessionId: string, chatId: string) => Promise<boolean>;
+  hasActive: (chatId: string) => boolean;
+}
+
+interface Deps {
+  sql: Sql;
+  inference: InferenceRunner;
+  broker: Broker;
+  log: FastifyBaseLogger;
+  config: Config;
+}
+
+const POLL_INTERVAL_MS = 5_000;
+const COMPLETION_POLL_MS = 2_000;
+
+export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<void> } {
+  const { sql, inference, log, config } = deps;
+  let timer: ReturnType<typeof setInterval> | null = null;
+  let running = false;
+  let stopping = false;
+  let inflightPromise: Promise<void> | null = null;
+
+  async function poll(): Promise<void> {
+    if (running || stopping) return;
+
+    // Grab one pending task
+    const rows = await sql<{ id: string; project_id: string; input: string; agent: string | null; model: string | null }[]>`
+      SELECT id, project_id, input, agent, model
+      FROM tasks
+      WHERE state = 'pending'
+      ORDER BY created_at
+      LIMIT 1
+    `;
+    if (rows.length === 0) return;
+
+    const task = rows[0]!;
+    running = true;
+    inflightPromise = runTask(task).finally(() => {
+      running = false;
+      inflightPromise = null;
+    });
+  }
+
+  async function runTask(task: { id: string; project_id: string; input: string; agent: string | null; model: string | null }): Promise<void> {
+    const taskId = task.id;
+
+    // Determine execution path: if agent is specified AND exists in available_agents → Path B
+    if (task.agent) {
+      const [agentRow] = await sql<{ name: string; supports_acp: boolean }[]>`
+        SELECT name, supports_acp FROM available_agents WHERE name = ${task.agent}
+      `;
+      if (agentRow) {
+        await runExternalAgent(task, agentRow.supports_acp);
+        return;
+      }
+      // Agent specified but not available — fall through to Path A with a warning
+      log.warn({ taskId, agent: task.agent }, 'dispatcher: specified agent not available, falling back to native');
+    }
+
+    // Path A — native inference (existing behavior)
+    await runNativeInference(task);
+  }
+
+  // ─── Path A: Native Inference ───────────────────────────────────────────────
+
+  async function runNativeInference(task: { id: string; project_id: string; input: string; agent: string | null; model: string | null }): Promise<void> {
+    const taskId = task.id;
+    log.info({ taskId }, 'dispatcher: starting task (path A — native)');
+
+    try {
+      // Mark running
+      await sql`
+        UPDATE tasks
+        SET state = 'running', started_at = clock_timestamp(), execution_path = 'native'
+        WHERE id = ${taskId}
+      `;
+
+      // Create session + chat for this task
+      const model = task.model ?? config.DEFAULT_MODEL;
+      const sessionName = 'Task: ' + task.input.slice(0, 40);
+
+      const [session] = await sql<{ id: string }[]>`
+        INSERT INTO sessions (project_id, name, model, status)
+        VALUES (${task.project_id}, ${sessionName}, ${model}, 'open')
+        RETURNING id
+      `;
+      const sessionId = session!.id;
+
+      const [chat] = await sql<{ id: string }[]>`
+        INSERT INTO chats (session_id, name, status)
+        VALUES (${sessionId}, 'Task execution', 'open')
+        RETURNING id
+      `;
+      const chatId = chat!.id;
+
+      // Link task to session
+      await sql`UPDATE tasks SET session_id = ${sessionId} WHERE id = ${taskId}`;
+
+      // Create user message + streaming assistant
+      await sql<{ id: string }[]>`
+        INSERT INTO messages (session_id, chat_id, role, content, status, created_at)
+        VALUES (${sessionId}, ${chatId}, 'user', ${task.input}, 'complete', clock_timestamp())
+        RETURNING id
+      `;
+      const [assistantMsg] = await sql<{ id: string }[]>`
+        INSERT INTO messages (session_id, chat_id, role, content, status, created_at)
+        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', clock_timestamp())
+        RETURNING id
+      `;
+      const assistantId = assistantMsg!.id;
+
+      // Enqueue inference
+      inference.enqueue(sessionId, chatId, assistantId, 'default');
+
+      // Wait for inference to complete (poll message status)
+      const finalStatus = await waitForCompletion(assistantId);
+
+      if (stopping) {
+        await sql`
+          UPDATE tasks
+          SET state = 'cancelled', ended_at = clock_timestamp()
+          WHERE id = ${taskId}
+        `;
+        return;
+      }
+
+      // Aggregate token cost for the task's session
+      const [costRow] = await sql<{ total: number | null }[]>`
+        SELECT SUM(tokens_used)::int AS total
+        FROM messages
+        WHERE session_id = ${sessionId} AND tokens_used IS NOT NULL
+      `;
+      const costTokens = costRow?.total ?? null;
+
+      if (finalStatus === 'complete') {
+        const [msg] = await sql<{ content: string | null }[]>`
+          SELECT content FROM messages WHERE id = ${assistantId}
+        `;
+        const summary = (msg?.content ?? '').slice(0, 500);
+        await sql`
+          UPDATE tasks
+          SET state = 'completed', ended_at = clock_timestamp(), output_summary = ${summary}, cost_tokens = ${costTokens}
+          WHERE id = ${taskId}
+        `;
+        log.info({ taskId, costTokens }, 'dispatcher: task completed (native)');
+      } else {
+        const [msg] = await sql<{ content: string | null }[]>`
+          SELECT content FROM messages WHERE id = ${assistantId}
+        `;
+        const summary = (msg?.content ?? 'Inference failed').slice(0, 500);
+        await sql`
+          UPDATE tasks
+          SET state = 'failed', ended_at = clock_timestamp(), output_summary = ${summary}, cost_tokens = ${costTokens}
+          WHERE id = ${taskId}
+        `;
+        log.warn({ taskId, finalStatus }, 'dispatcher: task failed (native)');
+      }
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      log.error({ taskId, err: errMsg }, 'dispatcher: task error (native)');
+      await sql`
+        UPDATE tasks
+        SET state = 'failed', ended_at = clock_timestamp(), output_summary = ${errMsg.slice(0, 500)}
+        WHERE id = ${taskId}
+      `.catch(() => {});
+    }
+  }
+
+  // ─── Path B: External Agent Dispatch ──────<E29480><E29480><EFBFBD>─────────────────────────────────
+
+  async function runExternalAgent(
+    task: { id: string; project_id: string; input: string; agent: string | null; model: string | null },
+    supportsAcp: boolean,
+  ): Promise<void> {
+    const taskId = task.id;
+    const agent = task.agent!;
+    const executionPath = supportsAcp ? 'acp' : 'pty';
+
+    log.info({ taskId, agent, executionPath }, 'dispatcher: starting task (path B — external)');
+
+    // Resolve the project's root path
+    const [project] = await sql<{ root_path: string | null }[]>`
+      SELECT root_path FROM projects WHERE id = ${task.project_id}
+    `;
+    const projectPath = project?.root_path;
+    if (!projectPath) {
+      await sql`
+        UPDATE tasks
+        SET state = 'failed', ended_at = clock_timestamp(), output_summary = 'Project has no root_path — cannot create worktree'
+        WHERE id = ${taskId}
+      `;
+      return;
+    }
+
+    // Create an abort controller for this task
+    const ac = new AbortController();
+
+    try {
+      // Mark running
+      await sql`
+        UPDATE tasks
+        SET state = 'running', started_at = clock_timestamp(), execution_path = ${executionPath}
+        WHERE id = ${taskId}
+      `;
+
+      // Create session + chat for this task (same as Path A — for output tracking)
+      const sessionName = `Task [${agent}]: ${task.input.slice(0, 30)}`;
+      const [session] = await sql<{ id: string }[]>`
+        INSERT INTO sessions (project_id, name, model, status)
+        VALUES (${task.project_id}, ${sessionName}, ${task.model ?? config.DEFAULT_MODEL}, 'open')
+        RETURNING id
+      `;
+      const sessionId = session!.id;
+
+      const [chat] = await sql<{ id: string }[]>`
+        INSERT INTO chats (session_id, name, status)
+        VALUES (${sessionId}, 'External agent execution', 'open')
+        RETURNING id
+      `;
+      const chatId = chat!.id;
+
+      // Link task to session
+      await sql`UPDATE tasks SET session_id = ${sessionId} WHERE id = ${taskId}`;
+
+      // Create user message for the task input
+      await sql`
+        INSERT INTO messages (session_id, chat_id, role, content, status, created_at)
+        VALUES (${sessionId}, ${chatId}, 'user', ${task.input}, 'complete', clock_timestamp())
+      `;
+
+      // Step 1: Create worktree
+      log.info({ taskId, projectPath }, 'dispatcher: creating worktree');
+      const worktreePath = await createWorktree(projectPath, taskId, { signal: ac.signal });
+      log.info({ taskId, worktreePath }, 'dispatcher: worktree created');
+
+      // Step 2: Dispatch to agent
+      let outputSummary: string;
+
+      if (supportsAcp) {
+        const result = await dispatchViaAcp({
+          agent,
+          task: task.input,
+          worktreePath,
+          model: task.model ?? undefined,
+          signal: ac.signal,
+          log,
+        });
+        outputSummary = result.output.slice(0, 500);
+
+        // Store agent output as an assistant message
+        await sql`
+          INSERT INTO messages (session_id, chat_id, role, content, status, created_at)
+          VALUES (${sessionId}, ${chatId}, 'assistant', ${result.output.slice(0, 50_000)}, 'complete', clock_timestamp())
+        `;
+      } else {
+        const result = await dispatchViaPty({
+          agent,
+          task: task.input,
+          worktreePath,
+          model: task.model ?? undefined,
+          signal: ac.signal,
+          log,
+        });
+        outputSummary = (result.stdout || result.stderr).slice(0, 500);
+
+        // Store agent output as an assistant message
+        const content = result.stdout || result.stderr || '(no output)';
+        await sql`
+          INSERT INTO messages (session_id, chat_id, role, content, status, created_at)
+          VALUES (${sessionId}, ${chatId}, 'assistant', ${content.slice(0, 50_000)}, 'complete', clock_timestamp())
+        `;
+      }
+
+      if (stopping) {
+        await sql`
+          UPDATE tasks SET state = 'cancelled', ended_at = clock_timestamp() WHERE id = ${taskId}
+        `;
+        await cleanupWorktree(projectPath, taskId);
+        return;
+      }
+
+      // Step 3: Diff the worktree and queue pending changes
+      log.info({ taskId }, 'dispatcher: diffing worktree');
+      const diff = await diffWorktree(worktreePath, projectPath, { signal: ac.signal });
+
+      if (diff) {
+        // Queue a single pending_change entry with the full unified diff
+        await sql`
+          INSERT INTO pending_changes (session_id, task_id, file_path, operation, diff)
+          VALUES (${sessionId}, ${taskId}, ${projectPath}, 'edit', ${diff})
+        `;
+        log.info({ taskId, diffLength: diff.length }, 'dispatcher: diff queued as pending change');
+      } else {
+        log.info({ taskId }, 'dispatcher: no changes detected in worktree');
+      }
+
+      // Step 4: Cleanup worktree
+      await cleanupWorktree(projectPath, taskId);
+
+      // Step 5: Aggregate token cost
+      const [extCostRow] = await sql<{ total: number | null }[]>`
+        SELECT SUM(tokens_used)::int AS total
+        FROM messages
+        WHERE session_id = ${sessionId} AND tokens_used IS NOT NULL
+      `;
+      const extCostTokens = extCostRow?.total ?? null;
+
+      // Step 6: Mark task completed
+      await sql`
+        UPDATE tasks
+        SET state = 'completed', ended_at = clock_timestamp(), output_summary = ${outputSummary}, cost_tokens = ${extCostTokens}
+        WHERE id = ${taskId}
+      `;
+      log.info({ taskId, agent, costTokens: extCostTokens }, 'dispatcher: task completed (external)');
+
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      log.error({ taskId, agent, err: errMsg }, 'dispatcher: external agent error');
+
+      await sql`
+        UPDATE tasks
+        SET state = 'failed', ended_at = clock_timestamp(), output_summary = ${errMsg.slice(0, 500)}
+        WHERE id = ${taskId}
+      `.catch(() => {});
+
+      // Best-effort cleanup
+      await cleanupWorktree(projectPath, taskId);
+    }
+  }
+
+  // ─── Helpers ────────────────────────────────────────────────────────────────
+
+  async function waitForCompletion(assistantId: string): Promise<string> {
+    for (;;) {
+      if (stopping) return 'cancelled';
+
+      const [row] = await sql<{ status: string }[]>`
+        SELECT status FROM messages WHERE id = ${assistantId}
+      `;
+      const status = row?.status ?? 'failed';
+      if (status !== 'streaming') return status;
+
+      await sleep(COMPLETION_POLL_MS);
+    }
+  }
+
+  function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  return {
+    start() {
+      log.info('dispatcher: starting poll loop');
+      timer = setInterval(() => {
+        poll().catch((err) => {
+          log.error({ err }, 'dispatcher: poll error');
+        });
+      }, POLL_INTERVAL_MS);
+    },
+
+    async stop() {
+      stopping = true;
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+      if (inflightPromise) {
+        log.info('dispatcher: waiting for in-flight task');
+        await inflightPromise;
+      }
+      log.info('dispatcher: stopped');
+    },
+  };
+}

apps/coder/src/services/mcp-server.ts

@@ -0,0 +1,201 @@
+/**
+ * BooCoder MCP Server — exposes task primitives as MCP tools.
+ *
+ * Started when `--mcp` flag is passed to the entry point. Runs stdio transport
+ * so external tools (opencode in Termius) can drive the task queue.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import type { Sql } from '../db.js';
+import { applyOne, rejectOne } from './pending_changes.js';
+
+// --- Tool handlers -----------------------------------------------------------
+
+interface TaskRow {
+  id: string;
+  state: string;
+}
+
+interface PendingRow {
+  id: string;
+  file_path: string;
+  operation: string;
+  diff: string;
+  session_id: string;
+}
+
+interface WorktreeRow {
+  id: string;
+  worktree_path: string;
+  agent: string;
+  started_at: string;
+}
+
+interface ProjectPathRow {
+  path: string;
+}
+
+function textResult(data: unknown) {
+  return { content: [{ type: 'text' as const, text: JSON.stringify(data, null, 2) }] };
+}
+
+// --- Public entry ------------------------------------------------------------
+
+export async function startMcpServer(sql: Sql): Promise<void> {
+  const server = new McpServer(
+    { name: 'boocoder', version: '2.0.2' },
+    { capabilities: { tools: {} } },
+  );
+
+  // 1. boocoder.create_task
+  server.tool(
+    'boocoder.create_task',
+    'Create a new task in the BooCoder task queue',
+    {
+      project_id: z.string().describe('Project UUID'),
+      input: z.string().describe('Task description / prompt for the agent'),
+      agent: z.string().optional().describe('Agent name (optional — uses default if omitted)'),
+      model: z.string().optional().describe('Model override (optional)'),
+    },
+    async (args) => {
+      const [row] = await sql<TaskRow[]>`
+        INSERT INTO tasks (project_id, input, agent, model, state)
+        VALUES (${args.project_id}, ${args.input}, ${args.agent ?? null}, ${args.model ?? null}, 'pending')
+        RETURNING id, state
+      `;
+      return textResult({ task_id: row!.id, state: row!.state });
+    },
+  );
+
+  // 2. boocoder.list_pending_changes
+  server.tool(
+    'boocoder.list_pending_changes',
+    'List pending changes awaiting review',
+    {
+      session_id: z.string().optional().describe('Optional session filter'),
+    },
+    async (args) => {
+      let rows: PendingRow[];
+      if (args.session_id) {
+        rows = await sql<PendingRow[]>`
+          SELECT id, file_path, operation, diff, session_id
+          FROM pending_changes
+          WHERE status = 'pending' AND session_id = ${args.session_id}
+          ORDER BY created_at ASC
+        `;
+      } else {
+        rows = await sql<PendingRow[]>`
+          SELECT id, file_path, operation, diff, session_id
+          FROM pending_changes
+          WHERE status = 'pending'
+          ORDER BY created_at ASC
+        `;
+      }
+      const items = rows.map((r) => ({
+        id: r.id,
+        file_path: r.file_path,
+        operation: r.operation,
+        diff_preview: r.diff.slice(0, 200),
+      }));
+      return textResult(items);
+    },
+  );
+
+  // 3. boocoder.apply
+  server.tool(
+    'boocoder.apply',
+    'Apply a pending change (write to disk)',
+    {
+      change_id: z.string().describe('Pending change UUID'),
+    },
+    async (args) => {
+      // Resolve projectRoot from the change's session → project path
+      const [proj] = await sql<ProjectPathRow[]>`
+        SELECT p.path FROM pending_changes pc
+        JOIN sessions s ON pc.session_id = s.id
+        JOIN projects p ON s.project_id = p.id
+        WHERE pc.id = ${args.change_id}
+      `;
+      if (!proj) {
+        return textResult({ success: false, file_path: '', error: 'change not found or project path unresolved' });
+      }
+      const result = await applyOne(sql, args.change_id, proj.path);
+      return textResult({ success: result.success, file_path: result.file_path, error: result.error });
+    },
+  );
+
+  // 4. boocoder.reject
+  server.tool(
+    'boocoder.reject',
+    'Reject a pending change (mark as rejected, no disk write)',
+    {
+      change_id: z.string().describe('Pending change UUID'),
+    },
+    async (args) => {
+      await rejectOne(sql, args.change_id);
+      return textResult({ success: true });
+    },
+  );
+
+  // 5. boocoder.dispatch_external_agent
+  server.tool(
+    'boocoder.dispatch_external_agent',
+    'Create a task targeting a specific external agent (ACP or PTY dispatch)',
+    {
+      project_id: z.string().describe('Project UUID'),
+      input: z.string().describe('Task prompt'),
+      agent: z.string().describe('Agent name (must match available_agents registry)'),
+      model: z.string().optional().describe('Model override (optional)'),
+    },
+    async (args) => {
+      const [row] = await sql<TaskRow[]>`
+        INSERT INTO tasks (project_id, input, agent, model, state)
+        VALUES (${args.project_id}, ${args.input}, ${args.agent}, ${args.model ?? null}, 'pending')
+        RETURNING id, state
+      `;
+
+      // Determine execution path from available_agents
+      const [agentRow] = await sql<{ supports_acp: boolean }[]>`
+        SELECT supports_acp FROM available_agents WHERE name = ${args.agent}
+      `;
+      const executionPath = agentRow?.supports_acp ? 'acp' : 'pty';
+
+      return textResult({ task_id: row!.id, state: row!.state, execution_path: executionPath });
+    },
+  );
+
+  // 6. boocoder.list_worktrees
+  server.tool(
+    'boocoder.list_worktrees',
+    'List active worktrees from running tasks',
+    {},
+    async () => {
+      const rows = await sql<WorktreeRow[]>`
+        SELECT id, worktree_path, agent, started_at
+        FROM tasks
+        WHERE worktree_path IS NOT NULL AND state = 'running'
+        ORDER BY started_at DESC
+      `;
+      const items = rows.map((r) => ({
+        task_id: r.id,
+        worktree_path: r.worktree_path,
+        agent: r.agent,
+        started_at: r.started_at,
+      }));
+      return textResult(items);
+    },
+  );
+
+  // Connect via stdio
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  // Block until stdin closes (transport handles lifecycle)
+  await new Promise<void>((resolve) => {
+    process.stdin.on('end', resolve);
+    process.stdin.on('close', resolve);
+  });
+
+  await sql.end({ timeout: 5 });
+}

apps/coder/src/services/pty-dispatch.ts

@@ -0,0 +1,139 @@
+/**
+ * PTY dispatch — runs external agents on the host via SSH.
+ *
+ * For agents without ACP support (claude, pi), we pipe the task into their
+ * non-interactive mode and capture stdout/stderr. The agent runs in a git
+ * worktree so it can modify files freely.
+ *
+ * Supported agents:
+ * - claude: `claude -p --model <model>` (print mode, reads task from stdin)
+ * - opencode: `echo <task> | opencode` (stdin pipe — exact flags TBD)
+ * - goose: stub (not yet supported)
+ * - pi: stub (not yet supported)
+ */
+import type { FastifyBaseLogger } from 'fastify';
+import { sshSpawnWithStdin } from './ssh.js';
+
+export interface DispatchResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+export interface PtyDispatchOpts {
+  agent: string;
+  task: string;
+  worktreePath: string;
+  model?: string;
+  signal?: AbortSignal;
+  log: FastifyBaseLogger;
+}
+
+/**
+ * Build the shell command that runs the agent non-interactively.
+ * The command will be executed inside `cd <worktreePath> && ...`.
+ */
+function buildAgentCommand(agent: string, task: string, model?: string): string | null {
+  // Escape the task for embedding in a shell command
+  const escapedTask = task.replace(/'/g, "'\\''");
+
+  switch (agent) {
+    case 'claude':
+      // Claude Code's print mode: reads prompt from stdin, runs autonomously, prints result
+      return model
+        ? `echo '${escapedTask}' | claude -p --model '${model}'`
+        : `echo '${escapedTask}' | claude -p`;
+
+    case 'opencode':
+      // opencode non-interactive: pipe task via stdin
+      // NOTE: exact flags may vary — opencode may need --non-interactive or --pipe
+      return model
+        ? `echo '${escapedTask}' | opencode --model '${model}'`
+        : `echo '${escapedTask}' | opencode`;
+
+    case 'goose':
+      // Not yet verified for non-interactive use
+      return null;
+
+    case 'pi':
+      // Not yet verified for non-interactive use
+      return null;
+
+    default:
+      return null;
+  }
+}
+
+/**
+ * Dispatch a task to an external agent via SSH.
+ *
+ * The agent runs in the worktree directory on the host. stdout/stderr are
+ * captured in full and returned. The SSH process is killed on abort signal.
+ */
+export async function dispatchViaPty(opts: PtyDispatchOpts): Promise<DispatchResult> {
+  const { agent, task, worktreePath, model, signal, log } = opts;
+
+  const agentCmd = buildAgentCommand(agent, task, model);
+  if (!agentCmd) {
+    return {
+      exitCode: 1,
+      stdout: '',
+      stderr: `Agent '${agent}' is not yet supported for PTY dispatch.`,
+    };
+  }
+
+  // Wrap in cd to the worktree
+  const fullCommand = `cd '${worktreePath.replace(/'/g, "'\\''")}' && ${agentCmd}`;
+
+  log.info({ agent, worktreePath }, 'pty-dispatch: starting');
+
+  return new Promise<DispatchResult>((resolve, reject) => {
+    const child = sshSpawnWithStdin(fullCommand, '');
+    // Note: sshSpawnWithStdin already closes stdin. For agents that read from
+    // stdin via echo piping, the command itself handles the piping on the remote
+    // side. We just need the SSH tunnel.
+
+    // Actually, re-think: sshSpawnWithStdin writes input and closes stdin on the
+    // LOCAL ssh process. But the remote command is `echo '...' | agent`, which
+    // provides its own stdin. So we should use sshSpawn (no local stdin needed)
+    // or just let the empty stdin close — the remote shell handles piping internally.
+    // This is fine as-is because the echo piping happens WITHIN the remote shell command.
+
+    let stdout = '';
+    let stderr = '';
+    let killed = false;
+
+    child.stdout!.on('data', (chunk: Buffer) => { stdout += chunk.toString(); });
+    child.stderr!.on('data', (chunk: Buffer) => { stderr += chunk.toString(); });
+
+    const cleanup = () => {
+      if (!killed) {
+        killed = true;
+        child.kill('SIGTERM');
+        // Give it a moment then force-kill
+        setTimeout(() => child.kill('SIGKILL'), 5_000);
+      }
+    };
+
+    if (signal) {
+      if (signal.aborted) {
+        cleanup();
+        resolve({ exitCode: 130, stdout: '', stderr: 'Aborted before start' });
+        return;
+      }
+      signal.addEventListener('abort', cleanup, { once: true });
+    }
+
+    child.on('close', (code) => {
+      if (signal) signal.removeEventListener('abort', cleanup);
+      log.info({ agent, exitCode: code }, 'pty-dispatch: completed');
+      resolve({ exitCode: code ?? 1, stdout, stderr });
+    });
+
+    child.on('error', (err) => {
+      if (signal) signal.removeEventListener('abort', cleanup);
+      log.error({ agent, err: err.message }, 'pty-dispatch: spawn error');
+      reject(err);
+    });
+  });
+}

apps/coder/src/services/ssh.ts

@@ -0,0 +1,126 @@
+/**
+ * SSH helper — spawns commands on the host via SSH.
+ *
+ * BooCode's container cannot directly spawn host processes (opencode, goose, claude, pi).
+ * They live on the HOST at /usr/local/bin/ or Sam's PATH. We SSH to the host over the
+ * Tailscale IP (same mechanism BooTerm uses: samkintop@100.114.205.53).
+ */
+import { spawn, type ChildProcess } from 'node:child_process';
+
+export const SSH_HOST = process.env.BOOCODER_SSH_HOST ?? '100.114.205.53';
+export const SSH_USER = process.env.BOOCODER_SSH_USER ?? 'samkintop';
+
+/** Common SSH args — strict host checking disabled for container-to-host trust. */
+const SSH_BASE_ARGS = [
+  '-o', 'StrictHostKeyChecking=no',
+  '-o', 'UserKnownHostsFile=/dev/null',
+  '-o', 'LogLevel=ERROR',
+  '-o', 'BatchMode=yes',
+];
+
+export interface SshExecResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * Execute a command on the host via SSH, collecting all output.
+ * Returns when the remote process exits.
+ */
+export async function sshExec(
+  command: string,
+  opts?: { signal?: AbortSignal; timeoutMs?: number },
+): Promise<SshExecResult> {
+  return new Promise<SshExecResult>((resolve, reject) => {
+    const child = spawn('ssh', [
+      ...SSH_BASE_ARGS,
+      `${SSH_USER}@${SSH_HOST}`,
+      command,
+    ], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    let stderr = '';
+    let killed = false;
+
+    child.stdout!.on('data', (chunk: Buffer) => { stdout += chunk.toString(); });
+    child.stderr!.on('data', (chunk: Buffer) => { stderr += chunk.toString(); });
+
+    const cleanup = () => {
+      if (!killed) {
+        killed = true;
+        child.kill('SIGTERM');
+      }
+    };
+
+    // Abort signal
+    if (opts?.signal) {
+      if (opts.signal.aborted) {
+        cleanup();
+        reject(new Error('SSH exec aborted before start'));
+        return;
+      }
+      opts.signal.addEventListener('abort', cleanup, { once: true });
+    }
+
+    // Timeout
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    if (opts?.timeoutMs) {
+      timer = setTimeout(() => {
+        cleanup();
+        reject(new Error(`SSH exec timed out after ${opts.timeoutMs}ms`));
+      }, opts.timeoutMs);
+    }
+
+    child.on('close', (code) => {
+      if (timer) clearTimeout(timer);
+      if (opts?.signal) opts.signal.removeEventListener('abort', cleanup);
+      resolve({ exitCode: code ?? 1, stdout, stderr });
+    });
+
+    child.on('error', (err) => {
+      if (timer) clearTimeout(timer);
+      if (opts?.signal) opts.signal.removeEventListener('abort', cleanup);
+      reject(err);
+    });
+
+    // Close stdin immediately — we're not sending input via sshExec
+    child.stdin!.end();
+  });
+}
+
+/**
+ * Spawn an SSH child process with a command on the host.
+ * Returns the raw ChildProcess for callers that need streaming I/O (ACP, PTY).
+ */
+export function sshSpawn(command: string): ChildProcess {
+  return spawn('ssh', [
+    ...SSH_BASE_ARGS,
+    `${SSH_USER}@${SSH_HOST}`,
+    command,
+  ], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+}
+
+/**
+ * Spawn an SSH child process that pipes stdin through.
+ * Used for agents that read a task from stdin (e.g. `echo "task" | claude -p`).
+ */
+export function sshSpawnWithStdin(command: string, input: string): ChildProcess {
+  const child = spawn('ssh', [
+    ...SSH_BASE_ARGS,
+    `${SSH_USER}@${SSH_HOST}`,
+    command,
+  ], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  // Write the input and close stdin
+  child.stdin!.write(input);
+  child.stdin!.end();
+
+  return child;
+}

apps/coder/src/services/tools/check_task_status.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import type { ToolDef, ToolContext } from './types.js';
+
+const CheckTaskStatusInput = z.object({
+  task_id: z.string().uuid().describe('ID of the task to check'),
+});
+
+type CheckTaskStatusInputT = z.infer<typeof CheckTaskStatusInput>;
+
+export const checkTaskStatusTool: ToolDef<CheckTaskStatusInputT> = {
+  name: 'check_task_status',
+  description: 'Check the status and output of a subtask by ID. Returns state, output_summary, and timing.',
+  inputSchema: CheckTaskStatusInput,
+  jsonSchema: {
+    type: 'function',
+    function: {
+      name: 'check_task_status',
+      description: 'Check the status and output of a subtask by ID.',
+      parameters: {
+        type: 'object',
+        properties: {
+          task_id: { type: 'string', description: 'ID of the task to check' },
+        },
+        required: ['task_id'],
+      },
+    },
+  },
+
+  async execute(input: CheckTaskStatusInputT, _projectRoot: string, context: ToolContext): Promise<unknown> {
+    const { sql } = context;
+
+    const [task] = await sql<{ id: string; state: string; output_summary: string | null; started_at: string | null; ended_at: string | null }[]>`
+      SELECT id, state, output_summary, started_at, ended_at
+      FROM tasks
+      WHERE id = ${input.task_id}
+    `;
+
+    if (!task) {
+      return { error: `Task ${input.task_id} not found` };
+    }
+
+    return {
+      id: task.id,
+      state: task.state,
+      output_summary: task.output_summary,
+      started_at: task.started_at,
+      ended_at: task.ended_at,
+    };
+  },
+};

apps/coder/src/services/tools/index.ts

@@ -4,6 +4,9 @@ import { createFileTool } from './create_file.js';
 import { deleteFileTool } from './delete_file.js';
 import { applyPendingTool } from './apply_pending.js';
 import { rewindTool } from './rewind.js';
+import { newTaskTool } from './new_task.js';
+import { listTasksTool } from './list_tasks.js';
+import { checkTaskStatusTool } from './check_task_status.js';
 
 export type { ToolDef, ToolContext, ToolJsonSchema } from './types.js';
 
@@ -16,6 +19,11 @@ export const WRITE_TOOLS: readonly ToolDef<any>[] = [
   deleteFileTool,
   editFileTool,
   rewindTool,
+  // Boomerang subtask tools — orchestrator agents call these to spawn/monitor child tasks.
+  // An "Orchestrator" agent profile would whitelist [new_task, list_tasks, check_task_status].
+  newTaskTool,
+  listTasksTool,
+  checkTaskStatusTool,
 ];
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -23,4 +31,4 @@ export const WRITE_TOOLS_BY_NAME: ReadonlyMap<string, ToolDef<any>> = new Map(
   WRITE_TOOLS.map((t) => [t.name, t]),
 );
 
-export { editFileTool, createFileTool, deleteFileTool, applyPendingTool, rewindTool };
+export { editFileTool, createFileTool, deleteFileTool, applyPendingTool, rewindTool, newTaskTool, listTasksTool, checkTaskStatusTool };

apps/coder/src/services/tools/list_tasks.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import type { ToolDef, ToolContext } from './types.js';
+import { getInferenceContext } from './inference_context.js';
+
+const ListTasksInput = z.object({
+  parent_task_id: z.string().uuid().optional().describe('Filter by parent task ID. Omit to list children of current task.'),
+});
+
+type ListTasksInputT = z.infer<typeof ListTasksInput>;
+
+export const listTasksTool: ToolDef<ListTasksInputT> = {
+  name: 'list_tasks',
+  description: 'List child tasks of the current task (or a specified parent). Returns id, state, input preview, and output_summary.',
+  inputSchema: ListTasksInput,
+  jsonSchema: {
+    type: 'function',
+    function: {
+      name: 'list_tasks',
+      description: 'List child tasks of the current task (or a specified parent).',
+      parameters: {
+        type: 'object',
+        properties: {
+          parent_task_id: { type: 'string', description: 'Filter by parent task ID. Omit to list children of current task.' },
+        },
+        required: [],
+      },
+    },
+  },
+
+  async execute(input: ListTasksInputT, _projectRoot: string, context: ToolContext): Promise<unknown> {
+    const { sql } = context;
+    const ctx = getInferenceContext();
+    const parentId = input.parent_task_id ?? ctx.taskId;
+
+    if (!parentId) {
+      return { tasks: [], note: 'No parent task context — not running inside a task.' };
+    }
+
+    const rows = await sql<{ id: string; state: string; input: string; output_summary: string | null }[]>`
+      SELECT id, state, input, output_summary
+      FROM tasks
+      WHERE parent_task_id = ${parentId}
+      ORDER BY created_at DESC
+      LIMIT 50
+    `;
+
+    return {
+      tasks: rows.map((r) => ({
+        id: r.id,
+        state: r.state,
+        input_preview: r.input.slice(0, 100),
+        output_summary: r.output_summary,
+      })),
+    };
+  },
+};

apps/coder/src/services/tools/new_task.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import type { ToolDef, ToolContext } from './types.js';
+import { getInferenceContext } from './inference_context.js';
+
+const NewTaskInput = z.object({
+  input: z.string().min(1).describe('Task description for the child subtask'),
+  agent: z.string().optional().describe('Optional: dispatch to a specific agent'),
+  model: z.string().optional().describe('Optional: model override for the subtask'),
+});
+
+type NewTaskInputT = z.infer<typeof NewTaskInput>;
+
+export const newTaskTool: ToolDef<NewTaskInputT> = {
+  name: 'new_task',
+  description:
+    'Spawn a subtask that runs in isolation. The subtask gets its own session and ' +
+    'worktree. Use check_task_status to monitor progress. Only the output_summary is ' +
+    'accessible to the parent — full isolation (Boomerang pattern).',
+  inputSchema: NewTaskInput,
+  jsonSchema: {
+    type: 'function',
+    function: {
+      name: 'new_task',
+      description:
+        'Spawn a subtask that runs in isolation. The subtask gets its own session and ' +
+        'worktree. Use check_task_status to monitor progress.',
+      parameters: {
+        type: 'object',
+        properties: {
+          input: { type: 'string', description: 'Task description for the child subtask' },
+          agent: { type: 'string', description: 'Optional: dispatch to a specific agent' },
+          model: { type: 'string', description: 'Optional: model override for the subtask' },
+        },
+        required: ['input'],
+      },
+    },
+  },
+
+  async execute(input: NewTaskInputT, _projectRoot: string, context: ToolContext): Promise<unknown> {
+    const { sql } = context;
+    // Get the current task's project_id from the inference context
+    const ctx = getInferenceContext();
+    const currentTaskId = ctx.taskId;
+
+    // Look up the project_id from the current session
+    const [session] = await sql<{ project_id: string }[]>`
+      SELECT project_id FROM sessions WHERE id = ${ctx.sessionId}
+    `;
+    if (!session) {
+      return { error: 'Cannot determine project_id from current session' };
+    }
+
+    const [task] = await sql<{ id: string; state: string }[]>`
+      INSERT INTO tasks (project_id, parent_task_id, input, agent, model)
+      VALUES (${session.project_id}, ${currentTaskId}, ${input.input}, ${input.agent ?? null}, ${input.model ?? null})
+      RETURNING id, state
+    `;
+
+    return {
+      message: `Subtask created (id: ${task!.id}). It will run in isolation. Use check_task_status to monitor.`,
+      task_id: task!.id,
+      state: task!.state,
+    };
+  },
+};

apps/coder/src/services/worktrees.ts

@@ -0,0 +1,118 @@
+/**
+ * Git worktree management for external agent dispatch.
+ *
+ * Each dispatched task gets its own git worktree so the external agent
+ * can modify files freely without touching the main working tree.
+ * After the agent completes, we diff the worktree against HEAD and
+ * queue the diff into pending_changes.
+ */
+import { sshExec } from './ssh.js';
+
+const WORKTREE_BASE = '/tmp/booworktrees';
+
+/**
+ * Create a git worktree for a task on the host.
+ * Returns the absolute path to the worktree directory.
+ */
+export async function createWorktree(
+  projectPath: string,
+  taskId: string,
+  opts?: { signal?: AbortSignal },
+): Promise<string> {
+  const worktreePath = `${WORKTREE_BASE}/${taskId}`;
+  const branchName = `task-${taskId}`;
+
+  // Ensure the base directory exists
+  await sshExec(`mkdir -p ${WORKTREE_BASE}`, { signal: opts?.signal });
+
+  // Create the worktree with a new branch from HEAD
+  const result = await sshExec(
+    `git -C ${shellEscape(projectPath)} worktree add ${shellEscape(worktreePath)} -b ${shellEscape(branchName)} HEAD`,
+    { signal: opts?.signal, timeoutMs: 30_000 },
+  );
+
+  if (result.exitCode !== 0) {
+    throw new Error(`Failed to create worktree: ${result.stderr.trim() || result.stdout.trim()}`);
+  }
+
+  return worktreePath;
+}
+
+/**
+ * Get the unified diff of changes made in the worktree vs the parent branch (HEAD).
+ * Returns an empty string if there are no changes.
+ */
+export async function diffWorktree(
+  worktreePath: string,
+  projectPath: string,
+  opts?: { signal?: AbortSignal },
+): Promise<string> {
+  // First, commit any uncommitted changes in the worktree so we can diff branches
+  // Stage all changes
+  const addResult = await sshExec(
+    `cd ${shellEscape(worktreePath)} && git add -A`,
+    { signal: opts?.signal, timeoutMs: 30_000 },
+  );
+  if (addResult.exitCode !== 0) {
+    throw new Error(`Failed to stage worktree changes: ${addResult.stderr.trim()}`);
+  }
+
+  // Check if there are staged changes
+  const statusResult = await sshExec(
+    `cd ${shellEscape(worktreePath)} && git diff --cached --quiet`,
+    { signal: opts?.signal, timeoutMs: 10_000 },
+  );
+
+  if (statusResult.exitCode === 0) {
+    // No changes
+    return '';
+  }
+
+  // Commit staged changes (needed to produce a clean branch diff)
+  await sshExec(
+    `cd ${shellEscape(worktreePath)} && git -c user.email=boocoder@local -c user.name=BooCoder commit -m "task changes" --allow-empty`,
+    { signal: opts?.signal, timeoutMs: 15_000 },
+  );
+
+  // Diff the worktree branch against the parent commit (HEAD of main tree)
+  const diffResult = await sshExec(
+    `git -C ${shellEscape(projectPath)} diff HEAD...$(git -C ${shellEscape(worktreePath)} rev-parse HEAD)`,
+    { signal: opts?.signal, timeoutMs: 60_000 },
+  );
+
+  if (diffResult.exitCode !== 0) {
+    throw new Error(`Failed to diff worktree: ${diffResult.stderr.trim()}`);
+  }
+
+  return diffResult.stdout;
+}
+
+/**
+ * Remove a worktree and its associated branch.
+ * Best-effort — does not throw on failure (task may have already been cleaned up).
+ */
+export async function cleanupWorktree(
+  projectPath: string,
+  taskId: string,
+): Promise<void> {
+  const worktreePath = `${WORKTREE_BASE}/${taskId}`;
+  const branchName = `task-${taskId}`;
+
+  // Remove the worktree (--force handles dirty state)
+  await sshExec(
+    `git -C ${shellEscape(projectPath)} worktree remove ${shellEscape(worktreePath)} --force`,
+    { timeoutMs: 15_000 },
+  ).catch(() => {});
+
+  // Delete the task branch
+  await sshExec(
+    `git -C ${shellEscape(projectPath)} branch -D ${shellEscape(branchName)}`,
+    { timeoutMs: 10_000 },
+  ).catch(() => {});
+}
+
+/** Minimal shell escape for paths (single-quote wrapping). */
+function shellEscape(s: string): string {
+  // Replace single quotes with escaped version, wrap in single quotes
+  return "'" + s.replace(/'/g, "'\\''") + "'";
+}

pnpm-lock.yaml

@@ -48,6 +48,9 @@ importers:
 
   apps/coder:
     dependencies:
+      '@agentclientprotocol/sdk':
+        specifier: ^0.22.1
+        version: 0.22.1(zod@3.25.76)
       '@boocode/server':
         specifier: workspace:*
         version: link:../server
@@ -57,12 +60,18 @@ importers:
       '@fastify/websocket':
         specifier: ^10.0.1
         version: 10.0.1
+      '@modelcontextprotocol/sdk':
+        specifier: ^1.29.0
+        version: 1.29.0(zod@3.25.76)
       fastify:
         specifier: ^4.28.1
         version: 4.29.1
       postgres:
         specifier: ^3.4.4
         version: 3.4.9
+      ws:
+        specifier: ^8.18.0
+        version: 8.20.1
       zod:
         specifier: ^3.23.8
         version: 3.25.76
@@ -70,6 +79,9 @@ importers:
       '@types/node':
         specifier: ^20.14.10
         version: 20.19.41
+      '@types/ws':
+        specifier: ^8.5.10
+        version: 8.18.1
       tsx:
         specifier: ^4.16.2
         version: 4.22.0
@@ -268,6 +280,11 @@ importers:
 
 packages:
 
+  '@agentclientprotocol/sdk@0.22.1':
+    resolution: {integrity: sha512-DfqXtl/8gO9NImq094MTaCXEU2vkhh6v7q/kT+9UjZxUqj8hYaya2OjLVIqn16MzNHcXEpShTR2RIauLSYeDQQ==}
+    peerDependencies:
+      zod: ^3.25.0 || ^4.0.0
+
   '@ai-sdk/gateway@3.0.119':
     resolution: {integrity: sha512-VAhfRWC+JexZakkVfmjaJKaTj00x7/UHdE8kMWL3NhuQAlf8oXtg9r4dfvFZrByXxchGRBvYE3biEUyibkg0xg==}
     engines: {node: '>=18'}
@@ -4097,6 +4114,10 @@ packages:
 
 snapshots:
 
+  '@agentclientprotocol/sdk@0.22.1(zod@3.25.76)':
+    dependencies:
+      zod: 3.25.76
+
   '@ai-sdk/gateway@3.0.119(zod@3.25.76)':
     dependencies:
       '@ai-sdk/provider': 3.0.10