fix(coder): include model in WS snapshot SELECT so the attribution chip survives refresh

CoderPane hydrates from the HTTP listMessages fetch (SELECT has model) AND the WS snapshot frame, and the snapshot handler setMessages-overwrites the HTTP load. The snapshot query in apps/coder/src/routes/ws.ts had its own column list that omitted model, so on coder refresh the chip's model was lost (it showed live via the message_complete frame). One-column fix: add model to that SELECT. CLAUDE.md mapper-chain note updated to list the WS snapshot SELECT.

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

.env.example

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

.gitignore

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

CHANGELOG.md

@@ -2,6 +2,30 @@
 
 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.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`.

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

apps/coder/.env.host

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

apps/coder/CLAUDE.md

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

apps/coder/src/index.ts

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

@@ -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/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/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/agent-backend.ts

@@ -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/server/ws-frames';
+import type { AgentStatus } from './normalize-agent-status.js';
+
+// The exact slice of Broker we need — accepting just the bound method keeps call
+// sites flexible (pass `broker.publishFrame.bind(broker)` or, since the broker's
+// publishFrame doesn't read `this`, `broker.publishFrame` directly).
+type PublishFrame = Broker['publishFrame'];
+
+/**
+ * Best-effort publish of a normalized agent status. The broker's publishFrame
+ * already fail-closes (validates + logs + drops on bad input, never throws), but
+ * we additionally swallow any unexpected error so a publish can NEVER break the
+ * turn it's reporting on.
+ *
+ * @param publishFrame  the session channel publisher (broker.publishFrame)
+ * @param sessionId     WS subscription channel (CoderPane subscribes per-session)
+ * @param chatId        the (chat) half of the (chat, agent) status key
+ * @param agent         the (agent) half of the key
+ * @param status        normalized lifecycle status
+ * @param reason        free-form discriminator (turn_start / turn_complete / …)
+ * @param at            ISO timestamp; defaults to now
+ */
+export function publishAgentStatus(
+  publishFrame: PublishFrame,
+  sessionId: string,
+  chatId: string,
+  agent: string,
+  status: AgentStatus,
+  reason?: string,
+  at: string = new Date().toISOString(),
+): void {
+  try {
+    const frame: WsFrame = {
+      type: 'agent_status_updated',
+      chat_id: chatId,
+      agent,
+      status,
+      ...(reason ? { reason } : {}),
+      at,
+    };
+    publishFrame(sessionId, frame);
+  } catch {
+    // never let a status publish break the turn — best-effort only.
+  }
+}

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

@@ -179,3 +179,73 @@ describe('mapSdkMessage — non-content messages', () => {
     ).toEqual([]);
   });
 });
+
+describe('mapSdkMessage — user tool results', () => {
+  /** A `user` message carrying tool_result blocks (the SDK feeds tool output back here). */
+  function userMsg(content: unknown): SDKMessage {
+    return msg({ type: 'user', message: { role: 'user', content }, parent_tool_use_id: null, uuid: 'u', session_id: 's' });
+  }
+
+  it('maps a string tool_result to a completed tool_update carrying the output', () => {
+    const state = createClaudeSdkMapState();
+    const out = mapSdkMessage(userMsg([{ type: 'tool_result', tool_use_id: 't1', content: 'done' }]), state);
+    expect(out).toEqual<AgentEvent[]>([
+      {
+        type: 'tool_update',
+        toolCall: { toolCallId: 't1', title: 't1', kind: null, status: 'completed', rawInput: undefined, rawOutput: 'done' },
+      },
+    ]);
+  });
+
+  it('marks an is_error result failed', () => {
+    const state = createClaudeSdkMapState();
+    const out = mapSdkMessage(userMsg([{ type: 'tool_result', tool_use_id: 't1', content: 'boom', is_error: true }]), state);
+    const ev = out[0]!;
+    if (ev.type !== 'tool_update') throw new Error('expected tool_update');
+    expect(ev.toolCall.status).toBe('failed');
+    expect(ev.toolCall.rawOutput).toBe('boom');
+  });
+
+  it('flattens array text blocks (skipping non-text) and reuses a prior snapshot title', () => {
+    const state = createClaudeSdkMapState();
+    mapSdkMessage(
+      streamEvent({ type: 'content_block_start', index: 1, content_block: { type: 'tool_use', id: 't2', name: 'view_file', input: {} } }),
+      state,
+    );
+    const out = mapSdkMessage(
+      userMsg([
+        {
+          type: 'tool_result',
+          tool_use_id: 't2',
+          content: [
+            { type: 'text', text: 'line1' },
+            { type: 'image', source: {} },
+            { type: 'text', text: 'line2' },
+          ],
+        },
+      ]),
+      state,
+    );
+    const ev = out[0]!;
+    if (ev.type !== 'tool_update') throw new Error('expected tool_update');
+    expect(ev.toolCall.toolCallId).toBe('t2');
+    expect(ev.toolCall.title).toBe('view_file');
+    expect(ev.toolCall.status).toBe('completed');
+    expect(ev.toolCall.rawOutput).toBe('line1\nline2');
+  });
+
+  it('surfaces a result for an unknown tool_use_id with the id as the title', () => {
+    const state = createClaudeSdkMapState();
+    const out = mapSdkMessage(userMsg([{ type: 'tool_result', tool_use_id: 'orphan-id', content: 'x' }]), state);
+    expect(out[0]).toMatchObject({
+      type: 'tool_update',
+      toolCall: { toolCallId: 'orphan-id', title: 'orphan-id', kind: null, status: 'completed' },
+    });
+  });
+
+  it('ignores non-tool_result blocks and non-array content', () => {
+    const state = createClaudeSdkMapState();
+    expect(mapSdkMessage(userMsg([{ type: 'text', text: 'hi' }]), state)).toEqual([]);
+    expect(mapSdkMessage(userMsg('plain string'), state)).toEqual([]);
+  });
+});

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

@@ -49,6 +49,7 @@ import type { AcpToolSnapshot } from '../acp-tool-snapshot.js';
 type StreamEvent = Extract<SDKMessage, { type: 'stream_event' }>['event'];
 type AssistantContent = Extract<SDKMessage, { type: 'assistant' }>['message']['content'];
 type ContentBlock = AssistantContent extends readonly (infer B)[] ? B : never;
+type UserContent = Extract<SDKMessage, { type: 'user' }>['message']['content'];
 
 /**
  * Caller-owned accumulator threaded across `mapSdkMessage` calls within ONE turn.
@@ -81,6 +82,12 @@ export function mapSdkMessage(msg: SDKMessage, state: ClaudeSdkMapState): AgentE
       return mapStreamEvent(msg.event, state);
     case 'assistant':
       return mapFinalAssistant(msg.message.content, state);
+    case 'user':
+      // Tool RESULTS ride in as user messages (tool_result blocks): the SDK ran
+      // the tool and feeds its output back. Without mapping these, the tool_call
+      // never reaches a terminal snapshot — it persists as status:'running' with
+      // no output and the UI spinner never stops (the bug this fixes).
+      return mapUserToolResults(msg.message.content, state);
     default:
       // system/init, status, result, hooks, task_*, etc. — no turn content here.
       // (The backend reads session_id off the init message and usage/cost off the
@@ -180,6 +187,52 @@ function mapFinalAssistant(content: ContentBlock[], state: ClaudeSdkMapState): A
   return out;
 }
 
+/**
+ * User-message tool_result blocks → terminal tool_update events. The SDK runs
+ * each tool and feeds the output back in a `user` message; we mark the matching
+ * snapshot completed (or failed, on is_error) WITH its output so the snapshot
+ * persists/renders as resolved instead of spinning. Unknown ids (no prior
+ * snapshot) are still surfaced so a stray result isn't silently lost.
+ */
+function mapUserToolResults(content: UserContent, state: ClaudeSdkMapState): AgentEvent[] {
+  if (!Array.isArray(content)) return [];
+  const out: AgentEvent[] = [];
+  for (const raw of content) {
+    const block = raw as { type?: string; tool_use_id?: string; content?: unknown; is_error?: boolean };
+    if (block.type !== 'tool_result' || !block.tool_use_id) continue;
+    const prev = state.snapshots.get(block.tool_use_id);
+    const snap: AcpToolSnapshot = {
+      toolCallId: block.tool_use_id,
+      title: prev?.title ?? block.tool_use_id,
+      kind: prev?.kind ?? null,
+      status: block.is_error ? 'failed' : 'completed',
+      rawInput: prev?.rawInput,
+      rawOutput: toolResultText(block.content),
+    };
+    state.snapshots.set(block.tool_use_id, snap);
+    out.push({ type: 'tool_update', toolCall: snap });
+  }
+  return out;
+}
+
+/** tool_result content is a string OR an array of content blocks (text/image).
+ *  Flatten text blocks; fall back to the raw value so nothing is lost. */
+function toolResultText(content: unknown): unknown {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    const text = content
+      .map((c) =>
+        c && typeof c === 'object' && (c as { type?: string }).type === 'text'
+          ? String((c as { text?: unknown }).text ?? '')
+          : '',
+      )
+      .filter(Boolean)
+      .join('\n');
+    return text || content;
+  }
+  return content ?? '';
+}
+
 /** Parse a buffered JSON string; fall back to a prior value on empty/invalid. */
 function parseJsonOr(buf: string, fallback: unknown): unknown {
   const s = buf.trim();

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

@@ -165,6 +165,12 @@ export class ClaudeSdkBackend implements AgentBackend {
       // 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 } : {}),
@@ -192,6 +198,11 @@ export class ClaudeSdkBackend implements AgentBackend {
 
     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.
@@ -214,7 +225,32 @@ export class ClaudeSdkBackend implements AgentBackend {
     queue.push(userMsg);
 
     try {
-      for await (const msg of gen) {
+      // 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) {
@@ -234,19 +270,28 @@ export class ClaudeSdkBackend implements AgentBackend {
             await this.markIdle();
           }
           if (aborted) return { ok: false, error: 'aborted' };
-          return ok
+          if (!ok) return { ok: false, error: resultErrorMessage(msg) };
-            ? { ok: true }
+          // Context-window telemetry for the ContextBar (paseo's method):
-            : { ok: false, error: resultErrorMessage(msg) };
+          //   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);
         }
       }
-      // Generator ended without a result message (e.g. it was disposed) — treat as
-      // a non-fatal incomplete turn so the dispatcher still finalizes the row.
-      if (aborted) return { ok: false, error: 'aborted' };
-      return { ok: false, error: 'claude-sdk: query ended before result' };
     } catch (err) {
       if (aborted) return { ok: false, error: 'aborted' };
       await this.markCrashed();
@@ -351,6 +396,22 @@ function numF(v: unknown): number {
   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';

apps/coder/src/services/dispatcher.ts

@@ -20,6 +20,8 @@ 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;
@@ -66,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
@@ -196,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)
+        INSERT INTO messages (session_id, chat_id, role, content, status, model, created_at)
-        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', clock_timestamp())
+        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', ${task.model}, clock_timestamp())
         RETURNING id
       `;
       const assistantId = assistantMsg!.id;
