fix(docker): trust bind-mounted repos via git safe.directory

The container runs as root over uid-1000-owned host repos; git's dubious-
ownership guard made every project read as not-a-repo, hiding the git diff
panel's Git tab and nulling the branch indicator. Bakes safe.directory='*'
into the runtime image. Applied live to the running container too.

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

BOOCHAT.md

@@ -28,6 +28,11 @@
 - Prefer codecontext (`search_symbols`, `get_symbol_info`, `get_dependencies`) over `grep` for symbol-level questions. Fall back to `grep` / `view_file` when codecontext returns degraded or empty results — that signals an unsupported language or parse failure.
 - Verify before reporting work complete: run the relevant test/build/smoke command and confirm output matches the claim. Evidence first, assertion second.
 
+## Recovery and context (v2.7)
+
+- **Heed the recovery nudge.** Native inference tracks consecutive tool **failures** (`mistake-tracker.ts`): after 3 in a row with no successful step between, a `mistake_recovery` sentinel is injected telling you to re-read tool schemas, verify a path exists before acting, and try a *different* approach — not retry variations of the same failing call. Ignoring it (a second failure run with the nudge still outstanding) **escalates and stops the turn** to protect the step budget. This complements the doom-loop guard, which only catches *identical* repeats.
+- **Files-read provenance survives compaction.** Paths you read via `view_file` / `grep` / `find_files` / `list_dir` are accumulated and merged into a cumulative `## Files Read` ledger in the rolling summary, so a file read long ago stays in context across compactions. You don't manage this — but it means you usually don't need to re-read a file just because the raw turn scrolled out of the window.
+
 ## Output format
 
 - Stay in Markdown by default for every reply, short or long.

BOOCODER.md

@@ -23,6 +23,8 @@ You are BooCoder, a write-capable coding agent. You can read AND modify files wi
 
 Every file modification queues in `pending_changes` before touching disk. The user sees a diff preview and approves/rejects each change. Never bypass this queue — it is the safety boundary between inference and the filesystem.
 
+`edit_file`'s `old_string` match is **fuzzy** (`fuzzy-match.ts`, v2.7.1): an exact → per-line-whitespace → unicode-canonicalization (curly quotes/dashes/nbsp) → Levenshtein-≥0.66 ladder, so minor whitespace/indentation/unicode drift in `old_string` still lands on the right span. Two consequences: a near-miss `old_string` may still apply (verify the queued diff is what you intended), and an `old_string` matching **more than one** place is rejected as **ambiguous** rather than editing the first — add surrounding context to disambiguate. A genuine non-match returns a clear failure, not a thrown error.
+
 ## Behavior
 
 - Show diffs clearly. Explain what you're changing and why.
@@ -102,7 +104,7 @@ Either way, **adding to config does NOT install the binary.** Until the CLI is o
 ### Deploy + smoke
 
 Two deploy targets:
-- **Routes (host service):** `pnpm -C apps/server build && pnpm -C apps/coder build && sudo systemctl restart boocoder`
+- **Routes (host service):** `pnpm -C packages/contracts build && pnpm -C apps/server build && pnpm -C apps/coder build && sudo systemctl restart boocoder`
 - **Web UI (container):** `docker compose up --build -d boocode`
 
 Green gate (verified across phases 1–5): `pnpm -C apps/coder test` (134 passing) `&& pnpm -C apps/coder build`.
@@ -115,3 +117,35 @@ curl http://100.114.205.53:9500/api/coder/providers/config   # raw config, throu
 # Settings → Providers: disable goose → it leaves the composer picker, stays in the tab
 # POST refresh → models repopulate; Add a catalog entry → it appears after refresh (unavailable until its CLI is installed)
 ```
+
+## Persistent agent sessions (v2.6)
+
+When you `dispatch_external_agent` to a chat-tab provider, BooCoder keeps that agent **warm and resumable** instead of spawning a fresh process per turn. This is mostly transparent — but the model below explains why turn 2 is fast, why an external agent remembers earlier turns, and how edits flow.
+
+### Backends and keying
+
+- One live backend per **`(chat_id, agent)`** pair, owned by the `agent-pool` (`agent-pool.ts`). State lives in `agent_sessions` (the resumable session id) and `worktrees` (the per-chat working copy).
+- **opencode** runs a long-lived `opencode serve` (`backends/opencode-server.ts`) with per-session SSE; turns after the first reuse the same session (memory intact, ~9× faster).
+- **goose / qwen** run a warm ACP connection (`backends/warm-acp.ts`) — `initialize` + `session/new` once per `(chat,agent)`, then `session/prompt` per turn. Interrupt cancels the prompt (`session/cancel`), never the child.
+- **claude** runs the Claude Agent SDK backend (`backends/claude-sdk.ts`) over a clean-room Postgres session store.
+- Arena, MCP `new_task`, and one-shot dispatches still use the cold `runExternalAgent` path — warm reuse needs both a `session_id` and a `chat_id`.
+
+### Worktrees
+
+- External agents write **directly into a persistent per-chat worktree** (`/tmp/booworktrees/sess-<id>`), not into the project root via `pending_changes`. The worktree is created once, base commit captured, and **reused across turns and across agents in the same chat** — so opencode and goose in one chat share one worktree.
+- Each turn's worktree diff supersedes the prior `pending_changes` row for that `(chat,agent)` (latest-wins) and is badged with the authoring agent in the DiffPanel.
+- **Staging boundary:** a provider only sees another agent's edits once they are **applied**. Unapplied worktree edits from a different agent are invisible to you — the DiffPanel shows a muted hint when that's the case.
+
+### Lifecycle (v2.6.10–v2.6.11)
+
+- **Idle eviction:** a backend idle past `AGENT_POOL_IDLE_TTL_MS` (default 30 min) is disposed; an LRU cap of `AGENT_POOL_MAX_LIVE` (default 10) bounds live backends. A busy backend is never evicted, and the next turn transparently re-attaches or re-creates from `agent_sessions`/`worktrees`.
+- **Crash recovery:** a health monitor restarts a crashed server (opencode → fresh sessions; ACP → re-`session/new`) and reclaims its port.
+- **Close cleanup:** closing/deleting a chat or session evicts its backends, archives the `worktrees` row, and removes the worktree. An hourly reaper sweeps orphaned worktrees (dirty/unpushed preflight before removal).
+
+### Checkpoints (v2.7.1)
+
+Because external agents write the worktree directly (outside `pending_changes`), a worktree **checkpoint** is shadow-committed before each external-agent turn (tracked + untracked, into `refs/boocode/checkpoints/<id>`), anchored to that turn's assistant message. The per-message **"Restore to here"** affordance 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. `rewind` still only reverses BooCoder's own applied `pending_changes`; checkpoints are what cover external-agent worktree edits.
+
+### Normalized status (v2.6 / v2.7.6)
+
+Turn boundaries publish a normalized per-`(chat,agent)` status — `working | blocked | idle | error` — to the UI (`agent_status_updated` frame), so blocked-on-permission and crash/idle are visible, not just WS liveness.

CHANGELOG.md

@@ -2,6 +2,38 @@
 
 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.16-container-git-safedir — 2026-06-03
+
+Hotfix that makes the `v2.7.15-git-diff-panel` work in production. The `boocode` container runs as root but bind-mounts host project repos owned by uid 1000, so git rejected them with "detected dubious ownership" and the diff route reported every project as not-a-repo — which hid the Git tab entirely (and had been silently nulling the existing branch indicator too). Adds `git config --system --add safe.directory '*'` to the Dockerfile runtime stage so the container's git trusts the mounted repos; applied live to the running container and baked into the image for future rebuilds. Surfaced by a live smoke immediately after the v2.7.14/v2.7.15 deploy.
+
+## v2.7.15-git-diff-panel — 2026-06-03
+
+A Files / Git tab in the right-side file panel (the file-browser sidebar) that shows the project repository's git diff and lets the user stage, unstage, commit, and discard whole files in-session — modeled on Paseo's diff view, scoped and planned through the `plan-a-feature` → `plan-implementation` skills, then built and audited via `paseo-epic` in an isolated worktree. Two comparison modes (Uncommitted vs HEAD, and the current branch vs its base — the upstream tracking branch else `origin/HEAD`), auto-selected by repo dirty-state on first open and pinned after an explicit choice; per-file expand/collapse with lazy Shiki `lang:'diff'` highlighting, +/- stats, and binary/too-large placeholders. All git read and write logic lives in `apps/server` (new `git_diff.ts` + routes on `projects.ts`) — the read-only-server posture governs the assistant's tools, not the user's own actions, and the container already mounts `/opt` read-write while `project_bootstrap` already commits via `execFile`. Every write uses the safe `execFile` argv pattern (never a shell string) with `--` operand separators, per-file `pathGuard` + realpath symlink-escape validation, server-derived `-c` commit identity (the request body is `.strict()` and carries no author fields), and the write endpoints are deliberately absent from the assistant tool registry. Reads are bounded (30s deadline, 10MB); an index lock or an in-progress merge/rebase/cherry-pick/bisect surfaces as "repository busy" and disables writes. The panel stays current via a client `git_diff_refresh` sessionEvent (no new wire contract) coalesced across tab-open, mutations, turn completion, and pending-change apply; discard is an irrecoverable hard-delete behind a plain confirm distinguishing a tracked revert from an untracked delete. New `git_diff` pure-helper + temp-repo integration tests (59 cases); server 630 tests green, web tsc clean. Pairs with `v2.7.14-backlog-hardening` (shipped together).
+
+## v2.7.14-backlog-hardening — 2026-06-03
+
+Five independent items from the second external-code-review backlog (`boocode_code_review_v2.md`), each built and audited as its own phase via `paseo-epic`. **External task-cancel** now actually works: Stop on an opencode/goose/qwen/claude task aborts the running child via a per-task `AbortController` registry reachable from the cancel route and finalizes the assistant message as `cancelled` — fixing two latent bugs (catch blocks left the message `streaming`; warm success-paths wrote `complete` on an aborted turn); warm pools/worktrees are preserved (abort the prompt only, never the pooled process) and the native boocode path is unchanged. **Parser prune**: the tool-call parser drops to its two load-bearing exports (eight zero-caller symbols unexported, a gate test added for the `<invoke>`-as-text fallback) with no live-path behavior change, and placeholder-rejection logging moves to pino. **BooChat stall-timeout**: a 90s per-chunk deadline wraps native inference's `fullStream` via `AbortSignal.any` so a hung local stream finalizes the message instead of hanging — no retry, since re-running re-emits already-streamed deltas (a pure `classifyStreamError` helper is added). **view_session_history**: a read-only MCP tool returning the newest-N transcript (role≠system) in chronological order. **Retire :9502**: the unused `apps/coder/web` fallback SPA is removed (package, static-serve block, build step, Dockerfile copy, `@fastify/static`), keeping every API/WS/health/MCP route. F1 added an optional `status` field to the shared `message_complete` contracts frame (so a deploy rebuilds `@boocode/contracts` first, as the sequence already does). Server 630 / coder 360 tests green.
+
+## v2.7.13-contracts-ssot — 2026-06-02
+
+Creates `@boocode/contracts` (`packages/contracts`), a new workspace package that becomes the single source of truth for every cross-app wire contract — reversing the decision recorded in `v2.5.12-provider-lifecycle-phase4` that declined a shared types package as not worth the Docker/build-order risk at solo scale; a live `AgentSessionConfig` drift that had since appeared between `apps/coder` and `apps/web` justified the investment. Six contracts are now defined exactly once: the `WsFrameSchema` Zod runtime schema, the provider snapshot types (`ProviderSnapshotEntry` and family), the Zod provider-config schemas, `MessageMetadata` + `ErrorReason`, `AgentSessionConfig`, and `WorktreeRiskReport`; both Zod-backed contracts use `z.infer` so validator and type derive from the same definition and cannot drift independently. All four consumers — `apps/server`, `apps/web`, `apps/coder`, and the fallback SPA `apps/coder/web` — import via `workspace:*` through a per-subpath exports map consuming built dist only (no tsconfig project references); the hand-synced copies and their parity tests (`provider-types-parity.test.ts`; the ws-frames byte-parity assertion) are deleted while the KNOWN_FRAME_TYPES drift test and broker fail-closed tests are preserved. Build order is inverted in the root build script, Dockerfile, and coder deploy docs; `apps/coder/web`'s migration also removed dead `pending_change_*` reducer arms (no frame publisher exists for these — pending changes are HTTP-delivered), closing a latent missing-default-arm crash, and reconciled field-type conflicts with the canonical `WsFrame`; zod is pinned to a single version across the workspace. Server 543 / coder 293 / contracts 11 tests passing; human smoke verified on the live stack 2026-06-02.
+
+## 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`.

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.
 
@@ -23,98 +23,33 @@ pnpm -C apps/server build  # server only (tsc + copy schema.sql)
 pnpm -C apps/web build     # web only (vite)
 
 # Type checking (no emit)
-npx tsc --noEmit                              # project references (root)
+# Per-app is authoritative. There is NO root tsconfig.json (only tsconfig.base.json),
-npx tsc -p apps/web/tsconfig.app.json --noEmit  # web app specifically
+# so a bare `npx tsc --noEmit` at root compiles nothing.
-
+npx tsc -p apps/web/tsconfig.app.json --noEmit   # web (authoritative)
-# IMPORTANT: root tsc --noEmit uses project references and can miss errors
+pnpm -C apps/server build                        # server typecheck (tsc + copy schema)
-# that the per-app tsconfig catches. Always verify with the per-app command
+pnpm -C apps/coder build                         # coder typecheck
-# when editing web code. The server build (pnpm -C apps/server build) is
+pnpm -C apps/booterm typecheck                   # booterm typecheck
-# authoritative for server code.
 
 # Production
 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`). `apps/coder` has its own vitest suite too — `pnpm -C apps/coder test` (same `src/**/__tests__/**/*.test.ts` glob; `globals:false`, so import `describe`/`it`/`expect` from `vitest`). Extract pure helpers to unit-test (`backends/turn-guard.ts`, `lifecycle-decisions.ts` are the pattern).
+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), `packages/contracts` (`@boocode/contracts`, cross-app wire-contract SSOT — builds FIRST).
 
-### Server (`apps/server/src/`)
+### Per-app deep references
 
-- **Fastify** with `@fastify/websocket` and `@fastify/static` (serves built frontend)
+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):
-- **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:
+- **`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.
-- **`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.
+- **`apps/coder/CLAUDE.md`** — BooCoder dispatch, provider registry/probe/snapshot, opencode/ACP/PTY/Claude-SDK backends, `agent_sessions` resume.
-- **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:
+- **`apps/web/CLAUDE.md`** — React app, hooks/event buses, font & CSS pipeline, multi-pane workspace, all UI conventions.
-  - **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.
+- **`docs/project-discovery.md`** — full stack / tooling / command inventory across all packages (read-on-demand).
-  - **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`.
 
-Route registration: all routes registered in `index.ts` via `register*Routes(app, sql, ...)` functions. Routes are in `routes/*.ts`.
+Cross-app contracts (WS-frame & provider-type parity, sentinels) and everything below stay here.
-
-### 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.
-- **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). `: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). 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.
 
 ### Data flow for chat
 
@@ -125,92 +60,67 @@ 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`).
+
+**A `SELECT *` view pins every column** (`2BP01`): `DROP COLUMN` on the table fails while such a view exists. `human_inbox` is `SELECT * FROM tasks` — to drop a `tasks` column, `DROP VIEW IF EXISTS human_inbox` first, drop the column(s), then recreate the view (idempotent). Bites existing DBs only; a fresh DB never had the column, so fresh-DB testing misses it.
 
 ## 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}`.
+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 packages/contracts build && 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.
+- `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 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.
+- 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 (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.
+- 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.
-- Sam often has uncommitted `apps/web` work in flight mid-session — stage your own commits **explicitly by path** (never `git add -A`); and `docker compose up --build -d boocode` builds the working tree, so a container rebuild also ships his uncommitted web changes.
+- 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.
-- Cutting a release: name the feature branch DIFFERENTLY from the tag (branch `f1-interrupt-guard`, tag `v2.6.7-interrupt-guard`) — identical branch+tag names trigger `warning: refname ... is ambiguous`.
+- **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.
-- 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.
+- 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`.
-- 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).
+- 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`).
-- `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.
+- 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).
-- 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).
+- `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.
-- 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`. 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.
+- 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 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`.
+- 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. Faster than bisecting source. Watch for `=== null`/`!== null` on optional fields fed an `as unknown as` cast — those bypass tsc.
+- 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 setting `Content-Type` tricks on the client.
+- 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.
+- `/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` (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.
+- 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/`. 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 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 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.
+- 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 by default). Use `export PATH=$PATH:/snap/go/current/bin` or full path for Go commands.
+- 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 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.
+- `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`.
+- TypeScript strict mode. Both apps share `tsconfig.base.json`. Server + coder use NodeNext module resolution (`.js` extensions in imports).
-- Server uses 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.
+- **Adding a new WS frame type** (cross-app): add it to `WsFrameSchema` in `packages/contracts/src/ws-frames.ts` (single source of truth; rebuild with `pnpm -C packages/contracts build`). The server's `InferenceFrame` loose union (`services/inference/turn.ts`) and the web's strict `WsFrame` discriminated union (`apps/web/src/api/types.ts`) still exist separately and also need updating. Server publish is permissive; the frontend type is the wire-format gate — 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.
+- **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. `MessageMetadata` is single-sourced in `@boocode/contracts` (`packages/contracts/src/message-metadata.ts`). A new kind requires updating that file and rebuilding the package, plus a render branch in `apps/web/src/components/MessageBubble.tsx`.
-- `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".
+- **Provider snapshot types** (`ProviderSnapshotEntry`, `ProviderModel`, `ProviderMode`, `ThinkingOption`, `AgentCommand`, `ProviderSnapshotStatus`) are single-sourced in `@boocode/contracts` (`packages/contracts/src/provider-snapshot.ts`); `apps/coder/src/services/provider-types.ts` re-exports them. Edit the package source; there is no hand-synced web copy to update.
-- `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.
+- **`@boocode/contracts`** single-sources cross-app wire contracts via per-subpath built-dist exports, consumed by all four apps (incl. `apps/coder/web`): `./ws-frames`, `./provider-snapshot`, `./provider-config` (Zod schemas), `./message-metadata` (`MessageMetadata`/`ErrorReason`/`AgentSessionConfig`), `./worktree-risk`. It builds BEFORE every consumer (root build, Dockerfile, coder deploy). Its `WsFrame` is the loose `z.infer` of `WsFrameSchema` (payloads `unknown`); the web's richer strict `WsFrame` union is **deliberately web-local** (`apps/web/src/api/types.ts`), bridged to the validated frame by a cast — don't move it into the package. Consume built `dist` via the exports map; never add the package to a tsconfig `references` array.
-- 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.
+- **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`.
-- `vite.config.ts` proxy entries are order-sensitive: more-specific prefixes (`/api/term`, `/ws/term`) must come BEFORE `/api`.
+- 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.
-- 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.
+### Coding standards
-- 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.
+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.
-- **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).

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)
+- **Last shipped:** `v2.7.8-ember-coder-tabs-model-chips` (2026-06-01)
-- **Branch:** `main`
+- **Branch:** `codebase-audit-cleanup` (audit + cleanup epic, off main HEAD)
-- **Blockers:** none
+- **In progress:** Phase 3 — stale comments + docs refresh
-- **Last shipped:** `v2.2.2-xml-placeholder-reject`
 
-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.

Dockerfile

@@ -5,11 +5,15 @@ RUN corepack enable
 WORKDIR /build
 
 COPY package.json pnpm-workspace.yaml pnpm-lock.yaml tsconfig.base.json ./
+COPY packages/contracts/package.json ./packages/contracts/
 COPY apps/server/package.json ./apps/server/
 COPY apps/web/package.json ./apps/web/
 
 RUN pnpm install --frozen-lockfile
 
+# @boocode/contracts must be present before `pnpm build`, which builds it FIRST
+# (root build script) so apps/web can resolve its compiled dist via the exports map.
+COPY packages/contracts ./packages/contracts
 COPY apps/server ./apps/server
 COPY apps/web ./apps/web
 
@@ -20,6 +24,9 @@ RUN pnpm deploy --filter=@boocode/server --prod --legacy /out/server
 
 FROM node:20-alpine AS runtime
 RUN apk add --no-cache ripgrep git openssh-client
+# The container runs as root but bind-mounts host project repos owned by uid 1000;
+# trust them so git read/write tools (git_status, the git diff panel) work over the mount.
+RUN git config --system --add safe.directory '*'
 RUN mkdir -p /root/.ssh && ssh-keyscan -p 2222 -H 100.114.205.53 git.indifferentketchup.com >> /root/.ssh/known_hosts && chmod 700 /root/.ssh && chmod 600 /root/.ssh/known_hosts
 WORKDIR /app
 

README.md

@@ -58,7 +58,7 @@ upstream and inject `Remote-User`. Postgres binds loopback only.
 BooCoder runs as a **host systemd service** (`boocoder.service`, port `:9502`), not in Docker:
 
 ```bash
-pnpm -C apps/server build && pnpm -C apps/coder build
+pnpm -C packages/contracts build && pnpm -C apps/server build && pnpm -C apps/coder build
 sudo systemctl restart boocoder
 curl http://100.114.205.53:9502/api/health
 ```

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": {

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/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 packages/contracts build && 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/Dockerfile

@@ -7,7 +7,6 @@ WORKDIR /build
 COPY package.json pnpm-workspace.yaml pnpm-lock.yaml tsconfig.base.json ./
 COPY apps/server/package.json ./apps/server/
 COPY apps/coder/package.json ./apps/coder/
-COPY apps/coder/web/package.json ./apps/coder/web/
 
 RUN pnpm install --frozen-lockfile
 
@@ -16,7 +15,6 @@ COPY apps/server ./apps/server
 RUN pnpm -C apps/server build
 
 COPY apps/coder ./apps/coder
-RUN pnpm -C apps/coder/web build
 RUN pnpm -C apps/coder build
 
 RUN pnpm deploy --filter=@boocode/coder --prod --legacy /out/coder
@@ -27,7 +25,6 @@ RUN apt-get update && apt-get install -y --no-install-recommends ripgrep git ope
 WORKDIR /app
 
 COPY --from=builder /out/coder ./
-COPY --from=builder /build/apps/coder/web/dist ./web
 
 ENV NODE_ENV=production
 EXPOSE 3000

apps/coder/package.json

@@ -13,10 +13,10 @@
     "test": "vitest run"
   },
   "dependencies": {
+    "@boocode/contracts": "workspace:*",
     "@agentclientprotocol/sdk": "^0.22.1",
     "@anthropic-ai/claude-agent-sdk": "^0.3.159",
     "@boocode/server": "workspace:*",
-    "@fastify/static": "^7.0.4",
     "@fastify/websocket": "^10.0.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@opencode-ai/sdk": "~1.15.0",

apps/coder/src/index.ts

@@ -1,12 +1,5 @@
-import { resolve, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { existsSync } from 'node:fs';
 import Fastify from 'fastify';
 import fastifyWebsocket from '@fastify/websocket';
-import fastifyStatic from '@fastify/static';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
 import { loadConfig } from './config.js';
 import { getSql, applySchema, pingDb, closeDb } from './db.js';
 import { startMcpServer } from './services/mcp-server.js';
@@ -16,7 +9,7 @@ import { createInferenceRunner } from '@boocode/server/inference';
 import { createBroker } from '@boocode/server/broker';
 import { appendMcpTools, ALL_TOOLS } from '@boocode/server/tools';
 import type { Config as ServerConfig } from '@boocode/server/config';
-import type { WsFrame } from '@boocode/server/ws-frames';
+import type { WsFrame } from '@boocode/contracts/ws-frames';
 // v2.0.0 Phase 2C: write tools + adapter for BooChat ToolDef compatibility.
 import { WRITE_TOOLS } from './services/tools/index.js';
 import { adaptWriteTool } from './services/tools/adapter.js';
@@ -257,7 +250,7 @@ async function main() {
   registerPendingRoutes(app, sql);
   registerCheckpointRoutes(app, sql);
   registerAgentSessionRoutes(app, sql);
-  registerTaskRoutes(app, sql, inferenceApi);
+  registerTaskRoutes(app, sql, inferenceApi, dispatcher.cancelExternalTask);
   registerInboxRoutes(app, sql);
   registerStatsRoutes(app, sql);
   registerArenaRoutes(app, sql);
@@ -266,28 +259,6 @@ async function main() {
   registerLifecycleRoutes(app, sql);
   registerWebSocket(app, sql, broker);
 
-  // Serve static frontend (built web app). In production, the dist/ is
-  // copied to ../web relative to the dist/ directory at /app/web. In dev,
-  // check adjacent to the source.
-  const webRoot = resolve(__dirname, '../web');
-  if (existsSync(webRoot)) {
-    await app.register(fastifyStatic, {
-      root: webRoot,
-      prefix: '/',
-      // Don't intercept /api routes — static only serves files that exist.
-      wildcard: false,
-    });
-    // SPA fallback: serve index.html for non-API routes that don't match a file.
-    app.setNotFoundHandler(async (req, reply) => {
-      if (req.url.startsWith('/api')) {
-        reply.code(404);
-        return { error: 'not found' };
-      }
-      return reply.sendFile('index.html');
-    });
-    app.log.info(`serving frontend from ${webRoot}`);
-  }
-
   // Graceful shutdown
   const shutdown = async () => {
     app.log.info('shutting down');

apps/coder/src/routes/__tests__/tasks-cancel.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import Fastify, { type FastifyInstance } from 'fastify';
+import postgres from 'postgres';
+import { registerTaskRoutes } from '../tasks.js';
+
+/**
+ * F1 — POST /api/tasks/:id/cancel route wiring.
+ *
+ * The route's job: reach the in-flight external run via `cancelExternal(taskId)`
+ * (the new abort hook), keep cancelling native inference for open chats unchanged,
+ * and land the task row in 'cancelled'. The streaming assistant message is
+ * finalized by the dispatcher's run-function, not here — that path is covered by
+ * finalize-message.test.ts. This suite pins the route's behavior against a real DB.
+ */
+describe.runIf(!!process.env.DATABASE_URL)('POST /api/tasks/:id/cancel (route, F1)', () => {
+  let sql: ReturnType<typeof postgres>;
+  let app: FastifyInstance;
+  let projectId: string;
+  let sessionId: string;
+  let chatId: string;
+
+  const externalCancelCalls: string[] = [];
+  const inferenceCancelCalls: Array<[string, string]> = [];
+  let externalReturns = true;
+
+  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'));
+
+    const [p] = await sql<{ id: string }[]>`
+      INSERT INTO projects (name, path, status) VALUES ('f1-cancel-route', '/tmp/f1-cancel-route', 'open') RETURNING id
+    `;
+    projectId = p!.id;
+    const [s] = await sql<{ id: string }[]>`
+      INSERT INTO sessions (project_id, name, model, status) VALUES (${projectId}, 'f1', 'm', 'open') RETURNING id
+    `;
+    sessionId = s!.id;
+    const [c] = await sql<{ id: string }[]>`
+      INSERT INTO chats (session_id, name, status) VALUES (${sessionId}, 'tab', 'open') RETURNING id
+    `;
+    chatId = c!.id;
+
+    app = Fastify();
+    registerTaskRoutes(
+      app,
+      sql,
+      {
+        cancel: async (sid: string, cid: string) => {
+          inferenceCancelCalls.push([sid, cid]);
+          return false;
+        },
+      },
+      (taskId: string) => {
+        externalCancelCalls.push(taskId);
+        return externalReturns;
+      },
+    );
+    await app.ready();
+  });
+
+  afterAll(async () => {
+    if (app) await app.close();
+    if (!sql) return;
+    await sql`DELETE FROM messages WHERE session_id = ${sessionId}`.catch(() => {});
+    await sql`DELETE FROM tasks WHERE project_id = ${projectId}`.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 });
+  });
+
+  async function insertTask(agent: string | null, state: string): Promise<string> {
+    const [t] = await sql<{ id: string }[]>`
+      INSERT INTO tasks (project_id, input, agent, session_id, state, started_at)
+      VALUES (${projectId}, 'do a thing', ${agent}, ${sessionId}, ${state}, clock_timestamp())
+      RETURNING id
+    `;
+    return t!.id;
+  }
+
+  it('reaches cancelExternal and lands the task cancelled for a running external task', async () => {
+    externalReturns = true;
+    externalCancelCalls.length = 0;
+    const taskId = await insertTask('opencode', 'running');
+
+    const res = await app.inject({ method: 'POST', url: `/api/tasks/${taskId}/cancel` });
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({ cancelled: true });
+
+    expect(externalCancelCalls).toContain(taskId);
+
+    const [row] = await sql<{ state: string; ended_at: Date | null }[]>`
+      SELECT state, ended_at FROM tasks WHERE id = ${taskId}
+    `;
+    expect(row!.state).toBe('cancelled');
+    expect(row!.ended_at).not.toBeNull();
+  });
+
+  it('still cancels a native boocode task (cancelExternal returns false → inference.cancel path unchanged)', async () => {
+    externalReturns = false; // native task: no controller registered
+    externalCancelCalls.length = 0;
+    inferenceCancelCalls.length = 0;
+    const taskId = await insertTask(null, 'running');
+
+    const res = await app.inject({ method: 'POST', url: `/api/tasks/${taskId}/cancel` });
+    expect(res.statusCode).toBe(200);
+
+    // The route calls cancelExternal unconditionally (cheap, returns false here)...
+    expect(externalCancelCalls).toContain(taskId);
+    // ...and the native inference.cancel path still fires for the open chat.
+    expect(inferenceCancelCalls).toContainEqual([sessionId, chatId]);
+
+    const [row] = await sql<{ state: string }[]>`SELECT state FROM tasks WHERE id = ${taskId}`;
+    expect(row!.state).toBe('cancelled');
+  });
+
+  it('rejects cancelling an already-terminal task with 409 and never touches the abort hook', async () => {
+    externalCancelCalls.length = 0;
+    const taskId = await insertTask('opencode', 'completed');
+
+    const res = await app.inject({ method: 'POST', url: `/api/tasks/${taskId}/cancel` });
+    expect(res.statusCode).toBe(409);
+    expect(externalCancelCalls).not.toContain(taskId);
+  });
+
+  it('returns 404 for an unknown task', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: `/api/tasks/00000000-0000-0000-0000-000000000000/cancel`,
+    });
+    expect(res.statusCode).toBe(404);
+  });
+});

apps/coder/src/routes/messages.ts

@@ -2,7 +2,7 @@ import type { FastifyInstance } from 'fastify';
 import { z } from 'zod';
 import type { Sql } from '../db.js';
 import type { Broker } from '@boocode/server/broker';
-import type { WsFrame } from '@boocode/server/ws-frames';
+import type { WsFrame } from '@boocode/contracts/ws-frames';
 import { resolveChatId } from './chat-resolve.js';
 
 const AnswerUserInputBody = z.object({

apps/coder/src/routes/skills.ts

@@ -2,7 +2,7 @@ import type { FastifyInstance } from 'fastify';
 import { z } from 'zod';
 import type { Sql } from '../db.js';
 import type { Broker } from '@boocode/server/broker';
-import type { WsFrame } from '@boocode/server/ws-frames';
+import type { WsFrame } from '@boocode/contracts/ws-frames';
 import { getSkillBody } from '@boocode/server/skills';
 import {
   buildSkillInvokeSyntheticFrames,

apps/coder/src/routes/tasks.ts

@@ -8,6 +8,12 @@ interface InferenceApi {
   cancel: (sessionId: string, chatId: string) => Promise<boolean>;
 }
 
+// F1: the dispatcher's reach into an in-flight external-agent run. Narrow by
+// design (not the whole dispatcher) — the route only needs to fire the abort.
+// Returns true when a controller was registered for the task (an external run was
+// in flight), false otherwise (native boocode task, or already finished).
+export type ExternalCancelFn = (taskId: string) => boolean;
+
 const CreateBody = z.object({
   project_id: z.string().uuid(),
   input: z.string().min(1).max(64_000),
@@ -27,7 +33,12 @@ const ListQuery = z.object({
   project_id: z.string().uuid().optional(),
 });
 
-export function registerTaskRoutes(app: FastifyInstance, sql: Sql, inference: InferenceApi): void {
+export function registerTaskRoutes(
+  app: FastifyInstance,
+  sql: Sql,
+  inference: InferenceApi,
+  cancelExternal: ExternalCancelFn,
+): void {
   // POST /api/tasks — create a new task
   app.post('/api/tasks', async (req, reply) => {
     const parsed = CreateBody.safeParse(req.body);
@@ -95,7 +106,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}
     `;
