refactor: codebase audit cleanup — dead code, dedup, module splits

Multi-agent audit + aggressive cleanup across server/web/coder/booterm,
delivered behind a DEFER discipline so none of the in-flight files were
touched. Removes dead code/deps/columns, dedups server + coder helpers,
and splits the oversized modules (tools.ts, opencode-server.ts,
sentinel-summaries, turn.ts, TerminalPane.tsx) behind stable contracts.
Adds 78 parity/unit tests (server 587, coder 323); fixes two latent bugs
(ChatPane queue keys, FileViewerOverlay blank-line parity).

Intended tag: v2.7.12-audit-cleanup.

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

.env.example

@@ -11,6 +11,10 @@ POSTGRES_PASSWORD=CHANGE_ME
 # point BooCode at a different SearXNG instance.
 SEARXNG_URL=http://100.114.205.53:8888
 
+# Context7 MCP key. Referenced from data/mcp.json as "{env:CONTEXT7_API_KEY}"
+# ({env:VAR} substitution, opencode-compatible). Leave unset to send no key.
+# CONTEXT7_API_KEY=ctx7sk-...
+
 # Task model: lightweight model for auto-naming, search rewrite, etc.
 # Direct llama-server instance (NOT llama-swap). Falls back to LLAMA_SWAP_URL
 # with FAST_MODEL when unset.

.gitignore

@@ -15,6 +15,6 @@ secrets/
 data/*
 !data/AGENTS.md
 !data/skills/
-!data/mcp.json
+!data/mcp.example.json
 !data/coder-providers.example.json
 codecontext/fork.tar.gz

CHANGELOG.md

@@ -2,6 +2,70 @@
 
 All notable changes per release tag. Most recent on top, ordered by tag creation date (which matches the git history). Tag names follow `vMAJOR.MINOR.PATCH-slug` — the slug describes what shipped, so the tag name alone is enough to recall the batch.
 
+## v2.7.12-audit-cleanup — 2026-06-02
+
+A repo-wide audit and aggressive cleanup pass, run as a multi-agent orchestration (five read-only Opus auditors over server/web/coder/booterm + cross-cutting deps/build/parity + a structural-architecture lens) followed by phased, behavior-preserving implementation — every change gated on the per-app test suites and delivered behind a strict DEFER discipline that never touched the files in flight for `v2.7.9`–`v2.7.11` (`mcp-config`, the `ws-frames` pair, `dispatcher`, `claude-sdk-map`, `AgentComposerBar`/`CoderMessageList`/`CoderPane`), so the branch rebased onto current main with zero conflicts. **Dead code/deps/schema**: removed ~9 dead files and a swathe of dead exports/write-only state across all four apps, dropped dead deps (`next-themes`, `@xterm/addon-webgl`, booterm `tslib`; `shadcn`→devDep), and idempotently dropped dead schema columns/tables (`sessions.tags`, `tasks.worktree_path`/`feature_values`, `available_agents.supports_mcp_client`, the superseded `session_worktrees` table, the always-empty `list_worktrees` MCP tool) — chat/session/message DATA untouched, only never-read columns. **Server dedup + reshapes**: collapsed the dead `budget.ts` tier system (surfacing a latent `READ_ONLY_TOOL_NAMES` drift, then deleted), extracted shared `MESSAGE_COLUMNS`/`selectProject`/`stripQuotes`/`SENTINEL_KINDS`/`samplerOptsFromAgent`/`createContentFlusher`/`insertSentinel`/a `makeCodecontextTool` factory/a pending-tool-call resolver, split `tools.ts` (799→46 barrel + `tools/{types,fs-tools,misc-tools,registry,tiers}`, register-through registry preserved so coder's import contract stays byte-stable), and decomposed the inference pipeline (`sentinel-summaries`→`runWrapUpSummary`, `turn.ts`→`turn-config`+`step-decision`, a pure `stream-phase-adapter`, shared finalize atoms — stopping short of fusing synthesis to preserve frame timing). **Coder reshapes**: split the 1062-line `opencode-server.ts` god-class into supervisor / sse-loop / pure event-map / port-utils + extracted `buildAcpClient`/`makeFrameEmitter`/`worktree-risk`, plus happy-path-safe concurrency hardening (reconnect backoff, double-spawn guard; a defensive busy-assert + ensureSession coalescing flagged for review). **Web**: `React.memo` on `MessageBubble`/`MarkdownRenderer` + module-hoisted markdown components (the streaming re-parse was the biggest perf cost), shared `linkifyPaths`/artifact/tab dedup, two latent bug fixes (`ChatPane` index-keys → stable ids; `FileViewerOverlay` blank-line line-number desync), and decomposed the 1298-line `TerminalPane.tsx` into fit/socket/selection hooks + presentational pieces (verbatim move, all ~30 listeners/timers inventoried; the label-dep fix stops a live terminal tearing down on pane renumber). +78 parity/unit tests (server 597, coder 328 green; `apps/web` has no harness, so its changes are typecheck + manual/device QA). Net ≈ −4,600 LOC. Deferred (designed; blueprints in the audit reports): the `tasks` dual-CREATE / `project_id` FK (a cross-service deploy-ordering decision, not a data migration), web structural decomposition of `useWorkspacePanes`/`MessageBubble` (needs a web test harness first), a `@boocode/contracts` shared package, and the `dispatcher.ts` split — the last two now unblocked since their in-flight files shipped in `v2.7.9`–`v2.7.11`. Rebased clean onto `v2.7.11-coder-model-snapshot`.
+
+## v2.7.11-coder-model-snapshot — 2026-06-02
+
+Hotfix for the coder model-attribution chip vanishing on refresh. The chip showed during a live turn (the `message_complete` frame carries `model`) but disappeared when a BooCoder session was reloaded — only in the coder, not BooChat. Root cause: `CoderPane`'s `useCoderMessages` hydrates from two sources on load — the HTTP `listMessages` fetch (whose SELECT includes `model`, added `v2.7.8`) AND the WS `snapshot` frame — and the WS snapshot's query in `apps/coder/src/routes/ws.ts` had its own column list that omitted `model`. The client's `snapshot` handler `setMessages`-overwrites the HTTP load, so the model-less rows won, and with no later `message_complete` for historical messages the chip stayed gone. Fix is one column: add `model` to the WS snapshot SELECT so both hydration paths agree. The `apps/coder/CLAUDE.md` "update every mapper" note now lists the WS snapshot SELECT explicitly (it was the one place not enumerated). apps/server + apps/coder builds green; deployed via `systemctl restart boocoder` (host service — the earlier `v2.7.10` docker deploy rebuilt only the container, never this route). Fixes the chip shipped in `v2.7.8-ember-coder-tabs-model-chips` / completed in `v2.7.9-mcp-keys-docs-coder-fixes`.
+
+## v2.7.10-composer-chips — 2026-06-02
+
+A composer control-row refresh shared by BooChat and BooCoder via `ChatInput`. The slash-commands menu moves out of the full-width `AgentCommandsHint` disclosure (now removed) into a compact chip in the message box's bottom controls row — clicking it opens the existing `SlashCommandPicker` anchored to the chip and selecting inserts `/<name> `, while the typed-`/` autocomplete is unchanged. A new attach-file button sits beside it, opening a native multi-file picker that funnels picks through the same drag-drop pipeline (5 MB / binary gate, 10-attachment cap, chips + preview, `source:'drop'`). On mobile both collapse to icon-only — the slash count is `max-md:hidden` and the paperclip is icon-only — so the row stays on one line per the no-scroll toolbar rule. Web tsc + build green; deployed (docker). Builds on the BooCode 2.0 composer work in `v2.7.8-ember-coder-tabs-model-chips`.
+
+## v2.7.9-mcp-keys-docs-coder-fixes — 2026-06-02
+
+The MCP-key hygiene feature plus accumulated in-flight coder fixes and a docs refactor. **MCP `{env:VAR}` substitution** (`mcp-config.ts:substituteEnvVars`, opencode-compatible) recursively resolves `{env:NAME}` references in any string value of `data/mcp.json` from `process.env` *before* Zod validation, so real keys live in `.env` (`env_file`) instead of the gitignored config — an unset var resolves to `''` with a boot-log warning, and on a validation failure the loader names the unset vars alongside the field errors (an empty `{env:VAR}` in a strict url/command field invalidates the whole config, an otherwise-disconnected warning). `data/mcp.json` is now untracked (`.gitignore` flips `!data/mcp.json` → `!data/mcp.example.json`); the tracked template `data/mcp.example.json` carries `"CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"` and `.env.example` documents the key (9 mcp-config tests). **Two coder bug fixes** ride along: the `message_complete` frame's `model` is widened `string` → `string | null` in both ws-frames copies (server + web parity) and the dispatcher now publishes `model: task.model` at all four external assistant-completion points — without the nullable widen a null model would fail-closed in `publishFrame` and drop the entire frame including the `status:'complete'` transition (regression test added); and Claude-SDK `mapUserToolResults` now maps `user`-message `tool_result` blocks → terminal `tool_update` events (completed/failed with output) so external-agent tool snapshots resolve instead of spinning forever (the SDK feeds tool output back as a user message, previously unmapped). On the view side the `AgentComposerBar` drops the §9b resumed/history/new-session chip and token-usage readout and loses `flex-wrap` so the control row stays on one line, while `CoderPane` gains a per-chat `localStorage` agent-config cache (provider/model/mode/thinking keyed by chat id, restoring the last model on reopen) and threads the new `model` field into the timeline + attribution chip. **Docs refactor**: the root `CLAUDE.md` is slimmed (~190 lines) with per-app deep references split into `apps/{coder,server,web}/CLAUDE.md` (auto-loaded in-subtree), plus a new 372-line `docs/coder-backends.md` dispatch reference, a `docs/project-discovery.md` stack inventory, and a `docs/coding-standards/` set (the `cross-app-contract-parity` standard, fronted by `.claude/rules` path-scoped indexes) — `ARCHITECTURE.md` links the backends doc. Server 555 + coder 299 tests passing (incl. new mcp-config, ws-frames, and claude-sdk-map suites), web tsc + server + coder builds green. Builds on `v2.7.8-ember-coder-tabs-model-chips`.
+
+## v2.7.8-ember-coder-tabs-model-chips — 2026-06-01
+
+The BooCode 2.0 visual identity plus two workflow features. **Ember theme** (`styles/themes/ember.css`, now `DEFAULT_THEME_ID`) is the signature orange-on-near-black look — rebuilt on Obsidian's flat charcoal structure (`#0c0c0e`/`#15151a`/`#1f1f23`) with `#ff7a18` swapped in for the purple, after a Reinvented-direction detour (neon borders + a scanline/glow texture overlay) was dialed back to taste; the server `theme_id` whitelist gains `ember` so it can actually be selected. The **brand banner** (`ProjectSidebar`) shows the eye-patch Westie mascot + the `>_BooCode` wordmark big and edge-to-edge on transparent backgrounds — the source PNGs shipped with baked-white canvases, so they were flood-filled to transparency from the corners (preserving the white dog, which a naive white-key would have destroyed) and cropped to bounds. **Coder panes are now multi-tab**: `+` opens a new BooCode tab (a fresh chat = a new agent context sharing the session worktree) while the split button still opens a pane — coder panes reuse the shared `ChatTabBar` via a kind-aware `tabKind`, backed by a new `createCoderTab` action with `closeOtherTabs`/tab-numbering extended to coder kind. **Model-attribution chips**: a new `messages.model` column (both apps share the table) stamped at `finalizeCompletion` (BooChat + native coder) and at the dispatcher's assistant-row creation (external coder), surfaced through the `messages_with_parts` view + wire types + the live `message_complete` frame (the Zod already allowed `model`; nothing consumed it), and rendered as a subtle accent chip with a shortened label (`shortenModelName` → `Sonnet 4.6`, `Qwen3.6 35B`) beside the message stats — so swapping models mid-coder-session stays legible. Also the composer moved its Web toggle into a boxed, focus-ringed input, tool rows lead with a glowing accent dot, and the Claude-SDK-backend follow-ups validated live this session (1M context window, follow-up-message fix, collapsed thinking/tool chips) land with `CLAUDE_SDK_BACKEND=1` flipped on. One snag fixed mid-deploy: the view's new `m.model` was first inserted mid-list and `CREATE OR REPLACE VIEW` can't reorder columns (42P16) — appended at the end. Web tsc + server + coder builds green; deployed (docker + boocoder, tools:34). Builds on `v2.7.7-pane-header-actions`.
+
+## v2.7.7-pane-header-actions — 2026-06-01
+
+In-flight workspace UX work, committed alongside the v2.7 review batches. Extracts a shared `PaneHeaderActions` cluster (the +/Split/Reopen-closed-pane/Session-history/Close controls) used across the `ChatTabBar` and the desktop coder + terminal pane headers in `Workspace`, replacing the divergent per-header copies, with `SessionLandingPage` history enhancements and `useWorkspacePanes` tweaks. Also fixes a coder-side correctness bug: `resolveChatId` (`apps/coder/src/routes/chat-resolve.ts`) still read `sessions.workspace_panes` as a bare `WorkspacePane[]`, but `v2.6.5-panes-tabs-composer` widened it to a `WorkspaceState` envelope — so it mis-read the panes and, worse, clobbered `tabNumbers`/`nextTabNumber`/`closedPaneStack` back to a bare array on every pane-chat write; a new `normalizeWorkspaceState` accepts either shape and preserves the envelope (with a regression test). Plus a CLAUDE.md doc-sync (apps/coder vitest suite, deploy-by-surface, dual-remote push, in-flight-web-WIP staging, release-branch naming). Web tsc + coder build + coder tests green. Builds on `v2.7.6-agent-status-normalize`.
+
+## v2.7.6-agent-status-normalize — 2026-06-01
+
+The scoped half of `boocode_code_review_v2.md` §1 #10 — normalized external-agent status, surfaced from BooCoder's own dispatch observation (the heavier config-injection notify-hook, clean-room from superset's ELv2 `agent-setup`, is documented as the follow-on). The review's premise ("PTY agents have no status") had partly aged out — warm-ACP/opencode/SDK already carry working/done — so the real gap was that BooCoder never *published* a normalized per-`(chat,agent)` status (blocked-on-permission was invisible; crash/idle weren't pushed). Adds an `agent_status_updated` WS frame (`working|blocked|idle|error`, server+web parity) published from the dispatcher's turn boundaries across all four external paths (warm-acp/opencode/sdk/pty — `working` at start, `idle`/`error` at end) and the permission flow (`blocked` on request, `working` on resolve), best-effort so it never breaks a turn. A clean-room `normalizeAgentEvent` helper (superset's ~30-vendor-event → Start/blocked/Stop collapse, reimplemented with the event names as facts) ships now with 25 tests so the deferred notify-hook injection reuses it verbatim. The `AgentComposerBar` gains a normalized status dot (working=spinner, blocked=amber, idle=gray, error=red) distinct from the WS-liveness dot, fed by a `useAgentStatus` map `CoderPane` tracks per `(chat,agent)`. Built by two parallel agents (data plane + view plane) against a pinned frame contract; server 545 + coder 294 tests passing (25 new), web tsc + builds clean, ws-frames parity green. Clears the actionable review backlog (#1/#3/#4/#6–#12). Builds on `v2.7.5-claude-sdk-sessionstore`; openspec `agent-status-normalize`.
+
+## v2.7.5-claude-sdk-sessionstore — 2026-06-01
+
+Lands the Claude Agent SDK direction (`boocode_code_review_v2.md` §1 #9, §6.2 "lean SDK") behind a flag. Adds `@anthropic-ai/claude-agent-sdk@0.3.159` (Commercial Terms — runtime dep, code reference-only) and builds a warm, resumable claude backend to supersede one-shot PTY dispatch — env-gated (`CLAUDE_SDK_BACKEND`, default off) so production claude stays on the unchanged PTY path until a host smoke. **Clean-room `PostgresSessionStore`** implements the SDK's real `SessionStore` type (`append`/`load`/`listSessions`/`delete`/`listSubkeys`) over a new `claude_session_entries` table — typechecked against the installed SDK type, 8 DB-integration tests. **`ClaudeSdkBackend`** (`implements AgentBackend`, mirroring warm-acp/opencode-server) drives one persistent `query()` per `(chat,'claude')` in streaming-input mode via a pushable async-iterable pump, with `sessionStore` + `resume` for cross-turn/cross-restart continuity, a pure `mapSdkMessage`→`AgentEvent` mapper, `session_id` captured from the `init` message, and `result.usage`/`total_cost_usd` accumulated onto `agent_sessions` (backend CHECK gains `'claude_sdk'`). Built against the REAL SDK 0.3.159 types after installing it — surfacing shapes a blind build would have missed (`SDKPartialAssistantMessage` is `type:'stream_event'` needing `includePartialMessages`; `SDKUserMessage.message` is `MessageParam`; the `SDKResultMessage` error arm). Also fixes a latent test-infra deadlock — three DB-integration suites applying the full schema in parallel under `DATABASE_URL` deadlocked, now serialized via `fileParallelism:false`. ~32 new tests (8 store + 10 mapper + 8 pushable + 6 routing); coder suite 269 passing default / 290 with DB; tsc clean against the SDK types; builds clean. **The live streaming pump + resume + an actual claude turn need a host smoke (`CLAUDE_SDK_BACKEND=1` + claude binary + ANTHROPIC auth) — cannot run from the dev container.** The zod peer-dep wants `^4` (workspace `3.25`) — watch at runtime. Builds on `v2.7.4-mistake-tracker-ledger`; openspec `claude-sdk-sessionstore`.
+
+## v2.7.4-mistake-tracker-ledger — 2026-06-01
+
+Two native-inference hardening features from `boocode_code_review_v2.md` §1 #12 (cline, algorithm-reimplemented). **MistakeTracker:** complements the doom-loop guard (identical repeats) and cap-hit (budget) by catching a run of consecutive tool *failures*. A new pure `mistake-tracker.ts` tracks heterogeneous failure kinds (`zod_reject`/`tool_not_found`/`exec_error`/`api_error`/`permission_denied`, surfaced per tool from `tool-phase.ts`); after 3 consecutive failures the `turn.ts` loop does a **soft nudge** — injects model-facing recovery guidance into the next step + drops a `mistake_recovery` UI sentinel + resets — then **escalates** to stopping the turn (cap-hit-style, with a Continue affordance) if it re-trips without an intervening success, so heterogeneous failures can't burn the whole step budget. **File-provenance ledger:** `compaction.ts` now derives a deterministic, sorted `## Files Read` list from the head messages' read-tool calls (`view_file`/`grep`/`find_files`/`list_dir`) and injects it into the rolling-summary prompt so file provenance survives compaction (no new table; prompt-driven merge, read-only since BooChat has no write tools). The `mistake_recovery` sentinel adds an arm to `MessageMetadata` in both server + web type copies plus a `MessageBubble` render branch. Built by two parallel agents (backend + frontend sentinel) over disjoint apps; server 545 tests passing (23 new: 12 mistake-tracker + 11 compaction), build + web tsc clean. Native-inference only (external agents run their own loops). Builds on `v2.7.3-sampling-streamjson-tokens`; openspec `mistake-tracker-file-ledger`.
+
+## v2.7.3-sampling-streamjson-tokens — 2026-06-01
+
+Three small BooCode wins from `boocode_code_review_v2.md` §1 #11/#7/#8. **Sampling knobs:** per-agent `top_n_sigma` + the `dry_*` repetition family (`dry_multiplier`/`dry_base`/`dry_allowed_length`/`dry_penalty_last_n`) are now first-class Agent frontmatter fields, parsed in `agents.ts` and threaded into the llama-swap chat-completion body via `providerOptions.openaiCompatible` (the `@ai-sdk/openai-compatible` extra-body channel). This surfaced and fixed a **latent bug**: `top_k` (rejected by the AI-SDK provider as unsupported) and `min_p` (never passed to `streamText` at all) had been dead on the wire — no agent's `top_k`/`min_p` ever affected sampling; both now route through the same channel, so agents that set them will start using them. `--reasoning-budget` is documented in `data/AGENTS.md` (already works via `llama_extra_args`, permitted by the deny-list validator). **Live PTY stream-json:** qwen/claude PTY dispatch sliced stdout opaque; a new `stream-json-parser.ts` line-buffers the Claude-Code-compatible NDJSON and emits text/reasoning/tool frames live as they arrive (mirroring the ACP/opencode paths) + persists the structured parts, with a clean fallback to the old opaque slice when output isn't NDJSON (claude now runs `--output-format stream-json --verbose`). **Token UI:** the per-`(chat,agent)` `agent_sessions.input_tokens`/`output_tokens`/`cost` columns (accumulated since `v2.6.8` but dropped by the read route + wire type) now flow through and render condensed beside the AgentComposerBar session chip. Built by three parallel agents over disjoint subsystems; server 523 + coder 245 tests passing (incl. 11 new stream-json-parser + new agent-parse tests), all builds + web tsc clean. Builds on `v2.7.2-checkpoint-idor`; openspec `sampling-streamjson-tokens`. The qwen-vs-claude `usage` field names in #7 are best-guess pending a live smoke.
+
+## v2.7.2-checkpoint-idor — 2026-06-01
+
+Closes two IDOR authorization holes in the `v2.7.1-write-edit-robustness` checkpoint routes, flagged by the automated push security review. The `GET /api/sessions/:id/checkpoints?chat_id=` list route scoped its `chat_id` branch by `chat_id` alone — any session's `chat_id` would read its checkpoints; it now joins through `chats` and gates on `chats.session_id` (authoritative; `checkpoints.session_id` is a nullable denormalized hint). The `restoreCheckpoint` scope guard was fail-open — `cp.session_id && cp.session_id !== sessionId` fell through whenever the checkpoint's denormalized `session_id` was null, allowing a cross-session restore (worktree reset + transcript trim) — it now resolves the owning session via the checkpoint's chat and denies on any missing-or-mismatched row. A DB-integration regression covers the exact null-`session_id` cross-session case. Real-world blast radius is small (BooCoder is single-user behind Authelia on loopback), but both are genuine authorization bugs. Coder suite 234 passing (7/7 checkpoint tests incl. the regression against live postgres+git), typecheck clean. Hotfix on `v2.7.1-write-edit-robustness`.
+
+## v2.7.1-write-edit-robustness — 2026-06-01
+
+Two BooCoder hardening features for local quantized models, algorithm-reimplemented (not vendored) from the cline findings in `boocode_code_review_v2.md` §1 #3/#4. **Fuzzy patch applier:** `edit_file`'s apply path was exact-`.includes`-or-throw + first-occurrence `.replace` (`pending_changes.ts`), so a qwen3.6 whitespace/indentation/unicode drift in `old_string` lost the edit; a new pure `fuzzy-match.ts` (`locateMatch`) now runs an exact → per-line-trim → unicode-canon (curly quotes/dashes/nbsp) → Levenshtein-≥0.66 ladder and returns the real file span, refusing multi-exact matches as ambiguous rather than silently editing the first. `applyOne`/`rewindOne` both use it. **Worktree checkpoints + conversation-trim:** `rewind` only reversed BooCode's own `pending_changes`, blind to what external agents (opencode/goose/qwen/claude) write directly into the session worktree — so a new `checkpoints` table + `checkpoints.ts` shadow-commit (tracked **and** untracked, captured via a temp-index `read-tree`/`add`/`write-tree`/`commit-tree` into a GC-safe `refs/boocode/checkpoints/<id>`) snapshots the worktree before each external-agent turn (hooked into all three dispatcher paths), anchored to the turn's assistant message. A new `POST /api/sessions/:id/checkpoints/:cid/restore` resets the worktree (`reset --hard` + `clean -fd`), trims the transcript past that message, and resets the `(chat,agent)` backend session so files, transcript, and agent context land consistent at the restore point; a per-message "Restore to here" affordance in `CoderMessageList` drives it. Built by three parallel agents over disjoint files; DB-integration testing caught a microsecond-`created_at` self-deletion bug in the later-checkpoint cleanup. Full coder suite 234 passing (incl. 17 fuzzy-match + 6 checkpoint tests), server+coder build + web tsc clean. Builds on `v2.7.0-mit`; openspec `write-edit-robustness`. Live host smoke (dispatcher hook + restore UI end-to-end) still to run.
+
+## v2.7.0-mit — 2026-06-01
+
+Relicenses BooCode from AGPL-3.0 back to MIT by clearing the three Unsloth-Studio-derived files the `v2.4.0`/`v2.4.1` lifts pulled in — the root `LICENSE` and all five `package.json` had been `AGPL-3.0-only`, making the network-served work AGPL §13-encumbered. The enabling finding decoupled the relicense from the long-planned native-llama-server-parsing retirement: `tool-call-parser.ts`'s Unsloth-ported algorithm (`parseToolCallsFromText`/`scanBalancedBraces` + unused nudge constants) was **dead code** with no production import, so it was simply deleted while the load-bearing `extractToolCallBlocks`/`stripToolMarkup` (BooCode-authored streaming helpers) were kept byte-identical — no behavior change to the live tool-call path. `html-to-md.ts` was swapped to the MIT `node-html-markdown` library (`parse5` dropped; the only behavior delta is column-aligned tables, GFM hard-break `<br>`, and `<ol start>` renumbering, all feeding the LLM via `web_fetch`), and `llama-args-validator.ts` was clean-room rewritten with the managed-flag denylist re-derived from the public llama-server flag list (facts, not copyrightable). The license flip set `LICENSE` to MIT (`Copyright (c) 2026 indifferentketchup`), the five `package.json` to `MIT`, removed every AGPL SPDX header, added a README License section, and added a `license-mit` guard test that fails if AGPL provenance returns. Built by three parallel agents over the disjoint files; full server suite 519 passing (incl. 9 new guard tests), server build + coder typecheck clean. Resolves `boocode_code_review_v2.md` §1 #1 / §5k and the roadmap's `License-debt` batch (openspec `license-debt-mit`); supersedes that batch's original staged plan, which had entangled the flip with a live qwen3.6 validation window.
+
+## v2.6.11-close-hooks-staging — 2026-06-01
+
+The two v2.6 follow-ups left after `v2.6.10-lifecycle-hardening`. **Server close-hook caller:** `apps/server` (BooChat) now fire-and-forgets BooCoder's Phase-3 close hooks so warm agent backends + worktrees tear down *immediately* on delete/archive instead of waiting for the idle-evict/reaper backstop — a new `coder-notify.ts` `notifyCoderClose(kind,id)` (reusing the v2.6.2 `BOOCODER_URL` reach, never-rejects) is `void`-called after the WS frame at session-delete (`POST /api/sessions/:id/close`) and chat archive / archive-all / delete (`POST /api/chats/:id/close`); an unreachable coder can never block or fail the user's delete/archive. **Staging-boundary hint (task 3.7):** the BooCoder DiffPanel now shows a muted one-liner when the selected provider can't see another agent's unapplied worktree edits — native boocode selected + external-agent-staged changes (or vice-versa) → "<agent>'s edits live in its worktree — BooCode won't see them until applied" — derived purely from the per-change `agent` + current provider, no new state. 6 new server tests (`coder-notify`), 537 server tests pass; web + server tsc/build clean. **With these the v2.6 openspec is fully closed** — only the live Smoke 2/2b/3 remain (manual exercise).
+
+## v2.6.10-lifecycle-hardening — 2026-06-01
+
+v2.6 Phase 3 (the last phase) — lifecycle hardening of the warm-process backends. **Idle eviction + LRU cap:** the agent pool runs a 60s sweep that evicts backends/sessions idle past `AGENT_POOL_IDLE_TTL_MS` (30 min default) and any beyond `AGENT_POOL_MAX_LIVE` (10, LRU) — **never a busy one** (in-flight turn, double-checked via a new `isBusy()` backend hook); the worktree persists (DB-backed) and the next turn re-spawns + reattaches. The eviction/LRU/restart decisions are factored into a pure `lifecycle-decisions.ts` (modeled on the inference `selectPruneTargets` pattern). **Crash recovery:** lifts openchamber's health-monitor + busy-aware-restart + consecutive-failure + stale-busy-grace state machine into `opencode-server.ts` (with port reclaim) and `warm-acp.ts` — an opencode server crash settles in-flight turns as failed, marks the rows `crashed`, and recreates fresh sessions (a fresh server can't hold the old in-memory id), while a warm-ACP child crash re-`session/new`s next turn; the F.1 turn-guard and U.6 usage are preserved (their tests still pass). **Worktree reaper:** a periodic reaper removes orphan on-disk worktrees (no live `worktrees` row, 1h grace) behind a superset-style preflight that skips dirty/unpushed/unmerged work, with Paseo-style soft-delete (`status='archived'`). Plus close hooks (`/api/chats/:id/close`, `/api/sessions/:id/close`, awaiting the apps/server caller) and diff re-baseline after `apply_pending`. Built test-first — 35 new tests (`lifecycle-decisions` 22, `agent-pool` 13) + a DB-opt-in reconnect integration test; 215 coder tests pass, tsc + build clean. **This completes v2.6** (Phase 0–3 + F.1 + Phase 1-UX). Remaining follow-ups (out of v2.6 scope): the apps/server close-hook caller, the 3.7 DiffPanel staging-boundary hint (frontend), and live Smoke 2/2b/3.
+
+## v2.6.9-warm-acp — 2026-05-31
+
+v2.6 Phase 2: goose and qwen now run as **warm ACP backends** instead of one-shot-per-task. A new `WarmAcpBackend` (`backends/warm-acp.ts`, implementing the same `AgentBackend` interface as the opencode warm server) holds one persistent `goose acp` / `qwen --acp` child + `ClientSideConnection` + ACP session per `(chat, agent)`, running `initialize` + `session/new` once and reusing the connection across turns; per-turn abort cancels the in-flight prompt (`session/cancel`) without killing the child, and a child exit marks `agent_sessions.status='crashed'` for re-spawn on the next turn. The dispatcher routes `goose`/`qwen` chat-tab tasks to the pooled warm backend via a pure `shouldUseWarmBackend(task)` predicate (warm only when both `session_id` and `chat_id` are set), keeping the one-shot `runExternalAgent` path as the fallback for session-less creators (arena, MCP, `new_task`); broker frames + `persistExternalAgentTurn` + the latest-wins `pending_changes` diff are identical to the opencode path. The `acp-dispatch.ts` `handleSessionUpdate` switch was extracted into a pure shared `acp-event-map.ts` mapper used by both the one-shot and warm paths (one-shot behavior byte-identical, all existing acp tests green). The design's `unstable_resumeSession` concern is resolved — the installed `@agentclientprotocol/sdk@^0.22.1` exposes stable `resumeSession`/`loadSession`, but resume is moot in the hot path (warm reuse needs none); cross-restart resume + idle eviction are deferred to Phase 3. Built test-first (15 new tests: `warm-acp-routing`, `acp-event-map`); 180 coder tests pass, tsc + build clean. **Smoke 2/2b (live two-message warm reuse + the opencode→boocode→opencode switch round-trip) to be run post-deploy.** Phase 3 (lifecycle hardening) is the last v2.6 phase.
+
 ## v2.6.8-agent-attribution — 2026-05-31
 
 v2.6 Phase 1-UX: agent attribution + switch affordances over the already-shipped `pending_changes.agent` column and `agent_sessions` table (read+display, no new backend capability). **Backend:** `pending_changes.agent` is now stamped at every queue site (native write tools → `'boocode'`, dispatched external agents → the task's agent, manual RightRail create → `NULL`) and flows through `listPending`; a new `GET /api/sessions/:id/agent-sessions` route returns `[{agent,status,has_session,last_active_at}]` per `(chat,agent)` for the session's chats; and the opencode warm-server backend consumes opencode's `session.next.step.ended` events, accumulating `input_tokens`/`output_tokens`/`cost` onto the `agent_sessions` row (new columns, idempotent). **Frontend:** the BooCoder DiffPanel renders a per-row agent badge (provider icon + label; `null` → "manual") with a "Changes from X, Y" note when a pending set spans multiple agents, and the AgentComposerBar shows a resumed / history / new-session chip beside the Provider picker — gated on an optional `sessionId` prop so BooChat is unaffected — driven by a new `useAgentSessions` hook that refetches on message-complete; `providerIcon` was extracted to a shared `components/coder/providerIcons.tsx`. Built by three parallel subagents over disjoint file sets; web + coder typecheck clean, 165 coder tests pass (9 new across `opencode-usage` and `agent-sessions.routes`). U.6's persisted token totals are conversation-cumulative and not yet surfaced in the UI (deferred). Implements the U.1–U.6 "remaining" plan from the v2.6 openspec reconciliation; Phase 2 (warm ACP goose/qwen) + Phase 3 (lifecycle hardening) remain.

CLAUDE.md

@@ -2,11 +2,11 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-**Cursor agents:** start with `docs/ARCHITECTURE.md` (diagram). This file is the deep engineering reference. (Note: the root navigation `AGENTS.md` was removed in v1.12; `data/AGENTS.md` is the agent *registry*, not navigation.)
+**Cursor agents:** start with `docs/ARCHITECTURE.md` (diagram); this file is the deep engineering reference. `data/AGENTS.md` is the agent *registry*, not navigation (the root navigation `AGENTS.md` was removed).
 
 ## What is BooCode
 
-Self-hosted single-user developer chat app. AI assistant with read-only file tools (view_file, list_dir, grep, find_files) running against a local llama-swap inference server. Sessions organized by project, with a multi-pane workspace (chat + file browser side by side).
+Self-hosted single-user developer chat app. AI assistant with read-only file tools (view_file, list_dir, grep, find_files) against a local llama-swap inference server. Sessions organized by project, multi-pane workspace (chat + file browser side by side).
 
 Plus `apps/booterm` (second container, port 9501, bookworm-slim+glibc): Fastify + node-pty + tmux. Browser terminal panes WS to `/ws/term/sessions/:sid/panes/:pid`; per-session tmux session `bc-<sid>`, per-pane window `term-<pid>`. Shells drop privs to samkintop via `gosu` in `tmux.conf` default-command.
 
@@ -35,85 +35,22 @@ npx tsc -p apps/web/tsconfig.app.json --noEmit  # web app specifically
 docker compose build --no-cache boocode && docker compose up -d
 ```
 
-Tests: `pnpm -C apps/server test` runs the vitest suite. No test harness on `apps/web` (adding it requires installing vitest as a new devDep). Vitest pinned to `^3` because Vite 5 / vitest 4 are incompatible. No linters configured. Vitest include glob is `src/**/__tests__/**/*.test.ts` (see `apps/server/vitest.config.ts`) — tests outside `src/**/__tests__/` silently won't run; match the per-domain convention (`apps/server/src/services/__tests__/foo.test.ts`).
+Tests: `pnpm -C apps/server test` (vitest); `apps/coder` has its own suite — `pnpm -C apps/coder test` (`globals:false`, so import `describe`/`it`/`expect` from `vitest`). No `apps/web` test harness, no linters. Vitest pinned to `^3` (Vite 5 / vitest 4 incompatible). Include glob is `src/**/__tests__/**/*.test.ts` — tests outside it silently won't run. Extract pure helpers to unit-test (`backends/turn-guard.ts`, `lifecycle-decisions.ts` are the pattern).
 
 ## Architecture
 
-**Monorepo**: pnpm workspaces with `apps/server` (Fastify + postgres), `apps/web` (React + Vite), and `apps/booterm` (Fastify + node-pty + tmux).
+**Monorepo**: pnpm workspaces with `apps/server` (Fastify + postgres), `apps/web` (React + Vite), `apps/booterm` (Fastify + node-pty + tmux), `apps/coder` (BooCoder, host service).
 
-### Server (`apps/server/src/`)
+### Per-app deep references
 
-- **Fastify** with `@fastify/websocket` and `@fastify/static` (serves built frontend)
-- **postgres** (porsager/postgres) with tagged-template SQL — no ORM. Schema in `schema.sql`, applied on startup. LSP may false-positive on `sql<Type[]>\`...\`` generics; CLI `tsc` / `pnpm build` is authoritative.
-- **Zod** for request validation and config parsing.
+Detailed engineering notes live in per-app `CLAUDE.md` files, **auto-loaded when you read/edit files in that subtree** (and worth opening before non-trivial work there):
 
-Key services:
-- **`services/inference/`** — Public surface re-exported via `inference/index.ts`; callers import from `./services/inference/index.js` explicitly (NodeNext doesn't honor directory-index resolution). Layout: `turn.ts` (runAssistantTurn / runInference / createInferenceRunner; exports `InferenceFrame`, `InferenceContext`, `TurnArgs`, `StreamResult`, `MAX_STEPS`), `stream-phase.ts` (streamCompletion as a v1.13.1-A AI SDK adapter + executeStreamPhase), `provider.ts` (`upstreamModel(baseURL, modelId)` wrapping `createOpenAICompatible` against llama-swap), `tool-phase.ts` (executeToolPhase → returns `ToolPhaseResult`; no longer recurses into runAssistantTurn — v1.14.0 converted the recursion to an explicit while loop in turn.ts), `sentinel-summaries.ts` (runCapHitSummary + runDoomLoopSummary + runStepCapSummary + their sentinel inserters), `error-handler.ts` (handleAbortOrError, finalizeCompletion), `payload.ts` (buildMessagesPayload, loadContext, maybeFlagForCompaction, `OpenAiMessage`), `sentinels.ts` (`detectDoomLoop`, `DOOM_LOOP_THRESHOLD`, sentinel predicates), `budget.ts` (resolveToolBudget), `xml-parser.ts` (qwen3.6 XML tool-call fallback — KEEP, AI SDK doesn't handle inline-XML tool calls), `parts.ts` (parts-table write helpers: `partsFromAssistantMessage`, `partsFromToolMessage`, `insertParts` — v1.13.20 made parts the sole source of truth), `prune.ts` (v1.13.4 two-tier compaction; `selectPruneTargets` is the pure decision helper), `types.ts` (`StreamPhaseState`, `DB_FLUSH_INTERVAL_MS`). **`TurnArgs`** is the per-turn state envelope populated from loop locals each iteration; reset in `runInference` at user-message boundary. The outer loop in `runAssistantTurn` (v1.14.0) runs `while (stepNumber < effectiveCap)` where `effectiveCap = Math.min(agent.steps ?? Infinity, MAX_STEPS=200)`. Per-agent `steps:` field in AGENTS.md frontmatter. `steps: 0` means text-only (no tool execution). Step-cap hit writes a `cap_hit` sentinel so `CapHitSentinel.tsx` renders it.
-- **AI SDK v6 streamCompletion adapter** (v1.13.1-A; `services/inference/stream-phase.ts`). `streamText` is the underlying call; the BooCode layer above (executeStreamPhase, finalize, dual-write) is shape-preserved via an adapter. Five gotchas the LSP/test suite won't catch:
-  - **Abort signals are swallowed.** `streamText`'s `fullStream` iterator exits cleanly when `abortSignal` fires — no throw. Post-iteration `if (signal?.aborted) throw <AbortError>` is required; without it the row finalizes as `complete` instead of `cancelled`. Comment in stream-phase.ts pins this; don't refactor it away.
-  - **Usage lands only at stream end** via `await result.usage` (`inputTokens` / `outputTokens` v6 names → mapped to `promptTokens` / `completionTokens` for the existing onUsage callback). Mid-stream live tok/s is gone vs v1.12.2; ChatThroughput shows a single value at stream end.
-  - **Tools have NO `execute` field.** BooCode dispatches tools in tool-phase.ts, not the AI SDK loop. Only `description` + `inputSchema: jsonSchema(parameters)` — surfacing tool-call parts via `fullStream` and stopping is what we want.
-  - **`includeUsage: true` MUST be set on `createOpenAICompatible`** in `services/inference/provider.ts`. The adapter defaults it false, omitting `stream_options.include_usage` from the request body; llama-swap then never emits the usage block and `result.usage.inputTokens/outputTokens` resolve to `undefined`. Latent regression from v1.13.1-A through v1.13.7 — every assistant row in that window has `tokens_used`/`ctx_used` NULL. Don't remove this flag during refactor.
-  - **Tool-call-only turns may emit a leading `\n` text-delta** as the assistant content. `MessageList.flatten`'s `hasText` and `MessageBubble`'s `hasContent` both `.trim()` before the length check — otherwise whitespace-only content renders an empty bubble + ActionRow between every tool call (v1.13.7 fix). `payload.ts:buildMessagesPayload` also skips `status='failed'` AND complete-but-empty (no content, no tool_calls) assistant rows to avoid "Cannot have 2 or more assistant messages at the end of the list" upstream rejections after cap-hit + Continue.
-- **AI SDK ModelMessage conversion** (`toModelMessages` in stream-phase.ts). Tool messages need a `toolName` for `ToolResultPart` — BooCode's OpenAI-shape history doesn't carry it, so a forward-scan builds a `tool_call_id → toolName` map from prior assistant `tool_calls`. Tool outputs wrapped as `{ type: 'json' | 'text', value }` matching the v6 `ToolResultOutput` union. Assistant messages with reasoning emit a `ReasoningPart` first in the content array (v1.13.1-C).
-- **`experimental_repairToolCall`** (v1.13.3) wired into `streamText` to keep the stream alive when qwen3.6 emits malformed tool args. Pass-through implementation — logs the bad call and returns it unmodified; `executeToolPhase`'s existing zod-reject error path routes it to the model on the next turn.
-- **`chat_status` frame shape** (published via `broker.publishUser`) — `status: 'streaming' | 'tool_running' | 'waiting_for_input' | 'idle' | 'error'` (widened from `working|idle|error` in v1.12.1). Frontend `useChatStatus` derives `idle_warm` (<30s since idle) vs `idle_cold`. `ChatThroughput` renders inline beside `StatusDot` only when streaming or tool_running, fed by 500ms-throttled `'usage'` WS frames (`completion_tokens` + `ctx_used` + `ctx_max`). The `POST /api/chats/:id/discard_stale` endpoint exists to mark a stuck-streaming row as `failed` when the frontend's 60s no-token-activity timer (`ChatPane` content-length watcher) gives up.
-- **Boot-time stale-streaming sweep** in `apps/server/src/index.ts` after `applySchema()`: any `messages.status='streaming'` older than 5 minutes flips to `'failed'`. Logs only on non-zero count. Recovers from container restart while inference was mid-stream (v1.12.1).
-- **Periodic 60s sweeper** in `apps/server/src/index.ts` (v1.13.3 + v1.13.5). Same `setInterval` runs `sweepStaleStreaming` (marks `messages.status='streaming'` older than 5 min as `failed`, publishes `chat_status='idle'` so the UI dot drops) and `cleanupTruncations` (TTL + orphan reap of tmpfs truncation files). `app.addHook('onClose')` clears the timer. No-op when nothing to reap.
-- **`services/broker.ts`** — In-memory pub/sub with two channel types: per-session (message streaming) and per-user (sidebar updates). No persistence; clients reconnect on restart. v1.13.11: every WS publish goes through `broker.publishFrame(sessionId, frame)` or `broker.publishUserFrame(user, frame)` — both Zod-validate against `WsFrameSchema` (`types/ws-frames.ts`) and fail-closed (log + drop). `ctx.publish` / `ctx.publishUser` in inference + auto_name route through the index.ts adapter that calls publishFrame internally. The schema is duplicated byte-identical at `apps/web/src/api/ws-frames.ts`; a `ws-frames.test.ts` case enforces parity. Don't add new raw `broker.publish()` / `publishUser()` calls.
-- **`services/tools.ts`** — Tool registry (`ALL_TOOLS`, `READ_ONLY_TOOL_NAMES`, `TOOLS_BY_NAME`). Filesystem tools (view_file/list_dir/grep/find_files) go through three guard layers: `path_guard.ts` (workspace scope), `secret_guard.ts` (filename deny list), `url_guard.ts` (SSRF/private-IP block for web_fetch). v1.11.8+ web tools (`web_search`, `web_fetch`) are opt-in per chat via `session.web_search_enabled` (resolved with `project.default_web_search_enabled` fallback) and filtered out of the LLM's tool schema when false. v1.13.5 truncation: when a tool slice cuts content, `services/truncate.ts` stashes the full text on tmpfs at `BOOCODE_TRUNCATION_DIR` (default `/tmp/boocode-truncations`, 0o700) keyed by an opaque `tr_<12 base32 chars>` id, and the `view_truncated_output(id)` tool retrieves it. 5MB cap (matches `view_file`'s `MAX_FILE_BYTES`), 7-day TTL, reaped by the periodic sweeper. Tmpfs path means container restart loses retrieval — acceptable, the model usually has moved on.
-- **`services/compaction.ts`** + **`services/model-context.ts`** — v1.11.0 anchored rolling summary (single `summary=true` assistant row per chat, supersedes itself on each compaction). Triggered when `chats.needs_compaction` is set after an inference turn exceeds `usable(ctx_max) = floor(0.85 × ctx_max)` (v1.13.9 opencode-pattern early trigger; was `ctx_max - 20k` pre-v1.13.9, which gave only 7.6% headroom at 262k and 0 budget for ≤20k contexts). **`ctx_max` comes from `model-context.getModelContext()` which fetches `${LLAMA_SWAP_URL}/upstream/<model>/props`** — NOT from `parsed.timings.n_ctx` (the stream completion's `timings` doesn't carry n_ctx; that read was dead code until v1.11.3 ripped it out). First inferences after a boocode boot may have `ctx_max=NULL` if llama-swap hasn't loaded the model yet; negative cache TTL is 60s, recovers on next turn. v1.13.6: `buildHeadPayload` embeds `reasoning_parts` as a `<reasoning>...</reasoning>` prose prefix on the assistant `content` (OpenAI wire shape has no structured reasoning field; the summarizer reads text). Standalone tag when content is empty (tool-call-only turn). `buildHeadPayload` + `OpenAiMessage` exported for test access — keep them exported.
-- **`services/system-prompt.ts`** — `buildSystemPrompt` is the string-returning shim; `buildSystemPromptWithFingerprint` is the canonical impl returning `{prompt, fingerprint, drift}`. v1.13.8 instrumentation: SHA-256 of the assembled prefix is logged per `buildMessagesPayload` call (msg `prefix-fingerprint`, level=info); a `Map<sessionId, lastHash>` observer fires `prefix-drift` (level=warn) on hash change with a field-level `changed_inputs` diff. Smoke proved the prefix is byte-stable across turns in steady-state — the originally-planned `system_prompt_cache` DB table was dropped as redundant against the v1.12.0 input-layer mtime caches (BOOCHAT.md here + AGENTS.md global+per-project in `agents.ts:safeStat`).
-- **`services/inference/budget.ts`** — tool-call budgets: `BUDGET_READ_ONLY = 30`, `BUDGET_NON_READ_ONLY = 10` (forward-looking; no write tools yet), `BUDGET_NO_AGENT = 30` (v1.13.7; was 15 — every tool in `ALL_TOOLS` is read-only today, so no-agent mode shares the read-only-agent cap). Per-agent `max_tool_calls` from AGENTS.md frontmatter overrides.
-- **`messages_with_parts` view** (v1.13.1-B; `schema.sql`). Read sites that need `tool_calls` / `tool_results` / `reasoning_parts` SELECT from this view, NOT `messages` directly. v1.13.20 dropped the legacy `messages.tool_calls` / `messages.tool_results` JSON columns; the view now reads parts-only subselects. Writes target `message_parts` exclusively via `insertParts` (or via the helpers `partsFromAssistantMessage` / `partsFromToolMessage`). The `Message` wire type still carries `tool_calls?` / `tool_results?` because the view synthesizes them from parts — frontend reads are unchanged. Shapes: `tool_calls jsonb[]`, `tool_results jsonb` single object, `reasoning_parts jsonb[]` of `{text}`. If you ever need to UPDATE a message and return its full Message shape, do a two-step UPDATE returning `id` followed by SELECT from the view — RETURNING off the bare `messages` table no longer carries the tool fields.
-- **`services/file_ops.ts`** — Shared file operation implementations used by both inference tools and HTTP routes.
-- **`services/auto_name.ts`** — Non-streaming LLM call to generate 4-word session titles after first assistant reply.
-- **`apps/coder/src/services/provider-registry.ts`** (BooCoder, NOT apps/server) — Static registry of provider metadata (label, transport, model source). `PROVIDERS` array, `PROVIDERS_BY_NAME` map. 5 providers: boocode (native), opencode (acp), goose (pty), claude (pty), qwen (pty).
-- **`apps/coder/src/services/agent-probe.ts`** (BooCoder) — Startup probe using direct `exec()` (not SSH). Discovers installed agents on host, their versions, ACP support, and models. Qwen models read from `~/.qwen/settings.json`. Claude models are static from the registry. Results persisted to `available_agents` table.
-- **`apps/coder/src/routes/providers.ts`** (BooCoder) — `GET /api/providers` returns installed providers with models. Transport field reflects actual capability (checks `supports_acp` from DB, not just registry preference). The apps/server side of this flow is the "Provider picker dispatch" bullet below.
-- **Provider picker dispatch**: when `provider !== 'boocode'`, the message route creates a `tasks` row (with `session_id` set) instead of calling `inference.enqueue`. The dispatcher picks it up and dispatches via ACP or PTY using the agent's `install_path`.
+- **`apps/server/CLAUDE.md`** — inference pipeline, AI-SDK adapter gotchas, tools, compaction, broker, the `messages_with_parts` view, sidecar routing, secret guard, the `data/AGENTS.md` registry.
+- **`apps/coder/CLAUDE.md`** — BooCoder dispatch, provider registry/probe/snapshot, opencode/ACP/PTY/Claude-SDK backends, `agent_sessions` resume.
+- **`apps/web/CLAUDE.md`** — React app, hooks/event buses, font & CSS pipeline, multi-pane workspace, all UI conventions.
+- **`docs/project-discovery.md`** — full stack / tooling / command inventory across all packages (read-on-demand).
 
-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. Runs as a **systemd service on the host** (`boocoder.service`), NOT in Docker. Fastify server at port 9502, connects to postgres at `127.0.0.1:5500`.
-- **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.
-- Build + deploy: `pnpm -C apps/server build && pnpm -C apps/coder build && sudo systemctl restart boocoder`. Env file at `apps/coder/.env.host`. Service file at `/etc/systemd/system/boocoder.service`.
-- After `pnpm -C apps/coder build` the host `boocoder.service` keeps running the OLD process until `sudo systemctl restart boocoder` — a stale process shows **new routes 404 with `{error:'not found'}` while old routes still 200** (the `/api` not-found handler returns that shape). Restart, don't re-debug.
-- Agent dispatch spawns binaries directly using `install_path` from `available_agents` — no `spawn('sh', ['-c', ...])` (fails under systemd). Follows Paseo's pattern: `spawn(fullBinaryPath, argsArray, { cwd })`.
-- systemd hardening: only `NoNewPrivileges=true` is safe. `ProtectSystem`, `ProtectHome`, `PrivateTmp` all break agent dispatch (agents need full filesystem access to read configs, write to worktrees).
-- `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 the boocoder host service (`BOOCODER_URL` env var, default `http://100.114.205.53:9502`). WS connects directly to `:9502`.
-- `apps/coder/web/` is a STANDALONE fallback SPA served at `:9502` directly. The PRIMARY BooCoder frontend is the `CoderPane` in BooChat's SPA (`apps/web/src/components/panes/CoderPane.tsx`), accessible via the "Coder" pane in the workspace at `code.indifferentketchup.com`. Both exist; the pane is what Sam uses.
-- **Provider snapshot lifecycle** (`apps/coder/src/services/`): `provider-config.ts` (Zod config, never-throws on bad input) → `provider-config-registry.ts` (`buildResolvedRegistry`, singleton) → `provider-snapshot.ts` (two-tier probe: tier-1 fast presence, tier-2 cold ACP probe skipped unless force / stale `PROVIDER_PROBE_TTL_MS` 24h / dbEmpty; cached). Verify live: `curl http://100.114.205.53:9502/api/providers/snapshot` — returns providers + models + commands, the exact shape `AgentComposerBar` renders.
-- `PATCH /api/providers/config` replaces a provider id's override object **wholesale** (per-id shallow merge) — to flip one field send `{...existing, enabled}`, or a custom ACP entry's `command`/`label` is wiped and it drops out of the resolved registry. `data/coder-providers.json` is **gitignored** (it's live runtime config — the coder reads AND writes it on UI toggles); the tracked reference is `data/coder-providers.example.json`. The loader falls back to `{providers:{}}` (built-ins only) when the live file is absent, so a fresh checkout needs no copy.
-- **opencode** runs as a warm HTTP server (v2.6 Phase 1, `services/backends/opencode-server.ts` — `opencode serve` per BooCoder process, one opencode session per BooCode session, resumed via `agent_sessions`). goose/qwen/claude still dispatch **one-shot** ACP/PTY with no ctx/token usage; only native `boocode` (llama-swap engine) tracks ctx. Paseo's per-provider native clients (design §12) deliberately not ported.
-- **opencode SSE** (`opencode-server.ts`): live streaming arrives as `session.next.text.delta` / `session.next.reasoning.delta` / `session.next.tool.{called,success,failed}` — NOT `message.part.*` (those are terminal/post-hoc). `client.event.subscribe({ directory })` MUST pass the session's worktree directory; omit it and opencode scopes events to the server's `process.cwd()` → zero session events (empty turns, 180s watchdog timeout). Per-session SSE (P1.5-a): each live session owns its own `event.subscribe({directory})` loop + AbortController, so concurrent sessions in different worktrees stream independently; a `sessionID` demux guard drops cross-session events when two share a dir. Turn completes on `session.idle`; `promptAsync` is fire-and-forget (204).
-- **opencode model strings** must be provider-prefixed (`llama-swap/<model>`) AND exist in `~/.config/opencode/opencode.json` `provider.llama-swap.models` — not merely loadable by llama-swap. `parseModel` infers `llama-swap/` for a bare id; the dispatcher coalesces empty→DEFAULT_MODEL then prefixes. `agent-probe` populates opencode's `available_agents.models` via `mergeLlamaSwap` (fetches `/v1/models`); empty model list → frontend sends `''` → no inference (`input:0`, empty turn).
-- **agent_sessions resume**: `config_hash = sha256('opencode_server|<model>')` — must NOT include the server port (random per boot; including it breaks cross-restart resume). P1.5-b: `agent_sessions` is keyed `(chat_id, agent)` — the tab/chat is the context unit (two opencode tabs in one session = two contexts sharing one worktree). `chat_id` CASCADEs from `chats`; `session_id`/`worktree_id` are informational `SET NULL`. The `worktrees` table (one-per-session, `session_id` SET NULL so it survives session delete) supersedes the defanged `session_worktrees`. `tasks.chat_id` threads the tab id to the dispatcher; `runOpenCodeServerTask` falls back to resolve-or-create a chat when it's null (arena/MCP/new_task). The `@opencode-ai/sdk` v2 client takes flattened params (`{sessionID, directory, parts, model:{providerID,modelID}}`), imports `createOpencodeClient` from `@opencode-ai/sdk/v2/client`.
-
-### Frontend (`apps/web/src/`)
-
-- **React 18** + React Router v6 + **Tailwind v4** + shadcn/radix-ui primitives.
-- **Shiki** for syntax highlighting (async `codeToHtml` in `CodeBlock.tsx` and `FileViewer` in `FileBrowserPane.tsx`).
-- Path alias: `@/` maps to `src/`.
-- **Mobile interaction primitives** (post-v1.6): `useViewport` (matchMedia, breakpoints mobile <768 / tablet 768–1023 / desktop ≥1024), `useSidebarDrawer` / `useRightRailDrawer` (Context + auto-close on `useLocation().pathname` change), `useLongPress` (500ms timer, dispatches synthetic `contextmenu` on `[data-tab-id]`), `usePullToRefresh` (80px threshold, 600ms hold), `SwipeablePaneTab` (60px close, 30px vertical bail). Tap-target convention: `max-md:min-h-[44px] max-md:min-w-[44px]`. Mobile headers: `border-b px-3 sm:px-4 py-2` + `style={{ paddingTop: 'max(0.5rem, env(safe-area-inset-top))' }}`. Hamburger left, FolderTree right.
-
-Key patterns:
-- **`hooks/sessionEvents.ts`** — Module-singleton event bus (Set of listeners). Used for cross-component communication: session renames, file-open events, attachment dispatch. 9 event types in the discriminated union. When adding a new event type to the `SessionEvent` union, you must also add a case to the `applyEvent` switch in `useSidebar.ts` (even if it's a no-op `return prev`).
-- **`hooks/useSessionStream.ts`** — WebSocket per session, `applyFrame` reducer builds message list from streaming frames.
-- **`hooks/useUserEvents.ts`** — Single app-level WS to `/api/ws/user` with exponential backoff reconnect. Forwards frames onto the sessionEvents bus.
-- **`hooks/useSidebar.ts`** — Module-singleton with Set<setState> subscriber pattern; one bus subscription guarded by `globalThis.__boocode_sidebar_subscribed` for HMR safety. Every new `SessionEvent` type needs a `case` in the `applyEvent` switch (no-op `return prev` is fine).
-- **`api/client.ts`** — Centralized typed fetch wrapper. All endpoints under `api.*` namespace.
-
-Font / CSS pipeline (apps/web):
-- Tailwind v4's `@import "tailwindcss"` directive strips font URLs from subsequent CSS `@import`s — `@fontsource*` packages must be imported as JS side-effect modules in `apps/web/src/main.tsx`, not via `@import` in `globals.css`. Otherwise the woff2 files never make it to `dist/`.
-- Lightning CSS (inside `@tailwindcss/postcss` v4) collapses contiguous unicode-ranges to wildcard shorthand (`U+0000-FFFF` → `U+????`), which iOS Safari/Vivaldi mishandles (silently drops the font from those codepoints). Use explicit non-wildcard-collapsible subranges (e.g. `U+2500-259F` not `U+2500-25FF`). The `apps/web` build script greps `dist/assets/*.css` for `U+2500-259F` and fails the build if missing — preserve that guard.
-- `@font-face` blocks must live AFTER all `@import` statements (CSS spec). Earlier placement silently breaks every subsequent `@import` (this broke the 18 theme palette imports in globals.css for one session).
-- JetBrainsMono Nerd Font self-hosted in `apps/web/src/fonts/` (TTF from ryanoasis/nerd-fonts release) — needed because `@fontsource-variable/jetbrains-mono` ships subsetted woff2s that don't cover `U+2500-259F` (box drawing + block elements, used by opencode's banner). "NL" = No Ligatures (matches `font-feature-settings: "liga" 0`); "Mono" = single-cell icon width so TUI layouts don't desync.
-- xterm-addon-webgl rasterizes glyphs via Canvas2D into a GPU texture atlas. Canvas2D does NOT honor `font-display: block` — it uses whatever font is currently registered. Gate xterm initialization on `document.fonts.load(<font-name>)` resolving before calling `term.open()` (see `fontsReady` useState in `TerminalPane.tsx`). iOS Safari/Vivaldi also reclaims WebGL contexts from backgrounded tabs: keep `webgl.onContextLoss(() => webgl.dispose())` + recreate via visibilitychange. Do NOT manually dispose+recreate the addon after font load — iOS silently fails the second GL context creation and the terminal drops to DOM renderer with stale metrics.
+Cross-app contracts (WS-frame & provider-type parity, sentinels) and everything below stay here.
 
 ### Data flow for chat
 
@@ -124,90 +61,64 @@ Font / CSS pipeline (apps/web):
 5. Tool calls: inference executes tools server-side, publishes tool_call/tool_result frames, loops back to LLM
 6. Terminal states (complete/error): DB updated with final content + token counts, `session_updated` frame published on user channel
 
-### Multi-pane workspace
-
-Sessions hold 1–5 panes (chat / empty / placeholder terminal+agent). v1.12.1 moved pane state from per-device localStorage to `sessions.workspace_panes jsonb` for cross-device sync. `PATCH /api/sessions/:id/workspace` persists; `session_workspace_updated` user-channel frame broadcasts to every device watching the session. `useWorkspacePanes` debounces saves 300ms and dedups echoes by JSON string. Legacy localStorage key `boocode.workspace.panes.<sessionId>` is read once on first hydrate (one-time seed-and-delete migration when server is empty but localStorage has data); no longer written. The deprecated `session_panes` table was dropped. `validatePanes(validChatIds)` prunes panes referencing chat IDs that no longer exist (called by `useSessionChats` after the chat list fetch lands). Each chat lives in at most one pane; tab strip is per-pane and tracks `chatIds[]` + `activeChatIdx`. Tab reorder via native HTML5 drag events. v2.6.5: `workspace_panes` is now a `WorkspaceState` envelope `{panes, tabNumbers (chatId→stable session-scoped tab number, assigned on chat-pane open, retired on close, never reused), nextTabNumber, closedPaneStack (reopen LIFO, max 10, persisted so it survives reload)}` — not a bare `WorkspacePane[]`. Hydrate (`toWorkspaceState`) and the server PATCH validator (`z.union([array, envelope])` in `routes/sessions.ts`) both accept the legacy array and normalize to the envelope on read/write. Closing a chat pane relocates its tabs to the oldest chat/empty pane; `reopenPane` strips the restored chatIds from all live panes first (no duplication). `read_tab_by_number` resolves a number→chatId through `tabNumbers`.
-
 ## Database
 
-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. **Two schema files, one DB:** `apps/server/src/schema.sql` owns `sessions`/`chats`/`messages`/`message_parts`; `apps/coder/src/schema.sql` (applied by the boocoder host service) owns `agent_sessions`, `worktrees`, `pending_changes`, `available_agents` and extends `tasks`. Both apply idempotently to the one `boochat` DB — so e.g. an `agent_sessions` FK change goes in the **coder** schema, not the server one. Idempotent FK-action flips (e.g. `ON DELETE CASCADE`→`SET NULL`) guard on `pg_constraint.confdeltype` so a re-run/fresh-deploy is a no-op (see the `session_worktrees`/`agent_sessions` defang blocks).
+PostgreSQL 16. DB name: `boochat` (Docker service stays `boocode_db`). Tables: `projects`, `sessions`, `chats`, `messages`, `settings`, `message_parts`, `pending_changes`, `tasks`, `available_agents`. Views: `messages_with_parts` (parts-merge read path), `tool_cost_stats` (per-tool 100-call rolling window), `human_inbox` (tasks WHERE state IN blocked/failed). Schema applied idempotently on startup via `applySchema()`. Use `clock_timestamp()` (not `NOW()`) inside transactions. CHECK constraints: `projects_status_chk`/`sessions_status_chk`/`chats_status_chk` ('open'|'archived'), `messages_role_chk`, `messages_status_chk` — keep in sync with the `*_STATUSES` const arrays in `apps/server/src/types/api.ts`. **Two schema files, one DB:** `apps/server/src/schema.sql` owns `sessions`/`chats`/`messages`/`message_parts`; `apps/coder/src/schema.sql` (applied by the boocoder host service) owns `agent_sessions`, `worktrees`, `pending_changes`, `available_agents` and extends `tasks` — so e.g. an `agent_sessions` FK change goes in the **coder** schema. Idempotent FK-action flips (e.g. `ON DELETE CASCADE`→`SET NULL`) guard on `pg_constraint.confdeltype` so re-runs are no-ops.
 
-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`.
+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 the new constraint ADD in a `DO $$ ... pg_constraint` guard — the only way to get `ADD CONSTRAINT IF NOT EXISTS`.
 
+**`CREATE OR REPLACE VIEW` can't reorder/rename columns** (Postgres `42P16`): append a new `messages_with_parts` column at the END of the SELECT — a mid-list insert shifts an existing column → crash-loops boot. Add it to each explicit read SELECT too (`routes/messages.ts`/`chats.ts`/`ws.ts`).
 
 ## 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), `MCP_CONFIG_PATH` (optional; default `/data/mcp.json` — JSON config for MCP servers matching opencode's `mcpServers` shape; file missing = no MCP).
+Required: `DATABASE_URL`, `LLAMA_SWAP_URL`. Optional: `PORT` (3000), `HOST` (0.0.0.0), `PROJECT_ROOT_WHITELIST` (/opt, read-only add-existing scope), `BOOTSTRAP_ROOT` (/opt/projects, writable bootstrap mkdir target — host must `mkdir -p` it before container start), `DEFAULT_MODEL`, `LOG_LEVEL`, `SEARXNG_URL` (default `http://100.114.205.53:8888` — internal Tailscale; the public host is behind Authelia, unusable from server context), `BOOCODE_TOOLS` (`core`|`standard`|`all`, default `all`; a ceiling, never expands an agent's whitelist), `MCP_CONFIG_PATH` (default `/data/mcp.json`, opencode `mcpServers` shape; missing = no MCP), `CONTEXT7_API_KEY` (the Context7 MCP key, referenced from `data/mcp.json` as `"{env:CONTEXT7_API_KEY}"`). `data/mcp.json` is **gitignored** but no longer holds secrets — string values support opencode-style `{env:VAR}` substitution (`mcp-config.ts:substituteEnvVars`, applied before Zod validation; unset var → `''` + warn), so real keys live in `.env`; template `data/mcp.example.json`. A config-only edit there needs only `docker compose restart boocode` (data/ is bind-mounted); changing a referenced secret edits `.env`. MCP loads at server startup with per-server graceful degradation; the coder does NOT load MCP (BooChat only).
 
 BooCoder at port 9502: `curl http://100.114.205.53:9502/api/health`. Runs as `boocoder.service` on the host (not Docker). Deploy: `pnpm -C apps/server build && pnpm -C apps/coder build && sudo systemctl restart boocoder`. Health reports tool count: `{"ok":true,"db":true,"tools":33}`.
 
-- `FAST_MODEL` (optional) — cheaper model for titles, summaries, labeling (auto_name.ts, tool-summaries.ts). Falls back to session model or DEFAULT_MODEL when unset. Set to a small model on llama-swap (e.g. `nemotron-nano-4b`) to avoid loading the 35B for 20-token calls.
-- Qwen Code dispatch: `OPENAI_BASE_URL=http://100.101.41.16:8401/v1 OPENAI_API_KEY=dummy qwen -p "<task>" --output-format stream-json`. Install: `npm install -g @qwen-code/qwen-code@latest`. Node ≥22 required on host (container stays Node 20; BooCoder dispatches via direct spawn on host). No `--yolo` flag — non-interactive mode (`-p`) runs autonomously without approval prompts. ACP bridge is HTTP daemon (not stdio); use PTY dispatch.
-- Arena (v2.0.5): `POST /api/arena {project_id, input, contestants: [{agent?, model?}]}` dispatches the same task to N models/agents in parallel. Each contestant gets its own task + worktree. `GET /api/arena/:id` for results. `POST /api/arena/:id/select/:task_id` picks winner.
+- `FAST_MODEL` (optional) — cheaper model for titles, summaries, labeling (auto_name.ts, tool-summaries.ts). Falls back to session model or DEFAULT_MODEL. Set to a small llama-swap model (e.g. `nemotron-nano-4b`) to avoid loading the 35B for 20-token calls.
+- Qwen Code dispatch: `OPENAI_BASE_URL=http://100.101.41.16:8401/v1 OPENAI_API_KEY=dummy qwen -p "<task>" --output-format stream-json`. Install: `npm install -g @qwen-code/qwen-code@latest`. Node ≥22 on host (container stays Node 20; BooCoder dispatches via direct spawn on host). No `--yolo` flag — `-p` runs autonomously without prompts. ACP bridge is an HTTP daemon (not stdio); use PTY dispatch.
+- Arena: `POST /api/arena {project_id, input, contestants: [{agent?, model?}]}` dispatches the same task to N models/agents in parallel; each contestant gets its own task + worktree. `GET /api/arena/:id` for results; `POST /api/arena/:id/select/:task_id` picks a winner.
 
 ## Workflow
 
 - Sam reviews all diffs and commits manually. Do not commit unless explicitly asked.
-- Per-batch docs live under `openspec/changes/<slug>/{proposal,tasks,design}.md`. Already-shipped batches are snapshots in `openspec/changes/archived/`. New batches follow the proposal+tasks shape; see `openspec/README.md` for the convention.
-- Tag naming: `vMAJOR.MINOR.PATCH-slug` (e.g. `v1.13.13-ws-publish`). Monotonic per minor — the slug describes the batch's content so the tag name alone is enough to recall what shipped. No letter suffixes (`-a`/`-b`), no pseudo-ranges (`v1.11.x`), no slug-only sub-versions sharing a number (`v1.13.15-tools` + `-openspec` + `-agentlint` — split into sequential patches instead).
-- `CHANGELOG.md` is the per-tag release log, most-recent on top. When a new tag is created, add a `## <tag> — <YYYY-MM-DD>` section with a 3–6 sentence paragraph summarizing what shipped, drawn from the commit body. Cross-reference other tags by name when the batch builds on, fixes, or pairs with prior work (e.g. "pairs with `v1.13.12-ws-schemas`", "fixed in `v1.13.5-stability-bundle`"). No nested bullets — one paragraph.
-- Deploy: `cd /opt/boocode && docker compose up --build -d` (or `docker compose build --no-cache boocode && docker compose up -d` if you suspect a layer-cache issue).
-- The `boocode` container is `build: .` — it builds web+server from the **working tree**, so uncommitted changes deploy. Web edits are live on the Vite dev server (HMR) but NOT on production (`:9500` / code.indifferentketchup.com) until `docker compose up --build -d boocode`.
-- Git push to Gitea: `GIT_SSH_COMMAND="ssh -i /opt/boocode/secrets/boocode_gitea -o IdentitiesOnly=yes" git push origin <branch>`. The default agent identity is rejected; the in-repo deploy key (`secrets/`, gitignored) is the working one. Transient `Connection reset by peer` retries cleanly after `sleep 5`.
+- Sam often has uncommitted `apps/web` work in flight — stage your own commits **explicitly by path** (never `git add -A`); `docker compose up --build -d boocode` builds the working tree, so a container rebuild also ships his uncommitted web changes.
+- **Deploy by surface:** an `apps/coder` change → `sudo systemctl restart boocoder`; an `apps/web` or `apps/server` change → `docker compose up --build -d boocode` (rebuilds web+server from the working tree). The `boocode` container is `build: .`, so uncommitted changes deploy; web edits are live on the Vite dev server (HMR) but NOT on production (`:9500` / code.indifferentketchup.com) until a rebuild. Use `docker compose build --no-cache boocode && docker compose up -d` if you suspect a layer-cache issue.
+- Cutting a release: name the feature branch DIFFERENTLY from the tag (branch `f1-interrupt-guard`, tag `v2.6.7-interrupt-guard`) — identical names trigger `warning: refname ... is ambiguous`.
+- Per-batch docs live under `openspec/changes/<slug>/{proposal,tasks,design}.md`; shipped batches are snapshots in `openspec/changes/archived/`. New batches follow the proposal+tasks shape (see `openspec/README.md`).
+- Tag naming: `vMAJOR.MINOR.PATCH-slug` (e.g. `v1.13.13-ws-publish`), monotonic per minor — the slug alone recalls what shipped. No letter suffixes, no pseudo-ranges, no slug-only sub-versions sharing a number (split into sequential patches).
+- `CHANGELOG.md` is the per-tag release log, newest on top. New tag → add a `## <tag> — <YYYY-MM-DD>` section, one 3–6 sentence paragraph (no nested bullets) from the commit body; cross-reference related tags by name when the batch builds on / fixes / pairs with prior work.
+- Git push to Gitea: `GIT_SSH_COMMAND="ssh -i /opt/boocode/secrets/boocode_gitea -o IdentitiesOnly=yes" git push origin <branch>`. The default agent identity is rejected; the in-repo deploy key (`secrets/`, gitignored) is the working one. Transient `Connection reset by peer` retries cleanly after `sleep 5`. Keep both remotes synced: push `main` + the release tag to `origin` (Gitea, deploy key above) AND `backup` (`git@github.com:indifferentketchup/boocode.git`, default key).
 - Don't accumulate `.bak-*` files. Clean them up in the same batch or immediately after merge.
-- DB-integration tests opt-in via env var: `DATABASE_URL='postgres://boocode:devpass@localhost:5500/boochat' pnpm -C apps/server test`. Host port is 5500 (mapped from `boocode_db:5432`); password is `${POSTGRES_PASSWORD}` from `.env` (`devpass`), NOT the literal in `.env`'s `DATABASE_URL=postgres://boocode:Ketchup1479@boocode_db:5432/...` line. `psql` is not on the host PATH — for an interactive query use `docker exec boocode_db psql -U boocode -d boochat -c "..."`. Pattern: `describe.runIf(!!process.env.DATABASE_URL)(...)` with a `beforeAll` that applies the schema via `sql.unsafe(readFileSync(schemaPath))`. Tests skip cleanly when var is unset. `tool_cost_stats.test.ts` is the reference.
-- Host-side smoke endpoint: `curl http://100.114.205.53:9500/api/...`. The boocode container's port mapping binds to the Tailscale IP, not `0.0.0.0`, so `localhost:9500` doesn't work from the host shell. Same for booterm at `:9501`.
-- Frontend blank-screen / runtime crash: get the stack-trace column offset from the browser console, then `cut -c <start>-<end> apps/web/dist/assets/index-*.js | sed -n '<line>p'` to read the exact minified expression that threw. Faster than bisecting source. Watch for `=== null`/`!== null` on optional fields fed an `as unknown as` cast — those bypass tsc.
-- Fastify global JSON parser tolerates empty bodies (overridden in `index.ts`); bodyless POSTs (archive, unarchive, stop) work without setting `Content-Type` tricks on the client.
+- DB-integration tests opt-in via env var: `DATABASE_URL='postgres://boocode:devpass@localhost:5500/boochat' pnpm -C apps/server test`. Host port 5500; password is `${POSTGRES_PASSWORD}` from `.env` (`devpass`), NOT the literal in `.env`'s `DATABASE_URL` line. `psql` isn't on host PATH — use `docker exec boocode_db psql -U boocode -d boochat -c "..."`. Pattern: `describe.runIf(!!process.env.DATABASE_URL)(...)` + `beforeAll` applying schema via `sql.unsafe(readFileSync(schemaPath))`. `tool_cost_stats.test.ts` is the reference.
+- Host-side smoke endpoint: `curl http://100.114.205.53:9500/api/...`. The container's port mapping binds to the Tailscale IP, not `0.0.0.0`, so `localhost:9500` doesn't work from the host shell. Same for booterm at `:9501`.
+- Frontend blank-screen / runtime crash: get the stack-trace column offset from the browser console, then `cut -c <start>-<end> apps/web/dist/assets/index-*.js | sed -n '<line>p'` to read the exact minified expression that threw. Watch for `=== null`/`!== null` on optional fields fed an `as unknown as` cast — those bypass tsc.
+- Fastify global JSON parser tolerates empty bodies (overridden in `index.ts`); bodyless POSTs (archive, unarchive, stop) work without `Content-Type` tricks on the client.
 - Event dedup discipline: for any mutation the server publishes via `broker.publishUser`, do NOT add a local `sessionEvents.emit(...)` after the API call — `useUserEvents` forwards the WS frame onto the bus. Frontend mutation handlers must be idempotent (dedup by id, no-op on already-present).
 - `node:20-*` base images ship a `node` user at uid/gid 1000 — delete it (`userdel`/`groupdel` on debian, `deluser`/`delgroup` on alpine) before adding samkintop at 1000.
 - node-pty's compiled `.node` is libc-specific: proddeps and runtime Dockerfile stages must share libc (alpine↔musl or bookworm-slim↔glibc); the TS-only builder stage can stay alpine for speed.
 - pnpm 10 `--frozen-lockfile` skips node-pty's postinstall — the Docker proddeps stage runs `cd node_modules/node-pty && npm run install` to force the native compile.
 - A local PreToolUse hook (`security_reminder_hook.py`) regex-flags Node's older `child_process` spawn helpers as unsafe (false positive even on the File-suffixed variant). Use `spawn` — it's accepted.
-- `/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` at project root is honored when `--respect-gitignore` is passed (enabled in the shim).
-- 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 requires staging the fork source first: `tar -czf codecontext/fork.tar.gz -C /opt/forks/codecontext --exclude=.git --exclude=bin .` then `docker compose build --no-cache codecontext`. The Dockerfile COPYs `fork.tar.gz` into the builder stage (Gitea is behind Authelia, no HTTP clone). `fork.tar.gz` is gitignored.
-- 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.
+- `/opt/boolab` hosts a sibling BooCode at `boocode.indifferentketchup.com` — useful for side-by-side iPhone comparison when debugging booterm rendering. It uses Tailwind v3, boocode uses v4 — don't assume build parity.
+- booterm SSHs to the host as `samkintop@100.114.205.53` (the Tailscale IP). The hostname `ubuntu-homelab` (in the bash prompt) does NOT resolve inside the container. Override via `BOOTERM_SSH_HOST` / `BOOTERM_SSH_USER` env vars in docker-compose if the shell moves to a different machine.
+- codecontext sidecar lives at `/opt/boocode/codecontext/`. 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` at project root is honored when `--respect-gitignore` is passed (enabled in the shim).
+- codecontext fork at `/opt/forks/codecontext/` — separate git repo (branch `boocode-ts`), pushed via the boocode_gitea SSH key to `indifferentketchup/codecontext`. Build `go build ./...`; test `go test ./...`. Docker rebuild requires staging the fork first: `tar -czf codecontext/fork.tar.gz -C /opt/forks/codecontext --exclude=.git --exclude=bin .` then `docker compose build --no-cache codecontext` (the Dockerfile COPYs `fork.tar.gz` into the builder stage; Gitea is behind Authelia, no HTTP clone). `fork.tar.gz` is gitignored.
+- Go binary: `/snap/go/current/bin/go` (not on PATH). Use `export PATH=$PATH:/snap/go/current/bin` or the full path.
+- `os/exec` child supervisors must 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` never fires because the parent stays alive. `codecontext/shim.go` is the reference.
 
 ## Conventions
 
-- `overflowWrap` not `wordWrap` — TypeScript's CSSStyleDeclaration marks `wordWrap` as deprecated (error 6385).
+Cross-cutting only. Per-app conventions live in the matching `apps/*/CLAUDE.md`.
+
 - No app-layer auth. Authelia handles auth at the reverse proxy. All `broker.publishUser`/`subscribeUser` calls use `'default'` as the user key.
-- TypeScript strict mode. Both apps share `tsconfig.base.json`.
-- Server uses NodeNext module resolution (`.js` extensions in imports).
+- TypeScript strict mode. Both apps share `tsconfig.base.json`. Server + coder use NodeNext module resolution (`.js` extensions in imports).
 - Discriminated unions for type narrowing: `Pane` (by `kind`), `SessionEvent` (by `type`), `InferenceFrame` (by `type`).
-- **Adding a new WS frame type** requires updating BOTH the server's `InferenceFrame` (loose `type:` union + optional fields in `services/inference/turn.ts`) AND the web `WsFrame` (strict discriminated union in `apps/web/src/api/types.ts`). Server publish is permissive; the frontend type is the wire-format gate. The `'usage'` frame added in v1.12.2 needed both sides; missing the web side silently drops the frame at JSON-parse.
-- shadcn primitives live in `components/ui/`. Don't modify them unless adding a new primitive.
-- `ui/` primitives present: button, card, context-menu, dialog, dropdown-menu, input, label, radio-group, sonner, textarea. No switch/sheet/drawer/badge/checkbox — use a `<button role="switch" aria-checked>` toggle (a hand-rolled `Switch` already lives in `SettingsPane.tsx`) and a Dialog-based panel for "drawers".
-- `inferLanguage()` from `lib/attachments.ts` is the canonical file-extension-to-language map. `CodeBlock.tsx` keeps its own `LANG_MAP` because it also resolves markdown fence names.
-- Two UI event buses: `hooks/sessionEvents.ts` for DB-state events (chat_created, session_updated); `lib/events.ts` for ephemeral UI (`sendToTerminal`, `terminalsRegistry`). Don't merge — different subscriber lifecycles.
-- `vite.config.ts` proxy entries are order-sensitive: more-specific prefixes (`/api/term`, `/ws/term`) must come BEFORE `/api`.
-- Mobile pane URL sync (`Session.tsx`): the `?pane=<id>` effect resets `activePaneIdx` whenever `panes` changes. New-pane creation on mobile must push `?pane=` atomically — `addPaneAndSwitch` is the wrapper that does this. `addSplitPane` returns the new pane id for callers.
-- A scrollable list inside a Dialog on mobile: cap `DialogContent` (`max-h-[85vh]` + `grid-rows-[auto_minmax(0,1fr)_auto]`) and make the list the single scroll region with `overscroll-contain` — otherwise touch-scroll drags the whole fixed modal / chains to the page.
-- xterm.js v5 uses canvas rendering — browser doesn't see xterm's selection; the native right-click menu has no working Copy for terminal text. App keybindings (`Cmd/Ctrl-C`, `Cmd/Ctrl-Shift-C`) are the path.
-- **New tools** live in their own `services/<name>.ts` file (see `web_search.ts`, `web_fetch.ts`) — exports a pure `executeFoo(input, ...deps)` for direct test access plus a `ToolDef` wrapper that `loadConfig()`s its real dependencies. Register the ToolDef in `tools.ts` `ALL_TOOLS` (and `READ_ONLY_TOOL_NAMES` if applicable). Inject `fetcher: typeof fetch = fetch` rather than `vi.spyOn(globalThis, 'fetch')` — cleanup is simpler and the production call site stays unchanged.
-- **DB/session-aware tools** take an optional 4th `ToolExecCtx { sql, sessionId }` arg on `ToolDef.execute`, plumbed `executeToolPhase`→`executeToolCall`→`execute`. It's optional so the filesystem tools and the `apps/coder` `ALL_TOOLS` consumer stay compatible; filesystem tools ignore it. `read_tab_by_number` (reads `sessions.workspace_panes` + the chat's messages via `sql`) is the reference.
-- **Sentinels** are `role='system'` rows with structured `metadata.kind` (`cap_hit`, `doom_loop`). UI-only — `buildMessagesPayload` strips them via `isAnySentinel` so the LLM never sees them. A new kind requires arms in `MessageMetadata` in BOTH `apps/server/src/types/api.ts` AND `apps/web/src/api/types.ts`, plus a render branch in `apps/web/src/components/MessageBubble.tsx`.
-- **ReadableStream test stubs** use `pull()` (not `start()`) so chunks are produced lazily — `start()` enqueues everything and calls `controller.close()` before the consumer reads, so a subsequent `reader.cancel()` finds the stream already closed and the `cancel()` callback never fires. Also provide MORE chunks than the test will consume so the source stays in 'readable' state when cancel runs (e.g. cap test reads ~6 chunks, stub provides 10).
-- React **StrictMode is on** (`main.tsx`): an updater passed to one `setState` that itself calls another `setState` (e.g. `setClosedPaneStack` inside a `setPanes` updater) is double-invoked in dev. Make such nested updates idempotent — `useWorkspacePanes`'s `appendClosed` dedupes a value-identical top entry for exactly this reason.
-- 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.
-- `data/AGENTS.md` is PARSED (`agents.ts` `splitSections`/`parseAgentSection`): each `## <Name>` is one agent and must be followed by a `---` frontmatter fence or the block throws; content before the first `## ` is discarded. Do NOT add free-form `## ` rule sections — they break the registry. Cross-cutting agent rules go in CLAUDE.md or a parser-ignored preamble.
-- Skills live in `data/skills/<vendor>/`; Sam's own namespace is `boocode/` (`committing-changes`, `using-worktrees`, `improving-boocode-guidance`) — `SKILL.md` + optional `eval.yaml` (gerund names; eval = `skill:` + `tasks:` of `prompt`+`grader`, incl. a negative-trigger task). `data/skills/` is canonical; a divergent mirror at `/opt/skills/` exists.
-- 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.
-- **JSONB columns**: use `sql.json(value as never)` — NOT `${JSON.stringify(value)}::jsonb` which double-serializes (stores a JSON string instead of a JSON object/array). Pattern established in `parts.ts`, `settings.ts`.
-- **`payload.ts:loadContext` SELECT**: must include every `Session` field that downstream code reads. The tool phase reads `session.allowed_read_paths`; if the SELECT omits it, cross-repo read grants silently fail. The `Session` TypeScript type doesn't catch this because `sql<Session[]>` doesn't enforce column coverage.
-- **Sidecar routing** (`services/inference/provider.ts`): `upstreamModel(config, modelId, agent)` routes to `LLAMA_SIDECAR_URL` when agent has `llama_extra_args`, otherwise `LLAMA_SWAP_URL`. `resolveRoute(agent)` returns `{route: 'swap'|'sidecar', flags}`. Sidecar provider created fresh per call (not cached) because `X-Agent-Flags` header varies per agent. Boot-time guard in `index.ts` refuses to start if any agent has `llama_extra_args` but `LLAMA_SIDECAR_URL` is unset.
-- **Secret guard safe patterns** (`services/secret_guard.ts`): `.env.example`, `.env.sample`, `.env.template`, `.env.defaults` are allowlisted via `SAFE_PATTERNS` set. Do NOT add `.env.production`/`.env.development`/`.env.test` — those can hold real secrets.
-- **CoderPane uses ChatInput** (`components/panes/CoderPane.tsx`): shares the same `ChatInput` component as BooChat for full parity — attachments, paste-to-chip, auto-grow textarea, queued messages during send. CoderPane's `sendOneMessage` is the send callback; queued messages drain via `useEffect` when `sending` goes false.
-- **Adding a new `SessionEvent` type**: add the interface, add it to the `SessionEvent` union, add a `case` in `useSidebar.ts` `applyEvent` switch (no-op `return prev` is fine), and subscribe in any hook that needs it (e.g. `useSessionStream` for `refetch_messages`).
-- **BooCoder provider registry** (`apps/coder/src/services/provider-registry.ts`): static list of provider defs (boocode, opencode, goose, claude, qwen). `PROBED_AGENT_NAMES` derives from it. Adding/removing providers means editing this file, not the frontend.
-- **AgentComposerBar filters `e.installed`**: provider snapshot entries with `installed:false` (loading/unavailable) are dropped from the dropdown. `getProviderSnapshot` must await the full build — returning synchronous `loading` placeholders makes every provider vanish (the v2.5.7 "no providers showing up" regression); surfacing loading states needs a client poll.
-- **Coder↔web provider-type parity** (`apps/coder/src/services/provider-types.ts` ↔ `apps/web/src/api/types.ts`): enforced by runtime `provider-types-parity.test.ts` (compile-time cross-import is blocked by TS6307 on web's composite tsconfig). Mirror of the ws-frames parity pattern — edit both copies together or the test fails.
-- **ACP command discovery is async**: `acp-probe.ts` must poll after `newSession` for `available_commands_update` (commands arrive in a later notification; reading synchronously captures 0). PTY providers (claude) instead discover from disk via `claude-command-discovery.ts` (`~/.claude/commands` + `enabledPlugins` `skills/`+`commands/`, bare names, deduped). `AgentCommand.kind` tags `'command'` vs `'skill'`; `CoderPane`'s `slashGroups` splits them into icon'd groups. `SlashCommandPicker`'s `groups?` prop is opt-in — BooChat passes flat `items` (unchanged).
-- **Pane header architecture (mobile vs desktop)**: Desktop coder pane header (BooCode label + [+] [×]) lives in `Workspace.tsx` gated by `isCoder && !isMobile`. Mobile coder controls (● ×) live in `Session.tsx` header row next to `MobileTabSwitcher`/`NewPaneMenu`. `AgentComposerBar` (provider/mode/model pickers) renders inside `CoderPane.tsx` on both. The ● status dot is passed via `connected` prop from CoderPane to AgentComposerBar.
-- **MessageBubble shared between BooChat and BooCoder** (`components/MessageBubble.tsx`): accepts optional `actions?: MessageActions` callbacks (onRegenerate, onResend, onFork, onDelete) and `hideActions?: ('fork'|'delete'|'openInPane')[]`. Defaults use BooChat API; CoderPane overrides via `CoderMessageList` props. `CoderTextBubble` was removed. **`CoderMessageList` passes `CoderMessageWire as unknown as Message`** — the coder wire shape lacks `metadata`/`kind`/`summary`, so those fields are `undefined` (not `null`) on coder messages. Null-guards on any `Message` field MUST use loose `!= null`, not strict `!== null` (`undefined !== null` is `true` → `.kind` throws → blank-screen crash). The `as unknown as` cast hides this from tsc; build + typecheck pass while runtime crashes.
-- **llama-sidecar** (`/opt/forks/llama-sidecar/`): Go daemon for per-agent llama-server process pool. Cross-compile: `GOOS=windows GOARCH=amd64 /snap/go/current/bin/go build -o bin/llama-sidecar.exe ./cmd/llama-sidecar`. Gitea: `indifferentketchup/llama-sidecar`. Windows child process gotchas: use `context.Background()` for child lifetime (not request ctx), `os.Open(os.DevNull)` for stdin, `os.Pipe()` for stdout with drain goroutine, `DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP` creation flags. SSH to sam-desktop: `ssh samki@100.101.41.16`; use `schtasks` for persistent process spawning (SSH `start /B` doesn't survive session close).
+- **Adding a new WS frame type** (cross-app) requires updating BOTH the server's `InferenceFrame` (loose `type:` union + optional fields in `services/inference/turn.ts`) AND the web `WsFrame` (strict discriminated union in `apps/web/src/api/types.ts`). Server publish is permissive; the frontend type is the wire-format gate — missing the web side silently drops the frame at JSON-parse.
+- **Sentinels** (cross-app) are `role='system'` rows with structured `metadata.kind` (`cap_hit`, `doom_loop`). UI-only — `buildMessagesPayload` strips them via `isAnySentinel` so the LLM never sees them. A new kind requires arms in `MessageMetadata` in BOTH `apps/server/src/types/api.ts` AND `apps/web/src/api/types.ts`, plus a render branch in `apps/web/src/components/MessageBubble.tsx`.
+- **Coder↔web provider-type parity** (`apps/coder/src/services/provider-types.ts` ↔ `apps/web/src/api/types.ts`): enforced by runtime `provider-types-parity.test.ts` (compile-time cross-import is blocked by TS6307 on web's composite tsconfig). Mirror of the ws-frames parity pattern — edit both copies together.
+- **JSONB columns**: use `sql.json(value as never)` — NOT `${JSON.stringify(value)}::jsonb` which double-serializes (stores a JSON string instead of an object/array). Pattern in `parts.ts`, `settings.ts`.
+- Skills live in `data/skills/<vendor>/`; Sam's own namespace is `boocode/` (`committing-changes`, `using-worktrees`, `improving-boocode-guidance`, `systematic-debugging`) — `SKILL.md` + optional `eval.yaml` (gerund names; eval = `skill:` + `tasks:` of `prompt`+`grader`, incl. a negative-trigger task). `data/skills/` is canonical; a divergent mirror at `/opt/skills/` exists.
+
+### Coding standards
+
+Coding standards live in `docs/coding-standards/` (canonical, human-readable). They are exposed to Claude Code through per-file-type/subsystem index files under `.claude/rules/coding-standards/`. Each index is a path-scoped rule that lists the standards relevant to its `paths:` glob with a one-line description of each. When Claude reads a file matching an index's `paths:`, it loads only that small index and then decides which (if any) standards to open with Read — the full text of a standard is never loaded automatically, and standards do not appear in the skills picker. Browse `docs/coding-standards/` for the readable form.

CURRENT.md

@@ -1,10 +1,9 @@
 # Current focus
 
-Last updated: 2026-05-26
+Last updated: 2026-06-02
 
-- **Batch:** v2.3-provider-lifecycle (openspec drafted; not started)
-- **Branch:** `main`
-- **Blockers:** none
-- **Last shipped:** `v2.2.2-xml-placeholder-reject`
+- **Last shipped:** `v2.7.8-ember-coder-tabs-model-chips` (2026-06-01)
+- **Branch:** `codebase-audit-cleanup` (audit + cleanup epic, off main HEAD)
+- **In progress:** Phase 3 — stale comments + docs refresh
 
-Update this file when starting or finishing a batch. Agents: read this first for session intent; if stale vs `CHANGELOG.md`, trust CHANGELOG for shipped state.
+See `CHANGELOG.md` for the full shipped history. That file is always authoritative; this file is a quick orientation pointer only.

LICENSE

@@ -1,661 +1,21 @@
-                    GNU AFFERO GENERAL PUBLIC LICENSE
-                       Version 3, 19 November 2007
-
- Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
-                            Preamble
-
-  The GNU Affero General Public License is a free, copyleft license for
-software and other kinds of works, specifically designed to ensure
-cooperation with the community in the case of network server software.
-
-  The licenses for most software and other practical works are designed
-to take away your freedom to share and change the works.  By contrast,
-our General Public Licenses are intended to guarantee your freedom to
-share and change all versions of a program--to make sure it remains free
-software for all its users.
-
-  When we speak of free software, we are referring to freedom, not
-price.  Our General Public Licenses are designed to make sure that you
-have the freedom to distribute copies of free software (and charge for
-them if you wish), that you receive source code or can get it if you
-want it, that you can change the software or use pieces of it in new
-free programs, and that you know you can do these things.
-
-  Developers that use our General Public Licenses protect your rights
-with two steps: (1) assert copyright on the software, and (2) offer
-you this License which gives you legal permission to copy, distribute
-and/or modify the software.
-
-  A secondary benefit of defending all users' freedom is that
-improvements made in alternate versions of the program, if they
-receive widespread use, become available for other developers to
-incorporate.  Many developers of free software are heartened and
-encouraged by the resulting cooperation.  However, in the case of
-software used on network servers, this result may fail to come about.
-The GNU General Public License permits making a modified version and
-letting the public access it on a server without ever releasing its
-source code to the public.
-
-  The GNU Affero General Public License is designed specifically to
-ensure that, in such cases, the modified source code becomes available
-to the community.  It requires the operator of a network server to
-provide the source code of the modified version running there to the
-users of that server.  Therefore, public use of a modified version, on
-a publicly accessible server, gives the public access to the source
-code of the modified version.
-
-  An older license, called the Affero General Public License and
-published by Affero, was designed to accomplish similar goals.  This is
-a different license, not a version of the Affero GPL, but Affero has
-released a new version of the Affero GPL which permits relicensing under
-this license.
-
-  The precise terms and conditions for copying, distribution and
-modification follow.
-
-                       TERMS AND CONDITIONS
-
-  0. Definitions.
-
-  "This License" refers to version 3 of the GNU Affero General Public License.
-
-  "Copyright" also means copyright-like laws that apply to other kinds of
-works, such as semiconductor masks.
-
-  "The Program" refers to any copyrightable work licensed under this
-License.  Each licensee is addressed as "you".  "Licensees" and
-"recipients" may be individuals or organizations.
-
-  To "modify" a work means to copy from or adapt all or part of the work
-in a fashion requiring copyright permission, other than the making of an
-exact copy.  The resulting work is called a "modified version" of the
-earlier work or a work "based on" the earlier work.
-
-  A "covered work" means either the unmodified Program or a work based
-on the Program.
-
-  To "propagate" a work means to do anything with it that, without
-permission, would make you directly or secondarily liable for
-infringement under applicable copyright law, except executing it on a
-computer or modifying a private copy.  Propagation includes copying,
-distribution (with or without modification), making available to the
-public, and in some countries other activities as well.
-
-  To "convey" a work means any kind of propagation that enables other
-parties to make or receive copies.  Mere interaction with a user through
-a computer network, with no transfer of a copy, is not conveying.
-
-  An interactive user interface displays "Appropriate Legal Notices"
-to the extent that it includes a convenient and prominently visible
-feature that (1) displays an appropriate copyright notice, and (2)
-tells the user that there is no warranty for the work (except to the
-extent that warranties are provided), that licensees may convey the
-work under this License, and how to view a copy of this License.  If
-the interface presents a list of user commands or options, such as a
-menu, a prominent item in the list meets this criterion.
-
-  1. Source Code.
-
-  The "source code" for a work means the preferred form of the work
-for making modifications to it.  "Object code" means any non-source
-form of a work.
-
-  A "Standard Interface" means an interface that either is an official
-standard defined by a recognized standards body, or, in the case of
-interfaces specified for a particular programming language, one that
-is widely used among developers working in that language.
-
-  The "System Libraries" of an executable work include anything, other
-than the work as a whole, that (a) is included in the normal form of
-packaging a Major Component, but which is not part of that Major
-Component, and (b) serves only to enable use of the work with that
-Major Component, or to implement a Standard Interface for which an
-implementation is available to the public in source code form.  A
-"Major Component", in this context, means a major essential component
-(kernel, window system, and so on) of the specific operating system
-(if any) on which the executable work runs, or a compiler used to
-produce the work, or an object code interpreter used to run it.
-
-  The "Corresponding Source" for a work in object code form means all
-the source code needed to generate, install, and (for an executable
-work) run the object code and to modify the work, including scripts to
-control those activities.  However, it does not include the work's
-System Libraries, or general-purpose tools or generally available free
-programs which are used unmodified in performing those activities but
-which are not part of the work.  For example, Corresponding Source
-includes interface definition files associated with source files for
-the work, and the source code for shared libraries and dynamically
-linked subprograms that the work is specifically designed to require,
-such as by intimate data communication or control flow between those
-subprograms and other parts of the work.
-
-  The Corresponding Source need not include anything that users
-can regenerate automatically from other parts of the Corresponding
-Source.
-
-  The Corresponding Source for a work in source code form is that
-same work.
-
-  2. Basic Permissions.
-
-  All rights granted under this License are granted for the term of
-copyright on the Program, and are irrevocable provided the stated
-conditions are met.  This License explicitly affirms your unlimited
-permission to run the unmodified Program.  The output from running a
-covered work is covered by this License only if the output, given its
-content, constitutes a covered work.  This License acknowledges your
-rights of fair use or other equivalent, as provided by copyright law.
-
-  You may make, run and propagate covered works that you do not
-convey, without conditions so long as your license otherwise remains
-in force.  You may convey covered works to others for the sole purpose
-of having them make modifications exclusively for you, or provide you
-with facilities for running those works, provided that you comply with
-the terms of this License in conveying all material for which you do
-not control copyright.  Those thus making or running the covered works
-for you must do so exclusively on your behalf, under your direction
-and control, on terms that prohibit them from making any copies of
-your copyrighted material outside their relationship with you.
-
-  Conveying under any other circumstances is permitted solely under
-the conditions stated below.  Sublicensing is not allowed; section 10
-makes it unnecessary.
-
-  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
-
-  No covered work shall be deemed part of an effective technological
-measure under any applicable law fulfilling obligations under article
-11 of the WIPO copyright treaty adopted on 20 December 1996, or
-similar laws prohibiting or restricting circumvention of such
-measures.
-
-  When you convey a covered work, you waive any legal power to forbid
-circumvention of technological measures to the extent such circumvention
-is effected by exercising rights under this License with respect to
-the covered work, and you disclaim any intention to limit operation or
-modification of the work as a means of enforcing, against the work's
-users, your or third parties' legal rights to forbid circumvention of
-technological measures.
-
-  4. Conveying Verbatim Copies.
-
-  You may convey verbatim copies of the Program's source code as you
-receive it, in any medium, provided that you conspicuously and
-appropriately publish on each copy an appropriate copyright notice;
-keep intact all notices stating that this License and any
-non-permissive terms added in accord with section 7 apply to the code;
-keep intact all notices of the absence of any warranty; and give all
-recipients a copy of this License along with the Program.
-
-  You may charge any price or no price for each copy that you convey,
-and you may offer support or warranty protection for a fee.
-
-  5. Conveying Modified Source Versions.
-
-  You may convey a work based on the Program, or the modifications to
-produce it from the Program, in the form of source code under the
-terms of section 4, provided that you also meet all of these conditions:
-
-    a) The work must carry prominent notices stating that you modified
-    it, and giving a relevant date.
-
-    b) The work must carry prominent notices stating that it is
-    released under this License and any conditions added under section
-    7.  This requirement modifies the requirement in section 4 to
-    "keep intact all notices".
-
-    c) You must license the entire work, as a whole, under this
-    License to anyone who comes into possession of a copy.  This
-    License will therefore apply, along with any applicable section 7
-    additional terms, to the whole of the work, and all its parts,
-    regardless of how they are packaged.  This License gives no
-    permission to license the work in any other way, but it does not
-    invalidate such permission if you have separately received it.
-
-    d) If the work has interactive user interfaces, each must display
-    Appropriate Legal Notices; however, if the Program has interactive
-    interfaces that do not display Appropriate Legal Notices, your
-    work need not make them do so.
-
-  A compilation of a covered work with other separate and independent
-works, which are not by their nature extensions of the covered work,
-and which are not combined with it such as to form a larger program,
-in or on a volume of a storage or distribution medium, is called an
-"aggregate" if the compilation and its resulting copyright are not
-used to limit the access or legal rights of the compilation's users
-beyond what the individual works permit.  Inclusion of a covered work
-in an aggregate does not cause this License to apply to the other
-parts of the aggregate.
-
-  6. Conveying Non-Source Forms.
-
-  You may convey a covered work in object code form under the terms
-of sections 4 and 5, provided that you also convey the
-machine-readable Corresponding Source under the terms of this License,
-in one of these ways:
-
-    a) Convey the object code in, or embodied in, a physical product
-    (including a physical distribution medium), accompanied by the
-    Corresponding Source fixed on a durable physical medium
-    customarily used for software interchange.
-
-    b) Convey the object code in, or embodied in, a physical product
-    (including a physical distribution medium), accompanied by a
-    written offer, valid for at least three years and valid for as
-    long as you offer spare parts or customer support for that product
-    model, to give anyone who possesses the object code either (1) a
-    copy of the Corresponding Source for all the software in the
-    product that is covered by this License, on a durable physical
-    medium customarily used for software interchange, for a price no
-    more than your reasonable cost of physically performing this
-    conveying of source, or (2) access to copy the
-    Corresponding Source from a network server at no charge.
-
-    c) Convey individual copies of the object code with a copy of the
-    written offer to provide the Corresponding Source.  This
-    alternative is allowed only occasionally and noncommercially, and
-    only if you received the object code with such an offer, in accord
-    with subsection 6b.
-
-    d) Convey the object code by offering access from a designated
-    place (gratis or for a charge), and offer equivalent access to the
-    Corresponding Source in the same way through the same place at no
-    further charge.  You need not require recipients to copy the
-    Corresponding Source along with the object code.  If the place to
-    copy the object code is a network server, the Corresponding Source
-    may be on a different server (operated by you or a third party)
-    that supports equivalent copying facilities, provided you maintain
-    clear directions next to the object code saying where to find the
-    Corresponding Source.  Regardless of what server hosts the
-    Corresponding Source, you remain obligated to ensure that it is
-    available for as long as needed to satisfy these requirements.
-
-    e) Convey the object code using peer-to-peer transmission, provided
-    you inform other peers where the object code and Corresponding
-    Source of the work are being offered to the general public at no
-    charge under subsection 6d.
-
-  A separable portion of the object code, whose source code is excluded
-from the Corresponding Source as a System Library, need not be
-included in conveying the object code work.
-
-  A "User Product" is either (1) a "consumer product", which means any
-tangible personal property which is normally used for personal, family,
-or household purposes, or (2) anything designed or sold for incorporation
-into a dwelling.  In determining whether a product is a consumer product,
-doubtful cases shall be resolved in favor of coverage.  For a particular
-product received by a particular user, "normally used" refers to a
-typical or common use of that class of product, regardless of the status
-of the particular user or of the way in which the particular user
-actually uses, or expects or is expected to use, the product.  A product
-is a consumer product regardless of whether the product has substantial
-commercial, industrial or non-consumer uses, unless such uses represent
-the only significant mode of use of the product.
-
-  "Installation Information" for a User Product means any methods,
-procedures, authorization keys, or other information required to install
-and execute modified versions of a covered work in that User Product from
-a modified version of its Corresponding Source.  The information must
-suffice to ensure that the continued functioning of the modified object
-code is in no case prevented or interfered with solely because
-modification has been made.
-
-  If you convey an object code work under this section in, or with, or
-specifically for use in, a User Product, and the conveying occurs as
-part of a transaction in which the right of possession and use of the
-User Product is transferred to the recipient in perpetuity or for a
-fixed term (regardless of how the transaction is characterized), the
-Corresponding Source conveyed under this section must be accompanied
-by the Installation Information.  But this requirement does not apply
-if neither you nor any third party retains the ability to install
-modified object code on the User Product (for example, the work has
-been installed in ROM).
-
-  The requirement to provide Installation Information does not include a
-requirement to continue to provide support service, warranty, or updates
-for a work that has been modified or installed by the recipient, or for
-the User Product in which it has been modified or installed.  Access to a
-network may be denied when the modification itself materially and
-adversely affects the operation of the network or violates the rules and
-protocols for communication across the network.
-
-  Corresponding Source conveyed, and Installation Information provided,
-in accord with this section must be in a format that is publicly
-documented (and with an implementation available to the public in
-source code form), and must require no special password or key for
-unpacking, reading or copying.
-
-  7. Additional Terms.
-
-  "Additional permissions" are terms that supplement the terms of this
-License by making exceptions from one or more of its conditions.
-Additional permissions that are applicable to the entire Program shall
-be treated as though they were included in this License, to the extent
-that they are valid under applicable law.  If additional permissions
-apply only to part of the Program, that part may be used separately
-under those permissions, but the entire Program remains governed by
-this License without regard to the additional permissions.
-
-  When you convey a copy of a covered work, you may at your option
-remove any additional permissions from that copy, or from any part of
-it.  (Additional permissions may be written to require their own
-removal in certain cases when you modify the work.)  You may place
-additional permissions on material, added by you to a covered work,
-for which you have or can give appropriate copyright permission.
-
-  Notwithstanding any other provision of this License, for material you
-add to a covered work, you may (if authorized by the copyright holders of
-that material) supplement the terms of this License with terms:
-
-    a) Disclaiming warranty or limiting liability differently from the
-    terms of sections 15 and 16 of this License; or
-
-    b) Requiring preservation of specified reasonable legal notices or
-    author attributions in that material or in the Appropriate Legal
-    Notices displayed by works containing it; or
-
-    c) Prohibiting misrepresentation of the origin of that material, or
-    requiring that modified versions of such material be marked in
-    reasonable ways as different from the original version; or
-
-    d) Limiting the use for publicity purposes of names of licensors or
-    authors of the material; or
-
-    e) Declining to grant rights under trademark law for use of some
-    trade names, trademarks, or service marks; or
-
-    f) Requiring indemnification of licensors and authors of that
-    material by anyone who conveys the material (or modified versions of
-    it) with contractual assumptions of liability to the recipient, for
-    any liability that these contractual assumptions directly impose on
-    those licensors and authors.
-
-  All other non-permissive additional terms are considered "further
-restrictions" within the meaning of section 10.  If the Program as you
-received it, or any part of it, contains a notice stating that it is
-governed by this License along with a term that is a further
-restriction, you may remove that term.  If a license document contains
-a further restriction but permits relicensing or conveying under this
-License, you may add to a covered work material governed by the terms
-of that license document, provided that the further restriction does
-not survive such relicensing or conveying.
-
-  If you add terms to a covered work in accord with this section, you
-must place, in the relevant source files, a statement of the
-additional terms that apply to those files, or a notice indicating
-where to find the applicable terms.
-
-  Additional terms, permissive or non-permissive, may be stated in the
-form of a separately written license, or stated as exceptions;
-the above requirements apply either way.
-
-  8. Termination.
-
-  You may not propagate or modify a covered work except as expressly
-provided under this License.  Any attempt otherwise to propagate or
-modify it is void, and will automatically terminate your rights under
-this License (including any patent licenses granted under the third
-paragraph of section 11).
-
-  However, if you cease all violation of this License, then your
-license from a particular copyright holder is reinstated (a)
-provisionally, unless and until the copyright holder explicitly and
-finally terminates your license, and (b) permanently, if the copyright
-holder fails to notify you of the violation by some reasonable means
-prior to 60 days after the cessation.
-
-  Moreover, your license from a particular copyright holder is
-reinstated permanently if the copyright holder notifies you of the
-violation by some reasonable means, this is the first time you have
-received notice of violation of this License (for any work) from that
-copyright holder, and you cure the violation prior to 30 days after
-your receipt of the notice.
-
-  Termination of your rights under this section does not terminate the
-licenses of parties who have received copies or rights from you under
-this License.  If your rights have been terminated and not permanently
-reinstated, you do not qualify to receive new licenses for the same
-material under section 10.
-
-  9. Acceptance Not Required for Having Copies.
-
-  You are not required to accept this License in order to receive or
-run a copy of the Program.  Ancillary propagation of a covered work
-occurring solely as a consequence of using peer-to-peer transmission
-to receive a copy likewise does not require acceptance.  However,
-nothing other than this License grants you permission to propagate or
-modify any covered work.  These actions infringe copyright if you do
-not accept this License.  Therefore, by modifying or propagating a
-covered work, you indicate your acceptance of this License to do so.
-
-  10. Automatic Licensing of Downstream Recipients.
-
-  Each time you convey a covered work, the recipient automatically
-receives a license from the original licensors, to run, modify and
-propagate that work, subject to this License.  You are not responsible
-for enforcing compliance by third parties with this License.
-
-  An "entity transaction" is a transaction transferring control of an
-organization, or substantially all assets of one, or subdividing an
-organization, or merging organizations.  If propagation of a covered
-work results from an entity transaction, each party to that
-transaction who receives a copy of the work also receives whatever
-licenses to the work the party's predecessor in interest had or could
-give under the previous paragraph, plus a right to possession of the
-Corresponding Source of the work from the predecessor in interest, if
-the predecessor has it or can get it with reasonable efforts.
-
-  You may not impose any further restrictions on the exercise of the
-rights granted or affirmed under this License.  For example, you may
-not impose a license fee, royalty, or other charge for exercise of
-rights granted under this License, and you may not initiate litigation
-(including a cross-claim or counterclaim in a lawsuit) alleging that
-any patent claim is infringed by making, using, selling, offering for
-sale, or importing the Program or any portion of it.
-
-  11. Patents.
-
-  A "contributor" is a copyright holder who authorizes use under this
-License of the Program or a work on which the Program is based.  The
-work thus licensed is called the contributor's "contributor version".
-
-  A contributor's "essential patent claims" are all patent claims
-owned or controlled by the contributor, whether already acquired or
-hereafter acquired, that would be infringed by some manner, permitted
-by this License, of making, using, or selling its contributor version,
-but do not include claims that would be infringed only as a
-consequence of further modification of the contributor version.  For
-purposes of this definition, "control" includes the right to grant
-patent sublicenses in a manner consistent with the requirements of
-this License.
-
-  Each contributor grants you a non-exclusive, worldwide, royalty-free
-patent license under the contributor's essential patent claims, to
-make, use, sell, offer for sale, import and otherwise run, modify and
-propagate the contents of its contributor version.
-
-  In the following three paragraphs, a "patent license" is any express
-agreement or commitment, however denominated, not to enforce a patent
-(such as an express permission to practice a patent or covenant not to
-sue for patent infringement).  To "grant" such a patent license to a
-party means to make such an agreement or commitment not to enforce a
-patent against the party.
-
-  If you convey a covered work, knowingly relying on a patent license,
-and the Corresponding Source of the work is not available for anyone
-to copy, free of charge and under the terms of this License, through a
-publicly available network server or other readily accessible means,
-then you must either (1) cause the Corresponding Source to be so
-available, or (2) arrange to deprive yourself of the benefit of the
-patent license for this particular work, or (3) arrange, in a manner
-consistent with the requirements of this License, to extend the patent
-license to downstream recipients.  "Knowingly relying" means you have
-actual knowledge that, but for the patent license, your conveying the
-covered work in a country, or your recipient's use of the covered work
-in a country, would infringe one or more identifiable patents in that
-country that you have reason to believe are valid.
-
-  If, pursuant to or in connection with a single transaction or
-arrangement, you convey, or propagate by procuring conveyance of, a
-covered work, and grant a patent license to some of the parties
-receiving the covered work authorizing them to use, propagate, modify
-or convey a specific copy of the covered work, then the patent license
-you grant is automatically extended to all recipients of the covered
-work and works based on it.
-
-  A patent license is "discriminatory" if it does not include within
-the scope of its coverage, prohibits the exercise of, or is
-conditioned on the non-exercise of one or more of the rights that are
-specifically granted under this License.  You may not convey a covered
-work if you are a party to an arrangement with a third party that is
-in the business of distributing software, under which you make payment
-to the third party based on the extent of your activity of conveying
-the work, and under which the third party grants, to any of the
-parties who would receive the covered work from you, a discriminatory
-patent license (a) in connection with copies of the covered work
-conveyed by you (or copies made from those copies), or (b) primarily
-for and in connection with specific products or compilations that
-contain the covered work, unless you entered into that arrangement,
-or that patent license was granted, prior to 28 March 2007.
-
-  Nothing in this License shall be construed as excluding or limiting
-any implied license or other defenses to infringement that may
-otherwise be available to you under applicable patent law.
-
-  12. No Surrender of Others' Freedom.
-
-  If conditions are imposed on you (whether by court order, agreement or
-otherwise) that contradict the conditions of this License, they do not
-excuse you from the conditions of this License.  If you cannot convey a
-covered work so as to satisfy simultaneously your obligations under this
-License and any other pertinent obligations, then as a consequence you may
-not convey it at all.  For example, if you agree to terms that obligate you
-to collect a royalty for further conveying from those to whom you convey
-the Program, the only way you could satisfy both those terms and this
-License would be to refrain entirely from conveying the Program.
-
-  13. Remote Network Interaction; Use with the GNU General Public License.
-
-  Notwithstanding any other provision of this License, if you modify the
-Program, your modified version must prominently offer all users
-interacting with it remotely through a computer network (if your version
-supports such interaction) an opportunity to receive the Corresponding
-Source of your version by providing access to the Corresponding Source
-from a network server at no charge, through some standard or customary
-means of facilitating copying of software.  This Corresponding Source
-shall include the Corresponding Source for any work covered by version 3
-of the GNU General Public License that is incorporated pursuant to the
-following paragraph.
-
-  Notwithstanding any other provision of this License, you have
-permission to link or combine any covered work with a work licensed
-under version 3 of the GNU General Public License into a single
-combined work, and to convey the resulting work.  The terms of this
-License will continue to apply to the part which is the covered work,
-but the work with which it is combined will remain governed by version
-3 of the GNU General Public License.
-
-  14. Revised Versions of this License.
-
-  The Free Software Foundation may publish revised and/or new versions of
-the GNU Affero General Public License from time to time.  Such new versions
-will be similar in spirit to the present version, but may differ in detail to
-address new problems or concerns.
-
-  Each version is given a distinguishing version number.  If the
-Program specifies that a certain numbered version of the GNU Affero General
-Public License "or any later version" applies to it, you have the
-option of following the terms and conditions either of that numbered
-version or of any later version published by the Free Software
-Foundation.  If the Program does not specify a version number of the
-GNU Affero General Public License, you may choose any version ever published
-by the Free Software Foundation.
-
-  If the Program specifies that a proxy can decide which future
-versions of the GNU Affero General Public License can be used, that proxy's
-public statement of acceptance of a version permanently authorizes you
-to choose that version for the Program.
-
-  Later license versions may give you additional or different
-permissions.  However, no additional obligations are imposed on any
-author or copyright holder as a result of your choosing to follow a
-later version.
-
-  15. Disclaimer of Warranty.
-
-  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
-APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
-HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
-OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
-THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
-IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
-ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
-
-  16. Limitation of Liability.
-
-  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
-WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
-THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
-GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
-USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
-DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
-PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
-EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
-SUCH DAMAGES.
-
-  17. Interpretation of Sections 15 and 16.
-
-  If the disclaimer of warranty and limitation of liability provided
-above cannot be given local legal effect according to their terms,
-reviewing courts shall apply local law that most closely approximates
-an absolute waiver of all civil liability in connection with the
-Program, unless a warranty or assumption of liability accompanies a
-copy of the Program in return for a fee.
-
-                     END OF TERMS AND CONDITIONS
-
-            How to Apply These Terms to Your New Programs
-
-  If you develop a new program, and you want it to be of the greatest
-possible use to the public, the best way to achieve this is to make it
-free software which everyone can redistribute and change under these terms.
-
-  To do so, attach the following notices to the program.  It is safest
-to attach them to the start of each source file to most effectively
-state the exclusion of warranty; and each file should have at least
-the "copyright" line and a pointer to where the full notice is found.
-
-    <one line to give the program's name and a brief idea of what it does.>
-    Copyright (C) <year>  <name of author>
-
-    This program is free software: you can redistribute it and/or modify
-    it under the terms of the GNU Affero General Public License as published by
-    the Free Software Foundation, either version 3 of the License, or
-    (at your option) any later version.
-
-    This program is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU Affero General Public License for more details.
-
-    You should have received a copy of the GNU Affero General Public License
-    along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
-Also add information on how to contact you by electronic and paper mail.
-
-  If your software can interact with users remotely through a computer
-network, you should also make sure that it provides a way for users to
-get its source.  For example, if your program is a web application, its
-interface could display a "Source" link that leads users to an archive
-of the code.  There are many ways you could offer source, and different
-solutions will be better for different programs; see section 13 for the
-specific requirements.
-
-  You should also get your employer (if you work as a programmer) or school,
-if any, to sign a "copyright disclaimer" for the program, if necessary.
-For more information on this, and how to apply and follow the GNU AGPL, see
-<https://www.gnu.org/licenses/>.
+MIT License
+
+Copyright (c) 2026 indifferentketchup
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -84,3 +84,7 @@ See [`boocode_roadmap.md`](boocode_roadmap.md) for full version history. Highlig
 ## Planned
 
 - **v2.3 provider lifecycle** — config-backed provider registry (`/data/coder-providers.json`), enable/disable toggles, two-tier probe (openspec drafted). See [`CURRENT.md`](CURRENT.md).
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

apps/booterm/package.json

@@ -15,7 +15,6 @@
     "fastify": "^4.28.1",
     "node-pty": "^1.0.0",
     "pg": "^8.13.0",
-    "tslib": "^2.6.3",
     "zod": "^3.23.8"
   },
   "devDependencies": {
@@ -24,5 +23,5 @@
     "tsx": "^4.16.2",
     "typescript": "^5.5.0"
   },
-  "license": "AGPL-3.0-only"
+  "license": "MIT"
 }

apps/booterm/src/config.ts

@@ -9,7 +9,7 @@ const ConfigSchema = z.object({
   TMUX_CONF_PATH: z.string().default('/etc/booterm/tmux.conf'),
 });
 
-export type Config = z.infer<typeof ConfigSchema>;
+type Config = z.infer<typeof ConfigSchema>;
 
 let cached: Config | null = null;
 

apps/booterm/src/db.ts

@@ -10,7 +10,7 @@ export function getPool(databaseUrl: string): pg.Pool {
   return pool;
 }
 
-export interface SessionInfo {
+interface SessionInfo {
   id: string;
   project_id: string;
   project_path: string;

apps/booterm/src/pty/pty.ts

@@ -1,7 +1,7 @@
 import * as pty from 'node-pty';
 import type { IPty } from 'node-pty';
 
-export interface AttachPtyOptions {
+interface AttachPtyOptions {
   sessionName: string;
   projectRoot: string;
   cols: number;

apps/coder/.env.host

@@ -14,3 +14,4 @@ GITEA_SSH_HOST=100.114.205.53:2222
 MCP_CONFIG_PATH=/data/mcp.json
 SKILLS_ROOT=/opt/boocode/data/skills
 CODER_PROVIDERS_PATH=/opt/boocode/data/coder-providers.json
+CLAUDE_SDK_BACKEND=1

apps/coder/CLAUDE.md

@@ -0,0 +1,34 @@
+# apps/coder — BooCoder (deep reference)
+
+> Per-app engineering notes for `apps/coder/src/`. BooCoder runs as a **systemd service on the host** (`boocoder.service`), NOT in Docker — Fastify at port 9502, postgres at `127.0.0.1:5500`. Cross-cutting commands, database, environment, workflow, and cross-app contracts live in the **root `CLAUDE.md`**. This file auto-loads when you read/edit files under `apps/coder/`.
+
+## Probe & provider discovery
+
+- **`services/provider-registry.ts`** — Static registry of provider metadata (label, transport, model source). `PROVIDERS` array, `PROVIDERS_BY_NAME` map. 5 providers: boocode (native), opencode (acp), goose (pty), claude (pty), qwen (pty). `PROBED_AGENT_NAMES` derives from it — adding/removing providers means editing this file, not the frontend.
+- **`services/agent-probe.ts`** — Startup probe via direct `exec()` (not SSH): discovers installed agents, versions, ACP support, models. Qwen models from `~/.qwen/settings.json`; Claude models static from the registry. Persisted to `available_agents`.
+- **`routes/providers.ts`** — `GET /api/providers` returns installed providers with models. Transport reflects actual capability (checks `supports_acp` from DB, not just registry preference). The apps/server side is "Provider picker dispatch" (see `apps/server/CLAUDE.md`).
+- **Provider snapshot lifecycle** (`services/`): `provider-config.ts` (Zod config, never-throws) → `provider-config-registry.ts` (`buildResolvedRegistry`, singleton) → `provider-snapshot.ts` (two-tier probe: tier-1 fast presence, tier-2 cold ACP probe skipped unless force / stale `PROVIDER_PROBE_TTL_MS` 24h / dbEmpty; cached). Verify live: `curl http://100.114.205.53:9502/api/providers/snapshot` — returns providers + models + commands, the exact shape `AgentComposerBar` renders.
+- `PATCH /api/providers/config` replaces a provider id's override object **wholesale** (per-id shallow merge) — to flip one field send `{...existing, enabled}`, or a custom ACP entry's `command`/`label` is wiped and it drops out of the resolved registry. `data/coder-providers.json` is **gitignored** (live runtime config — the coder reads AND writes it on UI toggles); tracked reference is `data/coder-providers.example.json`. The loader falls back to `{providers:{}}` (built-ins only) when absent, so a fresh checkout needs no copy.
+
+## Build, deploy, dispatch
+
+- **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.**
+- Build + deploy: `pnpm -C apps/server build && pnpm -C apps/coder build && sudo systemctl restart boocoder`. Env file at `apps/coder/.env.host`. Service file at `/etc/systemd/system/boocoder.service`.
+- After `pnpm -C apps/coder build` the host service keeps running the OLD process until `sudo systemctl restart boocoder` — a stale process shows **new routes 404 with `{error:'not found'}` while old routes still 200** (the `/api` not-found handler shape). Restart, don't re-debug.
+- `:9502/api/health` is down ~15–20s after a boocoder restart while the startup agent-probe scan runs — retry; an early connection-refused is not a failed deploy.
+- Agent dispatch spawns binaries directly using `install_path` from `available_agents` — no `spawn('sh', ['-c', ...])` (fails under systemd). Paseo's pattern: `spawn(fullBinaryPath, argsArray, { cwd })`.
+- systemd hardening: only `NoNewPrivileges=true` is safe. `ProtectSystem`, `ProtectHome`, `PrivateTmp` all break agent dispatch (agents need full filesystem access to read configs, write to worktrees).
+- `apps/server/tsconfig.json` has `declaration: true` so `.d.ts` files exist for workspace consumers. 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 can't find `.d.ts` files and tsc fails "Cannot find module" here.
+- Write tools (`edit_file`, `create_file`, `delete_file`, `apply_pending`, `rewind`) queue in `pending_changes`. Nothing hits disk until `apply_pending`. `write_guard.ts` validates paths (resolve + prefix-check, no realpath since files may not exist for creates).
+
+## Backends
+
+> Behavioral overview + flows + data model: see [/docs/coder-backends.md](/docs/coder-backends.md). The notes below are the deep per-fact reference.
+
+- **opencode** runs as a warm HTTP server (`services/backends/opencode-server.ts` — `opencode serve` per BooCoder process, one opencode session per BooCode session, resumed via `agent_sessions`). goose/qwen/claude dispatch **one-shot** ACP/PTY with no ctx/token usage; only native `boocode` (llama-swap) tracks ctx.
+- **opencode SSE** (`opencode-server.ts`): live streaming is `session.next.text.delta` / `.reasoning.delta` / `.tool.{called,success,failed}` — NOT `message.part.*` (terminal/post-hoc). `client.event.subscribe({ directory })` MUST pass the session's worktree dir; omit it and opencode scopes events to the server `process.cwd()` → zero session events (empty turns, 180s timeout). Each live session owns its own subscribe loop + AbortController (a `sessionID` demux guard drops cross-session events when two share a dir). Turn completes on `session.idle`; `promptAsync` is fire-and-forget (204).
+- **opencode model strings** must be provider-prefixed (`llama-swap/<model>`) AND exist in `~/.config/opencode/opencode.json` `provider.llama-swap.models` — not merely loadable by llama-swap. `parseModel` infers `llama-swap/` for a bare id; the dispatcher coalesces empty→DEFAULT_MODEL then prefixes. `agent-probe` populates opencode's `available_agents.models` via `mergeLlamaSwap` (fetches `/v1/models`); empty model list → frontend sends `''` → no inference (empty turn).
+- **agent_sessions resume**: `config_hash = sha256('opencode_server|<model>')` — must NOT include the server port (random per boot; breaks cross-restart resume). Keyed `(chat_id, agent)` — the tab/chat is the context unit (two opencode tabs = two contexts sharing one worktree). `chat_id` CASCADEs from `chats`; `session_id`/`worktree_id` are informational `SET NULL`. The `worktrees` table (one-per-session, survives session delete) supersedes the defanged `session_worktrees`. `tasks.chat_id` threads the tab id to the dispatcher; `runOpenCodeServerTask` resolves-or-creates a chat when null. The `@opencode-ai/sdk` v2 client takes flattened params (`{sessionID, directory, parts, model:{providerID,modelID}}`), `createOpencodeClient` from `@opencode-ai/sdk/v2/client`.
+- **Claude SDK backend tool RESULTS arrive as `type:'user'` SDK messages** (tool_result content blocks): `mapSdkMessage` (`claude-sdk-map.ts`) MUST map the `user` case → a terminal `tool_update` (completed/failed + output), else the tool_call persists `status:'running'` and the UI spinner never stops. The dispatcher's `tool_update` path then publishes + persists it.
+- **ACP command discovery is async**: `acp-probe.ts` must poll after `newSession` for `available_commands_update` (commands arrive in a later notification; reading synchronously captures 0). PTY providers (claude) discover from disk via `claude-command-discovery.ts` (`~/.claude/commands` + `enabledPlugins`, bare names, deduped). `AgentCommand.kind` tags `'command'` vs `'skill'`; `CoderPane`'s `slashGroups` splits them into icon'd groups. `SlashCommandPicker`'s `groups?` prop is opt-in.
+- **A new per-message coder field silently drops unless you update every mapper**: the HTTP read SELECT + `mapCoderMessageRow` (`apps/coder/src/routes/messages.ts`), **the WS `snapshot` SELECT (`apps/coder/src/routes/ws.ts`)** — it has its OWN column list and the client's `snapshot` handler `setMessages`-overwrites the HTTP load, so a field present in the HTTP route but absent here shows live yet vanishes on refresh — `CoderPane.tsx` (`RawCoderMessage`/`CoderMessage`/`mapCoderTimelineRow` + the live `message_complete` WS reducer), `CoderMessageWire` (`CoderMessageList.tsx`), and `api/types.ts`. The client `mapCoderTimelineRow` whitelists fields — easiest to forget. This bit `model` twice: the client chain (`v2.7.9`) and then the WS snapshot SELECT (`v2.7.11`) — the chip showed live but vanished on coder refresh until both were fixed.

apps/coder/package.json

@@ -14,11 +14,12 @@
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "^0.22.1",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.159",
     "@boocode/server": "workspace:*",
     "@fastify/static": "^7.0.4",
-    "@opencode-ai/sdk": "~1.15.0",
     "@fastify/websocket": "^10.0.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@opencode-ai/sdk": "~1.15.0",
     "fastify": "^4.28.1",
     "postgres": "^3.4.4",
     "ws": "^8.18.0",
@@ -31,5 +32,5 @@
     "typescript": "^5.5.0",
     "vitest": "^3.0.0"
   },
-  "license": "AGPL-3.0-only"
+  "license": "MIT"
 }

apps/coder/src/config.ts

@@ -35,6 +35,21 @@ const ConfigSchema = z.object({
   // 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'),
+  // v2.6 Phase 3 (lifecycle hardening). Idle TTL: evict a non-busy warm backend
+  // (opencode server / warm-ACP child) after this long with no turn — its worktree
+  // + agent_sessions row persist, so the next turn re-spawns + reattaches. 30 min
+  // default (design §6).
+  AGENT_POOL_IDLE_TTL_MS: z.coerce.number().int().positive().default(1_800_000),
+  // LRU cap: max live warm backends before the least-recently-used (non-busy) ones
+  // are evicted. Bounds the long-lived-daemon's per-(chat,agent) Map growth.
+  AGENT_POOL_MAX_LIVE: z.coerce.number().int().positive().default(10),
+  // Periodic sweep cadence (idle/LRU pool eviction + orphan-worktree reap). 60s
+  // mirrors the apps/server truncation/stale-streaming sweeper.
+  LIFECYCLE_SWEEP_INTERVAL_MS: z.coerce.number().int().positive().default(60_000),
+  // Orphan-worktree grace: an on-disk worktree dir with no live `worktrees` row is
+  // only reaped after it's been untouched this long (avoids sweeping a dir mid
+  // ensureSessionWorktree create). 1h default.
+  ORPHAN_WORKTREE_GRACE_MS: z.coerce.number().int().positive().default(3_600_000),
 });
 
 export type Config = z.infer<typeof ConfigSchema>;

apps/coder/src/index.ts

@@ -25,6 +25,7 @@ import { setInferenceContext, clearInferenceContext } from './services/tools/inf
 import { registerMessageRoutes } from './routes/messages.js';
 import { registerSkillRoutes } from './routes/skills.js';
 import { registerPendingRoutes } from './routes/pending.js';
+import { registerCheckpointRoutes } from './routes/checkpoints.js';
 import { registerAgentSessionRoutes } from './routes/agent-sessions.js';
 import { registerTaskRoutes } from './routes/tasks.js';
 import { registerInboxRoutes } from './routes/inbox.js';
@@ -32,13 +33,16 @@ import { registerStatsRoutes } from './routes/stats.js';
 import { registerArenaRoutes } from './routes/arena.js';
 import { registerProviderRoutes } from './routes/providers.js';
 import { registerWorktreeSafetyRoutes } from './routes/worktree-safety.js';
+import { registerLifecycleRoutes } from './routes/lifecycle.js';
 import { registerWebSocket } from './routes/ws.js';
 // Phase 4: dispatcher + agent probe
 import { createDispatcher } from './services/dispatcher.js';
 import { agentPool } from './services/agent-pool.js';
+import { createOrphanWorktreeReaper } from './services/orphan-worktree-reaper.js';
 import { probeAgents } from './services/agent-probe.js';
 import { getProviderSnapshot, persistProbedModels } from './services/provider-snapshot.js';
 import { setPermissionHooks } from './services/permission-waiter.js';
+import { publishAgentStatus } from './services/agent-status-publish.js';
 import { homedir } from 'node:os';
 
 async function main() {
@@ -79,6 +83,21 @@ async function main() {
   // Broker: in-memory pub/sub for session + user channel streaming.
   const broker = createBroker(app.log);
 
+  // agent-status-normalize (#10): the permission hooks carry only taskId +
+  // sessionId, but the tasks row holds the (chat_id, agent) pair the status frame
+  // is keyed on. Resolve it best-effort so a blocked/working status accompanies
+  // every permission_requested/permission_resolved. Returns null when the task
+  // lacks a chat_id or agent (sessionless creators) — we simply skip the status.
+  const resolveChatAgent = async (
+    taskId: string,
+  ): Promise<{ chatId: string; agent: string } | null> => {
+    const [row] = await sql<{ chat_id: string | null; agent: string | null }[]>`
+      SELECT chat_id, agent FROM tasks WHERE id = ${taskId}
+    `;
+    if (!row?.chat_id || !row.agent) return null;
+    return { chatId: row.chat_id, agent: row.agent };
+  };
+
   setPermissionHooks({
     onPrompt: async (prompt) => {
       await sql`
@@ -93,6 +112,18 @@ async function main() {
         ...(prompt.input ? { input: prompt.input } : {}),
         options: prompt.options.map((o) => ({ option_id: o.optionId, label: o.label })),
       } as WsFrame);
+      // #10: agent is blocked on a human decision.
+      const ca = await resolveChatAgent(prompt.taskId).catch(() => null);
+      if (ca) {
+        publishAgentStatus(
+          broker.publishFrame,
+          prompt.sessionId,
+          ca.chatId,
+          ca.agent,
+          'blocked',
+          'permission_request',
+        );
+      }
     },
     onResolved: async (taskId, sessionId) => {
       await sql`
@@ -103,6 +134,18 @@ async function main() {
         task_id: taskId,
         session_id: sessionId,
       } as WsFrame);
+      // #10: human responded — agent resumes work.
+      const ca = await resolveChatAgent(taskId).catch(() => null);
+      if (ca) {
+        publishAgentStatus(
+          broker.publishFrame,
+          sessionId,
+          ca.chatId,
+          ca.agent,
+          'working',
+          'permission_resolved',
+        );
+      }
     },
   });
 
@@ -181,10 +224,30 @@ async function main() {
   // Phase 4: dispatcher — polls tasks table and runs inference
   const dispatcher = createDispatcher({ sql, inference: inferenceApi, broker, log: app.log, config });
   dispatcher.start();
+
+  // v2.6 Phase 3: configure + start the agent-pool lifecycle sweep (idle-TTL +
+  // LRU-cap eviction of warm backends, plus each backend's proactive health probe)
+  // and the orphan-worktree reaper. Both run on the same periodic timer.
+  agentPool.configure({
+    idleTtlMs: config.AGENT_POOL_IDLE_TTL_MS,
+    maxLive: config.AGENT_POOL_MAX_LIVE,
+    sweepIntervalMs: config.LIFECYCLE_SWEEP_INTERVAL_MS,
+    log: app.log,
+  });
+  agentPool.startReaper(app.log);
+  const orphanReaper = createOrphanWorktreeReaper({
+    sql,
+    log: app.log,
+    intervalMs: config.LIFECYCLE_SWEEP_INTERVAL_MS,
+    graceMs: config.ORPHAN_WORKTREE_GRACE_MS,
+  });
+  orphanReaper.start();
+
   app.addHook('onClose', async () => {
-    // stop() first so in-flight dispatcher turns settle, then drain the pool.
-    // Pool is empty in Phase 0 (nothing spawns yet) — dispose() is inert.
+    // stop() first so in-flight dispatcher turns settle, then stop the reapers and
+    // drain the pool (kills opencode server + warm ACP children).
     await dispatcher.stop();
+    orphanReaper.stop();
     await agentPool.dispose();
   });
 
@@ -192,6 +255,7 @@ async function main() {
   registerMessageRoutes(app, sql, broker, inferenceApi);
   registerSkillRoutes(app, sql, broker, inferenceApi);
   registerPendingRoutes(app, sql);
+  registerCheckpointRoutes(app, sql);
   registerAgentSessionRoutes(app, sql);
   registerTaskRoutes(app, sql, inferenceApi);
   registerInboxRoutes(app, sql);
@@ -199,6 +263,7 @@ async function main() {
   registerArenaRoutes(app, sql);
   registerProviderRoutes(app, sql, config);
   registerWorktreeSafetyRoutes(app, sql);
+  registerLifecycleRoutes(app, sql);
   registerWebSocket(app, sql, broker);
 
   // Serve static frontend (built web app). In production, the dist/ is

apps/coder/src/routes/__tests__/chat-resolve.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect } from 'vitest';
+import { resolveChatId } from '../chat-resolve.js';
+import type { Sql } from '../../db.js';
+
+// Mock the porsager/postgres surface that chat-resolve.ts uses: a tagged-template
+// `tx` (dispatched by query substring), `tx.json`, and `sql.begin(fn)` which just
+// runs fn(tx). Captures the value written back to workspace_panes so we can assert
+// the WorkspaceState envelope survives the UPDATE.
+interface MockState {
+  stored: unknown; // initial sessions.workspace_panes value
+  existingChatOpen: boolean; // whether `SELECT id FROM chats ...` finds the active chat
+  newChatId: string;
+  written?: unknown; // captured tx.json(...) payload from `UPDATE sessions`
+  inserted: boolean; // whether INSERT INTO chats ran
+}
+
+interface MockTx {
+  (strings: TemplateStringsArray): Promise<unknown>;
+  json: (v: unknown) => unknown;
+}
+
+function mockSql(state: MockState): Sql {
+  const tx = ((strings: TemplateStringsArray) => {
+    const q = strings.join('');
+    if (q.includes('SELECT workspace_panes FROM sessions')) {
+      return Promise.resolve([{ workspace_panes: state.stored }]);
+    }
+    if (q.includes('FROM chats')) {
+      return Promise.resolve(state.existingChatOpen ? [{ id: 'placeholder' }] : []);
+    }
+    if (q.includes('INSERT INTO chats')) {
+      state.inserted = true;
+      return Promise.resolve([{ id: state.newChatId }]);
+    }
+    if (q.includes('UPDATE sessions')) {
+      return Promise.resolve([]);
+    }
+    return Promise.resolve([]);
+  }) as unknown as MockTx;
+  tx.json = (v: unknown) => {
+    state.written = v;
+    return v;
+  };
+  const sql = {
+    begin: (fn: (t: Sql) => Promise<unknown>) => fn(tx as unknown as Sql),
+  };
+  return sql as unknown as Sql;
+}
+
+const ENVELOPE = () => ({
+  panes: [{ id: 'pane-1', kind: 'coder', chatIds: [] as string[], activeChatIdx: 0 }],
+  tabNumbers: { 'chat-x': 3 },
+  nextTabNumber: 7,
+  closedPaneStack: [{ kind: 'coder', chatIds: ['old'], activeChatIdx: 0 }],
+});
+
+describe('resolveChatId — v2.6.5 WorkspaceState envelope', () => {
+  it('reads panes from the envelope without crashing (regression: panes.findIndex is not a function)', async () => {
+    const state: MockState = {
+      stored: ENVELOPE(),
+      existingChatOpen: false,
+      newChatId: 'new-chat-1',
+      inserted: false,
+    };
+    const chatId = await resolveChatId(mockSql(state), 'session-1', 'pane-1');
+    expect(chatId).toBe('new-chat-1');
+    expect(state.inserted).toBe(true);
+  });
+
+  it('preserves the envelope (tabNumbers/nextTabNumber/closedPaneStack) on write-back', async () => {
+    const state: MockState = {
+      stored: ENVELOPE(),
+      existingChatOpen: false,
+      newChatId: 'new-chat-1',
+      inserted: false,
+    };
+    await resolveChatId(mockSql(state), 'session-1', 'pane-1');
+    const w = state.written as Record<string, unknown>;
+    expect(Array.isArray(w.panes)).toBe(true); // envelope, not a bare array
+    expect(w.tabNumbers).toEqual({ 'chat-x': 3 });
+    expect(w.nextTabNumber).toBe(7);
+    expect(w.closedPaneStack).toEqual([{ kind: 'coder', chatIds: ['old'], activeChatIdx: 0 }]);
+  });
+
+  it('returns the existing open chat when the pane already has one', async () => {
+    const env = ENVELOPE();
+    env.panes[0]!.chatIds = ['existing-1'];
+    const state: MockState = {
+      stored: env,
+      existingChatOpen: true,
+      newChatId: 'should-not-be-used',
+      inserted: false,
+    };
+    const chatId = await resolveChatId(mockSql(state), 'session-1', 'pane-1');
+    expect(chatId).toBe('existing-1');
+    expect(state.inserted).toBe(false);
+  });
+
+  it('still accepts a legacy bare WorkspacePane[] array', async () => {
+    const state: MockState = {
+      stored: [{ id: 'pane-1', kind: 'coder', chatId: 'legacy-1', chatIds: ['legacy-1'], activeChatIdx: 0 }],
+      existingChatOpen: true,
+      newChatId: 'should-not-be-used',
+      inserted: false,
+    };
+    const chatId = await resolveChatId(mockSql(state), 'session-1', 'pane-1');
+    expect(chatId).toBe('legacy-1');
+    expect(state.inserted).toBe(false);
+  });
+});

apps/coder/src/routes/agent-sessions.ts

@@ -16,6 +16,11 @@ export interface AgentSessionRow {
   status: string;
   has_session: boolean;
   last_active_at: string | null;
+  // v2.6.8 per-(chat,agent) running token/cost totals (sampling-streamjson-tokens
+  // #8). BIGINT columns arrive as strings over the wire; the frontend coerces.
+  input_tokens: number;
+  output_tokens: number;
+  cost: number;
 }
 
 export function registerAgentSessionRoutes(app: FastifyInstance, sql: Sql): void {
@@ -39,7 +44,10 @@ export function registerAgentSessionRoutes(app: FastifyInstance, sql: Sql): void
           a.agent AS agent,
           a.status AS status,
           (a.agent_session_id IS NOT NULL) AS has_session,
-          a.last_active_at AS last_active_at
+          a.last_active_at AS last_active_at,
+          a.input_tokens AS input_tokens,
+          a.output_tokens AS output_tokens,
+          a.cost AS cost
         FROM agent_sessions a
         JOIN chats c ON c.id = a.chat_id
         WHERE c.session_id = ${sessionId}

apps/coder/src/routes/chat-resolve.ts

@@ -8,6 +8,36 @@ interface WorkspacePaneRow {
   activeChatIdx?: number;
 }
 
+// v2.6.5: sessions.workspace_panes widened from a bare WorkspacePane[] to a
+// WorkspaceState envelope { panes, tabNumbers, nextTabNumber, closedPaneStack }.
+// (See the union validator in apps/server routes/sessions.ts + normalizeWorkspaceState
+// in apps/server read_tab_by_number.ts — this is the coder-side mirror.)
+interface WorkspaceStateRow {
+  panes: WorkspacePaneRow[];
+  tabNumbers: Record<string, number>;
+  nextTabNumber: number;
+  closedPaneStack: unknown[];
+}
+
+// MIGRATION: the stored value may be the legacy bare array OR the envelope.
+// Normalize to a full envelope so callers always read `.panes` as an array and
+// write the envelope back intact (preserving tabNumbers/nextTabNumber/closedPaneStack).
+export function normalizeWorkspaceState(v: unknown): WorkspaceStateRow {
+  if (Array.isArray(v)) {
+    return { panes: v as WorkspacePaneRow[], tabNumbers: {}, nextTabNumber: 1, closedPaneStack: [] };
+  }
+  if (v && typeof v === 'object' && Array.isArray((v as { panes?: unknown }).panes)) {
+    const env = v as Partial<WorkspaceStateRow>;
+    return {
+      panes: env.panes ?? [],
+      tabNumbers: env.tabNumbers ?? {},
+      nextTabNumber: env.nextTabNumber ?? 1,
+      closedPaneStack: env.closedPaneStack ?? [],
+    };
+  }
+  return { panes: [], tabNumbers: {}, nextTabNumber: 1, closedPaneStack: [] };
+}
+
 function chatNameForKind(kind: string): string {
   if (kind === 'coder' || kind === 'agent') return 'BooCoder';
   if (kind === 'terminal') return 'Terminal';
@@ -28,12 +58,13 @@ export async function resolveChatId(
   paneId: string,
 ): Promise<string | null> {
   return sql.begin(async (tx) => {
-    const sessionRows = await tx<{ workspace_panes: WorkspacePaneRow[] }[]>`
+    const sessionRows = await tx<{ workspace_panes: unknown }[]>`
       SELECT workspace_panes FROM sessions WHERE id = ${sessionId} FOR UPDATE
     `;
     if (sessionRows.length === 0) return null;
 
-    const panes = sessionRows[0]!.workspace_panes ?? [];
+    const state = normalizeWorkspaceState(sessionRows[0]!.workspace_panes);
+    const panes = state.panes;
     const paneIdx = panes.findIndex((p) => p.id === paneId);
     if (paneIdx < 0) return null;
 
@@ -69,9 +100,10 @@ export async function resolveChatId(
         : p,
     );
 
+    const nextState: WorkspaceStateRow = { ...state, panes: nextPanes };
     await tx`
       UPDATE sessions
-      SET workspace_panes = ${tx.json(nextPanes as never)},
+      SET workspace_panes = ${tx.json(nextState as never)},
           updated_at = clock_timestamp()
       WHERE id = ${sessionId}
     `;

apps/coder/src/routes/checkpoints.ts

@@ -0,0 +1,73 @@
+/**
+ * write-edit-robustness #4 — checkpoint restore + list routes (coder side).
+ *
+ * Proxied through the apps/server `/api/coder/*` blanket forwarder (no server-side
+ * change needed for new routes). Restore rewinds the session worktree to the
+ * checkpoint's shadow commit, trims the transcript from the anchor message forward,
+ * and resets the agent backend — see services/checkpoints.ts.
+ */
+import type { FastifyInstance } from 'fastify';
+import type { Sql } from '../db.js';
+import { restoreCheckpoint, CheckpointNotFoundError } from '../services/checkpoints.js';
+
+export function registerCheckpointRoutes(app: FastifyInstance, sql: Sql): void {
+  // GET /api/sessions/:sessionId/checkpoints?chat_id= — list a chat's checkpoints
+  // so the frontend can mark which messages have a restore point. When chat_id is
+  // omitted, returns every checkpoint for the session's chats.
+  app.get<{ Params: { sessionId: string }; Querystring: { chat_id?: string } }>(
+    '/api/sessions/:sessionId/checkpoints',
+    async (req, reply) => {
+      const sessionId = req.params.sessionId;
+      const chatId = req.query.chat_id;
+
+      const session = await sql<{ id: string }[]>`SELECT id FROM sessions WHERE id = ${sessionId}`;
+      if (session.length === 0) {
+        reply.code(404);
+        return { error: 'session not found' };
+      }
+
+      // Scope authoritatively through chats.session_id (always set) — NOT the
+      // denormalized checkpoints.session_id (nullable). The chat_id branch must
+      // still be session-gated or it's an IDOR (any session's chat_id reads its
+      // checkpoints).
+      const rows = chatId
+        ? await sql<{ id: string; chat_id: string; message_id: string | null; label: string | null; created_at: Date }[]>`
+            SELECT cp.id, cp.chat_id, cp.message_id, cp.label, cp.created_at
+            FROM checkpoints cp
+            JOIN chats c ON c.id = cp.chat_id
+            WHERE cp.chat_id = ${chatId} AND c.session_id = ${sessionId}
+            ORDER BY cp.created_at
+          `
+        : await sql<{ id: string; chat_id: string; message_id: string | null; label: string | null; created_at: Date }[]>`
+            SELECT cp.id, cp.chat_id, cp.message_id, cp.label, cp.created_at
+            FROM checkpoints cp
+            JOIN chats c ON c.id = cp.chat_id
+            WHERE c.session_id = ${sessionId}
+            ORDER BY cp.created_at
+          `;
+      return rows;
+    },
+  );
+
+  // POST /api/sessions/:sessionId/checkpoints/:checkpointId/restore — restore.
+  app.post<{ Params: { sessionId: string; checkpointId: string } }>(
+    '/api/sessions/:sessionId/checkpoints/:checkpointId/restore',
+    async (req, reply) => {
+      const { sessionId, checkpointId } = req.params;
+
+      try {
+        const result = await restoreCheckpoint(sql, checkpointId, {
+          sessionId,
+          log: app.log,
+        });
+        return result;
+      } catch (err) {
+        if (err instanceof CheckpointNotFoundError) {
+          reply.code(404);
+          return { error: err.message };
+        }
+        throw err;
+      }
+    },
+  );
+}

apps/coder/src/routes/lifecycle.ts

@@ -0,0 +1,122 @@
+/**
+ * v2.6 Phase 3 (3.3) — chat/session close-or-archive cleanup hook (coder side).
+ *
+ * Chat/session close + archive + delete all live in apps/server (Docker), which
+ * cannot see the host worktree dirs (/tmp/booworktrees), run git on them, or reach
+ * the warm agent processes the dispatcher pooled in THIS (host systemd) process. So
+ * — exactly like the `worktree-risk` guard — the server signals the coder when a
+ * chat/session closes, and the coder does the real teardown:
+ *   1. dispose the chat's warm-ACP backends (`agentPool.closeChat`) — kills the
+ *      goose/qwen child processes for that chat,
+ *   2. close the chat's opencode session on the shared server (`closeSession`),
+ *   3. mark every `agent_sessions` row for the chat 'closed' + (when the session's
+ *      last open chat closes) remove the shared session worktree, preflighting
+ *      work-at-risk so uncommitted/unmerged work is never silently dropped
+ *      (`closeChatBackendState`).
+ *
+ * Idempotent: closing an already-closed chat is a no-op (0 rows, no backend).
+ *
+ * SERVER WIRING (not done here — apps/server, out of this batch's scope): the
+ * server's `POST /api/chats/:id/archive`, `DELETE /api/chats/:id`, and the
+ * session archive/delete routes should fire-and-forget
+ *   fetch(`${BOOCODER_URL}/api/chats/${id}/close`, { method: 'POST' })
+ * after publishing their WS frame (best-effort; the orphan-worktree reaper +
+ * idle-pool eviction are the backstop if the call is missed).
+ */
+import type { FastifyInstance } from 'fastify';
+import type { Sql } from '../db.js';
+import { agentPool, OPENCODE_POOL_KEY } from '../services/agent-pool.js';
+import { closeChatBackendState } from '../services/worktrees.js';
+import type { AgentSessionHandle } from '../services/agent-backend.js';
+
+export function registerLifecycleRoutes(app: FastifyInstance, sql: Sql): void {
+  // POST /api/chats/:chatId/close — tear down all warm state for a chat tab.
+  app.post<{ Params: { chatId: string }; Querystring: { force?: string } }>(
+    '/api/chats/:chatId/close',
+    async (req) => {
+      const chatId = req.params.chatId;
+      const force = req.query.force === 'true' || req.query.force === '1';
+
+      // 1. Close the chat's opencode session on the SHARED server (the server is
+      //    not chat-keyed, so agentPool.closeChat won't touch it). Resolve the
+      //    stored opencode session id and ask the backend to drop it.
+      const ocRows = await sql<{ agent: string; agent_session_id: string | null; worktree_id: string | null; session_id: string | null }[]>`
+        SELECT agent, agent_session_id, worktree_id, session_id
+        FROM agent_sessions
+        WHERE chat_id = ${chatId} AND backend = 'opencode_server'
+      `;
+      const ocBackend = agentPool.peek(OPENCODE_POOL_KEY, 'opencode');
+      if (ocBackend) {
+        for (const row of ocRows) {
+          if (!row.agent_session_id) continue;
+          const handle: AgentSessionHandle = {
+            sessionId: row.session_id ?? '',
+            agent: row.agent,
+            backend: 'opencode_server',
+            chatId,
+            worktreeId: row.worktree_id ?? '',
+            agentSessionId: row.agent_session_id,
+            serverPort: null,
+          };
+          await ocBackend.closeSession(handle).catch((err) => {
+            app.log.warn({ err: err instanceof Error ? err.message : String(err), chatId }, 'lifecycle: opencode closeSession threw');
+          });
+        }
+      }
+
+      // 2. Dispose any warm-ACP backends pooled under this chat (kills the
+      //    goose/qwen child + marks its agent row closed via the backend).
+      const disposed = await agentPool.closeChat(chatId);
+
+      // 3. DB + worktree truth: mark agent rows closed; remove the shared session
+      //    worktree iff this was the session's last open chat (preflight at-risk).
+      const result = await closeChatBackendState(sql, chatId, { force });
+
+      app.log.info({ chatId, disposed, ...result }, 'lifecycle: chat closed');
+      return { ok: true, disposed, ...result };
+    },
+  );
+
+  // POST /api/sessions/:sessionId/close — close every open chat in a session
+  // (session archive/delete). Loops the chat-close path so the same preflight +
+  // teardown applies per chat; the worktree is removed on the last one.
+  app.post<{ Params: { sessionId: string }; Querystring: { force?: string } }>(
+    '/api/sessions/:sessionId/close',
+    async (req) => {
+      const sessionId = req.params.sessionId;
+      const force = req.query.force === 'true' || req.query.force === '1';
+
+      const chats = await sql<{ id: string }[]>`
+        SELECT id FROM chats WHERE session_id = ${sessionId}
+      `;
+      const results: { chatId: string; disposed: string[]; worktreeRemoved: boolean; worktreeAtRisk: boolean }[] = [];
+      for (const c of chats) {
+        const ocBackend = agentPool.peek(OPENCODE_POOL_KEY, 'opencode');
+        if (ocBackend) {
+          const ocRows = await sql<{ agent: string; agent_session_id: string | null; worktree_id: string | null; session_id: string | null }[]>`
+            SELECT agent, agent_session_id, worktree_id, session_id
+            FROM agent_sessions WHERE chat_id = ${c.id} AND backend = 'opencode_server'
+          `;
+          for (const row of ocRows) {
+            if (!row.agent_session_id) continue;
+            await ocBackend.closeSession({
+              sessionId: row.session_id ?? '',
+              agent: row.agent,
+              backend: 'opencode_server',
+              chatId: c.id,
+              worktreeId: row.worktree_id ?? '',
+              agentSessionId: row.agent_session_id,
+              serverPort: null,
+            }).catch(() => {});
+          }
+        }
+        const disposed = await agentPool.closeChat(c.id);
+        const r = await closeChatBackendState(sql, c.id, { force });
+        results.push({ chatId: c.id, disposed, worktreeRemoved: r.worktreeRemoved, worktreeAtRisk: r.worktreeAtRisk });
+      }
+
+      app.log.info({ sessionId, chats: results.length }, 'lifecycle: session closed');
+      return { ok: true, results };
+    },
+  );
+}

apps/coder/src/routes/messages.ts

@@ -53,6 +53,9 @@ interface MessageRow {
   role: string;
   content: string | null;
   status: string | null;
+  model: string | null;
+  ctx_used: number | null;
+  ctx_max: number | null;
   tool_calls: Array<{ id: string; name: string; args?: Record<string, unknown> }> | null;
   tool_results: {
     tool_call_id: string;
@@ -88,6 +91,9 @@ function mapCoderMessageRow(row: MessageRow) {
     role: row.role as 'user' | 'assistant' | 'system',
     content: row.content ?? '',
     status: (row.status ?? 'complete') as 'streaming' | 'complete' | 'failed',
+    ...(row.model ? { model: row.model } : {}),
+    ...(row.ctx_used != null ? { ctx_used: row.ctx_used } : {}),
+    ...(row.ctx_max != null ? { ctx_max: row.ctx_max } : {}),
     ...(reasoningText ? { reasoning_text: reasoningText } : {}),
     ...(tool_calls?.length ? { tool_calls } : {}),
   };
@@ -126,13 +132,13 @@ export function registerMessageRoutes(
 
       const rows = chatId
         ? await sql<MessageRow[]>`
-            SELECT id, role, content, status, tool_calls, tool_results, reasoning_parts
+            SELECT id, role, content, status, model, ctx_used, ctx_max, tool_calls, tool_results, reasoning_parts
             FROM messages_with_parts
             WHERE session_id = ${sessionId} AND chat_id = ${chatId}
             ORDER BY created_at ASC, id ASC
           `
         : await sql<MessageRow[]>`
-            SELECT id, role, content, status, tool_calls, tool_results, reasoning_parts
+            SELECT id, role, content, status, model, ctx_used, ctx_max, tool_calls, tool_results, reasoning_parts
             FROM messages_with_parts
             WHERE session_id = ${sessionId}
             ORDER BY created_at ASC, id ASC

apps/coder/src/routes/pending.ts

@@ -10,6 +10,7 @@ import {
   queueCreate,
 } from '../services/pending_changes.js';
 import { WriteGuardError } from '../services/write_guard.js';
+import { rebaselineWorktreeAfterApply } from '../services/worktrees.js';
 
 const CreateBody = z.object({
   file_path: z.string().min(1),
@@ -117,6 +118,15 @@ export function registerPendingRoutes(app: FastifyInstance, sql: Sql): void {
       }
 
       const results = await applyAll(sql, sessionId, projectRoot);
+
+      // v2.6 Phase 3 (3.5): re-baseline the session worktree's diff to the applied
+      // state, so the next external-agent turn diffs against applied-not-original
+      // and doesn't re-surface the just-applied changes. Best-effort: a worktree
+      // session may not exist (native-only chat), and a re-baseline hiccup must not
+      // fail the apply the user just requested.
+      if (results.some((r) => r.success)) {
+        await rebaselineWorktreeAfterApply(sql, sessionId).catch(() => {});
+      }
       return { results };
     },
   );
@@ -136,6 +146,15 @@ export function registerPendingRoutes(app: FastifyInstance, sql: Sql): void {
       const result = await applyOne(sql, changeId, projectRoot);
       if (!result.success) {
         reply.code(422);
+      } else {
+        // v2.6 Phase 3 (3.5): re-baseline the session worktree after a successful
+        // apply so the next external-agent turn diffs against applied-not-original.
+        // Resolve the change's session; best-effort, never fails the apply.
+        const sessRows = await sql<{ session_id: string }[]>`
+          SELECT session_id FROM pending_changes WHERE id = ${changeId}
+        `;
+        const sessionId = sessRows[0]?.session_id;
+        if (sessionId) await rebaselineWorktreeAfterApply(sql, sessionId).catch(() => {});
       }
       return result;
     },

apps/coder/src/routes/tasks.ts

@@ -95,7 +95,7 @@ export function registerTaskRoutes(app: FastifyInstance, sql: Sql, inference: In
   // 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
+      SELECT id, project_id, parent_task_id, state, input, output_summary, agent, model, execution_path, session_id, cost_tokens, started_at, ended_at, created_at
       FROM tasks
       WHERE id = ${req.params.id}
     `;

apps/coder/src/routes/worktree-safety.ts

@@ -9,7 +9,7 @@
  */
 import type { FastifyInstance } from 'fastify';
 import type { Sql } from '../db.js';
-import { checkWorktreeWorkAtRisk, stashWorktree } from '../services/worktrees.js';
+import { checkWorktreeWorkAtRisk, stashWorktree } from '../services/worktree-risk.js';
 
 export function registerWorktreeSafetyRoutes(app: FastifyInstance, sql: Sql): void {
   // GET risk for a session's worktree(s). One row per session today (PK on

apps/coder/src/routes/ws.ts

@@ -25,7 +25,7 @@ export function registerWebSocket(
 
       // Send snapshot of existing messages so client can hydrate
       const messages = await sql<Record<string, unknown>[]>`
-        SELECT id, session_id, chat_id, role, content, kind, tool_calls, tool_results, reasoning_parts, status, last_seq,
+        SELECT id, session_id, chat_id, role, content, kind, tool_calls, tool_results, reasoning_parts, status, model, last_seq,
                tokens_used, ctx_used, ctx_max, started_at, finished_at, created_at, metadata,
                summary, tail_start_id, compacted_at
         FROM messages_with_parts

apps/coder/src/schema.sql

@@ -25,7 +25,6 @@ CREATE TABLE IF NOT EXISTS tasks (
   agent TEXT,
   model TEXT,
   execution_path TEXT,
-  worktree_path TEXT,
   cost_tokens INTEGER,
   started_at TIMESTAMPTZ,
   ended_at TIMESTAMPTZ,
@@ -39,9 +38,9 @@ CREATE TABLE IF NOT EXISTS available_agents (
   install_path TEXT,
   version TEXT,
   supports_acp BOOLEAN NOT NULL DEFAULT false,
-  supports_mcp_client BOOLEAN NOT NULL DEFAULT false,
   last_probed_at TIMESTAMPTZ
 );
+ALTER TABLE available_agents DROP COLUMN IF EXISTS supports_mcp_client;
 
 -- 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);
@@ -74,31 +73,10 @@ ALTER TABLE available_agents ADD COLUMN IF NOT EXISTS commands JSONB DEFAULT '[]
 -- v2.2.0: Paseo-style session config on tasks.
 ALTER TABLE tasks ADD COLUMN IF NOT EXISTS mode_id TEXT;
 ALTER TABLE tasks ADD COLUMN IF NOT EXISTS thinking_option_id TEXT;
-ALTER TABLE tasks ADD COLUMN IF NOT EXISTS feature_values JSONB;
-
--- v2.6: one shared worktree per session (all agents/panes in the session operate in it).
-CREATE TABLE IF NOT EXISTS session_worktrees (
-  session_id UUID PRIMARY KEY REFERENCES sessions(id) ON DELETE CASCADE,
-  worktree_path TEXT NOT NULL,
-  base_commit TEXT,
-  created_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp()
-);
--- P1.5-b: DEFANG the CASCADE — a session delete must no longer wipe its worktree
--- row. This table is SUPERSEDED by `worktrees` below; all readers are repointed
--- this phase, so the row just persists (dead) on session delete until a later
--- cleanup drops the table. session_id is this table's PRIMARY KEY, so it cannot be
--- nullable → SET NULL is invalid and NO ACTION/RESTRICT would block deletes; the
--- only valid defang is to drop the FK with no replacement. Idempotent: only fires
--- while the FK is still ON DELETE CASCADE ('c').
-DO $$ BEGIN
-  IF EXISTS (
-    SELECT 1 FROM pg_constraint
-    WHERE conname = 'session_worktrees_session_id_fkey'
-      AND confdeltype = 'c'
-  ) THEN
-    ALTER TABLE session_worktrees DROP CONSTRAINT session_worktrees_session_id_fkey;
-  END IF;
-END $$;
+-- tasks.feature_values and tasks.worktree_path were never read or written by any
+-- code path; drop them from existing DBs (fresh DBs never had them in the CREATE).
+ALTER TABLE tasks DROP COLUMN IF EXISTS feature_values;
+ALTER TABLE tasks DROP COLUMN IF EXISTS worktree_path;
 
 -- v2.6: one backend session per (session, agent); resumed on switch-back.
 CREATE TABLE IF NOT EXISTS agent_sessions (
@@ -168,12 +146,9 @@ CREATE TABLE IF NOT EXISTS worktrees (
 );
 CREATE UNIQUE INDEX IF NOT EXISTS worktrees_active_path_uidx ON worktrees(path) WHERE status='active';
 
--- Migrate any surviving session_worktrees rows → worktrees (idempotent; 0 rows
--- after the test-session delete, kept for generality / fresh-DB safety).
-INSERT INTO worktrees (session_id, path, branch, base_commit, status)
-SELECT sw.session_id, sw.worktree_path, 'session-' || sw.session_id, sw.base_commit, 'active'
-FROM session_worktrees sw
-WHERE NOT EXISTS (SELECT 1 FROM worktrees w WHERE w.session_id = sw.session_id AND w.status='active');
+-- session_worktrees was superseded by worktrees (v2.6/P1.5-b); all rows migrated
+-- before P2 cleanup. Drop the dead table; no-op on fresh DBs that never had it.
+DROP TABLE IF EXISTS session_worktrees;
 
 -- Dispatch hint: which chat (tab) a task belongs to. The coder message route and
 -- skills route set it from the frontend tab; session-less creators (arena, MCP,
@@ -240,6 +215,55 @@ END $$;
 -- v2.6: attribution for DiffPanel badges (Phase 1 UX reads this).
 ALTER TABLE pending_changes ADD COLUMN IF NOT EXISTS agent TEXT;
 
+-- write-edit-robustness #4: worktree checkpoints. A pre-turn shadow-commit of the
+-- session worktree (tracked + untracked, captured without disturbing the real
+-- index/working tree) stored in a private GC-safe ref refs/boocode/checkpoints/<id>.
+-- Created best-effort before each external-agent turn (opencode / warm-ACP / one-shot
+-- ACP+PTY); restore resets the worktree to commit_sha, trims the transcript from
+-- message_id forward, and resets the backend session. chat_id CASCADEs from chats
+-- (like agent_sessions); worktree_id SET NULL so a checkpoint outlives a reaped
+-- worktree row. session_id / message_id are informational (no FK — message rows are
+-- trimmed by a checkpoint restore and we must not block that on a dangling ref).
+CREATE TABLE IF NOT EXISTS checkpoints (
+  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  chat_id     UUID NOT NULL REFERENCES chats(id) ON DELETE CASCADE,
+  session_id  UUID,
+  worktree_id UUID REFERENCES worktrees(id) ON DELETE SET NULL,
+  message_id  UUID,            -- anchor: the assistant turn row this checkpoint precedes
+  commit_sha  TEXT NOT NULL,   -- shadow-commit capturing the pre-turn worktree tree
+  label       TEXT,
+  created_at  TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp()
+);
+CREATE INDEX IF NOT EXISTS checkpoints_chat_created_idx ON checkpoints(chat_id, created_at);
+
+-- claude-sdk-sessionstore #9 (Part 1): append-only mirror of Claude Agent SDK
+-- session transcripts. The SDK's SessionStore adapter writes one JSONL line per
+-- entry; PostgresSessionStore (services/backends/claude-session-store.ts) inserts
+-- one row per entry and replays them ORDER BY id on resume. The store is generic
+-- per the SDK's SessionKey (project_key, session_id, subpath) — chat↔session
+-- ownership lives in agent_sessions, not here. subpath '' is the main transcript
+-- (the SDK's undefined subpath maps to '' in the column).
+CREATE TABLE IF NOT EXISTS claude_session_entries (
+  id          BIGSERIAL PRIMARY KEY,
+  project_key TEXT NOT NULL,
+  session_id  TEXT NOT NULL,
+  subpath     TEXT NOT NULL DEFAULT '',   -- '' = main transcript (SDK's undefined subpath maps here)
+  entry       JSONB NOT NULL,
+  created_at  TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp()
+);
+CREATE INDEX IF NOT EXISTS claude_session_entries_key_idx ON claude_session_entries (project_key, session_id, subpath, id);
+
+-- claude-sdk-sessionstore #9 (Part 2): the warm Claude-SDK backend persists its
+-- agent_sessions rows with backend='claude_sdk'. Widen the named CHECK to accept
+-- it. Idempotent: DROP the named constraint (the inline CREATE TABLE check above
+-- carries this explicit name, so DROP IF EXISTS targets it) + re-ADD the widened
+-- list. Re-runs/fresh deploys land on the same final constraint (the table-level
+-- CREATE already includes only the old two values on a fresh DB; this block then
+-- replaces it with the three-value list).
+ALTER TABLE agent_sessions DROP CONSTRAINT IF EXISTS agent_sessions_backend_chk;
+ALTER TABLE agent_sessions ADD CONSTRAINT agent_sessions_backend_chk
+  CHECK (backend IN ('opencode_server', 'acp_warm', 'claude_sdk'));
+
 -- LISTEN/NOTIFY fast path: every tasks INSERT (from any call site — routes,
 -- new_task tool, arena, MCP server) fires pg_notify('tasks_new') in the same
 -- transaction, so the dispatcher reacts immediately instead of waiting for the

apps/coder/src/services/__tests__/acp-client.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, vi } from 'vitest';
+import type { RequestPermissionRequest, CreateElicitationRequest, SessionNotification } from '@agentclientprotocol/sdk';
+import { buildAcpClient, type AcpTurnContext } from '../acp-client.js';
+
+/**
+ * buildAcpClient (v2.7 audit reshape): the shared ACP `Client` closures. These
+ * tests cover the pure routing decisions that don't require the permission-waiter
+ * broker machinery — the auto-select/decline fallbacks and the between-turns drop.
+ */
+
+describe('buildAcpClient — sessionUpdate', () => {
+  it('drops the update when no turn is active (resolveTurn → null)', async () => {
+    const client = buildAcpClient('/wt', () => null);
+    // Must resolve without throwing and without an onSessionUpdate to call.
+    await expect(client.sessionUpdate({ sessionId: 's', update: {} } as unknown as SessionNotification)).resolves.toBeUndefined();
+  });
+
+  it('forwards the update to the active turn', async () => {
+    const onSessionUpdate = vi.fn();
+    const turn: AcpTurnContext = { taskId: 't', sessionId: 's', modeId: undefined, agent: 'goose', onSessionUpdate };
+    const client = buildAcpClient('/wt', () => turn);
+    const note = { sessionId: 's', update: {} } as unknown as SessionNotification;
+    await client.sessionUpdate(note);
+    expect(onSessionUpdate).toHaveBeenCalledWith(note);
+  });
+});
+
+describe('buildAcpClient — requestPermission fallback (no UI routing)', () => {
+  function req(options: Array<{ optionId: string }>): RequestPermissionRequest {
+    return { options } as unknown as RequestPermissionRequest;
+  }
+
+  it('auto-selects the first option when there is no turn', async () => {
+    const client = buildAcpClient('/wt', () => null);
+    const res = await client.requestPermission(req([{ optionId: 'allow' }, { optionId: 'deny' }]));
+    expect(res).toEqual({ outcome: { outcome: 'selected', optionId: 'allow' } });
+  });
+
+  it('cancels when there is no turn and no options', async () => {
+    const client = buildAcpClient('/wt', () => null);
+    const res = await client.requestPermission(req([]));
+    expect(res).toEqual({ outcome: { outcome: 'cancelled' } });
+  });
+
+  it('auto-selects when the turn has no taskId (UI routing gated off)', async () => {
+    const turn: AcpTurnContext = { taskId: undefined, sessionId: 's', modeId: undefined, agent: 'goose', onSessionUpdate: () => {} };
+    const client = buildAcpClient('/wt', () => turn);
+    const res = await client.requestPermission(req([{ optionId: 'ok' }]));
+    expect(res).toEqual({ outcome: { outcome: 'selected', optionId: 'ok' } });
+  });
+});
+
+describe('buildAcpClient — elicitation fallback', () => {
+  it('declines when there is no turn', async () => {
+    const client = buildAcpClient('/wt', () => null);
+    const res = await client.unstable_createElicitation!({} as CreateElicitationRequest);
+    expect(res).toEqual({ action: 'decline' });
+  });
+
+  it('declines when the turn has no taskId', async () => {
+    const turn: AcpTurnContext = { taskId: undefined, sessionId: 's', modeId: undefined, agent: 'goose', onSessionUpdate: () => {} };
+    const client = buildAcpClient('/wt', () => turn);
+    const res = await client.unstable_createElicitation!({} as CreateElicitationRequest);
+    expect(res).toEqual({ action: 'decline' });
+  });
+});
+
+describe('buildAcpClient — createTerminal', () => {
+  it('returns the noop terminal id', async () => {
+    const client = buildAcpClient('/wt', () => null);
+    const res = await client.createTerminal!({} as never);
+    expect(res).toEqual({ terminalId: 'noop' });
+  });
+});

apps/coder/src/services/__tests__/acp-event-map.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect } from 'vitest';
+import type { SessionNotification } from '@agentclientprotocol/sdk';
+import { mapSessionUpdate } from '../acp-event-map.js';
+import type { AcpToolSnapshot } from '../acp-tool-snapshot.js';
+
+/**
+ * Pure event-mapping shared by the one-shot ACP dispatch (AcpStreamContext) and
+ * the warm ACP backend (Phase 2). Mirrors the original handleSessionUpdate switch
+ * verbatim but returns normalized AgentEvents instead of publishing broker frames.
+ */
+describe('mapSessionUpdate (shared ACP event mapping)', () => {
+  function note(update: SessionNotification['update']): SessionNotification {
+    return { sessionId: 's1', update };
+  }
+
+  it('maps an agent_message_chunk text → a text event', () => {
+    const events = mapSessionUpdate(
+      note({ sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: 'hello' } }),
+    );
+    expect(events).toEqual([{ type: 'text', text: 'hello' }]);
+  });
+
+  it('maps an agent_thought_chunk text → a reasoning event', () => {
+    const events = mapSessionUpdate(
+      note({ sessionUpdate: 'agent_thought_chunk', content: { type: 'text', text: 'thinking' } }),
+    );
+    expect(events).toEqual([{ type: 'reasoning', text: 'thinking' }]);
+  });
+
+  it('ignores non-text content on message/thought chunks', () => {
+    const img = mapSessionUpdate(
+      note({
+        sessionUpdate: 'agent_message_chunk',
+        content: { type: 'image', data: 'x', mimeType: 'image/png' },
+      } as never),
+    );
+    expect(img).toEqual([]);
+  });
+
+  it('maps a tool_call → a tool_call event with a merged snapshot', () => {
+    const events = mapSessionUpdate(
+      note({
+        sessionUpdate: 'tool_call',
+        toolCallId: 't1',
+        title: 'read_file',
+        status: 'pending',
+        rawInput: { path: 'a.ts' },
+      } as never),
+    );
+    expect(events).toHaveLength(1);
+    expect(events[0]!.type).toBe('tool_call');
+    const snap = (events[0] as { type: 'tool_call'; toolCall: AcpToolSnapshot }).toolCall;
+    expect(snap.toolCallId).toBe('t1');
+    expect(snap.title).toBe('read_file');
+    expect(snap.status).toBe('pending');
+    expect(snap.rawInput).toEqual({ path: 'a.ts' });
+  });
+
+  it('maps a tool_call_update → a tool_update event merged over the prior snapshot', () => {
+    const prior = new Map<string, AcpToolSnapshot>([
+      ['t1', { toolCallId: 't1', title: 'read_file', status: 'pending', rawInput: { path: 'a.ts' } }],
+    ]);
+    const events = mapSessionUpdate(
+      note({
+        sessionUpdate: 'tool_call_update',
+        toolCallId: 't1',
+        status: 'completed',
+        rawOutput: 'file body',
+      } as never),
+      prior,
+    );
+    expect(events).toHaveLength(1);
+    expect(events[0]!.type).toBe('tool_update');
+    const snap = (events[0] as { type: 'tool_update'; toolCall: AcpToolSnapshot }).toolCall;
+    expect(snap.toolCallId).toBe('t1');
+    // merged: title carried from prior, status updated, output added, input retained
+    expect(snap.title).toBe('read_file');
+    expect(snap.status).toBe('completed');
+    expect(snap.rawOutput).toBe('file body');
+    expect(snap.rawInput).toEqual({ path: 'a.ts' });
+  });
+
+  it('maps available_commands_update → a commands event', () => {
+    const events = mapSessionUpdate(
+      note({
+        sessionUpdate: 'available_commands_update',
+        availableCommands: [
+          { name: 'plan', description: 'make a plan' },
+          { name: 'review', description: null },
+        ],
+      } as never),
+    );
+    expect(events).toEqual([
+      {
+        type: 'commands',
+        commands: [
+          { name: 'plan', description: 'make a plan' },
+          { name: 'review', description: undefined },
+        ],
+      },
+    ]);
+  });
+
+  it('returns [] for unhandled update kinds (plan, mode change)', () => {
+    expect(mapSessionUpdate(note({ sessionUpdate: 'plan', entries: [] } as never))).toEqual([]);
+    expect(
+      mapSessionUpdate(note({ sessionUpdate: 'current_mode_update', currentModeId: 'code' } as never)),
+    ).toEqual([]);
+  });
+});

apps/coder/src/services/__tests__/agent-pool.test.ts

@@ -0,0 +1,233 @@
+import { describe, it, expect, vi } from 'vitest';
+import { AgentPool, OPENCODE_POOL_KEY } from '../agent-pool.js';
+import type {
+  AgentBackend,
+  AgentSessionHandle,
+  EnsureSessionOpts,
+  PromptCtx,
+  TurnResult,
+} from '../agent-backend.js';
+
+/**
+ * v2.6 Phase 3 — AgentPool lifecycle unit test (T.1). No DB / no child process:
+ * a fake AgentBackend records dispose + reports busy/health, so we exercise
+ * get-or-create, idle eviction, the LRU cap, the busy-never-evict rule, closeChat,
+ * and dispose-drains directly. The pure decisions are covered separately in
+ * backends/__tests__/lifecycle-decisions.test.ts; this verifies the wiring.
+ */
+
+class FakeBackend implements AgentBackend {
+  disposed = 0;
+  closedSessions = 0;
+  private busyFlag = false;
+  tickHealthCalls = 0;
+
+  constructor(public readonly name = 'fake') {}
+
+  setBusy(b: boolean): void {
+    this.busyFlag = b;
+  }
+
+  // — AgentBackend —
+  async ensureSession(sessionId: string, opts: EnsureSessionOpts): Promise<AgentSessionHandle> {
+    return {
+      sessionId,
+      agent: opts.agent,
+      backend: 'acp_warm',
+      chatId: opts.chatId,
+      worktreeId: opts.worktreeId,
+      agentSessionId: 'fake-session',
+      serverPort: null,
+    };
+  }
+  async prompt(_h: AgentSessionHandle, _input: string, _ctx: PromptCtx): Promise<TurnResult> {
+    return { ok: true };
+  }
+  async closeSession(): Promise<void> {
+    this.closedSessions++;
+  }
+  async dispose(): Promise<void> {
+    this.disposed++;
+  }
+  health(): 'up' | 'down' {
+    return 'up';
+  }
+  isBusy(): boolean {
+    return this.busyFlag;
+  }
+  async tickHealth(): Promise<void> {
+    this.tickHealthCalls++;
+  }
+}
+
+describe('AgentPool — get/register/touch (3.1)', () => {
+  it('register then get returns the same backend', () => {
+    const pool = new AgentPool();
+    const b = new FakeBackend();
+    pool.register('chat-1', 'goose', b);
+    expect(pool.get('chat-1', 'goose')).toBe(b);
+    expect(pool.get('chat-1', 'qwen')).toBeUndefined();
+  });
+
+  it('peek does NOT exist for a missing key', () => {
+    const pool = new AgentPool();
+    expect(pool.peek('nope', 'goose')).toBeUndefined();
+  });
+
+  it('health reports size + busy count', () => {
+    const pool = new AgentPool();
+    const a = new FakeBackend();
+    const b = new FakeBackend();
+    b.setBusy(true);
+    pool.register('c1', 'goose', a);
+    pool.register('c2', 'qwen', b);
+    expect(pool.health()).toEqual({ size: 2, busy: 1 });
+  });
+});
+
+describe('AgentPool.sweep — idle TTL eviction (3.1)', () => {
+  it('evicts an idle backend past the TTL and disposes it', async () => {
+    const pool = new AgentPool({ idleTtlMs: 1_000, maxLive: 100 });
+    const b = new FakeBackend();
+    pool.register('c1', 'goose', b);
+    // Sweep with now far past the registration → idle → evicted.
+    const { evicted } = await pool.sweep(Date.now() + 10_000);
+    expect(evicted).toEqual(['c1:goose']);
+    expect(b.disposed).toBe(1);
+    expect(pool.get('c1', 'goose')).toBeUndefined();
+  });
+
+  it('never evicts a busy backend even past the TTL', async () => {
+    const pool = new AgentPool({ idleTtlMs: 1_000, maxLive: 100 });
+    const b = new FakeBackend();
+    b.setBusy(true);
+    pool.register('c1', 'goose', b);
+    const { evicted } = await pool.sweep(Date.now() + 10_000);
+    expect(evicted).toEqual([]);
+    expect(b.disposed).toBe(0);
+    expect(pool.get('c1', 'goose')).toBe(b);
+  });
+
+  it('touch keeps a backend warm so the TTL measures from the last turn', async () => {
+    const pool = new AgentPool({ idleTtlMs: 5_000, maxLive: 100 });
+    const b = new FakeBackend();
+    pool.register('c1', 'goose', b);
+    const base = Date.now();
+    // 4s later, touch — resets activity. A sweep at +6s from base is only +2s from
+    // the touch → still within TTL → not evicted.
+    vi.spyOn(Date, 'now').mockReturnValue(base + 4_000);
+    pool.touch('c1', 'goose');
+    vi.restoreAllMocks();
+    const { evicted } = await pool.sweep(base + 6_000);
+    expect(evicted).toEqual([]);
+  });
+});
+
+describe('AgentPool.sweep — LRU cap (3.4)', () => {
+  it('evicts the least-recently-used beyond the cap', async () => {
+    const pool = new AgentPool({ idleTtlMs: 1_000_000, maxLive: 2 });
+    const base = 1_000_000;
+    const mk = (key: string, regAt: number) => {
+      vi.spyOn(Date, 'now').mockReturnValue(regAt);
+      const b = new FakeBackend(key);
+      const [chat, agent] = key.split(':');
+      pool.register(chat!, agent!, b);
+      vi.restoreAllMocks();
+      return b;
+    };
+    const a = mk('c1:goose', base + 100);
+    const b = mk('c2:goose', base + 300);
+    const c = mk('c3:goose', base + 200);
+    // 3 entries, cap 2, all within idle TTL → LRU (oldest = a@+100) evicted.
+    const { evicted } = await pool.sweep(base + 1_000);
+    expect(evicted).toEqual(['c1:goose']);
+    expect(a.disposed).toBe(1);
+    expect(b.disposed).toBe(0);
+    expect(c.disposed).toBe(0);
+  });
+});
+
+describe('AgentPool.sweep — proactive health probe (3.2)', () => {
+  it('drives each backend tickHealth before eviction', async () => {
+    const pool = new AgentPool({ idleTtlMs: 1_000_000, maxLive: 100 });
+    const b = new FakeBackend();
+    pool.register('c1', 'opencode', b);
+    await pool.sweep(Date.now());
+    expect(b.tickHealthCalls).toBe(1);
+  });
+});
+
+describe('AgentPool.closeChat — chat-close teardown (3.3)', () => {
+  it('disposes only the matching chat keys, leaving others + the shared server', async () => {
+    const pool = new AgentPool();
+    const goose = new FakeBackend('goose');
+    const qwen = new FakeBackend('qwen');
+    const other = new FakeBackend('other-chat');
+    const ocServer = new FakeBackend('opencode-server');
+    pool.register('chat-1', 'goose', goose);
+    pool.register('chat-1', 'qwen', qwen);
+    pool.register('chat-2', 'goose', other);
+    pool.register(OPENCODE_POOL_KEY, 'opencode', ocServer);
+
+    const removed = await pool.closeChat('chat-1');
+    expect(removed.sort()).toEqual(['chat-1:goose', 'chat-1:qwen']);
+    expect(goose.disposed).toBe(1);
+    expect(qwen.disposed).toBe(1);
+    // other chat + shared opencode server untouched.
+    expect(other.disposed).toBe(0);
+    expect(ocServer.disposed).toBe(0);
+    expect(pool.peek('chat-2', 'goose')).toBe(other);
+    expect(pool.peek(OPENCODE_POOL_KEY, 'opencode')).toBe(ocServer);
+  });
+
+  it('does not dispose a busy backend on closeChat', async () => {
+    const pool = new AgentPool();
+    const b = new FakeBackend();
+    b.setBusy(true);
+    pool.register('chat-1', 'goose', b);
+    const removed = await pool.closeChat('chat-1');
+    expect(removed).toEqual([]);
+    expect(b.disposed).toBe(0);
+  });
+
+  it('does not match a chat id that is a prefix of another', async () => {
+    // 'chat-1' must not match 'chat-10' — keys are `${chatId}:${agent}` so the
+    // colon delimiter prevents the prefix collision.
+    const pool = new AgentPool();
+    const a = new FakeBackend();
+    const b = new FakeBackend();
+    pool.register('chat-1', 'goose', a);
+    pool.register('chat-10', 'goose', b);
+    await pool.closeChat('chat-1');
+    expect(a.disposed).toBe(1);
+    expect(b.disposed).toBe(0);
+    expect(pool.peek('chat-10', 'goose')).toBe(b);
+  });
+});
+
+describe('AgentPool.dispose — drain all (T.1)', () => {
+  it('disposes every backend and clears the map', async () => {
+    const pool = new AgentPool();
+    const a = new FakeBackend();
+    const b = new FakeBackend();
+    pool.register('c1', 'goose', a);
+    pool.register('c2', 'qwen', b);
+    await pool.dispose();
+    expect(a.disposed).toBe(1);
+    expect(b.disposed).toBe(1);
+    expect(pool.health()).toEqual({ size: 0, busy: 0 });
+  });
+
+  it('tolerates a backend whose dispose throws', async () => {
+    const pool = new AgentPool();
+    const good = new FakeBackend();
+    const bad = new FakeBackend();
+    bad.dispose = async () => {
+      throw new Error('boom');
+    };
+    pool.register('c1', 'goose', bad);
+    pool.register('c2', 'qwen', good);
+    await expect(pool.dispose()).resolves.toBeUndefined();
+    expect(good.disposed).toBe(1);
+  });
+});

apps/coder/src/services/__tests__/checkpoints.test.ts

@@ -0,0 +1,252 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { rm, mkdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import postgres from 'postgres';
+import {
+  buildShadowCommitCommand,
+  createCheckpoint,
+  restoreCheckpoint,
+  CheckpointNotFoundError,
+} from '../checkpoints.js';
+import { ensureSessionWorktree } from '../worktrees.js';
+import { hostExec } from '../host-exec.js';
+
+/**
+ * write-edit-robustness #4 — worktree checkpoint tests.
+ *
+ * Pure-helper coverage (no DB / no host) for the shadow-commit command builder,
+ * plus a DB+git integration block (DB-opt-in via DATABASE_URL, skips cleanly
+ * otherwise; mirrors reconnect_integration.test.ts) that exercises the real
+ * create → restore round trip against a worktree on the host fs.
+ */
+
+describe('buildShadowCommitCommand (pure)', () => {
+  it('parks the commit under refs/boocode/checkpoints/<id> and prints only the SHA', () => {
+    const cmd = buildShadowCommitCommand('/tmp/booworktrees/sess-abc', 'cp-id-123');
+    // Uses a temp index so the real working tree/index is untouched.
+    expect(cmd).toContain('TMP=$(mktemp)');
+    expect(cmd).toContain('GIT_INDEX_FILE="$TMP" git read-tree HEAD');
+    expect(cmd).toContain('GIT_INDEX_FILE="$TMP" git add -A');
+    expect(cmd).toContain('git write-tree');
+    expect(cmd).toContain("git commit-tree \"$TREE\" -p HEAD -m \"boocode checkpoint\"");
+    // Ref name matches the row id, and stdout is ONLY the SHA (printf, no newline).
+    expect(cmd).toContain("update-ref 'refs/boocode/checkpoints/cp-id-123'");
+    expect(cmd).toContain("printf '%s' \"$SHA\"");
+    expect(cmd).not.toContain('echo "$SHA"');
+  });
+
+  it('shell-escapes the worktree path and the id', () => {
+    const cmd = buildShadowCommitCommand("/tmp/it's a path", "id'; rm -rf /");
+    // Single quotes inside the path/id are escaped via the '\'' wrapping idiom — no
+    // bare interpolation that could break out of the quoting.
+    expect(cmd).toContain("cd '/tmp/it'\\''s a path'");
+    expect(cmd).toContain("refs/boocode/checkpoints/id'\\''; rm -rf /");
+  });
+});
+
+describe.runIf(!!process.env.DATABASE_URL)('checkpoint create + restore (DB + git)', () => {
+  let sql: ReturnType<typeof postgres>;
+  const stamp = Date.now();
+  const projectDir = `/tmp/boocode-checkpoint-proj-${stamp}`;
+  let projectId: string;
+  let sessionId: string;
+  let chatId: string;
+  let worktreePath: string;
+
+  beforeAll(async () => {
+    sql = postgres(process.env.DATABASE_URL!, { max: 3 });
+
+    // Server schema first (FK targets), then coder schema (worktrees + checkpoints).
+    const serverSchema = resolve(__dirname, '../../../../server/src/schema.sql');
+    const coderSchema = resolve(__dirname, '../../schema.sql');
+    await sql.unsafe(readFileSync(serverSchema, 'utf8'));
+    await sql.unsafe(readFileSync(coderSchema, 'utf8'));
+
+    await mkdir(projectDir, { recursive: true });
+    await hostExec(
+      `cd ${projectDir} && git init -q && git config user.email t@t && git config user.name t ` +
+        `&& echo hello > README.md && git add -A && git commit -qm init`,
+      { timeoutMs: 20_000 },
+    );
+
+    const [project] = await sql<{ id: string }[]>`
+      INSERT INTO projects (name, path, status) VALUES ('checkpoint-test', ${projectDir}, 'open') RETURNING id
+    `;
+    projectId = project!.id;
+    const [session] = await sql<{ id: string }[]>`
+      INSERT INTO sessions (project_id, name, model, status)
+      VALUES (${projectId}, 'cp', 'm', 'open') RETURNING id
+    `;
+    sessionId = session!.id;
+    const [chat] = await sql<{ id: string }[]>`
+      INSERT INTO chats (session_id, name, status) VALUES (${sessionId}, 'tab', 'open') RETURNING id
+    `;
+    chatId = chat!.id;
+
+    const wt = await ensureSessionWorktree(sql, projectDir, sessionId);
+    worktreePath = wt.worktreePath;
+  });
+
+  afterAll(async () => {
+    if (sql) {
+      const rows = await sql<{ path: string }[]>`SELECT path FROM worktrees WHERE session_id = ${sessionId}`.catch(() => []);
+      for (const r of rows) {
+        await hostExec(`git -C ${projectDir} worktree remove ${r.path} --force`, { timeoutMs: 10_000 }).catch(() => {});
+      }
+      await sql`DELETE FROM checkpoints WHERE chat_id = ${chatId}`.catch(() => {});
+      await sql`DELETE FROM agent_sessions WHERE chat_id = ${chatId}`.catch(() => {});
+      await sql`DELETE FROM worktrees WHERE session_id = ${sessionId}`.catch(() => {});
+      await sql`DELETE FROM chats WHERE id = ${chatId}`.catch(() => {});
+      await sql`DELETE FROM sessions WHERE id = ${sessionId}`.catch(() => {});
+      await sql`DELETE FROM projects WHERE id = ${projectId}`.catch(() => {});
+      await sql.end({ timeout: 5 });
+    }
+    await rm(projectDir, { recursive: true, force: true });
+  });
+
+  it('createCheckpoint inserts a row + a private ref capturing tracked + untracked', async () => {
+    const [wt] = await sql<{ id: string }[]>`SELECT id FROM worktrees WHERE session_id = ${sessionId} AND status = 'active'`;
+    const worktreeId = wt!.id;
+
+    // Pre-turn untracked + tracked-edit state the agent will start from.
+    await hostExec(`cd ${worktreePath} && echo edited >> README.md && echo new > extra.txt`, { timeoutMs: 10_000 });
+
+    const [assistantMsg] = await sql<{ id: string }[]>`
+      INSERT INTO messages (session_id, chat_id, role, content, status)
+      VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming') RETURNING id
+    `;
+    const messageId = assistantMsg!.id;
+
+    const cp = await createCheckpoint(sql, {
+      chatId,
+      sessionId,
+      worktreeId,
+      worktreePath,
+      messageId,
+    });
+    expect(cp).not.toBeNull();
+    expect(cp!.commit_sha).toMatch(/^[0-9a-f]{40}$/);
+
+    const [row] = await sql<{ commit_sha: string; worktree_id: string; message_id: string }[]>`
+      SELECT commit_sha, worktree_id, message_id FROM checkpoints WHERE id = ${cp!.id}
+    `;
+    expect(row!.commit_sha).toBe(cp!.commit_sha);
+    expect(row!.worktree_id).toBe(worktreeId);
+    expect(row!.message_id).toBe(messageId);
+
+    // The ref exists and the captured tree carries the untracked file (proves the
+    // temp-index `git add -A` snapshotted untracked content).
+    const refLs = await hostExec(
+      `git -C ${worktreePath} ls-tree -r --name-only ${cp!.commit_sha}`,
+      { timeoutMs: 10_000 },
+    );
+    expect(refLs.exitCode).toBe(0);
+    expect(refLs.stdout).toContain('extra.txt');
+
+    // The shadow commit did NOT disturb the real working tree: extra.txt is still
+    // present + still untracked (status shows it).
+    const status = await hostExec(`git -C ${worktreePath} status --porcelain`, { timeoutMs: 10_000 });
+    expect(status.stdout).toContain('extra.txt');
+  });
+
+  it('restoreCheckpoint resets the worktree, trims the transcript, and drops later checkpoints', async () => {
+    // Clean slate for this test: reset the worktree to HEAD, clear prior rows.
+    await hostExec(`git -C ${worktreePath} reset --hard HEAD && git -C ${worktreePath} clean -fd`, { timeoutMs: 10_000 });
+    await sql`DELETE FROM checkpoints WHERE chat_id = ${chatId}`;
+    await sql`DELETE FROM messages WHERE chat_id = ${chatId}`;
+
+    const [wt] = await sql<{ id: string }[]>`SELECT id FROM worktrees WHERE session_id = ${sessionId} AND status = 'active'`;
+    const worktreeId = wt!.id;
+
+    // Turn 1: a user msg, then the assistant turn the checkpoint anchors. The
+    // worktree is pristine (matches HEAD) when this checkpoint is captured.
+    await sql`INSERT INTO messages (session_id, chat_id, role, content, status) VALUES (${sessionId}, ${chatId}, 'user', 'do it', 'complete')`;
+    const [a1] = await sql<{ id: string }[]>`
+      INSERT INTO messages (session_id, chat_id, role, content, status)
+      VALUES (${sessionId}, ${chatId}, 'assistant', 'turn 1', 'complete') RETURNING id
+    `;
+    const cp1 = await createCheckpoint(sql, { chatId, sessionId, worktreeId, worktreePath, messageId: a1!.id });
+    expect(cp1).not.toBeNull();
+
+    // The agent (turn 1) writes a file into the worktree.
+    await hostExec(`cd ${worktreePath} && echo agent-wrote > agent.txt`, { timeoutMs: 10_000 });
+
+    // Turn 2: another user msg + assistant turn, AND a second (later) checkpoint.
+    await sql`INSERT INTO messages (session_id, chat_id, role, content, status) VALUES (${sessionId}, ${chatId}, 'user', 'more', 'complete')`;
+    const [a2] = await sql<{ id: string }[]>`
+      INSERT INTO messages (session_id, chat_id, role, content, status)
+      VALUES (${sessionId}, ${chatId}, 'assistant', 'turn 2', 'complete') RETURNING id
+    `;
+    const cp2 = await createCheckpoint(sql, { chatId, sessionId, worktreeId, worktreePath, messageId: a2!.id });
+    expect(cp2).not.toBeNull();
+
+    // An agent_sessions row that restore should mark 'crashed'.
+    await sql`
+      INSERT INTO agent_sessions (chat_id, session_id, worktree_id, agent, backend, agent_session_id, status, last_active_at)
+      VALUES (${chatId}, ${sessionId}, ${worktreeId}, 'goose', 'acp_warm', 'sess-1', 'active', clock_timestamp())
+      ON CONFLICT (chat_id, agent) DO UPDATE SET status = 'active'
+    `;
+
+    const before = await sql<{ id: string }[]>`SELECT id FROM messages WHERE chat_id = ${chatId} ORDER BY created_at`;
+    expect(before.length).toBe(4); // user, a1, user, a2
+
+    // Restore to cp1 (before turn 1's assistant message).
+    const result = await restoreCheckpoint(sql, cp1!.id, { sessionId });
+    expect(result.checkpoint_id).toBe(cp1!.id);
+    expect(result.worktree_reset).toBe(true);
+    expect(result.backend_reset).toBe(true);
+    // a1, user(turn2), a2 deleted (created_at >= a1) → 3 trimmed.
+    expect(result.messages_deleted).toBe(3);
+
+    // Transcript trimmed to just the first user message.
+    const after = await sql<{ role: string; content: string }[]>`SELECT role, content FROM messages WHERE chat_id = ${chatId} ORDER BY created_at`;
+    expect(after.length).toBe(1);
+    expect(after[0]!.role).toBe('user');
+
+    // Worktree reset: the agent's file is gone (it was written after cp1).
+    const ls = await hostExec(`ls ${worktreePath}/agent.txt`, { timeoutMs: 10_000 });
+    expect(ls.exitCode).not.toBe(0);
+
+    // The agent_sessions row was reset to 'crashed'.
+    const [as] = await sql<{ status: string }[]>`SELECT status FROM agent_sessions WHERE chat_id = ${chatId} AND agent = 'goose'`;
+    expect(as!.status).toBe('crashed');
+
+    // cp1 survives (re-restorable); cp2 (later) was dropped.
+    const cps = await sql<{ id: string }[]>`SELECT id FROM checkpoints WHERE chat_id = ${chatId}`;
+    expect(cps.map((c) => c.id)).toEqual([cp1!.id]);
+  });
+
+  it('restoreCheckpoint throws CheckpointNotFoundError for an unknown id', async () => {
+    await expect(
+      restoreCheckpoint(sql, '00000000-0000-0000-0000-000000000000', { sessionId }),
+    ).rejects.toBeInstanceOf(CheckpointNotFoundError);
+  });
+
+  it('restoreCheckpoint throws when the checkpoint is not in the requested session', async () => {
+    // A checkpoint whose session_id differs from the route's sessionId.
+    const [wt] = await sql<{ id: string }[]>`SELECT id FROM worktrees WHERE session_id = ${sessionId} AND status = 'active'`;
+    const cp = await createCheckpoint(sql, { chatId, sessionId, worktreeId: wt!.id, worktreePath, messageId: null });
+    expect(cp).not.toBeNull();
+    await expect(
+      restoreCheckpoint(sql, cp!.id, { sessionId: '11111111-1111-1111-1111-111111111111' }),
+    ).rejects.toBeInstanceOf(CheckpointNotFoundError);
+    await sql`DELETE FROM checkpoints WHERE id = ${cp!.id}`;
+  });
+
+  it('restoreCheckpoint denies a NULL-session_id checkpoint from another session (no fail-open IDOR)', async () => {
+    // Regression for the fail-open authorization bug: a checkpoint row whose
+    // denormalized session_id is NULL must STILL be scoped via its chat's owning
+    // session (chats.session_id), not skipped. The old guard `cp.session_id &&
+    // cp.session_id !== sessionId` fell through on NULL → cross-session restore.
+    const [row] = await sql<{ id: string }[]>`
+      INSERT INTO checkpoints (chat_id, session_id, message_id, commit_sha)
+      VALUES (${chatId}, NULL, NULL, 'deadbeef')
+      RETURNING id
+    `;
+    await expect(
+      restoreCheckpoint(sql, row!.id, { sessionId: '22222222-2222-2222-2222-222222222222' }),
+    ).rejects.toBeInstanceOf(CheckpointNotFoundError);
+    await sql`DELETE FROM checkpoints WHERE id = ${row!.id}`;
+  });
+});

apps/coder/src/services/__tests__/frame-emitter.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from 'vitest';
+import type { Broker } from '@boocode/server/broker';
+import { makeFrameEmitter } from '../frame-emitter.js';
+import { makeDcpStreamStripper } from '../dcp-strip.js';
+import type { AcpToolSnapshot } from '../acp-tool-snapshot.js';
+
+/**
+ * makeFrameEmitter (v2.7 audit reshape): the AgentEvent → WS-frame mapping + turn
+ * accumulators extracted from AcpStreamContext. Pure-ish over an injected broker.
+ */
+
+function fakeBroker(): { broker: Broker; frames: Array<{ sid: string; frame: Record<string, unknown> }> } {
+  const frames: Array<{ sid: string; frame: Record<string, unknown> }> = [];
+  const broker = {
+    publishFrame: (sid: string, frame: unknown) => {
+      frames.push({ sid, frame: frame as Record<string, unknown> });
+    },
+  } as unknown as Broker;
+  return { broker, frames };
+}
+
+const toolSnap: AcpToolSnapshot = { toolCallId: 'c1', title: 'grep', status: 'completed', rawOutput: 'x' };
+
+describe('makeFrameEmitter — streaming frames', () => {
+  it('maps text/reasoning/tool events to delta/reasoning_delta/tool_call frames', () => {
+    const { broker, frames } = fakeBroker();
+    const em = makeFrameEmitter({ broker, sessionId: 's1', chatId: 'ch1', assistantId: 'm1' });
+
+    em.onEvent({ type: 'text', text: 'hello ' });
+    em.onEvent({ type: 'reasoning', text: 'mulling' });
+    em.onEvent({ type: 'tool_call', toolCall: toolSnap });
+
+    expect(frames.map((f) => f.frame.type)).toEqual(['delta', 'reasoning_delta', 'tool_call']);
+    expect(frames[0]!.frame).toMatchObject({ message_id: 'm1', chat_id: 'ch1', content: 'hello ' });
+    expect(frames[2]!.frame).toMatchObject({ message_id: 'm1', chat_id: 'ch1' });
+    expect(em.output).toBe('hello ');
+    expect(em.reasoningText).toBe('mulling');
+    expect(em.snapshots).toHaveLength(1);
+  });
+
+  it('publishes a tool_call frame for BOTH tool_call and tool_update events', () => {
+    const { broker, frames } = fakeBroker();
+    const em = makeFrameEmitter({ broker, sessionId: 's1', chatId: 'ch1', assistantId: 'm1' });
+    em.onEvent({ type: 'tool_update', toolCall: toolSnap });
+    expect(frames).toHaveLength(1);
+    expect(frames[0]!.frame.type).toBe('tool_call');
+  });
+
+  it('publishes an agent_commands frame and merges the command cache', () => {
+    const { broker, frames } = fakeBroker();
+    const taskId = `task-fe-${Math.floor(performance.now())}-${frames.length}`;
+    const em = makeFrameEmitter({ broker, sessionId: 's1', chatId: 'ch1', assistantId: 'm1', taskId });
+    em.onEvent({ type: 'commands', commands: [{ name: 'plan' }] });
+    expect(frames).toHaveLength(1);
+    expect(frames[0]!.frame).toMatchObject({ type: 'agent_commands', task_id: taskId, session_id: 's1' });
+  });
+
+  it('does not publish a commands frame without a taskId', () => {
+    const { broker, frames } = fakeBroker();
+    const em = makeFrameEmitter({ broker, sessionId: 's1', chatId: 'ch1', assistantId: 'm1' });
+    em.onEvent({ type: 'commands', commands: [{ name: 'plan' }] });
+    expect(frames).toHaveLength(0);
+  });
+});
+
+describe('makeFrameEmitter — no broker (one-shot accumulation)', () => {
+  it('accumulates output/reasoning/snapshots but publishes nothing', () => {
+    const em = makeFrameEmitter({ sessionId: 's1', chatId: 'ch1', assistantId: 'm1' });
+    em.onEvent({ type: 'text', text: 'abc' });
+    em.onEvent({ type: 'reasoning', text: 'r' });
+    em.onEvent({ type: 'tool_call', toolCall: toolSnap });
+    expect(em.output).toBe('abc');
+    expect(em.reasoningText).toBe('r');
+    expect(em.snapshots).toHaveLength(1);
+  });
+});
+
+describe('makeFrameEmitter — dcp stripping (opencode path contract)', () => {
+  it('strips a split dcp tag across deltas and flushes the tail on finalize', () => {
+    const { broker, frames } = fakeBroker();
+    const em = makeFrameEmitter({ broker, sessionId: 's1', chatId: 'ch1', assistantId: 'm1', dcp: makeDcpStreamStripper() });
+
+    for (const chunk of ['Answer.', '<dcp', '-message', '-id>m1</dcp', '-message-id>', ' tail']) {
+      em.onEvent({ type: 'text', text: chunk });
+    }
+    em.finalize();
+
+    expect(em.output).toBe('Answer. tail');
+    const published = frames.filter((f) => f.frame.type === 'delta').map((f) => f.frame.content).join('');
+    expect(published).toBe('Answer. tail');
+  });
+
+  it('finalize is a no-op without a dcp stripper', () => {
+    const { broker, frames } = fakeBroker();
+    const em = makeFrameEmitter({ broker, sessionId: 's1', chatId: 'ch1', assistantId: 'm1' });
+    em.onEvent({ type: 'text', text: 'raw <dcp-message-id>m</dcp-message-id>' });
+    em.finalize();
+    // No stripping without a stripper — verbatim text (prior ACP-path behavior).
+    expect(em.output).toBe('raw <dcp-message-id>m</dcp-message-id>');
+    expect(frames).toHaveLength(1);
+  });
+});

apps/coder/src/services/__tests__/fuzzy-match.test.ts

@@ -0,0 +1,173 @@
+import { describe, it, expect } from 'vitest';
+import { locateMatch, SIMILARITY_THRESHOLD } from '../fuzzy-match.js';
+
+// Helper: assert a resolved span and slice it back out of the content so the
+// test pins the EXACT file text the caller would replace.
+function span(result: ReturnType<typeof locateMatch>): { start: number; end: number } {
+  if (result.kind !== 'exact' && result.kind !== 'fuzzy') {
+    throw new Error(`expected a located span, got ${result.kind}`);
+  }
+  return { start: result.start, end: result.end };
+}
+
+describe('locateMatch — strategy 1: exact', () => {
+  it('returns an exact unique span', () => {
+    const content = 'alpha\nbeta\ngamma\n';
+    const result = locateMatch(content, 'beta');
+    expect(result.kind).toBe('exact');
+    const { start, end } = span(result);
+    expect(content.slice(start, end)).toBe('beta');
+  });
+
+  it('returns the right offsets for a multi-line exact needle', () => {
+    const content = 'one\ntwo\nthree\nfour\n';
+    const needle = 'two\nthree';
+    const result = locateMatch(content, needle);
+    expect(result.kind).toBe('exact');
+    const { start, end } = span(result);
+    expect(content.slice(start, end)).toBe(needle);
+  });
+
+  it('refuses when the exact needle occurs more than once', () => {
+    const content = 'foo\nbar\nfoo\nbar\nfoo\n';
+    const result = locateMatch(content, 'foo');
+    expect(result).toEqual({ kind: 'ambiguous', count: 3 });
+  });
+});
+
+describe('locateMatch — strategy 2: per-line whitespace', () => {
+  it('matches across trailing-whitespace drift at the real span', () => {
+    // File has trailing spaces the model dropped from a TWO-line copy. A
+    // single-line needle would be located by exact indexOf (it's a substring),
+    // so use two lines where line 1's trailing ws breaks an exact substring run.
+    const content = 'function f() {\n  setup();   \n  return 1;\n}\n';
+    const needle = '  setup();\n  return 1;'; // line 1 missing trailing spaces
+    const result = locateMatch(content, needle);
+    expect(result.kind).toBe('fuzzy');
+    const { start, end } = span(result);
+    // The returned span covers the ORIGINAL lines including the trailing spaces.
+    expect(content.slice(start, end)).toBe('  setup();   \n  return 1;');
+  });
+
+  it('matches across indentation drift (multi-line block)', () => {
+    // File indents with 4 spaces; model emitted 2-space indentation. trimEnd
+    // alone does not normalize LEADING whitespace, so this exercises... actually
+    // leading-indent drift is a Levenshtein-tier fallback. Here we keep the
+    // leading indent identical and drift only trailing whitespace per line.
+    const content = ['if (x) {', '    doThing();    ', '    doOther();', '}'].join('\n');
+    const needle = ['    doThing();', '    doOther();'].join('\n');
+    const result = locateMatch(content, needle);
+    expect(result.kind).toBe('fuzzy');
+    const { start, end } = span(result);
+    expect(content.slice(start, end)).toBe('    doThing();    \n    doOther();');
+  });
+
+  it('ignores leading/trailing blank needle lines', () => {
+    const content = 'header\nbody line\nfooter\n';
+    const needle = '\n\nbody line\n\n';
+    const result = locateMatch(content, needle);
+    expect(result.kind).toBe('fuzzy');
+    const { start, end } = span(result);
+    expect(content.slice(start, end)).toBe('body line');
+  });
+
+  it('reports ambiguous when a whitespace-window matches twice', () => {
+    // Both line 1 and line 4 differ from the needle only by trailing whitespace,
+    // so exact indexOf fails (no exact substring) and the whitespace tier finds
+    // two equivalent windows → ambiguous.
+    const content = 'x = 1;  \ny = 2;\nz = 3;\nx = 1;\t\n';
+    const needle = 'x = 1;'; // no trailing ws → not an exact substring of either line
+    const result = locateMatch(content, needle);
+    expect(result).toEqual({ kind: 'ambiguous', count: 2 });
+  });
+});
+
+describe('locateMatch — strategy 3: unicode canonicalization', () => {
+  it('matches across curly quotes', () => {
+    const content = "const s = 'hello';\n";
+    const needle = 'const s = ‘hello’;'; // ‘hello’
+    const result = locateMatch(content, needle);
+    expect(result.kind).toBe('fuzzy');
+    const { start, end } = span(result);
+    // Span maps back to ORIGINAL (straight-quote) text.
+    expect(content.slice(start, end)).toBe("const s = 'hello';");
+  });
+
+  it('matches across curly double-quotes', () => {
+    const content = 'log("done");\n';
+    const needle = 'log(“done”);'; // “done”
+    const result = locateMatch(content, needle);
+    expect(result.kind).toBe('fuzzy');
+    const { start, end } = span(result);
+    expect(content.slice(start, end)).toBe('log("done");');
+  });
+
+  it('matches across an em-dash drift', () => {
+    const content = 'range 1-10 inclusive\n';
+    const needle = 'range 1—10 inclusive'; // em-dash
+    const result = locateMatch(content, needle);
+    expect(result.kind).toBe('fuzzy');
+    const { start, end } = span(result);
+    expect(content.slice(start, end)).toBe('range 1-10 inclusive');
+  });
+
+  it('matches across a non-breaking space drift', () => {
+    const content = 'a b c\n'; // plain spaces
+    const needle = 'a b c'; // nbsp between words
+    const result = locateMatch(content, needle);
+    expect(result.kind).toBe('fuzzy');
+    const { start, end } = span(result);
+    expect(content.slice(start, end)).toBe('a b c');
+  });
+});
+
+describe('locateMatch — strategy 4: Levenshtein', () => {
+  it('matches a >= threshold near-miss (small typo drift)', () => {
+    // Needle has a one-char typo ('totals' vs 'total') so it is NOT an exact
+    // substring and the whitespace/canonical tiers (which require equality) both
+    // miss; Levenshtein similarity stays well above the 0.66 floor.
+    const content = 'const total = sum + tax;\n';
+    const needle = 'const totals = sum + tax;';
+    const result = locateMatch(content, needle);
+    expect(result.kind).toBe('fuzzy');
+    const { start, end } = span(result);
+    // Span maps to the real (correctly-spelled) file line.
+    expect(content.slice(start, end)).toBe('const total = sum + tax;');
+  });
+
+  it('matches a multi-line block with indentation drift via Levenshtein', () => {
+    const content = ['function g() {', '  return compute(a, b);', '}'].join('\n');
+    // 6-space indent vs file's 2-space; trimEnd does not fix leading indent, so
+    // this lands on the Levenshtein tier (joined-trim makes it identical → ~1.0).
+    const needle = ['      return compute(a, b);'].join('\n');
+    const result = locateMatch(content, needle);
+    expect(result.kind).toBe('fuzzy');
+    const { start, end } = span(result);
+    expect(content.slice(start, end)).toBe('  return compute(a, b);');
+  });
+
+  it('returns not_found for a below-threshold miss', () => {
+    const content = 'the quick brown fox jumps over the lazy dog\n';
+    const needle = 'completely unrelated string of text here xyz';
+    const result = locateMatch(content, needle);
+    expect(result).toEqual({ kind: 'not_found' });
+  });
+
+  it('returns not_found for a genuinely-absent needle', () => {
+    const content = 'alpha\nbeta\ngamma\n';
+    const needle = 'this content does not exist anywhere at all';
+    const result = locateMatch(content, needle);
+    expect(result).toEqual({ kind: 'not_found' });
+  });
+});
+
+describe('locateMatch — edge cases', () => {
+  it('returns not_found for an empty needle', () => {
+    expect(locateMatch('anything', '')).toEqual({ kind: 'not_found' });
+  });
+
+  it('exposes a sane similarity threshold', () => {
+    expect(SIMILARITY_THRESHOLD).toBeGreaterThan(0);
+    expect(SIMILARITY_THRESHOLD).toBeLessThanOrEqual(1);
+  });
+});

apps/coder/src/services/__tests__/reconnect_integration.test.ts

@@ -0,0 +1,170 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { readFileSync, existsSync } from 'node:fs';
+import { rm, mkdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import postgres from 'postgres';
+import {
+  ensureSessionWorktree,
+  closeChatBackendState,
+  rebaselineWorktreeAfterApply,
+} from '../worktrees.js';
+import { reapOrphanWorktrees } from '../orphan-worktree-reaper.js';
+import { hostExec } from '../host-exec.js';
+
+/**
+ * v2.6 Phase 3 (3.6) — reconnect-after-restart integration test.
+ *
+ * Proves the DB-truth side of crash/restart recovery: a BooCoder restart wipes the
+ * in-memory pool, but the persistent `worktrees` + `agent_sessions` rows survive,
+ * so the "next turn" re-resolves the SAME worktree (reattach, no new dir) and the
+ * agent-session row is still there to resume from. Also exercises the chat-close
+ * hook (3.3), the apply re-baseline (3.5), and the orphan reaper (3.4) end-to-end
+ * against a real git repo + postgres.
+ *
+ * Requires DATABASE_URL (DB-opt-in; skips cleanly otherwise) AND git on PATH. Runs:
+ *   DATABASE_URL='postgres://boocode:devpass@localhost:5500/boochat' pnpm -C apps/coder test
+ */
+describe.runIf(!!process.env.DATABASE_URL)('reconnect after restart (Phase 3)', () => {
+  let sql: ReturnType<typeof postgres>;
+  const stamp = Date.now();
+  const projectDir = `/tmp/boocode-reconnect-proj-${stamp}`;
+  let projectId: string;
+  let sessionId: string;
+  let chatId: string;
+
+  beforeAll(async () => {
+    sql = postgres(process.env.DATABASE_URL!, { max: 3 });
+
+    // Both schemas land in the one boochat DB: server owns sessions/chats/projects,
+    // coder owns worktrees/agent_sessions (FK targets must pre-exist → server first).
+    const serverSchema = resolve(__dirname, '../../../../server/src/schema.sql');
+    const coderSchema = resolve(__dirname, '../../schema.sql');
+    await sql.unsafe(readFileSync(serverSchema, 'utf8'));
+    await sql.unsafe(readFileSync(coderSchema, 'utf8'));
+
+    // A real git repo with one commit so worktree add / diff / rev-parse work.
+    await mkdir(projectDir, { recursive: true });
+    await hostExec(
+      `cd ${projectDir} && git init -q && git config user.email t@t && git config user.name t ` +
+        `&& echo hello > README.md && git add -A && git commit -qm init`,
+      { timeoutMs: 20_000 },
+    );
+
+    const [project] = await sql<{ id: string }[]>`
+      INSERT INTO projects (name, path, status) VALUES ('reconnect-test', ${projectDir}, 'open') RETURNING id
+    `;
+    projectId = project!.id;
+    const [session] = await sql<{ id: string }[]>`
+      INSERT INTO sessions (project_id, name, model, status)
+      VALUES (${projectId}, 'recon', 'm', 'open') RETURNING id
+    `;
+    sessionId = session!.id;
+    const [chat] = await sql<{ id: string }[]>`
+      INSERT INTO chats (session_id, name, status) VALUES (${sessionId}, 'tab', 'open') RETURNING id
+    `;
+    chatId = chat!.id;
+  });
+
+  afterAll(async () => {
+    if (sql) {
+      // Best-effort worktree cleanup before dropping rows.
+      const rows = await sql<{ path: string }[]>`SELECT path FROM worktrees WHERE session_id = ${sessionId}`.catch(() => []);
+      for (const r of rows) {
+        await hostExec(`git -C ${projectDir} worktree remove ${r.path} --force`, { timeoutMs: 10_000 }).catch(() => {});
+      }
+      await sql`DELETE FROM agent_sessions WHERE chat_id = ${chatId}`.catch(() => {});
+      await sql`DELETE FROM worktrees WHERE session_id = ${sessionId}`.catch(() => {});
+      await sql`DELETE FROM chats WHERE id = ${chatId}`.catch(() => {});
+      await sql`DELETE FROM sessions WHERE id = ${sessionId}`.catch(() => {});
+      await sql`DELETE FROM projects WHERE id = ${projectId}`.catch(() => {});
+      await sql.end({ timeout: 5 });
+    }
+    await rm(projectDir, { recursive: true, force: true });
+  });
+
+  it('reattaches the SAME worktree across a simulated restart (no new dir)', async () => {
+    // "Turn 1" — first ensureSessionWorktree creates the worktree + row.
+    const first = await ensureSessionWorktree(sql, projectDir, sessionId);
+    expect(existsSync(first.worktreePath)).toBe(true);
+    expect(first.baseCommit).toBeTruthy();
+
+    // Simulate an agent_sessions row written by turn 1 (opencode).
+    await sql`
+      INSERT INTO agent_sessions (chat_id, session_id, worktree_id, agent, backend, agent_session_id, status, last_active_at)
+      VALUES (${chatId}, ${sessionId}, ${first.worktreeId}, 'opencode', 'opencode_server', 'oc-sess-1', 'active', clock_timestamp())
+      ON CONFLICT (chat_id, agent) DO NOTHING
+    `;
+
+    // "Restart" = brand-new resolution with NO in-memory state. ensureSessionWorktree
+    // must return the EXISTING row (same id + path), proving reattach not re-create.
+    const second = await ensureSessionWorktree(sql, projectDir, sessionId);
+    expect(second.worktreeId).toBe(first.worktreeId);
+    expect(second.worktreePath).toBe(first.worktreePath);
+    expect(second.baseCommit).toBe(first.baseCommit);
+
+    // The agent_sessions row survived the "restart" with its resume handle intact.
+    const [row] = await sql<{ agent_session_id: string; status: string }[]>`
+      SELECT agent_session_id, status FROM agent_sessions WHERE chat_id = ${chatId} AND agent = 'opencode'
+    `;
+    expect(row!.agent_session_id).toBe('oc-sess-1');
+  });
+
+  it('re-baselines the worktree diff after apply (3.5)', async () => {
+    const wt = await ensureSessionWorktree(sql, projectDir, sessionId);
+    const baseBefore = wt.baseCommit;
+    // Make a change in the worktree (as an external agent would).
+    await hostExec(`cd ${wt.worktreePath} && echo change >> README.md`, { timeoutMs: 10_000 });
+
+    const r = await rebaselineWorktreeAfterApply(sql, sessionId);
+    expect(r.rebaselined).toBe(true);
+    expect(r.newBaseCommit).toBeTruthy();
+    expect(r.newBaseCommit).not.toBe(baseBefore);
+
+    const [row] = await sql<{ base_commit: string }[]>`
+      SELECT base_commit FROM worktrees WHERE session_id = ${sessionId} AND status = 'active'
+    `;
+    expect(row!.base_commit).toBe(r.newBaseCommit);
+
+    // Idempotent: a second re-baseline with no new edits is a no-op.
+    const r2 = await rebaselineWorktreeAfterApply(sql, sessionId);
+    expect(r2.rebaselined).toBe(false);
+  });
+
+  it('chat-close hook closes agent rows + removes the worktree on the last chat (3.3)', async () => {
+    // Sanity: an active worktree + agent row exist from the prior tests.
+    const beforeWt = await sql<{ id: string }[]>`SELECT id FROM worktrees WHERE session_id = ${sessionId} AND status = 'active'`;
+    expect(beforeWt.length).toBe(1);
+
+    const result = await closeChatBackendState(sql, chatId);
+    expect(result.agentRowsClosed).toBeGreaterThanOrEqual(1);
+    // chatId is the session's only chat → worktree removed (it was clean after the
+    // re-baseline commit), not at-risk.
+    expect(result.worktreeAtRisk).toBe(false);
+    expect(result.worktreeRemoved).toBe(true);
+
+    const [agentRow] = await sql<{ status: string }[]>`
+      SELECT status FROM agent_sessions WHERE chat_id = ${chatId} AND agent = 'opencode'
+    `;
+    expect(agentRow!.status).toBe('closed');
+
+    const activeWt = await sql<{ id: string }[]>`SELECT id FROM worktrees WHERE session_id = ${sessionId} AND status = 'active'`;
+    expect(activeWt.length).toBe(0); // archived, no longer active
+  });
+
+  it('orphan reaper leaves a live worktree alone and reaps a row-less dir (3.4)', async () => {
+    // Recreate a live worktree for this session (the close test archived the old one).
+    const live = await ensureSessionWorktree(sql, projectDir, sessionId);
+    expect(existsSync(live.worktreePath)).toBe(true);
+
+    // A live worktree (active row) with grace 0 must NOT be reaped.
+    const r1 = await reapOrphanWorktrees(sql, console as never, 0, Date.now());
+    expect(r1.reaped).not.toContain(live.worktreePath);
+
+    // Now archive its row (simulating a leaked dir) and reap again — it becomes an
+    // orphan and is reclaimed (it's clean → not at-risk).
+    await sql`UPDATE worktrees SET status = 'archived' WHERE id = ${live.worktreeId}`;
+    const r2 = await reapOrphanWorktrees(sql, console as never, 0, Date.now());
+    expect(r2.reaped).toContain(live.worktreePath);
+    expect(existsSync(live.worktreePath)).toBe(false);
+  });
+});

apps/coder/src/services/__tests__/stream-json-parser.test.ts

@@ -0,0 +1,189 @@
+import { describe, it, expect } from 'vitest';
+import {
+  makeStreamJsonParser,
+  makeStreamJsonState,
+  parseStreamJsonLine,
+  type AgentEventList,
+} from '../stream-json-parser.js';
+import type { AgentEvent } from '../agent-backend.js';
+import type { AcpToolSnapshot } from '../acp-tool-snapshot.js';
+
+// Helpers to JSON-encode the representative Claude-Code stream-json lines.
+const sys = (sessionId: string) =>
+  JSON.stringify({ type: 'system', subtype: 'init', session_id: sessionId, tools: ['read', 'edit'] });
+
+const streamEvent = (event: unknown) => JSON.stringify({ type: 'stream_event', event });
+
+const textDelta = (index: number, text: string) =>
+  streamEvent({ type: 'content_block_delta', index, delta: { type: 'text_delta', text } });
+
+const thinkingDelta = (index: number, thinking: string) =>
+  streamEvent({ type: 'content_block_delta', index, delta: { type: 'thinking_delta', thinking } });
+
+const toolStart = (index: number, id: string, name: string) =>
+  streamEvent({ type: 'content_block_start', index, content_block: { type: 'tool_use', id, name } });
+
+const inputJsonDelta = (index: number, partial: string) =>
+  streamEvent({ type: 'content_block_delta', index, delta: { type: 'input_json_delta', partial_json: partial } });
+
+const blockStop = (index: number) => streamEvent({ type: 'content_block_stop', index });
+
+const resultLine = (input: number, output: number, sessionId?: string) =>
+  JSON.stringify({ type: 'result', subtype: 'success', session_id: sessionId, usage: { input_tokens: input, output_tokens: output } });
+
+describe('parseStreamJsonLine (pure per-line mapping)', () => {
+  it('captures session_id from the system init line and emits no events', () => {
+    const state = makeStreamJsonState();
+    const events = parseStreamJsonLine(sys('sess-abc'), state);
+    expect(events).toEqual([]);
+    expect(state.sessionId).toBe('sess-abc');
+  });
+
+  it('maps a text_delta stream_event → a text event', () => {
+    const state = makeStreamJsonState();
+    expect(parseStreamJsonLine(textDelta(0, 'Hello'), state)).toEqual([{ type: 'text', text: 'Hello' }]);
+  });
+
+  it('maps a thinking_delta stream_event → a reasoning event', () => {
+    const state = makeStreamJsonState();
+    expect(parseStreamJsonLine(thinkingDelta(0, 'pondering'), state)).toEqual([
+      { type: 'reasoning', text: 'pondering' },
+    ]);
+  });
+
+  it('tolerates a garbage / non-JSON line (returns [], no throw)', () => {
+    const state = makeStreamJsonState();
+    expect(parseStreamJsonLine('not json at all {{{', state)).toEqual([]);
+    expect(parseStreamJsonLine('', state)).toEqual([]);
+    expect(parseStreamJsonLine('   ', state)).toEqual([]);
+    // A truncated/partial JSON object also yields [] rather than throwing.
+    expect(parseStreamJsonLine('{"type":"stream_event","eve', state)).toEqual([]);
+  });
+
+  it('ignores unknown top-level line types and the user (tool-result) line', () => {
+    const state = makeStreamJsonState();
+    expect(parseStreamJsonLine(JSON.stringify({ type: 'user', message: {} }), state)).toEqual([]);
+    expect(parseStreamJsonLine(JSON.stringify({ type: 'whatever' }), state)).toEqual([]);
+  });
+
+  it('assembles a tool call across input_json_delta chunks (split across lines)', () => {
+    const state = makeStreamJsonState();
+    // start → tool_call (running, empty args)
+    const start = parseStreamJsonLine(toolStart(1, 'toolu_1', 'edit_file'), state);
+    expect(start).toHaveLength(1);
+    expect(start[0]!.type).toBe('tool_call');
+    const startSnap = (start[0] as { type: 'tool_call'; toolCall: AcpToolSnapshot }).toolCall;
+    expect(startSnap.toolCallId).toBe('toolu_1');
+    expect(startSnap.title).toBe('edit_file');
+    expect(startSnap.status).toBe('in_progress');
+    expect(startSnap.rawInput).toEqual({});
+
+    // args streamed in fragments — no events until stop
+    expect(parseStreamJsonLine(inputJsonDelta(1, '{"path":"a'), state)).toEqual([]);
+    expect(parseStreamJsonLine(inputJsonDelta(1, '.ts","content":'), state)).toEqual([]);
+    expect(parseStreamJsonLine(inputJsonDelta(1, '"hi"}'), state)).toEqual([]);
+
+    // stop → tool_update with the parsed, fully-assembled input
+    const stop = parseStreamJsonLine(blockStop(1), state);
+    expect(stop).toHaveLength(1);
+    expect(stop[0]!.type).toBe('tool_update');
+    const stopSnap = (stop[0] as { type: 'tool_update'; toolCall: AcpToolSnapshot }).toolCall;
+    expect(stopSnap.toolCallId).toBe('toolu_1');
+    expect(stopSnap.status).toBe('completed');
+    expect(stopSnap.rawInput).toEqual({ path: 'a.ts', content: 'hi' });
+  });
+
+  it('falls back to {_raw} when accumulated tool args are not valid JSON', () => {
+    const state = makeStreamJsonState();
+    parseStreamJsonLine(toolStart(0, 'toolu_x', 'run'), state);
+    parseStreamJsonLine(inputJsonDelta(0, '{"broken'), state);
+    const stop = parseStreamJsonLine(blockStop(0), state);
+    const snap = (stop[0] as { type: 'tool_update'; toolCall: AcpToolSnapshot }).toolCall;
+    expect(snap.rawInput).toEqual({ _raw: '{"broken' });
+  });
+
+  it('captures usage from message_delta and result lines', () => {
+    const state = makeStreamJsonState();
+    parseStreamJsonLine(streamEvent({ type: 'message_delta', usage: { output_tokens: 42 } }), state);
+    expect(state.usage.outputTokens).toBe(42);
+    parseStreamJsonLine(resultLine(100, 250, 'sess-z'), state);
+    expect(state.usage.inputTokens).toBe(100);
+    expect(state.usage.outputTokens).toBe(250);
+    expect(state.sessionId).toBe('sess-z');
+  });
+
+  it('maps a terminal assistant message (fallback) → text + reasoning + tool events', () => {
+    const state = makeStreamJsonState();
+    const line = JSON.stringify({
+      type: 'assistant',
+      session_id: 'sess-asst',
+      message: {
+        content: [
+          { type: 'thinking', thinking: 'let me think' },
+          { type: 'text', text: 'Here is the answer' },
+          { type: 'tool_use', id: 'toolu_9', name: 'view_file', input: { path: 'x.ts' } },
+        ],
+        usage: { input_tokens: 5, output_tokens: 7 },
+      },
+    });
+    const events = parseStreamJsonLine(line, state);
+    expect(events).toEqual([
+      { type: 'reasoning', text: 'let me think' },
+      { type: 'text', text: 'Here is the answer' },
+      {
+        type: 'tool_update',
+        toolCall: { toolCallId: 'toolu_9', title: 'view_file', kind: null, status: 'completed', rawInput: { path: 'x.ts' } },
+      },
+    ]);
+    expect(state.usage).toEqual({ inputTokens: 5, outputTokens: 7 });
+    expect(state.sessionId).toBe('sess-asst');
+  });
+});
+
+describe('makeStreamJsonParser (stateful wrapper over a full turn)', () => {
+  it('streams a representative turn: init → text → thinking → tool → result', () => {
+    const parser = makeStreamJsonParser();
+    const all: AgentEvent[] = [];
+    const feed = (line: string): AgentEventList => {
+      const evs = parser.push(line);
+      all.push(...evs);
+      return evs;
+    };
+
+    feed(sys('sess-1'));
+    feed(textDelta(0, 'Reading '));
+    feed(textDelta(0, 'the file. '));
+    feed(thinkingDelta(0, 'I should edit it'));
+    feed(toolStart(1, 'toolu_a', 'edit_file'));
+    feed(inputJsonDelta(1, '{"path":'));
+    feed(inputJsonDelta(1, '"main.ts"}'));
+    feed(blockStop(1));
+    feed(textDelta(0, 'Done.'));
+    feed(resultLine(120, 80, 'sess-1'));
+
+    expect(all).toEqual([
+      { type: 'text', text: 'Reading ' },
+      { type: 'text', text: 'the file. ' },
+      { type: 'reasoning', text: 'I should edit it' },
+      {
+        type: 'tool_call',
+        toolCall: { toolCallId: 'toolu_a', title: 'edit_file', kind: null, status: 'in_progress', rawInput: {} },
+      },
+      {
+        type: 'tool_update',
+        toolCall: { toolCallId: 'toolu_a', title: 'edit_file', kind: null, status: 'completed', rawInput: { path: 'main.ts' } },
+      },
+      { type: 'text', text: 'Done.' },
+    ]);
+
+    expect(parser.usage()).toEqual({ inputTokens: 120, outputTokens: 80 });
+    expect(parser.sessionId()).toBe('sess-1');
+  });
+
+  it('a garbage line interleaved mid-turn does not derail subsequent parsing', () => {
+    const parser = makeStreamJsonParser();
+    expect(parser.push(textDelta(0, 'a'))).toEqual([{ type: 'text', text: 'a' }]);
+    expect(parser.push('>>> not json <<<')).toEqual([]);
+    expect(parser.push(textDelta(0, 'b'))).toEqual([{ type: 'text', text: 'b' }]);
+  });
+});

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

@@ -0,0 +1,88 @@
+/**
+ * Shared ACP `Client` builder — the callback closures every ACP connection needs
+ * (worktree-scoped FS bridge + permission/elicitation routing + session updates).
+ *
+ * Extracted (v2.7 audit reshape) from the byte-identical `buildClient` closures in
+ * `acp-dispatch.ts` (one-shot) and `backends/warm-acp.ts` (warm). The two differed
+ * only in WHERE the per-turn context comes from (a fixed dispatch vs. the warm
+ * backend's `activeTurn`) and a trivially-equivalent permission gate — both are now
+ * supplied via the `resolveTurn` callback, so the FS/permission/elicitation wiring
+ * lives once. Behavior is preserved exactly:
+ *   - `sessionUpdate` drops when `resolveTurn()` returns null (between turns).
+ *   - permission/elicitation route to the UI only when BOTH a taskId AND sessionId
+ *     are present (warm always has a sessionId, so this matches its prior
+ *     `turn?.taskId` gate); otherwise the same auto-select-first / decline fallback.
+ */
+import type {
+  Client,
+  SessionNotification,
+  RequestPermissionRequest,
+  RequestPermissionResponse,
+  ReadTextFileRequest,
+  ReadTextFileResponse,
+  WriteTextFileRequest,
+  WriteTextFileResponse,
+  CreateTerminalRequest,
+  CreateTerminalResponse,
+  CreateElicitationRequest,
+  CreateElicitationResponse,
+} from '@agentclientprotocol/sdk';
+import { readWorktreeTextFile, writeWorktreeTextFile } from './acp-client-fs.js';
+import { waitForPermissionResponse, waitForElicitationResponse } from './permission-waiter.js';
+
+/** The per-turn context an ACP `Client` closure needs, resolved lazily per call. */
+export interface AcpTurnContext {
+  /** Per-turn task id, for routing permission/elicitation prompts back to the UI. */
+  taskId: string | undefined;
+  /** BooCode session id (for permission-waiter's broker frames). */
+  sessionId: string | undefined;
+  /** Per-turn mode id (autonomous-mode gate in permission-waiter). */
+  modeId: string | undefined;
+  /** The agent name (for permission-waiter routing). */
+  agent: string;
+  /** Forward a session/update notification to the turn's event sink. */
+  onSessionUpdate: (params: SessionNotification) => void | Promise<void>;
+}
+
+/**
+ * Build the ACP `Client` callbacks once per connection. `resolveTurn` is called at
+ * the moment each callback fires and returns the live turn context (or null when no
+ * turn is active — `sessionUpdate` then drops, matching the warm backend's
+ * between-turns behavior). The FS bridge is scoped to `worktreePath`.
+ */
+export function buildAcpClient(worktreePath: string, resolveTurn: () => AcpTurnContext | null): Client {
+  return {
+    sessionUpdate: async (params: SessionNotification): Promise<void> => {
+      const turn = resolveTurn();
+      if (!turn) return; // between turns — drop (no orphan settles a future turn)
+      await turn.onSessionUpdate(params);
+    },
+    requestPermission: async (params: RequestPermissionRequest): Promise<RequestPermissionResponse> => {
+      const turn = resolveTurn();
+      if (turn && turn.taskId && turn.sessionId) {
+        return waitForPermissionResponse(turn.taskId, turn.sessionId, turn.agent, turn.modeId, params);
+      }
+      const firstOption = params.options[0];
+      if (firstOption) return { outcome: { outcome: 'selected', optionId: firstOption.optionId } };
+      return { outcome: { outcome: 'cancelled' } };
+    },
+    readTextFile: async (params: ReadTextFileRequest): Promise<ReadTextFileResponse> => {
+      const content = await readWorktreeTextFile(worktreePath, params.path, params.line, params.limit);
+      return { content };
+    },
+    writeTextFile: async (params: WriteTextFileRequest): Promise<WriteTextFileResponse> => {
+      await writeWorktreeTextFile(worktreePath, params.path, params.content);
+      return {};
+    },
+    createTerminal: async (_params: CreateTerminalRequest): Promise<CreateTerminalResponse> => {
+      return { terminalId: 'noop' };
+    },
+    unstable_createElicitation: async (params: CreateElicitationRequest): Promise<CreateElicitationResponse> => {
+      const turn = resolveTurn();
+      if (turn && turn.taskId && turn.sessionId) {
+        return waitForElicitationResponse(turn.taskId, turn.sessionId, turn.agent, turn.modeId, params);
+      }
+      return { action: 'decline' };
+    },
+  };
+}

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

@@ -9,35 +9,20 @@ import {
   ClientSideConnection,
   type Client,
   type SessionNotification,
-  type RequestPermissionRequest,
-  type RequestPermissionResponse,
-  type ReadTextFileRequest,
-  type ReadTextFileResponse,
-  type WriteTextFileRequest,
-  type WriteTextFileResponse,
-  type CreateTerminalRequest,
-  type CreateTerminalResponse,
-  type CreateElicitationRequest,
-  type CreateElicitationResponse,
   type SessionConfigOption,
   type ClientSideConnection as ConnectionType,
 } from '@agentclientprotocol/sdk';
 import type { Broker } from '@boocode/server/broker';
-import type { WsFrame } from '@boocode/server/ws-frames';
 import { spawn } from 'node:child_process';
 import { findThoughtLevelConfigId } from './acp-derive.js';
 import { resolveLaunchSpec } from './acp-spawn.js';
 import { getResolvedRegistry, type ResolvedProviderDef } from './provider-config-registry.js';
 import { createAcpNdJsonStream } from './acp-stream.js';
-import { waitForPermissionResponse, waitForElicitationResponse, cancelPendingPermission } from './permission-waiter.js';
-import { mergeTaskCommands, getTaskCommands } from './agent-commands-cache.js';
-import { readWorktreeTextFile, writeWorktreeTextFile } from './acp-client-fs.js';
-import {
-  type AcpToolSnapshot,
-  mergeToolSnapshot,
-  snapshotToWireToolCall,
-  synthesizeCanceledSnapshots,
-} from './acp-tool-snapshot.js';
+import { cancelPendingPermission } from './permission-waiter.js';
+import { mapSessionUpdate } from './acp-event-map.js';
+import { type AcpToolSnapshot, synthesizeCanceledSnapshots } from './acp-tool-snapshot.js';
+import { makeFrameEmitter, type FrameEmitter } from './frame-emitter.js';
+import { buildAcpClient } from './acp-client.js';
 
 export interface AcpDispatchResult {
   exitCode: number;
@@ -111,162 +96,61 @@ async function applySessionOverrides(
 }
 
 class AcpStreamContext {
-  readonly textChunks: string[] = [];
-  readonly reasoningChunks: string[] = [];
-  readonly toolSnapshots = new Map<string, AcpToolSnapshot>();
-  private aborted = false;
+  /** AgentEvent → WS-frame mapping + text/reasoning/tool accumulation (shared
+   *  `makeFrameEmitter`). The one-shot path passes no `dcp` stripper, so text is
+   *  emitted verbatim — byte-identical to the prior inline switch. */
+  private readonly emitter: FrameEmitter;
 
   constructor(
-    private readonly opts: Pick<
-      AcpDispatchOpts,
-      'broker' | 'sessionId' | 'chatId' | 'messageId' | 'taskId'
-    >,
+    opts: Pick<AcpDispatchOpts, 'broker' | 'sessionId' | 'chatId' | 'messageId' | 'taskId'>,
     private readonly worktreePath: string,
-  ) {}
+  ) {
+    this.emitter = makeFrameEmitter({
+      broker: opts.broker,
+      sessionId: opts.sessionId,
+      chatId: opts.chatId,
+      assistantId: opts.messageId,
+      taskId: opts.taskId,
+    });
+  }
 
   get reasoningText(): string {
-    return this.reasoningChunks.join('');
+    return this.emitter.reasoningText;
   }
 
   get output(): string {
-    return this.textChunks.join('');
+    return this.emitter.output;
   }
 
   get snapshots(): AcpToolSnapshot[] {
-    return [...this.toolSnapshots.values()];
+    return this.emitter.snapshots;
   }
 
   markAborted(): void {
-    this.aborted = true;
-    for (const snap of synthesizeCanceledSnapshots(this.toolSnapshots.values())) {
-      this.toolSnapshots.set(snap.toolCallId, snap);
-      this.publishToolSnapshot(snap);
+    // Synthesize 'canceled' updates for still-running tool calls so the UI doesn't
+    // leave them spinning, then emit them through the same frame path (tool_update
+    // → the same `tool_call` wire frame the original published).
+    for (const snap of synthesizeCanceledSnapshots(this.emitter.toolSnapshots.values())) {
+      this.emitter.onEvent({ type: 'tool_update', toolCall: snap });
     }
   }
 
-  private canStream(): boolean {
-    return !!(this.opts.broker && this.opts.sessionId && this.opts.chatId && this.opts.messageId);
-  }
-
-  private publishToolSnapshot(snapshot: AcpToolSnapshot): void {
-    if (!this.canStream()) return;
-    const wire = snapshotToWireToolCall(snapshot);
-    this.opts.broker!.publishFrame(this.opts.sessionId!, {
-      type: 'tool_call',
-      message_id: this.opts.messageId!,
-      chat_id: this.opts.chatId!,
-      tool_call: wire,
-    } as WsFrame);
-  }
-
-  handleToolUpdate(toolCallId: string, update: Parameters<typeof mergeToolSnapshot>[1]): void {
-    const previous = this.toolSnapshots.get(toolCallId);
-    const snapshot = mergeToolSnapshot(toolCallId, update, previous);
-    this.toolSnapshots.set(toolCallId, snapshot);
-    this.publishToolSnapshot(snapshot);
-  }
-
-  async handleSessionUpdate(params: SessionNotification): Promise<void> {
-    const update = params.update;
-    switch (update.sessionUpdate) {
-      case 'agent_message_chunk': {
-        const content = update.content;
-        if (content.type === 'text' && 'text' in content) {
-          const text = (content as { text: string }).text;
-          this.textChunks.push(text);
-          if (this.canStream()) {
-            this.opts.broker!.publishFrame(this.opts.sessionId!, {
-              type: 'delta',
-              message_id: this.opts.messageId!,
-              chat_id: this.opts.chatId!,
-              content: text,
-            } as WsFrame);
-          }
-        }
-        break;
-      }
-      case 'agent_thought_chunk': {
-        const content = update.content;
-        if (content.type === 'text' && 'text' in content) {
-          const text = (content as { text: string }).text;
-          this.reasoningChunks.push(text);
-          if (this.canStream()) {
-            this.opts.broker!.publishFrame(this.opts.sessionId!, {
-              type: 'reasoning_delta',
-              message_id: this.opts.messageId!,
-              chat_id: this.opts.chatId!,
-              content: text,
-            } as WsFrame);
-          }
-        }
-        break;
-      }
-      case 'tool_call':
-        this.handleToolUpdate(update.toolCallId, update);
-        break;
-      case 'tool_call_update':
-        this.handleToolUpdate(update.toolCallId, update);
-        break;
-      case 'available_commands_update': {
-        const commands = update.availableCommands.map((cmd) => ({
-          name: cmd.name,
-          description: cmd.description ?? undefined,
-        }));
-        if (this.opts.taskId && commands.length > 0) {
-          mergeTaskCommands(this.opts.taskId, commands);
-          if (this.canStream() && this.opts.sessionId) {
-            const all = getTaskCommands(this.opts.taskId) ?? commands;
-            this.opts.broker!.publishFrame(this.opts.sessionId, {
-              type: 'agent_commands',
-              task_id: this.opts.taskId,
-              session_id: this.opts.sessionId,
-              commands: all,
-            } as WsFrame);
-          }
-        }
-        break;
-      }
-      default:
-        break;
+  handleSessionUpdate(params: SessionNotification): void {
+    // The merge accumulator (`this.emitter.toolSnapshots`) is the same Map the
+    // emitter publishes from, so a later tool_call_update merges over its tool_call.
+    for (const event of mapSessionUpdate(params, this.emitter.toolSnapshots)) {
+      this.emitter.onEvent(event);
     }
   }
 
   buildClient(agent: string, modeId: string | undefined, taskId: string | undefined, sessionId: string | undefined): Client {
-    return {
-      sessionUpdate: (params) => this.handleSessionUpdate(params),
-      requestPermission: async (params: RequestPermissionRequest): Promise<RequestPermissionResponse> => {
-        if (taskId && sessionId) {
-          return waitForPermissionResponse(taskId, sessionId, agent, modeId, params);
-        }
-        const firstOption = params.options[0];
-        if (firstOption) {
-          return { outcome: { outcome: 'selected', optionId: firstOption.optionId } };
-        }
-        return { outcome: { outcome: 'cancelled' } };
-      },
-      readTextFile: async (params: ReadTextFileRequest): Promise<ReadTextFileResponse> => {
-        const content = await readWorktreeTextFile(
-          this.worktreePath,
-          params.path,
-          params.line,
-          params.limit,
-        );
-        return { content };
-      },
-      writeTextFile: async (params: WriteTextFileRequest): Promise<WriteTextFileResponse> => {
-        await writeWorktreeTextFile(this.worktreePath, params.path, params.content);
-        return {};
-      },
-      createTerminal: async (_params: CreateTerminalRequest): Promise<CreateTerminalResponse> => {
-        return { terminalId: 'noop' };
-      },
-      unstable_createElicitation: async (params: CreateElicitationRequest): Promise<CreateElicitationResponse> => {
-        if (taskId && sessionId) {
-          return waitForElicitationResponse(taskId, sessionId, agent, modeId, params);
-        }
-        return { action: 'decline' };
-      },
-    };
+    return buildAcpClient(this.worktreePath, () => ({
+      taskId,
+      sessionId,
+      modeId,
+      agent,
+      onSessionUpdate: (params) => this.handleSessionUpdate(params),
+    }));
   }
 }
 

apps/coder/src/services/acp-event-map.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared ACP session-update → normalized AgentEvent mapping.
+ *
+ * Extracted verbatim (v2.6 Phase 2) from `AcpStreamContext.handleSessionUpdate`
+ * in `acp-dispatch.ts` so the warm ACP backend (`backends/warm-acp.ts`) and the
+ * one-shot dispatch share ONE mapping. The one-shot path translates the returned
+ * events into broker frames itself (preserving its prior behavior byte-for-byte);
+ * the warm backend forwards them to the dispatcher's `ctx.onEvent` exactly like
+ * the opencode-server backend does. No I/O, no broker — pure, so it's unit-testable.
+ *
+ * Spec: openspec/changes/v2-6-persistent-agent-sessions/design.md §2b.
+ */
+import type { SessionNotification } from '@agentclientprotocol/sdk';
+import type { AgentEvent } from './agent-backend.js';
+import { type AcpToolSnapshot, mergeToolSnapshot } from './acp-tool-snapshot.js';
+
+/**
+ * Map one ACP `session/update` notification to zero-or-more normalized AgentEvents.
+ *
+ * `priorSnapshots` is the caller-owned tool-call snapshot accumulator (toolCallId →
+ * snapshot). For `tool_call` / `tool_call_update` the merged snapshot is written
+ * back into it (mutated in place, mirroring `AcpStreamContext.handleToolUpdate`)
+ * so a later `tool_call_update` merges over the earlier `tool_call`. Pass an empty
+ * Map for a stateless single call.
+ *
+ * Returns an array (never throws) so the caller can splat it onto `onEvent`.
+ */
+export function mapSessionUpdate(
+  params: SessionNotification,
+  priorSnapshots: Map<string, AcpToolSnapshot> = new Map(),
+): AgentEvent[] {
+  const update = params.update;
+  switch (update.sessionUpdate) {
+    case 'agent_message_chunk': {
+      const content = update.content;
+      if (content.type === 'text' && 'text' in content) {
+        return [{ type: 'text', text: (content as { text: string }).text }];
+      }
+      return [];
+    }
+    case 'agent_thought_chunk': {
+      const content = update.content;
+      if (content.type === 'text' && 'text' in content) {
+        return [{ type: 'reasoning', text: (content as { text: string }).text }];
+      }
+      return [];
+    }
+    case 'tool_call': {
+      const snapshot = mergeToolSnapshot(update.toolCallId, update, priorSnapshots.get(update.toolCallId));
+      priorSnapshots.set(update.toolCallId, snapshot);
+      return [{ type: 'tool_call', toolCall: snapshot }];
+    }
+    case 'tool_call_update': {
+      const snapshot = mergeToolSnapshot(update.toolCallId, update, priorSnapshots.get(update.toolCallId));
+      priorSnapshots.set(update.toolCallId, snapshot);
+      return [{ type: 'tool_update', toolCall: snapshot }];
+    }
+    case 'available_commands_update': {
+      const commands = update.availableCommands.map((cmd) => ({
+        name: cmd.name,
+        description: cmd.description ?? undefined,
+      }));
+      return [{ type: 'commands', commands }];
+    }
+    default:
+      return [];
+  }
+}

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

@@ -2,7 +2,7 @@ import { Readable, Writable } from 'node:stream';
 import type { ChildProcess } from 'node:child_process';
 import { ndJsonStream } from '@agentclientprotocol/sdk';
 
-export function nodeReadableToWeb(nodeStream: NodeJS.ReadableStream): 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)));
@@ -17,7 +17,7 @@ export function nodeReadableToWeb(nodeStream: NodeJS.ReadableStream): ReadableSt
   });
 }
 
-export function nodeWritableToWeb(nodeStream: NodeJS.WritableStream): WritableStream<Uint8Array> {
+function nodeWritableToWeb(nodeStream: NodeJS.WritableStream): WritableStream<Uint8Array> {
   return new WritableStream<Uint8Array>({
     write(chunk) {
       return new Promise<void>((resolve, reject) => {

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

@@ -13,7 +13,7 @@ import type { AcpToolSnapshot } from './acp-tool-snapshot.js';
 import type { AgentCommand } from './provider-types.js';
 
 /** Backend transport kind. Mirrors `agent_sessions.backend` CHECK in schema.sql. */
-export type AgentBackendKind = 'opencode_server' | 'acp_warm';
+export type AgentBackendKind = 'opencode_server' | 'acp_warm' | 'claude_sdk';
 
 /**
  * Normalized, transport-agnostic events a backend emits during a turn (§2).
@@ -70,12 +70,24 @@ export interface PromptCtx {
   model: string;
   signal: AbortSignal;
   onEvent: (e: AgentEvent) => void;
+  /** Phase 2: per-turn task id, so a warm ACP backend can route permission /
+   *  elicitation prompts back to the UI via the permission-waiter. Optional —
+   *  the opencode-server backend (autonomous) ignores it. */
+  taskId?: string;
+  /** Phase 2: per-turn mode id (gates autonomous mode in the permission-waiter). */
+  modeId?: string;
 }
 
 /** Result of a completed turn (§2). Diff/persist happen outside the backend. */
 export interface TurnResult {
   ok: boolean;
   error?: string;
+  // Optional context-window telemetry (claude SDK): the model's reported window
+  // (ctxMax, 1M-aware) and the peak request input ≈ current fill (ctxUsed). The
+  // dispatcher writes these onto the assistant message so the ContextBar renders a
+  // real fill for the turn. Omitted by backends that don't report a window.
+  ctxUsed?: number;
+  ctxMax?: number;
 }
 
 /**
@@ -93,4 +105,21 @@ export interface AgentBackend {
   dispose(): Promise<void>;
   /** Liveness for health endpoint + dispatcher fallback decision. §2 */
   health(): 'up' | 'down';
+  /**
+   * v2.6 Phase 3: true iff a turn is in flight on this backend. The pool's idle
+   * eviction + LRU cap NEVER evict a busy backend (design §6 busy rule); the
+   * health-monitor defers a restart while busy (stale-grace). Optional so the
+   * Phase-0 scaffold and any test double stay compatible — absent ⇒ treated as
+   * not busy. opencode-server (multi-session) is busy iff ANY session has an
+   * active turn; warm-acp (single session) iff its one slot is active.
+   */
+  isBusy?(): boolean;
+  /**
+   * v2.6 Phase 3: optional proactive health probe + busy-aware self-restart, run
+   * by the pool's periodic sweep. The opencode-server backend implements it
+   * (detects a hung-but-not-exited server and restarts when non-busy). Backends
+   * with no long-lived shared process (warm-ACP recovers lazily on its own child
+   * exit) can omit it. Must never throw — the sweep ignores rejections.
+   */
+  tickHealth?(now?: number): Promise<void>;
 }

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

@@ -1,44 +1,246 @@
 /**
- * v2.6 — AgentPool (Phase 0 scaffold).
+ * v2.6 — AgentPool.
  *
  * Lazy get-or-create registry of `AgentBackend` instances keyed by
- * `${sessionId}:${agent}`. Phase 0 ships the skeleton only: an in-memory Map,
- * lookup / register / health, and clean disposal wired to the server's onClose.
- * Spawning lands in Phase 1/2; nothing populates the map yet.
+ * `${primary}:${agent}` (primary = chatId for warm-ACP, a fixed sentinel for the
+ * single shared opencode server). Phase 0 shipped the skeleton (Map + health +
+ * dispose). Phase 3 adds the LIFECYCLE: per-entry idle tracking, a periodic
+ * idle-TTL + LRU-cap sweep (the pure decisions live in
+ * `backends/lifecycle-decisions.ts`), and a `closeChat` helper for the chat-close
+ * hook. Reattach after eviction is implicit — the next turn's `ensureSession`
+ * rebuilds the backend from `agent_sessions` / `worktrees` (DB is the source of
+ * truth; the in-memory pool is a warm cache).
  *
- * Spec: openspec/changes/v2-6-persistent-agent-sessions/design.md §2.
+ * The hard rule (design §6): NEVER evict a busy backend (one with an in-flight
+ * turn). `selectIdleEvictionTargets` / `selectLruEvictionTargets` enforce it via
+ * `backend.isBusy()`; a long turn that outlives the TTL is left alone.
+ *
+ * Spec: openspec/changes/v2-6-persistent-agent-sessions/design.md §2 / §6.
  */
+import type { FastifyBaseLogger } from 'fastify';
 import type { AgentBackend } from './agent-backend.js';
+import {
+  selectIdleEvictionTargets,
+  selectLruEvictionTargets,
+  DEFAULT_IDLE_TTL_MS,
+  DEFAULT_MAX_LIVE_BACKENDS,
+} from './backends/lifecycle-decisions.js';
+
+interface PoolEntry {
+  primary: string;
+  agent: string;
+  backend: AgentBackend;
+  /** Epoch ms of the last turn boundary (register or touch). Drives idle/LRU. */
+  lastActiveAt: number;
+}
+
+export interface AgentPoolOpts {
+  /** Idle TTL before a non-busy backend is evicted. Default 30 min. */
+  idleTtlMs?: number;
+  /** Max live backends before the LRU cap evicts the least-recently-used. */
+  maxLive?: number;
+  /** Sweep cadence. Default 60s (mirrors the server's periodic sweeper). */
+  sweepIntervalMs?: number;
+  log?: FastifyBaseLogger;
+}
+
+const DEFAULT_SWEEP_INTERVAL_MS = 60_000;
 
 export class AgentPool {
-  private readonly backends = new Map<string, AgentBackend>();
+  private readonly backends = new Map<string, PoolEntry>();
+  private idleTtlMs: number;
+  private maxLive: number;
+  private sweepIntervalMs: number;
+  private log: FastifyBaseLogger | undefined;
+  private sweepTimer: ReturnType<typeof setInterval> | null = null;
+  /** Serializes sweep runs so a slow eviction can't overlap the next tick. */
+  private sweeping = false;
 
-  private key(sessionId: string, agent: string): string {
-    return `${sessionId}:${agent}`;
+  constructor(opts: AgentPoolOpts = {}) {
+    this.idleTtlMs = opts.idleTtlMs ?? DEFAULT_IDLE_TTL_MS;
+    this.maxLive = opts.maxLive ?? DEFAULT_MAX_LIVE_BACKENDS;
+    this.sweepIntervalMs = opts.sweepIntervalMs ?? DEFAULT_SWEEP_INTERVAL_MS;
+    this.log = opts.log;
   }
 
-  /** Map lookup only. Spawning is Phase 1/2 — never creates here. */
-  get(sessionId: string, agent: string): AgentBackend | undefined {
-    return this.backends.get(this.key(sessionId, agent));
+  /** Apply env-derived knobs to the module singleton at bootstrap (before
+   *  startReaper). Only overrides explicitly-provided fields. */
+  configure(opts: AgentPoolOpts): void {
+    if (opts.idleTtlMs != null) this.idleTtlMs = opts.idleTtlMs;
+    if (opts.maxLive != null) this.maxLive = opts.maxLive;
+    if (opts.sweepIntervalMs != null) this.sweepIntervalMs = opts.sweepIntervalMs;
+    if (opts.log) this.log = opts.log;
   }
 
-  /** Store a backend instance for this (session, agent). */
-  register(sessionId: string, agent: string, backend: AgentBackend): void {
-    this.backends.set(this.key(sessionId, agent), backend);
+  private key(primary: string, agent: string): string {
+    return `${primary}:${agent}`;
+  }
+
+  /** Map lookup only. Spawning happens in the dispatcher (Phase 1/2). A hit also
+   *  marks the entry recently-active so a resolve-without-prompt doesn't get it
+   *  evicted out from under an imminent turn. */
+  get(primary: string, agent: string): AgentBackend | undefined {
+    const entry = this.backends.get(this.key(primary, agent));
+    if (entry) entry.lastActiveAt = Date.now();
+    return entry?.backend;
+  }
+
+  /** Store a backend instance for this (primary, agent). */
+  register(primary: string, agent: string, backend: AgentBackend): void {
+    this.backends.set(this.key(primary, agent), { primary, agent, backend, lastActiveAt: Date.now() });
+  }
+
+  /** Mark a backend recently-active (call at turn start AND settle so a long turn
+   *  keeps its slot warm). No-op if the key isn't pooled. */
+  touch(primary: string, agent: string): void {
+    const entry = this.backends.get(this.key(primary, agent));
+    if (entry) entry.lastActiveAt = Date.now();
+  }
+
+  /** Snapshot for the decision helpers (busy is read live from the backend). */
+  private snapshots(): { key: string; lastActiveAt: number; busy: boolean }[] {
+    const out: { key: string; lastActiveAt: number; busy: boolean }[] = [];
+    for (const [key, e] of this.backends) {
+      out.push({ key, lastActiveAt: e.lastActiveAt, busy: e.backend.isBusy?.() ?? false });
+    }
+    return out;
   }
 
   /** Summary for the health endpoint. */
-  health(): { size: number } {
-    return { size: this.backends.size };
+  health(): { size: number; busy: number } {
+    let busy = 0;
+    for (const e of this.backends.values()) if (e.backend.isBusy?.()) busy++;
+    return { size: this.backends.size, busy };
+  }
+
+  // ─── Phase 3: idle-TTL + LRU eviction sweep ──────────────────────────────────
+
+  /** Start the periodic idle + LRU sweep. Idempotent; unref'd so it never holds
+   *  the process open on its own. */
+  startReaper(log?: FastifyBaseLogger): void {
+    if (log) this.log = log;
+    if (this.sweepTimer) return;
+    this.sweepTimer = setInterval(() => {
+      void this.sweep().catch((err) => {
+        this.log?.warn({ err: errMsg(err) }, 'agent-pool: sweep error');
+      });
+    }, this.sweepIntervalMs);
+    this.sweepTimer.unref?.();
+  }
+
+  stopReaper(): void {
+    if (this.sweepTimer) {
+      clearInterval(this.sweepTimer);
+      this.sweepTimer = null;
+    }
+  }
+
+  /**
+   * One sweep pass: evict idle-past-TTL backends, then enforce the LRU cap.
+   * Deduped (a key can't appear in both lists for one pass). Busy backends are
+   * excluded by the decision helpers — a live turn is never torn down.
+   */
+  async sweep(now: number = Date.now()): Promise<{ evicted: string[] }> {
+    if (this.sweeping) return { evicted: [] };
+    this.sweeping = true;
+    try {
+      // Phase 3: drive each backend's optional proactive health probe first (the
+      // opencode server's busy-aware hung-detect + self-restart). Best-effort —
+      // a probe must never fail the sweep.
+      for (const e of this.backends.values()) {
+        if (e.backend.tickHealth) {
+          await e.backend.tickHealth(now).catch((err) => {
+            this.log?.warn({ key: this.key(e.primary, e.agent), err: errMsg(err) }, 'agent-pool: tickHealth threw');
+          });
+        }
+      }
+      const snaps = this.snapshots();
+      const idle = selectIdleEvictionTargets(snaps, now, this.idleTtlMs);
+      // LRU runs on what remains after idle eviction, so the two never double-evict.
+      const idleSet = new Set(idle);
+      const remaining = snaps.filter((s) => !idleSet.has(s.key));
+      const lru = selectLruEvictionTargets(remaining, this.maxLive);
+      const targets = [...idle, ...lru];
+      if (targets.length === 0) return { evicted: [] };
+
+      const evicted: string[] = [];
+      for (const key of targets) {
+        const entry = this.backends.get(key);
+        if (!entry) continue;
+        // Re-check busy right before teardown — a turn may have started since the
+        // snapshot. Defensive; the decision already excluded busy at snapshot time.
+        if (entry.backend.isBusy?.()) continue;
+        this.backends.delete(key);
+        try {
+          await entry.backend.dispose();
+        } catch (err) {
+          this.log?.warn({ key, err: errMsg(err) }, 'agent-pool: backend dispose threw during eviction');
+        }
+        evicted.push(key);
+      }
+      if (evicted.length > 0) {
+        this.log?.info({ evicted, size: this.backends.size }, 'agent-pool: evicted idle/over-cap backends');
+      }
+      return { evicted };
+    } finally {
+      this.sweeping = false;
+    }
+  }
+
+  // ─── Phase 3: chat-close cleanup (3.3) ───────────────────────────────────────
+
+  /**
+   * Tear down every pooled backend whose key is for this chat. Used by the
+   * chat-close hook. The opencode server is shared (keyed on a sentinel, not the
+   * chat), so it is NOT disposed here — only its session is closed via
+   * `closeSession`, which the hook calls directly with the per-(chat,agent)
+   * handle. Returns the keys it removed. Skips busy entries (a close mid-turn is
+   * rare but must not kill a live stream — the idle sweep reaps it shortly after).
+   */
+  async closeChat(chatId: string): Promise<string[]> {
+    const removed: string[] = [];
+    const prefix = `${chatId}:`;
+    for (const [key, entry] of [...this.backends]) {
+      if (!key.startsWith(prefix)) continue;
+      if (entry.backend.isBusy?.()) continue;
+      this.backends.delete(key);
+      try {
+        await entry.backend.dispose();
+      } catch (err) {
+        this.log?.warn({ key, err: errMsg(err) }, 'agent-pool: dispose threw during closeChat');
+      }
+      removed.push(key);
+    }
+    return removed;
+  }
+
+  /** Look up a backend by exact key without bumping its activity (for closeSession). */
+  peek(primary: string, agent: string): AgentBackend | undefined {
+    return this.backends.get(this.key(primary, agent))?.backend;
   }
 
   /** Dispose every backend and clear the map. Tolerates throwing backends. */
   async dispose(): Promise<void> {
+    this.stopReaper();
     const entries = [...this.backends.values()];
     this.backends.clear();
-    await Promise.allSettled(entries.map((b) => b.dispose()));
+    await Promise.allSettled(entries.map((e) => e.backend.dispose()));
   }
 }
 
-/** Single shared instance — referenced only by the server's onClose hook in Phase 0. */
+function errMsg(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
+/**
+ * The shared opencode server is pooled under a FIXED sentinel (one server per
+ * BooCoder process, multiplexing all opencode sessions internally) rather than a
+ * chat id — so it is NOT torn down by `closeChat(chatId)` (only its per-chat
+ * session is closed). Exported so the dispatcher + the lifecycle close-hook agree
+ * on the key without drift.
+ */
+export const OPENCODE_POOL_KEY = '__opencode_server__';
+
+/** Single shared instance — registered by the dispatcher, swept + drained by the
+ *  server's onClose hook. */
 export const agentPool = new AgentPool();

apps/coder/src/services/agent-status-publish.ts

@@ -0,0 +1,55 @@
+/**
+ * agent-status-publish (#10) — builds + publishes the `agent_status_updated`
+ * WS frame on the per-session channel (the same channel CoderPane subscribes to).
+ *
+ * Kept separate from normalize-agent-status.ts so that module stays a pure,
+ * broker-free helper (trivially unit-testable; reused by the config-injection
+ * follow-on). The frame contract is pinned in apps/server/src/types/ws-frames.ts
+ * (`AgentStatusUpdatedFrame`) and mirrored byte-identical in apps/web.
+ */
+import type { Broker } from '@boocode/server/broker';
+import type { WsFrame } from '@boocode/server/ws-frames';
+import type { AgentStatus } from './normalize-agent-status.js';
+
+// The exact slice of Broker we need — accepting just the bound method keeps call
+// sites flexible (pass `broker.publishFrame.bind(broker)` or, since the broker's
+// publishFrame doesn't read `this`, `broker.publishFrame` directly).
+type PublishFrame = Broker['publishFrame'];
+
+/**
+ * Best-effort publish of a normalized agent status. The broker's publishFrame
+ * already fail-closes (validates + logs + drops on bad input, never throws), but
+ * we additionally swallow any unexpected error so a publish can NEVER break the
+ * turn it's reporting on.
+ *
+ * @param publishFrame  the session channel publisher (broker.publishFrame)
+ * @param sessionId     WS subscription channel (CoderPane subscribes per-session)
+ * @param chatId        the (chat) half of the (chat, agent) status key
+ * @param agent         the (agent) half of the key
+ * @param status        normalized lifecycle status
+ * @param reason        free-form discriminator (turn_start / turn_complete / …)
+ * @param at            ISO timestamp; defaults to now
+ */
+export function publishAgentStatus(
+  publishFrame: PublishFrame,
+  sessionId: string,
+  chatId: string,
+  agent: string,
+  status: AgentStatus,
+  reason?: string,
+  at: string = new Date().toISOString(),
+): void {
+  try {
+    const frame: WsFrame = {
+      type: 'agent_status_updated',
+      chat_id: chatId,
+      agent,
+      status,
+      ...(reason ? { reason } : {}),
+      at,
+    };
+    publishFrame(sessionId, frame);
+  } catch {
+    // never let a status publish break the turn — best-effort only.
+  }
+}

apps/coder/src/services/backends/__tests__/claude-sdk-map.test.ts

@@ -0,0 +1,251 @@
+import { describe, it, expect } from 'vitest';
+import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk';
+import { mapSdkMessage, createClaudeSdkMapState } from '../claude-sdk-map.js';
+import type { AgentEvent } from '../../agent-backend.js';
+
+/**
+ * Pure mapper for Claude-SDK messages → AgentEvents (claude-sdk-sessionstore #9 Part 2).
+ * Verifies the partial-stream → live-delta mapping, tool assembly across blocks, and
+ * the final-assistant dedup, with no live `claude` binary involved.
+ *
+ * Messages are cast through `unknown` to `SDKMessage`: the real SDK shapes carry many
+ * fields (uuid, parent_tool_use_id, …) irrelevant to the mapper, which reads only the
+ * `type`/`event`/`message.content` it discriminates on. The cast keeps the fixtures
+ * minimal while the production code path sees the full real types (the backend's
+ * typecheck against the real SDK is the type-safety proof).
+ */
+function msg(m: unknown): SDKMessage {
+  return m as SDKMessage;
+}
+
+/** A partial-stream message wrapping one BetaRawMessageStreamEvent. */
+function streamEvent(event: unknown): SDKMessage {
+  return msg({ type: 'stream_event', event, parent_tool_use_id: null, uuid: 'u', session_id: 's' });
+}
+
+describe('mapSdkMessage — partial stream deltas', () => {
+  it('maps a text_delta to a text event', () => {
+    const state = createClaudeSdkMapState();
+    const out = mapSdkMessage(
+      streamEvent({ type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text: 'Hello' } }),
+      state,
+    );
+    expect(out).toEqual<AgentEvent[]>([{ type: 'text', text: 'Hello' }]);
+  });
+
+  it('maps a thinking_delta to a reasoning event', () => {
+    const state = createClaudeSdkMapState();
+    const out = mapSdkMessage(
+      streamEvent({
+        type: 'content_block_delta',
+        index: 0,
+        delta: { type: 'thinking_delta', thinking: 'pondering', estimated_tokens: null },
+      }),
+      state,
+    );
+    expect(out).toEqual<AgentEvent[]>([{ type: 'reasoning', text: 'pondering' }]);
+  });
+
+  it('drops empty text/thinking deltas', () => {
+    const state = createClaudeSdkMapState();
+    expect(
+      mapSdkMessage(streamEvent({ type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text: '' } }), state),
+    ).toEqual([]);
+    expect(
+      mapSdkMessage(
+        streamEvent({ type: 'content_block_delta', index: 0, delta: { type: 'thinking_delta', thinking: '', estimated_tokens: null } }),
+        state,
+      ),
+    ).toEqual([]);
+  });
+
+  it('ignores message framing + signature/citation deltas', () => {
+    const state = createClaudeSdkMapState();
+    expect(mapSdkMessage(streamEvent({ type: 'message_start', message: {} }), state)).toEqual([]);
+    expect(mapSdkMessage(streamEvent({ type: 'message_stop' }), state)).toEqual([]);
+    expect(
+      mapSdkMessage(streamEvent({ type: 'content_block_delta', index: 0, delta: { type: 'signature_delta', signature: 'x' } }), state),
+    ).toEqual([]);
+  });
+});
+
+describe('mapSdkMessage — tool assembly across blocks', () => {
+  it('opens a tool_call on content_block_start, buffers input_json_delta, emits tool_update with parsed input on stop', () => {
+    const state = createClaudeSdkMapState();
+
+    const started = mapSdkMessage(
+      streamEvent({
+        type: 'content_block_start',
+        index: 1,
+        content_block: { type: 'tool_use', id: 'tool-1', name: 'view_file', input: {} },
+      }),
+      state,
+    );
+    expect(started).toEqual<AgentEvent[]>([
+      { type: 'tool_call', toolCall: { toolCallId: 'tool-1', title: 'view_file', kind: null, status: 'in_progress', rawInput: {}, rawOutput: undefined } },
+    ]);
+
+    // args stream in fragments under the same block index
+    expect(
+      mapSdkMessage(streamEvent({ type: 'content_block_delta', index: 1, delta: { type: 'input_json_delta', partial_json: '{"path":' } }), state),
+    ).toEqual([]);
+    expect(
+      mapSdkMessage(streamEvent({ type: 'content_block_delta', index: 1, delta: { type: 'input_json_delta', partial_json: '"a.ts"}' } }), state),
+    ).toEqual([]);
+
+    const stopped = mapSdkMessage(streamEvent({ type: 'content_block_stop', index: 1 }), state);
+    expect(stopped).toHaveLength(1);
+    const ev = stopped[0]!;
+    expect(ev.type).toBe('tool_update');
+    if (ev.type === 'tool_update') {
+      expect(ev.toolCall.toolCallId).toBe('tool-1');
+      expect(ev.toolCall.title).toBe('view_file');
+      expect(ev.toolCall.rawInput).toEqual({ path: 'a.ts' });
+    }
+  });
+
+  it('content_block_stop for a non-tool block (no tracked index) emits nothing', () => {
+    const state = createClaudeSdkMapState();
+    // text block was streamed at index 0 but never tracked as a tool
+    mapSdkMessage(streamEvent({ type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text: 'hi' } }), state);
+    expect(mapSdkMessage(streamEvent({ type: 'content_block_stop', index: 0 }), state)).toEqual([]);
+  });
+
+  it('falls back to the prior input when the buffered tool JSON is invalid', () => {
+    const state = createClaudeSdkMapState();
+    mapSdkMessage(
+      streamEvent({ type: 'content_block_start', index: 2, content_block: { type: 'tool_use', id: 't2', name: 'grep', input: { q: 'seed' } } }),
+      state,
+    );
+    mapSdkMessage(streamEvent({ type: 'content_block_delta', index: 2, delta: { type: 'input_json_delta', partial_json: '{not json' } }), state);
+    const stopped = mapSdkMessage(streamEvent({ type: 'content_block_stop', index: 2 }), state);
+    const ev = stopped[0]!;
+    if (ev.type === 'tool_update') {
+      expect(ev.toolCall.rawInput).toEqual({ q: 'seed' });
+    } else {
+      throw new Error('expected tool_update');
+    }
+  });
+});
+
+describe('mapSdkMessage — final assistant message', () => {
+  function assistant(content: unknown[]): SDKMessage {
+    return msg({ type: 'assistant', message: { content }, parent_tool_use_id: null, uuid: 'u', session_id: 's' });
+  }
+
+  it('dedups text/thinking (already streamed) and emits a completed tool_update per tool_use block', () => {
+    const state = createClaudeSdkMapState();
+    const out = mapSdkMessage(
+      assistant([
+        { type: 'text', text: 'final answer', citations: null },
+        { type: 'thinking', thinking: 'reasoned', signature: 'sig' },
+        { type: 'tool_use', id: 'tool-9', name: 'find_files', input: { glob: '**/*.ts' } },
+      ]),
+      state,
+    );
+    expect(out).toEqual<AgentEvent[]>([
+      {
+        type: 'tool_update',
+        toolCall: { toolCallId: 'tool-9', title: 'find_files', kind: null, status: 'completed', rawInput: { glob: '**/*.ts' }, rawOutput: undefined },
+      },
+    ]);
+  });
+
+  it('preserves a title from a prior partial tool_call snapshot', () => {
+    const state = createClaudeSdkMapState();
+    mapSdkMessage(
+      streamEvent({ type: 'content_block_start', index: 0, content_block: { type: 'tool_use', id: 'tool-x', name: 'view_file', input: {} } }),
+      state,
+    );
+    const out = mapSdkMessage(assistant([{ type: 'tool_use', id: 'tool-x', name: 'view_file', input: { path: 'z' } }]), state);
+    const ev = out[0]!;
+    if (ev.type === 'tool_update') {
+      expect(ev.toolCall.status).toBe('completed');
+      expect(ev.toolCall.title).toBe('view_file');
+      expect(ev.toolCall.rawInput).toEqual({ path: 'z' });
+    } else {
+      throw new Error('expected tool_update');
+    }
+  });
+});
+
+describe('mapSdkMessage — non-content messages', () => {
+  it('returns [] for system/init, status, result, and other variants', () => {
+    const state = createClaudeSdkMapState();
+    expect(mapSdkMessage(msg({ type: 'system', subtype: 'init', session_id: 's', uuid: 'u' }), state)).toEqual([]);
+    expect(mapSdkMessage(msg({ type: 'system', subtype: 'status', status: null, session_id: 's', uuid: 'u' }), state)).toEqual([]);
+    expect(
+      mapSdkMessage(msg({ type: 'result', subtype: 'success', result: 'done', session_id: 's', uuid: 'u' }), state),
+    ).toEqual([]);
+  });
+});
+
+describe('mapSdkMessage — user tool results', () => {
+  /** A `user` message carrying tool_result blocks (the SDK feeds tool output back here). */
+  function userMsg(content: unknown): SDKMessage {
+    return msg({ type: 'user', message: { role: 'user', content }, parent_tool_use_id: null, uuid: 'u', session_id: 's' });
+  }
+
+  it('maps a string tool_result to a completed tool_update carrying the output', () => {
+    const state = createClaudeSdkMapState();
+    const out = mapSdkMessage(userMsg([{ type: 'tool_result', tool_use_id: 't1', content: 'done' }]), state);
+    expect(out).toEqual<AgentEvent[]>([
+      {
+        type: 'tool_update',
+        toolCall: { toolCallId: 't1', title: 't1', kind: null, status: 'completed', rawInput: undefined, rawOutput: 'done' },
+      },
+    ]);
+  });
+
+  it('marks an is_error result failed', () => {
+    const state = createClaudeSdkMapState();
+    const out = mapSdkMessage(userMsg([{ type: 'tool_result', tool_use_id: 't1', content: 'boom', is_error: true }]), state);
+    const ev = out[0]!;
+    if (ev.type !== 'tool_update') throw new Error('expected tool_update');
+    expect(ev.toolCall.status).toBe('failed');
+    expect(ev.toolCall.rawOutput).toBe('boom');
+  });
+
+  it('flattens array text blocks (skipping non-text) and reuses a prior snapshot title', () => {
+    const state = createClaudeSdkMapState();
+    mapSdkMessage(
+      streamEvent({ type: 'content_block_start', index: 1, content_block: { type: 'tool_use', id: 't2', name: 'view_file', input: {} } }),
+      state,
+    );
+    const out = mapSdkMessage(
+      userMsg([
+        {
+          type: 'tool_result',
+          tool_use_id: 't2',
+          content: [
+            { type: 'text', text: 'line1' },
+            { type: 'image', source: {} },
+            { type: 'text', text: 'line2' },
+          ],
+        },
+      ]),
+      state,
+    );
+    const ev = out[0]!;
+    if (ev.type !== 'tool_update') throw new Error('expected tool_update');
+    expect(ev.toolCall.toolCallId).toBe('t2');
+    expect(ev.toolCall.title).toBe('view_file');
+    expect(ev.toolCall.status).toBe('completed');
+    expect(ev.toolCall.rawOutput).toBe('line1\nline2');
+  });
+
+  it('surfaces a result for an unknown tool_use_id with the id as the title', () => {
+    const state = createClaudeSdkMapState();
+    const out = mapSdkMessage(userMsg([{ type: 'tool_result', tool_use_id: 'orphan-id', content: 'x' }]), state);
+    expect(out[0]).toMatchObject({
+      type: 'tool_update',
+      toolCall: { toolCallId: 'orphan-id', title: 'orphan-id', kind: null, status: 'completed' },
+    });
+  });
+
+  it('ignores non-tool_result blocks and non-array content', () => {
+    const state = createClaudeSdkMapState();
+    expect(mapSdkMessage(userMsg([{ type: 'text', text: 'hi' }]), state)).toEqual([]);
+    expect(mapSdkMessage(userMsg('plain string'), state)).toEqual([]);
+  });
+});

apps/coder/src/services/backends/__tests__/claude-sdk-routing.test.ts

@@ -0,0 +1,49 @@
+import { describe, it, expect } from 'vitest';
+import { shouldUseClaudeSdk, claudeSdkBackendEnabled } from '../claude-sdk-routing.js';
+
+/**
+ * Env-flagged routing for the warm Claude-SDK backend. With CLAUDE_SDK_BACKEND off
+ * (the production default) every claude task falls through to the unchanged PTY path;
+ * with it on, only chat-tab claude tasks (session_id + chat_id) route to the SDK.
+ */
+const ON = { CLAUDE_SDK_BACKEND: '1' } as NodeJS.ProcessEnv;
+const OFF = {} as NodeJS.ProcessEnv;
+
+describe('claudeSdkBackendEnabled', () => {
+  it('is false when unset or falsy', () => {
+    expect(claudeSdkBackendEnabled({} as NodeJS.ProcessEnv)).toBe(false);
+    expect(claudeSdkBackendEnabled({ CLAUDE_SDK_BACKEND: '' } as NodeJS.ProcessEnv)).toBe(false);
+    expect(claudeSdkBackendEnabled({ CLAUDE_SDK_BACKEND: '0' } as NodeJS.ProcessEnv)).toBe(false);
+    expect(claudeSdkBackendEnabled({ CLAUDE_SDK_BACKEND: 'false' } as NodeJS.ProcessEnv)).toBe(false);
+    expect(claudeSdkBackendEnabled({ CLAUDE_SDK_BACKEND: 'off' } as NodeJS.ProcessEnv)).toBe(false);
+    expect(claudeSdkBackendEnabled({ CLAUDE_SDK_BACKEND: 'no' } as NodeJS.ProcessEnv)).toBe(false);
+  });
+
+  it('is true for any other truthy value', () => {
+    expect(claudeSdkBackendEnabled({ CLAUDE_SDK_BACKEND: '1' } as NodeJS.ProcessEnv)).toBe(true);
+    expect(claudeSdkBackendEnabled({ CLAUDE_SDK_BACKEND: 'true' } as NodeJS.ProcessEnv)).toBe(true);
+    expect(claudeSdkBackendEnabled({ CLAUDE_SDK_BACKEND: 'on' } as NodeJS.ProcessEnv)).toBe(true);
+  });
+});
+
+describe('shouldUseClaudeSdk', () => {
+  it('is always false while the env flag is off — production claude stays on PTY', () => {
+    expect(shouldUseClaudeSdk({ agent: 'claude', session_id: 's1', chat_id: 'c1' }, OFF)).toBe(false);
+  });
+
+  it('routes a chat-tab claude task to the SDK when the flag is on', () => {
+    expect(shouldUseClaudeSdk({ agent: 'claude', session_id: 's1', chat_id: 'c1' }, ON)).toBe(true);
+  });
+
+  it('only applies to the claude agent', () => {
+    expect(shouldUseClaudeSdk({ agent: 'qwen', session_id: 's1', chat_id: 'c1' }, ON)).toBe(false);
+    expect(shouldUseClaudeSdk({ agent: 'opencode', session_id: 's1', chat_id: 'c1' }, ON)).toBe(false);
+    expect(shouldUseClaudeSdk({ agent: null, session_id: 's1', chat_id: 'c1' }, ON)).toBe(false);
+  });
+
+  it('requires both session_id and chat_id (session-less creators stay one-shot)', () => {
+    expect(shouldUseClaudeSdk({ agent: 'claude', session_id: null, chat_id: null }, ON)).toBe(false);
+    expect(shouldUseClaudeSdk({ agent: 'claude', session_id: 's1', chat_id: null }, ON)).toBe(false);
+    expect(shouldUseClaudeSdk({ agent: 'claude', session_id: null, chat_id: 'c1' }, ON)).toBe(false);
+  });
+});

apps/coder/src/services/backends/__tests__/claude-session-store.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import postgres from 'postgres';
+import { PostgresSessionStore } from '../claude-session-store.js';
+import type { SessionStoreEntry } from '@anthropic-ai/claude-agent-sdk';
+
+/**
+ * claude-sdk-sessionstore #9 (Part 1) — PostgresSessionStore tests.
+ *
+ * DB-opt-in (DATABASE_URL), mirrors checkpoints.test.ts: skips cleanly when the
+ * var is unset; otherwise applies the server + coder schemas and exercises the
+ * real append/load/listSessions/delete/listSubkeys round trips against postgres.
+ * Rows are namespaced under a unique project_key so concurrent suites / leftover
+ * data can't collide, and afterAll deletes everything written.
+ */
+describe.runIf(!!process.env.DATABASE_URL)('PostgresSessionStore (DB)', () => {
+  let sql: ReturnType<typeof postgres>;
+  let store: PostgresSessionStore;
+  const projectKey = `claude-store-test-${Date.now()}`;
+
+  const entry = (type: string, extra: Record<string, unknown> = {}): SessionStoreEntry => ({
+    type,
+    ...extra,
+  });
+
+  beforeAll(async () => {
+    sql = postgres(process.env.DATABASE_URL!, { max: 3 });
+    const serverSchema = resolve(__dirname, '../../../../../server/src/schema.sql');
+    const coderSchema = resolve(__dirname, '../../../schema.sql');
+    await sql.unsafe(readFileSync(serverSchema, 'utf8'));
+    await sql.unsafe(readFileSync(coderSchema, 'utf8'));
+    store = new PostgresSessionStore(sql);
+  });
+
+  afterAll(async () => {
+    if (sql) {
+      await sql`DELETE FROM claude_session_entries WHERE project_key = ${projectKey}`.catch(() => {});
+      await sql.end({ timeout: 5 });
+    }
+  });
+
+  it('append → load round-trips and preserves order across two appends', async () => {
+    const key = { projectKey, sessionId: 'sess-order' };
+    await store.append(key, [entry('user', { uuid: 'u1' }), entry('assistant', { uuid: 'a1' })]);
+    await store.append(key, [entry('result', { uuid: 'r1' })]);
+
+    const loaded = await store.load(key);
+    expect(loaded).not.toBeNull();
+    expect(loaded!.map((e) => e.uuid)).toEqual(['u1', 'a1', 'r1']);
+    expect(loaded!.map((e) => e.type)).toEqual(['user', 'assistant', 'result']);
+  });
+
+  it('append with an empty batch is a no-op (load still null for an otherwise-unseen key)', async () => {
+    const key = { projectKey, sessionId: 'sess-empty' };
+    await store.append(key, []);
+    expect(await store.load(key)).toBeNull();
+  });
+
+  it('load of a key that was never written returns null', async () => {
+    expect(await store.load({ projectKey, sessionId: 'never-seen' })).toBeNull();
+  });
+
+  it('isolates the main transcript from a subpath (load each independently)', async () => {
+    const sessionId = 'sess-subpath';
+    const mainKey = { projectKey, sessionId };
+    const subKey = { projectKey, sessionId, subpath: 'subagents/x' };
+
+    await store.append(mainKey, [entry('user', { uuid: 'main-1' })]);
+    await store.append(subKey, [entry('assistant', { uuid: 'sub-1' })]);
+
+    const main = await store.load(mainKey);
+    const sub = await store.load(subKey);
+    expect(main!.map((e) => e.uuid)).toEqual(['main-1']);
+    expect(sub!.map((e) => e.uuid)).toEqual(['sub-1']);
+  });
+
+  it('listSessions returns the session with a numeric mtime (main transcripts only)', async () => {
+    const sessionId = 'sess-list';
+    await store.append({ projectKey, sessionId }, [entry('user', { uuid: 'l1' })]);
+    // A subagent-only session must NOT surface as a main-transcript session.
+    await store.append(
+      { projectKey, sessionId: 'sess-sub-only', subpath: 'subagents/y' },
+      [entry('user', { uuid: 's1' })],
+    );
+
+    const sessions = await store.listSessions(projectKey);
+    const ids = sessions.map((s) => s.sessionId);
+    expect(ids).toContain(sessionId);
+    expect(ids).not.toContain('sess-sub-only');
+
+    const row = sessions.find((s) => s.sessionId === sessionId)!;
+    expect(typeof row.mtime).toBe('number');
+    expect(Number.isFinite(row.mtime)).toBe(true);
+    expect(row.mtime).toBeGreaterThan(0);
+  });
+
+  it('delete with a subpath removes only that subpath', async () => {
+    const sessionId = 'sess-del-subpath';
+    const mainKey = { projectKey, sessionId };
+    const subKey = { projectKey, sessionId, subpath: 'subagents/z' };
+    await store.append(mainKey, [entry('user', { uuid: 'keep-1' })]);
+    await store.append(subKey, [entry('assistant', { uuid: 'drop-1' })]);
+
+    await store.delete(subKey);
+
+    expect(await store.load(subKey)).toBeNull();
+    expect((await store.load(mainKey))!.map((e) => e.uuid)).toEqual(['keep-1']);
+  });
+
+  it('delete without a subpath removes the whole session (all subpaths)', async () => {
+    const sessionId = 'sess-del-all';
+    const mainKey = { projectKey, sessionId };
+    const subKey = { projectKey, sessionId, subpath: 'subagents/w' };
+    await store.append(mainKey, [entry('user', { uuid: 'm' })]);
+    await store.append(subKey, [entry('assistant', { uuid: 's' })]);
+
+    await store.delete({ projectKey, sessionId });
+
+    expect(await store.load(mainKey)).toBeNull();
+    expect(await store.load(subKey)).toBeNull();
+    expect(await store.listSubkeys({ projectKey, sessionId })).toEqual([]);
+  });
+
+  it('listSubkeys returns the distinct non-main subpaths', async () => {
+    const sessionId = 'sess-subkeys';
+    await store.append({ projectKey, sessionId }, [entry('user', { uuid: 'main' })]);
+    await store.append({ projectKey, sessionId, subpath: 'subagents/a' }, [entry('user', { uuid: 'a1' })]);
+    await store.append({ projectKey, sessionId, subpath: 'subagents/a' }, [entry('user', { uuid: 'a2' })]);
+    await store.append({ projectKey, sessionId, subpath: 'subagents/b' }, [entry('user', { uuid: 'b1' })]);
+
+    const subkeys = await store.listSubkeys({ projectKey, sessionId });
+    expect(subkeys.sort()).toEqual(['subagents/a', 'subagents/b']);
+  });
+});

apps/coder/src/services/backends/__tests__/lifecycle-decisions.test.ts

@@ -0,0 +1,176 @@
+import { describe, it, expect } from 'vitest';
+import {
+  selectIdleEvictionTargets,
+  selectLruEvictionTargets,
+  decideRestart,
+  selectOrphanWorktreeTargets,
+  DEFAULT_IDLE_TTL_MS,
+  DEFAULT_MAX_LIVE_BACKENDS,
+  type PoolEntrySnapshot,
+} from '../lifecycle-decisions.js';
+
+/**
+ * v2.6 Phase 3 — pure lifecycle decisions. No DB, no children, no timers; `now`
+ * is injected. Models prune.ts:selectPruneTargets — the caller acts on the keys.
+ */
+
+const NOW = 1_000_000_000_000;
+
+function entry(key: string, ageMs: number, busy = false): PoolEntrySnapshot {
+  return { key, lastActiveAt: NOW - ageMs, busy };
+}
+
+describe('selectIdleEvictionTargets (3.1)', () => {
+  it('evicts entries idle past the TTL', () => {
+    const entries = [
+      entry('a:opencode', DEFAULT_IDLE_TTL_MS + 1),
+      entry('b:goose', DEFAULT_IDLE_TTL_MS - 1),
+    ];
+    expect(selectIdleEvictionTargets(entries, NOW)).toEqual(['a:opencode']);
+  });
+
+  it('never evicts a busy entry even when idle past the TTL', () => {
+    const entries = [entry('a:opencode', DEFAULT_IDLE_TTL_MS * 10, /* busy */ true)];
+    expect(selectIdleEvictionTargets(entries, NOW)).toEqual([]);
+  });
+
+  it('respects a custom TTL', () => {
+    const entries = [entry('a:goose', 5_000), entry('b:qwen', 500)];
+    expect(selectIdleEvictionTargets(entries, NOW, 1_000)).toEqual(['a:goose']);
+  });
+
+  it('treats exactly-at-TTL as evictable (>=)', () => {
+    expect(selectIdleEvictionTargets([entry('a:x', 1_000)], NOW, 1_000)).toEqual(['a:x']);
+  });
+
+  it('returns empty for an empty pool', () => {
+    expect(selectIdleEvictionTargets([], NOW)).toEqual([]);
+  });
+});
+
+describe('selectLruEvictionTargets (3.4)', () => {
+  it('returns nothing when at or under the cap', () => {
+    const entries = [entry('a:x', 10), entry('b:y', 20)];
+    expect(selectLruEvictionTargets(entries, 2)).toEqual([]);
+    expect(selectLruEvictionTargets(entries, 5)).toEqual([]);
+  });
+
+  it('evicts the least-recently-used beyond the cap', () => {
+    // oldest first: c (300ms ago) is LRU, then a (100ms), then b (10ms).
+    const entries = [entry('a:x', 100), entry('b:y', 10), entry('c:z', 300)];
+    expect(selectLruEvictionTargets(entries, 2)).toEqual(['c:z']);
+  });
+
+  it('evicts multiple LRU entries to reach the cap', () => {
+    const entries = [
+      entry('a:x', 100),
+      entry('b:y', 10),
+      entry('c:z', 300),
+      entry('d:w', 200),
+    ];
+    // cap 1: must remove 3, oldest-first c(300), d(200), a(100).
+    expect(selectLruEvictionTargets(entries, 1)).toEqual(['c:z', 'd:w', 'a:x']);
+  });
+
+  it('never evicts a busy entry even if it is the LRU', () => {
+    // c is LRU but busy → it cannot be evicted; fall to the next-oldest (a).
+    const entries = [entry('a:x', 100), entry('b:y', 10), entry('c:z', 300, true)];
+    expect(selectLruEvictionTargets(entries, 2)).toEqual(['a:x']);
+  });
+
+  it('can transiently exceed the cap when too many are busy', () => {
+    // cap 1, but both old entries busy → only the single idle one is evictable.
+    const entries = [entry('a:x', 100, true), entry('c:z', 300, true), entry('b:y', 10)];
+    expect(selectLruEvictionTargets(entries, 1)).toEqual(['b:y']);
+  });
+
+  it('uses the default cap when omitted', () => {
+    const entries = Array.from({ length: DEFAULT_MAX_LIVE_BACKENDS + 1 }, (_, i) =>
+      entry(`k${String(i).padStart(2, '0')}:a`, (i + 1) * 1000),
+    );
+    const evicted = selectLruEvictionTargets(entries);
+    // exactly one over the default cap → evict the single LRU (largest age).
+    expect(evicted).toHaveLength(1);
+    expect(evicted[0]).toBe(`k${String(DEFAULT_MAX_LIVE_BACKENDS).padStart(2, '0')}:a`);
+  });
+});
+
+describe('decideRestart (3.2, busy-aware)', () => {
+  const base = {
+    consecutiveFailures: 0,
+    busy: false,
+    unhealthyBusySince: 0,
+    now: NOW,
+    failureThreshold: 3,
+    staleBusyGraceMs: 120_000,
+  };
+
+  it('does nothing when healthy', () => {
+    expect(decideRestart({ ...base, processExited: false, healthy: true }))
+      .toEqual({ action: 'none', reason: 'healthy' });
+  });
+
+  it('restarts immediately when the process exited', () => {
+    expect(decideRestart({ ...base, processExited: true, busy: true }))
+      .toEqual({ action: 'restart', reason: 'process-exited' });
+  });
+
+  it('waits below the failure threshold', () => {
+    expect(decideRestart({ ...base, processExited: false, consecutiveFailures: 2 }))
+      .toEqual({ action: 'wait', reason: 'below-threshold' });
+  });
+
+  it('restarts at the threshold when idle', () => {
+    expect(decideRestart({ ...base, processExited: false, consecutiveFailures: 3 }))
+      .toEqual({ action: 'restart', reason: 'threshold' });
+  });
+
+  it('defers a restart while busy within the grace window', () => {
+    expect(decideRestart({
+      ...base, processExited: false, consecutiveFailures: 5, busy: true,
+      unhealthyBusySince: NOW - 1_000,
+    })).toEqual({ action: 'wait', reason: 'busy-grace' });
+  });
+
+  it('force-restarts a busy backend after the stale-busy grace', () => {
+    expect(decideRestart({
+      ...base, processExited: false, consecutiveFailures: 5, busy: true,
+      unhealthyBusySince: NOW - 120_001,
+    })).toEqual({ action: 'restart', reason: 'stale-busy-grace' });
+  });
+
+  it('waits (busy-grace) when busy + threshold but the window just started', () => {
+    // unhealthyBusySince === 0 means the caller is about to stamp it this cycle.
+    expect(decideRestart({
+      ...base, processExited: false, consecutiveFailures: 5, busy: true,
+      unhealthyBusySince: 0,
+    })).toEqual({ action: 'wait', reason: 'busy-grace' });
+  });
+});
+
+describe('selectOrphanWorktreeTargets (3.4)', () => {
+  it('skips dirs tracked by a live worktrees row', () => {
+    const onDisk = [{ path: '/wt/sess-a', mtimeMs: NOW - 10_000_000 }];
+    expect(selectOrphanWorktreeTargets(onDisk, new Set(['/wt/sess-a']), NOW, 1000)).toEqual([]);
+  });
+
+  it('reaps an untracked dir older than the grace', () => {
+    const onDisk = [{ path: '/wt/sess-orphan', mtimeMs: NOW - 5000 }];
+    expect(selectOrphanWorktreeTargets(onDisk, new Set(), NOW, 1000)).toEqual(['/wt/sess-orphan']);
+  });
+
+  it('never reaps a dir younger than the grace (mid-create race)', () => {
+    const onDisk = [{ path: '/wt/sess-fresh', mtimeMs: NOW - 500 }];
+    expect(selectOrphanWorktreeTargets(onDisk, new Set(), NOW, 1000)).toEqual([]);
+  });
+
+  it('mixes tracked, fresh, and orphaned correctly', () => {
+    const onDisk = [
+      { path: '/wt/sess-live', mtimeMs: NOW - 10_000 },
+      { path: '/wt/sess-fresh', mtimeMs: NOW - 100 },
+      { path: '/wt/sess-orphan', mtimeMs: NOW - 10_000 },
+    ];
+    expect(selectOrphanWorktreeTargets(onDisk, new Set(['/wt/sess-live']), NOW, 1000))
+      .toEqual(['/wt/sess-orphan']);
+  });
+});

apps/coder/src/services/backends/__tests__/opencode-concurrency.test.ts

@@ -0,0 +1,173 @@
+import { describe, it, expect, vi } from 'vitest';
+import type { Event, OpencodeClient } from '@opencode-ai/sdk/v2/client';
+import {
+  reconnectDecision,
+  runSessionEventLoop,
+  DEFAULT_RECONNECT_POLICY,
+  type SessionState,
+  type SseLoopDeps,
+} from '../opencode-sse.js';
+import { shouldStartServer } from '../opencode-server-process.js';
+
+/**
+ * v2.7 concurrency hardening (Phase 7): the pure decision cores for SSE reconnect
+ * backoff + the ensureServer double-spawn guard, plus a deterministic exercise of
+ * the loop's breaker (injected sleep, fake client). Happy path is asserted to be
+ * unchanged (clean stream end → reset → base-delay reconnect).
+ */
+
+function freshState(): SessionState {
+  return {
+    boocodeSessionId: 'boo1',
+    agentSessionId: 'oc1',
+    worktreePath: '/wt',
+    streamedPartKeys: new Set(),
+    partTypeById: new Map(),
+    activeTurn: { onEvent: () => {}, settle: () => {} },
+    watchdog: null,
+    sseAbort: null,
+    swallowNextTerminal: false,
+  };
+}
+
+const silentLog = {
+  warn: () => {},
+  info: () => {},
+  error: () => {},
+  debug: () => {},
+} as unknown as SseLoopDeps['log'];
+
+describe('reconnectDecision (pure backoff + breaker)', () => {
+  it('first failure uses the base delay (matches pre-hardening flat delay)', () => {
+    expect(reconnectDecision(1)).toEqual({ action: 'reconnect', delayMs: DEFAULT_RECONNECT_POLICY.baseMs });
+  });
+
+  it('grows exponentially and caps at maxMs', () => {
+    const policy = { baseMs: 1000, maxMs: 30_000, maxAttempts: 10 };
+    expect(reconnectDecision(2, policy)).toEqual({ action: 'reconnect', delayMs: 2000 });
+    expect(reconnectDecision(3, policy)).toEqual({ action: 'reconnect', delayMs: 4000 });
+    expect(reconnectDecision(6, policy)).toEqual({ action: 'reconnect', delayMs: 30_000 }); // 32000 capped
+    expect(reconnectDecision(9, policy)).toEqual({ action: 'reconnect', delayMs: 30_000 });
+  });
+
+  it('gives up once failures exceed maxAttempts', () => {
+    const policy = { baseMs: 1, maxMs: 8, maxAttempts: 3 };
+    expect(reconnectDecision(3, policy).action).toBe('reconnect');
+    expect(reconnectDecision(4, policy)).toEqual({ action: 'give-up' });
+  });
+});
+
+describe('shouldStartServer (double-spawn guard)', () => {
+  it('does not start when the server is live', () => {
+    expect(shouldStartServer({ up: true, hasClient: true, serverStarting: true, childDead: false, startInFlight: false })).toBe(false);
+  });
+
+  it('starts on a fresh process (no start in flight)', () => {
+    expect(shouldStartServer({ up: false, hasClient: false, serverStarting: false, childDead: false, startInFlight: false })).toBe(true);
+  });
+
+  it('re-spawns after a crash once the prior start finished', () => {
+    expect(shouldStartServer({ up: false, hasClient: false, serverStarting: true, childDead: true, startInFlight: false })).toBe(true);
+  });
+
+  it('does NOT double-spawn while a start is already in flight (the race fix)', () => {
+    expect(shouldStartServer({ up: false, hasClient: false, serverStarting: true, childDead: true, startInFlight: true })).toBe(false);
+  });
+
+  it('does NOT double-spawn when a crash nulled serverStarting mid-start', () => {
+    // The narrow window: a crash during the in-flight start (await freePort) nulls
+    // serverStarting while startInFlight is still true. The startInFlight guard must
+    // win over the !serverStarting branch, else a second server spawns on a new port.
+    expect(shouldStartServer({ up: false, hasClient: false, serverStarting: false, childDead: true, startInFlight: true })).toBe(false);
+  });
+
+  it('waits (no spawn) when a cached start exists and the child is still alive', () => {
+    expect(shouldStartServer({ up: false, hasClient: false, serverStarting: true, childDead: false, startInFlight: false })).toBe(false);
+  });
+});
+
+describe('runSessionEventLoop — happy path (unchanged)', () => {
+  it('dispatches streamed events, reconciles on clean end, reconnects at base delay', async () => {
+    const state = freshState();
+    const abort = new AbortController();
+    const events = [
+      { type: 'session.next.text.delta', properties: { sessionID: 'oc1', delta: 'hi' } },
+      { type: 'session.idle', properties: { sessionID: 'oc1' } },
+    ] as unknown as Event[];
+
+    const client = {
+      event: {
+        subscribe: vi.fn(async () => ({
+          stream: (async function* () {
+            for (const ev of events) yield ev;
+          })(),
+        })),
+      },
+    } as unknown as OpencodeClient;
+
+    const dispatched: Event[] = [];
+    const sleeps: number[] = [];
+    let reconciles = 0;
+
+    const deps: SseLoopDeps = {
+      isUp: () => true,
+      getClient: () => client,
+      dispatchEvent: (ev) => dispatched.push(ev),
+      reconcile: async () => {
+        reconciles += 1;
+        abort.abort(); // stop the loop after the first clean cycle
+        return false;
+      },
+      onReconnectGiveUp: () => {
+        throw new Error('should not give up on the happy path');
+      },
+      log: silentLog,
+      sleep: async (ms) => {
+        sleeps.push(ms);
+      },
+    };
+
+    await runSessionEventLoop(state, abort, deps);
+
+    expect(dispatched).toHaveLength(2);
+    expect(reconciles).toBe(1);
+    expect(sleeps).toEqual([DEFAULT_RECONNECT_POLICY.baseMs]); // base delay, not backed off
+  });
+});
+
+describe('runSessionEventLoop — circuit breaker', () => {
+  it('backs off on repeated throws then gives up + fails the turn', async () => {
+    const state = freshState();
+    const abort = new AbortController();
+    const policy = { baseMs: 1, maxMs: 8, maxAttempts: 3 };
+
+    const subscribe = vi.fn(async () => {
+      throw new Error('connection refused');
+    });
+    const client = { event: { subscribe } } as unknown as OpencodeClient;
+
+    const sleeps: number[] = [];
+    const gaveUp = vi.fn();
+
+    const deps: SseLoopDeps = {
+      isUp: () => true,
+      getClient: () => client,
+      dispatchEvent: () => {},
+      reconcile: async () => false,
+      onReconnectGiveUp: gaveUp,
+      log: silentLog,
+      sleep: async (ms) => {
+        sleeps.push(ms);
+      },
+      policy,
+    };
+
+    await runSessionEventLoop(state, abort, deps);
+
+    // 3 backoff sleeps (1, 2, 4), then the 4th failure trips the breaker.
+    expect(sleeps).toEqual([1, 2, 4]);
+    expect(subscribe).toHaveBeenCalledTimes(4);
+    expect(gaveUp).toHaveBeenCalledTimes(1);
+    expect(gaveUp).toHaveBeenCalledWith(state);
+  });
+});

apps/coder/src/services/backends/__tests__/opencode-event-map.test.ts

@@ -0,0 +1,226 @@
+import { describe, it, expect } from 'vitest';
+import type { Event, Part } from '@opencode-ai/sdk/v2/client';
+import {
+  stripDcpTags,
+  eventSessionId,
+  resolvePartDedupeKey,
+  mapToolStatus,
+  toolPartToSnapshot,
+  toolCalledSnapshot,
+  toolSuccessSnapshot,
+  toolFailedSnapshot,
+  classifyPartDelta,
+  classifyUpdatedPart,
+  errToString,
+  errMsg,
+  type DedupState,
+} from '../opencode-event-map.js';
+
+/**
+ * Pure opencode Event → AgentEvent translation + dedup gate (v2.7 audit reshape).
+ * Mirrors the original `dispatchEvent` / `handleUpdatedPart` arms verbatim — no
+ * I/O, so it's unit-testable. The slimmed backend keeps the routing + side effects.
+ */
+
+function freshDedup(): DedupState {
+  return { streamedPartKeys: new Set(), partTypeById: new Map() };
+}
+
+describe('stripDcpTags', () => {
+  it('removes a complete dcp tag', () => {
+    expect(stripDcpTags('hi <dcp-message-id>m1</dcp-message-id> there')).toBe('hi  there');
+  });
+  it('leaves untagged text untouched', () => {
+    expect(stripDcpTags('plain text <div>')).toBe('plain text <div>');
+  });
+});
+
+describe('eventSessionId', () => {
+  it('reads properties.sessionID for a normal event', () => {
+    const ev = { type: 'session.idle', properties: { sessionID: 's1' } } as unknown as Event;
+    expect(eventSessionId(ev)).toBe('s1');
+  });
+  it('reads properties.part.sessionID for message.part.updated', () => {
+    const ev = {
+      type: 'message.part.updated',
+      properties: { part: { sessionID: 's2' } },
+    } as unknown as Event;
+    expect(eventSessionId(ev)).toBe('s2');
+  });
+  it('returns null when there is no session', () => {
+    const ev = { type: 'server.connected', properties: {} } as unknown as Event;
+    expect(eventSessionId(ev)).toBeNull();
+  });
+});
+
+describe('resolvePartDedupeKey', () => {
+  it('prefers the part id', () => {
+    expect(resolvePartDedupeKey({ id: 'p1', messageID: 'm1' }, 'text')).toBe('text:p1');
+  });
+  it('falls back to the message id', () => {
+    expect(resolvePartDedupeKey({ id: '  ', messageID: 'm1' }, 'reasoning')).toBe('reasoning:message:m1');
+  });
+  it('returns null when neither is present', () => {
+    expect(resolvePartDedupeKey({ id: '', messageID: '' }, 'text')).toBeNull();
+  });
+});
+
+describe('mapToolStatus', () => {
+  it('maps the opencode tool states to ACP statuses', () => {
+    expect(mapToolStatus('pending')).toBe('pending');
+    expect(mapToolStatus('running')).toBe('in_progress');
+    expect(mapToolStatus('completed')).toBe('completed');
+    expect(mapToolStatus('error')).toBe('failed');
+    expect(mapToolStatus(undefined)).toBeNull();
+  });
+});
+
+describe('session.next.tool.* snapshot builders', () => {
+  it('toolCalledSnapshot → in_progress with tool title + raw input', () => {
+    expect(toolCalledSnapshot({ callID: 'c1', tool: 'read_file', input: { path: 'a.ts' } })).toEqual({
+      toolCallId: 'c1',
+      title: 'read_file',
+      kind: null,
+      status: 'in_progress',
+      rawInput: { path: 'a.ts' },
+      rawOutput: undefined,
+    });
+  });
+  it('toolSuccessSnapshot → completed with joined text content', () => {
+    const snap = toolSuccessSnapshot({ callID: 'c1', content: [{ text: 'foo' }, { text: 'bar' }, { other: 1 }] });
+    expect(snap.status).toBe('completed');
+    expect(snap.title).toBe('c1');
+    expect(snap.rawOutput).toBe('foobar');
+  });
+  it('toolSuccessSnapshot → empty output when content is missing', () => {
+    expect(toolSuccessSnapshot({ callID: 'c1' }).rawOutput).toBe('');
+  });
+  it('toolFailedSnapshot → failed with stringified error', () => {
+    const snap = toolFailedSnapshot({ callID: 'c1', error: 'boom' });
+    expect(snap.status).toBe('failed');
+    expect(snap.title).toBe('c1');
+    expect(snap.rawOutput).toBe('boom');
+  });
+});
+
+describe('toolPartToSnapshot', () => {
+  it('extracts input/output/title/status from the tool state', () => {
+    const part = {
+      type: 'tool',
+      callID: 'c1',
+      tool: 'grep',
+      state: { status: 'completed', input: { q: 'x' }, output: 'result', title: 'Grep run' },
+    } as unknown as Parameters<typeof toolPartToSnapshot>[0];
+    expect(toolPartToSnapshot(part)).toEqual({
+      toolCallId: 'c1',
+      title: 'Grep run',
+      kind: null,
+      status: 'completed',
+      rawInput: { q: 'x' },
+      rawOutput: 'result',
+    });
+  });
+  it('falls back to the tool name and uses error as output', () => {
+    const part = {
+      type: 'tool',
+      callID: 'c2',
+      tool: 'edit',
+      state: { status: 'error', error: 'nope' },
+    } as unknown as Parameters<typeof toolPartToSnapshot>[0];
+    const snap = toolPartToSnapshot(part);
+    expect(snap.title).toBe('edit');
+    expect(snap.status).toBe('failed');
+    expect(snap.rawOutput).toBe('nope');
+  });
+});
+
+describe('classifyPartDelta (message.part.delta dedup recording)', () => {
+  it('records a reasoning key and emits a reasoning event', () => {
+    const st = freshDedup();
+    const e = classifyPartDelta({ partID: 'p1', field: 'reasoning', delta: 'thinking' }, st);
+    expect(e).toEqual({ type: 'reasoning', text: 'thinking' });
+    expect(st.streamedPartKeys.has('reasoning:p1')).toBe(true);
+  });
+  it('records a text key, strips dcp, and emits text', () => {
+    const st = freshDedup();
+    const e = classifyPartDelta({ partID: 'p2', field: 'text', delta: 'hi <dcp-message-id>m</dcp-message-id>' }, st);
+    expect(e).toEqual({ type: 'text', text: 'hi ' });
+    expect(st.streamedPartKeys.has('text:p2')).toBe(true);
+  });
+  it('still records the text key even when the cleaned delta is empty', () => {
+    const st = freshDedup();
+    const e = classifyPartDelta({ partID: 'p3', field: 'text', delta: '<dcp-message-id>m</dcp-message-id>' }, st);
+    expect(e).toBeNull();
+    expect(st.streamedPartKeys.has('text:p3')).toBe(true);
+  });
+  it('uses the recorded part type when the field is absent', () => {
+    const st = freshDedup();
+    st.partTypeById.set('p4', 'reasoning');
+    const e = classifyPartDelta({ partID: 'p4', delta: 'more' }, st);
+    expect(e).toEqual({ type: 'reasoning', text: 'more' });
+  });
+  it('returns null for an unknown field', () => {
+    expect(classifyPartDelta({ partID: 'p5', field: 'other', delta: 'x' }, freshDedup())).toBeNull();
+  });
+});
+
+describe('classifyUpdatedPart (message.part.updated dedup gate)', () => {
+  function textPart(over: Partial<Part> = {}): Part {
+    return {
+      type: 'text',
+      id: 'p1',
+      messageID: 'm1',
+      sessionID: 's1',
+      text: 'final text',
+      time: { start: 1, end: 2 },
+      ...over,
+    } as unknown as Part;
+  }
+
+  it('drops a terminal part already streamed via deltas', () => {
+    const st = freshDedup();
+    st.streamedPartKeys.add('text:p1');
+    expect(classifyUpdatedPart(textPart(), st)).toBeNull();
+    // the key is consumed
+    expect(st.streamedPartKeys.has('text:p1')).toBe(false);
+  });
+  it('emits a finished (ended) text part not seen via deltas', () => {
+    const st = freshDedup();
+    expect(classifyUpdatedPart(textPart(), st)).toEqual({ type: 'text', text: 'final text' });
+    expect(st.partTypeById.get('p1')).toBe('text');
+  });
+  it('does not emit a part that has not ended yet', () => {
+    const st = freshDedup();
+    expect(classifyUpdatedPart(textPart({ time: { start: 1 } as never }), st)).toBeNull();
+  });
+  it('strips dcp tags from the finished text', () => {
+    const st = freshDedup();
+    const part = textPart({ text: 'a <dcp-message-id>m</dcp-message-id>b' });
+    expect(classifyUpdatedPart(part, st)).toEqual({ type: 'text', text: 'a b' });
+  });
+  it('maps a running tool part to tool_call', () => {
+    const st = freshDedup();
+    const part = { type: 'tool', callID: 'c1', tool: 'grep', state: { status: 'running' } } as unknown as Part;
+    const e = classifyUpdatedPart(part, st);
+    expect(e?.type).toBe('tool_call');
+  });
+  it('maps a completed tool part to tool_update', () => {
+    const st = freshDedup();
+    const part = { type: 'tool', callID: 'c1', tool: 'grep', state: { status: 'completed', output: 'x' } } as unknown as Part;
+    const e = classifyUpdatedPart(part, st);
+    expect(e?.type).toBe('tool_update');
+  });
+});
+
+describe('error formatters', () => {
+  it('errMsg unwraps Error.message', () => {
+    expect(errMsg(new Error('x'))).toBe('x');
+    expect(errMsg('plain')).toBe('plain');
+  });
+  it('errToString handles null/string/Error/object', () => {
+    expect(errToString(null)).toBe('unknown error');
+    expect(errToString('s')).toBe('s');
+    expect(errToString(new Error('e'))).toBe('e');
+    expect(errToString({ a: 1 })).toBe('{"a":1}');
+  });
+});

apps/coder/src/services/backends/__tests__/pushable-iterable.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect } from 'vitest';
+import { createPushable } from '../pushable-iterable.js';
+
+/**
+ * The pushable async-iterable that feeds the Claude SDK's streaming-input query()
+ * one message per turn while staying open across turns. Tests cover the ordering
+ * contract (push/close/async-iterate) without any SDK shape.
+ */
+describe('createPushable — push/iterate ordering', () => {
+  it('yields buffered values in FIFO order then parks', async () => {
+    const p = createPushable<number>();
+    const it = p.iterable[Symbol.asyncIterator]();
+
+    p.push(1);
+    p.push(2);
+    expect(await it.next()).toEqual({ value: 1, done: false });
+    expect(await it.next()).toEqual({ value: 2, done: false });
+
+    // No more buffered → next() parks; resolve it by pushing.
+    const parked = it.next();
+    p.push(3);
+    expect(await parked).toEqual({ value: 3, done: false });
+  });
+
+  it('hands a value directly to a parked consumer (push after await)', async () => {
+    const p = createPushable<string>();
+    const it = p.iterable[Symbol.asyncIterator]();
+    const pending = it.next(); // parks immediately (empty buffer)
+    p.push('hello');
+    expect(await pending).toEqual({ value: 'hello', done: false });
+  });
+
+  it('close() resolves a parked consumer as done and reports done thereafter', async () => {
+    const p = createPushable<number>();
+    const it = p.iterable[Symbol.asyncIterator]();
+    const pending = it.next();
+    p.close();
+    expect(await pending).toEqual({ value: undefined, done: true });
+    expect(await it.next()).toEqual({ value: undefined, done: true });
+    expect(p.closed).toBe(true);
+  });
+
+  it('still drains values buffered BEFORE close', async () => {
+    const p = createPushable<number>();
+    const it = p.iterable[Symbol.asyncIterator]();
+    p.push(10);
+    p.push(20);
+    p.close();
+    expect(await it.next()).toEqual({ value: 10, done: false });
+    expect(await it.next()).toEqual({ value: 20, done: false });
+    expect(await it.next()).toEqual({ value: undefined, done: true });
+  });
+
+  it('drops values pushed after close', async () => {
+    const p = createPushable<number>();
+    const it = p.iterable[Symbol.asyncIterator]();
+    p.close();
+    p.push(99); // no-op
+    expect(await it.next()).toEqual({ value: undefined, done: true });
+  });
+
+  it('close() is idempotent', () => {
+    const p = createPushable<number>();
+    p.close();
+    expect(() => p.close()).not.toThrow();
+    expect(p.closed).toBe(true);
+  });
+
+  it('works with a for-await loop driven by interleaved pushes', async () => {
+    const p = createPushable<number>();
+    const seen: number[] = [];
+    const consumer = (async () => {
+      for await (const v of p.iterable) seen.push(v);
+    })();
+
+    p.push(1);
+    await Promise.resolve();
+    p.push(2);
+    await Promise.resolve();
+    p.close();
+    await consumer;
+    expect(seen).toEqual([1, 2]);
+  });
+
+  it('return() on the iterator closes the queue (for-await break)', async () => {
+    const p = createPushable<number>();
+    const it = p.iterable[Symbol.asyncIterator]();
+    p.push(1);
+    expect(await it.next()).toEqual({ value: 1, done: false });
+    // Simulate a `break` in for-await: the runtime calls return().
+    expect(await it.return!()).toEqual({ value: undefined, done: true });
+    expect(p.closed).toBe(true);
+    p.push(2); // dropped — queue is closed
+    expect(await it.next()).toEqual({ value: undefined, done: true });
+  });
+});

apps/coder/src/services/backends/__tests__/warm-acp-routing.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from 'vitest';
+import { shouldUseWarmBackend, isTurnOkForStopReason } from '../warm-acp-routing.js';
+
+/**
+ * Phase 2 routing predicate: which goose/qwen tasks go to the warm pool backend
+ * vs the existing one-shot ACP path.
+ *
+ * The warm backend is keyed (chat_id, agent) — the persistent context unit (same
+ * as opencode-server). A task only routes warm when it carries BOTH a session_id
+ * and a chat_id, i.e. it originates from a real chat tab (the coder message route
+ * stamps both). Session-less creators (arena, MCP-created, generic /api/tasks,
+ * new_task) lack chat_id/session_id and keep the one-shot worktree-per-task path,
+ * which never spawns a warm process.
+ */
+describe('shouldUseWarmBackend (Phase 2 routing)', () => {
+  it('routes a chat-tab task (session_id + chat_id) to the warm backend', () => {
+    expect(shouldUseWarmBackend({ agent: 'qwen', session_id: 's1', chat_id: 'c1' })).toBe(true);
+    expect(shouldUseWarmBackend({ agent: 'goose', session_id: 's1', chat_id: 'c1' })).toBe(true);
+  });
+
+  it('keeps a session-less arena/MCP task on the one-shot path', () => {
+    expect(shouldUseWarmBackend({ agent: 'qwen', session_id: null, chat_id: null })).toBe(false);
+  });
+
+  it('keeps a task with a session but no chat on the one-shot path', () => {
+    // chat_id is the warm-key half; without it ensureSession would get a degenerate
+    // (null, agent) key, so fall back to one-shot rather than synthesize a chat.
+    expect(shouldUseWarmBackend({ agent: 'goose', session_id: 's1', chat_id: null })).toBe(false);
+  });
+
+  it('keeps a task with a chat but no session on the one-shot path', () => {
+    expect(shouldUseWarmBackend({ agent: 'qwen', session_id: null, chat_id: 'c1' })).toBe(false);
+  });
+
+  it('only applies to warm-capable agents (goose, qwen); others never warm here', () => {
+    // opencode has its own dedicated warm path; native/claude/etc. are not ACP-warm.
+    expect(shouldUseWarmBackend({ agent: 'opencode', session_id: 's1', chat_id: 'c1' })).toBe(false);
+    expect(shouldUseWarmBackend({ agent: 'claude', session_id: 's1', chat_id: 'c1' })).toBe(false);
+    expect(shouldUseWarmBackend({ agent: null, session_id: 's1', chat_id: 'c1' })).toBe(false);
+  });
+});
+
+describe('isTurnOkForStopReason (ACP stop-reason → ok/fail)', () => {
+  it('treats normal completions as ok', () => {
+    expect(isTurnOkForStopReason('end_turn')).toBe(true);
+    expect(isTurnOkForStopReason('max_tokens')).toBe(true);
+    expect(isTurnOkForStopReason('max_turn_requests')).toBe(true);
+  });
+
+  it('treats refusal and cancelled as failures', () => {
+    expect(isTurnOkForStopReason('refusal')).toBe(false);
+    expect(isTurnOkForStopReason('cancelled')).toBe(false);
+  });
+
+  it('defaults an absent stop reason to a successful end_turn', () => {
+    expect(isTurnOkForStopReason(undefined)).toBe(true);
+    expect(isTurnOkForStopReason(null)).toBe(true);
+  });
+});

apps/coder/src/services/backends/claude-sdk-map.ts

@@ -0,0 +1,245 @@
+/**
+ * claude-sdk-sessionstore #9 (Part 2) — PURE Claude-SDK message → AgentEvent mapper.
+ *
+ * `ClaudeSdkBackend` drives one `query()` per (chat, agent) session and feeds each
+ * `SDKMessage` it yields through this function, forwarding the returned
+ * `AgentEvent[]` to the dispatcher's `onEvent` (which maps them to WS frames +
+ * persists). Kept PURE (one message + a caller-owned accumulator → events) so it's
+ * unit-testable without a live `claude` binary — the whole point of Part 2's
+ * typecheck-and-unit-test gate (the live pump needs a host smoke).
+ *
+ * SDK shapes (verified against @anthropic-ai/claude-agent-sdk@0.3.159 sdk.d.ts +
+ * @anthropic-ai/sdk beta messages d.ts):
+ *   - `SDKPartialAssistantMessage` (`type:'stream_event'`) carries a
+ *     `BetaRawMessageStreamEvent` — the LIVE delta stream (only emitted when
+ *     `options.includePartialMessages` is set, which the backend sets). We map:
+ *       · content_block_delta + text_delta      → { text }
+ *       · content_block_delta + thinking_delta   → { reasoning }
+ *       · content_block_start  + tool_use block  → { tool_call } (in_progress)
+ *       · content_block_delta + input_json_delta → buffered into the tool's args
+ *         (no event; the assembled input rides the terminal tool_update)
+ *   - `SDKAssistantMessage` (`type:'assistant'`) carries the FINAL `message.content`
+ *     blocks. Text/thinking there are post-hoc repeats of what the partials already
+ *     streamed, so we DROP them (dedup) and only emit a terminal `tool_update`
+ *     (status completed) per `tool_use` block, with its now-complete `input`.
+ *   - All other `SDKMessage` variants (system/init, status, result, hooks, task
+ *     notifications, …) carry no renderable turn content → return [].
+ *
+ * Tool assembly spans messages: a tool_use block opens in a partial
+ * `content_block_start`, its args stream as `input_json_delta` frames keyed by the
+ * block `index`, and the final assistant message restates the complete block. The
+ * caller owns a `ClaudeSdkMapState` (snapshot map + per-index tool tracking) that
+ * threads this across calls, mirroring the `Map<string, AcpToolSnapshot>` the other
+ * backends pass into `mapSessionUpdate`. The result frames carry the SAME
+ * `AcpToolSnapshot` shape, so `persistExternalAgentTurn` / `snapshotToWireToolCall`
+ * are reused unchanged.
+ */
+import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk';
+import type { AgentEvent } from '../agent-backend.js';
+import type { AcpToolSnapshot } from '../acp-tool-snapshot.js';
+
+/**
+ * The underlying `@anthropic-ai/sdk` Beta message types (`BetaRawMessageStreamEvent`,
+ * `BetaContentBlock`) are a TRANSITIVE dep of `@anthropic-ai/claude-agent-sdk` — not
+ * a direct dependency of apps/coder — so a `@anthropic-ai/sdk/...` import does NOT
+ * resolve here under pnpm's strict node_modules. We instead DERIVE both shapes from
+ * the SDK's own exported message types, which is also more correct (it tracks the
+ * exact `event` / `content` shapes the SDK yields, not a hand-picked import path).
+ */
+type StreamEvent = Extract<SDKMessage, { type: 'stream_event' }>['event'];
+type AssistantContent = Extract<SDKMessage, { type: 'assistant' }>['message']['content'];
+type ContentBlock = AssistantContent extends readonly (infer B)[] ? B : never;
+type UserContent = Extract<SDKMessage, { type: 'user' }>['message']['content'];
+
+/**
+ * Caller-owned accumulator threaded across `mapSdkMessage` calls within ONE turn.
+ * The backend creates a fresh one per turn and clears it at turn end.
+ */
+export interface ClaudeSdkMapState {
+  /** Stable tool-call snapshots by tool_use id, merged across start/delta/stop. */
+  snapshots: Map<string, AcpToolSnapshot>;
+  /**
+   * Partial-stream block index → in-flight tool assembly. Anthropic's stream keys
+   * blocks by a numeric `index`; tool_use args arrive as `input_json_delta`s under
+   * that index with no id, so we map index→id to route them and buffer the raw
+   * JSON fragments until the block closes (or the final assistant message lands).
+   */
+  toolByIndex: Map<number, { id: string; name: string; jsonBuf: string }>;
+}
+
+/** Construct a fresh per-turn accumulator. */
+export function createClaudeSdkMapState(): ClaudeSdkMapState {
+  return { snapshots: new Map(), toolByIndex: new Map() };
+}
+
+/**
+ * Map one `SDKMessage` → zero or more `AgentEvent`s, mutating `state` for
+ * cross-message tool assembly + dedup. Pure w.r.t. its inputs otherwise.
+ */
+export function mapSdkMessage(msg: SDKMessage, state: ClaudeSdkMapState): AgentEvent[] {
+  switch (msg.type) {
+    case 'stream_event':
+      return mapStreamEvent(msg.event, state);
+    case 'assistant':
+      return mapFinalAssistant(msg.message.content, state);
+    case 'user':
+      // Tool RESULTS ride in as user messages (tool_result blocks): the SDK ran
+      // the tool and feeds its output back. Without mapping these, the tool_call
+      // never reaches a terminal snapshot — it persists as status:'running' with
+      // no output and the UI spinner never stops (the bug this fixes).
+      return mapUserToolResults(msg.message.content, state);
+    default:
+      // system/init, status, result, hooks, task_*, etc. — no turn content here.
+      // (The backend reads session_id off the init message and usage/cost off the
+      // result message directly; neither produces a renderable AgentEvent.)
+      return [];
+  }
+}
+
+/** Live partial-stream delta → AgentEvent(s). */
+function mapStreamEvent(event: StreamEvent, state: ClaudeSdkMapState): AgentEvent[] {
+  switch (event.type) {
+    case 'content_block_start': {
+      const block = event.content_block;
+      if (block.type === 'tool_use') {
+        const snap: AcpToolSnapshot = {
+          toolCallId: block.id,
+          title: block.name,
+          kind: null,
+          status: 'in_progress',
+          rawInput: block.input ?? undefined,
+          rawOutput: undefined,
+        };
+        state.snapshots.set(block.id, snap);
+        state.toolByIndex.set(event.index, { id: block.id, name: block.name, jsonBuf: '' });
+        return [{ type: 'tool_call', toolCall: snap }];
+      }
+      return [];
+    }
+    case 'content_block_delta': {
+      const delta = event.delta;
+      if (delta.type === 'text_delta') {
+        return delta.text ? [{ type: 'text', text: delta.text }] : [];
+      }
+      if (delta.type === 'thinking_delta') {
+        return delta.thinking ? [{ type: 'reasoning', text: delta.thinking }] : [];
+      }
+      if (delta.type === 'input_json_delta') {
+        // Buffer the tool's streamed args under its block index; no event yet —
+        // the assembled input rides the terminal tool_update (or the final block).
+        const t = state.toolByIndex.get(event.index);
+        if (t) t.jsonBuf += delta.partial_json ?? '';
+        return [];
+      }
+      // signature_delta / citations_delta / compaction_delta — nothing to render.
+      return [];
+    }
+    case 'content_block_stop': {
+      // Close out a streamed tool block: parse its buffered JSON args and emit a
+      // tool_update carrying the assembled input. The final assistant message will
+      // restate the same block, but its snapshot is dedup-merged (same id) so this
+      // is harmless — we emit here so a tool's input renders even if the assistant
+      // message is delayed/dropped.
+      const t = state.toolByIndex.get(event.index);
+      if (!t) return [];
+      state.toolByIndex.delete(event.index);
+      const prev = state.snapshots.get(t.id);
+      const snap: AcpToolSnapshot = {
+        toolCallId: t.id,
+        title: prev?.title ?? t.name,
+        kind: null,
+        status: 'in_progress',
+        rawInput: parseJsonOr(t.jsonBuf, prev?.rawInput),
+        rawOutput: undefined,
+      };
+      state.snapshots.set(t.id, snap);
+      return [{ type: 'tool_update', toolCall: snap }];
+    }
+    default:
+      // message_start / message_delta / message_stop — turn framing, no content.
+      return [];
+  }
+}
+
+/**
+ * Final assistant message content blocks. Text/thinking are post-hoc repeats of
+ * the partial stream → dropped (dedup). Only tool_use blocks emit a terminal
+ * tool_update carrying the complete `input`.
+ */
+function mapFinalAssistant(content: ContentBlock[], state: ClaudeSdkMapState): AgentEvent[] {
+  const out: AgentEvent[] = [];
+  for (const block of content) {
+    if (block.type === 'tool_use') {
+      const prev = state.snapshots.get(block.id);
+      const snap: AcpToolSnapshot = {
+        toolCallId: block.id,
+        title: prev?.title ?? block.name,
+        kind: null,
+        status: 'completed',
+        rawInput: block.input ?? prev?.rawInput,
+        rawOutput: undefined,
+      };
+      state.snapshots.set(block.id, snap);
+      out.push({ type: 'tool_update', toolCall: snap });
+    }
+    // text / thinking / redacted_thinking blocks: already streamed via partials.
+  }
+  return out;
+}
+
+/**
+ * User-message tool_result blocks → terminal tool_update events. The SDK runs
+ * each tool and feeds the output back in a `user` message; we mark the matching
+ * snapshot completed (or failed, on is_error) WITH its output so the snapshot
+ * persists/renders as resolved instead of spinning. Unknown ids (no prior
+ * snapshot) are still surfaced so a stray result isn't silently lost.
+ */
+function mapUserToolResults(content: UserContent, state: ClaudeSdkMapState): AgentEvent[] {
+  if (!Array.isArray(content)) return [];
+  const out: AgentEvent[] = [];
+  for (const raw of content) {
+    const block = raw as { type?: string; tool_use_id?: string; content?: unknown; is_error?: boolean };
+    if (block.type !== 'tool_result' || !block.tool_use_id) continue;
+    const prev = state.snapshots.get(block.tool_use_id);
+    const snap: AcpToolSnapshot = {
+      toolCallId: block.tool_use_id,
+      title: prev?.title ?? block.tool_use_id,
+      kind: prev?.kind ?? null,
+      status: block.is_error ? 'failed' : 'completed',
+      rawInput: prev?.rawInput,
+      rawOutput: toolResultText(block.content),
+    };
+    state.snapshots.set(block.tool_use_id, snap);
+    out.push({ type: 'tool_update', toolCall: snap });
+  }
+  return out;
+}
+
+/** tool_result content is a string OR an array of content blocks (text/image).
+ *  Flatten text blocks; fall back to the raw value so nothing is lost. */
+function toolResultText(content: unknown): unknown {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    const text = content
+      .map((c) =>
+        c && typeof c === 'object' && (c as { type?: string }).type === 'text'
+          ? String((c as { text?: unknown }).text ?? '')
+          : '',
+      )
+      .filter(Boolean)
+      .join('\n');
+    return text || content;
+  }
+  return content ?? '';
+}
+
+/** Parse a buffered JSON string; fall back to a prior value on empty/invalid. */
+function parseJsonOr(buf: string, fallback: unknown): unknown {
+  const s = buf.trim();
+  if (!s) return fallback;
+  try {
+    return JSON.parse(s);
+  } catch {
+    return fallback;
+  }
+}

apps/coder/src/services/backends/claude-sdk-routing.ts

@@ -0,0 +1,38 @@
+/**
+ * claude-sdk-sessionstore #9 (Part 2) — claude-SDK-vs-PTY routing predicate.
+ *
+ * Sibling to `shouldUseWarmBackend` (warm-acp-routing.ts). The warm Claude-SDK
+ * backend keys its persistent `query()` on (chat_id, agent) — exactly like the
+ * warm-ACP / opencode-server backends — so a task only routes to it when it carries
+ * BOTH a `session_id` and a `chat_id` (a real chat tab).
+ *
+ * CRUCIALLY this is ALSO gated behind the `CLAUDE_SDK_BACKEND` env flag (default
+ * OFF). While off — the production default — claude always falls through to the
+ * existing one-shot PTY `runExternalAgent` path, UNCHANGED. The live SDK streaming
+ * pump + cross-turn resume need a host smoke against the real `claude` binary, so
+ * we keep the working PTY path as the default until that lands. Flip the env var
+ * on a host (any truthy value) to opt a deployment into the SDK backend.
+ *
+ * Pure (env read injected) so it's unit-testable; the dispatcher consumes it.
+ */
+
+/** True iff the `CLAUDE_SDK_BACKEND` env flag is set to a truthy value. */
+export function claudeSdkBackendEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  const v = env.CLAUDE_SDK_BACKEND;
+  if (v == null) return false;
+  const s = v.trim().toLowerCase();
+  return s !== '' && s !== '0' && s !== 'false' && s !== 'off' && s !== 'no';
+}
+
+export function shouldUseClaudeSdk(
+  task: {
+    agent: string | null;
+    session_id: string | null;
+    chat_id: string | null;
+  },
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  if (!claudeSdkBackendEnabled(env)) return false;
+  if (task.agent !== 'claude') return false;
+  return task.session_id != null && task.chat_id != null;
+}

apps/coder/src/services/backends/claude-sdk.ts

@@ -0,0 +1,425 @@
+/**
+ * claude-sdk-sessionstore #9 (Part 2) — ClaudeSdkBackend.
+ *
+ * A warm, resumable backend for the `claude` agent built on the Claude Agent SDK
+ * (`@anthropic-ai/claude-agent-sdk`), implementing the Phase-0 `AgentBackend`
+ * contract (same shape as `WarmAcpBackend` / `OpenCodeServerBackend`). One
+ * persistent `query()` per (chat, agent) session, driven in STREAMING-INPUT mode:
+ * the `prompt` is a pushable `AsyncIterable<SDKUserMessage>` that stays open across
+ * turns, so the SDK subprocess + conversation stay warm between `prompt()` calls
+ * until `closeSession`/`dispose`.
+ *
+ * ⚠ LIVE PUMP IS HOST-ONLY. The actual streaming turn needs the real `claude`
+ * binary + ANTHROPIC auth on a host — it CANNOT run in the dev container. This file
+ * is written against the REAL SDK types so it TYPECHECKS, and the PURE pieces (the
+ * `mapSdkMessage` mapper + the `createPushable` queue) are unit-tested. Routing to
+ * this backend is gated behind `CLAUDE_SDK_BACKEND` (default OFF) so production
+ * claude stays on the working PTY path until a host smoke validates the pump +
+ * cross-turn resume.
+ *
+ * Lifecycle (mirrors warm-acp.ts / opencode-server.ts):
+ *   - `ensureSession`: resolve the resume id from `agent_sessions(chat_id,'claude')`
+ *     and (re)build the single `query()` if not already live. The SDK's own
+ *     `sessionStore` (Part 1 PostgresSessionStore) materializes the transcript on
+ *     resume; `options.resume` carries the provider session id.
+ *   - `prompt`: push ONE user message onto the open queue, iterate the generator,
+ *     map each `SDKMessage` → `AgentEvent`s via `mapSdkMessage`, forward to
+ *     `ctx.onEvent`, and resolve when the turn's `result` message lands. Capture the
+ *     `session_id` from the `init` message and persist it to `agent_sessions`;
+ *     accumulate `result.usage` / `total_cost_usd` onto the row (mirrors opencode U.6).
+ *   - `closeSession` / `dispose`: close the queue + dispose the query generator.
+ *   - A thrown error or `result.subtype==='error*'` marks `agent_sessions.status='crashed'`.
+ *
+ * Turn serialization: like warm-acp, exactly one turn is in flight at a time on a
+ * given backend (the dispatcher's per-session `inflight` map enforces this upstream;
+ * `isBusy()` reports it so the pool never evicts mid-turn).
+ */
+import { query, type Query, type SDKMessage, type SDKUserMessage, type Options } from '@anthropic-ai/claude-agent-sdk';
+import type { FastifyBaseLogger } from 'fastify';
+import type { Sql } from '../../db.js';
+import { PostgresSessionStore } from './claude-session-store.js';
+import { createPushable, type Pushable } from './pushable-iterable.js';
+import { mapSdkMessage, createClaudeSdkMapState, type ClaudeSdkMapState } from './claude-sdk-map.js';
+import type {
+  AgentBackend,
+  AgentSessionHandle,
+  EnsureSessionOpts,
+  PromptCtx,
+  TurnResult,
+} from '../agent-backend.js';
+
+export interface ClaudeSdkBackendDeps {
+  sql: Sql;
+  log: FastifyBaseLogger;
+  /** The (chat, agent) this backend serves — its pool identity + DB key. */
+  chatId: string;
+  /** Always 'claude' today; kept explicit so the pool key + DB writes stay honest. */
+  agent: string;
+  /** Resolved `claude` binary path (available_agents.install_path); null → SDK default. */
+  installPath: string | null;
+}
+
+export class ClaudeSdkBackend implements AgentBackend {
+  readonly backend = 'claude_sdk' as const;
+
+  private readonly sql: Sql;
+  private readonly log: FastifyBaseLogger;
+  private readonly chatId: string;
+  private readonly agent: string;
+  private readonly installPath: string | null;
+  private readonly sessionStore: PostgresSessionStore;
+
+  /** The single persistent query() generator; null until the first turn builds it. */
+  private query: Query | null = null;
+  /** The open input queue feeding the generator one SDKUserMessage per turn. */
+  private input: Pushable<SDKUserMessage> | null = null;
+  /** The provider's own session id (resume token), captured from the init message. */
+  private agentSessionId: string | null = null;
+  /** Resolved model the live query() was built with; a change forces a rebuild. */
+  private builtModel: string | null = null;
+  /** True between prompt() start and settle. */
+  private busy = false;
+  private up = false;
+
+  constructor(deps: ClaudeSdkBackendDeps) {
+    this.sql = deps.sql;
+    this.log = deps.log;
+    this.chatId = deps.chatId;
+    this.agent = deps.agent;
+    this.installPath = deps.installPath;
+    this.sessionStore = new PostgresSessionStore(deps.sql);
+  }
+
+  /** §2: liveness for the health endpoint + dispatcher fallback decision. */
+  health(): 'up' | 'down' {
+    return this.up ? 'up' : 'down';
+  }
+
+  /** Phase 3: busy iff a turn is in flight (pool never evicts a busy backend). */
+  isBusy(): boolean {
+    return this.busy;
+  }
+
+  // ─── ensureSession: resolve resume id + (re)build the warm query ──────────────
+
+  async ensureSession(sessionId: string, opts: EnsureSessionOpts): Promise<AgentSessionHandle> {
+    // Resolve the resume token from the (chat_id, agent) row. A crashed row is not
+    // resumed (the SDK would fail to load a dead session); we create fresh.
+    const [row] = await this.sql<{ agent_session_id: string | null; status: string }[]>`
+      SELECT agent_session_id, status FROM agent_sessions
+      WHERE chat_id = ${opts.chatId} AND agent = ${opts.agent}
+    `;
+    const resumeId = row && row.status !== 'crashed' ? row.agent_session_id : null;
+
+    // (Re)build the warm query if there is none, or the model changed (the SDK can
+    // change model mid-session via setModel, but a fresh build is simplest + matches
+    // opencode's config-drift → fresh-session rule). The query stays alive across
+    // turns; only closeSession/dispose tears it down.
+    if (!this.query || this.builtModel !== opts.model) {
+      await this.teardownQuery();
+      this.buildQuery(opts.worktreePath, opts.model, resumeId);
+    }
+
+    // Seed the in-memory resume id from the DB so a handle built before the first
+    // turn's init message still carries the last-known token. The init message
+    // overwrites it with the authoritative current id during the turn.
+    if (this.agentSessionId == null) this.agentSessionId = resumeId;
+
+    // Upsert the agent_sessions row (backend='claude_sdk'). agent_session_id may be
+    // null until the first turn captures it from the init message; prompt() updates it.
+    await this.sql`
+      INSERT INTO agent_sessions
+        (chat_id, session_id, worktree_id, agent, backend, agent_session_id, server_port, status, last_active_at)
+      VALUES
+        (${opts.chatId}, ${sessionId}, ${opts.worktreeId}, ${opts.agent}, 'claude_sdk', ${this.agentSessionId}, NULL, 'active', clock_timestamp())
+      ON CONFLICT (chat_id, agent) DO UPDATE SET
+        session_id = EXCLUDED.session_id,
+        worktree_id = EXCLUDED.worktree_id,
+        backend = 'claude_sdk',
+        agent_session_id = COALESCE(EXCLUDED.agent_session_id, agent_sessions.agent_session_id),
+        server_port = NULL,
+        status = 'active',
+        last_active_at = clock_timestamp()
+    `.catch((err) => {
+      this.log.warn({ err: errMsg(err), chatId: opts.chatId, agent: opts.agent }, 'claude-sdk: agent_sessions upsert failed (non-fatal)');
+    });
+
+    return {
+      sessionId,
+      agent: opts.agent,
+      backend: 'claude_sdk',
+      chatId: opts.chatId,
+      worktreeId: opts.worktreeId,
+      agentSessionId: this.agentSessionId,
+      serverPort: null,
+    };
+  }
+
+  /** Build the persistent query() in streaming-input mode. Lazy — no subprocess
+   *  work happens until the generator is first iterated in prompt(). */
+  private buildQuery(worktreePath: string, model: string, resumeId: string | null): void {
+    const input = createPushable<SDKUserMessage>();
+    const options: Options = {
+      sessionStore: this.sessionStore,
+      cwd: worktreePath,
+      // Stream partial assistant messages so text/thinking/tool deltas arrive live
+      // (the mapper reads them; without this only terminal messages land).
+      includePartialMessages: true,
+      // BooCode default: enable the documented 1M-context-window beta. Active on
+      // models that support it (the SDK lists Sonnet 4/4.5); a non-supporting model
+      // simply doesn't get the larger window. The TRUE window is read back from
+      // `result.modelUsage[*].contextWindow` and shown in the ContextBar, so whatever
+      // window a model actually gets is surfaced truthfully (no guessing).
+      betas: ['context-1m-2025-08-07'],
+      ...(model ? { model } : {}),
+      ...(resumeId ? { resume: resumeId } : {}),
+      ...(this.installPath ? { pathToClaudeCodeExecutable: this.installPath } : {}),
+      // ANTHROPIC auth/env must reach the child; inherit the process env (host concern).
+      env: process.env as Record<string, string>,
+    };
+    this.input = input;
+    this.query = query({ prompt: input.iterable, options });
+    this.builtModel = model;
+    this.up = true;
+    this.log.info({ chatId: this.chatId, agent: this.agent, model, resume: resumeId ?? null }, 'claude-sdk: warm query built');
+  }
+
+  // ─── prompt: push one user message + drain the generator until result ─────────
+
+  async prompt(handle: AgentSessionHandle, input: string, ctx: PromptCtx): Promise<TurnResult> {
+    if (!this.query || !this.input) {
+      // ensureSession should have built it; rebuild defensively (e.g. evicted/raced).
+      this.buildQuery(ctx.worktreePath, ctx.model, handle.agentSessionId);
+    }
+    const gen = this.query!;
+    const queue = this.input!;
+
+    if (ctx.signal.aborted) return { ok: false, error: 'aborted' };
+
+    this.busy = true;
+    const state: ClaudeSdkMapState = createClaudeSdkMapState();
+    // Peak per-request input (incl. cache) across the turn ≈ the conversation context
+    // held in the window. result.usage SUMS input over the turn's internal requests
+    // (overcounts for multi-tool turns), so the per-request peak is the accurate
+    // "context used" for the ContextBar (paseo's approach).
+    let maxInputTokens = 0;
+    // Per-turn abort: interrupt the in-flight query on the SAME generator (never
+    // tear down the warm query — that's the pool's lifetime). The generator then
+    // emits its terminal result and the drain loop exits.
+    let aborted = false;
+    const onAbort = () => {
+      if (aborted) return;
+      aborted = true;
+      void gen.interrupt().catch(() => {});
+    };
+    ctx.signal.addEventListener('abort', onAbort, { once: true });
+
+    // Push the turn's user message onto the open queue. session_id is optional on
+    // the wire; the SDK manages it via resume + the init message.
+    const userMsg: SDKUserMessage = {
+      type: 'user',
+      message: { role: 'user', content: input },
+      parent_tool_use_id: null,
+      ...(handle.agentSessionId ? { session_id: handle.agentSessionId } : {}),
+    };
+    queue.push(userMsg);
+
+    try {
+      // Manual iteration — NOT `for await (… of gen)`. Returning out of a for-await
+      // loop calls gen.return(), which CLOSES the async generator; that killed the
+      // warm streaming-input query after a single turn, so every FOLLOW-UP message
+      // hit a dead generator and failed. gen.next() leaves the generator suspended
+      // (alive) for the next pushed user message — the warm query is only closed
+      // deliberately in teardownQuery()/dispose().
+      while (true) {
+        const next = await gen.next();
+        if (next.done) {
+          // Generator ended (e.g. disposed) without a result — non-fatal incomplete.
+          if (aborted) return { ok: false, error: 'aborted' };
+          return { ok: false, error: 'claude-sdk: query ended before result' };
+        }
+        const msg = next.value;
+        // Track the peak per-request input from message_start usage (delivered by
+        // includePartialMessages) — the largest single request's input is the real
+        // context fill, unlike the summed result.usage.
+        if (msg.type === 'stream_event') {
+          const sev = msg.event as { type?: string; message?: { usage?: Record<string, unknown> } };
+          if (sev?.type === 'message_start' && sev.message?.usage) {
+            const ru = sev.message.usage;
+            const reqInput =
+              num(ru.input_tokens) + num(ru.cache_read_input_tokens) + num(ru.cache_creation_input_tokens);
+            if (reqInput > maxInputTokens) maxInputTokens = reqInput;
+          }
+        }
+        // Capture the provider session id from the init message (authoritative).
+        if (msg.type === 'system' && msg.subtype === 'init' && msg.session_id) {
+          if (this.agentSessionId !== msg.session_id) {
+            this.agentSessionId = msg.session_id;
+            await this.persistAgentSessionId(msg.session_id);
+          }
+        }
+        // The result message ends THIS turn (it does not close the generator —
+        // streaming-input keeps it alive for the next pushed message).
+        if (msg.type === 'result') {
+          await this.accumulateUsage(msg);
+          const ok = msg.subtype === 'success' && !aborted;
+          if (!ok) {
+            // error_during_execution / error_max_turns / aborted → crashed row.
+            await this.markCrashed();
+          } else {
+            await this.markIdle();
+          }
+          if (aborted) return { ok: false, error: 'aborted' };
+          if (!ok) return { ok: false, error: resultErrorMessage(msg) };
+          // Context-window telemetry for the ContextBar (paseo's method):
+          //   ctxMax = the model's OWN reported window (1M-aware — reflects the active
+          //            window, so the bar shows the truth per model);
+          //   ctxUsed = peak request input (history in the window) + this turn's output.
+          const ctxMax = extractMaxContextWindow((msg as { modelUsage?: unknown }).modelUsage);
+          const fallbackInput =
+            num(msg.usage?.input_tokens) +
+            num(msg.usage?.cache_read_input_tokens) +
+            num(msg.usage?.cache_creation_input_tokens);
+          const ctxUsed = (maxInputTokens || fallbackInput) + num(msg.usage?.output_tokens);
+          return {
+            ok: true,
+            ...(ctxMax > 0 ? { ctxMax } : {}),
+            ...(ctxUsed > 0 ? { ctxUsed } : {}),
+          };
+        }
+        // Map renderable content → AgentEvents for the dispatcher's onEvent.
+        for (const ev of mapSdkMessage(msg, state)) {
+          ctx.onEvent(ev);
+        }
+      }
+    } catch (err) {
+      if (aborted) return { ok: false, error: 'aborted' };
+      await this.markCrashed();
+      return { ok: false, error: errMsg(err) };
+    } finally {
+      ctx.signal.removeEventListener('abort', onAbort);
+      this.busy = false;
+    }
+  }
+
+  // ─── persistence helpers ──────────────────────────────────────────────────────
+
+  private async persistAgentSessionId(id: string): Promise<void> {
+    await this.sql`
+      UPDATE agent_sessions
+      SET agent_session_id = ${id}, last_active_at = clock_timestamp()
+      WHERE chat_id = ${this.chatId} AND agent = ${this.agent}
+    `.catch((err) => {
+      this.log.warn({ err: errMsg(err), chatId: this.chatId }, 'claude-sdk: failed to persist agent_session_id (non-fatal)');
+    });
+  }
+
+  /**
+   * Accumulate the turn's usage/cost onto the (chat_id, agent) row — mirrors the
+   * opencode U.6 running-total pattern. The SDK reports usage once per turn on the
+   * result message (not per step), so this fires once per prompt(). Cache read/write
+   * input tokens fold into `input_tokens`; usage telemetry never fails a turn.
+   */
+  private async accumulateUsage(result: Extract<SDKMessage, { type: 'result' }>): Promise<void> {
+    const u = result.usage;
+    const input = num(u?.input_tokens) + num(u?.cache_read_input_tokens) + num(u?.cache_creation_input_tokens);
+    const output = num(u?.output_tokens);
+    const cost = numF(result.total_cost_usd);
+    if (input === 0 && output === 0 && cost === 0) return;
+    await this.sql`
+      UPDATE agent_sessions SET
+        input_tokens = input_tokens + ${input},
+        output_tokens = output_tokens + ${output},
+        cost = cost + ${cost}
+      WHERE chat_id = ${this.chatId} AND agent = ${this.agent}
+    `.catch((err) => {
+      this.log.warn({ err: errMsg(err), chatId: this.chatId }, 'claude-sdk: failed to persist usage (non-fatal)');
+    });
+  }
+
+  private async markIdle(): Promise<void> {
+    await this.sql`
+      UPDATE agent_sessions SET status = 'idle', last_active_at = clock_timestamp()
+      WHERE chat_id = ${this.chatId} AND agent = ${this.agent}
+    `.catch(() => {});
+  }
+
+  private async markCrashed(): Promise<void> {
+    await this.sql`
+      UPDATE agent_sessions SET status = 'crashed'
+      WHERE chat_id = ${this.chatId} AND agent = ${this.agent}
+    `.catch(() => {});
+  }
+
+  // ─── teardown ────────────────────────────────────────────────────────────────
+
+  async closeSession(handle: AgentSessionHandle): Promise<void> {
+    await this.teardownQuery();
+    await this.sql`
+      UPDATE agent_sessions SET status = 'closed'
+      WHERE chat_id = ${handle.chatId} AND agent = ${handle.agent}
+    `.catch(() => {});
+  }
+
+  async dispose(): Promise<void> {
+    await this.teardownQuery();
+  }
+
+  /** Close the input queue + dispose the generator. Idempotent. */
+  private async teardownQuery(): Promise<void> {
+    this.up = false;
+    this.busy = false;
+    const q = this.query;
+    const queue = this.input;
+    this.query = null;
+    this.input = null;
+    this.builtModel = null;
+    queue?.close();
+    if (q) {
+      // return() ends the AsyncGenerator and lets the SDK clean up its subprocess.
+      await q.return(undefined).catch(() => {});
+    }
+  }
+}
+
+// ─── helpers ──────────────────────────────────────────────────────────────────
+
+/** Coerce to a non-negative finite integer (tokens). */
+function num(v: unknown): number {
+  const x = typeof v === 'number' ? v : Number(v);
+  return Number.isFinite(x) && x > 0 ? Math.round(x) : 0;
+}
+
+/** Coerce to a non-negative finite float (cost USD). */
+function numF(v: unknown): number {
+  const x = typeof v === 'number' ? v : Number(v);
+  return Number.isFinite(x) && x > 0 ? x : 0;
+}
+
+/** Largest context-window the SDK reports across `result.modelUsage` (a
+ *  `Record<model, ModelUsage>`, each with a `contextWindow`). This is the model's
+ *  OWN window — 1M when the 1M model/beta is active, 200K otherwise — so the
+ *  ContextBar shows the true window without us mapping model→size ourselves. */
+function extractMaxContextWindow(modelUsage: unknown): number {
+  if (!modelUsage || typeof modelUsage !== 'object') return 0;
+  let max = 0;
+  for (const v of Object.values(modelUsage as Record<string, unknown>)) {
+    if (v && typeof v === 'object') {
+      const cw = (v as { contextWindow?: unknown }).contextWindow;
+      if (typeof cw === 'number' && Number.isFinite(cw) && cw > max) max = cw;
+    }
+  }
+  return max;
+}
+
+/** Build a human-readable error from an SDK error-result message. */
+function resultErrorMessage(result: Extract<SDKMessage, { type: 'result' }>): string {
+  if (result.subtype === 'success') return 'ok';
+  const errs = (result as { errors?: string[] }).errors;
+  if (Array.isArray(errs) && errs.length > 0) return `${result.subtype}: ${errs.join('; ')}`;
+  return result.subtype;
+}
+
+function errMsg(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}

apps/coder/src/services/backends/claude-session-store.ts

@@ -0,0 +1,117 @@
+import type { SessionStore, SessionKey, SessionStoreEntry } from '@anthropic-ai/claude-agent-sdk';
+import type { Sql } from '../../db.js';
+
+/**
+ * claude-sdk-sessionstore #9 (Part 1) — clean-room PostgresSessionStore.
+ *
+ * A Postgres-backed implementation of the Claude Agent SDK's `SessionStore`
+ * adapter type. The SDK mirrors each transcript line (a JSON-safe POJO with a
+ * `type` discriminant) to this store via `append`; on resume it calls `load`
+ * to materialize the full transcript back. We treat entries as opaque blobs and
+ * preserve append order via a BIGSERIAL `id` — `load` replays `ORDER BY id`.
+ *
+ * Storage shape: one row per entry in `claude_session_entries`, keyed by the
+ * SDK's `SessionKey` (project_key, session_id, subpath). The SDK uses an
+ * *undefined* subpath for the main transcript and disallows the empty string;
+ * we collapse `undefined → ''` so the main transcript and subagent files share
+ * one table, distinguished by the `subpath` column (`'' = main`).
+ *
+ * Clean-room: written against the SDK's published `SessionStore` type contract
+ * and BooCode's existing SQL conventions (porsager tagged templates, `sql.json`
+ * for JSONB). No SDK example/reference code was consulted.
+ */
+export class PostgresSessionStore implements SessionStore {
+  constructor(private readonly sql: Sql) {}
+
+  /**
+   * Mirror a batch of transcript entries. No-op on an empty batch; otherwise a
+   * single multi-row INSERT writes them in array order. Because `id` is a
+   * monotonically-increasing BIGSERIAL, the insert order is the replay order
+   * `load` reconstructs — entries within one call land in the order given.
+   */
+  async append(key: SessionKey, entries: SessionStoreEntry[]): Promise<void> {
+    if (entries.length === 0) return;
+    const subpath = key.subpath ?? '';
+    const rows = entries.map((entry) => ({
+      project_key: key.projectKey,
+      session_id: key.sessionId,
+      subpath,
+      entry: this.sql.json(entry as never),
+    }));
+    await this.sql`
+      INSERT INTO claude_session_entries ${this.sql(rows, 'project_key', 'session_id', 'subpath', 'entry')}
+    `;
+  }
+
+  /**
+   * Load a full transcript for resume. Returns the entries in append order, or
+   * `null` for a (project_key, session_id, subpath) key that was never written.
+   */
+  async load(key: SessionKey): Promise<SessionStoreEntry[] | null> {
+    const subpath = key.subpath ?? '';
+    const rows = await this.sql<{ entry: SessionStoreEntry }[]>`
+      SELECT entry
+      FROM claude_session_entries
+      WHERE project_key = ${key.projectKey}
+        AND session_id = ${key.sessionId}
+        AND subpath = ${subpath}
+      ORDER BY id
+    `;
+    if (rows.length === 0) return null;
+    return rows.map((r) => r.entry);
+  }
+
+  /**
+   * List the main transcripts for a project. `mtime` is the storage write time
+   * (latest `created_at` for the session) in Unix epoch milliseconds; the SDK
+   * sorts the result by mtime descending.
+   */
+  async listSessions(projectKey: string): Promise<Array<{ sessionId: string; mtime: number }>> {
+    const rows = await this.sql<{ session_id: string; mtime: string }[]>`
+      SELECT session_id, extract(epoch FROM max(created_at)) * 1000 AS mtime
+      FROM claude_session_entries
+      WHERE project_key = ${projectKey}
+        AND subpath = ''
+      GROUP BY session_id
+    `;
+    return rows.map((r) => ({ sessionId: r.session_id, mtime: Number(r.mtime) }));
+  }
+
+  /**
+   * Delete a session. With a `subpath` set, only that subpath's rows are
+   * removed; with `subpath` omitted, every row for the session is removed
+   * (all subpaths, including the main transcript).
+   */
+  async delete(key: SessionKey): Promise<void> {
+    if (key.subpath !== undefined) {
+      await this.sql`
+        DELETE FROM claude_session_entries
+        WHERE project_key = ${key.projectKey}
+          AND session_id = ${key.sessionId}
+          AND subpath = ${key.subpath}
+      `;
+      return;
+    }
+    await this.sql`
+      DELETE FROM claude_session_entries
+      WHERE project_key = ${key.projectKey}
+        AND session_id = ${key.sessionId}
+    `;
+  }
+
+  /**
+   * List the distinct non-main subpaths under a session (e.g. subagent files).
+   * Used during resume to discover and materialize subagent transcripts; the
+   * main transcript (`subpath = ''`) is excluded.
+   */
+  async listSubkeys(key: { projectKey: string; sessionId: string }): Promise<string[]> {
+    const rows = await this.sql<{ subpath: string }[]>`
+      SELECT DISTINCT subpath
+      FROM claude_session_entries
+      WHERE project_key = ${key.projectKey}
+        AND session_id = ${key.sessionId}
+        AND subpath <> ''
+    `;
+    return rows.map((r) => r.subpath);
+  }
+}

apps/coder/src/services/backends/lifecycle-decisions.ts

@@ -0,0 +1,197 @@
+/**
+ * v2.6 Phase 3 — pure lifecycle decision helpers.
+ *
+ * The eviction / LRU-cap / busy-aware-restart / reaper-target logic, factored out
+ * of AgentPool + the backends + the periodic sweeper so it's unit-testable with no
+ * DB, no child processes, no timers (modeled on
+ * apps/server/src/services/inference/prune.ts:selectPruneTargets — a pure decision
+ * core the caller acts on).
+ *
+ * Three decisions live here:
+ *   1. selectIdleEvictionTargets — which warm backends to evict for being idle.
+ *   2. selectLruEvictionTargets — which warm backends to evict to honour a max-live
+ *      cap (least-recently-used beyond the cap), NEVER a busy one.
+ *   3. shouldRestartCrashedBackend (busy-aware) — openchamber's skip-while-busy +
+ *      stale-grace state machine, re-implemented for BooCode's per-(chat,agent) pool.
+ *
+ * "Busy" = the backend has an in-flight turn. The hard rule (design §6, decisions):
+ * never evict or force-restart a busy backend; defer with a stale-grace.
+ */
+
+// ─── Idle TTL eviction (3.1) ─────────────────────────────────────────────────
+
+/** Default idle TTL before a warm backend/session is evicted (design §6 ~30 min). */
+export const DEFAULT_IDLE_TTL_MS = 30 * 60 * 1000;
+
+/** A pool entry as the decision helpers see it (no backend internals). */
+export interface PoolEntrySnapshot {
+  /** Pool key `${primary}:${agent}` — opaque to the decision, used for selection. */
+  key: string;
+  /** Epoch ms of the last turn activity (start or settle) on this backend. */
+  lastActiveAt: number;
+  /** True iff a turn is in flight right now. Busy entries are never evicted. */
+  busy: boolean;
+}
+
+/**
+ * Idle eviction: an entry is evictable when it has been idle (no turn) for longer
+ * than `ttlMs` AND is not currently busy. Returns the keys to evict.
+ *
+ * Pure: `now` is injected so tests don't depend on wall-clock. Busy entries are
+ * categorically excluded — a long-running turn that exceeds the TTL must NOT be
+ * torn down mid-stream (the §6 / openchamber busy rule).
+ */
+export function selectIdleEvictionTargets(
+  entries: ReadonlyArray<PoolEntrySnapshot>,
+  now: number,
+  ttlMs: number = DEFAULT_IDLE_TTL_MS,
+): string[] {
+  const out: string[] = [];
+  for (const e of entries) {
+    if (e.busy) continue;
+    if (now - e.lastActiveAt >= ttlMs) out.push(e.key);
+  }
+  return out;
+}
+
+// ─── LRU cap (3.4) ───────────────────────────────────────────────────────────
+
+/** Default max live warm backends/worktrees before the LRU cap evicts (env-overridable). */
+export const DEFAULT_MAX_LIVE_BACKENDS = 10;
+
+/**
+ * LRU cap: when more than `cap` non-busy entries are live, evict the
+ * least-recently-used ones (oldest `lastActiveAt` first) until at most `cap`
+ * remain. Busy entries are never evicted AND are not counted toward the cap's
+ * "kept" budget being freed — i.e. we only ever evict idle entries, so a burst of
+ * concurrent busy turns can transiently exceed the cap rather than kill live work.
+ *
+ * Returns the keys to evict, least-recently-used first. Pure / deterministic:
+ * ties broken by key for stable test output.
+ */
+export function selectLruEvictionTargets(
+  entries: ReadonlyArray<PoolEntrySnapshot>,
+  cap: number = DEFAULT_MAX_LIVE_BACKENDS,
+): string[] {
+  if (cap < 0) cap = 0;
+  if (entries.length <= cap) return [];
+  // Only idle entries are eligible to be evicted.
+  const evictable = entries
+    .filter((e) => !e.busy)
+    .sort((a, b) => a.lastActiveAt - b.lastActiveAt || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+  // We must shrink total live count down to `cap`. Busy entries can't be evicted,
+  // so the number we CAN remove is bounded by the evictable pool; evict the oldest
+  // (total - cap) of them, never more than exist.
+  const overBy = entries.length - cap;
+  const toEvict = evictable.slice(0, Math.max(0, overBy));
+  return toEvict.map((e) => e.key);
+}
+
+// ─── Busy-aware crash restart (3.2) — openchamber lift ───────────────────────
+
+/**
+ * Default grace after which a backend that has stayed unhealthy WHILE busy is
+ * force-restarted anyway (openchamber's STALE_BUSY_GRACE_MS = 2 min). Guards
+ * against a permanently-stuck "busy" turn wedging recovery forever.
+ */
+export const DEFAULT_STALE_BUSY_GRACE_MS = 2 * 60 * 1000;
+
+/** Default consecutive health-check failures before a restart is attempted. */
+export const DEFAULT_HEALTH_FAILURE_THRESHOLD = 3;
+
+export interface RestartDecisionInput {
+  /** True iff the process is actually dead (exited). A dead process restarts
+   *  immediately regardless of busy/threshold — there's nothing to protect. */
+  processExited: boolean;
+  /** Consecutive failed health probes so far (including the current one). */
+  consecutiveFailures: number;
+  /** Whether the backend currently has an in-flight turn. */
+  busy: boolean;
+  /** Epoch ms when the unhealthy-while-busy window started, or 0 if not in one. */
+  unhealthyBusySince: number;
+  /** Injected clock. */
+  now: number;
+  failureThreshold?: number;
+  staleBusyGraceMs?: number;
+}
+
+export type RestartDecision =
+  | { action: 'restart'; reason: 'process-exited' | 'threshold' | 'stale-busy-grace' }
+  | { action: 'wait'; reason: 'below-threshold' | 'busy-grace' }
+  | { action: 'none'; reason: 'healthy' };
+
+/**
+ * Decide whether to restart a backend after a health probe. Mirrors
+ * openchamber's `runHealthCheckCycle` + `shouldSkipRestartForBusySessions`,
+ * re-implemented as a pure function over injected state (the caller owns the
+ * mutable counters + the actual restart side-effect).
+ *
+ * Order (matches openchamber):
+ *   - process exited            → restart now (nothing live to protect).
+ *   - below failure threshold   → wait (transient blip; the next probe re-checks).
+ *   - threshold reached + idle   → restart now.
+ *   - threshold reached + busy   → skip UNLESS the unhealthy-busy window exceeded
+ *                                  the stale grace, then force restart.
+ *
+ * `healthy: true` callers don't reach here; included for completeness so the
+ * caller can pass through and reset counters on a single code path.
+ */
+export function decideRestart(input: RestartDecisionInput & { healthy?: boolean }): RestartDecision {
+  if (input.healthy) return { action: 'none', reason: 'healthy' };
+  if (input.processExited) return { action: 'restart', reason: 'process-exited' };
+
+  const threshold = input.failureThreshold ?? DEFAULT_HEALTH_FAILURE_THRESHOLD;
+  if (input.consecutiveFailures < threshold) {
+    return { action: 'wait', reason: 'below-threshold' };
+  }
+
+  if (!input.busy) {
+    return { action: 'restart', reason: 'threshold' };
+  }
+
+  // Busy + unhealthy at/over threshold: defer, but not forever.
+  const grace = input.staleBusyGraceMs ?? DEFAULT_STALE_BUSY_GRACE_MS;
+  if (input.unhealthyBusySince > 0 && input.now - input.unhealthyBusySince >= grace) {
+    return { action: 'restart', reason: 'stale-busy-grace' };
+  }
+  return { action: 'wait', reason: 'busy-grace' };
+}
+
+// ─── Orphan worktree reaper target selection (3.4) ───────────────────────────
+
+/** Default TTL: an on-disk worktree dir with no live `worktrees` row is reaped
+ *  only after it's been orphaned at least this long (mtime-based grace so a
+ *  just-created dir mid-`ensureSessionWorktree` race is never swept). */
+export const DEFAULT_ORPHAN_WORKTREE_GRACE_MS = 60 * 60 * 1000; // 1h
+
+export interface OnDiskWorktree {
+  /** Absolute path of the worktree dir on disk. */
+  path: string;
+  /** Last-modified epoch ms of the dir (newest of dir + contents, caller's choice). */
+  mtimeMs: number;
+}
+
+/**
+ * Reaper target selection: which on-disk worktree dirs are orphans safe to
+ * inspect-and-reap. An orphan is a dir under the worktree base that has NO live
+ * `worktrees` row (path not in `liveWorktreePaths`) AND whose mtime is older than
+ * the grace window (so an in-flight create isn't swept).
+ *
+ * Pure — the caller (the sweeper) then runs the at-risk preflight (dirty/unpushed)
+ * on each returned path and only physically removes the SAFE ones. This helper
+ * never decides to remove work-at-risk; it only narrows the candidate set.
+ */
+export function selectOrphanWorktreeTargets(
+  onDisk: ReadonlyArray<OnDiskWorktree>,
+  liveWorktreePaths: ReadonlySet<string>,
+  now: number,
+  graceMs: number = DEFAULT_ORPHAN_WORKTREE_GRACE_MS,
+): string[] {
+  const out: string[] = [];
+  for (const w of onDisk) {
+    if (liveWorktreePaths.has(w.path)) continue; // tracked → not an orphan
+    if (now - w.mtimeMs < graceMs) continue; // too fresh → could be mid-create
+    out.push(w.path);
+  }
+  return out;
+}

apps/coder/src/services/backends/opencode-event-map.ts

@@ -0,0 +1,203 @@
+/**
+ * Pure opencode `Event` → normalized `AgentEvent` translation.
+ *
+ * Extracted (v2.7 audit reshape) from `OpenCodeServerBackend.dispatchEvent` /
+ * `handleUpdatedPart` and the file-local helpers. NO I/O, no timers, no DB, no
+ * `byOpencodeId` — every function here is a deterministic transform over its
+ * arguments (the dedup state is caller-owned and mutated in place, mirroring the
+ * `acp-event-map.ts` `priorSnapshots` pattern). This is the unit-testable core; the
+ * backend keeps the routing + side effects (watchdog, usage persistence, settle).
+ *
+ * Depends only on SDK TYPES + AcpToolSnapshot — safe to import anywhere.
+ */
+import type { Event, Part, ToolPart, ToolState } from '@opencode-ai/sdk/v2/client';
+import type { ToolCallStatus } from '@agentclientprotocol/sdk';
+import type { AcpToolSnapshot } from '../acp-tool-snapshot.js';
+import type { AgentEvent } from '../agent-backend.js';
+
+/** Per-(opencode session) dedup state the part-stream classifiers read + mutate. */
+export interface DedupState {
+  /** dedup gate: `${type}:${id}` added on delta, deleted-and-tested on updated. */
+  streamedPartKeys: Set<string>;
+  /** partID → 'text' | 'reasoning', so a delta with a non-'reasoning' field is still classed right. */
+  partTypeById: Map<string, string>;
+}
+
+/** Strip opencode-dcp plugin tags that render as literal text in the UI. */
+export function stripDcpTags(s: string): string {
+  return s.replace(/<dcp-message-id>[^<]*<\/dcp-message-id>/g, '');
+}
+
+/** Extract the opencode sessionID an event belongs to, across event shapes.
+ *  Most carry `properties.sessionID`; `message.part.updated` nests it under
+ *  `properties.part.sessionID`. Returns null when the event has no session
+ *  (the per-session loop then leaves it to dispatchEvent, which drops it). */
+export function eventSessionId(ev: Event): string | null {
+  const props = (ev as { properties?: unknown }).properties;
+  if (!props || typeof props !== 'object') return null;
+  if (ev.type === 'message.part.updated') {
+    const part = (props as { part?: { sessionID?: string } }).part;
+    return part?.sessionID ?? null;
+  }
+  return (props as { sessionID?: string }).sessionID ?? null;
+}
+
+/** Ported verbatim from Paseo opencode-agent.ts: id → message-id fallback → null. */
+export function resolvePartDedupeKey(part: { id: string; messageID: string }, type: string): string | null {
+  if (part.id.trim().length > 0) return `${type}:${part.id}`;
+  if (part.messageID.trim().length > 0) return `${type}:message:${part.messageID}`;
+  return null;
+}
+
+export function mapToolStatus(s: ToolState['status'] | undefined): ToolCallStatus | null {
+  switch (s) {
+    case 'pending':
+      return 'pending';
+    case 'running':
+      return 'in_progress';
+    case 'completed':
+      return 'completed';
+    case 'error':
+      return 'failed';
+    default:
+      return null;
+  }
+}
+
+/** opencode ToolPart → ACP-shaped snapshot (reuses the existing persist/render path). */
+export function toolPartToSnapshot(part: ToolPart): AcpToolSnapshot {
+  const state = part.state;
+  let rawInput: unknown;
+  let rawOutput: unknown;
+  let title: string | undefined;
+  if (state) {
+    if ('input' in state) rawInput = (state as { input?: unknown }).input;
+    if ('output' in state) rawOutput = (state as { output?: unknown }).output;
+    else if ('error' in state) rawOutput = (state as { error?: unknown }).error;
+    if ('title' in state) title = (state as { title?: string }).title;
+  }
+  return {
+    toolCallId: part.callID,
+    title: title ?? part.tool,
+    kind: null,
+    status: mapToolStatus(state?.status),
+    rawInput,
+    rawOutput,
+  };
+}
+
+// ─── session.next.tool.* snapshot builders ───────────────────────────────────
+
+/** `session.next.tool.called` → an in-progress tool_call snapshot. */
+export function toolCalledSnapshot(p: { callID: string; tool: string; input: unknown }): AcpToolSnapshot {
+  return {
+    toolCallId: p.callID,
+    title: p.tool,
+    kind: null,
+    status: 'in_progress',
+    rawInput: p.input,
+    rawOutput: undefined,
+  };
+}
+
+/** `session.next.tool.success` → a completed tool snapshot (text content joined). */
+export function toolSuccessSnapshot(p: { callID: string; content?: ReadonlyArray<unknown> | null }): AcpToolSnapshot {
+  const output = p.content?.map((c) => (c && typeof c === 'object' && 'text' in c ? (c as { text: string }).text : '')).join('') ?? '';
+  return {
+    toolCallId: p.callID,
+    title: p.callID,
+    kind: null,
+    status: 'completed',
+    rawInput: undefined,
+    rawOutput: output,
+  };
+}
+
+/** `session.next.tool.failed` → a failed tool snapshot (error stringified). */
+export function toolFailedSnapshot(p: { callID: string; error: unknown }): AcpToolSnapshot {
+  return {
+    toolCallId: p.callID,
+    title: p.callID,
+    kind: null,
+    status: 'failed',
+    rawInput: undefined,
+    rawOutput: errToString(p.error),
+  };
+}
+
+// ─── message.part.* dedup gate ────────────────────────────────────────────────
+
+/**
+ * `message.part.delta`: mark the part as streamed (so a later `message.part.updated`
+ * for the same part is deduped) and return the AgentEvent to emit, or null when the
+ * field is neither reasoning nor text, or a text delta strips down to empty. Mutates
+ * `st.streamedPartKeys` exactly as the original inline arm did (the key is recorded
+ * for text even when the cleaned delta is empty).
+ */
+export function classifyPartDelta(
+  p: { partID: string; field?: string; delta: string },
+  st: DedupState,
+): AgentEvent | null {
+  const isReasoning = p.field === 'reasoning' || st.partTypeById.get(p.partID) === 'reasoning';
+  if (isReasoning) {
+    st.streamedPartKeys.add(`reasoning:${p.partID}`);
+    return { type: 'reasoning', text: p.delta };
+  }
+  if (p.field === 'text') {
+    st.streamedPartKeys.add(`text:${p.partID}`);
+    const cleaned = stripDcpTags(p.delta);
+    return cleaned ? { type: 'text', text: cleaned } : null;
+  }
+  return null;
+}
+
+/**
+ * `message.part.updated` terminal part: the dedup gate for text/reasoning (drop a
+ * part already streamed via deltas; otherwise emit the finished text) plus the
+ * tool-part → tool_call/tool_update mapping. Returns null when nothing should be
+ * emitted. Mutates `st.partTypeById` / `st.streamedPartKeys` like the original.
+ */
+export function classifyUpdatedPart(part: Part, st: DedupState): AgentEvent | null {
+  if (part.type === 'text' || part.type === 'reasoning') {
+    st.partTypeById.set(part.id, part.type);
+    const key = resolvePartDedupeKey(part, part.type);
+    if (key && st.streamedPartKeys.delete(key)) return null; // already streamed via delta
+    const raw = part.text ?? '';
+    const text = part.type === 'text' ? stripDcpTags(raw) : raw;
+    if (text && part.time?.end != null) {
+      return { type: part.type, text };
+    }
+    return null;
+  }
+
+  if (part.type === 'tool') {
+    const snap = toolPartToSnapshot(part);
+    const status = part.state?.status;
+    // tool_call on start (pending/running), tool_update on terminal (completed/error).
+    // The current ACP path merges both into one frame; the contract keeps them
+    // distinct because opencode's SSE distinguishes start from result.
+    return status === 'completed' || status === 'error'
+      ? { type: 'tool_update', toolCall: snap }
+      : { type: 'tool_call', toolCall: snap };
+  }
+  // NOTE: opencode's SSE payload union carries no available-commands event, so the
+  // AgentEvent 'commands' arm is intentionally never emitted here.
+  return null;
+}
+
+// ─── shared error formatters (pure) ───────────────────────────────────────────
+
+export function errMsg(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
+export function errToString(e: unknown): string {
+  if (e == null) return 'unknown error';
+  if (typeof e === 'string') return e;
+  if (e instanceof Error) return e.message;
+  try {
+    return JSON.stringify(e);
+  } catch {
+    return String(e);
+  }
+}

apps/coder/src/services/backends/opencode-server-process.ts

@@ -0,0 +1,325 @@
+/**
+ * OpenCodeServerSupervisor — the opencode `serve` child + HTTP client + port +
+ * health-counter lifecycle, extracted (v2.7 audit reshape) from the backend
+ * god-class. Owns spawn / ready / crash / proactive-health restart / dispose and
+ * exposes `client` / `port` / `health()` / `tickHealth()` to the backend.
+ *
+ * Session-level recovery (failing in-flight turns, marking agent_sessions crashed,
+ * tearing down SSE loops) is NOT a process concern — it's delegated back to the
+ * backend through the injected `hooks.onServerDown` callback, keeping this module
+ * free of the demux map / SQL / turn state.
+ *
+ * v2.7 concurrency hardening: `ensureServer` is guarded against the crash-window
+ * double-spawn (two concurrent callers each re-spawning on different ports) via a
+ * synchronous `startInFlight` flag — see `shouldStartServer`.
+ */
+import { spawn, type ChildProcess } from 'node:child_process';
+import { createOpencodeClient, type OpencodeClient } from '@opencode-ai/sdk/v2/client';
+import type { FastifyBaseLogger } from 'fastify';
+import { decideRestart, DEFAULT_HEALTH_FAILURE_THRESHOLD } from './lifecycle-decisions.js';
+import { reclaimPort, waitForPortRelease, freePort } from '../net/port-utils.js';
+
+const READY_TIMEOUT_MS = 30_000;
+
+/** Info handed to the backend when the server goes down (crash or forced restart). */
+export interface ServerDownInfo {
+  code: number | null;
+  signal: NodeJS.Signals | null;
+  port: number;
+}
+
+export interface SupervisorHooks {
+  /** True iff ANY pooled session has an in-flight turn (defers a busy restart). */
+  isBusy: () => boolean;
+  /** Session-level recovery: fail in-flight turns, mark crashed, drop demux state. */
+  onServerDown: (info: ServerDownInfo) => void;
+}
+
+export interface OpenCodeServerSupervisorDeps {
+  /** Absolute path to the opencode binary (resolved from available_agents). */
+  opencodeBinary: string;
+  log: FastifyBaseLogger;
+  hooks: SupervisorHooks;
+}
+
+/**
+ * Pure decision for `ensureServer`: should we (re)spawn the server right now?
+ *
+ * - A live, ready server (`up && client`) → no.
+ * - A start already in flight (`startInFlight`) → no, NEVER double-spawn — join the
+ *   running start instead. This is checked BEFORE `serverStarting` because the crash
+ *   handler can null `serverStarting` mid-start (a crash during `await freePort()`),
+ *   and without this guard the `!serverStarting` branch would spawn a second server
+ *   on a different port while the first is still coming up.
+ * - No start cached/running → yes (fresh start or post-crash re-spawn, since the
+ *   crash handler nulls `serverStarting`).
+ * - A cached start that already finished, but the child has since died and the crash
+ *   handler hasn't reset us yet → yes.
+ */
+export function shouldStartServer(s: {
+  up: boolean;
+  hasClient: boolean;
+  serverStarting: boolean;
+  childDead: boolean;
+  startInFlight: boolean;
+}): boolean {
+  if (s.up && s.hasClient) return false;
+  if (s.startInFlight) return false;
+  if (!s.serverStarting) return true;
+  if (!s.up && s.childDead) return true;
+  return false;
+}
+
+export class OpenCodeServerSupervisor {
+  private readonly opencodeBinary: string;
+  private readonly log: FastifyBaseLogger;
+  private readonly hooks: SupervisorHooks;
+
+  private childProc: ChildProcess | null = null;
+  private opencodeClient: OpencodeClient | null = null;
+  private serverPort: number | null = null;
+  private up = false;
+  private serverStarting: Promise<void> | null = null;
+  /** True from the synchronous head of startServer() until it settles — the
+   *  double-spawn guard reads it so a concurrent ensureServer joins instead of
+   *  kicking a second spawn. */
+  private startInFlight = false;
+  // Phase 3 busy-aware health monitor (openchamber lift): consecutive failed
+  // probes + the start of an unhealthy-while-busy window feed `decideRestart`.
+  private consecutiveHealthFailures = 0;
+  private unhealthyBusySince = 0;
+  private restarting: Promise<void> | null = null;
+
+  constructor(deps: OpenCodeServerSupervisorDeps) {
+    this.opencodeBinary = deps.opencodeBinary;
+    this.log = deps.log;
+    this.hooks = deps.hooks;
+  }
+
+  /** The live opencode HTTP client, or null between (re)starts. */
+  get client(): OpencodeClient | null {
+    return this.opencodeClient;
+  }
+
+  /** The current server port, or null before the first start. */
+  get port(): number | null {
+    return this.serverPort;
+  }
+
+  /** §2: liveness for the health endpoint + dispatcher fallback decision. */
+  health(): 'up' | 'down' {
+    return this.up ? 'up' : 'down';
+  }
+
+  isUp(): boolean {
+    return this.up;
+  }
+
+  // ─── lifecycle (spawn once + client + ready; crash-restart) ──────────────────
+
+  /**
+   * Lazy: start the single server on first use; re-spawn after a crash. Idempotent
+   * within one live server — `serverStarting` caches the in-flight start, reset to
+   * null by the crash handler so the NEXT ensureServer re-spawns. A dead-but-not-
+   * yet-reaped child (exit handler raced) is also treated as needing a restart.
+   * Concurrent callers in a crash window are coalesced via `startInFlight`.
+   */
+  ensureServer(): Promise<void> {
+    if (this.up && this.opencodeClient) return Promise.resolve();
+    const childDead =
+      this.childProc != null && (this.childProc.exitCode !== null || this.childProc.signalCode !== null);
+    if (
+      shouldStartServer({
+        up: this.up,
+        hasClient: this.opencodeClient != null,
+        serverStarting: this.serverStarting != null,
+        childDead,
+        startInFlight: this.startInFlight,
+      })
+    ) {
+      this.serverStarting = this.startServer();
+    }
+    return this.serverStarting ?? Promise.resolve();
+  }
+
+  private async startServer(): Promise<void> {
+    // Set synchronously (before the first await) so a concurrent ensureServer sees
+    // the in-flight start and joins `serverStarting` instead of double-spawning.
+    this.startInFlight = true;
+    try {
+      const port = await freePort();
+
+      // Phase 1: run unsecured on loopback (opencode's documented default — serve.ts
+      // only WARNS when OPENCODE_SERVER_PASSWORD is unset). The real boundary is the
+      // 127.0.0.1 bind.
+      const child = spawn(this.opencodeBinary, ['serve', '--hostname', '127.0.0.1', '--port', String(port)], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env },
+      });
+      this.childProc = child;
+      this.serverPort = port;
+
+      // Child lifetime is the backend's (the pool's), NOT a request's. On unexpected
+      // exit we recover: settle in-flight turns, mark sessions crashed (the backend's
+      // onServerDown), reclaim the port, and reset state so the next ensureServer
+      // re-spawns.
+      child.on('exit', (code, signal) => {
+        // Only react to THIS child's exit (a restart may have swapped in a new one).
+        if (this.childProc !== child) return;
+        this.handleCrash(code, signal, port);
+      });
+
+      await waitForReady(child, READY_TIMEOUT_MS);
+
+      this.opencodeClient = createOpencodeClient({ baseUrl: `http://127.0.0.1:${port}` });
+      this.up = true;
+      this.log.info({ port }, 'opencode-server: ready');
+    } finally {
+      this.startInFlight = false;
+    }
+  }
+
+  /**
+   * Server down (crash-exit or forced restart): reset process/port state, delegate
+   * session-level recovery to the backend, and reclaim the port. Mirrors the
+   * original `handleServerCrash` ordering (up=false → session cleanup → client/
+   * serverStarting null → reclaimPort).
+   */
+  private handleCrash(code: number | null, signal: NodeJS.Signals | null, port: number): void {
+    this.up = false;
+    this.hooks.onServerDown({ code, signal, port });
+    this.opencodeClient = null;
+    this.serverStarting = null; // force a re-spawn on the next ensureServer
+    // Reclaim the port so a re-spawn on a fixed/leaked port isn't blocked. Best
+    // effort; the next start uses a fresh ephemeral port anyway.
+    reclaimPort(port);
+  }
+
+  /**
+   * Phase 3 proactive health monitor (openchamber `runHealthCheckCycle` lift,
+   * busy-aware). Probes /global/health; on a sustained failure of a NON-busy server,
+   * force a restart so the next turn isn't blocked by a wedged process. Busy servers
+   * are deferred via the stale-grace in `decideRestart`. No-op when never started or
+   * a restart is already in flight.
+   */
+  async tickHealth(now: number = Date.now()): Promise<void> {
+    if (!this.childProc || this.restarting) return;
+    const childExited = this.childProc.exitCode !== null || this.childProc.signalCode !== null;
+    // An exited child is recovered lazily by ensureServer; don't double-restart it.
+    if (childExited) return;
+
+    const healthy = await this.probeHealth();
+    if (healthy) {
+      this.consecutiveHealthFailures = 0;
+      this.unhealthyBusySince = 0;
+      return;
+    }
+    this.consecutiveHealthFailures += 1;
+    const busy = this.hooks.isBusy();
+    const decision = decideRestart({
+      processExited: false,
+      consecutiveFailures: this.consecutiveHealthFailures,
+      busy,
+      unhealthyBusySince: this.unhealthyBusySince,
+      now,
+      failureThreshold: DEFAULT_HEALTH_FAILURE_THRESHOLD,
+    });
+    // Stamp the start of an unhealthy-while-busy window so the stale-grace can fire.
+    if (busy && this.unhealthyBusySince === 0) this.unhealthyBusySince = now;
+    if (decision.action === 'restart') {
+      this.log.warn(
+        { failures: this.consecutiveHealthFailures, busy, reason: decision.reason },
+        'opencode-server: health monitor forcing restart',
+      );
+      this.consecutiveHealthFailures = 0;
+      this.unhealthyBusySince = 0;
+      await this.restartServer();
+    }
+  }
+
+  private async probeHealth(): Promise<boolean> {
+    if (!this.opencodeClient) return false;
+    try {
+      const res = await this.opencodeClient.global.health();
+      return !res.error;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Force-kill the current server + reclaim its port; the next ensureServer
+   *  re-spawns (lazy). Mirrors handleCrash's state reset but is initiated by the
+   *  health monitor rather than the OS. */
+  private async restartServer(): Promise<void> {
+    if (this.restarting) return this.restarting;
+    this.restarting = (async () => {
+      const child = this.childProc;
+      const port = this.serverPort;
+      this.up = false;
+      // Fail in-flight turns + mark sessions crashed via the same path as a crash.
+      if (child) {
+        this.handleCrash(null, null, port ?? 0);
+        if (!child.killed) child.kill('SIGTERM');
+      }
+      if (port) {
+        reclaimPort(port);
+        await waitForPortRelease(port, 3_000);
+      }
+      this.childProc = null;
+    })().finally(() => {
+      this.restarting = null;
+    });
+    return this.restarting;
+  }
+
+  /** Full teardown of the child + client + port state. */
+  async dispose(): Promise<void> {
+    this.up = false;
+    const child = this.childProc;
+    this.childProc = null;
+    this.opencodeClient = null;
+    if (child && !child.killed) {
+      child.kill('SIGTERM');
+      const t = setTimeout(() => {
+        if (!child.killed) child.kill('SIGKILL');
+      }, 5_000);
+      t.unref();
+    }
+  }
+}
+
+/** Resolve when the child prints the ready line; reject on timeout or early exit. */
+function waitForReady(child: ChildProcess, timeoutMs: number): Promise<void> {
+  return new Promise((resolve, reject) => {
+    let done = false;
+    let stderrBuf = '';
+
+    const finish = (err?: Error) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      child.stdout?.off('data', onOut);
+      child.stderr?.off('data', onErr);
+      child.off('exit', onExit);
+      if (err) reject(err);
+      else resolve();
+    };
+
+    const onOut = (buf: Buffer) => {
+      if (buf.toString().includes('opencode server listening on')) finish();
+    };
+    const onErr = (buf: Buffer) => {
+      stderrBuf += buf.toString();
+    };
+    const onExit = (code: number | null) =>
+      finish(new Error(`opencode serve exited before ready (code ${code}); stderr: ${stderrBuf.slice(-2000)}`));
+    const timer = setTimeout(
+      () => finish(new Error(`opencode serve not ready in ${timeoutMs}ms; stderr: ${stderrBuf.slice(-2000)}`)),
+      timeoutMs,
+    );
+
+    child.stdout?.on('data', onOut);
+    child.stderr?.on('data', onErr);
+    child.on('exit', onExit);
+  });
+}

apps/coder/src/services/backends/opencode-server.ts

@@ -1,90 +1,64 @@
 /**
- * v2.6 Phase 1 — OpenCodeServerBackend.
+ * v2.6 Phase 1 — OpenCodeServerBackend (slimmed, v2.7 audit reshape).
  *
  * Warm, multi-turn backend for the `opencode` agent. One `opencode serve` HTTP
  * server per BooCoder process; one opencode session per BooCode session (resumed
  * on switch-back); one SSE read loop PER session, each scoped to that session's
- * worktree directory so sessions in different directories stream concurrently
- * (P1.5-a — replaced the Phase-1 single-stream-last-directory model).
+ * worktree directory so sessions in different directories stream concurrently.
+ *
+ * This file is now just the `AgentBackend` SURFACE — ensureSession / prompt /
+ * accumulateUsage / closeSession + the per-session demux side effects (watchdog,
+ * reconcile, usage). It composes three extracted collaborators:
+ *   - `OpenCodeServerSupervisor` (opencode-server-process.ts) — child/client/port/
+ *     health lifecycle, spawn/crash/restart/dispose.
+ *   - the per-session SSE loop (opencode-sse.ts) — subscribe + reconnect/backoff.
+ *   - the pure event map (opencode-event-map.ts) — Event → AgentEvent translation,
+ *     dedup gate, dcp-strip, tool-snapshot.
  *
  * Implements the Phase 0 `AgentBackend` interface. Emits transport-agnostic
- * `AgentEvent`s — the dispatcher (Phase 1.7, NOT wired in this batch) maps them
- * to WS frames. No dispatcher/route references this file yet.
+ * `AgentEvent`s; the dispatcher maps them to WS frames.
  *
  * Spec: openspec/changes/v2-6-persistent-agent-sessions/design.md §2 / §2a.
- * SDK shapes verified by direct read of @opencode-ai/sdk@1.15.12 dist .d.ts:
- *   - client methods take FLATTENED params (sessionID/directory/body all inline),
- *     not {path,query,body}. create→{directory}, promptAsync→{sessionID,directory,
- *     parts,model}, abort→{sessionID,directory}. model is {providerID,modelID}.
- *   - client.event() resolves to { stream: AsyncGenerator<GlobalEvent> }; the
- *     real event is chunk.payload (discriminate on chunk.payload.type).
- *   - promptAsync is fire-and-forget (204); the turn completes via a
- *     'session.idle' event for that opencode session id.
  */
-import { spawn, type ChildProcess } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { createServer } from 'node:net';
 import type { FastifyBaseLogger } from 'fastify';
-import {
-  createOpencodeClient,
-  type OpencodeClient,
-  type Event,
-  type Part,
-  type ToolPart,
-  type ToolState,
-  type AssistantMessage,
-} from '@opencode-ai/sdk/v2/client';
-import type { ToolCallStatus } from '@agentclientprotocol/sdk';
+import type { Event, AssistantMessage } from '@opencode-ai/sdk/v2/client';
 import type { Sql } from '../../db.js';
-import type { AcpToolSnapshot } from '../acp-tool-snapshot.js';
 import { armAbortGuard, noteTurnActivity, consumeTerminal } from './turn-guard.js';
 import { stepEndedToUsage, type StepUsage } from './opencode-usage.js';
+import { OpenCodeServerSupervisor, type ServerDownInfo } from './opencode-server-process.js';
+import {
+  startSessionEventLoop,
+  type SessionState,
+  type TurnState,
+  type SseLoopDeps,
+} from './opencode-sse.js';
+import {
+  classifyPartDelta,
+  classifyUpdatedPart,
+  toolCalledSnapshot,
+  toolSuccessSnapshot,
+  toolFailedSnapshot,
+  stripDcpTags,
+  errMsg,
+  errToString,
+} from './opencode-event-map.js';
 import type {
   AgentBackend,
-  AgentEvent,
   AgentSessionHandle,
   EnsureSessionOpts,
   PromptCtx,
   TurnResult,
 } from '../agent-backend.js';
 
-const READY_TIMEOUT_MS = 30_000;
-const SSE_RECONNECT_DELAY_MS = 1_000;
 /**
  * No-activity backstop for an in-flight turn. opencode streams reasoning/text/tool
  * deltas continuously while working, so "zero events for this long" means the turn
- * is wedged or its terminal event (session.idle) was lost (see the reconnect race
- * below). Generous so a legitimately slow turn never trips it.
+ * is wedged or its terminal event (session.idle) was lost. Generous so a
+ * legitimately slow turn never trips it.
  */
 const TURN_INACTIVITY_MS = 180_000;
 
-/** One in-flight turn's emitter + completion settler. */
-interface TurnState {
-  onEvent: (e: AgentEvent) => void;
-  settle: (r: TurnResult) => void;
-}
-
-/** Per-(opencode session) demux state. dedup sets scoped here, cleared per turn. */
-interface SessionState {
-  boocodeSessionId: string;
-  agentSessionId: string;
-  /** Worktree directory for SDK `directory` routing; refreshed each turn from ctx. */
-  worktreePath: string;
-  /** dedup gate: `${type}:${id}` added on delta, deleted-and-tested on updated. Cleared at turn end. */
-  streamedPartKeys: Set<string>;
-  /** partID → 'text' | 'reasoning', so a delta with a non-'reasoning' field is still classed right. Cleared at turn end. */
-  partTypeById: Map<string, string>;
-  activeTurn: TurnState | null;
-  /** Inactivity backstop timer for the active turn; null when no turn in flight. */
-  watchdog: ReturnType<typeof setTimeout> | null;
-  /** Per-session SSE subscription handle. Non-null while the loop is running;
-   *  aborting it tears down the underlying fetch and exits the loop. */
-  sseAbort: AbortController | null;
-  /** F.1 post-abort orphan-terminal guard: swallow the one session.idle/error
-   *  opencode emits for an aborted turn so it can't settle the next turn. */
-  swallowNextTerminal: boolean;
-}
-
 export interface OpenCodeServerBackendDeps {
   sql: Sql;
   log: FastifyBaseLogger;
@@ -97,120 +71,97 @@ export class OpenCodeServerBackend implements AgentBackend {
 
   private readonly sql: Sql;
   private readonly log: FastifyBaseLogger;
-  private readonly opencodeBinary: string;
-
-  private child: ChildProcess | null = null;
-  private client: OpencodeClient | null = null;
-  private port: number | null = null;
-  private up = false;
-  private serverStarting: Promise<void> | null = null;
+  private readonly supervisor: OpenCodeServerSupervisor;
 
   /** opencode session id → demux state. Maintained by ensureSession; read by the SSE loop. */
   private readonly byOpencodeId = new Map<string, SessionState>();
+  /** Coalesces concurrent ensureSession calls for the same (chat, agent) key. */
+  private readonly ensuring = new Map<string, Promise<AgentSessionHandle>>();
 
   constructor(deps: OpenCodeServerBackendDeps) {
     this.sql = deps.sql;
     this.log = deps.log;
-    this.opencodeBinary = deps.opencodeBinary;
+    this.supervisor = new OpenCodeServerSupervisor({
+      opencodeBinary: deps.opencodeBinary,
+      log: deps.log,
+      hooks: {
+        isBusy: () => this.isBusy(),
+        onServerDown: (info) => this.onServerDown(info),
+      },
+    });
   }
 
   /** §2: liveness for the health endpoint + dispatcher fallback decision. */
   health(): 'up' | 'down' {
-    return this.up ? 'up' : 'down';
+    return this.supervisor.health();
   }
 
-  // ─── Server lifecycle (1.2: spawn once + client + ready) ─────────────────────
-
-  /** Lazy: start the single server on first use. Idempotent — one server per backend. */
-  private ensureServer(): Promise<void> {
-    if (!this.serverStarting) this.serverStarting = this.startServer();
-    return this.serverStarting;
-  }
-
-  private async startServer(): Promise<void> {
-    const port = await freePort();
-
-    // Phase 1: run unsecured on loopback (opencode's documented default — serve.ts
-    // only WARNS when OPENCODE_SERVER_PASSWORD is unset). The real boundary is the
-    // 127.0.0.1 bind. Defense-in-depth basic-auth is deferred: the hey-api client's
-    // auth wiring + opencode's exact scheme must be confirmed against a live server
-    // first, else every request 401s. Recon explicitly said "do NOT block on it".
-    const child = spawn(this.opencodeBinary, ['serve', '--hostname', '127.0.0.1', '--port', String(port)], {
-      stdio: ['ignore', 'pipe', 'pipe'],
-      env: { ...process.env },
-    });
-    this.child = child;
-    this.port = port;
-
-    // Child lifetime is the backend's (the pool's), NOT a request's. We never tie
-    // it to a per-turn abort signal. On unexpected exit we mark down + log; crash
-    // recovery is Phase 3.
-    child.on('exit', (code, signal) => {
-      this.up = false;
-      this.log.warn({ code, signal, port }, 'opencode-server: child exited (recovery is Phase 3)');
-    });
-
-    await waitForReady(child, READY_TIMEOUT_MS);
-
-    this.client = createOpencodeClient({ baseUrl: `http://127.0.0.1:${port}` });
-    this.up = true;
-    this.log.info({ port }, 'opencode-server: ready');
-  }
-
-  // ─── SSE read loop + demux + translate (1.3) + dedup (1.4) ───────────────────
-
-  /** Per-session SSE subscription, scoped to the session's worktree directory.
-   *  opencode scopes events by the `directory` query param (defaults to the
-   *  server's cwd if omitted), so two sessions in different worktrees each get
-   *  their own dir-scoped stream and never drop each other's events. Idempotent:
-   *  a no-op if this session's loop is already running. Started from ensureSession
-   *  (and defensively from prompt) once worktreePath is known. */
-  private startSessionEventLoop(state: SessionState): void {
-    if (state.sseAbort) return; // already running
-    const abort = new AbortController();
-    state.sseAbort = abort;
-    void this.runSessionEventLoop(state, abort).finally(() => {
-      // Only clear if this controller is still the live one (a later restart may
-      // have already installed a new one).
-      if (state.sseAbort === abort) state.sseAbort = null;
-    });
-  }
-
-  private async runSessionEventLoop(state: SessionState, abort: AbortController): Promise<void> {
-    const signal = abort.signal;
-    while (this.up && this.client && !signal.aborted) {
-      try {
-        // Re-read worktreePath each (re)subscribe so a directory refresh is picked
-        // up on reconnect. Passing `signal` lets close/dispose tear down a stream
-        // that's parked in `for await` between events.
-        const sub = await this.client.event.subscribe(
-          { directory: state.worktreePath },
-          { signal },
-        );
-        for await (const ev of sub.stream) {
-          if (signal.aborted) break;
-          // Dir-scoped streams should only carry this session's events, but two
-          // sessions sharing a worktree (possible post-P1.5-b) each receive BOTH
-          // sessions' events — so drop anything that isn't ours, else the other
-          // session's deltas get processed twice (once per loop).
-          const sid = eventSessionId(ev);
-          if (sid != null && sid !== state.agentSessionId) continue;
-          this.dispatchEvent(ev);
-        }
-        if (this.up && !signal.aborted) {
-          await this.reconcile(state); // recover an idle/error lost during the gap
-          await sleep(SSE_RECONNECT_DELAY_MS);
-        }
-      } catch (err) {
-        if (!this.up || signal.aborted) break;
-        this.log.warn(
-          { err: errMsg(err), agentSessionId: state.agentSessionId },
-          'opencode-server: session event loop error; reconnecting',
-        );
-        await this.reconcile(state);
-        await sleep(SSE_RECONNECT_DELAY_MS);
-      }
+  /** Phase 3: busy iff ANY pooled opencode session has an in-flight turn. */
+  isBusy(): boolean {
+    for (const st of this.byOpencodeId.values()) {
+      if (st.activeTurn) return true;
     }
+    return false;
+  }
+
+  /** Phase 3 proactive health probe + busy-aware self-restart, run by the pool's
+   *  periodic sweep. Delegates to the supervisor. */
+  async tickHealth(now: number = Date.now()): Promise<void> {
+    await this.supervisor.tickHealth(now);
+  }
+
+  /**
+   * Server down (crash-exit or forced restart): fail every in-flight turn so its
+   * dispatcher unblocks, mark each session crashed so ensureSession won't resume a
+   * now-dead native id, and tear down the SSE loops + demux state. Invoked by the
+   * supervisor (it owns the process/port reset). Mirrors the original
+   * handleServerCrash session-half byte-for-byte.
+   */
+  private onServerDown(info: ServerDownInfo): void {
+    const states = [...this.byOpencodeId.values()];
+    this.log.warn(
+      { code: info.code, signal: info.signal, port: info.port, liveSessions: states.length },
+      'opencode-server: child exited — recovering (fail in-flight, mark crashed, re-spawn next turn)',
+    );
+
+    const crashedIds: string[] = [];
+    for (const st of states) {
+      st.sseAbort?.abort();
+      if (st.activeTurn) {
+        st.activeTurn.settle({ ok: false, error: 'opencode server crashed mid-turn' });
+        st.activeTurn = null;
+      }
+      if (st.watchdog) {
+        clearTimeout(st.watchdog);
+        st.watchdog = null;
+      }
+      crashedIds.push(st.agentSessionId);
+    }
+    // Drop the demux map: every session id is stale against a fresh server.
+    this.byOpencodeId.clear();
+
+    if (crashedIds.length > 0) {
+      this.sql`
+        UPDATE agent_sessions SET status = 'crashed'
+        WHERE agent_session_id = ANY(${crashedIds}) AND status <> 'closed'
+      `.catch((err) => {
+        this.log.warn({ err: errMsg(err) }, 'opencode-server: failed to mark crashed sessions (non-fatal)');
+      });
+    }
+  }
+
+  // ─── SSE loop wiring ─────────────────────────────────────────────────────────
+
+  /** The dependency bundle the per-session SSE loop reads. */
+  private sseDeps(): SseLoopDeps {
+    return {
+      isUp: () => this.supervisor.isUp(),
+      getClient: () => this.supervisor.client,
+      dispatchEvent: (ev) => this.dispatchEvent(ev),
+      reconcile: (st) => this.reconcile(st),
+      onReconnectGiveUp: (st) => this.onReconnectGiveUp(st),
+      log: this.log,
+    };
   }
 
   /** Demux one event to the owning session's active turn. Unknown/between-turns → drop. */
@@ -239,15 +190,7 @@ export class OpenCodeServerBackend implements AgentBackend {
         const st = this.byOpencodeId.get(p.sessionID);
         if (!st?.activeTurn) return;
         this.bumpActivity(st);
-        const snap: AcpToolSnapshot = {
-          toolCallId: p.callID,
-          title: p.tool,
-          kind: null,
-          status: 'in_progress',
-          rawInput: p.input,
-          rawOutput: undefined,
-        };
-        st.activeTurn.onEvent({ type: 'tool_call', toolCall: snap });
+        st.activeTurn.onEvent({ type: 'tool_call', toolCall: toolCalledSnapshot(p) });
         return;
       }
       case 'session.next.tool.success': {
@@ -255,16 +198,7 @@ export class OpenCodeServerBackend implements AgentBackend {
         const st = this.byOpencodeId.get(p.sessionID);
         if (!st?.activeTurn) return;
         this.bumpActivity(st);
-        const output = p.content?.map((c) => ('text' in c ? (c as { text: string }).text : '')).join('') ?? '';
-        const snap: AcpToolSnapshot = {
-          toolCallId: p.callID,
-          title: p.callID,
-          kind: null,
-          status: 'completed',
-          rawInput: undefined,
-          rawOutput: output,
-        };
-        st.activeTurn.onEvent({ type: 'tool_update', toolCall: snap });
+        st.activeTurn.onEvent({ type: 'tool_update', toolCall: toolSuccessSnapshot(p) });
         return;
       }
       case 'session.next.tool.failed': {
@@ -272,15 +206,7 @@ export class OpenCodeServerBackend implements AgentBackend {
         const st = this.byOpencodeId.get(p.sessionID);
         if (!st?.activeTurn) return;
         this.bumpActivity(st);
-        const snap: AcpToolSnapshot = {
-          toolCallId: p.callID,
-          title: p.callID,
-          kind: null,
-          status: 'failed',
-          rawInput: undefined,
-          rawOutput: errToString(p.error),
-        };
-        st.activeTurn.onEvent({ type: 'tool_update', toolCall: snap });
+        st.activeTurn.onEvent({ type: 'tool_update', toolCall: toolFailedSnapshot(p) });
         return;
       }
       // ─── per-step usage (U.6) — token/cost accounting for opencode sessions ──
@@ -290,8 +216,7 @@ export class OpenCodeServerBackend implements AgentBackend {
         if (!st?.activeTurn) return;
         this.bumpActivity(st);
         // Accumulate this step's normalized usage onto the (chat_id, agent) row.
-        // Fire-and-forget: a DB hiccup must not stall the turn. opencode emits this
-        // once per LLM step, so a multi-tool turn sums several deltas.
+        // Fire-and-forget: a DB hiccup must not stall the turn.
         const usage = stepEndedToUsage(p);
         void this.accumulateUsage(st, usage);
         return;
@@ -302,15 +227,8 @@ export class OpenCodeServerBackend implements AgentBackend {
         const st = this.byOpencodeId.get(p.sessionID);
         if (!st?.activeTurn) return;
         this.bumpActivity(st);
-        const isReasoning = p.field === 'reasoning' || st.partTypeById.get(p.partID) === 'reasoning';
-        if (isReasoning) {
-          st.streamedPartKeys.add(`reasoning:${p.partID}`);
-          st.activeTurn.onEvent({ type: 'reasoning', text: p.delta });
-        } else if (p.field === 'text') {
-          st.streamedPartKeys.add(`text:${p.partID}`);
-          const cleaned = stripDcpTags(p.delta);
-          if (cleaned) st.activeTurn.onEvent({ type: 'text', text: cleaned });
-        }
+        const e = classifyPartDelta(p, st);
+        if (e) st.activeTurn.onEvent(e);
         return;
       }
       case 'message.part.updated': {
@@ -318,7 +236,8 @@ export class OpenCodeServerBackend implements AgentBackend {
         const st = this.byOpencodeId.get(part.sessionID);
         if (!st?.activeTurn) return;
         this.bumpActivity(st);
-        this.handleUpdatedPart(part, st);
+        const e = classifyUpdatedPart(part, st);
+        if (e) st.activeTurn.onEvent(e);
         return;
       }
       // ─── lifecycle ─────────────────────────────────────────────────────────
@@ -343,40 +262,6 @@ export class OpenCodeServerBackend implements AgentBackend {
     }
   }
 
-  /** Terminal part: dedup gate for text/reasoning; tool parts → tool_call/tool_update. */
-  private handleUpdatedPart(part: Part, st: SessionState): void {
-    const turn = st.activeTurn;
-    if (!turn) return;
-
-    if (part.type === 'text' || part.type === 'reasoning') {
-      st.partTypeById.set(part.id, part.type);
-      const key = resolvePartDedupeKey(part, part.type);
-      if (key && st.streamedPartKeys.delete(key)) return; // already streamed via delta
-      const raw = part.text ?? '';
-      const text = part.type === 'text' ? stripDcpTags(raw) : raw;
-      if (text && part.time?.end != null) {
-        turn.onEvent({ type: part.type, text });
-      }
-      return;
-    }
-
-    if (part.type === 'tool') {
-      const snap = toolPartToSnapshot(part);
-      const status = part.state?.status;
-      // tool_call on start (pending/running), tool_update on terminal (completed/error).
-      // The current ACP path merges both into one frame; the contract keeps them
-      // distinct because opencode's SSE distinguishes start from result.
-      const event: AgentEvent =
-        status === 'completed' || status === 'error'
-          ? { type: 'tool_update', toolCall: snap }
-          : { type: 'tool_call', toolCall: snap };
-      turn.onEvent(event);
-      return;
-    }
-    // NOTE: opencode's SSE payload union carries no available-commands event, so the
-    // AgentEvent 'commands' arm is intentionally never emitted here (1.3).
-  }
-
   // ─── turn-completion resilience (watchdog + reconnect reconcile) ─────────────
 
   /** Reset the inactivity backstop on any event routed to a session's active turn. */
@@ -391,8 +276,8 @@ export class OpenCodeServerBackend implements AgentBackend {
     st.watchdog.unref?.();
   }
 
-  /** Watchdog fired: reconcile once; if the server says still-running we can't tell, so fail closed.
-   *  Also mark the agent_sessions row crashed so a stale session isn't resumed next turn. */
+  /** Watchdog fired: reconcile once; if still-running we can't tell, so fail closed.
+   *  Also mark the agent_sessions row crashed so a stale session isn't resumed. */
   private async onTurnStall(st: SessionState): Promise<void> {
     const settled = await this.reconcile(st);
     if (!settled) {
@@ -405,16 +290,27 @@ export class OpenCodeServerBackend implements AgentBackend {
     }
   }
 
+  /** SSE circuit-breaker fired (reconnect gave up): fail the active turn + mark the
+   *  session crashed so it isn't resumed. The next turn re-creates a fresh session. */
+  private async onReconnectGiveUp(st: SessionState): Promise<void> {
+    if (!st.activeTurn) return;
+    await this.sql`
+      UPDATE agent_sessions SET status = 'crashed'
+      WHERE agent_session_id = ${st.agentSessionId}
+    `.catch(() => {});
+    st.activeTurn?.settle({ ok: false, error: 'opencode SSE stream lost (reconnect gave up)' });
+  }
+
   /**
    * Ask the server whether this session's turn already finished — recovers a
    * session.idle/error lost during an SSE gap. Returns true if it settled the turn.
-   * Inconclusive (still running / call failed) → false; the watchdog covers that.
    */
   private async reconcile(st: SessionState): Promise<boolean> {
     const turn = st.activeTurn;
-    if (!turn || !this.client) return false;
+    const client = this.supervisor.client;
+    if (!turn || !client) return false;
     try {
-      const res = await this.client.session.messages({
+      const res = await client.session.messages({
         sessionID: st.agentSessionId,
         directory: st.worktreePath,
       });
@@ -446,10 +342,8 @@ export class OpenCodeServerBackend implements AgentBackend {
 
   /**
    * Accumulate one `session.next.step.ended`'s normalized usage onto the session's
-   * agent_sessions row, keyed by the resumed `agent_session_id` (unique per active
-   * row — the dispatcher's `(chat_id, agent)` lookup wrote it). Running totals for
-   * the whole conversation context (not last-step). Zero-delta steps are skipped to
-   * avoid a no-op write. Errors are swallowed: usage telemetry must never fail a turn.
+   * agent_sessions row. Running totals for the whole conversation context. Zero-delta
+   * steps are skipped. Errors are swallowed: usage telemetry must never fail a turn.
    */
   private async accumulateUsage(st: SessionState, u: StepUsage): Promise<void> {
     if (u.input === 0 && u.output === 0 && u.cost === 0) return;
@@ -472,13 +366,29 @@ export class OpenCodeServerBackend implements AgentBackend {
   // ─── ensureSession: create-or-resume against agent_sessions (1.5) ────────────
 
   async ensureSession(sessionId: string, opts: EnsureSessionOpts): Promise<AgentSessionHandle> {
-    await this.ensureServer();
-    if (!this.client) throw new Error('opencode-server: client not ready after ensureServer');
+    // Coalesce concurrent first-turns for the same (chat, agent) so the SELECT…
+    // create…upsert can't race into two opencode sessions (the second orphaning
+    // the first). A single (non-concurrent) call is unaffected — the entry is set
+    // and removed within this call. Defensive: the dispatcher already serializes
+    // turns per (chat, agent) via its inflight map.
+    const key = `${opts.chatId}:${opts.agent}`;
+    const existing = this.ensuring.get(key);
+    if (existing) return existing;
+    const p = this.ensureSessionInner(sessionId, opts).finally(() => {
+      if (this.ensuring.get(key) === p) this.ensuring.delete(key);
+    });
+    this.ensuring.set(key, p);
+    return p;
+  }
+
+  private async ensureSessionInner(sessionId: string, opts: EnsureSessionOpts): Promise<AgentSessionHandle> {
+    await this.supervisor.ensureServer();
+    const client = this.supervisor.client;
+    if (!client) throw new Error('opencode-server: client not ready after ensureServer');
 
     const configHash = sessionConfigHash(opts.model);
     // P1.5-b: agent_sessions is keyed (chat_id, agent) — the tab/chat is the
     // context unit (two tabs in one session = two contexts sharing one worktree).
-    // session_id + worktree_id are retained as informational (SET NULL) columns.
     const [row] = await this.sql<{ agent_session_id: string | null; status: string; config_hash: string | null }[]>`
       SELECT agent_session_id, status, config_hash FROM agent_sessions
       WHERE chat_id = ${opts.chatId} AND agent = ${opts.agent}
@@ -496,7 +406,7 @@ export class OpenCodeServerBackend implements AgentBackend {
           'opencode-server: not resuming stale session, creating fresh');
         this.byOpencodeId.delete(agentSessionId);
       }
-      const created = await this.client.session.create({ directory: opts.worktreePath });
+      const created = await client.session.create({ directory: opts.worktreePath });
       if (created.error || !created.data) {
         throw new Error(`opencode-server: session.create failed: ${errToString(created.error)}`);
       }
@@ -505,7 +415,7 @@ export class OpenCodeServerBackend implements AgentBackend {
         INSERT INTO agent_sessions
           (chat_id, session_id, worktree_id, agent, backend, agent_session_id, server_port, status, last_active_at, config_hash)
         VALUES
-          (${opts.chatId}, ${sessionId}, ${opts.worktreeId}, ${opts.agent}, 'opencode_server', ${agentSessionId}, ${this.port}, 'active', clock_timestamp(), ${configHash})
+          (${opts.chatId}, ${sessionId}, ${opts.worktreeId}, ${opts.agent}, 'opencode_server', ${agentSessionId}, ${this.supervisor.port}, 'active', clock_timestamp(), ${configHash})
         ON CONFLICT (chat_id, agent) DO UPDATE SET
           session_id = EXCLUDED.session_id,
           worktree_id = EXCLUDED.worktree_id,
@@ -519,7 +429,7 @@ export class OpenCodeServerBackend implements AgentBackend {
     } else {
       await this.sql`
         UPDATE agent_sessions
-        SET status = 'active', last_active_at = clock_timestamp(), server_port = ${this.port}, config_hash = ${configHash}
+        SET status = 'active', last_active_at = clock_timestamp(), server_port = ${this.supervisor.port}, config_hash = ${configHash}
         WHERE chat_id = ${opts.chatId} AND agent = ${opts.agent}
       `;
     }
@@ -534,24 +444,13 @@ export class OpenCodeServerBackend implements AgentBackend {
       state.boocodeSessionId = sessionId;
       state.worktreePath = opts.worktreePath;
     } else {
-      state = {
-        boocodeSessionId: sessionId,
-        agentSessionId: ocSessionId,
-        worktreePath: opts.worktreePath,
-        streamedPartKeys: new Set(),
-        partTypeById: new Map(),
-        activeTurn: null,
-        watchdog: null,
-        sseAbort: null,
-        swallowNextTerminal: false,
-      };
+      state = this.makeSessionState(sessionId, ocSessionId, opts.worktreePath);
       this.byOpencodeId.set(ocSessionId, state);
     }
 
     // Start this session's own SSE loop, scoped to its worktree directory. Both
-    // fresh-create and resume reach here; idempotent, so a re-ensure (e.g. a
-    // second turn) won't spawn a duplicate loop.
-    this.startSessionEventLoop(state);
+    // fresh-create and resume reach here; idempotent.
+    startSessionEventLoop(state, this.sseDeps());
 
     return {
       sessionId,
@@ -560,40 +459,53 @@ export class OpenCodeServerBackend implements AgentBackend {
       chatId: opts.chatId,
       worktreeId: opts.worktreeId,
       agentSessionId: ocSessionId,
-      serverPort: this.port,
+      serverPort: this.supervisor.port,
+    };
+  }
+
+  /** Fresh per-(opencode session) demux state. */
+  private makeSessionState(boocodeSessionId: string, agentSessionId: string, worktreePath: string): SessionState {
+    return {
+      boocodeSessionId,
+      agentSessionId,
+      worktreePath,
+      streamedPartKeys: new Set(),
+      partTypeById: new Map(),
+      activeTurn: null,
+      watchdog: null,
+      sseAbort: null,
+      swallowNextTerminal: false,
     };
   }
 
   // ─── prompt: send one turn (1.6) ─────────────────────────────────────────────
 
   async prompt(handle: AgentSessionHandle, input: string, ctx: PromptCtx): Promise<TurnResult> {
-    if (!this.client) throw new Error('opencode-server: client not ready');
+    const client = this.supervisor.client;
+    if (!client) throw new Error('opencode-server: client not ready');
     const oc = handle.agentSessionId;
     if (!oc) throw new Error('opencode-server: handle has no agentSessionId');
 
     let state = this.byOpencodeId.get(oc);
     if (!state) {
-      state = {
-        boocodeSessionId: handle.sessionId,
-        agentSessionId: oc,
-        worktreePath: ctx.worktreePath,
-        streamedPartKeys: new Set(),
-        partTypeById: new Map(),
-        activeTurn: null,
-        watchdog: null,
-        sseAbort: null,
-        swallowNextTerminal: false,
-      };
+      state = this.makeSessionState(handle.sessionId, oc, ctx.worktreePath);
       this.byOpencodeId.set(oc, state);
     }
     const session = state;
+
+    // v2.7 busy-assert: one in-flight turn per session. The dispatcher serializes
+    // turns per (chat, agent), so this never fires in normal dispatch — but if a
+    // second prompt arrives while one is live it would silently overwrite the slot
+    // and orphan the first turn, so reject instead.
+    if (session.activeTurn) {
+      return { ok: false, error: 'opencode-server: session already has an in-flight turn' };
+    }
+
     // Authoritative per-turn directory for SDK routing + reconcile.
     session.worktreePath = ctx.worktreePath;
     // Defensive: ensureSession normally starts the loop, but if prompt is reached
     // with a freshly-created state (no loop yet), start it so the turn streams.
-    // Idempotent when ensureSession already started one.
-    this.startSessionEventLoop(session);
-    const client = this.client;
+    startSessionEventLoop(session, this.sseDeps());
 
     return await new Promise<TurnResult>((resolve) => {
       let settled = false;
@@ -622,7 +534,8 @@ export class OpenCodeServerBackend implements AgentBackend {
         settle({ ok: false, error: 'aborted' });
       };
 
-      session.activeTurn = { onEvent: ctx.onEvent, settle };
+      const turn: TurnState = { onEvent: ctx.onEvent, settle };
+      session.activeTurn = turn;
       this.bumpActivity(session); // arm the inactivity backstop
 
       if (ctx.signal.aborted) {
@@ -663,39 +576,15 @@ export class OpenCodeServerBackend implements AgentBackend {
   }
 
   async dispose(): Promise<void> {
-    this.up = false;
     // Abort every per-session SSE loop so none survive the teardown.
     for (const st of this.byOpencodeId.values()) st.sseAbort?.abort();
-    const child = this.child;
-    this.child = null;
-    this.client = null;
     this.byOpencodeId.clear();
-    if (child && !child.killed) {
-      child.kill('SIGTERM');
-      const t = setTimeout(() => {
-        if (!child.killed) child.kill('SIGKILL');
-      }, 5_000);
-      t.unref();
-    }
+    await this.supervisor.dispose();
   }
 }
 
 // ─── helpers ──────────────────────────────────────────────────────────────────
 
-/** Extract the opencode sessionID an event belongs to, across event shapes.
- *  Most carry `properties.sessionID`; `message.part.updated` nests it under
- *  `properties.part.sessionID`. Returns null when the event has no session
- *  (the per-session loop then leaves it to dispatchEvent, which drops it). */
-function eventSessionId(ev: Event): string | null {
-  const props = (ev as { properties?: unknown }).properties;
-  if (!props || typeof props !== 'object') return null;
-  if (ev.type === 'message.part.updated') {
-    const part = (props as { part?: { sessionID?: string } }).part;
-    return part?.sessionID ?? null;
-  }
-  return (props as { sessionID?: string }).sessionID ?? null;
-}
-
 /** BooCoder model string "provider/model" → opencode's structured {providerID, modelID}. */
 function parseModel(model: string | undefined): { providerID: string; modelID: string } | undefined {
   if (!model || !model.trim()) return undefined;
@@ -705,138 +594,14 @@ function parseModel(model: string | undefined): { providerID: string; modelID: s
     return { providerID: trimmed.slice(0, idx), modelID: trimmed.slice(idx + 1) };
   }
   // No slash but non-empty → infer llama-swap (the only configured provider).
-  // Guard against bare '/' or trailing/leading slash.
   if (idx < 0 && trimmed.length > 0) {
     return { providerID: 'llama-swap', modelID: trimmed };
   }
   return undefined;
 }
 
-/** Ported verbatim from Paseo opencode-agent.ts: id → message-id fallback → null. */
-function resolvePartDedupeKey(part: { id: string; messageID: string }, type: string): string | null {
-  if (part.id.trim().length > 0) return `${type}:${part.id}`;
-  if (part.messageID.trim().length > 0) return `${type}:message:${part.messageID}`;
-  return null;
-}
-
-/** opencode ToolPart → ACP-shaped snapshot (reuses the existing persist/render path). */
-function toolPartToSnapshot(part: ToolPart): AcpToolSnapshot {
-  const state = part.state;
-  let rawInput: unknown;
-  let rawOutput: unknown;
-  let title: string | undefined;
-  if (state) {
-    if ('input' in state) rawInput = (state as { input?: unknown }).input;
-    if ('output' in state) rawOutput = (state as { output?: unknown }).output;
-    else if ('error' in state) rawOutput = (state as { error?: unknown }).error;
-    if ('title' in state) title = (state as { title?: string }).title;
-  }
-  return {
-    toolCallId: part.callID,
-    title: title ?? part.tool,
-    kind: null,
-    status: mapToolStatus(state?.status),
-    rawInput,
-    rawOutput,
-  };
-}
-
-function mapToolStatus(s: ToolState['status'] | undefined): ToolCallStatus | null {
-  switch (s) {
-    case 'pending':
-      return 'pending';
-    case 'running':
-      return 'in_progress';
-    case 'completed':
-      return 'completed';
-    case 'error':
-      return 'failed';
-    default:
-      return null;
-  }
-}
-
-/** Bind-probe an ephemeral port on loopback. */
-function freePort(): Promise<number> {
-  return new Promise((resolve, reject) => {
-    const srv = createServer();
-    srv.unref();
-    srv.on('error', reject);
-    srv.listen(0, '127.0.0.1', () => {
-      const addr = srv.address();
-      if (addr && typeof addr === 'object') {
-        const { port } = addr;
-        srv.close(() => resolve(port));
-      } else {
-        srv.close(() => reject(new Error('opencode-server: could not determine a free port')));
-      }
-    });
-  });
-}
-
-/** Resolve when the child prints the ready line; reject on timeout or early exit. */
-function waitForReady(child: ChildProcess, timeoutMs: number): Promise<void> {
-  return new Promise((resolve, reject) => {
-    let done = false;
-    let stderrBuf = '';
-
-    const finish = (err?: Error) => {
-      if (done) return;
-      done = true;
-      clearTimeout(timer);
-      child.stdout?.off('data', onOut);
-      child.stderr?.off('data', onErr);
-      child.off('exit', onExit);
-      if (err) reject(err);
-      else resolve();
-    };
-
-    const onOut = (buf: Buffer) => {
-      if (buf.toString().includes('opencode server listening on')) finish();
-    };
-    const onErr = (buf: Buffer) => {
-      stderrBuf += buf.toString();
-    };
-    const onExit = (code: number | null) =>
-      finish(new Error(`opencode serve exited before ready (code ${code}); stderr: ${stderrBuf.slice(-2000)}`));
-    const timer = setTimeout(
-      () => finish(new Error(`opencode serve not ready in ${timeoutMs}ms; stderr: ${stderrBuf.slice(-2000)}`)),
-      timeoutMs,
-    );
-
-    child.stdout?.on('data', onOut);
-    child.stderr?.on('data', onErr);
-    child.on('exit', onExit);
-  });
-}
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((r) => setTimeout(r, ms));
-}
-
-/** Strip opencode-dcp plugin tags that render as literal text in the UI. */
-function stripDcpTags(s: string): string {
-  return s.replace(/<dcp-message-id>[^<]*<\/dcp-message-id>/g, '');
-}
-
-function errMsg(e: unknown): string {
-  return e instanceof Error ? e.message : String(e);
-}
-
-function errToString(e: unknown): string {
-  if (e == null) return 'unknown error';
-  if (typeof e === 'string') return e;
-  if (e instanceof Error) return e.message;
-  try {
-    return JSON.stringify(e);
-  } catch {
-    return String(e);
-  }
-}
-
 /** Hash of stable config — detects model changes across sessions without
- *  invalidating on ephemeral state like the random server port (which changes
- *  every BooCoder restart). */
+ *  invalidating on ephemeral state like the random server port. */
 function sessionConfigHash(model: string): string {
   return createHash('sha256').update(`opencode_server|${model}`).digest('hex').slice(0, 16);
 }

apps/coder/src/services/backends/opencode-sse.ts

@@ -0,0 +1,181 @@
+/**
+ * Per-session SSE subscribe loop + reconnect/backoff + eventSessionId demux.
+ *
+ * Extracted (v2.7 audit reshape) from `OpenCodeServerBackend.startSessionEventLoop`
+ * / `runSessionEventLoop`. opencode scopes events by the `directory` query param, so
+ * each session runs its own dir-scoped stream and never drops a sibling's events.
+ *
+ * The loop is intentionally thin: it owns subscribe + the demux filter + reconnect
+ * timing only. Translating an event into turn side effects (watchdog, usage,
+ * settle) stays on the backend via the injected `dispatchEvent` / `reconcile`
+ * callbacks — `opencode-sse` knows nothing about turns or the DB.
+ *
+ * v2.7 concurrency hardening: the throw-driven reconnect path now backs off
+ * exponentially and trips a circuit-breaker (`onReconnectGiveUp`) after a bounded
+ * number of consecutive failures, instead of looping forever at a flat 1s. The
+ * HAPPY PATH is unchanged — a clean stream end (server still up) reconnects after
+ * `baseMs` (1s, as before) and resets the failure counter, so a long-lived session
+ * that re-subscribes normally never backs off.
+ */
+import type { FastifyBaseLogger } from 'fastify';
+import type { Event, OpencodeClient } from '@opencode-ai/sdk/v2/client';
+import type { AgentEvent } from '../agent-backend.js';
+import type { TurnResult } from '../agent-backend.js';
+import { eventSessionId, errMsg } from './opencode-event-map.js';
+
+export const SSE_RECONNECT_DELAY_MS = 1_000;
+
+/** One in-flight turn's emitter + completion settler. */
+export interface TurnState {
+  onEvent: (e: AgentEvent) => void;
+  settle: (r: TurnResult) => void;
+}
+
+/** Per-(opencode session) demux state. dedup sets scoped here, cleared per turn. */
+export interface SessionState {
+  boocodeSessionId: string;
+  agentSessionId: string;
+  /** Worktree directory for SDK `directory` routing; refreshed each turn from ctx. */
+  worktreePath: string;
+  /** dedup gate: `${type}:${id}` added on delta, deleted-and-tested on updated. Cleared at turn end. */
+  streamedPartKeys: Set<string>;
+  /** partID → 'text' | 'reasoning', so a delta with a non-'reasoning' field is still classed right. Cleared at turn end. */
+  partTypeById: Map<string, string>;
+  activeTurn: TurnState | null;
+  /** Inactivity backstop timer for the active turn; null when no turn in flight. */
+  watchdog: ReturnType<typeof setTimeout> | null;
+  /** Per-session SSE subscription handle. Non-null while the loop is running;
+   *  aborting it tears down the underlying fetch and exits the loop. */
+  sseAbort: AbortController | null;
+  /** F.1 post-abort orphan-terminal guard: swallow the one session.idle/error
+   *  opencode emits for an aborted turn so it can't settle the next turn. */
+  swallowNextTerminal: boolean;
+}
+
+// ─── reconnect backoff (pure) ────────────────────────────────────────────────
+
+export interface ReconnectPolicy {
+  /** First retry delay (and the steady-state clean-reconnect delay). */
+  baseMs: number;
+  /** Cap on the exponential delay. */
+  maxMs: number;
+  /** Consecutive failures tolerated before the breaker trips (give up). */
+  maxAttempts: number;
+}
+
+export const DEFAULT_RECONNECT_POLICY: ReconnectPolicy = {
+  baseMs: SSE_RECONNECT_DELAY_MS,
+  maxMs: 30_000,
+  maxAttempts: 6,
+};
+
+export type ReconnectDecision =
+  | { action: 'reconnect'; delayMs: number }
+  | { action: 'give-up' };
+
+/**
+ * Pure backoff decision after `failures` consecutive throwing reconnect attempts
+ * (1-based: the first failure passes `failures=1`). Returns an exponentially
+ * growing delay capped at `maxMs`, or `give-up` once the count exceeds
+ * `maxAttempts`. `failures=1` yields `baseMs`, so the very first retry matches the
+ * pre-hardening flat delay (happy-path-preserving).
+ */
+export function reconnectDecision(
+  failures: number,
+  policy: ReconnectPolicy = DEFAULT_RECONNECT_POLICY,
+): ReconnectDecision {
+  if (failures > policy.maxAttempts) return { action: 'give-up' };
+  const exp = policy.baseMs * 2 ** (failures - 1);
+  return { action: 'reconnect', delayMs: Math.min(policy.maxMs, exp) };
+}
+
+// ─── the loop ────────────────────────────────────────────────────────────────
+
+export interface SseLoopDeps {
+  /** Live iff the server is up (read each iteration so a crash stops the loop). */
+  isUp: () => boolean;
+  /** The current opencode client (null between server restarts). */
+  getClient: () => OpencodeClient | null;
+  /** Route one demuxed event to its turn (backend side effects live here). */
+  dispatchEvent: (ev: Event) => void;
+  /** Recover an idle/error lost during an SSE gap. Returns true if it settled. */
+  reconcile: (state: SessionState) => Promise<boolean>;
+  /** Circuit-breaker: called once the backoff gives up; fail the active turn. */
+  onReconnectGiveUp: (state: SessionState) => Promise<void> | void;
+  log: FastifyBaseLogger;
+  /** Injectable for tests; defaults to a real timer sleep. */
+  sleep?: (ms: number) => Promise<void>;
+  policy?: ReconnectPolicy;
+}
+
+function defaultSleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/** Per-session SSE subscription, scoped to the session's worktree directory.
+ *  Idempotent: a no-op if this session's loop is already running. */
+export function startSessionEventLoop(state: SessionState, deps: SseLoopDeps): void {
+  if (state.sseAbort) return; // already running
+  const abort = new AbortController();
+  state.sseAbort = abort;
+  void runSessionEventLoop(state, abort, deps).finally(() => {
+    // Only clear if this controller is still the live one (a later restart may
+    // have already installed a new one).
+    if (state.sseAbort === abort) state.sseAbort = null;
+  });
+}
+
+export async function runSessionEventLoop(
+  state: SessionState,
+  abort: AbortController,
+  deps: SseLoopDeps,
+): Promise<void> {
+  const signal = abort.signal;
+  const sleep = deps.sleep ?? defaultSleep;
+  const policy = deps.policy ?? DEFAULT_RECONNECT_POLICY;
+  let failures = 0;
+  while (deps.isUp() && deps.getClient() && !signal.aborted) {
+    const client = deps.getClient()!;
+    try {
+      // Re-read worktreePath each (re)subscribe so a directory refresh is picked
+      // up on reconnect. Passing `signal` lets close/dispose tear down a stream
+      // that's parked in `for await` between events.
+      const sub = await client.event.subscribe({ directory: state.worktreePath }, { signal });
+      for await (const ev of sub.stream) {
+        if (signal.aborted) break;
+        // Dir-scoped streams should only carry this session's events, but two
+        // sessions sharing a worktree (possible post-P1.5-b) each receive BOTH
+        // sessions' events — so drop anything that isn't ours, else the other
+        // session's deltas get processed twice (once per loop).
+        const sid = eventSessionId(ev);
+        if (sid != null && sid !== state.agentSessionId) continue;
+        deps.dispatchEvent(ev);
+      }
+      // Clean stream end — a healthy reconnect, NOT a failure: recover any lost
+      // terminal then re-subscribe at the base delay (pre-hardening behavior).
+      failures = 0;
+      if (deps.isUp() && !signal.aborted) {
+        await deps.reconcile(state); // recover an idle/error lost during the gap
+        await sleep(policy.baseMs);
+      }
+    } catch (err) {
+      if (!deps.isUp() || signal.aborted) break;
+      failures += 1;
+      const decision = reconnectDecision(failures, policy);
+      deps.log.warn(
+        { err: errMsg(err), agentSessionId: state.agentSessionId, failures, action: decision.action },
+        'opencode-server: session event loop error; reconnecting',
+      );
+      await deps.reconcile(state);
+      if (decision.action === 'give-up') {
+        deps.log.warn(
+          { agentSessionId: state.agentSessionId, failures },
+          'opencode-server: SSE reconnect gave up (circuit breaker) — failing active turn',
+        );
+        await deps.onReconnectGiveUp(state);
+        break;
+      }
+      await sleep(decision.delayMs);
+    }
+  }
+}

apps/coder/src/services/backends/pushable-iterable.ts

@@ -0,0 +1,96 @@
+/**
+ * claude-sdk-sessionstore #9 (Part 2) — a tiny PURE pushable async-iterable.
+ *
+ * The Claude Agent SDK's streaming-input mode wants `query({ prompt })` where
+ * `prompt` is an `AsyncIterable<SDKUserMessage>`. To keep ONE `query()` generator
+ * alive across many turns (the "warm" property), the backend feeds it ONE user
+ * message per `prompt()` turn through a queue that stays open between turns and is
+ * only closed at `closeSession`/`dispose`. This is that queue.
+ *
+ * Semantics (the bit worth unit-testing — push/close/iterate ordering):
+ *   - `push(v)` enqueues a value. If a consumer is parked in `await next()`, it's
+ *     handed the value immediately; otherwise the value buffers in FIFO order.
+ *   - The async iterator yields buffered/pushed values in push order, and PARKS
+ *     (never busy-loops) when the buffer is empty — so the SDK generator waits for
+ *     the next turn's message instead of seeing end-of-input.
+ *   - `close()` ends the iterable: any parked consumer resolves `{done:true}` and
+ *     all future `next()`s return done. Values pushed after close are dropped.
+ *   - It's single-consumer (one `query()` reads it); concurrent consumers are not a
+ *     supported shape and not needed here.
+ *
+ * No SDK import — generic over the pushed value `T` — so the pure push/close/iterate
+ * ordering is testable without the `SDKUserMessage` shape or a live binary.
+ */
+export interface Pushable<T> {
+  /** Enqueue a value (or hand it to a parked consumer). No-op after close. */
+  push(value: T): void;
+  /** End the iterable. Idempotent; a parked consumer resolves done. */
+  close(): void;
+  /** True once `close()` has been called. */
+  readonly closed: boolean;
+  /** The async-iterable the consumer (the SDK `query`) drives. */
+  readonly iterable: AsyncIterable<T>;
+}
+
+export function createPushable<T>(): Pushable<T> {
+  const buffer: T[] = [];
+  // A waiting consumer's resolver (null when none is parked). Single-consumer.
+  let pendingResolve: ((res: IteratorResult<T>) => void) | null = null;
+  let closed = false;
+
+  function push(value: T): void {
+    if (closed) return;
+    if (pendingResolve) {
+      const resolve = pendingResolve;
+      pendingResolve = null;
+      resolve({ value, done: false });
+      return;
+    }
+    buffer.push(value);
+  }
+
+  function close(): void {
+    if (closed) return;
+    closed = true;
+    if (pendingResolve) {
+      const resolve = pendingResolve;
+      pendingResolve = null;
+      resolve({ value: undefined, done: true });
+    }
+  }
+
+  const iterator: AsyncIterator<T> = {
+    next(): Promise<IteratorResult<T>> {
+      // Drain the buffer first (FIFO), regardless of close — buffered values
+      // pushed before close are still delivered.
+      if (buffer.length > 0) {
+        return Promise.resolve({ value: buffer.shift() as T, done: false });
+      }
+      if (closed) {
+        return Promise.resolve({ value: undefined, done: true });
+      }
+      // Park until the next push/close. Single-consumer: only one waiter at a time.
+      return new Promise<IteratorResult<T>>((resolve) => {
+        pendingResolve = resolve;
+      });
+    },
+    return(): Promise<IteratorResult<T>> {
+      // Consumer abandoned the loop (e.g. `break`) → close so a later push no-ops.
+      close();
+      return Promise.resolve({ value: undefined, done: true });
+    },
+  };
+
+  return {
+    push,
+    close,
+    get closed() {
+      return closed;
+    },
+    iterable: {
+      [Symbol.asyncIterator]() {
+        return iterator;
+      },
+    },
+  };
+}

apps/coder/src/services/backends/warm-acp-routing.ts

@@ -0,0 +1,41 @@
+/**
+ * v2.6 Phase 2 — warm-vs-one-shot routing predicate for goose/qwen.
+ *
+ * The warm ACP backend keys its persistent process + ACP session on (chat_id,
+ * agent) — exactly like the opencode-server backend. A task therefore only routes
+ * to the warm pool when it carries BOTH a `session_id` and a `chat_id`, i.e. it
+ * came from a real chat tab (the coder message route + skills route stamp both).
+ *
+ * Session-less creators — arena contestants, MCP-created tasks, generic
+ * `POST /api/tasks`, `new_task` — leave one or both null. Those keep the existing
+ * one-shot worktree-per-task ACP path (`runExternalAgent`), which spawns a fresh
+ * `goose acp` / `qwen --acp` per turn and never holds a warm process. Routing them
+ * warm would either synthesize a degenerate (null, agent) key or create a chat per
+ * arena contestant — neither is wanted, so they stay one-shot.
+ *
+ * Pure, so it's unit-testable; the dispatcher consumes it.
+ */
+const WARM_CAPABLE_AGENTS = new Set(['goose', 'qwen']);
+
+export function shouldUseWarmBackend(task: {
+  agent: string | null;
+  session_id: string | null;
+  chat_id: string | null;
+}): boolean {
+  if (!task.agent || !WARM_CAPABLE_AGENTS.has(task.agent)) return false;
+  return task.session_id != null && task.chat_id != null;
+}
+
+/**
+ * Map an ACP prompt `stopReason` to the backend's ok/fail contract (TurnResult.ok).
+ *
+ * ACP's `StopReason` union includes normal completions (`end_turn`, `max_tokens`,
+ * `max_turn_requests`) and abnormal ones (`refusal`, `cancelled`). Only the latter
+ * two read as a failed turn; everything else (including an undefined/absent reason,
+ * which we default to `end_turn`) is a successful completion. Pure so it's testable
+ * independently of the warm process.
+ */
+export function isTurnOkForStopReason(stopReason: string | null | undefined): boolean {
+  const reason = stopReason ?? 'end_turn';
+  return reason !== 'refusal' && reason !== 'cancelled';
+}

apps/coder/src/services/backends/warm-acp.ts

@@ -0,0 +1,389 @@
+/**
+ * v2.6 Phase 2 — WarmAcpBackend (goose, qwen).
+ *
+ * One persistent stdio process + ONE `ClientSideConnection` per (chat, agent),
+ * `initialize` + `session/new` done ONCE, reused across every turn — the warm
+ * analogue of the previous one-shot `acp-dispatch.ts` (which spawned/torn-down a
+ * fresh `goose acp` / `qwen --acp` per turn). Mirrors Paseo's `SpawnedACPProcess`.
+ *
+ * Implements the Phase 0 `AgentBackend` interface (same contract as
+ * `OpenCodeServerBackend`). Emits transport-agnostic `AgentEvent`s via the SHARED
+ * `mapSessionUpdate` (reused verbatim from the one-shot stack); the dispatcher maps
+ * those to WS frames + `persistExternalAgentTurn`, unchanged.
+ *
+ * Lifecycle decisions (design.md §2b / §10):
+ *   - **Child lifetime is the pool's, not a request's.** Spawned once; never tied
+ *     to a per-turn abort signal. Only the in-flight `prompt` gets `ctx.signal` —
+ *     abort = ACP `session/cancel`, NOT killing the child.
+ *   - **Per-turn abort** cancels the prompt on the warm connection so the SAME
+ *     process serves the next turn.
+ *   - **Crash** (child exit) marks `agent_sessions.status='crashed'` + logs; the
+ *     next `ensureSession` re-spawns + re-`session/new` (Phase 3 hardens auto-restart).
+ *   - **Resume across a process restart is NOT attempted in Phase 2.** goose ACP
+ *     advertises no `loadSession`/`session.resume`; qwen does, but cross-restart
+ *     resume is Phase 3. Within ONE live process the ACP session persists across
+ *     turns (the whole point of "warm"); a restart re-`session/new` (memory loss
+ *     across restart, accepted per §10). The agent's resume capabilities ARE
+ *     probed and logged for forward-compat.
+ *
+ * Each WarmAcpBackend instance owns exactly one (chat, agent) — the dispatcher
+ * pools them under `agentPool.register(chatId, agent, backend)`.
+ *
+ * SDK note (@agentclientprotocol/sdk@^0.22.1, cross-checked against the design's
+ * `^0.14` worry): the resume method is the STABLE `resumeSession` (`session/resume`,
+ * gated by `agentCapabilities.sessionCapabilities.resume`), NOT the `^0.14`
+ * `unstable_resumeSession`. `loadSession` is gated by `agentCapabilities.loadSession`.
+ */
+import { spawn, type ChildProcess } from 'node:child_process';
+import type { FastifyBaseLogger } from 'fastify';
+import { ClientSideConnection, type Client } from '@agentclientprotocol/sdk';
+import type { Sql } from '../../db.js';
+import { resolveLaunchSpec } from '../acp-spawn.js';
+import { isTurnOkForStopReason } from './warm-acp-routing.js';
+import { getResolvedRegistry, type ResolvedProviderDef } from '../provider-config-registry.js';
+import { createAcpNdJsonStream } from '../acp-stream.js';
+import { mapSessionUpdate } from '../acp-event-map.js';
+import { buildAcpClient } from '../acp-client.js';
+import { cancelPendingPermission } from '../permission-waiter.js';
+import { type AcpToolSnapshot, synthesizeCanceledSnapshots } from '../acp-tool-snapshot.js';
+import type {
+  AgentBackend,
+  AgentEvent,
+  AgentSessionHandle,
+  EnsureSessionOpts,
+  PromptCtx,
+  TurnResult,
+} from '../agent-backend.js';
+
+/** State for one in-flight turn (only one at a time per backend — turns serialize). */
+interface TurnState {
+  /** Per-turn task id, for routing permission prompts back to the UI. */
+  taskId: string | undefined;
+  /** BooCode session id for permission-waiter's broker frames. */
+  sessionId: string;
+  /** Per-turn mode id (autonomous-mode gate in permission-waiter). */
+  modeId: string | undefined;
+  onEvent: (e: AgentEvent) => void;
+  /** Tool-call snapshot accumulator for this turn — merge across tool_call_update. */
+  snapshots: Map<string, AcpToolSnapshot>;
+}
+
+export interface WarmAcpBackendDeps {
+  sql: Sql;
+  log: FastifyBaseLogger;
+  /** The (chat, agent) this backend serves — its pool identity + DB key. */
+  chatId: string;
+  agent: string;
+  /** Resolved binary for the agent (from available_agents.install_path), or null. */
+  installPath: string | null;
+  /** Optional override of the resolved registry def (defaults to a live lookup). */
+  resolved?: ResolvedProviderDef;
+}
+
+export class WarmAcpBackend implements AgentBackend {
+  readonly backend = 'acp_warm' as const;
+
+  private readonly sql: Sql;
+  private readonly log: FastifyBaseLogger;
+  private readonly chatId: string;
+  private readonly agent: string;
+  private readonly installPath: string | null;
+  private readonly resolvedOverride: ResolvedProviderDef | undefined;
+
+  private child: ChildProcess | null = null;
+  private connection: ClientSideConnection | null = null;
+  /** The single ACP session id for this warm process; null until session/new. */
+  private acpSessionId: string | null = null;
+  private up = false;
+  /** Idempotent spawn guard — one warm process per backend, started lazily. */
+  private starting: Promise<void> | null = null;
+  /** Resume capabilities probed at initialize, logged for forward-compat (Phase 3). */
+  private supportsLoadSession = false;
+  private supportsResumeSession = false;
+
+  /** The current in-flight turn; the Client closures read it. Null between turns. */
+  private activeTurn: TurnState | null = null;
+
+  constructor(deps: WarmAcpBackendDeps) {
+    this.sql = deps.sql;
+    this.log = deps.log;
+    this.chatId = deps.chatId;
+    this.agent = deps.agent;
+    this.installPath = deps.installPath;
+    this.resolvedOverride = deps.resolved;
+  }
+
+  /** §2: liveness for the health endpoint + dispatcher fallback decision. */
+  health(): 'up' | 'down' {
+    return this.up ? 'up' : 'down';
+  }
+
+  /** Phase 3: busy iff this backend's single session has an in-flight turn. The
+   *  pool reads this to skip idle/LRU eviction (never kill the child mid-prompt). */
+  isBusy(): boolean {
+    return this.activeTurn != null;
+  }
+
+  // ─── warm-process lifecycle (2.1 spawn + initialize + session/new ONCE) ───────
+
+  /** Lazy: spawn the warm process on first use. Idempotent — one process per backend. */
+  private ensureProcess(worktreePath: string): Promise<void> {
+    if (this.up && this.connection && this.acpSessionId) return Promise.resolve();
+    if (!this.starting) {
+      this.starting = this.startProcess(worktreePath).catch((err) => {
+        // Reset so a later ensureSession can retry the spawn after a failed start.
+        this.starting = null;
+        throw err;
+      });
+    }
+    return this.starting;
+  }
+
+  private async startProcess(worktreePath: string): Promise<void> {
+    const resolved = this.resolvedOverride ?? getResolvedRegistry().get(this.agent);
+    const spec = resolved ? resolveLaunchSpec(resolved, this.installPath) : null;
+    if (!spec) throw new Error(`warm-acp: agent '${this.agent}' does not support ACP (no launch spec)`);
+
+    this.log.info({ agent: this.agent, chatId: this.chatId, binary: spec.binary, worktreePath }, 'warm-acp: spawning warm process');
+    // Child lifetime is the pool's. NOT tied to any per-turn abort signal — only
+    // the in-flight prompt is cancellable (via ACP session/cancel in prompt()).
+    const child = spawn(spec.binary, spec.args, {
+      cwd: worktreePath,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env, ...spec.env },
+    });
+    this.child = child;
+
+    // 2.3: supervise the child; react to its exit, never let a request scope kill it.
+    child.on('exit', (code, signal) => {
+      this.up = false;
+      this.connection = null;
+      this.acpSessionId = null;
+      this.starting = null;
+      this.log.warn({ agent: this.agent, chatId: this.chatId, code, signal }, 'warm-acp: warm process exited — marking crashed (rebuild on next turn)');
+      void this.markCrashed();
+    });
+    // A spawn error (e.g. ENOENT) surfaces here, not as an exit.
+    child.on('error', (err) => {
+      this.up = false;
+      this.log.error({ agent: this.agent, chatId: this.chatId, err: errMsg(err) }, 'warm-acp: warm process error');
+    });
+
+    const stream = createAcpNdJsonStream(child);
+    const connection = new ClientSideConnection(() => this.buildClient(worktreePath), stream);
+
+    const init = await connection.initialize({
+      protocolVersion: 1,
+      clientInfo: { name: 'boocoder', version: '2.6.0' },
+      clientCapabilities: {},
+    });
+    const caps = init.agentCapabilities;
+    this.supportsLoadSession = caps?.loadSession === true;
+    this.supportsResumeSession = caps?.sessionCapabilities?.resume != null;
+
+    const session = await connection.newSession({ cwd: worktreePath, mcpServers: [] });
+    this.connection = connection;
+    this.acpSessionId = session.sessionId;
+    this.up = true;
+    this.log.info(
+      {
+        agent: this.agent,
+        chatId: this.chatId,
+        acpSessionId: session.sessionId,
+        loadSession: this.supportsLoadSession,
+        resumeSession: this.supportsResumeSession,
+      },
+      'warm-acp: warm session ready',
+    );
+  }
+
+  /** Build the ACP Client callbacks ONCE per connection (shared `buildAcpClient`).
+   *  `resolveTurn` reads `this.activeTurn` at each callback so events/permissions
+   *  route to the live turn — exactly the prior behavior. The warm session always
+   *  has a non-empty `sessionId`, so the shared `taskId && sessionId` permission
+   *  gate is equivalent to the old `turn?.taskId` gate. */
+  private buildClient(worktreePath: string): Client {
+    return buildAcpClient(worktreePath, () => {
+      const turn = this.activeTurn;
+      if (!turn) return null;
+      return {
+        taskId: turn.taskId,
+        sessionId: turn.sessionId,
+        modeId: turn.modeId,
+        agent: this.agent,
+        onSessionUpdate: (params) => {
+          for (const event of mapSessionUpdate(params, turn.snapshots)) turn.onEvent(event);
+        },
+      };
+    });
+  }
+
+  // ─── ensureSession: create-or-reuse the warm session (2.1) ───────────────────
+
+  async ensureSession(sessionId: string, opts: EnsureSessionOpts): Promise<AgentSessionHandle> {
+    await this.ensureProcess(opts.worktreePath);
+    if (!this.acpSessionId) throw new Error('warm-acp: session not ready after ensureProcess');
+
+    // P1.5-b: agent_sessions keys on (chat_id, agent). The ACP session id is the
+    // resume handle WITHIN the live process; across a process restart it's stale,
+    // so ensureProcess re-`session/new` and we upsert the fresh id here.
+    await this.sql`
+      INSERT INTO agent_sessions
+        (chat_id, session_id, worktree_id, agent, backend, agent_session_id, server_port, status, last_active_at)
+      VALUES
+        (${opts.chatId}, ${sessionId}, ${opts.worktreeId}, ${opts.agent}, 'acp_warm', ${this.acpSessionId}, NULL, 'active', clock_timestamp())
+      ON CONFLICT (chat_id, agent) DO UPDATE SET
+        session_id = EXCLUDED.session_id,
+        worktree_id = EXCLUDED.worktree_id,
+        backend = 'acp_warm',
+        agent_session_id = EXCLUDED.agent_session_id,
+        server_port = NULL,
+        status = 'active',
+        last_active_at = clock_timestamp()
+    `.catch((err) => {
+      this.log.warn({ err: errMsg(err), chatId: opts.chatId, agent: opts.agent }, 'warm-acp: agent_sessions upsert failed (non-fatal)');
+    });
+
+    return {
+      sessionId,
+      agent: opts.agent,
+      backend: 'acp_warm',
+      chatId: opts.chatId,
+      worktreeId: opts.worktreeId,
+      agentSessionId: this.acpSessionId,
+      serverPort: null,
+    };
+  }
+
+  // ─── prompt: one turn on the warm connection (2.2) ───────────────────────────
+
+  async prompt(handle: AgentSessionHandle, input: string, ctx: PromptCtx): Promise<TurnResult> {
+    // The warm process may have crashed between ensureSession and here, or this
+    // backend was rebuilt — re-establish before prompting.
+    await this.ensureProcess(ctx.worktreePath);
+    const connection = this.connection;
+    const acpSessionId = this.acpSessionId;
+    if (!connection || !acpSessionId) {
+      return { ok: false, error: 'warm-acp: no live ACP connection' };
+    }
+
+    // v2.7 busy-assert: one in-flight turn per warm session. The dispatcher
+    // serializes turns per (chat, agent), so this never fires in normal dispatch —
+    // but a second concurrent prompt would silently overwrite `activeTurn` and
+    // orphan the first turn, so reject instead.
+    if (this.activeTurn) {
+      return { ok: false, error: 'warm-acp: session already has an in-flight turn' };
+    }
+
+    const snapshots = new Map<string, AcpToolSnapshot>();
+    // taskId routes permission/elicitation prompts back to the UI. The dispatcher
+    // passes it (plus mode) on the per-turn PromptCtx; permission-waiter keys on it.
+    const turn: TurnState = {
+      taskId: ctx.taskId,
+      sessionId: handle.sessionId,
+      modeId: ctx.modeId,
+      onEvent: ctx.onEvent,
+      snapshots,
+    };
+    this.activeTurn = turn;
+
+    // Per-turn abort: cancel the in-flight prompt on the SAME connection — never
+    // kill the child (that's the pool's lifetime). On cancel we also synthesize
+    // 'canceled' updates for any still-running tool calls so the UI doesn't leave
+    // them spinning (mirrors AcpStreamContext.markAborted).
+    let aborted = false;
+    const onAbort = () => {
+      if (aborted) return;
+      aborted = true;
+      connection.cancel({ sessionId: acpSessionId }).catch(() => {});
+      if (ctx.taskId) cancelPendingPermission(ctx.taskId);
+      for (const snap of synthesizeCanceledSnapshots(snapshots.values())) {
+        snapshots.set(snap.toolCallId, snap);
+        ctx.onEvent({ type: 'tool_update', toolCall: snap });
+      }
+    };
+
+    if (ctx.signal.aborted) {
+      this.activeTurn = null;
+      return { ok: false, error: 'aborted' };
+    }
+    ctx.signal.addEventListener('abort', onAbort, { once: true });
+
+    try {
+      const result = await connection.prompt({
+        sessionId: acpSessionId,
+        prompt: [{ type: 'text', text: input }],
+      });
+      if (aborted) return { ok: false, error: 'aborted' };
+      const stopReason = result.stopReason ?? 'end_turn';
+      return isTurnOkForStopReason(stopReason)
+        ? { ok: true }
+        : { ok: false, error: `stop_reason: ${stopReason}` };
+    } catch (err) {
+      if (aborted) return { ok: false, error: 'aborted' };
+      return { ok: false, error: errMsg(err) };
+    } finally {
+      ctx.signal.removeEventListener('abort', onAbort);
+      this.activeTurn = null;
+      await this.sql`
+        UPDATE agent_sessions SET status = 'idle', last_active_at = clock_timestamp()
+        WHERE chat_id = ${this.chatId} AND agent = ${this.agent}
+      `.catch(() => {});
+    }
+  }
+
+  // ─── teardown ────────────────────────────────────────────────────────────────
+
+  async closeSession(handle: AgentSessionHandle): Promise<void> {
+    // Gracefully close the ACP session if the agent supports it; then kill the child.
+    if (this.connection && this.acpSessionId) {
+      await this.connection.closeSession({ sessionId: this.acpSessionId }).catch(() => {});
+    }
+    await this.killChild();
+    await this.sql`
+      UPDATE agent_sessions SET status = 'closed'
+      WHERE chat_id = ${handle.chatId} AND agent = ${handle.agent}
+    `.catch(() => {});
+  }
+
+  async dispose(): Promise<void> {
+    this.up = false;
+    this.activeTurn = null;
+    if (this.connection && this.acpSessionId) {
+      await this.connection.closeSession({ sessionId: this.acpSessionId }).catch(() => {});
+    }
+    await this.killChild();
+    this.connection = null;
+    this.acpSessionId = null;
+    this.starting = null;
+  }
+
+  private async killChild(): Promise<void> {
+    const child = this.child;
+    this.child = null;
+    if (!child || child.killed) return;
+    child.kill('SIGTERM');
+    await new Promise<void>((resolve) => {
+      const t = setTimeout(() => {
+        if (!child.killed) child.kill('SIGKILL');
+        resolve();
+      }, 5_000);
+      t.unref?.();
+      child.once('close', () => {
+        clearTimeout(t);
+        resolve();
+      });
+    });
+  }
+
+  private async markCrashed(): Promise<void> {
+    await this.sql`
+      UPDATE agent_sessions SET status = 'crashed'
+      WHERE chat_id = ${this.chatId} AND agent = ${this.agent}
+    `.catch(() => {});
+  }
+}
+
+function errMsg(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}

apps/coder/src/services/checkpoints.ts

@@ -0,0 +1,306 @@
+/**
+ * write-edit-robustness #4 — worktree checkpoints.
+ *
+ * External agents (opencode / goose / qwen / claude) write DIRECTLY into the
+ * shared session worktree (`/tmp/booworktrees/sess-<id>`); BooCode's own `rewind`
+ * only reverses `pending_changes` against the project root, so it has zero coverage
+ * there. A checkpoint is a pre-turn shadow-commit of the worktree tree (tracked +
+ * untracked) captured WITHOUT touching the real index/working tree, stored in a
+ * private GC-safe ref. `restoreCheckpoint` rewinds the worktree to that commit,
+ * trims the transcript from the anchor message forward, and resets the agent
+ * backend so the next turn re-establishes a fresh context consistent with the
+ * restored files.
+ *
+ * All git goes through hostExec + shellEscape (BooCoder runs on the host; the
+ * worktrees live on the host fs). Checkpoint CREATION is best-effort: a failure
+ * logs and returns null — it must NEVER throw into the dispatch turn.
+ */
+import { randomUUID } from 'node:crypto';
+import type { FastifyBaseLogger } from 'fastify';
+import type { Sql } from '../db.js';
+import { hostExec } from './host-exec.js';
+import { agentPool, OPENCODE_POOL_KEY } from './agent-pool.js';
+import type { AgentSessionHandle } from './agent-backend.js';
+
+/** Minimal shell escape for paths/refs (single-quote wrapping). Mirrors worktrees.ts. */
+function shellEscape(s: string): string {
+  return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+
+/**
+ * Pure builder for the shadow-commit command. Captures tracked + untracked files
+ * in the worktree into a temp index (so the real index/working tree is untouched),
+ * writes a tree, commits it parented on HEAD, and parks the commit under a private
+ * ref `refs/boocode/checkpoints/<id>` so git's GC never reclaims it. Prints ONLY
+ * the resulting SHA on stdout (the trailing `printf '%s'`), so the caller parses
+ * stdout.trim() directly.
+ *
+ * `id` is the row UUID (minted before the ref so the ref name matches the row).
+ * Both the worktree path and the id are shell-escaped.
+ */
+export function buildShadowCommitCommand(worktreePath: string, id: string): string {
+  const wt = shellEscape(worktreePath);
+  const ref = shellEscape(`refs/boocode/checkpoints/${id}`);
+  return (
+    `cd ${wt} && TMP=$(mktemp) && GIT_INDEX_FILE="$TMP" git read-tree HEAD ` +
+    `&& GIT_INDEX_FILE="$TMP" git add -A ` +
+    `&& TREE=$(GIT_INDEX_FILE="$TMP" git write-tree) ` +
+    `&& SHA=$(git commit-tree "$TREE" -p HEAD -m "boocode checkpoint") ` +
+    `&& git update-ref ${ref} "$SHA" && rm -f "$TMP" && printf '%s' "$SHA"`
+  );
+}
+
+export interface CreateCheckpointArgs {
+  chatId: string;
+  sessionId: string | null;
+  worktreeId: string | null;
+  worktreePath: string;
+  messageId: string | null;
+  label?: string | null;
+}
+
+/**
+ * Capture a pre-turn checkpoint of the session worktree. Best-effort: returns the
+ * inserted row's { id, commit_sha } on success, or null on any failure (the turn
+ * proceeds either way — a missing checkpoint just means no restore point for that
+ * turn). NEVER throws.
+ *
+ * The id is minted up front so the git ref name (`refs/boocode/checkpoints/<id>`)
+ * matches the DB row id, keeping ref and row in lockstep.
+ */
+export async function createCheckpoint(
+  sql: Sql,
+  args: CreateCheckpointArgs,
+  opts?: { signal?: AbortSignal; log?: FastifyBaseLogger },
+): Promise<{ id: string; commit_sha: string } | null> {
+  const id = randomUUID();
+  try {
+    const cmd = buildShadowCommitCommand(args.worktreePath, id);
+    const res = await hostExec(cmd, { signal: opts?.signal, timeoutMs: 30_000 });
+    if (res.exitCode !== 0) {
+      opts?.log?.warn(
+        { chatId: args.chatId, worktreePath: args.worktreePath, stderr: res.stderr.trim().slice(0, 500) },
+        'checkpoint: shadow-commit failed (turn proceeds without a checkpoint)',
+      );
+      return null;
+    }
+    const commitSha = res.stdout.trim();
+    if (!commitSha) {
+      opts?.log?.warn(
+        { chatId: args.chatId, worktreePath: args.worktreePath },
+        'checkpoint: shadow-commit produced no SHA (turn proceeds)',
+      );
+      return null;
+    }
+
+    await sql`
+      INSERT INTO checkpoints (id, chat_id, session_id, worktree_id, message_id, commit_sha, label)
+      VALUES (${id}, ${args.chatId}, ${args.sessionId}, ${args.worktreeId}, ${args.messageId}, ${commitSha}, ${args.label ?? null})
+    `;
+    opts?.log?.info({ checkpointId: id, chatId: args.chatId, commitSha }, 'checkpoint: created');
+    return { id, commit_sha: commitSha };
+  } catch (err) {
+    opts?.log?.warn(
+      { chatId: args.chatId, err: err instanceof Error ? err.message : String(err) },
+      'checkpoint: create threw (turn proceeds without a checkpoint)',
+    );
+    return null;
+  }
+}
+
+/** Error the route maps to a 404 when the checkpoint can't be resolved / scoped. */
+export class CheckpointNotFoundError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'CheckpointNotFoundError';
+  }
+}
+
+export interface RestoreCheckpointResult {
+  checkpoint_id: string;
+  messages_deleted: number;
+  worktree_reset: boolean;
+  backend_reset: boolean;
+}
+
+export interface RestoreCheckpointOpts {
+  signal?: AbortSignal;
+  log?: FastifyBaseLogger;
+  /** If set, the checkpoint MUST belong to this session (route scope guard). */
+  sessionId?: string;
+}
+
+interface CheckpointRow {
+  id: string;
+  chat_id: string;
+  session_id: string | null;
+  worktree_id: string | null;
+  message_id: string | null;
+  commit_sha: string;
+  created_at: Date;
+}
+
+/**
+ * Restore a checkpoint: rewind its worktree to the shadow commit, trim the
+ * transcript from the anchor message forward, reset the backend session, and drop
+ * now-orphaned later checkpoints. Throws CheckpointNotFoundError when the
+ * checkpoint is missing or not in the requested session (route → 404).
+ */
+export async function restoreCheckpoint(
+  sql: Sql,
+  checkpointId: string,
+  opts?: RestoreCheckpointOpts,
+): Promise<RestoreCheckpointResult> {
+  // 1. Resolve the checkpoint.
+  const [cp] = await sql<CheckpointRow[]>`
+    SELECT id, chat_id, session_id, worktree_id, message_id, commit_sha, created_at
+    FROM checkpoints WHERE id = ${checkpointId}
+  `;
+  if (!cp) {
+    throw new CheckpointNotFoundError('checkpoint not found');
+  }
+  // Authorization scope (fail-safe): the checkpoint's chat must belong to the
+  // requested session. cp.session_id is a denormalized hint that may be null, so
+  // gating on it directly fails open — resolve the owning session via chats
+  // (authoritative; chat_id is NOT NULL) and deny on any mismatch or missing row.
+  if (opts?.sessionId) {
+    const [owner] = await sql<{ session_id: string | null }[]>`
+      SELECT session_id FROM chats WHERE id = ${cp.chat_id}
+    `;
+    if (!owner || owner.session_id !== opts.sessionId) {
+      throw new CheckpointNotFoundError('checkpoint not in session');
+    }
+  }
+
+  // 2. Resolve the worktree path (by worktree_id, else the session's active one).
+  let worktreePath: string | null = null;
+  if (cp.worktree_id) {
+    const [wt] = await sql<{ path: string }[]>`
+      SELECT path FROM worktrees WHERE id = ${cp.worktree_id}
+    `;
+    worktreePath = wt?.path ?? null;
+  }
+  if (!worktreePath) {
+    const sid = cp.session_id ?? opts?.sessionId ?? null;
+    if (sid) {
+      const [wt] = await sql<{ path: string }[]>`
+        SELECT path FROM worktrees WHERE session_id = ${sid} AND status = 'active' LIMIT 1
+      `;
+      worktreePath = wt?.path ?? null;
+    }
+  }
+
+  // 3. Worktree reset — hard-reset to the shadow commit, then clean untracked.
+  let worktreeReset = false;
+  if (worktreePath) {
+    const resetRes = await hostExec(
+      `git -C ${shellEscape(worktreePath)} reset --hard ${shellEscape(cp.commit_sha)}`,
+      { signal: opts?.signal, timeoutMs: 30_000 },
+    ).catch((err) => {
+      opts?.log?.warn(
+        { checkpointId, err: err instanceof Error ? err.message : String(err) },
+        'checkpoint restore: reset --hard threw',
+      );
+      return null;
+    });
+    if (resetRes && resetRes.exitCode === 0) {
+      const cleanRes = await hostExec(
+        `git -C ${shellEscape(worktreePath)} clean -fd`,
+        { signal: opts?.signal, timeoutMs: 30_000 },
+      ).catch(() => null);
+      worktreeReset = cleanRes != null && cleanRes.exitCode === 0;
+      if (!worktreeReset) {
+        opts?.log?.warn({ checkpointId, worktreePath }, 'checkpoint restore: clean -fd did not succeed');
+      }
+    } else {
+      opts?.log?.warn(
+        { checkpointId, worktreePath, stderr: resetRes?.stderr?.trim()?.slice(0, 500) },
+        'checkpoint restore: reset --hard did not succeed',
+      );
+    }
+  } else {
+    opts?.log?.warn({ checkpointId }, 'checkpoint restore: no worktree path resolved (files not reset)');
+  }
+
+  // 4. Trim the transcript from the anchor message forward. message_parts FK to
+  //    messages is ON DELETE CASCADE (apps/server schema.sql:49), so parts are
+  //    removed with their messages — no explicit parts delete needed.
+  let messagesDeleted = 0;
+  if (cp.message_id) {
+    const deleted = await sql<{ id: string }[]>`
+      DELETE FROM messages
+      WHERE chat_id = ${cp.chat_id}
+        AND created_at >= (SELECT created_at FROM messages WHERE id = ${cp.message_id})
+      RETURNING id
+    `;
+    messagesDeleted = deleted.length;
+  }
+
+  // 5. Backend reset — mark the chat's agent sessions crashed so the next turn
+  //    re-establishes a fresh backend, and evict the live pool session(s) for this
+  //    (chat, agent). Warm backends hold context server-side with no partial
+  //    rewind, so a full reset is the only consistent option (proposal §4).
+  const agentRows = await sql<{ agent: string; backend: string; agent_session_id: string | null; session_id: string | null; worktree_id: string | null }[]>`
+    SELECT agent, backend, agent_session_id, session_id, worktree_id
+    FROM agent_sessions WHERE chat_id = ${cp.chat_id}
+  `;
+  await sql`
+    UPDATE agent_sessions SET status = 'crashed' WHERE chat_id = ${cp.chat_id}
+  `.catch(() => {});
+
+  let backendReset = false;
+  try {
+    // opencode runs on the SHARED server (keyed on a sentinel, not the chat) — close
+    // just this chat's session(s) on it, mirroring the lifecycle close-hook.
+    const ocBackend = agentPool.peek(OPENCODE_POOL_KEY, 'opencode');
+    if (ocBackend) {
+      for (const row of agentRows) {
+        if (row.backend !== 'opencode_server' || !row.agent_session_id) continue;
+        const handle: AgentSessionHandle = {
+          sessionId: row.session_id ?? '',
+          agent: row.agent,
+          backend: 'opencode_server',
+          chatId: cp.chat_id,
+          worktreeId: row.worktree_id ?? '',
+          agentSessionId: row.agent_session_id,
+          serverPort: null,
+        };
+        await ocBackend.closeSession(handle).catch((err) => {
+          opts?.log?.warn(
+            { checkpointId, err: err instanceof Error ? err.message : String(err) },
+            'checkpoint restore: opencode closeSession threw',
+          );
+        });
+      }
+    }
+    // Warm-ACP backends are pooled under the chat id — dispose them (kills the
+    // goose/qwen child). closeChat skips busy backends (a live turn isn't torn down).
+    const disposed = await agentPool.closeChat(cp.chat_id);
+    backendReset = true;
+    opts?.log?.info({ checkpointId, chatId: cp.chat_id, disposed }, 'checkpoint restore: backend reset');
+  } catch (err) {
+    opts?.log?.warn(
+      { checkpointId, err: err instanceof Error ? err.message : String(err) },
+      'checkpoint restore: backend reset threw',
+    );
+  }
+
+  // 6. Drop now-orphaned later checkpoints for this chat (their anchor messages were
+  //    just trimmed). Compare `created_at` SERVER-SIDE via a subquery (NOT the JS
+  //    Date round-trip, which truncates the stored microsecond precision to ms and
+  //    would make this checkpoint delete ITSELF), and exclude this checkpoint's own
+  //    id so it always survives — letting the user re-restore to it.
+  await sql`
+    DELETE FROM checkpoints
+    WHERE chat_id = ${cp.chat_id}
+      AND id <> ${cp.id}
+      AND created_at > (SELECT created_at FROM checkpoints WHERE id = ${cp.id})
+  `.catch(() => {});
+
+  return {
+    checkpoint_id: checkpointId,
+    messages_deleted: messagesDeleted,
+    worktree_reset: worktreeReset,
+    backend_reset: backendReset,
+  };
+}

apps/coder/src/services/dispatcher.ts

@@ -4,6 +4,7 @@ import type { Broker } from '@boocode/server/broker';
 import type { WsFrame } from '@boocode/server/ws-frames';
 import type { Config } from '../config.js';
 import { createWorktree, diffWorktree, cleanupWorktree, ensureSessionWorktree } from './worktrees.js';
+import { createCheckpoint } from './checkpoints.js';
 import { makeDcpStreamStripper } from './dcp-strip.js';
 import { dispatchViaAcp } from './acp-dispatch.js';
 import { getResolvedRegistry } from './provider-config-registry.js';
@@ -12,9 +13,15 @@ import { clearTaskCommands, setTaskCommands } from './agent-commands-cache.js';
 import { getManifestCommands } from './provider-commands.js';
 import { persistExternalAgentTurn } from './agent-turn-persist.js';
 import { snapshotToWireToolCall, type AcpToolSnapshot } from './acp-tool-snapshot.js';
-import { agentPool } from './agent-pool.js';
+import { agentPool, OPENCODE_POOL_KEY } from './agent-pool.js';
 import { OpenCodeServerBackend } from './backends/opencode-server.js';
+import { WarmAcpBackend } from './backends/warm-acp.js';
+import { ClaudeSdkBackend } from './backends/claude-sdk.js';
+import { shouldUseWarmBackend } from './backends/warm-acp-routing.js';
+import { shouldUseClaudeSdk } from './backends/claude-sdk-routing.js';
 import type { AgentBackend, AgentEvent } from './agent-backend.js';
+import { publishAgentStatus } from './agent-status-publish.js';
+import type { AgentStatus } from './normalize-agent-status.js';
 
 interface InferenceRunner {
   enqueue: (sessionId: string, chatId: string, assistantId: string, user: string) => void;
@@ -61,6 +68,21 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
     return task.session_id ?? `task:${task.id}`;
   }
 
+  // agent-status-normalize (#10): publish a normalized per-(chat,agent) status on
+  // the session channel. Every external-agent path (warm-acp / opencode / claude-sdk /
+  // pty one-shot) reports `working` at turn start, `idle` on clean completion, and
+  // `error` on the failure path through this single helper so the four paths stay
+  // DRY and consistent. Best-effort — publishAgentStatus never throws.
+  function emitAgentStatus(
+    sessionId: string,
+    chatId: string,
+    agent: string,
+    status: AgentStatus,
+    reason: string,
+  ): void {
+    publishAgentStatus(broker.publishFrame, sessionId, chatId, agent, status, reason);
+  }
+
   async function poll(): Promise<void> {
     // `polling` serializes poll() execution itself (timer + NOTIFY can fire
     // concurrently) so we never double-select a task. It does NOT serialize task
@@ -121,10 +143,21 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         SELECT name, supports_acp, install_path FROM available_agents WHERE name = ${task.agent}
       `;
       if (agentRow) {
-        // v2.6 (1.7): opencode routes to the warm pool backend; every other
-        // external agent keeps the existing one-shot ACP/PTY path untouched.
+        // v2.6 (1.7): opencode routes to its warm HTTP-server backend.
+        // v2.6 Phase 2 (2.4): goose/qwen route to the warm ACP backend WHEN the
+        // task came from a real chat tab (session_id + chat_id) — shouldUseWarmBackend.
+        // Session-less creators (arena, MCP, new_task, generic /api/tasks) keep the
+        // existing one-shot worktree-per-task ACP/PTY path untouched.
         if (task.agent === 'opencode') {
           await runOpenCodeServerTask(task, agentRow.install_path);
+        } else if (shouldUseClaudeSdk(task)) {
+          // claude-sdk-sessionstore #9 (Part 2): env-flagged (CLAUDE_SDK_BACKEND, default
+          // OFF) warm Claude-SDK backend for chat-tab claude tasks. When the flag is off
+          // (production default) this predicate returns false and claude falls through to
+          // the UNCHANGED one-shot PTY runExternalAgent path below.
+          await runClaudeSdkTask(task, agentRow.install_path);
+        } else if (shouldUseWarmBackend(task)) {
+          await runWarmAcpTask(task, agentRow.install_path);
         } else {
           await runExternalAgent(task, agentRow.supports_acp, agentRow.install_path);
         }
@@ -180,8 +213,8 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         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())
+        INSERT INTO messages (session_id, chat_id, role, content, status, model, created_at)
+        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', ${task.model}, clock_timestamp())
         RETURNING id
       `;
       const assistantId = assistantMsg!.id;
@@ -282,6 +315,11 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
     // Create an abort controller for this task
     const ac = new AbortController();
 
+    // #10: hoisted above the try so the catch block can report `error` status with
+    // the (chat, agent) key. Empty until resolved below; guarded before use.
+    let sessionId = '';
+    let chatId = '';
+
     try {
       // Mark running
       await sql`
@@ -290,9 +328,6 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         WHERE id = ${taskId}
       `;
 
-      let sessionId: string;
-      let chatId: string;
-
       if (task.session_id) {
         sessionId = task.session_id;
         const chats = await sql<{ id: string }[]>`
@@ -345,12 +380,22 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
       let acpReasoning = '';
 
       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())
+        INSERT INTO messages (session_id, chat_id, role, content, status, model, created_at)
+        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', ${task.model}, clock_timestamp())
         RETURNING id
       `;
       const assistantId = assistantMsg!.id;
 
+      // write-edit-robustness #4: pre-turn worktree checkpoint (best-effort; a
+      // failure logs and never breaks dispatch). This path uses a per-task worktree
+      // (createWorktree, not the session worktree), so there's no worktrees-table id
+      // — pass null for worktreeId, the path is enough for restore's reset.
+      await createCheckpoint(
+        sql,
+        { chatId, sessionId, worktreeId: null, worktreePath, messageId: assistantId },
+        { signal: ac.signal, log },
+      ).catch(() => null);
+
       broker.publishFrame(sessionId, {
         type: 'message_started',
         message_id: assistantId,
@@ -358,6 +403,9 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         role: 'assistant',
       } as WsFrame);
 
+      // #10: external-agent turn begins.
+      emitAgentStatus(sessionId, chatId, agent, 'working', 'turn_start');
+
       const manifestCommands = getManifestCommands(agent);
       if (manifestCommands.length > 0) {
         setTaskCommands(taskId, manifestCommands);
@@ -392,6 +440,52 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         outputSummary = result.output.slice(0, 500);
         await persistExternalAgentTurn(sql, assistantId, result.toolSnapshots, acpReasoning);
       } else {
+        // v#7 (stream-json): claude + qwen run with --output-format stream-json.
+        // Parse the NDJSON live in pty-dispatch and forward AgentEvents here so we
+        // publish the SAME live frames the warm-ACP / opencode paths emit (text,
+        // reasoning, tool) and persist structured parts. Accumulate for the final
+        // message content + persistence; fall back to the opaque stdout slice when
+        // nothing parsed (agent ran without the flag, or crashed before emitting).
+        const ptyTextChunks: string[] = [];
+        const ptyReasoningChunks: string[] = [];
+        const ptyToolSnaps = new Map<string, AcpToolSnapshot>();
+
+        const onPtyEvent = (e: AgentEvent): void => {
+          switch (e.type) {
+            case 'text':
+              ptyTextChunks.push(e.text);
+              broker.publishFrame(sessionId, {
+                type: 'delta',
+                message_id: assistantId,
+                chat_id: chatId,
+                content: e.text,
+              } as WsFrame);
+              break;
+            case 'reasoning':
+              ptyReasoningChunks.push(e.text);
+              broker.publishFrame(sessionId, {
+                type: 'reasoning_delta',
+                message_id: assistantId,
+                chat_id: chatId,
+                content: e.text,
+              } as WsFrame);
+              break;
+            case 'tool_call':
+            case 'tool_update':
+              ptyToolSnaps.set(e.toolCall.toolCallId, e.toolCall);
+              broker.publishFrame(sessionId, {
+                type: 'tool_call',
+                message_id: assistantId,
+                chat_id: chatId,
+                tool_call: snapshotToWireToolCall(e.toolCall),
+              } as WsFrame);
+              break;
+            case 'commands':
+              // stream-json carries no commands today; ignore if it ever does.
+              break;
+          }
+        };
+
         const result = await dispatchViaPty({
           agent,
           task: task.input,
@@ -402,17 +496,33 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
           thinkingOptionId: task.thinking_option_id ?? undefined,
           signal: ac.signal,
           log,
+          onEvent: onPtyEvent,
         });
-        assistantContent = (result.stdout || result.stderr || '(no output)').slice(0, 50_000);
-        outputSummary = (result.stdout || result.stderr).slice(0, 500);
 
-        if (assistantContent) {
-          broker.publishFrame(sessionId, {
-            type: 'delta',
-            message_id: assistantId,
-            chat_id: chatId,
-            content: assistantContent,
-          } as WsFrame);
+        if (result.streamed) {
+          assistantContent = ptyTextChunks.join('').slice(0, 50_000);
+          // stream-json text can be empty for a tool-only turn — surface stderr or a
+          // placeholder so the message row isn't blank.
+          if (!assistantContent) {
+            assistantContent = (result.stderr || '(no text output)').slice(0, 50_000);
+          }
+          outputSummary = (ptyTextChunks.join('') || result.stderr).slice(0, 500);
+          acpReasoning = ptyReasoningChunks.join('').slice(0, 200_000);
+          await persistExternalAgentTurn(sql, assistantId, [...ptyToolSnaps.values()], acpReasoning);
+        } else {
+          // Fallback: agent produced no parseable NDJSON (ran without the flag, or
+          // crashed). Preserve today's opaque stdout-slice + single delta behavior.
+          assistantContent = (result.stdout || result.stderr || '(no output)').slice(0, 50_000);
+          outputSummary = (result.stdout || result.stderr).slice(0, 500);
+
+          if (assistantContent) {
+            broker.publishFrame(sessionId, {
+              type: 'delta',
+              message_id: assistantId,
+              chat_id: chatId,
+              content: assistantContent,
+            } as WsFrame);
+          }
         }
       }
 
@@ -426,6 +536,7 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         type: 'message_complete',
         message_id: assistantId,
         chat_id: chatId,
+        model: task.model,
       } as WsFrame);
 
       if (stopping) {
@@ -470,6 +581,8 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         WHERE id = ${taskId}
       `;
       log.info({ taskId, agent, costTokens: extCostTokens }, 'dispatcher: task completed (external)');
+      // #10: external-agent turn completed cleanly.
+      emitAgentStatus(sessionId, chatId, agent, 'idle', 'turn_complete');
       clearTaskCommands(taskId);
 
     } catch (err) {
@@ -482,6 +595,11 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         WHERE id = ${taskId}
       `.catch(() => {});
 
+      // #10: external-agent turn failed/crashed. chatId may be unbound if the throw
+      // preceded its assignment — guard so the status publish never masks the real
+      // error.
+      if (chatId) emitAgentStatus(sessionId, chatId, agent, 'error', 'failed');
+
       // Best-effort cleanup
       await cleanupWorktree(projectPath, taskId);
       clearTaskCommands(taskId);
@@ -492,9 +610,8 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
 
   // OpenCode runs ONE server per BooCoder process, shared across all sessions
   // (the backend multiplexes sessions internally), so it's pooled under a fixed
-  // key rather than per-session. Warm ACP backends (Phase 2) will be per-session.
-  const OPENCODE_POOL_KEY = '__opencode_server__';
-
+  // key (OPENCODE_POOL_KEY, shared with the lifecycle close-hook) rather than
+  // per-session. Warm ACP backends (Phase 2) are per (chat, agent).
   function getOpenCodeBackend(installPath: string | null): AgentBackend {
     let backend = agentPool.get(OPENCODE_POOL_KEY, 'opencode');
     if (!backend) {
@@ -537,6 +654,10 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
 
     const ac = new AbortController();
 
+    // #10: hoisted so the catch can report `error` with the (chat, agent) key.
+    let sessionId = '';
+    let chatId = '';
+
     try {
       // execution_path = 'acp' — the schema CHECK has no 'opencode_server' value
       // (schema is frozen at Phase 0); the warm-vs-one-shot distinction lives in
@@ -553,8 +674,6 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
       // it directly. Session-less creators (arena, MCP, new_task, generic
       // /api/tasks) leave it null; fall back to resolving/creating a real chat so
       // ensureSession never receives a degenerate (null, agent) key.
-      let sessionId: string;
-      let chatId: string;
       if (task.chat_id && task.session_id) {
         sessionId = task.session_id;
         chatId = task.chat_id;
@@ -605,12 +724,21 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
       log.info({ taskId, worktreePath }, 'dispatcher: session worktree ready');
 
       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())
+        INSERT INTO messages (session_id, chat_id, role, content, status, model, created_at)
+        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', ${task.model}, clock_timestamp())
         RETURNING id
       `;
       const assistantId = assistantMsg!.id;
 
+      // write-edit-robustness #4: pre-turn checkpoint of the persistent session
+      // worktree (best-effort; never breaks dispatch). worktreeId comes from the
+      // worktrees table (ensureSessionWorktree above).
+      await createCheckpoint(
+        sql,
+        { chatId, sessionId, worktreeId, worktreePath, messageId: assistantId },
+        { signal: ac.signal, log },
+      ).catch(() => null);
+
       broker.publishFrame(sessionId, {
         type: 'message_started',
         message_id: assistantId,
@@ -618,6 +746,9 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         role: 'assistant',
       } as WsFrame);
 
+      // #10: opencode-server turn begins.
+      emitAgentStatus(sessionId, chatId, agent, 'working', 'turn_start');
+
       const manifestCommands = getManifestCommands(agent);
       if (manifestCommands.length > 0) {
         setTaskCommands(taskId, manifestCommands);
@@ -703,6 +834,9 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         signal: ac.signal,
         onEvent,
       });
+      // Phase 3: keep the pooled backend's slot warm across this (possibly long)
+      // turn so the idle sweep measures from turn END, not start.
+      agentPool.touch(OPENCODE_POOL_KEY, agent);
 
       // Flush any text held back mid-tag at stream end (complete tags stripped).
       const dcpTail = dcp.flush();
@@ -731,6 +865,7 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         type: 'message_complete',
         message_id: assistantId,
         chat_id: chatId,
+        model: task.model,
       } as WsFrame);
 
       if (stopping) {
@@ -774,6 +909,14 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         WHERE id = ${taskId}
       `;
       log.info({ taskId, agent, finalState, costTokens: extCostTokens }, 'dispatcher: task finished (opencode server)');
+      // #10: clean completion → idle; backend-reported failure → error.
+      emitAgentStatus(
+        sessionId,
+        chatId,
+        agent,
+        result.ok ? 'idle' : 'error',
+        result.ok ? 'turn_complete' : 'failed',
+      );
       clearTaskCommands(taskId);
     } catch (err) {
       const errMsg = err instanceof Error ? err.message : String(err);
@@ -783,6 +926,530 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         SET state = 'failed', ended_at = clock_timestamp(), output_summary = ${errMsg.slice(0, 500)}
         WHERE id = ${taskId}
       `.catch(() => {});
+      // #10: turn crashed.
+      if (chatId) emitAgentStatus(sessionId, chatId, agent, 'error', 'crashed');
+      clearTaskCommands(taskId);
+      // No worktree cleanup (persistent); backend stays warm for the next turn.
+    }
+  }
+
+  // ─── Path B (warm ACP): goose / qwen warm backend (v2.6 Phase 2) ─────────────
+
+  // Warm ACP backends are per (chat, agent): each owns ONE stdio process + ACP
+  // connection + session. Pool key = chatId; the AgentPool's secondary key is the
+  // agent. This mirrors agent_sessions' (chat_id, agent) PK.
+  function getWarmAcpBackend(chatId: string, agent: string, installPath: string | null): WarmAcpBackend {
+    let backend = agentPool.get(chatId, agent);
+    if (!backend) {
+      backend = new WarmAcpBackend({
+        sql,
+        log,
+        chatId,
+        agent,
+        installPath,
+        resolved: getResolvedRegistry().get(agent),
+      });
+      agentPool.register(chatId, agent, backend);
+    }
+    return backend as WarmAcpBackend;
+  }
+
+  async function runWarmAcpTask(
+    task: {
+      id: string;
+      project_id: string;
+      input: string;
+      agent: string | null;
+      model: string | null;
+      mode_id: string | null;
+      thinking_option_id: string | null;
+      session_id: string | null;
+      chat_id: string | null;
+    },
+    installPath: string | null,
+  ): Promise<void> {
+    const taskId = task.id;
+    const agent = task.agent!;
+    // shouldUseWarmBackend guarantees both non-null before we get here.
+    const sessionId = task.session_id!;
+    const chatId = task.chat_id!;
+    log.info({ taskId, agent, chatId }, 'dispatcher: starting task (path B — warm ACP)');
+
+    const [project] = await sql<{ path: string | null }[]>`
+      SELECT path FROM projects WHERE id = ${task.project_id}
+    `;
+    const projectPath = project?.path;
+    if (!projectPath) {
+      await sql`
+        UPDATE tasks
+        SET state = 'failed', ended_at = clock_timestamp(), output_summary = 'Project has no path — cannot create worktree'
+        WHERE id = ${taskId}
+      `;
+      return;
+    }
+
+    const ac = new AbortController();
+
+    try {
+      await sql`
+        UPDATE tasks
+        SET state = 'running', started_at = clock_timestamp(), execution_path = 'acp'
+        WHERE id = ${taskId}
+      `;
+
+      // Persistent, session-keyed worktree (shared across turns + agents; NOT torn
+      // down per turn — Phase 3 reaps it). Same as the opencode-server path so a
+      // chat that switches opencode↔goose↔qwen shares one worktree.
+      const { worktreeId, worktreePath, baseCommit } = await ensureSessionWorktree(sql, projectPath, sessionId, {
+        signal: ac.signal,
+      });
+      log.info({ taskId, worktreePath }, 'dispatcher: session worktree ready (warm ACP)');
+
+      const [assistantMsg] = await sql<{ id: string }[]>`
+        INSERT INTO messages (session_id, chat_id, role, content, status, model, created_at)
+        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', ${task.model}, clock_timestamp())
+        RETURNING id
+      `;
+      const assistantId = assistantMsg!.id;
+
+      // write-edit-robustness #4: pre-turn checkpoint of the persistent session
+      // worktree (best-effort; never breaks dispatch). Same worktree the opencode
+      // path uses — a chat that switches opencode↔goose↔qwen shares one worktree.
+      await createCheckpoint(
+        sql,
+        { chatId, sessionId, worktreeId, worktreePath, messageId: assistantId },
+        { signal: ac.signal, log },
+      ).catch(() => null);
+
+      broker.publishFrame(sessionId, {
+        type: 'message_started',
+        message_id: assistantId,
+        chat_id: chatId,
+        role: 'assistant',
+      } as WsFrame);
+
+      // #10: warm-ACP turn begins.
+      emitAgentStatus(sessionId, chatId, agent, 'working', 'turn_start');
+
+      const manifestCommands = getManifestCommands(agent);
+      if (manifestCommands.length > 0) {
+        setTaskCommands(taskId, manifestCommands);
+        broker.publishFrame(sessionId, {
+          type: 'agent_commands',
+          task_id: taskId,
+          session_id: sessionId,
+          commands: manifestCommands,
+        } as WsFrame);
+      }
+
+      // Accumulate the turn's stream for persistence + the final message content.
+      const textChunks: string[] = [];
+      const reasoningChunks: string[] = [];
+      const toolSnaps = new Map<string, AcpToolSnapshot>();
+
+      // Map transport-agnostic AgentEvents → the SAME WS frames the one-shot ACP
+      // path emits (identical to runOpenCodeServerTask's onEvent). No dcp stripping:
+      // that's an opencode-plugin artifact; goose/qwen don't emit dcp tags.
+      const onEvent = (e: AgentEvent): void => {
+        switch (e.type) {
+          case 'text':
+            textChunks.push(e.text);
+            broker.publishFrame(sessionId, {
+              type: 'delta',
+              message_id: assistantId,
+              chat_id: chatId,
+              content: e.text,
+            } as WsFrame);
+            break;
+          case 'reasoning':
+            reasoningChunks.push(e.text);
+            broker.publishFrame(sessionId, {
+              type: 'reasoning_delta',
+              message_id: assistantId,
+              chat_id: chatId,
+              content: e.text,
+            } as WsFrame);
+            break;
+          case 'tool_call':
+          case 'tool_update':
+            toolSnaps.set(e.toolCall.toolCallId, e.toolCall);
+            broker.publishFrame(sessionId, {
+              type: 'tool_call',
+              message_id: assistantId,
+              chat_id: chatId,
+              tool_call: snapshotToWireToolCall(e.toolCall),
+            } as WsFrame);
+            break;
+          case 'commands':
+            if (e.commands.length > 0) {
+              setTaskCommands(taskId, e.commands);
+              broker.publishFrame(sessionId, {
+                type: 'agent_commands',
+                task_id: taskId,
+                session_id: sessionId,
+                commands: e.commands,
+              } as WsFrame);
+            }
+            break;
+        }
+      };
+
+      const model = task.model ?? undefined;
+      const backend = getWarmAcpBackend(chatId, agent, installPath);
+      const handle = await backend.ensureSession(sessionId, {
+        agent,
+        model: model ?? '',
+        chatId,
+        worktreePath,
+        worktreeId,
+        projectId: task.project_id,
+      });
+      const result = await backend.prompt(handle, task.input, {
+        worktreePath,
+        model: model ?? '',
+        signal: ac.signal,
+        onEvent,
+        taskId,
+        modeId: task.mode_id ?? undefined,
+      });
+      // Phase 3: keep the pooled (chat,agent) backend warm across the turn.
+      agentPool.touch(chatId, agent);
+
+      const assistantContent = textChunks.join('').slice(0, 50_000);
+      const reasoningText = reasoningChunks.join('').slice(0, 200_000);
+      const outputSummary = (result.ok ? textChunks.join('') : result.error ?? 'warm ACP turn failed').slice(0, 500);
+
+      await persistExternalAgentTurn(sql, assistantId, [...toolSnaps.values()], reasoningText);
+
+      await sql`
+        UPDATE messages
+        SET content = ${assistantContent}, status = 'complete', finished_at = clock_timestamp()
+        WHERE id = ${assistantId}
+      `;
+      broker.publishFrame(sessionId, {
+        type: 'message_complete',
+        message_id: assistantId,
+        chat_id: chatId,
+        model: task.model,
+      } as WsFrame);
+
+      if (stopping) {
+        await sql`UPDATE tasks SET state = 'cancelled', ended_at = clock_timestamp() WHERE id = ${taskId}`;
+        return; // worktree persists (no cleanup); backend stays warm
+      }
+
+      // Diff the persistent worktree against its captured baseline and SUPERSEDE
+      // the session's prior pending row (latest-wins) — identical to opencode.
+      const diff = await diffWorktree(worktreePath, projectPath, {
+        signal: ac.signal,
+        baseRef: baseCommit ?? 'HEAD',
+      });
+      if (diff) {
+        await sql`
+          DELETE FROM pending_changes WHERE session_id = ${sessionId} AND status = 'pending'
+        `;
+        await sql`
+          INSERT INTO pending_changes (session_id, task_id, file_path, operation, diff, agent)
+          VALUES (${sessionId}, ${taskId}, ${projectPath}, 'edit', ${diff}, ${agent})
+        `;
+        log.info({ taskId, diffLength: diff.length }, 'dispatcher: diff superseded prior pending change (warm ACP)');
+      } else {
+        log.info({ taskId }, 'dispatcher: no changes detected in session worktree (warm ACP)');
+      }
+
+      // NO worktree cleanup — persistent (Phase 3 reaps it). Backend stays warm.
+
+      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;
+
+      const finalState = result.ok ? 'completed' : 'failed';
+      await sql`
+        UPDATE tasks
+        SET state = ${finalState}, ended_at = clock_timestamp(), output_summary = ${outputSummary}, cost_tokens = ${extCostTokens}
+        WHERE id = ${taskId}
+      `;
+      log.info({ taskId, agent, finalState }, 'dispatcher: task finished (warm ACP)');
+      // #10: clean completion → idle; backend-reported failure → error.
+      emitAgentStatus(
+        sessionId,
+        chatId,
+        agent,
+        result.ok ? 'idle' : 'error',
+        result.ok ? 'turn_complete' : 'failed',
+      );
+      clearTaskCommands(taskId);
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      log.error({ taskId, agent, err: errMsg }, 'dispatcher: warm ACP error');
+      await sql`
+        UPDATE tasks
+        SET state = 'failed', ended_at = clock_timestamp(), output_summary = ${errMsg.slice(0, 500)}
+        WHERE id = ${taskId}
+      `.catch(() => {});
+      // #10: turn crashed.
+      emitAgentStatus(sessionId, chatId, agent, 'error', 'crashed');
+      clearTaskCommands(taskId);
+      // No worktree cleanup (persistent); backend stays warm for the next turn.
+    }
+  }
+
+  // ─── Path B (claude SDK): warm Claude-SDK backend (v2.6 #9 Part 2) ───────────
+
+  // Claude-SDK backends are per (chat, agent) — each owns ONE persistent query()
+  // generator driven in streaming-input mode. Pool key = chatId (secondary = agent),
+  // mirroring agent_sessions' (chat_id, agent) PK + the warm-ACP pooling.
+  function getClaudeSdkBackend(chatId: string, agent: string, installPath: string | null): ClaudeSdkBackend {
+    let backend = agentPool.get(chatId, agent);
+    if (!backend) {
+      backend = new ClaudeSdkBackend({ sql, log, chatId, agent, installPath });
+      agentPool.register(chatId, agent, backend);
+    }
+    return backend as ClaudeSdkBackend;
+  }
+
+  async function runClaudeSdkTask(
+    task: {
+      id: string;
+      project_id: string;
+      input: string;
+      agent: string | null;
+      model: string | null;
+      mode_id: string | null;
+      thinking_option_id: string | null;
+      session_id: string | null;
+      chat_id: string | null;
+    },
+    installPath: string | null,
+  ): Promise<void> {
+    const taskId = task.id;
+    const agent = task.agent!;
+    // shouldUseClaudeSdk guarantees both non-null before we get here.
+    const sessionId = task.session_id!;
+    const chatId = task.chat_id!;
+    log.info({ taskId, agent, chatId }, 'dispatcher: starting task (path B — claude SDK)');
+
+    const [project] = await sql<{ path: string | null }[]>`
+      SELECT path FROM projects WHERE id = ${task.project_id}
+    `;
+    const projectPath = project?.path;
+    if (!projectPath) {
+      await sql`
+        UPDATE tasks
+        SET state = 'failed', ended_at = clock_timestamp(), output_summary = 'Project has no path — cannot create worktree'
+        WHERE id = ${taskId}
+      `;
+      return;
+    }
+
+    const ac = new AbortController();
+
+    try {
+      await sql`
+        UPDATE tasks
+        SET state = 'running', started_at = clock_timestamp(), execution_path = 'acp'
+        WHERE id = ${taskId}
+      `;
+
+      // Persistent, session-keyed worktree (shared across turns + agents; NOT torn
+      // down per turn — Phase 3 reaps it). Same as the opencode/warm-ACP paths so a
+      // chat that switches agents shares one worktree.
+      const { worktreeId, worktreePath, baseCommit } = await ensureSessionWorktree(sql, projectPath, sessionId, {
+        signal: ac.signal,
+      });
+      log.info({ taskId, worktreePath }, 'dispatcher: session worktree ready (claude SDK)');
+
+      const [assistantMsg] = await sql<{ id: string }[]>`
+        INSERT INTO messages (session_id, chat_id, role, content, status, model, created_at)
+        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', ${task.model}, clock_timestamp())
+        RETURNING id
+      `;
+      const assistantId = assistantMsg!.id;
+
+      // write-edit-robustness #4: pre-turn checkpoint of the persistent session
+      // worktree (best-effort; never breaks dispatch).
+      await createCheckpoint(
+        sql,
+        { chatId, sessionId, worktreeId, worktreePath, messageId: assistantId },
+        { signal: ac.signal, log },
+      ).catch(() => null);
+
+      broker.publishFrame(sessionId, {
+        type: 'message_started',
+        message_id: assistantId,
+        chat_id: chatId,
+        role: 'assistant',
+      } as WsFrame);
+
+      // #10: claude-SDK turn begins.
+      emitAgentStatus(sessionId, chatId, agent, 'working', 'turn_start');
+
+      const manifestCommands = getManifestCommands(agent);
+      if (manifestCommands.length > 0) {
+        setTaskCommands(taskId, manifestCommands);
+        broker.publishFrame(sessionId, {
+          type: 'agent_commands',
+          task_id: taskId,
+          session_id: sessionId,
+          commands: manifestCommands,
+        } as WsFrame);
+      }
+
+      // Accumulate the turn's stream for persistence + the final message content.
+      const textChunks: string[] = [];
+      const reasoningChunks: string[] = [];
+      const toolSnaps = new Map<string, AcpToolSnapshot>();
+
+      // Map transport-agnostic AgentEvents → the SAME WS frames the warm-ACP /
+      // opencode paths emit. This boundary attaches message_id/chat_id.
+      const onEvent = (e: AgentEvent): void => {
+        switch (e.type) {
+          case 'text':
+            textChunks.push(e.text);
+            broker.publishFrame(sessionId, {
+              type: 'delta',
+              message_id: assistantId,
+              chat_id: chatId,
+              content: e.text,
+            } as WsFrame);
+            break;
+          case 'reasoning':
+            reasoningChunks.push(e.text);
+            broker.publishFrame(sessionId, {
+              type: 'reasoning_delta',
+              message_id: assistantId,
+              chat_id: chatId,
+              content: e.text,
+            } as WsFrame);
+            break;
+          case 'tool_call':
+          case 'tool_update':
+            toolSnaps.set(e.toolCall.toolCallId, e.toolCall);
+            broker.publishFrame(sessionId, {
+              type: 'tool_call',
+              message_id: assistantId,
+              chat_id: chatId,
+              tool_call: snapshotToWireToolCall(e.toolCall),
+            } as WsFrame);
+            break;
+          case 'commands':
+            if (e.commands.length > 0) {
+              setTaskCommands(taskId, e.commands);
+              broker.publishFrame(sessionId, {
+                type: 'agent_commands',
+                task_id: taskId,
+                session_id: sessionId,
+                commands: e.commands,
+              } as WsFrame);
+            }
+            break;
+        }
+      };
+
+      const model = task.model ?? undefined;
+      const backend = getClaudeSdkBackend(chatId, agent, installPath);
+      const handle = await backend.ensureSession(sessionId, {
+        agent,
+        model: model ?? '',
+        chatId,
+        worktreePath,
+        worktreeId,
+        projectId: task.project_id,
+      });
+      const result = await backend.prompt(handle, task.input, {
+        worktreePath,
+        model: model ?? '',
+        signal: ac.signal,
+        onEvent,
+        taskId,
+        modeId: task.mode_id ?? undefined,
+      });
+      // Phase 3: keep the pooled (chat,agent) backend warm across the turn.
+      agentPool.touch(chatId, agent);
+
+      const assistantContent = textChunks.join('').slice(0, 50_000);
+      const reasoningText = reasoningChunks.join('').slice(0, 200_000);
+      const outputSummary = (result.ok ? textChunks.join('') : result.error ?? 'claude SDK turn failed').slice(0, 500);
+
+      await persistExternalAgentTurn(sql, assistantId, [...toolSnaps.values()], reasoningText);
+
+      // ctx_used/ctx_max from the SDK result (1M-aware) → the assistant message, so
+      // the ContextBar renders a real context-window fill for claude.
+      await sql`
+        UPDATE messages
+        SET content = ${assistantContent}, status = 'complete', finished_at = clock_timestamp(),
+            ctx_used = ${result.ctxUsed ?? null}, ctx_max = ${result.ctxMax ?? null}
+        WHERE id = ${assistantId}
+      `;
+      broker.publishFrame(sessionId, {
+        type: 'message_complete',
+        message_id: assistantId,
+        chat_id: chatId,
+        model: task.model,
+      } as WsFrame);
+
+      if (stopping) {
+        await sql`UPDATE tasks SET state = 'cancelled', ended_at = clock_timestamp() WHERE id = ${taskId}`;
+        return; // worktree persists (no cleanup); backend stays warm
+      }
+
+      // Diff the persistent worktree against its captured baseline and SUPERSEDE
+      // the session's prior pending row (latest-wins) — identical to opencode/ACP.
+      const diff = await diffWorktree(worktreePath, projectPath, {
+        signal: ac.signal,
+        baseRef: baseCommit ?? 'HEAD',
+      });
+      if (diff) {
+        await sql`
+          DELETE FROM pending_changes WHERE session_id = ${sessionId} AND status = 'pending'
+        `;
+        await sql`
+          INSERT INTO pending_changes (session_id, task_id, file_path, operation, diff, agent)
+          VALUES (${sessionId}, ${taskId}, ${projectPath}, 'edit', ${diff}, ${agent})
+        `;
+        log.info({ taskId, diffLength: diff.length }, 'dispatcher: diff superseded prior pending change (claude SDK)');
+      } else {
+        log.info({ taskId }, 'dispatcher: no changes detected in session worktree (claude SDK)');
+      }
+
+      // NO worktree cleanup — persistent (Phase 3 reaps it). Backend stays warm.
+
+      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;
+
+      const finalState = result.ok ? 'completed' : 'failed';
+      await sql`
+        UPDATE tasks
+        SET state = ${finalState}, ended_at = clock_timestamp(), output_summary = ${outputSummary}, cost_tokens = ${extCostTokens}
+        WHERE id = ${taskId}
+      `;
+      log.info({ taskId, agent, finalState }, 'dispatcher: task finished (claude SDK)');
+      // #10: clean completion → idle; backend-reported failure → error.
+      emitAgentStatus(
+        sessionId,
+        chatId,
+        agent,
+        result.ok ? 'idle' : 'error',
+        result.ok ? 'turn_complete' : 'failed',
+      );
+      clearTaskCommands(taskId);
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      log.error({ taskId, agent, err: errMsg }, 'dispatcher: claude SDK error');
+      await sql`
+        UPDATE tasks
+        SET state = 'failed', ended_at = clock_timestamp(), output_summary = ${errMsg.slice(0, 500)}
+        WHERE id = ${taskId}
+      `.catch(() => {});
+      // #10: turn crashed.
+      emitAgentStatus(sessionId, chatId, agent, 'error', 'crashed');
       clearTaskCommands(taskId);
       // No worktree cleanup (persistent); backend stays warm for the next turn.
     }

apps/coder/src/services/frame-emitter.ts

@@ -0,0 +1,142 @@
+/**
+ * AgentEvent → WS-frame emitter + turn accumulators.
+ *
+ * Extracted (v2.7 audit reshape) from `AcpStreamContext.handleSessionUpdate` in
+ * `acp-dispatch.ts` — the `AgentEvent → broker.publishFrame` switch that maps a
+ * backend's normalized events onto the wire frames the UI consumes, while
+ * accumulating the turn's text / reasoning / tool snapshots for persistence.
+ *
+ * The same shape backs the dispatcher's 4 inline `onEvent` copies (DEFERRED while
+ * dispatcher.ts has uncommitted edits), hence the optional `dcp` stripper + the
+ * `finalize()` flush: the opencode dispatch path strips dcp tags from text deltas,
+ * the ACP path does not (passes no `dcp`, so text is emitted verbatim — identical
+ * to the prior AcpStreamContext behavior).
+ *
+ * Publishing is gated on `canStream()` (all of broker/sessionId/chatId/assistantId
+ * present) exactly as the original — a one-shot dispatch with no broker accumulates
+ * but never publishes.
+ */
+import type { Broker } from '@boocode/server/broker';
+import type { WsFrame } from '@boocode/server/ws-frames';
+import type { AgentEvent } from './agent-backend.js';
+import { type AcpToolSnapshot, snapshotToWireToolCall } from './acp-tool-snapshot.js';
+import { mergeTaskCommands, getTaskCommands } from './agent-commands-cache.js';
+import type { DcpStreamStripper } from './dcp-strip.js';
+
+export interface FrameEmitterOpts {
+  broker?: Broker;
+  sessionId?: string;
+  chatId?: string;
+  /** The assistant message id — the frames' `message_id`. */
+  assistantId?: string;
+  /** Per-turn task id, for the agent_commands frame + command cache. */
+  taskId?: string;
+  /** Optional cross-chunk dcp stripper for text deltas (opencode path). When
+   *  provided, text is stripped before push/publish and `finalize()` flushes the
+   *  held-back tail. The ACP path passes none → text emitted verbatim. */
+  dcp?: DcpStreamStripper;
+}
+
+export interface FrameEmitter {
+  /** Map one AgentEvent to its WS frame(s) + accumulate it. */
+  onEvent: (e: AgentEvent) => void;
+  /** Flush a dcp stripper's held-back tail at turn end (no-op without `dcp`). */
+  finalize: () => void;
+  /** The merge accumulator for tool snapshots (toolCallId → snapshot). */
+  readonly toolSnapshots: Map<string, AcpToolSnapshot>;
+  /** Accumulated assistant text (post-dcp-strip when a stripper is set). */
+  readonly output: string;
+  /** Accumulated reasoning text. */
+  readonly reasoningText: string;
+  /** Tool snapshots in insertion order. */
+  readonly snapshots: AcpToolSnapshot[];
+}
+
+export function makeFrameEmitter(opts: FrameEmitterOpts): FrameEmitter {
+  const { broker, sessionId, chatId, assistantId, taskId, dcp } = opts;
+  const textChunks: string[] = [];
+  const reasoningChunks: string[] = [];
+  const toolSnapshots = new Map<string, AcpToolSnapshot>();
+
+  const canStream = (): boolean => !!(broker && sessionId && chatId && assistantId);
+
+  const publishText = (content: string): void => {
+    textChunks.push(content);
+    if (canStream()) {
+      broker!.publishFrame(sessionId!, {
+        type: 'delta',
+        message_id: assistantId!,
+        chat_id: chatId!,
+        content,
+      } as WsFrame);
+    }
+  };
+
+  const onEvent = (e: AgentEvent): void => {
+    switch (e.type) {
+      case 'text': {
+        const safe = dcp ? dcp.push(e.text) : e.text;
+        if (safe) publishText(safe);
+        break;
+      }
+      case 'reasoning':
+        reasoningChunks.push(e.text);
+        if (canStream()) {
+          broker!.publishFrame(sessionId!, {
+            type: 'reasoning_delta',
+            message_id: assistantId!,
+            chat_id: chatId!,
+            content: e.text,
+          } as WsFrame);
+        }
+        break;
+      case 'tool_call':
+      case 'tool_update':
+        toolSnapshots.set(e.toolCall.toolCallId, e.toolCall);
+        if (canStream()) {
+          broker!.publishFrame(sessionId!, {
+            type: 'tool_call',
+            message_id: assistantId!,
+            chat_id: chatId!,
+            tool_call: snapshotToWireToolCall(e.toolCall),
+          } as WsFrame);
+        }
+        break;
+      case 'commands':
+        if (taskId && e.commands.length > 0) {
+          mergeTaskCommands(taskId, e.commands);
+          if (canStream() && sessionId) {
+            const all = getTaskCommands(taskId) ?? e.commands;
+            broker!.publishFrame(sessionId, {
+              type: 'agent_commands',
+              task_id: taskId,
+              session_id: sessionId,
+              commands: all,
+            } as WsFrame);
+          }
+        }
+        break;
+    }
+  };
+
+  const finalize = (): void => {
+    if (!dcp) return;
+    const tail = dcp.flush();
+    if (tail) publishText(tail);
+  };
+
+  return {
+    onEvent,
+    finalize,
+    toolSnapshots,
+    get output() {
+      return textChunks.join('');
+    },
+    get reasoningText() {
+      return reasoningChunks.join('');
+    },
+    get snapshots() {
+      return [...toolSnapshots.values()];
+    },
+  };
+}

apps/coder/src/services/fuzzy-match.ts

@@ -0,0 +1,271 @@
+// Fuzzy patch locator for staged edits.
+//
+// Local quantized models (qwen3.6 and friends) frequently reproduce an
+// `old_string` with small, semantically-irrelevant drift: trailing whitespace,
+// a different indent width, or "smart" unicode punctuation (curly quotes, an
+// en/em-dash, a non-breaking space) where the source has the plain ASCII form.
+// An exact `String.includes` then fails and the queued edit is lost even though
+// a human would say it obviously matches.
+//
+// `locateMatch` walks a ladder of progressively looser strategies and returns
+// the real `[start, end)` byte-offset span in the ORIGINAL content so the caller
+// can splice in `new_string` over the true file text (preserving the file's own
+// whitespace/unicode, not the model's drifted copy). The ladder stops at the
+// first strategy that resolves to a single span:
+//
+//   1. exact            — indexOf; >1 hit is reported `ambiguous` (we refuse to
+//                         guess which occurrence the model meant).
+//   2. per-line ws      — line-window compare ignoring per-line trailing
+//                         whitespace and leading/trailing blank needle lines.
+//   3. unicode canon    — same line-window compare after folding smart
+//                         punctuation to ASCII on both sides; the match is
+//                         mapped back to original offsets.
+//   4. levenshtein      — best line-window by normalized edit-distance
+//                         similarity; accepted only at >= SIMILARITY_THRESHOLD.
+//
+// Pure and dependency-free (Levenshtein is the standard iterative two-row DP),
+// reimplemented from the general technique — no vendored source.
+
+export type MatchResult =
+  | { kind: 'exact' | 'fuzzy'; start: number; end: number } // [start,end) offsets into content
+  | { kind: 'ambiguous'; count: number }
+  | { kind: 'not_found' };
+
+/** Levenshtein similarity floor for the final fuzzy fallback (strategy 4). */
+export const SIMILARITY_THRESHOLD = 0.66;
+
+export function locateMatch(content: string, needle: string): MatchResult {
+  // Empty needle has no meaningful match.
+  if (needle.length === 0) return { kind: 'not_found' };
+
+  // --- 1. Exact ----------------------------------------------------------------
+  const exact = locateExact(content, needle);
+  if (exact) return exact;
+
+  // --- 2. Per-line whitespace-insensitive -------------------------------------
+  const ws = locateByLineWindow(content, needle);
+  if (ws) return ws;
+
+  // --- 3. Unicode-canonicalized whitespace pass -------------------------------
+  const canon = locateCanonical(content, needle);
+  if (canon) return canon;
+
+  // --- 4. Levenshtein similarity ----------------------------------------------
+  const lev = locateByLevenshtein(content, needle);
+  if (lev) return lev;
+
+  return { kind: 'not_found' };
+}
+
+// --- Strategy 1: exact -------------------------------------------------------
+
+function locateExact(content: string, needle: string): MatchResult | null {
+  const first = content.indexOf(needle);
+  if (first === -1) return null;
+  const second = content.indexOf(needle, first + 1);
+  if (second === -1) {
+    return { kind: 'exact', start: first, end: first + needle.length };
+  }
+  // Count all occurrences so the caller can report a useful number.
+  let count = 2;
+  let idx = content.indexOf(needle, second + 1);
+  while (idx !== -1) {
+    count++;
+    idx = content.indexOf(needle, idx + 1);
+  }
+  return { kind: 'ambiguous', count };
+}
+
+// --- Line-window machinery ---------------------------------------------------
+
+interface Line {
+  /** Raw line text (no trailing newline). */
+  text: string;
+  /** Offset of the first char of this line in the original content. */
+  start: number;
+  /** Offset one past the last char of this line (before its newline, if any). */
+  end: number;
+}
+
+/**
+ * Split content into lines, tracking each line's real offset span. The span
+ * EXCLUDES the trailing newline so consecutive line spans plus their newlines
+ * exactly reconstruct the content; the match span we hand back covers from the
+ * first matched line's start through the last matched line's end (i.e. without a
+ * trailing newline), which is what an in-place splice wants.
+ */
+function splitLines(content: string): Line[] {
+  const lines: Line[] = [];
+  let start = 0;
+  for (let i = 0; i <= content.length; i++) {
+    if (i === content.length || content[i] === '\n') {
+      lines.push({ text: content.slice(start, i), start, end: i });
+      start = i + 1;
+    }
+  }
+  return lines;
+}
+
+/** Strip leading/trailing all-blank lines; returns the trimmed slice. */
+function trimBlankLines(lines: string[]): string[] {
+  let lo = 0;
+  let hi = lines.length;
+  while (lo < hi && lines[lo]!.trim() === '') lo++;
+  while (hi > lo && lines[hi - 1]!.trim() === '') hi--;
+  return lines.slice(lo, hi);
+}
+
+/**
+ * Find a contiguous window of content lines whose trailing-whitespace-trimmed
+ * text equals the needle's (blank-trimmed) lines. Returns the real offset span
+ * over the matched content lines, or null if zero match. Multiple matches →
+ * ambiguous. `normalize` lets the caller fold unicode before comparing.
+ */
+function locateByLineWindow(
+  content: string,
+  needle: string,
+  normalize: (s: string) => string = (s) => s,
+): MatchResult | null {
+  const contentLines = splitLines(content);
+  const needleLines = trimBlankLines(needle.split('\n'));
+  const n = needleLines.length;
+  if (n === 0) return null;
+  // A single needle line that is itself blank can't be located meaningfully.
+  if (n === 1 && needleLines[0]!.trim() === '') return null;
+
+  const needleKey = needleLines.map((l) => normalize(l.trimEnd())).join('\n');
+
+  const hits: Array<{ start: number; end: number }> = [];
+  for (let i = 0; i + n <= contentLines.length; i++) {
+    const windowKey = contentLines
+      .slice(i, i + n)
+      .map((l) => normalize(l.text.trimEnd()))
+      .join('\n');
+    if (windowKey === needleKey) {
+      hits.push({ start: contentLines[i]!.start, end: contentLines[i + n - 1]!.end });
+    }
+  }
+
+  if (hits.length === 0) return null;
+  if (hits.length > 1) return { kind: 'ambiguous', count: hits.length };
+  return { kind: 'fuzzy', start: hits[0]!.start, end: hits[0]!.end };
+}
+
+// --- Strategy 3: unicode canonicalization ------------------------------------
+
+/**
+ * Fold smart punctuation to its ASCII equivalent. Crucially this is a
+ * length-PRESERVING, per-character map (every replacement is one char → one
+ * char), so an offset into the canonical string is also a valid offset into the
+ * original — letting strategy 3 reuse the line-window matcher and still hand
+ * back true original-content offsets.
+ */
+function canonicalizeChar(ch: string): string {
+  switch (ch) {
+    // single quotes / apostrophes
+    case '‘': // '
+    case '’': // '
+    case '‚': // ‚
+    case '‛': // ‛
+      return "'";
+    // double quotes
+    case '“': // "
+    case '”': // "
+    case '„': // „
+    case '‟': // ‟
+      return '"';
+    // dashes
+    case '–': // – en dash
+    case '—': // — em dash
+    case '‒': // ‒ figure dash
+    case '―': // ― horizontal bar
+    case '−': // − minus sign
+      return '-';
+    // spaces
+    case ' ': // nbsp
+    case ' ': // figure space
+    case ' ': // narrow nbsp
+      return ' ';
+    default:
+      return ch;
+  }
+}
+
+function canonicalize(s: string): string {
+  let out = '';
+  for (const ch of s) out += canonicalizeChar(ch);
+  return out;
+}
+
+function locateCanonical(content: string, needle: string): MatchResult | null {
+  // Only worth running if canonicalization actually changes something on either
+  // side — otherwise it's identical to strategy 2 which already failed.
+  const canonContent = canonicalize(content);
+  const canonNeedle = canonicalize(needle);
+  if (canonContent === content && canonNeedle === needle) return null;
+  // Offsets are preserved (length-preserving fold), so a match on the canonical
+  // content maps directly back to the original.
+  return locateByLineWindow(canonContent, canonNeedle);
+}
+
+// --- Strategy 4: Levenshtein similarity --------------------------------------
+
+/** Standard iterative two-row Levenshtein edit distance. */
+function levenshtein(a: string, b: string): number {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+
+  let prev = new Array<number>(b.length + 1);
+  let curr = new Array<number>(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i;
+    const ac = a.charCodeAt(i - 1);
+    for (let j = 1; j <= b.length; j++) {
+      const cost = ac === b.charCodeAt(j - 1) ? 0 : 1;
+      curr[j] = Math.min(
+        prev[j]! + 1, // deletion
+        curr[j - 1]! + 1, // insertion
+        prev[j - 1]! + cost, // substitution
+      );
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[b.length]!;
+}
+
+/** Normalized similarity in [0,1]: 1 - dist / max(len). */
+function similarity(a: string, b: string): number {
+  const maxLen = Math.max(a.length, b.length);
+  if (maxLen === 0) return 1;
+  return 1 - levenshtein(a, b) / maxLen;
+}
+
+function locateByLevenshtein(content: string, needle: string): MatchResult | null {
+  const contentLines = splitLines(content);
+  const needleLines = trimBlankLines(needle.split('\n'));
+  const n = needleLines.length;
+  if (n === 0) return null;
+  if (contentLines.length < n) return null;
+
+  const needleJoined = needleLines.map((l) => l.trim()).join('\n');
+
+  let best = -1;
+  let bestSpan: { start: number; end: number } | null = null;
+  for (let i = 0; i + n <= contentLines.length; i++) {
+    const window = contentLines.slice(i, i + n);
+    const windowJoined = window.map((l) => l.text.trim()).join('\n');
+    const score = similarity(windowJoined, needleJoined);
+    if (score > best) {
+      best = score;
+      bestSpan = { start: window[0]!.start, end: window[n - 1]!.end };
+    }
+  }
+
+  if (bestSpan && best >= SIMILARITY_THRESHOLD) {
+    return { kind: 'fuzzy', start: bestSpan.start, end: bestSpan.end };
+  }
+  return null;
+}

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

@@ -25,13 +25,6 @@ interface PendingRow {
   session_id: string;
 }
 
-interface WorktreeRow {
-  id: string;
-  worktree_path: string;
-  agent: string;
-  started_at: string;
-}
-
 interface ProjectPathRow {
   path: string;
 }
@@ -196,28 +189,6 @@ export async function startMcpServer(sql: Sql): Promise<void> {
     },
   );
 
-  // 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);

apps/coder/src/services/net/port-utils.ts

@@ -0,0 +1,88 @@
+/**
+ * Generic POSIX loopback-port utilities.
+ *
+ * Extracted verbatim (v2.7 audit reshape) from `backends/opencode-server.ts`,
+ * where they were embedded in the backend god-class. They have nothing to do with
+ * opencode semantics — they reclaim/await/allocate a 127.0.0.1 port — so they live
+ * here as reusable infra. No behavior change from the original.
+ */
+import { createServer, connect as netConnect } from 'node:net';
+import { spawnSync } from 'node:child_process';
+
+/**
+ * Reclaim a loopback port a dead child may still hold (lift of openchamber
+ * `killProcessOnPort`). Best-effort, POSIX-only (`lsof`/`kill`); a failure is
+ * harmless because the next spawn allocates a fresh ephemeral port. Never kills
+ * this process. Synchronous + short-timeout so a crash handler doesn't block.
+ */
+export function reclaimPort(port: number | null): void {
+  if (!port || process.platform === 'win32') return;
+  try {
+    const res = spawnSync('lsof', ['-ti', `:${port}`], { encoding: 'utf8', timeout: 3_000, windowsHide: true });
+    const out = res.stdout || '';
+    const myPid = process.pid;
+    for (const pidStr of out.split(/\s+/)) {
+      const pid = parseInt(pidStr.trim(), 10);
+      if (pid && pid !== myPid) {
+        try {
+          spawnSync('kill', ['-9', String(pid)], { stdio: 'ignore', timeout: 2_000 });
+        } catch {
+          // ignore — best effort
+        }
+      }
+    }
+  } catch {
+    // lsof absent or failed — the fresh-ephemeral-port spawn doesn't need this.
+  }
+}
+
+/**
+ * Resolve true once nothing is listening on `port` (lift of openchamber
+ * `waitForPortRelease`). Used before re-spawning on a fixed port; with ephemeral
+ * ports it's a fast no-op. Probes 127.0.0.1; resolves false at the deadline.
+ */
+export function waitForPortRelease(port: number, timeoutMs: number): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  return new Promise((resolve) => {
+    const attempt = () => {
+      const socket = netConnect({ port, host: '127.0.0.1' });
+      let settled = false;
+      const finish = (released: boolean) => {
+        if (settled) return;
+        settled = true;
+        socket.removeAllListeners();
+        socket.destroy();
+        if (released || Date.now() >= deadline) {
+          resolve(released);
+          return;
+        }
+        setTimeout(attempt, 150);
+      };
+      socket.once('connect', () => finish(false));
+      socket.once('error', (err: NodeJS.ErrnoException) => {
+        if (err && (err.code === 'ECONNREFUSED' || err.code === 'EHOSTUNREACH')) finish(true);
+        else finish(false);
+      });
+      socket.setTimeout(500, () => finish(true));
+    };
+    attempt();
+  });
+}
+
+/** Bind-probe an ephemeral port on loopback. */
+export function freePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = createServer();
+    srv.unref();
+    srv.on('error', reject);
+    srv.listen(0, '127.0.0.1', () => {
+      const addr = srv.address();
+      if (addr && typeof addr === 'object') {
+        const { port } = addr;
+        srv.close(() => resolve(port));
+      } else {
+        srv.close(() => reject(new Error('port-utils: could not determine a free port')));
+      }
+    });
+  });
+}

apps/coder/src/services/normalize-agent-status.ts

@@ -0,0 +1,23 @@
+/**
+ * normalize-agent-status (#10) — clean-room vendor-event → bucket mapping.
+ *
+ * Different coding agents (claude, opencode, codex/gemini, goose, qwen) emit
+ * lifecycle hook events under inconsistent names: PascalCase (`SessionStart`),
+ * snake_case (`session_start`), camelCase (`sessionStart`), and a handful of
+ * provider-specific approval events (`exec_approval_request`). This module
+ * collapses every known event name into one of three coarse signals:
+ *
+ *   working  — the agent is actively progressing a turn
+ *   blocked  — the agent is waiting on a human (permission / approval / question)
+ *   done     — the turn / session ended cleanly
+ *
+ * `null` is returned for anything unrecognized so callers can ignore noise.
+ *
+ * Built now for the scoped status-publish, but specifically shaped for reuse by
+ * the documented config-injection follow-on: a future notify-hook injected into
+ * each agent's native config will POST the RAW vendor event name to a BooCoder
+ * endpoint, which runs this helper to derive the normalized status. The names
+ * below are facts about each agent's hook surface — not copied vendor code.
+ */
+
+export type AgentStatus = 'working' | 'blocked' | 'idle' | 'error';

apps/coder/src/services/orphan-worktree-reaper.ts

@@ -0,0 +1,171 @@
+/**
+ * v2.6 Phase 3 (3.4) — orphan worktree reaper.
+ *
+ * Reclaims on-disk session worktree dirs under WORKTREE_BASE that have NO live
+ * (`status='active'`) row in the `worktrees` table — leaks from a crash between
+ * `git worktree add` and the DB insert, a missed chat-close hook, or a manual rm
+ * of the DB row. Extends the periodic-sweeper pattern (apps/server's truncation +
+ * stale-streaming reaper).
+ *
+ * SAFETY (Paseo worktree-archive cascade + superset destroy-saga lift): before
+ * removing ANY dir, run `checkWorktreeWorkAtRisk` — a dirty / unpushed / unmerged
+ * worktree is SKIPPED (logged), never force-removed. The pure orphan-target
+ * selection (which dirs are candidates) lives in
+ * `backends/lifecycle-decisions.ts:selectOrphanWorktreeTargets` and is unit-tested;
+ * this module does the DB read + fs stat + git preflight + removal side-effects.
+ *
+ * The mtime grace (default 1h) means a dir mid-`ensureSessionWorktree` (created on
+ * disk, row not yet committed) is never swept — the grace window covers the gap.
+ */
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { FastifyBaseLogger } from 'fastify';
+import type { Sql } from '../db.js';
+import { WORKTREE_BASE } from './worktrees.js';
+import { checkWorktreeWorkAtRisk } from './worktree-risk.js';
+import { hostExec } from './host-exec.js';
+import {
+  selectOrphanWorktreeTargets,
+  DEFAULT_ORPHAN_WORKTREE_GRACE_MS,
+} from './backends/lifecycle-decisions.js';
+
+export interface OrphanWorktreeReaperDeps {
+  sql: Sql;
+  log: FastifyBaseLogger;
+  intervalMs: number;
+  graceMs?: number;
+}
+
+export interface OrphanReaperResult {
+  scanned: number;
+  candidates: number;
+  reaped: string[];
+  skippedAtRisk: string[];
+}
+
+/** Single-pass reap: select orphan candidates, preflight at-risk, remove the safe. */
+export async function reapOrphanWorktrees(
+  sql: Sql,
+  log: FastifyBaseLogger,
+  graceMs: number = DEFAULT_ORPHAN_WORKTREE_GRACE_MS,
+  now: number = Date.now(),
+): Promise<OrphanReaperResult> {
+  // Enumerate on-disk session worktree dirs (`sess-*`). Per-task worktrees
+  // (arena/new_task/MCP) are cleaned up inline by the one-shot path, so we only
+  // own the persistent session dirs the warm paths leave behind.
+  let dirents: string[];
+  try {
+    dirents = await readdir(WORKTREE_BASE);
+  } catch {
+    return { scanned: 0, candidates: 0, reaped: [], skippedAtRisk: [] }; // base absent → nothing to do
+  }
+  const onDisk: { path: string; mtimeMs: number }[] = [];
+  for (const name of dirents) {
+    if (!name.startsWith('sess-')) continue; // only persistent session worktrees
+    const path = join(WORKTREE_BASE, name);
+    try {
+      const s = await stat(path);
+      if (!s.isDirectory()) continue;
+      onDisk.push({ path, mtimeMs: s.mtimeMs });
+    } catch {
+      // vanished between readdir and stat — skip
+    }
+  }
+
+  // Live worktree paths from the DB (active rows only — archived/removed rows are
+  // not "live", so their leftover dirs are reapable orphans).
+  const liveRows = await sql<{ path: string }[]>`
+    SELECT path FROM worktrees WHERE status = 'active'
+  `;
+  const live = new Set(liveRows.map((r) => r.path));
+
+  const candidates = selectOrphanWorktreeTargets(onDisk, live, now, graceMs);
+  const reaped: string[] = [];
+  const skippedAtRisk: string[] = [];
+
+  for (const path of candidates) {
+    // Preflight: never reap work at risk. A git error forces atRisk=true (fail
+    // closed), so a half-broken worktree is kept, not silently destroyed.
+    const risk = await checkWorktreeWorkAtRisk(path);
+    if (risk.atRisk) {
+      skippedAtRisk.push(path);
+      log.warn({ path, dirty: risk.dirty, unmerged: risk.unmerged, error: risk.error }, 'orphan-reaper: skipping at-risk orphan worktree');
+      continue;
+    }
+    const removed = await removeOrphanDir(path);
+    if (removed) reaped.push(path);
+  }
+
+  if (reaped.length > 0 || skippedAtRisk.length > 0) {
+    log.info({ scanned: onDisk.length, candidates: candidates.length, reaped, skippedAtRisk }, 'orphan-reaper: pass complete');
+  }
+  return { scanned: onDisk.length, candidates: candidates.length, reaped, skippedAtRisk };
+}
+
+/**
+ * Remove a single orphan worktree dir. Resolve its main repo via the git
+ * common-dir, run `worktree remove --force` from there + prune, then rm the dir as
+ * a backstop. Best-effort: every step is independently fault-tolerant so a partial
+ * state (dir present, git untracked) still gets reclaimed.
+ */
+async function removeOrphanDir(path: string): Promise<boolean> {
+  // Find the owning repo (the common git dir's parent). When the dir isn't a valid
+  // worktree anymore, this fails and we fall back to a plain rm.
+  const common = await hostExec(
+    `git -C ${shellEscape(path)} rev-parse --path-format=absolute --git-common-dir`,
+    { timeoutMs: 10_000 },
+  ).catch(() => null);
+  const commonDir = common && common.exitCode === 0 ? common.stdout.trim() : '';
+  // The repo worktree root is the parent of the .git common dir (strip trailing /.git).
+  const repoRoot = commonDir.replace(/\/\.git\/?$/, '').replace(/\/\.git$/, '');
+
+  if (repoRoot && repoRoot !== commonDir) {
+    await hostExec(
+      `git -C ${shellEscape(repoRoot)} worktree remove ${shellEscape(path)} --force`,
+      { timeoutMs: 15_000 },
+    ).catch(() => {});
+    await hostExec(
+      `git -C ${shellEscape(repoRoot)} worktree prune`,
+      { timeoutMs: 10_000 },
+    ).catch(() => {});
+  }
+  // Backstop: ensure the dir is gone even if the git remove no-op'd.
+  const rm = await hostExec(`rm -rf ${shellEscape(path)}`, { timeoutMs: 15_000 }).catch(() => null);
+  return rm != null && rm.exitCode === 0;
+}
+
+/** Minimal single-quote shell escape (mirrors worktrees.ts). */
+function shellEscape(s: string): string {
+  return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+
+/** Periodic orphan-worktree reaper, started/stopped by the bootstrap. Unref'd. */
+export function createOrphanWorktreeReaper(deps: OrphanWorktreeReaperDeps): { start(): void; stop(): void } {
+  const { sql, log, intervalMs } = deps;
+  const graceMs = deps.graceMs ?? DEFAULT_ORPHAN_WORKTREE_GRACE_MS;
+  let timer: ReturnType<typeof setInterval> | null = null;
+  let running = false;
+
+  return {
+    start() {
+      if (timer) return;
+      timer = setInterval(() => {
+        if (running) return; // a slow pass must not overlap the next tick
+        running = true;
+        void reapOrphanWorktrees(sql, log, graceMs)
+          .catch((err) => log.warn({ err: err instanceof Error ? err.message : String(err) }, 'orphan-reaper: pass error'))
+          .finally(() => {
+            running = false;
+          });
+      }, intervalMs);
+      timer.unref?.();
+      log.info({ intervalMs, graceMs }, 'orphan-reaper: started');
+    },
+    stop() {
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+    },
+  };
+}

apps/coder/src/services/pending_changes.ts

@@ -2,6 +2,7 @@ import { readFile, writeFile, unlink, mkdir } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import type { Sql } from '../db.js';
 import { resolveWritePath } from './write_guard.js';
+import { locateMatch } from './fuzzy-match.js';
 
 // --- Types -------------------------------------------------------------------
 
@@ -121,10 +122,18 @@ export async function applyOne(
       case 'edit': {
         const { old: oldStr, new: newStr } = JSON.parse(change.diff) as { old: string; new: string };
         const content = await readFile(change.file_path, 'utf8');
-        if (!content.includes(oldStr)) {
-          throw new Error('old_string not found in file — file may have changed since the edit was queued');
+        const match = locateMatch(content, oldStr);
+        if (match.kind === 'ambiguous') {
+          throw new Error(
+            `old_string matches ${match.count} locations — add surrounding context to disambiguate`,
+          );
         }
-        const updated = content.replace(oldStr, newStr);
+        if (match.kind === 'not_found') {
+          throw new Error(
+            'old_string not found in file (even fuzzily) — file may have changed since the edit was queued',
+          );
+        }
+        const updated = content.slice(0, match.start) + newStr + content.slice(match.end);
         await writeFile(change.file_path, updated, 'utf8');
         break;
       }
@@ -172,10 +181,6 @@ export async function rejectOne(sql: Sql, changeId: string): Promise<void> {
   await sql`UPDATE pending_changes SET status = 'rejected' WHERE id = ${changeId} AND status = 'pending'`;
 }
 
-export async function rejectAll(sql: Sql, sessionId: string): Promise<void> {
-  await sql`UPDATE pending_changes SET status = 'rejected' WHERE session_id = ${sessionId} AND status = 'pending'`;
-}
-
 // --- Rewind functions --------------------------------------------------------
 
 export async function rewindOne(
@@ -203,10 +208,18 @@ export async function rewindOne(
         // Reverse an edit: swap old and new
         const { old: oldStr, new: newStr } = JSON.parse(change.diff) as { old: string; new: string };
         const content = await readFile(change.file_path, 'utf8');
-        if (!content.includes(newStr)) {
-          throw new Error('new_string not found in file — cannot rewind; file may have been modified since apply');
+        const match = locateMatch(content, newStr);
+        if (match.kind === 'ambiguous') {
+          throw new Error(
+            `new_string matches ${match.count} locations — cannot rewind; add surrounding context to disambiguate`,
+          );
         }
-        const reverted = content.replace(newStr, oldStr);
+        if (match.kind === 'not_found') {
+          throw new Error(
+            'new_string not found in file (even fuzzily) — cannot rewind; file may have been modified since apply',
+          );
+        }
+        const reverted = content.slice(0, match.start) + oldStr + content.slice(match.end);
         await writeFile(change.file_path, reverted, 'utf8');
         break;
       }

apps/coder/src/services/provider-config-registry.ts

@@ -127,7 +127,3 @@ export function getResolvedRegistry(): Map<string, ResolvedProviderDef> {
   return cachedRegistry ?? buildResolvedRegistry(PROVIDERS, { providers: {} });
 }
 
-/** Resolved provider ids in registry order. */
-export function getResolvedProviderIds(): string[] {
-  return [...getResolvedRegistry().keys()];
-}

apps/coder/src/services/provider-registry.ts

@@ -38,6 +38,12 @@ export const PROVIDERS: ProviderDef[] = [
   },
   {
     name: 'claude',
+    // transport stays 'pty' — the DEFAULT dispatch path (one-shot `claude
+    // --output-format stream-json`). claude-sdk-sessionstore #9 (Part 2) adds a warm
+    // Claude-Agent-SDK backend (services/backends/claude-sdk.ts) routed ONLY when the
+    // `CLAUDE_SDK_BACKEND` env flag is truthy AND the task is a chat tab; with the flag
+    // off (production default) claude always uses this PTY path, so the transport label
+    // is left unchanged. Flip the env var on a host (after a live smoke) to opt in.
     label: 'Claude Code',
     transport: 'pty',
     modelSource: 'static',

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

@@ -1,13 +1,29 @@
 /**
  * PTY dispatch — runs external agents directly on the host.
+ *
+ * claude + qwen run with `--output-format stream-json` and emit Claude-Code's
+ * stream-json NDJSON on stdout. When an `onEvent` callback is supplied we
+ * line-buffer that stdout (split on `\n`, hold the partial tail) and feed complete
+ * lines to `makeStreamJsonParser` so deltas surface live as AgentEvents. The raw
+ * stdout is still accumulated + returned for back-compat (and the dispatcher's
+ * fallback when nothing parsed). See `stream-json-parser.ts`.
  */
 import type { FastifyBaseLogger } from 'fastify';
 import { spawn } from 'node:child_process';
+import type { AgentEvent } from './agent-backend.js';
+import { makeStreamJsonParser, type StreamJsonUsage } from './stream-json-parser.js';
 
 export interface DispatchResult {
   exitCode: number;
   stdout: string;
   stderr: string;
+  /** True iff at least one NDJSON AgentEvent was parsed from stdout (v#7). When
+   *  false the dispatcher falls back to slicing stdout as the assistant content. */
+  streamed: boolean;
+  /** Final usage parsed from the stream-json `result` / `message_delta`, if any. */
+  usage?: StreamJsonUsage;
+  /** Provider session id from the stream-json `system` init line, if any. */
+  agentSessionId?: string | null;
 }
 
 export interface PtyDispatchOpts {
@@ -20,6 +36,10 @@ export interface PtyDispatchOpts {
   installPath?: string;
   signal?: AbortSignal;
   log: FastifyBaseLogger;
+  /** Optional live event sink. When set, stdout is line-buffered + NDJSON-parsed
+   *  and each AgentEvent is forwarded here as it arrives. Absent → opaque (old)
+   *  behavior: stdout is accumulated and returned, no parsing. */
+  onEvent?: (e: AgentEvent) => void;
 }
 
 interface PtySpawnSpec {
@@ -40,7 +60,9 @@ function buildPtySpawnSpec(
 
   switch (agent) {
     case 'claude': {
-      const args = ['-p'];
+      // stream-json on -p requires --verbose (Claude Code rejects stream-json
+      // print mode without it). qwen needs no such flag.
+      const args = ['-p', '--output-format', 'stream-json', '--verbose'];
       if (model) args.push('--model', model);
       if (modeId) args.push('--permission-mode', modeId);
       if (thinkingOptionId) args.push('--effort', thinkingOptionId);
@@ -73,7 +95,7 @@ function buildPtySpawnSpec(
 }
 
 export async function dispatchViaPty(opts: PtyDispatchOpts): Promise<DispatchResult> {
-  const { agent, task, worktreePath, model, modeId, thinkingOptionId, installPath, signal, log } = opts;
+  const { agent, task, worktreePath, model, modeId, thinkingOptionId, installPath, signal, log, onEvent } = opts;
 
   const cmd = buildPtySpawnSpec(agent, task, model, modeId, thinkingOptionId, installPath);
   if (!cmd) {
@@ -81,6 +103,7 @@ export async function dispatchViaPty(opts: PtyDispatchOpts): Promise<DispatchRes
       exitCode: 1,
       stdout: '',
       stderr: `Agent '${agent}' is not yet supported for PTY dispatch.`,
+      streamed: false,
     };
   }
 
@@ -102,7 +125,32 @@ export async function dispatchViaPty(opts: PtyDispatchOpts): Promise<DispatchRes
     let stderr = '';
     let killed = false;
 
-    child.stdout!.on('data', (chunk: Buffer) => { stdout += chunk.toString(); });
+    // Live NDJSON parsing (only when a sink is supplied). Line-buffer: split on
+    // '\n', dispatch complete lines, hold the partial tail until the next chunk.
+    const parser = onEvent ? makeStreamJsonParser() : null;
+    let lineBuf = '';
+    let streamed = false;
+    const feedLine = (line: string): void => {
+      if (!parser || !onEvent) return;
+      for (const e of parser.push(line)) {
+        streamed = true;
+        onEvent(e);
+      }
+    };
+
+    child.stdout!.on('data', (chunk: Buffer) => {
+      const text = chunk.toString();
+      stdout += text;
+      if (!parser) return;
+      lineBuf += text;
+      let nl = lineBuf.indexOf('\n');
+      while (nl !== -1) {
+        const line = lineBuf.slice(0, nl);
+        lineBuf = lineBuf.slice(nl + 1);
+        feedLine(line);
+        nl = lineBuf.indexOf('\n');
+      }
+    });
     child.stderr!.on('data', (chunk: Buffer) => { stderr += chunk.toString(); });
 
     const cleanup = () => {
@@ -116,7 +164,7 @@ export async function dispatchViaPty(opts: PtyDispatchOpts): Promise<DispatchRes
     if (signal) {
       if (signal.aborted) {
         cleanup();
-        resolve({ exitCode: 130, stdout: '', stderr: 'Aborted before start' });
+        resolve({ exitCode: 130, stdout: '', stderr: 'Aborted before start', streamed: false });
         return;
       }
       signal.addEventListener('abort', cleanup, { once: true });
@@ -124,8 +172,18 @@ export async function dispatchViaPty(opts: PtyDispatchOpts): Promise<DispatchRes
 
     child.on('close', (code) => {
       if (signal) signal.removeEventListener('abort', cleanup);
-      log.info({ agent, exitCode: code }, 'pty-dispatch: completed');
-      resolve({ exitCode: code ?? 1, stdout, stderr });
+      // Flush any final line with no trailing newline.
+      if (lineBuf.trim()) feedLine(lineBuf);
+      lineBuf = '';
+      log.info({ agent, exitCode: code, streamed }, 'pty-dispatch: completed');
+      resolve({
+        exitCode: code ?? 1,
+        stdout,
+        stderr,
+        streamed,
+        usage: parser?.usage(),
+        agentSessionId: parser?.sessionId() ?? null,
+      });
     });
 
     child.on('error', (err) => {

apps/coder/src/services/stream-json-parser.ts

@@ -0,0 +1,296 @@
+/**
+ * Claude-Code-compatible stream-json NDJSON parser (feature #7,
+ * openspec `sampling-streamjson-tokens`).
+ *
+ * qwen (`--output-format stream-json`) and claude (`--output-format stream-json`)
+ * both emit Claude-Code's stream-json NDJSON on stdout: one JSON object per line.
+ * This module turns that stream into the same transport-agnostic `AgentEvent`s the
+ * ACP / opencode-server backends emit, so the PTY dispatch path can publish live
+ * broker frames + persist structured parts instead of slicing stdout opaque.
+ *
+ * Two surfaces:
+ *  - `parseStreamJsonLine(line, state)` — PURE per-line mapping (unit-testable).
+ *    `state` is the caller-owned accumulator (open tool blocks + usage/session_id).
+ *  - `makeStreamJsonParser()` — a thin stateful wrapper holding the state, with a
+ *    `push(line)` that returns the events for that line and getters for the final
+ *    `usage` / `sessionId`.
+ *
+ * Defensive by contract: a non-JSON / partial / garbage line yields `[]` and never
+ * throws. Tool args (`input_json_delta`) arrive fragmented across many lines; we
+ * accumulate the partial JSON string per content-block index and only surface the
+ * parsed `rawInput` once the block stops (or, as a fallback, off the terminal
+ * `assistant` message which carries the fully-assembled `tool_use` blocks).
+ *
+ * Schema (keyed on top-level `type`):
+ *  - `system`     — init: { session_id, tools, ... }
+ *  - `assistant`  — { message: { content: [ {type:'text'|'thinking'|'tool_use', ...} ], usage? } }
+ *  - `user`       — tool results (ignored — diffing the worktree captures effects)
+ *  - `result`     — final: { usage: { input_tokens, output_tokens }, session_id? }
+ *  - `stream_event` — { event: { type, index?, content_block?, delta?, usage? } }
+ *      event.type:
+ *        content_block_start  — { index, content_block: {type, id?, name?} }
+ *        content_block_delta  — { index, delta: {type, text?|thinking?|partial_json?} }
+ *        content_block_stop   — { index }
+ *        message_delta        — { usage: { output_tokens } }
+ *        message_start        — { message: { usage } }
+ */
+import type { AgentEvent } from './agent-backend.js';
+import type { AcpToolSnapshot } from './acp-tool-snapshot.js';
+
+/** Convenience alias for the per-line return value. */
+export type AgentEventList = AgentEvent[];
+
+export interface StreamJsonUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+}
+
+/** Per-open-content-block accumulation for tool args assembled across deltas. */
+interface OpenToolBlock {
+  toolCallId: string;
+  name: string;
+  /** Concatenated `input_json_delta.partial_json` fragments. */
+  partialJson: string;
+}
+
+export interface StreamJsonState {
+  /** content-block index → open tool block (only `tool_use` blocks are tracked). */
+  toolBlocks: Map<number, OpenToolBlock>;
+  sessionId: string | null;
+  usage: StreamJsonUsage;
+}
+
+export function makeStreamJsonState(): StreamJsonState {
+  return { toolBlocks: new Map(), sessionId: null, usage: {} };
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  return null;
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}
+
+function asNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+/** Pull token counts out of an Anthropic-shape `usage` object, mutating state. */
+function captureUsage(usage: Record<string, unknown> | null, state: StreamJsonState): void {
+  if (!usage) return;
+  const input = asNumber(usage.input_tokens);
+  const output = asNumber(usage.output_tokens);
+  if (input !== undefined) state.usage.inputTokens = input;
+  // output_tokens is reported incrementally on message_delta; keep the latest.
+  if (output !== undefined) state.usage.outputTokens = output;
+}
+
+/** Parse the accumulated tool-arg JSON; tolerate an unparseable/partial body. */
+function parseToolInput(partialJson: string): unknown {
+  const trimmed = partialJson.trim();
+  if (!trimmed) return {};
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return { _raw: partialJson };
+  }
+}
+
+function toolSnapshot(block: OpenToolBlock, rawInput: unknown, status: AcpToolSnapshot['status']): AcpToolSnapshot {
+  return {
+    toolCallId: block.toolCallId,
+    title: block.name,
+    kind: null,
+    status,
+    rawInput,
+  };
+}
+
+/**
+ * Map one stream-event sub-object (the `event` field of a `stream_event` line) to
+ * AgentEvents, mutating `state` for open tool blocks + usage.
+ */
+function handleStreamEvent(event: Record<string, unknown>, state: StreamJsonState): AgentEvent[] {
+  const eventType = asString(event.type);
+  if (!eventType) return [];
+
+  switch (eventType) {
+    case 'content_block_start': {
+      const index = asNumber(event.index);
+      const block = asRecord(event.content_block);
+      if (index === undefined || !block) return [];
+      if (asString(block.type) !== 'tool_use') return [];
+      const toolCallId = asString(block.id) ?? `tool_${index}`;
+      const name = asString(block.name) ?? 'tool';
+      const open: OpenToolBlock = { toolCallId, name, partialJson: '' };
+      state.toolBlocks.set(index, open);
+      // Surface the tool start immediately (running, no args yet) so the UI shows
+      // the call before the args finish streaming.
+      return [{ type: 'tool_call', toolCall: toolSnapshot(open, {}, 'in_progress') }];
+    }
+
+    case 'content_block_delta': {
+      const index = asNumber(event.index);
+      const delta = asRecord(event.delta);
+      if (delta === null) return [];
+      const deltaType = asString(delta.type);
+      if (deltaType === 'text_delta') {
+        const text = asString(delta.text);
+        return text ? [{ type: 'text', text }] : [];
+      }
+      if (deltaType === 'thinking_delta') {
+        const text = asString(delta.thinking);
+        return text ? [{ type: 'reasoning', text }] : [];
+      }
+      if (deltaType === 'input_json_delta') {
+        // Accumulate tool args; no event until the block stops.
+        const fragment = asString(delta.partial_json);
+        if (index !== undefined && fragment) {
+          const open = state.toolBlocks.get(index);
+          if (open) open.partialJson += fragment;
+        }
+        return [];
+      }
+      return [];
+    }
+
+    case 'content_block_stop': {
+      const index = asNumber(event.index);
+      if (index === undefined) return [];
+      const open = state.toolBlocks.get(index);
+      if (!open) return [];
+      state.toolBlocks.delete(index);
+      const rawInput = parseToolInput(open.partialJson);
+      return [{ type: 'tool_update', toolCall: toolSnapshot(open, rawInput, 'completed') }];
+    }
+
+    case 'message_start': {
+      const message = asRecord(event.message);
+      captureUsage(asRecord(message?.usage), state);
+      return [];
+    }
+
+    case 'message_delta': {
+      captureUsage(asRecord(event.usage), state);
+      return [];
+    }
+
+    default:
+      return [];
+  }
+}
+
+/**
+ * Map the terminal `assistant` message (post-hoc full message) to AgentEvents. Used
+ * as a fallback for transports that emit only the assembled `assistant` line and no
+ * incremental `stream_event`s. When stream_events already streamed a block, the
+ * caller dedups by toolCallId, so re-emitting the assembled tool_use is harmless.
+ */
+function handleAssistantMessage(message: Record<string, unknown>, state: StreamJsonState): AgentEvent[] {
+  captureUsage(asRecord(message.usage), state);
+  const content = message.content;
+  if (!Array.isArray(content)) return [];
+  const out: AgentEvent[] = [];
+  let toolIdx = 0;
+  for (const rawBlock of content) {
+    const block = asRecord(rawBlock);
+    if (!block) continue;
+    const blockType = asString(block.type);
+    if (blockType === 'text') {
+      const text = asString(block.text);
+      if (text) out.push({ type: 'text', text });
+    } else if (blockType === 'thinking') {
+      const text = asString(block.thinking);
+      if (text) out.push({ type: 'reasoning', text });
+    } else if (blockType === 'tool_use') {
+      const toolCallId = asString(block.id) ?? `tool_${toolIdx}`;
+      const name = asString(block.name) ?? 'tool';
+      const rawInput = 'input' in block ? block.input : {};
+      out.push({
+        type: 'tool_update',
+        toolCall: { toolCallId, title: name, kind: null, status: 'completed', rawInput },
+      });
+    }
+    toolIdx++;
+  }
+  return out;
+}
+
+/**
+ * Pure per-line mapping. `line` is a single complete NDJSON line (no trailing
+ * newline required; surrounding whitespace tolerated). Returns the AgentEvents the
+ * line produces and mutates `state` (open tool blocks, usage, session_id). A blank,
+ * non-JSON, or unrecognized line yields `[]` and never throws.
+ */
+export function parseStreamJsonLine(line: string, state: StreamJsonState): AgentEvent[] {
+  const trimmed = line.trim();
+  if (!trimmed) return [];
+
+  let obj: Record<string, unknown> | null;
+  try {
+    const parsed: unknown = JSON.parse(trimmed);
+    obj = asRecord(parsed);
+  } catch {
+    return [];
+  }
+  if (!obj) return [];
+
+  const type = asString(obj.type);
+  switch (type) {
+    case 'system': {
+      const sid = asString(obj.session_id);
+      if (sid) state.sessionId = sid;
+      return [];
+    }
+
+    case 'stream_event': {
+      const event = asRecord(obj.event);
+      return event ? handleStreamEvent(event, state) : [];
+    }
+
+    case 'assistant': {
+      const sid = asString(obj.session_id);
+      if (sid) state.sessionId = sid;
+      const message = asRecord(obj.message);
+      return message ? handleAssistantMessage(message, state) : [];
+    }
+
+    case 'result': {
+      const sid = asString(obj.session_id);
+      if (sid) state.sessionId = sid;
+      captureUsage(asRecord(obj.usage), state);
+      return [];
+    }
+
+    default:
+      // `user` (tool results) and any unknown line type — ignore.
+      return [];
+  }
+}
+
+export interface StreamJsonParser {
+  /** Feed one complete NDJSON line; returns its AgentEvents (never throws). */
+  push(line: string): AgentEvent[];
+  /** Final usage (input/output tokens) accumulated so far. */
+  usage(): StreamJsonUsage;
+  /** Provider session id from the init `system` line / `result`, if seen. */
+  sessionId(): string | null;
+}
+
+/**
+ * Stateful wrapper around `parseStreamJsonLine`. Holds per-tool-block accumulation
+ * + usage/session_id across the turn. Line-buffering (splitting stdout on `\n` and
+ * holding the partial tail) is the caller's job — see `pty-dispatch.ts`.
+ */
+export function makeStreamJsonParser(): StreamJsonParser {
+  const state = makeStreamJsonState();
+  return {
+    push: (line: string) => parseStreamJsonLine(line, state),
+    usage: () => ({ ...state.usage }),
+    sessionId: () => state.sessionId,
+  };
+}

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

@@ -26,9 +26,4 @@ export const WRITE_TOOLS: readonly ToolDef<any>[] = [
   checkTaskStatusTool,
 ];
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-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, newTaskTool, listTasksTool, checkTaskStatusTool };

apps/coder/src/services/worktree-risk.ts

@@ -0,0 +1,175 @@
+/**
+ * Worktree work-at-risk assessment (split out of `worktrees.ts`, v2.7 audit
+ * reshape). The git-worktree create/diff/remove lifecycle stays in `worktrees.ts`;
+ * this module owns the orthogonal "would deleting this worktree lose work?" gate
+ * the server consults before a session delete, plus the recoverable stash escape.
+ *
+ * Session delete itself lives in apps/server (Docker), which CANNOT see the host
+ * worktree dirs or run git on them — only BooCoder (host systemd) can — so the
+ * server calls the routes that wrap these helpers. Behavior is unchanged from the
+ * original worktrees.ts implementation.
+ */
+import { hostExec } from './host-exec.js';
+
+/**
+ * Risk report for a single worktree, returned by checkWorktreeWorkAtRisk.
+ * `atRisk` is the gate the server reads before allowing a session delete.
+ * A git error never silently passes — it forces `atRisk` true and surfaces
+ * the message in `error` (fail-closed).
+ */
+export interface RiskReport {
+  worktreePath: string;
+  branch: string;
+  dirty: boolean;   // uncommitted working-tree changes (incl. untracked)
+  unpushed: number; // commits ahead of upstream, or -1 if no upstream is set
+  unmerged: number; // commits on this branch not in the project default branch
+  atRisk: boolean;  // dirty || unmerged > 0 || (upstream && unpushed > 0) || git error
+  error?: string;   // populated on a git failure; presence forces atRisk
+}
+
+/**
+ * Resolve the project's default branch as a git-usable ref (e.g. "origin/main").
+ *
+ * `refs/remotes/origin/HEAD` lives in the repo's COMMON git dir and is shared
+ * across every linked worktree, so reading it from the session worktree returns
+ * the REMOTE's default branch — never this worktree's own `session-<id>` branch
+ * (that would be `symbolic-ref HEAD`, a different ref). Falls back to probing
+ * common defaults by verified existence when origin/HEAD isn't set (e.g. a repo
+ * that never ran `git remote set-head`). Returns null if none resolve, in which
+ * case the unmerged check is skipped (dirty + unpushed still protect the work).
+ */
+async function detectDefaultBranchRef(
+  worktreePath: string,
+  opts?: { signal?: AbortSignal },
+): Promise<string | null> {
+  const head = await hostExec(
+    `git -C ${shellEscape(worktreePath)} symbolic-ref --short refs/remotes/origin/HEAD`,
+    { signal: opts?.signal, timeoutMs: 10_000 },
+  );
+  if (head.exitCode === 0) {
+    const ref = head.stdout.trim(); // e.g. "origin/main"
+    if (ref) {
+      const verify = await hostExec(
+        `git -C ${shellEscape(worktreePath)} rev-parse --verify --quiet ${shellEscape(ref + '^{commit}')}`,
+        { signal: opts?.signal, timeoutMs: 10_000 },
+      );
+      if (verify.exitCode === 0 && verify.stdout.trim()) return ref;
+    }
+  }
+  // origin/HEAD unset or unresolvable — probe common defaults. Prefer the
+  // remote-tracking ref (always resolvable in a fresh worktree) over the local
+  // head, which may not exist if the default branch lives only in the main tree.
+  for (const cand of ['origin/main', 'origin/master', 'main', 'master']) {
+    const verify = await hostExec(
+      `git -C ${shellEscape(worktreePath)} rev-parse --verify --quiet ${shellEscape(cand + '^{commit}')}`,
+      { signal: opts?.signal, timeoutMs: 10_000 },
+    );
+    if (verify.exitCode === 0 && verify.stdout.trim()) return cand;
+  }
+  return null;
+}
+
+/**
+ * Inspect a worktree for work that would be lost if its session were deleted.
+ * Three checks, all via the audited hostExec + shellEscape path (every
+ * interpolated value — paths, refs — is single-quote-escaped; no bare
+ * interpolation). Any unexpected git failure is treated as at-risk, never a
+ * silent pass.
+ */
+export async function checkWorktreeWorkAtRisk(
+  worktreePath: string,
+  opts?: { signal?: AbortSignal },
+): Promise<RiskReport> {
+  // Branch name — also doubles as the "is this still a git worktree?" probe.
+  const br = await hostExec(
+    `git -C ${shellEscape(worktreePath)} rev-parse --abbrev-ref HEAD`,
+    { signal: opts?.signal, timeoutMs: 10_000 },
+  );
+  if (br.exitCode !== 0) {
+    return {
+      worktreePath,
+      branch: '',
+      dirty: false,
+      unpushed: 0,
+      unmerged: 0,
+      atRisk: true,
+      error: `git rev-parse failed: ${br.stderr.trim() || 'not a git worktree'}`,
+    };
+  }
+  const branch = br.stdout.trim();
+
+  // (a) Uncommitted (dirty working tree, including untracked files).
+  const st = await hostExec(
+    `git -C ${shellEscape(worktreePath)} status --porcelain`,
+    { signal: opts?.signal, timeoutMs: 15_000 },
+  );
+  if (st.exitCode !== 0) {
+    return {
+      worktreePath,
+      branch,
+      dirty: false,
+      unpushed: 0,
+      unmerged: 0,
+      atRisk: true,
+      error: `git status failed: ${st.stderr.trim()}`,
+    };
+  }
+  const dirty = st.stdout.trim().length > 0;
+
+  // (b) Unpushed commits. No upstream configured => work exists only locally;
+  // treat as unpushed-by-definition (-1) rather than an error.
+  const up = await hostExec(
+    `git -C ${shellEscape(worktreePath)} rev-list --count ${shellEscape('@{u}..HEAD')}`,
+    { signal: opts?.signal, timeoutMs: 15_000 },
+  );
+  const unpushed = up.exitCode === 0 ? (parseInt(up.stdout.trim() || '0', 10) || 0) : -1;
+
+  // (c) Unmerged commits — on this branch but not in the project default branch.
+  const defaultRef = await detectDefaultBranchRef(worktreePath, opts);
+  let unmerged = 0;
+  if (defaultRef) {
+    const rl = await hostExec(
+      `git -C ${shellEscape(worktreePath)} rev-list --count ${shellEscape(defaultRef + '..HEAD')}`,
+      { signal: opts?.signal, timeoutMs: 15_000 },
+    );
+    if (rl.exitCode === 0) unmerged = parseInt(rl.stdout.trim() || '0', 10) || 0;
+  }
+
+  // unpushed only contributes when an upstream actually exists. Session branches
+  // (session-<id>) never have one (unpushed === -1), and any real local-only work
+  // there already surfaces as unmerged > 0 — so the no-upstream case adds no
+  // protection, only friction (it flagged every pristine worktree-backed session).
+  // The unpushed > 0 arm stays forward-compatible with P1.5 pushable branches.
+  const hasUpstream = unpushed !== -1;
+  const atRisk = dirty || unmerged > 0 || (hasUpstream && unpushed > 0);
+  return { worktreePath, branch, dirty, unpushed, unmerged, atRisk };
+}
+
+/**
+ * Stash a worktree's uncommitted changes (including untracked, via -u) so the
+ * working tree is clean. Stash entries live in the repo's common git dir, so
+ * they survive worktree-dir removal — this is the recoverable, safe-by-default
+ * escape. Note it only clears the *dirty* risk; unpushed/unmerged commits
+ * remain on the branch, so a re-attempted delete may still block on those.
+ */
+export async function stashWorktree(
+  worktreePath: string,
+  opts?: { signal?: AbortSignal },
+): Promise<{ stashed: boolean; error?: string }> {
+  const r = await hostExec(
+    `git -C ${shellEscape(worktreePath)} stash push -u -m ${shellEscape('boocode: pre-delete stash')}`,
+    { signal: opts?.signal, timeoutMs: 30_000 },
+  );
+  if (r.exitCode !== 0) {
+    return { stashed: false, error: r.stderr.trim() || r.stdout.trim() };
+  }
+  // "No local changes to save" => exit 0, nothing stashed — not an error.
+  const stashed = !/no local changes to save/i.test(r.stdout);
+  return { stashed };
+}
+
+/** 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, "'\\''") + "'";
+}

apps/coder/src/services/worktrees.ts

@@ -8,8 +8,9 @@
  */
 import type { Sql } from '../db.js';
 import { hostExec } from './host-exec.js';
+import { checkWorktreeWorkAtRisk } from './worktree-risk.js';
 
-const WORKTREE_BASE = '/tmp/booworktrees';
+export const WORKTREE_BASE = '/tmp/booworktrees';
 
 /**
  * Create a git worktree for a task on the host.
@@ -197,163 +198,185 @@ export async function ensureSessionWorktree(
   };
 }
 
-// ─── Session-delete work-loss guard ─────────────────────────────────────────
-
 /**
- * Risk report for a single worktree, returned by checkWorktreeWorkAtRisk.
- * `atRisk` is the gate the server reads before allowing a session delete.
- * A git error never silently passes — it forces `atRisk` true and surfaces
- * the message in `error` (fail-closed).
+ * v2.6 Phase 3 (3.3 / 3.4): physically remove a session's persistent worktree —
+ * the git worktree dir + its branch — and archive its `worktrees` row. Used by the
+ * chat/session-close hook (when the last chat in a session closes) and the orphan
+ * reaper. Best-effort on the git side (a dir already gone is not an error); the DB
+ * row is flipped to 'archived' (soft-delete, Paseo's worktree-archive pattern) so
+ * history/attribution survives and a re-run is idempotent.
+ *
+ * SAFETY: callers MUST run `checkWorktreeWorkAtRisk` first and skip at-risk
+ * worktrees — this function force-removes (`--force`), so it never silently drops
+ * uncommitted/unmerged work unless the caller already cleared/accepted the risk.
  */
-export interface RiskReport {
-  worktreePath: string;
-  branch: string;
-  dirty: boolean;   // uncommitted working-tree changes (incl. untracked)
-  unpushed: number; // commits ahead of upstream, or -1 if no upstream is set
-  unmerged: number; // commits on this branch not in the project default branch
-  atRisk: boolean;  // dirty || unmerged > 0 || (upstream && unpushed > 0) || git error
-  error?: string;   // populated on a git failure; presence forces atRisk
+export async function removeSessionWorktree(
+  sql: Sql,
+  projectPath: string,
+  worktree: { id: string; path: string; branch?: string | null },
+  opts?: { signal?: AbortSignal },
+): Promise<void> {
+  await hostExec(
+    `git -C ${shellEscape(projectPath)} worktree remove ${shellEscape(worktree.path)} --force`,
+    { signal: opts?.signal, timeoutMs: 15_000 },
+  ).catch(() => {});
+  const branch = worktree.branch ?? null;
+  if (branch) {
+    await hostExec(
+      `git -C ${shellEscape(projectPath)} branch -D ${shellEscape(branch)}`,
+      { signal: opts?.signal, timeoutMs: 10_000 },
+    ).catch(() => {});
+  }
+  // Prune any stale worktree administrative entries left behind by a partial remove.
+  await hostExec(
+    `git -C ${shellEscape(projectPath)} worktree prune`,
+    { signal: opts?.signal, timeoutMs: 10_000 },
+  ).catch(() => {});
+  await sql`UPDATE worktrees SET status = 'archived' WHERE id = ${worktree.id}`.catch(() => {});
 }
 
 /**
- * Resolve the project's default branch as a git-usable ref (e.g. "origin/main").
+ * v2.6 Phase 3 (3.3): the chat-close cleanup. Mark every `agent_sessions` row for
+ * the chat 'closed', then — only if this was the session's LAST open chat — remove
+ * the shared session worktree (a worktree is one-per-session, shared across the
+ * session's chat tabs, so closing one tab must not pull the rug from sibling tabs).
  *
- * `refs/remotes/origin/HEAD` lives in the repo's COMMON git dir and is shared
- * across every linked worktree, so reading it from the session worktree returns
- * the REMOTE's default branch — never this worktree's own `session-<id>` branch
- * (that would be `symbolic-ref HEAD`, a different ref). Falls back to probing
- * common defaults by verified existence when origin/HEAD isn't set (e.g. a repo
- * that never ran `git remote set-head`). Returns null if none resolve, in which
- * case the unmerged check is skipped (dirty + unpushed still protect the work).
+ * Returns what it did so the route can report it. The actual backend (process /
+ * server-session) teardown is the pool's job (`agentPool.closeChat` +
+ * `backend.closeSession`); this owns the DB + git truth.
+ *
+ * `worktreeRemoved` is false when other open chats remain (worktree kept) OR when
+ * the worktree held work at risk (preflight blocked it — never silently dropped).
  */
-async function detectDefaultBranchRef(
-  worktreePath: string,
-  opts?: { signal?: AbortSignal },
-): Promise<string | null> {
-  const head = await hostExec(
-    `git -C ${shellEscape(worktreePath)} symbolic-ref --short refs/remotes/origin/HEAD`,
-    { signal: opts?.signal, timeoutMs: 10_000 },
-  );
-  if (head.exitCode === 0) {
-    const ref = head.stdout.trim(); // e.g. "origin/main"
-    if (ref) {
-      const verify = await hostExec(
-        `git -C ${shellEscape(worktreePath)} rev-parse --verify --quiet ${shellEscape(ref + '^{commit}')}`,
-        { signal: opts?.signal, timeoutMs: 10_000 },
-      );
-      if (verify.exitCode === 0 && verify.stdout.trim()) return ref;
+export interface ChatCloseResult {
+  agentRowsClosed: number;
+  worktreeRemoved: boolean;
+  worktreeAtRisk: boolean;
+}
+
+export async function closeChatBackendState(
+  sql: Sql,
+  chatId: string,
+  opts?: { signal?: AbortSignal; force?: boolean },
+): Promise<ChatCloseResult> {
+  // Resolve the chat's session (and that session's project path) before we touch
+  // anything — a deleted chat row leaves agent_sessions/worktrees pointing nowhere.
+  const [chatRow] = await sql<{ session_id: string | null }[]>`
+    SELECT session_id FROM chats WHERE id = ${chatId}
+  `;
+  // chat row may already be gone (delete fired first); fall back to agent_sessions'
+  // session_id link, which SET NULLs only on session delete, not chat delete.
+  let sessionId = chatRow?.session_id ?? null;
+  if (!sessionId) {
+    const [as] = await sql<{ session_id: string | null }[]>`
+      SELECT session_id FROM agent_sessions WHERE chat_id = ${chatId} AND session_id IS NOT NULL LIMIT 1
+    `;
+    sessionId = as?.session_id ?? null;
+  }
+
+  // Mark this chat's (chat,agent) backend rows closed (idempotent).
+  const closedRows = await sql<{ agent: string }[]>`
+    UPDATE agent_sessions SET status = 'closed'
+    WHERE chat_id = ${chatId} AND status <> 'closed'
+    RETURNING agent
+  `;
+
+  let worktreeRemoved = false;
+  let worktreeAtRisk = false;
+
+  if (sessionId) {
+    // Other open chats still sharing the session worktree? If so, keep it.
+    const openRows = await sql<{ open_count: number }[]>`
+      SELECT COUNT(*)::int AS open_count FROM chats
+      WHERE session_id = ${sessionId} AND status = 'open' AND id <> ${chatId}
+    `;
+    const openCount = openRows[0]?.open_count ?? 0;
+    if (openCount === 0) {
+      const [wt] = await sql<{ id: string; path: string; branch: string | null }[]>`
+        SELECT id, path, branch FROM worktrees
+        WHERE session_id = ${sessionId} AND status = 'active' LIMIT 1
+      `;
+      if (wt) {
+        const projRows = await sql<{ path: string | null }[]>`
+          SELECT p.path FROM sessions s JOIN projects p ON p.id = s.project_id WHERE s.id = ${sessionId}
+        `;
+        const projectPath = projRows[0]?.path ?? null;
+        // Preflight (close-hook semantics): a DELIBERATE chat/session close — the
+        // server's session-delete already ran the full work-at-risk gate
+        // (dirty/unpushed/unmerged) before calling us, and chat-close discards the
+        // tab's staged review intentionally. So here we only block on UNCOMMITTED
+        // working-tree changes (`dirty`) — work the user never even staged into the
+        // review diff. The session branch's own commits (the diff-staging
+        // mechanism) are NOT a block; treating them as "unmerged risk" would make
+        // the worktree un-removable on every real session (the orphan reaper keeps
+        // the full at-risk gate because it runs unattended). `force` skips this.
+        if (!opts?.force) {
+          const risk = await checkWorktreeWorkAtRisk(wt.path, opts);
+          worktreeAtRisk = risk.dirty || risk.error != null;
+        }
+        if (projectPath && (opts?.force || !worktreeAtRisk)) {
+          await removeSessionWorktree(sql, projectPath, wt, opts);
+          worktreeRemoved = true;
+        }
+      }
     }
   }
-  // origin/HEAD unset or unresolvable — probe common defaults. Prefer the
-  // remote-tracking ref (always resolvable in a fresh worktree) over the local
-  // head, which may not exist if the default branch lives only in the main tree.
-  for (const cand of ['origin/main', 'origin/master', 'main', 'master']) {
-    const verify = await hostExec(
-      `git -C ${shellEscape(worktreePath)} rev-parse --verify --quiet ${shellEscape(cand + '^{commit}')}`,
-      { signal: opts?.signal, timeoutMs: 10_000 },
-    );
-    if (verify.exitCode === 0 && verify.stdout.trim()) return cand;
-  }
-  return null;
+
+  return { agentRowsClosed: closedRows.length, worktreeRemoved, worktreeAtRisk };
 }
 
 /**
- * Inspect a worktree for work that would be lost if its session were deleted.
- * Three checks, all via the audited hostExec + shellEscape path (every
- * interpolated value — paths, refs — is single-quote-escaped; no bare
- * interpolation). Any unexpected git failure is treated as at-risk, never a
- * silent pass.
+ * v2.6 Phase 3 (3.5): re-baseline a session's worktree diff after a successful
+ * `apply_pending`. The applied changes were written to the PROJECT ROOT; the
+ * worktree branch still holds the same delta against the ORIGINAL `base_commit`,
+ * so the next turn's `diffWorktree(base_commit...worktree-HEAD)` would re-surface
+ * the already-applied changes as "pending" — a confusing double-count.
+ *
+ * Fix: advance the stored `base_commit` to the worktree's CURRENT HEAD (the
+ * `diffWorktree` path commits the worktree's accumulated changes before diffing,
+ * so HEAD already encodes the applied state). The next turn then diffs against
+ * that, surfacing only edits made AFTER the apply. Idempotent: if the worktree has
+ * no new commits, the base is unchanged.
+ *
+ * Diff-baseline-correctness note (design §7): we re-baseline to the worktree's own
+ * HEAD, NOT to a moving project HEAD — so an out-of-band edit to the project root
+ * after apply doesn't corrupt the baseline. The trade-off is that a manual project
+ * edit isn't reflected as "already there"; acceptable, and matches the stored-base
+ * (not moving-target) decision in §7.
  */
-export async function checkWorktreeWorkAtRisk(
-  worktreePath: string,
+export async function rebaselineWorktreeAfterApply(
+  sql: Sql,
+  sessionId: string,
   opts?: { signal?: AbortSignal },
-): Promise<RiskReport> {
-  // Branch name — also doubles as the "is this still a git worktree?" probe.
-  const br = await hostExec(
-    `git -C ${shellEscape(worktreePath)} rev-parse --abbrev-ref HEAD`,
+): Promise<{ rebaselined: boolean; newBaseCommit: string | null }> {
+  const [wt] = await sql<{ id: string; path: string; base_commit: string | null }[]>`
+    SELECT id, path, base_commit FROM worktrees
+    WHERE session_id = ${sessionId} AND status = 'active' LIMIT 1
+  `;
+  if (!wt) return { rebaselined: false, newBaseCommit: null };
+
+  // Make sure the worktree's accumulated edits are committed so HEAD encodes the
+  // just-applied state (the diff path normally does this, but apply may run with no
+  // prior diff this turn). Commit ONLY when something is staged — NO --allow-empty,
+  // so a re-baseline with no new edits doesn't advance HEAD and stays idempotent.
+  await hostExec(
+    `cd ${shellEscape(wt.path)} && git add -A && ` +
+      `git diff --cached --quiet || ` +
+      `git -c user.email=boocoder@local -c user.name=BooCoder commit -q -m "rebaseline after apply"`,
+    { signal: opts?.signal, timeoutMs: 15_000 },
+  ).catch(() => {});
+
+  const headRes = await hostExec(
+    `git -C ${shellEscape(wt.path)} rev-parse HEAD`,
     { signal: opts?.signal, timeoutMs: 10_000 },
-  );
-  if (br.exitCode !== 0) {
-    return {
-      worktreePath,
-      branch: '',
-      dirty: false,
-      unpushed: 0,
-      unmerged: 0,
-      atRisk: true,
-      error: `git rev-parse failed: ${br.stderr.trim() || 'not a git worktree'}`,
-    };
-  }
-  const branch = br.stdout.trim();
-
-  // (a) Uncommitted (dirty working tree, including untracked files).
-  const st = await hostExec(
-    `git -C ${shellEscape(worktreePath)} status --porcelain`,
-    { signal: opts?.signal, timeoutMs: 15_000 },
-  );
-  if (st.exitCode !== 0) {
-    return {
-      worktreePath,
-      branch,
-      dirty: false,
-      unpushed: 0,
-      unmerged: 0,
-      atRisk: true,
-      error: `git status failed: ${st.stderr.trim()}`,
-    };
-  }
-  const dirty = st.stdout.trim().length > 0;
-
-  // (b) Unpushed commits. No upstream configured => work exists only locally;
-  // treat as unpushed-by-definition (-1) rather than an error.
-  const up = await hostExec(
-    `git -C ${shellEscape(worktreePath)} rev-list --count ${shellEscape('@{u}..HEAD')}`,
-    { signal: opts?.signal, timeoutMs: 15_000 },
-  );
-  const unpushed = up.exitCode === 0 ? (parseInt(up.stdout.trim() || '0', 10) || 0) : -1;
-
-  // (c) Unmerged commits — on this branch but not in the project default branch.
-  const defaultRef = await detectDefaultBranchRef(worktreePath, opts);
-  let unmerged = 0;
-  if (defaultRef) {
-    const rl = await hostExec(
-      `git -C ${shellEscape(worktreePath)} rev-list --count ${shellEscape(defaultRef + '..HEAD')}`,
-      { signal: opts?.signal, timeoutMs: 15_000 },
-    );
-    if (rl.exitCode === 0) unmerged = parseInt(rl.stdout.trim() || '0', 10) || 0;
+  ).catch(() => null);
+  const newBase = headRes && headRes.exitCode === 0 ? headRes.stdout.trim() || null : null;
+  if (!newBase || newBase === wt.base_commit) {
+    return { rebaselined: false, newBaseCommit: wt.base_commit };
   }
 
-  // unpushed only contributes when an upstream actually exists. Session branches
-  // (session-<id>) never have one (unpushed === -1), and any real local-only work
-  // there already surfaces as unmerged > 0 — so the no-upstream case adds no
-  // protection, only friction (it flagged every pristine worktree-backed session).
-  // The unpushed > 0 arm stays forward-compatible with P1.5 pushable branches.
-  const hasUpstream = unpushed !== -1;
-  const atRisk = dirty || unmerged > 0 || (hasUpstream && unpushed > 0);
-  return { worktreePath, branch, dirty, unpushed, unmerged, atRisk };
-}
-
-/**
- * Stash a worktree's uncommitted changes (including untracked, via -u) so the
- * working tree is clean. Stash entries live in the repo's common git dir, so
- * they survive worktree-dir removal — this is the recoverable, safe-by-default
- * escape. Note it only clears the *dirty* risk; unpushed/unmerged commits
- * remain on the branch, so a re-attempted delete may still block on those.
- */
-export async function stashWorktree(
-  worktreePath: string,
-  opts?: { signal?: AbortSignal },
-): Promise<{ stashed: boolean; error?: string }> {
-  const r = await hostExec(
-    `git -C ${shellEscape(worktreePath)} stash push -u -m ${shellEscape('boocode: pre-delete stash')}`,
-    { signal: opts?.signal, timeoutMs: 30_000 },
-  );
-  if (r.exitCode !== 0) {
-    return { stashed: false, error: r.stderr.trim() || r.stdout.trim() };
-  }
-  // "No local changes to save" => exit 0, nothing stashed — not an error.
-  const stashed = !/no local changes to save/i.test(r.stdout);
-  return { stashed };
+  await sql`UPDATE worktrees SET base_commit = ${newBase} WHERE id = ${wt.id}`;
+  return { rebaselined: true, newBaseCommit: newBase };
 }
 
 /** Minimal shell escape for paths (single-quote wrapping). */

apps/coder/vitest.config.ts

@@ -5,5 +5,11 @@ export default defineConfig({
     environment: 'node',
     globals: false,
     include: ['src/**/__tests__/**/*.test.ts'],
+    // DB-integration suites (checkpoints, claude-session-store, reconnect, etc.)
+    // each apply the full schema in beforeAll against the one shared dev DB; running
+    // test files in parallel makes those concurrent DDL applies deadlock under
+    // DATABASE_URL. Serialize file execution — the suites are fast, so the cost is
+    // negligible and the default (no-DATABASE_URL) run is unaffected.
+    fileParallelism: false,
   },
 });

apps/coder/web/vite.config.d.ts

@@ -1,2 +0,0 @@
-declare const _default: import("vite").UserConfig;
-export default _default;

apps/coder/web/vite.config.js

@@ -1,25 +0,0 @@
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react';
-import path from 'node:path';
-export default defineConfig({
-    plugins: [react()],
-    resolve: {
-        alias: {
-            '@': path.resolve(__dirname, './src'),
-        },
-    },
-    server: {
-        port: 5174,
-        proxy: {
-            '/api': {
-                target: 'http://127.0.0.1:3000',
-                changeOrigin: true,
-                ws: true,
-            },
-        },
-    },
-    build: {
-        outDir: 'dist',
-        emptyOutDir: true,
-    },
-});

apps/server/CLAUDE.md

@@ -0,0 +1,48 @@
+# apps/server — BooChat backend (deep reference)
+
+> Per-app engineering notes for `apps/server/src/`. Cross-cutting commands, database, environment, workflow, and cross-app contracts (WS-frame / provider-type parity, sentinels) live in the **root `CLAUDE.md`**. This file auto-loads when you read/edit files under `apps/server/`.
+
+## Stack
+
+- **Fastify** with `@fastify/websocket` and `@fastify/static` (serves the built frontend).
+- **postgres** (porsager/postgres) with tagged-template SQL — no ORM. Schema in `schema.sql`, applied on startup. LSP may false-positive on `sql<Type[]>\`...\`` generics; CLI `tsc` / `pnpm build` is authoritative.
+- **Zod** for request validation and config parsing.
+
+## Key services
+
+- **`services/inference/`** — Public surface re-exported via `inference/index.ts`; callers import from `./services/inference/index.js` explicitly (NodeNext doesn't honor directory-index resolution). Layout: `turn.ts` (runAssistantTurn/runInference/createInferenceRunner; exports `InferenceFrame`, `InferenceContext`, `TurnArgs`, `StreamResult`, `MAX_STEPS`); `stream-phase.ts` (streamCompletion AI SDK adapter + executeStreamPhase); `provider.ts` (`upstreamModel(baseURL, modelId)` wrapping `createOpenAICompatible` against llama-swap); `tool-phase.ts` (executeToolPhase → `ToolPhaseResult`; the turn loop lives in turn.ts, not recursion); `sentinel-summaries.ts` (cap-hit/doom-loop/step-cap summaries + inserters); `error-handler.ts` (handleAbortOrError, finalizeCompletion); `payload.ts` (buildMessagesPayload, loadContext, maybeFlagForCompaction, `OpenAiMessage`); `sentinels.ts` (`detectDoomLoop`, `DOOM_LOOP_THRESHOLD`); `budget.ts` (resolveToolBudget); `xml-parser.ts` (qwen3.6 XML tool-call fallback — KEEP, AI SDK doesn't handle inline-XML tool calls); `parts.ts` (`partsFromAssistantMessage`/`partsFromToolMessage`/`insertParts` — parts are the sole source of truth); `prune.ts` (two-tier compaction; `selectPruneTargets` is the pure helper); `types.ts` (`StreamPhaseState`, `DB_FLUSH_INTERVAL_MS`). **`TurnArgs`** is the per-turn state envelope, reset in `runInference` at the user-message boundary. Outer loop: `while (stepNumber < effectiveCap)`, `effectiveCap = Math.min(agent.steps ?? Infinity, MAX_STEPS=200)`. Per-agent `steps:` in AGENTS.md frontmatter; `steps: 0` = text-only. Step-cap hit writes a `cap_hit` sentinel (`CapHitSentinel.tsx` renders it).
+- **AI SDK v6 streamCompletion adapter** (`services/inference/stream-phase.ts`). `streamText` is the underlying call; the BooCode layer (executeStreamPhase, finalize, dual-write) is shape-preserved via an adapter. Five gotchas the LSP/tests won't catch:
+  - **Abort signals are swallowed.** `streamText`'s `fullStream` exits cleanly when `abortSignal` fires — no throw. Post-iteration `if (signal?.aborted) throw <AbortError>` is required, else the row finalizes `complete` instead of `cancelled`. Don't refactor away the pinning comment.
+  - **Usage lands only at stream end** via `await result.usage` (v6 `inputTokens`/`outputTokens` → mapped to `promptTokens`/`completionTokens`). No mid-stream tok/s; ChatThroughput shows one value at stream end.
+  - **Tools have NO `execute` field.** BooCode dispatches tools in tool-phase.ts, not the AI SDK loop — only `description` + `inputSchema: jsonSchema(parameters)`.
+  - **`includeUsage: true` MUST be set on `createOpenAICompatible`** in `provider.ts`. The adapter defaults it false → no `stream_options.include_usage` → llama-swap emits no usage block → `result.usage` resolves `undefined` (NULL token counts). Don't remove during refactor.
+  - **Tool-call-only turns may emit a leading `\n` text-delta.** `MessageList.flatten`'s `hasText` and `MessageBubble`'s `hasContent` both `.trim()` before the length check, else whitespace-only content renders an empty bubble + ActionRow between tool calls. `buildMessagesPayload` also skips `status='failed'` and complete-but-empty assistant rows (avoids "Cannot have 2 or more assistant messages at the end of the list" upstream rejection after cap-hit + Continue).
+- **AI SDK ModelMessage conversion** (`toModelMessages` in stream-phase.ts). Tool messages need a `toolName` for `ToolResultPart`; BooCode's OpenAI-shape history lacks it, so a forward-scan builds a `tool_call_id → toolName` map from prior assistant `tool_calls`. Tool outputs wrapped as `{ type: 'json' | 'text', value }` (v6 `ToolResultOutput`). Reasoning emits a `ReasoningPart` first in the content array.
+- **`experimental_repairToolCall`** wired into `streamText` to keep the stream alive when qwen3.6 emits malformed tool args. Pass-through: logs the bad call, returns it unmodified; `executeToolPhase`'s zod-reject path routes it back to the model next turn.
+- **`chat_status` frame** (via `broker.publishUser`) — `status: 'streaming' | 'tool_running' | 'waiting_for_input' | 'idle' | 'error'`. Frontend `useChatStatus` derives `idle_warm` (<30s since idle) vs `idle_cold`. `ChatThroughput` renders beside `StatusDot` only when streaming/tool_running, fed by 500ms-throttled `'usage'` frames (`completion_tokens` + `ctx_used` + `ctx_max`). `POST /api/chats/:id/discard_stale` marks a stuck-streaming row `failed` when the frontend's 60s no-token timer gives up.
+- **Stale-streaming sweeps** (`apps/server/src/index.ts`): a boot-time pass after `applySchema()` and a periodic 60s `setInterval` both flip `messages.status='streaming'` older than 5 min to `failed` (publishing `chat_status='idle'`); the interval also runs `cleanupTruncations` (TTL + orphan reap of tmpfs truncation files). `onClose` hook clears the timer. Recovers from a container restart mid-stream.
+- **`services/broker.ts`** — In-memory pub/sub, two channel types: per-session (message streaming) and per-user (sidebar). No persistence; clients reconnect on restart. Every WS publish goes through `broker.publishFrame(sessionId, frame)` / `publishUserFrame(user, frame)` — both Zod-validate against `WsFrameSchema` (`types/ws-frames.ts`) and fail-closed (log + drop). Schema duplicated byte-identical at `apps/web/src/api/ws-frames.ts`; `ws-frames.test.ts` enforces parity. Don't add raw `broker.publish()`/`publishUser()` calls.
+- **`services/tools.ts`** — Tool registry (`ALL_TOOLS`, `READ_ONLY_TOOL_NAMES`, `TOOLS_BY_NAME`). Filesystem tools (view_file/list_dir/grep/find_files) pass three guards: `path_guard.ts` (workspace scope), `secret_guard.ts` (filename deny list), `url_guard.ts` (SSRF/private-IP block for web_fetch). Web tools (`web_search`, `web_fetch`) are opt-in per chat via `session.web_search_enabled` (falls back to `project.default_web_search_enabled`) and filtered out of the LLM tool schema when false. Truncation: when a tool slice cuts content, `services/truncate.ts` stashes the full text on tmpfs (`BOOCODE_TRUNCATION_DIR`, default `/tmp/boocode-truncations`, 0o700) keyed by `tr_<12 base32>`; `view_truncated_output(id)` retrieves it. 5MB cap, 7-day TTL, reaped by the sweeper. Container restart loses retrieval — acceptable.
+- **`services/compaction.ts`** + **`services/model-context.ts`** — Anchored rolling summary (single `summary=true` assistant row per chat, supersedes itself each compaction). Triggered when `chats.needs_compaction` is set after a turn exceeds `usable(ctx_max) = floor(0.85 × ctx_max)`. **`ctx_max` comes from `model-context.getModelContext()` fetching `${LLAMA_SWAP_URL}/upstream/<model>/props`** — NOT from `parsed.timings.n_ctx`. First inferences after boot may have `ctx_max=NULL` if llama-swap hasn't loaded the model; negative cache TTL 60s, recovers next turn. `buildHeadPayload` embeds `reasoning_parts` as a `<reasoning>...</reasoning>` prose prefix on assistant `content` (OpenAI wire shape has no structured reasoning field); standalone tag when content is empty. `buildHeadPayload` + `OpenAiMessage` exported for tests — keep them exported.
+- **`services/system-prompt.ts`** — `buildSystemPrompt` is the string shim; `buildSystemPromptWithFingerprint` is the canonical impl returning `{prompt, fingerprint, drift}`. SHA-256 of the assembled prefix is logged per `buildMessagesPayload` (`prefix-fingerprint`, info); a `Map<sessionId, lastHash>` fires `prefix-drift` (warn) on change with a `changed_inputs` diff. The prefix is byte-stable in steady-state, so prefix caching is left to the input-layer mtime caches (BOOCHAT.md + AGENTS.md global/per-project in `agents.ts:safeStat`).
+- **`services/inference/budget.ts`** — tool-call budgets: `BUDGET_READ_ONLY = 30`, `BUDGET_NON_READ_ONLY = 10` (forward-looking; no write tools yet), `BUDGET_NO_AGENT = 30` (every `ALL_TOOLS` tool is read-only today, so no-agent shares the read-only cap). Per-agent `max_tool_calls` from AGENTS.md overrides.
+- **`messages_with_parts` view** (`schema.sql`). Read sites needing `tool_calls` / `tool_results` / `reasoning_parts` SELECT from this view, NOT `messages` — the legacy `messages.tool_calls`/`tool_results` JSON columns were dropped; the view reads parts-only subselects. Writes target `message_parts` via `insertParts` (or `partsFromAssistantMessage`/`partsFromToolMessage`). The `Message` wire type still carries `tool_calls?`/`tool_results?` because the view synthesizes them. Shapes: `tool_calls jsonb[]`, `tool_results jsonb` (single object), `reasoning_parts jsonb[]` of `{text}`. To UPDATE a message and return its full shape, do a two-step UPDATE returning `id` then SELECT from the view — RETURNING off bare `messages` no longer carries the tool fields. **`messages.model`** (attribution chip) stamps the model per assistant turn — at `finalizeCompletion` (BooChat + native coder) + the dispatcher's assistant-row INSERT (external coder); read via the view + the `message_complete` frame, rendered by `shortenModelName`.
+- **`services/file_ops.ts`** — Shared file operation implementations used by both inference tools and HTTP routes.
+- **`services/auto_name.ts`** — Non-streaming LLM call to generate 4-word session titles after the first assistant reply.
+- **Provider picker dispatch**: when `provider !== 'boocode'`, the message route creates a `tasks` row (with `session_id` set) instead of calling `inference.enqueue`. The dispatcher (in `apps/coder`) picks it up and dispatches via ACP or PTY using the agent's `install_path`.
+
+Route registration: all routes registered in `index.ts` via `register*Routes(app, sql, ...)`. Routes live in `routes/*.ts`.
+
+## Server conventions
+
+- **New tools** live in their own `services/<name>.ts` (see `web_search.ts`, `web_fetch.ts`) — a pure `executeFoo(input, ...deps)` for direct test access plus a `ToolDef` wrapper that `loadConfig()`s its real deps. Register the ToolDef in `tools.ts` `ALL_TOOLS` (and `READ_ONLY_TOOL_NAMES` if applicable). Inject `fetcher: typeof fetch = fetch` rather than `vi.spyOn(globalThis, 'fetch')`.
+- **DB/session-aware tools** take an optional 4th `ToolExecCtx { sql, sessionId }` arg on `ToolDef.execute`, plumbed `executeToolPhase`→`executeToolCall`→`execute`. Optional so filesystem tools and the `apps/coder` `ALL_TOOLS` consumer stay compatible; filesystem tools ignore it. `read_tab_by_number` is the reference.
+- **ReadableStream test stubs** use `pull()` (not `start()`) so chunks are produced lazily — `start()` enqueues everything and closes before the consumer reads, so a later `reader.cancel()` finds the stream closed and the `cancel()` callback never fires. Provide MORE chunks than the test consumes so the source stays 'readable' when cancel runs.
+- Tool-name whitelists must derive from `ALL_TOOLS` in `services/tools.ts`, never hardcoded (this drift class hit `services/agents.ts` `ALL_TOOL_NAMES` before).
+- Agent registry lives at `data/AGENTS.md` (global, bind-mounted at `/data/AGENTS.md`). No per-project `AGENTS.md` in this repo (removed to eliminate two-files-must-stay-in-sync drift); the `getAgentsForProject` per-project override mechanism remains for *other* projects.
+- `data/AGENTS.md` is PARSED (`agents.ts` `splitSections`/`parseAgentSection`): each `## <Name>` is one agent and must be followed by a `---` frontmatter fence or the block throws; content before the first `## ` is discarded. Do NOT add free-form `## ` rule sections — they break the registry. Cross-cutting agent rules go in CLAUDE.md or a parser-ignored preamble.
+- MCP stdio transport uses newline-delimited JSON (NDJSON), NOT LSP-style `Content-Length` headers. `codecontext/shim.go` is the reference (per the MCP spec, modelcontextprotocol.io/specification/server/transports).
+- **`payload.ts:loadContext` SELECT** must include every `Session` field downstream code reads. The tool phase reads `session.allowed_read_paths`; if the SELECT omits it, cross-repo read grants silently fail. `sql<Session[]>` doesn't enforce column coverage, so the type doesn't catch it.
+- **Sidecar routing** (`services/inference/provider.ts`): `upstreamModel(config, modelId, agent)` routes to `LLAMA_SIDECAR_URL` when the agent has `llama_extra_args`, else `LLAMA_SWAP_URL`. `resolveRoute(agent)` returns `{route, flags}`. Sidecar provider created fresh per call (not cached) because `X-Agent-Flags` varies per agent. Boot-time guard in `index.ts` refuses to start if any agent has `llama_extra_args` but `LLAMA_SIDECAR_URL` is unset.
+- **Secret guard safe patterns** (`services/secret_guard.ts`): `.env.example`, `.env.sample`, `.env.template`, `.env.defaults` are allowlisted via `SAFE_PATTERNS`. Do NOT add `.env.production`/`.env.development`/`.env.test` — those can hold real secrets.
+- **llama-sidecar** (`/opt/forks/llama-sidecar/`): Go daemon for a per-agent llama-server process pool (routed to via "Sidecar routing" above). Cross-compile: `GOOS=windows GOARCH=amd64 /snap/go/current/bin/go build -o bin/llama-sidecar.exe ./cmd/llama-sidecar`. Gitea: `indifferentketchup/llama-sidecar`. Windows child-process gotchas: `context.Background()` for child lifetime (not request ctx), `os.Open(os.DevNull)` for stdin, `os.Pipe()` for stdout with a drain goroutine, `DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP` flags. SSH to sam-desktop: `ssh samki@100.101.41.16`; use `schtasks` for persistent spawning (SSH `start /B` doesn't survive session close).

apps/server/package.json

@@ -87,7 +87,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "ai": "^6.0.190",
     "fastify": "^4.28.1",
-    "parse5": "^8.0.1",
+    "node-html-markdown": "^1.3.0",
     "postgres": "^3.4.4",
     "ws": "^8.18.0",
     "zod": "^3.23.8"
@@ -99,5 +99,5 @@
     "typescript": "^5.5.0",
     "vitest": "^3.2.4"
   },
-  "license": "AGPL-3.0-only"
+  "license": "MIT"
 }

apps/server/src/config.ts

@@ -18,7 +18,6 @@ const ConfigSchema = z.object({
   GITEA_BASE_URL: z.string().url().default('https://git.indifferentketchup.com'),
   GITEA_USER: z.string().default('indifferentketchup'),
   GITEA_TOKEN: z.string().optional(),
-  GITEA_SSH_HOST: z.string().default('100.114.205.53:2222'),
   // v1.15.0-mcp-multi: path to the MCP config JSON file. Default /data/mcp.json
   // (bind-mounted alongside AGENTS.md). File missing = no MCP (opt-in).
   MCP_CONFIG_PATH: z.string().optional(),

apps/server/src/routes/chats.ts

@@ -4,6 +4,8 @@ import type { Sql } from '../db.js';
 import type { Broker } from '../services/broker.js';
 import type { Chat, Message } from '../types/api.js';
 import { getModelContext } from '../services/model-context.js';
+import { notifyCoderClose } from '../services/coder-notify.js';
+import { MESSAGE_COLUMNS } from '../services/message-columns.js';
 
 const CreateBody = z.object({
   name: z.string().min(1).max(200).optional(),
@@ -167,6 +169,9 @@ export function registerChatRoutes(
           chat_id: id,
           session_id: req.params.id,
         });
+        // Fire-and-forget per archived chat: tear down its warm agent backends
+        // on the coder. Best-effort — never blocks/fails the bulk archive.
+        void notifyCoderClose('chat', id, req.log);
       }
       return { archived: ids.length, ids };
     }
@@ -208,6 +213,9 @@ export function registerChatRoutes(
         chat_id: row.id,
         session_id: row.session_id,
       });
+      // Fire-and-forget: tear down this chat's warm agent backends + (last-chat)
+      // worktree on the coder. Best-effort — never blocks/fails the archive.
+      void notifyCoderClose('chat', row.id, req.log);
       reply.code(204);
       return null;
     }
@@ -248,6 +256,9 @@ export function registerChatRoutes(
         chat_id: row.id,
         session_id: row.session_id,
       });
+      // Fire-and-forget: tear down this chat's warm agent backends + (last-chat)
+      // worktree on the coder. Best-effort — never blocks/fails the delete.
+      void notifyCoderClose('chat', row.id, req.log);
       reply.code(204);
       return null;
     }
@@ -429,9 +440,7 @@ export function registerChatRoutes(
       }
       // v1.13.1-B: reads tool_calls/tool_results via the parts-merged view.
       const rows = await sql<Message[]>`
-        SELECT id, session_id, chat_id, role, content, kind, tool_calls, tool_results, status, last_seq,
-               tokens_used, ctx_used, ctx_max, started_at, finished_at, created_at, metadata,
-               summary, tail_start_id, compacted_at
+        SELECT ${sql.unsafe(MESSAGE_COLUMNS)}
         FROM messages_with_parts
         WHERE chat_id = ${req.params.id}
         ORDER BY created_at ASC, id ASC

apps/server/src/routes/messages.ts

@@ -8,6 +8,81 @@ import type { Chat, Message, Session, ToolCall } from '../types/api.js';
 // decision time (not at request time) so concurrent project changes don't
 // stale-bind the resolution.
 import { resolveGrantRoot } from '../services/grant_resolver.js';
+import { MESSAGE_COLUMNS } from '../services/message-columns.js';
+
+// Shared lookup for the answer_user_input + grant_read_access pause-resume
+// endpoints. Finds the originating assistant tool_call by id in message_parts,
+// validates the tool name, finds the pending tool_result part, and checks the
+// already-answered guard. Returns ok:true+context on success, ok:false+HTTP
+// status+body on any error (caller does reply.code(ctx.code); return ctx.body).
+type PendingToolLookupResult =
+  | {
+      ok: true;
+      foundCall: ToolCall;
+      toolMessageId: string;
+      toolRow: { message_id: string; payload: { tool_call_id: string; output: unknown } };
+    }
+  | { ok: false; code: number; body: Record<string, unknown> };
+
+async function lookupPendingToolCall(
+  sql: Sql,
+  chatId: string,
+  tool_call_id: string,
+  expectedToolName: string,
+  wrongToolError: string,
+): Promise<PendingToolLookupResult> {
+  // Find the assistant's tool_call by id via message_parts.
+  const callerRows = await sql<{
+    message_id: string;
+    payload: { id: string; name: string; args: Record<string, unknown> };
+  }[]>`
+    SELECT p.message_id, p.payload
+    FROM message_parts p
+    JOIN messages m ON m.id = p.message_id
+    WHERE m.chat_id = ${chatId}
+      AND m.role = 'assistant'
+      AND p.kind = 'tool_call'
+      AND p.payload->>'id' = ${tool_call_id}
+    ORDER BY m.created_at DESC
+    LIMIT 1
+  `;
+  const callerRow = callerRows[0];
+  if (!callerRow) return { ok: false, code: 404, body: { error: 'unknown_tool_call_id' } };
+
+  const foundCall: ToolCall = {
+    id: callerRow.payload.id,
+    name: callerRow.payload.name,
+    args: callerRow.payload.args,
+  };
+  if (foundCall.name !== expectedToolName) {
+    return { ok: false, code: 400, body: { error: wrongToolError } };
+  }
+
+  // Find the pending tool_result part by tool_call_id.
+  const toolRows = await sql<{
+    message_id: string;
+    payload: { tool_call_id: string; output: unknown };
+  }[]>`
+    SELECT p.message_id, p.payload
+    FROM message_parts p
+    JOIN messages m ON m.id = p.message_id
+    WHERE m.chat_id = ${chatId}
+      AND m.role = 'tool'
+      AND p.kind = 'tool_result'
+      AND p.payload->>'tool_call_id' = ${tool_call_id}
+    ORDER BY m.created_at DESC
+    LIMIT 1
+  `;
+  const toolRow = toolRows[0];
+  if (!toolRow) {
+    return { ok: false, code: 404, body: { error: 'unknown_tool_call_id', detail: 'tool message not found' } };
+  }
+  if (toolRow.payload && toolRow.payload.output !== null) {
+    return { ok: false, code: 409, body: { error: 'tool_call_already_answered' } };
+  }
+
+  return { ok: true, foundCall, toolMessageId: toolRow.message_id, toolRow };
+}
 
 const SendBody = z.object({
   content: z.string().min(1).max(64_000),
@@ -116,9 +191,7 @@ export function registerMessageRoutes(
       // see services/inference.ts loadContext + services/compaction.ts.
       // v1.13.1-B: reads tool_calls/tool_results via the parts-merged view.
       const rows = await sql<Message[]>`
-        SELECT id, session_id, chat_id, role, content, kind, tool_calls, tool_results, status, last_seq,
-               tokens_used, ctx_used, ctx_max, started_at, finished_at, created_at, metadata,
-               summary, tail_start_id, compacted_at
+        SELECT ${sql.unsafe(MESSAGE_COLUMNS)}
         FROM messages_with_parts
         WHERE session_id = ${req.params.id}
         ORDER BY created_at ASC, id ASC
@@ -493,40 +566,16 @@ export function registerMessageRoutes(
       const chat = chatRows[0]!;
       const sessionId = chat.session_id;
 
-      // v1.13.1-C: find the assistant's tool_call by indexing message_parts
-      // directly on payload->>'id'. Scoped by chat_id + role via the JOIN.
-      // Pre-v1.13.0 history has no parts rows — those tool_calls become
-      // unreachable here (404). Acceptable per the dispatch decision: any
-      // pending elicitation from before v1.13.0 is long timed out by now;
-      // promote to a hotfix with a JSON-column fallback if it ever surfaces.
-      const callerRows = await sql<{
-        message_id: string;
-        payload: { id: string; name: string; args: Record<string, unknown> };
-      }[]>`
-        SELECT p.message_id, p.payload
-        FROM message_parts p
-        JOIN messages m ON m.id = p.message_id
-        WHERE m.chat_id = ${chat.id}
-          AND m.role = 'assistant'
-          AND p.kind = 'tool_call'
-          AND p.payload->>'id' = ${tool_call_id}
-        ORDER BY m.created_at DESC
-        LIMIT 1
-      `;
-      const callerRow = callerRows[0];
-      if (!callerRow) {
-        reply.code(404);
-        return { error: 'unknown_tool_call_id' };
-      }
-      const foundCall: ToolCall = {
-        id: callerRow.payload.id,
-        name: callerRow.payload.name,
-        args: callerRow.payload.args,
-      };
-      if (foundCall.name !== 'ask_user_input') {
-        reply.code(400);
-        return { error: 'tool_call_not_ask_user_input' };
+      // v1.13.1-C: resolve the originating tool_call + pending tool row.
+      // Pre-v1.13.0 history has no parts rows — those become unreachable (404).
+      const ctx = await lookupPendingToolCall(
+        sql, chat.id, tool_call_id, 'ask_user_input', 'tool_call_not_ask_user_input',
+      );
+      if (!ctx.ok) {
+        reply.code(ctx.code);
+        return ctx.body;
       }
+      const { foundCall, toolMessageId } = ctx;
 
       // Validate the args themselves — the LLM could have emitted bad JSON.
       const argsParsed = AskUserInputArgs.safeParse(foundCall.args);
@@ -569,33 +618,6 @@ export function registerMessageRoutes(
         }
       }
 
-      // v1.13.1-C: find the pending tool row via message_parts on
-      // payload->>'tool_call_id'. Same fallback caveat as the caller lookup
-      // above — pre-v1.13.0 rows are unreachable here.
-      const toolRows = await sql<{
-        message_id: string;
-        payload: { tool_call_id: string; output: unknown };
-      }[]>`
-        SELECT p.message_id, p.payload
-        FROM message_parts p
-        JOIN messages m ON m.id = p.message_id
-        WHERE m.chat_id = ${chat.id}
-          AND m.role = 'tool'
-          AND p.kind = 'tool_result'
-          AND p.payload->>'tool_call_id' = ${tool_call_id}
-        ORDER BY m.created_at DESC
-        LIMIT 1
-      `;
-      const toolRow = toolRows[0];
-      if (!toolRow) {
-        reply.code(404);
-        return { error: 'unknown_tool_call_id', detail: 'tool message not found' };
-      }
-      if (toolRow.payload && toolRow.payload.output !== null) {
-        reply.code(409);
-        return { error: 'tool_call_already_answered' };
-      }
-
       const answerSet = { answers };
       const newToolResults = {
         tool_call_id,
@@ -603,7 +625,6 @@ export function registerMessageRoutes(
         truncated: false,
       };
 
-      const toolMessageId = toolRow.message_id;
       const result = await sql.begin(async (tx) => {
         // v1.13.20: parts-only. Replace the pending tool_result part inserted
         // at message creation (tool-phase.ts) with the answered one. Delete-
@@ -681,35 +702,15 @@ export function registerMessageRoutes(
       const chat = chatRows[0]!;
       const sessionId = chat.session_id;
 
-      // Mirror the /answer lookup: assistant tool_call by id via message_parts.
-      const callerRows = await sql<{
-        message_id: string;
-        payload: { id: string; name: string; args: Record<string, unknown> };
-      }[]>`
-        SELECT p.message_id, p.payload
-        FROM message_parts p
-        JOIN messages m ON m.id = p.message_id
-        WHERE m.chat_id = ${chat.id}
-          AND m.role = 'assistant'
-          AND p.kind = 'tool_call'
-          AND p.payload->>'id' = ${tool_call_id}
-        ORDER BY m.created_at DESC
-        LIMIT 1
-      `;
-      const callerRow = callerRows[0];
-      if (!callerRow) {
-        reply.code(404);
-        return { error: 'unknown_tool_call_id' };
-      }
-      const foundCall: ToolCall = {
-        id: callerRow.payload.id,
-        name: callerRow.payload.name,
-        args: callerRow.payload.args,
-      };
-      if (foundCall.name !== 'request_read_access') {
-        reply.code(400);
-        return { error: 'tool_call_not_request_read_access' };
+      const grantCtx = await lookupPendingToolCall(
+        sql, chat.id, tool_call_id, 'request_read_access', 'tool_call_not_request_read_access',
+      );
+      if (!grantCtx.ok) {
+        reply.code(grantCtx.code);
+        return grantCtx.body;
       }
+      const { foundCall, toolMessageId } = grantCtx;
+
       const argsParsed = RequestReadAccessArgs.safeParse(foundCall.args);
       if (!argsParsed.success) {
         reply.code(400);
@@ -717,31 +718,6 @@ export function registerMessageRoutes(
       }
       const requestedPath = argsParsed.data.path;
 
-      // Find the pending tool row.
-      const toolRows = await sql<{
-        message_id: string;
-        payload: { tool_call_id: string; output: unknown };
-      }[]>`
-        SELECT p.message_id, p.payload
-        FROM message_parts p
-        JOIN messages m ON m.id = p.message_id
-        WHERE m.chat_id = ${chat.id}
-          AND m.role = 'tool'
-          AND p.kind = 'tool_result'
-          AND p.payload->>'tool_call_id' = ${tool_call_id}
-        ORDER BY m.created_at DESC
-        LIMIT 1
-      `;
-      const toolRow = toolRows[0];
-      if (!toolRow) {
-        reply.code(404);
-        return { error: 'unknown_tool_call_id', detail: 'tool message not found' };
-      }
-      if (toolRow.payload && toolRow.payload.output !== null) {
-        reply.code(409);
-        return { error: 'tool_call_already_answered' };
-      }
-
       // Look up session + project so we can re-resolve the grant root and
       // append to allowed_read_paths atomically. We don't need agent or
       // history here — just the project path for the resolver.
@@ -790,7 +766,6 @@ export function registerMessageRoutes(
         output: resultOutput,
         truncated: false,
       };
-      const toolMessageId = toolRow.message_id;
       const dbResult = await sql.begin(async (tx) => {
         // v1.13.20: parts-only. Same delete+insert dance as /answer —
         // UNIQUE (message_id, sequence) blocks plain UPDATE on append-style

apps/server/src/routes/projects.ts

@@ -67,6 +67,20 @@ export async function resolveProjectPath(
   return { real, name: basename(real) };
 }
 
+async function selectProject(sql: Sql, id: string): Promise<Project | null> {
+  const rows = await sql<Project[]>`
+    SELECT id, name, path, added_at, last_session_id, status, gitea_remote,
+           default_system_prompt, default_web_search_enabled
+    FROM projects WHERE id = ${id}
+  `;
+  return rows[0] ?? null;
+}
+
+async function selectProjectPath(sql: Sql, id: string): Promise<string | null> {
+  const rows = await sql<{ path: string }[]>`SELECT path FROM projects WHERE id = ${id}`;
+  return rows[0]?.path ?? null;
+}
+
 export function registerProjectRoutes(
   app: FastifyInstance,
   sql: Sql,
@@ -199,16 +213,12 @@ export function registerProjectRoutes(
   // v1.9: single-project fetch so the settings pane can refetch on
   // project_updated without pulling the whole project list.
   app.get<{ Params: { id: string } }>('/api/projects/:id', async (req, reply) => {
-    const rows = await sql<Project[]>`
-      SELECT id, name, path, added_at, last_session_id, status, gitea_remote,
-             default_system_prompt, default_web_search_enabled
-      FROM projects WHERE id = ${req.params.id}
-    `;
-    if (rows.length === 0) {
+    const project = await selectProject(sql, req.params.id);
+    if (!project) {
       reply.code(404);
       return { error: 'not found' };
     }
-    return rows[0];
+    return project;
   });
 
   app.patch<{ Params: { id: string } }>('/api/projects/:id', async (req, reply) => {
@@ -340,18 +350,14 @@ export function registerProjectRoutes(
       const { id } = req.params;
       const relPath = req.query.path ?? '.';
 
-      const rows = await sql<Project[]>`
-        SELECT id, name, path, added_at, last_session_id, status, gitea_remote
-        FROM projects WHERE id = ${id}
-      `;
-      if (rows.length === 0) {
+      const projectPath = await selectProjectPath(sql, id);
+      if (projectPath === null) {
         reply.code(404);
         return { error: 'not found' };
       }
-      const project = rows[0]!;
       let projectRoot: string;
       try {
-        projectRoot = await resolveProjectRoot(project.path);
+        projectRoot = await resolveProjectRoot(projectPath);
       } catch (err) {
         if (err instanceof PathScopeError) {
           reply.code(404);
@@ -385,18 +391,14 @@ export function registerProjectRoutes(
         return { error: 'path is required' };
       }
 
-      const rows = await sql<Project[]>`
-        SELECT id, name, path, added_at, last_session_id, status, gitea_remote
-        FROM projects WHERE id = ${id}
-      `;
-      if (rows.length === 0) {
+      const projectPath = await selectProjectPath(sql, id);
+      if (projectPath === null) {
         reply.code(404);
         return { error: 'not found' };
       }
-      const project = rows[0]!;
       let projectRoot: string;
       try {
-        projectRoot = await resolveProjectRoot(project.path);
+        projectRoot = await resolveProjectRoot(projectPath);
       } catch (err) {
         if (err instanceof PathScopeError) {
           reply.code(404);
@@ -431,18 +433,14 @@ export function registerProjectRoutes(
     '/api/projects/:id/git',
     async (req, reply) => {
       const { id } = req.params;
-      const rows = await sql<Project[]>`
-        SELECT id, name, path, added_at, last_session_id, status, gitea_remote
-        FROM projects WHERE id = ${id}
-      `;
-      if (rows.length === 0) {
+      const projectPath = await selectProjectPath(sql, id);
+      if (projectPath === null) {
         reply.code(404);
         return { error: 'not found' };
       }
-      const project = rows[0]!;
       let projectRoot: string;
       try {
-        projectRoot = await resolveProjectRoot(project.path);
+        projectRoot = await resolveProjectRoot(projectPath);
       } catch (err) {
         if (err instanceof PathScopeError) {
           reply.code(404);
@@ -461,18 +459,14 @@ export function registerProjectRoutes(
     async (req, reply) => {
       const { id } = req.params;
 
-      const rows = await sql<Project[]>`
-        SELECT id, name, path, added_at, last_session_id, status, gitea_remote
-        FROM projects WHERE id = ${id}
-      `;
-      if (rows.length === 0) {
+      const projectPath = await selectProjectPath(sql, id);
+      if (projectPath === null) {
         reply.code(404);
         return { error: 'not found' };
       }
-      const project = rows[0]!;
       let projectRoot: string;
       try {
-        projectRoot = await resolveProjectRoot(project.path);
+        projectRoot = await resolveProjectRoot(projectPath);
       } catch (err) {
         if (err instanceof PathScopeError) {
           reply.code(404);

apps/server/src/routes/sessions.ts

@@ -5,6 +5,7 @@ import type { Config } from '../config.js';
 import type { Broker } from '../services/broker.js';
 import type { Session, WorktreeRiskReport } from '../types/api.js';
 import { getSetting } from './settings.js';
+import { notifyCoderClose } from '../services/coder-notify.js';
 
 const CreateBody = z.object({
   name: z.string().min(1).max(200).optional(),
@@ -513,6 +514,10 @@ export function registerSessionRoutes(
       }
       const project_id = deleted[0]!.project_id;
       broker.publishUserFrame('default', { type: 'session_deleted', session_id: id, project_id });
+      // Fire-and-forget: ask BooCoder to tear down this session's warm agent
+      // backends + worktree immediately. Best-effort — never blocks/fails the
+      // delete; the coder's idle-evict + orphan reaper backstop a missed call.
+      void notifyCoderClose('session', id, req.log);
       reply.code(204);
       return null;
     }

apps/server/src/routes/settings.ts

@@ -22,8 +22,9 @@ export async function setSetting(
   `;
 }
 
-// themes-v1: whitelist of the 18 preset theme ids. Kept in sync with
+// themes-v1: whitelist of the preset theme ids. Kept in sync with
 // docs/themes_v1.md §1 and apps/web/src/lib/theme.ts THEMES.
+// (+ 'ember' — the BooCode 2.0 signature, now the default.)
 const THEME_IDS = [
   'obsidian',
   'gunmetal',
@@ -43,6 +44,7 @@ const THEME_IDS = [
   'chalk',
   'cobalt',
   'midnight-sapphire',
+  'ember',
 ] as const;
 
 const THEME_MODES = ['dark', 'light', 'system'] as const;

apps/server/src/routes/ws.ts

@@ -2,6 +2,7 @@ import type { FastifyInstance } from 'fastify';
 import type { Sql } from '../db.js';
 import type { Broker } from '../services/broker.js';
 import type { Message } from '../types/api.js';
+import { MESSAGE_COLUMNS } from '../services/message-columns.js';
 
 export function registerWebSocket(
   app: FastifyInstance,
@@ -25,9 +26,7 @@ export function registerWebSocket(
       // render the SummaryCard for summary=true rows on first connect.
       // v1.13.1-B: reads tool_calls/tool_results via the parts-merged view.
       const messages = await sql<Message[]>`
-        SELECT id, session_id, chat_id, role, content, kind, tool_calls, tool_results, status, last_seq,
-               tokens_used, ctx_used, ctx_max, started_at, finished_at, created_at, metadata,
-               summary, tail_start_id, compacted_at
+        SELECT ${sql.unsafe(MESSAGE_COLUMNS)}
         FROM messages_with_parts
         WHERE session_id = ${sessionId}
         ORDER BY created_at ASC, id ASC

apps/server/src/schema.sql

@@ -1,5 +1,5 @@
 -- v1.13.3: statement_timeout is set at database level via:
---   ALTER DATABASE boocode SET statement_timeout = '30s';
+--   ALTER DATABASE boochat SET statement_timeout = '30s';
 -- ALTER DATABASE can't run inside a DO block, so this is an operational
 -- step rather than schema. Re-apply after a volume reset (the setting
 -- lives in pg_db which survives `docker compose up --build` but NOT a
@@ -30,8 +30,6 @@ CREATE TABLE IF NOT EXISTS messages (
   session_id UUID NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
   role TEXT NOT NULL,
   content TEXT NOT NULL DEFAULT '',
-  tool_calls JSONB,
-  tool_results JSONB,
   status TEXT NOT NULL DEFAULT 'complete',
   last_seq INT NOT NULL DEFAULT 0,
   created_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp()
@@ -39,11 +37,10 @@ CREATE TABLE IF NOT EXISTS messages (
 
 CREATE INDEX IF NOT EXISTS idx_messages_session ON messages(session_id, created_at);
 
--- v1.13.0: granular message parts table for AI SDK migration. Old
--- messages.content / tool_calls / tool_results columns stay authoritative
--- for reads in v1.13.0; this table is dual-written so the swap can happen
--- in a later dispatch without a backfill window. ON DELETE CASCADE means
--- removing a message removes its parts in one go.
+-- v1.13.0: granular message parts table. v1.13.20: legacy tool_calls/
+-- tool_results columns dropped; message_parts is now the sole source of
+-- truth for tool calls, tool results, and reasoning. ON DELETE CASCADE
+-- means removing a message removes its parts in one go.
 CREATE TABLE IF NOT EXISTS message_parts (
   id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
   message_id uuid NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
@@ -107,6 +104,11 @@ END $$;
 -- a single jsonb object {tool_call_id, output, truncated, error?}.
 -- reasoning_parts is consumed by the inference history fetch (payload.ts)
 -- for v1.13.1-C reasoning round-tripping. Not surfaced in external APIs.
+-- model-attribution: which model produced an assistant message (NULL for
+-- user/system rows and pre-existing messages). Stamped at finalize (BooChat /
+-- native coder) and at assistant-row creation (external coder dispatcher).
+ALTER TABLE messages ADD COLUMN IF NOT EXISTS model TEXT;
+
 CREATE OR REPLACE VIEW messages_with_parts AS
 SELECT
   m.id, m.session_id, m.chat_id, m.role, m.content, m.kind, m.status,
@@ -122,7 +124,10 @@ SELECT
     ORDER BY p.sequence LIMIT 1) AS tool_results,
   (SELECT jsonb_agg(p.payload ORDER BY p.sequence)
      FROM message_parts p
-    WHERE p.message_id = m.id AND p.kind = 'reasoning' AND p.hidden_at IS NULL) AS reasoning_parts
+    WHERE p.message_id = m.id AND p.kind = 'reasoning' AND p.hidden_at IS NULL) AS reasoning_parts,
+  -- NEW columns MUST be appended at the end: CREATE OR REPLACE VIEW can't
+  -- reorder/rename existing columns (42P16). m.model added last.
+  m.model
 FROM messages m;
 
 -- v1.13.20: drop legacy tool_calls/tool_results columns. Reads have routed
@@ -134,10 +139,9 @@ ALTER TABLE messages DROP COLUMN IF EXISTS tool_calls;
 ALTER TABLE messages DROP COLUMN IF EXISTS tool_results;
 
 -- v1.13.10: per-tool token cost rolling window. Derives from
--- messages_with_parts (the v1.13.1-B view that COALESCEs message_parts over
--- the legacy JSON column) so this works whether the chat predates v1.13.0
--- or postdates v1.13.2 (column drop). No new write site — all source data
--- already lands via the existing tool-phase.ts:94-95 UPDATE.
+-- messages_with_parts (the v1.13.1-B view; v1.13.20 removed the legacy
+-- JSON-column COALESCE fallback — parts are sole source). No new write
+-- site — all source data already lands via tool-phase.ts:94-95 UPDATE.
 --
 -- Attribution model: equal split. A turn emitting N tool calls divides its
 -- prompt/completion tokens by N before attribution. See v1.13.10 dispatch
@@ -344,7 +348,7 @@ INSERT INTO settings (key, value) VALUES ('theme_mode', '"dark"') ON CONFLICT (k
 ALTER TABLE projects ADD COLUMN IF NOT EXISTS default_system_prompt TEXT NOT NULL DEFAULT '';
 ALTER TABLE projects ADD COLUMN IF NOT EXISTS default_web_search_enabled BOOLEAN NOT NULL DEFAULT false;
 ALTER TABLE sessions ADD COLUMN IF NOT EXISTS web_search_enabled BOOLEAN;
-ALTER TABLE sessions ADD COLUMN IF NOT EXISTS tags TEXT[] DEFAULT '{}';
+ALTER TABLE sessions DROP COLUMN IF EXISTS tags;
 
 -- v1.11: anchored rolling compaction.
 --   compacted_at  — marks rows that are "behind the curtain" of the latest
@@ -383,9 +387,7 @@ CREATE TABLE IF NOT EXISTS tasks (
   model             TEXT,
   mode_id           TEXT,
   thinking_option_id TEXT,
-  feature_values    JSONB,
   execution_path    TEXT CHECK (execution_path IS NULL OR execution_path IN ('native','acp','pty','qwen')),
-  worktree_path     TEXT,
   cost_tokens       INTEGER,
   started_at        TIMESTAMPTZ,
   ended_at          TIMESTAMPTZ,

apps/server/src/services/__tests__/agents.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, vi, afterEach } from 'vitest';
 import { isAgentRegistryMarkdown, parseAgentsMd } from '../agents.js';
 
 describe('isAgentRegistryMarkdown', () => {
@@ -31,3 +31,87 @@ Start here
     expect(r.errors.length).toBeGreaterThan(0);
   });
 });
+
+// v2.6 sampling-streamjson-tokens (#11): per-agent llama.cpp sampler extensions.
+describe('parseAgentsMd: v2.6 sampling knobs', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  const withFrontmatter = (lines: string) => `# Agents
+
+## Sampler
+---
+temperature: 0.6
+${lines}
+tools: [view_file]
+description: test
+---
+You sample.
+`;
+
+  it('parses top_n_sigma and the dry_* family from frontmatter', () => {
+    const md = withFrontmatter(
+      [
+        'top_n_sigma: 1.5',
+        'dry_multiplier: 0.8',
+        'dry_base: 1.75',
+        'dry_allowed_length: 2',
+        'dry_penalty_last_n: -1',
+      ].join('\n'),
+    );
+    const { agents, errors } = parseAgentsMd(md);
+    expect(errors).toHaveLength(0);
+    expect(agents).toHaveLength(1);
+    const a = agents[0]!;
+    expect(a.top_n_sigma).toBe(1.5);
+    expect(a.dry_multiplier).toBe(0.8);
+    expect(a.dry_base).toBe(1.75);
+    expect(a.dry_allowed_length).toBe(2);
+    expect(a.dry_penalty_last_n).toBe(-1);
+  });
+
+  it('defaults the new sampler fields to null when omitted', () => {
+    const { agents } = parseAgentsMd(withFrontmatter('top_p: 0.95'));
+    const a = agents[0]!;
+    expect(a.top_n_sigma).toBeNull();
+    expect(a.dry_multiplier).toBeNull();
+    expect(a.dry_base).toBeNull();
+    expect(a.dry_allowed_length).toBeNull();
+    expect(a.dry_penalty_last_n).toBeNull();
+  });
+
+  it('warns (does not error) on out-of-range top_n_sigma / dry_* values', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const md = withFrontmatter(
+      [
+        'top_n_sigma: -1',
+        'dry_multiplier: -0.5',
+        'dry_base: -2',
+        'dry_allowed_length: -3',
+        'dry_penalty_last_n: -5',
+      ].join('\n'),
+    );
+    const { agents, errors } = parseAgentsMd(md);
+    expect(errors).toHaveLength(0);
+    expect(agents).toHaveLength(1);
+    // Mirrors top_k/min_p: out-of-range still stored, with a warning.
+    expect(warn).toHaveBeenCalled();
+    const warnings = warn.mock.calls.map((c) => String(c[0])).join('\n');
+    expect(warnings).toContain('top_n_sigma');
+    expect(warnings).toContain('dry_multiplier');
+    expect(warnings).toContain('dry_base');
+    expect(warnings).toContain('dry_allowed_length');
+    expect(warnings).toContain('dry_penalty_last_n');
+  });
+
+  it('errors on non-numeric / non-integer sampler values', () => {
+    const md = withFrontmatter(
+      ['top_n_sigma: high', 'dry_allowed_length: 2.5'].join('\n'),
+    );
+    const { errors } = parseAgentsMd(md);
+    const joined = errors.map((e) => e.reason).join('\n');
+    expect(joined).toContain('top_n_sigma must be a number');
+    expect(joined).toContain('dry_allowed_length must be an integer');
+  });
+});

apps/server/src/services/__tests__/budget.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+import { resolveToolBudget } from '../inference/budget.js';
+import type { Agent } from '../../types/api.js';
+
+const BASE_AGENT: Agent = {
+  id: 'test-agent',
+  name: 'Test',
+  description: 'test',
+  system_prompt: '',
+  temperature: 0.7,
+  top_p: null,
+  top_k: null,
+  min_p: null,
+  presence_penalty: null,
+  top_n_sigma: null,
+  dry_multiplier: null,
+  dry_base: null,
+  dry_allowed_length: null,
+  dry_penalty_last_n: null,
+  tools: ['view_file'],
+  model: null,
+  source: 'global',
+  max_tool_calls: null,
+  steps: null,
+  llama_extra_args: null,
+};
+
+describe('resolveToolBudget', () => {
+  it('returns 100 when agent is null (no-agent raw chat)', () => {
+    expect(resolveToolBudget(null)).toBe(100);
+  });
+
+  it('returns 100 when agent has no max_tool_calls override', () => {
+    expect(resolveToolBudget(BASE_AGENT)).toBe(100);
+  });
+
+  it('returns max_tool_calls when agent overrides the default', () => {
+    const agent: Agent = { ...BASE_AGENT, max_tool_calls: 25 };
+    expect(resolveToolBudget(agent)).toBe(25);
+  });
+
+  it('returns 0 when max_tool_calls is explicitly 0 (text-only mode)', () => {
+    const agent: Agent = { ...BASE_AGENT, max_tool_calls: 0 };
+    expect(resolveToolBudget(agent)).toBe(0);
+  });
+});

apps/server/src/services/__tests__/coder-notify.test.ts

@@ -0,0 +1,67 @@
+// v2.6.10 Phase 3 (server wiring) — notifyCoderClose fire-and-forget helper.
+//
+// The guarantee under test: the helper NEVER throws (so it can't break the
+// user's delete/archive path), targets the correct coder URL shape, and folds
+// every failure mode (non-2xx, network error) into a `false` result.
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { notifyCoderClose } from '../coder-notify.js';
+
+const ORIGINAL_BOOCODER_URL = process.env.BOOCODER_URL;
+
+describe('notifyCoderClose', () => {
+  beforeEach(() => {
+    delete process.env.BOOCODER_URL;
+  });
+  afterEach(() => {
+    if (ORIGINAL_BOOCODER_URL === undefined) delete process.env.BOOCODER_URL;
+    else process.env.BOOCODER_URL = ORIGINAL_BOOCODER_URL;
+  });
+
+  it('POSTs the chat close hook at the default coder origin and resolves true on 2xx', async () => {
+    const fetcher = vi.fn().mockResolvedValue(new Response(null, { status: 200 }));
+    const ok = await notifyCoderClose('chat', 'chat-123', undefined, fetcher as unknown as typeof fetch);
+    expect(ok).toBe(true);
+    expect(fetcher).toHaveBeenCalledTimes(1);
+    const [url, init] = fetcher.mock.calls[0]!;
+    expect(url).toBe('http://boocoder:3000/api/chats/chat-123/close');
+    expect(init).toEqual({ method: 'POST' });
+  });
+
+  it('POSTs the session close hook with the sessions segment', async () => {
+    const fetcher = vi.fn().mockResolvedValue(new Response(null, { status: 200 }));
+    const ok = await notifyCoderClose('session', 'sess-abc', undefined, fetcher as unknown as typeof fetch);
+    expect(ok).toBe(true);
+    expect(fetcher.mock.calls[0]![0]).toBe('http://boocoder:3000/api/sessions/sess-abc/close');
+  });
+
+  it('honors BOOCODER_URL for the origin', async () => {
+    process.env.BOOCODER_URL = 'http://100.114.205.53:9502';
+    const fetcher = vi.fn().mockResolvedValue(new Response(null, { status: 200 }));
+    await notifyCoderClose('chat', 'c1', undefined, fetcher as unknown as typeof fetch);
+    expect(fetcher.mock.calls[0]![0]).toBe('http://100.114.205.53:9502/api/chats/c1/close');
+  });
+
+  it('resolves false on a non-2xx response (does not throw)', async () => {
+    const fetcher = vi.fn().mockResolvedValue(new Response(null, { status: 500 }));
+    const log = { debug: vi.fn() };
+    const ok = await notifyCoderClose('chat', 'c1', log, fetcher as unknown as typeof fetch);
+    expect(ok).toBe(false);
+    expect(log.debug).toHaveBeenCalledTimes(1);
+  });
+
+  it('resolves false on a network error (coder unreachable) — never rejects', async () => {
+    const fetcher = vi.fn().mockRejectedValue(new Error('ECONNREFUSED'));
+    const log = { debug: vi.fn() };
+    const ok = await notifyCoderClose('session', 's1', log, fetcher as unknown as typeof fetch);
+    expect(ok).toBe(false);
+    expect(log.debug).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not require a logger', async () => {
+    const fetcher = vi.fn().mockRejectedValue(new Error('boom'));
+    await expect(
+      notifyCoderClose('chat', 'c1', undefined, fetcher as unknown as typeof fetch),
+    ).resolves.toBe(false);
+  });
+});

apps/server/src/services/__tests__/compaction.test.ts

@@ -7,6 +7,8 @@ import {
   select,
   buildPrompt,
   buildHeadPayload,
+  deriveFilesRead,
+  buildFilesReadContext,
   type CompactionMessage,
 } from '../compaction.js';
 import { SUMMARY_TEMPLATE } from '../compaction-prompt.js';
@@ -321,3 +323,105 @@ describe('buildHeadPayload reasoning render', () => {
     expect(out[1]!.content).not.toContain('<reasoning>');
   });
 });
+
+// ---- buildHeadPayload sentinel stripping (#12) -------------------------------
+
+describe('buildHeadPayload strips all UI sentinels', () => {
+  it('drops cap_hit, doom_loop, and mistake_recovery system rows', () => {
+    const out = buildHeadPayload([
+      mkMsg('user', 'do the thing'),
+      mkMsg('system', 'budget reached', { metadata: { kind: 'cap_hit' } }),
+      mkMsg('system', 'looping', { metadata: { kind: 'doom_loop' } }),
+      mkMsg('system', 'repeated errors', { metadata: { kind: 'mistake_recovery' } }),
+      mkMsg('assistant', 'answer'),
+    ]);
+    // Only the user + assistant rows survive; all three sentinels stripped.
+    expect(out).toHaveLength(2);
+    expect(out[0]!.role).toBe('user');
+    expect(out[1]!.role).toBe('assistant');
+  });
+
+  it('keeps a non-sentinel system row (e.g. compact bridge) untouched', () => {
+    const out = buildHeadPayload([
+      mkMsg('system', 'legacy compact', { kind: 'compact', metadata: null }),
+      mkMsg('user', 'q'),
+    ]);
+    expect(out[0]!.role).toBe('system');
+    expect(out[0]!.content).toBe('legacy compact');
+  });
+});
+
+// ---- file-provenance ledger (#12, Part B) -----------------------------------
+
+describe('deriveFilesRead', () => {
+  it('returns [] when the head has no read-tool calls', () => {
+    expect(deriveFilesRead([mkMsg('user', 'hi'), mkMsg('assistant', 'hello')])).toEqual([]);
+  });
+
+  it('extracts the path arg from view_file / list_dir / grep / find_files', () => {
+    const head = [
+      mkMsg('assistant', '', {
+        tool_calls: [
+          { id: 'c1', name: 'view_file', args: { path: 'src/index.ts' } },
+          { id: 'c2', name: 'list_dir', args: { path: 'src' } },
+          { id: 'c3', name: 'grep', args: { pattern: 'TODO', path: 'apps' } },
+          { id: 'c4', name: 'find_files', args: { pattern: '**/*.ts', path: 'lib' } },
+        ],
+      }),
+    ];
+    expect(deriveFilesRead(head)).toEqual(['apps', 'lib', 'src', 'src/index.ts']);
+  });
+
+  it('dedupes and sorts paths across multiple assistant turns', () => {
+    const head = [
+      mkMsg('assistant', '', { tool_calls: [{ id: 'c1', name: 'view_file', args: { path: 'b.ts' } }] }),
+      mkMsg('assistant', '', { tool_calls: [{ id: 'c2', name: 'view_file', args: { path: 'a.ts' } }] }),
+      mkMsg('assistant', '', { tool_calls: [{ id: 'c3', name: 'view_file', args: { path: 'b.ts' } }] }),
+    ];
+    expect(deriveFilesRead(head)).toEqual(['a.ts', 'b.ts']);
+  });
+
+  it('ignores non-read tools and grep calls without a path arg', () => {
+    const head = [
+      mkMsg('assistant', '', {
+        tool_calls: [
+          { id: 'c1', name: 'web_search', args: { query: 'x' } },
+          { id: 'c2', name: 'grep', args: { pattern: 'foo' } }, // no path → root, skipped
+          { id: 'c3', name: 'view_file', args: { path: 'kept.ts' } },
+        ],
+      }),
+    ];
+    expect(deriveFilesRead(head)).toEqual(['kept.ts']);
+  });
+
+  it('ignores read-tool calls on non-assistant rows', () => {
+    const head = [
+      mkMsg('user', '', { tool_calls: [{ id: 'c1', name: 'view_file', args: { path: 'nope.ts' } }] }),
+    ];
+    expect(deriveFilesRead(head)).toEqual([]);
+  });
+});
+
+describe('buildFilesReadContext', () => {
+  it('returns null when nothing was read (no empty section injected)', () => {
+    expect(buildFilesReadContext([mkMsg('user', 'hi')])).toBeNull();
+  });
+
+  it('formats a ## Files Read block with sorted bullet paths', () => {
+    const head = [
+      mkMsg('assistant', '', {
+        tool_calls: [
+          { id: 'c1', name: 'view_file', args: { path: 'z.ts' } },
+          { id: 'c2', name: 'view_file', args: { path: 'a.ts' } },
+        ],
+      }),
+    ];
+    expect(buildFilesReadContext(head)).toBe('## Files Read\n- a.ts\n- z.ts');
+  });
+});
+
+describe('SUMMARY_TEMPLATE includes the Files Read section (#12)', () => {
+  it('declares a ## Files Read section the model must maintain', () => {
+    expect(SUMMARY_TEMPLATE).toContain('## Files Read');
+  });
+});

apps/server/src/services/__tests__/html-to-md.test.ts

@@ -70,10 +70,16 @@ describe('htmlToMarkdown', () => {
         </tbody>
       </table>`;
     const md = htmlToMarkdown(html);
-    expect(md).toContain('| Name | Age | City |');
-    expect(md).toContain('| --- | --- | --- |');
-    expect(md).toContain('| Alice | 30 | NYC |');
-    expect(md).toContain('| Bob | 25 | LA |');
+    // node-html-markdown pads columns to align them; assert structure rather
+    // than exact spacing. Each cell value and a GFM separator row are present.
+    expect(md).toContain('| Name ');
+    expect(md).toContain('| Age ');
+    expect(md).toContain('| City |');
+    expect(md).toMatch(/\| -+ \| -+ \| -+ \|/); // separator row
+    expect(md).toContain('| Alice ');
+    expect(md).toContain('| NYC  |');
+    expect(md).toContain('| Bob   ');
+    expect(md).toContain('| LA   |');
   });
 
   it('escapes pipe characters in table cells', () => {
@@ -162,14 +168,17 @@ describe('htmlToMarkdown', () => {
 
   it('converts br to newline', () => {
     const md = htmlToMarkdown('line one<br>line two');
-    expect(md).toContain('line one\nline two');
+    // node-html-markdown emits a GFM hard line break (trailing two spaces).
+    expect(md).toContain('line one  \nline two');
   });
 
   it('handles ol with start attribute', () => {
     const html = '<ol start="5"><li>five</li><li>six</li></ol>';
     const md = htmlToMarkdown(html);
-    expect(md).toContain('5. five');
-    expect(md).toContain('6. six');
+    // node-html-markdown does not honor the `start` attribute; it always
+    // renumbers ordered lists from 1. (Old parse5 renderer honored start=.)
+    expect(md).toContain('1. five');
+    expect(md).toContain('2. six');
   });
 
   it('collapses excessive blank lines', () => {
@@ -212,9 +221,12 @@ describe('htmlToMarkdown', () => {
     expect(md).toContain('[a link](https://example.com)');
     expect(md).toContain('## Features');
     expect(md).toContain('* Fast');
-    expect(md).toContain('| Metric | Value |');
-    expect(md).toContain('| --- | --- |');
-    expect(md).toContain('| Uptime | 99.9% |');
+    // Table columns are padded to align (node-html-markdown behavior).
+    expect(md).toContain('| Metric ');
+    expect(md).toContain('| Value |');
+    expect(md).toMatch(/\| -+ \| -+ \|/); // separator row
+    expect(md).toContain('| Uptime ');
+    expect(md).toContain('| 99.9% |');
     expect(md).toContain('> This tool is amazing.');
     expect(md).toContain('```js\nconsole.log("hello");\n```');
     expect(md).not.toContain('evil');

apps/server/src/services/__tests__/inference-helpers.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it, vi, afterEach } from 'vitest';
+import { samplerOptsFromAgent } from '../inference/stream-phase.js';
+import { createContentFlusher } from '../inference/content-flusher.js';
+import type { Sql } from '../../db.js';
+import type { Agent } from '../../types/api.js';
+
+const BASE_AGENT: Agent = {
+  id: 'test-agent',
+  name: 'Test',
+  description: 'test',
+  system_prompt: '',
+  temperature: 0.7,
+  top_p: null,
+  top_k: null,
+  min_p: null,
+  presence_penalty: null,
+  top_n_sigma: null,
+  dry_multiplier: null,
+  dry_base: null,
+  dry_allowed_length: null,
+  dry_penalty_last_n: null,
+  tools: ['view_file'],
+  model: null,
+  source: 'global',
+  max_tool_calls: null,
+  steps: null,
+  llama_extra_args: null,
+};
+
+describe('samplerOptsFromAgent', () => {
+  it('maps every nullable sampler field to undefined when agent is null', () => {
+    expect(samplerOptsFromAgent(null)).toEqual({
+      temperature: undefined,
+      top_p: undefined,
+      top_k: undefined,
+      min_p: undefined,
+      presence_penalty: undefined,
+      top_n_sigma: undefined,
+      dry_multiplier: undefined,
+      dry_base: undefined,
+      dry_allowed_length: undefined,
+      dry_penalty_last_n: undefined,
+    });
+  });
+
+  it('strips null sampler fields to undefined but keeps numeric values', () => {
+    const agent: Agent = {
+      ...BASE_AGENT,
+      temperature: 0.5,
+      top_p: 0.9,
+      top_k: null,
+      min_p: 0.05,
+      presence_penalty: null,
+      top_n_sigma: 1,
+      dry_multiplier: null,
+      dry_base: 1.75,
+      dry_allowed_length: null,
+      dry_penalty_last_n: 256,
+    };
+    expect(samplerOptsFromAgent(agent)).toEqual({
+      temperature: 0.5,
+      top_p: 0.9,
+      top_k: undefined,
+      min_p: 0.05,
+      presence_penalty: undefined,
+      top_n_sigma: 1,
+      dry_multiplier: undefined,
+      dry_base: 1.75,
+      dry_allowed_length: undefined,
+      dry_penalty_last_n: 256,
+    });
+  });
+
+  it('never includes a tools field (callers add it)', () => {
+    expect('tools' in samplerOptsFromAgent(BASE_AGENT)).toBe(false);
+  });
+});
+
+describe('createContentFlusher', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  // A tagged-template stub matching postgres' sql`...` shape. Records the
+  // interpolated content snapshot (values[0]) of each UPDATE.
+  function makeSqlSpy() {
+    const writes: string[] = [];
+    const sql = ((_strings: TemplateStringsArray, ...values: unknown[]) => {
+      writes.push(values[0] as string);
+      return Promise.resolve([]);
+    }) as unknown as Sql;
+    return { sql, writes };
+  }
+
+  it('debounces: many scheduleFlush calls in one window produce one write', async () => {
+    vi.useFakeTimers();
+    const { sql, writes } = makeSqlSpy();
+    let content = '';
+    const flusher = createContentFlusher(sql, 'msg-1', () => content, 500);
+
+    content = 'a';
+    flusher.scheduleFlush();
+    content = 'ab';
+    flusher.scheduleFlush();
+    content = 'abc';
+    flusher.scheduleFlush();
+
+    expect(writes).toHaveLength(0); // nothing before the interval elapses
+    vi.advanceTimersByTime(500);
+    await flusher.drain();
+
+    expect(writes).toHaveLength(1);
+    // snapshot is read at fire time → latest content, not the value at schedule time
+    expect(writes[0]).toBe('abc');
+  });
+
+  it('arms a fresh timer after a flush fires', async () => {
+    vi.useFakeTimers();
+    const { sql, writes } = makeSqlSpy();
+    let content = 'one';
+    const flusher = createContentFlusher(sql, 'msg-1', () => content, 500);
+
+    flusher.scheduleFlush();
+    vi.advanceTimersByTime(500);
+    await Promise.resolve();
+
+    content = 'two';
+    flusher.scheduleFlush();
+    vi.advanceTimersByTime(500);
+    await flusher.drain();
+
+    expect(writes).toEqual(['one', 'two']);
+  });
+
+  it('drain cancels a pending timer without performing a final flush', async () => {
+    vi.useFakeTimers();
+    const { sql, writes } = makeSqlSpy();
+    let content = 'pending';
+    const flusher = createContentFlusher(sql, 'msg-1', () => content, 500);
+
+    flusher.scheduleFlush();
+    // Drain before the timer fires — the pending flush is cancelled, not forced.
+    await flusher.drain();
+    vi.advanceTimersByTime(500);
+    await Promise.resolve();
+
+    expect(writes).toHaveLength(0);
+  });
+});

apps/server/src/services/__tests__/license-mit.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+// Guards the AGPL-3.0 -> MIT relicense (openspec license-debt-mit). If any of
+// these fail, AGPL-derived provenance has crept back in.
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../../../../..');
+
+describe('license: MIT relicense guard', () => {
+  it('LICENSE is MIT (no Affero/AGPL text)', () => {
+    const license = readFileSync(resolve(ROOT, 'LICENSE'), 'utf8');
+    expect(license).toMatch(/^MIT License/);
+    expect(license).not.toMatch(/AFFERO|AGPL/i);
+  });
+
+  const PACKAGE_JSONS = [
+    'package.json',
+    'apps/server/package.json',
+    'apps/web/package.json',
+    'apps/coder/package.json',
+    'apps/booterm/package.json',
+  ];
+  for (const rel of PACKAGE_JSONS) {
+    it(`${rel} declares "license": "MIT"`, () => {
+      const pkg = JSON.parse(readFileSync(resolve(ROOT, rel), 'utf8')) as { license?: string };
+      expect(pkg.license).toBe('MIT');
+    });
+  }
+
+  // The three files that were ported from Unsloth Studio (AGPL-3.0-only) and
+  // cleared in this batch — they must carry no AGPL/Unsloth provenance.
+  const FORMERLY_AGPL = [
+    'apps/server/src/services/inference/tool-call-parser.ts',
+    'apps/server/src/services/web/html-to-md.ts',
+    'apps/server/src/services/inference/llama-args-validator.ts',
+  ];
+  for (const rel of FORMERLY_AGPL) {
+    it(`${rel} carries no AGPL / Unsloth provenance`, () => {
+      const src = readFileSync(resolve(ROOT, rel), 'utf8');
+      expect(src).not.toMatch(/AGPL/);
+      expect(src).not.toMatch(/SPDX-License-Identifier:\s*AGPL/);
+      expect(src).not.toMatch(/Unsloth/i);
+    });
+  }
+});

apps/server/src/services/__tests__/mcp-config.test.ts

@@ -0,0 +1,93 @@
+/**
+ * Unit tests for `{env:VAR}` substitution in the MCP config loader.
+ * Pure — no live MCP server. Verifies secrets resolve from process.env
+ * (so real keys live in `.env`, not the gitignored config file).
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { substituteEnvVars } from '../mcp-config.js';
+
+// Minimal FastifyBaseLogger stub — only .warn is exercised here.
+function fakeLog() {
+  const warnings: string[] = [];
+  const log = {
+    warn: (msg: unknown) => {
+      warnings.push(typeof msg === 'string' ? msg : JSON.stringify(msg));
+    },
+  };
+  return { log: log as never, warnings };
+}
+
+describe('substituteEnvVars', () => {
+  const SAVED = process.env.MCP_TEST_SECRET;
+  beforeEach(() => {
+    process.env.MCP_TEST_SECRET = 'resolved-value';
+  });
+  afterEach(() => {
+    if (SAVED === undefined) delete process.env.MCP_TEST_SECRET;
+    else process.env.MCP_TEST_SECRET = SAVED;
+    delete process.env.MCP_TEST_MISSING;
+  });
+
+  it('replaces a {env:VAR} reference in a string value', () => {
+    const { log } = fakeLog();
+    expect(substituteEnvVars('{env:MCP_TEST_SECRET}', log)).toBe('resolved-value');
+  });
+
+  it('substitutes inside nested objects and arrays', () => {
+    const { log } = fakeLog();
+    const out = substituteEnvVars(
+      {
+        headers: { CONTEXT7_API_KEY: '{env:MCP_TEST_SECRET}' },
+        args: ['--token', '{env:MCP_TEST_SECRET}'],
+      },
+      log,
+    );
+    expect(out).toEqual({
+      headers: { CONTEXT7_API_KEY: 'resolved-value' },
+      args: ['--token', 'resolved-value'],
+    });
+  });
+
+  it('leaves object keys untouched, only transforms values', () => {
+    const { log } = fakeLog();
+    const out = substituteEnvVars({ '{env:MCP_TEST_SECRET}': 'literal' }, log) as Record<string, string>;
+    expect(Object.keys(out)).toEqual(['{env:MCP_TEST_SECRET}']);
+  });
+
+  it('resolves an unset var to empty string and warns', () => {
+    const { log, warnings } = fakeLog();
+    expect(substituteEnvVars('{env:MCP_TEST_MISSING}', log)).toBe('');
+    expect(warnings.some((w) => w.includes('MCP_TEST_MISSING'))).toBe(true);
+  });
+
+  it('passes non-string scalars through unchanged', () => {
+    const { log } = fakeLog();
+    expect(substituteEnvVars(true, log)).toBe(true);
+    expect(substituteEnvVars(42, log)).toBe(42);
+    expect(substituteEnvVars(null, log)).toBe(null);
+  });
+
+  it('leaves strings without a reference unchanged', () => {
+    const { log } = fakeLog();
+    expect(substituteEnvVars('https://mcp.context7.com/mcp', log)).toBe('https://mcp.context7.com/mcp');
+  });
+
+  it('resolves multiple references in one string (global flag)', () => {
+    const { log } = fakeLog();
+    expect(substituteEnvVars('{env:MCP_TEST_SECRET}/{env:MCP_TEST_SECRET}', log)).toBe(
+      'resolved-value/resolved-value',
+    );
+  });
+
+  it('passes an empty string through unchanged', () => {
+    const { log } = fakeLog();
+    expect(substituteEnvVars('', log)).toBe('');
+  });
+
+  it('collects unset var names into the optional collector set', () => {
+    const { log } = fakeLog();
+    const unset = new Set<string>();
+    substituteEnvVars({ url: '{env:MCP_TEST_MISSING}', headers: { k: '{env:MCP_TEST_SECRET}' } }, log, unset);
+    expect([...unset]).toEqual(['MCP_TEST_MISSING']);
+  });
+});

apps/server/src/services/__tests__/mistake-tracker.test.ts

@@ -0,0 +1,164 @@
+import { describe, it, expect } from 'vitest';
+import {
+  MISTAKE_THRESHOLD,
+  freshMistakeState,
+  recordStep,
+  detectMistakePattern,
+  MISTAKE_RECOVERY_NOTE,
+  type FailureKind,
+} from '../inference/mistake-tracker.js';
+
+// ---- helpers ----------------------------------------------------------------
+// Replays a sequence of outcomes against a fresh state, returning the final
+// state so assertions can read .run / .nudges. The caller mimics turn.ts: after
+// each recordStep we consult detectMistakePattern and, if it returns 'nudge',
+// bump nudges + reset run (the loop's nudge-handling side effect).
+
+function replay(
+  outcomes: (FailureKind | 'success')[],
+  { applyNudge = false }: { applyNudge?: boolean } = {},
+) {
+  const state = freshMistakeState();
+  const decisions: (ReturnType<typeof detectMistakePattern>)[] = [];
+  for (const o of outcomes) {
+    recordStep(state, o);
+    const decision = detectMistakePattern(state);
+    decisions.push(decision);
+    if (applyNudge && decision === 'nudge') {
+      // Mirror turn.ts's nudge side effect: bump the counter, reset the streak.
+      state.nudges += 1;
+      state.run = [];
+    }
+  }
+  return { state, decisions };
+}
+
+// ---- fresh state ------------------------------------------------------------
+
+describe('freshMistakeState', () => {
+  it('starts with an empty run and zero nudges', () => {
+    const s = freshMistakeState();
+    expect(s.run).toEqual([]);
+    expect(s.nudges).toBe(0);
+  });
+});
+
+// ---- below threshold --------------------------------------------------------
+
+describe('detectMistakePattern — below threshold', () => {
+  it('returns null on a fresh state', () => {
+    expect(detectMistakePattern(freshMistakeState())).toBeNull();
+  });
+
+  it('returns null after fewer than MISTAKE_THRESHOLD failures', () => {
+    const { decisions } = replay(['zod_reject', 'exec_error']);
+    expect(decisions).toEqual([null, null]);
+  });
+});
+
+// ---- success reset ----------------------------------------------------------
+
+describe('recordStep — success resets', () => {
+  it("'success' clears both the run streak and the nudge counter", () => {
+    const state = freshMistakeState();
+    recordStep(state, 'zod_reject');
+    recordStep(state, 'exec_error');
+    state.nudges = 2; // simulate prior nudges
+    recordStep(state, 'success');
+    expect(state.run).toEqual([]);
+    expect(state.nudges).toBe(0);
+  });
+
+  it('a success mid-streak prevents the threshold from tripping', () => {
+    // fail, fail, success, fail, fail → streak never reaches 3.
+    const { decisions } = replay([
+      'zod_reject',
+      'exec_error',
+      'success',
+      'tool_not_found',
+      'permission_denied',
+    ]);
+    expect(decisions.every((d) => d === null)).toBe(true);
+  });
+});
+
+// ---- 3-streak nudge ---------------------------------------------------------
+
+describe('detectMistakePattern — nudge on 3-streak', () => {
+  it("returns 'nudge' the first time the streak reaches MISTAKE_THRESHOLD", () => {
+    const { decisions } = replay(['zod_reject', 'exec_error', 'tool_not_found']);
+    expect(decisions).toEqual([null, null, 'nudge']);
+  });
+
+  it("fires 'nudge' for a streak of identical kinds too (kind-agnostic)", () => {
+    const { decisions } = replay(['exec_error', 'exec_error', 'exec_error']);
+    expect(decisions[2]).toBe('nudge');
+  });
+});
+
+// ---- re-trip escalate -------------------------------------------------------
+
+describe('detectMistakePattern — escalate on re-trip', () => {
+  it("escalates when the streak re-trips after a nudge with no intervening success", () => {
+    // 3 fails → nudge (run reset, nudges=1), then 3 more fails → escalate.
+    const { decisions } = replay(
+      [
+        'zod_reject',
+        'exec_error',
+        'tool_not_found',
+        'permission_denied',
+        'exec_error',
+        'zod_reject',
+      ],
+      { applyNudge: true },
+    );
+    expect(decisions[2]).toBe('nudge');
+    expect(decisions[5]).toBe('escalate');
+  });
+
+  it("does NOT escalate if a success lands between the nudge and the next streak", () => {
+    const { decisions } = replay(
+      [
+        'zod_reject',
+        'exec_error',
+        'tool_not_found', // nudge here
+        'success', // clears nudges back to 0
+        'exec_error',
+        'zod_reject',
+        'tool_not_found', // 3-streak again → nudge, NOT escalate
+      ],
+      { applyNudge: true },
+    );
+    expect(decisions[2]).toBe('nudge');
+    expect(decisions[6]).toBe('nudge');
+    expect(decisions).not.toContain('escalate');
+  });
+});
+
+// ---- mixed kinds ------------------------------------------------------------
+
+describe('detectMistakePattern — mixed failure kinds', () => {
+  it('counts a streak of all five distinct kinds toward the threshold', () => {
+    const { state, decisions } = replay([
+      'zod_reject',
+      'tool_not_found',
+      'exec_error',
+    ]);
+    expect(decisions[2]).toBe('nudge');
+    expect(state.run).toEqual(['zod_reject', 'tool_not_found', 'exec_error']);
+  });
+});
+
+// ---- contract ---------------------------------------------------------------
+
+describe('MISTAKE_THRESHOLD + MISTAKE_RECOVERY_NOTE', () => {
+  it('threshold is a positive integer (tests assume 3)', () => {
+    expect(MISTAKE_THRESHOLD).toBeGreaterThan(0);
+    expect(Number.isInteger(MISTAKE_THRESHOLD)).toBe(true);
+  });
+
+  it('recovery note is a non-empty model-facing string', () => {
+    expect(typeof MISTAKE_RECOVERY_NOTE).toBe('string');
+    expect(MISTAKE_RECOVERY_NOTE.length).toBeGreaterThan(0);
+  });
+});