@@ -298,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`
@@ -306,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 }[]>`
@@ -361,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)
+        INSERT INTO messages (session_id, chat_id, role, content, status, model, created_at)
-        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', clock_timestamp())
+        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', ${task.model}, clock_timestamp())
         RETURNING id
       `;
       const assistantId = assistantMsg!.id;
@@ -384,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);
@@ -514,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) {
@@ -558,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) {
@@ -570,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);
@@ -624,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
@@ -640,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;
@@ -692,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)
+        INSERT INTO messages (session_id, chat_id, role, content, status, model, created_at)
-        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', clock_timestamp())
+        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', ${task.model}, clock_timestamp())
         RETURNING id
       `;
       const assistantId = assistantMsg!.id;
@@ -714,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);
@@ -830,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) {
@@ -873,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);
@@ -882,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.
     }
@@ -960,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)
+        INSERT INTO messages (session_id, chat_id, role, content, status, model, created_at)
-        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', clock_timestamp())
+        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', ${task.model}, clock_timestamp())
         RETURNING id
       `;
       const assistantId = assistantMsg!.id;
@@ -982,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);
@@ -1081,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) {
@@ -1123,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);
@@ -1132,6 +1190,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.
+      emitAgentStatus(sessionId, chatId, agent, 'error', 'crashed');
       clearTaskCommands(taskId);
       // No worktree cleanup (persistent); backend stays warm for the next turn.
     }
@@ -1203,8 +1263,8 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
       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, created_at)
+        INSERT INTO messages (session_id, chat_id, role, content, status, model, created_at)
-        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', clock_timestamp())
+        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', ${task.model}, clock_timestamp())
         RETURNING id
       `;
       const assistantId = assistantMsg!.id;
@@ -1224,6 +1284,9 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         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);
@@ -1313,15 +1376,19 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
 
       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()
+        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) {
@@ -1364,6 +1431,14 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         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);
@@ -1373,6 +1448,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.
+      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/server/CLAUDE.md

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

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

@@ -111,6 +111,19 @@ describe('WsFrameSchema (v1.13.11-a)', () => {
     expect(result.success).toBe(true);
   });
 