@@ -127,7 +138,14 @@ export function registerTaskRoutes(app: FastifyInstance, sql: Sql, inference: In
 
     cancelPendingPermission(taskId);
 
-    // If running, try to cancel inference
+    // F1: abort the in-flight external-agent run (opencode / goose / qwen / claude).
+    // Idempotent — a double-Stop re-aborts harmlessly; a native boocode task is not
+    // registered, so this returns false and the inference.cancel path below handles
+    // it unchanged. The dispatcher's run-function finalizes the streaming assistant
+    // message as 'cancelled' once the backend honors the signal.
+    cancelExternal(taskId);
+
+    // If running, try to cancel inference (native boocode path — unchanged).
     if ((task.state === 'running' || task.state === 'blocked') && task.session_id) {
       // Find active chat in the task's session
       const chats = await sql<{ id: string }[]>`

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,16 @@ 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;
+-- 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).
--- v2.6: one shared worktree per session (all agents/panes in the session operate in it).
+-- human_inbox is `SELECT *` over tasks, so it pins every task column — dropping a
-CREATE TABLE IF NOT EXISTS session_worktrees (
+-- column while the view exists fails (2BP01). Drop the view, drop the columns, then
-  session_id UUID PRIMARY KEY REFERENCES sessions(id) ON DELETE CASCADE,
+-- recreate it with the current column set (idempotent on fresh + existing DBs).
-  worktree_path TEXT NOT NULL,
+DROP VIEW IF EXISTS human_inbox;
-  base_commit TEXT,
+ALTER TABLE tasks DROP COLUMN IF EXISTS feature_values;
-  created_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp()
+ALTER TABLE tasks DROP COLUMN IF EXISTS worktree_path;
-);
+CREATE OR REPLACE VIEW human_inbox AS
--- P1.5-b: DEFANG the CASCADE — a session delete must no longer wipe its worktree
+  SELECT * FROM tasks WHERE state IN ('blocked', 'failed');
--- 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 $$;
 
 -- v2.6: one backend session per (session, agent); resumed on switch-back.
 CREATE TABLE IF NOT EXISTS agent_sessions (
@@ -168,12 +152,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
+-- session_worktrees was superseded by worktrees (v2.6/P1.5-b); all rows migrated
--- after the test-session delete, kept for generality / fresh-DB safety).
+-- before P2 cleanup. Drop the dead table; no-op on fresh DBs that never had it.
-INSERT INTO worktrees (session_id, path, branch, base_commit, status)
+DROP TABLE IF EXISTS session_worktrees;
-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');
 
 -- 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,

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__/cancel-registry.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest';
+import { createCancelRegistry } from '../cancel-registry.js';
+
+/**
+ * F1 — per-task abort wiring. The registry is the missing link between the Stop
+ * route and the in-flight external run: register an AbortController per task id,
+ * cancel(taskId) aborts its signal, the run's .finally deletes it. Pure (no DB /
+ * child / IO) so the abort + idempotency contract is unit-testable in isolation.
+ */
+describe('CancelRegistry (F1 abort wiring)', () => {
+  it('register hands back a fresh controller; cancel aborts its signal', () => {
+    const reg = createCancelRegistry();
+    const ac = reg.register('t1');
+    expect(ac.signal.aborted).toBe(false);
+    expect(reg.has('t1')).toBe(true);
+
+    expect(reg.cancel('t1')).toBe(true);
+    expect(ac.signal.aborted).toBe(true);
+  });
+
+  it('cancel on an unknown task returns false (native task / cancel-before-register)', () => {
+    const reg = createCancelRegistry();
+    expect(reg.has('nope')).toBe(false);
+    expect(reg.cancel('nope')).toBe(false);
+  });
+
+  it('double-Stop is idempotent: a second cancel never throws and the signal stays aborted', () => {
+    const reg = createCancelRegistry();
+    const ac = reg.register('t1');
+
+    expect(reg.cancel('t1')).toBe(true);
+    // The run-function has not hit its .finally yet, so the entry is still
+    // present — a rapid second Stop re-aborts (abort() no-ops) without throwing.
+    expect(() => reg.cancel('t1')).not.toThrow();
+    expect(reg.cancel('t1')).toBe(true);
+    expect(ac.signal.aborted).toBe(true);
+  });
+
+  it('cancel after delete returns false (cancel-after-natural-exit is safe)', () => {
+    const reg = createCancelRegistry();
+    reg.register('t1');
+    reg.delete('t1');
+    expect(reg.has('t1')).toBe(false);
+    expect(reg.cancel('t1')).toBe(false);
+  });
+
+  it('delete of an unknown id is a no-op (never throws)', () => {
+    const reg = createCancelRegistry();
+    expect(() => reg.delete('ghost')).not.toThrow();
+  });
+});

apps/coder/src/services/__tests__/finalize-message.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import postgres from 'postgres';
+import type { WsFrame } from '@boocode/contracts/ws-frames';
+import { classifyTerminalStatus, finalizeStreamingMessage } from '../finalize-message.js';
+
+/**
+ * F1 (D-7 / OCE-001 / OCE-002) — finalizing a Stop'd or errored external turn.
+ *
+ * `classifyTerminalStatus` is the pure D-7 decision (user Stop / AbortError →
+ * cancelled, genuine error → failed). `finalizeStreamingMessage` writes that
+ * terminal state onto the streaming assistant row and publishes the matching
+ * message_complete frame — idempotently, guarded by `WHERE status='streaming'`,
+ * so a double-Stop or an abort-then-catch settles the message exactly once and
+ * never clobbers a row that already finished cleanly.
+ */
+describe('classifyTerminalStatus (pure, D-7)', () => {
+  it('maps a fired abort signal to cancelled (user Stop)', () => {
+    expect(classifyTerminalStatus({ aborted: true })).toBe('cancelled');
+  });
+
+  it('maps a thrown AbortError to cancelled', () => {
+    const e = new Error('the operation was aborted');
+    e.name = 'AbortError';
+    expect(classifyTerminalStatus({ aborted: false, error: e })).toBe('cancelled');
+  });
+
+  it('maps a genuine thrown error to failed', () => {
+    expect(classifyTerminalStatus({ aborted: false, error: new Error('boom') })).toBe('failed');
+  });
+
+  it('defaults a no-abort / no-error catch to failed', () => {
+    expect(classifyTerminalStatus({ aborted: false })).toBe('failed');
+  });
+});
+
+describe.runIf(!!process.env.DATABASE_URL)('finalizeStreamingMessage (DB)', () => {
+  let sql: ReturnType<typeof postgres>;
+  let projectId: string;
+  let sessionId: string;
+  let chatId: string;
+
+  beforeAll(async () => {
+    sql = postgres(process.env.DATABASE_URL!, { max: 3 });
+    // Server schema owns messages/sessions/chats (FK targets); coder schema after.
+    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'));
+
+    const [p] = await sql<{ id: string }[]>`
+      INSERT INTO projects (name, path, status) VALUES ('f1-finalize', '/tmp/f1-finalize', 'open') RETURNING id
+    `;
+    projectId = p!.id;
+    const [s] = await sql<{ id: string }[]>`
+      INSERT INTO sessions (project_id, name, model, status) VALUES (${projectId}, 'f1', 'm', 'open') RETURNING id
+    `;
+    sessionId = s!.id;
+    const [c] = await sql<{ id: string }[]>`
+      INSERT INTO chats (session_id, name, status) VALUES (${sessionId}, 'tab', 'open') RETURNING id
+    `;
+    chatId = c!.id;
+  });
+
+  afterAll(async () => {
+    if (!sql) return;
+    await sql`DELETE FROM messages 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 });
+  });
+
+  async function insertStreaming(): Promise<string> {
+    const [m] = await sql<{ id: string }[]>`
+      INSERT INTO messages (session_id, chat_id, role, content, status)
+      VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming') RETURNING id
+    `;
+    return m!.id;
+  }
+
+  it('finalizes a streaming row to cancelled, persists partial content, publishes one frame', async () => {
+    const id = await insertStreaming();
+    const frames: WsFrame[] = [];
+    const did = await finalizeStreamingMessage(sql, (_s, f) => frames.push(f), {
+      sessionId,
+      chatId,
+      assistantId: id,
+      status: 'cancelled',
+      model: 'qwen',
+      content: 'partial answer',
+    });
+
+    expect(did).toBe(true);
+    const [row] = await sql<{ status: string; content: string; finished_at: Date | null }[]>`
+      SELECT status, content, finished_at FROM messages WHERE id = ${id}
+    `;
+    expect(row!.status).toBe('cancelled');
+    expect(row!.content).toBe('partial answer');
+    expect(row!.finished_at).not.toBeNull();
+    expect(frames).toHaveLength(1);
+    expect(frames[0]!.type).toBe('message_complete');
+    expect((frames[0] as { status?: string }).status).toBe('cancelled');
+  });
+
+  it('is idempotent for a double-Stop: second call updates nothing and re-publishes nothing', async () => {
+    const id = await insertStreaming();
+    const frames: WsFrame[] = [];
+    const push = (_s: string, f: WsFrame): void => {
+      frames.push(f);
+    };
+
+    expect(
+      await finalizeStreamingMessage(sql, push, { sessionId, chatId, assistantId: id, status: 'cancelled', model: null }),
+    ).toBe(true);
+    expect(
+      await finalizeStreamingMessage(sql, push, { sessionId, chatId, assistantId: id, status: 'cancelled', model: null }),
+    ).toBe(false);
+
+    expect(frames).toHaveLength(1);
+    const [row] = await sql<{ status: string }[]>`SELECT status FROM messages WHERE id = ${id}`;
+    expect(row!.status).toBe('cancelled');
+  });
+
+  it('never clobbers a row that already finished cleanly (abort raced a clean finish)', async () => {
+    const [m] = await sql<{ id: string }[]>`
+      INSERT INTO messages (session_id, chat_id, role, content, status)
+      VALUES (${sessionId}, ${chatId}, 'assistant', 'done', 'complete') RETURNING id
+    `;
+    const id = m!.id;
+    const frames: WsFrame[] = [];
+
+    const did = await finalizeStreamingMessage(sql, (_s, f) => frames.push(f), {
+      sessionId,
+      chatId,
+      assistantId: id,
+      status: 'cancelled',
+      model: null,
+    });
+
+    expect(did).toBe(false);
+    expect(frames).toHaveLength(0);
+    const [row] = await sql<{ status: string; content: string }[]>`
+      SELECT status, content FROM messages WHERE id = ${id}
+    `;
+    expect(row!.status).toBe('complete');
+    expect(row!.content).toBe('done');
+  });
+
+  it('no-ops on an empty assistantId (throw happened before the row was created)', async () => {
+    const frames: WsFrame[] = [];
+    const did = await finalizeStreamingMessage(sql, (_s, f) => frames.push(f), {
+      sessionId,
+      chatId,
+      assistantId: '',
+      status: 'failed',
+      model: null,
+    });
+    expect(did).toBe(false);
+    expect(frames).toHaveLength(0);
+  });
+});

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__/normalize-agent-status.test.ts

@@ -1,83 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { normalizeAgentEvent } from '../normalize-agent-status.js';
-
-describe('normalizeAgentEvent', () => {
-  describe('working bucket', () => {
-    const cases = [
-      'SessionStart',
-      'UserPromptSubmit',
-      'UserPromptSubmitted',
-      'PostToolUse',
-      'PostToolUseFailure',
-      'BeforeAgent',
-      'AfterTool',
-      'task_started',
-    ];
-    for (const name of cases) {
-      it(`maps ${name} → working`, () => {
-        expect(normalizeAgentEvent(name)).toBe('working');
-      });
-    }
-  });
-
-  describe('blocked bucket', () => {
-    const cases = [
-      'PreToolUse',
-      'Notification',
-      'PermissionRequest',
-      'exec_approval_request',
-      'apply_patch_approval_request',
-      'request_user_input',
-    ];
-    for (const name of cases) {
-      it(`maps ${name} → blocked`, () => {
-        expect(normalizeAgentEvent(name)).toBe('blocked');
-      });
-    }
-  });
-
-  describe('done bucket', () => {
-    const cases = [
-      'Stop',
-      'AfterAgent',
-      'SessionEnd',
-      'task_complete',
-      'agent-turn-complete',
-    ];
-    for (const name of cases) {
-      it(`maps ${name} → done`, () => {
-        expect(normalizeAgentEvent(name)).toBe('done');
-      });
-    }
-  });
-
-  describe('unknown / nullish → null', () => {
-    it('returns null for an unrecognized event', () => {
-      expect(normalizeAgentEvent('SomeRandomEvent')).toBeNull();
-    });
-    it('returns null for empty string', () => {
-      expect(normalizeAgentEvent('')).toBeNull();
-    });
-    it('returns null for undefined', () => {
-      expect(normalizeAgentEvent(undefined)).toBeNull();
-    });
-  });
-
-  describe('case- and separator-insensitive matching', () => {
-    it('matches snake_case spelling of a PascalCase event', () => {
-      expect(normalizeAgentEvent('session_start')).toBe('working');
-      expect(normalizeAgentEvent('post_tool_use')).toBe('working');
-      expect(normalizeAgentEvent('pre_tool_use')).toBe('blocked');
-    });
-    it('matches camelCase spelling', () => {
-      expect(normalizeAgentEvent('userPromptSubmitted')).toBe('working');
-      expect(normalizeAgentEvent('postToolUse')).toBe('working');
-      expect(normalizeAgentEvent('preToolUse')).toBe('blocked');
-      expect(normalizeAgentEvent('sessionEnd')).toBe('done');
-    });
-    it('matches arbitrary case', () => {
-      expect(normalizeAgentEvent('STOP')).toBe('done');
-      expect(normalizeAgentEvent('notification')).toBe('blocked');
-    });
-  });
-});

apps/coder/src/services/__tests__/provider-types-parity.test.ts

