Merge contracts-ssot-pkg: v2.7.13 single-source cross-app wire contracts in @boocode/contracts

Move all hand-synced cross-app wire contracts into one built workspace
package, @boocode/contracts, consumed by server/web/coder/coder-web via
workspace:* + a per-subpath exports map. The ws-frames and provider-config
Zod schemas are schema-first (z.infer); MessageMetadata, ErrorReason,
AgentSessionConfig, the provider snapshot types, and WorktreeRiskReport are
each single-sourced. Deletes the byte-identical copies and their parity
tests, fixes a live AgentSessionConfig drift (coder dead copy removed,
unified to the web required/nullable shape), removes the dead pending_change
WS arms in the fallback SPA, and inverts the build order (contracts builds
first) across root build, Dockerfile, and the coder deploy docs. Reverses
the shared-package decision declined in v2.5.12.

Co-Authored-By: Claude Opus 4.8 <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.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.11-coder-model-snapshot — 2026-06-02
+
+Hotfix for the coder model-attribution chip vanishing on refresh. The chip showed during a live turn (the `message_complete` frame carries `model`) but disappeared when a BooCoder session was reloaded — only in the coder, not BooChat. Root cause: `CoderPane`'s `useCoderMessages` hydrates from two sources on load — the HTTP `listMessages` fetch (whose SELECT includes `model`, added `v2.7.8`) AND the WS `snapshot` frame — and the WS snapshot's query in `apps/coder/src/routes/ws.ts` had its own column list that omitted `model`. The client's `snapshot` handler `setMessages`-overwrites the HTTP load, so the model-less rows won, and with no later `message_complete` for historical messages the chip stayed gone. Fix is one column: add `model` to the WS snapshot SELECT so both hydration paths agree. The `apps/coder/CLAUDE.md` "update every mapper" note now lists the WS snapshot SELECT explicitly (it was the one place not enumerated). apps/server + apps/coder builds green; deployed via `systemctl restart boocoder` (host service — the earlier `v2.7.10` docker deploy rebuilt only the container, never this route). Fixes the chip shipped in `v2.7.8-ember-coder-tabs-model-chips` / completed in `v2.7.9-mcp-keys-docs-coder-fixes`.
+
+## v2.7.10-composer-chips — 2026-06-02
+
+A composer control-row refresh shared by BooChat and BooCoder via `ChatInput`. The slash-commands menu moves out of the full-width `AgentCommandsHint` disclosure (now removed) into a compact chip in the message box's bottom controls row — clicking it opens the existing `SlashCommandPicker` anchored to the chip and selecting inserts `/<name> `, while the typed-`/` autocomplete is unchanged. A new attach-file button sits beside it, opening a native multi-file picker that funnels picks through the same drag-drop pipeline (5 MB / binary gate, 10-attachment cap, chips + preview, `source:'drop'`). On mobile both collapse to icon-only — the slash count is `max-md:hidden` and the paperclip is icon-only — so the row stays on one line per the no-scroll toolbar rule. Web tsc + build green; deployed (docker). Builds on the BooCode 2.0 composer work in `v2.7.8-ember-coder-tabs-model-chips`.
+
+## v2.7.9-mcp-keys-docs-coder-fixes — 2026-06-02
+
+The MCP-key hygiene feature plus accumulated in-flight coder fixes and a docs refactor. **MCP `{env:VAR}` substitution** (`mcp-config.ts:substituteEnvVars`, opencode-compatible) recursively resolves `{env:NAME}` references in any string value of `data/mcp.json` from `process.env` *before* Zod validation, so real keys live in `.env` (`env_file`) instead of the gitignored config — an unset var resolves to `''` with a boot-log warning, and on a validation failure the loader names the unset vars alongside the field errors (an empty `{env:VAR}` in a strict url/command field invalidates the whole config, an otherwise-disconnected warning). `data/mcp.json` is now untracked (`.gitignore` flips `!data/mcp.json` → `!data/mcp.example.json`); the tracked template `data/mcp.example.json` carries `"CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"` and `.env.example` documents the key (9 mcp-config tests). **Two coder bug fixes** ride along: the `message_complete` frame's `model` is widened `string` → `string | null` in both ws-frames copies (server + web parity) and the dispatcher now publishes `model: task.model` at all four external assistant-completion points — without the nullable widen a null model would fail-closed in `publishFrame` and drop the entire frame including the `status:'complete'` transition (regression test added); and Claude-SDK `mapUserToolResults` now maps `user`-message `tool_result` blocks → terminal `tool_update` events (completed/failed with output) so external-agent tool snapshots resolve instead of spinning forever (the SDK feeds tool output back as a user message, previously unmapped). On the view side the `AgentComposerBar` drops the §9b resumed/history/new-session chip and token-usage readout and loses `flex-wrap` so the control row stays on one line, while `CoderPane` gains a per-chat `localStorage` agent-config cache (provider/model/mode/thinking keyed by chat id, restoring the last model on reopen) and threads the new `model` field into the timeline + attribution chip. **Docs refactor**: the root `CLAUDE.md` is slimmed (~190 lines) with per-app deep references split into `apps/{coder,server,web}/CLAUDE.md` (auto-loaded in-subtree), plus a new 372-line `docs/coder-backends.md` dispatch reference, a `docs/project-discovery.md` stack inventory, and a `docs/coding-standards/` set (the `cross-app-contract-parity` standard, fronted by `.claude/rules` path-scoped indexes) — `ARCHITECTURE.md` links the backends doc. Server 555 + coder 299 tests passing (incl. new mcp-config, ws-frames, and claude-sdk-map suites), web tsc + server + coder builds green. Builds on `v2.7.8-ember-coder-tabs-model-chips`.
+
+## v2.7.8-ember-coder-tabs-model-chips — 2026-06-01
+
+The BooCode 2.0 visual identity plus two workflow features. **Ember theme** (`styles/themes/ember.css`, now `DEFAULT_THEME_ID`) is the signature orange-on-near-black look — rebuilt on Obsidian's flat charcoal structure (`#0c0c0e`/`#15151a`/`#1f1f23`) with `#ff7a18` swapped in for the purple, after a Reinvented-direction detour (neon borders + a scanline/glow texture overlay) was dialed back to taste; the server `theme_id` whitelist gains `ember` so it can actually be selected. The **brand banner** (`ProjectSidebar`) shows the eye-patch Westie mascot + the `>_BooCode` wordmark big and edge-to-edge on transparent backgrounds — the source PNGs shipped with baked-white canvases, so they were flood-filled to transparency from the corners (preserving the white dog, which a naive white-key would have destroyed) and cropped to bounds. **Coder panes are now multi-tab**: `+` opens a new BooCode tab (a fresh chat = a new agent context sharing the session worktree) while the split button still opens a pane — coder panes reuse the shared `ChatTabBar` via a kind-aware `tabKind`, backed by a new `createCoderTab` action with `closeOtherTabs`/tab-numbering extended to coder kind. **Model-attribution chips**: a new `messages.model` column (both apps share the table) stamped at `finalizeCompletion` (BooChat + native coder) and at the dispatcher's assistant-row creation (external coder), surfaced through the `messages_with_parts` view + wire types + the live `message_complete` frame (the Zod already allowed `model`; nothing consumed it), and rendered as a subtle accent chip with a shortened label (`shortenModelName` → `Sonnet 4.6`, `Qwen3.6 35B`) beside the message stats — so swapping models mid-coder-session stays legible. Also the composer moved its Web toggle into a boxed, focus-ringed input, tool rows lead with a glowing accent dot, and the Claude-SDK-backend follow-ups validated live this session (1M context window, follow-up-message fix, collapsed thinking/tool chips) land with `CLAUDE_SDK_BACKEND=1` flipped on. One snag fixed mid-deploy: the view's new `m.model` was first inserted mid-list and `CREATE OR REPLACE VIEW` can't reorder columns (42P16) — appended at the end. Web tsc + server + coder builds green; deployed (docker + boocoder, tools:34). Builds on `v2.7.7-pane-header-actions`.
+
+## v2.7.7-pane-header-actions — 2026-06-01
+
+In-flight workspace UX work, committed alongside the v2.7 review batches. Extracts a shared `PaneHeaderActions` cluster (the +/Split/Reopen-closed-pane/Session-history/Close controls) used across the `ChatTabBar` and the desktop coder + terminal pane headers in `Workspace`, replacing the divergent per-header copies, with `SessionLandingPage` history enhancements and `useWorkspacePanes` tweaks. Also fixes a coder-side correctness bug: `resolveChatId` (`apps/coder/src/routes/chat-resolve.ts`) still read `sessions.workspace_panes` as a bare `WorkspacePane[]`, but `v2.6.5-panes-tabs-composer` widened it to a `WorkspaceState` envelope — so it mis-read the panes and, worse, clobbered `tabNumbers`/`nextTabNumber`/`closedPaneStack` back to a bare array on every pane-chat write; a new `normalizeWorkspaceState` accepts either shape and preserves the envelope (with a regression test). Plus a CLAUDE.md doc-sync (apps/coder vitest suite, deploy-by-surface, dual-remote push, in-flight-web-WIP staging, release-branch naming). Web tsc + coder build + coder tests green. Builds on `v2.7.6-agent-status-normalize`.
+
+## v2.7.6-agent-status-normalize — 2026-06-01
+
+The scoped half of `boocode_code_review_v2.md` §1 #10 — normalized external-agent status, surfaced from BooCoder's own dispatch observation (the heavier config-injection notify-hook, clean-room from superset's ELv2 `agent-setup`, is documented as the follow-on). The review's premise ("PTY agents have no status") had partly aged out — warm-ACP/opencode/SDK already carry working/done — so the real gap was that BooCoder never *published* a normalized per-`(chat,agent)` status (blocked-on-permission was invisible; crash/idle weren't pushed). Adds an `agent_status_updated` WS frame (`working|blocked|idle|error`, server+web parity) published from the dispatcher's turn boundaries across all four external paths (warm-acp/opencode/sdk/pty — `working` at start, `idle`/`error` at end) and the permission flow (`blocked` on request, `working` on resolve), best-effort so it never breaks a turn. A clean-room `normalizeAgentEvent` helper (superset's ~30-vendor-event → Start/blocked/Stop collapse, reimplemented with the event names as facts) ships now with 25 tests so the deferred notify-hook injection reuses it verbatim. The `AgentComposerBar` gains a normalized status dot (working=spinner, blocked=amber, idle=gray, error=red) distinct from the WS-liveness dot, fed by a `useAgentStatus` map `CoderPane` tracks per `(chat,agent)`. Built by two parallel agents (data plane + view plane) against a pinned frame contract; server 545 + coder 294 tests passing (25 new), web tsc + builds clean, ws-frames parity green. Clears the actionable review backlog (#1/#3/#4/#6–#12). Builds on `v2.7.5-claude-sdk-sessionstore`; openspec `agent-status-normalize`.
+
+## v2.7.5-claude-sdk-sessionstore — 2026-06-01
+
+Lands the Claude Agent SDK direction (`boocode_code_review_v2.md` §1 #9, §6.2 "lean SDK") behind a flag. Adds `@anthropic-ai/claude-agent-sdk@0.3.159` (Commercial Terms — runtime dep, code reference-only) and builds a warm, resumable claude backend to supersede one-shot PTY dispatch — env-gated (`CLAUDE_SDK_BACKEND`, default off) so production claude stays on the unchanged PTY path until a host smoke. **Clean-room `PostgresSessionStore`** implements the SDK's real `SessionStore` type (`append`/`load`/`listSessions`/`delete`/`listSubkeys`) over a new `claude_session_entries` table — typechecked against the installed SDK type, 8 DB-integration tests. **`ClaudeSdkBackend`** (`implements AgentBackend`, mirroring warm-acp/opencode-server) drives one persistent `query()` per `(chat,'claude')` in streaming-input mode via a pushable async-iterable pump, with `sessionStore` + `resume` for cross-turn/cross-restart continuity, a pure `mapSdkMessage`→`AgentEvent` mapper, `session_id` captured from the `init` message, and `result.usage`/`total_cost_usd` accumulated onto `agent_sessions` (backend CHECK gains `'claude_sdk'`). Built against the REAL SDK 0.3.159 types after installing it — surfacing shapes a blind build would have missed (`SDKPartialAssistantMessage` is `type:'stream_event'` needing `includePartialMessages`; `SDKUserMessage.message` is `MessageParam`; the `SDKResultMessage` error arm). Also fixes a latent test-infra deadlock — three DB-integration suites applying the full schema in parallel under `DATABASE_URL` deadlocked, now serialized via `fileParallelism:false`. ~32 new tests (8 store + 10 mapper + 8 pushable + 6 routing); coder suite 269 passing default / 290 with DB; tsc clean against the SDK types; builds clean. **The live streaming pump + resume + an actual claude turn need a host smoke (`CLAUDE_SDK_BACKEND=1` + claude binary + ANTHROPIC auth) — cannot run from the dev container.** The zod peer-dep wants `^4` (workspace `3.25`) — watch at runtime. Builds on `v2.7.4-mistake-tracker-ledger`; openspec `claude-sdk-sessionstore`.
+
 ## v2.7.4-mistake-tracker-ledger — 2026-06-01
 
 Two native-inference hardening features from `boocode_code_review_v2.md` §1 #12 (cline, algorithm-reimplemented). **MistakeTracker:** complements the doom-loop guard (identical repeats) and cap-hit (budget) by catching a run of consecutive tool *failures*. A new pure `mistake-tracker.ts` tracks heterogeneous failure kinds (`zod_reject`/`tool_not_found`/`exec_error`/`api_error`/`permission_denied`, surfaced per tool from `tool-phase.ts`); after 3 consecutive failures the `turn.ts` loop does a **soft nudge** — injects model-facing recovery guidance into the next step + drops a `mistake_recovery` UI sentinel + resets — then **escalates** to stopping the turn (cap-hit-style, with a Continue affordance) if it re-trips without an intervening success, so heterogeneous failures can't burn the whole step budget. **File-provenance ledger:** `compaction.ts` now derives a deterministic, sorted `## Files Read` list from the head messages' read-tool calls (`view_file`/`grep`/`find_files`/`list_dir`) and injects it into the rolling-summary prompt so file provenance survives compaction (no new table; prompt-driven merge, read-only since BooChat has no write tools). The `mistake_recovery` sentinel adds an arm to `MessageMetadata` in both server + web type copies plus a `MessageBubble` render branch. Built by two parallel agents (backend + frontend sentinel) over disjoint apps; server 545 tests passing (23 new: 12 mistake-tracker + 11 compaction), build + web tsc clean. Native-inference only (external agents run their own loops). Builds on `v2.7.3-sampling-streamjson-tokens`; openspec `mistake-tracker-file-ledger`.

CLAUDE.md

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

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
 

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/coder/.env.host

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

apps/coder/CLAUDE.md

@@ -0,0 +1,34 @@
+# apps/coder — BooCoder (deep reference)
+
+> Per-app engineering notes for `apps/coder/src/`. BooCoder runs as a **systemd service on the host** (`boocoder.service`), NOT in Docker — Fastify at port 9502, postgres at `127.0.0.1:5500`. Cross-cutting commands, database, environment, workflow, and cross-app contracts live in the **root `CLAUDE.md`**. This file auto-loads when you read/edit files under `apps/coder/`.
+
+## Probe & provider discovery
+
+- **`services/provider-registry.ts`** — Static registry of provider metadata (label, transport, model source). `PROVIDERS` array, `PROVIDERS_BY_NAME` map. 5 providers: boocode (native), opencode (acp), goose (pty), claude (pty), qwen (pty). `PROBED_AGENT_NAMES` derives from it — adding/removing providers means editing this file, not the frontend.
+- **`services/agent-probe.ts`** — Startup probe via direct `exec()` (not SSH): discovers installed agents, versions, ACP support, models. Qwen models from `~/.qwen/settings.json`; Claude models static from the registry. Persisted to `available_agents`.
+- **`routes/providers.ts`** — `GET /api/providers` returns installed providers with models. Transport reflects actual capability (checks `supports_acp` from DB, not just registry preference). The apps/server side is "Provider picker dispatch" (see `apps/server/CLAUDE.md`).
+- **Provider snapshot lifecycle** (`services/`): `provider-config.ts` (Zod config, never-throws) → `provider-config-registry.ts` (`buildResolvedRegistry`, singleton) → `provider-snapshot.ts` (two-tier probe: tier-1 fast presence, tier-2 cold ACP probe skipped unless force / stale `PROVIDER_PROBE_TTL_MS` 24h / dbEmpty; cached). Verify live: `curl http://100.114.205.53:9502/api/providers/snapshot` — returns providers + models + commands, the exact shape `AgentComposerBar` renders.
+- `PATCH /api/providers/config` replaces a provider id's override object **wholesale** (per-id shallow merge) — to flip one field send `{...existing, enabled}`, or a custom ACP entry's `command`/`label` is wiped and it drops out of the resolved registry. `data/coder-providers.json` is **gitignored** (live runtime config — the coder reads AND writes it on UI toggles); tracked reference is `data/coder-providers.example.json`. The loader falls back to `{providers:{}}` (built-ins only) when absent, so a fresh checkout needs no copy.
+
+## Build, deploy, dispatch
+
+- **Workspace dependency on `@boocode/server`**: imports `createInferenceRunner`, `createBroker`, `ALL_TOOLS`, `appendMcpTools` from the server's compiled `dist/`. apps/server's `package.json` has an `exports` map with `types` conditions for NodeNext resolution. **apps/server must build FIRST.**
+- Build + deploy: `pnpm -C 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/package.json

@@ -13,12 +13,14 @@
     "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",
-    "@opencode-ai/sdk": "~1.15.0",
     "@fastify/websocket": "^10.0.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@opencode-ai/sdk": "~1.15.0",
     "fastify": "^4.28.1",
     "postgres": "^3.4.4",
     "ws": "^8.18.0",

apps/coder/src/index.ts

@@ -16,7 +16,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';
@@ -42,6 +42,7 @@ import { createOrphanWorktreeReaper } from './services/orphan-worktree-reaper.js
 import { probeAgents } from './services/agent-probe.js';
 import { getProviderSnapshot, persistProbedModels } from './services/provider-snapshot.js';
 import { setPermissionHooks } from './services/permission-waiter.js';
+import { publishAgentStatus } from './services/agent-status-publish.js';
 import { homedir } from 'node:os';
 
 async function main() {
@@ -82,6 +83,21 @@ async function main() {
   // Broker: in-memory pub/sub for session + user channel streaming.
   const broker = createBroker(app.log);
 
+  // agent-status-normalize (#10): the permission hooks carry only taskId +
+  // sessionId, but the tasks row holds the (chat_id, agent) pair the status frame
+  // is keyed on. Resolve it best-effort so a blocked/working status accompanies
+  // every permission_requested/permission_resolved. Returns null when the task
+  // lacks a chat_id or agent (sessionless creators) — we simply skip the status.
+  const resolveChatAgent = async (
+    taskId: string,
+  ): Promise<{ chatId: string; agent: string } | null> => {
+    const [row] = await sql<{ chat_id: string | null; agent: string | null }[]>`
+      SELECT chat_id, agent FROM tasks WHERE id = ${taskId}
+    `;
+    if (!row?.chat_id || !row.agent) return null;
+    return { chatId: row.chat_id, agent: row.agent };
+  };
+
   setPermissionHooks({
     onPrompt: async (prompt) => {
       await sql`
@@ -96,6 +112,18 @@ async function main() {
         ...(prompt.input ? { input: prompt.input } : {}),
         options: prompt.options.map((o) => ({ option_id: o.optionId, label: o.label })),
       } as WsFrame);
+      // #10: agent is blocked on a human decision.
+      const ca = await resolveChatAgent(prompt.taskId).catch(() => null);
+      if (ca) {
+        publishAgentStatus(
+          broker.publishFrame,
+          prompt.sessionId,
+          ca.chatId,
+          ca.agent,
+          'blocked',
+          'permission_request',
+        );
+      }
     },
     onResolved: async (taskId, sessionId) => {
       await sql`
@@ -106,6 +134,18 @@ async function main() {
         task_id: taskId,
         session_id: sessionId,
       } as WsFrame);
+      // #10: human responded — agent resumes work.
+      const ca = await resolveChatAgent(taskId).catch(() => null);
+      if (ca) {
+        publishAgentStatus(
+          broker.publishFrame,
+          sessionId,
+          ca.chatId,
+          ca.agent,
+          'working',
+          'permission_resolved',
+        );
+      }
     },
   });
 

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

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

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

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

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

apps/coder/src/routes/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/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

@@ -261,6 +261,34 @@ CREATE TABLE IF NOT EXISTS checkpoints (
 );
 CREATE INDEX IF NOT EXISTS checkpoints_chat_created_idx ON checkpoints(chat_id, created_at);
 
+-- claude-sdk-sessionstore #9 (Part 1): append-only mirror of Claude Agent SDK
+-- session transcripts. The SDK's SessionStore adapter writes one JSONL line per
+-- entry; PostgresSessionStore (services/backends/claude-session-store.ts) inserts
+-- one row per entry and replays them ORDER BY id on resume. The store is generic
+-- per the SDK's SessionKey (project_key, session_id, subpath) — chat↔session
+-- ownership lives in agent_sessions, not here. subpath '' is the main transcript
+-- (the SDK's undefined subpath maps to '' in the column).
+CREATE TABLE IF NOT EXISTS claude_session_entries (
+  id          BIGSERIAL PRIMARY KEY,
+  project_key TEXT NOT NULL,
+  session_id  TEXT NOT NULL,
+  subpath     TEXT NOT NULL DEFAULT '',   -- '' = main transcript (SDK's undefined subpath maps here)
+  entry       JSONB NOT NULL,
+  created_at  TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp()
+);
+CREATE INDEX IF NOT EXISTS claude_session_entries_key_idx ON claude_session_entries (project_key, session_id, subpath, id);
+
+-- claude-sdk-sessionstore #9 (Part 2): the warm Claude-SDK backend persists its
+-- agent_sessions rows with backend='claude_sdk'. Widen the named CHECK to accept
+-- it. Idempotent: DROP the named constraint (the inline CREATE TABLE check above
+-- carries this explicit name, so DROP IF EXISTS targets it) + re-ADD the widened
+-- list. Re-runs/fresh deploys land on the same final constraint (the table-level
+-- CREATE already includes only the old two values on a fresh DB; this block then
+-- replaces it with the three-value list).
+ALTER TABLE agent_sessions DROP CONSTRAINT IF EXISTS agent_sessions_backend_chk;
+ALTER TABLE agent_sessions ADD CONSTRAINT agent_sessions_backend_chk
+  CHECK (backend IN ('opencode_server', 'acp_warm', 'claude_sdk'));
+
 -- LISTEN/NOTIFY fast path: every tasks INSERT (from any call site — routes,
 -- new_task tool, arena, MCP server) fires pg_notify('tasks_new') in the same
 -- transaction, so the dispatcher reacts immediately instead of waiting for the

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

@@ -0,0 +1,83 @@
+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-dispatch.ts

@@ -23,7 +23,7 @@ import {
   type ClientSideConnection as ConnectionType,
 } from '@agentclientprotocol/sdk';
 import type { Broker } from '@boocode/server/broker';
-import type { WsFrame } from '@boocode/server/ws-frames';
+import type { WsFrame } from '@boocode/contracts/ws-frames';
 import { spawn } from 'node:child_process';
 import { findThoughtLevelConfigId } from './acp-derive.js';
 import { resolveLaunchSpec } from './acp-spawn.js';

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

@@ -13,7 +13,7 @@ import type { AcpToolSnapshot } from './acp-tool-snapshot.js';
 import type { AgentCommand } from './provider-types.js';
 
 /** Backend transport kind. Mirrors `agent_sessions.backend` CHECK in schema.sql. */
-export type AgentBackendKind = 'opencode_server' | 'acp_warm';
+export type AgentBackendKind = 'opencode_server' | 'acp_warm' | 'claude_sdk';
 
 /**
  * Normalized, transport-agnostic events a backend emits during a turn (§2).
@@ -82,6 +82,12 @@ export interface PromptCtx {
 export interface TurnResult {
   ok: boolean;
   error?: string;
+  // Optional context-window telemetry (claude SDK): the model's reported window
+  // (ctxMax, 1M-aware) and the peak request input ≈ current fill (ctxUsed). The
+  // dispatcher writes these onto the assistant message so the ContextBar renders a
+  // real fill for the turn. Omitted by backends that don't report a window.
+  ctxUsed?: number;
+  ctxMax?: number;
 }
 
 /**

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

apps/coder/src/services/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';
@@ -16,8 +16,12 @@ import { snapshotToWireToolCall, type AcpToolSnapshot } from './acp-tool-snapsho
 import { agentPool, OPENCODE_POOL_KEY } from './agent-pool.js';
 import { OpenCodeServerBackend } from './backends/opencode-server.js';
 import { WarmAcpBackend } from './backends/warm-acp.js';
+import { ClaudeSdkBackend } from './backends/claude-sdk.js';
 import { shouldUseWarmBackend } from './backends/warm-acp-routing.js';
+import { shouldUseClaudeSdk } from './backends/claude-sdk-routing.js';
 import type { AgentBackend, AgentEvent } from './agent-backend.js';
+import { publishAgentStatus } from './agent-status-publish.js';
+import type { AgentStatus } from './normalize-agent-status.js';
 
 interface InferenceRunner {
   enqueue: (sessionId: string, chatId: string, assistantId: string, user: string) => void;
@@ -64,6 +68,21 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
     return task.session_id ?? `task:${task.id}`;
   }
 
+  // agent-status-normalize (#10): publish a normalized per-(chat,agent) status on
+  // the session channel. Every external-agent path (warm-acp / opencode / claude-sdk /
+  // pty one-shot) reports `working` at turn start, `idle` on clean completion, and
+  // `error` on the failure path through this single helper so the four paths stay
+  // DRY and consistent. Best-effort — publishAgentStatus never throws.
+  function emitAgentStatus(
+    sessionId: string,
+    chatId: string,
+    agent: string,
+    status: AgentStatus,
+    reason: string,
+  ): void {
+    publishAgentStatus(broker.publishFrame, sessionId, chatId, agent, status, reason);
+  }
+
   async function poll(): Promise<void> {
     // `polling` serializes poll() execution itself (timer + NOTIFY can fire
     // concurrently) so we never double-select a task. It does NOT serialize task
@@ -131,6 +150,12 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         // existing one-shot worktree-per-task ACP/PTY path untouched.
         if (task.agent === 'opencode') {
           await runOpenCodeServerTask(task, agentRow.install_path);
+        } else if (shouldUseClaudeSdk(task)) {
+          // claude-sdk-sessionstore #9 (Part 2): env-flagged (CLAUDE_SDK_BACKEND, default
+          // OFF) warm Claude-SDK backend for chat-tab claude tasks. When the flag is off
+          // (production default) this predicate returns false and claude falls through to
+          // the UNCHANGED one-shot PTY runExternalAgent path below.
+          await runClaudeSdkTask(task, agentRow.install_path);
         } else if (shouldUseWarmBackend(task)) {
           await runWarmAcpTask(task, agentRow.install_path);
         } else {
@@ -188,8 +213,8 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         RETURNING id
       `;
       const [assistantMsg] = await sql<{ id: string }[]>`
-        INSERT INTO messages (session_id, chat_id, role, content, status, created_at)
-        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', clock_timestamp())
+        INSERT INTO messages (session_id, chat_id, role, content, status, model, created_at)
+        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', ${task.model}, clock_timestamp())
         RETURNING id
       `;
       const assistantId = assistantMsg!.id;
@@ -290,6 +315,11 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
     // Create an abort controller for this task
     const ac = new AbortController();
 
+    // #10: hoisted above the try so the catch block can report `error` status with
+    // the (chat, agent) key. Empty until resolved below; guarded before use.
+    let sessionId = '';
+    let chatId = '';
+
     try {
       // Mark running
       await sql`
@@ -298,9 +328,6 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         WHERE id = ${taskId}
       `;
 
-      let sessionId: string;
-      let chatId: string;
-
       if (task.session_id) {
         sessionId = task.session_id;
         const chats = await sql<{ id: string }[]>`
@@ -353,8 +380,8 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
       let acpReasoning = '';
 
       const [assistantMsg] = await sql<{ id: string }[]>`
-        INSERT INTO messages (session_id, chat_id, role, content, status, created_at)
-        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', clock_timestamp())
+        INSERT INTO messages (session_id, chat_id, role, content, status, model, created_at)
+        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', ${task.model}, clock_timestamp())
         RETURNING id
       `;
       const assistantId = assistantMsg!.id;
@@ -376,6 +403,9 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         role: 'assistant',
       } as WsFrame);
 
+      // #10: external-agent turn begins.
+      emitAgentStatus(sessionId, chatId, agent, 'working', 'turn_start');
+
       const manifestCommands = getManifestCommands(agent);
       if (manifestCommands.length > 0) {
         setTaskCommands(taskId, manifestCommands);
@@ -506,6 +536,7 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         type: 'message_complete',
         message_id: assistantId,
         chat_id: chatId,
+        model: task.model,
       } as WsFrame);
 
       if (stopping) {
@@ -550,6 +581,8 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         WHERE id = ${taskId}
       `;
       log.info({ taskId, agent, costTokens: extCostTokens }, 'dispatcher: task completed (external)');
+      // #10: external-agent turn completed cleanly.
+      emitAgentStatus(sessionId, chatId, agent, 'idle', 'turn_complete');
       clearTaskCommands(taskId);
 
     } catch (err) {
@@ -562,6 +595,11 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         WHERE id = ${taskId}
       `.catch(() => {});
 
+      // #10: external-agent turn failed/crashed. chatId may be unbound if the throw
+      // preceded its assignment — guard so the status publish never masks the real
+      // error.
+      if (chatId) emitAgentStatus(sessionId, chatId, agent, 'error', 'failed');
+
       // Best-effort cleanup
       await cleanupWorktree(projectPath, taskId);
       clearTaskCommands(taskId);
@@ -616,6 +654,10 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
 
     const ac = new AbortController();
 
+    // #10: hoisted so the catch can report `error` with the (chat, agent) key.
+    let sessionId = '';
+    let chatId = '';
+
     try {
       // execution_path = 'acp' — the schema CHECK has no 'opencode_server' value
       // (schema is frozen at Phase 0); the warm-vs-one-shot distinction lives in
@@ -632,8 +674,6 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
       // it directly. Session-less creators (arena, MCP, new_task, generic
       // /api/tasks) leave it null; fall back to resolving/creating a real chat so
       // ensureSession never receives a degenerate (null, agent) key.
-      let sessionId: string;
-      let chatId: string;
       if (task.chat_id && task.session_id) {
         sessionId = task.session_id;
         chatId = task.chat_id;
@@ -684,8 +724,8 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
       log.info({ taskId, worktreePath }, 'dispatcher: session worktree ready');
 
       const [assistantMsg] = await sql<{ id: string }[]>`
-        INSERT INTO messages (session_id, chat_id, role, content, status, created_at)
-        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', clock_timestamp())
+        INSERT INTO messages (session_id, chat_id, role, content, status, model, created_at)
+        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', ${task.model}, clock_timestamp())
         RETURNING id
       `;
       const assistantId = assistantMsg!.id;
@@ -706,6 +746,9 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         role: 'assistant',
       } as WsFrame);
 
+      // #10: opencode-server turn begins.
+      emitAgentStatus(sessionId, chatId, agent, 'working', 'turn_start');
+
       const manifestCommands = getManifestCommands(agent);
       if (manifestCommands.length > 0) {
         setTaskCommands(taskId, manifestCommands);
@@ -822,6 +865,7 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         type: 'message_complete',
         message_id: assistantId,
         chat_id: chatId,
+        model: task.model,
       } as WsFrame);
 
       if (stopping) {
@@ -865,6 +909,14 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         WHERE id = ${taskId}
       `;
       log.info({ taskId, agent, finalState, costTokens: extCostTokens }, 'dispatcher: task finished (opencode server)');
+      // #10: clean completion → idle; backend-reported failure → error.
+      emitAgentStatus(
+        sessionId,
+        chatId,
+        agent,
+        result.ok ? 'idle' : 'error',
+        result.ok ? 'turn_complete' : 'failed',
+      );
       clearTaskCommands(taskId);
     } catch (err) {
       const errMsg = err instanceof Error ? err.message : String(err);
@@ -874,6 +926,8 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         SET state = 'failed', ended_at = clock_timestamp(), output_summary = ${errMsg.slice(0, 500)}
         WHERE id = ${taskId}
       `.catch(() => {});
+      // #10: turn crashed.
+      if (chatId) emitAgentStatus(sessionId, chatId, agent, 'error', 'crashed');
       clearTaskCommands(taskId);
       // No worktree cleanup (persistent); backend stays warm for the next turn.
     }
@@ -952,8 +1006,8 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
       log.info({ taskId, worktreePath }, 'dispatcher: session worktree ready (warm ACP)');
 
       const [assistantMsg] = await sql<{ id: string }[]>`
-        INSERT INTO messages (session_id, chat_id, role, content, status, created_at)
-        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', clock_timestamp())
+        INSERT INTO messages (session_id, chat_id, role, content, status, model, created_at)
+        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', ${task.model}, clock_timestamp())
         RETURNING id
       `;
       const assistantId = assistantMsg!.id;
@@ -974,6 +1028,9 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         role: 'assistant',
       } as WsFrame);
 
+      // #10: warm-ACP turn begins.
+      emitAgentStatus(sessionId, chatId, agent, 'working', 'turn_start');
+
       const manifestCommands = getManifestCommands(agent);
       if (manifestCommands.length > 0) {
         setTaskCommands(taskId, manifestCommands);
@@ -1073,6 +1130,7 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         type: 'message_complete',
         message_id: assistantId,
         chat_id: chatId,
+        model: task.model,
       } as WsFrame);
 
       if (stopping) {
@@ -1115,6 +1173,14 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         WHERE id = ${taskId}
       `;
       log.info({ taskId, agent, finalState }, 'dispatcher: task finished (warm ACP)');
+      // #10: clean completion → idle; backend-reported failure → error.
+      emitAgentStatus(
+        sessionId,
+        chatId,
+        agent,
+        result.ok ? 'idle' : 'error',
+        result.ok ? 'turn_complete' : 'failed',
+      );
       clearTaskCommands(taskId);
     } catch (err) {
       const errMsg = err instanceof Error ? err.message : String(err);
@@ -1124,6 +1190,266 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         SET state = 'failed', ended_at = clock_timestamp(), output_summary = ${errMsg.slice(0, 500)}
         WHERE id = ${taskId}
       `.catch(() => {});
+      // #10: turn crashed.
+      emitAgentStatus(sessionId, chatId, agent, 'error', 'crashed');
+      clearTaskCommands(taskId);
+      // No worktree cleanup (persistent); backend stays warm for the next turn.
+    }
+  }
+
+  // ─── Path B (claude SDK): warm Claude-SDK backend (v2.6 #9 Part 2) ───────────
+
+  // Claude-SDK backends are per (chat, agent) — each owns ONE persistent query()
+  // generator driven in streaming-input mode. Pool key = chatId (secondary = agent),
+  // mirroring agent_sessions' (chat_id, agent) PK + the warm-ACP pooling.
+  function getClaudeSdkBackend(chatId: string, agent: string, installPath: string | null): ClaudeSdkBackend {
+    let backend = agentPool.get(chatId, agent);
+    if (!backend) {
+      backend = new ClaudeSdkBackend({ sql, log, chatId, agent, installPath });
+      agentPool.register(chatId, agent, backend);
+    }
+    return backend as ClaudeSdkBackend;
+  }
+
+  async function runClaudeSdkTask(
+    task: {
+      id: string;
+      project_id: string;
+      input: string;
+      agent: string | null;
+      model: string | null;
+      mode_id: string | null;
+      thinking_option_id: string | null;
+      session_id: string | null;
+      chat_id: string | null;
+    },
+    installPath: string | null,
+  ): Promise<void> {
+    const taskId = task.id;
+    const agent = task.agent!;
+    // shouldUseClaudeSdk guarantees both non-null before we get here.
+    const sessionId = task.session_id!;
+    const chatId = task.chat_id!;
+    log.info({ taskId, agent, chatId }, 'dispatcher: starting task (path B — claude SDK)');
+
+    const [project] = await sql<{ path: string | null }[]>`
+      SELECT path FROM projects WHERE id = ${task.project_id}
+    `;
+    const projectPath = project?.path;
+    if (!projectPath) {
+      await sql`
+        UPDATE tasks
+        SET state = 'failed', ended_at = clock_timestamp(), output_summary = 'Project has no path — cannot create worktree'
+        WHERE id = ${taskId}
+      `;
+      return;
+    }
+
+    const ac = new AbortController();
+
+    try {
+      await sql`
+        UPDATE tasks
+        SET state = 'running', started_at = clock_timestamp(), execution_path = 'acp'
+        WHERE id = ${taskId}
+      `;
+
+      // Persistent, session-keyed worktree (shared across turns + agents; NOT torn
+      // down per turn — Phase 3 reaps it). Same as the opencode/warm-ACP paths so a
+      // chat that switches agents shares one worktree.
+      const { worktreeId, worktreePath, baseCommit } = await ensureSessionWorktree(sql, projectPath, sessionId, {
+        signal: ac.signal,
+      });
+      log.info({ taskId, worktreePath }, 'dispatcher: session worktree ready (claude SDK)');
+
+      const [assistantMsg] = await sql<{ id: string }[]>`
+        INSERT INTO messages (session_id, chat_id, role, content, status, model, created_at)
+        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', ${task.model}, clock_timestamp())
+        RETURNING id
+      `;
+      const assistantId = assistantMsg!.id;
+
+      // write-edit-robustness #4: pre-turn checkpoint of the persistent session
+      // worktree (best-effort; never breaks dispatch).
+      await createCheckpoint(
+        sql,
+        { chatId, sessionId, worktreeId, worktreePath, messageId: assistantId },
+        { signal: ac.signal, log },
+      ).catch(() => null);
+
+      broker.publishFrame(sessionId, {
+        type: 'message_started',
+        message_id: assistantId,
+        chat_id: chatId,
+        role: 'assistant',
+      } as WsFrame);
+
+      // #10: claude-SDK turn begins.
+      emitAgentStatus(sessionId, chatId, agent, 'working', 'turn_start');
+
+      const manifestCommands = getManifestCommands(agent);
+      if (manifestCommands.length > 0) {
+        setTaskCommands(taskId, manifestCommands);
+        broker.publishFrame(sessionId, {
+          type: 'agent_commands',
+          task_id: taskId,
+          session_id: sessionId,
+          commands: manifestCommands,
+        } as WsFrame);
+      }
+
+      // Accumulate the turn's stream for persistence + the final message content.
+      const textChunks: string[] = [];
+      const reasoningChunks: string[] = [];
+      const toolSnaps = new Map<string, AcpToolSnapshot>();
+
+      // Map transport-agnostic AgentEvents → the SAME WS frames the warm-ACP /
+      // opencode paths emit. This boundary attaches message_id/chat_id.
+      const onEvent = (e: AgentEvent): void => {
+        switch (e.type) {
+          case 'text':
+            textChunks.push(e.text);
+            broker.publishFrame(sessionId, {
+              type: 'delta',
+              message_id: assistantId,
+              chat_id: chatId,
+              content: e.text,
+            } as WsFrame);
+            break;
+          case 'reasoning':
+            reasoningChunks.push(e.text);
+            broker.publishFrame(sessionId, {
+              type: 'reasoning_delta',
+              message_id: assistantId,
+              chat_id: chatId,
+              content: e.text,
+            } as WsFrame);
+            break;
+          case 'tool_call':
+          case 'tool_update':
+            toolSnaps.set(e.toolCall.toolCallId, e.toolCall);
+            broker.publishFrame(sessionId, {
+              type: 'tool_call',
+              message_id: assistantId,
+              chat_id: chatId,
+              tool_call: snapshotToWireToolCall(e.toolCall),
+            } as WsFrame);
+            break;
+          case 'commands':
+            if (e.commands.length > 0) {
+              setTaskCommands(taskId, e.commands);
+              broker.publishFrame(sessionId, {
+                type: 'agent_commands',
+                task_id: taskId,
+                session_id: sessionId,
+                commands: e.commands,
+              } as WsFrame);
+            }
+            break;
+        }
+      };
+
+      const model = task.model ?? undefined;
+      const backend = getClaudeSdkBackend(chatId, agent, installPath);
+      const handle = await backend.ensureSession(sessionId, {
+        agent,
+        model: model ?? '',
+        chatId,
+        worktreePath,
+        worktreeId,
+        projectId: task.project_id,
+      });
+      const result = await backend.prompt(handle, task.input, {
+        worktreePath,
+        model: model ?? '',
+        signal: ac.signal,
+        onEvent,
+        taskId,
+        modeId: task.mode_id ?? undefined,
+      });
+      // Phase 3: keep the pooled (chat,agent) backend warm across the turn.
+      agentPool.touch(chatId, agent);
+
+      const assistantContent = textChunks.join('').slice(0, 50_000);
+      const reasoningText = reasoningChunks.join('').slice(0, 200_000);
+      const outputSummary = (result.ok ? textChunks.join('') : result.error ?? 'claude SDK turn failed').slice(0, 500);
+
+      await persistExternalAgentTurn(sql, assistantId, [...toolSnaps.values()], reasoningText);
+
+      // ctx_used/ctx_max from the SDK result (1M-aware) → the assistant message, so
+      // the ContextBar renders a real context-window fill for claude.
+      await sql`
+        UPDATE messages
+        SET content = ${assistantContent}, status = 'complete', finished_at = clock_timestamp(),
+            ctx_used = ${result.ctxUsed ?? null}, ctx_max = ${result.ctxMax ?? null}
+        WHERE id = ${assistantId}
+      `;
+      broker.publishFrame(sessionId, {
+        type: 'message_complete',
+        message_id: assistantId,
+        chat_id: chatId,
+        model: task.model,
+      } as WsFrame);
+
+      if (stopping) {
+        await sql`UPDATE tasks SET state = 'cancelled', ended_at = clock_timestamp() WHERE id = ${taskId}`;
+        return; // worktree persists (no cleanup); backend stays warm
+      }
+
+      // Diff the persistent worktree against its captured baseline and SUPERSEDE
+      // the session's prior pending row (latest-wins) — identical to opencode/ACP.
+      const diff = await diffWorktree(worktreePath, projectPath, {
+        signal: ac.signal,
+        baseRef: baseCommit ?? 'HEAD',
+      });
+      if (diff) {
+        await sql`
+          DELETE FROM pending_changes WHERE session_id = ${sessionId} AND status = 'pending'
+        `;
+        await sql`
+          INSERT INTO pending_changes (session_id, task_id, file_path, operation, diff, agent)
+          VALUES (${sessionId}, ${taskId}, ${projectPath}, 'edit', ${diff}, ${agent})
+        `;
+        log.info({ taskId, diffLength: diff.length }, 'dispatcher: diff superseded prior pending change (claude SDK)');
+      } else {
+        log.info({ taskId }, 'dispatcher: no changes detected in session worktree (claude SDK)');
+      }
+
+      // NO worktree cleanup — persistent (Phase 3 reaps it). Backend stays warm.
+
+      const [extCostRow] = await sql<{ total: number | null }[]>`
+        SELECT SUM(tokens_used)::int AS total
+        FROM messages
+        WHERE session_id = ${sessionId} AND tokens_used IS NOT NULL
+      `;
+      const extCostTokens = extCostRow?.total ?? null;
+
+      const finalState = result.ok ? 'completed' : 'failed';
+      await sql`
+        UPDATE tasks
+        SET state = ${finalState}, ended_at = clock_timestamp(), output_summary = ${outputSummary}, cost_tokens = ${extCostTokens}
+        WHERE id = ${taskId}
+      `;
+      log.info({ taskId, agent, finalState }, 'dispatcher: task finished (claude SDK)');
+      // #10: clean completion → idle; backend-reported failure → error.
+      emitAgentStatus(
+        sessionId,
+        chatId,
+        agent,
+        result.ok ? 'idle' : 'error',
+        result.ok ? 'turn_complete' : 'failed',
+      );
+      clearTaskCommands(taskId);
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      log.error({ taskId, agent, err: errMsg }, 'dispatcher: claude SDK error');
+      await sql`
+        UPDATE tasks
+        SET state = 'failed', ended_at = clock_timestamp(), output_summary = ${errMsg.slice(0, 500)}
+        WHERE id = ${taskId}
+      `.catch(() => {});
+      // #10: turn crashed.
+      emitAgentStatus(sessionId, chatId, agent, 'error', 'crashed');
       clearTaskCommands(taskId);
       // No worktree cleanup (persistent); backend stays warm for the next turn.
     }

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

@@ -0,0 +1,92 @@
+/**
+ * normalize-agent-status (#10) — clean-room vendor-event → bucket mapping.
+ *
+ * Different coding agents (claude, opencode, codex/gemini, goose, qwen) emit
+ * lifecycle hook events under inconsistent names: PascalCase (`SessionStart`),
+ * snake_case (`session_start`), camelCase (`sessionStart`), and a handful of
+ * provider-specific approval events (`exec_approval_request`). This module
+ * collapses every known event name into one of three coarse signals:
+ *
+ *   working  — the agent is actively progressing a turn
+ *   blocked  — the agent is waiting on a human (permission / approval / question)
+ *   done     — the turn / session ended cleanly
+ *
+ * `null` is returned for anything unrecognized so callers can ignore noise.
+ *
+ * Built now for the scoped status-publish, but specifically shaped for reuse by
+ * the documented config-injection follow-on: a future notify-hook injected into
+ * each agent's native config will POST the RAW vendor event name to a BooCoder
+ * endpoint, which runs this helper to derive the normalized status. The names
+ * below are facts about each agent's hook surface — not copied vendor code.
+ */
+
+export type AgentStatus = 'working' | 'blocked' | 'idle' | 'error';
+
+/** 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/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 const ProviderOverrideSchema = z.object({
-  extends: z.enum(['acp']).optional(), // v2.3: only 'acp' for custom; built-ins omit extends
-  label: z.string().min(1).optional(),
-  description: z.string().optional(),
-  command: z.array(z.string().min(1)).min(1).optional(), // [binary, ...args]
-  env: z.record(z.string()).optional(),
-  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>;
+export {
+  ProviderOverrideSchema,
+  CoderProvidersFileSchema,
+  ProviderConfigPatchSchema,
+  type ProviderOverride,
+  type CoderProvidersFile,
+  type ProviderConfigPatch,
+};
 
 /**
  * Shallow per-id merge (design.md §6.2 / Paseo `patchConfig`). Each key in

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

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

apps/coder/src/services/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 {
-  id: string;
-  label: string;
-  description?: string;
-  /** Auto-approve tool permissions when this mode is selected. */
-  isUnattended?: boolean;
-}
-
-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;
-}
+export type {
+  ProviderMode,
+  ThinkingOption,
+  ProviderModel,
+  ProviderSnapshotStatus,
+  AgentCommand,
+  ProviderSnapshotEntry,
+} from '@boocode/contracts/provider-snapshot';

apps/coder/src/services/worktrees.ts

@@ -8,6 +8,7 @@
  */
 import type { Sql } from '../db.js';
 import { hostExec } from './host-exec.js';
+import type { WorktreeRiskReport } from '@boocode/contracts/worktree-risk';
 
 export const WORKTREE_BASE = '/tmp/booworktrees';
 
@@ -379,22 +380,8 @@ export async function rebaselineWorktreeAfterApply(
 }
 
 // ─── Session-delete work-loss guard ─────────────────────────────────────────
-
-/**
- * Risk report for a single worktree, returned by checkWorktreeWorkAtRisk.
- * `atRisk` is the gate the server reads before allowing a session delete.
- * A git error never silently passes — it forces `atRisk` true and surfaces
- * the message in `error` (fail-closed).
- */
-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
-}
+// WorktreeRiskReport single-sourced in @boocode/contracts — edit the package, not here.
+export type { WorktreeRiskReport };
 
 /**
  * Resolve the project's default branch as a git-usable ref (e.g. "origin/main").
@@ -448,7 +435,7 @@ async function detectDefaultBranchRef(
 export async function checkWorktreeWorkAtRisk(
   worktreePath: string,
   opts?: { signal?: AbortSignal },
-): Promise<RiskReport> {
+): 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`,

apps/coder/vitest.config.ts

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

apps/coder/web/package.json

@@ -10,6 +10,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
+    "@boocode/contracts": "workspace:*",
     "lucide-react": "^1.16.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",

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

@@ -1,5 +1,22 @@
 // Minimal types for the BooCoder frontend.
 // Shared DB entities (same schema as BooChat).
+//
+// WS wire contracts are single-sourced from @boocode/contracts (the canonical
+// Zod-backed schema). The DB entity types below (Project/Session/Chat/Message/
+// ToolCall/ToolResult/PendingChange) are an intentional minimal SPA-local subset
+// and are NOT cross-app contracts — they stay defined here.
+
+import type { WsFrame } from '@boocode/contracts/ws-frames';
+
+// Re-export the canonical WebSocket frame union (single source of truth). The
+// coder backend publishes the full frame set; this SPA's reducer handles the
+// subset it renders and ignores the rest.
+export type { WsFrame };
+
+// The error frame's `reason`, single-sourced from the canonical schema's
+// frame-level reason enum (derived from WsFrame so it cannot drift from the
+// wire). Distinct from message-metadata's ErrorReason, which is a different set.
+export type ErrorReason = NonNullable<Extract<WsFrame, { type: 'error' }>['reason']>;
 
 export interface Project {
   id: string;
@@ -39,7 +56,9 @@ export interface ToolResult {
   tool_call_id: string;
   output: unknown;
   truncated?: boolean;
-  error?: boolean;
+  // Canonical wire shape: the failure message string (present only on error),
+  // not a boolean. ToolResultBubble treats it as truthy → renders error styling.
+  error?: string;
 }
 
 // Batch 9.7: ask_user_input shapes. The tool_call.args is { questions: AskUserQuestion[] }
@@ -96,15 +115,3 @@ export interface PendingChange {
   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/DiffPane.tsx

@@ -5,10 +5,9 @@ import { api } from '@/api/client';
 
 interface Props {
   sessionId: string;
-  onPendingChange: (cb: (change: PendingChange) => void) => () => void;
 }
 
-export function DiffPane({ sessionId, onPendingChange }: Props) {
+export function DiffPane({ sessionId }: Props) {
   const [changes, setChanges] = useState<PendingChange[]>([]);
   const [loading, setLoading] = useState(true);
   const [expandedId, setExpandedId] = useState<string | null>(null);
@@ -24,27 +23,13 @@ export function DiffPane({ sessionId, onPendingChange }: Props) {
     }
   }, [sessionId]);
 
-  // Initial load
+  // Initial load. Pending changes are delivered over HTTP (list + apply/reject/
+  // rewind below); there is no WS pending-change frame, so the list refreshes on
+  // mount, on the Refresh button, and optimistically as the user acts on it.
   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');
 

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

@@ -1,5 +1,5 @@
-import { useEffect, useRef, useState, useCallback } from 'react';
-import type { Message, WsFrame, PendingChange } from '@/api/types';
+import { useEffect, useRef, useState } from 'react';
+import type { Message, WsFrame } from '@/api/types';
 
 interface State {
   messages: Message[];
@@ -10,7 +10,9 @@ interface State {
 function applyFrame(state: State, frame: WsFrame): State {
   switch (frame.type) {
     case 'snapshot': {
-      return { ...state, messages: frame.messages };
+      // Canonical SnapshotFrame.messages is opaque (z.array(z.unknown())); the
+      // coder backend sends Message-shaped rows, so cast to the SPA's local type.
+      return { ...state, messages: frame.messages as Message[] };
     }
     case 'message_started': {
       const exists = state.messages.some((m) => m.id === frame.message_id);
@@ -18,7 +20,7 @@ function applyFrame(state: State, frame: WsFrame): State {
       const newMsg: Message = {
         id: frame.message_id,
         session_id: '',
-        chat_id: frame.chat_id,
+        chat_id: frame.chat_id ?? '',
         role: frame.role,
         content: '',
         kind: 'message',
@@ -72,7 +74,7 @@ function applyFrame(state: State, frame: WsFrame): State {
       const newMsg: Message = {
         id: frame.tool_message_id,
         session_id: '',
-        chat_id: frame.chat_id,
+        chat_id: frame.chat_id ?? '',
         role: 'tool',
         content: '',
         kind: 'message',
@@ -119,9 +121,12 @@ function applyFrame(state: State, frame: WsFrame): State {
         : 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
+    default:
+      // The canonical WsFrame carries the full set of frames the coder backend
+      // can publish; this SPA only renders the subset handled above and safely
+      // ignores the rest (reasoning_delta, usage, permission_*, agent_*, and the
+      // per-user sidebar frames). pending_change_* frames have no publisher —
+      // pending changes are delivered over HTTP, so there is nothing to handle.
       return state;
   }
 }
@@ -134,14 +139,11 @@ interface SessionStreamResult {
   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;
@@ -172,13 +174,6 @@ export function useSessionStream(sessionId: string | undefined): SessionStreamRe
           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));
       };
 
@@ -213,18 +208,10 @@ export function useSessionStream(sessionId: string | undefined): SessionStreamRe
 
   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/pages/Session.tsx

@@ -14,8 +14,7 @@ export function Session() {
   const [chat, setChat] = useState<Chat | null>(null);
   const [loading, setLoading] = useState(true);
 
-  const { messages, connected, isStreaming, onPendingChange } =
-    useSessionStream(sessionId);
+  const { messages, connected, isStreaming } = useSessionStream(sessionId);
 
   // Get or create a chat for this session
   useEffect(() => {
@@ -78,9 +77,7 @@ export function Session() {
           connected={connected}
         />
       }
-      diffPane={
-        <DiffPane sessionId={sessionId} onPendingChange={onPendingChange} />
-      }
+      diffPane={<DiffPane sessionId={sessionId} />}
     />
   );
 }

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/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

@@ -441,7 +441,7 @@ export function registerChatRoutes(
       const rows = await sql<Message[]>`
         SELECT id, session_id, chat_id, role, content, kind, tool_calls, tool_results, status, last_seq,
                tokens_used, ctx_used, ctx_max, started_at, finished_at, created_at, metadata,
-               summary, tail_start_id, compacted_at
+               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

@@ -118,7 +118,7 @@ export function registerMessageRoutes(
       const rows = await sql<Message[]>`
         SELECT id, session_id, chat_id, role, content, kind, tool_calls, tool_results, status, last_seq,
                tokens_used, ctx_used, ctx_max, started_at, finished_at, created_at, metadata,
-               summary, tail_start_id, compacted_at
+               summary, tail_start_id, compacted_at, model
         FROM messages_with_parts
         WHERE session_id = ${req.params.id}
         ORDER BY created_at ASC, id ASC

apps/server/src/routes/settings.ts

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

apps/server/src/routes/ws.ts

@@ -27,7 +27,7 @@ export function registerWebSocket(
       const messages = await sql<Message[]>`
         SELECT id, session_id, chat_id, role, content, kind, tool_calls, tool_results, status, last_seq,
                tokens_used, ctx_used, ctx_max, started_at, finished_at, created_at, metadata,
-               summary, tail_start_id, compacted_at
+               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

@@ -107,6 +107,11 @@ END $$;
 -- a single jsonb object {tool_call_id, output, truncated, error?}.
 -- reasoning_parts is consumed by the inference history fetch (payload.ts)
 -- for v1.13.1-C reasoning round-tripping. Not surfaced in external APIs.
+-- model-attribution: which model produced an assistant message (NULL for
+-- user/system rows and pre-existing messages). Stamped at finalize (BooChat /
+-- native coder) and at assistant-row creation (external coder dispatcher).
+ALTER TABLE messages ADD COLUMN IF NOT EXISTS model TEXT;
+
 CREATE OR REPLACE VIEW messages_with_parts AS
 SELECT
   m.id, m.session_id, m.chat_id, m.role, m.content, m.kind, m.status,
@@ -122,7 +127,10 @@ SELECT
     ORDER BY p.sequence LIMIT 1) AS tool_results,
   (SELECT jsonb_agg(p.payload ORDER BY p.sequence)
      FROM message_parts p
-    WHERE p.message_id = m.id AND p.kind = 'reasoning' AND p.hidden_at IS NULL) AS reasoning_parts
+    WHERE p.message_id = m.id AND p.kind = 'reasoning' AND p.hidden_at IS NULL) AS reasoning_parts,
+  -- NEW columns MUST be appended at the end: CREATE OR REPLACE VIEW can't
+  -- reorder/rename existing columns (42P16). m.model added last.
+  m.model
 FROM messages m;
 
 -- v1.13.20: drop legacy tool_calls/tool_results columns. Reads have routed

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__/ws-frames.test.ts

@@ -1,146 +1,13 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import {
-  WsFrameSchema,
-  KNOWN_FRAME_TYPES,
   type WsFrame,
-} from '../../types/ws-frames.js';
+} from '@boocode/contracts/ws-frames';
 import { createBroker } from '../broker.js';
 
 const VALID_UUID_A = '00000000-0000-0000-0000-000000000001';
 const VALID_UUID_B = '00000000-0000-0000-0000-000000000002';
-const VALID_UUID_C = '00000000-0000-0000-0000-000000000003';
 const VALID_TIMESTAMP = '2026-05-22T14:30:00.000Z';
 
-describe('WsFrameSchema (v1.13.11-a)', () => {
-  it('accepts a well-formed chat_status frame', () => {
-    const result = WsFrameSchema.safeParse({
-      type: 'chat_status',
-      chat_id: VALID_UUID_A,
-      status: 'streaming',
-      at: VALID_TIMESTAMP,
-    });
-    expect(result.success).toBe(true);
-  });
-
-  it('rejects an unknown frame type', () => {
-    const result = WsFrameSchema.safeParse({
-      type: 'cosmic_ray_strike',
-      chat_id: VALID_UUID_A,
-    });
-    expect(result.success).toBe(false);
-  });
-
-  it('rejects a chat_status frame with invalid status enum', () => {
-    // v1.12.1 dropped the legacy 'working' status. Any frame still emitting it
-    // should fail validation — that's a drift catcher.
-    const result = WsFrameSchema.safeParse({
-      type: 'chat_status',
-      chat_id: VALID_UUID_A,
-      status: 'working',
-      at: VALID_TIMESTAMP,
-    });
-    expect(result.success).toBe(false);
-  });
-
-  it('rejects a UUID field with a non-UUID string', () => {
-    const result = WsFrameSchema.safeParse({
-      type: 'chat_status',
-      chat_id: 'not-a-uuid',
-      status: 'idle',
-      at: VALID_TIMESTAMP,
-    });
-    expect(result.success).toBe(false);
-  });
-
-  it('rejects negative token counts in usage frame', () => {
-    const result = WsFrameSchema.safeParse({
-      type: 'usage',
-      message_id: VALID_UUID_A,
-      chat_id: VALID_UUID_B,
-      completion_tokens: -1,
-      ctx_used: 100,
-      ctx_max: 1000,
-    });
-    expect(result.success).toBe(false);
-  });
-
-  it('accepts a usage frame with nullable token counts (pre-v1.13.7 history)', () => {
-    const result = WsFrameSchema.safeParse({
-      type: 'usage',
-      message_id: VALID_UUID_A,
-      chat_id: VALID_UUID_B,
-      completion_tokens: null,
-      ctx_used: null,
-      ctx_max: null,
-    });
-    expect(result.success).toBe(true);
-  });
-
-  it('accepts a tool_result frame with non-UUID tool_call_id (model-emitted)', () => {
-    // Model-emitted tool_call_ids look like "call_abc123", not UUIDs.
-    const result = WsFrameSchema.safeParse({
-      type: 'tool_result',
-      tool_message_id: VALID_UUID_A,
-      chat_id: VALID_UUID_B,
-      tool_call_id: 'call_abc123',
-      output: { whatever: true },
-      truncated: false,
-    });
-    expect(result.success).toBe(true);
-  });
-
-  it('accepts a compacted frame', () => {
-    const result = WsFrameSchema.safeParse({
-      type: 'compacted',
-      session_id: VALID_UUID_A,
-      chat_id: VALID_UUID_B,
-      summary_message_id: VALID_UUID_C,
-    });
-    expect(result.success).toBe(true);
-  });
-
-  it('accepts a session_workspace_updated frame', () => {
-    const result = WsFrameSchema.safeParse({
-      type: 'session_workspace_updated',
-      session_id: VALID_UUID_A,
-      workspace_panes: [{ id: 'p1', kind: 'chat', chatIds: [], activeChatIdx: 0 }],
-    });
-    expect(result.success).toBe(true);
-  });
-
-  it('every KNOWN_FRAME_TYPES entry has a discriminated branch', () => {
-    // Probe each known type by attempting a minimal valid construction.
-    // Failure here means the union and the KNOWN_FRAME_TYPES list drifted.
-    for (const type of KNOWN_FRAME_TYPES) {
-      const probe = WsFrameSchema.safeParse({ type, __dummy__: true });
-      // We expect FAILURE on every type because we're missing required fields,
-      // but the failure must be ABOUT the missing fields, not about an unknown
-      // type. A "Invalid discriminator value" error means the type isn't in
-      // the union — that's a drift.
-      if (probe.success) continue;
-      const issues = probe.error.issues;
-      const hasInvalidDiscriminator = issues.some(
-        (i) => i.code === 'invalid_union_discriminator',
-      );
-      expect(hasInvalidDiscriminator, `frame type '${type}' is missing from the discriminated union`).toBe(false);
-    }
-  });
-});
-
-describe('ws-frames.ts file mirror parity', () => {
-  it('apps/server and apps/web copies are byte-identical', () => {
-    const here = fileURLToPath(import.meta.url);
-    const serverPath = resolve(here, '../../../types/ws-frames.ts');
-    const webPath = resolve(here, '../../../../../web/src/api/ws-frames.ts');
-    const serverContent = readFileSync(serverPath, 'utf8');
-    const webContent = readFileSync(webPath, 'utf8');
-    expect(webContent, 'apps/web/src/api/ws-frames.ts must be byte-identical to apps/server/src/types/ws-frames.ts').toBe(serverContent);
-  });
-});
-
 describe('broker.publishFrame / publishUserFrame fail-closed behavior', () => {
   let logErrors: Array<{ obj: unknown; msg: string }>;
   let mockLog: Parameters<typeof createBroker>[0];

apps/server/src/services/broker.ts

@@ -1,5 +1,5 @@
 import type { FastifyBaseLogger } from 'fastify';
-import { WsFrameSchema, type WsFrame } from '../types/ws-frames.js';
+import { WsFrameSchema, type WsFrame } from '@boocode/contracts/ws-frames';
 
 export type Frame = Record<string, unknown> & { type: string };
 export type Listener = (frame: Frame) => void;

apps/server/src/services/inference/error-handler.ts

@@ -119,6 +119,7 @@ export async function finalizeCompletion(
         tokens_used = ${completionTokens},
         ctx_used = ${promptTokens},
         ctx_max = ${nCtx},
+        model = ${session.model},
         finished_at = clock_timestamp()
     WHERE id = ${assistantMessageId}
     RETURNING tokens_used, ctx_used, ctx_max, finished_at

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

@@ -4,6 +4,12 @@
  * Reads a JSON config file (default `/data/mcp.json`) that declares MCP
  * servers — their transport type, connection parameters, and enabled state.
  * Schema shape matches opencode's `mcpServers` key for copy-paste compat.
+ *
+ * Secrets stay out of the config file via `{env:VAR}` substitution
+ * (opencode-compatible). Any string value can reference an environment
+ * variable, e.g. a header `"CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"`
+ * resolves from `process.env` at load. This keeps real keys in `.env`
+ * (`env_file` in docker-compose) rather than the gitignored config.
  */
 import { readFileSync } from 'node:fs';
 import { z } from 'zod';
@@ -38,6 +44,49 @@ export interface McpServerEntry {
   config: McpServerConfig;
 }
 
+// ---- Env-var substitution ----
+
+const ENV_VAR_PATTERN = /\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+/**
+ * Recursively replace `{env:VAR}` references in string values with the
+ * matching environment variable (opencode-compatible). Runs before Zod
+ * validation so a resolved value (e.g. a `{env:...}` URL) still validates.
+ * An unset var resolves to '' and logs a warning so a missing secret is
+ * visible in the boot log rather than silently sending a literal placeholder.
+ * Pass an optional `unsetVars` set to collect the names that resolved to '';
+ * the loader surfaces them on a validation failure (an empty value in a strict
+ * url/command field invalidates the whole config — see loadMcpConfig).
+ */
+export function substituteEnvVars(
+  value: unknown,
+  log: FastifyBaseLogger,
+  unsetVars?: Set<string>,
+): unknown {
+  if (typeof value === 'string') {
+    return value.replace(ENV_VAR_PATTERN, (_match, name: string) => {
+      const resolved = process.env[name];
+      if (resolved === undefined) {
+        unsetVars?.add(name);
+        log.warn(`mcp: env var ${name} referenced in config is unset; substituting empty string`);
+        return '';
+      }
+      return resolved;
+    });
+  }
+  if (Array.isArray(value)) {
+    return value.map((v) => substituteEnvVars(v, log, unsetVars));
+  }
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      out[k] = substituteEnvVars(v, log, unsetVars);
+    }
+    return out;
+  }
+  return value;
+}
+
 // ---- Loader ----
 
 /**
@@ -61,9 +110,19 @@ export function loadMcpConfig(configPath: string, log: FastifyBaseLogger): McpSe
     return [];
   }
 
-  const result = McpConfigSchema.safeParse(json);
+  const unsetVars = new Set<string>();
+  const result = McpConfigSchema.safeParse(substituteEnvVars(json, log, unsetVars));
   if (!result.success) {
-    log.warn({ errors: result.error.flatten().fieldErrors }, `mcp: invalid config at ${configPath}`);
+    // Connect the two otherwise-disconnected warnings: an unset {env:VAR} that
+    // resolved to '' can invalidate a strict field (url/command) and drop the
+    // whole config, so name the unset vars alongside the validation errors.
+    const hint = unsetVars.size
+      ? ` — ${unsetVars.size} referenced env var(s) unset & substituted with '' (${[...unsetVars].join(', ')}); an unset {env:VAR} in a url/command field invalidates the whole config`
+      : '';
+    log.warn(
+      { errors: result.error.flatten().fieldErrors, unsetEnvVars: [...unsetVars] },
+      `mcp: invalid config at ${configPath}${hint}`,
+    );
     return [];
   }
 

apps/server/src/types/api.ts

@@ -25,19 +25,9 @@ export interface AvailableProject {
 
 export type SessionStatus = 'open' | 'archived';
 
-// Session-delete work-loss guard. Returned (as `reports`) in the 409 body when
-// a delete is blocked because the session's worktree holds work at risk. The
-// shape is produced by BooCoder's checkWorktreeWorkAtRisk and passed through
-// verbatim; mirrored byte-for-byte in apps/web/src/api/types.ts for the dialog.
-export interface WorktreeRiskReport {
-  worktreePath: string;
-  branch: string;
-  dirty: boolean;
-  unpushed: number; // commits ahead of upstream, or -1 if no upstream
-  unmerged: number; // commits not in the project default branch
-  atRisk: boolean;
-  error?: string;
-}
+// WorktreeRiskReport single-sourced in @boocode/contracts — edit the package, not here.
+import type { WorktreeRiskReport } from '@boocode/contracts/worktree-risk';
+export type { WorktreeRiskReport };
 
 export interface Session {
   id: string;
@@ -198,51 +188,10 @@ export interface ToolResult {
   error?: string;
 }
 
-// v1.8.2: structured reason codes for failed inferences. `error` carries the
-// human text; `reason` is the machine-readable discriminator the UI matches
-// on (with `error` as fallback when reason is absent or unrecognized).
-export type ErrorReason =
-  | 'llm_provider_error'
-  | 'tool_execution_failed'
-  | 'summary_after_cap_failed';
-
-// v1.8.2 / v1.11.6: shapes stored in messages.metadata. Discriminated on `kind`.
-//   cap_hit          — system sentinel emitted when tool budget is exhausted
-//   doom_loop        — system sentinel emitted when the model called the same
-//                      tool with the same args DOOM_LOOP_THRESHOLD times in a row
-//   mistake_recovery — system sentinel emitted when a run of consecutive
-//                      *heterogeneous* tool failures is detected (#12). A nudge
-//                      (escalated:false) injects model-facing recovery guidance
-//                      and continues; an escalate (escalated:true) stops the
-//                      turn after the nudge failed to break the failure run.
-//   error            — attached to a failed assistant message so UI can show reason
-export type MessageMetadata =
-  | {
-      kind: 'cap_hit';
-      used: number;
-      limit: number;
-      agent_name: string | null;
-      can_continue: boolean;
-    }
-  | {
-      kind: 'doom_loop';
-      tool_name: string;
-      args: Record<string, unknown>;
-      threshold: number;
-    }
-  | {
-      // PINNED CONTRACT (#12) — mirrored byte-for-byte in apps/web/src/api/types.ts.
-      kind: 'mistake_recovery';
-      failure_kinds: string[];
-      count: number;
-      escalated: boolean;
-      can_continue?: boolean;
-    }
-  | {
-      kind: 'error';
-      error_reason: ErrorReason;
-      error_text: string;
-    };
+// v1.8.2 / v1.11.6: ErrorReason + MessageMetadata single-sourced in
+// @boocode/contracts — edit the package, not here.
+import type { ErrorReason, MessageMetadata } from '@boocode/contracts/message-metadata';
+export type { ErrorReason, MessageMetadata };
 
 export interface Message {
   id: string;

apps/web/CLAUDE.md

@@ -0,0 +1,47 @@
+# apps/web — BooChat frontend (deep reference)
+
+> Per-app engineering notes for `apps/web/src/`. The frontend is a single React SPA that also hosts the BooCoder `'coder'` pane. 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/web/`.
+
+## Stack
+
+- **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**: `useViewport` (matchMedia; mobile <768 / tablet 768–1023 / desktop ≥1024), `useSidebarDrawer` / `useRightRailDrawer` (Context + auto-close on `useLocation().pathname` change), `useLongPress` (500ms timer, 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` + `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) for cross-component communication: session renames, file-open, attachment dispatch. 26-arm discriminated union (and growing). Adding an event type also requires a `case` in the `applyEvent` switch in `useSidebar.ts` (no-op `return prev` is fine), and a subscribe in any hook that needs it (e.g. `useSessionStream` for `refetch_messages`).
+- **`hooks/useSessionStream.ts`** — WebSocket per session; `applyFrame` reducer builds the 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 `applyEvent`.
+- **`api/client.ts`** — Centralized typed fetch wrapper. All endpoints under `api.*`.
+
+## Font / CSS pipeline
+
+- Tailwind v4's `@import "tailwindcss"` strips font URLs from subsequent CSS `@import`s — `@fontsource*` packages must be JS side-effect imports in `apps/web/src/main.tsx`, not `@import` in `globals.css`, or the woff2 files never reach `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 for those codepoints). Use explicit non-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`.
+- JetBrainsMono Nerd Font self-hosted in `apps/web/src/fonts/` (TTF from ryanoasis/nerd-fonts) — `@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 atlas; Canvas2D does NOT honor `font-display: block` — it uses whatever font is registered. Gate xterm init on `document.fonts.load(<font-name>)` resolving before `term.open()` (`fontsReady` in `TerminalPane.tsx`). iOS Safari/Vivaldi also reclaim 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 drops to DOM renderer with stale metrics.
+
+## Multi-pane workspace
+
+Sessions hold 1–5 panes (chat / empty / placeholder terminal+agent). Pane state lives in `sessions.workspace_panes jsonb` for cross-device sync. `PATCH /api/sessions/:id/workspace` persists; `session_workspace_updated` user-channel frame broadcasts to every device. `useWorkspacePanes` debounces saves 300ms and dedups echoes by JSON string (legacy localStorage key seeded once on first hydrate, then no longer written). `validatePanes(validChatIds)` prunes panes referencing deleted chats. Each chat lives in at most one pane; the per-pane tab strip tracks `chatIds[]` + `activeChatIdx`, reorder via native HTML5 drag. `workspace_panes` is a `WorkspaceState` envelope `{panes, tabNumbers, nextTabNumber, closedPaneStack}` (tabNumbers = stable session-scoped chatId→number, never reused; closedPaneStack = reopen LIFO, max 10, persisted); hydrate (`toWorkspaceState`) and the server PATCH validator (`z.union([array, envelope])`) both accept the legacy bare array and normalize. Closing a chat pane relocates its tabs to the oldest chat/empty pane; `reopenPane` strips restored chatIds from all live panes first. `read_tab_by_number` resolves number→chatId through `tabNumbers`.
+
+## Frontend conventions
+
+- `overflowWrap` not `wordWrap` — TypeScript's CSSStyleDeclaration marks `wordWrap` deprecated (error 6385).
+- shadcn primitives live in `components/ui/`. Don't modify them unless adding a new primitive.
+- `ui/` primitives present: button, card, context-menu, dialog, dropdown-menu, input, label, radio-group, sonner, textarea. No switch/sheet/drawer/badge/checkbox — use a `<button role="switch" aria-checked>` toggle (a hand-rolled `Switch` lives in `SettingsPane.tsx`) and a Dialog-based panel for "drawers".
+- `inferLanguage()` from `lib/attachments.ts` is the canonical file-extension→language map. `CodeBlock.tsx` keeps its own `LANG_MAP` because it also resolves markdown fence names.
+- Two UI event buses: `hooks/sessionEvents.ts` for DB-state events (chat_created, session_updated); `lib/events.ts` for ephemeral UI (`sendToTerminal`, `terminalsRegistry`). Don't merge — different subscriber lifecycles.
+- `vite.config.ts` proxy entries are order-sensitive: more-specific prefixes (`/api/term`, `/ws/term`) must come BEFORE `/api`.
+- Mobile pane URL sync (`Session.tsx`): the `?pane=<id>` effect resets `activePaneIdx` whenever `panes` changes. New-pane creation on mobile must push `?pane=` atomically — `addPaneAndSwitch` does this; `addSplitPane` returns the new pane id.
+- A scrollable list inside a Dialog on mobile: cap `DialogContent` (`max-h-[85vh]` + `grid-rows-[auto_minmax(0,1fr)_auto]`) and make the list the single scroll region with `overscroll-contain` — otherwise touch-scroll drags the whole fixed modal / chains to the page.
+- xterm.js v5 uses canvas rendering — the browser doesn't see xterm's selection, so the native right-click Copy doesn't work for terminal text. App keybindings (`Cmd/Ctrl-C`, `Cmd/Ctrl-Shift-C`) are the path.
+- 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 this reason.
+- **CoderPane uses ChatInput** (`components/panes/CoderPane.tsx`): shares BooChat's `ChatInput` for full parity — attachments, paste-to-chip, auto-grow textarea, queued messages during send. `sendOneMessage` is the send callback; queued messages drain via `useEffect` when `sending` goes false.
+- **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; surfacing loading states needs a client poll.
+- **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` next to `MobileTabSwitcher`/`NewPaneMenu`. `AgentComposerBar` (provider/mode/model pickers) renders inside `CoderPane.tsx` on both; the ● status dot is passed via `connected` prop.
+- **MessageBubble shared between BooChat and BooCoder** (`components/MessageBubble.tsx`): optional `actions?: MessageActions` + `hideActions?` props; CoderPane overrides via `CoderMessageList`. **`CoderMessageList` passes `CoderMessageWire as unknown as Message`** — the coder shape lacks `metadata`/`kind`/`summary`, so they're `undefined` (not `null`). Null-guards on any `Message` field MUST use loose `!= null`, not `!== null` (`undefined !== null` is `true` → `.kind` throws → blank-screen crash). The cast hides this from tsc; build passes while runtime crashes.

apps/web/package.json

@@ -10,6 +10,7 @@
     "typecheck": "tsc -b --noEmit"
   },
   "dependencies": {
+    "@boocode/contracts": "workspace:*",
     "@fontsource-variable/inter": "^5.2.8",
     "@fontsource-variable/jetbrains-mono": "^5.2.8",
     "@xterm/addon-fit": "0.10.0",

apps/web/src/api/types.ts

@@ -34,18 +34,8 @@ export interface AvailableProject {
 
 export type SessionStatus = 'open' | 'archived';
 
-// Session-delete work-loss guard. Mirror of WorktreeRiskReport in
-// apps/server/src/types/api.ts — edit both copies together. Arrives as the
-// `reports` field of the 409 body when a delete is blocked.
-export interface WorktreeRiskReport {
-  worktreePath: string;
-  branch: string;
-  dirty: boolean;
-  unpushed: number; // commits ahead of upstream, or -1 if no upstream
-  unmerged: number; // commits not in the project default branch
-  atRisk: boolean;
-  error?: string;
-}
+// WorktreeRiskReport single-sourced in @boocode/contracts — edit the package, not here.
+export type { WorktreeRiskReport } from '@boocode/contracts/worktree-risk';
 
 export interface Session {
   id: string;
@@ -143,49 +133,10 @@ export interface ToolResult {
   error?: string;
 }
 
-// v1.8.2: structured reason codes that flow through error frames / metadata.
-// `error` text stays human; `reason` is the discriminator the UI matches on.
-export type ErrorReason =
-  | 'llm_provider_error'
-  | 'tool_execution_failed'
-  | 'summary_after_cap_failed';
-
-// v1.8.2 / v1.11.6: shapes stored in Message.metadata. Discriminated on `kind`.
-//   cap_hit    — sentinel emitted when the tool budget is hit; carries the
-//                budget + agent name + whether Continue is still allowed.
-//   doom_loop  — sentinel emitted when the model called the same tool with
-//                the same arguments threshold times in a row.
-//   mistake_recovery — sentinel emitted when the model hit repeated *different*
-//                errors; non-escalated means recovery guidance was injected and
-//                the turn continues, escalated means the turn was stopped.
-//   error      — attached to a failed assistant message so the bubble can show
-//                a specific reason on reload (WS error frame is one-shot).
-export type MessageMetadata =
-  | {
-      kind: 'cap_hit';
-      used: number;
-      limit: number;
-      agent_name: string | null;
-      can_continue: boolean;
-    }
-  | {
-      kind: 'doom_loop';
-      tool_name: string;
-      args: Record<string, unknown>;
-      threshold: number;
-    }
-  | {
-      kind: 'mistake_recovery';
-      failure_kinds: string[];
-      count: number;
-      escalated: boolean;
-      can_continue?: boolean;
-    }
-  | {
-      kind: 'error';
-      error_reason: ErrorReason;
-      error_text: string;
-    };
+// v1.8.2 / v1.11.6: ErrorReason + MessageMetadata single-sourced in
+// @boocode/contracts — edit the package, not here.
+import type { ErrorReason, MessageMetadata } from '@boocode/contracts/message-metadata';
+export type { ErrorReason, MessageMetadata };
 
 export interface Message {
   id: string;
@@ -201,6 +152,9 @@ export interface Message {
   tokens_used: number | null;
   ctx_used: number | null;
   ctx_max: number | null;
+  // model-attribution: which model produced this assistant message (null for
+  // user/system rows + pre-attribution messages). Rendered as a chip.
+  model: string | null;
   started_at: string | null;
   finished_at: string | null;
   created_at: string;
@@ -236,80 +190,23 @@ export interface ModelInfo {
   [key: string]: unknown;
 }
 
-export interface ProviderModel {
-  id: string;
-  label: string;
-  description?: string;
-  isDefault?: boolean;
-  thinkingOptions?: ThinkingOption[];
-  defaultThinkingOptionId?: string;
-}
+export type {
+  ProviderModel,
+  ProviderMode,
+  ThinkingOption,
+  ProviderSnapshotStatus,
+  AgentCommand,
+  ProviderSnapshotEntry,
+} from '@boocode/contracts/provider-snapshot';
 
-export interface ProviderMode {
-  id: string;
-  label: string;
-  description?: string;
-  isUnattended?: boolean;
-}
+export type {
+  ProviderOverride,
+  CoderProvidersFile,
+  ProviderConfigPatch,
+} from '@boocode/contracts/provider-config';
 
-export interface ThinkingOption {
-  id: string;
-  label: string;
-  isDefault?: boolean;
-}
-
-// v2.3 phase 2: 'loading' + 'unavailable' restored alongside 'ready' | 'error'.
-export type ProviderSnapshotStatus = 'loading' | 'ready' | 'unavailable' | 'error';
-
-// KEEP IN SYNC with apps/coder/src/services/provider-types.ts ProviderSnapshotEntry
-// — parity is enforced by coder __tests__/provider-types-parity.test.ts (field drift fails it).
-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;
-}
-
-// v2.3 Phase 4: provider config file wire types. Mirror of the Zod-inferred
-// ProviderOverride / CoderProvidersFile in apps/coder/src/services/provider-config.ts
-// (web can't cross-import the coder package — TS6307 on the composite project).
-export interface ProviderOverride {
-  extends?: 'acp';
-  label?: string;
-  description?: string;
-  command?: string[];
-  env?: Record<string, string>;
-  enabled?: boolean;
-  order?: number;
-  models?: Array<{ id: string; label: string }>;
-  additionalModels?: Array<{ id: string; label: string }>;
-}
-
-export interface CoderProvidersFile {
-  providers: Record<string, ProviderOverride>;
-}
-
-// PATCH body: a partial providers map. A `null` value deletes that id's
-// override (revert to built-in default); an object replaces it wholesale.
-export interface ProviderConfigPatch {
-  providers: Record<string, ProviderOverride | null>;
-}
-
-export interface AgentSessionConfig {
-  provider: string;
-  model: string;
-  modeId: string | null;
-  thinkingOptionId: string | null;
-}
+// AgentSessionConfig single-sourced in @boocode/contracts — edit the package, not here.
+export type { AgentSessionConfig } from '@boocode/contracts/message-metadata';
 
 export type PermissionKind = 'tool' | 'question' | 'plan' | 'elicitation';
 
@@ -321,14 +218,6 @@ export interface PermissionPrompt {
   options: Array<{ optionId: string; label: string }>;
 }
 
-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';
-}
-
 export interface CoderSendMessageBody {
   content: string;
   pane_id: string;
@@ -351,7 +240,13 @@ export interface CoderMessageWire {
   role: 'user' | 'assistant' | 'system';
   content: string;
   status?: 'streaming' | 'complete' | 'failed';
+  // model-attribution: which model produced this coder assistant message.
+  model?: string | null;
   reasoning_text?: string;
+  // Context-window fill for the ContextBar (claude SDK turns set these from the
+  // SDK's reported window; other agents omit them). Read via the Message cast.
+  ctx_used?: number | null;
+  ctx_max?: number | null;
   tool_calls?: Array<{
     id: string;
     function: { name: string; arguments: string };
@@ -571,6 +466,8 @@ export type WsFrame =
       ctx_max?: number | null;
       started_at?: string | null;
       finished_at?: string | null;
+      // model-attribution: the model that produced this assistant message.
+      model?: string | null;
       // v1.8.2: piggybacks the persisted metadata onto the terminal frame so
       // cap-hit sentinels (and any future stamped-on-complete metadata) flow
       // to the client without a refetch.
@@ -596,4 +493,16 @@ export type WsFrame =
   | { type: 'compacted'; session_id: string; chat_id: string; summary_message_id: string }
   // v1.8.2: `reason` discriminates structured failures (the UI prefers it
   // over `error` text when present).
-  | { type: 'error'; message_id?: string; chat_id?: string; error: string; reason?: ErrorReason };
+  | { type: 'error'; message_id?: string; chat_id?: string; error: string; reason?: ErrorReason }
+  // agent-status-normalize (#10): BooCoder publishes a normalized per-(chat,agent)
+  // lifecycle status for external coding agents on the per-session channel. The
+  // CoderPane tracks the latest status per (chat_id, agent) and resets on chat
+  // switch; AgentComposerBar renders the dot (distinct from the WS-liveness dot).
+  | {
+      type: 'agent_status_updated';
+      chat_id: string;
+      agent: string;
+      status: 'working' | 'blocked' | 'idle' | 'error';
+      reason?: string;
+      at: string;
+    };

apps/web/src/api/ws-frames.ts

@@ -1,381 +0,0 @@
-// v1.13.11-a: Zod schemas for every WebSocket frame published by the server.
-// Validation runs both on send (broker.publishFrame / publishUserFrame) and
-// on receive (apps/web/src/hooks/useSessionStream + useUserEvents). Catches
-// silent protocol drift between publisher and consumer.
-//
-// IMPORTANT: This file is duplicated byte-identical at
-// apps/web/src/api/ws-frames.ts. The two apps have separate tsconfigs and
-// no path alias; the duplication is sync-by-hand. A test asserts the two
-// files match. If you change one, change the other.
-//
-// Per-kind payload schemas (tool_call args, message_parts payloads, etc.)
-// stay z.unknown() in v1.13.11. Frame-level drift detection is the goal;
-// deep payload validation is follow-up work.
-
-import { z } from 'zod';
-
-// ---- shared primitives -----------------------------------------------------
-
-const Uuid = z.string().uuid();
-// Tool call IDs are model-emitted (e.g. "call_abc123") — not UUIDs.
-const ToolCallId = z.string().min(1);
-// v1.13.12 fix: postgres returns timestamp columns as JS Date objects, not
-// strings. The publish sites pass them through unchanged, so the schema must
-// tolerate both. preprocess converts Date → ISO string before string-validation;
-// on the web side (where frames arrive via JSON.parse) it's a no-op. Before
-// this fix, every message_complete / session_updated / chat_updated frame
-// failed validation and got dropped — symptoms: token tracking blank in UI,
-// status stuck at 'streaming' tripping the 60s stale-stream banner.
-const IsoTimestamp = z.preprocess(
-  (v) => (v instanceof Date ? v.toISOString() : v),
-  z.string().min(1),
-);
-
-const ChatStatusValue = z.enum([
-  'streaming',
-  'tool_running',
-  'waiting_for_input',
-  'idle',
-  'error',
-]);
-
-const ErrorReasonValue = z.enum([
-  'llm_provider_error',
-  'doom_loop',
-  'doom_loop_summary_failed',
-  'cap_hit',
-  'cap_hit_summary_failed',
-]);
-
-const MessageRoleValue = z.enum(['user', 'assistant', 'system', 'tool']);
-
-const ToolCallShape = z.object({
-  id: ToolCallId,
-  name: z.string().min(1),
-  args: z.record(z.string(), z.unknown()),
-});
-
-// Free-form bags: opaque to the frame schema; deep validation is out of
-// scope for v1.13.11 (frame-level drift detection is the goal; per-kind
-// payload narrowing is follow-up work). z.unknown() means the consumer
-// must narrow before reading — TypeScript-side this is fine because every
-// consumer already operates on the hand-maintained Project / Chat / Session
-// / WorkspacePane types (the brief's "Don't strip existing types yet"
-// rule), and the Zod-typed shape is only used at the publishFrame boundary.
-const OpaqueObject = z.unknown();
-
-// ---- per-session channel frames --------------------------------------------
-
-export const SnapshotFrame = z.object({
-  type: z.literal('snapshot'),
-  messages: z.array(OpaqueObject),
-});
-
-export const MessageStartedFrame = z.object({
-  type: z.literal('message_started'),
-  message_id: Uuid,
-  chat_id: Uuid.optional(),
-  role: MessageRoleValue,
-});
-
-export const DeltaFrame = z.object({
-  type: z.literal('delta'),
-  message_id: Uuid,
-  chat_id: Uuid.optional(),
-  content: z.string(),
-});
-
-export const ReasoningDeltaFrame = z.object({
-  type: z.literal('reasoning_delta'),
-  message_id: Uuid,
-  chat_id: Uuid.optional(),
-  content: z.string(),
-});
-
-export const ToolCallFrame = z.object({
-  type: z.literal('tool_call'),
-  message_id: Uuid,
-  chat_id: Uuid.optional(),
-  tool_call: ToolCallShape,
-});
-
-export const ToolResultFrame = z.object({
-  type: z.literal('tool_result'),
-  tool_message_id: Uuid,
-  chat_id: Uuid.optional(),
-  tool_call_id: ToolCallId,
-  output: z.unknown(),
-  truncated: z.boolean(),
-  error: z.string().optional(),
-});
-
-export const MessageCompleteFrame = z.object({
-  type: z.literal('message_complete'),
-  message_id: Uuid,
-  chat_id: Uuid.optional(),
-  tokens_used: z.number().int().nonnegative().nullable().optional(),
-  ctx_used: z.number().int().nonnegative().nullable().optional(),
-  ctx_max: z.number().int().positive().nullable().optional(),
-  started_at: IsoTimestamp.nullable().optional(),
-  finished_at: IsoTimestamp.nullable().optional(),
-  model: z.string().optional(),
-  metadata: OpaqueObject.nullable().optional(),
-});
-
-export const UsageFrame = z.object({
-  type: z.literal('usage'),
-  message_id: Uuid,
-  chat_id: Uuid.optional(),
-  completion_tokens: z.number().int().nonnegative().nullable(),
-  ctx_used: z.number().int().nonnegative().nullable(),
-  ctx_max: z.number().int().positive().nullable(),
-});
-
-export const MessagesDeletedFrame = z.object({
-  type: z.literal('messages_deleted'),
-  message_ids: z.array(Uuid),
-  chat_id: Uuid.optional(),
-});
-
-export const ChatRenamedFrame = z.object({
-  type: z.literal('chat_renamed'),
-  chat_id: Uuid,
-  name: z.string(),
-});
-
-export const CompactedFrame = z.object({
-  type: z.literal('compacted'),
-  session_id: Uuid,
-  chat_id: Uuid,
-  summary_message_id: Uuid,
-});
-
-export const ErrorFrame = z.object({
-  type: z.literal('error'),
-  message_id: Uuid.optional(),
-  chat_id: Uuid.optional(),
-  error: z.string(),
-  reason: ErrorReasonValue.optional(),
-});
-
-// ---- per-user channel frames (sidebar refresh) -----------------------------
-
-export const ChatStatusFrame = z.object({
-  type: z.literal('chat_status'),
-  chat_id: Uuid,
-  status: ChatStatusValue,
-  at: IsoTimestamp,
-  reason: ErrorReasonValue.optional(),
-});
-
-export const SessionUpdatedFrame = z.object({
-  type: z.literal('session_updated'),
-  session_id: Uuid,
-  project_id: Uuid,
-  name: z.string(),
-  updated_at: IsoTimestamp,
-});
-
-export const SessionRenamedFrame = z.object({
-  type: z.literal('session_renamed'),
-  session_id: Uuid,
-  name: z.string(),
-});
-
-export const SessionCreatedFrame = z.object({
-  type: z.literal('session_created'),
-  session: OpaqueObject,
-  project_id: Uuid,
-});
-
-export const SessionArchivedFrame = z.object({
-  type: z.literal('session_archived'),
-  session_id: Uuid,
-  project_id: Uuid,
-});
-
-export const SessionDeletedFrame = z.object({
-  type: z.literal('session_deleted'),
-  session_id: Uuid,
-  project_id: Uuid,
-});
-
-export const SessionWorkspaceUpdatedFrame = z.object({
-  type: z.literal('session_workspace_updated'),
-  session_id: Uuid,
-  // v2.6.x: widened from z.array — the payload is now either the legacy bare
-  // WorkspacePane[] OR the WorkspaceState envelope object (panes + tabNumbers +
-  // nextTabNumber + closedPaneStack). z.array alone would fail-closed and drop
-  // every envelope frame at validation. MUST be mirrored in the server's
-  // byte-identical copy (parity test).
-  workspace_panes: z.union([z.array(OpaqueObject), z.record(z.unknown())]),
-});
-
-export const ChatCreatedFrame = z.object({
-  type: z.literal('chat_created'),
-  chat: OpaqueObject,
-  session_id: Uuid,
-});
-
-export const ChatUpdatedFrame = z.object({
-  type: z.literal('chat_updated'),
-  chat_id: Uuid,
-  session_id: Uuid,
-  name: z.string().nullable(),
-  updated_at: IsoTimestamp,
-});
-
-export const ChatArchivedFrame = z.object({
-  type: z.literal('chat_archived'),
-  chat_id: Uuid,
-  session_id: Uuid,
-});
-
-export const ChatUnarchivedFrame = z.object({
-  type: z.literal('chat_unarchived'),
-  chat: OpaqueObject,
-});
-
-export const ChatDeletedFrame = z.object({
-  type: z.literal('chat_deleted'),
-  chat_id: Uuid,
-  session_id: Uuid,
-});
-
-export const ProjectCreatedFrame = z.object({
-  type: z.literal('project_created'),
-  project: OpaqueObject,
-});
-
-export const ProjectArchivedFrame = z.object({
-  type: z.literal('project_archived'),
-  project_id: Uuid,
-});
-
-export const ProjectUnarchivedFrame = z.object({
-  type: z.literal('project_unarchived'),
-  project: OpaqueObject,
-});
-
-export const ProjectUpdatedFrame = z.object({
-  type: z.literal('project_updated'),
-  project_id: Uuid,
-  name: z.string(),
-});
-
-export const ProjectDeletedFrame = z.object({
-  type: z.literal('project_deleted'),
-  project_id: Uuid,
-});
-
-const PermissionOptionShape = z.object({
-  option_id: z.string(),
-  label: z.string(),
-});
-
-export const PermissionRequestedFrame = z.object({
-  type: z.literal('permission_requested'),
-  task_id: Uuid,
-  session_id: Uuid,
-  kind: z.enum(['tool', 'question', 'plan', 'elicitation']).optional(),
-  tool_title: z.string().optional(),
-  input: z.record(z.unknown()).optional(),
-  options: z.array(PermissionOptionShape),
-});
-
-export const PermissionResolvedFrame = z.object({
-  type: z.literal('permission_resolved'),
-  task_id: Uuid,
-  session_id: Uuid,
-});
-
-const AgentCommandShape = z.object({
-  name: z.string(),
-  description: z.string().optional(),
-});
-
-export const AgentCommandsFrame = z.object({
-  type: z.literal('agent_commands'),
-  task_id: Uuid,
-  session_id: Uuid,
-  commands: z.array(AgentCommandShape),
-});
-
-// ---- discriminated union ---------------------------------------------------
-
-export const WsFrameSchema = z.discriminatedUnion('type', [
-  // per-session
-  SnapshotFrame,
-  MessageStartedFrame,
-  DeltaFrame,
-  ReasoningDeltaFrame,
-  ToolCallFrame,
-  ToolResultFrame,
-  MessageCompleteFrame,
-  UsageFrame,
-  MessagesDeletedFrame,
-  ChatRenamedFrame,
-  CompactedFrame,
-  ErrorFrame,
-  PermissionRequestedFrame,
-  PermissionResolvedFrame,
-  AgentCommandsFrame,
-  // per-user
-  ChatStatusFrame,
-  SessionUpdatedFrame,
-  SessionRenamedFrame,
-  SessionCreatedFrame,
-  SessionArchivedFrame,
-  SessionDeletedFrame,
-  SessionWorkspaceUpdatedFrame,
-  ChatCreatedFrame,
-  ChatUpdatedFrame,
-  ChatArchivedFrame,
-  ChatUnarchivedFrame,
-  ChatDeletedFrame,
-  ProjectCreatedFrame,
-  ProjectArchivedFrame,
-  ProjectUnarchivedFrame,
-  ProjectUpdatedFrame,
-  ProjectDeletedFrame,
-]);
-
-export type WsFrame = z.infer<typeof WsFrameSchema>;
-
-// Convenience: the set of known frame types. Useful for the publishFrame
-// helper to log the offending type name when validation fails. Kept in sync
-// by hand with the discriminated union above.
-export const KNOWN_FRAME_TYPES: readonly WsFrame['type'][] = [
-  'snapshot',
-  'message_started',
-  'delta',
-  'reasoning_delta',
-  'tool_call',
-  'tool_result',
-  'message_complete',
-  'usage',
-  'messages_deleted',
-  'chat_renamed',
-  'compacted',
-  'error',
-  'permission_requested',
-  'permission_resolved',
-  'agent_commands',
-  'chat_status',
-  'session_updated',
-  'session_renamed',
-  'session_created',
-  'session_archived',
-  'session_deleted',
-  'session_workspace_updated',
-  'chat_created',
-  'chat_updated',
-  'chat_archived',
-  'chat_unarchived',
-  'chat_deleted',
-  'project_created',
-  'project_archived',
-  'project_unarchived',
-  'project_updated',
-  'project_deleted',
-] as const;

apps/web/src/components/AgentCommandsHint.tsx

@@ -1,49 +0,0 @@
-import { ChevronDown } from 'lucide-react';
-import { useState } from 'react';
-import type { AgentCommand } from '@/api/types';
-import { cn } from '@/lib/utils';
-
-interface Props {
-  commands: AgentCommand[];
-}
-
-export function AgentCommandsHint({ commands }: Props) {
-  const [open, setOpen] = useState(false);
-  const [expanded, setExpanded] = useState<string | null>(null);
-
-  if (commands.length === 0) return null;
-
-  return (
-    <div className="mx-2 mb-1 rounded-md border border-border/60 bg-muted/30 text-xs">
-      <button
-        type="button"
-        onClick={() => setOpen((v) => !v)}
-        className="w-full flex items-center justify-between px-2 py-1.5 text-muted-foreground hover:text-foreground max-md:min-h-[44px]"
-      >
-        <span>Slash commands ({commands.length})</span>
-        <ChevronDown className={cn('size-3.5 transition-transform', open && 'rotate-180')} />
-      </button>
-      {open && (
-        <ul className="px-2 pb-2 space-y-1 border-t border-border/40 max-h-48 overflow-y-auto overscroll-contain touch-pan-y">
-          {commands.map((cmd) => (
-            <li
-              key={cmd.name}
-              className="cursor-pointer"
-              onClick={() => setExpanded((v) => v === cmd.name ? null : cmd.name)}
-            >
-              <span className="font-mono text-primary/80">/{cmd.name}</span>
-              {cmd.description && (
-                <span className={cn(
-                  'ml-1.5 text-muted-foreground font-sans',
-                  expanded === cmd.name ? '' : 'line-clamp-2',
-                )}>
-                  {cmd.description}
-                </span>
-              )}
-            </li>
-          ))}
-        </ul>
-      )}
-    </div>
-  );
-}

apps/web/src/components/AgentComposerBar.tsx

@@ -3,8 +3,8 @@ import { Check, ChevronDown, RefreshCw, Loader2, Shield, Brain, Bot } from 'luci
 import { api } from '@/api/client';
 import type { AgentSessionConfig, ProviderSnapshotEntry, AgentCommand } from '@/api/types';
 import { useProviderSnapshot, refreshProviderSnapshot } from '@/hooks/useProviderSnapshot';
+import type { AgentStatusEntry } from '@/hooks/useAgentStatus';
 import { providerIcon } from '@/components/coder/providerIcons';
-import { useAgentSessions } from '@/hooks/useAgentSessions';
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -173,44 +173,49 @@ interface Props {
   onChange: (next: AgentSessionConfig) => void;
   onProviderCommandsChange?: (commands: AgentCommand[]) => void;
   connected?: boolean;
-  // v2.6 Phase 1-UX §9b: chat id for the resumed/new-session chip. Optional so
-  // BooChat and any other AgentComposerBar caller renders no chip and is
-  // otherwise unaffected. When present + connected + the chat has ≥1 prior
-  // turn, a chip right of the Provider picker reports whether switching to the
-  // current provider resumes an agent session, replays history (boocode), or
-  // starts fresh.
-  sessionId?: string;
-  // True once the chat has at least one prior turn — gates the chip so it stays
-  // hidden on a brand-new chat. Defaults to false (no chip).
-  hasPriorTurn?: boolean;
+  // #10: normalized status (working|blocked|idle|error) for the active external
+  // agent in this chat, or null for native boocode / before any frame. Renders
+  // a status dot DISTINCT from the WS-liveness `connected` dot. Undefined for
+  // non-coder callers — no dot.
+  agentStatus?: AgentStatusEntry | null;
 }
 
-// Condensed token count: 950 → "950", 12_400 → "12.4K", 3_200_000 → "3.2M".
-// Sub-1000 stays exact; thousands/millions get one decimal, trailing .0 trimmed.
-function abbrevTokens(n: number): string {
-  if (!Number.isFinite(n) || n < 1000) return String(Math.max(0, Math.round(n)));
-  if (n < 1_000_000) return `${(n / 1000).toFixed(1).replace(/\.0$/, '')}K`;
-  return `${(n / 1_000_000).toFixed(1).replace(/\.0$/, '')}M`;
+// #10: normalized external-agent status dot. Mirrors StatusDot's visual
+// language but on the four normalized buckets (working|blocked|idle|error),
+// and is DISTINCT from the WS-liveness `connected` dot beside it:
+//   working — emerald spinning ring (subtle motion, like chat streaming)
+//   blocked — amber dot (matches the permission/blocked state colour)
+//   idle    — gray dot
+//   error   — red dot
+function AgentStatusDot({ entry, agent }: { entry: AgentStatusEntry; agent: string }) {
+  const title =
+    `${agent}: ${entry.status}` + (entry.reason ? ` — ${entry.reason}` : '');
+
+  if (entry.status === 'working') {
+    return (
+      <span
+        aria-label={`Agent status: working${entry.reason ? ` — ${entry.reason}` : ''}`}
+        title={title}
+        className="inline-block w-3 h-3 rounded-full border-2 border-emerald-500 border-t-transparent animate-spin shrink-0"
+      />
+    );
+  }
+
+  const bg =
+    entry.status === 'blocked' ? 'bg-amber-500'
+      : entry.status === 'error' ? 'bg-destructive'
+      : 'bg-muted-foreground/40';
+
+  return (
+    <span
+      aria-label={`Agent status: ${entry.status}${entry.reason ? ` — ${entry.reason}` : ''}`}
+      title={title}
+      className={cn('inline-block w-1.5 h-1.5 rounded-full shrink-0', bg)}
+    />
+  );
 }
 
-// Relative-time formatter for the resumed-chip title (e.g. "3m ago").
-function relativeTime(iso: string | null): string {
-  if (!iso) return 'unknown';
-  const then = new Date(iso).getTime();
-  if (Number.isNaN(then)) return 'unknown';
-  const diffMs = Date.now() - then;
-  if (diffMs < 0) return 'just now';
-  const sec = Math.floor(diffMs / 1000);
-  if (sec < 60) return 'just now';
-  const min = Math.floor(sec / 60);
-  if (min < 60) return `${min}m ago`;
-  const hr = Math.floor(min / 60);
-  if (hr < 24) return `${hr}h ago`;
-  const day = Math.floor(hr / 24);
-  return `${day}d ago`;
-}
-
-export function AgentComposerBar({ projectPath, value, onChange, onProviderCommandsChange, connected, sessionId, hasPriorTurn }: Props) {
+export function AgentComposerBar({ projectPath, value, onChange, onProviderCommandsChange, connected, agentStatus }: Props) {
   const allEntries = useProviderSnapshot(projectPath);
   // 5.5 — the composer picker only offers ENABLED providers that are ready (or
   // still loading). Disabled (enabled:false) and unavailable/error providers are
@@ -222,13 +227,6 @@ export function AgentComposerBar({ projectPath, value, onChange, onProviderComma
   );
   const [refreshing, setRefreshing] = useState(false);
 
-  // v2.6 Phase 1-UX §9b: chat-scoped agent-session rows for the resumed/new
-  // chip. Hook is unconditional (hooks rule); it self-no-ops when sessionId is
-  // undefined or the chat has no prior turn, so BooChat callers cost nothing.
-  const { sessions: agentSessions } = useAgentSessions(
-    sessionId && hasPriorTurn ? sessionId : undefined,
-  );
-
   const hydratedRef = useRef(false);
 
   useEffect(() => {
@@ -342,42 +340,8 @@ export function AgentComposerBar({ projectPath, value, onChange, onProviderComma
   const modelOptions = (currentEntry?.models ?? []).map((m) => ({ id: m.id, label: m.label }));
   const thinkingOpts = thinkingOptions.map((t) => ({ id: t.id, label: t.label }));
 
-  // v2.6 Phase 1-UX §9b: resumed / history / new-session chip. Only meaningful
-  // when this is a real chat (sessionId), the WS is connected, and the chat has
-  // ≥1 prior turn — otherwise render nothing so fresh chats and non-coder
-  // callers stay clean.
-  const sessionRow = agentSessions.find((s) => s.agent === value.provider);
-  const sessionChip: { label: string; title: string } | null =
-    sessionId && hasPriorTurn && connected
-      ? value.provider === 'boocode'
-        ? // Native boocode never holds an agent_sessions row — it reconstructs
-          // the conversation from the chat transcript each turn.
-          { label: 'history', title: 'BooCode replays the chat transcript each turn' }
-        : sessionRow?.has_session
-          ? {
-              label: 'resumed',
-              title: `Resuming ${value.provider} · last active ${relativeTime(sessionRow.last_active_at)}`,
-            }
-          : { label: 'new session', title: `${value.provider} starts a fresh session this turn` }
-      : null;
-
-  // sampling-streamjson-tokens #8: condensed per-(chat,agent) token/cost readout
-  // beside the session chip. Coerce — input/output are BIGINT (string over wire).
-  // Hidden when no session row or all totals are zero (e.g. native boocode, which
-  // holds no agent_sessions row, or a provider that hasn't run yet).
-  const usageReadout = (() => {
-    if (!sessionChip || !sessionRow) return null;
-    const inTok = Number(sessionRow.input_tokens) || 0;
-    const outTok = Number(sessionRow.output_tokens) || 0;
-    const cost = Number(sessionRow.cost) || 0;
-    if (inTok <= 0 && outTok <= 0 && cost <= 0) return null;
-    const parts = [`${abbrevTokens(inTok)} in`, `${abbrevTokens(outTok)} out`];
-    if (cost > 0) parts.push(`$${cost.toFixed(2)}`);
-    return parts.join(' · ');
-  })();
-
   return (
-    <div className="flex flex-wrap items-center gap-1 px-2 py-1 border-b border-border bg-muted/20 shrink-0">
+    <div className="flex items-center gap-1 px-2 py-1 border-b border-border bg-muted/20 shrink-0">
       <CompactPicker
         label="Provider"
         value={value.provider}
@@ -389,22 +353,6 @@ export function AgentComposerBar({ projectPath, value, onChange, onProviderComma
             : providerIcon(value.provider)
         }
       />
-      {sessionChip && (
-        <span
-          title={sessionChip.title}
-          className="inline-flex items-center rounded-full border border-border bg-muted/40 px-1.5 py-0.5 text-[10px] font-medium text-muted-foreground shrink-0"
-        >
-          {sessionChip.label}
-        </span>
-      )}
-      {usageReadout && (
-        <span
-          className="text-[10px] text-muted-foreground tabular-nums whitespace-nowrap shrink-0"
-          title="Tokens in · out · cost for this agent session"
-        >
-          {usageReadout}
-        </span>
-      )}
       <CompactPicker
         label="Mode"
         value={value.modeId ?? ''}
@@ -431,9 +379,13 @@ export function AgentComposerBar({ projectPath, value, onChange, onProviderComma
           icon={<Brain className="size-3 shrink-0" />}
         />
       )}
-      {/* Status dot + refresh as one right-aligned unit so the refresh button
-          stays on the top line instead of wrapping past the edge-pinned dot. */}
+      {/* Status dot + refresh — pinned right (ml-auto), never on its own line. */}
       <div className="ml-auto flex items-center gap-1 shrink-0">
+        {/* #10: normalized agent status — only for an external agent with a
+            live status frame. Distinct from the WS-liveness dot that follows. */}
+        {agentStatus && value.provider !== 'boocode' && (
+          <AgentStatusDot entry={agentStatus} agent={value.provider} />
+        )}
         {connected !== undefined && (
           <span
             className={cn('inline-block w-1.5 h-1.5 rounded-full shrink-0', connected ? 'bg-green-500' : 'bg-red-500')}

apps/web/src/components/ChatInput.tsx

@@ -1,14 +1,8 @@
 import { useCallback, useEffect, useMemo, useRef, useState, type DragEvent, type KeyboardEvent } from 'react';
-import { Check, ListPlus, Plus, Send, Square } from 'lucide-react';
+import { Globe, ListPlus, Paperclip, Send, Square, SquareSlash } from 'lucide-react';
 import { toast } from 'sonner';
 import { Textarea } from '@/components/ui/textarea';
 import { Button } from '@/components/ui/button';
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuTrigger,
-} from '@/components/ui/dropdown-menu';
 import {
   flattenToMessage,
   inferLanguage,
@@ -22,7 +16,6 @@ import { AttachmentPreviewModal } from '@/components/AttachmentPreviewModal';
 import { FileMentionPopover } from '@/components/FileMentionPopover';
 import { DropOverlay } from '@/components/DropOverlay';
 import { AgentPicker } from '@/components/AgentPicker';
-import { AgentCommandsHint } from '@/components/AgentCommandsHint';
 import { ContextBar } from '@/components/ContextBar';
 import { SlashCommandPicker, type SlashCommandGroup } from '@/components/SlashCommandPicker';
 import { isSlashCommandToken, parseSlashInput, slashQuery } from '@/lib/slash-command';
@@ -123,6 +116,11 @@ export function ChatInput({ disabled, projectId, agentId, onAgentChange, session
   );
   const [fileIndex, setFileIndex] = useState<string[] | null>(null);
   const textareaRef = useRef<HTMLTextAreaElement | null>(null);
+  // Attach-file button → hidden native picker (same File→Attachment path as drop).
+  const fileInputRef = useRef<HTMLInputElement | null>(null);
+  // Slash-commands chip → click-to-open command menu, anchored to the chip.
+  const cmdChipRef = useRef<HTMLButtonElement | null>(null);
+  const [cmdMenuOpen, setCmdMenuOpen] = useState(false);
 
   function addAttachment(a: Attachment) {
     setAttachments(prev => {
@@ -180,6 +178,23 @@ export function ChatInput({ disabled, projectId, agentId, onAgentChange, session
     setAttachments(prev => prev.filter(a => a.id !== id));
   }
 
+  // Attach-file button: funnel picked files through the same size/binary gate +
+  // chip pipeline as drag-drop. Reset value so re-picking the same file fires.
+  async function onPickFiles(e: React.ChangeEvent<HTMLInputElement>) {
+    const files = Array.from(e.target.files ?? []);
+    e.target.value = '';
+    if (files.length === 0) return;
+    let remaining = MAX_ATTACHMENTS - attachments.length;
+    for (const file of files) {
+      if (remaining <= 0) {
+        toast.error(`Attachment limit reached (${MAX_ATTACHMENTS}).`);
+        break;
+      }
+      await processDroppedFile(file);
+      remaining -= 1;
+    }
+  }
+
   async function submit() {
     const text = value.trim();
     if (!text && attachments.length === 0) return;
@@ -582,9 +597,6 @@ export function ChatInput({ disabled, projectId, agentId, onAgentChange, session
           ))}
         </div>
       )}
-      {slashItems.length > 0 && (
-        <AgentCommandsHint commands={slashItems} />
-      )}
       {/* Batch 9 toolbar — agent picker + quick-toggle menu. v1.11.5.1
           inlines ContextBar in the same row so the bar lives next to the
           picker rather than as a separate header above it. The row renders
@@ -598,39 +610,9 @@ export function ChatInput({ disabled, projectId, agentId, onAgentChange, session
               onChange={onAgentChange}
             />
           )}
-          {sessionId && (
-            <DropdownMenu>
-              <DropdownMenuTrigger asChild>
-                <button
-                  type="button"
-                  aria-label="Quick toggles"
-                  title="Quick toggles"
-                  className="inline-flex items-center justify-center size-6 rounded text-muted-foreground hover:bg-muted hover:text-foreground"
-                >
-                  <Plus className="size-3.5" />
-                </button>
-              </DropdownMenuTrigger>
-              <DropdownMenuContent align="start">
-                <DropdownMenuItem
-                  onSelect={async () => {
-                    // v1.9: tri-state collapses to two on the wire when toggled
-                    // here. null (inherit) treated as off; click flips to true.
-                    // To restore "inherit" the user opens SettingsPane.
-                    const next = webSearchEnabled === true ? false : true;
-                    try {
-                      await api.sessions.update(sessionId, { web_search_enabled: next });
-                    } catch (err) {
-                      toast.error(err instanceof Error ? err.message : 'failed to toggle web search');
-                    }
-                  }}
-                  className="text-xs"
-                >
-                  <Check className={`size-3 ${webSearchEnabled === true ? 'opacity-100' : 'opacity-0'}`} />
-                  Enable web search and fetch
-                </DropdownMenuItem>
-              </DropdownMenuContent>
-            </DropdownMenu>
-          )}
+          {/* BooCode 2.0: the web-search toggle moved out of this top toolbar
+              into the composer box's bottom controls row (the Web pill below),
+              leaving the top row as just the agent picker + context bar. */}
           {/* v1.11.5.1: ContextBar fills the remaining horizontal space.
               `flex-1 min-w-0` is set inside the component. Mounts only when
               the caller passes `messages` so older call sites (without the
@@ -640,54 +622,112 @@ export function ChatInput({ disabled, projectId, agentId, onAgentChange, session
           )}
         </div>
       )}
-      <div className="px-4 py-3 flex items-end gap-2">
-        <Textarea
-          ref={textareaRef}
-          value={value}
-          onChange={handleChange}
-          onKeyDown={onKeyDown}
-          onPaste={onPaste}
-          placeholder={
-            isMobile
-              ? 'Ask about this project. Tap send to submit.'
-              : 'Ask about this project. Enter to send · Shift+Enter for newline.'
-          }
-          disabled={disabled || busy}
-          rows={3}
-          className="resize-none min-h-[68px] max-h-[240px]"
-        />
-        {(() => {
-          const hasContent = value.trim().length > 0 || attachments.length > 0;
-          // While generating with an empty draft, the button stops generation.
-          if (generating && onStop && !hasContent) {
-            return (
-              <Button
-                onClick={() => void onStop()}
-                size="icon-lg"
-                variant="outline"
-                aria-label="Stop generating"
-                title="Stop generating"
-              >
-                <Square className="fill-current size-3.5" />
-              </Button>
-            );
-          }
-          // With a draft, submit. While generating the caller queues it, so the
-          // button reads as Queue; otherwise it's a normal Send.
-          const queueing = !!generating && hasContent;
-          return (
-            <Button
-              onClick={() => void submit()}
-              disabled={disabled || busy || !hasContent}
-              size="icon-lg"
-              variant={queueing ? 'secondary' : 'default'}
-              aria-label={queueing ? 'Queue message' : 'Send'}
-              title={queueing ? 'Queue message' : 'Send'}
+      {/* BooCode 2.0 composer: textarea + a bottom controls row live INSIDE one
+          bordered, focus-ringed message box (Refreshed direction). */}
+      <div className="px-4 py-3">
+        <div className="rounded-xl border bg-card transition-colors focus-within:border-primary/50 focus-within:ring-2 focus-within:ring-primary/15">
+          <Textarea
+            ref={textareaRef}
+            value={value}
+            onChange={handleChange}
+            onKeyDown={onKeyDown}
+            onPaste={onPaste}
+            placeholder={
+              isMobile
+                ? 'Ask about this project. Tap send to submit.'
+                : 'Ask about this project. Enter to send · Shift+Enter for newline.'
+            }
+            disabled={disabled || busy}
+            rows={3}
+            className="resize-none min-h-[56px] max-h-[240px] border-0 bg-transparent px-3 pt-2.5 shadow-none focus-visible:ring-0 dark:bg-transparent"
+          />
+          {/* bottom controls row: attach + slash chip + Web on the left, Send/Stop on the right */}
+          <div className="flex items-center gap-1.5 px-2 pb-2 pt-0.5">
+            <input ref={fileInputRef} type="file" multiple className="hidden" onChange={onPickFiles} />
+            <button
+              type="button"
+              onClick={() => fileInputRef.current?.click()}
+              disabled={disabled || busy || attachments.length >= MAX_ATTACHMENTS}
+              aria-label="Attach file"
+              title="Attach file"
+              className="inline-flex items-center justify-center rounded-full border border-border px-2.5 py-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground disabled:opacity-50 max-md:min-h-[36px] max-md:min-w-[36px]"
             >
-              {queueing ? <ListPlus /> : <Send />}
-            </Button>
-          );
-        })()}
+              <Paperclip className="size-3.5" />
+            </button>
+            {slashItems.length > 0 && (
+              <button
+                ref={cmdChipRef}
+                type="button"
+                onMouseDown={(e) => e.stopPropagation()}
+                onClick={() => setCmdMenuOpen((v) => !v)}
+                aria-expanded={cmdMenuOpen}
+                aria-label="Slash commands"
+                title="Slash commands"
+                className="inline-flex items-center gap-1.5 rounded-full border border-border px-2.5 py-1 text-xs text-muted-foreground transition-colors hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground max-md:min-h-[36px] max-md:min-w-[36px]"
+              >
+                <SquareSlash className="size-3.5" />
+                <span className="max-md:hidden">{slashItems.length}</span>
+              </button>
+            )}
+            {sessionId && (
+              <button
+                type="button"
+                onClick={async () => {
+                  // v1.9 tri-state collapses to two on toggle; null (inherit) → on.
+                  const next = webSearchEnabled === true ? false : true;
+                  try {
+                    await api.sessions.update(sessionId, { web_search_enabled: next });
+                  } catch (err) {
+                    toast.error(err instanceof Error ? err.message : 'failed to toggle web search');
+                  }
+                }}
+                aria-pressed={webSearchEnabled === true}
+                title="Web search & fetch"
+                className={`inline-flex items-center gap-1.5 rounded-full border px-2.5 py-1 text-xs transition-colors max-md:min-h-[36px] ${
+                  webSearchEnabled === true
+                    ? 'border-primary/40 bg-primary/10 text-primary'
+                    : 'border-border text-muted-foreground hover:bg-muted hover:text-foreground'
+                }`}
+              >
+                <Globe className="size-3.5" />
+                Web
+              </button>
+            )}
+            <div className="flex-1" />
+            {(() => {
+              const hasContent = value.trim().length > 0 || attachments.length > 0;
+              // While generating with an empty draft, the button stops generation.
+              if (generating && onStop && !hasContent) {
+                return (
+                  <Button
+                    onClick={() => void onStop()}
+                    size="icon"
+                    variant="outline"
+                    aria-label="Stop generating"
+                    title="Stop generating"
+                  >
+                    <Square className="fill-current size-3.5" />
+                  </Button>
+                );
+              }
+              // With a draft, submit. While generating the caller queues it, so the
+              // button reads as Queue; otherwise it's a normal Send.
+              const queueing = !!generating && hasContent;
+              return (
+                <Button
+                  onClick={() => void submit()}
+                  disabled={disabled || busy || !hasContent}
+                  size="icon"
+                  variant={queueing ? 'secondary' : 'default'}
+                  aria-label={queueing ? 'Queue message' : 'Send'}
+                  title={queueing ? 'Queue message' : 'Send'}
+                >
+                  {queueing ? <ListPlus /> : <Send />}
+                </Button>
+              );
+            })()}
+          </div>
+        </div>
       </div>
       </div>
       <AttachmentPreviewModal
@@ -714,6 +754,21 @@ export function ChatInput({ disabled, projectId, agentId, onAgentChange, session
           emptyLabel={slashGroups ? 'No commands available' : 'No skills available'}
         />
       )}
+      {/* Slash-commands chip menu (click-opened); anchored to the chip. */}
+      {cmdMenuOpen && slashItems.length > 0 && (
+        <SlashCommandPicker
+          query=""
+          items={slashItems}
+          groups={slashGroups}
+          inputRef={cmdChipRef}
+          onSelect={(name) => {
+            setCmdMenuOpen(false);
+            handleSlashSelect(name);
+          }}
+          onClose={() => setCmdMenuOpen(false)}
+          emptyLabel={slashGroups ? 'No commands available' : 'No skills available'}
+        />
+      )}
     </div>
   );
 }

apps/web/src/components/ChatTabBar.tsx

@@ -1,7 +1,8 @@
 import { useState } from 'react';
-import { Code, Columns2, History, MessageSquare, Plus, RotateCcw, Terminal, X } from 'lucide-react';
+import { Code, History, MessageSquare, X } from 'lucide-react';
 import type { Chat, WorkspacePane } from '@/api/types';
 import { StatusDot } from '@/components/StatusDot';
+import { PaneHeaderActions } from '@/components/PaneHeaderActions';
 import {
   ContextMenu,
   ContextMenuContent,
@@ -9,12 +10,6 @@ import {
   ContextMenuSeparator,
   ContextMenuTrigger,
 } from '@/components/ui/context-menu';
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuTrigger,
-} from '@/components/ui/dropdown-menu';
 import { useLongPress } from '@/hooks/useLongPress';
 import { sessionEvents } from '@/hooks/sessionEvents';
 import { cn } from '@/lib/utils';
@@ -22,6 +17,9 @@ import { cn } from '@/lib/utils';
 interface Props {
   pane: WorkspacePane;
   tabs: Chat[];
+  // Host pane kind — 'coder' shows the Code glyph + routes the "+" to a new
+  // BooCode tab. Defaults to 'chat' (the BooChat tab bar).
+  tabKind?: 'chat' | 'coder';
   // v2.6.x (Batch 3a): stable session-scoped tab number per chat id. Keyed by
   // chat.id, NEVER by tab position.
   tabNumbers: Record<string, number>;
@@ -41,6 +39,7 @@ interface Props {
 export function ChatTabBar({
   pane,
   tabs,
+  tabKind = 'chat',
   tabNumbers,
   onSwitchTab,
   onRemoveTab,
@@ -56,6 +55,8 @@ export function ChatTabBar({
 }: Props) {
   const [renamingId, setRenamingId] = useState<string | null>(null);
   const [renameValue, setRenameValue] = useState('');
+  const TabIcon = tabKind === 'coder' ? Code : MessageSquare;
+  const newLabel = tabKind === 'coder' ? 'New BooCode' : 'New chat';
 
   // Long-press: dispatch a synthetic contextmenu event on the tab so the
   // existing Radix ContextMenuTrigger opens at the touch coordinates. Works
@@ -109,7 +110,7 @@ export function ChatTabBar({
                     : 'bg-muted/30 text-muted-foreground hover:bg-muted/60'
                 )}
               >
-                <MessageSquare size={12} className="shrink-0" />
+                <TabIcon size={12} className="shrink-0" />
                 <StatusDot chatId={chat.id} />
                 {renamingId === chat.id ? (
                   <input
@@ -147,7 +148,7 @@ export function ChatTabBar({
             </ContextMenuTrigger>
             <ContextMenuContent>
               <ContextMenuItem onSelect={onNewTab}>
-                New chat
+                {newLabel}
               </ContextMenuItem>
               <ContextMenuItem
                 onSelect={() =>
@@ -191,90 +192,16 @@ export function ChatTabBar({
         </div>
       )}
 
-      <div className="flex items-center ml-auto gap-0.5 px-1 shrink-0">
-        <DropdownMenu>
-          <DropdownMenuTrigger asChild>
-            <button
-              type="button"
-              className="inline-flex items-center justify-center p-1 rounded text-muted-foreground hover:bg-muted hover:text-foreground max-md:min-h-[44px] max-md:min-w-[44px]"
-              aria-label="New chat, terminal, or coder"
-              title="New chat / terminal / coder"
-            >
-              <Plus size={12} />
-            </button>
-          </DropdownMenuTrigger>
-          <DropdownMenuContent align="end" className="w-fit">
-            {/* New BooChat opens a tab in THIS pane; terminal/coder can't be
-                tabs, so they split into a new pane (matches the Split menu). */}
-            <DropdownMenuItem onSelect={onNewTab}>
-              <MessageSquare size={14} /> New BooChat
-            </DropdownMenuItem>
-            <DropdownMenuItem onSelect={() => onSplitPane('terminal')}>
-              <Terminal size={14} /> New BooTerm
-            </DropdownMenuItem>
-            <DropdownMenuItem onSelect={() => onSplitPane('coder')}>
-              <Code size={14} /> New BooCode
-            </DropdownMenuItem>
-          </DropdownMenuContent>
-        </DropdownMenu>
-        <DropdownMenu>
-          <DropdownMenuTrigger asChild>
-            <button
-              type="button"
-              className="inline-flex items-center justify-center p-1 rounded text-muted-foreground hover:bg-muted hover:text-foreground max-md:min-h-[44px] max-md:min-w-[44px]"
-              aria-label="Split pane"
-              title="Split pane"
-            >
-              <Columns2 size={12} />
-            </button>
-          </DropdownMenuTrigger>
-          <DropdownMenuContent align="end" className="w-fit">
-            <DropdownMenuItem onSelect={() => onSplitPane('chat')}>
-              <MessageSquare size={14} /> New BooChat
-            </DropdownMenuItem>
-            <DropdownMenuItem onSelect={() => onSplitPane('terminal')}>
-              <Terminal size={14} /> New BooTerm
-            </DropdownMenuItem>
-            <DropdownMenuItem onSelect={() => onSplitPane('coder')}>
-              <Code size={14} /> New BooCode
-            </DropdownMenuItem>
-          </DropdownMenuContent>
-        </DropdownMenu>
-        {onReopenPane && (
-          <button
-            type="button"
-            onClick={onReopenPane}
-            className="inline-flex items-center justify-center p-1 rounded text-muted-foreground hover:bg-muted hover:text-foreground max-md:min-h-[44px] max-md:min-w-[44px]"
-            aria-label="Reopen closed pane"
-            title="Reopen closed pane"
-          >
-            <RotateCcw size={12} />
-          </button>
-        )}
-        <button
-          type="button"
-          onClick={onShowHistory}
-          className={cn(
-            'inline-flex items-center justify-center p-1 rounded text-muted-foreground hover:bg-muted hover:text-foreground max-md:min-h-[44px] max-md:min-w-[44px]',
-            pane.kind === 'empty' && 'text-foreground bg-muted/50'
-          )}
-          aria-label="Session history"
-          title="Session history"
-        >
-          <History size={12} />
-        </button>
-        {onRemovePane && (
-          <button
-            type="button"
-            onClick={onRemovePane}
-            className="inline-flex items-center justify-center p-1 rounded text-muted-foreground hover:bg-muted hover:text-foreground max-md:min-h-[44px] max-md:min-w-[44px]"
-            aria-label="Close pane"
-            title="Close pane"
-          >
-            <X size={12} />
-          </button>
-        )}
-      </div>
+      <PaneHeaderActions
+        className="ml-auto px-1"
+        onNewTab={onNewTab}
+        tabKind={tabKind}
+        onSplitPane={onSplitPane}
+        onReopenPane={onReopenPane}
+        onShowHistory={onShowHistory}
+        onRemovePane={onRemovePane}
+        historyActive={pane.kind === 'empty'}
+      />
     </div>
   );
 }

apps/web/src/components/ContextBar.tsx

@@ -19,18 +19,24 @@ interface Props {
 // the same boundaries the server's auto-compaction triggers.
 const COMPACTION_BUFFER = 20_000;
 
-// Walk newest-first; first message with both ctx_used and ctx_max non-null
-// AND ctx_max > 0 wins. Older messages may have ctx_used but missing ctx_max
-// (early v1 before llama-swap's n_ctx capture worked) — skip them and keep
-// walking. Returns null when no usable pair exists in the chat.
+// Take the latest ctx_used and the latest ctx_max INDEPENDENTLY (newest-first).
+// They needn't be on the same message: ctx_max is the model's context window — a
+// constant per model — while some agents report it only intermittently (the claude
+// SDK populates modelUsage.contextWindow on some turns, not all) yet report
+// ctx_used every turn. Pairing the latest of each gives a correct used/max even
+// when the most recent turn omitted the window. Native BooChat sets both on the
+// same assistant message, so this is identical there. Returns null until BOTH a
+// used and a positive max have been seen at least once.
 function latestPair(messages: Message[]): { used: number; max: number } | null {
+  let used: number | null = null;
+  let max: number | null = null;
   for (let i = messages.length - 1; i >= 0; i--) {
     const m = messages[i]!;
-    if (m.ctx_used == null || m.ctx_max == null) continue;
-    if (m.ctx_max <= 0) continue;
-    return { used: m.ctx_used, max: m.ctx_max };
+    if (used === null && m.ctx_used != null) used = m.ctx_used;
+    if (max === null && m.ctx_max != null && m.ctx_max > 0) max = m.ctx_max;
+    if (used !== null && max !== null) break;
   }
-  return null;
+  return used !== null && max !== null ? { used, max } : null;
 }
 
 interface ColorTier {

apps/web/src/components/MessageBubble.tsx

@@ -6,6 +6,7 @@ import type { Chat, ErrorReason, Message } from '@/api/types';
 import { api } from '@/api/client';
 import { sessionEvents } from '@/hooks/sessionEvents';
 import { sendToTerminal, terminalsRegistry, type TerminalRegistration } from '@/lib/events';
+import { shortenModelName } from '@/lib/modelName';
 import { CapHitSentinel } from './CapHitSentinel';
 import { DoomLoopSentinel } from './DoomLoopSentinel';
 import { MarkdownRenderer } from './MarkdownRenderer';
@@ -608,12 +609,12 @@ function SummaryCard({ message }: { message: Message }) {
 
 // Collapsible "Thinking" block for assistant reasoning. Fed by either
 // reasoning_text (coder wire / live reasoning_delta stream) or reasoning_parts
-// (native inference, persisted from message_parts). Auto-expands while the turn
-// is still streaming so the user watches it think (Paseo-style), then stays
-// where the user left it once the turn completes — initial state is captured
-// once at mount, so we never fight a manual collapse on later re-renders.
+// (native inference, persisted from message_parts). Starts COLLAPSED to start
+// (a quiet chip) — for native BooChat/BooCode and the external agents (opencode,
+// claude SDK) alike — so the transcript stays tidy; click to expand. The
+// `streaming` pulse still animates while the turn runs.
 function ReasoningBlock({ text, streaming }: { text: string; streaming: boolean }) {
-  const [expanded, setExpanded] = useState(() => streaming);
+  const [expanded, setExpanded] = useState(false);
   return (
     <div className="max-w-[90%] rounded-lg border bg-muted/30 text-sm">
       <button
@@ -768,7 +769,7 @@ export function MessageBubble({
     return (
       <div className="group flex flex-col items-end gap-1">
         <SendToTerminalMenu>
-          <div className="max-w-[80%] rounded-lg bg-primary text-primary-foreground px-3 py-2 text-sm whitespace-pre-wrap break-words min-w-0">
+          <div className="boo-user-bubble max-w-[80%] rounded-lg bg-primary text-primary-foreground px-3 py-2 text-sm whitespace-pre-wrap break-words min-w-0">
             {message.content}
           </div>
         </SendToTerminalMenu>
@@ -782,6 +783,8 @@ export function MessageBubble({
   // v1.13.7: match the MessageList.flatten trim guard so a whitespace-only
   // assistant turn doesn't render an empty bubble + dangling ActionRow.
   const hasContent = message.content.trim().length > 0;
+  // model-attribution chip: short label for the model that produced this turn.
+  const modelLabel = shortenModelName(message.model);
   // Reasoning arrives as a pre-joined string (coder wire) or as parts (native
   // inference). Read whichever is present; loose ?? chain tolerates the coder
   // shape where reasoning_parts is undefined (see CLAUDE.md null-guard note).
@@ -823,6 +826,14 @@ export function MessageBubble({
           )}
         </div>
       )}
+      {!isStreaming && (modelLabel || null) && (
+        <span
+          className="inline-flex w-fit items-center rounded-full border border-primary/25 bg-primary/10 px-2 py-0.5 text-[10px] font-mono text-primary/90"
+          title={message.model ?? undefined}
+        >
+          {modelLabel}
+        </span>
+      )}
       {!isStreaming && <StatsLine message={message} />}
       {!isStreaming && hasContent && (
         <ActionRow

apps/web/src/components/PaneHeaderActions.tsx

@@ -0,0 +1,148 @@
+import { Code, Columns2, History, MessageSquare, Plus, RotateCcw, Terminal, X } from 'lucide-react';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { cn } from '@/lib/utils';
+
+// Shared pane-header action cluster: + (new) / Split / Reopen-closed-pane /
+// Session history / Close. Rendered in the chat tab bar (ChatTabBar) and the
+// desktop coder + terminal pane headers (Workspace) so all pane kinds share one
+// control set. Extracted to avoid a divergent copy per header.
+interface Props {
+  // When provided, the "+" menu item matching `tabKind` opens an in-pane tab
+  // (e.g. chat panes: New BooChat → tab; coder panes: New BooCode → tab). Every
+  // OTHER kind splits into a new pane. When onNewTab is omitted (terminal
+  // panes, which can't host tabs) all three items split.
+  onNewTab?: () => void;
+  // The host pane's own kind — the "+" item of this kind becomes "new tab".
+  // Defaults to 'chat' for back-compat with the chat tab bar.
+  tabKind?: 'chat' | 'terminal' | 'coder';
+  onSplitPane: (kind: 'chat' | 'terminal' | 'coder') => void;
+  onReopenPane?: () => void;
+  onShowHistory: () => void;
+  onRemovePane?: () => void;
+  // Highlights the History button when the pane is showing the landing page.
+  historyActive?: boolean;
+  // Positioning/spacing supplied by the parent (e.g. "ml-auto px-1").
+  className?: string;
+}
+
+const BTN =
+  'inline-flex items-center justify-center p-1 rounded text-muted-foreground hover:bg-muted hover:text-foreground max-md:min-h-[44px] max-md:min-w-[44px]';
+
+export function PaneHeaderActions({
+  onNewTab,
+  tabKind = 'chat',
+  onSplitPane,
+  onReopenPane,
+  onShowHistory,
+  onRemovePane,
+  historyActive,
+  className,
+}: Props) {
+  // The "+" item of the host pane's own kind adds a tab; every other kind
+  // splits into a new pane. Falls back to split when onNewTab is absent.
+  const newOrSplit = (kind: 'chat' | 'terminal' | 'coder') =>
+    onNewTab && tabKind === kind ? onNewTab : () => onSplitPane(kind);
+  return (
+    <div className={cn('flex items-center gap-0.5 shrink-0', className)}>
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <button
+            type="button"
+            onClick={(e) => e.stopPropagation()}
+            className={BTN}
+            aria-label="New chat, terminal, or coder"
+            title="New chat / terminal / coder"
+          >
+            <Plus size={12} />
+          </button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end" className="w-fit">
+          {/* The item matching the host pane's kind opens an in-pane tab; the
+              others split into a new pane. (tabKind defaults to 'chat'.) */}
+          <DropdownMenuItem onSelect={newOrSplit('chat')}>
+            <MessageSquare size={14} /> New BooChat
+          </DropdownMenuItem>
+          <DropdownMenuItem onSelect={newOrSplit('terminal')}>
+            <Terminal size={14} /> New BooTerm
+          </DropdownMenuItem>
+          <DropdownMenuItem onSelect={newOrSplit('coder')}>
+            <Code size={14} /> New BooCode
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <button
+            type="button"
+            onClick={(e) => e.stopPropagation()}
+            className={cn(BTN, 'max-md:hidden')}
+            aria-label="Split pane"
+            title="Split pane"
+          >
+            <Columns2 size={12} />
+          </button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end" className="w-fit">
+          <DropdownMenuItem onSelect={() => onSplitPane('chat')}>
+            <MessageSquare size={14} /> New BooChat
+          </DropdownMenuItem>
+          <DropdownMenuItem onSelect={() => onSplitPane('terminal')}>
+            <Terminal size={14} /> New BooTerm
+          </DropdownMenuItem>
+          <DropdownMenuItem onSelect={() => onSplitPane('coder')}>
+            <Code size={14} /> New BooCode
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+
+      {onReopenPane && (
+        <button
+          type="button"
+          onClick={(e) => {
+            e.stopPropagation();
+            onReopenPane();
+          }}
+          className={cn(BTN, 'max-md:hidden')}
+          aria-label="Reopen closed pane"
+          title="Reopen closed pane"
+        >
+          <RotateCcw size={12} />
+        </button>
+      )}
+
+      <button
+        type="button"
+        onClick={(e) => {
+          e.stopPropagation();
+          onShowHistory();
+        }}
+        className={cn(BTN, 'max-md:hidden', historyActive && 'text-foreground bg-muted/50')}
+        aria-label="Session history"
+        title="Session history"
+      >
+        <History size={12} />
+      </button>
+
+      {onRemovePane && (
+        <button
+          type="button"
+          onClick={(e) => {
+            e.stopPropagation();
+            onRemovePane();
+          }}
+          className={BTN}
+          aria-label="Close pane"
+          title="Close pane"
+        >
+          <X size={12} />
+        </button>
+      )}
+    </div>
+  );
+}

apps/web/src/components/ProjectSidebar.tsx

@@ -3,6 +3,8 @@ import { NavLink, useLocation, useNavigate } from 'react-router-dom';
 import { ChevronRight, ExternalLink, Folder, MessageSquare, Plus, Settings as SettingsIcon, X, Code } from 'lucide-react';
 import { toast } from 'sonner';
 import { Button } from '@/components/ui/button';
+import mascot from '@/assets/brand/banner-mascot.png';
+import wordmark from '@/assets/brand/banner-wordmark.png';
 import { sessionEvents } from '@/hooks/sessionEvents';
 import {
   ContextMenu,
@@ -307,9 +309,22 @@ export function ProjectSidebar() {
 
   return (
     <aside className={asideCls}>
-      <div className="px-4 py-3 border-b flex items-center justify-between">
-        <NavLink to="/" className="font-semibold tracking-tight text-base">
-          BooCode
+      <div className="px-2 py-1 border-b flex items-center justify-between gap-1">
+        {/* BooCode brand banner: mascot badge + >_BooCode wordmark, big and
+            visible, on transparent backgrounds (no chip, no blend). */}
+        <NavLink to="/" aria-label="BooCode home" className="flex items-center gap-0.5 min-w-0 flex-1">
+          <img
+            src={mascot}
+            alt=""
+            draggable={false}
+            className="h-12 w-auto select-none shrink-0"
+          />
+          <img
+            src={wordmark}
+            alt="BooCode"
+            draggable={false}
+            className="h-12 w-auto select-none min-w-0 flex-1 object-contain object-left"
+          />
         </NavLink>
         <div className="flex items-center gap-1">
           <Button size="icon-sm" variant="ghost" onClick={() => setAddOpen(true)} aria-label="Add project">

apps/web/src/components/SessionLandingPage.tsx

@@ -1,7 +1,15 @@
 import { useCallback, useEffect, useState } from 'react';
-import { Archive, MessageSquare, RotateCcw } from 'lucide-react';
+import { Archive, Code, MessageSquare, RotateCcw, Terminal, Trash2 } from 'lucide-react';
 import { toast } from 'sonner';
 import { ChatInput } from '@/components/ChatInput';
+import { Button } from '@/components/ui/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
 import { api } from '@/api/client';
 import type { Chat } from '@/api/types';
 
@@ -22,6 +30,8 @@ interface Props {
   chats: Chat[];
   onOpenChat: (chatId: string) => void;
   onUnarchiveChat: (chatId: string) => Promise<void>;
+  onArchiveChat: (chatId: string) => Promise<void>;
+  onDeleteChat: (chatId: string) => Promise<void>;
 }
 
 function formatRelative(iso: string): string {
@@ -42,6 +52,16 @@ function byRecent(a: Chat, b: Chat): number {
   return (b.updated_at ?? '').localeCompare(a.updated_at ?? '');
 }
 
+// Pick the row icon by the chat's seed name: coder and terminal panes create
+// placeholder chats named 'BooCoder' / 'Terminal' (see useWorkspacePanes
+// chatNameForPaneKind + the coder chat-resolve). A name heuristic keeps this
+// frontend-only — matches ProjectSidebar's isCoderSessionName approach.
+function iconForChat(name: string | null) {
+  if (name === 'BooCoder') return Code;
+  if (name === 'Terminal') return Terminal;
+  return MessageSquare;
+}
+
 export function SessionLandingPage({
   projectId,
   sessionId,
@@ -53,9 +73,13 @@ export function SessionLandingPage({
   chats,
   onOpenChat,
   onUnarchiveChat,
+  onArchiveChat,
+  onDeleteChat,
 }: Props) {
   const [chatId, setChatId] = useState<string | null>(null);
   const [archived, setArchived] = useState<Chat[]>([]);
+  // Plain Cancel/Confirm delete (no type-to-confirm), mirroring ProjectSidebar.
+  const [deleteConfirm, setDeleteConfirm] = useState<{ id: string; name: string | null } | null>(null);
 
   // Archived chats aren't in the default (open-only) list, so fetch them. One
   // shot on session change — the history view is transient (pick a chat and
@@ -130,25 +154,52 @@ export function SessionLandingPage({
                     Conversations
                   </h3>
                   <div className="space-y-0.5 mb-4">
-                    {openChats.map((c) => (
-                      <button
-                        key={c.id}
-                        type="button"
-                        onClick={() => onOpenChat(c.id)}
-                        className="w-full flex items-center gap-2 text-left px-2 py-1.5 rounded hover:bg-muted text-sm max-md:min-h-[44px]"
-                      >
-                        <MessageSquare size={14} className="shrink-0 text-muted-foreground" />
-                        <span className="truncate shrink-0 max-w-[45%]">{c.name ?? 'New chat'}</span>
-                        {c.last_message_preview && (
-                          <span className="truncate flex-1 text-xs text-muted-foreground hidden sm:block">
-                            {c.last_message_preview}
-                          </span>
-                        )}
-                        <span className="shrink-0 ml-auto text-xs text-muted-foreground">
-                          {formatRelative(c.updated_at)}
-                        </span>
-                      </button>
-                    ))}
+                    {openChats.map((c) => {
+                      const Icon = iconForChat(c.name);
+                      return (
+                        <div
+                          key={c.id}
+                          className="group/row flex items-center gap-2 px-2 py-1.5 rounded hover:bg-muted text-sm max-md:min-h-[44px]"
+                        >
+                          <button
+                            type="button"
+                            onClick={() => onOpenChat(c.id)}
+                            className="flex items-center gap-2 flex-1 min-w-0 text-left"
+                          >
+                            <Icon size={14} className="shrink-0 text-muted-foreground" />
+                            <span className="truncate shrink-0 max-w-[45%]">{c.name ?? 'New chat'}</span>
+                            {c.last_message_preview && (
+                              <span className="truncate flex-1 text-xs text-muted-foreground hidden sm:block">
+                                {c.last_message_preview}
+                              </span>
+                            )}
+                            <span className="shrink-0 ml-auto text-xs text-muted-foreground">
+                              {formatRelative(c.updated_at)}
+                            </span>
+                          </button>
+                          <div className="shrink-0 flex items-center gap-0.5 opacity-0 group-hover/row:opacity-100 focus-within:opacity-100 transition-opacity">
+                            <button
+                              type="button"
+                              onClick={(e) => { e.stopPropagation(); void onArchiveChat(c.id); }}
+                              className="inline-flex items-center justify-center size-7 rounded text-muted-foreground hover:bg-muted hover:text-foreground max-md:size-9"
+                              aria-label="Archive chat"
+                              title="Archive"
+                            >
+                              <Archive size={14} />
+                            </button>
+                            <button
+                              type="button"
+                              onClick={(e) => { e.stopPropagation(); setDeleteConfirm({ id: c.id, name: c.name }); }}
+                              className="inline-flex items-center justify-center size-7 rounded text-muted-foreground hover:bg-destructive/20 hover:text-destructive max-md:size-9"
+                              aria-label="Delete chat"
+                              title="Delete"
+                            >
+                              <Trash2 size={14} />
+                            </button>
+                          </div>
+                        </div>
+                      );
+                    })}
                   </div>
                 </>
               )}
@@ -159,21 +210,34 @@ export function SessionLandingPage({
                   </h3>
                   <div className="space-y-0.5">
                     {archivedChats.map((c) => (
-                      <button
+                      <div
                         key={c.id}
-                        type="button"
-                        onClick={() => void restoreAndOpen(c.id)}
-                        title="Restore and open"
-                        className="group/arch w-full flex items-center gap-2 text-left px-2 py-1.5 rounded hover:bg-muted text-sm text-muted-foreground max-md:min-h-[44px]"
+                        className="group/arch flex items-center gap-2 px-2 py-1.5 rounded hover:bg-muted text-sm text-muted-foreground max-md:min-h-[44px]"
                       >
-                        <Archive size={14} className="shrink-0" />
-                        <span className="truncate flex-1">{c.name ?? 'New chat'}</span>
-                        <span className="shrink-0 text-xs">{formatRelative(c.updated_at)}</span>
-                        <RotateCcw
-                          size={13}
-                          className="shrink-0 opacity-0 group-hover/arch:opacity-100"
-                        />
-                      </button>
+                        <button
+                          type="button"
+                          onClick={() => void restoreAndOpen(c.id)}
+                          title="Restore and open"
+                          className="flex items-center gap-2 flex-1 min-w-0 text-left"
+                        >
+                          <Archive size={14} className="shrink-0" />
+                          <span className="truncate flex-1">{c.name ?? 'New chat'}</span>
+                          <span className="shrink-0 text-xs">{formatRelative(c.updated_at)}</span>
+                          <RotateCcw
+                            size={13}
+                            className="shrink-0 opacity-0 group-hover/arch:opacity-100"
+                          />
+                        </button>
+                        <button
+                          type="button"
+                          onClick={(e) => { e.stopPropagation(); setDeleteConfirm({ id: c.id, name: c.name }); }}
+                          className="shrink-0 inline-flex items-center justify-center size-7 rounded hover:bg-destructive/20 hover:text-destructive max-md:size-9 opacity-0 group-hover/arch:opacity-100 focus-within:opacity-100 transition-opacity"
+                          aria-label="Delete chat"
+                          title="Delete"
+                        >
+                          <Trash2 size={14} />
+                        </button>
+                      </div>
                     ))}
                   </div>
                 </>
@@ -195,6 +259,31 @@ export function SessionLandingPage({
         messages={[]}
         modelContextLimit={null}
       />
+      <Dialog
+        open={deleteConfirm !== null}
+        onOpenChange={(open) => { if (!open) setDeleteConfirm(null); }}
+      >
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Delete chat?</DialogTitle>
+            <DialogDescription>
+              Permanently deletes "{deleteConfirm?.name ?? 'New chat'}" and all its messages. This cannot be undone.
+            </DialogDescription>
+          </DialogHeader>
+          <div className="flex gap-2 justify-end pt-2">
+            <Button variant="outline" onClick={() => setDeleteConfirm(null)}>Cancel</Button>
+            <Button
+              variant="destructive"
+              onClick={() => {
+                if (deleteConfirm) void onDeleteChat(deleteConfirm.id);
+                setDeleteConfirm(null);
+              }}
+            >
+              Delete
+            </Button>
+          </div>
+        </DialogContent>
+      </Dialog>
     </div>
   );
 }

apps/web/src/components/ToolCallLine.tsx

@@ -149,8 +149,13 @@ export function ToolCallLine({ run, insideGroup }: Props) {
         onClick={() => setOpen((v) => !v)}
         className="flex items-center gap-1.5 w-full text-left hover:bg-muted/40 rounded px-1 py-0.5 -mx-1"
       >
+        {/* BooCode 2.0: glowing activity indicator (was ↳ / >_) */}
         {!insideGroup && (
-          <span className="text-muted-foreground/60 select-none shrink-0">↳</span>
+          <span
+            className="size-1.5 rounded-full bg-primary shrink-0"
+            style={{ boxShadow: '0 0 6px var(--primary)' }}
+            aria-hidden
+          />
         )}
         <ChevronRight
           className={`size-3 text-muted-foreground/60 shrink-0 transition-transform ${open ? 'rotate-90' : ''}`}

apps/web/src/components/Workspace.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useMemo, useState } from 'react';
-import { MessageSquare, Terminal, Code, Clipboard, Plus, X } from 'lucide-react';
+import { Terminal, Clipboard } from 'lucide-react';
 import { api } from '@/api/client';
 import type { Chat, Project, Session, WorkspacePane } from '@/api/types';
 import { MAX_PANES, activePaneChatId, type UseWorkspacePanesResult } from '@/hooks/useWorkspacePanes';
@@ -13,13 +13,8 @@ import { CoderPane } from '@/components/panes/CoderPane';
 import { MarkdownArtifactPane } from '@/components/MarkdownArtifactPane';
 import { HtmlArtifactPane } from '@/components/HtmlArtifactPane';
 import { ChatTabBar } from '@/components/ChatTabBar';
+import { PaneHeaderActions } from '@/components/PaneHeaderActions';
 import { SessionLandingPage } from '@/components/SessionLandingPage';
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuTrigger,
-} from '@/components/ui/dropdown-menu';
 import { cn } from '@/lib/utils';
 
 interface Props {
@@ -65,6 +60,7 @@ export function Workspace({
     closeAllTabs,
     showLandingPage,
     addSplitPane,
+    createCoderTab,
     removePane,
     reopenPane,
     hasClosedPanes,
@@ -219,46 +215,27 @@ export function Workspace({
                   onRemovePane={panes.length > 1 ? () => removePane(idx) : undefined}
                 />
               )}
+              {/* Coder panes host BooCode tabs (one chat = one agent context,
+                  all sharing the session worktree). "+" adds a tab; the split
+                  button adds a pane. Same tab strip as chat panes (tabKind). */}
               {isCoder && !isMobile && (
-                <div className="flex items-center gap-1 border-b border-border px-2 py-1 shrink-0">
-                  <Code size={12} className="text-muted-foreground" />
-                  <span className="text-xs text-muted-foreground">BooCode</span>
-                  <div className="ml-auto flex items-center gap-1">
-                    <DropdownMenu>
-                      <DropdownMenuTrigger asChild>
-                        <button
-                          type="button"
-                          onClick={(e) => e.stopPropagation()}
-                          className="inline-flex items-center justify-center size-5 rounded text-muted-foreground hover:bg-muted hover:text-foreground"
-                          aria-label="New pane"
-                        >
-                          <Plus size={12} />
-                        </button>
-                      </DropdownMenuTrigger>
-                      <DropdownMenuContent align="end" className="w-fit">
-                        <DropdownMenuItem onSelect={() => onAddPane('chat')}>
-                          <MessageSquare size={14} /> New BooChat
-                        </DropdownMenuItem>
-                        <DropdownMenuItem onSelect={() => onAddPane('terminal')}>
-                          <Terminal size={14} /> New BooTerm
-                        </DropdownMenuItem>
-                        <DropdownMenuItem onSelect={() => onAddPane('coder')}>
-                          <Code size={14} /> New BooCode
-                        </DropdownMenuItem>
-                      </DropdownMenuContent>
-                    </DropdownMenu>
-                    {panes.length > 1 && (
-                      <button
-                        type="button"
-                        onClick={(e) => { e.stopPropagation(); removePane(idx); }}
-                        className="inline-flex items-center justify-center size-5 rounded text-muted-foreground hover:bg-muted hover:text-foreground"
-                        aria-label="Close pane"
-                      >
-                        <X size={12} />
-                      </button>
-                    )}
-                  </div>
-                </div>
+                <ChatTabBar
+                  pane={pane}
+                  tabs={chatsForPane(pane)}
+                  tabKind="coder"
+                  tabNumbers={tabNumbers}
+                  onSwitchTab={(tabIdx) => switchTab(idx, tabIdx)}
+                  onRemoveTab={(chatId) => removeTab(idx, chatId)}
+                  onCloseOthers={(chatId) => closeOtherTabs(idx, chatId)}
+                  onCloseToRight={(chatId) => closeTabsToRight(idx, chatId)}
+                  onCloseAll={() => closeAllTabs(idx)}
+                  onNewTab={() => void createCoderTab(idx)}
+                  onSplitPane={(kind) => onAddPane(kind)}
+                  onReopenPane={hasClosedPanes ? reopenPane : undefined}
+                  onShowHistory={() => showLandingPage(idx)}
+                  onRename={renameChat}
+                  onRemovePane={panes.length > 1 ? () => removePane(idx) : undefined}
+                />
               )}
               {isTerminal && (
                 <div className="flex items-center gap-2 border-b border-border bg-muted/30 px-2 py-1 shrink-0">
@@ -266,61 +243,31 @@ export function Workspace({
                   <span className="text-xs text-muted-foreground">
                     {terminalLabels.get(pane.id) ?? 'Terminal'}
                   </span>
-                  <DropdownMenu>
-                    <DropdownMenuTrigger asChild>
-                      <button
-                        type="button"
-                        onClick={(e) => e.stopPropagation()}
-                        className="ml-auto inline-flex items-center justify-center size-5 rounded text-muted-foreground hover:bg-muted hover:text-foreground max-md:size-7"
-                        aria-label="New pane"
-                        title="New pane"
-                      >
-                        <Plus size={12} />
-                      </button>
-                    </DropdownMenuTrigger>
-                    <DropdownMenuContent align="end" className="w-fit">
-                      <DropdownMenuItem onSelect={() => onAddPane('chat')}>
-                        <MessageSquare size={14} /> New BooChat
-                      </DropdownMenuItem>
-                      <DropdownMenuItem onSelect={() => onAddPane('terminal')}>
-                        <Terminal size={14} /> New BooTerm
-                      </DropdownMenuItem>
-                      <DropdownMenuItem onSelect={() => onAddPane('coder')}>
-                        <Code size={14} /> New BooCode
-                      </DropdownMenuItem>
-                    </DropdownMenuContent>
-                  </DropdownMenu>
-                  {/* v1.10.4: iOS Safari restricts navigator.clipboard.readText
-                      outside direct user gestures. A real button click IS a
-                      gesture, so this works where keystroke-driven paste may
-                      not on iOS. The action lives in TerminalPane behind the
-                      registry's paste() callback. */}
-                  <button
-                    type="button"
-                    onClick={(e) => {
-                      e.stopPropagation();
-                      terminalsRegistry.get(pane.id)?.paste();
-                    }}
-                    className="inline-flex items-center justify-center size-5 rounded text-muted-foreground hover:bg-muted hover:text-foreground max-md:size-7"
-                    aria-label="Paste from clipboard"
-                    title="Paste from clipboard"
-                  >
-                    <Clipboard size={12} />
-                  </button>
-                  {panes.length > 1 && (
+                  <div className="ml-auto flex items-center gap-0.5">
+                    {/* v1.10.4: iOS Safari restricts navigator.clipboard.readText
+                        outside direct user gestures. A real button click IS a
+                        gesture, so this works where keystroke-driven paste may
+                        not on iOS. The action lives in TerminalPane behind the
+                        registry's paste() callback. */}
                     <button
                       type="button"
                       onClick={(e) => {
                         e.stopPropagation();
-                        removePane(idx);
+                        terminalsRegistry.get(pane.id)?.paste();
                       }}
-                      className="inline-flex items-center justify-center size-5 rounded text-muted-foreground hover:bg-muted hover:text-foreground max-md:size-7"
-                      aria-label="Close terminal pane"
-                      title="Close terminal pane"
+                      className="inline-flex items-center justify-center p-1 rounded text-muted-foreground hover:bg-muted hover:text-foreground max-md:min-h-[44px] max-md:min-w-[44px]"
+                      aria-label="Paste from clipboard"
+                      title="Paste from clipboard"
                     >
-                      <X size={12} />
+                      <Clipboard size={12} />
                     </button>
-                  )}
+                    <PaneHeaderActions
+                      onSplitPane={onAddPane}
+                      onReopenPane={hasClosedPanes ? reopenPane : undefined}
+                      onShowHistory={() => showLandingPage(idx)}
+                      onRemovePane={panes.length > 1 ? () => removePane(idx) : undefined}
+                    />
+                  </div>
                 </div>
               )}
             </div>
@@ -395,6 +342,8 @@ export function Workspace({
                   chats={chats}
                   onOpenChat={(chatId) => openChatInPane(idx, chatId)}
                   onUnarchiveChat={unarchiveChat}
+                  onArchiveChat={archiveChat}
+                  onDeleteChat={deleteChat}
                 />
               )}
             </div>

apps/web/src/components/panes/CoderMessageList.tsx

@@ -11,6 +11,7 @@ export interface CoderMessageWire {
   role: 'user' | 'assistant' | 'system';
   content: string;
   status?: 'streaming' | 'complete' | 'failed';
+  model?: string | null;
   reasoning_text?: string;
   tool_calls?: CoderToolCallWire[];
 }

apps/web/src/components/panes/CoderPane.tsx

@@ -18,6 +18,7 @@ import { mergeWireToolCall } from '@/lib/coder-tools';
 import { CoderMessageList, type CoderTimelineWire } from '@/components/panes/CoderMessageList';
 import { providerIcon, providerLabel } from '@/components/coder/providerIcons';
 import { refreshAgentSessions } from '@/hooks/useAgentSessions';
+import { useAgentStatus, type AgentStatus, type AgentStatusEntry } from '@/hooks/useAgentStatus';
 import { cn } from '@/lib/utils';
 
 // ---------------------------------------------------------------------------
@@ -29,6 +30,8 @@ interface CoderMessage {
   role: 'user' | 'assistant' | 'system';
   content: string;
   status?: 'streaming' | 'complete' | 'failed';
+  // model-attribution: which model produced this assistant message (chip).
+  model?: string | null;
   reasoning_text?: string;
   tool_calls?: Array<{
     id: string;
@@ -51,6 +54,46 @@ interface CoderToolMessage {
 
 type CoderTimelineMessage = CoderMessage | CoderToolMessage;
 
+// Per-chat agent-config cache (provider/model/mode/thinking). Keyed by chat id
+// so reopening or switching back to a chat restores the model that was loaded
+// last there. Per-device (localStorage) — a UI convenience, not authoritative.
+const DEFAULT_AGENT_CONFIG: AgentSessionConfig = {
+  provider: 'boocode',
+  model: '',
+  modeId: null,
+  thinkingOptionId: null,
+};
+function agentConfigKey(chatId: string | undefined): string | null {
+  return chatId ? `boocode.coder.config.${chatId}` : null;
+}
+function readCachedAgentConfig(chatId: string | undefined): AgentSessionConfig | null {
+  const key = agentConfigKey(chatId);
+  if (!key || typeof localStorage === 'undefined') return null;
+  try {
+    const raw = localStorage.getItem(key);
+    if (!raw) return null;
+    const c = JSON.parse(raw) as Partial<AgentSessionConfig>;
+    if (typeof c?.provider !== 'string') return null;
+    return {
+      provider: c.provider,
+      model: typeof c.model === 'string' ? c.model : '',
+      modeId: c.modeId ?? null,
+      thinkingOptionId: c.thinkingOptionId ?? null,
+    };
+  } catch {
+    return null;
+  }
+}
+function writeCachedAgentConfig(chatId: string | undefined, config: AgentSessionConfig): void {
+  const key = agentConfigKey(chatId);
+  if (!key || typeof localStorage === 'undefined') return;
+  try {
+    localStorage.setItem(key, JSON.stringify(config));
+  } catch {
+    /* quota / disabled storage — non-fatal */
+  }
+}
+
 interface PendingChange {
   id: string;
   file_path: string;
@@ -80,6 +123,14 @@ interface WsHandlers {
   onAssistantComplete?: () => void;
   onAgentCommands?: (taskId: string, commands: AgentCommand[]) => void;
   onConnectedChange?: (connected: boolean) => void;
+  // #10: normalized external-agent status (working|blocked|idle|error) for the
+  // (chat,agent) carried on the frame. CoderPane records it in a live map and
+  // feeds the active agent's status to AgentComposerBar's status dot.
+  onAgentStatus?: (
+    chatId: string,
+    agent: string,
+    entry: AgentStatusEntry,
+  ) => void;
 }
 
 type RawCoderMessage = {
@@ -88,6 +139,7 @@ type RawCoderMessage = {
   chat_id?: string;
   content?: string | null;
   status?: string | null;
+  model?: string | null;
   reasoning_text?: string;
   reasoning_parts?: Array<{ text?: string }> | null;
   tool_results?: {
@@ -135,6 +187,7 @@ function mapCoderTimelineRow(raw: RawCoderMessage): CoderTimelineMessage | null
     role: raw.role as CoderMessage['role'],
     content: raw.content ?? '',
     status: (raw.status ?? 'complete') as CoderMessage['status'],
+    ...(raw.model ? { model: raw.model } : {}),
     ...(reasoning_text ? { reasoning_text } : {}),
     ...(tool_calls?.length ? { tool_calls } : {}),
     ctx_used: raw.ctx_used ?? null,
@@ -244,6 +297,7 @@ function useCoderMessages(sessionId: string, chatId: string | undefined, handler
                 ? {
                     ...m,
                     status: 'complete' as const,
+                    model: (frame as any).model ?? (m as any).model ?? null,
                     ctx_used: (frame as any).ctx_used ?? (m as any).ctx_used ?? null,
                     ctx_max: (frame as any).ctx_max ?? (m as any).ctx_max ?? null,
                   }
@@ -326,6 +380,19 @@ function useCoderMessages(sessionId: string, chatId: string | undefined, handler
               description: c.description,
             })),
           );
+        } else if (frame.type === 'agent_status_updated') {
+          // #10: { chat_id, agent, status, reason?, at }. The chat_id guard
+          // above already dropped cross-chat frames; record per (chat,agent).
+          const chatId = (frame.chat_id ?? scopedChatId) as string | undefined;
+          const agent = frame.agent as string | undefined;
+          const status = frame.status as AgentStatus | undefined;
+          if (chatId && agent && status) {
+            handlersRef.current.onAgentStatus?.(chatId, agent, {
+              status,
+              ...(frame.reason ? { reason: frame.reason as string } : {}),
+              at: (frame.at as string) ?? new Date().toISOString(),
+            });
+          }
         }
       } catch {
         // ignore unparseable frames
@@ -564,12 +631,37 @@ export function CoderPane({
   onConnectedChange,
   onAgentLabelChange,
 }: Props) {
-  const [agentConfig, setAgentConfig] = useState<AgentSessionConfig>({
-    provider: 'boocode',
-    model: '',
-    modeId: null,
-    thinkingOptionId: null,
-  });
+  const [agentConfig, setAgentConfig] = useState<AgentSessionConfig>(
+    () => readCachedAgentConfig(chatId) ?? DEFAULT_AGENT_CONFIG,
+  );
+  // Restore the per-chat cached config when the chat changes. The ref guard
+  // skips the initial mount (lazy init already loaded it) + StrictMode double-runs.
+  const lastLoadedChatRef = useRef<string | undefined>(chatId);
+  useEffect(() => {
+    const prev = lastLoadedChatRef.current;
+    if (prev === chatId) return;
+    lastLoadedChatRef.current = chatId;
+    // undefined → real id: the pane just resolved its chat. A selection made
+    // while chatId was undefined could not be persisted (the key was null), so
+    // carry the current in-memory config into the new chat — and persist it —
+    // rather than clobbering the user's pick with DEFAULT on the cache miss.
+    if (prev === undefined && chatId) {
+      const cached = readCachedAgentConfig(chatId);
+      if (cached) setAgentConfig(cached);
+      else writeCachedAgentConfig(chatId, agentConfig);
+      return;
+    }
+    setAgentConfig(readCachedAgentConfig(chatId) ?? DEFAULT_AGENT_CONFIG);
+  }, [chatId, agentConfig]);
+  // Persist on user-driven changes only (not on the restore above), so switching
+  // chats never clobbers the new chat's cached config with the old one.
+  const handleAgentConfigChange = useCallback(
+    (next: AgentSessionConfig) => {
+      setAgentConfig(next);
+      writeCachedAgentConfig(chatId, next);
+    },
+    [chatId],
+  );
 
   useEffect(() => {
     const parts = [agentConfig.provider || 'boocode'];
@@ -642,6 +734,8 @@ export function CoderPane({
     return groups;
   }, [agentCommands, skillItems, agentConfig.provider]);
 
+  // #10: live normalized status per (chat,agent), reset on chat switch below.
+  const agentStatus = useAgentStatus();
   const { messages, setMessages, connected, loadMessages } = useCoderMessages(sessionId, chatId, {
     onConnectedChange,
     onPermissionRequested: (prompt) => {
@@ -661,7 +755,21 @@ export function CoderPane({
     onAgentCommands: (_taskId, commands) => {
       setLiveTaskCommands(commands);
     },
+    onAgentStatus: agentStatus.record,
   });
+
+  // Clear any stale status for the previous chat when the pane switches chats so
+  // a lingering working/blocked dot never carries into the next conversation.
+  useEffect(() => {
+    return () => agentStatus.reset(chatId);
+  }, [chatId, agentStatus]);
+
+  // The active agent's normalized status for this chat. null for native boocode
+  // (no external status published) or before any frame arrives — gates the dot.
+  const currentAgentStatus: AgentStatusEntry | null =
+    agentConfig.provider && agentConfig.provider !== 'boocode'
+      ? agentStatus.get(chatId, agentConfig.provider)
+      : null;
   const { changes, loading, refresh, approve, reject } = usePendingChanges(sessionId);
   const { checkpointMessageIds, refreshCheckpoints } = useCheckpoints(sessionId, chatId);
   const [input, setInput] = useState('');
@@ -689,13 +797,6 @@ export function CoderPane({
     }
   }, [messages, refresh, refreshCheckpoints, sessionId]);
 
-  // The §9b chip only shows once the chat has ≥1 prior turn (a completed
-  // assistant message). Hidden on a brand-new chat.
-  const hasPriorTurn = useMemo(
-    () => messages.some((m) => m.role === 'assistant' && (m as CoderMessage).status === 'complete'),
-    [messages],
-  );
-
   // Poll fallbacks when WS is disconnected (reconnect uses WS as source of truth)
   useEffect(() => {
     if (!activeTaskId || connected) return;
@@ -963,11 +1064,10 @@ export function CoderPane({
       <AgentComposerBar
         projectPath={projectPath}
         value={agentConfig}
-        onChange={setAgentConfig}
+        onChange={handleAgentConfigChange}
         onProviderCommandsChange={handleProviderCommandsChange}
         connected={connected}
-        sessionId={sessionId}
-        hasPriorTurn={hasPriorTurn}
+        agentStatus={currentAgentStatus}
       />
       {/* Chat area — BooChat-style timeline (text + tool runs as siblings) */}
       <div className="flex-1 min-h-0 flex flex-col">

apps/web/src/hooks/useAgentStatus.ts

@@ -0,0 +1,62 @@
+import { useCallback, useMemo, useState } from 'react';
+
+// Normalized external-agent status (#10). Consumed from the
+// `agent_status_updated` WS frame the coder backend publishes:
+//   { type: 'agent_status_updated'; chat_id; agent; status; reason?; at }
+// BooCoder collapses ~30 vendor lifecycle events into these four buckets:
+//   working  — turn in flight
+//   blocked  — waiting on a permission / approval
+//   idle     — clean completion
+//   error    — crash / failure
+export type AgentStatus = 'working' | 'blocked' | 'idle' | 'error';
+
+export interface AgentStatusEntry {
+  status: AgentStatus;
+  reason?: string;
+  at: string;
+}
+
+const key = (chatId: string, agent: string): string => `${chatId}:${agent}`;
+
+// Per-(chat,agent) live status map. The dot reflects the latest frame for the
+// active agent in the current chat; entries are reset when the chat switches so
+// a stale "working"/"blocked" from a previous chat never leaks into the next.
+export function useAgentStatus() {
+  const [map, setMap] = useState<Record<string, AgentStatusEntry>>({});
+
+  const record = useCallback(
+    (chatId: string, agent: string, entry: AgentStatusEntry) => {
+      setMap((prev) => ({ ...prev, [key(chatId, agent)]: entry }));
+    },
+    [],
+  );
+
+  // Drop every entry for a chat (called on chat switch). No-op when nothing
+  // matches so it's safe to call unconditionally from an effect.
+  const reset = useCallback((chatId: string | undefined) => {
+    setMap((prev) => {
+      if (!chatId) return prev;
+      const prefix = `${chatId}:`;
+      let changed = false;
+      const next: Record<string, AgentStatusEntry> = {};
+      for (const [k, v] of Object.entries(prev)) {
+        if (k.startsWith(prefix)) {
+          changed = true;
+          continue;
+        }
+        next[k] = v;
+      }
+      return changed ? next : prev;
+    });
+  }, []);
+
+  const get = useCallback(
+    (chatId: string | undefined, agent: string | undefined): AgentStatusEntry | null => {
+      if (!chatId || !agent) return null;
+      return map[key(chatId, agent)] ?? null;
+    },
+    [map],
+  );
+
+  return useMemo(() => ({ record, reset, get }), [record, reset, get]);
+}

apps/web/src/hooks/useSessionStream.ts

@@ -1,7 +1,7 @@
 import { useEffect, useRef, useState } from 'react';
 import { toast } from 'sonner';
 import type { Message, WsFrame } from '@/api/types';
-import { WsFrameSchema } from '@/api/ws-frames';
+import { WsFrameSchema } from '@boocode/contracts/ws-frames';
 import { api } from '@/api/client';
 import { sessionEvents } from './sessionEvents';
 import { recordUsage } from './useChatThroughput';
@@ -40,6 +40,7 @@ function applyFrame(state: State, frame: WsFrame): State {
         tokens_used: null,
         ctx_used: null,
         ctx_max: null,
+        model: null,
         started_at: null,
         finished_at: null,
         created_at: new Date().toISOString(),
@@ -105,6 +106,7 @@ function applyFrame(state: State, frame: WsFrame): State {
         tokens_used: null,
         ctx_used: null,
         ctx_max: null,
+        model: null,
         started_at: null,
         finished_at: null,
         created_at: new Date().toISOString(),
@@ -123,6 +125,7 @@ function applyFrame(state: State, frame: WsFrame): State {
               ...(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.model !== undefined ? { model: frame.model } : {}),
               // v1.8.2: cap-hit sentinels (and future stamped metadata) ride
               // in on this terminal frame so the reducer can attach it
               // without waiting for a refetch.
@@ -189,6 +192,12 @@ function applyFrame(state: State, frame: WsFrame): State {
       // duplicating async work inside a synchronous reducer.
       return state;
     }
+    case 'agent_status_updated': {
+      // agent-status-normalize (#10): coder-only frame consumed by CoderPane's
+      // own WS handler, not BooChat's native message reducer. No-op here to keep
+      // TS exhaustiveness satisfied (native sessions never emit it).
+      return state;
+    }
   }
 }
 

apps/web/src/hooks/useUserEvents.ts

@@ -1,5 +1,5 @@
 import { useEffect } from 'react';
-import { WsFrameSchema } from '@/api/ws-frames';
+import { WsFrameSchema } from '@boocode/contracts/ws-frames';
 import { sessionEvents } from './sessionEvents';
 import { createWsReconnectToast } from './wsReconnectToast';
 

apps/web/src/hooks/useWorkspacePanes.ts

@@ -188,6 +188,8 @@ export interface UseWorkspacePanesResult {
   // id to update mobile URL state so the URL-sync effect doesn't fight the
   // freshly-set activePaneIdx.
   addSplitPane: (kind: 'chat' | 'terminal' | 'coder') => string | null;
+  /** Append a new BooCode tab to an existing coder pane (the coder "+"). */
+  createCoderTab: (paneIdx: number) => Promise<void>;
   // Open-on-first-click, close-on-second-click. Singleton — settings panes
   // don't count toward MAX_PANES. Closing the only remaining pane (edge case)
   // falls back to an empty pane to preserve the "always one pane" invariant.
@@ -265,6 +267,42 @@ export function useWorkspacePanes(sessionId: string): UseWorkspacePanesResult {
     [sessionId, attachChatToPane, markPaneChatPending],
   );
 
+  // Add a new BooCode tab to an existing coder pane (the "+" in the coder pane
+  // header). Creates a fresh chat row (= a new agent context that shares the
+  // session worktree) and APPENDS it to the pane's chatIds, keeping the pane
+  // kind 'coder' and focusing the new tab. Mirrors createChat for chat panes;
+  // the per-pane "split into a new pane" action stays addSplitPane.
+  const createCoderTab = useCallback(
+    async (paneIdx: number) => {
+      const paneId = panes[paneIdx]?.id;
+      if (!paneId) return;
+      markPaneChatPending(paneId, true);
+      try {
+        const chat = await api.chats.create(sessionId, { name: chatNameForPaneKind('coder') });
+        setPanes((prev) => {
+          const idx = prev.findIndex((p) => p.id === paneId);
+          if (idx < 0) return prev;
+          const pane = prev[idx]!;
+          const newIds = [...pane.chatIds, chat.id];
+          const next = [...prev];
+          next[idx] = {
+            ...pane,
+            kind: 'coder',
+            chatId: chat.id,
+            chatIds: newIds,
+            activeChatIdx: newIds.length - 1,
+          };
+          return next;
+        });
+      } catch (err) {
+        toast.error(err instanceof Error ? err.message : 'Failed to create coder tab');
+      } finally {
+        markPaneChatPending(paneId, false);
+      }
+    },
+    [sessionId, panes, markPaneChatPending],
+  );
+
   const seedEmptyScopedPanes = useCallback(
     (paneList: WorkspacePane[]) => {
       for (const pane of paneList) {
@@ -426,16 +464,16 @@ export function useWorkspacePanes(sessionId: string): UseWorkspacePanesResult {
   }, [sessionId, panes, tabNumbers, nextTabNumber, closedPaneStack]);
 
   // v2.6.x (Batch 3a): maintain stable, session-scoped tab numbers. Collect the
-  // chat ids that appear in CHAT-kind panes in deterministic order (pane index,
-  // then tab index). Assign numbers to any without one (global per session,
-  // only ever increasing, never reused) and prune entries whose chat is no
-  // longer in any chat-kind pane. Guarded against render loops: only setState
-  // when something actually changed.
+  // chat ids that appear in CHAT- or CODER-kind panes in deterministic order
+  // (pane index, then tab index). Assign numbers to any without one (global per
+  // session, only ever increasing, never reused) and prune entries whose chat
+  // is no longer in any tab-hosting pane. Guarded against render loops: only
+  // setState when something actually changed.
   useEffect(() => {
     const liveChatIds: string[] = [];
     const liveSet = new Set<string>();
     for (const pane of panes) {
-      if (pane.kind !== 'chat') continue;
+      if (pane.kind !== 'chat' && pane.kind !== 'coder') continue;
       for (const id of pane.chatIds) {
         if (!liveSet.has(id)) {
           liveSet.add(id);
@@ -597,9 +635,9 @@ export function useWorkspacePanes(sessionId: string): UseWorkspacePanesResult {
       const pane = next[paneIdx]!;
       const keepIdx = pane.chatIds.indexOf(keepChatId);
       if (keepIdx < 0) return prev;
+      // Preserve pane.kind (...pane) — a coder pane stays a coder pane.
       next[paneIdx] = {
         ...pane,
-        kind: 'chat',
         chatId: keepChatId,
         chatIds: [keepChatId],
         activeChatIdx: 0,
@@ -640,13 +678,23 @@ export function useWorkspacePanes(sessionId: string): UseWorkspacePanesResult {
   const showLandingPage = useCallback((paneIdx: number) => {
     setPanes((prev) => {
       const pane = prev[paneIdx];
-      // Coder/terminal panes are not chat hosts — history button is chat-only.
-      if (!pane || pane.kind === 'coder' || pane.kind === 'terminal') return prev;
+      if (!pane) return prev;
       const next = [...prev];
-      next[paneIdx] = { ...pane, kind: 'empty', chatId: undefined };
+      if (pane.kind === 'coder' || pane.kind === 'terminal') {
+        // Scoped panes don't host chat tabs. Leaving one for the session
+        // history closes it: drop the pane→chat binding, and for terminals
+        // kill the tmux session (terminals are ephemeral — closing = killing,
+        // mirroring removePane).
+        if (pane.kind === 'terminal') {
+          api.terminals.kill(sessionId, pane.id).catch(() => { /* non-fatal */ });
+        }
+        next[paneIdx] = { ...pane, kind: 'empty', chatId: undefined, chatIds: [], activeChatIdx: -1 };
+      } else {
+        next[paneIdx] = { ...pane, kind: 'empty', chatId: undefined };
+      }
       return next;
     });
-  }, []);
+  }, [sessionId]);
 
   const addSplitPane = useCallback((kind: 'chat' | 'terminal' | 'coder'): string | null => {
     // Generate the id outside the updater so we can return it deterministically.
@@ -944,6 +992,7 @@ export function useWorkspacePanes(sessionId: string): UseWorkspacePanesResult {
     closeAllTabs,
     showLandingPage,
     addSplitPane,
+    createCoderTab,
     toggleSettingsPane,
     removePane,
     reopenPane,

apps/web/src/lib/modelName.ts

@@ -0,0 +1,32 @@
+// model-attribution: turn a raw model id into a short, friendly label for the
+// per-message model chip (e.g. "claude-sonnet-4-6" → "Sonnet 4.6",
+// "qwen3.6-35b-a3b-mxfp4" → "Qwen3.6 35B"). Strips provider prefixes and maps
+// the common families; falls back to the cleaned id so unknown models still
+// read. Returns null for empty/absent input so the caller can skip the chip.
+export function shortenModelName(model: string | null | undefined): string | null {
+  if (!model) return null;
+  let m = model.trim();
+  if (!m) return null;
+
+  // opencode / provider-prefixed ids: "llama-swap/qwen…", "anthropic/claude…".
+  const slash = m.lastIndexOf('/');
+  if (slash >= 0) m = m.slice(slash + 1);
+
+  // claude-{opus,sonnet,haiku}-X-Y[-date] → "Opus X.Y".
+  const claude = /^claude-(opus|sonnet|haiku)-(\d+)-(\d+)/i.exec(m);
+  if (claude) {
+    const tier = claude[1]!.charAt(0).toUpperCase() + claude[1]!.slice(1).toLowerCase();
+    return `${tier} ${claude[2]}.${claude[3]}`;
+  }
+
+  // qwen3.6-35b-a3b-… → "Qwen3.6 35B".
+  const qwen = /^qwen([\d.]+)-(\d+)b/i.exec(m);
+  if (qwen) return `Qwen${qwen[1]} ${qwen[2]}B`;
+
+  // gpt-4o, gpt-5-… → "GPT-4o" / "GPT-5".
+  const gpt = /^gpt-([\w.-]+)/i.exec(m);
+  if (gpt) return `GPT-${gpt[1]}`;
+
+  // Fallback: keep the id readable, cap the length for the chip.
+  return m.length > 26 ? `${m.slice(0, 25)}…` : m;
+}

apps/web/src/lib/theme.ts

@@ -24,7 +24,8 @@ export type ThemeId =
   | 'ivory'
   | 'chalk'
   | 'cobalt'
-  | 'midnight-sapphire';
+  | 'midnight-sapphire'
+  | 'ember';
 
 export type ThemeMode = 'dark' | 'light' | 'system';
 
@@ -74,9 +75,13 @@ export const THEMES: readonly ThemeMeta[] = [
     anchors: ['#020817', '#061434', '#0c2244', '#3060a0', '#0047ab'] },
   { id: 'midnight-sapphire', name: 'Midnight Sapphire', family: 'Blue', supportsDark: true, supportsLight: true,
     anchors: ['#02050e', '#060c1f', '#0e1a36', '#4a6088', '#1e3a8a'] },
+  { id: 'ember', name: 'BooCode Ember', family: 'Amber', supportsDark: true, supportsLight: true,
+    anchors: ['#0c0c0e', '#15151a', '#1f1f23', '#6b6b75', '#ff7a18'] },
 ] as const;
 
-export const DEFAULT_THEME_ID: ThemeId = 'obsidian';
+// BooCode 2.0: orange-on-black "BooCode Ember" is the out-of-the-box signature
+// (was 'obsidian' / purple). Also the dark fallback for the light-only themes.
+export const DEFAULT_THEME_ID: ThemeId = 'ember';
 export const DEFAULT_THEME_MODE: ThemeMode = 'dark';
 export const STORAGE_KEY = 'boocode.theme';
 

apps/web/src/main.tsx

@@ -7,7 +7,6 @@ import React from 'react';
 import ReactDOM from 'react-dom/client';
 import App from './App';
 import './styles/globals.css';
-
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <React.StrictMode>
     <App />

apps/web/src/styles/globals.css

@@ -25,6 +25,7 @@
 @import "./themes/chalk.css";
 @import "./themes/cobalt.css";
 @import "./themes/midnight-sapphire.css";
+@import "./themes/ember.css";
 
 @custom-variant dark (&:is(.dark *));
 

apps/web/src/styles/themes/ember.css

@@ -0,0 +1,76 @@
+/* BooCode Ember (family: Amber) — the signature brand theme. Mirrors the
+   Obsidian theme's flat charcoal structure (same neutrals, flat hairline
+   borders), with ember orange (--accent #ff7a18) swapped in for Obsidian's
+   purple. Dark anchors: #0c0c0e #15151a #1f1f23 #6b6b75 #ff7a18. */
+.theme-ember {
+  --background: #fafafa;
+  --foreground: #18181b;
+  --card: #f4f4f5;
+  --card-foreground: #18181b;
+  --popover: #f4f4f5;
+  --popover-foreground: #18181b;
+  --primary: #e25f00;
+  --primary-foreground: #ffffff;
+  --secondary: #e4e4e7;
+  --secondary-foreground: #18181b;
+  --muted: #e4e4e7;
+  --muted-foreground: #71717a;
+  --accent: #e25f00;
+  --accent-foreground: #ffffff;
+  --destructive: #b91c1c;
+  --destructive-foreground: #ffffff;
+  --border: #e4e4e7;
+  --input: #e4e4e7;
+  --ring: #e25f00;
+  --sidebar: #f4f4f5;
+  --sidebar-foreground: #18181b;
+  --sidebar-primary: #e25f00;
+  --sidebar-primary-foreground: #ffffff;
+  --sidebar-accent: #e4e4e7;
+  --sidebar-accent-foreground: #18181b;
+  --sidebar-border: #e4e4e7;
+  --sidebar-ring: #e25f00;
+}
+.theme-ember.dark {
+  --background: #0c0c0e;
+  --foreground: #ece9f0;
+  --card: #15151a;
+  --card-foreground: #ece9f0;
+  --popover: #15151a;
+  --popover-foreground: #ece9f0;
+  --primary: #ff7a18;
+  --primary-foreground: #120a04;
+  --secondary: #1f1f23;
+  --secondary-foreground: #ece9f0;
+  --muted: #1f1f23;
+  --muted-foreground: #6b6b75;
+  --accent: #ff7a18;
+  --accent-foreground: #120a04;
+  --destructive: #dc2626;
+  --destructive-foreground: #ffffff;
+  --border: #1f1f23;
+  --input: #1f1f23;
+  --ring: #ff7a18;
+  --sidebar: #15151a;
+  --sidebar-foreground: #ece9f0;
+  --sidebar-primary: #ff7a18;
+  --sidebar-primary-foreground: #120a04;
+  /* Softened selected/hover surface — a faint accent tint, NOT the solid bright
+     accent Obsidian uses (per your earlier "selected button shouldn't be solid
+     orange"). Set --sidebar-accent: #ff7a18 + foreground #120a04 for parity. */
+  --sidebar-accent: color-mix(in oklab, #ff7a18 16%, transparent);
+  --sidebar-accent-foreground: #ece9f0;
+  --sidebar-border: #1f1f23;
+  --sidebar-ring: #ff7a18;
+}
+
+/* User message bubble: a dark surface card with a 2px accent right-edge — not
+   the solid-orange fill (per your earlier preference). Remove this block to get
+   the Obsidian-style solid-accent bubble. */
+.theme-ember.dark .boo-user-bubble {
+  background: var(--popover);
+  color: var(--foreground);
+  border: 1px solid var(--border);
+  border-right: 2px solid var(--primary);
+  border-radius: 6px;
+}

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

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

boocode_roadmap.md

@@ -399,25 +399,11 @@ All tags `vMAJOR.MINOR.PATCH-slug`, monotonic per minor, assigned at ship time (
 
 -----
 
-## v2.4 — BooCoder as ACP agent (driveable from external editors)
+## v2.4 — BooCoder as ACP agent (driveable from external editors) — DROPPED
 
-**Status: not shipped.** This is a conceptual milestone, not yet built. The `v2.4.0`/`v2.4.1` *patch tags* shipped unrelated content (Unsloth Studio parser/HTML-to-md lift, llama-sidecar routing) — patch numbers are assigned at ship time and have outrun the milestone plan. The outbound ACP-agent surface below is still future work.
+**Status: DROPPED (Sam, 2026-06-02).** Will not be built. Sam only ever drives BooCoder through BooCoder's own surface (CoderPane) — never from an external editor (Zed/JetBrains/Avante/CodeCompanion). The outbound `boocoder acp` exposure solves a problem he doesn't have, so the milestone is closed as won't-do rather than deferred. (The `v2.4.0`/`v2.4.1` *patch tags* shipped unrelated content — Unsloth Studio parser/HTML-to-md lift, llama-sidecar routing — and never had anything to do with this milestone; patch numbers are assigned at ship time.)
 
-**Goal:** expose `boocoder acp` so Zed, JetBrains, Avante.nvim, CodeCompanion.nvim can drive BooCoder as their agent. Outbound exposure of the BooCoder write-tool surface to ACP-compatible editors.
-
-**Scope:**
-
-1. New ACP server entry point: `boocoder acp` reads JSON-RPC over stdio, exposes BooCoder's task primitives as ACP sessions.
-1. BooCoder UI features remain optional: editor drives session via ACP; pending-changes queue still gates writes; user can approve/reject from either BooCoder's web UI or the editor's permission dialog (whichever responds first).
-1. Same auth model as the rest of BooCoder — editor must be reachable on the Tailscale mesh, or BooCoder is invoked with a short-lived token.
-
-**Why v2.4, not v2.0:** outbound ACP-agent role is cheap once the inbound ACP-client side is implemented (same protocol library, server side), but it's a *different product surface* — driving BooCoder from external editors. Ship it after BooCoder's own surface stabilizes. (The v2.2 version number was used for the Paseo provider/dispatch batch shipped 2026-05-26.)
-
-**Lift source:** `zed-industries/codex-acp` (Apache-2.0) as a server-side ACP reference implementation.
-
-**Dependencies:** v2.0 + v2.2 (recommended; v2.1 runtime isolation optional).
-
-**Estimated:** ~400 LoC.
+The original plan (kept for record): expose `boocoder acp` (JSON-RPC over stdio) so ACP-compatible editors could drive BooCoder's write-tool surface, pending-changes queue still gating writes; lift source `zed-industries/codex-acp` (Apache-2.0), ~400 LoC. If an external-editor use case ever appears, re-open from here.
 
 -----
 

data/mcp.example.json

@@ -3,6 +3,9 @@
     "context7": {
       "type": "streamableHttp",
       "url": "https://mcp.context7.com/mcp",
+      "headers": {
+        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
+      },
       "enabled": false
     }
   }

docs/ARCHITECTURE.md

@@ -96,6 +96,8 @@ flowchart LR
 
 Since v2.1.0, BooCoder runs on the host (not Docker). Agent binaries spawn directly — no SSH tunnel.
 
+See [coder-backends.md](./coder-backends.md) for the full dispatch-backend reference: routing predicates, the warm vs. one-shot lifecycle, agent-session resume, and the provider-discovery pipeline.
+
 ## Supporting services
 
 | Service | Reachability | Purpose |
@@ -118,5 +120,5 @@ Since v2.1.0, BooCoder runs on the host (not Docker). Agent binaries spawn direc
 ## Deploy topology
 
 - **BooChat + BooTerm + Postgres + codecontext:** `docker compose up --build -d` from `/opt/boocode`
-- **BooCoder:** `pnpm -C apps/server build && pnpm -C apps/coder build && sudo systemctl restart boocoder`
+- **BooCoder:** `pnpm -C packages/contracts build && pnpm -C apps/server build && pnpm -C apps/coder build && sudo systemctl restart boocoder`
 - **Ports bind to Tailscale IP** `100.114.205.53`, not `0.0.0.0` — use that IP for host smoke curls

docs/DEFERRED-WORK.md

@@ -152,16 +152,18 @@ These were explicitly scoped out of v2.3 (see `design.md` §11) and remain open:
 
 - **`provider_snapshot_updated` WS frame** — the loading state uses a capped client poll / one-shot refetch instead of a server-pushed frame (design §4.4, §11; tasks O.1).
 - **`available_agents.enabled` DB column** — `enabled` is read from the in-memory resolved registry only; no DB mirror, so settings state after a coder restart re-derives from the JSON config rather than the DB (design §3.3; tasks O.2).
-- **Single-source-of-truth shared types package** — the provider snapshot types are duplicated across `apps/coder/.../provider-types.ts` and `apps/web/src/api/types.ts`, guarded by the text-identity `provider-types-parity.test.ts` rather than a shared package (see §3 below).
+- ~~**Single-source-of-truth shared types package**~~ — **shipped as `@boocode/contracts`** (branch `contracts-ssot-pkg`): all duplicated cross-app contracts (ws-frames schema, provider-snapshot types, provider-config schemas, `MessageMetadata`, `WorktreeRiskReport`) are now single-sourced in `packages/contracts/`; `provider-types-parity.test.ts` and the byte-parity test were deleted. See §3 below (now historical).
 - **MCP `list_providers` / `inspect_provider` tools** — provider introspection over MCP is not wired (design §11).
 
 ---
 
-## 3. Unified `packages/types` for provider snapshot JSON
+## 3. ~~Unified `packages/types` for provider snapshot JSON~~ (resolved — shipped as `@boocode/contracts`)
 
-### Current behavior
+> **Status: resolved.** All contracts described below are now single-sourced in `packages/contracts/` (`@boocode/contracts`), shipped on branch `contracts-ssot-pkg`. The rest of this section is historical.
 
-Provider snapshot shapes are **duplicated** (not byte-identical exports):
+### Former behavior (pre-`@boocode/contracts`)
+
+Provider snapshot shapes were **duplicated** (not byte-identical exports):
 
 | Location | Types |
 |----------|-------|

docs/STALE-DEPRECATED.md

@@ -74,4 +74,4 @@ _No open stale items from the 2026-05-26 review._
 
 - **Task cancel → abort external ACP/PTY child** — `AbortController` in dispatcher not wired to cancel route
 - **Skip ACP cold probe when DB models fresh** — perf; changes snapshot semantics
-- **Unified `packages/types`** for provider snapshot JSON — Zod parity test may suffice
+- ~~**Unified `packages/types`** for provider snapshot JSON~~ — **shipped as `@boocode/contracts`** (`packages/contracts/`); all duplicated contracts are now single-sourced there

docs/coder-backends.md

@@ -0,0 +1,372 @@
+# BooCoder Dispatch Backends
+
+<!-- How BooCoder turns a coding request into work performed by one of several pluggable agent backends, streams the turn back to the browser, and resumes each agent's context across turns. -->
+
+- **Last Updated:** 2026-06-02 00:00
+- **Authors:**
+  - indifferentketchup (samkintop@gmail.com)
+
+## Summary
+
+BooCoder is the write-capable surface of BooCode: it takes a message you type into a coder tab and gets an AI coding agent to actually do the work in an isolated copy of your project. Unlike the read-only chat surface, BooCoder can edit, create, and delete files — every change is staged for your review before it touches disk. The interesting part is that BooCoder does not have one agent; it has several, each spoken to over a different protocol (a local model, OpenCode, Goose, Claude Code, Qwen Code), and it hides those differences behind a single internal contract so the rest of the system streams them all the same way.
+
+When you send a message, BooCoder decides which backend should handle it, keeps that agent "warm" so a follow-up message reuses the same conversation, streams the agent's text, reasoning, and tool calls back to your browser live, and records what files changed. The picker you see (provider, model, mode, slash commands) is built from a discovery pipeline that probes which agents are installed on the host.
+
+- **Five providers, four transports.** `boocode` (native llama-swap inference), `opencode` (warm HTTP server), `goose`/`qwen` (ACP), `claude` (PTY or — behind a flag — the Claude Agent SDK).
+- **One internal contract.** Every external backend implements the same `AgentBackend` interface and emits the same transport-agnostic `AgentEvent`s; the dispatcher maps those to WebSocket frames identically regardless of which agent produced them.
+- **Warm vs. one-shot.** Tasks that come from a real chat tab get a long-lived, resumable agent session; session-less tasks (arena, MCP, raw API) get a fresh one-shot process per turn.
+- **The tab is the unit of context.** Agent sessions are keyed `(chat_id, agent)` — two tabs in one workspace are two independent conversations that happen to share one worktree.
+- **Changes are staged, never auto-applied.** Write tools queue rows in `pending_changes`; nothing hits disk until you apply.
+- **BooCoder runs on the host**, not in Docker — a `boocoder.service` systemd unit on port 9502, so it can spawn agent binaries with full filesystem access.
+
+Key files:
+- `apps/coder/src/services/dispatcher.ts` — the task loop; routes each task to a backend and maps its events to WS frames
+- `apps/coder/src/services/agent-backend.ts` — the `AgentBackend` interface and `AgentEvent` contract every backend implements
+- `apps/coder/src/services/backends/` — the four backend implementations plus routing predicates
+- `apps/coder/src/services/provider-snapshot.ts` — the provider discovery / probe pipeline that builds the picker
+- `apps/coder/src/schema.sql` — `agent_sessions`, `worktrees`, `tasks`, `available_agents`, `pending_changes`
+
+## Architecture
+
+```mermaid
+flowchart TD
+    Msg["User message<br/>(CoderPane)"] --> Route{"provider?"}
+    Route -->|boocode| Inf["runNativeInference<br/>in-process llama-swap"]
+    Route -->|external| Task[("tasks row")]
+    Task --> Disp["dispatcher.ts<br/>LISTEN/NOTIFY + 2s poll"]
+
+    Disp --> Pred{"routing<br/>predicates"}
+    Pred -->|opencode| OC["OpenCodeServerBackend<br/>(warm HTTP server)"]
+    Pred -->|"goose / qwen + tab"| WA["WarmAcpBackend<br/>(warm ACP process)"]
+    Pred -->|"claude + tab + flag"| CS["ClaudeSdkBackend<br/>(warm SDK query)"]
+    Pred -->|"session-less / flag off"| OS["runExternalAgent<br/>(one-shot ACP / PTY)"]
+
+    OC -->|AgentEvent| Map["onEvent → WS frames"]
+    WA -->|AgentEvent| Map
+    CS -->|AgentEvent| Map
+    OS -->|AgentEvent| Map
+
+    Map -->|"delta / reasoning_delta / tool_call"| Broker["broker.publishFrame"]
+    Map -->|"message_complete + model"| Broker
+    Broker -->|WebSocket| Web["apps/web CoderPane"]
+
+    OC -.session.-> AS[("agent_sessions<br/>(chat_id, agent)")]
+    WA -.session.-> AS
+    CS -.session.-> AS
+    Map -->|"diff worktree"| PC[("pending_changes")]
+    Inf --> PC
+```
+
+## How It Works
+
+Everything starts from a row in the `tasks` table. When you send a message to a coder tab with an external provider selected, the message route writes a `tasks` row carrying the provider, model, chat id, and session id. A long-running **dispatcher** notices the row (instantly via a Postgres `LISTEN/NOTIFY` signal, with a 2-second poll as a safety net) and runs it. Only one turn runs at a time per session, so two messages in the same workspace queue rather than collide. If the provider is the native `boocode`, there is no task and no external agent — the dispatcher runs llama-swap inference in-process instead, the same way the chat surface does.
+
+For an external provider, the dispatcher picks **which backend** should handle the task using small pure predicates. The deciding factors are: which agent it is, whether the task came from a real chat tab (has both a session id and a chat id), and — for Claude — whether a feature flag is on. OpenCode always uses its warm HTTP server. Goose and Qwen use a warm, long-lived ACP process when they come from a tab, and a fresh one-shot process otherwise. Claude uses the warm Claude Agent SDK backend only when the `CLAUDE_SDK_BACKEND` flag is set; by default it falls through to a one-shot PTY process. Anything session-less — arena contestants, MCP-created tasks, raw `POST /api/tasks` — always takes the one-shot path.
+
+A **warm backend** keeps the agent's process and conversation alive between turns. The first turn in a tab spawns the process and creates the agent's session; later turns reuse it, so the agent remembers the conversation without re-sending it. Each backend persists a small row in `agent_sessions` keyed on the tab and agent, including a resume token and a `config_hash` of the model. If you switch models in the same tab, the hash changes and the backend transparently starts a fresh agent session while keeping the same worktree. If the process crashes, the row is marked `crashed` and the next turn re-spawns it.
+
+No matter which backend runs, the turn streams the same way. Each backend emits a small set of **transport-agnostic events** — text, reasoning, tool-call-started, tool-call-updated, commands — and the dispatcher maps every one of them to a WebSocket frame, identically across all backends. That uniformity is the whole point of the design: OpenCode's server-sent events, an ACP process's notifications, and the Claude SDK's message stream all arrive in your browser as the same `delta`, `reasoning_delta`, and `tool_call` frames. When the turn finishes, the dispatcher publishes a `message_complete` frame (now carrying the model id, so the UI can show a model attribution chip), diffs the worktree, and queues the file changes into `pending_changes` for you to review.
+
+## Primary Flows
+
+### A warm external-agent turn
+
+**Trigger:** You type a message in a coder tab with OpenCode, Goose, Qwen, or (flag-on) Claude selected.
+
+1. **The message becomes a task.** The coder message route creates your user message row and a `tasks` row stamped with the agent, model, `chat_id`, and `session_id`, then returns `202 { task_id, dispatched: true }`. Nothing is computed yet.
+2. **The dispatcher picks it up.** A Postgres `NOTIFY` wakes the dispatcher immediately (a 2-second poll is the backstop). It enforces one-turn-per-session concurrency, then evaluates the routing predicates and lands on a warm backend.
+3. **The session is ensured or resumed.** The backend looks up `agent_sessions` for this `(chat_id, agent)`. If a healthy session exists and the model's `config_hash` matches, it resumes — the agent still has the conversation. Otherwise it spawns the process (or, for OpenCode, reuses the one shared server) and creates a fresh agent session against the tab's worktree.
+4. **The turn streams.** The backend sends your message and emits `AgentEvent`s as the agent works. The dispatcher's `onEvent` maps each to a WebSocket frame — `text` → `delta`, `reasoning` → `reasoning_delta`, `tool_call`/`tool_update` → `tool_call` — and publishes them through the broker. Your browser renders the agent thinking, talking, and calling tools live. Tool snapshots accumulate so the final transcript persists with each tool's input, output, and status.
+5. **Outcome.** On completion the dispatcher publishes `message_complete` (with the model id for the attribution chip), records token/context usage on the message, diffs the worktree against its base commit, and supersedes any prior pending changes with one `pending_changes` set for the turn. You review the diff and apply it when ready.
+
+**When it fails:** If the agent stalls and emits no events for 180 seconds, an inactivity watchdog reconciles the session — it asks the server whether the turn actually finished and, if not, marks the `agent_sessions` row `crashed`. A crashed or exited backend is re-spawned on your next message. An aborted turn (you hit stop) cancels the prompt on the warm connection without killing the process, and a guard swallows any late "turn done" signal so it cannot accidentally settle your *next* turn.
+
+### A one-shot dispatch
+
+**Trigger:** A task with no chat tab behind it (arena contestant, MCP-created task, raw `POST /api/tasks`), or a Claude task while `CLAUDE_SDK_BACKEND` is off.
+
+1. **No warm session.** The routing predicates return false (missing `session_id`/`chat_id`, or the Claude flag is off), so the dispatcher calls `runExternalAgent`.
+2. **A fresh process per turn.** It creates a per-task worktree, then spawns the agent once — over ACP for OpenCode/Goose, or over a PTY with `--output-format stream-json` for Claude/Qwen — runs the single turn, and tears the process down.
+3. **Outcome.** Events stream and persist exactly as in the warm flow (same `onEvent` mapping, same `message_complete` with model), and the worktree diff queues one `pending_changes` row. Nothing is kept warm; the next such task starts over.
+
+### Native boocode inference
+
+**Trigger:** You send a message with the native `boocode` provider selected.
+
+1. **No task, no agent.** The message route sees a non-external provider, creates a streaming assistant message row, and enqueues in-process inference — there is no `tasks` row and no external process.
+2. **The shared inference loop runs.** BooCoder reuses the chat surface's inference runner against llama-swap; deltas and tool calls publish through the broker just like the chat surface, and write tools queue into `pending_changes`.
+3. **Outcome.** The assistant message is finalized in place with its content and token counts. (This path is the only one that tracks context fill natively; external one-shot agents report no ctx usage.)
+
+**When it fails:** If inference is already running for the session, the route returns `409` rather than starting a second concurrent turn.
+
+## Key Files
+
+### Backend
+| File | Purpose |
+|------|---------|
+| `apps/coder/src/services/dispatcher.ts` | Task loop (LISTEN/NOTIFY + poll), per-session concurrency, routes to each backend, maps `AgentEvent`→WS frames, publishes the four `message_complete` sites, diffs worktree → `pending_changes` |
+| `apps/coder/src/services/agent-backend.ts` | The `AgentBackend` interface, `AgentEvent` union, `EnsureSessionOpts`/`AgentSessionHandle`/`PromptCtx`/`TurnResult` |
+| `apps/coder/src/services/backends/opencode-server.ts` | Warm OpenCode HTTP server backend: one `opencode serve` per process, per-session SSE loop, `config_hash` resume, inactivity watchdog, orphan-terminal guard |
+| `apps/coder/src/services/backends/warm-acp.ts` | Warm ACP backend (goose/qwen): one persistent ACP process per `(chat, agent)`, reused across turns |
+| `apps/coder/src/services/backends/claude-sdk.ts` | Warm Claude Agent SDK backend: one streaming-input `query()` per `(chat, agent)`; transcript via `PostgresSessionStore` |
+| `apps/coder/src/services/backends/claude-sdk-map.ts` | Maps `SDKMessage` (stream_event / assistant / user) → `AgentEvent`s; the `user` tool_result → terminal `tool_update` mapping |
+| `apps/coder/src/services/backends/warm-acp-routing.ts` | `shouldUseWarmBackend` predicate + ACP `stopReason`→ok mapping |
+| `apps/coder/src/services/backends/claude-sdk-routing.ts` | `shouldUseClaudeSdk` + `claudeSdkBackendEnabled` (the `CLAUDE_SDK_BACKEND` flag) |
+| `apps/coder/src/services/backends/lifecycle-decisions.ts` | Pure idle/LRU/restart eviction decisions for the agent pool |
+| `apps/coder/src/services/backends/turn-guard.ts` | Post-abort orphan-terminal suppression |
+| `apps/coder/src/services/acp-dispatch.ts` / `pty-dispatch.ts` | One-shot ACP / PTY dispatch used by `runExternalAgent` |
+| `apps/coder/src/services/acp-event-map.ts` | Shared ACP `session/update` → `AgentEvent` normalization (warm + one-shot) |
+| `apps/coder/src/services/acp-tool-snapshot.ts` | `AcpToolSnapshot` shape, `mergeToolSnapshot`, `snapshotToWireToolCall`, lifecycle mapping |
+| `apps/coder/src/services/agent-pool.ts` | Holds live backends keyed `(primaryKey, agent)`; lazy spawn, idle/LRU eviction, never evicts a busy backend |
+| `apps/coder/src/services/provider-registry.ts` | Static `PROVIDERS` registry (label/transport/model source) |
+| `apps/coder/src/services/provider-snapshot.ts` | Two-tier probe → the snapshot the picker renders; `persistProbedModels` |
+| `apps/coder/src/services/agent-probe.ts` | Startup discovery of installed agents/versions/ACP/models → `available_agents` |
+| `apps/coder/src/services/write_guard.ts` / `pending_changes.ts` | Write-path validation (escape + secret-file block) and the stage/apply/rewind queue |
+| `apps/coder/src/routes/providers.ts` / `messages.ts` | Provider snapshot/config/refresh endpoints; coder message read/post |
+| `apps/coder/src/schema.sql` | `agent_sessions`, `worktrees`, `tasks`, `available_agents`, `pending_changes`, `claude_session_entries` |
+
+### Frontend
+| File | Purpose |
+|------|---------|
+| `apps/web/src/components/AgentComposerBar.tsx` | Renders the provider/model/mode/command picker from the provider snapshot |
+| `apps/web/src/components/panes/CoderPane.tsx` | Coder tab: live `message_complete` reducer, slash-command groups, message timeline mapping |
+| `apps/web/src/components/panes/CoderMessageList.tsx` | Message rendering (`CoderMessageWire`), model-attribution chip |
+| `apps/web/src/api/types.ts` | Web wire copy of `ProviderSnapshotEntry` / `AgentCommand` (parity with `provider-types.ts`) |
+
+### Infrastructure
+| File | Purpose |
+|------|---------|
+| `/etc/systemd/system/boocoder.service` | Host service (port 9502); only `NoNewPrivileges=true` is safe — `ProtectSystem`/`ProtectHome`/`PrivateTmp` break agent dispatch |
+| `apps/coder/.env.host` | Production env (DATABASE_URL, LLAMA_SWAP_URL, CODER_PROVIDERS_PATH, CLAUDE_SDK_BACKEND, …) |
+| `data/coder-providers.json` | Live runtime provider overrides (gitignored); template is `data/coder-providers.example.json` |
+
+**Build & deploy.** `apps/coder` imports from both `@boocode/contracts` and the server's compiled `dist/` (`createInferenceRunner`, `createBroker`, `ALL_TOOLS`), so **`packages/contracts` and `apps/server` must build first**: `pnpm -C packages/contracts build && pnpm -C apps/server build && pnpm -C apps/coder build && sudo systemctl restart boocoder`. The server's `package.json` `exports` map needs both `types` and `default` conditions per subpath (and `declaration: true` in its tsconfig) or NodeNext can't find the `.d.ts` and tsc fails "Cannot find module" here. Agent dispatch spawns binaries **directly** — `spawn(fullBinaryPath, argsArray, { cwd })` using `install_path` — never `spawn('sh', ['-c', ...])`, which fails under systemd.
+
+## Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `DATABASE_URL` | Postgres connection (shared `boochat` DB) | _required_ |
+| `LLAMA_SWAP_URL` | llama-swap base; `/v1/models` for native + opencode model discovery | _required_ |
+| `CLAUDE_SDK_BACKEND` | Truthy opts a deployment into the warm Claude Agent SDK backend; otherwise Claude uses one-shot PTY | _off_ |
+| `CODER_PROVIDERS_PATH` | Provider override config file | `/data/coder-providers.json` |
+| `PROVIDER_PROBE_TTL_MS` | Tier-2 cold ACP probe staleness threshold | `86400000` (24h) |
+| `DEFAULT_MODEL` | Fallback model when a task carries none | _deployment-specific_ |
+| `FAST_MODEL` | Cheaper model for titles/summaries; falls back to session/DEFAULT_MODEL | _unset_ |
+| `AGENT_POOL_IDLE_TTL_MS` | Idle timeout before a warm backend is evicted | `1800000` (30m) |
+| `AGENT_POOL_MAX_LIVE` | LRU cap on simultaneously-live warm backends | `10` |
+| `LIFECYCLE_SWEEP_INTERVAL_MS` | Cadence of the idle/LRU/health sweep | `60000` |
+| `ORPHAN_WORKTREE_GRACE_MS` | Grace before an untouched worktree dir is reaped | `3600000` (1h) |
+| `PORT` / `HOST` | Service bind (production binds the Tailscale IP) | `9502` / `0.0.0.0` |
+
+> BooCoder does **not** load MCP (that is BooChat only). Default values above are the documented fallbacks; production overrides live in `apps/coder/.env.host`. A config-only edit to `data/coder-providers.json` needs only the appropriate restart, not a rebuild.
+
+## Error Handling
+
+This table is the lookup for failure behavior; step-by-step recovery recipes for the common ones live under [Troubleshooting](#troubleshooting) in Technical Reference.
+
+### Backend
+| Scenario | Result | Behavior |
+|----------|--------|----------|
+| Warm turn stalls (no events ≥180s) | inactivity watchdog | Reconciles the session; if the turn isn't actually finished, marks `agent_sessions.status='crashed'` |
+| Backend process exits / crashes | next turn | Row marked `crashed`; `ensureSession` re-spawns and re-initializes on the next message |
+| User aborts a turn | cancel, not kill | Prompt cancelled on the warm connection (process kept); turn-guard swallows a late terminal so it can't settle the next turn |
+| Model changed in a tab | `config_hash` mismatch | Fresh agent session created, worktree preserved |
+| OpenCode SSE missing `directory` | zero session events | Events scope to the server `cwd` → empty turn → 180s timeout (the subscribe MUST pass the worktree dir) |
+| Native inference already running | `409 Conflict` | Second concurrent turn refused |
+| Write target escapes project / is a secret file | `WriteGuardError` | Change is not queued (`.env`, `*.pem`, `id_rsa`, `credentials.json`, … blocked) |
+| Invalid provider config PATCH | `422` | In-memory registry untouched; on disk-write failure, `500` and state left unchanged to avoid divergence |
+
+### Frontend
+| Scenario | Handling | Behavior |
+|----------|----------|----------|
+| Unknown WS frame type | wire-format gate | Frames whose `type` isn't in the web `WsFrame` union drop silently at JSON-parse — add new frame types to both sides |
+| New per-message field not whitelisted | `mapCoderTimelineRow` | The field silently vanishes in the coder unless every mapper is updated (this is how the model chip once disappeared) |
+
+---
+
+## Technical Reference
+
+*Below this point is code-level lookup detail — schema, types, constants, endpoints, and extension recipes. Stop here if you only need to understand the backends' behavior.*
+
+### Data Model
+
+`apps/coder/src/schema.sql` owns the coder-side tables and extends `tasks`. (The chat-side `sessions`/`chats`/`messages` live in `apps/server/src/schema.sql`.) The defining choice: a backend session is keyed on the **tab** (`chat_id`), not the session — two tabs in one workspace are two independent contexts sharing one worktree.
+
+```sql
+-- One resumable backend session per (tab, agent). Re-keyed to (chat_id, agent)
+-- in P1.5-b; session_id/worktree_id are informational SET NULL links.
+CREATE TABLE agent_sessions (
+  session_id       UUID REFERENCES sessions(id) ON DELETE SET NULL,
+  agent            TEXT NOT NULL,
+  backend          TEXT NOT NULL,   -- CHECK IN ('opencode_server','acp_warm','claude_sdk')
+  agent_session_id TEXT,            -- provider's resume token; null until assigned
+  server_port      INTEGER,         -- opencode HTTP port; null for ACP/SDK
+  status           TEXT NOT NULL DEFAULT 'idle', -- 'idle'|'active'|'crashed'|'closed'
+  config_hash      TEXT,            -- sha256('opencode_server|<model>').slice(0,16); stale-detect
+  worktree_id      UUID REFERENCES worktrees(id) ON DELETE SET NULL,
+  input_tokens     BIGINT NOT NULL DEFAULT 0,   -- accumulated per (chat_id, agent)
+  output_tokens    BIGINT NOT NULL DEFAULT 0,
+  cost             DOUBLE PRECISION NOT NULL DEFAULT 0,
+  chat_id          UUID NOT NULL REFERENCES chats(id) ON DELETE CASCADE,
+  PRIMARY KEY (chat_id, agent)      -- closing a tab CASCADEs its context away
+);
+
+-- First-class worktree entity: one per session, survives session delete.
+CREATE TABLE worktrees (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  session_id UUID REFERENCES sessions(id) ON DELETE SET NULL,
+  project_id UUID, path TEXT NOT NULL, branch TEXT, base_commit TEXT, slug TEXT,
+  status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','archived'))
+);
+
+-- Dispatcher work units (external agents only; native boocode uses messages+inference).
+-- tasks is created by apps/server schema; the coder adds these columns.
+-- Key coder columns: agent, model, execution_path ('native'|'acp'|'pty'|'qwen'),
+-- session_id (REFERENCES sessions), chat_id (REFERENCES chats ON DELETE SET NULL),
+-- state ('pending'|'running'|'completed'|'failed'|'blocked'|'cancelled').
+
+-- Probed agent registry (UPSERT by name at startup).
+-- available_agents(name PK, install_path, version, supports_acp, models JSONB,
+--   label, transport, commands JSONB, last_probed_at)
+
+-- Claude Agent SDK transcript store (resume materialization).
+-- claude_session_entries(id BIGSERIAL, project_key, session_id, subpath, ... )
+
+-- Staged file changes — nothing hits disk until apply_pending.
+-- pending_changes(id, session_id, task_id, file_path, operation('create'|'edit'|'delete'),
+--   diff, status('pending'|'applied'|'rejected'|'reverted'), agent)
+```
+
+Idempotent FK-action flips and PK swaps in this file guard on `pg_constraint` so re-runs are no-ops — see the P1.5-b re-key block.
+
+### Core Types
+
+The contract every external backend implements. Backends emit `AgentEvent`s without any WS envelope; the dispatcher owns the mapping to frames. `tool_call` and `tool_update` are kept distinct because OpenCode's SSE distinguishes tool-start from tool-result.
+
+See `apps/coder/src/services/agent-backend.ts` for the full definitions. Key shapes:
+
+```typescript
+type AgentEvent =
+  | { type: 'text'; text: string }
+  | { type: 'reasoning'; text: string }
+  | { type: 'tool_call'; toolCall: AcpToolSnapshot }   // tool started
+  | { type: 'tool_update'; toolCall: AcpToolSnapshot }  // tool result / status change
+  | { type: 'commands'; commands: AgentCommand[] };      // ACP available_commands_update
+
+interface AgentBackend {
+  ensureSession(sessionId: string, opts: EnsureSessionOpts): Promise<AgentSessionHandle>;
+  prompt(handle: AgentSessionHandle, input: string, ctx: PromptCtx): Promise<TurnResult>;
+  closeSession(handle: AgentSessionHandle): Promise<void>;
+  dispose(): Promise<void>;
+  health(): 'up' | 'down';
+  isBusy?(): boolean;              // pool never evicts a busy backend
+  tickHealth?(now?: number): Promise<void>;  // proactive restart (opencode only)
+}
+```
+
+`AcpToolSnapshot` (`apps/coder/src/services/acp-tool-snapshot.ts`) is the accumulating shape for a tool call — `{ toolCallId, title, kind?, status?, rawInput?, rawOutput? }` — merged incrementally and rendered via `snapshotToWireToolCall`.
+
+The provider picker is driven by `ProviderSnapshotEntry` / `AgentCommand` single-sourced in `@boocode/contracts` (`packages/contracts/src/provider-snapshot.ts`). `apps/coder/src/services/provider-types.ts` re-exports them; the web imports them directly. There is no hand-synced copy to keep in sync.
+
+### Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| poll interval | `2000` ms | Dispatcher fallback poll between `NOTIFY` signals |
+| turn inactivity watchdog | `180000` ms | OpenCode turn with no events → reconcile |
+| snapshot cache TTL | `5 min` | Per-cwd provider snapshot memory cache |
+| `PROVIDER_PROBE_TTL_MS` | `86400000` ms (24h) | Tier-2 cold ACP probe staleness |
+| `config_hash` length | 16 hex chars | `sha256('opencode_server|<model>')` prefix; excludes port |
+| agent pool idle TTL | `1800000` ms (30m) | Default warm-backend eviction |
+| agent pool max live | `10` | Default LRU cap |
+
+### Implementation Notes
+
+#### Routing predicates
+
+`shouldUseWarmBackend(task)` (`backends/warm-acp-routing.ts`) returns true only for `goose`/`qwen` tasks that carry **both** a `session_id` and a `chat_id` — i.e. they came from a real chat tab. `shouldUseClaudeSdk(task, env)` (`backends/claude-sdk-routing.ts`) is the same shape for `claude`, additionally gated behind `claudeSdkBackendEnabled` (the `CLAUDE_SDK_BACKEND` flag, default off). OpenCode tasks always route to the warm server. Everything that fails these predicates — arena, MCP, raw `POST /api/tasks`, flag-off Claude — falls through to `runExternalAgent`'s one-shot path. Both predicates are pure so they unit-test without a live process.
+
+#### The `user` tool_result mapping (Claude SDK)
+
+The Claude Agent SDK feeds tool **results** back in as `type:'user'` messages containing `tool_result` blocks. `mapSdkMessage` must map the `user` case to a terminal `tool_update` (completed, or failed on `is_error`) carrying the tool's output. Without it, the tool call persists `status:'running'` forever and the UI spinner never stops. See `mapUserToolResults` / `toolResultText` in `apps/coder/src/services/backends/claude-sdk-map.ts`. The same mapper dedups text/thinking already streamed via partials and assembles buffered `input_json_delta` fragments on `content_block_stop`.
+
+#### OpenCode SSE and `config_hash` resume
+
+OpenCode runs as one warm `opencode serve` HTTP server per BooCoder process, multiplexed across sessions. Live streaming reads `session.next.text.delta` / `.reasoning.delta` / `.tool.{called,success,failed}` (not the post-hoc `message.part.*`), and the subscribe **must** pass the session's worktree `directory` or events scope to the server cwd and the turn times out. Resume hinges on `config_hash = sha256('opencode_server|<model>').slice(0,16)` — deliberately excluding the random per-boot server port so resume survives restarts; a model change flips the hash and forces a fresh opencode session while keeping the worktree. A `streamedPartKeys` set drops post-hoc duplicate deltas; a `sessionID` demux guard drops cross-session events when two sessions share a server.
+
+#### Warm vs. one-shot lifetime
+
+The agent pool (`agent-pool.ts`) holds OpenCode once per process (one server, many sessions) and warm-ACP / Claude-SDK once per `(chat, agent)`. Idle-TTL and LRU eviction are computed by the pure functions in `lifecycle-decisions.ts` and never evict a backend whose `isBusy()` is true. One-shot dispatch holds nothing warm: `runExternalAgent` spawns, runs one turn, and tears down.
+
+#### Worktree diff → pending changes
+
+All paths run in a git worktree (per-session for warm backends, per-task for one-shot). At turn end the dispatcher diffs against the worktree's base commit and queues the result as a single `pending_changes` set, superseding the previous one (latest-wins). Write tools validate every path through `write_guard.ts` (`resolveWritePath` — `resolve` + prefix check, no `realpath` since created files may not exist yet — plus `isSecretPath`).
+
+### API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/providers` | Installed providers with models; transport reflects actual capability (`supports_acp`) |
+| `GET` | `/api/providers/snapshot?cwd=` | Full picker shape (providers + models + modes + commands); 5-min cache |
+| `GET` | `/api/providers/config` | Raw `data/coder-providers.json` (`{ providers: {} }` if absent) |
+| `PATCH` | `/api/providers/config` | Per-id **wholesale** override replace → save → reload → clear cache |
+| `POST` | `/api/providers/refresh` | Force cold ACP re-probe of installed providers |
+| `GET` | `/api/providers/:id/diagnostic` | Read-only diagnostics (no probe) |
+| `GET` | `/api/sessions/:sessionId/messages?chat_id=` | Coder message list via `mapCoderMessageRow` |
+| `POST` | `/api/sessions/:sessionId/messages` | Send: external → `202 { task_id, dispatched }`; native → `202 { assistant_message_id }` |
+| `GET` | `/api/health` | `{ ok, db, tools }` (down ~15–20s after restart while the agent probe runs) |
+
+`PATCH /api/providers/config` replaces a provider id's override object wholesale (per-id shallow merge) — to flip one field, send `{...existing, field}` or you wipe the rest. A custom ACP entry requires `extends: 'acp'` + `label` + `command` or it drops out of the resolved registry.
+
+### Provider discovery pipeline
+
+The picker is built by a four-stage pipeline: `provider-config.ts` (never-throws Zod load of the overrides file) → `provider-config-registry.ts` (`buildResolvedRegistry`, a singleton merging built-ins with overrides) → `provider-snapshot.ts` (two-tier probe) → `routes/providers.ts`. Tier 1 is a fast presence check; tier 2 is a cold ACP probe, skipped unless forced, stale past `PROVIDER_PROBE_TTL_MS`, or the DB has no models yet. Model sources differ per provider: `boocode`/`opencode` from llama-swap `/v1/models` (opencode IDs prefixed `llama-swap/`), `claude` from static registry entries, `qwen` from `~/.qwen/settings.json`, `goose` from the cold ACP probe. Startup `agent-probe.ts` UPSERTs all of this into `available_agents`. Commands come from the static `PROVIDER_COMMANDS` hints merged with live ACP `available_commands_update` (async — must poll after `newSession`); Claude, a PTY provider, discovers commands from disk via `claude-command-discovery.ts` (`~/.claude/commands` + enabled plugin skills). `AgentCommand.kind` (`'command'` vs `'skill'`) drives the slash-menu icon split in `CoderPane`.
+
+### Testing
+
+`apps/coder` has its own vitest suite (`pnpm -C apps/coder test`). Config: `globals: false` (import `describe`/`it`/`expect` from `vitest`), include glob `src/**/__tests__/**/*.test.ts` (files outside it silently don't run), `fileParallelism: false` so DB-integration suites serialize. The pattern is to extract pure helpers and unit-test them in isolation.
+
+- `services/backends/__tests__/claude-sdk-map.test.ts` — SDK stream assembly, text/thinking dedup, tool input buffering, the `user` tool_result mapping
+- `services/backends/__tests__/warm-acp-routing.test.ts` / `claude-sdk-routing.test.ts` — routing predicates
+- `services/backends/__tests__/turn-guard.test.ts` — abort orphan-terminal suppression
+- `services/backends/__tests__/lifecycle-decisions.test.ts` — idle/LRU/restart eviction
+- `services/__tests__/acp-event-map.test.ts` / `acp-tool-snapshot.test.ts` — ACP normalization + snapshot merge
+- `services/__tests__/provider-types-parity.test.ts` — **deleted**: provider snapshot types are now single-sourced in `@boocode/contracts/provider-snapshot`; parity is enforced by the single definition
+- `services/__tests__/write_guard.test.ts` (+ `_fuzz`) — path escape + secret-file blocking
+
+### Adding a new backend
+
+1. **Implement `AgentBackend`** — new file under `apps/coder/src/services/backends/`; emit `AgentEvent`s, persist an `agent_sessions` row, honor `isBusy()`.
+2. **Add a routing predicate** — a pure `shouldUseX(task, env?)` sibling to `warm-acp-routing.ts`, plus a unit test.
+3. **Wire the dispatcher** — branch in `runTask` (`dispatcher.ts`) to construct/pool the backend and run `ensureSession`/`prompt`; reuse the shared `onEvent` mapping and `message_complete` publish.
+4. **Extend the schema** — add the backend value to the `agent_sessions_backend_chk` CHECK in `apps/coder/src/schema.sql` (idempotent DROP + re-ADD).
+5. **Register the provider** — entry in `provider-registry.ts` (and `provider-manifest.ts`/`provider-commands.ts` if it has modes/commands).
+
+### Adding a new per-message field
+
+A new per-message coder field silently drops unless **every** mapper is updated: the server read SELECT + `mapCoderMessageRow` (`routes/messages.ts`), `CoderPane.tsx` (`RawCoderMessage`/`CoderMessage`/`mapCoderTimelineRow` + the live `message_complete` reducer), `CoderMessageWire` (`CoderMessageList.tsx`), and `api/types.ts`. The client `mapCoderTimelineRow` whitelists fields — the easiest to forget (this is how the `model` chip once vanished, and what the `model: task.model` on `message_complete` restores).
+
+### Troubleshooting
+
+#### New routes 404 after deploy
+
+The host service keeps running the OLD process until `sudo systemctl restart boocoder` — a stale process shows new routes `404 {error:'not found'}` while old routes still `200`. Restart, don't re-debug. `:9502/api/health` is down ~15–20s after a restart while the startup agent probe runs; an early connection-refused is not a failed deploy.
+
+#### Empty turns / 180s timeouts on OpenCode
+
+Confirm the SSE subscribe passes the session's worktree `directory`; without it, events scope to the server cwd and the session sees zero events. Confirm the opencode model string is provider-prefixed (`llama-swap/<model>`) and present in `~/.config/opencode/opencode.json` — not merely loadable by llama-swap.
+
+#### A stuck tool spinner that never resolves
+
+The tool's terminal `tool_update` isn't being emitted. For the Claude SDK backend, verify the `user` tool_result mapping in `claude-sdk-map.ts`; for ACP, verify `tool_call_update` is reaching `mapSessionUpdate`.
+
+## Related Documentation
+
+- [Cross-App Contract Parity](./coding-standards/cross-app-contract-parity.md) — the coding standard for editing the duplicated provider-snapshot / WS-frame contracts this doc references
+- [Architecture overview](./ARCHITECTURE.md) — system diagram; BooCoder execution paths in context
+- [Provider picker backend plan](./superpowers/plans/2026-05-25-provider-picker-backend.md) — historical design of provider discovery (shipped v2.1.0)
+- `apps/coder/CLAUDE.md` — per-app deep engineering reference (auto-loads when editing `apps/coder/`)
+- `apps/server/CLAUDE.md` — the chat-side inference pipeline BooCoder's native path reuses
+- `openspec/changes/v2-6-persistent-agent-sessions/` — `proposal.md` / `design.md` / `tasks.md`: the rationale behind keying sessions on `chat_id`, the warm-vs-one-shot decision, and the backend abstraction
+- `openspec/changes/claude-sdk-sessionstore/` — the Claude Agent SDK backend + the `user` tool_result mapping batch

docs/coding-standards/cross-app-contract-parity.md

@@ -0,0 +1,202 @@
+---
+paths:
+  - "packages/contracts/src/ws-frames.ts"
+  - "packages/contracts/src/provider-snapshot.ts"
+  - "packages/contracts/src/message-metadata.ts"
+  - "apps/server/src/types/api.ts"
+  - "apps/web/src/api/types.ts"
+  - "apps/coder/src/services/provider-types.ts"
+  - "apps/web/src/components/MessageBubble.tsx"
+  - "apps/server/src/services/inference/turn.ts"
+---
+
+# Cross-App Contract Parity
+
+*Reach for this when adding a new WS frame type, a new sentinel `kind`, or touching the server's `InferenceFrame` loose union or the web's strict `WsFrame` union — contracts whose primary definition now lives in `@boocode/contracts` but that still have split secondary representations in the apps. The fix-it path is [When to Apply](#when-to-apply) + its Verification step.*
+
+- **Status:** proposed
+- **Date Created:** 2026-06-02 00:00
+- **Last Updated:** 2026-06-02 00:00
+- **Authors:**
+  - indifferentketchup (samkintop@gmail.com)
+- **Reviewers:**
+- **Applies To:**
+  - The remaining split contracts that cross app boundaries: the server's `InferenceFrame` loose publish union (`services/inference/turn.ts`), the web's strict `WsFrame` discriminated union (`apps/web/src/api/types.ts`), and the `MessageBubble` sentinel render arm (`apps/web/src/components/MessageBubble.tsx`). The primary contracts (WS-frame Zod schema, provider-snapshot types, `MessageMetadata`, `WorktreeRiskReport`, provider-config schemas) are now **single-sourced in `@boocode/contracts`** — those are governed by editing the package, not by this sync-both-copies rule.
+
+## Introduction
+
+The primary wire contracts (WS-frame Zod schema, provider-snapshot types, provider-config schemas, `MessageMetadata`, `WorktreeRiskReport`, `AgentSessionConfig`) are now **single-sourced in `@boocode/contracts`** — edit `packages/contracts/src/<subpath>.ts` and rebuild the package. There is no second copy to sync for those contracts.
+
+What this standard still governs: adding a new WS frame type or a new sentinel `kind` touches contracts whose primary definition is in the package but that also have split secondary representations in the apps. The server's `InferenceFrame` loose publish union (`services/inference/turn.ts`) and the web's strict `WsFrame` discriminated union (`apps/web/src/api/types.ts`) both still exist separately from the canonical `WsFrameSchema` in the package, and must be updated together with it. The sentinel `MessageBubble` render arm (`apps/web/src/components/MessageBubble.tsx`) has no compile-time guard and still needs updating when a new `MessageMetadata` kind is added to the package.
+
+### Purpose
+
+- **Primary:** prevent *silent runtime* contract breakage. Nothing at compile time links the copies — each app type-checks against its own copy, so `tsc` stays green when they drift. The failure surfaces only at runtime, and silently: a WS frame whose `type` exists on one side but not the other is **dropped at JSON-parse** with no error; a sentinel `kind` added without a render arm shows nothing. Editing every copy in lockstep is the only thing that keeps the contract whole.
+- **Secondary:** the `@boocode/contracts` package's `ws-frames.test.ts` tests schema correctness (accept/reject behavior) and the `KNOWN_FRAME_TYPES` drift probe. `provider-types-parity.test.ts` was deleted when the provider-snapshot types moved to the package. The sentinel render arm still has no automated test.
+- **Side effect:** for the remaining split representations (server `InferenceFrame`, web `WsFrame`), updating them together with the package source in a single commit makes the change reviewable as a matched diff across files.
+
+### Scope
+
+The specific duplicated contracts listed in `paths:` above, inside the `apps/server`, `apps/web`, and `apps/coder` TypeScript packages. It does **not** govern types that live in a single app.
+
+## When to Apply
+
+Walk this before editing a type, schema, enum, or metadata union:
+
+1. **Does this shape exist as a copy in another app?** — Check: `grep -rn "<TypeOrFieldName>" apps/*/src`. If it appears under two or more of `apps/server`, `apps/web`, `apps/coder` → continue. If it lives in exactly one app → see "When NOT to Apply".
+2. **Are you changing its wire shape?** — adding, removing, renaming, or re-typing a field; adding/removing a frame `type`; adding an enum value or a sentinel `kind`. If yes → apply this standard: update the `@boocode/contracts` package source, rebuild, and also update every secondary app-side representation (the server `InferenceFrame` loose union, the web `WsFrame` strict union, and the `MessageBubble` render arm for sentinel kinds), in the **same commit**. If no (a comment or formatting change) → see "When NOT to Apply".
+
+**Exception — the sentinel render arm:** `MessageMetadata` is single-sourced in `@boocode/contracts/message-metadata` (one definition, no second copy). However, a new `kind` is inert until it gets a render branch in `apps/web/src/components/MessageBubble.tsx`. There is no test to catch a missing render arm — when adding a `kind`, the render branch in `MessageBubble.tsx` is the one consumer you must update manually.
+
+**Verification step:** run the guards that exist *now*, before you commit:
+
+```bash
+# Build the contracts package first, then run its tests.
+pnpm -C packages/contracts build
+pnpm -C packages/contracts test ws-frames.test     # WS-frame schema correctness + KNOWN_FRAME_TYPES drift
+# provider-types-parity.test.ts was deleted — provider snapshot types are in @boocode/contracts
+
+# Sentinel render arm has no test — grep for the new kind in the package definition and MessageBubble:
+grep -rn "<new-kind>" packages/contracts/src/message-metadata.ts apps/web/src/components/MessageBubble.tsx
+```
+
+For a **rendering** sentinel kind (`cap_hit` / `doom_loop` / `mistake_recovery`) the new `kind` must appear in `packages/contracts/src/message-metadata.ts` and have a render branch in `MessageBubble.tsx`. The non-rendering `error` arm has no `MessageBubble` branch — for it, only the package definition needs updating.
+
+## When NOT to Apply
+
+- **The type lives in a single app.** Internal server types, web-only view models, coder-only helpers — there is no second copy, so there is nothing to sync. Edit the one definition directly; do **not** manufacture a duplicate in another app "for symmetry." A new cross-app contract should prefer the eventual shared package or, at minimum, ship with its own parity test — not a third hand-synced copy.
+- **A comment- or whitespace-only edit to a `@boocode/contracts` source file.** The package's `ws-frames.test.ts` tests behavior and structure, not formatting, so a comment-only change does not require secondary app-side updates.
+- **The type lives in `@boocode/contracts` and has no split secondary representations.** For the migrated contracts (WS-frame Zod schema, provider-snapshot, provider-config, `MessageMetadata`, `WorktreeRiskReport`) the package IS the single source of truth. Edit the package source; there is nothing to sync in the apps. The split representations that still require multi-file changes are the server `InferenceFrame` loose union, the web `WsFrame` strict union, and the `MessageBubble` render arm — all documented in [When to Apply](#when-to-apply).
+
+## Background
+
+*The history below explains why the duplication existed, not the current state.* The primary contracts (WS-frame Zod schema, provider-snapshot types, provider-config schemas, `MessageMetadata`, `WorktreeRiskReport`) were formerly hand-synced copies guarded by runtime parity tests — because `apps/web/tsconfig.app.json` is a composite project and rejects out-of-include files with **TS6307**, blocking cross-project type import. The WS-frame copies were kept **byte-identical** so a single `readFileSync` equality test could guard them; provider-snapshot copies were kept **text-identical per named block**. These contracts have since moved to `@boocode/contracts` (the `packages/contracts` workspace package), the hand-sync discipline and the byte-parity test are retired, and drift is prevented by there being exactly one definition. The split representations that remain (server `InferenceFrame` loose union, web `WsFrame` strict union, `MessageBubble` render arm) still require lockstep edits when frame types or sentinel kinds are added — that is what this standard now governs.
+
+## Coding Standard
+
+### Edit all copies of a cross-app contract together (cross-cutting)
+
+When you change one copy of a duplicated contract, change the others in the same commit. Each contract family has its own home files and its own (or no) guard.
+
+**WS frame schema — single-sourced at `packages/contracts/src/ws-frames.ts` (imported as `@boocode/contracts/ws-frames`):**
+
+```typescript
+// Single source of truth: WsFrameSchema (Zod), WsFrame (z.infer), KNOWN_FRAME_TYPES.
+// No second copy to sync. When adding a frame type:
+//   1. Add it here (the canonical schema definition) and rebuild the package.
+//   2. Also add to the server's InferenceFrame loose union (services/inference/turn.ts).
+//   3. Also add to the web's strict WsFrame discriminated union (apps/web/src/api/types.ts).
+// Adding a frame also means adding its `type` to KNOWN_FRAME_TYPES — the package
+// test probes every entry for a discriminated branch.
+```
+
+**Provider snapshot types — single-sourced at `packages/contracts/src/provider-snapshot.ts` (imported as `@boocode/contracts/provider-snapshot`):**
+
+```typescript
+// Single source of truth for ProviderSnapshotEntry, ProviderModel, ProviderMode,
+// ThinkingOption, AgentCommand, ProviderSnapshotStatus. No second copy to sync.
+// apps/coder/src/services/provider-types.ts re-exports from this package.
+// provider-types-parity.test.ts was deleted — drift is prevented by the single definition.
+export interface ProviderSnapshotEntry { /* ...fields... */ }
+```
+
+**Sentinel metadata — `packages/contracts/src/message-metadata.ts` (single source) plus the render arm in `apps/web/src/components/MessageBubble.tsx` (no automated test):**
+
+```typescript
+// MessageMetadata is single-sourced in @boocode/contracts/message-metadata.
+// A new *rendering* sentinel kind is a TWO-step change with NO test to catch a miss:
+//   1. packages/contracts/src/message-metadata.ts — add the arm to MessageMetadata, rebuild
+//   2. MessageBubble.tsx             — add the render branch, else it shows nothing
+// The real union has FOUR arms; show it whole so nobody reads two as the full set:
+export type MessageMetadata =
+  | { kind: 'cap_hit';          /* used, limit, agent_name, can_continue */ }
+  | { kind: 'doom_loop';        /* tool_name, args, threshold */ }
+  | { kind: 'mistake_recovery'; /* failure_kinds, count, escalated */ }  // PINNED CONTRACT (#12), mirrored byte-for-byte
+  | { kind: 'error';            /* error_reason, error_text */ };        // NOT a rendered sentinel → 2-file change
+//
+// CROSS-APP CAVEAT for the MessageBubble render branch: the coder feeds rows in via
+// `CoderMessageWire as unknown as Message`, so `metadata` can be undefined there.
+// Null-guard the loose way — `message.metadata?.kind === 'x'` or `metadata != null` —
+// NEVER `metadata !== null` (undefined !== null is true → `.kind` throws → blank
+// screen, and tsc can't see it). See apps/web/CLAUDE.md.
+```
+
+**What to avoid:**
+
+```typescript
+// ANTI-PATTERN: editing only the package schema without updating the app-side representations.
+// Add a new frame type to packages/contracts/src/ws-frames.ts but not to the
+// web's strict WsFrame union (apps/web/src/api/types.ts): tsc stays green because
+// they're separate projects, but the frontend silently discards the frame at
+// JSON-parse. A half-edited contract is invisible to the type-checker; never land one.
+```
+
+**Project references:**
+- `packages/contracts/src/ws-frames.ts` — `WsFrameSchema`, `WsFrame`, `KNOWN_FRAME_TYPES` (via `@boocode/contracts/ws-frames`). The two former app-level `ws-frames.ts` copies are deleted.
+- `packages/contracts/src/provider-snapshot.ts` — provider snapshot types (via `@boocode/contracts/provider-snapshot`). The former web mirror block in `apps/web/src/api/types.ts` and the former coder copy in `provider-types.ts` are deleted; `provider-types.ts` now re-exports from the package.
+- `packages/contracts/src/message-metadata.ts` — `MessageMetadata`, `ErrorReason` (via `@boocode/contracts/message-metadata`). The former copies in `apps/server/src/types/api.ts` and `apps/web/src/api/types.ts` are deleted.
+- `apps/web/src/api/types.ts` — the web-local strict `WsFrame` discriminated union (still maintained separately from the canonical schema in the package).
+- `apps/web/src/components/MessageBubble.tsx` — the sentinel render arms (`metadata?.kind` branches).
+
+### A wire-shape change passes through the gate, then a consumer
+
+A frame is published by the server's permissive `InferenceFrame` union (`apps/server/src/services/inference/turn.ts`) but only reaches the UI if the strict schema/union accepts it — permissive publish, strict receive. Keep the **type/schema copies** (this standard's scope) in lockstep so the frame survives validation; then make sure something consumes it.
+
+> **Where consumer-wiring fits.** This standard governs the duplicated *type/schema* copies and the one consumer with no compile-time guard — the sentinel `MessageBubble` render arm. A new WS frame additionally needs a runtime handler to *do* anything: `applyFrame` in `apps/web/src/hooks/useSessionStream.ts` (per-session frames) and `useUserEvents` (user-channel frames), plus the sidebar reducer. That wiring — and the event-dedup discipline around it — is governed by `apps/web/CLAUDE.md`, not by this parity standard. A frame that passes `WsFrameSchema` validation but has no reducer `case` is then silently ignored.
+
+**Correct usage:**
+
+```typescript
+// Adding a WS frame type, all in one commit:
+//   - packages/contracts/src/ws-frames.ts         — WsFrameSchema + WsFrame + KNOWN_FRAME_TYPES (rebuild package)
+//   - apps/server/src/services/inference/turn.ts  — loose InferenceFrame publish union (+ optional fields)
+//   - apps/web/src/api/types.ts                   — strict WsFrame discriminated union (the web gate)
+// The web strict WsFrame is the wire-format gate: a frame whose type isn't in
+// it is dropped at JSON-parse. The loose publish union and the strict gate are
+// BOTH required — permissive publish, strict receive. The canonical schema in the
+// package is validated by the broker fail-closed (Zod) on every publish.
+```
+
+**What to avoid:**
+
+```typescript
+// ANTI-PATTERN: widening the server publish union but not the strict schema.
+// turn.ts now emits { type: 'my_new_frame', ... }; the broker Zod-validates
+// against WsFrameSchema, which doesn't know the type, and fail-closed drops it.
+// The feature "does nothing" with no error in either app's logs.
+```
+
+**Project references:**
+- `packages/contracts/src/ws-frames.ts` — `WsFrameSchema` (the broker's fail-closed validation gate) + `WsFrame` + `KNOWN_FRAME_TYPES`.
+- `apps/server/src/services/inference/turn.ts` — the loose `InferenceFrame` publish union.
+- `apps/web/src/api/types.ts` — the web-local strict `WsFrame` discriminated union.
+- `apps/web/src/components/MessageBubble.tsx` — the consumer for sentinel `MessageMetadata` kinds.
+
+### Keep the package tests; never weaken them
+
+When a package test fails, the fix is to update the package source — not to delete the assertion or skip the test. When adding a **new** nested type to `ProviderSnapshotEntry`, add it to `packages/contracts/src/provider-snapshot.ts` — there is no `names` array to update since `provider-types-parity.test.ts` was deleted; the single definition is the guard.
+
+**What to avoid:**
+
+```typescript
+// ANTI-PATTERN: "fixing" a red package test by deleting the assertion, skipping
+// the it(), or removing a frame type from the tested set. That converts caught
+// drift into a shipped, silent contract break. Fix the package source instead.
+```
+
+**Project references:**
+- `packages/contracts/src/__tests__/ws-frames.test.ts` — schema correctness (accept/reject) and the `KNOWN_FRAME_TYPES` drift probe. (The former server-side `ws-frames.ts file mirror parity` byte-identical test was deleted when the schema moved to the package.)
+- `apps/coder/src/services/__tests__/provider-types-parity.test.ts` — **deleted**: provider snapshot types moved to `@boocode/contracts/provider-snapshot`.
+
+## Additional Resources
+
+### Project Documentation
+
+- [BooCoder Dispatch Backends](../coder-backends.md) — the provider-snapshot contract and the WS-frame mapping in their runtime context (see "Core Types" and the parity notes).
+- [Architecture overview](../ARCHITECTURE.md) — the three surfaces and the shared database the contracts cross.
+- Root `CLAUDE.md` → "Conventions" — the cross-app contract rules (WS frame schema, sentinels, provider snapshot types, JSONB) this standard formalizes; updated to reflect `@boocode/contracts` SSOT.
+- `apps/server/CLAUDE.md` (`services/broker.ts`) — broker validation against the `@boocode/contracts` schema. `apps/coder/CLAUDE.md` — `provider-types.ts` re-exports from the package.
+
+### External Resources
+
+- [Claude Code path-scoped rules](https://code.claude.com/docs/en/memory) — how the `.claude/rules/coding-standards/` index that surfaces this standard is loaded.

docs/features/git-diff-panel/artifacts/decision-log.md

@@ -0,0 +1,361 @@
+# Decision log — Git diff panel
+
+Decisions behind [`feature-specification.md`](../feature-specification.md). Full decisions carry rationale,
+evidence, and rejected alternatives; trivial decisions are one-liners. Shared D# counter.
+
+## Full decisions
+
+### D1 — Placement: a tab inside the file browser
+**Question:** Where does the diff view live in the workspace?
+**Decision:** The diff view lives in the right-side file panel as a Files / Git tab, occupying the same
+slot as the file tree, rather than as a new standalone workspace pane.
+**Rationale:** The request was "instead of the file browser," and the file browser is a right-side sidebar,
+not a workspace-grid pane. The reference design (Paseo) puts Changes / Files tabs in one sidebar slot. A
+new workspace pane would require new pane-kind plumbing for an affordance the user described as a
+replacement, not an addition.
+**Evidence:** User answer (2026-06-02). Codebase: the file browser is the right-rail sidebar; the legacy
+"file_browser" pane kind is unused. Paseo `explorer-sidebar.tsx` (Changes/Files tabs in one slot).
+**Rejected alternatives:**
+- A standalone git-diff workspace pane — rejected: it is an addition, not a replacement, and adds pane
+  plumbing the user did not ask for.
+**Driven by findings:** —
+**Linked technical notes:** —
+**Dependent decisions:** D9, D10.
+**Referenced in spec:** Actors and triggers, Primary flow, User interactions.
+
+### D2 — Scope: the project repository, with two comparison modes
+**Question:** What repository and comparison modes does the panel cover?
+**Decision:** The panel shows the **project repository's** changes, with a selector between **Uncommitted**
+(working tree vs. last commit) and **Committed** (current branch vs. its upstream tracking branch when
+set, otherwise the repository's default branch). It does not show the session agent's separate
+working-copy diff — that remains the pending-changes panel's job. In Committed mode the view labels the
+base it resolved ("Git — branch vs <base>"); when no base resolves the panel falls back to
+Uncommitted and labels the mode as a fallback.
+**Rationale:** The file browser is scoped to the project repository, so the diff "instead of" it should
+share that scope. The user chose both comparison modes (Paseo-style) over a single mode. The agent
+working-copy diff is already surfaced by the pending-changes panel; duplicating it here would create two
+overlapping surfaces. Labeling the base prevents silent ambiguity (F11).
+**Evidence:** User answer (2026-06-02, "Both, with a selector"). Codebase: the file browser and project
+git-metadata are scoped to the project path; agent worktree diffs already flow to the pending-changes
+panel. Paseo uncommitted/committed mode selector. F11 (base unlabeled finding).
+**Rejected alternatives:**
+- Project working tree only — rejected: user wanted both modes.
+- Session agent worktree — rejected: overlaps the pending-changes panel and is not the file browser's scope.
+- No base labeling — rejected (F11): the base is ambiguous between upstream tracking branch and default
+  branch; unlabeled output invites confusion.
+**Driven by findings:** F11.
+**Linked technical notes:** —
+**Dependent decisions:** D3, D4, D5, D11, D13.
+**Referenced in spec:** Outcome, Primary flow, Edge cases and failure modes, Coordinations.
+
+### D3 — Mode auto-selection and session pinning
+**Question:** How is the initial mode chosen and how does it behave across refreshes?
+**Decision:** Auto mode-selection applies on first open only: Uncommitted when the working tree is dirty,
+Committed when it is clean. Once the user selects a mode explicitly it is pinned for the session;
+refreshes do not override it. If a refresh would change the auto-selected mode (e.g. the tree went clean
+while Uncommitted was pinned), the panel briefly notes the change rather than swapping silently.
+**Rationale:** Paseo's convention is auto-select by state. However, a refresh-triggered silent mode swap
+would dislocate the user's view without warning — they could be mid-review and suddenly see a different
+file list (F12). Pinning after explicit selection preserves the user's intent.
+**Evidence:** Paseo convention (auto-select by dirty state). F12 (silent-dislocation finding;
+design-judgment resolution).
+**Rejected alternatives:**
+- Always auto-select on every refresh — rejected (F12): silently dislocates the view when the tree state
+  changes mid-session.
+- No auto-selection (always start in a fixed mode) — rejected: ignores the most useful starting point.
+**Driven by findings:** F12.
+**Linked technical notes:** —
+**Dependent decisions:** D14.
+**Referenced in spec:** Primary flow, Alternate flows and states.
+
+### D5 — Binary and large-file handling
+**Question:** What does the panel show for files it cannot diff or whose diff is too large?
+**Decision:** Binary files show a "Binary file" placeholder instead of a diff body. Files over a display-
+size threshold show "Diff too large to display" in place of the diff body. A git read that does not
+complete within a deadline exits the loading state, shows an error, and offers Refresh. The total
+response payload is bounded so a huge change set cannot stall the panel.
+**Rationale:** Paseo-style caps prevent the panel from hanging or overflowing on large repos. The read-
+deadline (F7) is a distinct concern from the large-result cap: a slow git process can stall the panel
+even when individual files are small.
+**Evidence:** Paseo codebase (display-size caps). F7 (hanging git-read finding; evidence-backed addition).
+**Rejected alternatives:**
+- No cap — rejected: a huge change set can stall or overflow the panel.
+- Combine deadline and size cap into one mechanism — rejected (F7): they address different failure modes
+  (slow process vs. large output); both are needed.
+**Driven by findings:** F7.
+**Linked technical notes:** —
+**Dependent decisions:** —
+**Referenced in spec:** Edge cases and failure modes.
+
+### D6 — v1 actions: stage, unstage, commit, discard (no push)
+**Question:** Which write actions are included in v1, and in which modes are they available?
+**Decision:** v1 includes staging/unstaging files, committing staged files with a message, and discarding a
+file's changes — all available only in Uncommitted mode. Committed mode is read-only review with no write
+actions. Pushing, pulling, PRs, and merges are excluded. Commit author/committer identity is derived
+server-side; the request cannot set or influence it.
+**Rationale:** The user chose to include stage/commit over a read-only view. Remote operations were not
+requested and the assistant-level rule already treats remote writes as out of band, so v1 stops at local
+history. Allowing write actions in Committed mode would mean reverting committed history (per-file resets
+of committed commits), which was not requested and creates a different risk profile. Committer identity
+must be server-derived to prevent the request body from spoofing authorship (F3).
+**Evidence:** User answer (2026-06-02, "Include stage/commit"). Convention: the assistant cannot push to
+remotes (project docs) — signals remotes are deliberately out of band. F3 (committer-identity
+finding). F14 (mode-scoping finding; design-judgment resolution).
+**Rejected alternatives:**
+- Read-only review — rejected by the user.
+- Full git actions incl. push/pull/PR (Paseo's set) — deferred (YAGNI): not requested.
+- Write actions in Committed mode too — rejected (F14): reverting committed history is a distinct,
+  unrequested capability with a different risk profile.
+- Request-supplied commit identity — rejected (F3): allows spoofing; server-derived identity is the only
+  safe source.
+**Driven by findings:** F3, F14.
+**Linked technical notes:** —
+**Dependent decisions:** D7, D8, D12.
+**Referenced in spec:** Primary flow, User interactions.
+
+### D7 — Discard requires a plain confirmation
+**Question:** What confirmation does discard require, and what wording?
+**Decision:** Discarding a file's changes prompts a plain Cancel / Discard confirmation with wording that
+distinguishes the two cases: "Discard changes to X?" for a tracked file (reverts to committed content)
+and "Delete X? It has never been committed and cannot be recovered" for an untracked file (permanently
+removed). Stage, unstage, and commit do not prompt.
+**Rationale:** Discard is the only irreversible action in the set; a confirmation guards an accidental tap,
+especially on mobile. The project's stated preference is plain confirm dialogs, never type-the-name
+patterns. A tracked revert and an untracked permanent delete are different losses — the user deserves to
+know which one they are confirming (F4).
+**Evidence:** Convention: destructive actions use plain Cancel/Confirm dialogs (no type-to-confirm).
+Stage/unstage/commit are reversible (commits can be amended/reset), so they need no prompt. F4
+(tracked-vs-untracked and affordance-separation finding; design-judgment resolution).
+**Rejected alternatives:**
+- No confirmation — rejected: irreversible data loss on a stray tap.
+- Type-the-filename-to-confirm — rejected: against the project's confirmation convention.
+- Single generic confirmation for tracked and untracked — rejected (F4): hides the difference in
+  consequence (revert vs. permanent delete) from the user.
+**Driven by findings:** F4.
+**Linked technical notes:** —
+**Dependent decisions:** D15.
+**Referenced in spec:** Alternate flows and states.
+
+### D8 — Git write is a user action, not an assistant tool
+**Question:** Are the panel's write actions gated by session type (e.g. read-only-assistant sessions)?
+**Decision:** The diff panel's write actions (stage/commit/discard) are available wherever the file panel
+appears, including read-only-assistant sessions, because they are the human user's own UI actions, not
+the AI's. The git-write endpoints are never registered as assistant tools, and the artifact sandbox
+prevents a rendered artifact from invoking them.
+**Rationale:** The "read-only" rule constrains what the AI assistant's tools may do. A human committing
+their own repository through a panel is a different actor; gating the panel by session type would be a
+category error and produce inconsistent behavior across sessions. The artifact-sandbox commitment (F1)
+closes the indirect path an artifact might otherwise exploit.
+**Evidence:** Convention: the read-only invariant is defined over the assistant's tool surface; the file
+browser (also user-driven) already appears in all sessions. F1 (artifact-sandbox finding; evidenced by
+`connect-src 'none'` in the artifact iframe sandbox per BOOCHAT.md output-format section).
+**Rejected alternatives:**
+- Restrict the write actions to write-capable (coder) sessions only — rejected: conflates the assistant's
+  tool permissions with the user's UI affordances; produces inconsistent behavior.
+**Driven by findings:** F1.
+**Linked technical notes:** —
+**Dependent decisions:** D12.
+**Referenced in spec:** Actors and triggers, Coordinations.
+
+### D10 — Refresh on open, on mutation, on turn completion, on demand, with coalescence
+**Question:** When does the panel re-read the repository, and how are concurrent triggers handled?
+**Decision:** The panel re-reads the repository state when the Git tab is opened, after any stage /
+unstage / commit / discard it performs, after an agent turn completes, after the user applies or discards
+a queued change in the pending-changes panel, and on an explicit Refresh control. Concurrent refresh
+triggers are coalesced — a refresh already in flight absorbs later triggers rather than spawning a
+second concurrent read, so the panel settles to a single final snapshot. Continuous file-watching is
+excluded.
+**Rationale:** These triggers cover every event that can change the project repository's state within the
+app's single-user workflow. Coalescence (F8) prevents a burst of triggers (e.g. multiple rapid mutations)
+from causing redundant concurrent reads or a stale intermediate result overwriting a fresher one. A
+continuous file watcher adds cost without a multi-user need.
+**Evidence:** Convention: event-driven refresh follows the session-event / broker model already used for
+other panels. F8 (concurrent-refresh finding; evidence-backed addition).
+**Rejected alternatives:**
+- Continuous file-watch stream — rejected (YAGNI): event- and demand-driven covers the single-user case;
+  deferred under YAGNI.
+- No coalescence (each trigger spawns its own read) — rejected (F8): can produce concurrent reads and
+  stale-snapshot overwrites.
+**Driven by findings:** F8.
+**Linked technical notes:** —
+**Dependent decisions:** —
+**Referenced in spec:** Alternate flows and states.
+
+### D11 — All git operations scoped to the project repository path
+**Question:** How is the git operation target scoped and validated?
+**Decision:** Every read and write the panel performs is confined to the project's own repository. The
+repository root is derived server-side from the session's project record — never from the request. Per-
+file arguments are validated as repo-relative paths and rejected if they escape the repository root.
+User-supplied text (commit message, file arguments) is passed as discrete arguments and never
+interpolated into a shell string.
+**Rationale:** The panel acts on the project repo only. Deriving the root server-side and validating
+per-file arguments closes the path-escape and command-injection vectors (F2). Passing text as discrete
+arguments (not a shell string) ensures user-supplied content cannot be interpreted as git flags or shell
+syntax.
+**Evidence:** Convention: project file operations resolve and scope to the project path via the existing
+path-scoping guard; git-metadata reads already do this. F2 (derivation + argument-safety finding;
+evidenced by the existing path-scoping guard).
+**Rejected alternatives:**
+- Accept a caller-supplied repository path — rejected: needless write surface, no use case.
+- Validate path only at the root level (not per-file arguments) — rejected (F2): per-file arguments can
+  escape the repo root via `../` traversal if not independently validated.
+- Build git invocations as a shell string — rejected (F2): user-supplied content (commit message, file
+  names with special characters) can be interpreted as flags or shell syntax.
+**Driven by findings:** F2.
+**Linked technical notes:** —
+**Dependent decisions:** D12.
+**Referenced in spec:** Coordinations.
+
+### D12 — Git-write security posture
+**Question:** What are the combined security commitments for the git-write surface?
+**Decision:** The git-write surface (stage / commit / discard) has three security commitments: (1) these
+actions are user-initiated UI actions only and are never registered as assistant tools; the artifact
+sandbox prevents a rendered artifact from invoking them; (2) all git operations target only the project's
+own repository, with the root derived server-side and per-file paths validated inside it; (3) commit
+author/committer identity is derived from a server-side source (host git configuration) and cannot be set
+by the request.
+**Rationale:** F1, F2, and F3 each attacked a distinct vector — artifact-driven invocation, path/argument
+injection, and identity spoofing — that D8 and D11 individually did not close. D12 records all three
+commitments together as the complete security posture of the write surface.
+**Evidence:** F1 (artifact-sandbox; `connect-src 'none'` per BOOCHAT.md output-format section).
+F2 (path-scoping guard in the codebase; derivation and validation commitments). F3 (server-derived
+identity commitment; design-judgment that no request field should influence authorship).
+**Rejected alternatives:**
+- Trust the client-supplied repository path — rejected (F2): see D11.
+- Allow request-supplied commit identity — rejected (F3): allows spoofing; no legitimate use case in a
+  single-user app.
+- Rely on session-type gating instead of endpoint-level exclusion from tool registry — rejected (F1):
+  session type is the wrong layer; artifact-sandbox closes the actual indirect path.
+**Driven by findings:** F1, F2, F3.
+**Linked technical notes:** —
+**Dependent decisions:** —
+**Referenced in spec:** Actors and triggers, Coordinations.
+
+### D13 — Committed-mode base resolution and labeling
+**Question:** What is the base for Committed mode, and how is it surfaced when resolution fails?
+**Decision:** Committed mode compares the current branch against its upstream tracking branch when one is
+set, falling back to the repository's default branch (main/master). The panel labels the base it used in
+the mode header ("Git — branch vs <base>"). When no base resolves (no tracking branch and no
+discoverable default branch), the panel falls back to showing uncommitted changes and labels the mode as
+a fallback, rather than erroring or silently swapping.
+**Rationale:** "Base" was undefined in D2, leaving the committed comparison ambiguous (F11). The tracking-
+branch-first resolution matches git's own upstream model and is the most useful default for contributors
+tracking a remote. Labeling the resolved base makes the comparison unambiguous to the user. A labeled
+fallback is more informative than an error and does not leave the panel empty.
+**Evidence:** F11 (base-unlabeled finding; UX-002, JD-002; design-judgment resolution). Git upstream
+model (tracking branch as natural "base" for a contributor's branch).
+**Rejected alternatives:**
+- Always compare against the default branch, ignoring tracking — rejected (F11): wrong for contributors
+  whose tracking branch is a personal fork or a PR target branch, not the default.
+- Error when no base resolves — rejected: leaves the panel useless; an unlabeled fallback is more
+  helpful.
+- Silently swap to uncommitted without a label — rejected (F11): the original spec's behavior; confusing
+  because the mode selector still shows "Committed".
+**Driven by findings:** F11.
+**Linked technical notes:** —
+**Dependent decisions:** —
+**Referenced in spec:** Primary flow, Edge cases and failure modes, User interactions.
+
+### D14 — Mode pinning and first-open auto-selection
+**Question:** Does auto mode-selection persist across refreshes after the user has acted?
+**Decision:** Auto mode-selection applies on first open only. Once the user selects a mode explicitly (via
+the selector), that choice is pinned for the session. Refreshes do not override a pinned mode. If a
+refresh would change the auto-selected mode (e.g. the tree transitioned from dirty to clean while
+Uncommitted was pinned), the panel briefly notes the change rather than swapping silently.
+**Rationale:** Auto-select on every refresh would dislocate the user mid-review without warning —
+illustrated by the scenario where the tree goes clean while the user is reading the uncommitted diff (F12).
+A brief note on a state change preserves awareness without overriding intent.
+**Evidence:** F12 (silent-dislocation finding; design-judgment resolution). D3 (auto-selection origin).
+**Rejected alternatives:**
+- Re-run auto-selection on every refresh — rejected (F12): dislocates the user's active view.
+- No notification on a would-be mode change — rejected: leaves the user unaware that the repository
+  state changed in a way that would normally affect the view.
+**Driven by findings:** F12.
+**Linked technical notes:** —
+**Dependent decisions:** —
+**Referenced in spec:** Primary flow.
+
+### D15 — Discard is irrecoverable; tracked vs. untracked confirmation; separated affordance
+**Question:** What are the full discard semantics and the UI placement of the discard control?
+**Decision:** Discard is hard-delete and irrecoverable. The confirmation dialog uses two distinct wordings:
+"Discard changes to X?" for a tracked file (which reverts to its committed content; the work is lost but
+the file remains in history) and "Delete X? It has never been committed and cannot be recovered" for an
+untracked file (permanent deletion with no recovery path). The Discard affordance is placed in an
+overflow or secondary position rather than as an equal-weight sibling of Stage/Unstage.
+**Rationale:** The spec previously called discard "irrecoverable" but left the git mechanic ambiguous.
+Owning the word and spelling out the two cases (F4) ensures the confirmation is honest. Separating the
+affordance from Stage/Unstage reduces the risk of an accidental tap on mobile (F4, UX concern).
+**Evidence:** F4 (discard-semantics and affordance-separation finding; on-call-engineer OCE-002,
+UX-005, adversarial-security-analyst; design-judgment resolution). Convention: plain
+Cancel/Confirm dialogs.
+**Rejected alternatives:**
+- Single generic confirmation for tracked and untracked cases — rejected (F4): obscures the difference
+  in consequence.
+- Discard at equal weight alongside Stage/Unstage — rejected (F4): accidental-tap risk on mobile.
+**Driven by findings:** F4.
+**Linked technical notes:** —
+**Dependent decisions:** —
+**Referenced in spec:** Alternate flows and states, User interactions.
+
+### D16 — Tab named "Git"
+**Question:** What is the new tab called?
+**Decision:** The new tab is named **Git**, giving a Files / Git tab pair. The existing "Pending Changes"
+panel is not renamed; that rename is out of scope.
+**Rationale:** "Changes" (the working name in the initial spec) collides with "Pending Changes" — the name
+of an existing distinct panel — creating discoverability confusion (F10, UX-001, UX-008, JD-001). "Git"
+is shorter, unambiguous, and describes the surface (the project's git state) without implying overlap
+with the pending-changes panel.
+**Evidence:** F10 (naming-collision finding; design-judgment resolution). Existing surface name: "Pending
+Changes" panel in the codebase.
+**Rejected alternatives:**
+- "Changes" — rejected (F10): collides with "Pending Changes"; confusion in context-switching.
+- Rename "Pending Changes" to disambiguate — rejected (F10): out of scope; would require changes to an
+  existing surface the user did not ask to rename.
+**Driven by findings:** F10.
+**Linked technical notes:** —
+**Dependent decisions:** —
+**Referenced in spec:** Actors and triggers, User interactions, Out of scope.
+
+### D17 — Ambient dirty indicator and empty-state hint
+**Question:** How does the user discover the Git tab when the panel defaults to Files?
+**Decision:** An ambient indicator on the file-panel toggle/header signals the repository is dirty (derived
+from the refresh data already gathered), making the Git tab findable without opening it. When the Git
+view is empty but the session has unapplied pending changes, the empty state hints that those live in the
+pending-changes panel.
+**Rationale:** Without a visual signal the Git tab is invisible until the user already knows to look for it
+(F10, UX-001). The indicator reuses state already gathered by the refresh cycle — no additional read
+needed. The empty-state hint prevents the user from concluding the panel is broken when what they are
+looking for is actually in the adjacent pending-changes panel.
+**Evidence:** F10 (discoverability finding; design-judgment resolution). Refresh cycle already produces
+dirty/clean state (D10).
+**Rejected alternatives:**
+- No ambient indicator (rely on the user knowing the tab exists) — rejected (F10): undiscoverable by
+  new users.
+- Always show dirty indicator (not just when dirty) — rejected: misleading on clean repos.
+**Driven by findings:** F10.
+**Linked technical notes:** —
+**Dependent decisions:** —
+**Referenced in spec:** Actors and triggers, Alternate flows and states.
+
+### D18 — Mobile tap-target and header-fit
+**Question:** What are the layout and accessibility constraints for the new tab and controls?
+**Decision:** All interactive controls in the diff panel follow the app's existing mobile tap-target
+minimum. The Files / Git tab strip and header fit on one line without horizontal scroll or wrapping;
+existing header elements are condensed if needed to maintain fit.
+**Rationale:** The app has an existing toolbar-fit rule (no scroll/wrap on crowded control bars) and a
+mobile-first posture. The new Git tab and its in-panel controls must not break either. Condensing
+existing elements rather than scrolling is the project's established pattern (F15, UX-009, JD-008).
+**Evidence:** F15 (mobile-fit finding; convention). Project convention: toolbars must fit one line (no
+scroll or wrapping); MEMORY.md toolbar-fit rule.
+**Rejected alternatives:**
+- Allow horizontal scroll if the header gets crowded — rejected: against the project's toolbar-fit rule.
+- Wrap the header to a second line — rejected: against the project's toolbar-fit rule.
+**Driven by findings:** F15.
+**Linked technical notes:** —
+**Dependent decisions:** —
+**Referenced in spec:** User interactions.
+
+## Trivial decisions
+
+- D4: Untracked files included in Uncommitted view — untracked files appear in the Uncommitted file list as additions (considered tracked-only; rejected because the user's new files are part of "what changed"). — Referenced in spec: Primary flow.
+- D9: Unified layout, syntax-highlighted — diffs render in a single-column unified layout reusing the existing code highlighter (considered side-by-side; deferred under YAGNI as a desktop-only enhancement). — Referenced in spec: User interactions.

docs/features/git-diff-panel/artifacts/team-findings.md

@@ -0,0 +1,168 @@
+# Team findings — Git diff panel
+
+Review-team findings on [`feature-specification.md`](../feature-specification.md) and resolutions. Team
+(medium): junior-developer, user-experience-designer, adversarial-security-analyst, on-call-engineer.
+Dispatched 2026-06-02. All findings resolved by evidence/convention/design-judgment; none required new
+user input beyond the three foundational answers already given. Shared F# counter. All resolutions
+applied to spec and decision log 2026-06-02.
+
+## Major findings
+
+### F1 — Assistant could drive the new git-write endpoints via a rendered artifact (security)
+- **Raised by:** adversarial-security-analyst (D8). Highest priority.
+- **Concern:** D8 says the read-only-assistant rule covers the AI's tools, not the user's UI. But the AI can
+  emit HTML artifacts; if an artifact could POST to the new stage/commit/discard endpoints using the user's
+  Authelia cookie, the assistant would gain a write path it is forbidden.
+- **Resolved by:** evidence. The HTML artifact iframe is sandboxed with `connect-src 'none'` (per
+  `BOOCHAT.md` output-format section — fetch/WebSocket do not work in artifacts), so an artifact cannot reach
+  the endpoints. Spec gains an explicit commitment: the git-write actions are user-initiated UI actions only,
+  are never registered as an assistant tool, and the artifact sandbox prevents an artifact from invoking them.
+- **Affected decisions:** D8 (expanded), D12 (new).
+- **Affected tech-notes:** —
+- **Changed in spec:** Actors and triggers, Coordinations.
+
+### F2 — D11 scoping needs explicit derivation + argument-safety commitments (security)
+- **Raised by:** adversarial-security-analyst (D11).
+- **Concern:** "confined to the project path" is a destination constraint that doesn't say the path is
+  derived server-side, that per-file arguments are validated to resolve inside the repo, or that the commit
+  message and file arguments are passed as discrete arguments (not shell-interpolated).
+- **Resolved by:** evidence (the existing project path-scoping guard derives roots from the project record,
+  never from the request). Spec/D11 gain three commitments: repository root derived server-side from the
+  session's project; per-file arguments validated as repo-relative and rejected if they escape; commit
+  message and file arguments passed as discrete arguments, never built into a shell string.
+- **Affected decisions:** D11 (expanded), D12 (new).
+- **Affected tech-notes:** —
+- **Changed in spec:** Coordinations.
+
+### F3 — Commit author identity must be server-derived, not request-supplied (security + clarity)
+- **Raised by:** adversarial-security-analyst, junior-developer (JD-004; Open items).
+- **Concern:** identity was deferred entirely to implementation; an unauthenticated local request could set an
+  arbitrary author, and the codebase already hardcodes differing identities elsewhere.
+- **Resolved by:** evidence + commitment. Spec commits: a panel commit's author/committer is derived from a
+  server-side source (host git config or a configured value); the request body cannot set or influence it.
+  The exact source is left to plan-implementation.
+- **Affected decisions:** D6 (expanded), D12 (new).
+- **Affected tech-notes:** —
+- **Changed in spec:** Primary flow, Open items (closed).
+
+### F4 — Discard semantics: own "irrecoverable", distinguish tracked vs untracked, separate the affordance
+- **Raised by:** adversarial-security-analyst (D7), on-call-engineer (OCE-002), user-experience-designer (UX-005).
+- **Concern:** the spec calls discard "irrecoverable" but defers the git mechanic, creating a tension; a
+  tracked-file revert and an untracked-file permanent delete are different losses; and Discard sitting next to
+  Stage at equal weight invites accidental taps on mobile.
+- **Resolved by:** design-judgment. Discard hard-deletes (own the word "irrecoverable"). The confirmation uses
+  two variants — "Discard changes to X?" (tracked, reverts to committed content) vs "Delete X? It has never
+  been committed and cannot be recovered" (untracked). The Discard affordance is separated from Stage/Unstage
+  (an overflow/secondary placement), not an equal-weight sibling button.
+- **Affected decisions:** D7 (expanded), D15 (new).
+- **Affected tech-notes:** —
+- **Changed in spec:** Alternate flows and states, User interactions.
+
+### F5 — Index-lock contention with concurrent agent turns is unnamed (resilience)
+- **Raised by:** on-call-engineer (OCE-001).
+- **Resolved by:** evidence. Spec names the case: when a write fails because the repository is busy (its index
+  is locked by another process, e.g. a concurrent agent turn), the panel communicates "the repository is busy,
+  try again" rather than a raw git error.
+- **Affected decisions:** —
+- **Affected tech-notes:** —
+- **Changed in spec:** Edge cases and failure modes.
+
+### F6 — "Leave state unchanged" is unenforceable for partial failures (resilience wording)
+- **Raised by:** on-call-engineer (OCE-002).
+- **Resolved by:** reword. "Leaves the repository state unchanged" → "leaves the repository as close to its
+  pre-action state as the git layer allows, and the list refreshes to reflect the repository's true state";
+  an untracked-directory discard that fails partway may leave a partially-removed tree, surfaced on refresh.
+- **Affected decisions:** —
+- **Affected tech-notes:** —
+- **Changed in spec:** Edge cases and failure modes.
+
+### F7 — No deadline on a hanging git read (resilience)
+- **Raised by:** on-call-engineer (OCE-003).
+- **Resolved by:** add commitment. If a git read does not complete within a deadline, the panel leaves the
+  loading state, shows an error, and offers Refresh (distinct from the large-result cap in D5).
+- **Affected decisions:** D5 (expanded).
+- **Affected tech-notes:** —
+- **Changed in spec:** Edge cases and failure modes.
+
+### F8 — Concurrent refresh triggers have no coalescence commitment (resilience)
+- **Raised by:** on-call-engineer (OCE-004).
+- **Resolved by:** add commitment. Concurrent refresh triggers are coalesced — a refresh already in flight
+  absorbs later triggers instead of spawning a second concurrent read; the panel settles to a single final
+  snapshot.
+- **Affected decisions:** D10 (expanded).
+- **Affected tech-notes:** —
+- **Changed in spec:** Alternate flows and states.
+
+### F9 — In-progress git states (merge/rebase/cherry-pick/bisect) make writes fail opaquely (resilience)
+- **Raised by:** on-call-engineer (OCE-005).
+- **Resolved by:** add commitment. When the repository is mid-operation (merge, rebase, cherry-pick, or bisect),
+  the panel disables its write affordances and shows the repository's state rather than letting stage/commit/
+  discard fail with raw git errors.
+- **Affected decisions:** —
+- **Affected tech-notes:** —
+- **Changed in spec:** Edge cases and failure modes.
+
+### F10 — The Changes tab is undiscoverable and collides with "Pending Changes" naming (UX)
+- **Raised by:** user-experience-designer (UX-001, UX-008), junior-developer (JD-001).
+- **Resolved by:** design-judgment. (a) The new tab is named **Git** (Files / Git), distinct from the existing
+  "Pending Changes" panel; the existing panel is NOT renamed (out of scope). (b) An ambient indicator on the
+  file-panel toggle/header signals the repository is dirty (derived from the refresh data already gathered),
+  so the tab is findable. (c) When the Git view is empty but the session has unapplied pending changes, the
+  empty state hints that those live in the pending-changes panel.
+- **Affected decisions:** D16 (new tab name), D17 (new dirty indicator + empty-state hint).
+- **Affected tech-notes:** —
+- **Changed in spec:** Actors and triggers, Alternate flows and states, User interactions, Coordinations, Out of scope.
+
+### F11 — Committed-mode base is undefined and unlabeled (UX + correctness)
+- **Raised by:** user-experience-designer (UX-002), junior-developer (JD-002).
+- **Resolved by:** decision. Committed mode compares the current branch against its **base** — the upstream
+  tracking branch when set, otherwise the repository's default branch (main/master). The view labels the base
+  it used ("Git — branch vs <base>"). When no base resolves, the panel shows uncommitted changes and labels
+  the mode as falling back, rather than silently swapping.
+- **Affected decisions:** D2 (expanded), D13 (new).
+- **Affected tech-notes:** —
+- **Changed in spec:** Primary flow, Edge cases and failure modes, User interactions.
+
+### F12 — Auto-mode selection silently dislocates the view on refresh (UX)
+- **Raised by:** user-experience-designer (UX-003).
+- **Resolved by:** design-judgment. Auto mode-selection applies on first open only; once the user picks a mode
+  it is pinned for the session and refreshes do not override it. A refresh that would change the mode (e.g. the
+  tree went clean) briefly notes the change rather than swapping silently.
+- **Affected decisions:** D3 (expanded), D14 (new).
+- **Affected tech-notes:** —
+- **Changed in spec:** Primary flow, Alternate flows and states.
+
+### F13 — Staged vs unstaged distinction must not be color-only (UX/accessibility)
+- **Raised by:** user-experience-designer (UX-004).
+- **Resolved by:** add commitment. Staged and unstaged files are distinguished by more than color (a label/icon,
+  and grouping into staged/unstaged sections); each stage/unstage control carries an accessible name that
+  includes the file path.
+- **Affected decisions:** —
+- **Affected tech-notes:** —
+- **Changed in spec:** Primary flow, User interactions.
+
+### F14 — Discard's availability across modes is unspecified (clarity)
+- **Raised by:** junior-developer (JD-003).
+- **Resolved by:** decision. Stage, unstage, commit, and discard are available only in Uncommitted mode;
+  Committed mode is read-only review (no per-file revert of committed history in v1).
+- **Affected decisions:** D6 (scoped), D15 (new).
+- **Affected tech-notes:** —
+- **Changed in spec:** User interactions, Alternate flows and states.
+
+### F15 — Mobile fit + tap-target convention for the new tab and controls (UX)
+- **Raised by:** user-experience-designer (UX-009), junior-developer (JD-008).
+- **Resolved by:** convention. All interactive controls in the panel follow the app's existing mobile tap-target
+  minimum; the Files / Git tab strip and header fit one line without horizontal scroll or wrapping (the project's
+  toolbar-fit rule), condensing existing header elements if needed.
+- **Affected decisions:** D18 (new).
+- **Affected tech-notes:** —
+- **Changed in spec:** User interactions.
+
+## Minor edits
+
+- F16: Successful commit shows a brief, non-blocking success confirmation (not just files disappearing) — user-experience-designer (UX-006) — **Affected decisions:** — **Affected tech-notes:** — **Changed in spec:** Primary flow.
+- F17: Error placement — commit-area errors appear by the commit control, per-file action errors appear in the affected file row — user-experience-designer (UX-007) — **Affected decisions:** — **Affected tech-notes:** — **Changed in spec:** Edge cases and failure modes.
+- F18: Which service runs the git read vs write operations (read-only server vs write-capable host service) is an architecture/module-boundary decision routed to plan-implementation; the spec stays behavioral ("the system performs…") — junior-developer (JD-005) — **Affected decisions:** — **Affected tech-notes:** — **Changed in spec:** — (plan-implementation input).
+- F19: The git-write surface is the larger half of v1; implementation should sequence diff-display before the write actions even within v1 — junior-developer (JD-007) — **Affected decisions:** — **Affected tech-notes:** — **Changed in spec:** — (plan-implementation note).
+- F20: The refresh-on-pending-apply and refresh-on-turn-complete triggers require an event/frame wiring that must follow the project's WS-frame / sessionEvents parity steps — junior-developer (JD-009) — **Affected decisions:** — **Affected tech-notes:** — **Changed in spec:** — (plan-implementation note).
+- F21: D8's commit-button-in-a-read-only-session affordance needs no extra label; the "Git" tab name and dirty indicator make it clearly the user's own git surface, not assistant output — junior-developer (JD-006) — **Affected decisions:** D8 confirmed, no extra label needed — **Affected tech-notes:** — **Changed in spec:** — (D8 confirmed).

docs/features/git-diff-panel/feature-specification.md

@@ -0,0 +1,203 @@
+# Feature specification — Git diff panel
+
+## Source
+
+No formal upstream PRD. Authored from a direct request (2026-06-02): "add a git diff panel that can be
+shown instead of the file browser, similar to Paseo," plus a read-only review of the Paseo reference at
+`/opt/forks/paseo`. Ground-truth conventions drawn from the project's own docs and existing surfaces.
+
+## Outcome
+
+A person working in a session can review the uncommitted (and on-branch) changes of the project's
+repository in a diff view that lives in the same right-side panel slot as the file browser, switching
+between the two with a tab. From that view they can read each changed file's diff, stage and unstage
+files, commit staged work with a message, and discard a file's changes — without leaving the session or
+opening a terminal. The view tells them, at a glance, which files changed and by how much, and stays
+current as agents and the user make edits.
+
+## Actors and triggers
+
+- **The session user** (single user) opens the right-side file panel and switches its tab from Files to
+  Git. The Git tab is the trigger; switching back to Files restores the file tree in the same slot
+  ([D1](artifacts/decision-log.md#d1--placement-a-tab-inside-the-file-browser)).
+- The panel is available in any session that has the file panel, because the stage / commit / discard
+  actions are the human user's own UI actions, not assistant tools — the AI has no access to these
+  endpoints, and the artifact sandbox prevents a rendered artifact from reaching them
+  ([D8](artifacts/decision-log.md#d8--git-write-is-a-user-action-not-an-assistant-tool),
+  [D12](artifacts/decision-log.md#d12--git-write-security-posture)).
+- An ambient indicator on the file-panel header signals the repository is dirty, making the Git tab
+  findable without opening it ([D17](artifacts/decision-log.md#d17--ambient-dirty-indicator-and-empty-state-hint)).
+
+## Primary flow
+
+1. The user opens the right-side file panel and selects the **Git** tab.
+2. The panel shows the changes of the **project's repository**, defaulting its comparison mode by the
+   repository state on first open: **Uncommitted** (working tree vs. the last commit) when the working
+   tree is dirty, **Committed** (the current branch vs. its base) when it is clean. Once the user
+   selects a mode explicitly, that choice is pinned for the session and subsequent refreshes do not
+   override it; if a refresh would change the auto-selected mode (e.g. the tree went clean while
+   Uncommitted was pinned), the panel briefly notes the change rather than swapping silently
+   ([D2](artifacts/decision-log.md#d2--scope-the-project-repository-with-two-comparison-modes),
+   [D3](artifacts/decision-log.md#d3--mode-auto-selection-and-session-pinning),
+   [D14](artifacts/decision-log.md#d14--mode-pinning-and-first-open-auto-selection)).
+3. The panel presents a list of changed files, each with its path, change type (added / modified /
+   deleted / renamed / untracked), and an added/removed line count. In Committed mode the header labels
+   the base used ("Git — branch vs <base>")
+   ([D13](artifacts/decision-log.md#d13--committed-mode-base-resolution-and-labeling)).
+4. The user expands a file to read its diff inline; collapsing hides it again. A control expands or
+   collapses all files at once.
+5. The user **stages** or **unstages** individual files. Staged and unstaged files are grouped into
+   separate sections and distinguished by both a label/icon and grouping — not color alone — and each
+   stage/unstage control carries an accessible name that includes the file path.
+6. The user writes a commit message and **commits** the staged files. The commit's author and committer
+   identity is derived from a server-side source; the request cannot set or influence it
+   ([D12](artifacts/decision-log.md#d12--git-write-security-posture)). On success the committed files
+   leave the list, the panel refreshes to the new repository state, and a brief non-blocking confirmation
+   is shown ([D6](artifacts/decision-log.md#d6--v1-actions-stage-unstage-commit-discard-no-push)).
+7. The user may switch the comparison mode explicitly (Uncommitted ↔ Committed) at any time; the file
+   list and counts update to the selected mode, and the choice is pinned for the remainder of the session.
+
+## Alternate flows and states
+
+- **Loading:** while the first difference is being computed the panel shows a brief loading indicator in
+  place of the file list.
+- **Empty (no changes):** when the selected mode has no changes the panel shows a mode-specific empty
+  message ("No uncommitted changes" / "No changes vs. the base branch") instead of a file list. When
+  the Git view is empty but the session has unapplied pending changes, the empty state hints that those
+  live in the pending-changes panel
+  ([D17](artifacts/decision-log.md#d17--ambient-dirty-indicator-and-empty-state-hint)).
+- **Discard a file:** the user discards a single file's changes from an overflow or secondary affordance,
+  separated from the Stage/Unstage controls (not an equal-weight sibling). Because discard is
+  irrecoverable, the panel asks for a plain confirmation before acting, with wording that distinguishes
+  the two cases: "Discard changes to X?" for a tracked file (which returns to its committed content) and
+  "Delete X? It has never been committed and cannot be recovered" for an untracked file (which is
+  permanently removed). On confirmation the file's changes are applied and the list refreshes
+  ([D7](artifacts/decision-log.md#d7--discard-requires-a-plain-confirmation),
+  [D15](artifacts/decision-log.md#d15--discard-is-irrecoverable-tracked-vs-untracked-confirmation-separated-affordance)).
+- **Commit with an empty message or nothing staged:** the commit control is unavailable until at least one
+  file is staged and a non-empty message is present.
+- **Refresh:** the panel re-reads the repository state when the Git tab is opened, after any stage /
+  unstage / commit / discard it performs, after an agent turn completes, after the user applies or
+  discards a queued change in the pending-changes panel, and on an explicit Refresh control. Concurrent
+  refresh triggers are coalesced — a refresh already in flight absorbs later triggers rather than
+  spawning a second concurrent read, so the panel settles to a single final snapshot
+  ([D10](artifacts/decision-log.md#d10--refresh-on-open-on-mutation-on-turn-completion-on-demand-with-coalescence)).
+
+## Edge cases and failure modes
+
+- **Not a git repository:** when the project's path is not a git repository the Git tab is not offered;
+  the file panel stays on Files only.
+- **Binary files:** a changed binary file appears in the list with its path and change type but its body
+  shows a "Binary file" placeholder instead of a diff.
+- **Very large diffs:** a file whose diff exceeds a display threshold appears in the list with its path and
+  counts but its body shows a "Diff too large to display" placeholder; a git read that does not complete
+  within a deadline exits the loading state, shows an error, and offers Refresh; the overall response is
+  bounded so a huge change set cannot stall the panel
+  ([D5](artifacts/decision-log.md#d5--binary-and-large-file-handling)).
+- **A git action fails:** the panel surfaces the failure as an inline error — commit-area errors appear
+  near the commit control; per-file action errors appear in the affected file row. The panel leaves the
+  repository as close to its pre-action state as the git layer allows; the list refreshes to reflect the
+  repository's true state.
+- **Repository busy (index locked):** when a write fails because the repository's index is locked by
+  another process (e.g. a concurrent agent turn), the panel communicates "the repository is busy, try
+  again" rather than a raw error.
+- **In-progress git operations:** when the repository is mid-operation (merge, rebase, cherry-pick, or
+  bisect), the panel disables its write affordances and shows the repository's current state, rather than
+  allowing stage / commit / discard to fail with raw errors.
+- **Concurrent edits during a read:** the displayed diff is a snapshot at read time; a later edit is picked
+  up on the next refresh rather than mutating the view mid-read.
+- **The base branch cannot be resolved** (Committed mode, no discoverable base): the panel falls back to
+  showing uncommitted changes and labels the mode as a fallback, rather than silently swapping or erroring
+  ([D13](artifacts/decision-log.md#d13--committed-mode-base-resolution-and-labeling)).
+
+## User interactions
+
+- A **Files / Git** tab switch in the file panel header. The diff view occupies the same slot as the
+  file tree; only one is shown at a time. The tab strip and header fit on one line without horizontal
+  scroll or wrapping; all interactive controls meet the app's existing mobile tap-target minimum. The
+  tab affordance and the panel work the same on mobile (where the panel is a slide-in drawer) as on
+  desktop ([D16](artifacts/decision-log.md#d16--tab-named-git),
+  [D18](artifacts/decision-log.md#d18--mobile-tap-target-and-header-fit)).
+- An **ambient dirty indicator** on the file-panel toggle/header when the repository is dirty
+  ([D17](artifacts/decision-log.md#d17--ambient-dirty-indicator-and-empty-state-hint)).
+- A **comparison-mode** selector (Uncommitted / Committed) at the top of the Git view.
+- Per-file rows showing path, change type, and an added/removed count, each expandable to reveal a
+  syntax-highlighted unified diff, with an expand-all / collapse-all control.
+- Files grouped into **staged** and **unstaged** sections; each section is labeled and the grouping
+  itself is the primary distinction (supplemented by a per-file label/icon), not color alone; each
+  stage/unstage control carries an accessible name including the file path.
+- Per-file **Stage / Unstage** affordances and a **Discard** affordance in an overflow or secondary
+  position (not an equal-weight sibling of Stage/Unstage), and a **commit message** field with a
+  **Commit** action. Stage / Unstage / Commit / Discard are available only in Uncommitted mode;
+  Committed mode is read-only review
+  ([D6](artifacts/decision-log.md#d6--v1-actions-stage-unstage-commit-discard-no-push),
+  [D15](artifacts/decision-log.md#d15--discard-is-irrecoverable-tracked-vs-untracked-confirmation-separated-affordance)).
+- A **Refresh** control.
+- Diffs render in a single (unified) layout; additions and removals are visually distinguished with line
+  numbers ([D9](artifacts/decision-log.md)).
+
+## Coordinations
+
+- **The file panel** hosts the view and owns the Files ↔ Git tab state.
+- **The project repository** is the single source of truth for the diff and the target of stage / commit /
+  discard. The repository root is derived server-side from the session's project record; per-file
+  arguments are validated to resolve inside the repository and rejected if they escape it; user-supplied
+  text (commit message, file targets) is passed as discrete arguments and never interpreted as commands.
+  The git-write actions are never registered as assistant tools; the artifact sandbox prevents a rendered
+  artifact from invoking them
+  ([D11](artifacts/decision-log.md#d11--all-git-operations-scoped-to-the-project-repository-path),
+  [D12](artifacts/decision-log.md#d12--git-write-security-posture)).
+- **The pending-changes panel** remains the place where unapplied agent edits (held in a separate working
+  copy) are reviewed and applied; the diff panel reflects the project repository's real state, so applying
+  or discarding a pending change is one of the events that refreshes the diff panel. The two panels are
+  complementary, not duplicates ([D2](artifacts/decision-log.md#d2--scope-the-project-repository-with-two-comparison-modes)).
+- **Agent turns and the user's own edits** change the repository; turn completion is a refresh trigger.
+
+## Out of scope
+
+- Pushing, pulling, creating pull requests, merging, or any operation that talks to a remote.
+- Per-line or per-hunk review comments and "send selected lines to an agent" — that is a separate feature
+  (the diff-line re-prompt item), and this panel deliberately does not build a line-selection/commenting
+  surface.
+- Side-by-side (split) diff layout.
+- Staging or discarding individual hunks/lines (stage and discard operate at whole-file granularity).
+- A live file-system watcher that streams diffs as files change on disk; refresh is event- and
+  demand-driven, not continuous.
+- Showing the session agent's separate working-copy diff in this panel; that remains the pending-changes
+  panel's job.
+- Renaming the existing pending-changes panel; naming and scope changes to that panel are out of scope
+  for this feature.
+
+## Deferred (YAGNI)
+
+- **Push / pull / pull-request / merge actions.** Deferred — not requested (the request was "stage/commit"),
+  and the assistant-level no-remote-write rule signals remotes are out of band for now. Reopening trigger: a
+  stated need to publish commits from the panel. Evidence gate failed: no user-described need.
+- **Side-by-side diff layout.** Deferred — the primary surface is mobile-first and unified reads well there;
+  a split layout is a desktop-only enhancement. Reopening trigger: a request to compare wide files
+  side-by-side on desktop. Evidence gate: simpler unified version satisfies the stated need.
+- **Per-hunk staging / discarding.** Deferred — whole-file granularity covers the stated stage/commit need.
+  Reopening trigger: a request to commit part of a file.
+- **Continuous file-watch streaming of the diff.** Deferred — event- and demand-driven refresh covers a
+  single-user workflow without a watcher's cost. Reopening trigger: the diff is observed to feel stale
+  between refresh events in practice.
+
+## Open items
+
+- None. Commit author/committer identity is settled: derived server-side from the host git configuration;
+  the request cannot set or influence it (F3, [D12](artifacts/decision-log.md#d12--git-write-security-posture)).
+
+## Summary
+
+A Files / Git tab in the right-side file panel that shows the project repository's diff in two modes
+(uncommitted vs. HEAD, and the branch vs. its upstream/default base, auto-selected by repo state on
+first open and then pinned to the user's choice), lets the user stage, unstage, commit (with
+server-derived identity), and discard whole files (with irrecoverable-discard confirmation distinguishing
+tracked and untracked cases), and stays current via coalesced event- and demand-driven refresh. Single
+actor (the session user); the panel is complementary to the existing pending-changes panel. The tab is
+named "Git" (Files / Git), distinct from the pending-changes panel. An ambient dirty indicator makes it
+findable. Write affordances are disabled during in-progress git operations. 18 decisions recorded. Four
+items deferred under YAGNI (remote actions, split layout, per-hunk granularity, file-watch streaming).
+Review team: junior-developer, user-experience-designer, adversarial-security-analyst, on-call-engineer.
+No load-bearing mechanics required a technical-notes file (the git mechanics are discoverable from the
+codebase's existing git-metadata path).

docs/plans/post-review-backlog/artifacts/.discovery-notes.md

@@ -0,0 +1,76 @@
+# Discovery notes — post-review-backlog plan
+
+Single source of truth for project context. Specialists: read this first, do NOT re-grep what is here.
+Search further only for what your domain needs that is not covered.
+
+## Tech stack
+
+- Monorepo, pnpm workspaces: `apps/server` (BooChat — Fastify + postgres, native inference, read-only tools),
+  `apps/web` (React + Vite SPA), `apps/coder` (BooCoder — host systemd service, write tools + external-agent
+  dispatch, port 9502), `apps/booterm` (PTY/tmux). TypeScript strict, NodeNext (`.js` import suffixes) on
+  server + coder.
+- Tests: vitest (pinned ^3). server `pnpm -C apps/server test`; coder `pnpm -C apps/coder test`
+  (`globals:false` — import describe/it/expect). Include glob `src/**/__tests__/**/*.test.ts`. No web test
+  harness, no linters. DB-integration tests opt-in via `DATABASE_URL` + `describe.runIf`.
+- Deploy: apps/coder → `sudo systemctl restart boocoder`; apps/web|server → `docker compose up --build -d boocode`.
+- Postgres 16, DB `boochat`. Two schema files: `apps/server/src/schema.sql` (sessions/chats/messages/
+  message_parts) + `apps/coder/src/schema.sql` (agent_sessions, worktrees, pending_changes, available_agents,
+  checkpoints, claude_session_entries, tasks extension).
+
+## ADRs / coding standards found
+
+- No `docs/adr/` directory. Architectural decisions live in `boocode_roadmap.md` (Decisions log) +
+  per-app `CLAUDE.md` files (auto-loaded when editing that subtree) + `openspec/changes/archived/`.
+- Coding standards: `docs/coding-standards/` (canonical), surfaced via `.claude/rules/coding-standards/`
+  path-scoped index files. Not loaded automatically; open on demand.
+- Cross-cutting conventions in root `CLAUDE.md` "Conventions" section (WS-frame parity, sentinels, JSONB
+  via `sql.json`, event dedup discipline, deploy-by-surface).
+
+## Code touch points (per scope-brief item)
+
+- **F1 task-cancel:** `apps/coder/src/services/dispatcher.ts` (private `ac=new AbortController()` at
+  ~316/655/991/1248; `inflight=Map<sessionId,Promise>` at :56 — no per-task AbortController registry);
+  `apps/coder/src/routes/tasks.ts:110-148` (cancel route — inference.cancel + DB only); `routes/messages.ts:388`
+  (session stop); backends honor `ctx.signal`: `pty-dispatch.ts:159` (child.kill), `backends/warm-acp.ts:318`
+  (session/cancel), `backends/opencode-server.ts:775` (session.abort), `backends/claude-sdk.ts:209` (interrupt).
+  Frontend `apps/web/src/components/panes/CoderPane.tsx:987` handleStop; `api/client.ts:395` cancelTask.
+- **F2 parser prune:** `apps/server/src/services/inference/tool-call-parser.ts` (exports extractToolCallBlocks,
+  stripToolMarkup, parseXmlToolCall, parseInvokeToolCall, isPlaceholderArgValue, XML_/INVOKE_ consts).
+  Live consumers: `stream-phase.ts:263-284` (extractToolCallBlocks, text-delta fallback path), `:285-294`
+  (structured tool-call path — authoritative today), `tool-phase.ts:122` + `error-handler.ts:25,106`
+  (stripToolMarkup). llama-swap native `--jinja` parsing confirmed ON (external host `:8401`).
+- **F3 xml logging:** `tool-call-parser.ts:65` console.debug; one call site in `stream-phase.ts` executeStreamPhase.
+- **F4 notify-hook:** agent config paths `~/.claude/settings.json`, `~/.qwen/settings.json`,
+  `~/.config/goose/`; existing readers `claude-command-discovery.ts:84`, `qwen-settings.ts`,
+  `provider-registry.ts`. Existing normalize helper `apps/coder/src/services/normalize-agent-status.ts`
+  (`normalizeAgentEvent`). Existing status publish wired at dispatcher turn boundaries (v2.7.6);
+  `index.ts:86` references #10. `permission-waiter.ts:47` has a `PermissionHooks` registry.
+- **F5 compaction surfacing:** `apps/coder/src/services/backends/opencode-server.ts` SSE arm handling
+  (~215-311 region); WS frame parity → server `ws-frames.ts` + web `apps/web/src/api/types.ts` (`WsFrame`).
+- **F6 resilience:** `apps/server/src/services/inference/stream-phase.ts:261` (`for await ... result.fullStream`),
+  abort check at :333, usage at :343. Frontend 60s `discard_stale` watchdog is the only stall guard today.
+- **F7 session-history MCP tool:** `apps/coder/src/services/mcp-server.ts` (existing BooCoder MCP tools);
+  read path `messages_with_parts` view.
+- **F8 diff-line UX:** diff UI component NOT located by `git ls-files apps/web | grep -i diff` (returned
+  empty) — UX specialist must locate the actual diff/changes panel component (BOOCODER.md calls it
+  "DiffPanel"; may be named differently or nested). Routes through dispatcher + AgentComposerBar.
+- **F9 retire :9502:** `apps/coder/web/` package + static serve in `apps/coder/src/index.ts` + coder build
+  scripts/Dockerfile. KEEP WS + REST routes.
+
+## Recent activity / precedent
+
+- HEAD `e5ce01a` (v2.7.11). v2.7.x line (relicense, write-edit-robustness, sampling-streamjson-tokens,
+  mistake-tracker-ledger, claude-sdk-sessionstore, agent-status-normalize, UI batches) all shipped 2026-06-01.
+- Pure-helper + TDD precedent for extraction: `backends/turn-guard.ts`, `backends/lifecycle-decisions.ts`,
+  `mistake-tracker.ts` (pure module + unit test, then wire). F1/F2/F6 should follow it.
+- Parallel-disjoint-file agent precedent: v2.7.0/v2.7.1/v2.7.3 each built by 3 parallel agents over disjoint
+  files — relevant to decomposition/sequencing.
+
+## Enumerated gaps (searched, not found)
+
+- No `feature-specification.md` — `scope-brief.md` is the ground-truth stand-in.
+- No `docs/adr/`.
+- Diff UI component filename not found via naive grep (F8) — needs UX specialist location.
+- llama-swap config is NOT in-repo (external host `:8401`); native-jinja state confirmed by live probe only.
+- F8 (diff-line UX) and F4 (notify-hook) are the two items most likely to need their own plan-a-feature; they
+  have no behavioral spec beyond the review-doc pattern description.

docs/plans/post-review-backlog/artifacts/implementation-decision-log.md

@@ -0,0 +1,147 @@
+# Implementation Decision Log: Post-Review Backlog (F1–F9)
+
+<!--
+This file records every implementation decision committed while planning the post-review backlog.
+Behavioral and implementation statements live in [../feature-implementation-plan.md](../feature-implementation-plan.md) —
+this file captures the question, rationale, evidence, and rejected alternatives for each decision.
+Round-by-round history lives in [implementation-iteration-history.md](implementation-iteration-history.md).
+-->
+
+Source of truth: [../scope-brief.md](../scope-brief.md) (ground-truth spec stand-in) and
+[synthesis-input.md](synthesis-input.md) (the consolidated Round-1 specialist aggregation; its file:line
+evidence is treated as verbatim). The D-N counter is shared across the Trivial and Full sections below.
+
+## Trivial decisions
+
+- D-2: F3 logger threading shape — pass an optional `log?: { debug }` param to `extractToolCallBlocks` from its single call site in `stream-phase.ts` `executeStreamPhase`; no interface (one site, one impl). — Referenced in plan: Implementation Approach (F2+F3), Decomposition and Sequencing.
+- D-6: F7 query shape — read `messages_with_parts` `WHERE role != 'system'` (strips sentinels), params `session_id` + optional `chat_id` + `limit` (default 50, max 200), `ORDER BY created_at ASC`, returns `{role,content,...}[]`. — Referenced in plan: Implementation Approach (F7), External Interfaces.
+- D-9: Patch-tag-per-unit — each ready item ships as its own sequential patch tag (one batch per coherent unit), not a minor bump; Sam declined v2.8.0 twice. — Referenced in plan: Decomposition and Sequencing, Operational Readiness.
+- D-10: F1 Stop-button terminal label — render a muted "Stopped" label (not red, not a toast) for `status='cancelled'`. — Referenced in plan: Implementation Approach (F1), Testing Strategy.
+
+## Full decisions
+
+### D-1: F1 cancel registry shape and finalization-fix scope
+
+- **Question:** How does a Stop on an external agent task actually abort the running child, and what message-state corruption does wiring that abort newly expose?
+- **Decision:** Add `taskControllers = new Map<string, AbortController>()` inside `createDispatcher`; `taskControllers.set(taskId, ac)` at each of the four run-functions (`dispatcher.ts` ~316/655/991/1248) and `.delete` in the existing `.finally()` (`dispatcher.ts:117`); export `cancelExternalTask(taskId): boolean` (idempotent — `ac.abort()` no-ops when already aborted, so double-Stop and cancel-after-exit are safe). Pass a narrow `ExternalCancelFn` (not the whole dispatcher) into `registerTaskRoutes`, wired in `index.ts:254`. **In the same batch**, fix the two pre-existing finalization bugs this newly makes reachable: (1) the four catch blocks update only `tasks` state and leave the assistant `messages` row `status='streaming'` (the BooChat 5-min sweep is a different process and cannot recover it); (2) the warm-backend success path writes `messages.status='complete'` unconditionally before checking abort (`dispatcher.ts` ~853/1122/1377). Fix via a shared `cancelAndFinalize` helper across all four paths: after `await backend.prompt(...)`, `if (ac.signal.aborted)` → write `status='cancelled'`, publish the terminal `message_complete` frame, emit idle, return; in each catch finalize the message with `WHERE status='streaming'` (idempotent), mapping `AbortError → cancelled` vs `error → failed`.
+- **Rationale:** 4-way specialist consensus (on-call B1, behavioral B1, architect A1, junior). The frontend and all four backends already honor the abort signal correctly (PTY `child.kill` `pty-dispatch.ts:159`; warm-ACP `session/cancel` `warm-acp.ts:318`; opencode `session.abort` `opencode-server.ts:775`; claude-sdk interrupt `claude-sdk.ts:209`); the only missing link is the registry + export + route wiring. Shipping the abort wiring **without** the finalization fixes would convert a silent no-op into a new bug (cancelled turns recorded `complete`, or messages stuck `streaming`), so the two are inseparable in one batch (on-call OCE-001/OCE-002, behavioral B2/B3).
+- **Evidence:** `routes/tasks.ts:110-148` (cancel route calls `cancelPendingPermission` + `inference.cancel` native-only + DB cancelled; never reaches dispatcher); `dispatcher.ts:316/655/991/1248` (four private `ac` unreachable); `cancelExternalTask` absent anywhere (synthesis-input C1); finalization bugs at `dispatcher.ts` catch blocks + ~853/1122/1377 (synthesis-input C2); backend signal honoring cited above (scope-brief F1).
+- **Rejected alternatives:**
+  - Abort wiring only, defer the finalization fixes — rejected because wiring abort makes the `streaming`/`complete` corruption reachable from the UI for the first time; deferring ships a new bug (synthesis-input C2, on-call/behavioral).
+  - Recover stuck messages via the BooChat 5-min sweep — rejected because the sweep runs in a different process (BooChat) and does not see BooCoder's `agent_sessions`/`tasks` finalization (on-call OCE-001).
+  - Pass the whole dispatcher into `registerTaskRoutes` — rejected for over-coupling; a narrow `ExternalCancelFn` is sufficient (architect A1).
+- **Specialist owner:** on-call-engineer (resilience) with software-architect (registry shape).
+- **Revisit criterion:** a fifth external backend is added whose abort contract differs from signal-based cancellation, or the warm-vs-one-shot worktree-cleanup split changes.
+- **Dissent (if any):** none.
+- **Driven by rounds:** R1.
+- **Dependent decisions:** D-7 (F1 terminal state), D-8 (F1 frame-extension over new frame type), D-10.
+- **Referenced in plan:** Implementation Approach (F1), Runtime Behavior, On-Call Resilience Posture, Decomposition and Sequencing, RAID Log (R1).
+
+### D-3: F2 prune scope — option A (prune-now-minimal), keep the load-bearing guard
+
+- **Question:** How far does the tool-call-parser prune go — unexport the dead symbols only, or the full flag-gated retirement of the text-scrape fallback?
+- **Decision:** Option A only. KEEP `extractToolCallBlocks` + `stripToolMarkup` and their types (`ToolCallExtraction`, `ParsedCall`) — the load-bearing `<invoke>`-as-text guard. REMOVE only the `export` keyword (not the implementations) from the 8 zero-external-caller symbols: `isPlaceholderArgValue`, `parseXmlToolCall`, `parseInvokeToolCall`, `partialXmlOpenerStart`, and the 4 consts `XML_TOOL_OPEN/CLOSE`, `INVOKE_TOOL_OPEN/CLOSE`. Zero runtime effect; public export surface goes 11 → 4.
+- **Rationale:** The TS parser is dormant defense-in-depth but the `<invoke>`-as-text path is the *only* guard for "tool call emitted as plain text" — `experimental_repairToolCall` does not cover that case, and the sidecar `--jinja` state is confirmed only by a live probe, not pinned in-repo, so keeping the guard is correct (architect A2, confirms junior OQ-F2c). Unexporting is pure simplification with no behavior change; the relicense already removed the AGPL-dead exports, so there is no license pressure forcing the larger move.
+- **Evidence:** live consumers `stream-phase.ts:263-284` (extractToolCallBlocks text-delta fallback), `tool-phase.ts:122` + `error-handler.ts:25,106` (stripToolMarkup); structured path `stream-phase.ts:285` does all real work today; llama-swap `--jinja` confirmed ON by live probe of `:8401` only (scope-brief F2, synthesis-input C3).
+- **Rejected alternatives:**
+  - Option B — flag-gate the text-scrape fallback, validate native parsing on live qwen3.6 for one release, then delete — rejected (deferred) because there is no evidence qwen3.6 stopped emitting `<invoke>` text on live and the sidecar `--jinja` state is unconfirmed in-repo; deleting the only plain-text-tool-call guard on that basis is unsafe (architect/test-engineer R1). See Deferred (YAGNI).
+  - Delete the 8 symbols' implementations outright — rejected because three of them (`parseXmlToolCall`, `parseInvokeToolCall`, `isPlaceholderArgValue`) are called internally by the retained `extractToolCallBlocks`; only the `export` keyword is dead.
+- **Specialist owner:** software-architect.
+- **Revisit criterion:** a documented multi-session live probe shows zero text-delta tool calls from qwen3.6 (then Option B reopens).
+- **Dissent (if any):** none.
+- **Driven by rounds:** R1.
+- **Dependent decisions:** D-2 (F3 logger — safe because F2 keeps `extractToolCallBlocks`), D-4 (F2 gate test).
+- **Referenced in plan:** Implementation Approach (F2+F3), Decomposition and Sequencing, Testing Strategy, RAID Log (R2), Deferred (YAGNI).
+
+### D-4: F2 fallback gate test — pin the untested guard before pruning
+
+- **Question:** The `<invoke>`-as-text fallback is currently exercised by no test; how do we prevent the prune from silently removing it?
+- **Decision:** Add a gate test before the prune: stub `streamText` to emit a text-delta containing a complete `<invoke>` block; assert the call lands in `result.toolCalls` and the markup is NOT present in `result.content`. The test must stay green through the prune and fail if `extractToolCallBlocks` is ever removed from the text-delta path.
+- **Rationale:** Pruning around an untested load-bearing path risks a silent regression; the gate test converts D-3's "keep the guard" commitment into an enforced invariant (test-engineer T6).
+- **Evidence:** untested fallback at `stream-phase.ts:263-284` (synthesis-input C4, test-engineer T6).
+- **Rejected alternatives:**
+  - Prune without the gate test, relying on review — rejected because the fallback has no current coverage, so a future removal would pass CI silently (test-engineer T6).
+- **Specialist owner:** test-engineer.
+- **Revisit criterion:** the fallback path is intentionally retired under Option B (then this test is rewritten, not deleted).
+- **Dissent (if any):** none.
+- **Driven by rounds:** R1.
+- **Dependent decisions:** none.
+- **Referenced in plan:** Testing Strategy, Decomposition and Sequencing.
+
+### D-5: F6 stall-timeout via AbortSignal.any; no retry
+
+- **Question:** How does BooChat detect and recover a hung llama-swap stream server-side, and does it retry?
+- **Decision:** Wrap the `stream-phase.ts:261` `fullStream` loop with a per-chunk stall deadline. Create a local `stallAc = new AbortController()`, pass `effectiveSignal = AbortSignal.any([signal, stallAc.signal])` to `streamText`, bump a `setTimeout(STALL_TIMEOUT_MS = 90_000)` on each chunk, clear it in the existing `finally`. At the post-loop check (`stream-phase.ts:337`) test `signal?.aborted || stallAc.signal.aborted` and throw `AbortError` (→ `handleAbortOrError` writes `cancelled`). **No retry** at `executeStreamPhase`/`streamCompletion`.
+- **Rationale:** Today a hung stream relies entirely on the frontend 60s `discard_stale` watchdog with zero server-side guard; the 90s server stall-timeout closes that gap and reuses the existing abort/finalize path. Retry is deferred (YAGNI): a retry after a partial stream re-emits already-streamed deltas (`state.accumulated` + live `delta` frames are non-idempotent), which is worse than the current behavior; at single-local-instance scale the user re-sending is the correct recovery (on-call, strong).
+- **Evidence:** `stream-phase.ts:261` fullStream loop, `:333` abort check, `:343` usage; frontend 60s `discard_stale` is the only stall guard today (scope-brief F6, synthesis-input C6).
+- **Rejected alternatives:**
+  - `Promise.race` of the loop against a timeout — rejected in favor of `AbortSignal.any`, which threads cancellation through `streamText` and the existing finalize path cleanly (OQ-F6a, on-call).
+  - Retry/backoff classifier (transient-5xx / stall) — rejected (deferred) because partial-stream re-emit is non-idempotent and llama-swap is a single local instance (synthesis-input YAGNI ledger). See Deferred (YAGNI).
+- **Specialist owner:** on-call-engineer.
+- **Revisit criterion:** llama-swap gains restart-in-place-with-clear-partial, or a second instance is added for failover (then retry reopens).
+- **Dissent (if any):** none.
+- **Driven by rounds:** R1.
+- **Dependent decisions:** none.
+- **Referenced in plan:** Implementation Approach (F6), On-Call Resilience Posture, Testing Strategy, RAID Log (R3), Deferred (YAGNI).
+
+### D-7: F1 terminal state for user Stop — `cancelled`, not `failed`
+
+- **Question:** When a user hits Stop, what terminal `messages.status` does the finalized assistant message land in?
+- **Decision:** `cancelled` for a user-initiated Stop (`AbortError`); `failed` only for a genuine thrown error in the catch path.
+- **Rationale:** A user Stop is a deliberate, non-error outcome; `MessageStatus` already includes `'cancelled'` and the web reducer can map it without a new enum value. Distinguishing `AbortError → cancelled` vs `error → failed` keeps the human-inbox / failure surfaces honest (resolved OQ, on-call/behavioral).
+- **Evidence:** `MessageStatus` includes `'cancelled'`; reducer map point `CoderPane.tsx:299` (synthesis-input F1 UX + resolved OQs).
+- **Rejected alternatives:**
+  - Record user Stop as `failed` — rejected because it pollutes failure surfaces with deliberate user actions (resolved OQ F1 terminal state).
+- **Specialist owner:** behavioral-analyst.
+- **Revisit criterion:** product decides a user Stop should count against a failure/alerting budget.
+- **Dissent (if any):** none.
+- **Driven by rounds:** R1.
+- **Dependent decisions:** D-8, D-10.
+- **Referenced in plan:** Implementation Approach (F1), Runtime Behavior.
+
+### D-8: F1 status surfacing — extend the existing frame, no new frame type
+
+- **Question:** How does the cancelled terminal state reach the web reducer — a new WS frame type, or an extension of the existing one?
+- **Decision:** Extend the coder `message_complete` frame with an optional `status` field (Option A — minimal); map it in the reducer (`CoderPane.tsx:299`). No new frame type, so the cross-app `WsFrame` parity rule does not force a paired strict-union arm beyond the optional field.
+- **Rationale:** Adding a whole new frame type triggers the full cross-app parity dance (server `InferenceFrame`/`ws-frames.ts` + web `WsFrame`) for a single optional value already carried on a terminal frame; an optional field on the existing frame is the smaller change with the same observable result (UX agent).
+- **Evidence:** reducer map point `CoderPane.tsx:299`; cross-app frame parity rule (CLAUDE.md Conventions; scope-brief cross-cutting constraints).
+- **Rejected alternatives:**
+  - New `agent_cancelled` frame type — rejected because it forces a paired strict-union arm in two files for a single optional status value (UX agent, Option A vs B).
+- **Specialist owner:** user-experience-designer.
+- **Revisit criterion:** a second distinct terminal sub-state needs carrying that does not fit `message_complete.status`.
+- **Dissent (if any):** none.
+- **Driven by rounds:** R1.
+- **Dependent decisions:** D-10.
+- **Referenced in plan:** Implementation Approach (F1), External Interfaces.
+
+### D-11: F9 retire :9502 SPA — delete the serve block, keep all API/WS routes
+
+- **Question:** What exactly is removed when retiring the :9502 fallback SPA, and what must stay?
+- **Decision:** Delete the `if (existsSync(webRoot))` block in `index.ts` (~269-289) which already no-ops when the dist is absent; keep the inline 404 handler (`{error:'not found'}`). Remove `apps/coder/web` from `pnpm-workspace.yaml`, the coder build step, and the Dockerfile copy; remove the now-unused `fastifyStatic` import (verify it is only used there). KEEP all `/api/coder/*` REST + WS + `/api/health` + `--mcp` routes — CoderPane depends on them. Optionally add a 2-line `GET /` redirect-to-BooChat (no `fastifyStatic`).
+- **Rationale:** Sam confirmed "I don't use 9502"; primary UI is CoderPane inside BooChat. OQ-F9a resolved: nothing probes `GET /` on :9502 (health is `/api/health`; the compose healthcheck targets the boocode container, not the host-systemd coder), so 404-or-redirect at `/` is safe (architect A5, verified).
+- **Evidence:** serve block `index.ts` ~269-289; `GET /` unprobed (synthesis-input C8, OQ-F9a resolved); scope-brief F9 / DEFERRED #5 removal checklist.
+- **Rejected alternatives:**
+  - Keep the SPA — rejected; Sam greenlit removal and the build step is dead weight (scope-brief F9).
+  - Remove the REST/WS routes too — rejected because CoderPane inside BooChat depends on every `/api/coder/*` route (architect A5).
+- **Specialist owner:** software-architect.
+- **Revisit criterion:** a standalone :9502 UI is ever wanted again (would be a fresh feature, not a revert).
+- **Dissent (if any):** none.
+- **Driven by rounds:** R1.
+- **Dependent decisions:** none.
+- **Referenced in plan:** Implementation Approach (F9), Operational Readiness, Decomposition and Sequencing.
+
+### D-12: F4/F5/F8 disposition under the standing override — document as Blocked, do not halt
+
+- **Question:** The spec-maturity gate tripped on F4/F5/F8; the skill says recommend routing them out. Sam issued a standing override to plan everything. How are they recorded?
+- **Decision:** Proceed with the plan but record F4, F5, F8 in a structurally separate **BLOCKED** tier with their exact blocking open question(s) and recommended resolution path, rather than halting synthesis. F4 → route to `plan-a-feature` (hook-firing-in-unattended-mode premise UNVERIFIED + goose hook mechanism unknown). F5 → SDK capability check (pinned `@opencode-ai/sdk` exposes no compaction event arm); UI treatment (sentinel-row vs ephemeral-frame) stays disputed until the event is confirmed to exist. F8 → route to `plan-a-feature` (no line-selection infra exists, diff source ambiguous). These three do NOT block the ready cluster (F1/F2/F3/F6/F7/F9).
+- **Rationale:** The spec-maturity gate tripped with ≥5 spec-level findings (C9, C11, C12, C13, OQ-F4b, OQ-F8a) concentrated in F4/F5/F8 across junior, behavioral, and UX. Sam pre-acknowledged the WANT items would be planned more shallowly when choosing scope "everything we discussed," so the honest synthesis records them as Blocked with explicit reopen paths rather than fabricating plan-level resolutions or stalling the ready work.
+- **Evidence:** spec-maturity gate TRIPPED (synthesis-input "Spec-maturity gate"); USER OVERRIDE STANDING (same section); blocking OQs OQ-F4a/F4b, OQ-F5a/F5b, OQ-F8a/b/c (synthesis-input Open Questions); claims C9, C11, C12, C13.
+- **Rejected alternatives:**
+  - Halt synthesis and route F4/F5/F8 out before any planning — rejected because Sam's standing override directs the plan to proceed and document (synthesis-input gate section).
+  - Plan F4/F5/F8 at plan-level alongside the ready cluster — rejected because their core premises are unverified (F4) / capability-blocked (F5) / infra-absent (F8); plan-level decisions would rest on unproven assumptions (C9/C11/C13).
+- **Specialist owner:** project-manager.
+- **Revisit criterion:** the named blocking OQ for an item resolves (F4: hooks confirmed to fire unattended + goose format known; F5: SDK compaction event confirmed; F8: diff source chosen + line-selection approach specified) — then that item graduates to its own plan.
+- **Dissent (if any):** none; the gate-trip is acknowledged rather than overridden silently.
+- **Driven by rounds:** R1.
+- **Dependent decisions:** none.
+- **Referenced in plan:** Implementation Approach (Blocked tier), RAID Log (R4, R5, assumptions), Open Items, Deferred (YAGNI).

docs/plans/post-review-backlog/artifacts/implementation-iteration-history.md

@@ -0,0 +1,48 @@
+# Implementation Iteration History: Post-Review Backlog (F1–F9)
+
+<!--
+This file records how the implementation plan for the post-review backlog evolved across discussion rounds.
+Committed decisions live in [implementation-decision-log.md](implementation-decision-log.md) and the primary
+plan lives in [../feature-implementation-plan.md](../feature-implementation-plan.md). It also consolidates
+the project-manager's per-round facilitation output (claim ledger, Open Questions, spec-maturity tags).
+The loop converged in one round; remaining unknowns are spec-level, not resolvable by more specialist rounds.
+-->
+
+## R1: Parallel six-specialist backlog review
+
+- **Specialists engaged:** on-call-engineer, behavioral-analyst, software-architect, test-engineer, user-experience-designer, junior-developer, project-manager (coordinator). Team size: large (cross-subsystem; user chose scope "everything we discussed"). Round cap 3; converged in 1.
+- **New input provided:** Initial inputs — the [scope brief](../scope-brief.md) (ground-truth spec stand-in; two items live-verified 2026-06-02 with file:line evidence) and the [discovery notes](.discovery-notes.md) (per-item code touch points). No prior round; this is the initial sweep.
+- **Claim ledger:** (consolidated, deduped — see [synthesis-input.md](synthesis-input.md) for the full table)
+
+  | # | Claim | State | Spec-maturity |
+  |---|-------|-------|---------------|
+  | C1 | F1 cancel route never aborts external child; no registry/export | Evidenced | plan-level |
+  | C2 | F1 catch blocks leave message `streaming`; success path writes `complete` on abort — fix same batch | Evidenced | plan-level |
+  | C3 | F2 = prune-now-minimal: unexport 8 zero-caller symbols, keep extractToolCallBlocks+stripToolMarkup | Evidenced | plan-level |
+  | C4 | F2 `<invoke>`-text fallback untested → add gate test before prune | Evidenced | plan-level |
+  | C5 | F3 optional logger param, do with F2 (same file) | Evidenced | plan-level |
+  | C6 | F6 stall-timeout via AbortSignal.any, 90s; NO retry (non-idempotent deltas) | Evidenced | plan-level |
+  | C7 | F7 inline MCP tool, messages_with_parts, role!='system', limit 50/200 | Evidenced | plan-level |
+  | C8 | F9 delete SPA block, keep routes; GET / unprobed → safe | Evidenced | plan-level |
+  | C9 | F4 hook-firing in unattended mode UNVERIFIED; goose hook mechanism unknown | Anecdotal (premise) | spec-level |
+  | C10 | F4 dedup rule: confirm running before `blocked`; suppress hook `done` | Evidenced | plan-level |
+  | C11 | F5 pinned @opencode-ai/sdk exposes no compaction arm → blocked on capability check | Evidenced | spec-level |
+  | C12 | F5 UI treatment sentinel-row vs ephemeral-frame | Disputed | spec-level |
+  | C13 | F8 no line-selection infra; diff source ambiguous; needs own spec | Evidenced | spec-level |
+
+- **Open Questions raised:**
+  - F1: terminal state (→ D-7, `cancelled`); registry key (→ D-1, `taskId`); shared finalize helper (→ D-1, yes); warm re-throw on abort (→ D-1, short-circuit on `ac.signal.aborted`).
+  - OQ-F2a (sidecar jinja) → moot under D-3 option A; OQ-F2c (a vs b) → D-3 option A.
+  - OQ-F6a/b/c → D-5 (AbortSignal.any, no retry, 90s).
+  - OQ-F7a (session vs chat id) → D-6 (both, chat_id optional, + limit).
+  - OQ-F9a (GET / probe) → D-11 (unprobed, safe).
+  - OQ-F4a (hooks fire unattended?), OQ-F4b (goose hook format) → UNRESOLVED, spec-level → OI-1, route F4 to plan-a-feature (D-12).
+  - OQ-F5a (SDK compaction event existence/name) → UNRESOLVED, capability check → OI-2, blocks F5 (D-12).
+  - OQ-F5b (sentinel vs ephemeral UI) → UNRESOLVED → OI-3, settle once event confirmed (D-12).
+  - OQ-F8a/b/c (diff source, serialization, new viewer) → UNRESOLVED, spec-level → OI-4, route F8 to plan-a-feature (D-12).
+  - OI-5 (F1 best-effort session-stop leg) → non-blocking, decided at implementation.
+- **Spec-maturity tags:** plan-level — C1-C8, C10 (9 claims). spec-level — C9, C11, C12, C13, plus OQ-F4b and OQ-F8a (≥5 across junior, behavioral, UX). **Spec-maturity gate TRIPPED**, concentrated in the three WANT items F4/F5/F8; F1/F2/F3/F6/F7/F9 are all plan-level and ready. No T#-contradictions.
+- **Resolution source:** evidence (Step 6 specialist findings) for every plan-level OQ (F1, F2, F3, F6, F7, F9); user input for the gate disposition (Sam's standing override → D-12); deferred-to-spec for OQ-F4a/F4b, OQ-F5a/F5b, OQ-F8a/b/c (recorded as OI-1..OI-4, routed out rather than resolved in this loop). The YAGNI gate ran during synthesis: F6 retry, F2 option B, F4 interface, F5 extra compaction arms, F7 reader interface all deferred.
+- **Decisions produced:** D-1, D-2, D-3, D-4, D-5, D-6, D-7, D-8, D-9, D-10, D-11, D-12 (all 12; the loop converged in one round so every decision originates here).
+- **Changed in plan:** all sections (initial authoring) — Source Specification, Outcome, Context, Implementation Approach (TIER 1 READY / TIER 2 BLOCKED), Decomposition and Sequencing, RAID Log, Testing Strategy, Security Posture, Operational Readiness, On-Call Resilience Posture, Definition of Done, Specialist Handoffs, Deferred (YAGNI), Open Items, Summary.
+- **Project-manager next-step recommendation:** Go to synthesis (done — this plan). Build the READY cluster in order F1 → F2+F3 → F6 → F7 → F9 as sequential patch tags; route F4 and F8 to `plan-a-feature` and F5 to an `@opencode-ai/sdk` capability check before any build on those three.