feat: MCP {env:VAR} key substitution + coder model/tool-result fixes + docs refactor (v2.7.9)

- MCP secrets: substituteEnvVars recursively resolves {env:NAME} in mcp.json string values from process.env before Zod (opencode-compatible); unset -> '' + boot warning, and invalid-config log names the unset vars (an empty {env:VAR} in a strict url/command field invalidates the whole config)
- data/mcp.json now untracked (.gitignore flips !data/mcp.json -> !data/mcp.example.json); tracked template data/mcp.example.json carries "{env:CONTEXT7_API_KEY}"; .env.example documents the key (9 mcp-config tests)
- Coder fix: message_complete frame model widened string -> string|null (server+web ws-frames parity); dispatcher publishes model: task.model at all 4 external completion points — a null model otherwise fail-closed in publishFrame and dropped the whole frame incl. status:'complete' (regression test)
- Coder fix: claude-sdk mapUserToolResults maps user-message tool_result blocks -> terminal tool_update events (completed/failed w/ output) so tool snapshots resolve instead of spinning forever
- Composer: AgentComposerBar drops §9b resumed/history/new chip + token readout, loses flex-wrap so the row stays one line; CoderPane gains a per-chat localStorage agent-config cache (restores last model on reopen) + threads model into the timeline/chip
- Docs: root CLAUDE.md slimmed (~190 lines), per-app refs split to apps/{coder,server,web}/CLAUDE.md; new docs/coder-backends.md, docs/project-discovery.md, docs/coding-standards/ (cross-app-contract-parity); ARCHITECTURE.md links the backends doc

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**: server read SELECT + `mapCoderMessageRow` (`apps/coder/src/routes/messages.ts`), `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 is how the `model` chip silently vanished in the coder).

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

@@ -536,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) {
@@ -864,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) {
@@ -1128,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) {
@@ -1385,6 +1388,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) {