@@ -1,64 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { readFileSync } from 'node:fs';
-import { resolve, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-/**
- * Parity guard between the two copies of the provider snapshot types:
- *   apps/coder/src/services/provider-types.ts  (backend source of truth)
- *   apps/web/src/api/types.ts                  (web wire copy)
- *
- * APPROACH: text-identity of each shared type block (mirrors the repo's existing
- * ws-frames.test.ts byte-parity convention). A compile-time bidirectional-
- * assignability check was attempted first (a web-side file importing coder's
- * import-free provider-types.ts), but apps/web/tsconfig.app.json is a composite
- * project and rejects out-of-include files with TS6307 — so cross-project type
- * import is structurally blocked. This runtime guard FAILS on any field
- * add/remove/rename/loosen in either copy, including the nested model/mode/
- * command types that ProviderSnapshotEntry references. Single-source-of-truth
- * (shared workspace package) is deferred as a Tier-2 follow-up.
- */
-const here = dirname(fileURLToPath(import.meta.url));
-const coderSrc = readFileSync(resolve(here, '../provider-types.ts'), 'utf8');
-const webSrc = readFileSync(resolve(here, '../../../../web/src/api/types.ts'), 'utf8');
-
-function extractBlock(src: string, name: string): string {
-  const iface = src.match(new RegExp(`export interface ${name} \\{[\\s\\S]*?\\n\\}`));
-  const alias = src.match(new RegExp(`export type ${name} =[^;]*;`));
-  const block = iface?.[0] ?? alias?.[0];
-  if (!block) throw new Error(`type block '${name}' not found`);
-  // Normalize to type structure: drop blank + comment lines (//, /* */, *),
-  // trim each line. Field add/remove/rename/loosen still changes a field line.
-  return block
-    .split('\n')
-    .map((l) => l.trim())
-    .filter(
-      (l) =>
-        l.length > 0 &&
-        !l.startsWith('//') &&
-        !l.startsWith('/*') &&
-        !l.startsWith('*'),
-    )
-    .join('\n');
-}
-
-describe('provider snapshot type parity (coder ↔ web)', () => {
-  // Includes the nested types ProviderSnapshotEntry references, so structural
-  // drift anywhere in the snapshot surface is caught.
-  const names = [
-    'ProviderSnapshotStatus',
-    'ProviderSnapshotEntry',
-    'ProviderModel',
-    'ProviderMode',
-    'ThinkingOption',
-    'AgentCommand',
-  ];
-  for (const name of names) {
-    it(`${name} is identical in both copies`, () => {
-      expect(
-        extractBlock(webSrc, name),
-        `${name} drifted between apps/coder/src/services/provider-types.ts and apps/web/src/api/types.ts`,
-      ).toBe(extractBlock(coderSrc, name));
-    });
-  }
-});

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,21 @@ 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 { cancelPendingPermission } from './permission-waiter.js';
-import { mergeTaskCommands, getTaskCommands } from './agent-commands-cache.js';
-import { readWorktreeTextFile, writeWorktreeTextFile } from './acp-client-fs.js';
 import { mapSessionUpdate } from './acp-event-map.js';
-import {
+import { type AcpToolSnapshot, synthesizeCanceledSnapshots } from './acp-tool-snapshot.js';
-  type AcpToolSnapshot,
+import { makeFrameEmitter, type FrameEmitter } from './frame-emitter.js';
-  snapshotToWireToolCall,
+import { buildAcpClient } from './acp-client.js';
-  synthesizeCanceledSnapshots,
-} from './acp-tool-snapshot.js';
 
 export interface AcpDispatchResult {
   exitCode: number;
@@ -111,144 +97,61 @@ async function applySessionOverrides(
 }
 
 class AcpStreamContext {
-  readonly textChunks: string[] = [];
+  /** AgentEvent → WS-frame mapping + text/reasoning/tool accumulation (shared
-  readonly reasoningChunks: string[] = [];
+   *  `makeFrameEmitter`). The one-shot path passes no `dcp` stripper, so text is
-  readonly toolSnapshots = new Map<string, AcpToolSnapshot>();
+   *  emitted verbatim — byte-identical to the prior inline switch. */
-  private aborted = false;
+  private readonly emitter: FrameEmitter;
 
   constructor(
-    private readonly opts: Pick<
+    opts: Pick<AcpDispatchOpts, 'broker' | 'sessionId' | 'chatId' | 'messageId' | 'taskId'>,
-      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;
+    // Synthesize 'canceled' updates for still-running tool calls so the UI doesn't
-    for (const snap of synthesizeCanceledSnapshots(this.toolSnapshots.values())) {
+    // leave them spinning, then emit them through the same frame path (tool_update
-      this.toolSnapshots.set(snap.toolCallId, snap);
+    // → the same `tool_call` wire frame the original published).
-      this.publishToolSnapshot(snap);
+    for (const snap of synthesizeCanceledSnapshots(this.emitter.toolSnapshots.values())) {
+      this.emitter.onEvent({ type: 'tool_update', toolCall: snap });
     }
   }
 
-  private canStream(): boolean {
+  handleSessionUpdate(params: SessionNotification): void {
-    return !!(this.opts.broker && this.opts.sessionId && this.opts.chatId && this.opts.messageId);
+    // 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)) {
-  private publishToolSnapshot(snapshot: AcpToolSnapshot): void {
+      this.emitter.onEvent(event);
-    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);
-  }
-
-  async handleSessionUpdate(params: SessionNotification): Promise<void> {
-    // v2.6 Phase 2: the case-by-case mapping now lives in the shared, pure
-    // `mapSessionUpdate` (reused by the warm ACP backend). This method keeps the
-    // identical broker-publishing side effects — it just translates the normalized
-    // AgentEvents back into the same frames it always emitted. `this.toolSnapshots`
-    // is the merge accumulator, so a later tool_call_update merges over its
-    // tool_call (the prior `handleToolUpdate` behavior, byte-for-byte).
-    for (const event of mapSessionUpdate(params, this.toolSnapshots)) {
-      switch (event.type) {
-        case 'text':
-          this.textChunks.push(event.text);
-          if (this.canStream()) {
-            this.opts.broker!.publishFrame(this.opts.sessionId!, {
-              type: 'delta',
-              message_id: this.opts.messageId!,
-              chat_id: this.opts.chatId!,
-              content: event.text,
-            } as WsFrame);
-          }
-          break;
-        case 'reasoning':
-          this.reasoningChunks.push(event.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: event.text,
-            } as WsFrame);
-          }
-          break;
-        case 'tool_call':
-        case 'tool_update':
-          // mapSessionUpdate already stored the merged snapshot in this.toolSnapshots.
-          this.publishToolSnapshot(event.toolCall);
-          break;
-        case 'commands':
-          if (this.opts.taskId && event.commands.length > 0) {
-            mergeTaskCommands(this.opts.taskId, event.commands);
-            if (this.canStream() && this.opts.sessionId) {
-              const all = getTaskCommands(this.opts.taskId) ?? event.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;
-      }
     }
   }
 
   buildClient(agent: string, modeId: string | undefined, taskId: string | undefined, sessionId: string | undefined): Client {
-    return {
+    return buildAcpClient(this.worktreePath, () => ({
-      sessionUpdate: (params) => this.handleSessionUpdate(params),
+      taskId,
-      requestPermission: async (params: RequestPermissionRequest): Promise<RequestPermissionResponse> => {
+      sessionId,
-        if (taskId && sessionId) {
+      modeId,
-          return waitForPermissionResponse(taskId, sessionId, agent, modeId, params);
+      agent,
-        }
+      onSessionUpdate: (params) => this.handleSessionUpdate(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' };
-      },
-    };
   }
 }
 

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-status-publish.ts

@@ -8,7 +8,7 @@
  * (`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 { WsFrame } from '@boocode/contracts/ws-frames';
 import type { AgentStatus } from './normalize-agent-status.js';
 
 // The exact slice of Broker we need — accepting just the bound method keeps call

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

@@ -179,3 +179,73 @@ describe('mapSdkMessage — non-content messages', () => {
     ).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__/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/claude-sdk-map.ts

@@ -49,6 +49,7 @@ import type { AcpToolSnapshot } from '../acp-tool-snapshot.js';
 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.
@@ -81,6 +82,12 @@ export function mapSdkMessage(msg: SDKMessage, state: ClaudeSdkMapState): AgentE
       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
@@ -180,6 +187,52 @@ function mapFinalAssistant(content: ContentBlock[], state: ClaudeSdkMapState): A
   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();

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,91 +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
+ * worktree directory so sessions in different directories stream concurrently.
- * (P1.5-a — replaced the Phase-1 single-stream-last-directory model).
+ *
+ * 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
+ * `AgentEvent`s; the dispatcher maps them to WS frames.
- * to WS frames. No dispatcher/route references this file yet.
  *
  * 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, spawnSync, type ChildProcess } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { createServer, connect as netConnect } from 'node:net';
 import type { FastifyBaseLogger } from 'fastify';
-import {
+import type { Event, AssistantMessage } from '@opencode-ai/sdk/v2/client';
-  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 { 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 { decideRestart, DEFAULT_HEALTH_FAILURE_THRESHOLD } from './lifecycle-decisions.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
+ * is wedged or its terminal event (session.idle) was lost. Generous so a
- * below). Generous so a legitimately slow turn never trips it.
+ * 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;
@@ -98,36 +71,32 @@ export class OpenCodeServerBackend implements AgentBackend {
 
   private readonly sql: Sql;
   private readonly log: FastifyBaseLogger;
-  private readonly opencodeBinary: string;
+  private readonly supervisor: OpenCodeServerSupervisor;
-
-  private child: ChildProcess | null = null;
-  private client: OpencodeClient | null = null;
-  private port: number | null = null;
-  private up = false;
-  private serverStarting: Promise<void> | null = null;
-  // 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;
 
   /** 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();
   }
 
-  /** Phase 3: busy iff ANY pooled opencode session has an in-flight turn. The
+  /** Phase 3: busy iff ANY pooled opencode session has an in-flight turn. */
-   *  pool reads this to skip idle/LRU eviction and the health-monitor to defer a
-   *  restart (never tear down a session mid-stream). */
   isBusy(): boolean {
     for (const st of this.byOpencodeId.values()) {
       if (st.activeTurn) return true;
@@ -135,72 +104,23 @@ export class OpenCodeServerBackend implements AgentBackend {
     return false;
   }
 
-  // ─── Server lifecycle (1.2: spawn once + client + ready; Phase 3 crash-restart) ──
+  /** 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> {
-   * Lazy: start the single server on first use; re-spawn after a crash. Idempotent
+    await this.supervisor.tickHealth(now);
-   * within one live server — `serverStarting` caches the in-flight start, and is
-   * reset to null by the crash handler so the NEXT ensureServer re-spawns a fresh
-   * server (Phase 3 crash recovery). A dead-but-not-yet-reaped child (exit handler
-   * raced) is also treated as needing a restart.
-   */
-  private ensureServer(): Promise<void> {
-    const childDead = this.child != null && (this.child.exitCode !== null || this.child.signalCode !== null);
-    if (!this.serverStarting || (!this.up && childDead)) {
-      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. Phase 3: on unexpected exit we recover —
-    // settle any in-flight turns as failed, mark their agent_sessions rows crashed,
-    // and reset `serverStarting` so the next ensureServer re-spawns. opencode keeps
-    // sessions on disk, but a fresh server's in-memory state is gone, so the next
-    // turn's ensureSession (rows now 'crashed') creates fresh opencode sessions.
-    child.on('exit', (code, signal) => {
-      // Only react to THIS child's exit (a restart may have swapped in a new one).
-      if (this.child !== child) return;
-      this.handleServerCrash(code, signal, port);
-    });
-
-    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');
   }
 
   /**
-   * Crash handler (Phase 3, lift of openchamber's restart-on-exit path). The
+   * Server down (crash-exit or forced restart): fail every in-flight turn so its
-   * server died with N live opencode sessions; we can't restart it here (the next
+   * dispatcher unblocks, mark each session crashed so ensureSession won't resume a
-   * turn does, lazily — avoids a restart storm if the binary is broken). We:
+   * now-dead native id, and tear down the SSE loops + demux state. Invoked by the
-   *   1. fail every in-flight turn so its dispatcher unblocks + publishes an error,
+   * supervisor (it owns the process/port reset). Mirrors the original
-   *   2. mark each session's agent_sessions row 'crashed' so ensureSession won't
+   * handleServerCrash session-half byte-for-byte.
-   *      resume a now-dead native session id (it creates fresh),
-   *   3. tear down the SSE loops + demux state (stale against the dead server),
-   *   4. reclaim the port + reset state so the next ensureServer re-spawns.
    */
-  private handleServerCrash(code: number | null, signal: NodeJS.Signals | null, port: number): void {
+  private onServerDown(info: ServerDownInfo): void {
-    this.up = false;
     const states = [...this.byOpencodeId.values()];
     this.log.warn(
-      { code, signal, port, liveSessions: states.length },
+      { 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)',
     );
 
@@ -219,8 +139,6 @@ export class OpenCodeServerBackend implements AgentBackend {
     }
     // Drop the demux map: every session id is stale against a fresh server.
     this.byOpencodeId.clear();
-    this.client = null;
-    this.serverStarting = null; // force a re-spawn on the next ensureServer
 
     if (crashedIds.length > 0) {
       this.sql`
@@ -230,146 +148,20 @@ export class OpenCodeServerBackend implements AgentBackend {
         this.log.warn({ err: errMsg(err) }, 'opencode-server: failed to mark crashed sessions (non-fatal)');
       });
     }
-
-    // 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);
   }
 
-  /**
+  // ─── SSE loop wiring ─────────────────────────────────────────────────────────
-   * Phase 3 proactive health monitor (openchamber `runHealthCheckCycle` lift,
-   * busy-aware). Probes the server's /global/health; on a sustained failure of a
-   * NON-busy server, force a restart so the next turn isn't blocked by a wedged
-   * (hung-but-not-exited) process. Busy servers are deferred via the stale-grace in
-   * `decideRestart` — never tear down live work. Driven by the pool's periodic
-   * sweep (best-effort; a crash-exit is already handled by `handleServerCrash` +
-   * lazy `ensureServer` re-spawn, so this only catches the hung case). No-op when
-   * the server was never started or a restart is already in flight.
-   */
-  async tickHealth(now: number = Date.now()): Promise<void> {
-    if (!this.child || this.restarting) return;
-    const childExited = this.child.exitCode !== null || this.child.signalCode !== null;
-    // An exited child is recovered lazily by ensureServer; don't double-restart it.
-    if (childExited) return;
 
-    const healthy = await this.probeHealth();
+  /** The dependency bundle the per-session SSE loop reads. */
-    if (healthy) {
+  private sseDeps(): SseLoopDeps {
-      this.consecutiveHealthFailures = 0;
+    return {
-      this.unhealthyBusySince = 0;
+      isUp: () => this.supervisor.isUp(),
-      return;
+      getClient: () => this.supervisor.client,
-    }
+      dispatchEvent: (ev) => this.dispatchEvent(ev),
-    this.consecutiveHealthFailures += 1;
+      reconcile: (st) => this.reconcile(st),
-    const busy = this.isBusy();
+      onReconnectGiveUp: (st) => this.onReconnectGiveUp(st),
-    const decision = decideRestart({
+      log: this.log,
-      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.client) return false;
-    try {
-      const res = await this.client.global.health();
-      return !res.error;
-    } catch {
-      return false;
-    }
-  }
-
-  /** Force-kill the current server + reclaim its port; the next ensureServer
-   *  re-spawns (lazy). Mirrors handleServerCrash'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.child;
-      const port = this.port;
-      this.up = false;
-      // Fail in-flight turns + mark sessions crashed via the same path as a crash.
-      if (child) {
-        this.handleServerCrash(null, null, port ?? 0);
-        if (!child.killed) child.kill('SIGTERM');
-      }
-      if (port) {
-        reclaimPort(port);
-        await waitForPortRelease(port, 3_000);
-      }
-      this.child = null;
-    })().finally(() => {
-      this.restarting = null;
-    });
-    return this.restarting;
-  }
-
-  // ─── 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);
-      }
-    }
   }
 
   /** Demux one event to the owning session's active turn. Unknown/between-turns → drop. */
@@ -398,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 = {
+        st.activeTurn.onEvent({ type: 'tool_call', toolCall: toolCalledSnapshot(p) });
-          toolCallId: p.callID,
-          title: p.tool,
-          kind: null,
-          status: 'in_progress',
-          rawInput: p.input,
-          rawOutput: undefined,
-        };
-        st.activeTurn.onEvent({ type: 'tool_call', toolCall: snap });
         return;
       }
       case 'session.next.tool.success': {
@@ -414,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('') ?? '';
+        st.activeTurn.onEvent({ type: 'tool_update', toolCall: toolSuccessSnapshot(p) });
-        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 });
         return;
       }
       case 'session.next.tool.failed': {
@@ -431,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 = {
+        st.activeTurn.onEvent({ type: 'tool_update', toolCall: toolFailedSnapshot(p) });
-          toolCallId: p.callID,
-          title: p.callID,
-          kind: null,
-          status: 'failed',
-          rawInput: undefined,
-          rawOutput: errToString(p.error),
-        };
-        st.activeTurn.onEvent({ type: 'tool_update', toolCall: snap });
         return;
       }
       // ─── per-step usage (U.6) — token/cost accounting for opencode sessions ──
@@ -449,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
+        // Fire-and-forget: a DB hiccup must not stall the turn.
-        // once per LLM step, so a multi-tool turn sums several deltas.
         const usage = stepEndedToUsage(p);
         void this.accumulateUsage(st, usage);
         return;
@@ -461,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';
+        const e = classifyPartDelta(p, st);
-        if (isReasoning) {
+        if (e) st.activeTurn.onEvent(e);
-          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 });
-        }
         return;
       }
       case 'message.part.updated': {
@@ -477,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 ─────────────────────────────────────────────────────────
@@ -502,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. */
@@ -550,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.
+  /** 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 next turn. */
+   *  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) {
@@ -564,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,
       });
@@ -605,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
+   * agent_sessions row. Running totals for the whole conversation context. Zero-delta
-   * row — the dispatcher's `(chat_id, agent)` lookup wrote it). Running totals for
+   * steps are skipped. Errors are swallowed: usage telemetry must never fail a turn.
-   * 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.
    */
   private async accumulateUsage(st: SessionState, u: StepUsage): Promise<void> {
     if (u.input === 0 && u.output === 0 && u.cost === 0) return;
@@ -631,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();
+    // Coalesce concurrent first-turns for the same (chat, agent) so the SELECT…
-    if (!this.client) throw new Error('opencode-server: client not ready after ensureServer');
+    // 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}
@@ -655,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)}`);
       }
@@ -664,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,
@@ -678,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}
       `;
     }
@@ -693,24 +444,13 @@ export class OpenCodeServerBackend implements AgentBackend {
       state.boocodeSessionId = sessionId;
       state.worktreePath = opts.worktreePath;
     } else {
-      state = {
+      state = this.makeSessionState(sessionId, ocSessionId, opts.worktreePath);
-        boocodeSessionId: sessionId,
-        agentSessionId: ocSessionId,
-        worktreePath: opts.worktreePath,
-        streamedPartKeys: new Set(),
-        partTypeById: new Map(),
-        activeTurn: null,
-        watchdog: null,
-        sseAbort: null,
-        swallowNextTerminal: false,
-      };
       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
+    // fresh-create and resume reach here; idempotent.
-    // second turn) won't spawn a duplicate loop.
+    startSessionEventLoop(state, this.sseDeps());
-    this.startSessionEventLoop(state);
 
     return {
       sessionId,
@@ -719,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 = {
+      state = this.makeSessionState(handle.sessionId, oc, ctx.worktreePath);
-        boocodeSessionId: handle.sessionId,
-        agentSessionId: oc,
-        worktreePath: ctx.worktreePath,
-        streamedPartKeys: new Set(),
-        partTypeById: new Map(),
-        activeTurn: null,
-        watchdog: null,
-        sseAbort: null,
-        swallowNextTerminal: false,
-      };
       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.
+    startSessionEventLoop(session, this.sseDeps());
-    this.startSessionEventLoop(session);
-    const client = this.client;
 
     return await new Promise<TurnResult>((resolve) => {
       let settled = false;
@@ -781,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) {
@@ -822,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) {
+    await this.supervisor.dispose();
-      child.kill('SIGTERM');
-      const t = setTimeout(() => {
-        if (!child.killed) child.kill('SIGKILL');
-      }, 5_000);
-      t.unref();
-    }
   }
 }
 
 // ─── 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;
@@ -864,199 +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;
-  }
-}
-
-/**
- * Reclaim a loopback port a dead opencode 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 the crash handler
- * doesn't block.
- */
-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.
- */
-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. */
-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
+ *  invalidating on ephemeral state like the random server port. */
- *  every BooCoder restart). */
 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/warm-acp.ts

@@ -36,29 +36,15 @@
  */
 import { spawn, type ChildProcess } from 'node:child_process';
 import type { FastifyBaseLogger } from 'fastify';
-import {
+import { ClientSideConnection, type Client } from '@agentclientprotocol/sdk';
-  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,
-} 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 { readWorktreeTextFile, writeWorktreeTextFile } from '../acp-client-fs.js';
+import { buildAcpClient } from '../acp-client.js';
-import { waitForPermissionResponse, waitForElicitationResponse, cancelPendingPermission } from '../permission-waiter.js';
+import { cancelPendingPermission } from '../permission-waiter.js';
 import { type AcpToolSnapshot, synthesizeCanceledSnapshots } from '../acp-tool-snapshot.js';
 import type {
   AgentBackend,
@@ -211,47 +197,25 @@ export class WarmAcpBackend implements AgentBackend {
     );
   }
 
-  /** Build the ACP Client callbacks ONCE per connection. They read `this.activeTurn`
+  /** Build the ACP Client callbacks ONCE per connection (shared `buildAcpClient`).
-   *  so each turn's events/permissions route to the right place — exactly the
+   *  `resolveTurn` reads `this.activeTurn` at each callback so events/permissions
-   *  opencode-server `activeTurn` pattern. Worktree-scoped FS like AcpStreamContext. */
+   *  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 {
+    return buildAcpClient(worktreePath, () => {
-      sessionUpdate: async (params: SessionNotification): Promise<void> => {
+      const turn = this.activeTurn;
-        const turn = this.activeTurn;
+      if (!turn) return null;
-        if (!turn) return; // between turns — drop (no orphan settles a future turn)
+      return {
-        for (const event of mapSessionUpdate(params, turn.snapshots)) {
+        taskId: turn.taskId,
-          turn.onEvent(event);
+        sessionId: turn.sessionId,
-        }
+        modeId: turn.modeId,
-      },
+        agent: this.agent,
-      requestPermission: async (params: RequestPermissionRequest): Promise<RequestPermissionResponse> => {
+        onSessionUpdate: (params) => {
-        const turn = this.activeTurn;
+          for (const event of mapSessionUpdate(params, turn.snapshots)) turn.onEvent(event);
-        if (turn?.taskId) {
+        },
-          // Route to the UI via the per-turn task id (same as the one-shot path).
+      };
-          return waitForPermissionResponse(turn.taskId, turn.sessionId, this.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 = this.activeTurn;
-        if (turn?.taskId) {
-          return waitForElicitationResponse(turn.taskId, turn.sessionId, this.agent, turn.modeId, params);
-        }
-        return { action: 'decline' };
-      },
-    };
   }
 
   // ─── ensureSession: create-or-reuse the warm session (2.1) ───────────────────
@@ -303,6 +267,14 @@ export class WarmAcpBackend implements AgentBackend {
       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.

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

@@ -0,0 +1,50 @@
+/**
+ * F1 — per-task abort registry. A Stop on an external-agent task must reach the
+ * in-flight run and abort its child / prompt. Each external run-function registers
+ * its per-turn AbortController here keyed by task id; the cancel route calls
+ * `cancel(taskId)` to fire it; the run-function's `.finally` deletes the entry.
+ *
+ * Idempotent by construction:
+ *   - `cancel()` on an already-aborted controller no-ops (AbortController.abort()
+ *     is idempotent) → a rapid double-Stop is safe.
+ *   - `cancel()` on an unknown / already-finished task returns false → a
+ *     cancel-after-natural-exit (entry already deleted) and a Stop on a native
+ *     boocode task (never registered) are both safe no-ops.
+ *
+ * Pure (no DB / child / IO) so the abort wiring + idempotency contract is
+ * unit-testable in isolation — mirrors the turn-guard / lifecycle-decisions
+ * pure-helper precedent.
+ */
+export interface CancelRegistry {
+  /** Create + store an AbortController for this task, returning it for the run. */
+  register(taskId: string): AbortController;
+  /** Abort the task's in-flight run. Returns false when no controller is registered. */
+  cancel(taskId: string): boolean;
+  /** Drop the task's entry (called from the run's `.finally`). No-op if absent. */
+  delete(taskId: string): void;
+  /** Whether a controller is currently registered for this task. */
+  has(taskId: string): boolean;
+}
+
+export function createCancelRegistry(): CancelRegistry {
+  const controllers = new Map<string, AbortController>();
+  return {
+    register(taskId) {
+      const ac = new AbortController();
+      controllers.set(taskId, ac);
+      return ac;
+    },
+    cancel(taskId) {
+      const ac = controllers.get(taskId);
+      if (!ac) return false;
+      ac.abort();
+      return true;
+    },
+    delete(taskId) {
+      controllers.delete(taskId);
+    },
+    has(taskId) {
+      return controllers.has(taskId);
+    },
+  };
+}

apps/coder/src/services/dispatcher.ts

@@ -1,7 +1,7 @@
 import type { Sql } from '../db.js';
 import type { FastifyBaseLogger } from 'fastify';
 import type { Broker } from '@boocode/server/broker';
-import type { WsFrame } from '@boocode/server/ws-frames';
+import type { WsFrame } from '@boocode/contracts/ws-frames';
 import type { Config } from '../config.js';
 import { createWorktree, diffWorktree, cleanupWorktree, ensureSessionWorktree } from './worktrees.js';
 import { createCheckpoint } from './checkpoints.js';
@@ -22,6 +22,12 @@ 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';
+import { createCancelRegistry } from './cancel-registry.js';
+import {
+  finalizeStreamingMessage,
+  classifyTerminalStatus,
+  type TerminalMessageStatus,
+} from './finalize-message.js';
 
 interface InferenceRunner {
   enqueue: (sessionId: string, chatId: string, assistantId: string, user: string) => void;
@@ -43,7 +49,11 @@ interface Deps {
 const POLL_INTERVAL_MS = 2_000;
 const COMPLETION_POLL_MS = 2_000;
 
-export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<void> } {
+export function createDispatcher(deps: Deps): {
+  cancelExternalTask(taskId: string): boolean;
+  start(): void;
+  stop(): Promise<void>;
+} {
   const { sql, inference, broker, log, config } = deps;
   let timer: ReturnType<typeof setInterval> | null = null;
   let listener: { unlisten: () => Promise<void> } | null = null;
@@ -55,6 +65,13 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
   // turn at a time.
   const inflight = new Map<string, Promise<void>>();
 
+  // F1: per-task abort registry. Each external run-function registers its per-turn
+  // AbortController here (keyed by task id); the cancel route reaches it through the
+  // exported `cancelExternalTask`; the run's `.finally` deletes the entry. Native
+  // boocode tasks are never registered, so a Stop on one returns false and falls
+  // through to the unchanged inference.cancel path.
+  const taskControllers = createCancelRegistry();
+
   // Shared entry point for both the poll timer and the NOTIFY listener. poll()'s
   // `polling`/`stopping` guard makes this safe to call concurrently — a notify
   // arriving mid-poll returns immediately and never double-dispatches.
@@ -83,6 +100,40 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
     publishAgentStatus(broker.publishFrame, sessionId, chatId, agent, status, reason);
   }
 
+  // F1 (OCE-001/OCE-002): finalize a streaming assistant message into a terminal
+  // state and publish the matching message_complete frame. Best-effort + idempotent
+  // (the helper's `WHERE status='streaming'` guard) — a failure here must never mask
+  // the original abort/error, so it logs and swallows.
+  function finalizeMessage(
+    sessionId: string,
+    chatId: string,
+    assistantId: string,
+    status: TerminalMessageStatus,
+    model: string | null,
+    content?: string,
+  ): Promise<boolean> {
+    return finalizeStreamingMessage(sql, broker.publishFrame, {
+      sessionId,
+      chatId,
+      assistantId,
+      status,
+      model,
+      content,
+    }).catch((err) => {
+      log.error({ err: err instanceof Error ? err.message : String(err), assistantId }, 'dispatcher: finalizeStreamingMessage failed');
+      return false;
+    });
+  }
+
+  // F1: the cancel route's reach into an in-flight external run. Idempotent — a
+  // double-Stop re-aborts an already-aborted controller (no-op) and a Stop on a
+  // finished/native task returns false. Aborting only fires the backend's per-turn
+  // cancel (session.abort / session/cancel / interrupt / child.kill); it never kills
+  // a warm pool process, so persistent worktrees + pooled backends are preserved.
+  function cancelExternalTask(taskId: string): boolean {
+    return taskControllers.cancel(taskId);
+  }
+
   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
@@ -116,6 +167,9 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         // with the same key is skipped and a concurrent poll can't re-pick it.
         const p = runTask(task).finally(() => {
           inflight.delete(key);
+          // F1: drop the abort controller once the run settles. After this, a Stop
+          // on the (now-finished) task returns false — cancel-after-exit is safe.
+          taskControllers.delete(task.id);
         });
         inflight.set(key, p);
       }
@@ -312,13 +366,16 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
       return;
     }
 
-    // Create an abort controller for this task
+    // F1: register the per-task abort controller so a Stop reaches this run.
-    const ac = new AbortController();
+    const ac = taskControllers.register(taskId);
 
     // #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 = '';
+    // F1: hoisted so the catch / abort short-circuit can finalize the streaming
+    // assistant row. Empty until the row is created; finalize no-ops on ''.
+    let assistantId = '';
 
     try {
       // Mark running
@@ -384,7 +441,7 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', ${task.model}, clock_timestamp())
         RETURNING id
       `;
-      const assistantId = assistantMsg!.id;
+      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
@@ -526,6 +583,20 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         }
       }
 
+      // F1: abort short-circuit BEFORE the unconditional 'complete' write. A Stop
+      // (cancelExternalTask → ac.abort) or shutdown finalizes the streaming row as
+      // 'cancelled' (keeping whatever streamed) instead of recording 'complete',
+      // and skips the diff. This one-shot path owns a per-task worktree, so we DO
+      // tear it down here (unlike the warm paths, which keep their persistent one).
+      if (ac.signal.aborted || stopping) {
+        await finalizeMessage(sessionId, chatId, assistantId, 'cancelled', task.model, assistantContent);
+        await sql`UPDATE tasks SET state = 'cancelled', ended_at = clock_timestamp() WHERE id = ${taskId}`;
+        emitAgentStatus(sessionId, chatId, agent, 'idle', stopping ? 'shutdown' : 'cancelled');
+        await cleanupWorktree(projectPath, taskId);
+        clearTaskCommands(taskId);
+        return;
+      }
+
       await sql`
         UPDATE messages
         SET content = ${assistantContent}, status = 'complete', finished_at = clock_timestamp()
@@ -536,16 +607,9 @@ 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) {
-        await sql`
-          UPDATE tasks SET state = 'cancelled', ended_at = clock_timestamp() WHERE id = ${taskId}
-        `;
-        await cleanupWorktree(projectPath, taskId);
-        return;
-      }
-
       // Step 3: Diff the worktree and queue pending changes
       log.info({ taskId }, 'dispatcher: diffing worktree');
       const diff = await diffWorktree(worktreePath, projectPath, { signal: ac.signal });
@@ -586,18 +650,26 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
 
     } catch (err) {
       const errMsg = err instanceof Error ? err.message : String(err);
+      const status = classifyTerminalStatus({ aborted: ac.signal.aborted, error: err });
       log.error({ taskId, agent, err: errMsg }, 'dispatcher: external agent error');
 
+      // Guard `NOT IN ('cancelled','completed')` so a genuine error in the catch
+      // never overwrites a state the cancel route already wrote (user-Stop wins).
       await sql`
         UPDATE tasks
-        SET state = 'failed', ended_at = clock_timestamp(), output_summary = ${errMsg.slice(0, 500)}
+        SET state = ${status}, ended_at = clock_timestamp(), output_summary = ${errMsg.slice(0, 500)}
-        WHERE id = ${taskId}
+        WHERE id = ${taskId} AND state NOT IN ('cancelled', 'completed')
       `.catch(() => {});
 
+      // F1 (OCE-001): finalize the streaming assistant message — the catch
+      // previously updated only `tasks` and left the message 'streaming' forever
+      // (the BooChat 5-min sweep runs in a different process and can't reach it).
+      await finalizeMessage(sessionId, chatId, assistantId, status, task.model);
+
       // #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');
+      if (chatId) emitAgentStatus(sessionId, chatId, agent, status === 'cancelled' ? 'idle' : 'error', status === 'cancelled' ? 'cancelled' : 'failed');
 
       // Best-effort cleanup
       await cleanupWorktree(projectPath, taskId);
@@ -651,11 +723,14 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
       return;
     }
 
-    const ac = new AbortController();
+    // F1: register the per-task abort controller so a Stop reaches this run.
+    const ac = taskControllers.register(taskId);
 
     // #10: hoisted so the catch can report `error` with the (chat, agent) key.
     let sessionId = '';
     let chatId = '';
+    // F1: hoisted so the catch / abort short-circuit can finalize the streaming row.
+    let assistantId = '';
 
     try {
       // execution_path = 'acp' — the schema CHECK has no 'opencode_server' value
@@ -727,7 +802,7 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', ${task.model}, clock_timestamp())
         RETURNING id
       `;
-      const assistantId = assistantMsg!.id;
+      assistantId = assistantMsg!.id;
 
       // write-edit-robustness #4: pre-turn checkpoint of the persistent session
       // worktree (best-effort; never breaks dispatch). worktreeId comes from the
@@ -855,6 +930,18 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
 
       await persistExternalAgentTurn(sql, assistantId, [...toolSnaps.values()], reasoningText);
 
+      // F1: abort short-circuit BEFORE the unconditional 'complete' write — fixes
+      // the warm success-path recording 'complete' on a Stop'd turn. The abort fired
+      // session.abort on the prompt only: the persistent session worktree is kept
+      // (no cleanup) and the pooled opencode server stays warm for the next turn.
+      if (ac.signal.aborted || stopping) {
+        await finalizeMessage(sessionId, chatId, assistantId, 'cancelled', task.model, assistantContent);
+        await sql`UPDATE tasks SET state = 'cancelled', ended_at = clock_timestamp() WHERE id = ${taskId}`;
+        emitAgentStatus(sessionId, chatId, agent, 'idle', stopping ? 'shutdown' : 'cancelled');
+        clearTaskCommands(taskId);
+        return; // worktree persists (no cleanup); backend stays warm
+      }
+
       await sql`
         UPDATE messages
         SET content = ${assistantContent}, status = 'complete', finished_at = clock_timestamp()
@@ -864,13 +951,9 @@ 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) {
-        await sql`UPDATE tasks SET state = 'cancelled', ended_at = clock_timestamp() WHERE id = ${taskId}`;
-        return; // worktree persists (no cleanup); backend stays warm
-      }
-
       // 1.10: diff the persistent worktree against its captured baseline and
       // SUPERSEDE the session's prior pending row (latest-wins, one accumulating
       // diff) instead of stacking. Stamp agent for DiffPanel attribution.
@@ -918,14 +1001,17 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
       clearTaskCommands(taskId);
     } catch (err) {
       const errMsg = err instanceof Error ? err.message : String(err);
+      const status = classifyTerminalStatus({ aborted: ac.signal.aborted, error: err });
       log.error({ taskId, agent, err: errMsg }, 'dispatcher: opencode server error');
       await sql`
         UPDATE tasks
-        SET state = 'failed', ended_at = clock_timestamp(), output_summary = ${errMsg.slice(0, 500)}
+        SET state = ${status}, ended_at = clock_timestamp(), output_summary = ${errMsg.slice(0, 500)}
-        WHERE id = ${taskId}
+        WHERE id = ${taskId} AND state NOT IN ('cancelled', 'completed')
       `.catch(() => {});
+      // F1 (OCE-001): finalize the streaming message (was left 'streaming').
+      await finalizeMessage(sessionId, chatId, assistantId, status, task.model);
       // #10: turn crashed.
-      if (chatId) emitAgentStatus(sessionId, chatId, agent, 'error', 'crashed');
+      if (chatId) emitAgentStatus(sessionId, chatId, agent, status === 'cancelled' ? 'idle' : 'error', status === 'cancelled' ? 'cancelled' : 'crashed');
       clearTaskCommands(taskId);
       // No worktree cleanup (persistent); backend stays warm for the next turn.
     }
@@ -986,7 +1072,10 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
       return;
     }
 
-    const ac = new AbortController();
+    // F1: register the per-task abort controller so a Stop reaches this run.
+    const ac = taskControllers.register(taskId);
+    // F1: hoisted so the catch / abort short-circuit can finalize the streaming row.
+    let assistantId = '';
 
     try {
       await sql`
@@ -1008,7 +1097,7 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', ${task.model}, clock_timestamp())
         RETURNING id
       `;
-      const assistantId = assistantMsg!.id;
+      assistantId = assistantMsg!.id;
 
       // write-edit-robustness #4: pre-turn checkpoint of the persistent session
       // worktree (best-effort; never breaks dispatch). Same worktree the opencode
@@ -1119,6 +1208,18 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
 
       await persistExternalAgentTurn(sql, assistantId, [...toolSnaps.values()], reasoningText);
 
+      // F1: abort short-circuit BEFORE the unconditional 'complete' write — fixes
+      // the warm success-path recording 'complete' on a Stop'd turn. The abort fired
+      // session/cancel on the warm connection only (never killed the child), so the
+      // persistent worktree is kept and the pooled (chat,agent) backend stays warm.
+      if (ac.signal.aborted || stopping) {
+        await finalizeMessage(sessionId, chatId, assistantId, 'cancelled', task.model, assistantContent);
+        await sql`UPDATE tasks SET state = 'cancelled', ended_at = clock_timestamp() WHERE id = ${taskId}`;
+        emitAgentStatus(sessionId, chatId, agent, 'idle', stopping ? 'shutdown' : 'cancelled');
+        clearTaskCommands(taskId);
+        return; // worktree persists (no cleanup); backend stays warm
+      }
+
       await sql`
         UPDATE messages
         SET content = ${assistantContent}, status = 'complete', finished_at = clock_timestamp()
@@ -1128,13 +1229,9 @@ 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) {
-        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, {
@@ -1181,14 +1278,17 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
       clearTaskCommands(taskId);
     } catch (err) {
       const errMsg = err instanceof Error ? err.message : String(err);
+      const status = classifyTerminalStatus({ aborted: ac.signal.aborted, error: 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)}
+        SET state = ${status}, ended_at = clock_timestamp(), output_summary = ${errMsg.slice(0, 500)}
-        WHERE id = ${taskId}
+        WHERE id = ${taskId} AND state NOT IN ('cancelled', 'completed')
       `.catch(() => {});
+      // F1 (OCE-001): finalize the streaming message (was left 'streaming').
+      await finalizeMessage(sessionId, chatId, assistantId, status, task.model);
       // #10: turn crashed.
-      emitAgentStatus(sessionId, chatId, agent, 'error', 'crashed');
+      emitAgentStatus(sessionId, chatId, agent, status === 'cancelled' ? 'idle' : 'error', status === 'cancelled' ? 'cancelled' : 'crashed');
       clearTaskCommands(taskId);
       // No worktree cleanup (persistent); backend stays warm for the next turn.
     }
@@ -1242,7 +1342,10 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
       return;
     }
 
