docs(changelog): v2.6.10-lifecycle-hardening (completes v2.6)

CHANGELOG + roadmap (through v2.6.10; v2.6 marked complete) + openspec v2-6 Phase 3 checked off (3.1-3.6; 3.7 frontend + apps/server caller as follow-ups).

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

CHANGELOG.md

@@ -2,6 +2,26 @@
 
 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.6.10-lifecycle-hardening — 2026-06-01
+
+v2.6 Phase 3 (the last phase) — lifecycle hardening of the warm-process backends. **Idle eviction + LRU cap:** the agent pool runs a 60s sweep that evicts backends/sessions idle past `AGENT_POOL_IDLE_TTL_MS` (30 min default) and any beyond `AGENT_POOL_MAX_LIVE` (10, LRU) — **never a busy one** (in-flight turn, double-checked via a new `isBusy()` backend hook); the worktree persists (DB-backed) and the next turn re-spawns + reattaches. The eviction/LRU/restart decisions are factored into a pure `lifecycle-decisions.ts` (modeled on the inference `selectPruneTargets` pattern). **Crash recovery:** lifts openchamber's health-monitor + busy-aware-restart + consecutive-failure + stale-busy-grace state machine into `opencode-server.ts` (with port reclaim) and `warm-acp.ts` — an opencode server crash settles in-flight turns as failed, marks the rows `crashed`, and recreates fresh sessions (a fresh server can't hold the old in-memory id), while a warm-ACP child crash re-`session/new`s next turn; the F.1 turn-guard and U.6 usage are preserved (their tests still pass). **Worktree reaper:** a periodic reaper removes orphan on-disk worktrees (no live `worktrees` row, 1h grace) behind a superset-style preflight that skips dirty/unpushed/unmerged work, with Paseo-style soft-delete (`status='archived'`). Plus close hooks (`/api/chats/:id/close`, `/api/sessions/:id/close`, awaiting the apps/server caller) and diff re-baseline after `apply_pending`. Built test-first — 35 new tests (`lifecycle-decisions` 22, `agent-pool` 13) + a DB-opt-in reconnect integration test; 215 coder tests pass, tsc + build clean. **This completes v2.6** (Phase 0–3 + F.1 + Phase 1-UX). Remaining follow-ups (out of v2.6 scope): the apps/server close-hook caller, the 3.7 DiffPanel staging-boundary hint (frontend), and live Smoke 2/2b/3.
+
+## v2.6.9-warm-acp — 2026-05-31
+
+v2.6 Phase 2: goose and qwen now run as **warm ACP backends** instead of one-shot-per-task. A new `WarmAcpBackend` (`backends/warm-acp.ts`, implementing the same `AgentBackend` interface as the opencode warm server) holds one persistent `goose acp` / `qwen --acp` child + `ClientSideConnection` + ACP session per `(chat, agent)`, running `initialize` + `session/new` once and reusing the connection across turns; per-turn abort cancels the in-flight prompt (`session/cancel`) without killing the child, and a child exit marks `agent_sessions.status='crashed'` for re-spawn on the next turn. The dispatcher routes `goose`/`qwen` chat-tab tasks to the pooled warm backend via a pure `shouldUseWarmBackend(task)` predicate (warm only when both `session_id` and `chat_id` are set), keeping the one-shot `runExternalAgent` path as the fallback for session-less creators (arena, MCP, `new_task`); broker frames + `persistExternalAgentTurn` + the latest-wins `pending_changes` diff are identical to the opencode path. The `acp-dispatch.ts` `handleSessionUpdate` switch was extracted into a pure shared `acp-event-map.ts` mapper used by both the one-shot and warm paths (one-shot behavior byte-identical, all existing acp tests green). The design's `unstable_resumeSession` concern is resolved — the installed `@agentclientprotocol/sdk@^0.22.1` exposes stable `resumeSession`/`loadSession`, but resume is moot in the hot path (warm reuse needs none); cross-restart resume + idle eviction are deferred to Phase 3. Built test-first (15 new tests: `warm-acp-routing`, `acp-event-map`); 180 coder tests pass, tsc + build clean. **Smoke 2/2b (live two-message warm reuse + the opencode→boocode→opencode switch round-trip) to be run post-deploy.** Phase 3 (lifecycle hardening) is the last v2.6 phase.
+
+## v2.6.8-agent-attribution — 2026-05-31
+
+v2.6 Phase 1-UX: agent attribution + switch affordances over the already-shipped `pending_changes.agent` column and `agent_sessions` table (read+display, no new backend capability). **Backend:** `pending_changes.agent` is now stamped at every queue site (native write tools → `'boocode'`, dispatched external agents → the task's agent, manual RightRail create → `NULL`) and flows through `listPending`; a new `GET /api/sessions/:id/agent-sessions` route returns `[{agent,status,has_session,last_active_at}]` per `(chat,agent)` for the session's chats; and the opencode warm-server backend consumes opencode's `session.next.step.ended` events, accumulating `input_tokens`/`output_tokens`/`cost` onto the `agent_sessions` row (new columns, idempotent). **Frontend:** the BooCoder DiffPanel renders a per-row agent badge (provider icon + label; `null` → "manual") with a "Changes from X, Y" note when a pending set spans multiple agents, and the AgentComposerBar shows a resumed / history / new-session chip beside the Provider picker — gated on an optional `sessionId` prop so BooChat is unaffected — driven by a new `useAgentSessions` hook that refetches on message-complete; `providerIcon` was extracted to a shared `components/coder/providerIcons.tsx`. Built by three parallel subagents over disjoint file sets; web + coder typecheck clean, 165 coder tests pass (9 new across `opencode-usage` and `agent-sessions.routes`). U.6's persisted token totals are conversation-cumulative and not yet surfaced in the UI (deferred). Implements the U.1–U.6 "remaining" plan from the v2.6 openspec reconciliation; Phase 2 (warm ACP goose/qwen) + Phase 3 (lifecycle hardening) remain.
+
+## v2.6.7-interrupt-guard — 2026-05-31
+
+Fixes a post-interrupt correctness bug in the `v2.6.1-phase1-opencode` warm-server backend, made one-click reachable by `v2.6.5-panes-tabs-composer`'s Send→Stop composer. `opencode-server.ts` settled an in-flight turn on opencode's `session.idle`/`session.error` by calling `activeTurn.settle()` on whatever turn currently held the session slot — but opencode emits one trailing terminal event for a *cancelled* turn after `client.session.abort()`, and those events carry only a `sessionID` (no turn id). So after the user hit Stop and immediately sent another message, the aborted turn's orphan `session.idle` settled the *new* turn early as success (Paseo hit and fixed the same class in `1d38aac`). The fix adds a small pure guard (`turn-guard.ts`: `armAbortGuard`/`noteTurnActivity`/`consumeTerminal` over a per-session `swallowNextTerminal` flag): abort arms it, the next terminal is swallowed once, and a new turn's first delta self-heals the flag so a never-arriving orphan can't strand a real turn. Implemented test-first — three regression tests in `turn-guard.test.ts` (swallow-the-orphan, settle-when-no-abort, self-heal); full coder suite green (156 passed). This is the F.1 "fix-next" item from the v2.6 openspec reconciliation; Phase 1-UX / Phase 2 / Phase 3 remain.
+
+## v2.6.6-claude-md — 2026-05-31
+
+Docs-only — CLAUDE.md session-learnings update, no code. Captures four recurring gotchas surfaced while shipping `v2.6.5-panes-tabs-composer`: (1) `sessions.workspace_panes` is now a `WorkspaceState` envelope (`panes` + `tabNumbers`/`nextTabNumber` + `closedPaneStack`), migrated from the legacy bare `WorkspacePane[]` on both frontend hydrate (`toWorkspaceState`) and the union-accepting server PATCH validator; (2) DB/session-aware tools take an optional `ToolExecCtx` (`{ sql, sessionId }`) 4th arg on `ToolDef.execute`, plumbed through the tool phase, with `read_tab_by_number` as the reference; (3) the two-schema-files-one-DB ownership split — `apps/coder/src/schema.sql` owns `agent_sessions`/`worktrees`/`pending_changes`/`available_agents` and extends `tasks`, distinct from BooChat's `apps/server/src/schema.sql` — plus the idempotent `confdeltype` FK-action-flip pattern (guard `ON DELETE` changes on `pg_constraint.confdeltype` so re-runs no-op); and (4) React StrictMode is on, so a `setState` called inside another `setState`'s updater double-fires in dev and must be made idempotent. Pairs with `v2.6.5-panes-tabs-composer`.
+
 ## v2.6.5-panes-tabs-composer — 2026-05-31
 
 A workspace UX batch across BooChat panes, tabs, and the composer, plus the persistence model that backs them. **Panes & tabs:** a chat can be opened in a fresh pane (the ChatTabBar tab context menu's "Open in new pane", and the fork button — which now lands the fork beside the original via a new `open_chat_in_new_pane` event instead of replacing the active pane); the per-pane "+" became a New BooChat/BooTerm/BooCode menu; closing a chat pane relocates its tabs (in order) into the oldest chat/empty pane instead of discarding them, and reopen strips the restored chatIds from every live pane first so a relocated-then-reopened pane never duplicates a tab (no stack-shape change); each tab carries a stable session-scoped number assigned on open and retired on close (never reused), rendered map-keyed rather than positional. The per-message "Open in pane" artifact button was removed, and the empty/landing pane became a real session history — the session's open chats plus separately-fetched archived chats, click to open or restore-and-open. **Persistence:** `sessions.workspace_panes` was widened from a bare `WorkspacePane[]` to a `WorkspaceState` envelope (`panes` + `tabNumbers`/`nextTabNumber` + `closedPaneStack`) so tab numbers and the reopen stack survive reload; the PATCH validator accepts the legacy array or the envelope (zod union) and migrates on write, and the `session_workspace_updated` WS-frame schema was widened on both web and server (byte-identical, parity test green) — the same schema-drift class as `v2.6.4-agent-sessions-fk`. **Composer:** the send button morphs Send → Stop → Queue with generation state (BooCoder keys on `sending || activeTaskId`, which also corrected its queue gates and added `cancelTask`), the standalone "Stop generating" pill was folded into it, and pasted chips now trail the typed text so a leading slash command stays first. **Tooling:** adds the read-only `read_tab_by_number` tool — resolves a session-scoped tab number to its chat via the persisted `tabNumbers` map and returns that chat's transcript; tools gained an optional `ToolExecCtx` (`{ sql, sessionId }`) on `execute` to support DB-reading tools. Builds on `v2.6.4-agent-sessions-fk`.

CLAUDE.md

@@ -126,11 +126,11 @@ Font / CSS pipeline (apps/web):
 
 ### 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.
+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.
+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).
 
 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`.
 
@@ -188,8 +188,10 @@ BooCoder at port 9502: `curl http://100.114.205.53:9502/api/health`. Runs as `bo
 - A scrollable list inside a Dialog on mobile: cap `DialogContent` (`max-h-[85vh]` + `grid-rows-[auto_minmax(0,1fr)_auto]`) and make the list the single scroll region with `overscroll-contain` — otherwise touch-scroll drags the whole fixed modal / chains to the page.
 - xterm.js v5 uses canvas rendering — browser doesn't see xterm's selection; the native right-click menu has no working Copy for terminal text. App keybindings (`Cmd/Ctrl-C`, `Cmd/Ctrl-Shift-C`) are the path.
 - **New tools** live in their own `services/<name>.ts` file (see `web_search.ts`, `web_fetch.ts`) — exports a pure `executeFoo(input, ...deps)` for direct test access plus a `ToolDef` wrapper that `loadConfig()`s its real dependencies. Register the ToolDef in `tools.ts` `ALL_TOOLS` (and `READ_ONLY_TOOL_NAMES` if applicable). Inject `fetcher: typeof fetch = fetch` rather than `vi.spyOn(globalThis, 'fetch')` — cleanup is simpler and the production call site stays unchanged.
+- **DB/session-aware tools** take an optional 4th `ToolExecCtx { sql, sessionId }` arg on `ToolDef.execute`, plumbed `executeToolPhase`→`executeToolCall`→`execute`. It's optional so the filesystem tools and the `apps/coder` `ALL_TOOLS` consumer stay compatible; filesystem tools ignore it. `read_tab_by_number` (reads `sessions.workspace_panes` + the chat's messages via `sql`) is the reference.
 - **Sentinels** are `role='system'` rows with structured `metadata.kind` (`cap_hit`, `doom_loop`). UI-only — `buildMessagesPayload` strips them via `isAnySentinel` so the LLM never sees them. A new kind requires arms in `MessageMetadata` in BOTH `apps/server/src/types/api.ts` AND `apps/web/src/api/types.ts`, plus a render branch in `apps/web/src/components/MessageBubble.tsx`.
 - **ReadableStream test stubs** use `pull()` (not `start()`) so chunks are produced lazily — `start()` enqueues everything and calls `controller.close()` before the consumer reads, so a subsequent `reader.cancel()` finds the stream already closed and the `cancel()` callback never fires. Also provide MORE chunks than the test will consume so the source stays in 'readable' state when cancel runs (e.g. cap test reads ~6 chunks, stub provides 10).
+- React **StrictMode is on** (`main.tsx`): an updater passed to one `setState` that itself calls another `setState` (e.g. `setClosedPaneStack` inside a `setPanes` updater) is double-invoked in dev. Make such nested updates idempotent — `useWorkspacePanes`'s `appendClosed` dedupes a value-identical top entry for exactly this reason.
 - Tool-name whitelists must derive from `ALL_TOOLS` in `services/tools.ts`, never hardcoded. `services/agents.ts` `ALL_TOOL_NAMES` had this drift class until v1.12 — same pattern applies to any future tool-aware code.
 - Agent registry lives at `data/AGENTS.md` (global, bind-mounted at `/data/AGENTS.md`). No per-project `AGENTS.md` in this repo — removed in v1.12 to eliminate the two-files-must-stay-in-sync drift. The `getAgentsForProject` per-project override mechanism remains for *other* projects.
 - `data/AGENTS.md` is PARSED (`agents.ts` `splitSections`/`parseAgentSection`): each `## <Name>` is one agent and must be followed by a `---` frontmatter fence or the block throws; content before the first `## ` is discarded. Do NOT add free-form `## ` rule sections — they break the registry. Cross-cutting agent rules go in CLAUDE.md or a parser-ignored preamble.

apps/coder/src/config.ts

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

apps/coder/src/index.ts

@@ -25,16 +25,19 @@ import { setInferenceContext, clearInferenceContext } from './services/tools/inf
 import { registerMessageRoutes } from './routes/messages.js';
 import { registerSkillRoutes } from './routes/skills.js';
 import { registerPendingRoutes } from './routes/pending.js';
+import { registerAgentSessionRoutes } from './routes/agent-sessions.js';
 import { registerTaskRoutes } from './routes/tasks.js';
 import { registerInboxRoutes } from './routes/inbox.js';
 import { registerStatsRoutes } from './routes/stats.js';
 import { registerArenaRoutes } from './routes/arena.js';
 import { registerProviderRoutes } from './routes/providers.js';
 import { registerWorktreeSafetyRoutes } from './routes/worktree-safety.js';
+import { registerLifecycleRoutes } from './routes/lifecycle.js';
 import { registerWebSocket } from './routes/ws.js';
 // Phase 4: dispatcher + agent probe
 import { createDispatcher } from './services/dispatcher.js';
 import { agentPool } from './services/agent-pool.js';
+import { createOrphanWorktreeReaper } from './services/orphan-worktree-reaper.js';
 import { probeAgents } from './services/agent-probe.js';
 import { getProviderSnapshot, persistProbedModels } from './services/provider-snapshot.js';
 import { setPermissionHooks } from './services/permission-waiter.js';