+  it('accepts a message_complete frame with a null model (external coder, no model selected)', () => {
+    // Regression guard: the dispatcher publishes `model: task.model` (string |
+    // null). When null, this MUST validate or publishFrame fail-closes and drops
+    // the whole frame, incl. the status:'complete' transition.
+    const result = WsFrameSchema.safeParse({
+      type: 'message_complete',
+      message_id: VALID_UUID_A,
+      chat_id: VALID_UUID_B,
+      model: null,
+    });
+    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.

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

@@ -39,6 +39,12 @@ const ChatStatusValue = z.enum([
   'error',
 ]);
 
+// agent-status-normalize (#10): normalized per-(chat,agent) lifecycle status for
+// external coding agents (warm-acp / opencode / claude-sdk / pty). Distinct from
+// ChatStatusValue (native-inference chat lifecycle) — published by BooCoder's
+// dispatcher + permission flow on the per-session channel.
+const AgentStatusValue = z.enum(['working', 'blocked', 'idle', 'error']);
+
 const ErrorReasonValue = z.enum([
   'llm_provider_error',
   'doom_loop',
@@ -118,7 +124,11 @@ export const MessageCompleteFrame = z.object({
   ctx_max: z.number().int().positive().nullable().optional(),
   started_at: IsoTimestamp.nullable().optional(),
   finished_at: IsoTimestamp.nullable().optional(),
-  model: z.string().optional(),
+  // nullable: external-coder turns carry task.model, which is null when no
+  // model was selected. This frame is published through the same fail-closed
+  // publishFrame, so null MUST validate or the entire frame (incl. the
+  // status:'complete' transition) is dropped.
+  model: z.string().nullable().optional(),
   metadata: OpaqueObject.nullable().optional(),
 });
 
@@ -301,6 +311,21 @@ export const AgentCommandsFrame = z.object({
   commands: z.array(AgentCommandShape),
 });
 
+// agent-status-normalize (#10): published by BooCoder on the per-session channel
+// when an external agent's normalized status changes (turn start/end, permission
+// block/unblock). Keyed per (chat_id, agent); the frontend tracks the latest per
+// pair and resets on chat switch. `reason` is a free-form discriminator
+// (turn_start / turn_complete / failed / crashed / permission_request /
+// permission_resolved).
+export const AgentStatusUpdatedFrame = z.object({
+  type: z.literal('agent_status_updated'),
+  chat_id: Uuid,
+  agent: z.string().min(1),
+  status: AgentStatusValue,
+  reason: z.string().optional(),
+  at: IsoTimestamp,
+});
+
 // ---- discriminated union ---------------------------------------------------
 
 export const WsFrameSchema = z.discriminatedUnion('type', [
@@ -320,6 +345,7 @@ export const WsFrameSchema = z.discriminatedUnion('type', [
   PermissionRequestedFrame,
   PermissionResolvedFrame,
   AgentCommandsFrame,
+  AgentStatusUpdatedFrame,
   // per-user
   ChatStatusFrame,
   SessionUpdatedFrame,
@@ -361,6 +387,7 @@ export const KNOWN_FRAME_TYPES: readonly WsFrame['type'][] = [
   'permission_requested',
   'permission_resolved',
   'agent_commands',
+  'agent_status_updated',
   'chat_status',
   'session_updated',
   'session_renamed',

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/src/api/types.ts

@@ -201,6 +201,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;
@@ -351,7 +354,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 +580,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 +607,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

@@ -39,6 +39,12 @@ const ChatStatusValue = z.enum([
   'error',
 ]);
 
+// agent-status-normalize (#10): normalized per-(chat,agent) lifecycle status for
+// external coding agents (warm-acp / opencode / claude-sdk / pty). Distinct from
+// ChatStatusValue (native-inference chat lifecycle) — published by BooCoder's
+// dispatcher + permission flow on the per-session channel.
+const AgentStatusValue = z.enum(['working', 'blocked', 'idle', 'error']);
+
 const ErrorReasonValue = z.enum([
   'llm_provider_error',
   'doom_loop',
@@ -118,7 +124,11 @@ export const MessageCompleteFrame = z.object({
   ctx_max: z.number().int().positive().nullable().optional(),
   started_at: IsoTimestamp.nullable().optional(),
   finished_at: IsoTimestamp.nullable().optional(),
-  model: z.string().optional(),
+  // nullable: external-coder turns carry task.model, which is null when no
+  // model was selected. This frame is published through the same fail-closed
+  // publishFrame, so null MUST validate or the entire frame (incl. the
+  // status:'complete' transition) is dropped.
+  model: z.string().nullable().optional(),
   metadata: OpaqueObject.nullable().optional(),
 });
 
@@ -301,6 +311,21 @@ export const AgentCommandsFrame = z.object({
   commands: z.array(AgentCommandShape),
 });
 
+// agent-status-normalize (#10): published by BooCoder on the per-session channel
+// when an external agent's normalized status changes (turn start/end, permission
+// block/unblock). Keyed per (chat_id, agent); the frontend tracks the latest per
+// pair and resets on chat switch. `reason` is a free-form discriminator
+// (turn_start / turn_complete / failed / crashed / permission_request /
+// permission_resolved).
+export const AgentStatusUpdatedFrame = z.object({
+  type: z.literal('agent_status_updated'),
+  chat_id: Uuid,
+  agent: z.string().min(1),
+  status: AgentStatusValue,
+  reason: z.string().optional(),
+  at: IsoTimestamp,
+});
+
 // ---- discriminated union ---------------------------------------------------
 
 export const WsFrameSchema = z.discriminatedUnion('type', [
@@ -320,6 +345,7 @@ export const WsFrameSchema = z.discriminatedUnion('type', [
   PermissionRequestedFrame,
   PermissionResolvedFrame,
   AgentCommandsFrame,
+  AgentStatusUpdatedFrame,
   // per-user
   ChatStatusFrame,
   SessionUpdatedFrame,
@@ -361,6 +387,7 @@ export const KNOWN_FRAME_TYPES: readonly WsFrame['type'][] = [
   'permission_requested',
   'permission_resolved',
   'agent_commands',
+  'agent_status_updated',
   'chat_status',
   'session_updated',
   'session_renamed',

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
+  // #10: normalized status (working|blocked|idle|error) for the active external
-  // BooChat and any other AgentComposerBar caller renders no chip and is
+  // agent in this chat, or null for native boocode / before any frame. Renders
-  // otherwise unaffected. When present + connected + the chat has ≥1 prior
+  // a status dot DISTINCT from the WS-liveness `connected` dot. Undefined for
-  // turn, a chip right of the Provider picker reports whether switching to the
+  // non-coder callers — no dot.
-  // current provider resumes an agent session, replays history (boocode), or
+  agentStatus?: AgentStatusEntry | null;
-  // 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;
 }
 
-// Condensed token count: 950 → "950", 12_400 → "12.4K", 3_200_000 → "3.2M".
+// #10: normalized external-agent status dot. Mirrors StatusDot's visual
-// Sub-1000 stays exact; thousands/millions get one decimal, trailing .0 trimmed.
+// language but on the four normalized buckets (working|blocked|idle|error),
-function abbrevTokens(n: number): string {
+// and is DISTINCT from the WS-liveness `connected` dot beside it:
-  if (!Number.isFinite(n) || n < 1000) return String(Math.max(0, Math.round(n)));
+//   working — emerald spinning ring (subtle motion, like chat streaming)
-  if (n < 1_000_000) return `${(n / 1000).toFixed(1).replace(/\.0$/, '')}K`;
+//   blocked — amber dot (matches the permission/blocked state colour)
-  return `${(n / 1_000_000).toFixed(1).replace(/\.0$/, '')}M`;
+//   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"
+      />
+    );
   }
 
-// Relative-time formatter for the resumed-chip title (e.g. "3m ago").
+  const bg =
-function relativeTime(iso: string | null): string {
+    entry.status === 'blocked' ? 'bg-amber-500'
-  if (!iso) return 'unknown';
+      : entry.status === 'error' ? 'bg-destructive'
-  const then = new Date(iso).getTime();
+      : 'bg-muted-foreground/40';
-  if (Number.isNaN(then)) return 'unknown';
+
-  const diffMs = Date.now() - then;
+  return (
-  if (diffMs < 0) return 'just now';
+    <span
-  const sec = Math.floor(diffMs / 1000);
+      aria-label={`Agent status: ${entry.status}${entry.reason ? ` — ${entry.reason}` : ''}`}
-  if (sec < 60) return 'just now';
+      title={title}
-  const min = Math.floor(sec / 60);
+      className={cn('inline-block w-1.5 h-1.5 rounded-full shrink-0', bg)}
-  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
+      {/* Status dot + refresh — pinned right (ml-auto), never on its own line. */}
-          stays on the top line instead of wrapping past the edge-pinned dot. */}
       <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 && (
+          {/* BooCode 2.0: the web-search toggle moved out of this top toolbar
-            <DropdownMenu>
+              into the composer box's bottom controls row (the Web pill below),
-              <DropdownMenuTrigger asChild>
+              leaving the top row as just the agent picker + context bar. */}
-                <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>
-          )}
           {/* 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,7 +622,10 @@ export function ChatInput({ disabled, projectId, agentId, onAgentChange, session
           )}
         </div>
       )}
-      <div className="px-4 py-3 flex items-end gap-2">
+      {/* 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}
@@ -654,8 +639,61 @@ export function ChatInput({ disabled, projectId, agentId, onAgentChange, session
             }
             disabled={disabled || busy}
             rows={3}
-          className="resize-none min-h-[68px] max-h-[240px]"
+            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]"
+            >
+              <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.
@@ -663,7 +701,7 @@ export function ChatInput({ disabled, projectId, agentId, onAgentChange, session
                 return (
                   <Button
                     onClick={() => void onStop()}
-                size="icon-lg"
+                    size="icon"
                     variant="outline"
                     aria-label="Stop generating"
                     title="Stop generating"
@@ -679,7 +717,7 @@ export function ChatInput({ disabled, projectId, agentId, onAgentChange, session
                 <Button
                   onClick={() => void submit()}
                   disabled={disabled || busy || !hasContent}
-              size="icon-lg"
+                  size="icon"
                   variant={queueing ? 'secondary' : 'default'}
                   aria-label={queueing ? 'Queue message' : 'Send'}
                   title={queueing ? 'Queue message' : 'Send'}
@@ -690,6 +728,8 @@ export function ChatInput({ disabled, projectId, agentId, onAgentChange, session
             })()}
           </div>
         </div>
+      </div>
+      </div>
       <AttachmentPreviewModal
         attachment={previewAttachment}
         onClose={() => setPreviewAttachment(null)}
@@ -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">
+      <PaneHeaderActions
-        <DropdownMenu>
+        className="ml-auto px-1"
-          <DropdownMenuTrigger asChild>
+        onNewTab={onNewTab}
-            <button
+        tabKind={tabKind}
-              type="button"
+        onSplitPane={onSplitPane}
-              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]"
+        onReopenPane={onReopenPane}
-              aria-label="New chat, terminal, or coder"
+        onShowHistory={onShowHistory}
-              title="New chat / terminal / coder"
+        onRemovePane={onRemovePane}
-            >
+        historyActive={pane.kind === 'empty'}
-              <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>
     </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
+// Take the latest ctx_used and the latest ctx_max INDEPENDENTLY (newest-first).
-// AND ctx_max > 0 wins. Older messages may have ctx_used but missing ctx_max
+// They needn't be on the same message: ctx_max is the model's context window — a
-// (early v1 before llama-swap's n_ctx capture worked) — skip them and keep
+// constant per model — while some agents report it only intermittently (the claude
-// walking. Returns null when no usable pair exists in the chat.
+// 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 (used === null && m.ctx_used != null) used = m.ctx_used;
-    if (m.ctx_max <= 0) continue;
+    if (max === null && m.ctx_max != null && m.ctx_max > 0) max = m.ctx_max;
-    return { used: m.ctx_used, 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
+// (native inference, persisted from message_parts). Starts COLLAPSED to start
-// is still streaming so the user watches it think (Paseo-style), then stays
+// (a quiet chip) — for native BooChat/BooCode and the external agents (opencode,
-// where the user left it once the turn completes — initial state is captured
+// claude SDK) alike — so the transcript stays tidy; click to expand. The
-// once at mount, so we never fight a manual collapse on later re-renders.
+// `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">
+      <div className="px-2 py-1 border-b flex items-center justify-between gap-1">
-        <NavLink to="/" className="font-semibold tracking-tight text-base">
+        {/* BooCode brand banner: mascot badge + >_BooCode wordmark, big and
-          BooCode
+            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,14 +154,19 @@ export function SessionLandingPage({
                     Conversations
                   </h3>
                   <div className="space-y-0.5 mb-4">
-                    {openChats.map((c) => (
+                    {openChats.map((c) => {
-                      <button
+                      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="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]"
+                            className="flex items-center gap-2 flex-1 min-w-0 text-left"
                           >
-                        <MessageSquare size={14} className="shrink-0 text-muted-foreground" />
+                            <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">
@@ -148,7 +177,29 @@ export function SessionLandingPage({
                               {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,12 +210,15 @@ export function SessionLandingPage({
                   </h3>
                   <div className="space-y-0.5">
                     {archivedChats.map((c) => (
-                      <button
+                      <div
                         key={c.id}
+                        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]"
+                      >
+                        <button
                           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="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>
@@ -174,6 +228,16 @@ export function SessionLandingPage({
                             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">
+                <ChatTabBar
-                  <Code size={12} className="text-muted-foreground" />
+                  pane={pane}
-                  <span className="text-xs text-muted-foreground">BooCode</span>
+                  tabs={chatsForPane(pane)}
-                  <div className="ml-auto flex items-center gap-1">
+                  tabKind="coder"
-                    <DropdownMenu>
+                  tabNumbers={tabNumbers}
-                      <DropdownMenuTrigger asChild>
+                  onSwitchTab={(tabIdx) => switchTab(idx, tabIdx)}
-                        <button
+                  onRemoveTab={(chatId) => removeTab(idx, chatId)}
-                          type="button"
+                  onCloseOthers={(chatId) => closeOtherTabs(idx, chatId)}
-                          onClick={(e) => e.stopPropagation()}
+                  onCloseToRight={(chatId) => closeTabsToRight(idx, chatId)}
-                          className="inline-flex items-center justify-center size-5 rounded text-muted-foreground hover:bg-muted hover:text-foreground"
+                  onCloseAll={() => closeAllTabs(idx)}
-                          aria-label="New pane"
+                  onNewTab={() => void createCoderTab(idx)}
-                        >
+                  onSplitPane={(kind) => onAddPane(kind)}
-                          <Plus size={12} />
+                  onReopenPane={hasClosedPanes ? reopenPane : undefined}
-                        </button>
+                  onShowHistory={() => showLandingPage(idx)}
-                      </DropdownMenuTrigger>
+                  onRename={renameChat}
-                      <DropdownMenuContent align="end" className="w-fit">
+                  onRemovePane={panes.length > 1 ? () => removePane(idx) : undefined}
-                        <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>
               )}
               {isTerminal && (
                 <div className="flex items-center gap-2 border-b border-border bg-muted/30 px-2 py-1 shrink-0">
@@ -266,30 +243,7 @@ export function Workspace({
                   <span className="text-xs text-muted-foreground">
                     {terminalLabels.get(pane.id) ?? 'Terminal'}
                   </span>
-                  <DropdownMenu>
+                  <div className="ml-auto flex items-center gap-0.5">
-                    <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
@@ -301,26 +255,19 @@ export function Workspace({
                         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"
+                      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"
                     >
                       <Clipboard size={12} />
                     </button>
-                  {panes.length > 1 && (
+                    <PaneHeaderActions
-                    <button
+                      onSplitPane={onAddPane}
-                      type="button"
+                      onReopenPane={hasClosedPanes ? reopenPane : undefined}
-                      onClick={(e) => {
+                      onShowHistory={() => showLandingPage(idx)}
-                        e.stopPropagation();
+                      onRemovePane={panes.length > 1 ? () => removePane(idx) : undefined}
-                        removePane(idx);
+                    />
-                      }}
+                  </div>
-                      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"
-                    >
-                      <X size={12} />
-                    </button>
-                  )}
                 </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>({
+  const [agentConfig, setAgentConfig] = useState<AgentSessionConfig>(
-    provider: 'boocode',
+    () => readCachedAgentConfig(chatId) ?? DEFAULT_AGENT_CONFIG,
-    model: '',
+  );
-    modeId: null,
+  // Restore the per-chat cached config when the chat changes. The ref guard
-    thinkingOptionId: null,
+  // 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}
+        agentStatus={currentAgentStatus}
-        hasPriorTurn={hasPriorTurn}
       />
       {/* 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

@@ -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/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,
+  // chat ids that appear in CHAT- or CODER-kind panes in deterministic order
-  // then tab index). Assign numbers to any without one (global per session,
+  // (pane index, then tab index). Assign numbers to any without one (global per
-  // only ever increasing, never reused) and prune entries whose chat is no
+  // session, only ever increasing, never reused) and prune entries whose chat
-  // longer in any chat-kind pane. Guarded against render loops: only setState
+  // is no longer in any tab-hosting pane. Guarded against render loops: only
-  // when something actually changed.
+  // 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) return prev;
-      if (!pane || pane.kind === 'coder' || pane.kind === 'terminal') return prev;
       const next = [...prev];
+      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/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" />

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 |

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 the server's compiled `dist/` (`createInferenceRunner`, `createBroker`, `ALL_TOOLS`), so **`apps/server` must build first**: `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` in `apps/coder/src/services/provider-types.ts`, which must stay byte-identical to the web copy in `apps/web/src/api/types.ts` (see Testing).
+
+### 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` — text-identity parity between `provider-types.ts` and the web `api/types.ts` copy (compile-time cross-import is blocked by TS6307 on web's composite tsconfig)
+- `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,206 @@
+---
+paths:
+  - "apps/server/src/types/ws-frames.ts"
+  - "apps/web/src/api/ws-frames.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 a parity test goes red (`ws-frames.test.ts`, `provider-types-parity.test.ts`), a reviewer flags a "half-synced" type, or a frame/sentinel "does nothing" at runtime — i.e. one copy of a duplicated cross-app contract drifted from the other. 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:**
+  - Every hand-synced type/schema contract that crosses the `apps/server` ↔ `apps/web` ↔ `apps/coder` boundary in the files under `paths:`. The primary examples are the WS-frame Zod schema, the provider-snapshot types, and the sentinel `MessageMetadata` union plus its `MessageBubble` render arm — but the same rule governs the other duplicated pairs in these files (`WorktreeRiskReport`, the provider-config wire types, and the interface-typed `WsFrame` union that mirrors the Zod schema).
+
+## Introduction
+
+Several wire contracts in BooCode exist as **two or three hand-synced copies** in different apps, because the apps have separate `tsconfig`s with no shared path alias and a composite-project restriction (TS6307) that structurally blocks importing one app's types from another. There is no shared workspace package for these types yet. This standard governs what you must do when you touch one of those copies: **change every copy in the same commit** — and, where the contract has no compile-time consumer guarantee (the sentinel render arm), the consumer too.
+
+The three families in [Coding Standard](#coding-standard) are the primary examples, but the rule applies to **every** hand-synced pair in the files under `paths:`, each of which carries its own in-code `edit both copies` / `Mirror of …` / `KEEP IN SYNC` marker. Beyond the three: `WorktreeRiskReport` (`apps/server/src/types/api.ts` ↔ `apps/web/src/api/types.ts`), the provider-config wire types (`ProviderOverride` / `CoderProvidersFile`, web mirror of the coder's Zod-inferred shapes), and — note this one — a **second** representation of the WS wire shape: the interface-typed `WsFrame` union in `apps/web/src/api/types.ts` plus the `*Frame` interfaces in `apps/server/src/types/api.ts`, which is distinct from the byte-identical Zod `ws-frames.ts` pair and is **not** covered by the byte-parity test. A WS frame's shape therefore lives in more than one place; treat all of them as one contract.
+
+### 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:** two of the three contracts have runtime parity tests (`ws-frames.test.ts`, `provider-types-parity.test.ts`) that catch drift in the test run — but they are a backstop, not the mechanism, and the sentinel triple has no test at all.
+- **Side effect:** keeping the copies byte- or text-identical makes a contract 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: edit **every** copy, plus every consumer that switches on the shape, in the **same commit**. If no (a comment or formatting change that the contract's parity test normalizes away) → see "When NOT to Apply".
+
+**Exception — the sentinel/consumer triple:** `MessageMetadata` (`apps/server/src/types/api.ts` ↔ `apps/web/src/api/types.ts`) has **no parity test**, and a new `kind` is inert until it gets a render branch in `apps/web/src/components/MessageBubble.tsx`. When the shape you are editing is `MessageMetadata`, "every copy" includes that render arm — there is no test to remind you.
+
+**Verification step:** run the guards that exist *now*, before you commit:
+
+```bash
+# The trailing arg is a FILE-PATH substring filter for `vitest run` (not a test
+# name). A typo matches zero files and still exits 0 — a false green — so confirm
+# the run actually executed the file (look for "1 passed" on the named file).
+pnpm -C apps/server test ws-frames.test            # WS-frame byte-parity + KNOWN_FRAME_TYPES drift
+pnpm -C apps/coder  test provider-types-parity     # provider-snapshot text-parity (incl. nested blocks)
+# Sentinel triple has no test — grep all copies for a NEW rendering kind:
+grep -rn "<new-kind>" apps/server/src/types/api.ts apps/web/src/api/types.ts apps/web/src/components/MessageBubble.tsx
+```
+
+For a **rendering** sentinel kind (`cap_hit` / `doom_loop` / `mistake_recovery`) the new `kind` must appear in all three files. The non-rendering `error` arm of `MessageMetadata` lives in the two type copies only — it has no `MessageBubble` branch — so for it the grep should match the two `api.ts`/`types.ts` copies, not `MessageBubble.tsx`.
+
+## 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 *text-parity* file.** `provider-types-parity.test.ts` strips comments and blank lines before comparing, so a comment-only change to one provider-types copy is tolerated and you needn't chase the other. (This relief does **not** apply to `ws-frames.ts`, which is compared **byte-for-byte** — every character, including comments, must match.)
+- **The shared workspace package lands.** This standard exists *only* because the single source of truth was deferred (a Tier-2 follow-up noted in `provider-types-parity.test.ts`). Once these types move into one shared package, delete the hand-syncing rule rather than keep paying it — the SSOT supersedes this standard.
+
+## Background
+
+The duplication is deliberate, not accidental. A compile-time bidirectional-assignability check was attempted first — a web-side file importing the 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. The team chose hand-synced copies guarded by runtime tests over a premature shared package. The WS-frame copies go further and are kept **byte-identical** so a single `readFileSync` equality test can guard them; the provider-snapshot copies are kept **text-identical per named type block** (comments normalized away) because they sit among unrelated types. The cost of this choice is exactly what this standard manages: a copy can drift, and because each app compiles independently, only a runtime test — or a runtime bug — reveals it.
+
+## 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 — `apps/server/src/types/ws-frames.ts` ↔ `apps/web/src/api/ws-frames.ts` (byte-identical):**
+
+```typescript
+// PRIMARY: no compile-time link exists across apps (separate tsconfigs, TS6307
+// blocks cross-import). A frame type added to one copy but not the other breaks
+// silently at runtime — the frontend drops the frame at JSON-parse. So this file
+// and apps/web/src/api/ws-frames.ts MUST stay byte-identical, in the same commit.
+//
+//   IMPORTANT: This file is duplicated byte-identical at
+//   apps/web/src/api/ws-frames.ts. ... If you change one, change the other.
+//
+// Adding a frame also means adding its `type` to KNOWN_FRAME_TYPES (a drift test
+// probes every entry for a discriminated branch).
+```
+
+**Provider snapshot types — `apps/coder/src/services/provider-types.ts` ↔ `apps/web/src/api/types.ts`, text-identical per block.** By convention you author on the coder side and mirror to web (the in-code `KEEP IN SYNC` markers point that way), but the parity test is **symmetric** — it fails on drift in *either* file and names no authoritative copy, so "fix the red test" means re-sync the two, not edit one in particular:
+
+```typescript
+// PRIMARY: nothing links these two copies at compile time — a field added here
+// but not in apps/web/src/api/types.ts breaks silently at runtime (the web side
+// drops or mis-reads the snapshot). The in-file marker, with its test backstop:
+//   KEEP IN SYNC with apps/web/src/api/types.ts ProviderSnapshotEntry — parity
+//   is enforced by __tests__/provider-types-parity.test.ts (fails on field drift).
+// Applies to the nested ProviderModel / ProviderMode / ThinkingOption /
+// AgentCommand / ProviderSnapshotStatus blocks the entry references, too.
+export interface ProviderSnapshotEntry { /* ...fields... */ }
+```
+
+**Sentinel metadata — `apps/server/src/types/api.ts` ↔ `apps/web/src/api/types.ts`, plus the render arm in `apps/web/src/components/MessageBubble.tsx` (no parity test):**
+
+```typescript
+// A new *rendering* sentinel kind is a THREE-file change with NO test to catch a miss:
+//   1. apps/server/src/types/api.ts  — add the arm to MessageMetadata
+//   2. apps/web/src/api/types.ts     — add the identical arm
+//   3. 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 one copy only.
+// Add a new frame type to apps/web/src/api/ws-frames.ts but not the server copy
+// (or vice versa): tsc stays green — they're separate projects — but the parity
+// test fails, and had it not existed, the server would publish a frame the
+// frontend silently discards at JSON-parse. A half-edited contract is invisible
+// to the type-checker; never land one.
+```
+
+**Project references:**
+- `apps/server/src/types/ws-frames.ts` — the byte-identical sync comment (top of file) and `KNOWN_FRAME_TYPES`.
+- `apps/web/src/api/ws-frames.ts` — the web copy that must match it byte-for-byte.
+- `apps/coder/src/services/provider-types.ts` — the `KEEP IN SYNC` comment above `ProviderSnapshotEntry`.
+- `apps/web/src/api/types.ts` — the provider-snapshot wire copy and the `MessageMetadata` copy.
+- `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 the byte-parity test but has no reducer `case` validates and is then silently ignored.
+
+**Correct usage:**
+
+```typescript
+// Adding a WS frame type, all in one commit:
+//   - apps/server/src/services/inference/turn.ts  — loose InferenceFrame publish union (+ optional fields)
+//   - apps/server/src/types/ws-frames.ts          — strict WsFrameSchema + WsFrame + KNOWN_FRAME_TYPES
+//   - apps/web/src/api/ws-frames.ts               — byte-identical copy of the strict gate
+// The strict web-side type 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.
+```
+
+**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:**
+- `apps/server/src/services/inference/turn.ts` — the loose `InferenceFrame` publish union.
+- `apps/server/src/types/ws-frames.ts` — `WsFrameSchema` (the broker's fail-closed validation gate) + `KNOWN_FRAME_TYPES`.
+- `apps/web/src/components/MessageBubble.tsx` — the consumer for sentinel `MessageMetadata` kinds.
+
+### Sync the copies; never weaken the parity test
+
+When a parity test fails, the fix is to make the copies match — not to make the test stop checking. The corollary also holds: when you add a **new** nested type that `ProviderSnapshotEntry` references, add its name to the `names` array in `provider-types-parity.test.ts`, or the new type is hand-synced but **unguarded**.
+
+**What to avoid:**
+
+```typescript
+// ANTI-PATTERN: a red parity test "fixed" by deleting the assertion, skipping
+// the it(), or trimming a type out of the compared `names` list. That converts a
+// caught drift into a shipped, silent contract break. Re-sync the copies instead.
+```
+
+**Project references:**
+- `apps/server/src/services/__tests__/ws-frames.test.ts` — `ws-frames.ts file mirror parity` (byte-identical) and the `KNOWN_FRAME_TYPES` drift probe.
+- `apps/coder/src/services/__tests__/provider-types-parity.test.ts` — text-identity of each shared block across the coder ↔ web copies.
+
+## 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, sentinels, provider-type parity, JSONB) this standard formalizes.
+- `apps/server/CLAUDE.md` (`services/broker.ts`) and `apps/coder/CLAUDE.md` — per-app notes on the broker validation and the provider-type mirror.
+
+### 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/project-discovery.md

@@ -0,0 +1,132 @@
+# Project Discovery
+
+> Auto-generated stack / tooling / command inventory for the BooCode repository. Static reference for skills, agents, and contributors. Deep engineering notes live in the root and per-app `CLAUDE.md` files; this file is the factual "what's installed and how to run it" map.
+
+## Repository
+
+- type: pnpm monorepo (workspaces `apps/*` + `apps/coder/web`)
+- package manager: pnpm 10.15.1 (root `package.json` `packageManager`)
+- lock file: `pnpm-lock.yaml`
+- workspace config: `pnpm-workspace.yaml`
+- shared TS config: `tsconfig.base.json` (ES2022 target, strict, `noUncheckedIndexedAccess`, `isolatedModules`)
+- languages: TypeScript (all Node packages), Go 1.24 (codecontext sidecar)
+- database: PostgreSQL 16 (single `boochat` DB; two schema files applied idempotently — `apps/server/src/schema.sql` + `apps/coder/src/schema.sql`)
+- members: 5 Node packages (`@boocode/server`, `@boocode/web`, `@boocode/coder`, `@boocode/coder-web`, `@boocode/booterm`) + 1 Go sidecar (`codecontext/`)
+- cross-workspace dep: `@boocode/coder` → `@boocode/server` (`workspace:*`); **server must build first** (emits `.d.ts` for consumers)
+- build order: server → coder → web/booterm (independent) → codecontext (Docker, Go)
+
+## Repository-level
+
+### Documentation
+
+- primary guidance: `CLAUDE.md` (root, tracked) + per-app `apps/server/CLAUDE.md`, `apps/coder/CLAUDE.md`, `apps/web/CLAUDE.md` (lazy-loaded per subtree)
+- overview: `README.md`
+- release log: `CHANGELOG.md` (per-tag, newest-first)
+- system prompts: `BOOCHAT.md`, `BOOCODER.md` (bind-mounted into containers)
+- architecture: `docs/ARCHITECTURE.md` (system diagram + overview)
+- planning docs: `docs/codecontext-ts-plan.md`, `docs/DEFERRED-WORK.md`, `docs/STALE-DEPRECATED.md`, `docs/themes_v1.md`, `docs/superpowers/plans/`
+- specs/design: `openspec/README.md` (convention) + `openspec/changes/<slug>/{proposal,tasks,design}.md`; shipped batches snapshot under `openspec/changes/archived/`
+
+### Agent registry & skills
+
+- agent registry: `data/AGENTS.md` (tracked; parsed — each `## <Name>` + `---` frontmatter fence is one agent)
+- skills: `data/skills/<vendor>/` (each skill = `SKILL.md` + optional `eval.yaml`); vendors include `boocode/` (`committing-changes`, `improving-boocode-guidance`, `systematic-debugging`, `using-worktrees`), `anthropics/`, `superpowers/`, `mattpocock/`, others
+
+### Infrastructure
+
+- container build: `Dockerfile` (root — boocode = server + web; `node:20-alpine` builder + runtime; runtime adds ripgrep/git/ssh)
+- container build: `apps/booterm/Dockerfile` (`node:20-alpine` builder → `node:20-bookworm-slim` runtime for node-pty libc parity)
+- container build: `codecontext/Dockerfile` (`golang:1.24-alpine` → `alpine:3.20`)
+- container build: `apps/coder/Dockerfile` (present but unused — BooCoder now runs via host systemd, not Docker)
+- orchestration: `docker-compose.yml` — services `boocode` (:9500), `booterm` (:9501), `boocode_db` (postgres:16-alpine, host :5500), `codecontext` (internal :8080); `boocoder` service commented out (moved to host systemd `boocoder.service`, :9502)
+- CI/CD: none in repo (`.github/workflows`, `.gitea`, `.gitlab-ci.yml` absent); deploy is manual (`docker compose up --build -d`; boocoder via `pnpm build` + `sudo systemctl restart boocoder`)
+- git hooks: none committed (`.git/hooks/` has only `.sample`); a host-side `security_reminder_hook.py` is referenced but not in-repo
+- ADRs: no dedicated directory; decisions live inline in `CLAUDE.md` files, `docs/ARCHITECTURE.md`, and `openspec/changes/*/design.md`
+- linters/formatters: none configured (no eslint/prettier/stylelint config)
+
+### Environment & configuration
+
+- env file: `.env` (gitignored) / `.env.example` (tracked template)
+- boocoder host env: `apps/coder/.env.host`
+- config template: `data/mcp.example.json` (tracked) — live `data/mcp.json` is gitignored; secrets live in `.env` and resolve via `{env:VAR}` substitution (e.g. `CONTEXT7_API_KEY`)
+- config template: `data/coder-providers.example.json` (tracked) — live `data/coder-providers.json` is gitignored (runtime, read+written on UI toggles)
+
+## Projects
+
+### `boocode` (root coordinator) — `/`
+
+- manifest: `package.json`
+- role: pnpm workspace root; coordinates dev/build across members
+- install: `pnpm install`
+- dev: `pnpm dev:server` (tsx watch, :3000), `pnpm dev:web` (Vite, :5173)
+- build: `pnpm build` (web then server)
+- start: `pnpm start` (`node apps/server/dist/index.js`)
+- typecheck: `npx tsc --noEmit` (project references; per-app `tsc` is authoritative)
+
+### `@boocode/server` — `apps/server/`
+
+- manifest: `apps/server/package.json`
+- runtime: Node.js + TypeScript
+- frameworks: Fastify ^4.28.1 (+ `@fastify/websocket` ^10, `@fastify/static` ^7); postgres ^3.4.4 (porsager, tagged-template SQL, no ORM); Vercel AI SDK — `ai` ^6 + `@ai-sdk/openai-compatible` ^2 (llama-swap); Zod ^3; `@modelcontextprotocol/sdk` ^1.29
+- build: `pnpm -C apps/server build` (`tsc` + copy `schema.sql` → `dist/`) — authoritative for server code
+- dev: `pnpm -C apps/server dev` (tsx watch)
+- typecheck: `pnpm -C apps/server typecheck`
+- test: `pnpm -C apps/server test` (vitest run)
+- tsconfig: `apps/server/tsconfig.json` (NodeNext, `declaration: true` for workspace consumers; `exports` map with `types` conditions)
+- test config: `apps/server/vitest.config.ts` (vitest ^3.2.4, env=node, `globals: false`, `fileParallelism: false`)
+- test pattern: `src/**/__tests__/**/*.test.ts`
+- DB-integration tests: opt-in via `DATABASE_URL='postgres://boocode:devpass@localhost:5500/boochat' pnpm -C apps/server test`
+
+### `@boocode/web` — `apps/web/`
+
+- manifest: `apps/web/package.json`
+- runtime: Node.js + TypeScript (browser SPA; also hosts the BooCoder pane)
+- frameworks: React ^18.3.1 + React DOM; React Router v6.26.0; Tailwind v4.3.0 (+ `@tailwindcss/postcss`); shadcn/radix-ui primitives; Shiki ^1.29 (highlighting); `@xterm/xterm` 5.5 (+ addons fit/web-links/webgl); Vite ^5.3.4 (+ `@vitejs/plugin-react`)
+- build: `pnpm -C apps/web build` (`tsc -b` + `vite build`)
+- dev: `pnpm -C apps/web dev` (Vite, :5173)
+- preview: `pnpm -C apps/web preview`
+- typecheck: `pnpm -C apps/web typecheck` (`tsc -b --noEmit`) — or `npx tsc -p apps/web/tsconfig.app.json --noEmit`
+- tests: none (no test harness by design)
+- tsconfig: `apps/web/tsconfig.json` (composite refs) + `apps/web/tsconfig.app.json` (Bundler resolution, `react-jsx`, path alias `@/` → `src/*`)
+- dev config: `apps/web/vite.config.ts` (proxy order: `/api/term` + `/ws/term` → :9501, `/api/coder` → :9502, `/api` → :3000)
+
+### `@boocode/coder` — `apps/coder/`
+
+- manifest: `apps/coder/package.json`
+- runtime: Node.js + TypeScript; runs as host systemd service (`boocoder.service`, :9502), postgres at `127.0.0.1:5500`
+- frameworks: Fastify ^4.28.1 (+ `@fastify/websocket`); postgres ^3.4.4; agent SDKs — `@agentclientprotocol/sdk` ^0.22, `@anthropic-ai/claude-agent-sdk` ^0.3, `@opencode-ai/sdk` ~1.15 (imported via `@opencode-ai/sdk/v2/client`); `@modelcontextprotocol/sdk` ^1.29; `@boocode/server` (`workspace:*`)
+- build: `pnpm -C apps/coder build` (`tsc` + copy `schema.sql`) — requires server built first
+- dev: `pnpm -C apps/coder dev` (tsx watch)
+- cli: `pnpm -C apps/coder cli` (`tsx src/cli.ts`)
+- typecheck: `pnpm -C apps/coder typecheck`
+- test: `pnpm -C apps/coder test` (vitest run)
+- deploy: `pnpm -C apps/server build && pnpm -C apps/coder build && sudo systemctl restart boocoder`
+- tsconfig: `apps/coder/tsconfig.json` (NodeNext, `declaration: false`)
+- test config: `apps/coder/vitest.config.ts` (vitest ^3.0.0, env=node, `globals: false`, `fileParallelism: false`)
+- test pattern: `src/**/__tests__/**/*.test.ts`
+
+### `@boocode/coder-web` — `apps/coder/web/`
+
+- manifest: `apps/coder/web/package.json`
+- runtime: Node.js + TypeScript; standalone fallback SPA served at :9502 (primary coder UI is the pane in `@boocode/web`)
+- frameworks: React ^18.3.1 + React Router v6.26.0 + Tailwind v4.3.0 + Vite ^5.3.4
+- dev config: `apps/coder/web/vite.config.ts` (port 5174; proxies `/api` → `http://127.0.0.1:3000`)
+
+### `@boocode/booterm` — `apps/booterm/`
+
+- manifest: `apps/booterm/package.json`
+- runtime: Node.js + TypeScript; Docker container (:9501, bookworm-slim+glibc)
+- frameworks: Fastify ^4.28.1 (+ `@fastify/websocket`); node-pty ^1.0.0; `pg` ^8.13 (session persistence); tmux (per-session `bc-<sid>`)
+- build: `pnpm -C apps/booterm build` (`tsc` only)
+- dev: `pnpm -C apps/booterm dev` (tsx watch)
+- typecheck: `pnpm -C apps/booterm typecheck`
+- tests: none
+- tsconfig: `apps/booterm/tsconfig.json` (NodeNext, `declaration: false`)
+
+### codecontext shim — `codecontext/`
+
+- manifest: `codecontext/go.mod`
+- runtime: Go 1.24; standalone binary, MCP stdio↔HTTP adapter (NDJSON framing); Docker sidecar at `http://codecontext:8080/v1/<tool_name>`
+- source: single `shim.go`; wraps the CodeContext fork staged via `codecontext/fork.tar.gz` (gitignored; fork repo at `/opt/forks/codecontext/`, branch `boocode-ts`)
+- build: `go build ./...` (use `/snap/go/current/bin/go`); built into the container in Docker
+- test: `go test ./...`

openspec/changes/agent-status-normalize/proposal.md

@@ -0,0 +1,61 @@
+# Normalized external-agent status (#10, scoped)
+
+**Status:** in progress (started 2026-06-01)
+**Source:** `boocode_code_review_v2.md` §1 #10, §5j (superset, Elastic License 2.0 — PATTERN-ONLY,
+clean-room; `/opt/forks/superset/.../map-event-type.ts`, `notify-hook.template.sh`, `agent-setup/*`).
+**Decision (Sam, 2026-06-01):** scoped status-publish now; config-injection notify-hook as a follow-on.
+
+## Why (corrected premise)
+BooCoder already *observes* agent lifecycle (warm-acp/opencode/SDK backends know active/idle/crashed;
+the permission-waiter knows blocked) but never **publishes a normalized per-`(chat,agent)` status** to the
+UI — so blocked-on-permission is invisible and crash/idle aren't pushed proactively. The `AgentComposerBar`
+dot only shows WS liveness. This batch publishes the status BooCoder already knows; the heavier
+config-injection notify-hook (for out-of-band signals) is the documented follow-on.
+
+## State model (clean-room from superset's `mapEventType`)
+Superset collapses ~30 vendor event names → 3 signals: **Start** (working), **PermissionRequest**
+(blocked), **Stop** (done). BooCoder adds idle (after done) + error (crash/fail). Normalized status:
+`working | blocked | idle | error`.
+
+## Pinned frame contract (server + web, byte-identical, parity-tested)
+```ts
+{ type: 'agent_status_updated', chat_id: Uuid, agent: string,
+  status: 'working' | 'blocked' | 'idle' | 'error', reason?: string, at: IsoTimestamp }
+```
+Added to `apps/server/src/types/ws-frames.ts` AND `apps/web/src/api/ws-frames.ts` (the `ws-frames` parity
+test), plus the web `WsFrame` union in `apps/web/src/api/types.ts`. Published via the coder's
+`broker.publishFrame` (validated against the server `WsFrameSchema`).
+
+## Clean-room normalize helper (built now, reused by the injection follow-on)
+`apps/coder/src/services/normalize-agent-status.ts`:
+`normalizeAgentEvent(raw: string): 'working' | 'blocked' | 'done' | null` — a clean-room reimplementation
+of the vendor-event-name → bucket mapping (the event names are facts about each agent's hooks:
+`SessionStart`/`UserPromptSubmit`/`PostToolUse`→working; `PreToolUse`/`Notification`/`PermissionRequest`/
+`exec_approval_request`→blocked; `Stop`/`session_end`/`task_complete`→done). The scoped publish points use
+BooCoder's own already-normalized turn boundaries; this helper exists so the config-injection follow-on
+(which receives raw vendor event names POSTed from agent hooks) reuses it. Unit-tested.
+
+## Publish points (BooCoder's existing observation — no per-backend change)
+- Dispatcher (`dispatcher.ts`) turn boundaries, for every external-agent path (warm-acp/opencode/sdk/pty):
+  `working` at turn start, `idle` on clean completion, `error` on failure.
+- Permission-waiter (`permission-waiter.ts` / the `setPermissionHooks` publish in `index.ts`): `blocked`
+  when a permission is requested, back to `working` when resolved.
+A small `publishAgentStatus(broker, chatId, agent, status, reason?)` helper centralizes the frame.
+
+## Frontend
+- `CoderPane.tsx` tracks the latest `agent_status_updated` per `(chat, agent)` (a small live map; reset on
+  chat switch).
+- `AgentComposerBar.tsx` renders a normalized status dot beside the existing session chip (reuse the
+  `StatusDot` visual language: working=spinner/green, blocked=amber, idle=gray, error=red), distinct from
+  the WS-liveness `connected` dot.
+
+## Follow-on (documented, not built): config-injection notify-hook
+Clean-room re-derive superset's `agent-setup`: inject a notify hook into each agent's native config
+(claude `~/.claude/settings.json`, opencode plugin, codex/gemini templates) that POSTs
+`{agent, chat_id, eventType}` to a new `POST /api/coder/agent-status` endpoint, which runs
+`normalizeAgentEvent` → publishes the SAME `agent_status_updated` frame. Reuses everything this batch
+builds. Catches out-of-band signals BooCoder's dispatch can't see.
+
+## Verify
+- `pnpm -C apps/coder test` (+ normalize-agent-status tests) + `pnpm -C apps/server test` (ws-frames parity)
+- `pnpm -C apps/server build && pnpm -C apps/coder build`; `npx tsc -p apps/web/tsconfig.app.json --noEmit`