-    const ac = new AbortController();
+    // F1: register the per-task abort controller so a Stop reaches this run.
+    const ac = taskControllers.register(taskId);
+    // F1: hoisted so the catch / abort short-circuit can finalize the streaming row.
+    let assistantId = '';
 
     try {
       await sql`
@@ -1264,7 +1367,7 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', ${task.model}, clock_timestamp())
         RETURNING id
       `;
-      const assistantId = assistantMsg!.id;
+      assistantId = assistantMsg!.id;
 
       // write-edit-robustness #4: pre-turn checkpoint of the persistent session
       // worktree (best-effort; never breaks dispatch).
@@ -1373,6 +1476,18 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
 
       await persistExternalAgentTurn(sql, assistantId, [...toolSnaps.values()], reasoningText);
 
+      // F1: abort short-circuit BEFORE the unconditional 'complete' write — fixes
+      // the warm success-path recording 'complete' on a Stop'd turn. The abort fired
+      // the SDK interrupt on the same query generator only (never killed the warm
+      // process), so the persistent worktree is kept and the backend stays warm.
+      if (ac.signal.aborted || stopping) {
+        await finalizeMessage(sessionId, chatId, assistantId, 'cancelled', task.model, assistantContent);
+        await sql`UPDATE tasks SET state = 'cancelled', ended_at = clock_timestamp() WHERE id = ${taskId}`;
+        emitAgentStatus(sessionId, chatId, agent, 'idle', stopping ? 'shutdown' : 'cancelled');
+        clearTaskCommands(taskId);
+        return; // worktree persists (no cleanup); backend stays warm
+      }
+
       // 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`
@@ -1385,13 +1500,9 @@ 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) {
-        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, {
@@ -1438,14 +1549,17 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
       clearTaskCommands(taskId);
     } catch (err) {
       const errMsg = err instanceof Error ? err.message : String(err);
+      const status = classifyTerminalStatus({ aborted: ac.signal.aborted, error: 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)}
+        SET state = ${status}, ended_at = clock_timestamp(), output_summary = ${errMsg.slice(0, 500)}
-        WHERE id = ${taskId}
+        WHERE id = ${taskId} AND state NOT IN ('cancelled', 'completed')
       `.catch(() => {});
+      // F1 (OCE-001): finalize the streaming message (was left 'streaming').
+      await finalizeMessage(sessionId, chatId, assistantId, status, task.model);
       // #10: turn crashed.
-      emitAgentStatus(sessionId, chatId, agent, 'error', 'crashed');
+      emitAgentStatus(sessionId, chatId, agent, status === 'cancelled' ? 'idle' : 'error', status === 'cancelled' ? 'cancelled' : 'crashed');
       clearTaskCommands(taskId);
       // No worktree cleanup (persistent); backend stays warm for the next turn.
     }
@@ -1472,6 +1586,7 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
   }
 
   return {
+    cancelExternalTask,
     start() {
       log.info('dispatcher: starting poll loop + tasks_new listener');
 

apps/coder/src/services/finalize-message.ts

@@ -0,0 +1,76 @@
+import type { Sql } from '../db.js';
+import type { WsFrame } from '@boocode/contracts/ws-frames';
+
+export type TerminalMessageStatus = 'cancelled' | 'failed';
+
+/**
+ * F1 (D-7) — decide the terminal status a Stop'd / errored external turn lands in.
+ *
+ * A user Stop (the per-task AbortController fired) or a thrown `AbortError` is a
+ * deliberate, non-error outcome → `'cancelled'`. A genuine thrown error → `'failed'`.
+ * Keeping the two distinct keeps the human-inbox / failure surfaces honest.
+ *
+ * Pure (no DB / IO) so the mapping is unit-testable in isolation.
+ */
+export function classifyTerminalStatus(opts: { aborted: boolean; error?: unknown }): TerminalMessageStatus {
+  if (opts.aborted) return 'cancelled';
+  if (opts.error instanceof Error && opts.error.name === 'AbortError') return 'cancelled';
+  return 'failed';
+}
+
+/**
+ * F1 (OCE-001 / OCE-002) — finalize a streaming assistant message into a terminal
+ * state and publish the matching `message_complete` frame.
+ *
+ * Idempotent via `WHERE status = 'streaming'`: a second call (a double-Stop, or an
+ * abort short-circuit followed by the catch block) updates zero rows and does NOT
+ * re-publish, so the frontend reducer settles the message exactly once. It also
+ * never clobbers a row that already finished cleanly (`complete`) — the abort that
+ * raced a clean finish is a no-op.
+ *
+ * Returns `true` iff this call performed the finalization (the row was still
+ * streaming); `false` if it was already terminal or the id is absent (the throw
+ * preceded the row's creation).
+ */
+export async function finalizeStreamingMessage(
+  sql: Sql,
+  publishFrame: (sessionId: string, frame: WsFrame) => void,
+  opts: {
+    sessionId: string;
+    chatId: string;
+    assistantId: string;
+    status: TerminalMessageStatus;
+    model: string | null;
+    /** Partial accumulated text to persist; omit to leave the row's content untouched. */
+    content?: string;
+  },
+): Promise<boolean> {
+  const { sessionId, chatId, assistantId, status, model, content } = opts;
+  if (!assistantId) return false;
+
+  const rows =
+    content !== undefined
+      ? await sql<{ id: string }[]>`
+          UPDATE messages
+          SET content = ${content}, status = ${status}, finished_at = clock_timestamp()
+          WHERE id = ${assistantId} AND status = 'streaming'
+          RETURNING id
+        `
+      : await sql<{ id: string }[]>`
+          UPDATE messages
+          SET status = ${status}, finished_at = clock_timestamp()
+          WHERE id = ${assistantId} AND status = 'streaming'
+          RETURNING id
+        `;
+
+  if (rows.length === 0) return false;
+
+  publishFrame(sessionId, {
+    type: 'message_complete',
+    message_id: assistantId,
+    chat_id: chatId,
+    model,
+    status,
+  } as WsFrame);
+  return true;
+}

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/contracts/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/mcp-server.ts

@@ -25,17 +25,21 @@ interface PendingRow {
   session_id: string;
 }
 
-interface WorktreeRow {
-  id: string;
-  worktree_path: string;
-  agent: string;
-  started_at: string;
-}
-
 interface ProjectPathRow {
   path: string;
 }
 
+interface MessageRow {
+  id: string;
+  session_id: string;
+  chat_id: string | null;
+  role: string;
+  content: string;
+  status: string;
+  model: string | null;
+  created_at: Date;
+}
+
 function textResult(data: unknown) {
   return { content: [{ type: 'text' as const, text: JSON.stringify(data, null, 2) }] };
 }
@@ -196,25 +200,53 @@ export async function startMcpServer(sql: Sql): Promise<void> {
     },
   );
 
-  // 6. boocoder.list_worktrees
+  // 6. boocoder.view_session_history
   server.tool(
-    'boocoder.list_worktrees',
+    'boocoder.view_session_history',
-    'List active worktrees from running tasks',
+    'Retrieve the most-recent N messages of a session chat transcript (role != system) from messages_with_parts, returned in chronological (oldest→newest) order',
-    {},
+    {
-    async () => {
+      session_id: z.string().describe('Session UUID'),
-      const rows = await sql<WorktreeRow[]>`
+      chat_id: z.string().optional().describe('Optional chat UUID — narrows to one chat tab'),
-        SELECT id, worktree_path, agent, started_at
+      limit: z
-        FROM tasks
+        .number()
-        WHERE worktree_path IS NOT NULL AND state = 'running'
+        .int()
-        ORDER BY started_at DESC
+        .min(1)
-      `;
+        .max(200)
-      const items = rows.map((r) => ({
+        .optional()
-        task_id: r.id,
+        .describe('Max messages to return (default 50, max 200)'),
-        worktree_path: r.worktree_path,
+    },
-        agent: r.agent,
+    async (args) => {
-        started_at: r.started_at,
+      const effectiveLimit = Math.min(args.limit ?? 50, 200);
-      }));
+      let rows: MessageRow[];
-      return textResult(items);
+      if (args.chat_id) {
+        rows = await sql<MessageRow[]>`
+          SELECT id, session_id, chat_id, role, content, status, model, created_at
+          FROM (
+            SELECT id, session_id, chat_id, role, content, status, model, created_at
+            FROM messages_with_parts
+            WHERE session_id = ${args.session_id}
+              AND chat_id = ${args.chat_id}
+              AND role != 'system'
+            ORDER BY created_at DESC
+            LIMIT ${effectiveLimit}
+          ) sub
+          ORDER BY created_at ASC
+        `;
+      } else {
+        rows = await sql<MessageRow[]>`
+          SELECT id, session_id, chat_id, role, content, status, model, created_at
+          FROM (
+            SELECT id, session_id, chat_id, role, content, status, model, created_at
+            FROM messages_with_parts
+            WHERE session_id = ${args.session_id}
+              AND role != 'system'
+            ORDER BY created_at DESC
+            LIMIT ${effectiveLimit}
+          ) sub
+          ORDER BY created_at ASC
+        `;
+      }
+      return textResult({ session_id: args.session_id, count: rows.length, messages: rows });
     },
   );
 

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

@@ -21,72 +21,3 @@
  */
 
 export type AgentStatus = 'working' | 'blocked' | 'idle' | 'error';
-
-/** The coarse signal a raw vendor event collapses to. */
-export type AgentEventBucket = 'working' | 'blocked' | 'done';
-
-// Each bucket lists the canonical vendor event names. Lookup is
-// case-insensitive AND separator-insensitive (snake_case / camelCase /
-// PascalCase all fold to the same key), so we normalize the raw input the same
-// way before matching rather than enumerating every spelling here.
-const WORKING_EVENTS = [
-  'SessionStart',
-  'UserPromptSubmit',
-  'UserPromptSubmitted',
-  'PostToolUse',
-  'PostToolUseFailure',
-  'BeforeAgent',
-  'AfterTool',
-  'task_started',
-] as const;
-
-const BLOCKED_EVENTS = [
-  'PreToolUse',
-  'Notification',
-  'PermissionRequest',
-  'exec_approval_request',
-  'apply_patch_approval_request',
-  'request_user_input',
-] as const;
-
-const DONE_EVENTS = [
-  'Stop',
-  'AfterAgent',
-  'SessionEnd',
-  'task_complete',
-  'agent-turn-complete',
-] as const;
-
-/**
- * Fold a raw event name to a separator/case-insensitive key:
- * strip every non-alphanumeric character and lowercase. So `post_tool_use`,
- * `postToolUse`, `PostToolUse`, and `POST-TOOL-USE` all map to `posttooluse`.
- */
-function foldKey(raw: string): string {
-  return raw.replace(/[^a-z0-9]/gi, '').toLowerCase();
-}
-
-function buildLookup(
-  groups: ReadonlyArray<readonly [AgentEventBucket, readonly string[]]>,
-): Map<string, AgentEventBucket> {
-  const map = new Map<string, AgentEventBucket>();
-  for (const [bucket, names] of groups) {
-    for (const name of names) map.set(foldKey(name), bucket);
-  }
-  return map;
-}
-
-const EVENT_LOOKUP = buildLookup([
-  ['working', WORKING_EVENTS],
-  ['blocked', BLOCKED_EVENTS],
-  ['done', DONE_EVENTS],
-]);
-
-/**
- * Map a raw vendor hook-event name to its normalized bucket, or `null` when the
- * name is unknown / undefined. Case- and separator-insensitive.
- */
-export function normalizeAgentEvent(raw: string | undefined): AgentEventBucket | null {
-  if (!raw) return null;
-  return EVENT_LOOKUP.get(foldKey(raw)) ?? null;
-}

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

@@ -21,7 +21,8 @@ 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, checkWorktreeWorkAtRisk } from './worktrees.js';
+import { WORKTREE_BASE } from './worktrees.js';
+import { checkWorktreeWorkAtRisk } from './worktree-risk.js';
 import { hostExec } from './host-exec.js';
 import {
   selectOrphanWorktreeTargets,

apps/coder/src/services/pending_changes.ts

@@ -181,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(

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-config.ts

@@ -5,42 +5,28 @@
  * (see provider-config-registry.ts). Loading NEVER throws at startup (design.md
  * §2.1): a missing file, invalid JSON, or schema mismatch all fall back to
  * `{ providers: {} }` (built-ins only, all enabled).
+ *
+ * Schemas are defined once in @boocode/contracts/provider-config and re-exported
+ * here so existing importers (routes, tests, registry) don't need path changes.
  */
 import { readFileSync, writeFileSync } from 'node:fs';
-import { z } from 'zod';
+import {
+  ProviderOverrideSchema,
+  CoderProvidersFileSchema,
+  ProviderConfigPatchSchema,
+  type ProviderOverride,
+  type CoderProvidersFile,
+  type ProviderConfigPatch,
+} from '@boocode/contracts/provider-config';
 
-// Schemas verbatim from design.md §2.2.
+export {
-export const ProviderOverrideSchema = z.object({
+  ProviderOverrideSchema,
-  extends: z.enum(['acp']).optional(), // v2.3: only 'acp' for custom; built-ins omit extends
+  CoderProvidersFileSchema,
-  label: z.string().min(1).optional(),
+  ProviderConfigPatchSchema,
-  description: z.string().optional(),
+  type ProviderOverride,
-  command: z.array(z.string().min(1)).min(1).optional(), // [binary, ...args]
+  type CoderProvidersFile,
-  env: z.record(z.string()).optional(),
+  type ProviderConfigPatch,
-  enabled: z.boolean().optional(), // default true
+};
-  order: z.number().int().optional(), // UI sort key
-  models: z.array(z.object({ id: z.string(), label: z.string() })).optional(),
-  additionalModels: z.array(z.object({ id: z.string(), label: z.string() })).optional(),
-});
-
-export const CoderProvidersFileSchema = z.object({
-  providers: z.record(ProviderOverrideSchema).default({}),
-});
-
-export type ProviderOverride = z.infer<typeof ProviderOverrideSchema>;
-export type CoderProvidersFile = z.infer<typeof CoderProvidersFileSchema>;
-
-/**
- * PATCH body schema (design.md §6.2). A partial providers map where each value
- * is either a full override object (REPLACES that id's override) or `null`
- * (DELETES the override → revert to the built-in default). Ids absent from the
- * patch are left untouched. The route validates the body against this first
- * (malformed → 422) so a bad shape can never reach the merge/save step.
- */
-export const ProviderConfigPatchSchema = z.object({
-  providers: z.record(ProviderOverrideSchema.nullable()).default({}),
-});
-
-export type ProviderConfigPatch = z.infer<typeof ProviderConfigPatchSchema>;
 
 /**
  * Shallow per-id merge (design.md §6.2 / Paseo `patchConfig`). Each key in

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

@@ -1,61 +1,10 @@
-/** Shared provider / snapshot types (Paseo-shaped, BooCoder-native). */
+/** Provider snapshot types — re-exported from @boocode/contracts for local consumers. */
 
-export interface ProviderMode {
+export type {
-  id: string;
+  ProviderMode,
-  label: string;
+  ThinkingOption,
-  description?: string;
+  ProviderModel,
-  /** Auto-approve tool permissions when this mode is selected. */
+  ProviderSnapshotStatus,
-  isUnattended?: boolean;
+  AgentCommand,
-}
+  ProviderSnapshotEntry,
-
+} from '@boocode/contracts/provider-snapshot';
-export interface ThinkingOption {
-  id: string;
-  label: string;
-  isDefault?: boolean;
-}
-
-export interface ProviderModel {
-  id: string;
-  label: string;
-  description?: string;
-  isDefault?: boolean;
-  thinkingOptions?: ThinkingOption[];
-  defaultThinkingOptionId?: string;
-}
-
-// v2.3 phase 2: 'loading' (cache-miss, probe in flight) + 'unavailable'
-// (disabled or not installed) restored alongside the terminal 'ready' | 'error'.
-export type ProviderSnapshotStatus = 'loading' | 'ready' | 'unavailable' | 'error';
-
-export interface AgentCommand {
-  name: string;
-  description?: string;
-  // v2.5.11: 'skill' (plugin skill) vs 'command' (native/CLI slash command).
-  // Drives the icon split in the coder slash menu. Undefined → command.
-  kind?: 'command' | 'skill';
-}
-
-// KEEP IN SYNC with apps/web/src/api/types.ts ProviderSnapshotEntry — parity is
-// enforced by __tests__/provider-types-parity.test.ts (fails on any field drift).
-export interface ProviderSnapshotEntry {
-  name: string;
-  label: string;
-  description?: string;
-  transport: string;
-  status: ProviderSnapshotStatus;
-  enabled: boolean;
-  installed: boolean;
-  models: ProviderModel[];
-  modes: ProviderMode[];
-  defaultModeId: string | null;
-  commands: AgentCommand[];
-  error?: string;
-  fetchedAt?: string;
-}
-
-export interface AgentSessionConfig {
-  provider: string;
-  model?: string;
-  modeId?: string;
-  thinkingOptionId?: string;
-}

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,160 @@
+/**
+ * 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 type { WorktreeRiskReport } from '@boocode/contracts/worktree-risk';
+import { hostExec } from './host-exec.js';
+
+/**
+ * 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<WorktreeRiskReport> {
+  // 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,6 +8,8 @@
  */
 import type { Sql } from '../db.js';
 import { hostExec } from './host-exec.js';
+import type { WorktreeRiskReport } from '@boocode/contracts/worktree-risk';
+import { checkWorktreeWorkAtRisk } from './worktree-risk.js';
 
 export const WORKTREE_BASE = '/tmp/booworktrees';
 
@@ -379,163 +381,8 @@ export async function rebaselineWorktreeAfterApply(
 }
 
 // ─── Session-delete work-loss guard ─────────────────────────────────────────
-
+// WorktreeRiskReport single-sourced in @boocode/contracts — edit the package, not here.
-/**
+export type { WorktreeRiskReport };
- * 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 {

apps/coder/web/index.html

@@ -1,12 +0,0 @@
-<!doctype html>
-<html lang="en" class="dark">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>BooCoder</title>
-  </head>
-  <body class="bg-zinc-900 text-zinc-100">
-    <div id="root"></div>
-    <script type="module" src="/src/main.tsx"></script>
-  </body>
-</html>

apps/coder/web/package.json

@@ -1,29 +0,0 @@
-{
-  "name": "@boocode/coder-web",
-  "version": "2.0.0",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "dev": "vite",
-    "build": "tsc -b && vite build",
-    "typecheck": "tsc -b --noEmit",
-    "preview": "vite preview"
-  },
-  "dependencies": {
-    "lucide-react": "^1.16.0",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "react-markdown": "^10.1.0",
-    "react-router-dom": "^6.26.0",
-    "remark-gfm": "^4.0.1"
-  },
-  "devDependencies": {
-    "@tailwindcss/postcss": "^4.3.0",
-    "@types/react": "^18.3.3",
-    "@types/react-dom": "^18.3.0",
-    "@vitejs/plugin-react": "^4.3.1",
-    "tailwindcss": "^4.3.0",
-    "typescript": "^5.5.0",
-    "vite": "^5.3.4"
-  }
-}

apps/coder/web/postcss.config.js

@@ -1,5 +0,0 @@
-export default {
-  plugins: {
-    '@tailwindcss/postcss': {},
-  },
-};

apps/coder/web/src/App.tsx

@@ -1,13 +0,0 @@
-import { Routes, Route, Navigate } from 'react-router-dom';
-import { Home } from './pages/Home';
-import { Session } from './pages/Session';
-
-export function App() {
-  return (
-    <Routes>
-      <Route path="/" element={<Home />} />
-      <Route path="/sessions/:sessionId" element={<Session />} />
-      <Route path="*" element={<Navigate to="/" replace />} />
-    </Routes>
-  );
-}

apps/coder/web/src/api/client.ts

@@ -1,101 +0,0 @@
-import type { Project, Session, Chat, Message, PendingChange, AskUserAnswer } from './types';
-
-export class ApiError extends Error {
-  constructor(
-    public status: number,
-    public body: unknown,
-  ) {
-    super(
-      typeof body === 'object' && body && 'error' in body
-        ? String((body as { error: unknown }).error)
-        : `HTTP ${status}`,
-    );
-  }
-}
-
-async function request<T>(path: string, init: RequestInit = {}): Promise<T> {
-  const res = await fetch(path, {
-    ...init,
-    headers: {
-      'Content-Type': 'application/json',
-      ...(init.headers ?? {}),
-    },
-  });
-  if (res.status === 204) return undefined as T;
-  const text = await res.text();
-  const data = text ? JSON.parse(text) : undefined;
-  if (!res.ok) throw new ApiError(res.status, data);
-  return data as T;
-}
-
-export const api = {
-  health: () => request<{ ok: boolean; db: boolean; tools: number }>('/api/health'),
-
-  projects: {
-    list: (params?: { status?: 'open' | 'archived' }) =>
-      request<Project[]>(`/api/projects${params?.status ? `?status=${params.status}` : ''}`),
-  },
-
-  sessions: {
-    listForProject: (projectId: string, status?: 'open' | 'archived') =>
-      request<Session[]>(
-        `/api/projects/${projectId}/sessions${status ? `?status=${status}` : ''}`,
-      ),
-    get: (id: string) => request<Session>(`/api/sessions/${id}`),
-  },
-
-  chats: {
-    listForSession: (sessionId: string) =>
-      request<Chat[]>(`/api/sessions/${sessionId}/chats`),
-    create: (sessionId: string, body?: { name?: string }) =>
-      request<Chat>(`/api/sessions/${sessionId}/chats`, {
-        method: 'POST',
-        body: JSON.stringify(body ?? {}),
-      }),
-    answerUserInput: (chatId: string, toolCallId: string, answers: AskUserAnswer[]) =>
-      request<{ tool_message_id: string; assistant_message_id: string }>(
-        `/api/chats/${chatId}/answer_user_input`,
-        {
-          method: 'POST',
-          body: JSON.stringify({ tool_call_id: toolCallId, answers }),
-        },
-      ),
-  },
-
-  messages: {
-    send: (sessionId: string, chatId: string, content: string) =>
-      request<{ user_message_id: string; assistant_message_id: string }>(
-        `/api/sessions/${sessionId}/messages`,
-        {
-          method: 'POST',
-          body: JSON.stringify({ content, chat_id: chatId }),
-        },
-      ),
-    stop: (sessionId: string) =>
-      request<{ cancelled: boolean }>(`/api/sessions/${sessionId}/stop`, {
-        method: 'POST',
-      }),
-  },
-
-  pending: {
-    list: (sessionId: string) =>
-      request<PendingChange[]>(`/api/sessions/${sessionId}/pending`),
-    applyAll: (sessionId: string) =>
-      request<{ results: Array<{ id: string; success: boolean; error?: string }> }>(
-        `/api/sessions/${sessionId}/pending/apply`,
-        { method: 'POST' },
-      ),
-    applyOne: (changeId: string) =>
-      request<{ success: boolean; error?: string }>(`/api/pending/${changeId}/apply`, {
-        method: 'POST',
-      }),
-    rejectOne: (changeId: string) =>
-      request<{ ok: boolean }>(`/api/pending/${changeId}/reject`, {
-        method: 'POST',
-      }),
-    rewindOne: (changeId: string) =>
-      request<{ success: boolean; error?: string }>(`/api/pending/${changeId}/rewind`, {
-        method: 'POST',
-      }),
-  },
-};

apps/coder/web/src/api/types.ts

@@ -1,110 +0,0 @@
-// Minimal types for the BooCoder frontend.
-// Shared DB entities (same schema as BooChat).
-
-export interface Project {
-  id: string;
-  name: string;
-  path: string;
-  status: 'open' | 'archived';
-  created_at: string;
-  updated_at: string;
-}
-
-export interface Session {
-  id: string;
-  project_id: string;
-  name: string | null;
-  model: string | null;
-  status: 'open' | 'archived';
-  created_at: string;
-  updated_at: string;
-}
-
-export interface Chat {
-  id: string;
-  session_id: string;
-  name: string | null;
-  status: 'open' | 'archived';
-  created_at: string;
-  updated_at: string;
-}
-
-export interface ToolCall {
-  id: string;
-  name: string;
-  args: unknown;
-}
-
-export interface ToolResult {
-  tool_call_id: string;
-  output: unknown;
-  truncated?: boolean;
-  error?: boolean;
-}
-
-// Batch 9.7: ask_user_input shapes. The tool_call.args is { questions: AskUserQuestion[] }
-// (1-3 entries); the eventual tool_result.output is { answers: AskUserAnswer[] } in the
-// same order. AskUserInputCard renders questions and POSTs answers.
-export type AskUserQuestionType = 'single_select' | 'multi_select';
-
-export interface AskUserQuestion {
-  question: string;
-  type: AskUserQuestionType;
-  options: string[];
-}
-
-export interface AskUserAnswer {
-  question: string;
-  selected_options: string[];
-  free_text: string | null;
-}
-
-export interface AskUserAnswerSet {
-  answers: AskUserAnswer[];
-}
-
-export interface Message {
-  id: string;
-  session_id: string;
-  chat_id: string;
-  role: 'user' | 'assistant' | 'tool' | 'system';
-  content: string;
-  kind: string;
-  tool_calls: ToolCall[] | null;
-  tool_results: ToolResult | null;
-  status: 'streaming' | 'complete' | 'failed' | 'cancelled';
-  tokens_used: number | null;
-  ctx_used: number | null;
-  ctx_max: number | null;
-  started_at: string | null;
-  finished_at: string | null;
-  created_at: string;
-  metadata: unknown;
-}
-
-export interface PendingChange {
-  id: string;
-  session_id: string;
-  task_id: string | null;
-  file_path: string;
-  operation: 'create' | 'edit' | 'delete';
-  old_string: string | null;
-  new_string: string | null;
-  content: string | null;
-  diff: string | null;
-  status: 'pending' | 'applied' | 'rejected' | 'reverted';
-  created_at: string;
-  applied_at: string | null;
-}
-
-// WebSocket frame types (subset of what the coder backend publishes)
-export type WsFrame =
-  | { type: 'snapshot'; messages: Message[] }
-  | { type: 'message_started'; message_id: string; chat_id: string; role: Message['role'] }
-  | { type: 'delta'; message_id: string; chat_id: string; content: string }
-  | { type: 'tool_call'; message_id: string; chat_id: string; tool_call: ToolCall }
-  | { type: 'tool_result'; tool_message_id: string; chat_id: string; tool_call_id: string; output: string; truncated?: boolean; error?: boolean }
-  | { type: 'message_complete'; message_id: string; chat_id: string; tokens_used?: number; ctx_used?: number; ctx_max?: number; started_at?: string; finished_at?: string; metadata?: unknown }
-  | { type: 'error'; message_id?: string; error: string; reason?: string }
-  | { type: 'pending_change_added'; change: PendingChange }
-  | { type: 'pending_change_updated'; change: PendingChange };

apps/coder/web/src/components/AskUserInputCard.tsx

@@ -1,323 +0,0 @@
-import { useMemo, useState } from 'react';
-import { Check } from 'lucide-react';
-import { api } from '@/api/client';
-import { RadioGroup, RadioGroupItem } from '@/components/ui/radio-group';
-import { Button } from '@/components/ui/button';
-import type {
-  AskUserAnswer,
-  AskUserAnswerSet,
-  AskUserQuestion,
-  ToolCall,
-  ToolResult,
-} from '@/api/types';
-
-// Batch 9.7: Inline interactive picker. Renders inside MessageList in place of
-// the standard ToolCallLine when the assistant emits an ask_user_input tool
-// call. While the tool result is null (server pre-stamps a sentinel with
-// output=null), shows the form; once the WS tool_result frame arrives with a
-// real AnswerSet, flips to read-only review mode.
-
-interface Props {
-  toolCall: ToolCall;
-  toolResult: ToolResult | null;
-  chatId: string;
-}
-
-function parseQuestions(raw: unknown): AskUserQuestion[] {
-  if (!raw || typeof raw !== 'object' || !('questions' in raw)) return [];
-  const arr = (raw as { questions: unknown }).questions;
-  if (!Array.isArray(arr)) return [];
-  const out: AskUserQuestion[] = [];
-  for (const item of arr) {
-    if (!item || typeof item !== 'object') continue;
-    const q = item as { question?: unknown; type?: unknown; options?: unknown };
-    if (typeof q.question !== 'string') continue;
-    if (q.type !== 'single_select' && q.type !== 'multi_select') continue;
-    if (!Array.isArray(q.options)) continue;
-    const opts = q.options.filter((o): o is string => typeof o === 'string');
-    if (opts.length < 2) continue;
-    out.push({ question: q.question, type: q.type, options: opts });
-  }
-  return out;
-}
-
-function parseAnswerSet(raw: unknown): AskUserAnswerSet | null {
-  if (!raw || typeof raw !== 'object' || !('answers' in raw)) return null;
-  const arr = (raw as { answers: unknown }).answers;
-  if (!Array.isArray(arr)) return null;
-  const answers: AskUserAnswer[] = [];
-  for (const item of arr) {
-    if (!item || typeof item !== 'object') continue;
-    const a = item as { question?: unknown; selected_options?: unknown; free_text?: unknown };
-    if (typeof a.question !== 'string') continue;
-    if (!Array.isArray(a.selected_options)) continue;
-    if (a.free_text !== null && typeof a.free_text !== 'string') continue;
-    const sel = a.selected_options.filter((s): s is string => typeof s === 'string');
-    answers.push({
-      question: a.question,
-      selected_options: sel,
-      free_text: (a.free_text as string | null) ?? null,
-    });
-  }
-  return { answers };
-}
-
-export function AskUserInputCard({ toolCall, toolResult, chatId }: Props) {
-  const questions = useMemo(() => parseQuestions(toolCall.args), [toolCall.args]);
-
-  if (questions.length === 0) {
-    return (
-      <div className="rounded border border-destructive/40 bg-destructive/10 text-xs px-3 py-2 text-destructive">
-        ask_user_input: malformed tool args
-      </div>
-    );
-  }
-
-  // Tool result with a non-null output means the answer is already submitted.
-  // The pending sentinel uses output=null, so this branch only triggers after
-  // the real WS tool_result frame lands.
-  const answered = toolResult && toolResult.output !== null;
-  if (answered) {
-    const answerSet = parseAnswerSet(toolResult!.output);
-    return <AnsweredView questions={questions} answers={answerSet} />;
-  }
-
-  return (
-    <PendingView questions={questions} toolCallId={toolCall.id} chatId={chatId} />
-  );
-}
-
-function PendingView({
-  questions,
-  toolCallId,
-  chatId,
-}: {
-  questions: AskUserQuestion[];
-  toolCallId: string;
-  chatId: string;
-}) {
-  // Per-question selections + free text. Selections are option arrays so the
-  // multi_select case is uniform; single_select just constrains to length 1.
-  const [selections, setSelections] = useState<string[][]>(() => questions.map(() => []));
-  const [freeTexts, setFreeTexts] = useState<string[]>(() => questions.map(() => ''));
-  const [submitting, setSubmitting] = useState(false);
-
-  const singleQuestion = questions.length === 1;
-  const anyFreeText = freeTexts.some((t) => t.trim().length > 0);
-
-  // Submit button shows when:
-  //   - more than one question (always batched), OR
-  //   - one question and the user has typed free text (committing it needs an
-  //     explicit Submit so an accidental Tab/click doesn't lose it).
-  // For one question with no free text, clicking an option submits inline.
-  const showSubmitButton = !singleQuestion || anyFreeText;
-
-  // Every question must have at least one of (option, free text).
-  const allComplete = questions.every((_, i) => {
-    return selections[i]!.length > 0 || freeTexts[i]!.trim().length > 0;
-  });
-
-  function buildAnswers(): AskUserAnswer[] {
-    return questions.map((q, i) => {
-      const freeText = freeTexts[i]!.trim();
-      return {
-        question: q.question,
-        selected_options: selections[i]!,
-        free_text: freeText.length > 0 ? freeText : null,
-      };
-    });
-  }
-
-  async function submit(answers: AskUserAnswer[]) {
-    if (submitting) return;
-    setSubmitting(true);
-    try {
-      await api.chats.answerUserInput(chatId, toolCallId, answers);
-      // Card stays mounted; the incoming WS tool_result frame will flip it
-      // into AnsweredView via the parent prop change.
-    } catch (err) {
-      console.error('ask_user_input submit failed:', err instanceof Error ? err.message : err);
-      setSubmitting(false);
-    }
-  }
-
-  function pickSingle(qIdx: number, option: string) {
-    setSelections((prev) => prev.map((arr, i) => (i === qIdx ? [option] : arr)));
-    // Immediate submit for the single-question single-select shortcut. Only
-    // fires when no free text exists anywhere — once the user typed, the
-    // Submit button takes over so the typed text isn't silently dropped.
-    if (singleQuestion && !anyFreeText) {
-      const answers: AskUserAnswer[] = [
-        {
-          question: questions[0]!.question,
-          selected_options: [option],
-          free_text: null,
-        },
-      ];
-      void submit(answers);
-    }
-  }
-
-  function toggleMulti(qIdx: number, option: string) {
-    setSelections((prev) =>
-      prev.map((arr, i) => {
-        if (i !== qIdx) return arr;
-        return arr.includes(option) ? arr.filter((o) => o !== option) : [...arr, option];
-      }),
-    );
-  }
-
-  function setFreeText(qIdx: number, value: string) {
-    setFreeTexts((prev) => prev.map((t, i) => (i === qIdx ? value : t)));
-  }
-
-  return (
-    <div className="rounded-lg border bg-muted/20 text-sm">
-      <div className="px-4 py-3 space-y-4">
-        {questions.map((q, i) => (
-          <div key={i} className="space-y-2">
-            {questions.length > 1 && (
-              <div className="text-[10px] uppercase tracking-wide text-muted-foreground/70">
-                Question {i + 1}
-              </div>
-            )}
-            <div className="font-medium leading-snug">{q.question}</div>
-            {q.type === 'single_select' ? (
-              <RadioGroup
-                value={selections[i]![0] ?? ''}
-                onValueChange={(v) => pickSingle(i, v)}
-                disabled={submitting}
-                className="gap-1.5"
-              >
-                {q.options.map((opt, j) => {
-                  const id = `q${i}-opt${j}`;
-                  return (
-                    <label
-                      key={j}
-                      htmlFor={id}
-                      className="flex items-start gap-2 text-sm leading-snug cursor-pointer rounded px-1 py-0.5 hover:bg-muted/40"
-                    >
-                      <RadioGroupItem id={id} value={opt} className="mt-0.5" />
-                      <span>{opt}</span>
-                    </label>
-                  );
-                })}
-              </RadioGroup>
-            ) : (
-              <div className="grid gap-1.5">
-                {q.options.map((opt, j) => {
-                  const id = `q${i}-opt${j}`;
-                  const checked = selections[i]!.includes(opt);
-                  return (
-                    <label
-                      key={j}
-                      htmlFor={id}
-                      className="flex items-start gap-2 text-sm leading-snug cursor-pointer rounded px-1 py-0.5 hover:bg-muted/40"
-                    >
-                      <input
-                        id={id}
-                        type="checkbox"
-                        checked={checked}
-                        disabled={submitting}
-                        onChange={() => toggleMulti(i, opt)}
-                        className="mt-1 size-3.5 rounded border-input accent-primary"
-                      />
-                      <span>{opt}</span>
-                    </label>
-                  );
-                })}
-              </div>
-            )}
-            <div className="pt-1 space-y-1">
-              <div className="text-[10px] uppercase tracking-wide text-muted-foreground/70">
-                Or type a custom answer
-              </div>
-              <input
-                type="text"
-                value={freeTexts[i]}
-                disabled={submitting}
-                placeholder="Free text…"
-                onChange={(e) => setFreeText(i, e.target.value)}
-                className="w-full rounded border border-input bg-background px-2 py-1 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring/40 disabled:opacity-60"
-              />
-            </div>
-          </div>
-        ))}
-      </div>
-      {showSubmitButton && (
-        <div className="flex justify-end gap-2 border-t px-4 py-2">
-          <Button
-            type="button"
-            size="sm"
-            disabled={!allComplete || submitting}
-            onClick={() => void submit(buildAnswers())}
-          >
-            {submitting ? 'Submitting…' : 'Submit'}
-          </Button>
-        </div>
-      )}
-    </div>
-  );
-}
-
-function AnsweredView({
-  questions,
-  answers,
-}: {
-  questions: AskUserQuestion[];
-  answers: AskUserAnswerSet | null;
-}) {
-  if (!answers) {
-    return (
-      <div className="rounded-lg border bg-muted/20 text-xs px-4 py-3 text-muted-foreground">
-        ask_user_input: answers unavailable
-      </div>
-    );
-  }
-
-  return (
-    <div className="rounded-lg border bg-muted/10 text-sm">
-      <div className="px-4 py-3 space-y-3">
-        {questions.map((q, i) => {
-          const a = answers.answers[i];
-          if (!a) return null;
-          return (
-            <div key={i} className="space-y-1.5">
-              {questions.length > 1 && (
-                <div className="text-[10px] uppercase tracking-wide text-muted-foreground/70">
-                  Question {i + 1}
-                </div>
-              )}
-              <div className="font-medium leading-snug">{q.question}</div>
-              <div className="space-y-0.5">
-                {q.options.map((opt, j) => {
-                  const selected = a.selected_options.includes(opt);
-                  return (
-                    <div
-                      key={j}
-                      className={
-                        selected
-                          ? 'flex items-start gap-2 text-sm leading-snug text-foreground'
-                          : 'flex items-start gap-2 text-sm leading-snug text-muted-foreground/60 line-through'
-                      }
-                    >
-                      <span className="mt-0.5 size-3.5 shrink-0 inline-flex items-center justify-center">
-                        {selected && <Check className="size-3 text-primary" />}
-                      </span>
-                      <span>{opt}</span>
-                    </div>
-                  );
-                })}
-              </div>
-              {a.free_text && (
-                <div className="rounded bg-background border px-2 py-1 text-xs font-mono whitespace-pre-wrap">
-                  {a.free_text}
-                </div>
-              )}
-            </div>
-          );
-        })}
-      </div>
-    </div>
-  );
-}

apps/coder/web/src/components/ChatPane.tsx

@@ -1,139 +0,0 @@
-import { useState, useRef, useEffect } from 'react';
-import { Send, Square } from 'lucide-react';
-import type { Message, ToolResult } from '@/api/types';
-import { api } from '@/api/client';
-import { MessageBubble } from './MessageBubble';
-
-interface Props {
-  sessionId: string;
-  chatId: string;
-  messages: Message[];
-  isStreaming: boolean;
-  connected: boolean;
-}
-
-export function ChatPane({ sessionId, chatId, messages, isStreaming, connected }: Props) {
-  const [input, setInput] = useState('');
-  const [sending, setSending] = useState(false);
-  const messagesEndRef = useRef<HTMLDivElement>(null);
-  const textareaRef = useRef<HTMLTextAreaElement>(null);
-
-  // Auto-scroll to bottom when messages change
-  useEffect(() => {
-    messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
-  }, [messages]);
-
-  // Auto-resize textarea
-  useEffect(() => {
-    const el = textareaRef.current;
-    if (!el) return;
-    el.style.height = 'auto';
-    el.style.height = Math.min(el.scrollHeight, 200) + 'px';
-  }, [input]);
-
-  const handleSend = async () => {
-    const content = input.trim();
-    if (!content || sending || isStreaming) return;
-
-    setInput('');
-    setSending(true);
-    try {
-      await api.messages.send(sessionId, chatId, content);
-    } catch (err) {
-      console.error('send failed:', err);
-      // Restore input on failure
-      setInput(content);
-    } finally {
-      setSending(false);
-    }
-  };
-
-  const handleStop = async () => {
-    try {
-      await api.messages.stop(sessionId);
-    } catch (err) {
-      console.error('stop failed:', err);
-    }
-  };
-
-  const handleKeyDown = (e: React.KeyboardEvent) => {
-    if (e.key === 'Enter' && !e.shiftKey) {
-      e.preventDefault();
-      handleSend();
-    }
-  };
-
-  // Filter out system messages for display (sentinels)
-  const visibleMessages = messages.filter((m) => m.role !== 'system');
-
-  // Build a lookup map from tool_call_id -> ToolResult for all messages
-  const toolResultsMap: Record<string, ToolResult> = {};
-  for (const msg of messages) {
-    if (msg.tool_results) {
-      toolResultsMap[msg.tool_results.tool_call_id] = msg.tool_results;
-    }
-  }
-
-  return (
-    <div className="flex flex-col h-full">
-      {/* Connection indicator */}
-      <div className="flex items-center gap-2 px-4 py-2 border-b border-zinc-800 text-xs text-zinc-500">
-        <div
-          className={`w-1.5 h-1.5 rounded-full ${connected ? 'bg-green-500' : 'bg-red-500'}`}
-        />
-        <span>{connected ? 'Connected' : 'Disconnected'}</span>
-        {isStreaming && (
-          <span className="text-blue-400 ml-auto">Generating...</span>
-        )}
-      </div>
-
-      {/* Messages list */}
-      <div className="flex-1 overflow-y-auto px-4 py-4">
-        {visibleMessages.length === 0 && (
-          <div className="text-center text-zinc-500 mt-8">
-            <p className="text-lg font-medium">BooCoder</p>
-            <p className="text-sm mt-1">Send a message to start coding.</p>
-          </div>
-        )}
-        {visibleMessages.map((msg) => (
-          <MessageBubble key={msg.id} message={msg} chatId={msg.chat_id} toolResultsMap={toolResultsMap} />
-        ))}
-        <div ref={messagesEndRef} />
-      </div>
-
-      {/* Input area */}
-      <div className="border-t border-zinc-800 px-4 py-3">
-        <div className="flex items-end gap-2">
-          <textarea
-            ref={textareaRef}
-            value={input}
-            onChange={(e) => setInput(e.target.value)}
-            onKeyDown={handleKeyDown}
-            placeholder="Message BooCoder..."
-            rows={1}
-            className="flex-1 bg-zinc-800 border border-zinc-700 rounded-lg px-3 py-2 text-sm text-zinc-100 placeholder-zinc-500 resize-none focus:outline-none focus:ring-1 focus:ring-blue-500 focus:border-blue-500"
-            disabled={sending}
-          />
-          {isStreaming ? (
-            <button
-              onClick={handleStop}
-              className="p-2 rounded-lg bg-red-600 hover:bg-red-500 text-white transition-colors"
-              title="Stop generation"
-            >
-              <Square size={18} />
-            </button>
-          ) : (
-            <button
-              onClick={handleSend}
-              disabled={!input.trim() || sending}
-              className="p-2 rounded-lg bg-blue-600 hover:bg-blue-500 disabled:opacity-40 disabled:cursor-not-allowed text-white transition-colors"
-              title="Send message"
-            >
-              <Send size={18} />
-            </button>
-          )}
-        </div>
-      </div>
-    </div>
-  );
-}

apps/coder/web/src/components/DiffPane.tsx

@@ -1,352 +0,0 @@
-import { useState, useEffect, useCallback } from 'react';
-import { Check, X, RotateCcw, FileText, FilePlus, Trash2, RefreshCw } from 'lucide-react';
-import type { PendingChange } from '@/api/types';
-import { api } from '@/api/client';
-
-interface Props {
-  sessionId: string;
-  onPendingChange: (cb: (change: PendingChange) => void) => () => void;
-}
-
-export function DiffPane({ sessionId, onPendingChange }: Props) {
-  const [changes, setChanges] = useState<PendingChange[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [expandedId, setExpandedId] = useState<string | null>(null);
-
-  const fetchPending = useCallback(async () => {
-    try {
-      const result = await api.pending.list(sessionId);
-      setChanges(result);
-    } catch (err) {
-      console.error('fetch pending failed:', err);
-    } finally {
-      setLoading(false);
-    }
-  }, [sessionId]);
-
-  // Initial load
-  useEffect(() => {
-    fetchPending();
-  }, [fetchPending]);
-
-  // Listen for WS pending change events
-  useEffect(() => {
-    const unsub = onPendingChange((change) => {
-      setChanges((prev) => {
-        const idx = prev.findIndex((c) => c.id === change.id);
-        if (idx >= 0) {
-          const next = [...prev];
-          next[idx] = change;
-          return next;
-        }
-        return [...prev, change];
-      });
-    });
-    return unsub;
-  }, [onPendingChange]);
-
-  const pendingChanges = changes.filter((c) => c.status === 'pending');
-  const resolvedChanges = changes.filter((c) => c.status !== 'pending');
-
-  const handleApplyOne = async (id: string) => {
-    try {
-      await api.pending.applyOne(id);
-      setChanges((prev) =>
-        prev.map((c) => (c.id === id ? { ...c, status: 'applied' as const } : c)),
-      );
-    } catch (err) {
-      console.error('apply failed:', err);
-    }
-  };
-
-  const handleRejectOne = async (id: string) => {
-    try {
-      await api.pending.rejectOne(id);
-      setChanges((prev) =>
-        prev.map((c) => (c.id === id ? { ...c, status: 'rejected' as const } : c)),
-      );
-    } catch (err) {
-      console.error('reject failed:', err);
-    }
-  };
-
-  const handleRewindOne = async (id: string) => {
-    try {
-      await api.pending.rewindOne(id);
-      setChanges((prev) =>
-        prev.map((c) => (c.id === id ? { ...c, status: 'reverted' as const } : c)),
-      );
-    } catch (err) {
-      console.error('rewind failed:', err);
-    }
-  };
-
-  const handleApplyAll = async () => {
-    try {
-      const result = await api.pending.applyAll(sessionId);
-      const appliedIds = new Set(
-        result.results.filter((r) => r.success).map((r) => r.id),
-      );
-      setChanges((prev) =>
-        prev.map((c) =>
-          appliedIds.has(c.id) ? { ...c, status: 'applied' as const } : c,
-        ),
-      );
-    } catch (err) {
-      console.error('apply all failed:', err);
-    }
-  };
-
-  const handleRejectAll = async () => {
-    // Reject each pending change individually (no batch reject endpoint)
-    for (const c of pendingChanges) {
-      await handleRejectOne(c.id);
-    }
-  };
-
-  const OpIcon = ({ op }: { op: PendingChange['operation'] }) => {
-    switch (op) {
-      case 'create':
-        return <FilePlus size={14} className="text-green-400" />;
-      case 'edit':
-        return <FileText size={14} className="text-blue-400" />;
-      case 'delete':
-        return <Trash2 size={14} className="text-red-400" />;
-    }
-  };
-
-  const StatusBadge = ({ status }: { status: PendingChange['status'] }) => {
-    const colors: Record<PendingChange['status'], string> = {
-      pending: 'bg-yellow-500/20 text-yellow-400',
-      applied: 'bg-green-500/20 text-green-400',
-      rejected: 'bg-zinc-500/20 text-zinc-400',
-      reverted: 'bg-orange-500/20 text-orange-400',
-    };
-    return (
-      <span className={`text-[10px] px-1.5 py-0.5 rounded ${colors[status]}`}>
-        {status}
-      </span>
-    );
-  };
-
-  return (
-    <div className="flex flex-col h-full">
-      {/* Header */}
-      <div className="flex items-center justify-between px-4 py-2 border-b border-zinc-800">
-        <h2 className="text-sm font-medium text-zinc-300">
-          Pending Changes
-          {pendingChanges.length > 0 && (
-            <span className="ml-1.5 text-xs text-zinc-500">
-              ({pendingChanges.length})
-            </span>
-          )}
-        </h2>
-        <div className="flex items-center gap-1">
-          <button
-            onClick={fetchPending}
-            className="p-1 rounded hover:bg-zinc-800 text-zinc-400 hover:text-zinc-200"
-            title="Refresh"
-          >
-            <RefreshCw size={14} />
-          </button>
-          {pendingChanges.length > 0 && (
-            <>
-              <button
-                onClick={handleApplyAll}
-                className="text-xs px-2 py-1 rounded bg-green-600/80 hover:bg-green-600 text-white"
-              >
-                Apply All
-              </button>
-              <button
-                onClick={handleRejectAll}
-                className="text-xs px-2 py-1 rounded bg-zinc-700 hover:bg-zinc-600 text-zinc-300"
-              >
-                Reject All
-              </button>
-            </>
-          )}
-        </div>
-      </div>
-
-      {/* Changes list */}
-      <div className="flex-1 overflow-y-auto">
-        {loading && (
-          <div className="text-center text-zinc-500 text-sm py-8">Loading...</div>
-        )}
-
-        {!loading && changes.length === 0 && (
-          <div className="text-center text-zinc-500 text-sm py-8">
-            No pending changes yet.
-          </div>
-        )}
-
-        {/* Pending changes first */}
-        {pendingChanges.map((change) => (
-          <ChangeItem
-            key={change.id}
-            change={change}
-            expanded={expandedId === change.id}
-            onToggle={() =>
-              setExpandedId((prev) => (prev === change.id ? null : change.id))
-            }
-            onApply={() => handleApplyOne(change.id)}
-            onReject={() => handleRejectOne(change.id)}
-            OpIcon={OpIcon}
-            StatusBadge={StatusBadge}
-          />
-        ))}
-
-        {/* Resolved changes */}
-        {resolvedChanges.length > 0 && pendingChanges.length > 0 && (
-          <div className="border-t border-zinc-800 my-1" />
-        )}
-        {resolvedChanges.map((change) => (
-          <ChangeItem
-            key={change.id}
-            change={change}
-            expanded={expandedId === change.id}
-            onToggle={() =>
-              setExpandedId((prev) => (prev === change.id ? null : change.id))
-            }
-            onRewind={
-              change.status === 'applied'
-                ? () => handleRewindOne(change.id)
-                : undefined
-            }
-            OpIcon={OpIcon}
-            StatusBadge={StatusBadge}
-          />
-        ))}
-      </div>
-    </div>
-  );
-}
-
-interface ChangeItemProps {
-  change: PendingChange;
-  expanded: boolean;
-  onToggle: () => void;
-  onApply?: () => void;
-  onReject?: () => void;
-  onRewind?: () => void;
-  OpIcon: React.ComponentType<{ op: PendingChange['operation'] }>;
-  StatusBadge: React.ComponentType<{ status: PendingChange['status'] }>;
-}
-
-function ChangeItem({
-  change,
-  expanded,
-  onToggle,
-  onApply,
-  onReject,
-  onRewind,
-  OpIcon,
-  StatusBadge,
-}: ChangeItemProps) {
-  const fileName = change.file_path.split('/').pop() || change.file_path;
-  const dirPath = change.file_path.split('/').slice(0, -1).join('/');
-
-  return (
-    <div className="border-b border-zinc-800/50">
-      <div
-        className="flex items-center gap-2 px-4 py-2 hover:bg-zinc-800/50 cursor-pointer"
-        onClick={onToggle}
-      >
-        <OpIcon op={change.operation} />
-        <div className="flex-1 min-w-0">
-          <span className="text-sm font-mono text-zinc-200 truncate block">
-            {fileName}
-          </span>
-          {dirPath && (
-            <span className="text-[11px] text-zinc-500 truncate block">
-              {dirPath}
-            </span>
-          )}
-        </div>
-        <StatusBadge status={change.status} />
-        {change.status === 'pending' && (
-          <div className="flex items-center gap-1 ml-1">
-            <button
-              onClick={(e) => {
-                e.stopPropagation();
-                onApply?.();
-              }}
-              className="p-1 rounded hover:bg-green-600/30 text-green-400"
-              title="Apply"
-            >
-              <Check size={14} />
-            </button>
-            <button
-              onClick={(e) => {
-                e.stopPropagation();
-                onReject?.();
-              }}
-              className="p-1 rounded hover:bg-red-600/30 text-red-400"
-              title="Reject"
-            >
-              <X size={14} />
-            </button>
-          </div>
-        )}
-        {change.status === 'applied' && onRewind && (
-          <button
-            onClick={(e) => {
-              e.stopPropagation();
-              onRewind();
-            }}
-            className="p-1 rounded hover:bg-orange-600/30 text-orange-400"
-            title="Rewind"
-          >
-            <RotateCcw size={14} />
-          </button>
-        )}
-      </div>
-
-      {expanded && (
-        <div className="px-4 pb-3">
-          {change.operation === 'edit' && (
-            <div className="space-y-2">
-              {change.old_string && (
-                <div className="rounded bg-red-950/30 border border-red-900/30 p-2">
-                  <div className="text-[10px] text-red-400 mb-1 font-medium">
-                    Remove
-                  </div>
-                  <pre className="text-xs text-red-200 whitespace-pre-wrap break-all font-mono">
-                    {change.old_string}
-                  </pre>
-                </div>
-              )}
-              {change.new_string && (
-                <div className="rounded bg-green-950/30 border border-green-900/30 p-2">
-                  <div className="text-[10px] text-green-400 mb-1 font-medium">
-                    Add
-                  </div>
-                  <pre className="text-xs text-green-200 whitespace-pre-wrap break-all font-mono">
-                    {change.new_string}
-                  </pre>
-                </div>
-              )}
-            </div>
-          )}
-          {change.operation === 'create' && change.content && (
-            <div className="rounded bg-green-950/30 border border-green-900/30 p-2">
-              <div className="text-[10px] text-green-400 mb-1 font-medium">
-                New file
-              </div>
-              <pre className="text-xs text-green-200 whitespace-pre-wrap break-all font-mono max-h-60 overflow-y-auto">
-                {change.content.length > 2000
-                  ? change.content.slice(0, 2000) + '\n... (truncated)'
-                  : change.content}
-              </pre>
-            </div>
-          )}
-          {change.operation === 'delete' && (
-            <div className="rounded bg-red-950/30 border border-red-900/30 p-2 text-xs text-red-300">
-              This file will be deleted.
-            </div>
-          )}
-        </div>
-      )}
-    </div>
-  );
-}

apps/coder/web/src/components/Layout.tsx

@@ -1,62 +0,0 @@
-import { useState } from 'react';
-import { Code2, MessageSquare, GitPullRequest } from 'lucide-react';
-
-interface Props {
-  chatPane: React.ReactNode;
-  diffPane: React.ReactNode;
-}
-
-export function Layout({ chatPane, diffPane }: Props) {
-  const [activeTab, setActiveTab] = useState<'chat' | 'diff'>('chat');
-
-  return (
-    <div className="flex flex-col h-screen bg-zinc-900">
-      {/* Top bar */}
-      <header className="flex items-center gap-3 px-4 py-2 border-b border-zinc-800 bg-zinc-900/95">
-        <Code2 size={20} className="text-blue-400" />
-        <h1 className="text-sm font-semibold text-zinc-200">BooCoder</h1>
-      </header>
-
-      {/* Mobile tab bar (visible below lg breakpoint) */}
-      <div className="lg:hidden flex border-b border-zinc-800">
-        <button
-          onClick={() => setActiveTab('chat')}
-          className={`flex-1 flex items-center justify-center gap-1.5 py-2 text-sm ${
-            activeTab === 'chat'
-              ? 'text-blue-400 border-b-2 border-blue-400'
-              : 'text-zinc-500'
-          }`}
-        >
-          <MessageSquare size={14} />
-          Chat
-        </button>
-        <button
-          onClick={() => setActiveTab('diff')}
-          className={`flex-1 flex items-center justify-center gap-1.5 py-2 text-sm ${
-            activeTab === 'diff'
-              ? 'text-blue-400 border-b-2 border-blue-400'
-              : 'text-zinc-500'
-          }`}
-        >
-          <GitPullRequest size={14} />
-          Changes
-        </button>
-      </div>
-
-      {/* Desktop split layout */}
-      <div className="flex-1 hidden lg:flex overflow-hidden">
-        <div className="w-[60%] border-r border-zinc-800 overflow-hidden">
-          {chatPane}
-        </div>
-        <div className="w-[40%] overflow-hidden">
-          {diffPane}
-        </div>
-      </div>
-
-      {/* Mobile: show only the active tab */}
-      <div className="flex-1 lg:hidden overflow-hidden">
-        {activeTab === 'chat' ? chatPane : diffPane}
-      </div>
-    </div>
-  );
-}

apps/coder/web/src/components/MessageBubble.tsx

@@ -1,135 +0,0 @@
-import Markdown from 'react-markdown';
-import remarkGfm from 'remark-gfm';
-import type { Message, ToolResult } from '@/api/types';
-import { Wrench, AlertCircle, Loader2 } from 'lucide-react';
-import { AskUserInputCard } from './AskUserInputCard';
-
-interface Props {
-  message: Message;
-  chatId: string;
-  toolResultsMap: Record<string, ToolResult>;
-}
-
-export function MessageBubble({ message, chatId }: Props) {
-  if (message.role === 'tool') {
-    return <ToolResultBubble message={message} />;
-  }
-
-  const isUser = message.role === 'user';
-  const isStreaming = message.status === 'streaming';
-  const isFailed = message.status === 'failed';
-
-  return (
-    <div className={`flex ${isUser ? 'justify-end' : 'justify-start'} mb-3`}>
-      <div
-        className={`max-w-[85%] rounded-lg px-4 py-2.5 ${
-          isUser
-            ? 'bg-blue-600 text-white'
-            : 'bg-zinc-800 text-zinc-100 border border-zinc-700'
-        }`}
-      >
-        {isFailed && (
-          <div className="flex items-center gap-1.5 text-red-400 text-xs mb-1">
-            <AlertCircle size={12} />
-            <span>Failed</span>
-          </div>
-        )}
-
-        {message.tool_calls && message.tool_calls.length > 0 && (
-          <div className="mb-2 space-y-1">
-            {message.tool_calls.map((tc) => {
-              if (tc.name === 'ask_user_input') {
-                const result = message.tool_results ?? null;
-                return (
-                  <AskUserInputCard
-                    key={tc.id}
-                    toolCall={tc}
-                    toolResult={result}
-                    chatId={chatId}
-                  />
-                );
-              }
-              return (
-                <div
-                  key={tc.id}
-                  className="flex items-center gap-1.5 text-xs text-zinc-400 bg-zinc-900/50 rounded px-2 py-1"
-                >
-                  <Wrench size={11} />
-                  <span className="font-mono">{tc.name}</span>
-                  <span className="text-zinc-500 truncate max-w-[200px]">
-                    {truncateArgs(tc.args)}
-                  </span>
-                </div>
-              );
-            })}
-          </div>
-        )}
-
-        {message.content.trim() && (
-          <div className="prose prose-invert prose-sm max-w-none [&_pre]:bg-zinc-900 [&_pre]:p-3 [&_pre]:rounded [&_pre]:overflow-x-auto [&_code]:text-zinc-300 [&_p]:my-1.5">
-            <Markdown remarkPlugins={[remarkGfm]}>{message.content}</Markdown>
-          </div>
-        )}
-
-        {isStreaming && !message.content.trim() && (
-          <div className="flex items-center gap-1.5 text-zinc-400">
-            <Loader2 size={14} className="animate-spin" />
-            <span className="text-xs">Thinking...</span>
-          </div>
-        )}
-
-        {isStreaming && message.content.trim() && (
-          <span className="inline-block w-1.5 h-4 bg-zinc-400 animate-pulse ml-0.5 align-middle" />
-        )}
-      </div>
-    </div>
-  );
-}
-
-function ToolResultBubble({ message }: { message: Message }) {
-  const result = message.tool_results;
-  if (!result) return null;
-
-  const isError = result.error;
-  const output = result.output != null ? String(result.output) : '';
-  const displayOutput =
-    output.length > 300 ? output.slice(0, 300) + '...' : output;
-
-  return (
-    <div className="flex justify-start mb-2 ml-6">
-      <div
-        className={`max-w-[80%] rounded px-3 py-2 text-xs font-mono border ${
-          isError
-            ? 'bg-red-950/30 border-red-800/50 text-red-300'
-            : 'bg-zinc-800/50 border-zinc-700/50 text-zinc-400'
-        }`}
-      >
-        {result.truncated && (
-          <span className="text-yellow-500 text-[10px] block mb-1">
-            [truncated]
-          </span>
-        )}
-        <pre className="whitespace-pre-wrap break-all">{displayOutput}</pre>
-      </div>
-    </div>
-  );
-}
-
-function truncateArgs(args: unknown): string {
-  if (!args) return '';
-  try {
-    if (typeof args === 'object' && args !== null) {
-      const obj = args as Record<string, unknown>;
-      const keys = Object.keys(obj);
-      if (keys.length === 0) return '';
-      const first = keys[0]!;
-      const val = String(obj[first] ?? '');
-      const display = val.length > 40 ? val.slice(0, 40) + '...' : val;
-      return `${first}: ${display}`;
-    }
-    const str = String(args);
-    return str.length > 50 ? str.slice(0, 50) + '...' : str;
-  } catch {
-    return String(args).length > 50 ? String(args).slice(0, 50) + '...' : String(args);
-  }
-}

apps/coder/web/src/components/ui/button.tsx

@@ -1,35 +0,0 @@
-import * as React from 'react';
-
-export interface ButtonProps
-  extends React.ButtonHTMLAttributes<HTMLButtonElement> {
-  variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link';
-  size?: 'default' | 'sm' | 'lg' | 'icon';
-}
-
-const variantClasses: Record<string, string> = {
-  default: 'bg-primary text-primary-foreground hover:bg-primary/90',
-  destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
-  outline: 'border border-input bg-background hover:bg-accent hover:text-accent-foreground',
-  secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
-  ghost: 'hover:bg-accent hover:text-accent-foreground',
-  link: 'text-primary underline-offset-4 hover:underline',
-};
-
-const sizeClasses: Record<string, string> = {
-  default: 'h-9 px-4 py-2',
-  sm: 'h-8 rounded-md px-3 text-xs',
-  lg: 'h-10 rounded-md px-8',
-  icon: 'h-9 w-9',
-};
-
-const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
-  ({ className, variant = 'default', size = 'default', ...props }, ref) => {
-    const base =
-      'inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/40 disabled:pointer-events-none disabled:opacity-60';
-    const cls = [base, variantClasses[variant] ?? '', sizeClasses[size] ?? '', className ?? ''].join(' ');
-    return <button className={cls} ref={ref} {...props} />;
-  },
-);
-Button.displayName = 'Button';
-
-export { Button };

apps/coder/web/src/components/ui/radio-group.tsx

@@ -1,56 +0,0 @@
-import * as React from 'react';
-
-const RadioGroupContext = React.createContext<{
-  value: string | undefined;
-  onValueChange: (v: string) => void;
-  disabled?: boolean;
-} | null>(null);
-
-interface RadioGroupProps extends React.HTMLAttributes<HTMLDivElement> {
-  value?: string;
-  onValueChange?: (value: string) => void;
-  disabled?: boolean;
-}
-
-const RadioGroup = React.forwardRef<HTMLDivElement, RadioGroupProps>(
-  ({ className, value, onValueChange, disabled, ...props }, ref) => {
-    const ctx = React.useMemo(() => ({ value, onValueChange: onValueChange ?? (() => {}), disabled }), [value, onValueChange, disabled]);
-    return (
-      <RadioGroupContext.Provider value={ctx}>
-        <div
-          ref={ref}
-          role="radiogroup"
-          className={className}
-          {...props}
-        />
-      </RadioGroupContext.Provider>
-    );
-  },
-);
-RadioGroup.displayName = 'RadioGroup';
-
-interface RadioGroupItemProps extends React.InputHTMLAttributes<HTMLInputElement> {
-  value: string;
-}
-
-const RadioGroupItem = React.forwardRef<HTMLInputElement, RadioGroupItemProps>(
-  ({ className, value, ...props }, ref) => {
-    const ctx = React.useContext(RadioGroupContext);
-    if (!ctx) return <input ref={ref} type="radio" className={className} value={value} {...props} />;
-    const checked = ctx.value === value;
-    return (
-      <input
-        ref={ref}
-        type="radio"
-        checked={checked}
-        disabled={ctx.disabled}
-        onChange={() => ctx.onValueChange(value)}
-        className={className}
-        {...props}
-      />
-    );
-  },
-);
-RadioGroupItem.displayName = 'RadioGroupItem';
-
-export { RadioGroup, RadioGroupItem };

apps/coder/web/src/globals.css

@@ -1,22 +0,0 @@
-@import "tailwindcss";
-
-body {
-  margin: 0;
-  min-height: 100vh;
-}
-
-/* Scrollbar styling for dark theme */
-::-webkit-scrollbar {
-  width: 8px;
-  height: 8px;
-}
-::-webkit-scrollbar-track {
-  background: transparent;
-}
-::-webkit-scrollbar-thumb {
-  background: #3f3f46;
-  border-radius: 4px;
-}
-::-webkit-scrollbar-thumb:hover {
-  background: #52525b;
-}

apps/coder/web/src/hooks/useSessionStream.ts

@@ -1,230 +0,0 @@
-import { useEffect, useRef, useState, useCallback } from 'react';
-import type { Message, WsFrame, PendingChange } from '@/api/types';
-
-interface State {
-  messages: Message[];
-  connected: boolean;
-  error: string | null;
-}
-
-function applyFrame(state: State, frame: WsFrame): State {
-  switch (frame.type) {
-    case 'snapshot': {
-      return { ...state, messages: frame.messages };
-    }
-    case 'message_started': {
-      const exists = state.messages.some((m) => m.id === frame.message_id);
-      if (exists) return state;
-      const newMsg: Message = {
-        id: frame.message_id,
-        session_id: '',
-        chat_id: frame.chat_id,
-        role: frame.role,
-        content: '',
-        kind: 'message',
-        tool_calls: null,
-        tool_results: null,
-        status: frame.role === 'system' ? 'complete' : 'streaming',
-        tokens_used: null,
-        ctx_used: null,
-        ctx_max: null,
-        started_at: null,
-        finished_at: null,
-        created_at: new Date().toISOString(),
-        metadata: null,
-      };
-      return { ...state, messages: [...state.messages, newMsg] };
-    }
-    case 'delta': {
-      const next = state.messages.map((m) =>
-        m.id === frame.message_id ? { ...m, content: m.content + frame.content } : m,
-      );
-      return { ...state, messages: next };
-    }
-    case 'tool_call': {
-      const next = state.messages.map((m) =>
-        m.id === frame.message_id
-          ? { ...m, tool_calls: [...(m.tool_calls ?? []), frame.tool_call] }
-          : m,
-      );
-      return { ...state, messages: next };
-    }
-    case 'tool_result': {
-      const exists = state.messages.some((m) => m.id === frame.tool_message_id);
-      if (exists) {
-        const next = state.messages.map((m) =>
-          m.id === frame.tool_message_id
-            ? {
-                ...m,
-                role: 'tool' as const,
-                tool_results: {
-                  tool_call_id: frame.tool_call_id,
-                  output: frame.output,
-                  truncated: frame.truncated,
-                  ...(frame.error ? { error: frame.error } : {}),
-                },
-                status: 'complete' as const,
-              }
-            : m,
-        );
-        return { ...state, messages: next };
-      }
-      const newMsg: Message = {
-        id: frame.tool_message_id,
-        session_id: '',
-        chat_id: frame.chat_id,
-        role: 'tool',
-        content: '',
-        kind: 'message',
-        tool_calls: null,
-        tool_results: {
-          tool_call_id: frame.tool_call_id,
-          output: frame.output,
-          truncated: frame.truncated,
-          ...(frame.error ? { error: frame.error } : {}),
-        },
-        status: 'complete',
-        tokens_used: null,
-        ctx_used: null,
-        ctx_max: null,
-        started_at: null,
-        finished_at: null,
-        created_at: new Date().toISOString(),
-        metadata: null,
-      };
-      return { ...state, messages: [...state.messages, newMsg] };
-    }
-    case 'message_complete': {
-      const next = state.messages.map((m) =>
-        m.id === frame.message_id
-          ? {
-              ...m,
-              status: 'complete' as const,
-              ...(frame.tokens_used !== undefined ? { tokens_used: frame.tokens_used } : {}),
-              ...(frame.ctx_used !== undefined ? { ctx_used: frame.ctx_used } : {}),
-              ...(frame.ctx_max !== undefined ? { ctx_max: frame.ctx_max } : {}),
-              ...(frame.started_at !== undefined ? { started_at: frame.started_at } : {}),
-              ...(frame.finished_at !== undefined ? { finished_at: frame.finished_at } : {}),
-              ...(frame.metadata !== undefined ? { metadata: frame.metadata } : {}),
-            }
-          : m,
-      );
-      return { ...state, messages: next };
-    }
-    case 'error': {
-      const next = frame.message_id
-        ? state.messages.map((m) =>
-            m.id === frame.message_id ? { ...m, status: 'failed' as const } : m,
-          )
-        : state.messages;
-      return { ...state, messages: next, error: frame.error };
-    }
-    case 'pending_change_added':
-    case 'pending_change_updated':
-      // These are handled by the pending changes listener, not the message state
-      return state;
-  }
-}
-
-const RECONNECT_INITIAL_MS = 1000;
-const RECONNECT_MAX_MS = 30_000;
-
-interface SessionStreamResult {
-  messages: Message[];
-  connected: boolean;
-  error: string | null;
-  isStreaming: boolean;
-  /** Listeners for pending change frames */
-  onPendingChange: (cb: (change: PendingChange) => void) => () => void;
-}
-
-export function useSessionStream(sessionId: string | undefined): SessionStreamResult {
-  const [state, setState] = useState<State>({ messages: [], connected: false, error: null });
-  const wsRef = useRef<WebSocket | null>(null);
-  const pendingListenersRef = useRef<Set<(change: PendingChange) => void>>(new Set());
-
-  useEffect(() => {
-    if (!sessionId) return;
-
-    setState({ messages: [], connected: false, error: null });
-
-    let unmounted = false;
-    let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
-    let reconnectDelay = RECONNECT_INITIAL_MS;
-
-    const connect = () => {
-      if (unmounted) return;
-      const proto = window.location.protocol === 'https:' ? 'wss' : 'ws';
-      const url = `${proto}://${window.location.host}/api/ws/sessions/${sessionId}`;
-      const ws = new WebSocket(url);
-      wsRef.current = ws;
-
-      ws.onopen = () => {
-        reconnectDelay = RECONNECT_INITIAL_MS;
-        setState((s) => ({ ...s, connected: true, error: null }));
-      };
-
-      ws.onmessage = (ev) => {
-        let frame: WsFrame;
-        try {
-          frame = JSON.parse(typeof ev.data === 'string' ? ev.data : '') as WsFrame;
-        } catch {
-          return;
-        }
-
-        // Notify pending change listeners
-        if (frame.type === 'pending_change_added' || frame.type === 'pending_change_updated') {
-          for (const cb of pendingListenersRef.current) {
-            cb(frame.change);
-          }
-        }
-
-        setState((s) => applyFrame(s, frame));
-      };
-
-      ws.onerror = () => {
-        try {
-          ws.close();
-        } catch {}
-      };
-
-      ws.onclose = () => {
-        if (unmounted) return;
-        setState((s) => ({ ...s, connected: false }));
-        const delay = reconnectDelay;
-        reconnectDelay = Math.min(reconnectDelay * 2, RECONNECT_MAX_MS);
-        reconnectTimer = setTimeout(connect, delay);
-      };
-    };
-
-    connect();
-
-    return () => {
-      unmounted = true;
-      if (reconnectTimer) clearTimeout(reconnectTimer);
-      const ws = wsRef.current;
-      wsRef.current = null;
-      if (ws)
-        try {
-          ws.close();
-        } catch {}
-    };
-  }, [sessionId]);
-
-  const isStreaming = state.messages.some((m) => m.status === 'streaming');
-
-  const onPendingChange = useCallback((cb: (change: PendingChange) => void) => {
-    pendingListenersRef.current.add(cb);
-    return () => {
-      pendingListenersRef.current.delete(cb);
-    };
-  }, []);
-
-  return {
-    messages: state.messages,
-    connected: state.connected,
-    error: state.error,
-    isStreaming,
-    onPendingChange,
-  };
-}