@@ -180,10 +183,30 @@ async function main() {
   // Phase 4: dispatcher — polls tasks table and runs inference
   const dispatcher = createDispatcher({ sql, inference: inferenceApi, broker, log: app.log, config });
   dispatcher.start();
+
+  // v2.6 Phase 3: configure + start the agent-pool lifecycle sweep (idle-TTL +
+  // LRU-cap eviction of warm backends, plus each backend's proactive health probe)
+  // and the orphan-worktree reaper. Both run on the same periodic timer.
+  agentPool.configure({
+    idleTtlMs: config.AGENT_POOL_IDLE_TTL_MS,
+    maxLive: config.AGENT_POOL_MAX_LIVE,
+    sweepIntervalMs: config.LIFECYCLE_SWEEP_INTERVAL_MS,
+    log: app.log,
+  });
+  agentPool.startReaper(app.log);
+  const orphanReaper = createOrphanWorktreeReaper({
+    sql,
+    log: app.log,
+    intervalMs: config.LIFECYCLE_SWEEP_INTERVAL_MS,
+    graceMs: config.ORPHAN_WORKTREE_GRACE_MS,
+  });
+  orphanReaper.start();
+
   app.addHook('onClose', async () => {
-    // stop() first so in-flight dispatcher turns settle, then drain the pool.
+    // stop() first so in-flight dispatcher turns settle, then stop the reapers and
-    // Pool is empty in Phase 0 (nothing spawns yet) — dispose() is inert.
+    // drain the pool (kills opencode server + warm ACP children).
     await dispatcher.stop();
+    orphanReaper.stop();
     await agentPool.dispose();
   });
 
@@ -191,12 +214,14 @@ async function main() {
   registerMessageRoutes(app, sql, broker, inferenceApi);
   registerSkillRoutes(app, sql, broker, inferenceApi);
   registerPendingRoutes(app, sql);
+  registerAgentSessionRoutes(app, sql);
   registerTaskRoutes(app, sql, inferenceApi);
   registerInboxRoutes(app, sql);
   registerStatsRoutes(app, sql);
   registerArenaRoutes(app, sql);
   registerProviderRoutes(app, sql, config);
   registerWorktreeSafetyRoutes(app, sql);
+  registerLifecycleRoutes(app, sql);
   registerWebSocket(app, sql, broker);
 
   // Serve static frontend (built web app). In production, the dist/ is

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

@@ -0,0 +1,75 @@
+import { describe, it, expect } from 'vitest';
+import Fastify, { type FastifyInstance } from 'fastify';
+import { registerAgentSessionRoutes } from '../agent-sessions.js';
+import type { Sql } from '../../db.js';
+
+// Mock the porsager surface this route uses: a tagged-template `sql` dispatched by
+// query substring. Two queries: the session-existence check and the agent_sessions
+// JOIN. We return post-coercion shapes (booleans/strings) exactly as porsager would
+// hand them to the route — `has_session` already a JS boolean, `last_active_at` a
+// string|null — so the asserted JSON matches the API contract end-to-end.
+interface MockState {
+  sessionExists: boolean;
+  rows: Array<{ agent: string; status: string; has_session: boolean; last_active_at: string | null }>;
+}
+
+function mockSql(state: MockState): Sql {
+  return ((strings: TemplateStringsArray) => {
+    const q = strings.join('');
+    if (q.includes('SELECT id FROM sessions')) {
+      return Promise.resolve(state.sessionExists ? [{ id: 'session-1' }] : []);
+    }
+    if (q.includes('FROM agent_sessions')) {
+      return Promise.resolve(state.rows);
+    }
+    return Promise.resolve([]);
+  }) as unknown as Sql;
+}
+
+function buildApp(state: MockState): FastifyInstance {
+  const app = Fastify();
+  registerAgentSessionRoutes(app, mockSql(state));
+  return app;
+}
+
+describe('GET /api/sessions/:id/agent-sessions', () => {
+  it('returns the per-(chat,agent) rows in the contracted shape', async () => {
+    const app = buildApp({
+      sessionExists: true,
+      rows: [
+        { agent: 'opencode', status: 'active', has_session: true, last_active_at: '2026-05-31T12:00:00.000Z' },
+        { agent: 'goose', status: 'idle', has_session: false, last_active_at: null },
+      ],
+    });
+    const res = await app.inject({ method: 'GET', url: '/api/sessions/session-1/agent-sessions' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(Array.isArray(body)).toBe(true);
+    expect(body).toEqual([
+      { agent: 'opencode', status: 'active', has_session: true, last_active_at: '2026-05-31T12:00:00.000Z' },
+      { agent: 'goose', status: 'idle', has_session: false, last_active_at: null },
+    ]);
+    // Contract field types.
+    expect(typeof body[0].agent).toBe('string');
+    expect(typeof body[0].status).toBe('string');
+    expect(typeof body[0].has_session).toBe('boolean');
+    expect(body[1].last_active_at).toBeNull();
+    await app.close();
+  });
+
+  it('returns an empty array when the session has no agent_sessions rows', async () => {
+    const app = buildApp({ sessionExists: true, rows: [] });
+    const res = await app.inject({ method: 'GET', url: '/api/sessions/session-1/agent-sessions' });
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual([]);
+    await app.close();
+  });
+
+  it('404s when the session does not exist', async () => {
+    const app = buildApp({ sessionExists: false, rows: [] });
+    const res = await app.inject({ method: 'GET', url: '/api/sessions/nope/agent-sessions' });
+    expect(res.statusCode).toBe(404);
+    expect(res.json()).toEqual({ error: 'session not found' });
+    await app.close();
+  });
+});

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

@@ -0,0 +1,51 @@
+import type { FastifyInstance } from 'fastify';
+import type { Sql } from '../db.js';
+
+// v2.6 Phase 1-UX (design §9b): chat-scoped "resumed vs new session" indicator.
+// `agent_sessions` is keyed (chat_id, agent) — the tab/chat is the agent-context
+// unit (P1.5-b). The route param is a SESSION id, so we resolve every chat in the
+// session and return the union of their agent_sessions rows. A session with two
+// opencode tabs yields two rows (one per chat); the frontend keys the chip per
+// chat, but the wire shape is a flat per-(chat,agent) list.
+//
+// has_session = agent_session_id IS NOT NULL — i.e. a native backend session id
+// (opencode/ACP) was created and stored, so switching back resumes rather than
+// starts fresh.
+export interface AgentSessionRow {
+  agent: string;
+  status: string;
+  has_session: boolean;
+  last_active_at: string | null;
+}
+
+export function registerAgentSessionRoutes(app: FastifyInstance, sql: Sql): void {
+  // GET /api/sessions/:sessionId/agent-sessions — list the agent-session rows for
+  // every chat in the session (drives the AgentComposerBar resumed/new chip).
+  app.get<{ Params: { sessionId: string } }>(
+    '/api/sessions/:sessionId/agent-sessions',
+    async (req, reply) => {
+      const sessionId = req.params.sessionId;
+
+      const session = await sql<{ id: string }[]>`SELECT id FROM sessions WHERE id = ${sessionId}`;
+      if (session.length === 0) {
+        reply.code(404);
+        return { error: 'session not found' };
+      }
+
+      // Join through chats so the session-scoped param resolves to its (chat,agent)
+      // rows. last_active_at first → the frontend reads the freshest activity.
+      const rows = await sql<AgentSessionRow[]>`
+        SELECT
+          a.agent AS agent,
+          a.status AS status,
+          (a.agent_session_id IS NOT NULL) AS has_session,
+          a.last_active_at AS last_active_at
+        FROM agent_sessions a
+        JOIN chats c ON c.id = a.chat_id
+        WHERE c.session_id = ${sessionId}
+        ORDER BY a.last_active_at DESC NULLS LAST, a.agent ASC
+      `;
+      return rows;
+    },
+  );
+}

apps/coder/src/routes/lifecycle.ts

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

apps/coder/src/routes/pending.ts

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

apps/coder/src/schema.sql

@@ -131,6 +131,17 @@ END $$;
 -- v2.6: config fingerprint for stale-session detection (auto-recover on model change).
 ALTER TABLE agent_sessions ADD COLUMN IF NOT EXISTS config_hash TEXT;
 
+-- v2.6 Phase 1-UX (U.6): opencode token/cost usage, ACCUMULATED per (chat_id, agent).
+-- opencode's warm server emits `session.next.step.ended` once per LLM step (several
+-- per multi-tool turn) carrying {tokens{input,output,reasoning,cache},cost}. We sum
+-- each step's normalized {input,output,cost} onto the session row — running totals
+-- for the whole conversation context, not last-step. Backend-only; no route/UI yet.
+-- input_tokens folds in cache read+write; output_tokens folds in reasoning (see
+-- backends/opencode-usage.ts). Defaults 0 so accumulation (col + delta) is well-defined.
+ALTER TABLE agent_sessions ADD COLUMN IF NOT EXISTS input_tokens BIGINT NOT NULL DEFAULT 0;
+ALTER TABLE agent_sessions ADD COLUMN IF NOT EXISTS output_tokens BIGINT NOT NULL DEFAULT 0;
+ALTER TABLE agent_sessions ADD COLUMN IF NOT EXISTS cost DOUBLE PRECISION NOT NULL DEFAULT 0;
+
 -- ─── P1.5-b (corrected): worktrees entity + re-key agent_sessions to (chat_id, agent) ───
 -- The TAB (a chat) is the context unit: two opencode tabs in one session = two
 -- independent contexts sharing one worktree. So agent_sessions keys on

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

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

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

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

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

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

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

@@ -32,9 +32,9 @@ import { createAcpNdJsonStream } from './acp-stream.js';
 import { waitForPermissionResponse, waitForElicitationResponse, cancelPendingPermission } from './permission-waiter.js';
 import { mergeTaskCommands, getTaskCommands } from './agent-commands-cache.js';
 import { readWorktreeTextFile, writeWorktreeTextFile } from './acp-client-fs.js';
+import { mapSessionUpdate } from './acp-event-map.js';
 import {
   type AcpToolSnapshot,
-  mergeToolSnapshot,
   snapshotToWireToolCall,
   synthesizeCanceledSnapshots,
 } from './acp-tool-snapshot.js';
@@ -159,63 +159,47 @@ class AcpStreamContext {
     } as WsFrame);
   }
 
-  handleToolUpdate(toolCallId: string, update: Parameters<typeof mergeToolSnapshot>[1]): void {
-    const previous = this.toolSnapshots.get(toolCallId);
-    const snapshot = mergeToolSnapshot(toolCallId, update, previous);
-    this.toolSnapshots.set(toolCallId, snapshot);
-    this.publishToolSnapshot(snapshot);
-  }
-
   async handleSessionUpdate(params: SessionNotification): Promise<void> {
-    const update = params.update;
+    // v2.6 Phase 2: the case-by-case mapping now lives in the shared, pure
-    switch (update.sessionUpdate) {
+    // `mapSessionUpdate` (reused by the warm ACP backend). This method keeps the
-      case 'agent_message_chunk': {
+    // identical broker-publishing side effects — it just translates the normalized
-        const content = update.content;
+    // AgentEvents back into the same frames it always emitted. `this.toolSnapshots`
-        if (content.type === 'text' && 'text' in content) {
+    // is the merge accumulator, so a later tool_call_update merges over its
-          const text = (content as { text: string }).text;
+    // tool_call (the prior `handleToolUpdate` behavior, byte-for-byte).
-          this.textChunks.push(text);
+    for (const event of mapSessionUpdate(params, this.toolSnapshots)) {
+      switch (event.type) {
+        case 'text':
+          this.textChunks.push(event.text);
           if (this.canStream()) {
             this.opts.broker!.publishFrame(this.opts.sessionId!, {
               type: 'delta',
               message_id: this.opts.messageId!,
               chat_id: this.opts.chatId!,
-              content: text,
+              content: event.text,
             } as WsFrame);
           }
-        }
           break;
-      }
+        case 'reasoning':
-      case 'agent_thought_chunk': {
+          this.reasoningChunks.push(event.text);
-        const content = update.content;
-        if (content.type === 'text' && 'text' in content) {
-          const text = (content as { text: string }).text;
-          this.reasoningChunks.push(text);
           if (this.canStream()) {
             this.opts.broker!.publishFrame(this.opts.sessionId!, {
               type: 'reasoning_delta',
               message_id: this.opts.messageId!,
               chat_id: this.opts.chatId!,
-              content: text,
+              content: event.text,
             } as WsFrame);
           }
-        }
           break;
-      }
         case 'tool_call':
-        this.handleToolUpdate(update.toolCallId, update);
+        case 'tool_update':
+          // mapSessionUpdate already stored the merged snapshot in this.toolSnapshots.
+          this.publishToolSnapshot(event.toolCall);
           break;
-      case 'tool_call_update':
+        case 'commands':
-        this.handleToolUpdate(update.toolCallId, update);
+          if (this.opts.taskId && event.commands.length > 0) {
-        break;
+            mergeTaskCommands(this.opts.taskId, event.commands);
-      case 'available_commands_update': {
-        const commands = update.availableCommands.map((cmd) => ({
-          name: cmd.name,
-          description: cmd.description ?? undefined,
-        }));
-        if (this.opts.taskId && commands.length > 0) {
-          mergeTaskCommands(this.opts.taskId, commands);
             if (this.canStream() && this.opts.sessionId) {
-            const all = getTaskCommands(this.opts.taskId) ?? commands;
+              const all = getTaskCommands(this.opts.taskId) ?? event.commands;
               this.opts.broker!.publishFrame(this.opts.sessionId, {
                 type: 'agent_commands',
                 task_id: this.opts.taskId,
@@ -226,8 +210,6 @@ class AcpStreamContext {
           }
           break;
       }
-      default:
-        break;
     }
   }
 

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

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

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

@@ -70,6 +70,12 @@ export interface PromptCtx {
   model: string;
   signal: AbortSignal;
   onEvent: (e: AgentEvent) => void;
+  /** Phase 2: per-turn task id, so a warm ACP backend can route permission /
+   *  elicitation prompts back to the UI via the permission-waiter. Optional —
+   *  the opencode-server backend (autonomous) ignores it. */
+  taskId?: string;
+  /** Phase 2: per-turn mode id (gates autonomous mode in the permission-waiter). */
+  modeId?: string;
 }
 
 /** Result of a completed turn (§2). Diff/persist happen outside the backend. */
@@ -93,4 +99,21 @@ export interface AgentBackend {
   dispose(): Promise<void>;
   /** Liveness for health endpoint + dispatcher fallback decision. §2 */
   health(): 'up' | 'down';
+  /**
+   * v2.6 Phase 3: true iff a turn is in flight on this backend. The pool's idle
+   * eviction + LRU cap NEVER evict a busy backend (design §6 busy rule); the
+   * health-monitor defers a restart while busy (stale-grace). Optional so the
+   * Phase-0 scaffold and any test double stay compatible — absent ⇒ treated as
+   * not busy. opencode-server (multi-session) is busy iff ANY session has an
+   * active turn; warm-acp (single session) iff its one slot is active.
+   */
+  isBusy?(): boolean;
+  /**
+   * v2.6 Phase 3: optional proactive health probe + busy-aware self-restart, run
+   * by the pool's periodic sweep. The opencode-server backend implements it
+   * (detects a hung-but-not-exited server and restarts when non-busy). Backends
+   * with no long-lived shared process (warm-ACP recovers lazily on its own child
+   * exit) can omit it. Must never throw — the sweep ignores rejections.
+   */
+  tickHealth?(now?: number): Promise<void>;
 }

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

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

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

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

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

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest';
+import { stepEndedToUsage } from '../opencode-usage.js';
+
+describe('stepEndedToUsage (U.6)', () => {
+  it('folds cache read+write into input and reasoning into output', () => {
+    const u = stepEndedToUsage({
+      cost: 0.0123,
+      tokens: { input: 100, output: 50, reasoning: 20, cache: { read: 10, write: 5 } },
+    });
+    expect(u).toEqual({ input: 115, output: 70, cost: 0.0123 });
+  });
+
+  it('handles a step with no cache and no reasoning', () => {
+    const u = stepEndedToUsage({
+      cost: 0,
+      tokens: { input: 8, output: 4, reasoning: 0, cache: { read: 0, write: 0 } },
+    });
+    expect(u).toEqual({ input: 8, output: 4, cost: 0 });
+  });
+
+  it('is defensive against a missing tokens block', () => {
+    const u = stepEndedToUsage({ cost: 0.5 } as never);
+    expect(u).toEqual({ input: 0, output: 0, cost: 0.5 });
+  });
+
+  it('is defensive against undefined props', () => {
+    expect(stepEndedToUsage(undefined)).toEqual({ input: 0, output: 0, cost: 0 });
+  });
+
+  it('drops NaN / negative noise to zero rather than poisoning the accumulated total', () => {
+    const u = stepEndedToUsage({
+      cost: Number.NaN,
+      tokens: {
+        input: -5,
+        output: Number.NaN,
+        reasoning: 3,
+        cache: { read: Number.POSITIVE_INFINITY, write: 2 },
+      },
+    });
+    // input: (-5→0) + (Inf→0) + 2 = 2; output: (NaN→0) + 3 = 3; cost: NaN→0
+    expect(u).toEqual({ input: 2, output: 3, cost: 0 });
+  });
+
+  it('rounds fractional token counts', () => {
+    const u = stepEndedToUsage({
+      cost: 1.5,
+      tokens: { input: 10.6, output: 4.4, reasoning: 0, cache: { read: 0, write: 0 } },
+    });
+    expect(u).toEqual({ input: 11, output: 4, cost: 1.5 });
+  });
+});

apps/coder/src/services/backends/__tests__/turn-guard.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest';
+import {
+  armAbortGuard,
+  noteTurnActivity,
+  consumeTerminal,
+  type AbortTerminalGuard,
+} from '../turn-guard.js';
+
+describe('post-abort terminal guard (F.1)', () => {
+  it('swallows the orphan terminal that follows an abort, then settles the next real one', () => {
+    // Reproduces the v2.6.5 Stop-button bug: abort turn A, then opencode emits a
+    // trailing session.idle for A. That orphan must NOT settle the next turn.
+    const g: AbortTerminalGuard = { swallowNextTerminal: false };
+
+    armAbortGuard(g); // user aborts turn A
+    expect(consumeTerminal(g)).toBe('swallow'); // opencode's orphan idle for A → dropped
+    expect(consumeTerminal(g)).toBe('settle'); // turn B's real idle → settles B
+  });
+
+  it('settles a terminal when no abort happened', () => {
+    const g: AbortTerminalGuard = { swallowNextTerminal: false };
+    expect(consumeTerminal(g)).toBe('settle');
+  });
+
+  it('self-heals if the orphan never arrives: new-turn activity clears the guard', () => {
+    // If opencode emits no orphan idle (e.g. abort-before-prompt), the next turn's
+    // real terminal must still settle rather than being swallowed forever.
+    const g: AbortTerminalGuard = { swallowNextTerminal: false };
+
+    armAbortGuard(g); // abort A, but no orphan idle arrives
+    noteTurnActivity(g); // turn B produces its first delta
+    expect(consumeTerminal(g)).toBe('settle'); // turn B's idle settles, not swallowed
+  });
+});

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

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

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

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

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

@@ -21,9 +21,9 @@
  *   - promptAsync is fire-and-forget (204); the turn completes via a
  *     'session.idle' event for that opencode session id.
  */
-import { spawn, type ChildProcess } from 'node:child_process';
+import { spawn, spawnSync, type ChildProcess } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { createServer } from 'node:net';
+import { createServer, connect as netConnect } from 'node:net';
 import type { FastifyBaseLogger } from 'fastify';
 import {
   createOpencodeClient,
@@ -37,6 +37,9 @@ import {
 import type { ToolCallStatus } from '@agentclientprotocol/sdk';
 import type { Sql } from '../../db.js';
 import type { AcpToolSnapshot } from '../acp-tool-snapshot.js';
+import { armAbortGuard, noteTurnActivity, consumeTerminal } from './turn-guard.js';
+import { stepEndedToUsage, type StepUsage } from './opencode-usage.js';
+import { decideRestart, DEFAULT_HEALTH_FAILURE_THRESHOLD } from './lifecycle-decisions.js';
 import type {
   AgentBackend,
   AgentEvent,
@@ -78,6 +81,9 @@ interface SessionState {
   /** Per-session SSE subscription handle. Non-null while the loop is running;
    *  aborting it tears down the underlying fetch and exits the loop. */
   sseAbort: AbortController | null;
+  /** F.1 post-abort orphan-terminal guard: swallow the one session.idle/error
+   *  opencode emits for an aborted turn so it can't settle the next turn. */
+  swallowNextTerminal: boolean;
 }
 
 export interface OpenCodeServerBackendDeps {
@@ -99,6 +105,11 @@ export class OpenCodeServerBackend implements AgentBackend {
   private port: number | null = null;
   private up = false;
   private serverStarting: Promise<void> | null = null;
+  // Phase 3 busy-aware health monitor (openchamber lift): consecutive failed
+  // probes + the start of an unhealthy-while-busy window feed `decideRestart`.
+  private consecutiveHealthFailures = 0;
+  private unhealthyBusySince = 0;
+  private restarting: Promise<void> | null = null;
 
   /** opencode session id → demux state. Maintained by ensureSession; read by the SSE loop. */
   private readonly byOpencodeId = new Map<string, SessionState>();
@@ -114,11 +125,30 @@ export class OpenCodeServerBackend implements AgentBackend {
     return this.up ? 'up' : 'down';
   }
 
-  // ─── Server lifecycle (1.2: spawn once + client + ready) ─────────────────────
+  /** Phase 3: busy iff ANY pooled opencode session has an in-flight turn. The
+   *  pool reads this to skip idle/LRU eviction and the health-monitor to defer a
+   *  restart (never tear down a session mid-stream). */
+  isBusy(): boolean {
+    for (const st of this.byOpencodeId.values()) {
+      if (st.activeTurn) return true;
+    }
+    return false;
+  }
 
-  /** Lazy: start the single server on first use. Idempotent — one server per backend. */
+  // ─── Server lifecycle (1.2: spawn once + client + ready; Phase 3 crash-restart) ──
+
+  /**
+   * Lazy: start the single server on first use; re-spawn after a crash. Idempotent
+   * within one live server — `serverStarting` caches the in-flight start, and is
+   * reset to null by the crash handler so the NEXT ensureServer re-spawns a fresh
+   * server (Phase 3 crash recovery). A dead-but-not-yet-reaped child (exit handler
+   * raced) is also treated as needing a restart.
+   */
   private ensureServer(): Promise<void> {
-    if (!this.serverStarting) this.serverStarting = this.startServer();
+    const childDead = this.child != null && (this.child.exitCode !== null || this.child.signalCode !== null);
+    if (!this.serverStarting || (!this.up && childDead)) {
+      this.serverStarting = this.startServer();
+    }
     return this.serverStarting;
   }
 
@@ -138,11 +168,15 @@ export class OpenCodeServerBackend implements AgentBackend {
     this.port = port;
 
     // Child lifetime is the backend's (the pool's), NOT a request's. We never tie
-    // it to a per-turn abort signal. On unexpected exit we mark down + log; crash
+    // it to a per-turn abort signal. Phase 3: on unexpected exit we recover —
-    // recovery is Phase 3.
+    // settle any in-flight turns as failed, mark their agent_sessions rows crashed,
+    // and reset `serverStarting` so the next ensureServer re-spawns. opencode keeps
+    // sessions on disk, but a fresh server's in-memory state is gone, so the next
+    // turn's ensureSession (rows now 'crashed') creates fresh opencode sessions.
     child.on('exit', (code, signal) => {
-      this.up = false;
+      // Only react to THIS child's exit (a restart may have swapped in a new one).
-      this.log.warn({ code, signal, port }, 'opencode-server: child exited (recovery is Phase 3)');
+      if (this.child !== child) return;
+      this.handleServerCrash(code, signal, port);
     });
 
     await waitForReady(child, READY_TIMEOUT_MS);
@@ -152,6 +186,136 @@ export class OpenCodeServerBackend implements AgentBackend {
     this.log.info({ port }, 'opencode-server: ready');
   }
 
+  /**
+   * Crash handler (Phase 3, lift of openchamber's restart-on-exit path). The
+   * server died with N live opencode sessions; we can't restart it here (the next
+   * turn does, lazily — avoids a restart storm if the binary is broken). We:
+   *   1. fail every in-flight turn so its dispatcher unblocks + publishes an error,
+   *   2. mark each session's agent_sessions row 'crashed' so ensureSession won't
+   *      resume a now-dead native session id (it creates fresh),
+   *   3. tear down the SSE loops + demux state (stale against the dead server),
+   *   4. reclaim the port + reset state so the next ensureServer re-spawns.
+   */
+  private handleServerCrash(code: number | null, signal: NodeJS.Signals | null, port: number): void {
+    this.up = false;
+    const states = [...this.byOpencodeId.values()];
+    this.log.warn(
+      { code, signal, port, liveSessions: states.length },
+      'opencode-server: child exited — recovering (fail in-flight, mark crashed, re-spawn next turn)',
+    );
+
+    const crashedIds: string[] = [];
+    for (const st of states) {
+      st.sseAbort?.abort();
+      if (st.activeTurn) {
+        st.activeTurn.settle({ ok: false, error: 'opencode server crashed mid-turn' });
+        st.activeTurn = null;
+      }
+      if (st.watchdog) {
+        clearTimeout(st.watchdog);
+        st.watchdog = null;
+      }
+      crashedIds.push(st.agentSessionId);
+    }
+    // Drop the demux map: every session id is stale against a fresh server.
+    this.byOpencodeId.clear();
+    this.client = null;
+    this.serverStarting = null; // force a re-spawn on the next ensureServer
+
+    if (crashedIds.length > 0) {
+      this.sql`
+        UPDATE agent_sessions SET status = 'crashed'
+        WHERE agent_session_id = ANY(${crashedIds}) AND status <> 'closed'
+      `.catch((err) => {
+        this.log.warn({ err: errMsg(err) }, 'opencode-server: failed to mark crashed sessions (non-fatal)');
+      });
+    }
+
+    // Reclaim the port so a re-spawn on a fixed/leaked port isn't blocked. Best
+    // effort; the next start uses a fresh ephemeral port anyway.
+    reclaimPort(port);
+  }
+
+  /**
+   * Phase 3 proactive health monitor (openchamber `runHealthCheckCycle` lift,
+   * busy-aware). Probes the server's /global/health; on a sustained failure of a
+   * NON-busy server, force a restart so the next turn isn't blocked by a wedged
+   * (hung-but-not-exited) process. Busy servers are deferred via the stale-grace in
+   * `decideRestart` — never tear down live work. Driven by the pool's periodic
+   * sweep (best-effort; a crash-exit is already handled by `handleServerCrash` +
+   * lazy `ensureServer` re-spawn, so this only catches the hung case). No-op when
+   * the server was never started or a restart is already in flight.
+   */
+  async tickHealth(now: number = Date.now()): Promise<void> {
+    if (!this.child || this.restarting) return;
+    const childExited = this.child.exitCode !== null || this.child.signalCode !== null;
+    // An exited child is recovered lazily by ensureServer; don't double-restart it.
+    if (childExited) return;
+
+    const healthy = await this.probeHealth();
+    if (healthy) {
+      this.consecutiveHealthFailures = 0;
+      this.unhealthyBusySince = 0;
+      return;
+    }
+    this.consecutiveHealthFailures += 1;
+    const busy = this.isBusy();
+    const decision = decideRestart({
+      processExited: false,
+      consecutiveFailures: this.consecutiveHealthFailures,
+      busy,
+      unhealthyBusySince: this.unhealthyBusySince,
+      now,
+      failureThreshold: DEFAULT_HEALTH_FAILURE_THRESHOLD,
+    });
+    // Stamp the start of an unhealthy-while-busy window so the stale-grace can fire.
+    if (busy && this.unhealthyBusySince === 0) this.unhealthyBusySince = now;
+    if (decision.action === 'restart') {
+      this.log.warn(
+        { failures: this.consecutiveHealthFailures, busy, reason: decision.reason },
+        'opencode-server: health monitor forcing restart',
+      );
+      this.consecutiveHealthFailures = 0;
+      this.unhealthyBusySince = 0;
+      await this.restartServer();
+    }
+  }
+
+  private async probeHealth(): Promise<boolean> {
+    if (!this.client) return false;
+    try {
+      const res = await this.client.global.health();
+      return !res.error;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Force-kill the current server + reclaim its port; the next ensureServer
+   *  re-spawns (lazy). Mirrors handleServerCrash's state reset but is initiated by
+   *  the health monitor rather than the OS. */
+  private async restartServer(): Promise<void> {
+    if (this.restarting) return this.restarting;
+    this.restarting = (async () => {
+      const child = this.child;
+      const port = this.port;
+      this.up = false;
+      // Fail in-flight turns + mark sessions crashed via the same path as a crash.
+      if (child) {
+        this.handleServerCrash(null, null, port ?? 0);
+        if (!child.killed) child.kill('SIGTERM');
+      }
+      if (port) {
+        reclaimPort(port);
+        await waitForPortRelease(port, 3_000);
+      }
+      this.child = null;
+    })().finally(() => {
+      this.restarting = null;
+    });
+    return this.restarting;
+  }
+
   // ─── SSE read loop + demux + translate (1.3) + dedup (1.4) ───────────────────
 
   /** Per-session SSE subscription, scoped to the session's worktree directory.
@@ -278,6 +442,19 @@ export class OpenCodeServerBackend implements AgentBackend {
         st.activeTurn.onEvent({ type: 'tool_update', toolCall: snap });
         return;
       }
+      // ─── per-step usage (U.6) — token/cost accounting for opencode sessions ──
+      case 'session.next.step.ended': {
+        const p = ev.properties;
+        const st = this.byOpencodeId.get(p.sessionID);
+        if (!st?.activeTurn) return;
+        this.bumpActivity(st);
+        // Accumulate this step's normalized usage onto the (chat_id, agent) row.
+        // Fire-and-forget: a DB hiccup must not stall the turn. opencode emits this
+        // once per LLM step, so a multi-tool turn sums several deltas.
+        const usage = stepEndedToUsage(p);
+        void this.accumulateUsage(st, usage);
+        return;
+      }
       // ─── message.part.* — terminal/post-hoc events (dedup gate) ────────────
       case 'message.part.delta': {
         const p = ev.properties;
@@ -305,13 +482,19 @@ export class OpenCodeServerBackend implements AgentBackend {
       }
       // ─── lifecycle ─────────────────────────────────────────────────────────
       case 'session.idle': {
-        this.byOpencodeId.get(ev.properties.sessionID)?.activeTurn?.settle({ ok: true });
+        const st = this.byOpencodeId.get(ev.properties.sessionID);
+        if (!st) return;
+        if (consumeTerminal(st) === 'swallow') return; // F.1: drop the post-abort orphan
+        st.activeTurn?.settle({ ok: true });
         return;
       }
       case 'session.error': {
         const sid = ev.properties.sessionID;
         if (!sid) return;
-        this.byOpencodeId.get(sid)?.activeTurn?.settle({ ok: false, error: errToString(ev.properties.error) });
+        const st = this.byOpencodeId.get(sid);
+        if (!st) return;
+        if (consumeTerminal(st) === 'swallow') return; // F.1: drop the post-abort orphan
+        st.activeTurn?.settle({ ok: false, error: errToString(ev.properties.error) });
         return;
       }
       default:
@@ -358,6 +541,8 @@ export class OpenCodeServerBackend implements AgentBackend {
   /** Reset the inactivity backstop on any event routed to a session's active turn. */
   private bumpActivity(st: SessionState): void {
     if (!st.activeTurn) return;
+    // A live turn is producing → the post-abort orphan-terminal window is over.
+    noteTurnActivity(st);
     if (st.watchdog) clearTimeout(st.watchdog);
     st.watchdog = setTimeout(() => {
       void this.onTurnStall(st);
@@ -416,6 +601,33 @@ export class OpenCodeServerBackend implements AgentBackend {
     }
   }
 
+  // ─── per-step usage persistence (U.6) ────────────────────────────────────────
+
+  /**
+   * Accumulate one `session.next.step.ended`'s normalized usage onto the session's
+   * agent_sessions row, keyed by the resumed `agent_session_id` (unique per active
+   * row — the dispatcher's `(chat_id, agent)` lookup wrote it). Running totals for
+   * the whole conversation context (not last-step). Zero-delta steps are skipped to
+   * avoid a no-op write. Errors are swallowed: usage telemetry must never fail a turn.
+   */
+  private async accumulateUsage(st: SessionState, u: StepUsage): Promise<void> {
+    if (u.input === 0 && u.output === 0 && u.cost === 0) return;
+    try {
+      await this.sql`
+        UPDATE agent_sessions SET
+          input_tokens = input_tokens + ${u.input},
+          output_tokens = output_tokens + ${u.output},
+          cost = cost + ${u.cost}
+        WHERE agent_session_id = ${st.agentSessionId}
+      `;
+    } catch (err) {
+      this.log.warn(
+        { err: errMsg(err), agentSessionId: st.agentSessionId },
+        'opencode-server: failed to persist step usage (non-fatal)',
+      );
+    }
+  }
+
   // ─── ensureSession: create-or-resume against agent_sessions (1.5) ────────────
 
   async ensureSession(sessionId: string, opts: EnsureSessionOpts): Promise<AgentSessionHandle> {
@@ -490,6 +702,7 @@ export class OpenCodeServerBackend implements AgentBackend {
         activeTurn: null,
         watchdog: null,
         sseAbort: null,
+        swallowNextTerminal: false,
       };
       this.byOpencodeId.set(ocSessionId, state);
     }
@@ -528,6 +741,7 @@ export class OpenCodeServerBackend implements AgentBackend {
         activeTurn: null,
         watchdog: null,
         sseAbort: null,
+        swallowNextTerminal: false,
       };
       this.byOpencodeId.set(oc, state);
     }
@@ -561,6 +775,9 @@ export class OpenCodeServerBackend implements AgentBackend {
       const onAbort = () => {
         // Abort the turn only — never the server.
         client.session.abort({ sessionID: oc, directory: ctx.worktreePath }).catch(() => {});
+        // F.1: opencode emits one trailing session.idle/error for the cancelled
+        // turn — arm the guard so it's swallowed, not used to settle the next turn.
+        armAbortGuard(session);
         settle({ ok: false, error: 'aborted' });
       };
 
@@ -698,6 +915,67 @@ function mapToolStatus(s: ToolState['status'] | undefined): ToolCallStatus | nul
   }
 }
 
+/**
+ * Reclaim a loopback port a dead opencode child may still hold (lift of
+ * openchamber `killProcessOnPort`). Best-effort, POSIX-only (`lsof`/`kill`); a
+ * failure is harmless because the next spawn allocates a fresh ephemeral port.
+ * Never kills this process. Synchronous + short-timeout so the crash handler
+ * doesn't block.
+ */
+function reclaimPort(port: number | null): void {
+  if (!port || process.platform === 'win32') return;
+  try {
+    const res = spawnSync('lsof', ['-ti', `:${port}`], { encoding: 'utf8', timeout: 3_000, windowsHide: true });
+    const out = res.stdout || '';
+    const myPid = process.pid;
+    for (const pidStr of out.split(/\s+/)) {
+      const pid = parseInt(pidStr.trim(), 10);
+      if (pid && pid !== myPid) {
+        try {
+          spawnSync('kill', ['-9', String(pid)], { stdio: 'ignore', timeout: 2_000 });
+        } catch {
+          // ignore — best effort
+        }
+      }
+    }
+  } catch {
+    // lsof absent or failed — the fresh-ephemeral-port spawn doesn't need this.
+  }
+}
+
+/**
+ * Resolve true once nothing is listening on `port` (lift of openchamber
+ * `waitForPortRelease`). Used before re-spawning on a fixed port; with ephemeral
+ * ports it's a fast no-op. Probes 127.0.0.1; resolves false at the deadline.
+ */
+function waitForPortRelease(port: number, timeoutMs: number): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  return new Promise((resolve) => {
+    const attempt = () => {
+      const socket = netConnect({ port, host: '127.0.0.1' });
+      let settled = false;
+      const finish = (released: boolean) => {
+        if (settled) return;
+        settled = true;
+        socket.removeAllListeners();
+        socket.destroy();
+        if (released || Date.now() >= deadline) {
+          resolve(released);
+          return;
+        }
+        setTimeout(attempt, 150);
+      };
+      socket.once('connect', () => finish(false));
+      socket.once('error', (err: NodeJS.ErrnoException) => {
+        if (err && (err.code === 'ECONNREFUSED' || err.code === 'EHOSTUNREACH')) finish(true);
+        else finish(false);
+      });
+      socket.setTimeout(500, () => finish(true));
+    };
+    attempt();
+  });
+}
+
 /** Bind-probe an ephemeral port on loopback. */
 function freePort(): Promise<number> {
   return new Promise((resolve, reject) => {

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

@@ -0,0 +1,77 @@
+/**
+ * v2.6 Phase 1-UX (U.6) — pure mapper for opencode's per-step usage event.
+ *
+ * opencode's warm server emits `session.next.step.ended` once per completed LLM
+ * step (so a multi-tool turn fires it several times). Its `properties` carry the
+ * step's token + cost accounting:
+ *
+ *   {
+ *     timestamp: number;
+ *     sessionID: string;
+ *     finish: string;
+ *     cost: number;                                  // USD for this step
+ *     tokens: {
+ *       input: number; output: number; reasoning: number;
+ *       cache: { read: number; write: number };
+ *     };
+ *     snapshot?: string;
+ *   }
+ *
+ * (Verified against @opencode-ai/sdk@1.15.12 — `EventSessionNextStepEnded` in
+ * `dist/v2/gen/types.gen.d.ts`, a member of the `Event` union the SSE loop
+ * switches on.)
+ *
+ * We normalize to the review's target slice `{input, output, cost}` (the
+ * provider-agnostic `AgentUsage` shape lands later). cache read/write tokens are
+ * folded into `input` so the persisted input count reflects the real context the
+ * model billed for; reasoning tokens are folded into `output` since that's what
+ * the provider counts them as for generation. This keeps the persisted totals a
+ * faithful sum of what opencode reported, without inventing extra columns yet.
+ */
+
+/** The `properties` shape of a `session.next.step.ended` event (subset we read). */
+export interface StepEndedProps {
+  cost: number;
+  tokens: {
+    input: number;
+    output: number;
+    reasoning: number;
+    cache: { read: number; write: number };
+  };
+}
+
+/** Normalized per-step usage delta persisted onto the agent_sessions row. */
+export interface StepUsage {
+  input: number;
+  output: number;
+  cost: number;
+}
+
+/** Coerce a possibly-missing/NaN number to a non-negative finite integer (tokens). */
+function n(v: unknown): number {
+  const x = typeof v === 'number' ? v : Number(v);
+  return Number.isFinite(x) && x > 0 ? Math.round(x) : 0;
+}
+
+/** Coerce a possibly-missing/NaN number to a non-negative finite float (cost USD). */
+function f(v: unknown): number {
+  const x = typeof v === 'number' ? v : Number(v);
+  return Number.isFinite(x) && x > 0 ? x : 0;
+}
+
+/**
+ * Map a `session.next.step.ended` payload → the normalized `{input, output, cost}`
+ * delta. Defensive against missing/partial token blocks (the wire is trusted but
+ * we never want a NaN to poison the accumulated DB total). `input` folds in cache
+ * read+write; `output` folds in reasoning.
+ */
+export function stepEndedToUsage(props: Partial<StepEndedProps> | undefined): StepUsage {
+  const t = props?.tokens;
+  const cacheRead = n(t?.cache?.read);
+  const cacheWrite = n(t?.cache?.write);
+  return {
+    input: n(t?.input) + cacheRead + cacheWrite,
+    output: n(t?.output) + n(t?.reasoning),
+    cost: f(props?.cost),
+  };
+}

apps/coder/src/services/backends/turn-guard.ts

@@ -0,0 +1,38 @@
+/**
+ * Guard against opencode's post-abort "orphan" terminal event (F.1).
+ *
+ * When a turn is aborted (`client.session.abort`), opencode emits one trailing
+ * `session.idle` / `session.error` for the cancelled turn. Without a guard that
+ * orphan settles whatever turn currently holds the session slot — which, after
+ * the user immediately sends another message, is the NEXT turn, settling it early
+ * as success (the v2.6.5 Stop-button bug). opencode terminal events carry only a
+ * `sessionID` (no turn id), so we can't match by id; instead we swallow exactly
+ * one terminal per abort, and self-heal if that orphan never arrives.
+ */
+export interface AbortTerminalGuard {
+  /** True between an abort and the orphan terminal event that follows it. */
+  swallowNextTerminal: boolean;
+}
+
+/** Arm on abort: the next terminal event for this session is the orphan. */
+export function armAbortGuard(g: AbortTerminalGuard): void {
+  g.swallowNextTerminal = true;
+}
+
+/**
+ * A new turn produced activity (delta) → the orphan window is over. Self-heals
+ * the case where opencode emits no orphan idle (e.g. abort-before-prompt), so a
+ * real terminal still settles instead of being swallowed forever.
+ */
+export function noteTurnActivity(g: AbortTerminalGuard): void {
+  g.swallowNextTerminal = false;
+}
+
+/** Decide a terminal (idle/error): swallow the post-abort orphan once, else settle. */
+export function consumeTerminal(g: AbortTerminalGuard): 'swallow' | 'settle' {
+  if (g.swallowNextTerminal) {
+    g.swallowNextTerminal = false;
+    return 'swallow';
+  }
+  return 'settle';
+}

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

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

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

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

apps/coder/src/services/dispatcher.ts

@@ -12,8 +12,10 @@ import { clearTaskCommands, setTaskCommands } from './agent-commands-cache.js';
 import { getManifestCommands } from './provider-commands.js';
 import { persistExternalAgentTurn } from './agent-turn-persist.js';
 import { snapshotToWireToolCall, type AcpToolSnapshot } from './acp-tool-snapshot.js';
-import { agentPool } from './agent-pool.js';
+import { agentPool, OPENCODE_POOL_KEY } from './agent-pool.js';
 import { OpenCodeServerBackend } from './backends/opencode-server.js';
+import { WarmAcpBackend } from './backends/warm-acp.js';
+import { shouldUseWarmBackend } from './backends/warm-acp-routing.js';
 import type { AgentBackend, AgentEvent } from './agent-backend.js';
 
 interface InferenceRunner {
@@ -121,10 +123,15 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         SELECT name, supports_acp, install_path FROM available_agents WHERE name = ${task.agent}
       `;
       if (agentRow) {
-        // v2.6 (1.7): opencode routes to the warm pool backend; every other
+        // v2.6 (1.7): opencode routes to its warm HTTP-server backend.
-        // external agent keeps the existing one-shot ACP/PTY path untouched.
+        // v2.6 Phase 2 (2.4): goose/qwen route to the warm ACP backend WHEN the
+        // task came from a real chat tab (session_id + chat_id) — shouldUseWarmBackend.
+        // Session-less creators (arena, MCP, new_task, generic /api/tasks) keep the
+        // existing one-shot worktree-per-task ACP/PTY path untouched.
         if (task.agent === 'opencode') {
           await runOpenCodeServerTask(task, agentRow.install_path);
+        } else if (shouldUseWarmBackend(task)) {
+          await runWarmAcpTask(task, agentRow.install_path);
         } else {
           await runExternalAgent(task, agentRow.supports_acp, agentRow.install_path);
         }
@@ -441,10 +448,11 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
       const diff = await diffWorktree(worktreePath, projectPath, { signal: ac.signal });
 
       if (diff) {
-        // Queue a single pending_change entry with the full unified diff
+        // Queue a single pending_change entry with the full unified diff, stamped
+        // with the dispatched agent for DiffPanel attribution (v2.6 Phase 1-UX).
         await sql`
-          INSERT INTO pending_changes (session_id, task_id, file_path, operation, diff)
+          INSERT INTO pending_changes (session_id, task_id, file_path, operation, diff, agent)
-          VALUES (${sessionId}, ${taskId}, ${projectPath}, 'edit', ${diff})
+          VALUES (${sessionId}, ${taskId}, ${projectPath}, 'edit', ${diff}, ${agent})
         `;
         log.info({ taskId, diffLength: diff.length }, 'dispatcher: diff queued as pending change');
       } else {
@@ -491,9 +499,8 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
 
   // OpenCode runs ONE server per BooCoder process, shared across all sessions
   // (the backend multiplexes sessions internally), so it's pooled under a fixed
-  // key rather than per-session. Warm ACP backends (Phase 2) will be per-session.
+  // key (OPENCODE_POOL_KEY, shared with the lifecycle close-hook) rather than
-  const OPENCODE_POOL_KEY = '__opencode_server__';
+  // per-session. Warm ACP backends (Phase 2) are per (chat, agent).
-
   function getOpenCodeBackend(installPath: string | null): AgentBackend {
     let backend = agentPool.get(OPENCODE_POOL_KEY, 'opencode');
     if (!backend) {
@@ -702,6 +709,9 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         signal: ac.signal,
         onEvent,
       });
+      // Phase 3: keep the pooled backend's slot warm across this (possibly long)
+      // turn so the idle sweep measures from turn END, not start.
+      agentPool.touch(OPENCODE_POOL_KEY, agent);
 
       // Flush any text held back mid-tag at stream end (complete tags stripped).
       const dcpTail = dcp.flush();
@@ -787,6 +797,247 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
     }
   }
 
+  // ─── Path B (warm ACP): goose / qwen warm backend (v2.6 Phase 2) ─────────────
+
+  // Warm ACP backends are per (chat, agent): each owns ONE stdio process + ACP
+  // connection + session. Pool key = chatId; the AgentPool's secondary key is the
+  // agent. This mirrors agent_sessions' (chat_id, agent) PK.
+  function getWarmAcpBackend(chatId: string, agent: string, installPath: string | null): WarmAcpBackend {
+    let backend = agentPool.get(chatId, agent);
+    if (!backend) {
+      backend = new WarmAcpBackend({
+        sql,
+        log,
+        chatId,
+        agent,
+        installPath,
+        resolved: getResolvedRegistry().get(agent),
+      });
+      agentPool.register(chatId, agent, backend);
+    }
+    return backend as WarmAcpBackend;
+  }
+
+  async function runWarmAcpTask(
+    task: {
+      id: string;
+      project_id: string;
+      input: string;
+      agent: string | null;
+      model: string | null;
+      mode_id: string | null;
+      thinking_option_id: string | null;
+      session_id: string | null;
+      chat_id: string | null;
+    },
+    installPath: string | null,
+  ): Promise<void> {
+    const taskId = task.id;
+    const agent = task.agent!;
+    // shouldUseWarmBackend guarantees both non-null before we get here.
+    const sessionId = task.session_id!;
+    const chatId = task.chat_id!;
+    log.info({ taskId, agent, chatId }, 'dispatcher: starting task (path B — warm ACP)');
+
+    const [project] = await sql<{ path: string | null }[]>`
+      SELECT path FROM projects WHERE id = ${task.project_id}
+    `;
+    const projectPath = project?.path;
+    if (!projectPath) {
+      await sql`
+        UPDATE tasks
+        SET state = 'failed', ended_at = clock_timestamp(), output_summary = 'Project has no path — cannot create worktree'
+        WHERE id = ${taskId}
+      `;
+      return;
+    }
+
+    const ac = new AbortController();
+
+    try {
+      await sql`
+        UPDATE tasks
+        SET state = 'running', started_at = clock_timestamp(), execution_path = 'acp'
+        WHERE id = ${taskId}
+      `;
+
+      // Persistent, session-keyed worktree (shared across turns + agents; NOT torn
+      // down per turn — Phase 3 reaps it). Same as the opencode-server path so a
+      // chat that switches opencode↔goose↔qwen shares one worktree.
+      const { worktreeId, worktreePath, baseCommit } = await ensureSessionWorktree(sql, projectPath, sessionId, {
+        signal: ac.signal,
+      });
+      log.info({ taskId, worktreePath }, 'dispatcher: session worktree ready (warm ACP)');
+
+      const [assistantMsg] = await sql<{ id: string }[]>`
+        INSERT INTO messages (session_id, chat_id, role, content, status, created_at)
+        VALUES (${sessionId}, ${chatId}, 'assistant', '', 'streaming', clock_timestamp())
+        RETURNING id
+      `;
+      const assistantId = assistantMsg!.id;
+
+      broker.publishFrame(sessionId, {
+        type: 'message_started',
+        message_id: assistantId,
+        chat_id: chatId,
+        role: 'assistant',
+      } as WsFrame);
+
+      const manifestCommands = getManifestCommands(agent);
+      if (manifestCommands.length > 0) {
+        setTaskCommands(taskId, manifestCommands);
+        broker.publishFrame(sessionId, {
+          type: 'agent_commands',
+          task_id: taskId,
+          session_id: sessionId,
+          commands: manifestCommands,
+        } as WsFrame);
+      }
+
+      // Accumulate the turn's stream for persistence + the final message content.
+      const textChunks: string[] = [];
+      const reasoningChunks: string[] = [];
+      const toolSnaps = new Map<string, AcpToolSnapshot>();
+
+      // Map transport-agnostic AgentEvents → the SAME WS frames the one-shot ACP
+      // path emits (identical to runOpenCodeServerTask's onEvent). No dcp stripping:
+      // that's an opencode-plugin artifact; goose/qwen don't emit dcp tags.
+      const onEvent = (e: AgentEvent): void => {
+        switch (e.type) {
+          case 'text':
+            textChunks.push(e.text);
+            broker.publishFrame(sessionId, {
+              type: 'delta',
+              message_id: assistantId,
+              chat_id: chatId,
+              content: e.text,
+            } as WsFrame);
+            break;
+          case 'reasoning':
+            reasoningChunks.push(e.text);
+            broker.publishFrame(sessionId, {
+              type: 'reasoning_delta',
+              message_id: assistantId,
+              chat_id: chatId,
+              content: e.text,
+            } as WsFrame);
+            break;
+          case 'tool_call':
+          case 'tool_update':
+            toolSnaps.set(e.toolCall.toolCallId, e.toolCall);
+            broker.publishFrame(sessionId, {
+              type: 'tool_call',
+              message_id: assistantId,
+              chat_id: chatId,
+              tool_call: snapshotToWireToolCall(e.toolCall),
+            } as WsFrame);
+            break;
+          case 'commands':
+            if (e.commands.length > 0) {
+              setTaskCommands(taskId, e.commands);
+              broker.publishFrame(sessionId, {
+                type: 'agent_commands',
+                task_id: taskId,
+                session_id: sessionId,
+                commands: e.commands,
+              } as WsFrame);
+            }
+            break;
+        }
+      };
+
+      const model = task.model ?? undefined;
+      const backend = getWarmAcpBackend(chatId, agent, installPath);
+      const handle = await backend.ensureSession(sessionId, {
+        agent,
+        model: model ?? '',
+        chatId,
+        worktreePath,
+        worktreeId,
+        projectId: task.project_id,
+      });
+      const result = await backend.prompt(handle, task.input, {
+        worktreePath,
+        model: model ?? '',
+        signal: ac.signal,
+        onEvent,
+        taskId,
+        modeId: task.mode_id ?? undefined,
+      });
+      // Phase 3: keep the pooled (chat,agent) backend warm across the turn.
+      agentPool.touch(chatId, agent);
+
+      const assistantContent = textChunks.join('').slice(0, 50_000);
+      const reasoningText = reasoningChunks.join('').slice(0, 200_000);
+      const outputSummary = (result.ok ? textChunks.join('') : result.error ?? 'warm ACP turn failed').slice(0, 500);
+
+      await persistExternalAgentTurn(sql, assistantId, [...toolSnaps.values()], reasoningText);
+
+      await sql`
+        UPDATE messages
+        SET content = ${assistantContent}, status = 'complete', finished_at = clock_timestamp()
+        WHERE id = ${assistantId}
+      `;
+      broker.publishFrame(sessionId, {
+        type: 'message_complete',
+        message_id: assistantId,
+        chat_id: chatId,
+      } as WsFrame);
+
+      if (stopping) {
+        await sql`UPDATE tasks SET state = 'cancelled', ended_at = clock_timestamp() WHERE id = ${taskId}`;
+        return; // worktree persists (no cleanup); backend stays warm
+      }
+
+      // Diff the persistent worktree against its captured baseline and SUPERSEDE
+      // the session's prior pending row (latest-wins) — identical to opencode.
+      const diff = await diffWorktree(worktreePath, projectPath, {
+        signal: ac.signal,
+        baseRef: baseCommit ?? 'HEAD',
+      });
+      if (diff) {
+        await sql`
+          DELETE FROM pending_changes WHERE session_id = ${sessionId} AND status = 'pending'
+        `;
+        await sql`
+          INSERT INTO pending_changes (session_id, task_id, file_path, operation, diff, agent)
+          VALUES (${sessionId}, ${taskId}, ${projectPath}, 'edit', ${diff}, ${agent})
+        `;
+        log.info({ taskId, diffLength: diff.length }, 'dispatcher: diff superseded prior pending change (warm ACP)');
+      } else {
+        log.info({ taskId }, 'dispatcher: no changes detected in session worktree (warm ACP)');
+      }
+
+      // NO worktree cleanup — persistent (Phase 3 reaps it). Backend stays warm.
+
+      const [extCostRow] = await sql<{ total: number | null }[]>`
+        SELECT SUM(tokens_used)::int AS total
+        FROM messages
+        WHERE session_id = ${sessionId} AND tokens_used IS NOT NULL
+      `;
+      const extCostTokens = extCostRow?.total ?? null;
+
+      const finalState = result.ok ? 'completed' : 'failed';
+      await sql`
+        UPDATE tasks
+        SET state = ${finalState}, ended_at = clock_timestamp(), output_summary = ${outputSummary}, cost_tokens = ${extCostTokens}
+        WHERE id = ${taskId}
+      `;
+      log.info({ taskId, agent, finalState }, 'dispatcher: task finished (warm ACP)');
+      clearTaskCommands(taskId);
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      log.error({ taskId, agent, err: errMsg }, 'dispatcher: warm ACP error');
+      await sql`
+        UPDATE tasks
+        SET state = 'failed', ended_at = clock_timestamp(), output_summary = ${errMsg.slice(0, 500)}
+        WHERE id = ${taskId}
+      `.catch(() => {});
+      clearTaskCommands(taskId);
+      // No worktree cleanup (persistent); backend stays warm for the next turn.
+    }
+  }
+
   // ─── Helpers ────────────────────────────────────────────────────────────────
 
   async function waitForCompletion(assistantId: string): Promise<string> {

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

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

apps/coder/src/services/pending_changes.ts

@@ -13,6 +13,10 @@ export interface PendingChange {
   operation: 'create' | 'edit' | 'delete';
   diff: string;
   status: 'pending' | 'applied' | 'rejected' | 'reverted';
+  // v2.6 Phase 1-UX: which agent staged this change (DiffPanel attribution).
+  // Native boocode write tools stamp 'boocode'; the manual RightRail create path
+  // passes null (renders as "manual"). NULL on legacy rows queued pre-v2.6.
+  agent: string | null;
   created_at: string;
 }
 
@@ -34,13 +38,17 @@ export async function queueEdit(
   oldString: string,
   newString: string,
   projectRoot: string,
+  // v2.6 Phase 1-UX: attribution. Defaults to 'boocode' because the only callers
+  // that omit it are the native write tools (edit_file/create_file/delete_file).
+  // Pass null explicitly for the manual RightRail create path.
+  agent: string | null = 'boocode',
 ): Promise<PendingChange> {
   const resolved = resolveWritePath(projectRoot, filePath);
   const diff = JSON.stringify({ old: oldString, new: newString });
 
   const [row] = await sql<PendingChange[]>`
-    INSERT INTO pending_changes (session_id, task_id, file_path, operation, diff)
+    INSERT INTO pending_changes (session_id, task_id, file_path, operation, diff, agent)
-    VALUES (${sessionId}, ${taskId}, ${resolved}, 'edit', ${diff})
+    VALUES (${sessionId}, ${taskId}, ${resolved}, 'edit', ${diff}, ${agent})
     RETURNING *
   `;
   return row!;
@@ -53,12 +61,15 @@ export async function queueCreate(
   filePath: string,
   content: string,
   projectRoot: string,
+  // See queueEdit: defaults to 'boocode' for the native write tools; the manual
+  // RightRail create route passes null.
+  agent: string | null = 'boocode',
 ): Promise<PendingChange> {
   const resolved = resolveWritePath(projectRoot, filePath);
 
   const [row] = await sql<PendingChange[]>`
-    INSERT INTO pending_changes (session_id, task_id, file_path, operation, diff)
+    INSERT INTO pending_changes (session_id, task_id, file_path, operation, diff, agent)
-    VALUES (${sessionId}, ${taskId}, ${resolved}, 'create', ${content})
+    VALUES (${sessionId}, ${taskId}, ${resolved}, 'create', ${content}, ${agent})
     RETURNING *
   `;
   return row!;
@@ -70,12 +81,14 @@ export async function queueDelete(
   taskId: string | null,
   filePath: string,
   projectRoot: string,
+  // See queueEdit: defaults to 'boocode' for the native write tools.
+  agent: string | null = 'boocode',
 ): Promise<PendingChange> {
   const resolved = resolveWritePath(projectRoot, filePath);
 
   const [row] = await sql<PendingChange[]>`
-    INSERT INTO pending_changes (session_id, task_id, file_path, operation, diff)
+    INSERT INTO pending_changes (session_id, task_id, file_path, operation, diff, agent)
-    VALUES (${sessionId}, ${taskId}, ${resolved}, 'delete', '')
+    VALUES (${sessionId}, ${taskId}, ${resolved}, 'delete', '', ${agent})
     RETURNING *
   `;
   return row!;

apps/coder/src/services/worktrees.ts

@@ -9,7 +9,7 @@
 import type { Sql } from '../db.js';
 import { hostExec } from './host-exec.js';
 
-const WORKTREE_BASE = '/tmp/booworktrees';
+export const WORKTREE_BASE = '/tmp/booworktrees';
 
 /**
  * Create a git worktree for a task on the host.
@@ -197,6 +197,187 @@ export async function ensureSessionWorktree(
   };
 }
 
+/**
+ * v2.6 Phase 3 (3.3 / 3.4): physically remove a session's persistent worktree —
+ * the git worktree dir + its branch — and archive its `worktrees` row. Used by the
+ * chat/session-close hook (when the last chat in a session closes) and the orphan
+ * reaper. Best-effort on the git side (a dir already gone is not an error); the DB
+ * row is flipped to 'archived' (soft-delete, Paseo's worktree-archive pattern) so
+ * history/attribution survives and a re-run is idempotent.
+ *
+ * SAFETY: callers MUST run `checkWorktreeWorkAtRisk` first and skip at-risk
+ * worktrees — this function force-removes (`--force`), so it never silently drops
+ * uncommitted/unmerged work unless the caller already cleared/accepted the risk.
+ */
+export async function removeSessionWorktree(
+  sql: Sql,
+  projectPath: string,
+  worktree: { id: string; path: string; branch?: string | null },
+  opts?: { signal?: AbortSignal },
+): Promise<void> {
+  await hostExec(
+    `git -C ${shellEscape(projectPath)} worktree remove ${shellEscape(worktree.path)} --force`,
+    { signal: opts?.signal, timeoutMs: 15_000 },
+  ).catch(() => {});
+  const branch = worktree.branch ?? null;
+  if (branch) {
+    await hostExec(
+      `git -C ${shellEscape(projectPath)} branch -D ${shellEscape(branch)}`,
+      { signal: opts?.signal, timeoutMs: 10_000 },
+    ).catch(() => {});
+  }
+  // Prune any stale worktree administrative entries left behind by a partial remove.
+  await hostExec(
+    `git -C ${shellEscape(projectPath)} worktree prune`,
+    { signal: opts?.signal, timeoutMs: 10_000 },
+  ).catch(() => {});
+  await sql`UPDATE worktrees SET status = 'archived' WHERE id = ${worktree.id}`.catch(() => {});
+}
+
+/**
+ * v2.6 Phase 3 (3.3): the chat-close cleanup. Mark every `agent_sessions` row for
+ * the chat 'closed', then — only if this was the session's LAST open chat — remove
+ * the shared session worktree (a worktree is one-per-session, shared across the
+ * session's chat tabs, so closing one tab must not pull the rug from sibling tabs).
+ *
+ * Returns what it did so the route can report it. The actual backend (process /
+ * server-session) teardown is the pool's job (`agentPool.closeChat` +
+ * `backend.closeSession`); this owns the DB + git truth.
+ *
+ * `worktreeRemoved` is false when other open chats remain (worktree kept) OR when
+ * the worktree held work at risk (preflight blocked it — never silently dropped).
+ */
+export interface ChatCloseResult {
+  agentRowsClosed: number;
+  worktreeRemoved: boolean;
+  worktreeAtRisk: boolean;
+}
+
+export async function closeChatBackendState(
+  sql: Sql,
+  chatId: string,
+  opts?: { signal?: AbortSignal; force?: boolean },
+): Promise<ChatCloseResult> {
+  // Resolve the chat's session (and that session's project path) before we touch
+  // anything — a deleted chat row leaves agent_sessions/worktrees pointing nowhere.
+  const [chatRow] = await sql<{ session_id: string | null }[]>`
+    SELECT session_id FROM chats WHERE id = ${chatId}
+  `;
+  // chat row may already be gone (delete fired first); fall back to agent_sessions'
+  // session_id link, which SET NULLs only on session delete, not chat delete.
+  let sessionId = chatRow?.session_id ?? null;
+  if (!sessionId) {
+    const [as] = await sql<{ session_id: string | null }[]>`
+      SELECT session_id FROM agent_sessions WHERE chat_id = ${chatId} AND session_id IS NOT NULL LIMIT 1
+    `;
+    sessionId = as?.session_id ?? null;
+  }
+
+  // Mark this chat's (chat,agent) backend rows closed (idempotent).
+  const closedRows = await sql<{ agent: string }[]>`
+    UPDATE agent_sessions SET status = 'closed'
+    WHERE chat_id = ${chatId} AND status <> 'closed'
+    RETURNING agent
+  `;
+
+  let worktreeRemoved = false;
+  let worktreeAtRisk = false;
+
+  if (sessionId) {
+    // Other open chats still sharing the session worktree? If so, keep it.
+    const openRows = await sql<{ open_count: number }[]>`
+      SELECT COUNT(*)::int AS open_count FROM chats
+      WHERE session_id = ${sessionId} AND status = 'open' AND id <> ${chatId}
+    `;
+    const openCount = openRows[0]?.open_count ?? 0;
+    if (openCount === 0) {
+      const [wt] = await sql<{ id: string; path: string; branch: string | null }[]>`
+        SELECT id, path, branch FROM worktrees
+        WHERE session_id = ${sessionId} AND status = 'active' LIMIT 1
+      `;
+      if (wt) {
+        const projRows = await sql<{ path: string | null }[]>`
+          SELECT p.path FROM sessions s JOIN projects p ON p.id = s.project_id WHERE s.id = ${sessionId}
+        `;
+        const projectPath = projRows[0]?.path ?? null;
+        // Preflight (close-hook semantics): a DELIBERATE chat/session close — the
+        // server's session-delete already ran the full work-at-risk gate
+        // (dirty/unpushed/unmerged) before calling us, and chat-close discards the
+        // tab's staged review intentionally. So here we only block on UNCOMMITTED
+        // working-tree changes (`dirty`) — work the user never even staged into the
+        // review diff. The session branch's own commits (the diff-staging
+        // mechanism) are NOT a block; treating them as "unmerged risk" would make
+        // the worktree un-removable on every real session (the orphan reaper keeps
+        // the full at-risk gate because it runs unattended). `force` skips this.
+        if (!opts?.force) {
+          const risk = await checkWorktreeWorkAtRisk(wt.path, opts);
+          worktreeAtRisk = risk.dirty || risk.error != null;
+        }
+        if (projectPath && (opts?.force || !worktreeAtRisk)) {
+          await removeSessionWorktree(sql, projectPath, wt, opts);
+          worktreeRemoved = true;
+        }
+      }
+    }
+  }
+
+  return { agentRowsClosed: closedRows.length, worktreeRemoved, worktreeAtRisk };
+}
+
+/**
+ * v2.6 Phase 3 (3.5): re-baseline a session's worktree diff after a successful
+ * `apply_pending`. The applied changes were written to the PROJECT ROOT; the
+ * worktree branch still holds the same delta against the ORIGINAL `base_commit`,
+ * so the next turn's `diffWorktree(base_commit...worktree-HEAD)` would re-surface
+ * the already-applied changes as "pending" — a confusing double-count.
+ *
+ * Fix: advance the stored `base_commit` to the worktree's CURRENT HEAD (the
+ * `diffWorktree` path commits the worktree's accumulated changes before diffing,
+ * so HEAD already encodes the applied state). The next turn then diffs against
+ * that, surfacing only edits made AFTER the apply. Idempotent: if the worktree has
+ * no new commits, the base is unchanged.
+ *
+ * Diff-baseline-correctness note (design §7): we re-baseline to the worktree's own
+ * HEAD, NOT to a moving project HEAD — so an out-of-band edit to the project root
+ * after apply doesn't corrupt the baseline. The trade-off is that a manual project
+ * edit isn't reflected as "already there"; acceptable, and matches the stored-base
+ * (not moving-target) decision in §7.
+ */
+export async function rebaselineWorktreeAfterApply(
+  sql: Sql,
+  sessionId: string,
+  opts?: { signal?: AbortSignal },
+): Promise<{ rebaselined: boolean; newBaseCommit: string | null }> {
+  const [wt] = await sql<{ id: string; path: string; base_commit: string | null }[]>`
+    SELECT id, path, base_commit FROM worktrees
+    WHERE session_id = ${sessionId} AND status = 'active' LIMIT 1
+  `;
+  if (!wt) return { rebaselined: false, newBaseCommit: null };
+
+  // Make sure the worktree's accumulated edits are committed so HEAD encodes the
+  // just-applied state (the diff path normally does this, but apply may run with no
+  // prior diff this turn). Commit ONLY when something is staged — NO --allow-empty,
+  // so a re-baseline with no new edits doesn't advance HEAD and stays idempotent.
+  await hostExec(
+    `cd ${shellEscape(wt.path)} && git add -A && ` +
+      `git diff --cached --quiet || ` +
+      `git -c user.email=boocoder@local -c user.name=BooCoder commit -q -m "rebaseline after apply"`,
+    { signal: opts?.signal, timeoutMs: 15_000 },
+  ).catch(() => {});
+
+  const headRes = await hostExec(
+    `git -C ${shellEscape(wt.path)} rev-parse HEAD`,
+    { signal: opts?.signal, timeoutMs: 10_000 },
+  ).catch(() => null);
+  const newBase = headRes && headRes.exitCode === 0 ? headRes.stdout.trim() || null : null;
+  if (!newBase || newBase === wt.base_commit) {
+    return { rebaselined: false, newBaseCommit: wt.base_commit };
+  }
+
+  await sql`UPDATE worktrees SET base_commit = ${newBase} WHERE id = ${wt.id}`;
+  return { rebaselined: true, newBaseCommit: newBase };
+}
+
 // ─── Session-delete work-loss guard ─────────────────────────────────────────
 
 /**

apps/web/src/api/client.ts

@@ -25,6 +25,17 @@ import type {
   WorkspaceState,
 } from './types';
 
+// v2.6 Phase 1-UX §9b: chat-scoped agent-session rows. Returned by
+// GET /api/coder/sessions/:id/agent-sessions; drives the AgentComposerBar
+// resumed/new-session chip via useAgentSessions. `has_session` is true when a
+// resumable backend session id exists for that agent in the chat.
+export interface AgentSessionInfo {
+  agent: string;
+  status: string;
+  has_session: boolean;
+  last_active_at: string | null;
+}
+
 export class ApiError extends Error {
   constructor(
     public status: number,
@@ -363,6 +374,11 @@ export const api = {
       request<CoderMessageWire[]>(
         `/api/coder/sessions/${sessionId}/messages${chatId ? `?chat_id=${encodeURIComponent(chatId)}` : ''}`,
       ),
+    // v2.6 Phase 1-UX §9b: per-(chat,agent) backend-session state for the
+    // resumed/new-session chip. Chat-scoped (NOT foldable into the project-level
+    // provider snapshot). Proxied to boocoder at /api/sessions/:id/agent-sessions.
+    agentSessions: (sessionId: string) =>
+      request<AgentSessionInfo[]>(`/api/coder/sessions/${sessionId}/agent-sessions`),
     skillInvoke: (
       sessionId: string,
       paneId: string,

apps/web/src/components/AgentComposerBar.tsx

@@ -1,9 +1,10 @@
 import { useEffect, useMemo, useRef, useState } from 'react';
-import { Check, ChevronDown, RefreshCw, Loader2, Shield, Brain, Bird, Bot, Dog, Terminal as TermIcon } from 'lucide-react';
+import { Check, ChevronDown, RefreshCw, Loader2, Shield, Brain, Bot } from 'lucide-react';
-import { ClaudeIcon, OpenCodeIcon } from '@/components/icons/ProviderIcons';
 import { api } from '@/api/client';
 import type { AgentSessionConfig, ProviderSnapshotEntry, AgentCommand } from '@/api/types';
 import { useProviderSnapshot, refreshProviderSnapshot } from '@/hooks/useProviderSnapshot';
+import { providerIcon } from '@/components/coder/providerIcons';
+import { useAgentSessions } from '@/hooks/useAgentSessions';
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -172,9 +173,36 @@ interface Props {
   onChange: (next: AgentSessionConfig) => void;
   onProviderCommandsChange?: (commands: AgentCommand[]) => void;
   connected?: boolean;
+  // v2.6 Phase 1-UX §9b: chat id for the resumed/new-session chip. Optional so
+  // BooChat and any other AgentComposerBar caller renders no chip and is
+  // otherwise unaffected. When present + connected + the chat has ≥1 prior
+  // turn, a chip right of the Provider picker reports whether switching to the
+  // current provider resumes an agent session, replays history (boocode), or
+  // starts fresh.
+  sessionId?: string;
+  // True once the chat has at least one prior turn — gates the chip so it stays
+  // hidden on a brand-new chat. Defaults to false (no chip).
+  hasPriorTurn?: boolean;
 }
 
-export function AgentComposerBar({ projectPath, value, onChange, onProviderCommandsChange, connected }: Props) {
+// Relative-time formatter for the resumed-chip title (e.g. "3m ago").
+function relativeTime(iso: string | null): string {
+  if (!iso) return 'unknown';
+  const then = new Date(iso).getTime();
+  if (Number.isNaN(then)) return 'unknown';
+  const diffMs = Date.now() - then;
+  if (diffMs < 0) return 'just now';
+  const sec = Math.floor(diffMs / 1000);
+  if (sec < 60) return 'just now';
+  const min = Math.floor(sec / 60);
+  if (min < 60) return `${min}m ago`;
+  const hr = Math.floor(min / 60);
+  if (hr < 24) return `${hr}h ago`;
+  const day = Math.floor(hr / 24);
+  return `${day}d ago`;
+}
+
+export function AgentComposerBar({ projectPath, value, onChange, onProviderCommandsChange, connected, sessionId, hasPriorTurn }: Props) {
   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
@@ -186,6 +214,13 @@ 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(() => {
@@ -294,21 +329,30 @@ export function AgentComposerBar({ projectPath, value, onChange, onProviderComma
     );
   }
 
-  const providerIcon = (name: string) => {
-    switch (name) {
-      case 'claude': return <ClaudeIcon size={13} className="shrink-0" />;
-      case 'opencode': return <OpenCodeIcon size={13} className="shrink-0" />;
-      case 'goose': return <Bird size={13} className="shrink-0" />;
-      case 'qwen': return <TermIcon size={13} className="shrink-0" />;
-      default: return <Dog size={13} className="shrink-0" />;
-    }
-  };
-
   const providerOptions = entries.map((e) => ({ id: e.name, label: e.label }));
   const modeOptions = (currentEntry?.modes ?? []).map((m) => ({ id: m.id, label: m.label }));
   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;
+
   return (
     <div className="flex flex-wrap items-center gap-1 px-2 py-1 border-b border-border bg-muted/20 shrink-0">
       <CompactPicker
@@ -322,6 +366,14 @@ 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>
+      )}
       <CompactPicker
         label="Mode"
         value={value.modeId ?? ''}

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

@@ -0,0 +1,56 @@
+// Shared provider icon + label helpers for BooCoder UI.
+//
+// Single source of truth for the per-provider glyph used in the
+// AgentComposerBar picker and the CoderPane DiffPanel agent-attribution
+// badges (v2.6 Phase 1-UX §9a/§9b). Extracted from AgentComposerBar's local
+// `providerIcon` switch so both call sites stay in sync.
+
+import type { ReactNode } from 'react';
+import { Bird, Dog, Terminal as TermIcon } from 'lucide-react';
+import { ClaudeIcon, OpenCodeIcon } from '@/components/icons/ProviderIcons';
+
+/**
+ * Glyph for a provider/agent name. Mirrors AgentComposerBar's original
+ * `providerIcon` switch verbatim — `boocode` (native) falls through to the
+ * neutral dog like any unmapped name, preserving the composer's prior look.
+ * Sized to match the picker (13px) by default; pass a different size for
+ * inline badges.
+ */
+export function providerIcon(name: string | null, size = 13): ReactNode {
+  switch (name) {
+    case 'claude':
+      return <ClaudeIcon size={size} className="shrink-0" />;
+    case 'opencode':
+      return <OpenCodeIcon size={size} className="shrink-0" />;
+    case 'goose':
+      return <Bird size={size} className="shrink-0" />;
+    case 'qwen':
+      return <TermIcon size={size} className="shrink-0" />;
+    default:
+      return <Dog size={size} className="shrink-0" />;
+  }
+}
+
+/**
+ * Human label for a provider/agent name. `null` → "manual" (a RightRail-staged
+ * change with no dispatching agent, per §9a). Unknown names pass through
+ * verbatim so a future provider still reads sensibly.
+ */
+export function providerLabel(name: string | null): string {
+  switch (name) {
+    case null:
+      return 'manual';
+    case 'boocode':
+      return 'BooCode';
+    case 'opencode':
+      return 'opencode';
+    case 'claude':
+      return 'Claude';
+    case 'goose':
+      return 'goose';
+    case 'qwen':
+      return 'Qwen';
+    default:
+      return name;
+  }
+}

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

@@ -16,6 +16,8 @@ import { toast } from 'sonner';
 import { isSlashCommandToken, mergeCommandsByName, parseSlashInput, slashQuery } from '@/lib/slash-command';
 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 { cn } from '@/lib/utils';
 
 // ---------------------------------------------------------------------------
@@ -56,6 +58,10 @@ interface PendingChange {
   diff?: string;
   new_content?: string;
   status: 'pending' | 'approved' | 'rejected';
+  // v2.6 Phase 1-UX §9a: which agent staged this change. 'boocode' for native
+  // write tools, the dispatched agent for worktree edits, null for a manual
+  // RightRail-staged create (renders as a neutral "manual" badge).
+  agent: string | null;
 }
 
 interface Props {
@@ -394,6 +400,15 @@ function DiffPanel({
 }) {
   const pending = changes.filter((c) => c.status === 'pending');
 
+  // v2.6 Phase 1-UX §9a: when pending changes span >1 distinct agent, surface a
+  // one-line "Changes from <a>, <b>" note so mixed provenance is obvious. Null
+  // (manual) counts as its own bucket and renders as "manual".
+  const distinctAgents = Array.from(new Set(pending.map((c) => c.agent)));
+  const mixedNote =
+    distinctAgents.length > 1
+      ? `Changes from ${distinctAgents.map((a) => providerLabel(a)).join(', ')}`
+      : null;
+
   return (
     <div className="flex flex-col h-full border-t border-border">
       <div className="flex items-center justify-between px-3 py-1.5 border-b border-border bg-muted/30">
@@ -410,6 +425,11 @@ function DiffPanel({
           <RefreshCw size={12} className={loading ? 'animate-spin' : ''} />
         </button>
       </div>
+      {mixedNote && (
+        <div className="px-3 py-1 border-b border-border bg-muted/10 text-[11px] text-muted-foreground truncate">
+          {mixedNote}
+        </div>
+      )}
       <div className="flex-1 overflow-y-auto">
         {pending.length === 0 ? (
           <div className="flex items-center justify-center h-full text-sm text-muted-foreground">
@@ -420,14 +440,25 @@ function DiffPanel({
             {pending.map((change) => (
               <div key={change.id} className="px-3 py-2">
                 <div className="flex items-center justify-between mb-1">
-                  <span className="text-xs font-mono text-foreground truncate flex-1 mr-2">
+                  <span className="text-xs font-mono text-foreground truncate flex-1 mr-2 inline-flex items-center min-w-0">
+                    <span
+                      className="inline-flex items-center gap-1 rounded border border-border bg-muted/40 px-1 py-px mr-1.5 text-[10px] font-medium text-muted-foreground shrink-0"
+                      title={
+                        change.agent === null
+                          ? 'Manually staged (no dispatching agent)'
+                          : `Staged by ${providerLabel(change.agent)}`
+                      }
+                    >
+                      {providerIcon(change.agent, 11)}
+                      <span>{providerLabel(change.agent)}</span>
+                    </span>
                     <span className={cn(
-                      'inline-block w-1.5 h-1.5 rounded-full mr-1.5',
+                      'inline-block w-1.5 h-1.5 rounded-full mr-1.5 shrink-0',
                       change.operation === 'create' && 'bg-green-500',
                       change.operation === 'modify' && 'bg-yellow-500',
                       change.operation === 'delete' && 'bg-red-500',
                     )} />
-                    {change.file_path}
+                    <span className="truncate">{change.file_path}</span>
                   </span>
                   <div className="flex items-center gap-1 shrink-0">
                     <button
@@ -586,15 +617,24 @@ export function CoderPane({
   // dispatch returns — so queueing/stop must key on this combined signal.
   const generating = sending || activeTaskId !== null;
 
-  // Refresh pending changes when a message_complete arrives
+  // Refresh pending changes (and agent-session state for the §9b chip) when a
+  // message_complete arrives — same trigger usePendingChanges already uses.
   useEffect(() => {
     const lastAssistant = [...messages].reverse().find(
       (m): m is CoderMessage => m.role === 'assistant',
     );
     if (lastAssistant?.status === 'complete') {
       refresh();
+      void refreshAgentSessions(sessionId);
     }
-  }, [messages, refresh]);
+  }, [messages, refresh, 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(() => {
@@ -834,6 +874,8 @@ export function CoderPane({
         onChange={setAgentConfig}
         onProviderCommandsChange={handleProviderCommandsChange}
         connected={connected}
+        sessionId={sessionId}
+        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/useAgentSessions.ts

@@ -0,0 +1,88 @@
+// v2.6 Phase 1-UX §9b — chat-scoped agent-session state.
+//
+// Reads GET /api/coder/sessions/:id/agent-sessions (the per-(chat,agent)
+// backend-session rows) and drives the AgentComposerBar resumed/new-session
+// chip. Module-singleton external store keyed by sessionId — same shape as
+// useProviderSnapshot — so the two consumers (CoderPane, which owns the
+// message_complete WS signal, and AgentComposerBar, which renders the chip)
+// share one cache and one fetch per chat. CoderPane calls
+// refreshAgentSessions(sessionId) on each message_complete (the same trigger
+// usePendingChanges already keys off); the chip then reflects the freshly
+// resumed/created session.
+
+import { useEffect, useSyncExternalStore } from 'react';
+import { api, type AgentSessionInfo } from '@/api/client';
+
+type Entry = {
+  data: AgentSessionInfo[];
+  inflight: Promise<AgentSessionInfo[]> | null;
+};
+
+const store = new Map<string, Entry>();
+const listeners = new Set<() => void>();
+const EMPTY: AgentSessionInfo[] = [];
+
+function notify(): void {
+  for (const fn of listeners) fn();
+}
+
+function subscribe(fn: () => void): () => void {
+  listeners.add(fn);
+  return () => listeners.delete(fn);
+}
+
+function getEntry(sessionId: string): Entry {
+  let entry = store.get(sessionId);
+  if (!entry) {
+    entry = { data: EMPTY, inflight: null };
+    store.set(sessionId, entry);
+  }
+  return entry;
+}
+
+async function doFetch(sessionId: string): Promise<AgentSessionInfo[]> {
+  const data = await api.coder.agentSessions(sessionId);
+  const entry = getEntry(sessionId);
+  entry.data = data;
+  entry.inflight = null;
+  notify();
+  return data;
+}
+
+function ensureLoaded(sessionId: string): void {
+  const entry = getEntry(sessionId);
+  if (entry.data !== EMPTY || entry.inflight) return;
+  entry.inflight = doFetch(sessionId).catch(() => {
+    // boocoder may be down or the chat has no agent-session rows yet; treat as
+    // empty (the chip falls back to "new session" / hides).
+    const e = getEntry(sessionId);
+    e.inflight = null;
+    return EMPTY;
+  });
+}
+
+/** Force a refetch for one chat. Wired to message_complete by CoderPane. */
+export function refreshAgentSessions(sessionId: string): Promise<AgentSessionInfo[]> {
+  const entry = getEntry(sessionId);
+  entry.inflight = null;
+  return doFetch(sessionId);
+}
+
+/**
+ * Chat-scoped agent-session rows. Pass `undefined` to opt out (no fetch, empty
+ * result) — AgentComposerBar does this for BooChat callers and fresh chats so
+ * the chip stays hidden. Fetches on mount (and on sessionId change); refetch on
+ * message_complete is driven externally via refreshAgentSessions.
+ */
+export function useAgentSessions(sessionId: string | undefined): {
+  sessions: AgentSessionInfo[];
+} {
+  const sessions = useSyncExternalStore(
+    subscribe,
+    () => (sessionId ? getEntry(sessionId).data : EMPTY),
+  );
+  useEffect(() => {
+    if (sessionId) ensureLoaded(sessionId);
+  }, [sessionId]);
+  return { sessions: sessionId ? sessions : EMPTY };
+}

boocode_code_review_v2.md

@@ -0,0 +1,253 @@
+# BooCode — External Code Review v2 (lift findings)
+
+Last updated: 2026-05-31
+
+**Synced through `v2.6.6-claude-md` (HEAD, 2026-05-31).** The **AGPL-3.0 → MIT relicense decision** (remove all **3** AGPL-derived files) and the **jinja-gate-green** resolution are folded in below — they **supersede this doc's earlier "AGPL confirmed, recommendation stands" / two-file framing.** Canonical plan: the roadmap's `## License-debt — relicense AGPL-3.0 → MIT (planned)` batch.
+
+A point-in-time **findings** doc, not a standing inventory. It consolidates two reconnaissance passes against the upstream forks at `/opt/forks/` and decides, per area, what BooCode should do about it. Pin it so the same upstreams aren't re-evaluated from scratch next month.
+
+> **Companion docs:** `boocode_code_review.md` is the standing external-repo inventory (every repo BooCode references, *why* each earned its row, license analysis). `boocode_roadmap.md` is the canonical shipping-state / version-ordering source. This v2 doc is the **action layer** on top of both: "given what's upstream as of 2026-05-31, here's the lift/cross-check/re-derive/n-a call." Reconcile shipping state via the roadmap when in doubt; fold durable rows back into `boocode_code_review.md`.
+
+## Sources feeding this doc
+
+1. **Paseo recon (Sam)** — two passes: a Phase 2/3 server-manager recon and a claude-transport recon. Conclusions consolidated by area below (§2a). AGPL-3.0 — **pattern-only, no code lift, ever.**
+2. **Three-fork agent sweep (this session, 2026-05-31)** — read-only general-purpose agents over `anomalyco/opencode` (MIT, code-liftable), `getpaseo/paseo` (AGPL, pattern-only), `ggml-org/llama.cpp` (consumed via llama-swap/sidecar — adopt features/flags, not C++). Detail in §2–§4.
+3. **Second fork sweep (this session, 2026-05-31)** — 8 read-only agents over the remaining 11 repos in `/opt/forks/` (conductor, superset, openchamber, happy, cline, qwen-code, amp-acp, pi-acp, claude-code, goose, unsloth). Detail in §5; high-value items folded into §1.
+
+### Caveats
+- `/opt/forks/llama.cpp` is a **shallow clone** (90 commits, ~5 days visible). llama.cpp findings are read from source as it stands today; "what changed when" attribution is limited. `git fetch --unshallow` before the next review.
+- `/opt/forks/opencode` arrived shallow (rooted 2026-05-25); the agent ran `git fetch --unshallow` and re-surveyed the real 6-week window. opencode also did a v2 Effect/event-sourced rewrite (`packages/core/`, `packages/llm/`) — most of that churn is architecturally divergent and ruled out.
+- HEADs at review time: paseo `41cb1af` (main, v0.1.87), opencode `1afa9e3` (dev, ~v1.15.13), llama.cpp `aa46bda8` (detached).
+
+## Verdict legend
+
+| Verdict | Meaning |
+|---|---|
+| **LIFT** | Take it. Flavor noted: *code-lift* (MIT), *pattern-lift* (AGPL/clean-room re-impl), *config-adopt* (new upstream flag), *drop-our-code* (upstream now does it → delete ours). |
+| **RE-DERIVE** | Idea is right, their impl is insufficient/divergent for our needs — write fresh, don't adapt theirs. |
+| **CROSS-CHECK** | We already have it; confirmed current vs upstream. No action. |
+| **TRACK** | Behavioral/external change to be aware of. No code action now. |
+| **N-A** | Not liftable into our architecture, or reduces to a separate decision. |
+
+-----
+
+## 1. Net actionables (priority roll-up)
+
+Updated after the **second fork sweep** (2026-05-31, §5). New items from that sweep are tagged ⁺.
+
+| # | Item | Source | Verdict | Maps to | Effort |
+|---|------|--------|---------|---------|--------|
+| 1 | **Relicense AGPL-3.0 → MIT — remove all 3 AGPL files** (`tool-call-parser.ts`, `html-to-md.ts`, `llama-args-validator.ts`). llama-server now parses qwen3.x tool calls server-side (**jinja gate green, §6.1**) → parser goes; html-to-md → permissive lib; llama-args-validator → clean-room; then flip `LICENSE` + 5 `package.json` + headers + prose. **The tree is currently AGPL-3.0.** | llama.cpp + unsloth⁺ | LIFT · drop-our-code (relicense) | License-debt batch (roadmap) | M, staged |
+| 2 | **Warm-ACP backend (goose/qwen)** — one spawn, one `session/new`, many prompts; **validated by qwen's own `qwen --acp` reference impl** (the "qwen ACP was HTTP-only" premise is stale) | Paseo recon + qwen-code⁺ | LIFT · pattern | **v2.6 Phase 2** | M |
+| 3 ⁺ | **Fuzzy patch applier for `edit_file`** — exact→whitespace→Levenshtein match ladder + unicode canon + multi-occurrence guard; BooCoder's `edit_file` is exact-`.includes`-or-throw today | cline⁺ | LIFT · code | edit/diff robustness (local-model drift) | M |
+| 4 ⁺ | **`git stash create` + private-ref checkpoint** — per-turn workspace snapshot capturing **all** state incl. external-agent edits (BooCode `rewind` only undoes its own queued edits) | cline⁺ | LIFT · code | checkpoint/restore UX | M |
+| 5 ⁺ | **opencode lifecycle hardening** — health monitor + crash auto-restart + busy-aware restart + port reclaim + stall-detecting SSE; **MIT, same warm-server architecture** (supersedes the paseo RE-DERIVE — better source) | openchamber⁺ | LIFT · pattern/code | **v2.6 Phase 3** | M |
+| 6 | **Post-interrupt stale-terminal guard** — confirmed correctness bug in `opencode-server.ts`; **now more user-reachable** since `v2.6.5` shipped the Send→Stop composer (`cancelTask`) → abort path is one click | opencode/paseo (verified) | LIFT · pattern (bugfix) | v2.6 Phase 1/2 | S (~½ day) |
+| 7 ⁺ | **Parse qwen/claude `stream-json` NDJSON in PTY fallback** — today stdout is sliced opaque; one parser serves both (Claude-Code-compatible schema) | qwen-code⁺ | LIFT · pattern | v2.6 Phase 2 / dispatch parsing | S |
+| 8 | **ctx/token usage for opencode sessions** — `session.next.step.ended` already on the wire | opencode + paseo (converged) | LIFT · code | v2.6 Phase 1 UX | S–M (~80–150 LoC) |
+| 9 | **Claude continuity + transport** — adopt `@anthropic-ai/claude-agent-sdk`; resume via the SDK's **native `SessionStore`** (`0.3.x`) keyed `(chat_id,agent)`, not happy's hook/jsonl-watcher (predates it). SDK is commercial-terms → runtime dep OK, code reference-only | happy⁺ + SDK `.d.ts`⁺ | LIFT · code + decision | claude-provider batch | M |
+| 10 ⁺ | **Universal-agent notify-hook → normalized status** — inject a hook into each PTY agent's config, normalize ~30 event names → 5 states; gives goose/qwen/claude real working/blocked/done signals | superset⁺ (clean-room, ELv2) | RE-DERIVE | v2.6 Phase 2/3 status | M–H |
+| 11 | **New sampling knobs** `top_n_sigma`, `dry_*` family; **`--reasoning-budget`** | llama.cpp | LIFT · config-adopt | AGENTS.md frontmatter + validator allowlist | S |
+| 12 ⁺ | **File-provenance compaction ledger** (`## Files Read/Modified`) + **`MistakeTracker`** (heterogeneous-failure recovery) | cline⁺ | LIFT · pattern | context-mgmt / recovery | S–M |
+| 13 | Bundle/watch: stall-timeout + retry/backoff (opencode); worktree-archive cascade (paseo); LRU-bound caches; subagent permission demux; tool-pair-atomic prune cross-check (cline)⁺; diff-line→agent re-prompt (superset)⁺ | mixed | WATCH | Phase 2/3, review UX, resilience | varies |
+
+**Headline:** #1 is the strategic win and is now a **committed decision: relicense AGPL-3.0 → MIT** (the tree is *currently* AGPL — `LICENSE` + all 5 `package.json` are `AGPL-3.0-only`). Scope is **3 AGPL-derived files**, not 2 — this doc's earlier count missed `llama-args-validator.ts` (corrected in §5k). The jinja gate is **green** (§6.1), so it's actionable now. The second sweep added four genuinely-new code lifts: **#3 fuzzy patch applier** and **#4 git-stash checkpoint** (both cline, both directly fix where BooCoder's write/edit surface is weakest for local models), **#5 openchamber lifecycle hardening** (the concrete, MIT, same-architecture answer to v2.6 Phase 3 — supersedes the weaker paseo re-derive), and **#7 stream-json parsing** (cheap, shared by qwen+claude PTY). #2 Phase-2 warm-ACP is now de-risked by qwen's own reference impl. #9 resolves the claude direction (lean SDK).
+
+-----
+
+## 2. Paseo (AGPL-3.0 — pattern-only)
+
+### 2a. Consolidated recon, by area (Sam's two passes)
+
+| Area | Verdict | One-line |
+|------|---------|----------|
+| OpenCode server lifecycle | **CROSS-CHECK** | Paseo hand-rolls the spawn (not `createOpencodeServer`), waits for "listening on" on stdout, port-0 allocation, concurrent callers wait on one `startPromise`, no `OPENCODE_SERVER_PASSWORD`. Same shape BooCode shipped in v2.6.1 — nothing to lift. |
+| OpenCode crash recovery + reconnect | **RE-DERIVE → superseded** | Lazy restart-on-demand (exit handler nulls the server, next `getCurrentServer()` respawns), no active supervision; `resumeSession` does **not** verify the session exists on disk before resuming. Insufficient for Phase 3. **Update (2nd sweep):** `openchamber` (§5c) has a *better, MIT, same-architecture* version — health-monitor state machine + crash auto-restart + busy-aware restart. Lift from openchamber, not paseo. |
+| Warm-ACP supervision (goose/qwen) | **LIFT · pattern** | `SpawnedACPProcess`: one spawn, one `session/new`, many prompts; child lives for the session not the turn; per-turn abort = `connection.cancel({sessionId})` **without killing the child**; child-exit fires `turn_failed` (no restart). Clean signal split; integrates against BooCode's existing `acp-dispatch.ts`. **This is the Phase 2 lift — and qwen-code (§5f) ships its own `qwen --acp` reference impl that validates the whole approach.** |
+| OpenCode reasoning dedup | **CROSS-CHECK** | `streamedPartKeys` keyed `reasoning:${partID}`; delta adds the key, final part skips if present, cleared per turn. Identical to v2.6.1. |
+| Claude transport | **N-A** | Paseo uses `@anthropic-ai/claude-agent-sdk` in stream-json mode, not PTY. Getting Paseo's transport means adopting the SDK — net-new integration, not a lift. |
+| Claude continuity | **LIFT · code** | `claude --resume <sessionId>` across turns: capture the session id from claude's output, store it, pass `--resume` next turn; claude re-reads its transcript and continues. Small change to BooCode's PTY dispatch (run with `--output-format stream-json`, parse the id, persist, resume). **The actionable claude finding.** |
+| Claude streaming/parsing | **N-A** | Structured events (tool calls, reasoning, partials) come from the SDK; PTY degrades to scraping. Adopting structured claude streaming = adopting the SDK — separate decision. |
+| Claude session persistence | **CROSS-CHECK** | Same `describePersistence`/`resumeSession` shape BooCode already has for opencode; claude slots in. Neither Paseo nor BooCode verifies the transcript exists on disk before resume (**shared open question** — see §5). |
+
+**Recon's net:** LIFT = warm-ACP supervision (Phase 2) + claude `--resume` continuity (standalone batch). RE-DERIVE = OpenCode crash recovery (Phase 3). Everything else cross-check or n/a. The two n/a claude items both reduce to **one deferred decision: adopt `@anthropic-ai/claude-agent-sdk` or stay PTY.**
+
+### 2b. Additional findings (this session's Paseo agent sweep)
+
+These came from the broader agent pass, not the targeted Phase 2/3 recon. Where they touch the same code as §2a, the §2a recon is authoritative.
+
+| Finding | Verdict | Notes |
+|---------|---------|-------|
+| **Post-interrupt stale-terminal suppression** (paseo `1d38aac`) | **LIFT · pattern (bugfix)** | See §3 #3 — verified to be a live bug in BooCode. Highest-confidence paseo item. |
+| **Provider-agnostic `AgentUsage`** normalized usage/cost frame | **LIFT · pattern** | Converges with opencode's `session.next.step.ended` (§3 #4). Paseo's `{inputTokens, cachedInputTokens, outputTokens, totalCostUsd, contextWindowMax/Used}` is the target *shape* for normalizing across providers; do the opencode slice first. |
+| **Worktree-archive → cascade-archive agents + schedule cleanup** (paseo `b6103a5`) | **WATCH → adopt in Phase 3** | Soft-delete (keep `archivedAt`), single archive event fans out to children + downstream rows, `Promise.allSettled` so one failed delete doesn't abandon the rest. Right shape for the v2.6 Phase 3 worktree reaper. |
+| **Server retire/refcount + LRU-bound caches** (paseo `server-manager.ts`, leak-fix `f20393d`) | **WATCH** (low confidence) | The agent read a retire-set/refcount mechanism; the §2a server-manager recon concluded "nothing to lift." Treat the *lifecycle* as cross-check (§2a wins). The one durable takeaway: **bound the per-session/per-worktree Maps in the warm opencode server** (long-lived daemon → unbounded caches leak). Confirm against §2a before acting. |
+| **Subagent permission forwarding** (paseo `44863ec`) | **WATCH (gated)** | opencode `task` tool spawns child sessions; forward `permission.asked` from tracked children by `parentID` demux. **Blocked:** BooCode's opencode-SSE path has zero permission handling today (runs auto-approve). Reachable only after BooCoder builds opencode-SSE permission cards at all. Ties to v2.4. |
+
+-----
+
+## 3. OpenCode (MIT — code-liftable)
+
+| # | Finding | Evidence | Verdict | Notes |
+|---|---------|----------|---------|-------|
+| 1 | **Consume the fuller `session.next.*` event set** in `opencode-server.ts` | `packages/core/src/session/event.ts:105-365`; BooCode handles only ~5 arms (`opencode-server.ts:215-311`) | **LIFT · code** | Events already in the **installed** `@opencode-ai/sdk` — **no dep bump.** High-value arms: **`step.ended`** (`{tokens{input,output,reasoning,cache},cost}` → #4 below); **`compaction.{started,delta,ended}`** (warm server auto-compacts mid-conversation; today shows as a silent context gap); `tool.progress`, `tool.input.{started,delta}`, `retried`, `step.failed`. |
+| 4 | **ctx/token usage for opencode** (the high-value slice of #1) | `event.ts:117-135` | **LIFT · code** | Closes the roadmap-named gap: *"opencode/goose/qwen/claude dispatch with no ctx/token usage; only native boocode tracks ctx."* Mirror BooChat's existing `'usage'` WS frame on the coder side; accumulate per `(chat, agent)`. Converges with paseo `AgentUsage` (§2b). |
+| 2 | **Stalled-stream chunk-timeout** (`wrapSSE` + header timeout) | `provider/provider.ts:40-96` (`f965db9`, `c7e1fc5`) | **WATCH · pattern** | BooChat's `stream-phase.ts` has **no server-side stall timeout** — a hung llama-swap stream relies entirely on the frontend 60s `discard_stale` watchdog. ~40-60 LoC to wrap the `fullStream` loop with a per-chunk timeout firing the existing abort path. Low incidence on a single local instance; do it if stuck rows recur. |
+| 3 | **Retry-with-backoff + retryability classifier** (`session/retry.ts`) | `session/retry.ts`, `message-v2.ts:1155` (`14e0b9b`) | **WATCH · pattern** | BooChat has **zero** retry logic. `delay()` parses `retry-after[-ms]` headers w/ exp-backoff fallback; `retryable()` classifies transient-5xx / rate-limit / context-overflow-exclusion. Strip the Go-billing arms. Pairs naturally with #2. llama-swap rarely emits `retry-after`, so value is mostly transient-5xx/stall retry. |
+| — | **MCP auth file-lock** (`mcp/auth.ts`, `fa73ec4`) | — | **N-A (deferred)** | Serializes concurrent OAuth token refreshes. Can't trigger — BooCode's config schema *rejects* OAuth MCP servers until secret storage lands (roadmap). Note for when OAuth MCP is un-deferred. |
+
+**Confirmed current (cross-check, no refresh needed):** compaction algorithm (incl. `tail_start_id`/`splitTurn` post-fix — verified identical), two-tier prune, truncate, run-loop (BooCode drives off live `result.toolCalls`, not a history scan — not vulnerable to opencode's interrupted-tool re-prompt bug), doom-loop guard, MCP client, permission ruleset. **Ruled out:** v2 Effect/event-sourced core, `packages/llm/` native runtime (diverges from the AI SDK v6 BooCode just adopted), adaptive-reasoning (cloud-Anthropic only), `acp-next` (BooCoder is the ACP *client*).
+
+-----
+
+## 4. llama.cpp (consumed via llama-swap / llama-sidecar — adopt features, not C++)
+
+### 4a. ⭐ Retire the AGPL tool-call parser — **LIFT · drop-our-code**
+
+llama-server moved to a **template-learning PEG auto-parser + lazy grammar** that parses qwen3.5/3.6's tool markup server-side into OpenAI `tool_calls`.
+
+- **Evidence:** `common/chat-auto-parser-generator.cpp`, `common/chat-diff-analyzer.cpp` (1570 lines), `common/chat-peg-parser.cpp`; shipped `models/templates/Qwen3.5-4B.jinja` (uses BooCode's exact Pattern-2 `<tool_call><function=…><parameter=…>` + `<think>`); server emits structured `tool_calls` in **both** non-streaming and streaming (`tools/server/server-chat.cpp:421-577`), reasoning split into `reasoning_content`/`reasoning_content_delta`. `tool_choice=required` + grammar-constrained calls exist (`common/chat.cpp:290-300`).
+- **Gate (RESOLVED — green, Sam 2026-05-31):** llama-server runs with **`--jinja` + a qwen3.x template**, so server-side tool-call parsing is live. BooCode already treats `--jinja`/`--chat-template*` as managed flags (`llama-args-validator.ts:92-102` — itself one of the 3 AGPL files to clean-room) and sends `tools`/`toolChoice:'auto'` through the AI SDK (`stream-phase.ts:202,438`). The retirement is actionable now (§6.1).
+- **What's missing:** no qwen3.x-named native handler — qwen3.6 rides the generic template-driven path. The template teaches Patterns 1 (`<tool_call>{json}`) and 2 (`<function=…>`) but **not Pattern 3 (`<invoke name=…>`)**, the Anthropic-shape residue qwen drifts into.
+- **Staged plan (do not delete blind — CLAUDE.md notes qwen3.6 was unreliable):**
+  1. Confirm `--jinja` + Qwen3.5 template are live (add the flags if not).
+  2. Validate native `tool_calls` against **real qwen3.6 streaming** for one release, behind a feature flag.
+  3. Trim `tool-call-parser.ts` to a **clean-room `<invoke>`-only fallback** (~250 of 427 lines deletable; rewrite the remainder without Unsloth/AGPL provenance). **Net: AGPL-3.0 liability eliminated** even if a thin fallback stays.
+
+### 4b. Config-level adopts — **LIFT · config-adopt** (pass straight through llama-swap as OpenAI-compat body fields; no binary upgrade)
+
+- **New sampling params** (`server-task.cpp:279-290`): `top_n_sigma`, `xtc_probability/threshold`, `typical_p`, the **`dry_*` repetition family** (`dry_multiplier/base/allowed_length/penalty_last_n/sequence_breakers`), `frequency_penalty`, `repeat_penalty`. `top_n_sigma` + `dry_*` are the high-value pair for an agentic model prone to loops — ties to the doom-loop sentinel. Surface in AGENTS.md frontmatter + the validator allowlist.
+- **`--reasoning-budget N`** (`LLAMA_ARG_THINK_BUDGET`) + `--reasoning on|off|auto`, default `reasoning_format=auto`: server-side cap on qwen3.6 thinking (cheaper turns) without prompt hacks, and `reasoning_content` arrives as a **separate field** — BooCode could consume it directly instead of scraping `<think>`.
+
+### 4c. Behavioral changes — **TRACK** (no code action; awareness)
+
+- **SSE headers sent at slot-start** (`0821c5fcf`): in stream mode, HTTP 200 + headers flush when prompt processing *begins*, before the first token. BooCode keys its stale-stream timer on **token activity**, not header arrival → safe, but time-to-headers semantics shift. Also `task_params.stream` default flipped `true → false` — harmless for BooCode (always sets `stream`), but any llama-swap/sidecar code omitting `stream` now defaults to non-streaming.
+- **`/props` router-mode dummy `n_ctx:0`** (`server-models.cpp:1170-1173`): llama.cpp gained a native multi-model router; its **bare** `/props` (no `?model=`) returns `n_ctx:0`. BooCode reads `/upstream/<model>/props` which resolves to a specific model → still correct today. Silent failure mode only if a bare router `/props` is ever hit: `ctx_max=0` → rejected → negative-cache masks the misconfig → compaction budget degrades. (Aside: the native router could eventually **replace llama-swap** — separate evaluation.)
+- **`LLAMA_ARG_` env-prefix unification** (`6b4e4bd58`): confirm the sidecar's `LLAMA_*` env vars use the `LLAMA_ARG_` prefix.
+
+### 4d. **SKIP**
+
+- Native **Anthropic Messages API** in llama-server (`test_compat_anthropic.py`) — BooCode is OpenAI-compat via the AI SDK; switching wire formats buys nothing. (Minor TRACK: could in principle back a local "claude-compatible" provider — net-new feature, not a lift.)
+- Qwen 3.5/3.6 **TP granularity fix** (`8b0e0db60`) — only relevant if running qwen3.6 across 3 GPUs with tensor-parallel; then it's a binary-upgrade correctness fix, not an API change.
+- HTTP ETags / `--api-key-file` / timeout bump — irrelevant behind Authelia + llama-swap.
+
+-----
+
+## 5. Second fork sweep (2026-05-31) — 11 repos
+
+Read-only agent review of everything else in `/opt/forks/` except the three already covered (paseo/opencode/llama.cpp), BooCode's own `llama-sidecar`, and `codecontext`/`codesight` (skipped on request). Repos: **conductor, superset, openchamber, happy, cline, qwen-code, amp-acp, pi-acp, claude-code, goose, unsloth.** Shallow clones (history-limited but source intact): cline, qwen-code, amp-acp, pi-acp, claude-code, goose, unsloth. Full: conductor, superset, openchamber, happy.
+
+### 5a. openchamber (`openchamber/openchamber`, **MIT** — code-liftable) ⭐
+Multi-runtime (web/PWA/Electron/VS Code) GUI for **opencode-as-warm-server** — the closest architectural sibling to BooCoder's backend. **Stronger than BooCode in exactly one dimension: opencode process-lifecycle hardening** (BooCode's v2.6 Phase 3 frontier). Divergence shaping every lift: openchamber runs **one global opencode server + one `/global/event` stream**; BooCode runs per-`(chat,agent)` sessions with per-session `event.subscribe({directory})` — so these are pattern/code-adaptation lifts, not drop-ins.
+
+| # | Finding | Evidence (HEAD `a394a877`) | Verdict | Maps to |
+|---|---------|---------|---------|---------|
+| 5c | **Lifecycle hardening: health monitor + crash auto-restart + busy-aware restart** | `packages/web/server/lib/opencode/lifecycle.js` — `runHealthCheckCycle` (L896), `HEALTH_CHECK_MAX_CONSECUTIVE_FAILURES=20`, `shouldSkipRestartForBusySessions`+`STALE_BUSY_GRACE_MS` (L872/838), `startHealthMonitoring` 15s (L938), `triggerHealthCheck` (L930). BooCode's `opencode-server.ts:143` literally comments *"recovery is Phase 3"* | **LIFT · pattern** | **v2.6 Phase 3** (#5) |
+| | **Port reclaim before respawn** (`killProcessOnPort` lsof+kill, `waitForPortRelease` net.connect poll) | `lifecycle.js:44,101`, used in `restartOpenCode` L595 | LIFT · code (S) | Phase 3 |
+| | **Stall-detecting SSE reader + `Last-Event-ID` replay** (2048-event ring, 20s stall-abort) | `lib/event-stream/upstream-reader.js:110-131`, `global-hub.js:88-149` | LIFT · pattern (the stall-timer half is S, high-value) | hardens `runSessionEventLoop` |
+| | **`OPENCODE_SERVER_PASSWORD` scheme confirmed** = `Authorization: Basic base64("opencode:"+pw)`, rotate-on-restart | `packages/vscode/src/opencode.ts:55-65,786`; `lifecycle.js:458` | CROSS-CHECK → LIFT · config | closes a known unknown (BooCode runs the warm server unsecured on loopback) |
+| | Worktree layout/reaper mirrors opencode's `<data>/worktree/<projectID>/`; `removeWorktree` saga | `packages/vscode/src/gitService.ts:1062,1874` | CROSS-CHECK | Phase 3 reaper; check BooCode's worktree paths align with opencode's expected layout |
+
+Ruled out: warm-ACP/goose/qwen/claude (openchamber is **opencode-only**), SSE part-translation/reasoning-dedup (BooCode's is more complete), Arena-equivalent, permission cards — all already-better-in-BooCode or N-A.
+
+### 5b. cline (`cline/cline`, **Apache-2.0** — code-liftable) ⭐
+Re-architected into a layered SDK. Two strong **code** lifts that hit exactly where BooCoder's write/edit surface is weakest for local quantized models.
+
+| # | Finding | Evidence (HEAD `31a118f`) | Verdict | Maps to |
+|---|---------|---------|---------|---------|
+| 5d | **`git stash create` + private-ref checkpoint** — per-turn snapshot of full dirty worktree, GC-safe, invisible to `git stash list`, restorable with conversation-trim in sync | `sdk/packages/core/src/hooks/checkpoint-hooks.ts:177-253`; `session/checkpoint-restore.ts:161-189` | **LIFT · code+pattern** (#4) | checkpoint/restore — captures **external-agent** edits BooCode's `rewind` can't |
+| 5e | **Fuzzy patch applier** — exact→`trimEnd`→`trim`→Levenshtein≥0.66 ladder + unicode canon (dashes/curly-quotes/nbsp) + multi-occurrence guard; unmatched→warning not throw | `extensions/tools/executors/apply-patch-parser.ts:347-431,58-83`; `editor.ts:133-143` | **LIFT · code** (#3) | BooCoder `edit_file` is exact `.includes`-or-throw (`pending_changes.ts:111`) |
+| | **File-provenance carry-forward** — `## Files {Read,Modified}` ledger merged across compactions, deterministic | `extensions/context/compaction-shared.ts:351-410` | LIFT · pattern (#12) | context-mgmt |
+| | **`MistakeTracker`** — counts *heterogeneous* consecutive failures (api/invalid-tool/exec), injects recovery guidance + resets vs hard-stop | `runtime/safety/mistake-tracker.ts:82-142` | LIFT · pattern (#12) | complements doom-loop (which only catches *identical* repeats) |
+| | Tool-pair-atomic compaction eviction (BFS over `tool_use_id`, turn-boundary cut) | `extensions/context/basic-compaction.ts:181-205` | CROSS-CHECK | verify `selectPruneTargets` never orphans a `tool_result` |
+
+Ruled out: prompt-caching (Anthropic `cache_control` markers — N-A, llama.cpp auto-prefix-caches), stream retry (delegated to AI SDK — same as BooCode), MCP marketplace, hub/daemon (multi-client — BooCode is single-process).
+
+### 5f. qwen-code (`QwenLM/qwen-code` v0.17.0, **Apache-2.0** — code-liftable) ⭐
+**The "qwen = one-shot PTY because ACP was HTTP-only" premise is obsolete.** qwen now ships a full stdio-ACP agent, a `qwen serve` HTTP+SSE daemon, and a Claude-Code-compatible stream-json protocol.
+
+| # | Finding | Evidence | Verdict | Maps to |
+|---|---------|---------|---------|---------|
+| | **Warm `qwen --acp` is real** — multi-session `Map<sessionId,Session>`, `loadSession`/`unstable_resumeSession`, `setSessionMode`/`unstable_setSessionModel`, stdio NDJSON via `@agentclientprotocol/sdk` | `packages/cli/src/acp-integration/acpAgent.ts:308,322-351,384-568` | CROSS-CHECK → **LIFT · pattern** (#2) | **v2.6 Phase 2** — validates the openspec plan; wire goose/qwen to `acp-dispatch.ts` |
+| 5g | **stream-json = Claude-compatible NDJSON** (`system`/`assistant`/`result`/`stream_event` with `content_block_delta` text/thinking/tool deltas, `usage`, `session_id`) — BooCode **parses none of it** (`dispatcher.ts:406` slices stdout opaque) | `nonInteractive/types.ts:88-262`, `StreamJsonOutputAdapter.ts` | **LIFT · pattern** (#7) | one parser serves qwen **and** claude PTY fallbacks |
+| | **Resume primitives** `--resume <uuid\|title>` / `--continue` / `--session-id <uuid>` / `--fork-session` | `config/config.ts:825-985,1668-1721` | LIFT · config | mint a stable per-`(chat,agent)` UUID; parity with claude `--resume` |
+| | `qwen serve` daemon + `@qwen-code/sdk` (HTTP+SSE, **`Last-Event-ID` replay ring**, better than opencode's SSE) | `commands/serve.ts:51-266`; `packages/sdk-typescript/src/daemon/*` | TRACK | stdio-ACP is cheaper now; mine its SSE-reconnect design when hardening opencode SSE (converges w/ openchamber 5c) |
+
+Note: BooCode ships `@agentclientprotocol/sdk@^0.22.1` (newer than qwen's `^0.14.1`) — same package family, BooCode ahead; **cross-check the v0.14↔v0.22 `initialize`/capability handshake before relying on `unstable_resumeSession`** (the `unstable_` prefix signals churn). Ruled out: the `rewind` commit (`c699738`) is a qwen-TUI history-count fix, not a wire event — N-A.
+
+### 5h. happy (`slopus/happy`, **MIT** — code-liftable) ⭐
+Mobile/remote client that drives **Claude Code** via the **`@anthropic-ai/claude-agent-sdk`** (NOT PTY). A working existence-proof for BooCode's claude SDK-vs-PTY decision. **SDK note (published `.d.ts` reviewed 2026-05-31, `@0.3.158`):** the SDK is under **Anthropic Commercial Terms** (`package.json` `license: "SEE LICENSE IN README.md"`) — not OSS, so **runtime dep OK but code/examples are reference-only, do not vendor** (esp. mid AGPL→MIT cleanup). It now ships a **native pluggable `SessionStore` + `resume`** that **supersedes happy's hook/jsonl-watcher** (happy pins `^0.2.96`, before that API landed). Readable refs on disk: `/opt/forks/claude-agent-sdk-python` (MIT mirror) + `/opt/forks/claude-agent-sdk-typescript` (examples, commercial terms).
+
+| # | Finding | Evidence (HEAD `21c6ced`) | Verdict | Maps to |
+|---|---------|---------|---------|---------|
+| | **Claude Agent SDK in streaming-input mode** — one persistent `query()` fed a `PushableAsyncIterable<SDKUserMessage>`; structured `system/init` (tools/skills/mcp), `assistant`, `result`, tool parts — no stdout scraping | `claude/sdk/query.ts`, `claude/claudeRemote.ts:152-259`; dep `@anthropic-ai/claude-agent-sdk@^0.2.96` | **LIFT · pattern** + resolves the decision → **lean SDK** (#9) | claude-provider direction |
+| 5i | **Session resume — use the SDK's native `SessionStore`, not happy's hook/watcher.** happy uses a SessionStart-hook + jsonl-watcher because it pins SDK `^0.2.96`; the current SDK (`0.3.158`) exposes a pluggable `SessionStore` (`append`/`load`/`listSessions`/`delete`/`listSubkeys`) + `query({options:{sessionStore,resume}})`. Implement `PostgresSessionStore` over BooCode's Postgres keyed `(chat_id,agent)`; `importSessionToStore()` migrates a local session, `InMemorySessionStore` is the shape. | `sdk.d.ts@0.3.158` (`InMemorySessionStore` L870, `query` L2391, `resume` L1695); happy `claude/utils/*` = legacy ref | **LIFT · code** (#9) | native, supersedes the hook/watcher; clean-room the store (SDK is commercial-terms) |
+| | `canUseTool` permission callback — single chokepoint, live `setPermissionMode`, bash-prefix allow-cache | `claude/claudeRemote.ts:134,169`, `permissionHandler.ts` | CROSS-CHECK | cleaner integration point than parsing PTY permission prompts |
+| | Local↔remote single-session handoff (TTY ⇄ SDK share one Claude UUID); E2E socket.io relay | `claude/loop.ts:77-115`; `api/encryption.ts` | TRACK / N-A | relay N-A (Authelia owns auth); handoff only if BooTerm⇄CoderPane session-continue is ever wanted |
+
+### 5j. superset (`superset-sh/superset`, **Elastic License 2.0 — source-available, PATTERN-ONLY**)
+Electron macOS "code editor for AI agents"; runs every agent as a **raw PTY process** and learns state purely from **hooks the agents POST back** (no editor↔agent protocol, tracks **zero** tokens/cost). All items clean-room only.
+
+| # | Finding | Evidence (HEAD `7f3e5b3`) | Verdict | Maps to |
+|---|---------|---------|---------|---------|
+| 5j | **Universal-agent lifecycle hooks → normalized status** — inject a notify hook into each agent's native config (`~/.claude/settings.json`, `~/.codex/hooks.json`, opencode plugin), POST `{terminalId,eventType,agent}`; server collapses ~30 vendor event names → 5 states | `apps/desktop/.../agent-setup/*`, `templates/notify-hook.template.sh`, `host-service/.../map-event-type.ts` | **RE-DERIVE** (#10) | gives BooCode's **PTY agents (goose/qwen/claude) real working/blocked/done state** it lacks today |
+| | Worktree destroy saga — preflight `inspect` (dirty/unpushed) + ordered failure semantics + in-flight guard | `host-service/.../workspace-cleanup.ts` | RE-DERIVE | Phase 3 worktree reaper |
+| | Out-of-process PTY daemon w/ crash supervision + adoption (circuit-breaker, adopted-PID liveness poll) | `host-service/.../DaemonSupervisor.ts` | RE-DERIVE / TRACK | Phase 3 (BooTerm tmux already does some) |
+| | Diff-line → agent-comment re-prompt loop (select lines → send to existing session or new agent) | `apps/desktop/.../DiffPane/AgentCommentComposer/*` | RE-DERIVE | review/diff UX frontier |
+
+Ruled out: token/cost (superset tracks **none** — BooCode ahead), permission cards (BooCode's intercept-and-render is richer; superset just chimes + bypass-flags the agent), editor↔agent protocol (there is none), all SaaS/cloud/billing plumbing.
+
+### 5k. unsloth (`unslothai/unsloth`) — **DECISION: remove all AGPL code, relicense BooCode AGPL-3.0 → MIT**
+**Tree audit (corrects this doc's earlier 2-file count):** BooCode is **currently licensed AGPL-3.0** — root `LICENSE` is GNU Affero GPL v3 and **all five `package.json` declare `"license": "AGPL-3.0-only"`** (cause: the `v2.4.0`/`v2.4.1` Unsloth-Studio lifts). **Three** files carry `SPDX-License-Identifier: AGPL-3.0-only`, not two — `llama-args-validator.ts` was missed: `apps/server/src/services/inference/tool-call-parser.ts` (← `tool_call_parser.py`), `apps/server/src/services/web/html-to-md.ts` (← `_html_to_md.py`), `apps/server/src/services/inference/llama-args-validator.ts` (← `llama_server_args.py`). Unsloth is dual-licensed — core `unsloth/` = Apache-2.0, but the `studio/` subtree (source of all three) = **AGPL-3.0-only** (dedicated `studio/LICENSE.AGPL-3.0`, `studio/package.json` `"license":"AGPL-3.0-only"`, per-file SPDX headers, README line 262 carves Studio out). Network-served ⇒ **AGPL §13 network-copyleft is the live liability.**
+
+**Decision (Sam, 2026-05-31): relicense AGPL-3.0 → MIT** (supersedes this doc's earlier "clean-room recommendation stands" framing — it's now a committed batch, not a flag). Remove all three: parser → native llama-server parsing (jinja green) + clean-room `<invoke>` fallback; html-to-md → permissive lib (turndown / node-html-markdown); llama-args-validator → clean-room from the llama-server README flag list. Then flip `LICENSE` + the five `package.json` + per-file headers + roadmap/README prose. Canonical plan: roadmap `## License-debt — relicense AGPL-3.0 → MIT (planned)`.
+
+### 5l. conductor (`conductor-oss/conductor`, **Apache-2.0**, Java) — **LOW / near-NONE**
+Confirmed **Netflix/Orkes Conductor** — enterprise distributed workflow engine (5600 commits, Spring/Flyway/Cassandra), **not** the Mac Claude-Code app. Wrong scale + wrong substrate (polling workers + Redis queues vs BooCode's single-user Postgres LISTEN/NOTIFY), and BooCode already sourced its task-DAG/dispatcher/pipelines/human_inbox from `agent-hub` + Roo Boomerang. **One** worth-a-glance reference: the **retry/backoff/timeout taxonomy** (`TaskDef.java` `RetryLogic{FIXED,LINEAR,EXP}` + `TimeoutPolicy`, delay formula in `DeciderService.java:634-680`, with jitter + total-time-budget guard) — BooCode has **no retries today**; copy the *field set + three formulas* when retries land. Everything else (decider-replay engine, 24 task mappers, fork-join, sub-workflow, human-task) = N-A, already-covered or wrong-scale.
+
+### 5m. ACP provider candidates — amp-acp **SKIP**, pi-acp **WATCH**
+Both are config-only adds to BooCode's v2.3 catalog (`{extends:'acp', label, command, env}`) and both use **`@agentclientprotocol/sdk@~0.22/0.12`, proto v1 — wire-compatible with BooCode's own `@agentclientprotocol/sdk@0.22.1`** (see correction in §6).
+- **amp-acp** (`tao12345666333/amp-acp`, Apache-2.0): adapter for Sourcegraph **Amp**. `npx -y amp-acp` + `AMP_API_KEY`. **SKIP** — Amp is a **paid cloud product with no self-host / no BYO-key / no local-model path**; can't point at llama-swap. Keep only as the canonical *"does add-from-catalog work"* smoke entry (lowest-risk Apache-2.0 ACP adapter).
+- **pi-acp** (`svkozak/pi-acp`, MIT): bridge for **pi** (spawns `pi --mode rpc`). `npx -y pi-acp`, pi free + self-hostable, dynamic model discovery. **WATCH** — but found **no evidence pi supports an OpenAI-compatible/llama-swap base URL** (cloud BYO-keys only today) + v0.0.27 maturity ("MVP", MCP not wired). Re-evaluate if pi adds a local provider — then it's a strong config-only ADD.
+
+### 5n. claude-code & goose — low/cosmetic
+- **claude-code** (`anthropics/claude-code`, depth-1): the public **issue-tracker/docs repo, not source.** Thin. No stream-json schema doc (keep relying on observed output). Notables: `CLAUDE_CODE_SESSION_ID` env injected into Bash-tool subprocesses (hook↔session correlation); `examples/settings/*.json` permission/sandbox shapes; `SKILL.md` frontmatter is simpler (`name/description/version`) than BooCode's `eval.yaml`. The one example hook (`bash_command_validator`) is the same family BooCode already vendored. **Nothing net-new liftable.**
+- **goose** (`block/goose`, depth-1, Apache-2.0 Rust → pattern-only): the **AAIF/Linux-Foundation move is cosmetic** — binary `goose`, `goose acp` invocation, and `~/.config/goose/` config path all **UNCHANGED**; only org/URLs changed (`block/goose` → `aaif-goose/goose`). **Watch:** grep BooCode install docs for `block/goose` URLs (will eventually 404). **For v2.6 Phase 2:** goose ACP supports multi-session + mid-session model/mode switch + session persistence, but **no `loadSession`/resume method surfaced** → cross-restart resume looks thinner than opencode's; don't assume opencode-style `agent_sessions` resume works identically for goose.
+
+-----
+
+## 6. Open decisions / things to think about
+
+1. **The jinja gate — RESOLVED (green, Sam 2026-05-31).** `--jinja` + a qwen3.x template are live in the llama-swap/sidecar config, so llama-server already does server-side tool-call parsing. #1 (the relicense batch's parser removal) is **actionable now** — step 1 is to validate native parsing on live qwen3.6 behind a flag for one release, then delete.
+2. **Claude transport: SDK vs PTY — now evidenced, leaning SDK.** `happy` (§5h) is a working existence-proof that `@anthropic-ai/claude-agent-sdk` in streaming-input mode drives Claude Code with structured events (tool calls, reasoning, `system/init` tool/skill/mcp lists, usage) and clean continuity — richer than PTY stdout-scraping. **Decision narrowed to: adopt the SDK** (net-new integration, ~100-line streaming-input pump) **vs. stay PTY + just add `--resume`.** Independent of warm-ACP Phase 2. Note the continuity mechanism is now the SDK's **native `SessionStore`** (§5i — a `PostgresSessionStore` keyed `(chat_id,agent)`, superseding happy's hook/jsonl-watcher) and is transport-independent — ship it either way.
+3. **`stream-json` parser is shared infrastructure, not a per-agent chore.** qwen-code (§5g) and claude-code emit the *same* Claude-Code-compatible NDJSON. One parser keyed on `type` / `stream_event.event.type` unlocks tool/reasoning/usage surfacing for **both** qwen and claude PTY fallbacks (today both are sliced opaque). Decide whether to build it as a shared module now (cheap) rather than twice later.
+4. **Transcript/session verification before resume (shared gap).** Neither Paseo nor BooCode (nor openchamber, nor goose's ACP) verifies the session/transcript exists on disk before resuming — true for opencode, claude, qwen. Folds into v2.6 Phase 3 (crash recovery + active supervision, now lifting from openchamber §5c). Decide whether "resume blindly, recover on failure" is good enough for single-user, or worth a pre-resume existence check. **Caveat:** goose ACP exposes no `loadSession`/resume (§5n) → its cross-restart resume needs a different design than opencode's.
+5. **Usage *and status* normalization scope.** Two converging gaps: (a) **tokens/cost** — the opencode token slice (#8) converges with paseo `AgentUsage`; (b) **liveness/status** — superset's notify-hook pattern (§5j, #10) is the only way to know whether a one-shot PTY agent (goose/qwen/claude) is working / blocked-on-permission / done. Decide whether to design one normalized per-`(chat,agent)` "agent telemetry" shape (tokens + status) up front so all providers slot in, or ship opencode-token-only and generalize at Phase 2.
+6. **Correction — ACP SDK package.** This doc and the roadmap state BooCode uses `@zed-industries/agent-client-protocol`; the live `apps/coder/package.json` actually declares **`@agentclientprotocol/sdk@^0.22.1`** (verified installed). Both amp-acp and pi-acp use the same package, so the "version-drift" worry is moot. ✅ Now corrected in `boocode_roadmap.md`'s lift table (2026-05-31).
+
+-----
+
+## 7. Housekeeping
+
+- **Stale `.bak` in the working tree:** `apps/server/src/services/inference/tool-phase.ts.bak-20260531` (today, 15.5 KB). Violates CLAUDE.md's "don't accumulate `.bak-*`". Dated today and `tool-phase.ts` is on the active path — may be an in-progress safety copy. **Confirm before removing.**
+- **Unshallow `/opt/forks/llama.cpp`** (`git fetch --unshallow`) before the next review so commit-level attribution is possible. (opencode was unshallowed mid-review; cline/qwen-code/amp-acp/pi-acp/claude-code/goose/unsloth remain shallow but their source was intact.)
+- **Grep BooCode install docs/scripts for `block/goose` URLs** — goose moved to `aaif-goose/goose` (§5n); old release URLs will eventually 404.
+- **Correct the ACP-SDK package name** in `boocode_roadmap.md`'s lift table → `@agentclientprotocol/sdk@0.22.1` (§6.6).
+
+-----
+
+## 8. Roadmap mapping (where each actionable lands)
+
+| Roadmap slot | Items from this review |
+|---|---|
+| **v2.6 Phase 2** (warm ACP goose/qwen) | #2 warm-ACP backend — **validated by qwen's own `qwen --acp`** (§5f); #7 parse qwen/claude stream-json in the one-shot fallback |
+| **v2.6 Phase 3** (lifecycle hardening) | **#5 openchamber lifecycle hardening** (health monitor + crash restart + port reclaim + stall-SSE — §5c, supersedes the paseo re-derive); worktree-archive cascade (paseo) + superset destroy-saga (§5j); LRU-bound caches; pre-resume session verification |
+| **v2.6 Phase 1 UX** | #6 interrupt-bug fix; #8 opencode token/ctx usage; richer SSE arms (compaction surfacing) |
+| **Write/edit robustness (NEW batch)** | **#3 fuzzy patch applier** + **#4 git-stash checkpoint** (cline §5b) — both directly harden BooCoder's edit/rewind surface for local models |
+| **Cross-agent telemetry (NEW)** | #10 superset notify-hook → normalized **status** for PTY agents (§5j); pairs with #8 token usage |
+| **Standalone claude-provider batch** | #9 SDK transport + native `SessionStore` resume (§5h–§5i; supersedes hook/jsonl-watcher) + the SDK-vs-PTY decision (lean-SDK, §6.2); #12 MistakeTracker + file-provenance ledger (cline) |
+| **Inference / license-debt batch** | #1 AGPL parser retirement (**AGPL confirmed §5k**; gated on the jinja check §6.1); #11 sampling/reasoning-budget config adopts |
+| **BooChat resilience (opportunistic)** | stall-timeout + retry/backoff (opencode); tool-pair-atomic prune cross-check (cline §5b) |
+| **Provider catalog** | amp-acp = keep as add-from-catalog **smoke test only** (§5m); pi-acp = WATCH for a local-provider mode |
+| **Deferred / gated** | subagent permission demux (needs opencode-SSE permission cards first); MCP auth lock (needs OAuth MCP un-deferred); `qwen serve` HTTP backend (stdio-ACP cheaper) |
+| **Not actionable** | conductor (wrong scale — only the retry-taxonomy reference §5l); claude-code public repo (docs only §5n) |

boocode_roadmap.md

@@ -1,6 +1,6 @@
 # BooCode roadmap (v1.x–v2.x)
 
-Last updated: 2026-05-26
+Last updated: 2026-05-31
 
 > **Companion doc:** `boocode_code_review.md` holds the full external-repo inventory, lift rationale, and license analysis. This document is the canonical source for shipping state, version ordering, and what's planned vs. shipped.
 
@@ -9,7 +9,7 @@ Last updated: 2026-05-26
 BooCode is a **3-app monorepo** at `/opt/boocode/` (locked 2026-05-22):
 
 - **BooChat** (`apps/server` + `apps/web`, port `9500`, `code.indifferentketchup.com`) — read-only chat with file-inspection tools. Backend in `apps/server`, SPA in `apps/web`. Database `boochat` (renamed from `boocode` at v2.0).
-- **BooCoder** (`apps/coder`, port `9502`, `coder.indifferentketchup.com`) — write tools + external-CLI dispatch. **Shipped v2.0.0–v2.2.1.** Host systemd service (not Docker since v2.1.0). In-process inference (with `pending_changes` table) AND Paseo-style ACP dispatch for seven providers (cursor, opencode, goose, claude, qwen, copilot + native boocode) with PTY fallback where ACP is unavailable.
+- **BooCoder** (`apps/coder`, port `9502`, `coder.indifferentketchup.com`) — write tools + external-CLI dispatch. **Shipped v2.0.0–v2.6.6** (repo tag line; v2.6.5–v2.6.6 were BooChat workspace UX + docs). Host systemd service (not Docker since v2.1.0). In-process inference (with `pending_changes` table) AND Paseo-style ACP dispatch for five providers (opencode, goose, claude, qwen + native boocode; cursor + copilot retired at v2.5.3) with PTY fallback where ACP is unavailable. Provider lifecycle is config-backed (`data/coder-providers.json`, enable/disable, two-tier probe — shipped v2.5.4–v2.5.13). opencode now runs as a **warm HTTP server** with persistent per-chat sessions (v2.6 Phase 1); goose/qwen/claude still dispatch one-shot.
 - **BooTerm** (`apps/booterm`, port `9501`) — PTY/tmux/xterm.js. **Live since May 2026.** bookworm-slim + node-pty + tmux + xterm.js. Tmux session per pane (`bc-<uuid>`), SSH-out works (openssh-client + gosu in the image). Shares Postgres database `boochat`.
 
 Caddy → Authelia → Tailscale → `100.114.205.53` → 9500/9501/9502. Three apps, **one shared Postgres** (Docker service `boocode_db`, database name `boochat`).
@@ -21,7 +21,7 @@ Caddy → Authelia → Tailscale → `100.114.205.53` → 9500/9501/9502. Three
 - **Mount strategy: blanket `/opt:rw`, permission gating at the write-tool layer.** Per-project scoping is policy, not mount. Path-guard correctness is the #1 test target for v2.0.
 - **External CLI agents (`opencode`/`claude`/`goose`/`pi`) live on the host, not in containers.** BooCoder shells out via local-exec PTY or ACP subprocess. Host install inherits Sam's existing `~/.opencode/`, `~/.claude/`, `~/.config/goose/` configs.
 - **Protocol roles locked (2026-05-22):** **BooChat = MCP client only** (read-only tool consumer, never enables write-capable MCP servers). **BooCoder = MCP client + MCP server + ACP client (host) + ACP agent (driveable)** — full matrix. BooCoder's ACP-client role replaces raw-PTY dispatch for ACP-capable agents (opencode `opencode acp`, goose `goose acp`); PTY fallback retained for claude/pi/smallcode.
-- **Paseo-equivalent dispatcher inside BooCode** (2026-05-22 pivot, **shipped v2.2**). Paseo (`getpaseo/paseo`) is AGPL-3.0 — incompatible with BooCode's MIT license and network-served deployment. BooCode reproduces the architecture using license-clean patterns only (`provider-snapshot.ts`, ACP merge/stream/persist, `AgentComposerBar`). Primary architectural template: `Dominic789654/agent-hub` (Apache-2.0). Critical context-management primitive: Roo Code Boomerang Tasks pattern. Observation pattern: Claude Code hooks (siropkin/budi reference).
+- **Paseo-equivalent dispatcher inside BooCode** (2026-05-22 pivot, **shipped v2.2**). Paseo (`getpaseo/paseo`) is AGPL-3.0 — incompatible with BooCode's **target** MIT license and network-served deployment (the tree is *currently* AGPL-3.0 via the v2.4 Unsloth-Studio lifts — see the **License-debt → relicense to MIT** batch; the Paseo pattern-only rule holds regardless). BooCode reproduces the architecture using license-clean patterns only (`provider-snapshot.ts`, ACP merge/stream/persist, `AgentComposerBar`). Primary architectural template: `Dominic789654/agent-hub` (Apache-2.0). Critical context-management primitive: Roo Code Boomerang Tasks pattern. Observation pattern: Claude Code hooks (siropkin/budi reference).
 
 External code lifted from / referenced in: see `boocode_code_review.md` for full inventory.
 
@@ -348,9 +348,49 @@ Per-session Docker sandbox spawned by BooCoder on first write. Only project path
 
 -----
 
+## Shipped (v2.2.2–v2.6.10 — interactive ACP, provider lifecycle, persistent agent sessions, workspace UX)
+
+All tags `vMAJOR.MINOR.PATCH-slug`, monotonic per minor, assigned at ship time (planning slugs differ — see the numbering-discipline note below). `CHANGELOG.md` is the canonical per-tag record. **Note on numbering divergence:** the *planned-feature* "v2.3 — Provider lifecycle" actually shipped under the **v2.5.4–v2.5.13** tags; the *planned-feature* "v2.4 — BooCoder as ACP agent" remains **unshipped** even though v2.4.0/v2.4.1 *tags* shipped unrelated content (Unsloth lifts, sidecar routing). The patch-tag thread and the conceptual-milestone thread have diverged — read tags as the ship record, the `## v2.x` feature sections below as the milestone plan. The v2.3.0–v2.5.1 tags were never CHANGELOG-backfilled; summarized here from commit bodies.
+
+- `v2.2.2-xml-placeholder-reject` — reject placeholder XML tool args (`...`, `<path>`, empty/whitespace, angle-bracket sentinels) at parse time; appends raw block to prose instead of silent-deleting. Fixes qwen3.6 answer-then-spurious-tools duplicate-row tail
+- `v2.3.0-sampling-params-ask-user` — per-agent sampling params (`top_p`/`top_k`/`min_p`/`presence_penalty`) in AGENTS.md frontmatter threaded through inference (null = omit, preserve provider default); `ask_user_input` interactive card wired into both BooCoder frontends (CoderPane + standalone coder SPA)
+- `v2.3.1-permission-questions` — enrich ACP `permission_requested` frame with `kind` (`tool`|`question`|`plan`|`elicitation`) + `input` + `description`; PermissionCard renders interactive radio/checkbox forms for AskUserQuestion; ACP `createElicitation` (experimental) JSON-Schema-driven forms
+- `v2.3.2-coder-answer-endpoint` — fix `ask_user_input` submit in CoderPane (register `answer_user_input` on the boocoder service; `apiPrefix` routes through `/api/coder/...` so the right inference runner picks up the answer)
+- `v2.4.0-unsloth-studio-lift` — port of Unsloth Studio modules: `tool-call-parser.ts` (replaces `xml-parser.ts`; balanced-brace JSON scanner, `hasToolSignal`/`stripToolMarkup`/`parseToolCallsFromText`, stripping at all 3 final-write sites) + `web/html-to-md.ts` (parse5 HTML→Markdown for `web_fetch`). **License consequence (recorded 2026-05-31):** Unsloth Studio is AGPL-3.0-only — this lift (plus `llama-args-validator.ts` from `v2.4.1-sidecar-routing`) put the **whole BooCode tree under AGPL-3.0** (`LICENSE` + all five `package.json` are `AGPL-3.0-only`; three files carry the AGPL SPDX header). Scheduled for removal in the **License-debt → relicense to MIT** batch
+- `v2.4.1-sidecar-routing` — route per-agent `llama_extra_args` to `LLAMA_SIDECAR_URL` via `X-Agent-Flags` (boot guard if set but URL unset); `resolveRoute` + PrefixFingerprint `route` field. AGENTS.md tool-gap fix: 8 post-hoc tools (`request_read_access`, `view_truncated_output`, `ask_user_input`, `git_status`, …) added to every agent's whitelist
+- `v2.5.0-task-model` — lightweight task-model services (`TASK_MODEL_URL` dedicated llama-server, falls back to `LLAMA_SWAP_URL`+`FAST_MODEL`) for auto-naming/search-rewrite/tags/summaries; search-query rewriting on step 0 when web tools enabled; `sessions.tags` column
+- `v2.5.1-budget-100` — tool-call budgets raised 50/10/50 → **100/100/100** (read-only / non-read-only / no-agent); per-agent `max_tool_calls` still overrides. `.claude/worktrees/` added to `.codecontextignore`
+- `v2.5.2-coder-ux-fixes` — dispatcher reacts immediately via Postgres `LISTEN/NOTIFY` (`tasks_new` trigger, 2s poll fallback); mobile nav-drawer bfcache fix (`useViewport` re-syncs on `pageshow`/`visibilitychange`); reasoning "Thinking" collapsible in MessageBubble (ACP `agent_thought_chunk` + native `reasoning_parts`); paste-to-chip verbatim; "New file from pasted text" RightRail affordance; DiffPanel approve/reject repointed to real routes. Ships the `v2-6-persistent-agent-sessions` openspec as planning docs only
+- `v2.5.3-remove-cursor-copilot` — retire cursor + copilot providers entirely (argv cases, manifest, command maps, cursor model-CLI branch, `cursor-models.ts`). Built-ins now: claude, opencode, goose, qwen, native boocode
+- `v2.5.4-provider-lifecycle-phase1` — **(v2.3 milestone, phase 1/5)** config-backed provider layer (`CODER_PROVIDERS_PATH` default `/data/coder-providers.json`; `provider-config.ts` never-throws loader; `buildResolvedRegistry` merge) over built-ins; `agent-probe` iterates the resolved registry. No runtime change when no config file exists
+- `v2.5.5-provider-lifecycle-phase2` — **(phase 2/5)** snapshot lifecycle status (`loading`|`ready`|`unavailable`|`error`) + `enabled` flag; always lists every registered provider; two-tier probe (fast `which` vs cold ACP, skipped unless forced / `PROVIDER_PROBE_TTL_MS` 24h stale / DB-empty); `provider-types-parity.test.ts`
+- `v2.5.6-provider-lifecycle-phase3` — **(phase 3/5)** generic ACP dispatch (`resolveLaunchSpec` from config `launchCommand`; spawn `spec.binary`/`args`/`env`); built-in dispatch byte-identical (regression-tested). Config-defined custom ACP providers dispatch with no new switch case
+- `v2.5.7-claude-models-and-picker-fix` — fix the empty provider picker (a v2.5.5 regression: `getProviderSnapshot` returned sync `loading` entries the composer filtered out → now awaits build, returns terminal entries); wire config `models` (replace) / `additionalModels` (merge); claude static models bumped to opus/sonnet/haiku latest-aliases + pinned full names
+- `v2.5.8-mobile-composer-row` — AgentComposerBar mobile fix (dot + refresh as one right-aligned unit, was wrapping); Mode picker icon-only on mobile via `CompactPicker` `iconOnly`. Desktop unchanged
+- `v2.5.9-agent-slash-commands` — segmented per-agent slash menu (active agent's commands first, BooCoder skills second; opt-in `groups` prop, BooChat flat path byte-identical); skills now run under the selected external agent (skill body injected into a dispatched task); landing-chat skill-invoke fix
+- `v2.5.10-opencode-live-commands` — capture opencode's live ACP `available_commands` (poll for the async `available_commands_update`, was racing to 0); persist to new `available_agents.commands` JSONB; serve merged on the tier-2-probe-skip path
+- `v2.5.11-claude-skill-discovery` — surface Claude Code's real enabled commands + plugin skills in the coder slash menu (`claude-command-discovery.ts` reads `~/.claude/commands` + `enabledPlugins` skills/commands); three icon'd groups (agent commands / agent skills / BooCoder skills); `AgentCommand.kind`
+- `v2.5.12-provider-lifecycle-phase4` — **(phase 4/5)** HTTP API: `GET`/`PATCH /api/providers/config`, optional-subset `POST /refresh`, `GET /:id/diagnostic`. PATCH ordering validate→save→reload→clear (malformed body → 422 no-write; save-fail → 500 no-divergence); `mergeProviderConfigPatch`; +28 tests
+- `v2.5.13-provider-lifecycle-phase5` — **(phase 5/5, closes the v2.3 arc)** Settings → Providers UI (status badge, enable/disable toggle, per-provider refresh, plaintext diagnostic); composer filters to `enabled && ready|loading`; curated ACP catalog + `AddProviderModal`; two mobile fixes (Settings reachable on phones; modal scroll-containment). `docs/DEFERRED-WORK.md` §2 marked addressed
+- `v2.5.14-claude-md` — docs-only CLAUDE.md session-learnings (stale boocoder process after build, container `build:.` deploys working tree, wholesale `PATCH /providers/config` merge, one-shot external dispatch has no ctx tracking, `ui/` switch/sheet fallbacks, mobile Dialog scroll recipe); backfills v2.5.7–v2.5.11 doc bullets
+- `v2.5.15-acp-path-guard` — security: separator-bounded worktree path guard in `acp-client-fs.ts` (closes a sibling-prefix `<worktree>-evil/` escape; `writeWorktreeTextFile` bypasses `pending_changes`, writes disk directly) via shared `resolveInWorktree` + regression test; stop tracking live `data/coder-providers.json` (gitignore + `data/coder-providers.example.json` reference; loader falls back to built-ins-only)
+- `v2.6.0-phase0-foundations` — **(v2.6 Phase 0, no behavior change)** schema + interface scaffold: `session_worktrees` (one shared worktree per session) + `agent_sessions` (one backend session per `(session, agent)`) tables, `pending_changes.agent` attribution column; `AgentBackend`/`AgentSessionHandle` interface + normalized transport-agnostic `AgentEvent` union (types only)
+- `v2.6.1-phase1-opencode` — **(Phase 1)** opencode as a **warm HTTP server** (`opencode serve` per BooCoder process, one opencode session per BooCode session resumed across turns via `agent_sessions`); single SSE read loop, Paseo reasoning-dedup, inactivity watchdog, stale-session guard (`config_hash` = `opencode_server|<model>`, excludes the ephemeral port so cross-restart resume survives). Hard-won: opencode streams `session.next.*` (not `message.part.*`), `event.subscribe()` must pass the worktree `directory`, models must be `llama-swap/`-prefixed + in opencode's config. Bundled: dcp-message-id strip, reopen-pane control, `[+]`/split separation, auto-name on session model, `systematic-debugging` slash command. Known limit (closed in v2.6.2): single SSE scoped to the most-recent directory
+- `v2.6.2-delete-guard-and-sse` — session-delete work-loss guard (server gates `DELETE /api/sessions/:id`: reads `session_worktrees`, calls BooCoder `/worktree-risk` which runs git on the host; dirty/unpushed/unmerged → 409 + per-worktree `RiskReport[]`, `force` bypasses, fail-closed; sidebar block dialog distinguishes at-risk from couldn't-verify, never auto-commits). **Per-session SSE (P1.5-a):** one `event.subscribe({directory})` per live opencode session, each with an `AbortController`, so sessions in different worktrees stream concurrently (was: second silently dropped); `sessionID` demux guard + zombie-loop fix
+- `v2.6.3-chatkey-and-skills` — re-key `agent_sessions` to **`(chat_id, agent)`** (P1.5-b: the tab/chat is the agent-context unit; two opencode tabs in one session = two contexts sharing one worktree); `tasks.chat_id` threaded end-to-end (`runOpenCodeServerTask` resolve-or-creates a chat for session-less creators); first-class `worktrees` table (one-per-session, survives session delete) supersedes the defanged `session_worktrees`; `agent_sessions.chat_id` CASCADEs from `chats`; stateful cross-chunk dcp-message-id stripper; `committing-changes` + `using-worktrees` judgment skills in `data/skills/boocode/` + parser-safe `data/AGENTS.md` preamble
+- `v2.6.4-agent-sessions-fk` — converge the live `agent_sessions.session_id` FK `CASCADE → SET NULL` (standalone `confdeltype`-guarded `DO` block, idempotent — the P1.5-b re-key gate skipped already-re-keyed DBs and left it diverged); CLAUDE.md doc-sync (per-session SSE, `(chat_id, agent)` re-key, `data/AGENTS.md` parsing + `data/skills/<vendor>/` conventions)
+- `v2.6.5-panes-tabs-composer` — **workspace UX batch (BooChat panes/tabs/composer + the persistence that backs it).** *Panes/tabs:* open a chat in a fresh pane (ChatTabBar "Open in new pane" + fork-beside-original via a new `open_chat_in_new_pane` event), per-pane `[+]` → New BooChat/BooTerm/BooCode menu, closing a chat pane relocates its tabs (in order) to the oldest chat/empty pane (reopen strips restored chatIds from every live pane first → no dup), stable session-scoped tab numbers (assigned on open, retired on close, never reused, map-keyed render), and the empty/landing pane became a real session history (open + separately-fetched archived chats). Removed the per-message "Open in pane" artifact button. *Persistence:* `sessions.workspace_panes` widened from bare `WorkspacePane[]` → a `WorkspaceState` envelope (`panes` + `tabNumbers`/`nextTabNumber` + `closedPaneStack`); PATCH validator zod-unions legacy-array-or-envelope and migrates on write; `session_workspace_updated` WS frame widened (web+server byte-identical, parity test green). *Composer:* morphing **Send → Stop → Queue** button keyed on `sending || activeTaskId` (folds in the standalone Stop pill, adds `cancelTask`); pasted chips trail the typed text so a leading slash stays first. *Tooling:* new read-only `read_tab_by_number` tool + an optional `ToolExecCtx` (`{ sql, sessionId }`) 4th arg on `ToolDef.execute`
+- `v2.6.6-claude-md` — docs-only CLAUDE.md session-learnings from the v2.6.5 batch: the `WorkspaceState` envelope migration, the `ToolExecCtx` plumb (`read_tab_by_number` as reference), the two-schema-files-one-DB ownership split + idempotent `confdeltype` FK-action-flip pattern, and React-StrictMode nested-`setState` idempotency
+- `v2.6.7-interrupt-guard` — **F.1 fix:** post-interrupt stale-terminal bug in the opencode warm-server backend (one-click reachable since `v2.6.5`'s Stop button). opencode emits one trailing `session.idle`/`session.error` for a cancelled turn (sessionID only, no turn id) that settled the *next* turn early as success. Pure per-session guard (`backends/turn-guard.ts` — arm-on-abort / swallow-one-orphan / self-heal-on-activity) wired into `opencode-server.ts`; 3 regression tests (TDD). First item of the v2.6 openspec "remaining" plan; Phase 1-UX / 2 / 3 still open
+- `v2.6.8-agent-attribution` — **v2.6 Phase 1-UX** (U.1–U.6), built by 3 parallel subagents over disjoint files. Backend: `pending_changes.agent` stamped at every queue site + flows through `listPending`; new `GET /api/sessions/:id/agent-sessions` route; opencode warm-server consumes `session.next.step.ended` → accumulates `input_tokens`/`output_tokens`/`cost` on `agent_sessions`. Frontend: DiffPanel per-row agent badges + multi-agent note; AgentComposerBar resumed/history/new-session chip (gated on optional `sessionId`, BooChat unaffected); shared `providerIcons.tsx` + `useAgentSessions` hook. 9 new tests; web+coder tsc clean. Both surfaces deployed (boocoder restart + `boocode` Docker rebuild). Phase 2/3 remain
+- `v2.6.9-warm-acp` — **v2.6 Phase 2:** goose/qwen run as **warm ACP backends** (one persistent `goose acp`/`qwen --acp` child + `ClientSideConnection` + ACP session per `(chat,agent)`, `initialize`+`session/new` once, reused across turns) instead of one-shot. New `WarmAcpBackend` (same `AgentBackend` interface as opencode); abort = `session/cancel` the prompt only (never kills the child); dispatcher routes goose/qwen chat-tab tasks via pure `shouldUseWarmBackend` (one-shot fallback kept for arena/MCP/`new_task`); `handleSessionUpdate` extracted to a shared pure `acp-event-map.ts` (one-shot path byte-identical). SDK concern resolved (`@agentclientprotocol/sdk@^0.22.1` has stable resume; moot warm, deferred to Phase 3). 15 new tests, 180 coder tests pass. Backend-only deploy (boocoder restart). **Smoke 2/2b pending live.** Phase 3 (lifecycle hardening) is the last v2.6 phase
+- `v2.6.10-lifecycle-hardening` — **v2.6 Phase 3 (final phase — completes v2.6).** Idle TTL eviction (`AGENT_POOL_IDLE_TTL_MS`=30min) + LRU cap (`AGENT_POOL_MAX_LIVE`=10), busy backends never evicted; pure `lifecycle-decisions.ts`. Crash recovery via openchamber's health-monitor + busy-aware-restart + stale-grace state machine in `opencode-server.ts` (+ port reclaim) + `warm-acp.ts` (opencode → fresh sessions; ACP → re-`session/new`; F.1 guard + U.6 usage preserved). Orphan worktree reaper (1h grace, superset-style dirty/unpushed preflight, Paseo soft-delete) + close hooks + re-baseline after apply. 35 new tests + DB-opt-in reconnect test; 215 coder tests pass. Backend-only deploy. **Follow-ups (out of v2.6 scope): apps/server close-hook caller, 3.7 DiffPanel staging hint (frontend), live Smoke 2/2b/3.** With this, **v2.6 persistent agent sessions is complete** (Phase 0–3 + F.1 + Phase 1-UX)
+
+-----
+
 ## v2.3 — Provider lifecycle (Paseo-style registry)
 
-**Planned.** Config-backed provider registry (`/data/coder-providers.json`), merged built-ins + overrides, enable/disable toggles, two-tier probe (fast binary vs slow ACP session), generic ACP spawn from config without new code paths. Depends on v2.2 snapshot wire shape. Openspec: `openspec/changes/v2-3-provider-lifecycle/`. See `CURRENT.md`.
+**Shipped across `v2.5.4`–`v2.5.13` (5 phases, 2026-05-29).** Config-backed provider registry (`data/coder-providers.json`), merged built-ins + overrides, enable/disable toggles in Settings → Providers, two-tier probe (fast binary vs slow ACP session, TTL-gated), generic ACP spawn from config without new code paths, HTTP config/refresh/diagnostic API, curated add-from-catalog. The milestone shipped under v2.5.x patch tags (not "v2.3.x") because patch numbers are assigned at ship time. Openspec: `openspec/changes/v2-3-provider-lifecycle/` (design §2–§6 map to phases 1–4; phase 5 = UI). `docs/DEFERRED-WORK.md` §2 marked addressed; Tier-2 follow-ups (WS `provider_snapshot_updated` frame, `available_agents.enabled` column, shared types package, MCP provider tools) stay deferred.
 
 **Lift source:** Paseo provider docs (design only — no AGPL code lift).
 
@@ -360,6 +400,8 @@ Per-session Docker sandbox spawned by BooCoder on first write. Only project path
 
 ## v2.4 — BooCoder as ACP agent (driveable from external editors)
 
+**Status: not shipped.** This is a conceptual milestone, not yet built. The `v2.4.0`/`v2.4.1` *patch tags* shipped unrelated content (Unsloth Studio parser/HTML-to-md lift, llama-sidecar routing) — patch numbers are assigned at ship time and have outrun the milestone plan. The outbound ACP-agent surface below is still future work.
+
 **Goal:** expose `boocoder acp` so Zed, JetBrains, Avante.nvim, CodeCompanion.nvim can drive BooCoder as their agent. Outbound exposure of the BooCoder write-tool surface to ACP-compatible editors.
 
 **Scope:**
@@ -378,6 +420,78 @@ Per-session Docker sandbox spawned by BooCoder on first write. Only project path
 
 -----
 
+## v2.6 — Persistent agent sessions (warm processes + OpenCode server)
+
+**Goal:** make a BooCode chat map to a **persistent agent backend + a persistent worktree** that live for the whole conversation, so turns are warm and the agent sees its own accumulating edits. Replaces the one-shot-per-task model (fresh worktree + process spawn + ACP handshake every turn) with Paseo's pattern: OpenCode as a long-lived HTTP server, goose/qwen as warm stdio-ACP processes. Reasoning passthrough was already solved in v2.5.2's Thinking block — this batch is about persistence, not capability.
+
+**Decisions locked:** persistent worktree per session (shared across agents); free agent-switch with per-agent memory (one backend session per `(chat, agent)` pair, re-keyed from `(session, agent)` in P1.5-b); OpenCode → one shared `opencode serve` HTTP server (multi-session, directory-routed); goose/qwen → warm stdio ACP per live session; claude stays one-shot PTY.
+
+**Shipped so far:**
+
+1. `v2.6.0-phase0-foundations` ✅ — schema + `AgentBackend`/`AgentEvent` interface scaffold (no behavior change).
+1. `v2.6.1-phase1-opencode` ✅ — OpenCode warm-server backend, per-chat resumable session, SSE demux, reasoning dedup, watchdog, stale-session guard.
+1. `v2.6.2-delete-guard-and-sse` ✅ — session-delete work-loss guard + **per-session SSE (P1.5-a)** so concurrent opencode sessions in different worktrees stream independently.
+1. `v2.6.3-chatkey-and-skills` ✅ — **P1.5-b** re-key `agent_sessions` to `(chat_id, agent)`; first-class `worktrees` table; `tasks.chat_id` threading; cross-chunk dcp-strip; judgment skills.
+1. `v2.6.4-agent-sessions-fk` ✅ — converge `agent_sessions.session_id` FK to `SET NULL`; doc-sync.
+
+**Remaining (per openspec `v2-6-persistent-agent-sessions/tasks.md`):**
+
+- **Phase 1 UX** — DiffPanel per-change agent attribution (`pending_changes.agent` badges), resumed/new-session chip on AgentComposerBar (`GET /api/sessions/:id/agent-sessions`), staging-boundary hint.
+- **Phase 2 — warm ACP backend (goose, qwen)** — persistent `SpawnedACPProcess` connection reused across turns (one `session/new`, many prompts); dispatcher routes goose/qwen to the warm backend; switch round-trip smoke (opencode → boocode → opencode resumes the same session). **De-risked (v2 review, 2026-05-31):** `qwen --acp` is a real stdio multi-session agent (`Map<sessionId,Session>`, `loadSession`/`resume`, mid-session model/mode switch) — the old "qwen ACP was HTTP-only → use PTY" premise is **stale**, so wire qwen into the existing `acp-dispatch.ts` stack. Cross-check qwen's `@agentclientprotocol/sdk@^0.14` vs BooCode's `^0.22` handshake before relying on `unstable_resumeSession`. Separately, qwen's one-shot PTY fallback emits Claude-Code-compatible `stream-json` NDJSON (today sliced opaque in `dispatcher.ts`) — **one parser serves both qwen and claude** PTY fallbacks.
+- **Phase 3 — lifecycle hardening** — idle TTL eviction per `(chat, agent)`, crash recovery, chat-close/archive worktree cleanup, orphan reaper + max-live-worktrees LRU cap, re-baseline diff after `apply_pending`, reconnect test. **Primary reference (v2 review, 2026-05-31): `openchamber` (MIT, same warm-opencode-server architecture — code-liftable)** — health-monitor + crash auto-restart + busy-aware restart + port reclaim (`killProcessOnPort`/`waitForPortRelease`) + stall-detecting SSE reader; **supersedes the Paseo "re-derive"** (paseo's lazy restart-on-demand has no active supervision). Also confirms the deferred `OPENCODE_SERVER_PASSWORD` scheme = `Authorization: Basic base64("opencode:"+pw)`.
+
+**Lift sources:** `getpaseo/paseo` (design only — OpenCode-as-HTTP-server pattern, `streamedPartKeys` reasoning dedup), `@opencode-ai/sdk` (v2 client), `/opt/forks/opencode`; **`openchamber` (MIT — Phase 3 lifecycle hardening, code-liftable)**; **`QwenLM/qwen-code` (Apache-2.0 — `qwen --acp` reference + `stream-json` schema)**. See `boocode_code_review_v2.md` §5a/§5f for evidence.
+
+**Dependencies:** v2.2 (ACP dispatch) + v2.3 provider lifecycle (registry/snapshot). Openspec: `openspec/changes/v2-6-persistent-agent-sessions/`.
+
+-----
+
+## License-debt — relicense AGPL-3.0 → MIT (planned)
+
+**Status: planned, not started.** Recorded 2026-05-31 from the v2 external review (`boocode_code_review_v2.md` §5k) + a direct tree audit. **Decision (Sam, 2026-05-31): relicense the project back to MIT.**
+
+**Current state (the problem):** the tree is **currently AGPL-3.0** — root `LICENSE` is GNU Affero GPL v3 and all five `package.json` declare `"license": "AGPL-3.0-only"`. Cause: the `v2.4.0`/`v2.4.1` Unsloth-Studio lifts pulled in AGPL-3.0-only code, which makes the whole network-served work AGPL-encumbered. This batch clears that so the MIT flip is valid; **nothing else AGPL remains once these files are gone.**
+
+**The three AGPL-3.0-only files to clear** (each `SPDX-License-Identifier: AGPL-3.0-only`, ported from Unsloth Studio):
+1. `apps/server/src/services/inference/tool-call-parser.ts` (← `tool_call_parser.py`) — remove by routing tool-call parsing to **native llama-server** template parsing + a **clean-room `<invoke>`-only fallback** (no Unsloth provenance).
+2. `apps/server/src/services/web/html-to-md.ts` (← `_html_to_md.py`, used by `web_fetch`) — replace with a permissively-licensed library (`turndown` / `node-html-markdown`) or a clean-room walker.
+3. `apps/server/src/services/inference/llama-args-validator.ts` (← `llama_server_args.py`, the v2.4.1 sidecar flag-denylist) — clean-room rewrite from the llama-server README flag list (the denylist is facts, not copyrightable).
+
+**Steps:**
+1. Confirm native llama-server tool-parsing on **live qwen3.6** (jinja gate already green — `--jinja` + qwen3.x template live; llama.cpp server-side template parser, v2 review §4a).
+2. Run native parsing **behind a flag for one release** (qwen3.6 was historically unreliable — validate before deleting).
+3. **Delete** the ~250 Unsloth-derived parser lines + clean-room the `<invoke>` fallback; replace `html-to-md.ts`; clean-room `llama-args-validator.ts`.
+4. **Flip the license:** root `LICENSE` AGPL→MIT, the five `package.json` `license` fields `AGPL-3.0-only`→`MIT`, remove the per-file AGPL SPDX headers, and update roadmap/README prose. After this, **no AGPL remains in the tree** and the "BooCode is MIT" claim becomes true.
+
+**Source:** `boocode_code_review_v2.md` §1 #1, §5k. **Prerequisite for the license flip — this batch is the blocker, not optional.**
+
+-----
+
+## Write/edit robustness (planned)
+
+**Status: planned, not started.** From the v2 review (`boocode_code_review_v2.md` §5b; `cline/cline`, Apache-2.0 — code-liftable). Two lifts that harden BooCoder's write surface where it's weakest for local quantized models:
+
+1. **Fuzzy patch applier for `edit_file`.** BooCoder's `edit_file` is exact-match today (`apps/coder/src/services/pending_changes.ts` — `if (!content.includes(oldStr)) throw`; no whitespace/unicode tolerance, no multi-occurrence guard). Lift cline's tiered match ladder (exact → `trimEnd` → `trim` → Levenshtein ≥0.66) + unicode canonicalization (dashes, curly quotes, nbsp) + multi-occurrence guard; unmatched → warning, not throw. `apply-patch-parser.ts:347-431`.
+2. **`git stash create` + private-ref checkpoint.** A per-turn workspace snapshot that captures **all** state — including edits made by dispatched external agents (opencode/claude/qwen/goose), build artifacts, test side-effects — which BooCoder's current `rewind` cannot (it only reverse-applies BooCoder's own queued `pending_changes`). Snapshot stored under a private `refs/…/checkpoints/…` ref, restorable with conversation-trim in sync. `checkpoint-hooks.ts:177-253`.
+
+**Source:** `boocode_code_review_v2.md` §1 #3–#4, §5b.
+
+-----
+
+## Claude provider — SDK transport + native session resume (planned)
+
+**Status: planned, not started.** From the v2 review (`boocode_code_review_v2.md` §5h–§5i) + a direct read of the published SDK `.d.ts` (`@anthropic-ai/claude-agent-sdk@0.3.158`, reviewed 2026-05-31). Today BooCoder dispatches `claude` one-shot via PTY (`claude --output-format stream-json`) with no continuity. Plan:
+
+1. **Adopt the Agent SDK** (`@anthropic-ai/claude-agent-sdk`) over the PTY path. `query({ prompt, options })` yields structured `SDKMessage`s — `SDKSystemMessage` (`subtype:'init'`, carries the session id + tool/skill/mcp lists), `SDKPartialAssistantMessage` (`type:'stream_event'` deltas), `SDKResultMessage` (turn end) — no stdout scraping. `happy` (`slopus/happy`) is the working existence-proof.
+2. **Native session resume via a pluggable `SessionStore`.** Implement `PostgresSessionStore implements SessionStore` (5 methods: `append`/`load`/`listSessions`/`delete`/`listSubkeys`) over BooCode's Postgres, keyed by `(chat_id, agent)`; drive turns with `query({ options: { sessionStore, resume } })` and the SDK materializes the stored session for the CLI subprocess. **This supersedes happy's SessionStart-hook + jsonl-watcher** — that was a workaround predating the feature (happy pins SDK `^0.2.96`; the `SessionStore` API is `0.3.x`). `importSessionToStore()` migrates an existing local session; `InMemorySessionStore` is the reference shape.
+3. **Permissions:** wire BooCoder's permission cards to the SDK's `canUseTool(toolName, input, opts) → Promise<PermissionResult>` callback (one chokepoint, supports `permissionMode`) instead of parsing PTY permission prompts.
+
+**License posture (reference-only):** `@anthropic-ai/claude-agent-sdk` is under **Anthropic Commercial Terms** (`package.json` `license: "SEE LICENSE IN README.md"`), **not OSS** — acceptable as a runtime **dependency** (same posture as already shelling out to the `claude` CLI), but its source/examples (incl. GitHub `examples/session-stores/postgres`) are **reference-only — do not vendor**, especially mid AGPL→MIT cleanup (relicense batch). Readable references on disk: `/opt/forks/claude-agent-sdk-python` (MIT mirror) + `/opt/forks/claude-agent-sdk-typescript` (examples, commercial terms).
+
+**Source:** `boocode_code_review_v2.md` §1 #9, §5h–§5i. Refines the v2.6 "claude stays one-shot PTY" assumption on the continuity dimension.
+
+-----
+
 ## v2.1.0 — Provider picker + model discovery
 
 **Shipped `v2.1.0-provider-picker`.** Provider registry with 5 providers (boocode, opencode, goose, claude, qwen). Model discovery via `LLAMA_SWAP_URL/upstream/<model>/props`. `/api/providers` route returns installed providers with models. v2.1 `ProviderPicker` UI **superseded by `AgentComposerBar` in v2.2.** Agent-probe startup probe discovers installed agents on host, their versions, ACP support, and models. Booterm SSH host configurable via `BOOTERM_SSH_HOST`/`BOOTERM_SSH_USER` env vars.
@@ -412,7 +526,7 @@ Per-session Docker sandbox spawned by BooCoder on first write. Only project path
 |-------------------------------|---------------------|-----------------------------|------------------------------------------------------------------------|----------------------|
 |`boochat` (was `boocode`)      |`100.114.205.53:9500`|`/opt:/opt:ro`               |Read-only chat + SPA host + MCP client                                  |Live (renames at v2.0)|
 |`booterm`                      |`100.114.205.53:9501`|`/opt:/opt`                  |PTY/tmux terminal sessions                                              |**Live (May 2026)**   |
-|`boocoder` (host systemd)       |`100.114.205.53:9502`|full host FS (policy-gated)  |Write tools + ACP client + MCP client + MCP server + external-CLI dispatch|**Shipped v2.0.0–v2.2.1** (systemd since v2.1.0) |
+|`boocoder` (host systemd)       |`100.114.205.53:9502`|full host FS (policy-gated)  |Write tools + ACP client + MCP client + MCP server + external-CLI dispatch + warm opencode server|**Shipped v2.0.0–v2.6.6** (systemd since v2.1.0) |
 |**`boochat`** (Docker service `boocode_db`)|`127.0.0.1:5500`     |`boocode_pgdata` volume      |Postgres 16-alpine (shared by all three)                                |**Live** (DB renamed from `boocode` at v2.0)|
 |`codecontext`                  |`:8080` (internal, Docker network)   |`/opt:/opt:ro`|Go HTTP sidecar for code graph tools                                          |**Live (v1.12.0)**    |
 
@@ -459,7 +573,12 @@ term.indifferentketchup.com         → booterm   :9501   (or routed under code.
 - **v1.16:** `repo_health_cache (project_id, file_hashes_sig, payload JSONB, created_at)`
 - **v2.0 (shipped):** `pending_changes`, `tasks`, `available_agents`, `human_inbox` view; database renamed `boocode` → `boochat`
 - **v2.2 (shipped):** none (provider snapshot + ACP dispatch are runtime/services; pane chat scoping uses existing `sessions.workspace_panes` + `chats`)
-- **v2.4:** none (`boocoder acp` is a new entry point, not a schema change)
+- **v2.5.0 (shipped):** `sessions.tags` column (task-model tagging)
+- **v2.5.10 (shipped):** `available_agents.commands jsonb` column (persisted ACP `available_commands`)
+- **v2.6.0 (shipped):** `session_worktrees` (one shared worktree per session) + `agent_sessions` (one backend session per `(session, agent)`, `backend`/`status` CHECKs) tables; `pending_changes.agent` attribution column. All idempotent (`IF NOT EXISTS`)
+- **v2.6.3 (shipped):** re-key `agent_sessions` to `(chat_id, agent)` (`chat_id` FK CASCADEs from `chats`; `session_id`/`worktree_id` informational); new first-class `worktrees` table (one-per-session, `session_id` `SET NULL`) supersedes the defanged `session_worktrees`; `tasks.chat_id` column
+- **v2.6.4 (shipped):** `agent_sessions.session_id` FK converged `CASCADE → SET NULL` (standalone `confdeltype`-guarded `DO` block; idempotent)
+- **v2.4 (planned, not shipped):** none (`boocoder acp` is a new entry point, not a schema change)
 
 -----
 
@@ -494,8 +613,9 @@ Full inventory and rationale in `boocode_code_review.md`. Headline items below;
 |`spirituslab/codesight`                                                         |MIT-ish                                 |Repo health analyzer (`analyze.mjs`)                                                                                      |v1.16                                         |
 |`plandex-ai/plandex`                                                            |MIT                                     |Pending-changes data model + diff/apply/rewind UX                                                                         |v2.0                                          |
 |`Dominic789654/agent-hub`                                                       |Apache-2.0                              |**Task DAG schema, dispatcher worker, project registry, human inbox** — primary architectural template for v2.0 dispatcher|v2.0                                          |
-|`getpaseo/paseo`                                                                |AGPL-3.0 (**design only, no code lift**)|Daemon+clients arch, CLI verb shape, –worktree flag, provider snapshot/dispatch patterns                                  |**v2.2 (shipped)** / v2.x                                   |
+|`getpaseo/paseo`                                                                |AGPL-3.0 (**design only, no code lift**)|Daemon+clients arch, CLI verb shape, –worktree flag, provider snapshot/dispatch, OpenCode-as-HTTP-server + reasoning dedup |**v2.2, v2.6 (shipped)** / v2.x              |
-|**`agentclientprotocol.com` spec + `@zed-industries/agent-client-protocol` SDK**|**Apache-2.0**                          |**ACP client (host) — replaces raw-PTY dispatch for opencode/goose/cursor**                                               |**v2.0 → v2.2**                                      |
+|**`@opencode-ai/sdk`**                                                          |**MIT**                                 |**OpenCode warm HTTP server client (`opencode serve`, SSE `session.next.*`, multi-session)**                              |**v2.6.1 (shipped)**                          |
+|**`agentclientprotocol.com` spec + `@agentclientprotocol/sdk@^0.22.1`**|**Apache-2.0**                          |**ACP client (host) — replaces raw-PTY dispatch for opencode/goose (cursor retired v2.5.3)**                              |**v2.0 → v2.2**                                      |
 |**anthropics/skills `mcp-builder`**                                             |**MIT**                                 |**MCP server build workflow + 10-question evaluation framework**                                                          |**v2.0 (BooCoder MCP server)**                |
 |**`zed-industries/codex-acp`**                                                  |**Apache-2.0**                          |**ACP server-side reference for `boocoder acp`**                                                                          |**v2.4**                                      |
 |Roo Code: Boomerang Tasks                                                       |Apache-2.0 (pattern only)               |Orchestrator capability restriction + down-pass/up-pass context discipline                                                |v1.14 (AGENTS.md) → v2.0 (real delegation)    |
@@ -547,14 +667,14 @@ Full inventory and rationale in `boocode_code_review.md`. Headline items below;
 
 ### Strategic pivot: Paseo-equivalent dispatcher (2026-05-22, **shipped v2.2**)
 
-Sam wanted BooCode to function like Paseo without using Paseo itself. **Paseo is AGPL-3.0** — incompatible with BooCode's MIT license and its network-served deployment at `code.indifferentketchup.com`. Solution: **reproduce the architecture in BooCode's existing Fastify + TS + PostgreSQL + React stack, using only license-clean patterns**.
+Sam wanted BooCode to function like Paseo without using Paseo itself. **Paseo is AGPL-3.0** — incompatible with BooCode's **target** MIT license and its network-served deployment at `code.indifferentketchup.com`. Solution: **reproduce the architecture in BooCode's existing Fastify + TS + PostgreSQL + React stack, using only license-clean patterns**. **Reality check (2026-05-31):** the no-AGPL-code-lift rule was later broken by the `v2.4.0`/`v2.4.1` Unsloth-Studio lifts, which put the whole tree under AGPL-3.0 (root `LICENSE` + all five `package.json` are `AGPL-3.0-only` today). The **License-debt → relicense to MIT** batch restores the MIT target.
 
 - **Primary architectural template:** `Dominic789654/agent-hub` (Apache-2.0) — three-process model (board server + dispatcher + assistant terminal) and schema (tasks/projects/templates/pipelines/human_inbox).
 - **Critical context-management primitive:** Roo Code Boomerang Tasks pattern — orchestrator with intentional capability restriction, down-pass/up-pass context discipline, no implicit inheritance.
 - **Observation pattern:** Claude Code hooks (siropkin/budi reference) — register BooCode as the hook receiver for `SessionStart`/`UserPromptSubmit`/`PostToolUse`/`SubagentStart`/`Stop`.
 - **Protocol-level Paseo equivalence (shipped v2.2):** the ACP client + MCP server combination in BooCoder is the protocol-spelled version of Paseo's daemon. ACP gives multi-agent dispatch with structured events instead of free-form PTY output. MCP server gives BooCoder-as-task-board, callable from any MCP client (Termius-based opencode, future editors). One MCP config feeds every dispatched agent (via `context_servers` auto-forward). v2.2 added provider snapshot, mode/thinking, permission prompts, and Paseo-style stream/persist.
 
-**Next on this track:** v2.3 provider lifecycle (config-backed registry, enable/disable, two-tier probe). See openspec `v2-3-provider-lifecycle`.
+**Next on this track:** v2.3 provider lifecycle shipped (`v2.5.4`–`v2.5.13`); the live frontier is **v2.6 persistent agent sessions** — Phase 0/1 + P1.5-a/b shipped (`v2.6.0`–`v2.6.4`), Phase 2 (warm ACP for goose/qwen) + Phase 3 (lifecycle hardening) remain. See openspec `v2-6-persistent-agent-sessions`.
 
 ### BooCoder execution: both Option A AND Option B, full-featured (2026-05-22)
 
@@ -575,9 +695,20 @@ The v1.13.x cleanup line shipped 21 batches over a single intense window in `vMA
 - **v2.2-paseo-providers** ✅ — 7-provider snapshot, `AgentComposerBar`, ACP dispatch rewrite, permission prompts, agent commands, cursor/copilot providers
 - **v2.2.1-pane-scoped-chats** ✅ — pane-scoped chat resolution, `CoderMessageList` tool UI, WS user-delta fix, inference orphan tool_call stripping
 
+### v2.2.2–v2.6 shipped (2026-05-26 → 2026-05-31)
+
+Full per-tag detail in the **Shipped (v2.2.2–v2.6.6)** section above and in `CHANGELOG.md`. Threads:
+
+- **Interactive ACP** (`v2.2.2`–`v2.3.2`) ✅ — placeholder-XML reject; per-agent sampling params; `ask_user_input` cards in both BooCoder frontends; enriched `permission_requested` frame (question/plan/elicitation) with interactive PermissionCard; coder `answer_user_input` endpoint fix.
+- **Unsloth lift + sidecar + task model** (`v2.4.0`–`v2.5.1`) ✅ — Unsloth Studio `tool-call-parser.ts` (replaces `xml-parser.ts`) + parse5 `html-to-md.ts` + `llama-args-validator.ts` (**all three AGPL-3.0-only — this is what relicensed the whole tree to AGPL-3.0**); llama-sidecar per-agent-flags routing; dedicated task-model services; tool budgets → 100/100/100. **→ removal tracked in the License-debt → relicense to MIT batch.**
+- **Provider lifecycle = the planned "v2.3"** (`v2.5.3`–`v2.5.15`) ✅ — cursor/copilot retired; config-backed registry + snapshot lifecycle + two-tier probe (phases 1–5); empty-picker fix; claude model list; mobile composer; per-agent + claude/opencode slash-command discovery; ACP path-guard security fix.
+- **v2.6 persistent agent sessions** (`v2.6.0`–`v2.6.4`) ✅ Phase 0/1 + P1.5-a/b — foundations scaffold; opencode warm HTTP server with per-chat resumable sessions; session-delete work-loss guard; per-session SSE; `(chat_id, agent)` re-key + `worktrees` table; FK convergence.
+- **Workspace UX + composer** (`v2.6.5`–`v2.6.6`) ✅ — BooChat panes/tabs overhaul (open-in-new-pane, `[+]` New BooChat/BooTerm/BooCode menu, tab relocation, stable tab numbers, session-history landing pane); `workspace_panes` → `WorkspaceState` envelope; morphing Send→Stop→Queue composer + `cancelTask`; `read_tab_by_number` tool + `ToolExecCtx`; CLAUDE.md doc-sync. (This is the work the earlier draft listed as "uncommitted frontend UX" — now shipped.)
+
 ### In flight
 
-- **v2.3-provider-lifecycle** — config-backed provider registry, enable/disable, two-tier probe (openspec drafted; not started). See `CURRENT.md`.
+- **License-debt → relicense AGPL-3.0 → MIT** — see the planned batch above; the tree is currently AGPL-3.0 and three Unsloth-derived files must be cleared before the MIT flip. Prerequisite, blocker-status.
+- **v2.6 persistent agent sessions — Phase 2/3** — warm ACP backend for goose/qwen (persistent process reused across turns) + lifecycle hardening (idle eviction, crash recovery, worktree cleanup/reaper, post-apply re-baseline) + the Phase-1 UX attribution work (DiffPanel agent badges, resumed/new-session chip). See openspec `v2-6-persistent-agent-sessions/tasks.md`.
 
 ### Numbering and scope-revision discipline during v1.13.x (2026-05-23)
 

openspec/changes/v2-3-provider-lifecycle/design.md

@@ -2,6 +2,8 @@
 
 Detailed implementation plan for Paseo-style provider registration, readiness probing, and enable/disable toggles in BooCoder.
 
+> **✅ Shipped 2026-05-29 across `v2.5.4`–`v2.5.13` (reconciled 2026-05-31).** All 6 phases live. As-built deltas: the diagnostic ships as JSON `{ diagnostic: string }` (§6) rather than a plaintext HTTP body (§8's framing); the provider-management UI landed as a **Settings → Providers tab** (the §7.1 "or section under existing settings" path), not a standalone `ProviderSettingsDrawer`; `AddProviderModal` is at `apps/web/src/components/coder/`. **Deferred** (the §7.1 "optional phase 2" + tasks O.1–O.3): WS `provider_snapshot_updated` frame, `available_agents.enabled` column, diagnostic row-click modal — tracked in `docs/DEFERRED-WORK.md`.
+
 **Audience:** Sam + future agents implementing the batch.  
 **Paseo reference:** `/opt/forks/paseo/packages/server/src/server/agent/` (registry, snapshot manager, generic ACP), `/opt/forks/paseo/packages/app/src/screens/settings/providers-section.tsx` (UI behavior).
 

openspec/changes/v2-3-provider-lifecycle/proposal.md

@@ -1,10 +1,12 @@
 # v2.3 Provider lifecycle (Paseo-style registry)
 
-**Status:** Planned  
+**Status:** ✅ **Shipped** across `v2.5.4`–`v2.5.13` (2026-05-29; reconciled 2026-05-31) — all 6 phases live; only the 3 optional Tier-2 items deferred  
 **Depends on:** v2.2 Paseo providers (snapshot, modes, commands, ACP dispatch)  
 **Reference fork:** `/opt/forks/paseo`  
 **Related deferred work:** [`docs/DEFERRED-WORK.md`](../../../docs/DEFERRED-WORK.md) §2 (cold-probe skip)
 
+> **Shipped mapping (reconciled 2026-05-31):** Phase 1 → `v2.5.4`, Phase 2 → `v2.5.5`, Phase 3 → `v2.5.6`, Phase 4 → `v2.5.12`, Phase 5 → `v2.5.13`, Phase 6 docs → `v2.5.13`/`v2.5.14`. **Deferred (tasks O.1–O.3):** WS `provider_snapshot_updated` frame, `available_agents.enabled` column, diagnostic row-click modal — tracked in `docs/DEFERRED-WORK.md`. (Cursor was retired in `v2.5.3`, so the success-criterion mention below is historical.)
+
 ## Why
 
 BooCode v2.2 copied Paseo’s **snapshot wire shape** (modes, thinking, commands) but not Paseo’s **provider lifecycle**:
@@ -46,12 +48,12 @@ Paseo’s model (see `/opt/forks/paseo/public-docs/providers.md`) treats provide
 
 ## Success criteria
 
-- Add `amp-acp` via catalog → appears in picker after refresh without coder redeploy
+- ✅ Add `amp-acp` via catalog → appears in picker after refresh without coder redeploy *(catalog smoke-test entry; per `boocode_code_review_v2.md` §5m, Amp itself is paid-cloud, not a usable local provider)*
-- Disable goose in settings → gone from picker, still visible as “Disabled” in settings
+- ✅ Disable goose in settings → gone from picker, still visible as “Disabled” in settings
-- opencode not on PATH → shows “Not installed” in settings, hidden from picker
+- ✅ opencode not on PATH → shows “Not installed” in settings, hidden from picker
-- Second snapshot open within warm window completes in <500ms (no ACP spawns)
+- ✅ Second snapshot open within warm window completes in <500ms (no ACP spawns)
-- `POST /api/providers/refresh` still runs full cold probe
+- ✅ `POST /api/providers/refresh` still runs full cold probe
-- Existing v2.2 dispatch (cursor, opencode, claude, qwen) unchanged for built-ins
+- ✅ Existing v2.2 dispatch unchanged for built-ins *(opencode, claude, qwen, goose — cursor + copilot retired `v2.5.3`)*
 
 ## Deliverables
 

openspec/changes/v2-3-provider-lifecycle/tasks.md

@@ -2,70 +2,68 @@
 
 Implement in phase order from [`design.md`](./design.md). Do not commit unless Sam asks.
 
-## Phase 1 — Config + registry
+> **✅ SHIPPED across `v2.5.4`–`v2.5.13` (reconciled 2026-05-31).** All 6 phases done; the 3 Optional items (O.1–O.3) deferred (tracked in `docs/DEFERRED-WORK.md`). Verified in tree: `provider-config.ts`, `provider-config-registry.ts`, `command-availability.ts`, `provider-diagnostic.ts`, `acp-provider-catalog.ts`, `components/coder/AddProviderModal.tsx`, Settings→Providers tab.
 
-- [ ] 1.1 Add `CODER_PROVIDERS_PATH` to `apps/coder/src/config.ts` (default `/data/coder-providers.json`)
+## Phase 1 — Config + registry — ✅ `v2.5.4-provider-lifecycle-phase1`
-- [ ] 1.2 Add `data/coder-providers.json` example + wire in `apps/coder/.env.host`
-- [ ] 1.3 Implement `provider-config.ts` (Zod schema + load/merge/save)
-- [ ] 1.4 Implement `provider-config-registry.ts` (`buildResolvedRegistry`, module singleton + reload)
-- [ ] 1.5 Unit tests: built-in override, custom ACP add, enabled false, invalid entry skipped
-- [ ] 1.6 Update `agent-probe.ts` to iterate resolved registry (include custom ids, respect enabled)
 
-## Phase 2 — Snapshot lifecycle
+- [x] 1.1 Add `CODER_PROVIDERS_PATH` to `apps/coder/src/config.ts` (default `/data/coder-providers.json`)
+- [x] 1.2 Add `data/coder-providers.json` example + wire in `apps/coder/.env.host`
+- [x] 1.3 Implement `provider-config.ts` (Zod schema + load/merge/save)
+- [x] 1.4 Implement `provider-config-registry.ts` (`buildResolvedRegistry`, module singleton + reload)
+- [x] 1.5 Unit tests: built-in override, custom ACP add, enabled false, invalid entry skipped
+- [x] 1.6 Update `agent-probe.ts` to iterate resolved registry (include custom ids, respect enabled)
 
-- [ ] 2.1 Extend `ProviderSnapshotEntry` / status union in coder + web types (`loading`, `unavailable`, `enabled`)
+## Phase 2 — Snapshot lifecycle — ✅ `v2.5.5-provider-lifecycle-phase2`
-- [ ] 2.2 Add `command-availability.ts` (`isCommandAvailable`)
-- [ ] 2.3 Rewrite `buildProviderEntry`: never return null; handle disabled/uninstalled/loading
-- [ ] 2.4 Implement tier-2 skip using `available_agents.last_probed_at` + `PROVIDER_PROBE_TTL_MS`
-- [ ] 2.5 Return `loading` entries synchronously on cache miss; complete via inflight promise
-- [ ] 2.6 Extend `provider-snapshot.test.ts` for disabled, uninstalled, fresh DB skip, force refresh
-- [ ] 2.7 Verify warm cache: second snapshot call does not invoke `probeAcpProvider` (mock assert)
 
-## Phase 3 — Generic dispatch
+- [x] 2.1 Extend `ProviderSnapshotEntry` / status union in coder + web types (`loading`, `unavailable`, `enabled`)
+- [x] 2.2 Add `command-availability.ts` (`isCommandAvailable`)
+- [x] 2.3 Rewrite `buildProviderEntry`: never return null; handle disabled/uninstalled/loading
+- [x] 2.4 Implement tier-2 skip using `available_agents.last_probed_at` + `PROVIDER_PROBE_TTL_MS`
+- [x] 2.5 Return `loading` entries synchronously on cache miss; complete via inflight promise *(client-side poll deferred to Phase 5; cache miss returns `loading` then settles)*
+- [x] 2.6 Extend `provider-snapshot.test.ts` for disabled, uninstalled, fresh DB skip, force refresh
+- [x] 2.7 Verify warm cache: second snapshot call does not invoke `probeAcpProvider` (mock assert)
 
-- [ ] 3.1 Add `resolveLaunchSpec()` to `acp-spawn.ts`
+## Phase 3 — Generic dispatch — ✅ `v2.5.6-provider-lifecycle-phase3`
-- [ ] 3.2 Wire `acp-dispatch.ts` to use launch spec + env merge
-- [ ] 3.3 Wire `dispatcher.ts` to load resolved def by agent name
-- [ ] 3.4 Unit test: custom command argv reaches spawn
-- [ ] 3.5 Smoke: task dispatch for one custom catalog provider (if installed on host)
 
-## Phase 4 — HTTP API
+- [x] 3.1 Add `resolveLaunchSpec()` to `acp-spawn.ts`
+- [x] 3.2 Wire `acp-dispatch.ts` to use launch spec + env merge
+- [x] 3.3 Wire `dispatcher.ts` to load resolved def by agent name
+- [x] 3.4 Unit test: custom command argv reaches spawn (built-in dispatch byte-identical)
+- [x] 3.5 Smoke: task dispatch for one custom catalog provider (if installed on host)
 
-- [ ] 4.1 `GET /api/providers/config`
+## Phase 4 — HTTP API — ✅ `v2.5.12-provider-lifecycle-phase4`
-- [ ] 4.2 `PATCH /api/providers/config` (merge + write file + reload registry + clear snapshot cache)
-- [ ] 4.3 `POST /api/providers/refresh` optional body `{ providers?: string[] }`
-- [ ] 4.4 `GET /api/providers/:id/diagnostic` (plaintext report)
-- [ ] 4.5 Extend `apps/web/src/api/client.ts` coder namespace
-- [ ] 4.6 Confirm BooChat proxy forwards new routes (or document direct :9502)
 
-## Phase 5 — Web UI
+- [x] 4.1 `GET /api/providers/config`
+- [x] 4.2 `PATCH /api/providers/config` (merge + write file + reload registry + clear snapshot cache)
+- [x] 4.3 `POST /api/providers/refresh` optional body `{ providers?: string[] }`
+- [x] 4.4 `GET /api/providers/:id/diagnostic` *(ships as JSON `{ diagnostic: string }`, not plaintext — see design §8 delta)*
+- [x] 4.5 Extend `apps/web/src/api/client.ts` coder namespace
+- [x] 4.6 Confirm BooChat proxy forwards new routes (blanket `/api/coder/*` forward)
 
-- [ ] 5.1 Create `apps/web/src/data/acp-provider-catalog.ts` (5–10 curated entries)
+## Phase 5 — Web UI — ✅ `v2.5.13-provider-lifecycle-phase5`
-- [ ] 5.2 `AddProviderModal.tsx` — search, install → patch + refresh subset
-- [ ] 5.3 `ProviderSettingsDrawer.tsx` — list, status, toggle, refresh, link to add
-- [ ] 5.4 Entry point from CoderPane / AgentComposerBar (gear or settings link)
-- [ ] 5.5 Filter `AgentComposerBar` selectable providers (`enabled && ready`)
-- [ ] 5.6 Loading state while snapshot entries `loading` (poll or one-shot refetch)
-- [ ] 5.7 `npx tsc -p apps/web/tsconfig.app.json --noEmit`
 
-## Phase 6 — Docs, deploy, closeout
+- [x] 5.1 Create `apps/web/src/data/acp-provider-catalog.ts` (5–10 curated entries)
+- [x] 5.2 `AddProviderModal.tsx` — search, install → patch + refresh subset *(at `components/coder/`)*
+- [x] 5.3 Provider management UI *(shipped as a **Settings → Providers tab** in `SettingsPane.tsx`, not a standalone `ProviderSettingsDrawer` — design §7.1 "or section under existing settings")*
+- [x] 5.4 Entry point from CoderPane / AgentComposerBar (gear or settings link)
+- [x] 5.5 Filter `AgentComposerBar` selectable providers (`enabled && ready|loading`)
+- [x] 5.6 Loading state while snapshot entries `loading`
+- [x] 5.7 `npx tsc -p apps/web/tsconfig.app.json --noEmit`
 
-- [ ] 6.1 `BOOCODER.md` — config file, refresh contract, enable/disable
+## Phase 6 — Docs, deploy, closeout — ✅ `v2.5.13` / docs `v2.5.14`
-- [ ] 6.2 Update `docs/DEFERRED-WORK.md` — mark tier-2 cold-probe item addressed
-- [ ] 6.3 `CHANGELOG.md` entry when tagged
-- [ ] 6.4 `pnpm -C apps/coder test && pnpm -C apps/coder build`
-- [ ] 6.5 `sudo systemctl restart boocoder`
-- [ ] 6.6 Smoke via Tailscale:
-  - `curl http://100.114.205.53:9502/api/providers/snapshot`
-  - PATCH disable goose → absent from composer, visible in settings
-  - POST refresh → models repopulate
-  - Add catalog entry → appears after refresh
 
-## Optional (same batch if time)
+- [x] 6.1 `BOOCODER.md` — config file, refresh contract, enable/disable
+- [x] 6.2 Update `docs/DEFERRED-WORK.md` — tier-2 cold-probe item marked addressed
+- [x] 6.3 `CHANGELOG.md` entries (per-phase tags, not a single tag)
+- [x] 6.4 `pnpm -C apps/coder test && pnpm -C apps/coder build`
+- [x] 6.5 `sudo systemctl restart boocoder`
+- [x] 6.6 Smoke via Tailscale (snapshot / disable goose / refresh / add-catalog)
 
-- [ ] O.1 WS frame `provider_snapshot_updated` (skip polling)
+## Optional — ⬜ DEFERRED (tracked in `docs/DEFERRED-WORK.md`)
-- [ ] O.2 `available_agents.enabled` column mirror
+
-- [ ] O.3 Diagnostic sheet UI (row click → modal)
+- [ ] O.1 WS frame `provider_snapshot_updated` (skip polling) — **deferred**; `AgentComposerBar:219` polls instead (comment notes the absence)
+- [ ] O.2 `available_agents.enabled` column mirror — **deferred**; `enabled` read from config memory only (no DB column)
+- [ ] O.3 Diagnostic sheet UI (row click → modal) — **deferred**; the plaintext/JSON diagnostic API + Settings surface shipped, the modal polish did not
 
 ## Explicitly out of scope
 

openspec/changes/v2-6-persistent-agent-sessions/design.md

@@ -3,6 +3,8 @@
 Reference implementations: `/opt/forks/opencode` (server + SDK),
 `/opt/forks/paseo` (warm ACP + opencode server-manager + reasoning dedup).
 
+> **⚠️ Reconciled 2026-05-31 — read the proposal's Reconciliation note first.** §2a and §3 describe the *original* design; four details were revised during implementation (per-session SSE; `(chat_id, agent)` key + `worktrees` table; `session.next.*` events; password deferred) — flagged inline. **Phases 2–3 and the Phase-1 UX (§2b, §6, §9) are not yet built**; updated lift sources for them are in new **§10**.
+
 ## 1. Architecture overview
 
 ```
@@ -47,6 +49,8 @@ interface AgentBackend {
 
 ### 2a. OpenCodeServerBackend (shared HTTP server)
 
+> **⚠️ Shipped deltas vs the bullets below:** (a) **per-session SSE** — one `event.subscribe({directory})` per live opencode session (P1.5-a, `v2.6.2`), NOT one global `/event` loop; (b) events are **`session.next.*`** (`text.delta`/`reasoning.delta`/`tool.{called,success,failed}`), NOT `message.part.*`; (c) **`OPENCODE_SERVER_PASSWORD` deferred** — server binds loopback unsecured.
+
 - **Spawn once per BooCoder process:** `opencode serve --hostname 127.0.0.1 --port <p>`
   with `OPENCODE_SERVER_PASSWORD=<random-at-boot>` (verified: `serve.ts`, `network.ts`;
   default port 4096, prints `opencode server listening on http://…`). Use the official
@@ -82,6 +86,8 @@ interface AgentBackend {
 
 ## 3. Data model
 
+> **⚠️ Shipped (P1.5-b, `v2.6.3`–`v2.6.4`):** `agent_sessions` is keyed **`(chat_id, agent)`** (the tab/chat is the agent-context unit; `chat_id` CASCADEs from `chats`), and a first-class **`worktrees`** table (one-per-session, survives session delete via `session_id` `SET NULL`) replaced `session_worktrees`. `tasks.chat_id` threads the tab id to the dispatcher. The SQL below is the original `(session_id, agent)` / `session_worktrees` shape — see `apps/coder/src/schema.sql` for the live DDL.
+
 Agent switching is **free** within a chat (the picker is per-turn, not locked), so
 the worktree is shared across agents but each agent keeps its own backend session.
 That splits into two tables: one **shared worktree per chat**, and one **backend
@@ -281,3 +287,12 @@ over the new `agent` column and `agent_sessions` — no dispatch-logic change.
   "opencode's edits live in its worktree — boocode won't see them until applied."
   Derived purely from per-change `agent` + current `value.provider`; no new state.
   Keeps the §3a staging caveat from biting silently.
+
+## 10. Lift sources for the remaining phases (added 2026-05-31)
+
+From the second external review (`boocode_code_review_v2.md`). These supersede/augment §2b, §6, §9 for the unbuilt work:
+
+- **Phase 2 (warm ACP, goose/qwen) — `qwen --acp` is a validated reference.** qwen-code ships a real stdio multi-session ACP agent (`Map<sessionID,Session>`, `loadSession`/`unstable_resumeSession`, mid-session model/mode switch), so `warm-acp.ts` (§2b) wires qwen into the existing `acp-dispatch.ts` stack as planned. **Caveat:** goose ACP exposes **no `loadSession`/resume** → its cross-restart resume needs a different design than opencode's (re-`session/new` + accept memory loss, or replay). Cross-check qwen's `@agentclientprotocol/sdk@^0.14` vs BooCode's `^0.22` handshake before relying on `unstable_resumeSession`. (`boocode_code_review_v2.md` §5f, §5n.)
+- **Phase 3 (lifecycle hardening) — lift from `openchamber` (MIT, same warm-opencode-server architecture), not Paseo.** Health-monitor + crash auto-restart + busy-aware restart (skip-while-busy + stale-grace) + port reclaim (`killProcessOnPort`/`waitForPortRelease`) + stall-detecting SSE reader — a concrete state machine for §6's "supervise children / rebuild on next turn" sketch. Worktree reaper: Paseo's worktree-archive cascade (soft-delete + `Promise.allSettled` fan-out) + superset's destroy-saga (preflight dirty/unpushed inspect + ordered failure semantics). Bound the warm server's per-session Maps (LRU) — long-lived-daemon leak class. (`boocode_code_review_v2.md` §5c, §5b, §5j.)
+- **Fix-next (Phase 1/2) — the post-interrupt stale-terminal bug (confirmed live).** `opencode-server.ts:~307` settles any `session.idle` onto whatever `activeTurn` holds the session slot, with **no turn-identity guard** → after abort + new prompt, a stale `session.idle` from the cancelled turn settles the *new* turn early as success. Paseo fix `1d38aac` (suppress-terminal-until-next-user-message). **Now one-click reachable** since `v2.6.5` shipped the Send→Stop composer. (`boocode_code_review_v2.md` §1 #6, §3.)
+- **Phase 1 UX (§9) — opencode already streams token/ctx usage.** `session.next.step.ended` carries `{tokens, cost}` on the wire (SDK already installed) → consume it to fill ctx/token usage for opencode sessions, closing the "no usage for external agents" gap; surfaces beside the §9b chip. (`boocode_code_review_v2.md` §1 #8, §3.)

openspec/changes/v2-6-persistent-agent-sessions/proposal.md

@@ -1,10 +1,16 @@
 # v2.6 Persistent agent sessions (warm processes + OpenCode server)
 
-**Status:** Planned
+**Status:** Phase 0 + Phase 1 + P1.5-a/b **shipped** (`v2.6.0`–`v2.6.4`); Phase 1-UX, Phase 2, Phase 3, and unit tests **remaining.** (Reconciled 2026-05-31.)
 **Depends on:** v2.2 Paseo providers (ACP dispatch), v2.3 provider lifecycle (registry/snapshot)
-**Reference fork:** `/opt/forks/paseo`, `/opt/forks/opencode`
+**Reference fork:** `/opt/forks/paseo`, `/opt/forks/opencode`; **remaining-phase lift sources in `boocode_code_review_v2.md`** (openchamber → Phase 3, qwen-code → Phase 2).
 **Pairs with:** the v2.5.x MessageBubble "Thinking" render fix — reasoning already flows; this batch is about persistence, not capability.
 
+> **Reconciliation note (2026-05-31).** Four design details below were revised *during* implementation; the original prose/SQL is now superseded:
+> 1. **Per-session SSE** — one `event.subscribe({directory})` per live opencode session (P1.5-a, `v2.6.2`) replaced the single global `/event` read loop (design §2a).
+> 2. **`agent_sessions` is keyed `(chat_id, agent)`**, and a first-class **`worktrees`** table replaced `session_worktrees` (P1.5-b, `v2.6.3`); `session_id`/`worktree_id` are informational `SET NULL` (`v2.6.4`). The design §3 SQL is the *original* shape.
+> 3. **opencode streams `session.next.*` events**, not `message.part.*` (design §2a's event names were wrong).
+> 4. **`OPENCODE_SERVER_PASSWORD` was deferred** — the warm server binds loopback unsecured (design §2a specified a random password). Basic-auth scheme since confirmed (openchamber, `boocode_code_review_v2.md` §5c) if ever wanted.
+
 ## Why
 
 BooCode dispatches external agents (opencode, goose, qwen) **one-shot per task**:
@@ -93,18 +99,20 @@ this batch does not touch it beyond porting OpenCode's reasoning-dedup.
 
 ## Success criteria
 
-- Send two messages in one external-agent chat → second turn reuses the same agent
+(Status reconciled 2026-05-31: ✅ met · 🟡 partial · ⬜ remaining)
+
+- ✅ Send two messages in one external-agent chat → second turn reuses the same agent
   session **and** the same worktree (verified: no second `createWorktree`, agent
-  references files it edited in turn 1).
+  references files it edited in turn 1). *(opencode; Smoke 1, `v2.6.1`)*
-- Warm-start latency for turn 2 materially below turn 1 (no spawn/handshake).
+- ✅ Warm-start latency for turn 2 materially below turn 1 (no spawn/handshake). *(turn 2 ~9× faster, `v2.6.1`)*
-- opencode reasoning shows once per thought (no dupes) in the Thinking block.
+- ✅ opencode reasoning shows once per thought (no dupes) in the Thinking block.
-- Killing the opencode server mid-session → pool restarts it and the next turn
+- ⬜ Killing the opencode server mid-session → pool restarts it and the next turn
-  recovers (opencode persists sessions on disk).
+  recovers (opencode persists sessions on disk). *(Phase 3 — `opencode-server.ts` still comments "recovery is Phase 3")*
-- Switch opencode → boocode → opencode in one chat → opencode resumes its *same*
+- 🟡 Switch opencode → boocode → opencode in one chat → opencode resumes its *same*
   session (its memory intact), boocode saw opencode's turns as history, and all three
-  shared the one worktree. No agent is locked to the chat.
+  shared the one worktree. No agent is locked to the chat. *(opencode↔boocode works; goose/qwen warm side is Phase 2 → full round-trip = Smoke 2b, unshipped)*
-- Closing/archiving a session removes its worktree; BooCoder restart drains cleanly.
+- ⬜ Closing/archiving a session removes its worktree; BooCoder restart drains cleanly. *(delete-guard shipped `v2.6.2`, but the close→cleanup hook + orphan reaper are Phase 3)*
-- Existing one-shot paths (arena, `new_task` tool, MCP create-task) still work.
+- ✅ Existing one-shot paths (arena, `new_task` tool, MCP create-task) still work. *(dispatcher resolve-or-create fallback)*
 
 ## Deliverables
 

openspec/changes/v2-6-persistent-agent-sessions/tasks.md

@@ -4,91 +4,98 @@ Phased so each phase is independently shippable and smoke-testable. Phase 1
 (OpenCode server) delivers the most value on the cleanest API; goose/qwen warm
 ACP follows; hardening last.
 
-## Phase 0 — Foundations (no behavior change)
+## Phase 0 — Foundations (no behavior change) — ✅ SHIPPED `v2.6.0-phase0-foundations`
 
-- [ ] 0.1 Add `session_worktrees` + `agent_sessions` tables (per `(session_id, agent)`)
+- [x] 0.1 Tables added to `apps/coder/src/schema.sql` (idempotent) + `pending_changes.agent` column. *Later re-keyed to `(chat_id, agent)` + `worktrees` table in P1.5-b.*
-      to `apps/coder/src/schema.sql` (idempotent; see design §3).
+- [x] 0.2 `AgentBackend` / `AgentSessionHandle` interface + normalized `AgentEvent` union — `apps/coder/src/services/agent-backend.ts`.
-- [ ] 0.2 Define `AgentBackend` / `AgentSessionHandle` interface + normalized `onEvent`
+- [x] 0.3 `agent-pool.ts` scaffolded (lazy get-or-create, health, `dispose()`, `onClose` hook).
-      event union (reuse shapes from `acp-dispatch.ts`).
-- [ ] 0.3 Scaffold `agent-pool.ts` with lazy get-or-create keyed by `(chat, agent)`,
-      health, `dispose()`; wire `app.addHook('onClose')` to dispose alongside dispatcher `stop()`.
 
-## Phase 1 — OpenCode server backend (multi-turn, warm)
+## Phase 1 — OpenCode server backend (multi-turn, warm) — ✅ SHIPPED `v2.6.1-phase1-opencode` (Smoke 1 verified)
 
-- [ ] 1.1 Add `@opencode-ai/sdk` to `apps/coder/package.json`; pin to installed opencode major.
+- [x] 1.1 `@opencode-ai/sdk` added to `apps/coder/package.json`.
-- [ ] 1.2 `backends/opencode-server.ts`: spawn `opencode serve` once (random
+- [x] 1.2 `backends/opencode-server.ts`: spawn `opencode serve`, allocated port, wait for ready line. *`OPENCODE_SERVER_PASSWORD` deferred — loopback-unsecured.*
-      `OPENCODE_SERVER_PASSWORD`, allocated port), `createOpencodeClient`, wait for ready line.
+- [x] 1.3 SSE read loop + demux + text/reasoning/tool mapping. *Superseded by per-session SSE (P1.5-a); events are `session.next.*`, not `message.part.*`.*
-- [ ] 1.3 Single `/event` SSE read loop; demux by `properties.sessionID`; map
+- [x] 1.4 Paseo `streamedPartKeys` reasoning dedup (delta vs final part).
-      `message.part.delta`/`updated` (text + reasoning) + tool parts to `onEvent`.
+- [x] 1.5 `ensureSession` reuse/resume. *Re-keyed `(chat_id, agent)` in P1.5-b.*
-- [ ] 1.4 Port Paseo `streamedPartKeys` reasoning dedup (delta vs final part).
+- [x] 1.6 `prompt` via SDK with worktree `directory` + `model`.
-- [ ] 1.5 `ensureSession`: reuse the `(chat, opencode)` `agent_sessions` row if present
+- [x] 1.7 Dispatcher routes `agent==='opencode'` to the pool backend; broker frames + `persistExternalAgentTurn` identical.
-      (resume on switch-back), else `client.session.create()` → store `agent_session_id`.
+- [x] 1.8 Persistent worktree, chat-keyed, base commit captured, reused across turns/agents. *Now the first-class `worktrees` table (P1.5-b).*
-- [ ] 1.6 `prompt`: send via SDK with `x-opencode-directory` = session worktree + `model`.
+- [x] 1.9 Per-session concurrency: `Map<sessionId,Promise>`; `poll()` skips in-flight sessions.
-- [ ] 1.7 Dispatcher: when `agent==='opencode'`, route to pool backend instead of
+- [x] 1.10 Per-turn diff supersedes prior `pending_changes` row (latest-wins).
-      `dispatchViaAcp`; keep broker frames + `persistExternalAgentTurn` identical.
+- [x] **Smoke 1** — verified end-to-end (two turns, same session + worktree, turn 2 ~9× faster, reasoning once).
-- [ ] 1.8 Persistent worktree: chat-keyed `createWorktree` (shared across agents);
-      capture base commit in `session_worktrees`; reuse across turns and agents.
-- [ ] 1.9 Per-session concurrency: replace global `running` with `Map<sessionId,Promise>`;
-      `poll()` skips sessions with an in-flight turn.
-- [ ] 1.10 Per-turn diff → supersede prior `pending_changes` row for the session (latest-wins).
-- [ ] **Smoke 1:** two messages in one opencode chat → same `agent_session_id`, same worktree,
-      no second `createWorktree`; agent references turn-1 edits; reasoning shows once; turn-2 faster.
 
-## Phase 1 (UX) — Attribution & switch affordances (design §9)
+## Phase 1.5 — concurrency + chat-keying follow-ups (added during impl, not in original plan) — ✅ SHIPPED
 
-- [ ] U.1 Stamp `pending_changes.agent` at queue time (worktree path → task agent;
+- [x] P1.5-a **Per-session SSE** (`v2.6.2-delete-guard-and-sse`): one `event.subscribe({directory})` per live opencode session, each with an `AbortController`; `sessionID` demux guard + zombie-loop fix — replaces task 1.3's single global loop. Bundled: session-delete work-loss guard (`/worktree-risk`).
-      native write tools → `'boocode'`; manual RightRail create → NULL).
+- [x] P1.5-b **Re-key `agent_sessions` → `(chat_id, agent)`** + first-class `worktrees` table (`v2.6.3-chatkey-and-skills`); `tasks.chat_id` threaded; `runOpenCodeServerTask` resolve-or-creates a chat for session-less creators; cross-chunk dcp-strip. FK convergence to `SET NULL` (`v2.6.4-agent-sessions-fk`).
-- [ ] U.2 Add `agent` to `listPending` response + frontend `PendingChange` type.
+
-- [ ] U.3 Extract `providerIcon()` to a shared helper; DiffPanel renders an agent badge
+## Phase 1 (UX) — Attribution & switch affordances (design §9) — ✅ SHIPPED `v2.6.8-agent-attribution` (Smoke U pending live frontend deploy)
-      per row + a "Changes from X, Y" note when the pending set spans >1 agent (§9a).
+
-- [ ] U.4 `GET /api/sessions/:id/agent-sessions` route + `api.coder.agentSessions` +
+- [x] U.1 Stamp `pending_changes.agent` at queue time — native tools default `'boocode'`, dispatched external → `task.agent`, manual RightRail → `NULL` (`pending_changes.ts`, `dispatcher.ts`).
-      `useAgentSessions(sessionId)` (refetch on `message_complete`) (§9b).
+- [x] U.2 `agent` flows through `listPending` + backend & frontend `PendingChange` types.
-- [ ] U.5 `AgentComposerBar` optional `sessionId` prop → resumed / history / new-session
+- [x] U.3 Shared `components/coder/providerIcons.tsx`; DiffPanel per-row agent badge + "Changes from X, Y" multi-agent note (§9a).
-      chip beside the Provider picker; hidden on fresh chats and other callers (§9b).
+- [x] U.4 `GET /api/sessions/:id/agent-sessions` route + `api.coder.agentSessions` + `useAgentSessions` hook (refetch on message-complete) (§9b).
+- [x] U.5 `AgentComposerBar` optional `sessionId` prop → resumed/history/new-session chip; hidden on fresh chats + other callers (§9b).
+- [x] U.6 Consume opencode `session.next.step.ended` → accumulate `input_tokens`/`output_tokens`/`cost` on `agent_sessions` (new cols). Backend persist only; UI surfacing deferred.
 - [ ] **Smoke U:** stage edits with opencode then boocode → DiffPanel badges each row to the
-      right agent; composer shows "resumed" when re-selecting opencode, "new session" for goose.
+      right agent; composer shows "resumed" when re-selecting opencode, "new session" for goose. *(pending live frontend deploy — Docker container rebuild)*
 
-## Phase 2 — Warm ACP backend (goose, qwen)
+## Phase 2 — Warm ACP backend (goose, qwen) — ✅ SHIPPED `v2.6.9-warm-acp` (Smoke 2/2b pending live)
 
-- [ ] 2.1 `backends/warm-acp.ts`: persistent spawn + `ClientSideConnection`; `initialize` +
+> **Lift (design §10):** `qwen --acp` is a validated reference (real stdio multi-session, `loadSession`/resume) — wire qwen into the existing `acp-dispatch.ts` stack. **goose ACP has no `loadSession`/resume** → cross-restart resume needs a different design (re-`session/new` + accept memory loss, or replay). Cross-check qwen `@agentclientprotocol/sdk@^0.14` vs BooCode `^0.22` before relying on `unstable_resumeSession`. Do **qwen first** to de-risk.
-      `session/new` once; reuse `acp-dispatch.ts` `handleSessionUpdate`.
+
-- [ ] 2.2 `prompt`: `session/prompt` on the warm connection per turn; per-turn abort signal only.
+- [x] 2.1 `backends/warm-acp.ts` `WarmAcpBackend` — persistent spawn + `ClientSideConnection`; `initialize` + `session/new` once per `(chat,agent)`. `handleSessionUpdate` extracted to a shared pure `acp-event-map.ts` (one-shot path byte-identical).
-- [ ] 2.3 Child supervision: detached lifetime, exit handler marks `status='crashed'`.
+- [x] 2.2 `prompt`: `session/prompt` on the warm connection per turn; abort = `session/cancel` the prompt only (never kills the child).
-- [ ] 2.4 Dispatcher routes `goose`/`qwen` to warm backend; keep one-shot fallback for arena/MCP
+- [x] 2.3 Child supervision: pool-owned lifetime; `exit` marks `agent_sessions.status='crashed'` → re-spawn next turn.
-      (or opt those into pool too — decide in review).
+- [x] 2.4 Dispatcher routes `goose`/`qwen` chat-tab tasks to the warm backend via pure `shouldUseWarmBackend(task)` (needs `session_id`+`chat_id`); one-shot `runExternalAgent` fallback kept for arena/MCP/`new_task`. *(SDK note resolved: installed `@agentclientprotocol/sdk@^0.22.1` has stable `resumeSession`/`loadSession`; resume moot in the warm hot path, deferred to Phase 3.)*
 - [ ] **Smoke 2:** two messages in a goose chat reuse the same process + ACP session + worktree;
       reasoning still renders; no per-turn respawn.
 - [ ] **Smoke 2b (switch round-trip):** opencode → boocode → opencode in one chat — opencode
       resumes the SAME `agent_session_id` (memory intact), boocode saw opencode's turns as
       history, all three shared the one worktree, and no agent was locked to the chat.
 
-## Phase 3 — Lifecycle hardening
+## Phase 3 — Lifecycle hardening — ✅ SHIPPED `v2.6.10-lifecycle-hardening` (3.1–3.6; 3.7 frontend + apps/server close-hook caller are follow-ups)
 
-- [ ] 3.1 Idle TTL eviction keyed per `(chat, agent)`; reattach-on-next-turn from `agent_sessions`.
+> **Lift (design §10):** hardening from **openchamber** (MIT, same warm-opencode-server architecture) — health-monitor + crash auto-restart + busy-aware restart + port reclaim (`killProcessOnPort`/`waitForPortRelease`) + stall-SSE = a concrete state machine for 3.1/3.2/3.6. Reaper (3.3/3.4): Paseo worktree-archive cascade + superset destroy-saga (preflight dirty/unpushed inspect) + LRU cap on warm-server Maps. Do crash-recovery + reaper together (shared supervision loop).
-- [ ] 3.2 Crash recovery: opencode server restart recreates sessions; ACP re-`session/new`.
-- [ ] 3.3 Chat close/archive hook → `closeSession` for every `(chat, agent)` + remove the
-      shared `session_worktrees` row + worktree; mark agent rows `status='closed'`.
-- [ ] 3.4 Orphan worktree reaper (extend periodic sweeper) + max-live-worktrees LRU cap.
-- [ ] 3.5 Re-baseline worktree diff after `apply_pending`.
-- [ ] 3.6 Reconnect test: restart BooCoder mid-session → next turn reattaches/recreates cleanly.
-- [ ] 3.7 Staging-boundary hint in DiffPanel (§9c): muted one-liner when the selected
-      provider can't see another agent's unapplied worktree edits (derived from per-change
-      `agent` + current provider; no new state).
 
-## Tests
+- [x] 3.1 Idle TTL eviction per `(chat, agent)` (`AGENT_POOL_IDLE_TTL_MS`=30min) + LRU cap (`AGENT_POOL_MAX_LIVE`=10), busy never evicted; reattach next turn. Pure `lifecycle-decisions.ts` (TDD).
+- [x] 3.2 Crash recovery: openchamber health-monitor + busy-aware-restart + stale-grace state machine in `opencode-server.ts` (+ port reclaim) + `warm-acp.ts`. opencode → fresh sessions; ACP → re-`session/new`. F.1 guard + U.6 usage preserved.
+- [x] 3.3 Close hooks (`/api/chats/:id/close`, `/api/sessions/:id/close`) → `closeChat` evicts backends + archives the `worktrees` row + removes the worktree. *(apps/server caller is a follow-up; idle-evict + reaper backstop it.)*
+- [x] 3.4 Orphan worktree reaper (periodic, 1h grace, superset-style dirty/unpushed preflight, Paseo soft-delete) + LRU cap on the pool.
+- [x] 3.5 Re-baseline `worktrees.base_commit` after a successful `apply_pending` (both apply routes).
+- [x] 3.6 Reconnect integration test (DB-opt-in): restart mid-session → next turn reattaches/recreates from `agent_sessions`/`worktrees`.
+- [ ] 3.7 Staging-boundary hint in DiffPanel (§9c) — **frontend follow-up** (apps/web; deferred — Sam has uncommitted web work).
+
+## Tests — ⬜ REMAINING (none of T.1–T.3 exist yet)
 
 - [ ] T.1 `agent-pool` unit: get-or-create, idle evict, dispose drains in-flight (DB-opt-in pattern).
-- [ ] T.2 opencode SSE demux + reasoning dedup unit (fixture event stream).
+- [ ] T.2 opencode SSE demux + reasoning dedup unit (fixture event stream). *Fold in an F.1 interrupt-bug regression case.*
 - [ ] T.3 per-session concurrency: two sessions run concurrently, one session serializes.
 
 ## Docs
 
-- [ ] D.1 Update `CLAUDE.md` (BooCoder dispatch section) + `BOOCODER.md` health/contract.
+- [~] D.1 `CLAUDE.md` BooCoder-dispatch section **done** (v2.6.1 / v2.6.4 doc-syncs); **`BOOCODER.md` health/contract still pending** (no v2.6 warm-server mentions).
-- [ ] D.2 Note opencode `@opencode-ai/sdk` dep + `OPENCODE_SERVER_PASSWORD` env in env docs.
+- [~] D.2 `@opencode-ai/sdk` dep noted; `OPENCODE_SERVER_PASSWORD` env n/a (deferred — loopback-unsecured).
-- [ ] D.3 `CHANGELOG.md` entry on tag (`v2.6.0-persistent-agent-sessions`).
+- [x] D.3 `CHANGELOG.md` entries per tag (`v2.6.0`–`v2.6.4`) — shipped as 5 tags, not the single planned `-persistent-agent-sessions`.
 
-## Build / deploy gate
+## Build / deploy gate — ✅ (per shipped tags; re-run per remaining batch)
 
-- [ ] B.1 `pnpm -C apps/server build && pnpm -C apps/coder build` clean.
+- [x] B.1 `pnpm -C apps/server build && pnpm -C apps/coder build` clean.
-- [ ] B.2 `pnpm -C apps/server test` (+ DB-opt-in) green.
+- [x] B.2 `pnpm -C apps/server test` green. *(v2.6-specific T.1–T.3 units still unwritten.)*
-- [ ] B.3 Deploy: `sudo systemctl restart boocoder`; `curl :9502/api/health` reports tool count.
+- [x] B.3 Deployed (`sudo systemctl restart boocoder`; `curl :9502/api/health`).
+
+-----
+
+## Fix-next (before Phase 2) — ✅ SHIPPED `v2.6.7-interrupt-guard`
+
+- [x] F.1 **Post-interrupt stale-terminal guard.** opencode emits one trailing `session.idle`/`session.error` for a cancelled turn (sessionID only, no turn id) which settled the *next* turn early. Fixed with a pure per-session guard (`backends/turn-guard.ts`: `armAbortGuard`/`noteTurnActivity`/`consumeTerminal` over `swallowNextTerminal`) wired into `opencode-server.ts` (arm on abort, swallow the orphan terminal, self-heal on next-turn activity). 3 regression tests (`turn-guard.test.ts`), TDD. Paseo parallel: `1d38aac`.
+
+## Remaining — recommended order (implementation plan, 2026-05-31)
+
+1. ~~**F.1 interrupt-bug fix**~~ — ✅ shipped `v2.6.7-interrupt-guard` (3 regression tests, TDD).
+2. ~~**Phase 1-UX** (U.1–U.6)~~ — ✅ shipped `v2.6.8-agent-attribution` (3 parallel agents, disjoint files; 9 new tests). Smoke U pending the frontend Docker rebuild.
+3. ~~**Phase 2 — warm ACP, qwen first then goose**~~ — ✅ shipped `v2.6.9-warm-acp` (15 new tests; one-shot path preserved). Smoke 2 + 2b pending live exercise post-deploy.
+4. **Phase 3 — lifecycle hardening** — lift openchamber's state machine; do crash-recovery (3.1/3.2/3.6) + worktree reaper (3.3/3.4 + LRU) together (shared supervision loop). Closes the two ⬜ success criteria (server-crash recovery, close→cleanup).
+5. **Tests T.1–T.3 + `BOOCODER.md` (D.1 remainder)** — backfill alongside each phase, not at the end.
+
+Each phase stays independently shippable + smoke-testable (original phasing holds). Tag monotonically from `v2.6.7`, one batch per phase.