apps/coder/web/src/main.tsx

@@ -1,13 +0,0 @@
-import { StrictMode } from 'react';
-import { createRoot } from 'react-dom/client';
-import { BrowserRouter } from 'react-router-dom';
-import { App } from './App';
-import './globals.css';
-
-createRoot(document.getElementById('root')!).render(
-  <StrictMode>
-    <BrowserRouter>
-      <App />
-    </BrowserRouter>
-  </StrictMode>,
-);

apps/coder/web/src/pages/Home.tsx

@@ -1,138 +0,0 @@
-import { useEffect, useState } from 'react';
-import { useNavigate } from 'react-router-dom';
-import { Code2, Folder, ArrowRight } from 'lucide-react';
-import type { Project, Session } from '@/api/types';
-import { api } from '@/api/client';
-
-export function Home() {
-  const navigate = useNavigate();
-  const [projects, setProjects] = useState<Project[]>([]);
-  const [sessions, setSessions] = useState<Session[]>([]);
-  const [selectedProject, setSelectedProject] = useState<string | null>(null);
-  const [loading, setLoading] = useState(true);
-
-  // Fetch projects on mount
-  useEffect(() => {
-    api.projects
-      .list({ status: 'open' })
-      .then(setProjects)
-      .catch(console.error)
-      .finally(() => setLoading(false));
-  }, []);
-
-  // Fetch sessions when a project is selected
-  useEffect(() => {
-    if (!selectedProject) {
-      setSessions([]);
-      return;
-    }
-    api.sessions
-      .listForProject(selectedProject, 'open')
-      .then(setSessions)
-      .catch(console.error);
-  }, [selectedProject]);
-
-  const handleSessionClick = (session: Session) => {
-    navigate(`/sessions/${session.id}`);
-  };
-
-  if (loading) {
-    return (
-      <div className="min-h-screen bg-zinc-900 flex items-center justify-center">
-        <div className="text-zinc-500">Loading...</div>
-      </div>
-    );
-  }
-
-  return (
-    <div className="min-h-screen bg-zinc-900 p-6">
-      <div className="max-w-2xl mx-auto">
-        {/* Header */}
-        <div className="flex items-center gap-3 mb-8">
-          <Code2 size={28} className="text-blue-400" />
-          <h1 className="text-2xl font-bold text-zinc-100">BooCoder</h1>
-        </div>
-
-        {/* Projects list */}
-        <div className="mb-8">
-          <h2 className="text-sm font-medium text-zinc-400 uppercase tracking-wide mb-3">
-            Projects
-          </h2>
-          {projects.length === 0 ? (
-            <p className="text-zinc-500 text-sm">
-              No projects found. Create one in BooChat first.
-            </p>
-          ) : (
-            <div className="space-y-1">
-              {projects.map((project) => (
-                <button
-                  key={project.id}
-                  onClick={() => setSelectedProject(project.id)}
-                  className={`w-full flex items-center gap-3 px-4 py-3 rounded-lg text-left transition-colors ${
-                    selectedProject === project.id
-                      ? 'bg-blue-600/20 border border-blue-500/40'
-                      : 'bg-zinc-800/50 border border-zinc-800 hover:bg-zinc-800'
-                  }`}
-                >
-                  <Folder
-                    size={16}
-                    className={
-                      selectedProject === project.id
-                        ? 'text-blue-400'
-                        : 'text-zinc-500'
-                    }
-                  />
-                  <div className="flex-1 min-w-0">
-                    <div className="text-sm font-medium text-zinc-200 truncate">
-                      {project.name}
-                    </div>
-                    <div className="text-xs text-zinc-500 truncate">
-                      {project.path}
-                    </div>
-                  </div>
-                </button>
-              ))}
-            </div>
-          )}
-        </div>
-
-        {/* Sessions list */}
-        {selectedProject && (
-          <div>
-            <h2 className="text-sm font-medium text-zinc-400 uppercase tracking-wide mb-3">
-              Sessions
-            </h2>
-            {sessions.length === 0 ? (
-              <p className="text-zinc-500 text-sm">
-                No open sessions. Create one in BooChat first.
-              </p>
-            ) : (
-              <div className="space-y-1">
-                {sessions.map((session) => (
-                  <button
-                    key={session.id}
-                    onClick={() => handleSessionClick(session)}
-                    className="w-full flex items-center gap-3 px-4 py-3 rounded-lg bg-zinc-800/50 border border-zinc-800 hover:bg-zinc-800 text-left transition-colors group"
-                  >
-                    <div className="flex-1 min-w-0">
-                      <div className="text-sm font-medium text-zinc-200 truncate">
-                        {session.name || 'Untitled session'}
-                      </div>
-                      <div className="text-xs text-zinc-500">
-                        {new Date(session.updated_at).toLocaleDateString()}
-                      </div>
-                    </div>
-                    <ArrowRight
-                      size={16}
-                      className="text-zinc-600 group-hover:text-zinc-400 transition-colors"
-                    />
-                  </button>
-                ))}
-              </div>
-            )}
-          </div>
-        )}
-      </div>
-    </div>
-  );
-}

apps/coder/web/src/pages/Session.tsx

@@ -1,86 +0,0 @@
-import { useEffect, useState } from 'react';
-import { useParams, useNavigate } from 'react-router-dom';
-import { ArrowLeft } from 'lucide-react';
-import type { Chat } from '@/api/types';
-import { api } from '@/api/client';
-import { useSessionStream } from '@/hooks/useSessionStream';
-import { ChatPane } from '@/components/ChatPane';
-import { DiffPane } from '@/components/DiffPane';
-import { Layout } from '@/components/Layout';
-
-export function Session() {
-  const { sessionId } = useParams<{ sessionId: string }>();
-  const navigate = useNavigate();
-  const [chat, setChat] = useState<Chat | null>(null);
-  const [loading, setLoading] = useState(true);
-
-  const { messages, connected, isStreaming, onPendingChange } =
-    useSessionStream(sessionId);
-
-  // Get or create a chat for this session
-  useEffect(() => {
-    if (!sessionId) return;
-
-    api.chats
-      .listForSession(sessionId)
-      .then((chats) => {
-        // Use the first open chat, or create one
-        const openChat = chats.find((c) => c.status === 'open');
-        if (openChat) {
-          setChat(openChat);
-        } else {
-          // Create a new chat
-          return api.chats.create(sessionId).then((newChat) => {
-            setChat(newChat);
-          });
-        }
-      })
-      .catch(console.error)
-      .finally(() => setLoading(false));
-  }, [sessionId]);
-
-  if (!sessionId) {
-    navigate('/');
-    return null;
-  }
-
-  if (loading) {
-    return (
-      <div className="min-h-screen bg-zinc-900 flex items-center justify-center">
-        <div className="text-zinc-500">Loading session...</div>
-      </div>
-    );
-  }
-
-  if (!chat) {
-    return (
-      <div className="min-h-screen bg-zinc-900 flex flex-col items-center justify-center gap-4">
-        <div className="text-zinc-500">Could not load chat for this session.</div>
-        <button
-          onClick={() => navigate('/')}
-          className="flex items-center gap-2 text-sm text-blue-400 hover:text-blue-300"
-        >
-          <ArrowLeft size={14} />
-          Back to projects
-        </button>
-      </div>
-    );
-  }
-
-  return (
-    <Layout
-      chatPane={
-        <ChatPane
-          sessionId={sessionId}
-          chatId={chat.id}
-          messages={messages}
-          isStreaming={isStreaming}
-          connected={connected}
-        />
-      }
-      diffPane={
-        <DiffPane sessionId={sessionId} onPendingChange={onPendingChange} />
-      }
-    />
-  );
-}

apps/coder/web/src/vite-env.d.ts

@@ -1 +0,0 @@
-/// <reference types="vite/client" />

apps/coder/web/tsconfig.app.json

@@ -1,27 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "Bundler",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true,
-    "allowSyntheticDefaultImports": true,
-    "isolatedModules": true,
-    "noUncheckedIndexedAccess": true,
-    "composite": true,
-    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
-    "lib": ["ES2022", "DOM", "DOM.Iterable"],
-    "jsx": "react-jsx",
-    "noEmit": true,
-    "useDefineForClassFields": true,
-    "allowImportingTsExtensions": true,
-    "baseUrl": ".",
-    "paths": {
-      "@/*": ["./src/*"]
-    }
-  },
-  "include": ["src"]
-}

apps/coder/web/tsconfig.json

@@ -1,13 +0,0 @@
-{
-  "files": [],
-  "references": [
-    { "path": "./tsconfig.app.json" },
-    { "path": "./tsconfig.node.json" }
-  ],
-  "compilerOptions": {
-    "baseUrl": ".",
-    "paths": {
-      "@/*": ["./src/*"]
-    }
-  }
-}

apps/coder/web/tsconfig.node.json

@@ -1,14 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "Bundler",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "composite": true,
-    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
-    "allowSyntheticDefaultImports": true
-  },
-  "include": ["vite.config.ts"]
-}

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/coder/web/vite.config.ts

@@ -1,26 +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 single-sourced in `@boocode/contracts` (`packages/contracts/src/ws-frames.ts`); the package's `ws-frames.test.ts` enforces schema correctness. 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

@@ -53,10 +53,6 @@
       "types": "./dist/types/api.d.ts",
       "default": "./dist/types/api.js"
     },
-    "./ws-frames": {
-      "types": "./dist/types/ws-frames.d.ts",
-      "default": "./dist/types/ws-frames.js"
-    },
     "./db": {
       "types": "./dist/db.d.ts",
       "default": "./dist/db.js"
@@ -81,6 +77,7 @@
     "test": "vitest run"
   },
   "dependencies": {
+    "@boocode/contracts": "workspace:*",
     "@ai-sdk/openai-compatible": "^2.0.47",
     "@fastify/static": "^7.0.4",
     "@fastify/websocket": "^10.0.1",

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/index.ts

@@ -140,7 +140,7 @@ async function main() {
       publish: (sessionId, frame) => {
         // v1.13.11-b: route through the typed publishFrame so the broker's
         // Zod gate validates every inference frame before delivery.
-        broker.publishFrame(sessionId, frame as unknown as import('./types/ws-frames.js').WsFrame);
+        broker.publishFrame(sessionId, frame as unknown as import('@boocode/contracts/ws-frames').WsFrame);
       },
       // v1.11: broker handle for compaction.process to publish 'compacted'
       // frames on the per-session channel. Inference's regular publish path
@@ -149,7 +149,7 @@ async function main() {
       broker,
     },
     (user, frame) => {
-      broker.publishUserFrame(user, frame as unknown as import('./types/ws-frames.js').WsFrame);
+      broker.publishUserFrame(user, frame as unknown as import('@boocode/contracts/ws-frames').WsFrame);
     }
   );
   registerMessageRoutes(app, sql, config, broker, {
@@ -194,7 +194,7 @@ async function main() {
       });
     },
     publishSessionFrame: (sessionId, frame) => {
-      broker.publishFrame(sessionId, frame as import('./types/ws-frames.js').WsFrame);
+      broker.publishFrame(sessionId, frame as import('@boocode/contracts/ws-frames').WsFrame);
     },
   });
   registerArtifactRoutes(app, sql);
@@ -222,7 +222,7 @@ async function main() {
       });
     },
     publishSessionFrame: (sessionId, frame) => {
-      broker.publishFrame(sessionId, frame as import('./types/ws-frames.js').WsFrame);
+      broker.publishFrame(sessionId, frame as import('@boocode/contracts/ws-frames').WsFrame);
     },
   });
   registerWebSocket(app, sql, broker);

apps/server/src/routes/chats.ts

@@ -5,6 +5,7 @@ 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(),
@@ -439,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,
+        SELECT ${sql.unsafe(MESSAGE_COLUMNS)}
-               tokens_used, ctx_used, ctx_max, started_at, finished_at, created_at, metadata,
-               summary, tail_start_id, compacted_at, model
         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,
+        SELECT ${sql.unsafe(MESSAGE_COLUMNS)}
-               tokens_used, ctx_used, ctx_max, started_at, finished_at, created_at, metadata,
-               summary, tail_start_id, compacted_at, model
         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
+      // v1.13.1-C: resolve the originating tool_call + pending tool row.
-      // directly on payload->>'id'. Scoped by chat_id + role via the JOIN.
+      // Pre-v1.13.0 history has no parts rows — those become unreachable (404).
-      // Pre-v1.13.0 history has no parts rows — those tool_calls become
+      const ctx = await lookupPendingToolCall(
-      // unreachable here (404). Acceptable per the dispatch decision: any
+        sql, chat.id, tool_call_id, 'ask_user_input', 'tool_call_not_ask_user_input',
-      // 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.
+      if (!ctx.ok) {
-      const callerRows = await sql<{
+        reply.code(ctx.code);
-        message_id: string;
+        return ctx.body;
-        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' };
       }
+      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 grantCtx = await lookupPendingToolCall(
-      const callerRows = await sql<{
+        sql, chat.id, tool_call_id, 'request_read_access', 'tool_call_not_request_read_access',
-        message_id: string;
+      );
-        payload: { id: string; name: string; args: Record<string, unknown> };
+      if (!grantCtx.ok) {
-      }[]>`
+        reply.code(grantCtx.code);
-        SELECT p.message_id, p.payload
+        return grantCtx.body;
-        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 { 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

@@ -10,6 +10,18 @@ import { resolveProjectRoot, PathScopeError } from '../services/path_guard.js';
 import { listDir, viewFile } from '../services/file_ops.js';
 import { getProjectFiles } from '../services/file_index.js';
 import { getGitMeta } from '../services/git_meta.js';
+import {
+  getGitDiff,
+  stageFiles,
+  unstageFiles,
+  commitFiles,
+  discardFiles,
+  detectInProgress,
+  isRepoDirty,
+  autoSelectMode,
+  GitWriteError,
+} from '../services/git_diff.js';
+import type { GitDiffMode } from '../services/git_diff.js';
 import {
   bootstrapProject,
   BootstrapNameError,
@@ -67,6 +79,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 +225,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[]>`
+    const project = await selectProject(sql, req.params.id);
-      SELECT id, name, path, added_at, last_session_id, status, gitea_remote,
+    if (!project) {
-             default_system_prompt, default_web_search_enabled
-      FROM projects WHERE id = ${req.params.id}
-    `;
-    if (rows.length === 0) {
       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 +362,14 @@ export function registerProjectRoutes(
       const { id } = req.params;
       const relPath = req.query.path ?? '.';
 
-      const rows = await sql<Project[]>`
+      const projectPath = await selectProjectPath(sql, id);
-        SELECT id, name, path, added_at, last_session_id, status, gitea_remote
+      if (projectPath === null) {
-        FROM projects WHERE id = ${id}
-      `;
-      if (rows.length === 0) {
         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 +403,14 @@ export function registerProjectRoutes(
         return { error: 'path is required' };
       }
 
-      const rows = await sql<Project[]>`
+      const projectPath = await selectProjectPath(sql, id);
-        SELECT id, name, path, added_at, last_session_id, status, gitea_remote
+      if (projectPath === null) {
-        FROM projects WHERE id = ${id}
-      `;
-      if (rows.length === 0) {
         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 +445,14 @@ export function registerProjectRoutes(
     '/api/projects/:id/git',
     async (req, reply) => {
       const { id } = req.params;
-      const rows = await sql<Project[]>`
+      const projectPath = await selectProjectPath(sql, id);
-        SELECT id, name, path, added_at, last_session_id, status, gitea_remote
+      if (projectPath === null) {
-        FROM projects WHERE id = ${id}
-      `;
-      if (rows.length === 0) {
         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);
@@ -455,24 +465,192 @@ export function registerProjectRoutes(
     }
   );
 
+  // GET /api/projects/:id/git/diff?mode=uncommitted|committed
+  // Returns the structured diff payload for the project repository. mode param
+  // selects the comparison: uncommitted (working tree vs HEAD) or committed
+  // (branch vs its upstream/default-branch base). When mode is absent the server
+  // auto-selects based on dirty state (FIX 1: dirty → uncommitted, clean → committed).
+  // Always includes auto_mode (the dirty-state-derived mode) so the client can
+  // show a suggestion when a pinned mode diverges from what would be auto-selected.
+  // Returns { git_repo: false } when the path is not a git repository.
+  app.get<{ Params: { id: string }; Querystring: { mode?: string } }>(
+    '/api/projects/:id/git/diff',
+    async (req, reply) => {
+      const { id } = req.params;
+      const rawMode = req.query.mode;
+
+      const projectPath = await selectProjectPath(sql, id);
+      if (projectPath === null) {
+        reply.code(404);
+        return { error: 'not found' };
+      }
+      let projectRoot: string;
+      try {
+        projectRoot = await resolveProjectRoot(projectPath);
+      } catch (err) {
+        if (err instanceof PathScopeError) {
+          reply.code(404);
+          return { error: err.message };
+        }
+        throw err;
+      }
+
+      // Always detect dirty state: used for auto-select (FIX 1) and suggestion (FIX 4).
+      const dirty = await isRepoDirty(projectRoot);
+      const auto_mode = autoSelectMode(dirty);
+
+      const mode: GitDiffMode =
+        rawMode === 'committed' ? 'committed' :
+        rawMode === 'uncommitted' ? 'uncommitted' :
+        auto_mode; // no mode param → auto-select (FIX 1)
+
+      const result = await getGitDiff(projectRoot, mode);
+      if (result === null) {
+        return { git_repo: false, mode, auto_mode, base_label: null, in_progress_op: null, files: [] };
+      }
+      return { git_repo: true, ...result, auto_mode };
+    }
+  );
+
+  // ── Git write routes (Phase 2) ─────────────────────────────────────────────
+  // These are user UI actions — NOT registered in the assistant tool registry.
+  // D-3: argv-safe runGit/execFile with -- separators (never shell strings).
+  // D-4: per-file pathGuard validation via validateWritePath.
+  // D-5: commit identity server-derived; request body .strict(), no author fields.
+  // D-7: index-lock → 409; in-progress op → 409.
+  // D-13: NOT in ALL_TOOLS.
+
+  const GitFilesBody = z.object({ files: z.array(z.string().min(1)).min(1) });
+
+  const GitCommitBody = z
+    .object({
+      message: z.string().min(1),
+      files: z.array(z.string().min(1)).optional(),
+    })
+    .strict();
+
+  const GitDiscardBody = z.object({
+    files: z.array(
+      z
+        .object({
+          path: z.string().min(1),
+          change_type: z.string().min(1),
+          staged: z.boolean(),
+        })
+        .strict(),
+    ).min(1),
+  });
+
+  // POST /api/projects/:id/git/stage — stage whole files
+  app.post<{ Params: { id: string } }>(
+    '/api/projects/:id/git/stage',
+    async (req, reply) => {
+      const body = GitFilesBody.safeParse(req.body);
+      if (!body.success) { reply.code(400); return { error: body.error.message }; }
+      const { id } = req.params;
+      const projectPath = await selectProjectPath(sql, id);
+      if (!projectPath) { reply.code(404); return { error: 'not found' }; }
+      let root: string;
+      try { root = await resolveProjectRoot(projectPath); }
+      catch (err) { if (err instanceof PathScopeError) { reply.code(404); return { error: (err as Error).message }; } throw err; }
+      const inProg = await detectInProgress(root);
+      if (inProg) { reply.code(409); return { error: `git ${inProg} in progress — write actions disabled` }; }
+      try {
+        await stageFiles(root, body.data.files);
+        return { ok: true };
+      } catch (err) {
+        if (err instanceof GitWriteError) { reply.code(err.busy ? 409 : 500); return { error: err.message }; }
+        throw err;
+      }
+    },
+  );
+
+  // POST /api/projects/:id/git/unstage — unstage whole files
+  app.post<{ Params: { id: string } }>(
+    '/api/projects/:id/git/unstage',
+    async (req, reply) => {
+      const body = GitFilesBody.safeParse(req.body);
+      if (!body.success) { reply.code(400); return { error: body.error.message }; }
+      const { id } = req.params;
+      const projectPath = await selectProjectPath(sql, id);
+      if (!projectPath) { reply.code(404); return { error: 'not found' }; }
+      let root: string;
+      try { root = await resolveProjectRoot(projectPath); }
+      catch (err) { if (err instanceof PathScopeError) { reply.code(404); return { error: (err as Error).message }; } throw err; }
+      const inProg = await detectInProgress(root);
+      if (inProg) { reply.code(409); return { error: `git ${inProg} in progress — write actions disabled` }; }
+      try {
+        await unstageFiles(root, body.data.files);
+        return { ok: true };
+      } catch (err) {
+        if (err instanceof GitWriteError) { reply.code(err.busy ? 409 : 500); return { error: err.message }; }
+        throw err;
+      }
+    },
+  );
+
+  // POST /api/projects/:id/git/commit — commit staged files (identity server-derived)
+  app.post<{ Params: { id: string } }>(
+    '/api/projects/:id/git/commit',
+    async (req, reply) => {
+      const body = GitCommitBody.safeParse(req.body);
+      if (!body.success) { reply.code(400); return { error: body.error.message }; }
+      const { id } = req.params;
+      const projectPath = await selectProjectPath(sql, id);
+      if (!projectPath) { reply.code(404); return { error: 'not found' }; }
+      let root: string;
+      try { root = await resolveProjectRoot(projectPath); }
+      catch (err) { if (err instanceof PathScopeError) { reply.code(404); return { error: (err as Error).message }; } throw err; }
+      const inProg = await detectInProgress(root);
+      if (inProg) { reply.code(409); return { error: `git ${inProg} in progress — write actions disabled` }; }
+      try {
+        await commitFiles(root, body.data.message, body.data.files);
+        return { ok: true };
+      } catch (err) {
+        if (err instanceof GitWriteError) { reply.code(err.busy ? 409 : 500); return { error: err.message }; }
+        throw err;
+      }
+    },
+  );
+
+  // POST /api/projects/:id/git/discard — discard file changes (irrecoverable)
+  app.post<{ Params: { id: string } }>(
+    '/api/projects/:id/git/discard',
+    async (req, reply) => {
+      const body = GitDiscardBody.safeParse(req.body);
+      if (!body.success) { reply.code(400); return { error: body.error.message }; }
+      const { id } = req.params;
+      const projectPath = await selectProjectPath(sql, id);
+      if (!projectPath) { reply.code(404); return { error: 'not found' }; }
+      let root: string;
+      try { root = await resolveProjectRoot(projectPath); }
+      catch (err) { if (err instanceof PathScopeError) { reply.code(404); return { error: (err as Error).message }; } throw err; }
+      const inProg = await detectInProgress(root);
+      if (inProg) { reply.code(409); return { error: `git ${inProg} in progress — write actions disabled` }; }
+      try {
+        await discardFiles(root, body.data.files);
+        return { ok: true };
+      } catch (err) {
+        if (err instanceof GitWriteError) { reply.code(err.busy ? 409 : 500); return { error: err.message }; }
+        throw err;
+      }
+    },
+  );
+
   // GET /api/projects/:id/files
   app.get<{ Params: { id: string } }>(
     '/api/projects/:id/files',
     async (req, reply) => {
       const { id } = req.params;
 
-      const rows = await sql<Project[]>`
+      const projectPath = await selectProjectPath(sql, id);
-        SELECT id, name, path, added_at, last_session_id, status, gitea_remote
+      if (projectPath === null) {
-        FROM projects WHERE id = ${id}
-      `;
-      if (rows.length === 0) {
         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/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,
+        SELECT ${sql.unsafe(MESSAGE_COLUMNS)}
-               tokens_used, ctx_used, ctx_max, started_at, finished_at, created_at, metadata,
-               summary, tail_start_id, compacted_at, model
         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
+-- v1.13.0: granular message parts table. v1.13.20: legacy tool_calls/
--- messages.content / tool_calls / tool_results columns stay authoritative
+-- tool_results columns dropped; message_parts is now the sole source of
--- for reads in v1.13.0; this table is dual-written so the swap can happen
+-- truth for tool calls, tool results, and reasoning. ON DELETE CASCADE
--- in a later dispatch without a backfill window. ON DELETE CASCADE means
+-- means removing a message removes its parts in one go.
--- 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,
@@ -142,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
+-- messages_with_parts (the v1.13.1-B view; v1.13.20 removed the legacy
--- the legacy JSON column) so this works whether the chat predates v1.13.0
+-- JSON-column COALESCE fallback — parts are sole source). No new write
--- or postdates v1.13.2 (column drop). No new write site — all source data
+-- site — all source data already lands via tool-phase.ts:94-95 UPDATE.
--- already lands via the existing 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
@@ -352,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
@@ -391,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__/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__/git_diff.test.ts

@@ -0,0 +1,346 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { realpath } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import {
+  parseNameStatus,
+  splitDiffByFile,
+  classifyDiffBody,
+  autoSelectMode,
+  detectInProgress,
+  resolveCommittedBase,
+  canCommit,
+  getGitDiff,
+} from '../git_diff.js';
+import type { GitDiffFile } from '../git_diff.js';
+
+const execFileAsync = promisify(execFile);
+
+// ── T1: parseNameStatus ────────────────────────────────────────────────────
+
+describe('parseNameStatus', () => {
+  it('parses modified file', () => {
+    const files = parseNameStatus('M\tsrc/foo.ts\n');
+    expect(files).toHaveLength(1);
+    expect(files[0]).toMatchObject({ path: 'src/foo.ts', change_type: 'modified', old_path: null });
+  });
+
+  it('parses added file', () => {
+    const files = parseNameStatus('A\tnewfile.ts\n');
+    expect(files).toHaveLength(1);
+    expect(files[0]).toMatchObject({ path: 'newfile.ts', change_type: 'added' });
+  });
+
+  it('parses deleted file', () => {
+    const files = parseNameStatus('D\tremoved.ts\n');
+    expect(files).toHaveLength(1);
+    expect(files[0]).toMatchObject({ path: 'removed.ts', change_type: 'deleted' });
+  });
+
+  it('parses renamed file with similarity score', () => {
+    const files = parseNameStatus('R100\told.ts\tnew.ts\n');
+    expect(files).toHaveLength(1);
+    expect(files[0]).toMatchObject({ path: 'new.ts', old_path: 'old.ts', change_type: 'renamed' });
+  });
+
+  it('parses type-changed file as modified', () => {
+    const files = parseNameStatus('T\tsymlink.ts\n');
+    expect(files).toHaveLength(1);
+    expect(files[0]).toMatchObject({ path: 'symlink.ts', change_type: 'modified' });
+  });
+
+  it('parses multiple files from multiline output', () => {
+    const output = 'M\ta.ts\nA\tb.ts\nD\tc.ts\n';
+    const files = parseNameStatus(output);
+    expect(files).toHaveLength(3);
+    expect(files.map((f) => f.change_type)).toEqual(['modified', 'added', 'deleted']);
+  });
+
+  it('ignores blank lines', () => {
+    const files = parseNameStatus('\n\nM\ta.ts\n\n');
+    expect(files).toHaveLength(1);
+  });
+
+  it('returns empty array for empty input', () => {
+    expect(parseNameStatus('')).toHaveLength(0);
+    expect(parseNameStatus('\n')).toHaveLength(0);
+  });
+});
+
+// ── T2: splitDiffByFile ────────────────────────────────────────────────────
+
+describe('splitDiffByFile', () => {
+  const FIXTURE = `diff --git a/src/a.ts b/src/a.ts
+index abc1234..def5678 100644
+--- a/src/a.ts
++++ b/src/a.ts
+@@ -1,3 +1,4 @@
+ context
+-old line
++new line
+ more context
+diff --git a/src/b.ts b/src/b.ts
+index 1111111..2222222 100644
+--- a/src/b.ts
++++ b/src/b.ts
+@@ -10,2 +10,3 @@
+ ctx
++added
+`;
+
+  it('splits two-file diff into two entries', () => {
+    const map = splitDiffByFile(FIXTURE);
+    expect(map.size).toBe(2);
+    expect(map.has('src/a.ts')).toBe(true);
+    expect(map.has('src/b.ts')).toBe(true);
+  });
+
+  it('each segment starts with diff --git header', () => {
+    const map = splitDiffByFile(FIXTURE);
+    expect(map.get('src/a.ts')).toMatch(/^diff --git a\/src\/a\.ts/);
+    expect(map.get('src/b.ts')).toMatch(/^diff --git a\/src\/b\.ts/);
+  });
+
+  it('handles deleted file (no +++ b/ line)', () => {
+    const deleted = `diff --git a/gone.ts b/gone.ts
+deleted file mode 100644
+--- a/gone.ts
++++ /dev/null
+@@ -1,2 +0,0 @@
+-line1
+-line2
+`;
+    const map = splitDiffByFile(deleted);
+    expect(map.size).toBe(1);
+    expect(map.has('gone.ts')).toBe(true);
+  });
+
+  it('returns empty map for empty input', () => {
+    expect(splitDiffByFile('').size).toBe(0);
+    expect(splitDiffByFile('\n').size).toBe(0);
+  });
+});
+
+// ── T3: resolveCommittedBase (integration with temp git repo) ──────────────
+
+describe('resolveCommittedBase', () => {
+  let tmp: string;
+
+  beforeAll(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), 'boocode-gitdiff-base-')));
+    await execFileAsync('git', ['init'], { cwd: tmp });
+    await execFileAsync('git', ['-c', 'user.email=test@test.com', '-c', 'user.name=Test',
+      'commit', '--allow-empty', '-m', 'init'], { cwd: tmp });
+  });
+
+  afterAll(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  it('returns null base when no upstream and no origin', async () => {
+    const { base, label } = await resolveCommittedBase(tmp);
+    expect(base).toBeNull();
+    expect(label).toBeTruthy(); // still has a descriptive label
+  });
+});
+
+// ── T4: autoSelectMode ────────────────────────────────────────────────────
+
+describe('autoSelectMode', () => {
+  it('returns uncommitted when dirty', () => {
+    expect(autoSelectMode(true)).toBe('uncommitted');
+  });
+
+  it('returns committed when clean', () => {
+    expect(autoSelectMode(false)).toBe('committed');
+  });
+});
+
+// ── T5: classifyDiffBody ──────────────────────────────────────────────────
+
+describe('classifyDiffBody', () => {
+  it('classifies a normal diff as diff', () => {
+    const body = `diff --git a/foo b/foo
+--- a/foo
++++ b/foo
+@@ -1 +1 @@
+-old
++new
+`;
+    expect(classifyDiffBody(body)).toBe('diff');
+  });
+
+  it('classifies binary diff as binary', () => {
+    const body = `diff --git a/image.png b/image.png
+index abc..def 100644
+Binary files a/image.png and b/image.png differ
+`;
+    expect(classifyDiffBody(body)).toBe('binary');
+  });
+
+  it('classifies oversized diff as too_large', () => {
+    const big = 'a'.repeat(600 * 1024); // 600KB > default cap
+    expect(classifyDiffBody(big)).toBe('too_large');
+  });
+
+  it('respects custom cap', () => {
+    const body = 'a'.repeat(100);
+    expect(classifyDiffBody(body, 50)).toBe('too_large');
+    expect(classifyDiffBody(body, 200)).toBe('diff');
+  });
+});
+
+// ── T6: detectInProgress ──────────────────────────────────────────────────
+
+describe('detectInProgress', () => {
+  let tmp: string;
+
+  beforeAll(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), 'boocode-inprogress-')));
+    await mkdir(join(tmp, '.git'));
+  });
+
+  afterAll(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  it('returns null when no sentinel files present', async () => {
+    expect(await detectInProgress(tmp)).toBeNull();
+  });
+
+  it('detects merge via MERGE_HEAD', async () => {
+    await writeFile(join(tmp, '.git', 'MERGE_HEAD'), 'abc');
+    expect(await detectInProgress(tmp)).toBe('merge');
+    await rm(join(tmp, '.git', 'MERGE_HEAD'));
+  });
+
+  it('detects cherry-pick via CHERRY_PICK_HEAD', async () => {
+    await writeFile(join(tmp, '.git', 'CHERRY_PICK_HEAD'), 'abc');
+    expect(await detectInProgress(tmp)).toBe('cherry-pick');
+    await rm(join(tmp, '.git', 'CHERRY_PICK_HEAD'));
+  });
+
+  it('detects bisect via BISECT_LOG', async () => {
+    await writeFile(join(tmp, '.git', 'BISECT_LOG'), 'abc');
+    expect(await detectInProgress(tmp)).toBe('bisect');
+    await rm(join(tmp, '.git', 'BISECT_LOG'));
+  });
+
+  it('detects rebase via rebase-merge directory', async () => {
+    await mkdir(join(tmp, '.git', 'rebase-merge'));
+    expect(await detectInProgress(tmp)).toBe('rebase');
+    await rm(join(tmp, '.git', 'rebase-merge'), { recursive: true });
+  });
+
+  it('detects rebase via rebase-apply directory', async () => {
+    await mkdir(join(tmp, '.git', 'rebase-apply'));
+    expect(await detectInProgress(tmp)).toBe('rebase');
+    await rm(join(tmp, '.git', 'rebase-apply'), { recursive: true });
+  });
+});
+
+// ── T7: canCommit ─────────────────────────────────────────────────────────
+
+describe('canCommit', () => {
+  const stagedFile: GitDiffFile = {
+    path: 'a.ts',
+    old_path: null,
+    change_type: 'modified',
+    added_lines: 1,
+    removed_lines: 0,
+    staged: true,
+    diff_body: '+new',
+    is_binary: false,
+    is_too_large: false,
+  };
+  const unstagedFile: GitDiffFile = { ...stagedFile, staged: false };
+
+  it('returns true when at least one file is staged', () => {
+    expect(canCommit([stagedFile, unstagedFile])).toBe(true);
+  });
+
+  it('returns false when no files are staged', () => {
+    expect(canCommit([unstagedFile])).toBe(false);
+    expect(canCommit([])).toBe(false);
+  });
+});
+
+// ── T8: getGitDiff integration test ───────────────────────────────────────
+
+describe('getGitDiff integration (temp repo)', () => {
+  let tmp: string;
+
+  beforeAll(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), 'boocode-gitdiff-int-')));
+
+    // Init repo + initial commit
+    await execFileAsync('git', ['init'], { cwd: tmp });
+    await execFileAsync('git', ['config', 'user.email', 'test@test.com'], { cwd: tmp });
+    await execFileAsync('git', ['config', 'user.name', 'Test'], { cwd: tmp });
+    await writeFile(join(tmp, 'existing.ts'), 'const x = 1;\n');
+    await execFileAsync('git', ['add', '.'], { cwd: tmp });
+    await execFileAsync('git', ['commit', '-m', 'init'], { cwd: tmp });
+
+    // Modify existing file (unstaged)
+    await writeFile(join(tmp, 'existing.ts'), 'const x = 2;\n');
+    // Add new untracked file
+    await writeFile(join(tmp, 'untracked.ts'), 'export {};\n');
+    // Stage a new file
+    await writeFile(join(tmp, 'staged.ts'), 'export const y = 1;\n');
+    await execFileAsync('git', ['add', 'staged.ts'], { cwd: tmp });
+  });
+
+  afterAll(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  it('getGitDiff returns git_repo true for a git repo', async () => {
+    const result = await getGitDiff(tmp, 'uncommitted');
+    expect(result).not.toBeNull();
+    expect(result!.mode).toBe('uncommitted');
+  });
+
+  it('includes modified file in uncommitted mode', async () => {
+    const result = await getGitDiff(tmp, 'uncommitted');
+    const paths = result!.files.map((f: GitDiffFile) => f.path);
+    expect(paths).toContain('existing.ts');
+  });
+
+  it('includes staged file with staged=true', async () => {
+    const result = await getGitDiff(tmp, 'uncommitted');
+    const staged = result!.files.find((f: GitDiffFile) => f.path === 'staged.ts');
+    expect(staged).toBeDefined();
+    expect(staged!.staged).toBe(true);
+    expect(staged!.change_type).toBe('added');
+  });
+
+  it('includes untracked file with change_type=untracked', async () => {
+    const result = await getGitDiff(tmp, 'uncommitted');
+    const untracked = result!.files.find((f: GitDiffFile) => f.path === 'untracked.ts');
+    expect(untracked).toBeDefined();
+    expect(untracked!.change_type).toBe('untracked');
+  });
+
+  it('returns null for a non-git directory', async () => {
+    const nonGit = await realpath(await mkdtemp(join(tmpdir(), 'boocode-nongit-')));
+    try {
+      const result = await getGitDiff(nonGit, 'uncommitted');
+      expect(result).toBeNull();
+    } finally {
+      await rm(nonGit, { recursive: true, force: true });
+    }
+  });
+
+  it('returns in_progress_op when MERGE_HEAD exists', async () => {
+    await writeFile(join(tmp, '.git', 'MERGE_HEAD'), 'abc\n');
+    try {
+      const result = await getGitDiff(tmp, 'uncommitted');
+      expect(result!.in_progress_op).toBe('merge');
+    } finally {
+      await rm(join(tmp, '.git', 'MERGE_HEAD'));
+    }
+  });
+});

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

@@ -0,0 +1,379 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdtemp, rm, writeFile, mkdir, access, symlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { realpath } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import {
+  validateWritePath,
+  checkSymlinkEscape,
+  stageFiles,
+  unstageFiles,
+  commitFiles,
+  discardFiles,
+  deriveCommitIdentity,
+  GitWriteError,
+  getGitDiff,
+} from '../git_diff.js';
+
+const execFileAsync = promisify(execFile);
+
+// ── T12: validateWritePath — pure validation ──────────────────────────────
+
+describe('validateWritePath', () => {
+  const root = '/repo/root';
+
+  it('accepts a simple relative path', () => {
+    expect(() => validateWritePath(root, 'src/foo.ts')).not.toThrow();
+  });
+
+  it('accepts a nested path', () => {
+    expect(() => validateWritePath(root, 'a/b/c.ts')).not.toThrow();
+  });
+
+  it('rejects empty string', () => {
+    expect(() => validateWritePath(root, '')).toThrow(GitWriteError);
+  });
+
+  it('rejects path starting with - (flag injection)', () => {
+    expect(() => validateWritePath(root, '-flag')).toThrow(GitWriteError);
+    expect(() => validateWritePath(root, '--option')).toThrow(GitWriteError);
+  });
+
+  it('rejects "." (repo root discard)', () => {
+    expect(() => validateWritePath(root, '.')).toThrow(GitWriteError);
+  });
+
+  it('rejects absolute paths', () => {
+    expect(() => validateWritePath(root, '/etc/passwd')).toThrow(GitWriteError);
+    expect(() => validateWritePath(root, '/repo/root/file.ts')).toThrow(GitWriteError);
+  });
+
+  it('rejects ".." traversal escaping root', () => {
+    expect(() => validateWritePath(root, '../outside/file.ts')).toThrow(GitWriteError);
+    expect(() => validateWritePath(root, 'a/../../outside')).toThrow(GitWriteError);
+  });
+
+  it('rejects path resolving exactly to root', () => {
+    // e.g. "a/.." resolves to /repo/root which is the root itself
+    expect(() => validateWritePath(root, 'a/..')).toThrow(GitWriteError);
+  });
+
+  it('throws GitWriteError not just Error', () => {
+    try {
+      validateWritePath(root, '-bad');
+    } catch (err) {
+      expect(err).toBeInstanceOf(GitWriteError);
+      expect((err as GitWriteError).busy).toBe(false);
+    }
+  });
+});
+
+// ── Integration tests (temp git repo) ─────────────────────────────────────
+
+async function initRepo(dir: string) {
+  await execFileAsync('git', ['init'], { cwd: dir });
+  await execFileAsync('git', ['config', 'user.email', 'test@test.com'], { cwd: dir });
+  await execFileAsync('git', ['config', 'user.name', 'Test User'], { cwd: dir });
+}
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── T9: stage / unstage round-trip ────────────────────────────────────────
+
+describe('stageFiles / unstageFiles round-trip (temp repo)', () => {
+  let tmp: string;
+
+  beforeAll(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), 'boocode-write-stage-')));
+    await initRepo(tmp);
+    await writeFile(join(tmp, 'initial.ts'), 'const a = 1;\n');
+    await execFileAsync('git', ['add', '.'], { cwd: tmp });
+    await execFileAsync('git', ['commit', '-m', 'init'], { cwd: tmp });
+  });
+
+  afterAll(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  it('staging an untracked file shows it as staged in diff', async () => {
+    await writeFile(join(tmp, 'new.ts'), 'export const x = 1;\n');
+    // Before staging
+    const before = await getGitDiff(tmp, 'uncommitted');
+    const untrackedBefore = before!.files.find((f) => f.path === 'new.ts');
+    expect(untrackedBefore?.change_type).toBe('untracked');
+    expect(untrackedBefore?.staged).toBe(false);
+
+    // Stage
+    await stageFiles(tmp, ['new.ts']);
+
+    // After staging
+    const after = await getGitDiff(tmp, 'uncommitted');
+    const stagedAfter = after!.files.find((f) => f.path === 'new.ts');
+    expect(stagedAfter?.staged).toBe(true);
+    expect(stagedAfter?.change_type).toBe('added');
+  });
+
+  it('unstaging removes file from staged set', async () => {
+    // new.ts is currently staged from the previous test
+    await unstageFiles(tmp, ['new.ts']);
+    const after = await getGitDiff(tmp, 'uncommitted');
+    const f = after!.files.find((f) => f.path === 'new.ts');
+    expect(f?.staged).toBe(false);
+    expect(f?.change_type).toBe('untracked');
+  });
+
+  it('stageFiles rejects a path starting with -', async () => {
+    await expect(stageFiles(tmp, ['-bad'])).rejects.toThrow(GitWriteError);
+  });
+
+  it('stageFiles rejects path traversal', async () => {
+    await expect(stageFiles(tmp, ['../outside.ts'])).rejects.toThrow(GitWriteError);
+  });
+});
+
+// ── T10: commit with server-derived identity ──────────────────────────────
+
+describe('commitFiles with server-derived identity (temp repo)', () => {
+  let tmp: string;
+
+  beforeAll(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), 'boocode-write-commit-')));
+    await initRepo(tmp);
+    await writeFile(join(tmp, 'base.ts'), 'export const a = 1;\n');
+    await execFileAsync('git', ['add', '.'], { cwd: tmp });
+    await execFileAsync('git', ['commit', '-m', 'init'], { cwd: tmp });
+  });
+
+  afterAll(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  it('deriveCommitIdentity falls back when no git config set', async () => {
+    // New repo initialized without global user config — may or may not have local config.
+    // The function should always return a non-empty name and email.
+    const identity = await deriveCommitIdentity(tmp);
+    expect(identity.name).toBeTruthy();
+    expect(identity.email).toBeTruthy();
+  });
+
+  it('deriveCommitIdentity uses git config when set', async () => {
+    const identity = await deriveCommitIdentity(tmp);
+    // We set user.email/name in initRepo above
+    expect(identity.name).toBe('Test User');
+    expect(identity.email).toBe('test@test.com');
+  });
+
+  it('commit creates a new commit and the staged file is no longer in diff', async () => {
+    await writeFile(join(tmp, 'newfile.ts'), 'export const b = 2;\n');
+    await stageFiles(tmp, ['newfile.ts']);
+
+    const before = await getGitDiff(tmp, 'uncommitted');
+    expect(before!.files.find((f) => f.path === 'newfile.ts')).toBeDefined();
+
+    await commitFiles(tmp, 'add newfile');
+
+    const after = await getGitDiff(tmp, 'uncommitted');
+    expect(after!.files.find((f) => f.path === 'newfile.ts')).toBeUndefined();
+  });
+
+  it('commit with specific files only commits those files', async () => {
+    await writeFile(join(tmp, 'a.ts'), 'const a = 1;\n');
+    await writeFile(join(tmp, 'b.ts'), 'const b = 2;\n');
+    await stageFiles(tmp, ['a.ts', 'b.ts']);
+
+    await commitFiles(tmp, 'partial commit', ['a.ts']);
+
+    const after = await getGitDiff(tmp, 'uncommitted');
+    const aFile = after!.files.find((f) => f.path === 'a.ts');
+    const bFile = after!.files.find((f) => f.path === 'b.ts');
+    // a.ts was committed — should not appear in uncommitted diff
+    expect(aFile).toBeUndefined();
+    // b.ts is still staged
+    expect(bFile?.staged).toBe(true);
+  });
+
+  it('commit rejects a path starting with - in files list', async () => {
+    await expect(commitFiles(tmp, 'msg', ['-bad'])).rejects.toThrow(GitWriteError);
+  });
+});
+
+// ── T11: discard tracked vs untracked ─────────────────────────────────────
+
+describe('discardFiles (temp repo)', () => {
+  let tmp: string;
+
+  beforeAll(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), 'boocode-write-discard-')));
+    await initRepo(tmp);
+    await writeFile(join(tmp, 'tracked.ts'), 'const orig = 1;\n');
+    await execFileAsync('git', ['add', '.'], { cwd: tmp });
+    await execFileAsync('git', ['commit', '-m', 'init'], { cwd: tmp });
+  });
+
+  afterAll(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  it('discarding a modified tracked file reverts its content', async () => {
+    await writeFile(join(tmp, 'tracked.ts'), 'const modified = 99;\n');
+    const before = await getGitDiff(tmp, 'uncommitted');
+    expect(before!.files.find((f) => f.path === 'tracked.ts')).toBeDefined();
+
+    await discardFiles(tmp, [{ path: 'tracked.ts', change_type: 'modified', staged: false }]);
+
+    const after = await getGitDiff(tmp, 'uncommitted');
+    expect(after!.files.find((f) => f.path === 'tracked.ts')).toBeUndefined();
+  });
+
+  it('discarding an untracked file removes it from disk', async () => {
+    await writeFile(join(tmp, 'untracked.ts'), 'orphan\n');
+    const exists = await fileExists(join(tmp, 'untracked.ts'));
+    expect(exists).toBe(true);
+
+    await discardFiles(tmp, [{ path: 'untracked.ts', change_type: 'untracked', staged: false }]);
+
+    expect(await fileExists(join(tmp, 'untracked.ts'))).toBe(false);
+  });
+
+  it('discarding a staged-addition file removes it from index and disk', async () => {
+    await writeFile(join(tmp, 'staged-add.ts'), 'new file\n');
+    await stageFiles(tmp, ['staged-add.ts']);
+
+    const before = await getGitDiff(tmp, 'uncommitted');
+    expect(before!.files.find((f) => f.path === 'staged-add.ts')?.staged).toBe(true);
+
+    await discardFiles(tmp, [{ path: 'staged-add.ts', change_type: 'added', staged: true }]);
+
+    const after = await getGitDiff(tmp, 'uncommitted');
+    expect(after!.files.find((f) => f.path === 'staged-add.ts')).toBeUndefined();
+    expect(await fileExists(join(tmp, 'staged-add.ts'))).toBe(false);
+  });
+
+  it('discardFiles rejects "." (repo root)', async () => {
+    await expect(
+      discardFiles(tmp, [{ path: '.', change_type: 'modified', staged: false }]),
+    ).rejects.toThrow(GitWriteError);
+  });
+
+  it('discardFiles rejects path traversal', async () => {
+    await expect(
+      discardFiles(tmp, [{ path: '../outside', change_type: 'untracked', staged: false }]),
+    ).rejects.toThrow(GitWriteError);
+  });
+});
+
+// ── Index-lock → busy error ────────────────────────────────────────────────
+
+describe('index-lock detection', () => {
+  let tmp: string;
+
+  beforeAll(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), 'boocode-write-lock-')));
+    await initRepo(tmp);
+    await writeFile(join(tmp, 'file.ts'), 'const x = 1;\n');
+    await execFileAsync('git', ['add', '.'], { cwd: tmp });
+    await execFileAsync('git', ['commit', '-m', 'init'], { cwd: tmp });
+  });
+
+  afterAll(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  it('stageFiles throws GitWriteError with busy=true when index.lock exists', async () => {
+    await writeFile(join(tmp, 'new.ts'), 'export {};\n');
+    // Simulate a lock by creating .git/index.lock
+    await mkdir(join(tmp, '.git'), { recursive: true });
+    await writeFile(join(tmp, '.git', 'index.lock'), '');
+    try {
+      await stageFiles(tmp, ['new.ts']);
+      // Should not reach here
+      expect(true).toBe(false);
+    } catch (err) {
+      expect(err).toBeInstanceOf(GitWriteError);
+      expect((err as GitWriteError).busy).toBe(true);
+    } finally {
+      try { await rm(join(tmp, '.git', 'index.lock')); } catch { /* already gone */ }
+    }
+  });
+});
+
+// ── Commit request schema: reject unknown author fields ───────────────────
+
+describe('GitCommitBody schema strictness (unit)', () => {
+  it('rejects extra author/email fields via Zod strict', () => {
+    // We import Zod inline to mirror the route's schema
+    const { z } = require('zod');
+    const GitCommitBody = z
+      .object({
+        message: z.string().min(1),
+        files: z.array(z.string().min(1)).optional(),
+      })
+      .strict();
+
+    const result = GitCommitBody.safeParse({
+      message: 'test commit',
+      author: 'Evil <evil@hack.com>',
+      email: 'evil@hack.com',
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('accepts valid commit body with message only', () => {
+    const { z } = require('zod');
+    const GitCommitBody = z
+      .object({
+        message: z.string().min(1),
+        files: z.array(z.string().min(1)).optional(),
+      })
+      .strict();
+
+    const result = GitCommitBody.safeParse({ message: 'add feature' });
+    expect(result.success).toBe(true);
+  });
+});
+
+// ── T13: checkSymlinkEscape (FIX 3) ──────────────────────────────────────────
+
+describe('checkSymlinkEscape', () => {
+  let repoDir: string;
+  let outsideDir: string;
+
+  beforeAll(async () => {
+    repoDir = await realpath(await mkdtemp(join(tmpdir(), 'boocode-symlink-repo-')));
+    outsideDir = await realpath(await mkdtemp(join(tmpdir(), 'boocode-symlink-outside-')));
+    await writeFile(join(outsideDir, 'secret.ts'), 'secret data\n');
+    // Symlink inside repo pointing to outside dir
+    await symlink(outsideDir, join(repoDir, 'evil'));
+  });
+
+  afterAll(async () => {
+    await rm(repoDir, { recursive: true, force: true });
+    await rm(outsideDir, { recursive: true, force: true });
+  });
+
+  it('rejects a path that escapes via a directory symlink', async () => {
+    await expect(checkSymlinkEscape(repoDir, 'evil/secret.ts')).rejects.toThrow(GitWriteError);
+  });
+
+  it('rejects a path that resolves to the symlink itself (outside)', async () => {
+    await expect(checkSymlinkEscape(repoDir, 'evil')).rejects.toThrow(GitWriteError);
+  });
+
+  it('accepts a path that resolves within the repo', async () => {
+    await writeFile(join(repoDir, 'legit.ts'), 'export {};\n');
+    await expect(checkSymlinkEscape(repoDir, 'legit.ts')).resolves.toBeUndefined();
+  });
+
+  it('accepts a non-existent path (new file being staged)', async () => {
+    await expect(checkSymlinkEscape(repoDir, 'brand-new-file-not-yet-created.ts')).resolves.toBeUndefined();
+  });
+});

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__/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__/model-context.test.ts

@@ -9,12 +9,9 @@ import {
 
 const TEST_URL = 'http://llama-swap.test:8401';
 
-function mockOkProps(n_ctx: number, total_slots = 1) {
+function mockOkProps(n_ctx: number) {
   return new Response(
-    JSON.stringify({
+    JSON.stringify({ default_generation_settings: { n_ctx } }),
-      default_generation_settings: { n_ctx },
-      total_slots,
-    }),
     { status: 200, headers: { 'Content-Type': 'application/json' } },
   );
 }
@@ -33,12 +30,10 @@ afterEach(() => {
 
 describe('getModelContext — positive cache', () => {
   it('returns the parsed body on a 200 with valid shape', async () => {
-    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(mockOkProps(262_144, 1));
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(mockOkProps(262_144));
     const result = await getModelContext('qwen3.6');
     expect(result).not.toBeNull();
     expect(result!.n_ctx).toBe(262_144);
-    expect(result!.total_slots).toBe(1);
-    expect(typeof result!.fetched_at).toBe('number');
     // Verify the URL was constructed correctly — encodes the model name in
     // case it contains characters that would break the path.
     expect(fetchSpy).toHaveBeenCalledExactlyOnceWith(
@@ -57,19 +52,6 @@ describe('getModelContext — positive cache', () => {
     expect(fetchSpy).toHaveBeenCalledTimes(1);
   });
 
-  it('defaults total_slots to 1 when the server omits it', async () => {
-    // Mirror the docstring claim — total_slots is informational and we don't
-    // reject the response just because it's missing.
-    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
-      new Response(JSON.stringify({ default_generation_settings: { n_ctx: 8192 } }), {
-        status: 200,
-      }),
-    );
-    const result = await getModelContext('partial-model');
-    expect(result).not.toBeNull();
-    expect(result!.n_ctx).toBe(8192);
-    expect(result!.total_slots).toBe(1);
-  });
 });
 
 // ---- negative cache (single-shot) ------------------------------------------

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

@@ -0,0 +1,87 @@
+import { describe, it, expect } from 'vitest';
+import { SENTINEL_KINDS, isAnySentinel, isCapHitSentinel, isDoomLoopSentinel, isMistakeRecoverySentinel } from '../inference/sentinels.js';
+import type { Message } from '../../types/api.js';
+
+function makeSentinel(kind: string): Message {
+  return {
+    id: 'msg-1',
+    session_id: 's',
+    chat_id: 'c',
+    role: 'system',
+    content: '',
+    kind: 'message',
+    tool_calls: null,
+    tool_results: null,
+    status: 'complete',
+    last_seq: 0,
+    tokens_used: null,
+    ctx_used: null,
+    ctx_max: null,
+    started_at: null,
+    finished_at: null,
+    created_at: new Date().toISOString(),
+    metadata: { kind } as unknown as import('../../types/api.js').MessageMetadata,
+    summary: false,
+    tail_start_id: null,
+    compacted_at: null,
+  };
+}
+
+describe('SENTINEL_KINDS — single source of truth', () => {
+  it('contains the three known sentinel kinds', () => {
+    expect(SENTINEL_KINDS.has('cap_hit')).toBe(true);
+    expect(SENTINEL_KINDS.has('doom_loop')).toBe(true);
+    expect(SENTINEL_KINDS.has('mistake_recovery')).toBe(true);
+  });
+
+  it('does not contain arbitrary strings', () => {
+    expect(SENTINEL_KINDS.has('user')).toBe(false);
+    expect(SENTINEL_KINDS.has('assistant')).toBe(false);
+    expect(SENTINEL_KINDS.has('')).toBe(false);
+  });
+});
+
+describe('isAnySentinel', () => {
+  it('returns true for cap_hit', () => {
+    expect(isAnySentinel(makeSentinel('cap_hit'))).toBe(true);
+  });
+
+  it('returns true for doom_loop', () => {
+    expect(isAnySentinel(makeSentinel('doom_loop'))).toBe(true);
+  });
+
+  it('returns true for mistake_recovery', () => {
+    expect(isAnySentinel(makeSentinel('mistake_recovery'))).toBe(true);
+  });
+
+  it('returns false for non-system role', () => {
+    const m = { ...makeSentinel('cap_hit'), role: 'user' as const };
+    expect(isAnySentinel(m)).toBe(false);
+  });
+
+  it('returns false for null metadata', () => {
+    const m = { ...makeSentinel('cap_hit'), metadata: null };
+    expect(isAnySentinel(m)).toBe(false);
+  });
+
+  it('returns false for unknown kind', () => {
+    expect(isAnySentinel(makeSentinel('unknown_kind'))).toBe(false);
+  });
+});
+
+describe('individual sentinel predicates still work', () => {
+  it('isCapHitSentinel matches cap_hit only', () => {
+    expect(isCapHitSentinel(makeSentinel('cap_hit'))).toBe(true);
+    expect(isCapHitSentinel(makeSentinel('doom_loop'))).toBe(false);
+  });
+
+  it('isDoomLoopSentinel matches doom_loop only', () => {
+    expect(isDoomLoopSentinel(makeSentinel('doom_loop'))).toBe(true);
+    expect(isDoomLoopSentinel(makeSentinel('cap_hit'))).toBe(false);
+  });
+
+  it('isMistakeRecoverySentinel matches mistake_recovery only', () => {
+    expect(isMistakeRecoverySentinel(makeSentinel('mistake_recovery'))).toBe(true);
+    expect(isMistakeRecoverySentinel(makeSentinel('cap_hit'))).toBe(false);
+  });
+});

apps/server/src/services/__tests__/step-decision.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from 'vitest';
+import { resolveTurnConfig, MAX_STEPS } from '../inference/turn-config.js';
+import { decideStep, decidePostToolAction } from '../inference/step-decision.js';
+import { DOOM_LOOP_THRESHOLD } from '../inference/sentinels.js';
+import type { MistakeState } from '../inference/mistake-tracker.js';
+import type { Agent, ToolCall } 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,
+};
+
+function call(name: string, args: Record<string, unknown> = {}): ToolCall {
+  return { id: `tc-${name}-${JSON.stringify(args)}`, name, args };
+}
+
+describe('resolveTurnConfig', () => {
+  it('no agent → budget 100, cap MAX_STEPS, not text-only', () => {
+    expect(resolveTurnConfig(null)).toEqual({
+      effectiveCap: MAX_STEPS,
+      budget: 100,
+      isTextOnly: false,
+    });
+  });
+
+  it('steps: 0 → effectiveCap 0 and isTextOnly true', () => {
+    expect(resolveTurnConfig({ ...BASE_AGENT, steps: 0 })).toEqual({
+      effectiveCap: 0,
+      budget: 100,
+      isTextOnly: true,
+    });
+  });
+
+  it('steps below MAX_STEPS → effectiveCap is the agent value', () => {
+    expect(resolveTurnConfig({ ...BASE_AGENT, steps: 5 }).effectiveCap).toBe(5);
+  });
+
+  it('steps above MAX_STEPS → effectiveCap clamps to MAX_STEPS', () => {
+    expect(resolveTurnConfig({ ...BASE_AGENT, steps: 9999 }).effectiveCap).toBe(MAX_STEPS);
+  });
+
+  it('max_tool_calls overrides the budget', () => {
+    expect(resolveTurnConfig({ ...BASE_AGENT, max_tool_calls: 12 }).budget).toBe(12);
+  });
+});
+
+describe('decideStep (top-of-loop gate)', () => {
+  it('returns stream when no doom loop and under budget', () => {
+    expect(decideStep({ recentToolCalls: [], toolsUsed: 0, budget: 30 })).toEqual({ kind: 'stream' });
+  });
+
+  it('returns budget when toolsUsed has reached the budget', () => {
+    expect(decideStep({ recentToolCalls: [], toolsUsed: 30, budget: 30 })).toEqual({ kind: 'budget' });
+  });
+
+  it('returns doom (with the looping call) on identical-repeat tail', () => {
+    const recent = Array.from({ length: DOOM_LOOP_THRESHOLD }, () => call('view_file', { path: '/a' }));
+    const d = decideStep({ recentToolCalls: recent, toolsUsed: 1, budget: 30 });
+    expect(d.kind).toBe('doom');
+    if (d.kind === 'doom') {
+      expect(d.loop.name).toBe('view_file');
+      expect(d.loop.args).toEqual({ path: '/a' });
+    }
+  });
+
+  it('doom takes precedence over budget when both would trip', () => {
+    const recent = Array.from({ length: DOOM_LOOP_THRESHOLD }, () => call('grep', { q: 'x' }));
+    expect(decideStep({ recentToolCalls: recent, toolsUsed: 30, budget: 30 }).kind).toBe('doom');
+  });
+});
+
+describe('decidePostToolAction (post-tool decision)', () => {
+  const clean: MistakeState = { run: [], nudges: 0 };
+
+  it('non-continue actions stop the loop without consulting the tracker', () => {
+    expect(decidePostToolAction('paused', { run: ['exec_error', 'exec_error', 'exec_error'], nudges: 0 })).toBe('stop');
+    expect(decidePostToolAction('synthesis_done', clean)).toBe('stop');
+  });
+
+  it('continue with a clean tracker → continue', () => {
+    expect(decidePostToolAction('continue', clean)).toBe('continue');
+  });
+
+  it('continue with a threshold streak and no prior nudge → nudge', () => {
+    const tracker: MistakeState = { run: ['zod_reject', 'tool_not_found', 'exec_error'], nudges: 0 };
+    expect(decidePostToolAction('continue', tracker)).toBe('nudge');
+  });
+
+  it('continue with a threshold streak after a nudge already fired → escalate', () => {
+    const tracker: MistakeState = { run: ['zod_reject', 'tool_not_found', 'exec_error'], nudges: 1 };
+    expect(decidePostToolAction('continue', tracker)).toBe('escalate');
+  });
+});