feat: Wave 1 complete — state machine, Paseo hub, collision detection, PTY search

- Task state machine: TIMED_OUT state, retriable steps, timeout detection
- Paseo hub: paseo-client.ts (HTTP+CLI), PaseoBackend (AgentBackend), 14 tests
- Collision detection: collision-detector.ts, conflict-index.ts, ws-frames type
- PTY search: ring buffer, search route, capture-pane fallback

.ascli.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "binding": {
+    "apiBaseUrl": "https://agentspace.so",
+    "claimToken": "5Jr5_HEFEH_4Mc-7_dzUTEhYUWKFC-uOi58RrqMQ7RTGTA01",
+    "claimUrl": "https://agentspace.so/claim?workspaceId=ws_iTSoXqyy7Mcf&token=5Jr5_HEFEH_4Mc-7_dzUTEhYUWKFC-uOi58RrqMQ7RTGTA01",
+    "clientId": "ascli",
+    "createdAt": "2026-06-07T17:39:16.001Z",
+    "workspaceId": "ws_iTSoXqyy7Mcf",
+    "workspaceName": "fork-lifts-phases-3-11"
+  }
+}

.codesight/components.md

@@ -0,0 +1,71 @@
+# Components
+
+- **App** — `apps/web/src/App.tsx`
+- **AddProjectModal** — props: open, onOpenChange, onAdded — `apps/web/src/components/AddProjectModal.tsx`
+- **AgentComposerBar** — props: projectPath, value, onChange, onProviderCommandsChange, connected, agentStatus — `apps/web/src/components/AgentComposerBar.tsx`
+- **AgentPicker** — props: projectId, value, onChange — `apps/web/src/components/AgentPicker.tsx`
+- **ArenaLauncherDialog** — `apps/web/src/components/ArenaLauncherDialog.tsx`
+- **ArtifactPaneHeader** — props: title, defaultTitle, onDownload, downloadDisabled, onClose, onCopy, justCopied, copyDisabled — `apps/web/src/components/ArtifactPaneHeader.tsx`
+- **AskUserInputCard** — props: toolCall, toolResult, chatId, apiPrefix — `apps/web/src/components/AskUserInputCard.tsx`
+- **AttachmentChip** — props: attachment, onRemove, onPreview — `apps/web/src/components/AttachmentChip.tsx`
+- **AttachmentPreviewModal** — props: attachment, onClose — `apps/web/src/components/AttachmentPreviewModal.tsx`
+- **BottomSheet** — props: open, onClose, title — `apps/web/src/components/BottomSheet.tsx`
+- **CapHitSentinel** — props: message, capHitPosition, isLatest — `apps/web/src/components/CapHitSentinel.tsx`
+- **ChatInput** — props: disabled, projectId, agentId, onAgentChange, sessionId, webSearchEnabled, onSend, onForceSend, generating, onStop — `apps/web/src/components/ChatInput.tsx`
+- **ChatTabBar** — props: pane, tabs, tabNumbers, onSwitchTab, onRemoveTab, onCloseOthers, onCloseToRight, onCloseAll, onNewTab, onSplitPane — `apps/web/src/components/ChatTabBar.tsx`
+- **ChatThroughput** — props: chatId, className — `apps/web/src/components/ChatThroughput.tsx`
+- **CodeBlock** — props: code, lang — `apps/web/src/components/CodeBlock.tsx`
+- **ContextMeter** — props: messages, modelContextLimit, sessionCostUsd — `apps/web/src/components/ContextMeter.tsx`
+- **CreateProjectModal** — props: open, onOpenChange — `apps/web/src/components/CreateProjectModal.tsx`
+- **DoomLoopSentinel** — props: message — `apps/web/src/components/DoomLoopSentinel.tsx`
+- **DropOverlay** — props: visible — `apps/web/src/components/DropOverlay.tsx`
+- **FileMentionPopover** — props: query, files, anchorRect, onSelect, onClose — `apps/web/src/components/FileMentionPopover.tsx`
+- **FileViewerOverlay** — props: path, content, lang, onClose — `apps/web/src/components/FileViewerOverlay.tsx`
+- **FlowLauncherDialog** — `apps/web/src/components/FlowLauncherDialog.tsx`
+- **GitDiffView** — props: result, loading, error, mode, onSelectMode, onRefresh, mutating, mutateError, onStage, onUnstage — `apps/web/src/components/GitDiffView.tsx`
+- **HtmlArtifactPane** — props: chatId, state, onClose — `apps/web/src/components/HtmlArtifactPane.tsx`
+- **InferenceSettings** — `apps/web/src/components/InferenceSettings.tsx`
+- **MarkdownArtifactPane** — props: chatId, state, onClose — `apps/web/src/components/MarkdownArtifactPane.tsx`
+- **MarkdownRenderer** — props: content — `apps/web/src/components/MarkdownRenderer.tsx`
+- **MessageBubble** — props: message, sessionChats, capHitInfo, actions, hideActions, hasCheckpoint, restoreDisabled — `apps/web/src/components/MessageBubble.tsx`
+- **MessageList** — props: messages, sessionChats — `apps/web/src/components/MessageList.tsx`
+- **MobileTabSwitcher** — props: panes, activePaneIdx, chats, onSwitchPane, onRemovePane, onRenameChat — `apps/web/src/components/MobileTabSwitcher.tsx`
+- **ModelPicker** — props: value, onChange — `apps/web/src/components/ModelPicker.tsx`
+- **NewPaneMenu** — props: onAddPane, disabled, projectId — `apps/web/src/components/NewPaneMenu.tsx`
+- **PaneHeaderActions** — props: onNewTab, onSplitPane, onNewOrchestrator, onNewArena, onReopenPane, onShowHistory, onRemovePane, historyActive, className — `apps/web/src/components/PaneHeaderActions.tsx`
+- **PermissionCard** — props: prompt, onRespond, busy — `apps/web/src/components/PermissionCard.tsx`
+- **ProjectSidebar** — `apps/web/src/components/ProjectSidebar.tsx`
+- **RequestReadAccessCard** — props: toolCall, toolResult, chatId — `apps/web/src/components/RequestReadAccessCard.tsx`
+- **RightRail** — props: projectId, sessionId — `apps/web/src/components/RightRail.tsx`
+- **SessionLandingPage** — props: projectId, sessionId, agentId, onAgentChange, onSend, onSkillInvoke, createChat, chats, onOpenChat, onUnarchiveChat — `apps/web/src/components/SessionLandingPage.tsx`
+- **SlashCommandPicker** — props: query, items, groups, inputRef, onSelect, onClose, emptyLabel — `apps/web/src/components/SlashCommandPicker.tsx`
+- **StaleStreamBanner** — props: onRetry, onDiscard — `apps/web/src/components/StaleStreamBanner.tsx`
+- **StatusDot** — props: chatId, className — `apps/web/src/components/StatusDot.tsx`
+- **ThemePicker** — `apps/web/src/components/ThemePicker.tsx`
+- **ToolCallGroup** — props: runs — `apps/web/src/components/ToolCallGroup.tsx`
+- **ToolCallLine** — props: run, insideGroup — `apps/web/src/components/ToolCallLine.tsx`
+- **Workspace** — props: sessionId, projectId, agentId, onAgentChange, panesHook, chatsHook, session, project, onAddPane — `apps/web/src/components/Workspace.tsx`
+- **AddProviderModal** — props: open, onOpenChange, onAdded — `apps/web/src/components/coder/AddProviderModal.tsx`
+- **ProvidersSettings** — `apps/web/src/components/coder/ProvidersSettings.tsx`
+- **MatrixRain** — props: enabled, density, speed, opacity — `apps/web/src/components/fx/MatrixRain.tsx`
+- **NeonField** — props: enabled, opacity, speed — `apps/web/src/components/fx/NeonField.tsx`
+- **ThemeFx** — `apps/web/src/components/fx/ThemeFx.tsx`
+- **ClaudeIcon** — props: size, className — `apps/web/src/components/icons/ProviderIcons.tsx`
+- **OpenCodeIcon** — props: size, className — `apps/web/src/components/icons/ProviderIcons.tsx`
+- **ArenaPane** — props: state, onClose — `apps/web/src/components/panes/ArenaPane.tsx`
+- **ChatPane** — props: sessionId, chatId, projectId, agentId, onAgentChange, sessionChats, webSearchEnabled — `apps/web/src/components/panes/ChatPane.tsx`
+- **CoderMessageList** — props: messages, chatId, footer, actions, checkpointMessageIds, restoreDisabled — `apps/web/src/components/panes/CoderMessageList.tsx`
+- **CoderPane** — props: sessionId, paneId, chatId, chatPending, projectPath, onConnectedChange, onAgentLabelChange — `apps/web/src/components/panes/CoderPane.tsx`
+- **OrchestratorPane** — props: state, onClose — `apps/web/src/components/panes/OrchestratorPane.tsx`
+- **SettingsPane** — props: session, project, maximized, onToggleMaximize, onClose, isMobile — `apps/web/src/components/panes/SettingsPane.tsx`
+- **TerminalPane** — props: sessionId, paneId, label, active — `apps/web/src/components/panes/TerminalPane.tsx`
+- **FloatingMenu** — props: x, y, hasSelection, chatInputs, onCopy, onPaste, onSelectAll, onSearch, onSendToChat, onDismiss — `apps/web/src/components/panes/terminal/FloatingMenu.tsx`
+- **SearchBar** — props: searchRef, theme, onClose — `apps/web/src/components/panes/terminal/SearchBar.tsx`
+- **TerminalHotkeyBar** — props: ctrlArmed, onSendBytes, onArmCtrl, onFit — `apps/web/src/components/panes/terminal/TerminalHotkeyBar.tsx`
+- **RightRailDrawerProvider** — `apps/web/src/hooks/useRightRailDrawer.tsx`
+- **SidebarDrawerProvider** — `apps/web/src/hooks/useSidebarDrawer.tsx`
+- **PATH_REGEX** — `apps/web/src/lib/linkify-paths.tsx`
+- **Home** — `apps/web/src/pages/Home.tsx`
+- **Project** — `apps/web/src/pages/Project.tsx`
+- **Session** — `apps/web/src/pages/Session.tsx`
+- **Settings** — `apps/web/src/pages/Settings.tsx`

.codesight/config.md

@@ -0,0 +1,50 @@
+# Config
+
+## Environment Variables
+
+- `AUDIT_DOT_DIR` **required** — apps/server/src/services/audit/runs-dir.ts
+- `BOOCODE_DATA_DIR` **required** — apps/server/src/routes/inference-settings.ts
+- `BOOCODE_TOOLS` **required** — apps/server/src/services/agents.ts
+- `BOOCODE_TRUNCATION_DIR` **required** — apps/server/src/services/__tests__/truncate.test.ts
+- `BOOCODER_DEV_URL` **required** — apps/web/vite.config.ts
+- `BOOCODER_URL` **required** — apps/coder/src/cli.ts
+- `BOOTERM_DEV_URL` **required** — apps/web/vite.config.ts
+- `BOOTERM_SSH_HOST` **required** — apps/booterm/src/pty/manager.ts
+- `BOOTERM_SSH_USER` **required** — apps/booterm/src/pty/manager.ts
+- `BOOTSTRAP_ROOT` (has default) — .env.example
+- `BRAINSTORM_DIR` **required** — data/skills/superpowers/brainstorming/scripts/server.cjs
+- `BRAINSTORM_HOST` **required** — data/skills/superpowers/brainstorming/scripts/server.cjs
+- `BRAINSTORM_OWNER_PID` **required** — data/skills/superpowers/brainstorming/scripts/server.cjs
+- `BRAINSTORM_PORT` **required** — data/skills/superpowers/brainstorming/scripts/server.cjs
+- `BRAINSTORM_URL_HOST` **required** — data/skills/superpowers/brainstorming/scripts/server.cjs
+- `CODECONTEXT_CHILD` **required** — codecontext/shim.go
+- `CODECONTEXT_URL` **required** — apps/server/src/services/codecontext_client.ts
+- `CONDUCTOR_MODEL` **required** — conductor/src/dispatch.ts
+- `CONDUCTOR_OPENCODE_BIN` **required** — conductor/src/dispatch.ts
+- `CONDUCTOR_TIMEOUT_MS` **required** — conductor/src/dispatch.ts
+- `CONTAINER_GUIDANCE_FILE` **required** — apps/server/src/services/__tests__/system-prompt.test.ts
+- `CONTEXT7_API_KEY` (has default) — .env
+- `DATABASE_URL` (has default) — .env.example
+- `DEFAULT_MODEL` (has default) — .env.example
+- `DEV_REMOTE_USER` **required** — apps/web/vite.config.ts
+- `GITEA_BASE_URL` (has default) — .env
+- `GITEA_SSH_HOST` (has default) — .env
+- `GITEA_TOKEN` (has default) — .env
+- `GITEA_USER` (has default) — .env
+- `LLAMA_SWAP_URL` (has default) — .env.example
+- `MCP_TEST_MISSING` **required** — apps/server/src/services/__tests__/mcp-config.test.ts
+- `MCP_TEST_SECRET` **required** — apps/server/src/services/__tests__/mcp-config.test.ts
+- `NODE_ENV` (has default) — .env.example
+- `PORT` (has default) — .env.example
+- `POSTGRES_PASSWORD` (has default) — .env.example
+- `PROJECT_ROOT_WHITELIST` (has default) — .env.example
+- `SEARXNG_URL` (has default) — .env.example
+- `SKILLS_ROOT` **required** — apps/server/src/services/skills.ts
+- `WEB_DIST_PATH` **required** — apps/server/src/index.ts
+
+## Config Files
+
+- `.env.example`
+- `Dockerfile`
+- `apps/web/vite.config.ts`
+- `docker-compose.yml`

.codesight/graph.md

@@ -0,0 +1,37 @@
+# Dependency Graph
+
+## Most Imported Files (change these carefully)
+
+- `apps/coder/src/db.ts` — imported by **40** files
+- `apps/server/src/types/api.ts` — imported by **28** files
+- `apps/server/src/db.ts` — imported by **25** files
+- `packages/ion/src/cli/utils.ts` — imported by **24** files
+- `apps/coder/src/services/tools/types.ts` — imported by **18** files
+- `apps/coder/src/conductor/types.ts` — imported by **14** files
+- `apps/coder/src/services/agent-backend.ts` — imported by **14** files
+- `apps/coder/src/services/acp-tool-snapshot.ts` — imported by **14** files
+- `apps/server/src/services/tools/codecontext/factory.ts` — imported by **14** files
+- `apps/server/src/services/tools.ts` — imported by **13** files
+- `conductor/src/types.ts` — imported by **13** files
+- `apps/coder/src/services/provider-config-registry.ts` — imported by **12** files
+- `apps/server/src/config.ts` — imported by **12** files
+- `apps/coder/src/config.ts` — imported by **11** files
+- `apps/coder/src/services/provider-types.ts` — imported by **11** files
+- `apps/server/src/services/agents.ts` — imported by **10** files
+- `apps/coder/src/services/pending_changes.ts` — imported by **9** files
+- `apps/server/src/services/broker.ts` — imported by **9** files
+- `apps/server/src/services/path_guard.ts` — imported by **9** files
+- `apps/server/src/services/inference/payload.ts` — imported by **9** files
+
+## Import Map (who imports what)
+
+- `apps/coder/src/db.ts` ← `apps/coder/src/index.ts`, `apps/coder/src/routes/__tests__/agent-sessions.routes.test.ts`, `apps/coder/src/routes/__tests__/chat-resolve.test.ts`, `apps/coder/src/routes/__tests__/providers.routes.test.ts`, `apps/coder/src/routes/agent-sessions.ts` +35 more
+- `apps/server/src/types/api.ts` ← `apps/server/src/routes/chats.ts`, `apps/server/src/routes/messages.ts`, `apps/server/src/routes/models.ts`, `apps/server/src/routes/projects.ts`, `apps/server/src/routes/sessions.ts` +23 more
+- `apps/server/src/db.ts` ← `apps/server/src/index.ts`, `apps/server/src/routes/agents.ts`, `apps/server/src/routes/artifacts.ts`, `apps/server/src/routes/chats.ts`, `apps/server/src/routes/messages.ts` +20 more
+- `packages/ion/src/cli/utils.ts` ← `packages/ion/src/cli/commands/abandon.ts`, `packages/ion/src/cli/commands/abandon.ts`, `packages/ion/src/cli/commands/approve.ts`, `packages/ion/src/cli/commands/approve.ts`, `packages/ion/src/cli/commands/cleanup.ts` +19 more
+- `apps/coder/src/services/tools/types.ts` ← `apps/coder/src/routes/messages.ts`, `apps/coder/src/services/dispatcher.ts`, `apps/coder/src/services/tools/adapter.ts`, `apps/coder/src/services/tools/apply_pending.ts`, `apps/coder/src/services/tools/check_task_status.ts` +13 more
+- `apps/coder/src/conductor/types.ts` ← `apps/coder/src/conductor/flows/_util.ts`, `apps/coder/src/conductor/flows/architectural-analysis.ts`, `apps/coder/src/conductor/flows/authoring.ts`, `apps/coder/src/conductor/flows/code-review.ts`, `apps/coder/src/conductor/flows/discovery.ts` +9 more
+- `apps/coder/src/services/agent-backend.ts` ← `apps/coder/src/routes/lifecycle.ts`, `apps/coder/src/services/__tests__/stream-json-parser.test.ts`, `apps/coder/src/services/acp-event-map.ts`, `apps/coder/src/services/agent-pool.ts`, `apps/coder/src/services/backends/__tests__/claude-sdk-map.test.ts` +9 more
+- `apps/coder/src/services/acp-tool-snapshot.ts` ← `apps/coder/src/services/__tests__/acp-event-map.test.ts`, `apps/coder/src/services/__tests__/frame-emitter.test.ts`, `apps/coder/src/services/__tests__/stream-json-parser.test.ts`, `apps/coder/src/services/acp-dispatch.ts`, `apps/coder/src/services/acp-event-map.ts` +9 more
+- `apps/server/src/services/tools/codecontext/factory.ts` ← `apps/server/src/services/tools/codecontext/get_blast_radius.ts`, `apps/server/src/services/tools/codecontext/get_call_graph.ts`, `apps/server/src/services/tools/codecontext/get_codebase_overview.ts`, `apps/server/src/services/tools/codecontext/get_dependencies.ts`, `apps/server/src/services/tools/codecontext/get_file_analysis.ts` +9 more
+- `apps/server/src/services/tools.ts` ← `apps/server/src/index.ts`, `apps/server/src/services/__tests__/agent-allowlist.test.ts`, `apps/server/src/services/agents.ts`, `apps/server/src/services/inference/stream-phase-adapter.ts`, `apps/server/src/services/inference/stream-phase.ts` +8 more

.codesight/libs.md

@@ -0,0 +1,927 @@
+# Libraries
+
+- `apps/booterm/src/auth.ts` — function getUser: (req) => string
+- `apps/booterm/src/config.ts` — function loadConfig: () => Config
+- `apps/booterm/src/db.ts`
+  - function getPool: (databaseUrl) => pg.Pool
+  - function getSessionInfo: (sessionId) => Promise<SessionInfo | null>
+  - function pingDb: () => Promise<boolean>
+  - function closeDb: () => Promise<void>
+- `apps/booterm/src/pty/manager.ts`
+  - function sanitizeId: (raw) => string | null
+  - function tmuxSessionName: (paneId) => string
+  - function hasSession: (tmuxConfPath, sessionName) => Promise<boolean>
+  - function ensureSession: (tmuxConfPath, sessionName, projectRoot, log, cols?, rows?) => Promise<void>
+  - function killSession: (tmuxConfPath, sessionName) => Promise<boolean>
+  - function capturePane: (tmuxConfPath, sessionName, lines) => Promise<string>
+- `apps/booterm/src/pty/pty.ts` — function attachPty: (opts) => IPty
+- `apps/booterm/src/ws/attach.ts` — function registerWsAttachRoute: (app, tmuxConfPath) => void
+- `apps/coder/src/conductor/contracts.ts`
+  - function produceContract: (contracts) => string
+  - function reviewContract: (contracts) => string
+  - type Contract
+  - const EVIDENCE_PRODUCE
+  - const EVIDENCE_REVIEW
+  - const YAGNI_PRODUCE
+  - _...1 more_
+- `apps/coder/src/conductor/flows/_util.ts` — function q, function repoLine
+- `apps/coder/src/conductor/flows/index.ts`
+  - function describeFlows: () => string
+  - function getFlow: (name) => Flow | undefined
+  - const FLOWS: Record<string, Flow>
+  - const FLOW_NAMES: string[]
+- `apps/coder/src/conductor/persona-loader.ts` — function loadPersona: (agent) => Promise<string>, const AGENTS_DIR
+- `apps/coder/src/conductor/render.ts` — function slugify: (s) => string
+- `apps/coder/src/conductor/spine.ts`
+  - function readBand: (input) => Band
+  - function fastNote: (ctx) => string
+  - function buildSpineFlow: (spine) => Flow
+- `apps/coder/src/config.ts` — function loadConfig: () => Config, type Config
+- `apps/coder/src/db.ts`
+  - function getSql: (config) => Sql
+  - function applySchema: (sql) => Promise<void>
+  - function pingDb: (sql) => Promise<boolean>
+  - function closeDb: () => Promise<void>
+  - type Sql
+- `apps/coder/src/plugins/host.ts`
+  - function registerHook: (name, fn) => void
+  - function emitHook: (name, ctx) => Promise<any>
+  - function clearHooks: () => void
+  - interface ToolHookContext
+  - interface ToolResultContext
+  - type HookName
+  - _...1 more_
+- `apps/coder/src/services/acp-client-fs.ts` — function readWorktreeTextFile: (worktreePath, filePath, line?, limit?) => Promise<string>, function writeWorktreeTextFile: (worktreePath, filePath, content) => Promise<void>
+- `apps/coder/src/services/acp-client.ts` — function buildAcpClient: (worktreePath, resolveTurn) => void, interface AcpTurnContext
+- `apps/coder/src/services/acp-derive.ts`
+  - function deriveModesFromACP: (fallbackModes, modeState?, configOptions?) => void
+  - function deriveModelDefinitionsFromACP: (models, configOptions?) => ProviderModel[]
+  - function findThoughtLevelConfigId: (configOptions) => string | null
+- `apps/coder/src/services/acp-dispatch.ts`
+  - function dispatchViaAcp: (opts) => Promise<AcpDispatchResult>
+  - interface AcpDispatchResult
+  - interface AcpDispatchOpts
+- `apps/coder/src/services/acp-event-map.ts` — function mapSessionUpdate: (params, priorSnapshots, AcpToolSnapshot>) => void
+- `apps/coder/src/services/acp-probe.ts` — function probeAcpProvider: (agent, installPath, cwd) => Promise<AcpProbeResult>, interface AcpProbeResult
+- `apps/coder/src/services/acp-spawn.ts`
+  - function resolveAcpSpawnArgs: (agent) => string[] | null
+  - function resolveLaunchSpec: (resolved, installPath) => void
+  - function resolveAcpProbeBinaries: (agent) => string[]
+- `apps/coder/src/services/acp-stream.ts` — function createAcpNdJsonStream: (child) => void
+- `apps/coder/src/services/acp-tool-snapshot.ts`
+  - function mergeToolSnapshot: (toolCallId, update, previous?) => AcpToolSnapshot
+  - function mapToolLifecycleStatus: (status, rawOutput?) => AcpToolLifecycleStatus
+  - function snapshotToWireToolCall: (snapshot) => void
+  - function snapshotToPartPayload: (snapshot) => void
+  - function synthesizeCanceledSnapshots: (snapshots) => AcpToolSnapshot[]
+  - interface AcpToolSnapshot
+  - _...2 more_
+- `apps/coder/src/services/agent-commands-cache.ts`
+  - function setTaskCommands: (taskId, commands) => void
+  - function mergeTaskCommands: (taskId, commands) => void
+  - function getTaskCommands: (taskId) => AgentCommand[] | null
+  - function clearTaskCommands: (taskId) => void
+- `apps/coder/src/services/agent-pool.ts`
+  - class AgentPool
+  - interface AgentPoolOpts
+  - const OPENCODE_POOL_KEY
+  - const agentPool
+- `apps/coder/src/services/agent-probe.ts` — function probeAgents: (sql, log) => Promise<void>
+- `apps/coder/src/services/agent-status-publish.ts` — function publishAgentStatus: (publishFrame, sessionId, chatId, agent, status, reason?, at) => void
+- `apps/coder/src/services/agent-turn-persist.ts` — function persistExternalAgentTurn: (sql, assistantMessageId, snapshots, reasoningText) => Promise<void>
+- `apps/coder/src/services/arena-analyzer-helpers.ts`
+  - function buildDigestPrompt: (input) => void
+  - function buildJudgePrompt: (originalPrompt, digests) => void
+  - function shouldNameWinner: (succeededCount) => boolean
+  - function extractWinner: (judgeOutput) => void
+  - function buildCrossExamPrompt: (opts) => void
+  - interface ContestantDigestInput
+  - _...1 more_
+- `apps/coder/src/services/arena-analyzer.ts` — function createAnalyzer: (deps) => Analyzer, interface Analyzer
+- `apps/coder/src/services/arena-decisions.ts`
+  - function classifyLane: (battleType, _identity, model, localModels) => ContestantLane
+  - function nextLocalContestant: (contestants) => string | null
+  - function isBattleComplete: (contestants) => boolean
+  - function computeBenchmark: (startedAt, endedAt, costTokens, lane) => Benchmark
+  - function sanitizeSlug: (s) => string
+  - function buildBattleSlug: (battleId, battleType, createdAt) => string
+  - _...7 more_
+- `apps/coder/src/services/arena-model-call.ts` — function arenaModelCall: (opts, 'LLAMA_SWAP_URL'>;
+  model) => Promise<string>
+- `apps/coder/src/services/arena-runner.ts`
+  - function createBattleRunner: (deps) => BattleRunner
+  - interface ContestantSpec
+  - interface BattleStartOpts
+  - interface BattleRunner
+  - type DispatchContestantFn
+  - type OnBattleComplete
+  - _...1 more_
+- `apps/coder/src/services/audit-session.ts`
+  - function generateSessionId: () => string
+  - function getCurrentSession: (basePath?) => Promise<string | null>
+  - function getSessionJson: (sessionId, basePath?) => Promise<SessionJson | null>
+  - function getIndex: (basePath?) => Promise<IndexJson | null>
+  - function startSession: (task, basePath?) => Promise<StartSessionResult>
+  - function endSession: (basePath?) => Promise<EndSessionResult | null>
+  - _...18 more_
+- `apps/coder/src/services/backends/claude-sdk-map.ts`
+  - function createClaudeSdkMapState: () => ClaudeSdkMapState
+  - function mapSdkMessage: (msg, state) => AgentEvent[]
+  - interface ClaudeSdkMapState
+- `apps/coder/src/services/backends/claude-sdk-routing.ts` — function claudeSdkBackendEnabled: (env) => boolean, function shouldUseClaudeSdk: (task, env) => boolean
+- `apps/coder/src/services/backends/claude-sdk.ts` — class ClaudeSdkBackend, interface ClaudeSdkBackendDeps
+- `apps/coder/src/services/backends/claude-session-store.ts` — class PostgresSessionStore
+- `apps/coder/src/services/backends/lifecycle-decisions.ts`
+  - function selectIdleEvictionTargets: (entries, now, ttlMs) => string[]
+  - function selectLruEvictionTargets: (entries, cap) => string[]
+  - function decideRestart: (input) => RestartDecision
+  - function selectOrphanWorktreeTargets: (onDisk, liveWorktreePaths, now, graceMs) => string[]
+  - interface PoolEntrySnapshot
+  - interface RestartDecisionInput
+  - _...7 more_
+- `apps/coder/src/services/backends/opencode-event-map.ts`
+  - function stripDcpTags: (s) => string
+  - function eventSessionId: (ev) => string | null
+  - function resolvePartDedupeKey: (part, type) => string | null
+  - function mapToolStatus: (s) => ToolCallStatus | null
+  - function toolPartToSnapshot: (part) => AcpToolSnapshot
+  - function toolCalledSnapshot: (p) => AcpToolSnapshot
+  - _...7 more_
+- `apps/coder/src/services/backends/opencode-server-process.ts`
+  - function shouldStartServer: (s) => boolean
+  - class OpenCodeServerSupervisor
+  - interface ServerDownInfo
+  - interface SupervisorHooks
+  - interface OpenCodeServerSupervisorDeps
+- `apps/coder/src/services/backends/opencode-server.ts` — class OpenCodeServerBackend, interface OpenCodeServerBackendDeps
+- `apps/coder/src/services/backends/opencode-sse.ts`
+  - function reconnectDecision: (failures, policy) => ReconnectDecision
+  - function startSessionEventLoop: (state, deps) => void
+  - function runSessionEventLoop: (state, abort, deps) => Promise<void>
+  - interface TurnState
+  - interface SessionState
+  - interface ReconnectPolicy
+  - _...4 more_
+- `apps/coder/src/services/backends/opencode-usage.ts`
+  - function stepEndedToUsage: (props) => StepUsage
+  - interface StepEndedProps
+  - interface StepUsage
+- `apps/coder/src/services/backends/pushable-iterable.ts` — function createPushable: () => Pushable<T>, interface Pushable
+- `apps/coder/src/services/backends/turn-guard.ts`
+  - function armAbortGuard: (g) => void
+  - function noteTurnActivity: (g) => void
+  - function consumeTerminal: (g) => 'swallow' | 'settle'
+  - interface AbortTerminalGuard
+- `apps/coder/src/services/backends/warm-acp-routing.ts` — function shouldUseWarmBackend: (task) => boolean, function isTurnOkForStopReason: (stopReason) => boolean
+- `apps/coder/src/services/backends/warm-acp.ts` — class WarmAcpBackend, interface WarmAcpBackendDeps
+- `apps/coder/src/services/cancel-registry.ts` — function createCancelRegistry: () => CancelRegistry, interface CancelRegistry
+- `apps/coder/src/services/checkpoints.ts`
+  - function buildShadowCommitCommand: (worktreePath, id) => string
+  - function createCheckpoint: (sql, args, opts?) => Promise<
+  - function restoreCheckpoint: (sql, checkpointId, opts?) => Promise<RestoreCheckpointResult>
+  - class CheckpointNotFoundError
+  - interface CreateCheckpointArgs
+  - interface RestoreCheckpointResult
+  - _...1 more_
+- `apps/coder/src/services/claude-command-discovery.ts` — function discoverClaudeCommands: () => AgentCommand[]
+- `apps/coder/src/services/command-availability.ts` — function isCommandAvailable: (binary) => Promise<boolean>
+- `apps/coder/src/services/correction-service.ts`
+  - function recordCorrection: (originalClaim, correction, principleExtracted, persistedTo, basePath?) => Promise<UserCorrectionRecord>
+  - function scanForCorrections: (auditPath) => Promise<UserCorrectionRecord[]>
+  - function checkContradiction: (action, corrections) => void
+  - function markPersisted: (correctionId, filePath, basePath?) => Promise<UserCorrectionRecord | null>
+  - function listCorrections: (basePath?) => Promise<UserCorrectionRecord[]>
+  - function appendCorrectionToTrail: (trailPath, correction) => Promise<void>
+  - _...2 more_
+- `apps/coder/src/services/dcp-strip.ts`
+  - function stripDcpTags: (s) => string
+  - function makeDcpStreamStripper: () => DcpStreamStripper
+  - interface DcpStreamStripper
+- `apps/coder/src/services/dispatcher.ts` — function createDispatcher: (deps) => void
+- `apps/coder/src/services/edit-guards-imports.ts` — function checkDroppedImports: (original, updated, filePath) => ImportCheckResult, interface ImportCheckResult
+- `apps/coder/src/services/edit-guards.ts`
+  - function validateEditResult: (original, updated, filePath) => GuardResult
+  - function formatGuardError: (guard, filePath) => string
+  - interface GuardResult
+- `apps/coder/src/services/finalize-message.ts`
+  - function classifyTerminalStatus: (opts) => TerminalMessageStatus
+  - function finalizeStreamingMessage: (sql, publishFrame, frame) => void
+  - type TerminalMessageStatus
+- `apps/coder/src/services/flow-artifacts.ts` — function getArtifactPath: (flowRunId, stepId) => string, function writeFlowArtifact: (flowRunId, stepId, content) => Promise<string>
+- `apps/coder/src/services/flow-runner-decisions.ts`
+  - function manifestSteps: (flow, launchCtx) => Step[]
+  - function readySteps: (flow, state) => Step[]
+  - function partitionReady: (ready, ctx) => void
+  - function isRunComplete: (flow, state) => boolean
+  - function isStuck: (flow, state) => boolean
+  - function reconcileResumeStep: (status, taskId, taskState) => ResumeAction
+  - _...5 more_
+- `apps/coder/src/services/flow-runner.ts`
+  - function createFlowRunner: (deps) => FlowRunner
+  - interface LaunchOpts
+  - interface FlowRunner
+- `apps/coder/src/services/frame-emitter.ts`
+  - function makeFrameEmitter: (opts) => FrameEmitter
+  - interface FrameEmitterOpts
+  - interface FrameEmitter
+- `apps/coder/src/services/fuzzy-match.ts`
+  - function locateMatch: (content, needle) => MatchResult
+  - type MatchResult
+  - const SIMILARITY_THRESHOLD
+  - const AMBIGUITY_EPSILON
+- `apps/coder/src/services/guideline-service.ts`
+  - function createGuideline: (params, basePath?) => Promise<Guideline>
+  - function listGuidelines: (filter?, basePath?) => Promise<Guideline[]>
+  - function readGuideline: (id, basePath?) => Promise<Guideline | null>
+  - function updateGuideline: (id, params, basePath?) => Promise<Guideline | null>
+  - function deleteGuideline: (id, basePath?) => Promise<boolean>
+  - function findGuideline: (content, basePath?) => Promise<Guideline | null>
+  - _...14 more_
+- `apps/coder/src/services/host-exec.ts` — function hostExec: (command, opts?) => Promise<HostExecResult>, interface HostExecResult
+- `apps/coder/src/services/lsp/client.ts` — class LspClient
+- `apps/coder/src/services/lsp/config.ts` — function getServerConfig: (filePath) => LspServerConfig | null, interface LspServerConfig
+- `apps/coder/src/services/lsp/operations.ts`
+  - function openDocument: (client, filePath, content, version) => Promise<void>
+  - function closeDocument: (client, filePath) => Promise<void>
+  - function getDiagnostics: (client, filePath, content) => Promise<Diagnostic[]>
+  - function gotoDefinition: (client, filePath, content, line, character) => Promise<Location | null>
+  - function findReferences: (client, filePath, content, line, character) => Promise<Location[]>
+- `apps/coder/src/services/lsp/server-manager.ts` — class LspServerManager, const lspManager
+- `apps/coder/src/services/mcp-server.ts` — function startMcpServer: (sql) => Promise<void>
+- `apps/coder/src/services/net/port-utils.ts`
+  - function reclaimPort: (port) => void
+  - function waitForPortRelease: (port, timeoutMs) => Promise<boolean>
+  - function freePort: () => Promise<number>
+- `apps/coder/src/services/orphan-worktree-reaper.ts`
+  - function reapOrphanWorktrees: (sql, log, graceMs, now) => void
+  - function createOrphanWorktreeReaper: (deps) => void
+  - interface OrphanWorktreeReaperDeps
+  - interface OrphanReaperResult
+- `apps/coder/src/services/pending_changes.ts`
+  - function planEdit: (content, oldStr, newStr) => EditPlan
+  - function queueEdit: (sql, sessionId, taskId, filePath, oldString, newString, projectRoot, // v2.6 Phase 1-UX) => void
+  - function queueCreate: (sql, sessionId, taskId, filePath, content, projectRoot, // See queueEdit) => Promise<PendingChange>
+  - function queueDelete: (sql, sessionId, taskId, filePath, projectRoot, // See queueEdit) => Promise<PendingChange>
+  - function applyOne: (sql, changeId, projectRoot) => Promise<ApplyResult>
+  - function applyAll: (sql, sessionId, projectRoot) => Promise<ApplyResult[]>
+  - _...6 more_
+- `apps/coder/src/services/permission-waiter.ts`
+  - function setPermissionHooks: (next) => void
+  - function waitForPermissionResponse: (taskId, sessionId, provider, modeId, params, timeoutMs) => Promise<RequestPermissionResponse>
+  - function respondToPermission: (taskId, optionId, updatedInput?, unknown>) => boolean
+  - function getPendingPermission: (taskId) => PermissionPrompt | null
+  - function waitForElicitationResponse: (taskId, sessionId, provider, modeId, params, timeoutMs) => Promise<CreateElicitationResponse>
+  - function cancelPendingPermission: (taskId) => void
+  - _...3 more_
+- `apps/coder/src/services/provider-commands.ts`
+  - function getManifestCommands: (provider) => AgentCommand[]
+  - function mergeCommands: (...lists) => AgentCommand[]
+  - const PROVIDER_COMMANDS: Record<string, AgentCommand[]>
+- `apps/coder/src/services/provider-config-registry.ts`
+  - function buildResolvedRegistry: (builtins, config) => Map<string, ResolvedProviderDef>
+  - function loadProviderConfig: (path) => Map<string, ResolvedProviderDef>
+  - function reloadProviderConfig: () => Map<string, ResolvedProviderDef>
+  - function getResolvedRegistry: () => Map<string, ResolvedProviderDef>
+  - interface ResolvedProviderDef
+- `apps/coder/src/services/provider-config.ts`
+  - function mergeProviderConfigPatch: (current, patch) => CoderProvidersFile
+  - function load: (path) => CoderProvidersFile
+  - function save: (path, config) => void
+- `apps/coder/src/services/provider-diagnostic.ts` — function getProviderDiagnostic: (resolved, agentRow, opts) => Promise<string>, interface DiagnosticAgentRow
+- `apps/coder/src/services/provider-manifest.ts`
+  - function getManifestModes: (provider) => ProviderMode[]
+  - function getManifestDefaultModeId: (provider) => string | null
+  - function isUnattendedMode: (provider, modeId) => boolean
+  - interface ProviderManifestEntry
+  - const PROVIDER_MANIFEST: Record<string, ProviderManifestEntry>
+- `apps/coder/src/services/provider-snapshot.ts`
+  - function fetchLlamaSwapModels: (config) => Promise<ProviderModel[]>
+  - function prefixLlamaSwapModels: (models) => ProviderModel[]
+  - function mergeModels: (...lists) => ProviderModel[]
+  - function getProviderSnapshot: (sql, config, cwd?, force) => Promise<ProviderSnapshotEntry[]>
+  - function clearProviderSnapshotCache: () => void
+  - function peekSnapshotEntry: (name, cwd?) => ProviderSnapshotEntry | undefined
+  - _...1 more_
+- `apps/coder/src/services/pty-dispatch.ts`
+  - function dispatchViaPty: (opts) => Promise<DispatchResult>
+  - interface DispatchResult
+  - interface PtyDispatchOpts
+- `apps/coder/src/services/qwen-settings.ts` — function readQwenSettingsModels: () => Promise<ProviderModel[]>
+- `apps/coder/src/services/stream-json-parser.ts`
+  - function makeStreamJsonState: () => StreamJsonState
+  - function parseStreamJsonLine: (line, state) => AgentEvent[]
+  - function makeStreamJsonParser: () => StreamJsonParser
+  - interface StreamJsonUsage
+  - interface StreamJsonState
+  - interface StreamJsonParser
+  - _...1 more_
+- `apps/coder/src/services/token-analysis/analyzer.ts` — function analyzeMessages: (parts) => TokenBreakdown, interface TokenBreakdown
+- `apps/coder/src/services/token-analysis/persist.ts`
+  - function persistTaskBreakdown: (sql, taskId, breakdown) => Promise<void>
+  - function getTaskBreakdown: (sql, taskId) => Promise<TokenBreakdown | null>
+  - function analyzeAndPersistTaskBreakdown: (sql, taskId, parts) => Promise<TokenBreakdown>
+- `apps/coder/src/services/tools/adapter.ts` — function adaptWriteTool: (tool) => ServerToolDef<any>
+- `apps/coder/src/services/tools/inference_context.ts`
+  - function runWithInferenceContext: (ctx, fn) => void
+  - function getInferenceContext: () => InferenceContext
+  - interface InferenceContext
+- `apps/coder/src/services/tools/types.ts`
+  - function asPermissionMode: (id) => PermissionMode | undefined
+  - interface ToolJsonSchema
+  - interface ToolContext
+  - interface ToolDef
+  - type PermissionMode
+- `apps/coder/src/services/tools/write-gate.ts` — function denyReadOnly: (operation) => unknown, function finalizeWrite: (context, projectRoot, change, queuedHint) => Promise<unknown>
+- `apps/coder/src/services/worktree-risk.ts` — function checkWorktreeWorkAtRisk: (worktreePath, opts?) => Promise<WorktreeRiskReport>, function stashWorktree: (worktreePath, opts?) => Promise<
+- `apps/coder/src/services/worktrees.ts`
+  - function createWorktree: (projectPath, taskId, opts?) => Promise<string>
+  - function diffWorktree: (worktreePath, projectPath, opts?) => Promise<string>
+  - function cleanupWorktree: (projectPath, taskId) => Promise<void>
+  - function ensureSessionWorktree: (sql, projectPath, sessionId, opts?) => Promise<SessionWorktree>
+  - function removeSessionWorktree: (sql, projectPath, worktree, opts?) => Promise<void>
+  - function closeChatBackendState: (sql, chatId, opts?) => Promise<ChatCloseResult>
+  - _...4 more_
+- `apps/coder/src/services/write_guard.ts`
+  - function isSecretPath: (filePath) => boolean
+  - function resolveWritePath: (projectRoot, filePath) => string
+  - class WriteGuardError
+- `apps/server/src/config.ts` — function loadConfig: () => Config, type Config
+- `apps/server/src/db.ts`
+  - function getSql: (config) => Sql
+  - function applySchema: (sql) => Promise<void>
+  - function pingDb: (sql) => Promise<boolean>
+  - function closeDb: () => Promise<void>
+  - type Sql
+- `apps/server/src/services/agents.ts`
+  - function refreshToolNames: () => void
+  - function matchToolGlob: (toolName, patterns) => boolean
+  - function slugify: (name) => string
+  - function parseAgentsMd: (content) => ParseResult
+  - function isAgentRegistryMarkdown: (content) => boolean
+  - function getAgentsMtimes: (projectPath) => void
+  - _...2 more_
+- `apps/server/src/services/artifacts.ts`
+  - function deriveMarkdownSlug: (messageContent) => string
+  - function deriveHtmlSlug: (payload) => string
+  - function deriveHtmlTitle: (html) => string | null
+  - function detectHtmlArtifact: (text) => string | null
+  - function decideHtmlArtifactWrite: (htmlContent) => HtmlArtifactDecision
+  - function writeMarkdownArtifact: (message, 'content'>, ctx) => Promise<ArtifactWriteResult>
+  - _...6 more_
+- `apps/server/src/services/audit/corrections.ts`
+  - function createCorrection: (params) => UserCorrectionRecord
+  - function findCorrections: (records, unknown>[]) => UserCorrectionRecord[]
+  - function checkCorrectionConflict: (proposedAction, corrections) => UserCorrectionRecord | null
+  - interface UserCorrectionRecord
+- `apps/server/src/services/audit/guideline-store.ts`
+  - class GuidelineDocumentStore
+  - interface GuidelineContent
+  - interface Guideline
+  - interface GuidelineDocument
+  - interface GuidelineUpdateParams
+  - type GuidelineId
+  - _...3 more_
+- `apps/server/src/services/audit/journey-projection.ts`
+  - function projectJourneyToGuidelines: (journey, nodes, edges) => ProjectedGuideline[]
+  - function detectJourneyBacktrack: (journey, nodes, edges, currentNodeId, previousNodeId) => BacktrackCheck
+  - interface ProjectedGuideline
+  - interface BacktrackCheck
+- `apps/server/src/services/audit/journey-store.ts`
+  - class JourneyStore
+  - interface JourneyNode
+  - interface JourneyEdge
+  - interface Journey
+  - type JourneyId
+  - type JourneyNodeId
+  - _...1 more_
+- `apps/server/src/services/audit/runs-dir.ts`
+  - function findRunsDir: (projectRoot?) => string
+  - function ensureRunsDir: (projectRoot?) => string
+  - function readCurrentSession: (projectRoot?) => string | null
+  - function writeCurrentSession: (sessionId, projectRoot?) => void
+  - function clearCurrentSession: (projectRoot?) => void
+  - function readIndex: (projectRoot?) => IndexFile
+  - _...7 more_
+- `apps/server/src/services/audit/session-manager.ts`
+  - function generateSessionId: () => string
+  - function isoNow: () => string
+  - function createSession: (task, sessionId?, projectRoot?) => string
+  - function getSessionDir: (sessionId, projectRoot?) => string
+  - function getActiveSession: (projectRoot?) => SessionJson | null
+  - function readSession: (sessionId, projectRoot?) => SessionJson | null
+  - _...9 more_
+- `apps/server/src/services/auto_name.ts` — function maybeAutoNameChat: (ctx, chatId, sessionId) => Promise<void>
+- `apps/server/src/services/broker.ts`
+  - function createBroker: (log?) => Broker
+  - interface Broker
+  - type Frame
+  - type Listener
+- `apps/server/src/services/codecontext_client.ts`
+  - function callCodecontext: (req, fetcher) => Promise<CodecontextResponse>
+  - interface CodecontextRequest
+  - interface CodecontextResponse
+- `apps/server/src/services/coder-notify.ts` — function notifyCoderClose: (kind, id, log?, 'debug'>, fetcher) => Promise<boolean>, type CoderCloseKind
+- `apps/server/src/services/compaction.ts`
+  - function usable: (contextLimit) => number
+  - function isOverflow: (usage, contextLimit) => boolean
+  - function estimate: (messages) => number
+  - function turns: (messages) => Turn[]
+  - function select: (messages, contextLimit, tailTurns) => SelectResult
+  - function deriveFilesRead: (head) => string[]
+  - _...8 more_
+- `apps/server/src/services/file_index.ts` — function getProjectFiles: (projectId, projectRoot) => Promise<string[]>
+- `apps/server/src/services/file_ops.ts`
+  - function listDir: (projectRoot, relPath, opts?) => Promise<ListDirResult>
+  - function viewFile: (projectRoot, relPath, opts?) => Promise<ViewFileResult>
+  - function grep: (projectRoot, pattern, opts?) => Promise<GrepResult>
+  - function findFiles: (projectRoot, pattern?, opts?) => Promise<FindFilesResult>
+  - interface FileEntry
+  - interface ListDirResult
+  - _...4 more_
+- `apps/server/src/services/git_diff.ts`
+  - function parseNameStatus: (output) => void
+  - function parseNumStatLine: (line) => void
+  - function splitDiffByFile: (diffText) => Map<string, string>
+  - function classifyDiffBody: (body, cap) => 'diff' | 'binary' | 'too_large'
+  - function autoSelectMode: (isDirty) => GitDiffMode
+  - function canCommit: (files) => boolean
+  - _...17 more_
+- `apps/server/src/services/git_meta.ts` — function getGitMeta: (rootPath) => Promise<GitMeta | null>, interface GitMeta
+- `apps/server/src/services/gitea.ts`
+  - function createGiteaRepo: (cfg, name, options) => Promise<GiteaRepo>
+  - class GiteaRepoExistsError
+  - interface GiteaConfig
+  - interface GiteaRepo
+- `apps/server/src/services/grant_resolver.ts` — function resolveGrantRoot: (sql, requestedPath, projectRoot, whitelistRoot) => Promise<GrantResolution>, type GrantResolution
+- `apps/server/src/services/inference/budget.ts` — function resolveToolBudget: (agent) => number
+- `apps/server/src/services/inference/content-flusher.ts` — function createContentFlusher: (sql, messageId, getContent) => void, interface ContentFlusher
+- `apps/server/src/services/inference/dcp/messages.ts`
+  - function toDcpMessages: (parts) => DcpMessage[]
+  - function fromDcpMessages: (msgs) => any[]
+  - interface DcpMessage
+- `apps/server/src/services/inference/dcp/state.ts`
+  - function getDcpState: (chatId) => ChatDcpState | undefined
+  - function setDcpState: (chatId, messageCount) => void
+  - function clearDcpState: (chatId) => void
+  - function shouldTransform: (chatId, messageCount) => boolean
+- `apps/server/src/services/inference/dcp/strategies/deduplication.ts` — function deduplicate: (messages) => void
+- `apps/server/src/services/inference/dcp/strategies/purge-errors.ts` — function purgeErrors: (messages, windowSize) => void
+- `apps/server/src/services/inference/dcp/transform.ts`
+  - function transformMessages: (chatId, messages) => TransformResult
+  - interface TransformStats
+  - interface TransformResult
+- `apps/server/src/services/inference/error-handler.ts`
+  - function handleAbortOrError: (ctx, args, accumulated, err) => Promise<void>
+  - function finalizeStreamedRow: (ctx, opts) => void
+  - function finalizeEmpty: (ctx, args) => Promise<void>
+  - function finalizeCompletion: (ctx, args, result, startedAt, session) => Promise<void>
+- `apps/server/src/services/inference/llama-args-validator.ts`
+  - function validateExtraArgs: (args?) => string[]
+  - function isManagedFlag: (flag) => boolean
+  - function stripShadowingFlags: (args, opts?) => string[]
+  - interface StripOptions
+- `apps/server/src/services/inference/loop-detectors.ts`
+  - function detectContentRepeat: (messages) => LoopDetectionResult
+  - function detectToolLoop: (toolNames) => LoopDetectionResult
+  - function detectDoomLoop: (messages, toolNames) => LoopDetectionResult
+  - interface LoopDetectionResult
+- `apps/server/src/services/inference/mistake-tracker.ts`
+  - function freshMistakeState: () => MistakeState
+  - function recordStep: (state, outcome) => void
+  - function detectMistakePattern: (state) => 'nudge' | 'escalate' | null
+  - interface MistakeState
+  - type FailureKind
+  - const MISTAKE_THRESHOLD
+  - _...1 more_
+- `apps/server/src/services/inference/parts.ts`
+  - function insertParts: (sql, parts) => Promise<void>
+  - function partsFromAssistantMessage: (args) => void
+  - function partsFromToolMessage: (args) => Omit<PartInsert, 'message_id'>[]
+  - interface PartInsert
+  - type PartKind
+- `apps/server/src/services/inference/payload.ts`
+  - function buildMessagesPayload: (session, project, history, agent, log?) => Promise<OpenAiMessage[]>
+  - function loadContext: (sql, sessionId, chatId) => Promise<
+  - function maybeFlagForCompaction: (ctx, chatId, updated) => Promise<void>
+  - interface OpenAiMessage
+- `apps/server/src/services/inference/provider.ts`
+  - function resolveRoute: (agent, config?) => RoutingInfo
+  - function upstreamModel: (config, modelId, agent?) => LanguageModel
+  - interface RoutingInfo
+  - type InferenceRoute
+- `apps/server/src/services/inference/prune.ts`
+  - function selectPruneTargets: (partsNewestFirst, tailStartCreatedAt) => void
+  - function prune: (args) => Promise<PruneResult>
+  - interface PruneResult
+  - interface PartForPrune
+  - const PROTECTED_TOKENS
+  - const PRUNE_TRIGGER_TOKENS
+- `apps/server/src/services/inference/sentinel-summaries.ts`
+  - function runCapHitSummary: (ctx, args, session, project, history, agent, budget) => Promise<void>
+  - function runDoomLoopSummary: (ctx, args, session, project, history, agent, loop, unknown> }) => Promise<void>
+  - function runStepCapSummary: (ctx, args, session, project, history, agent, steps, cap) => Promise<void>
+  - function insertMistakeRecoverySentinel: (ctx, sessionId, chatId, opts) => Promise<void>
+- `apps/server/src/services/inference/sentinels.ts`
+  - function detectDoomLoop: (recentToolCalls) => void
+  - function isCapHitSentinel: (m) => boolean
+  - function isDoomLoopSentinel: (m) => boolean
+  - function isMistakeRecoverySentinel: (m) => boolean
+  - function isAnySentinel: (m) => boolean
+  - const DOOM_LOOP_THRESHOLD
+  - _...1 more_
+- `apps/server/src/services/inference/step-decision.ts`
+  - function decideStep: (input) => PreStepDecision
+  - function decidePostToolAction: (action, mistakeTracker) => PostToolDecision
+  - type PreStepDecision
+  - type PostToolDecision
+- `apps/server/src/services/inference/stream-error-classifier.ts` — function classifyStreamError: (err) => StreamErrorKind, type StreamErrorKind
+- `apps/server/src/services/inference/stream-phase-adapter.ts`
+  - function samplerOptsFromAgent: (agent) => SamplerOpts
+  - function streamCompletion: (ctx, model, messages, opts, onDelta) => void
+  - interface StreamAdapterContext
+  - interface StreamOptions
+  - type SamplerOpts
+  - const STALL_TIMEOUT_MS
+- `apps/server/src/services/inference/stream-phase.ts` — function executeStreamPhase: (ctx, args, session, messages, state, agent, // v1.11.8, web_search and web_fetch are stripped from the
+  // tool list sent to the LLM, so the model can't even attempt them.
+  webToolsEnabled) => Promise<StreamResult>
+- `apps/server/src/services/inference/tool-call-parser.ts`
+  - function stripToolMarkup: (text, opts?) => string
+  - function extractToolCallBlocks: (buffer, log?) => ToolCallExtraction
+  - interface ParsedCall
+  - interface ToolCallExtraction
+- `apps/server/src/services/inference/tool-phase.ts` — function executeToolPhase: (ctx, args, result, startedAt, session, projectRoot, agent?) => Promise<ToolPhaseResult>, interface ToolPhaseResult
+- `apps/server/src/services/inference/tool-shim.ts`
+  - function extractToolCalls: (text) => ParsedToolCall[]
+  - function hasToolCallMarkup: (text) => boolean
+  - interface ParsedToolCall
+- `apps/server/src/services/inference/tool-suggestions.ts`
+  - function levenshtein: (a, b) => number
+  - function suggestToolName: (name, available) => string | null
+  - function formatUnknownToolError: (name, available) => string
+- `apps/server/src/services/inference/turn-config.ts`
+  - function resolveTurnConfig: (agent) => TurnConfig
+  - interface TurnConfig
+  - const MAX_STEPS
+- `apps/server/src/services/inference/turn.ts`
+  - function runAssistantTurn: (ctx, args) => Promise<void>
+  - function runInference: (ctx, sessionId, chatId, assistantMessageId, signal?) => Promise<void>
+  - function createInferenceRunner: (ctx, 'publishUser'>, publishUserFn, frame) => void
+- `apps/server/src/services/mcp-client.ts`
+  - function initialize: (entries, logger) => Promise<void>
+  - function callTool: (prefixedName, args, unknown>) => Promise<unknown>
+  - function getTools: () => ToolDef<Record<string, unknown>>[]
+  - function getMcpServers: () => Array<
+  - function shutdown: () => Promise<void>
+  - function wrapMcpTool: (serverName, mcpTool) => ToolDef<Record<string, unknown>>
+  - _...2 more_
+- `apps/server/src/services/mcp-config.ts`
+  - function substituteEnvVars: (value, log, unsetVars?) => unknown
+  - function loadMcpConfig: (configPath, log) => McpServerEntry[]
+  - interface McpServerEntry
+  - type McpServerConfig
+- `apps/server/src/services/memory/entries.ts` — function parseMemoryEntries: (fileName, markdown) => MemoryEntry[], interface MemoryEntry
+- `apps/server/src/services/memory/paths.ts`
+  - function getMemoryRoot: (projectRoot) => string
+  - function getTopicDir: (root, topic) => string
+  - function ensureMemoryScaffold: (root) => Promise<void>
+  - type MemoryTopic
+- `apps/server/src/services/memory/prompt.ts` — function formatMemoryBlock: (entries) => string
+- `apps/server/src/services/memory/recall.ts` — function rankByRelevance: (query, entries) => MemoryEntry[], function loadMemoryForSession: (projectRoot, _sessionId?, query?) => Promise<string[]>
+- `apps/server/src/services/memory/scan.ts`
+  - function scanMemoryScopes: (scope) => Promise<MemoryEntry[]>
+  - function scanProjectMemory: (projectRoot) => Promise<MemoryEntry[]>
+  - interface MemoryScope
+- `apps/server/src/services/memory/store.ts` — function readTopicFiles: (root, topic) => Promise<Map<string, string>>, function writeEntry: (root, topic, title, content, tags) => Promise<void>
+- `apps/server/src/services/model-context.ts`
+  - function configureModelContext: (opts) => void
+  - function getModelContext: (model) => Promise<ModelContext | null>
+  - function invalidateModelContext: (model?) => void
+  - interface ModelContext
+- `apps/server/src/services/path_guard.ts`
+  - function resolveProjectRoot: (projectPath) => Promise<string>
+  - function pathGuard: (projectRoot, requested, extraRoots) => Promise<string>
+  - class PathScopeError
+- `apps/server/src/services/project_bootstrap.ts`
+  - function sanitizeFolderName: (raw) => string
+  - function bootstrapProject: (config, log, options) => Promise<BootstrapResult>
+  - class BootstrapNameError
+  - class BootstrapCollisionError
+  - class BootstrapPathError
+  - interface BootstrapResult
+- `apps/server/src/services/read_tab_by_number.ts`
+  - function executeReadTabByNumber: (input, sql, sessionId) => Promise<string>
+  - type ReadTabByNumberInputT
+  - const readTabByNumber: ToolDef<ReadTabByNumberInputT>
+- `apps/server/src/services/secret_guard.ts`
+  - function isSecretPath: (relPath) => boolean
+  - function filterSecretEntries: (entries, pathOf) => void
+  - class SecretBlockedError
+  - const DEFAULT_SECURITY_IGNORE_FILETYPES: ReadonlyArray<string>
+- `apps/server/src/services/skill-invoke.ts`
+  - function runSkillInvokeTransaction: (sql, args) => Promise<
+  - function buildSkillInvokeSyntheticFrames: (chatId, result, toolCall, skillBody) => SkillInvokeSessionFrame[]
+  - function buildSkillInvokeUserFrames: (chatId, userMessageId, userText) => SkillInvokeSessionFrame[]
+  - interface SkillInvokeTransactionResult
+  - interface SkillInvokeToolCall
+  - type SkillInvokeSessionFrame
+  - _...1 more_
+- `apps/server/src/services/skills.ts`
+  - function listSkills: () => Promise<Skill[]>
+  - function findSkills: (query) => Promise<SkillSummary[]>
+  - function getSkillBody: (name) => Promise<string | null>
+  - function getSkillResource: (name, relativePath) => Promise<SkillResourceResult>
+  - interface Skill
+  - interface SkillSummary
+  - _...2 more_
+- `apps/server/src/services/synthesisPipeline.ts`
+  - function runSynthesisPass: (p) => Promise<boolean>
+  - interface SynthesisParams
+  - const SYNTHESIS_TOOLS: ReadonlySet<string>
+- `apps/server/src/services/system-prompt.ts`
+  - function loadContainerGuidance: () => Promise<string | null>
+  - function getContainerGuidance: () => Promise<string | null>
+  - function _resetContainerGuidanceCacheForTests: () => void
+  - function _resetPrefixObserverForTests: () => void
+  - function buildSystemPromptWithFingerprint: (project, session, agent) => Promise<
+  - function buildSystemPrompt: (project, session, agent) => Promise<string>
+  - _...2 more_
+- `apps/server/src/services/task-model.ts` — function taskModelCompletion: (opts) => Promise<string>
+- `apps/server/src/services/task-search-rewrite.ts` — function rewriteSearchQuery: (userMessage) => Promise<string>
+- `apps/server/src/services/tools/codecontext/factory.ts` — function makeCodecontextTool: (opts, unknown>;
+  mapArgs) => void
+- `apps/server/src/services/tools/registry.ts` — function appendMcpTools: (mcpTools) => void, function toolJsonSchemas: () => ToolJsonSchema[]
+- `apps/server/src/services/tools/tiers.ts`
+  - function resolveToolTier: (tier) => readonly string[]
+  - const CORE_TOOL_NAMES
+  - const STANDARD_TOOL_NAMES
+- `apps/server/src/services/truncate.ts`
+  - function storeTruncation: (fullContent) => Promise<string>
+  - function readTruncation: (id) => Promise<string | null>
+  - function truncateIfNeeded: (args) => Promise<
+  - function cleanupTruncations: (args, msg) => void
+  - const TRUNCATION_DIR
+  - const TRUNCATION_TTL_MS
+  - _...1 more_
+- `apps/server/src/services/url_guard.ts` — function isPublicUrl: (input) => UrlGuardResult, interface UrlGuardResult
+- `apps/server/src/services/web/html-to-md.ts` — function htmlToMarkdown: (sourceHtml) => string
+- `apps/server/src/services/web_fetch.ts`
+  - function executeWebFetch: (input, fetcher) => Promise<WebFetchOutput>
+  - type WebFetchInputT
+  - type WebFetchOutput
+  - const webFetch: ToolDef<WebFetchInputT>
+- `apps/server/src/services/web_search.ts`
+  - function executeWebSearch: (input, searxngUrl, fetcher) => Promise<WebSearchOutput>
+  - interface WebSearchOutput
+  - type WebSearchInputT
+  - const webSearch: ToolDef<WebSearchInputT>
+- `apps/server/src/utils/string-utils.ts` — function stripQuotes: (s) => string
+- `apps/web/src/api/client.ts`
+  - class ApiError
+  - interface AgentSessionInfo
+  - interface CoderCheckpoint
+  - interface CoderRestoreResult
+  - const api
+- `apps/web/src/data/acp-provider-catalog.ts`
+  - function buildAcpProviderConfigPatch: (entry) => ProviderConfigPatch
+  - interface AcpCatalogEntry
+  - const ACP_PROVIDER_CATALOG: AcpCatalogEntry[]
+- `apps/web/src/hooks/terminal/useTerminalFit.ts`
+  - function cellSize: (term, container) => void
+  - function useTerminalFit: ({...}, containerRef, sessionId, paneId }) => TerminalFit
+  - interface TerminalFit
+- `apps/web/src/hooks/terminal/useTerminalSelection.ts`
+  - function useTerminalSelection: ({...}, containerRef, sessionId, paneId, label, send, }) => TerminalSelection
+  - interface TerminalSelectionActions
+  - interface TerminalSelection
+- `apps/web/src/hooks/terminal/useTerminalSocket.ts`
+  - function useTerminalSocket: ({...}, sessionId, paneId, fit, getSize, setSize, }) => TerminalSocket
+  - interface TerminalSocket
+  - type ConnState
+- `apps/web/src/hooks/useActivePane.ts`
+  - function setActivePaneInfo: (next) => void
+  - function clearActivePane: () => void
+  - function useActivePane: () => ActivePaneSnapshot
+  - interface ActivePaneSnapshot
+- `apps/web/src/hooks/useAgentSessions.ts` — function refreshAgentSessions: (sessionId) => Promise<AgentSessionInfo[]>, function useAgentSessions: (sessionId) => void
+- `apps/web/src/hooks/useAgentStatus.ts`
+  - function useAgentStatus: () => void
+  - interface AgentStatusEntry
+  - type AgentStatus
+- `apps/web/src/hooks/useArtifactDownload.ts` — function useArtifactDownload: (chatId, messageId, format) => void
+- `apps/web/src/hooks/useChatStatus.ts`
+  - function useChatStatus: (chatId) => DerivedStatus
+  - type RawStatus
+  - type DerivedStatus
+- `apps/web/src/hooks/useChatThroughput.ts`
+  - function recordUsage: (chatId, data) => void
+  - function useChatThroughput: (chatId) => ThroughputSample | null
+  - interface ThroughputSample
+- `apps/web/src/hooks/useCoderUserEvents.ts` — function useCoderUserEvents: () => void
+- `apps/web/src/hooks/useDiffPreferences.ts` — function useDiffPreferences: () => void, interface DiffPreferences
+- `apps/web/src/hooks/useGitDiff.ts` — function useGitDiff: (projectId) => void
+- `apps/web/src/hooks/useLongPress.ts` — function useLongPress: (callback) => void
+- `apps/web/src/hooks/useProjectGit.ts` — function useProjectGit: (projectId) => GitMeta | null
+- `apps/web/src/hooks/useProviderSnapshot.ts` — function refreshProviderSnapshot: (cwd?) => Promise<ProviderSnapshotEntry[]>, function useProviderSnapshot: (cwd?) => ProviderSnapshotEntry[] | null
+- `apps/web/src/hooks/usePullToRefresh.ts` — function usePullToRefresh: (onRefresh) => void
+- `apps/web/src/hooks/useSessionChats.ts`
+  - function useSessionChats: (sessionId, opts) => UseSessionChatsResult
+  - interface UseSessionChatsOpts
+  - interface UseSessionChatsResult
+- `apps/web/src/hooks/useSessionStream.ts` — function useSessionStream: (sessionId) => void
+- `apps/web/src/hooks/useSessions.ts` — function useSessions: (projectId) => void
+- `apps/web/src/hooks/useSidebar.ts` — function useSidebar: () => void
+- `apps/web/src/hooks/useSkills.ts` — function useSkills: () => void
+- `apps/web/src/hooks/useUserEvents.ts` — function useUserEvents: () => void
+- `apps/web/src/hooks/useViewport.ts` — function useViewport: () => ViewportSnapshot, interface ViewportSnapshot
+- `apps/web/src/hooks/useWorkspacePanes.ts`
+  - function activePaneChatId: (pane) => string | undefined
+  - function useWorkspacePanes: (sessionId) => UseWorkspacePanesResult
+  - interface UseWorkspacePanesResult
+  - const MAX_PANES
+- `apps/web/src/hooks/wsReconnectToast.ts` — function createWsReconnectToast: (opts) => WsReconnectToast, interface WsReconnectToast
+- `apps/web/src/lib/anim.ts`
+  - function getAnimBg: () => boolean
+  - function setAnimBg: (on) => void
+  - function setAnimDensity: (v) => void
+  - function setAnimSpeed: (v) => void
+  - function setAnimOpacity: (v) => void
+  - function useAnimBg: () => boolean
+  - _...3 more_
+- `apps/web/src/lib/attachments.ts`
+  - function looksBinary: (content) => boolean
+  - function inferLanguage: (filename) => string | null
+  - function flattenToMessage: (attachments, text) => string
+  - type Attachment
+  - const MAX_FILE_SIZE_BYTES
+  - const PASTE_INLINE_MAX_LINES
+  - _...1 more_
+- `apps/web/src/lib/coder-session.ts` — function isCoderSessionName: (name) => boolean
+- `apps/web/src/lib/coder-tools.ts`
+  - function wireToolCallToRun: (wire) => ToolRun
+  - function mergeWireToolCall: (existing, incoming, unknown> }) => CoderToolCallWire[]
+  - interface AcpWireMeta
+  - interface CoderToolCallWire
+- `apps/web/src/lib/format.ts`
+  - function relTime: (iso) => string
+  - function formatRelative: (iso) => string
+  - function formatAgo: (iso) => string
+- `apps/web/src/lib/model-label.ts` — function formatModelLabel: (raw) => string
+- `apps/web/src/lib/modelName.ts` — function shortenModelName: (model) => string | null
+- `apps/web/src/lib/permission-mode.ts`
+  - function nativeModeForPermission: (mode, modes, defaultModeId) => string | null
+  - function permissionForModeId: (modeId, modes) => PermissionMode
+  - function availablePermissionModes: (modes) => Array<
+  - type PermissionMode
+  - const PERMISSION_LABELS: Record<PermissionMode, string>
+- `apps/web/src/lib/projectUrls.ts` — function giteaUrlFor: (project) => string
+- `apps/web/src/lib/slash-command.ts`
+  - function isSlashCommandToken: (value) => boolean
+  - function slashQuery: (value) => string
+  - function parseSlashInput: (text) => void
+  - function mergeCommandsByName: (...lists) => T[]
+  - interface SlashCommandItem
+- `apps/web/src/lib/terminal-protocol.ts`
+  - function encodeInput: (text) => Uint8Array
+  - function encodeResize: (cols, rows) => string
+  - function parseServerFrame: (data) => ServerControlFrame | null
+  - type ServerControlFrame
+- `apps/web/src/lib/theme.ts`
+  - function isThemeId: (s) => s is ThemeId
+  - function applyTheme: (id, mode) => void
+  - function setTheme: (id, mode) => Promise<void>
+  - function useTheme: () => ThemeState
+  - interface ThemeMeta
+  - type ThemeId
+  - _...5 more_
+- `apps/web/src/lib/utils.ts` — function cn: (...inputs) => void
+- `apps/web/src/utils/diff-layout.ts`
+  - function parseDiff: (diffBody) => ParsedDiffFile[]
+  - function buildSplitRows: (file) => SplitRow[]
+  - function reconstructNewContent: (hunks) => string
+  - interface DiffLine
+  - interface DiffHunk
+  - interface ParsedDiffFile
+  - _...3 more_
+- `conductor/src/contracts.ts`
+  - function produceContract: (contracts) => string
+  - function reviewContract: (contracts) => string
+  - type Contract
+  - const EVIDENCE_PRODUCE
+  - const EVIDENCE_REVIEW
+  - const YAGNI_PRODUCE
+  - _...1 more_
+- `conductor/src/dispatch.ts`
+  - function loadPersona: (agent) => Promise<string>
+  - function dispatchAgent: (agent, task, opts) => Promise<string>
+  - function cleanOutput: (raw) => string
+- `conductor/src/flow.ts` — function runFlow: (flow, input, opts) => Promise<RunResult>, interface RunOptions
+- `conductor/src/flows/_util.ts` — function q, function repoLine
+- `conductor/src/flows/index.ts`
+  - function describeFlows: () => string
+  - function getFlow: (name) => Flow | undefined
+  - const FLOWS: Record<string, Flow>
+  - const FLOW_NAMES: string[]
+- `conductor/src/render.ts` — function slugify: (s) => string
+- `conductor/src/spine.ts`
+  - function readBand: (input) => Band
+  - function fastNote: (ctx) => string
+  - function buildSpineFlow: (spine) => Flow
+- `data/skills/superpowers/systematic-debugging/condition-based-waiting-example.ts`
+  - function waitForEvent: (threadManager, threadId, eventType, timeoutMs) => Promise<LaceEvent>
+  - function waitForEventCount: (threadManager, threadId, eventType, count, timeoutMs) => Promise<LaceEvent[]>
+  - function waitForEventMatch: (threadManager, threadId, predicate) => void
+- `packages/ion/src/cli/commands/abandon.ts` — function abandonCommand: (args, options) => Promise<void>
+- `packages/ion/src/cli/commands/approve.ts` — function approveCommand: (args, options) => Promise<void>
+- `packages/ion/src/cli/commands/cleanup.ts` — function cleanupCommand: (args, options) => Promise<void>
+- `packages/ion/src/cli/commands/convert.ts` — function convertCommand: (args, options) => Promise<void>
+- `packages/ion/src/cli/commands/list.ts` — function listCommand: (_args, options) => Promise<void>
+- `packages/ion/src/cli/commands/reject.ts` — function rejectCommand: (args, options) => Promise<void>
+- `packages/ion/src/cli/commands/resume.ts` — function resumeCommand: (args, options) => Promise<void>
+- `packages/ion/src/cli/commands/run.ts` — function runCommand: (args, options) => Promise<void>
+- `packages/ion/src/cli/commands/runs.ts` — function runsCommand: (args, options) => Promise<void>
+- `packages/ion/src/cli/commands/status.ts` — function statusCommand: (_args, options) => Promise<void>
+- `packages/ion/src/cli/commands/validate.ts` — function validateCommand: (args, options) => Promise<void>
+- `packages/ion/src/cli/index.ts` — function main: (argv) => void
+- `packages/ion/src/cli/utils.ts`
+  - function formatDuration: (ms) => string
+  - function formatTimestamp: (date) => string
+  - function truncate: (str, max) => string
+  - function printTable: (rows, unknown>[], columns) => void
+  - function printJson: (data) => void
+  - function parseArgs: (argv) => void
+  - _...3 more_
+- `packages/ion/src/engine/command-validation.ts` — function isValidCommandName: (name) => boolean
+- `packages/ion/src/engine/condition-evaluator.ts` — function evaluateCondition: (expression, nodeOutputs, Record<string, unknown>>) => boolean, class ConditionError
+- `packages/ion/src/engine/dag-executor.ts`
+  - function buildTopologicalLayers: (nodes) => DagNode[][]
+  - function checkTriggerRule: (node, nodeOutputs, NodeOutput>) => 'run' | 'skip'
+  - function executeNodeInternal: (node, deps, platform, conversationId, cwd, config, nodeOutputs, NodeOutput>, workflowVariables, unknown>) => Promise<NodeExecutionResult>
+  - function executeScriptNode: (node, cwd, envVars, string>, artifactsDir) => Promise<NodeExecutionResult>
+  - function handleApprovalNode: (node, deps, platform, conversationId, workflowRunId, nodeOutputs, NodeOutput>, workflowVariables, unknown>) => Promise<NodeExecutionResult>
+  - function handleLoopNode: (node, deps, platform, conversationId, cwd, config, nodeOutputs, NodeOutput>, workflowVariables, unknown>) => Promise<NodeExecutionResult>
+  - _...2 more_
+- `packages/ion/src/engine/event-emitter.ts`
+  - function getWorkflowEventEmitter: () => WorkflowEventEmitter
+  - class WorkflowEventEmitter
+  - interface WorkflowEventBase
+  - interface WorkflowStartedEvent
+  - interface WorkflowCompletedEvent
+  - interface WorkflowFailedEvent
+  - _...11 more_
+- `packages/ion/src/engine/executor-shared.ts`
+  - function substituteWorkflowVariables: (template, context) => string
+  - function buildPromptWithContext: (template, context, issueContext?) => string
+  - function classifyError: (error) => ErrorClassification
+  - function safeSendMessage: (platform, conversationId, message, metadata?, unknown>) => Promise<boolean>
+  - function detectCompletionSignal: (output, until) => boolean
+  - function stripCompletionTags: (output, until) => string
+  - _...5 more_
+- `packages/ion/src/engine/executor.ts`
+  - function executeWorkflow: (deps, platform, conversationId, cwd, workflow, userMessage, opts) => Promise<WorkflowExecutionResult>
+  - function hydrateResumableRun: (deps, candidate) => Promise<HydratedResumableRun>
+  - function resolveProjectPaths: (_deps, cwd, workflowRunId, codebaseId?) => ProjectPaths
+  - interface WorkflowExecutionOptions
+  - interface WorkflowExecutionResult
+  - interface HydratedResumableRun
+  - _...1 more_
+- `packages/ion/src/engine/model-validation.ts`
+  - function isLiteralSpec: (spec) => spec is LiteralModelSpec
+  - function buildAiProfile: (opts) => AiProfile
+  - function resolveModelSpec: (profile, modelRef) => LiteralModelSpec
+  - interface LiteralModelSpec
+  - interface ModelAliasPreset
+  - interface AiProfileTiers
+  - _...2 more_
+- `packages/ion/src/engine/output-ref.ts`
+  - function declaredFieldsFromSchema: (outputFormat, unknown> | string | undefined) => Set<string>
+  - function resolveNodeOutputField: (nodeOutput, unknown>, nodeId, field, declaredFields?) => OutputRefResult
+  - class OutputRefError
+  - interface OutputRefResult
+  - type OutputRefKind
+- `packages/ion/src/engine/utils.ts`
+  - function substituteWorkflowVariables: (template, variables, unknown>) => string
+  - function substituteNodeOutputRefs: (prompt, nodeOutputs, NodeOutput>, escapedForBash) => string
+  - function resolveNodeOutputField: (output, field) => string
+  - function buildPromptWithContext: (prompt, variables, unknown>, nodeOutputs, NodeOutput>, escapedForBash) => string
+  - function evaluateCondition: (condition, variables, unknown>) => boolean
+  - function classifyError: (error) => ErrorCategory
+  - _...10 more_
+- `packages/ion/src/format/sop-discovery.ts` — function discoverSopFiles: (cwd, globFn) => Promise<string[]>, type GlobFn
+- `packages/ion/src/format/sop-parser.ts`
+  - function parseSopContent: (markdown) => SopDocument
+  - interface SopParameter
+  - interface SopStep
+  - interface SopDocument
+- `packages/ion/src/format/sop-to-yaml.ts` — function convertSopToWorkflowYaml: (sop) => string
+- `packages/ion/src/schema/dag-node.ts`
+  - function isBashNode: (node) => node is BashNode
+  - function isScriptNode: (node) => node is ScriptNode
+  - function isLoopNode: (node) => node is LoopNode
+  - function isApprovalNode: (node) => node is ApprovalNode
+  - function isCancelNode: (node) => node is CancelNode
+  - function isPromptNode: (node) => node is PromptNode
+  - _...27 more_
+- `packages/ion/src/store/fs-store.ts` — function createFsStore: (basePath) => IWorkflowStore
+- `packages/ion/src/store/pg-store.ts` — function createPostgresStore: (connectionString) => Promise<IWorkflowStore>
+- `packages/ion/src/store/sqlite-store.ts` — function createSqliteStore: (dbPath) => Promise<IWorkflowStore>

.codesight/middleware.md

@@ -0,0 +1,23 @@
+# Middleware
+
+## auth
+- auth — `apps/booterm/src/auth.ts`
+- authoring — `apps/coder/src/conductor/flows/authoring.ts`
+- turn-guard.test — `apps/coder/src/services/backends/__tests__/turn-guard.test.ts`
+- turn-guard — `apps/coder/src/services/backends/turn-guard.ts`
+- get_middleware — `apps/server/src/services/tools/codecontext/get_middleware.ts`
+- authoring — `conductor/src/flows/authoring.ts`
+
+## custom
+- write_guard.test — `apps/coder/src/services/__tests__/write_guard.test.ts`
+- write_guard_fuzz.test — `apps/coder/src/services/__tests__/write_guard_fuzz.test.ts`
+- edit-guards-imports — `apps/coder/src/services/edit-guards-imports.ts`
+- write_guard — `apps/coder/src/services/write_guard.ts`
+- secret_guard.test — `apps/server/src/services/__tests__/secret_guard.test.ts`
+- path_guard — `apps/server/src/services/path_guard.ts`
+- secret_guard — `apps/server/src/services/secret_guard.ts`
+- url_guard — `apps/server/src/services/url_guard.ts`
+
+## validation
+- edit-guards — `apps/coder/src/services/edit-guards.ts`
+- path_guard.test — `apps/server/src/services/__tests__/path_guard.test.ts`

.codesight/routes.md

@@ -0,0 +1,141 @@
+# Routes
+
+## CRUD Resources
+
+- **`/api/battles`** GET | POST | GET/:id → Battle
+- **`/api/runs`** GET | POST | GET/:id → Run
+- **`/api/tasks`** GET | POST | GET/:id → Task
+- **`/api/chats/:id/messages`** GET | POST | GET/:id | DELETE/:id → Message
+- **`/api/projects`** GET | POST | GET/:id | PATCH/:id | DELETE/:id → Project
+- **`/api/sessions`** GET/:id | PATCH/:id | DELETE/:id → Session
+
+## Other Routes
+
+### fastify
+
+- `GET` `/api/term/health` params()
+- `POST` `/api/term/sessions/:sid/panes/:pid/start` params(sid, pid) [auth]
+- `POST` `/api/term/sessions/:sid/panes/:pid/kill` params(sid, pid) [auth]
+- `GET` `/ws/term/sessions/:sid/panes/:pid` params(sid, pid) [auth]
+- `GET` `/api/health` params() [auth, db, queue, ai]
+- `GET` `/api/sessions/:sessionId/agent-sessions` params(sessionId) [auth, db]
+- `POST` `/api/battles/generate-prompt` params() [auth, db]
+- `POST` `/api/battles/:id/stop` params(id) [auth, db]
+- `GET` `/api/battles/:id/analysis` params(id) [auth, db]
+- `POST` `/api/battles/:id/analyze` params(id) [auth, db]
+- `PATCH` `/api/battles/:id/winner` params(id) [auth, db]
+- `GET` `/api/battles/:id/contestants/:cid/diff` params(id, cid) [auth, db]
+- `POST` `/api/battles/:id/cross-examine` params(id) [auth, db]
+- `GET` `/api/sessions/:sessionId/checkpoints` params(sessionId) [auth, db]
+- `POST` `/api/sessions/:sessionId/checkpoints/:checkpointId/restore` params(sessionId, checkpointId) [auth, db]
+- `GET` `/api/inbox` params() [auth, db]
+- `POST` `/api/inbox/:id/retry` params(id) [auth, db]
+- `POST` `/api/chats/:chatId/close` params(chatId) [auth, db]
+- `POST` `/api/sessions/:sessionId/close` params(sessionId) [auth, db]
+- `GET` `/api/sessions/:sessionId/messages` params(sessionId) [auth, db, queue]
+- `POST` `/api/sessions/:sessionId/messages` params(sessionId) [auth, db, queue]
+- `POST` `/api/chats/:id/answer_user_input` params(id) [auth, db, queue]
+- `POST` `/api/sessions/:sessionId/stop` params(sessionId) [auth, db, queue]
+- `GET` `/api/sessions/:sessionId/pending` params(sessionId) [auth, db, queue]
+- `POST` `/api/sessions/:sessionId/pending/create` params(sessionId) [auth, db, queue]
+- `POST` `/api/sessions/:sessionId/pending/apply` params(sessionId) [auth, db, queue]
+- `POST` `/api/pending/:id/apply` params(id) [auth, db, queue]
+- `POST` `/api/pending/:id/reject` params(id) [auth, db, queue]
+- `POST` `/api/pending/:id/rewind` params(id) [auth, db, queue]
+- `GET` `/api/providers/snapshot` params() [db, cache]
+- `GET` `/api/providers/config` params() [db, cache]
+- `PATCH` `/api/providers/config` params() [db, cache]
+- `POST` `/api/providers/refresh` params() [db, cache]
+- `GET` `/api/providers/:id/diagnostic` params(id) [db, cache]
+- `POST` `/api/runs/:id/cancel` params(id) [auth, db]
+- `POST` `/api/sessions/:sessionId/skill_invoke` params(sessionId) [auth, db, queue]
+- `GET` `/api/stats/costs` params() [auth, db]
+- `POST` `/api/tasks/:id/cancel` params(id) [auth, db, cache, ai]
+- `GET` `/api/tasks/:id/permission` params(id) [auth, db, cache, ai]
+- `POST` `/api/tasks/:id/permission` params(id) [auth, db, cache, ai]
+- `GET` `/api/tasks/:id/commands` params(id) [auth, db, cache, ai]
+- `GET` `/api/sessions/:sessionId/worktree-risk` params(sessionId) [auth, db]
+- `POST` `/api/sessions/:sessionId/worktree-stash` params(sessionId) [auth, db]
+- `GET` `/api/ws/sessions/:sessionId` params(sessionId) [auth, db]
+- `GET` `/api/ws/user` params() [auth, db]
+- `GET` `/api/projects/:id/agents` params(id) [db, cache]
+- `POST` `/api/chats/:id/messages/:msg_id/artifacts/download` params(id, msg_id) [auth, db]
+- `GET` `/api/chats/:id/messages/:msg_id/html_artifact` params(id, msg_id) [auth, db]
+- `GET` `/api/projects/:project_id/artifacts/:filename` params(project_id, filename) [auth, db]
+- `GET` `/api/sessions/:id/chats` params(id) [auth, db]
+- `POST` `/api/sessions/:id/chats` params(id) [auth, db]
+- `PATCH` `/api/chats/:id` params(id) [auth, db]
+- `POST` `/api/sessions/:id/chats/archive-all` params(id) [auth, db]
+- `GET` `/api/sessions/:id/chats/open-count` params(id) [auth, db]
+- `POST` `/api/chats/:id/archive` params(id) [auth, db]
+- `POST` `/api/chats/:id/unarchive` params(id) [auth, db]
+- `DELETE` `/api/chats/:id` params(id) [auth, db]
+- `POST` `/api/chats/:id/fork` params(id) [auth, db]
+- `POST` `/api/chats/:id/discard_stale` params(id) [auth, db]
+- `GET` `/api/coder/ws/sessions/:sessionId` params(sessionId) [auth]
+- `ALL` `/api/coder/*` params() [auth]
+- `GET` `/api/settings/inference` params() [cache]
+- `PATCH` `/api/settings/inference` params() [cache]
+- `GET` `/api/sessions/:id/messages` params(id) [auth, db, queue]
+- `POST` `/api/chats/:id/messages/:message_id/regenerate` params(id, message_id) [auth, db, queue]
+- `POST` `/api/chats/:id/compact` params(id) [auth, db, queue]
+- `POST` `/api/chats/:id/stop` params(id) [auth, db, queue]
+- `POST` `/api/chats/:id/continue` params(id) [auth, db, queue]
+- `POST` `/api/chats/:id/force_send` params(id) [auth, db, queue]
+- `POST` `/api/chats/:id/grant_read_access` params(id) [auth, db, queue]
+- `GET` `/api/models` params()
+- `POST` `/api/projects/create` params() [auth, db]
+- `POST` `/api/projects/:id/archive` params(id) [auth, db]
+- `POST` `/api/projects/:id/unarchive` params(id) [auth, db]
+- `GET` `/api/projects/available` params() [auth, db]
+- `GET` `/api/projects/:id/list_dir` params(id) [auth, db]
+- `GET` `/api/projects/:id/view_file` params(id) [auth, db]
+- `GET` `/api/projects/:id/git` params(id) [auth, db]
+- `GET` `/api/projects/:id/git/diff` params(id) [auth, db]
+- `POST` `/api/projects/:id/git/stage` params(id) [auth, db]
+- `POST` `/api/projects/:id/git/unstage` params(id) [auth, db]
+- `POST` `/api/projects/:id/git/commit` params(id) [auth, db]
+- `POST` `/api/projects/:id/git/discard` params(id) [auth, db]
+- `POST` `/api/projects/:id/write_file` params(id) [auth, db]
+- `GET` `/api/projects/:id/files` params(id) [auth, db]
+- `GET` `/api/projects/:id/sessions` params(id) [auth, db]
+- `POST` `/api/projects/:id/sessions` params(id) [auth, db]
+- `PATCH` `/api/sessions/:id/workspace` params(id) [auth, db]
+- `POST` `/api/projects/:id/sessions/archive-all` params(id) [auth, db]
+- `GET` `/api/projects/:id/sessions/open-count` params(id) [auth, db]
+- `POST` `/api/sessions/:id/archive` params(id) [auth, db]
+- `POST` `/api/sessions/:id/unarchive` params(id) [auth, db]
+- `GET` `/api/settings` params() [db]
+- `PATCH` `/api/settings` params() [db]
+- `GET` `/api/sidebar` params() [auth, db]
+- `GET` `/api/skills` params() [auth, db, queue]
+- `POST` `/api/chats/:id/skill_invoke` params(id) [auth, db, queue]
+- `GET` `/api/tools/cost_stats` params() [auth, db]
+- `GET` `/api/ws/sessions/:id` params(id) [auth, db]
+
+### go-net-http
+
+- `GET` `/health` params() [queue]
+- `POST` `/v1/get_codebase_overview` params() [queue]
+- `POST` `/v1/get_file_analysis` params() [queue]
+- `POST` `/v1/get_symbol_info` params() [queue]
+- `POST` `/v1/search_symbols` params() [queue]
+- `POST` `/v1/get_dependencies` params() [queue]
+- `POST` `/v1/watch_changes` params() [queue]
+- `POST` `/v1/get_semantic_neighborhoods` params() [queue]
+- `POST` `/v1/get_framework_analysis` params() [queue]
+- `POST` `/v1/get_symbol_details` params() [queue]
+- `POST` `/v1/get_call_graph` params() [queue]
+- `POST` `/v1/get_blast_radius` params() [queue]
+
+## WebSocket Events
+
+- `WS` `message` — `apps/booterm/src/ws/attach.ts`
+- `WS` `close` — `apps/booterm/src/ws/attach.ts`
+- `WS` `message` — `apps/coder/src/cli.ts`
+- `WS` `error` — `apps/coder/src/cli.ts`
+- `WS` `close` — `apps/coder/src/cli.ts`
+- `WS` `close` — `apps/coder/src/routes/ws.ts`
+- `WS` `error` — `apps/coder/src/routes/ws.ts`
+- `WS` `close` — `apps/server/src/routes/ws.ts`
+- `WS` `error` — `apps/server/src/routes/ws.ts`

.codesight/schema.md

@@ -0,0 +1,157 @@
+# Schema
+
+### pending_changes
+- id: uuid (pk)
+- session_id: uuid (required, fk)
+- task_id: uuid (fk)
+- file_path: text (required)
+- operation: text (required)
+- diff: text (required)
+- status: text (required)
+
+### tasks
+- id: uuid (pk)
+- project_id: uuid (required, fk)
+- parent_task_id: uuid (fk)
+- state: text (required)
+- input: text (required)
+- output_summary: text
+- agent: text
+- model: text
+- execution_path: text
+- cost_tokens: integer
+- started_at: timestamp(tz)
+- ended_at: timestamp(tz)
+
+### available_agents
+- name: text (pk)
+- install_path: text
+- version: text
+- supports_acp: boolean (required)
+- last_probed_at: timestamp(tz)
+
+### agent_sessions
+- session_id: uuid (required, fk)
+- agent: text (required)
+- backend: text (required)
+- agent_session_id: text (fk)
+- server_port: integer
+- status: text (required)
+- last_active_at: timestamp(tz)
+
+### worktrees
+- id: uuid (pk)
+- session_id: uuid (fk)
+- project_id: uuid (fk)
+- path: text (required)
+- branch: text
+- base_commit: text
+- slug: text
+- status: text (required)
+
+### checkpoints
+- id: uuid (pk)
+- chat_id: uuid (required, fk)
+- session_id: uuid (fk)
+- worktree_id: uuid (fk)
+- message_id: uuid (fk)
+
+### claude_session_entries
+- id: bigint(auto) (pk)
+- project_key: text (required)
+- session_id: text (required, fk)
+- subpath: text (required)
+
+### flow_runs
+- id: uuid (pk)
+- project_id: uuid (required, fk)
+- flow_name: text (required)
+- band: text (required)
+- model: text (required)
+- status: text (required)
+- input: jsonb (required)
+- report: text
+- error: text
+
+### flow_steps
+- id: uuid (pk)
+- run_id: uuid (required, fk)
+- step_id: text (required, fk)
+- kind: text (required)
+- agent: text
+- status: text (required)
+- task_id: uuid (fk)
+- chat_id: uuid (fk)
+- input: text
+- output: text
+- error: text
+
+### battles
+- id: uuid (pk)
+- project_id: uuid (required, fk)
+- battle_type: text (required)
+- prompt: text (required)
+- status: text (required)
+- winner_contestant_id: uuid (fk)
+- results_path: text
+- error: text
+
+### contestants
+- id: uuid (pk)
+- battle_id: uuid (required, fk)
+- identity: text (required)
+- model: text (required)
+- lane: text (required)
+- task_id: uuid (fk)
+- worktree_id: uuid (fk)
+- status: text (required)
+- duration_ms: integer
+- tokens_per_sec: float8
+- cost_tokens: integer
+- result_path: text
+- error: text
+
+### cross_examinations
+- id: uuid (pk)
+- battle_id: uuid (required, fk)
+- identity: text (required)
+- model: text (required)
+- verdict: text
+
+### projects
+- id: uuid (pk)
+- name: text (required)
+- path: text (required)
+- added_at: timestamp(tz) (required)
+- last_session_id: uuid (fk)
+
+### sessions
+- id: uuid (pk)
+- project_id: uuid (required, fk)
+- name: text (required)
+- model: text (required)
+- system_prompt: text (required)
+
+### messages
+- id: uuid (pk)
+- session_id: uuid (required, fk)
+- role: text (required)
+- content: text (required)
+- status: text (required)
+- last_seq: integer (required)
+
+### message_parts
+- id: uuid (pk)
+- message_id: uuid (required, fk)
+- sequence: integer (required)
+- kind: text (required)
+- payload: jsonb (required)
+
+### settings
+- value: jsonb (required)
+
+### chats
+- id: uuid (pk)
+- session_id: uuid (required, fk)
+- name: text
+- status: text (required)

.env.example

@@ -20,6 +20,12 @@ SEARXNG_URL=http://100.114.205.53:8888
 # with FAST_MODEL when unset.
 # TASK_MODEL_URL=http://100.90.172.55:7995
 
+# DeepSeek API key. When set, models with IDs starting with 'deepseek-'
+# (e.g. deepseek-chat, deepseek-reasoner, deepseek-v4-flash) route through
+# DeepSeek's API instead of llama-swap. Requires a DeepSeek Platform API key.
+# DEEPSEEK_API_KEY=sk-...
+# DEEPSEEK_BASE_URL=https://api.deepseek.com
+
 # v1.13.15-tools: BOOCODE_TOOLS narrows the tool whitelist sent to the LLM.
 # Unset (default) → all tools (~21k schema). Useful primarily for single-purpose
 # sessions where the model only needs read-only filesystem access.

.learnings/HEALS.md

@@ -0,0 +1,37 @@
+# Self-healing log
+
+Verified fixes for runtime failures. Each entry documents a failure, its root cause, the applied fix, and the verification proof.
+
+**Pattern-Key discipline:** before filing a new HEAL, search this file for an existing Pattern-Key. If found, increment `Recurrence-Count` and update `Last-Seen` — do not duplicate.
+
+**Lifecycle:** verified heals at Recurrence-Count ≥ 3 across distinct tasks get a `Handoff` block for promotion to project memory (`CLAUDE.md`, `AGENTS.md`, or a skill).
+
+---
+
+## [HEAL-YYYYMMDD-XXX] short_kebab_name
+
+**Logged**: ISO-8601 timestamp
+**Status**: pending-verify
+**Trigger**: tool-failure | missing-capability | env-issue | external-change | <free-form>
+**Area**: free-form tag (e.g. `build`, `tests`, `ci`, `auth`, `data-pipeline`)
+**Priority**: low | medium | high | critical
+
+### Failure
+Concrete error: command, error message, exit code, blocked action.
+
+### Diagnosis
+Root cause as understood after investigation. What was verified during diagnosis.
+
+### Fix
+Patch applied. Verbatim commands, code snippets, or pointers to `.learnings/heals/<HEAL-ID>/`.
+
+### Verification
+What was run after the fix and what it returned. Exit code, output snippet, test pass count. **Proof.**
+
+### Metadata
+- Related Files: path/to/file.ext
+- See Also: HEAL-... | LRN-... | ERR-...
+- Pattern-Key: lower.snake.case (e.g. `env.lockfile_mismatch`)
+- Recurrence-Count: 1
+- First-Seen: YYYY-MM-DD
+- Last-Seen: YYYY-MM-DD

.omo/drafts/openspec-cleanup.md

@@ -0,0 +1,89 @@
+# Draft: openspec-cleanup
+
+## Cross-Reference: Git Tags vs openspec Batches
+
+### Archived Stub Files — Tag Verification
+
+| Stub File | Claims Version | Actual Tag | Verdict |
+|---|---|---|---|
+| `v1.13.12-skills-audit.md` (57B) | v1.13.12 | `v1.13.14-skills-audit` | **WRONG** — off by 2 versions |
+| `v1.13.15-codecontext-synth.md` (62B) | v1.13.15 | `v1.13.15-codecontext-synth` | ✅ correct |
+| `v1.13.17-cross-repo-reads.md` (61B) | v1.13.17 | `v1.13.17-cross-repo-reads` | ✅ correct |
+| `v1.13.18-codecontext-file-path.md` (66B) | v1.13.18 | `v1.13.18-codecontext-file-path` | ✅ correct |
+| `v1.13.20-drop-legacy-cols.md` (61B) | v1.13.20 | `v1.13.20-drop-legacy-cols` | ✅ correct |
+| `v1.14-outer-loop.md` (52B) | v1.14 | `v1.14.0-outer-loop` | ⚠️ close (1.14 → 1.14.0) |
+| `v1.14.1-mcp-poc.md` (51B) | v1.14.1 | `v1.14.1-mcp-poc` | ✅ correct |
+| `v1.14.x-html-artifact-panes.md` (63B) | v1.14.x | `v1.13.19-html-artifact-panes` | **WRONG** — shipped as 1.13.19 |
+| `v1.15-mcp-multi.md` (51B) | v1.15 | `v1.15.0-mcp-multi` | ⚠️ close (1.15 → 1.15.0) |
+| `v2.0-boocoder.md` (49B) | v2.0 | `v2.0.0` | ⚠️ close (2.0 → 2.0.0) |
+| `v2.2-paseo-providers.md` (222B) | v2.2 | `v2.2-paseo-providers` | ✅ correct |
+
+### Archived Folder Entries — Tag Verification
+
+| Archived Folder | Git Tag(s) | Status |
+|---|---|---|
+| `agent-status-normalize/` | `v2.7.6-agent-status-normalize` | ✅ shipped |
+| `claude-sdk-sessionstore/` | `v2.7.5-claude-sdk-sessionstore` | ✅ shipped |
+| `contracts-ssot/` | `v2.7.13-contracts-ssot` | ✅ shipped |
+| `license-debt-mit/` | `v2.7.0-mit` | ✅ shipped |
+| `mistake-tracker-file-ledger/` | `v2.7.4-mistake-tracker-ledger` | ✅ shipped (slug differs slightly) |
+| `orchestrator/` | `v2.7.17-orchestrator` | ✅ shipped |
+| `sampling-streamjson-tokens/` | `v2.7.3-sampling-streamjson-tokens` | ✅ shipped |
+| `v2-3-provider-lifecycle/` | `v2.5.4-*` through `v2.5.13-*` | ✅ shipped (diff version numbering) |
+| `v2-6-persistent-agent-sessions/` | `v2.6.4-*`, `v2.6.8-*` | ✅ shipped |
+| `write-edit-robustness/` | `v2.7.1-write-edit-robustness` | ✅ shipped |
+
+### Misplaced Proposals in Archived/
+
+| 2026-06-07 Folder | Git Tag? | Actually Shipped? | Should Be |
+|---|---|---|---|
+| `2026-06-07-boocontext/` | **None** | No | `changes/boocontext/` (partly shipped in v2.8.0) |
+| `2026-06-07-eval-sandbox-agent-runtime/` | **None** | No | Merge into `changes/import-*` |
+| `2026-06-07-hybrid-workflow-engine/` | **None** | No | Merge into `changes/orchestrator-flow-advanced/` |
+| `2026-06-07-memory-context-engineering/` | **None** | No | Merge into `changes/memory-context/` |
+| `2026-06-07-port-audit-parlant-patterns/` | **None** | No | Merge into `changes/add-behavioral-engine/` |
+
+## Active Batches — All Uncommitted, All Unshipped
+
+All 22 active batches (changes/*/) have **zero** git tags or commits referencing them. Every batch was created locally on 2026-06-07 and exists only on the filesystem.
+
+## High-Value Prioritization (for Implementation Plan)
+
+### Tier 1: Ship in Current Batch (small scope, high value)
+1. **openspec-cleanup** — Fix folder structure: delete stubs, move misplaced proposals, add .openspec.yaml, populate config.yaml
+2. **llama-cache-and-spec** — KV cache quantization + ngram speculative decoding (llama-server arg changes only)
+3. **results-page** — New `/results` route, uses existing API endpoints
+4. **token-analyzer-ui** — New `/analytics` route, uses existing DB data
+
+### Tier 2: Current+ Batch (moderate scope)
+5. **enhanced-file-panel** — Side-by-side diff, inline comments, in-browser editing
+6. **pty-enhancements** — Exit notifications, session metadata, X-Agent-Flags
+
+### Tier 3: Next Batch (larger scope, foundation work)
+7. **memory-v2-hybrid-search** — BM25 + local embedding hybrid search
+8. **orchestrator-flow-advanced** — Trigger rules, conditional branching, HITL
+9. **omo-paseo-bridge** — OMO subagent visibility in Paseo
+
+### Tier 4: Future Batches (speculative / big effort)
+10. **add-behavioral-engine** / **audit-harness-integration** / **import-llm-evaluator** / **import-pregel-engine** — Big integration efforts
+11. **code-intelligence-upgrade** / **dev-workflow** / **conductor-evolution** — Platform work
+12. **plugin-platform** / **ui-overhaul** / **add-3tier-memory** / **add-type-inject-mcp** — Future
+
+## Scope Boundaries for This Plan
+
+**IN SCOPE:**
+- Delete 11 stub files from archived/
+- Move 5 misplaced 2026-06-07 proposals from archived/ to changes/ (with dedup)
+- Add missing .openspec.yaml to 6 active batches
+- Populate openspec/config.yaml with project context
+- Implement Tier 1-2 high-value batches:
+  - llama-cache-and-spec (llama-server args)
+  - results-page (new route, frontend)
+  - token-analyzer-ui (new route, frontend + backend)
+  - enhanced-file-panel (frontend changes)
+  - pty-enhancements (backend changes)
+
+**OUT OF SCOPE:**
+- Tier 3-4 batches (future planning)
+- Full behavioral engine or Pregel state machine integration
+- Plugin platform architecture

.omo/plans/enhanced-file-panel.md

@@ -0,0 +1,485 @@
+# Enhanced File Panel — Implementation Plan
+
+## TL;DR
+
+> **Quick Summary**: Add side-by-side diff, hide whitespace, wrap lines, expand all files, inline diff comments, and in-browser file editing to BooCode's right-rail file panel.
+>
+> **Deliverables**:
+> - Enhanced `GitDiffView.tsx` with toolbar (layout/whitespace/wrap/expand-all toggles)
+> - Split-layout diff renderer (side-by-side)
+> - `useDiffPreferences` hook (localStorage persistence)
+> - Inline diff comment components + Zustand store
+> - File editing mode in file tree + server write endpoint
+> - Server `git diff -w` support
+>
+> **Estimated Effort**: Medium-Large
+> **Parallel Execution**: YES — 4 waves
+> **Critical Path**: Wave 1 (server) → Wave 2 (diff preferences + toolbar) → Wave 3 (split layout) → Wave 4 (comments + editing)
+
+---
+
+## Context
+
+### Original Request
+User wants to implement these features from Paseo into BooCode's file manager:
+1. Unified diff ✅ (exists) / Side by side diff ❌
+2. Hide whitespace ❌
+3. Wrap long lines ❌
+4. Expand all files ❌ (only per-file)
+5. Refresh ✅ (exists)
+6. Comments on specific diffs ❌
+7. File edits (editing in the file browser) ❌
+
+### Research Findings
+- **Paseo** (`/opt/forks/paseo`): Best reference for all features. Key files: `diff-pane.tsx`, `diff-layout.ts`, `diff-rendering.ts`, `review/surface.tsx`, `review/store.ts`, `use-changes-preferences/`
+- **Existing BooCode files**: `GitDiffView.tsx`, `RightRail.tsx`, `useGitDiff.ts`, `git_diff.ts`, `FileViewerOverlay.tsx`
+- Key insight: None of the web references have true inline file editing in the browser — this is new ground
+
+---
+
+## Work Objectives
+
+### Core Objective
+Augment the existing file panel with side-by-side diff, whitespace/wrap/expand toggles, inline comments, and inline file editing.
+
+### Definition of Done
+- [x] `pnpm -C apps/web build` succeeds with no errors
+- [x] `pnpm -C apps/server build` succeeds with no errors
+- [ ] Side-by-side diff renders correctly (two aligned columns)
+- [ ] Hide whitespace toggles and re-fetches diff
+- [ ] Wrap lines toggles between pre / pre-wrap
+- [ ] Expand/Collapse all toggles all file diffs
+- [ ] Inline comments: click gutter → type → save → display thread
+- [ ] File edit: double-click tree → edit → save → file changes on disk
+- [ ] All preferences persist across page refresh
+
+### Must Have
+- Side-by-side diff view
+- Hide whitespace toggle (server param)
+- Wrap long lines toggle (CSS)
+- Expand/Collapse all file diffs
+- Inline diff comments with thread UI
+- In-browser file editing with save
+- Preference persistence
+
+### Must NOT Have (Guardrails)
+- No DB migration (comments are client-side)
+- No new WS frames (reuse git_diff_refresh)
+- No new `@boocode/contracts` types
+- No multi-user comment sharing
+- No git push/pull/PR operations
+- No inline hunk staging
+
+---
+
+## Verification Strategy
+
+### Test Decision
+- **Infrastructure exists**: YES (vitest for server)
+- **Automated tests**: Tests-after for new server route + `git_diff.ts` changes
+- **Agent-Executed QA**: Playwright for diff interactions, curl for API endpoints
+
+### QA Policy
+Every task includes agent-executed scenarios. Evidence saved to `.omo/evidence/`.
+
+---
+
+## Execution Strategy
+
+### Waves
+
+```
+Wave 1 (Server — foundation):
+├── Task 1: Server: whitespace param in git_diff.ts
+├── Task 2: Server: POST /api/projects/:id/write_file endpoint
+├── Task 3: Server tests for whitespace + write
+└── [tests + typecheck]
+
+Wave 2 (Frontend — preferences + toolbar):
+├── Task 4: useDiffPreferences hook (localStorage)
+├── Task 5: GitDiffView toolbar (layout/whitespace/wrap/expand-all toggles)
+├── Task 6: Wrap lines CSS + hide whitespace re-fetch
+└── [pnpm build]
+
+Wave 3 (Frontend — split layout):
+├── Task 7: Diff layout utilities (buildSplitDiffRows etc.)
+├── Task 8: Side-by-side renderer in GitDiffView
+├── Task 9: Line number gutter + alignment
+└── [pnpm build]
+
+Wave 4 (Frontend — comments + file editing):
+├── Task 10: InlineComment store (Zustand + localStorage)
+├── Task 11: InlineReviewGutterCell + InlineReviewEditor
+├── Task 12: InlineReviewThread (comment display)
+├── Task 13: File editing mode in RightRail file tree
+└── [pnpm build + full smoke test]
+```
+
+Critical Path: T1 → T2 → T4 → T5 → T7 → T8 → T10 → T11 → T12 → T13
+
+---
+
+## TODOs
+
+- [x] 1. **Server: Add `ignoreWhitespace` param to git diff**
+
+  **What to do**:
+  - In `apps/server/src/services/git_diff.ts`, add `ignoreWhitespace?: boolean` to the `getGitDiff` function signature
+  - When `ignoreWhitespace` is true, append `'-w'` to the git diff argv call in `getGitDiff` (the main diff command, not name-status)
+  - Update `GET /api/projects/:id/git/diff` route in `routes/projects.ts` to accept optional query param `whitespace=1`
+  - The param should be optional (backward compatible) — default false
+
+  **Files to modify**:
+  - `apps/server/src/services/git_diff.ts` — update `getGitDiff()` to accept and use `ignoreWhitespace`
+  - `apps/server/src/routes/projects.ts` — add `whitespace` query param
+
+  **References**:
+  - Paseo: `useCheckoutDiffQuery({ ignoreWhitespace })` passes to server → `git diff -w`
+  - Existing `git_diff.ts:36-48` `runGit` function — argv pattern to follow
+
+  **QA Scenarios**:
+  ```
+  Scenario: Diff with whitespace changes respects ignoreWhitespace param
+    Tool: Bash (curl)
+    Preconditions: A file exists with whitespace-only changes (extra spaces)
+    Steps:
+      1. GET /api/projects/:id/git/diff ⇒ verify diff_body includes whitespace changes
+      2. GET /api/projects/:id/git/diff?whitespace=1 ⇒ verify diff_body excludes whitespace-only changes
+    Expected: With whitespace=1, files that only had whitespace changes show as unchanged
+    Evidence: .omo/evidence/task-1-whitespace.txt
+  ```
+
+- [x] 2. **Server: Add POST /api/projects/:id/write_file endpoint**
+
+  **What to do**:
+  - Add `POST /api/projects/:id/write_file` route in `routes/projects.ts`
+  - Accept `{ path: string, content: string }` body
+  - Validate path via existing `pathGuard` helper (same as git discard)
+  - Write file content atomically: write to `.tmp` then `rename` the file
+  - Return `{ ok: boolean }` on success
+  - Reuse the safe file-write pattern from `services/file_ops.ts`
+
+  **Files to modify**:
+  - `apps/server/src/routes/projects.ts` — add POST route
+  - `apps/web/src/api/client.ts` — add `writeFile` method
+  - `apps/web/src/api/types.ts` — add write types if needed
+
+  **References**:
+  - `apps/server/src/services/file_ops.ts` — existing file operations pattern
+  - `apps/server/src/routes/projects.ts:544-592` — git write routes (same security pattern)
+  - `apps/server/src/services/path_guard.ts` — path validation
+
+  **QA Scenarios**:
+  ```
+  Scenario: Write file content and verify on disk
+    Tool: Bash (curl)
+    Preconditions: A project exists with a writable path
+    Steps:
+      1. POST /api/projects/:id/write_file { path: "test.txt", content: "hello" }
+      2. GET /api/projects/:id/view_file?path=test.txt
+    Expected: Status 200, view_file returns "hello"
+    Evidence: .omo/evidence/task-2-write.txt
+  ```
+
+- [x] 3. **Frontend: useDiffPreferences hook**
+
+  **What to do**:
+  - Create `apps/web/src/hooks/useDiffPreferences.ts`
+  - Define `DiffPreferences` interface: `{ layout: 'unified'|'split', wrapLines: boolean, hideWhitespace: boolean }`
+  - Default: `{ layout: 'unified', wrapLines: false, hideWhitespace: false }`
+  - Read/write to localStorage key `boocode.diff.preferences`
+  - Return `{ preferences, updatePreferences, resetPreferences }`
+  - Zod-validate on read for forward compatibility
+
+  **Files to create/modify**:
+  - Create `apps/web/src/hooks/useDiffPreferences.ts`
+
+  **References**:
+  - `/opt/forks/paseo/packages/app/src/hooks/use-changes-preferences/storage.ts` — exact pattern
+  - `apps/web/src/hooks/useProjectGit.ts` — hooks pattern in BooCode
+
+  **QA Scenarios**:
+  ```
+  Scenario: Preferences persist across page refresh
+    Tool: Playwright
+    Preconditions: Page loaded
+    Steps:
+      1. Call updatePreferences({ layout: 'split' })
+      2. Read localStorage.getItem('boocode.diff.preferences')
+      3. Reload page, read preferences again
+    Expected: layout is 'split' after reload
+    Evidence: .omo/evidence/task-3-prefs.txt
+  ```
+
+- [x] 4. **Frontend: GitDiffView toolbar with all toggles**
+
+  **What to do**:
+  - Add a toolbar row inside `GitDiffView.tsx` between the mode selector and file list
+  - Controls (left to right):
+    - **Layout toggle**: two-segment button (Unified | Split) — uses `AlignJustify` / `Columns2` icons
+    - **Hide whitespace**: toggle button — `Pilcrow` icon, active state highlights
+    - **Wrap lines**: toggle button — `WrapText` icon  
+    - **Expand/Collapse all**: toggle button — `ListChevronsUpDown` / `ListChevronsDownUp` icons
+    - **Refresh**: existing button (already present)
+  - Wire each toggle to the `useDiffPreferences` hook
+  - Expand all state: compute `allExpanded = files.every(f => expandedPaths.has(f.path))`
+  - Pass expand state as a new prop or local state
+
+  **Files to modify**:
+  - `apps/web/src/components/GitDiffView.tsx` — add toolbar section, expand-all logic
+
+  **References**:
+  - Paseo `diff-pane.tsx:1114-1273` — `DiffLayoutToggleGroup`, `DiffWhitespaceToggle`, `DiffFilesToolbar`
+  - openchamber `DiffViewToggle.tsx` — simple toggle pattern
+  - happy `InlineFileDiff.tsx:196-219` — `DiffStyleToggle` segment control
+
+  **QA Scenarios**:
+  ```
+  Scenario: All toolbar controls render and toggle
+    Tool: Playwright
+    Preconditions: Git tab active with changed files
+    Steps:
+      1. Verify layout toggle shows "Unified" / "Split" buttons
+      2. Click "Split" — verify visual change
+      3. Click "Wrap" — verify wrap toggle
+      4. Click "Expand all" — verify all files expand
+      5. Click "Collapse all" — verify all files collapse
+    Expected: Each toggle works and updates state
+    Evidence: .omo/evidence/task-4-toolbar.png
+  ```
+
+- [x] 5. **Frontend: Diff layout utilities + side-by-side renderer**
+
+  **What to do**:
+  - Create `apps/web/src/utils/diff-layout.ts` with pure functions:
+    - `buildNumberedDiffHunks(diffBody: string): NumberedDiffHunk[]` — parse diff text into hunks with old/new line numbers
+    - `buildUnifiedDiffLines(file): UnifiedDiffDisplayLine[]` — existing behavior
+    - `buildSplitDiffRows(file): SplitDiffRow[]` — pair removals/additions into left/right rows
+  - Create `apps/web/src/components/DiffSplitView.tsx` — the side-by-side renderer:
+    - Two columns (left = deletions, right = additions) with a thin divider
+    - Each column has its own gutter (line numbers) + code content
+    - Use Shiki `codeToHtml(language)` for syntax highlighting per side
+    - Handle empty cells (unpaired lines render as blank)
+  - In `GitDiffView.tsx`, when `layout === 'split'`, render `DiffSplitView` instead of the unified diff body
+
+  **Files to create/modify**:
+  - Create `apps/web/src/utils/diff-layout.ts`
+  - Create `apps/web/src/components/DiffSplitView.tsx`
+  - Modify `apps/web/src/components/GitDiffView.tsx` — add layout branching
+
+  **References**:
+  - `/opt/forks/paseo/packages/app/src/utils/diff-layout.ts` — full algorithm
+  - `/opt/forks/paseo/packages/app/src/git/diff-pane.tsx:968-989` — split layout rendering
+  - existing `git_diff.ts` `splitDiffByFile` — already splits unified diff per file
+
+  **QA Scenarios**:
+  ```
+  Scenario: Side-by-side diff renders correctly
+    Tool: Playwright
+    Preconditions: Git tab active, files with changes
+    Steps:
+      1. Click "Split" layout toggle
+      2. Verify two columns appear with a divider
+      3. Verify deleted lines are on left side (red background)
+      4. Verify added lines are on right side (green background)
+      5. Verify context lines appear on both sides, aligned
+    Expected: Layout matches Paseo's split diff
+    Evidence: .omo/evidence/task-5-splitdiff.png
+  ```
+
+- [x] 6. **Frontend: Inline comment store + Zustand**
+
+  **What to do**:
+  - Create `apps/web/src/stores/useDiffCommentStore.ts`
+  - Define `DiffComment` interface: `{ id, filePath, side, lineNumber, body, createdAt, updatedAt }`
+  - Create Zustand store with:
+    - `commentsByKey: Map<string, DiffComment[]>` keyed by `${sessionId}:${mode}:${filePath}`
+    - `addComment(key, comment)` / `updateComment(key, id, body)` / `deleteComment(key, id)`
+    - `loadComments(key)` — load from localStorage
+    - `persist()` — subscribe to store changes, write to localStorage key `boocode.diff.comments.[key]`
+  - Export `useDiffCommentStore`
+
+  **Files to create**:
+  - Create `apps/web/src/stores/useDiffCommentStore.ts`
+
+  **References**:
+  - `/opt/forks/paseo/packages/app/src/review/store.ts` — zustand store for comments
+  - `/opt/forks/paseo/packages/app/src/review/state.ts` — CRUD operations
+
+  **QA Scenarios**:
+  ```
+  Scenario: Comments persist across page refresh
+    Tool: Playwright
+    Preconditions: Diff panel open with changes
+    Steps:
+      1. Add comment on a diff line
+      2. Verify comment thread appears
+      3. Reload page
+      4. Navigate to same diff
+    Expected: Comment thread still visible after reload
+    Evidence: .omo/evidence/task-6-comment-store.txt
+  ```
+
+- [x] 7. **Frontend: InlineReviewGutterCell + InlineReviewEditor**
+
+  **What to do**:
+  - Create `apps/web/src/components/InlineReviewGutterCell.tsx`:
+    - Replaces the plain line-number display in diff rows
+    - Shows line number + "+" icon on hover (to start a comment)
+    - Uses `ReviewableDiffTarget { filePath, side, lineNumber }` for tracking
+  - Create `apps/web/src/components/InlineReviewEditor.tsx`:
+    - Textarea with placeholder "Add comment..."
+    - Save (Ctrl+Enter) / Cancel (Escape) buttons
+    - Animates in below the target line
+  - Integrate into `GitDiffView.tsx` — gutter cells render in the diff line view
+  - Wire to `useDiffCommentStore`
+
+  **Files to create/modify**:
+  - Create `apps/web/src/components/InlineReviewGutterCell.tsx`
+  - Create `apps/web/src/components/InlineReviewEditor.tsx`
+  - Modify `apps/web/src/components/GitDiffView.tsx` — integrate gutter cells
+
+  **References**:
+  - Paseo `review/surface.tsx:245-309` — `DiffGutterCell` + `InlineReviewGutterCell`
+  - Paseo `InlineReviewEditor` pattern
+
+  **QA Scenarios**:
+  ```
+  Scenario: Create inline comment on diff line
+    Tool: Playwright
+    Preconditions: Git tab, file expanded
+    Steps:
+      1. Hover over a gutter cell
+      2. Click "+" button
+      3. Type comment text
+      4. Click Save (or Ctrl+Enter)
+    Expected: Comment thread appears below the line
+    Evidence: .omo/evidence/task-7-comment-create.png
+  ```
+
+- [x] 8. **Frontend: InlineReviewThread component**
+
+  **What to do**:
+  - Create `apps/web/src/components/InlineReviewThread.tsx`:
+    - Renders below a diff line when comments exist for that target
+    - Each comment shown as a card: avatar placeholder, body, timestamp, edit/delete actions
+    - Collapsed state shows comment count badge
+    - Expanded state shows full thread
+  - Integrate into `GitDiffView.tsx` below diff line rows
+
+  **Files to create/modify**:
+  - Create `apps/web/src/components/InlineReviewThread.tsx`
+  - Modify `apps/web/src/components/GitDiffView.tsx` — render thread below lines
+
+  **Reference**:
+  - Paseo `review/surface.tsx:537-573` — `InlineReviewThreadContent`
+
+  **QA Scenarios**:
+  ```
+  Scenario: Comment thread displays and supports edit/delete
+    Tool: Playwright
+    Preconditions: Comments exist on a diff line
+    Steps:
+      1. Expand comment thread
+      2. Verify comment body is visible with timestamp
+      3. Click edit → modify text → save
+      4. Click delete → verify comment removed
+    Expected: Full CRUD works on comments
+    Evidence: .omo/evidence/task-8-thread.png
+  ```
+
+- [x] 9. **Frontend: File editing in the file tree**
+
+  **What to do**:
+  - In `RightRail.tsx`, add a file edit mode:
+    - Double-click a file in the tree (or context menu "Edit") enters edit mode
+    - The file row transforms: file name becomes a monospace textarea pre-filled with file content (fetched via existing `api.projects.viewFile`)
+    - The row shows Save / Cancel buttons
+    - Save: calls `api.projects.writeFile(projectId, path, content)` — the new endpoint from Task 2
+    - Cancel: reverts to the original content and exits edit mode
+    - After save: re-fetch the file tree + emit `git_diff_refresh`
+  - Only one file editable at a time (close any existing editor before opening new)
+  - Visual indicator (highlighted row) when in edit mode
+
+  **Files to modify**:
+  - `apps/web/src/components/RightRail.tsx` — add edit mode state, edit UI
+  - `apps/web/src/api/client.ts` — add `writeFile` method (from Task 2)
+  - `apps/web/src/components/TreeLevel.tsx` (inline in RightRail) — accept edit mode props
+
+  **References**:
+  - Existing `RightRail.tsx:170-175` `openFile` function — pattern for file interaction
+  - Existing `FileViewerOverlay.tsx` — Shiki highlighting reference
+  - Paseo `file-explorer-pane.tsx` — context menu actions pattern
+
+  **QA Scenarios**:
+  ```
+  Scenario: Edit file in file tree and save
+    Tool: Playwright
+    Preconditions: Project with a text file
+    Steps:
+      1. Double-click a file in the file tree
+      2. Verify file enters edit mode (textarea replaces filename)
+      3. Modify content
+      4. Ctrl+Enter to save
+      5. Verify success indicator
+    Expected: File content updated on disk, tree refreshes
+    Evidence: .omo/evidence/task-9-edit-save.png
+
+  Scenario: Cancel file edit reverts changes
+    Tool: Playwright
+    Preconditions: File in edit mode
+    Steps:
+      1. Modify content in textarea
+      2. Click Cancel / press Escape
+      3. Re-open file
+    Expected: Original content preserved, edit mode exited
+    Evidence: .omo/evidence/task-9-edit-cancel.txt
+  ```
+
+---
+
+## Final Verification
+
+- [ ] F1. **Plan Compliance Audit** — `oracle`
+  Verify all Must Have features are implemented, Must NOT Have are absent.
+  Output: VERDICT
+
+- [ ] F2. **Code Quality** — `unspecified-high`
+  Run `pnpm -C apps/web build`, `pnpm -C apps/server build`, check for `as any`/`@ts-ignore`/console.log.
+  Output: VERDICT
+
+- [ ] F3. **Real Manual QA** — `unspecified-high` + `playwright`
+  Execute all QA scenarios from every task, capture evidence.
+  Output: Scenarios [N/N pass]
+
+- [ ] F4. **Scope Fidelity** — `deep`
+  Verify spec matches implementation, no scope creep.
+  Output: Tasks [N/N compliant]
+
+---
+
+## Commit Strategy
+
+- **1**: `feat(server): add whitespace param to git diff + write_file endpoint`
+- **2**: `feat(web): diff preferences hook, toolbar toggles, split layout`
+- **3**: `feat(web): inline diff comments with zustand store`
+- **4**: `feat(web): in-browser file editing in file tree`
+
+---
+
+## Success Criteria
+
+### Verification Commands
+```bash
+pnpm -C apps/web build     # Must pass
+pnpm -C apps/server build  # Must pass
+```
+
+### Final Checklist
+- [ ] Side-by-side diff renders correctly
+- [ ] Hide whitespace re-fetches with `-w`
+- [ ] Wrap lines toggles CSS
+- [ ] Expand/Collapse all toggles
+- [ ] Inline comments: create, read, update, delete
+- [ ] File editing: read, modify, save, cancel
+- [ ] All preferences survive page reload

.omo/plans/paseo-orchestrator.md

@@ -0,0 +1,239 @@
+# Paseo-like Orchestrator — Implementation Plan
+
+> **Goal:** Transform BooCode into a Paseo-style thin-client orchestration layer with observability, dynamic workflows, resumability, background subagents, multi-modal, and cache shape telemetry.
+>
+> **Architecture:** Durable agent execution engine beneath thin chat/coder frontends. Trace system as foundation, workflow engine as the structural addition, everything else layered on top.
+>
+> **Inspired by:** Paseo (agent lifecycle, worktree isolation), Whale (workflow engine, cache telemetry), OpenCode (session resume), Claude Code (workflow script format).
+
+---
+
+## TL;DR
+
+> **Quick Summary**: Build a durable orchestration layer with trace observability, dynamic JS workflows, session persistence, background subagents, and multi-modal support over 5 phases.
+>
+> **Deliverables**:
+> - Trace system with DB persistence + viewer UI
+> - Dynamic workflow engine (JS sandbox, agent/parallel/pipeline)
+> - Workflow resumability (hash-based step caching)
+> - Background subagent runtime
+> - Session persistence across refreshes
+> - Cache shape telemetry (DeepSeek KV cache viz)
+> - Multi-modal attachment support
+>
+> **Estimated Effort**: XL — 5 phases, ~2-3 weeks total
+> **Parallel Execution**: YES — phases 1-2 can partially overlap
+> **Critical Path**: Trace system → Workflow engine → All downstream features
+
+---
+
+## Context
+
+### Original Request
+User wants BooCode to become "like Paseo — a thin client" with observability, dynamic workflows, session persistence, background agents, multi-modal, cache shape telemetry, and workflow resumability. They invoked skills across model evaluation, long context, SGLang, LangChain, LangSmith, agentic eval, agent harness construction, agent governance, and chat SDKs — indicating broad ambition for a production-quality AI coding platform.
+
+### Key Decisions
+- **Trace system first**: Foundation for all debugging and optimization
+- **isolated-vm for workflow sandbox**: Node-native, no external deps
+- **DB-backed sessions**: Postgres for trace store + session state
+- **Existing WS frames + new `tool_trace` frame**: Live streaming to frontend
+- **Phase ordering**: Foundation (trace) → UX (persistence) → Power (workflows) → Polish (background/multi-modal/cache)
+
+---
+
+## Phases
+
+### Phase 1: Trace System + Observability
+**Est. effort**: 3-4 days
+
+Core observability infrastructure. Every tool call gets timed, logged, and persisted.
+
+**Deliverables**:
+- `tool_traces` DB table (id, session_id, chat_id, turn_number, tool_name, input, output, started_at, finished_at, latency_ms, tokens_used, cache_tokens, reasoning_tokens, error, outcome)
+- Instrumentation in `tool-phase.ts` wrapping `executeToolCall` with start/end timing
+- `tool_trace` WS frame type for live streaming to frontend
+- GET `/api/chats/:id/traces` endpoint (paginated)
+- Trace viewer pane (collapsible tree, timing bars, expand/collapse per call)
+
+**Files to create**: 5-7 files across server + web + contracts
+**Dependencies**: None — standalone feature
+
+---
+
+### Phase 2: Session Persistence + Resume
+**Est. effort**: 2-3 days
+
+Agent state survives browser refresh. Active sessions can be resumed.
+
+**Deliverables**:
+- Serialize active agent state to DB on each turn boundary
+- Restore state on WS reconnect (existing `snapshot` frame enhanced)
+- Agent session timeline view (history of all turns in a session)
+- Coder pane rehydrates from persisted state
+
+**Files to modify**: ws.ts, useSessionStream.ts, session store, dispatcher
+**Dependencies**: None — standalone, but benefits from Phase 1 trace data
+
+---
+
+### Phase 3: Dynamic Workflow Engine
+**Est. effort**: 5-7 days
+
+JS sandbox for multi-agent orchestration. Claude Code compatible.
+
+**Deliverables**:
+- `isolated-vm` sandbox (or Node `vm` module with restricted context)
+- Workflow API: `agent()`, `parallel()`, `pipeline()`, `phase()`, `budget()`, `log()`, `args`
+- Workflow file discovery (`.boocode/workflows/*.js` → project, `~/.boocode/workflows/*.js` → global)
+- Built-in workflow catalog (deep-research, multi-review, etc.)
+- Workflow manager with concurrency limits, token budgets
+- Integration with existing Orchestrator panel for UI
+
+**Files to create**: 10-15 files (workflow runtime, scheduler, tool bridge, manager, catalog)
+**Dependencies**: Phase 1 traces feed into workflow observability
+
+**Workflow Resumability** (within Phase 3):
+- SHA-256 hash of agent spec (prompt + options)
+- Cache completed results by hash
+- On re-run, skip cached agents, only execute new/changed ones
+- In-memory cache for current session, optional DB persistence
+
+**Est. effort**: 1-2 days within Phase 3
+
+---
+
+### Phase 4: Background Subagents
+**Est. effort**: 2-3 days
+
+Non-blocking subagent execution. `spawn_subagent` returns immediately, results collected later.
+
+**Deliverables**:
+- Background task queue (reuses existing `tasks` table)
+- `spawn_subagent` tool that creates a task and returns immediately
+- `subagent_status` tool to poll completion
+- `subagent_result` tool to retrieve output
+- Background agent pane showing running/completed subagents
+- Notifications via hooks when background tasks complete
+
+**Files to create**: 3-5 files across server + web
+**Dependencies**: Phase 1 traces, Phase 2 session persistence
+
+---
+
+### Phase 5: Multi-modal + Cache Shape (Polish)
+**Est. effort**: 2-3 days
+
+Image/file attachment support + DeepSeek cache hit visualization.
+
+**Deliverables (Multi-modal)**:
+- Image/file attachment storage (tmpfs, referenced in message)
+- Forward image content through DeepSeek API's multimodal support
+- Render attached images in message bubble
+- Model can "see" screenshots, diagrams, UI mocks
+
+**Deliverables (Cache Shape)**:
+- Extract `prompt_cache_hit_tokens` from DeepSeek provider metadata
+- Build cache segment visualization (system prompt, tool schema, conversation)
+- Per-turn cache hit rate in trace viewer
+- Cumulative cache stats in session view
+
+**Files to create**: 3-5 files
+**Dependencies**: Phase 1 traces (for cache shape), existing DeepSeek integration
+
+---
+
+## Execution Strategy
+
+### Parallel Execution Waves
+
+```
+Wave 1 (Start Immediately):
+├── Phase 1: Trace system backend (tool_traces table + instrumentation) [deep]
+├── Phase 1: Trace viewer frontend [visual-engineering]
+└── Phase 2: Session persistence backbone [deep]
+
+Wave 2 (After Wave 1):
+├── Phase 3: Workflow engine sandbox + API surface [deep]
+├── Phase 3: Workflow file discovery + manager [unspecified-high]
+├── Phase 3: Workflow resumability cache [quick]
+└── Phase 4: Background subagent queue + tools [unspecified-high]
+
+Wave 3 (After Wave 2):
+├── Phase 4: Background agent pane + notifications [visual-engineering]
+├── Phase 5: Multi-modal attachment pipeline [deep]
+└── Phase 5: Cache shape telemetry UI [visual-engineering]
+
+Wave FINAL:
+├── F1: Plan compliance audit (oracle)
+├── F2: Code quality review (unspecified-high)
+├── F3: Integration QA (unspecified-high)
+└── F4: Scope fidelity check (deep)
+```
+
+---
+
+## TODOs
+
+> Phase 1: Trace System + Observability
+
+- [ ] 1. Create tool_traces DB table + migration
+
+- [ ] 2. Add tool_trace WS frame + contracts schema
+
+- [ ] 3. Instrument tool-phase.ts with start/end timing
+
+- [ ] 4. Add GET /api/chats/:id/traces endpoint
+
+- [ ] 5. Build trace viewer frontend component
+
+> Phase 2: Session Persistence + Resume
+
+- [ ] 6. Serialize agent state to DB on turn boundaries
+
+- [ ] 7. Restore state on WS reconnect
+
+- [ ] 8. Agent session timeline view
+
+> Phase 3: Dynamic Workflow Engine
+
+- [ ] 9. Create isolated-vm workflow sandbox
+
+- [ ] 10. Implement agent/parallel/pipeline primitives
+
+- [ ] 11. Workflow file discovery system
+
+- [ ] 12. Workflow manager + built-in catalog
+
+- [ ] 13. Workflow resumability (hash-based cache)
+
+- [ ] 14. Workflow UI integration with Orchestrator panel
+
+> Phase 4: Background Subagents
+
+- [ ] 15. Background task queue + spawn_subagent tool
+
+- [ ] 16. subagent_status + subagent_result tools
+
+- [ ] 17. Background agent pane
+
+> Phase 5: Multi-modal + Cache Shape
+
+- [ ] 18. Multi-modal attachment pipeline
+
+- [ ] 19. Image render in message bubble
+
+- [ ] 20. Cache shape telemetry data pipeline
+
+- [ ] 21. Cache shape visualization in trace viewer
+
+---
+
+## Success Criteria
+
+- Tool trace viewer shows every call with timing bars and token costs
+- Browser refresh preserves agent session state
+- Workflow scripts run in isolated sandbox with agent/parallel/pipeline
+- Re-running a workflow skips cached agents (hash-based)
+- Background subagents run independently, results collected later
+- Model can see attached images in chat
+- Cache hit rate visible per-turn and cumulative

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 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.8.18-deepseek-whale-lift — 2026-06-08
+
+Integrates DeepSeek API directly into BooChat and BooCoder via `@ai-sdk/deepseek`, replacing the generic `openai-compatible` wrapper. DeepSeek V4 models (`deepseek-v4-flash`, `deepseek-v4-pro`) with configurable thinking effort levels appear in both chat and coder pane model pickers. Full token tracking — cache hit tokens and reasoning tokens — flow from the API through new DB columns and WS frames into the UI message stats line. Lifts three high-value features from the Whale codebase: a schema-based tool input repair system that coerces types and unwraps markdown autolinks before Zod validation, a shell-based lifecycle hooks system (PreToolUse, PostToolUse, Stop, PreCompact, PostCompact) with JSON stdin/stdout contract, and per-MCP-server permissions (allow/ask/deny) gating tool execution.
+
 ## v2.8.0-fork-lifts — 2026-06-07
 
 Completes the eight fork-lift integrations from `/opt/forks` into BooCode: boocontext sidecar upgrade, LSP code intelligence, DCP clean-room pruning, institutional memory, subagent protocol enhancements, plugin hook host, inference reliability (tool-shim + loop detectors), and TokenScope token breakdown. Backfills edit safety guards (truncation + dropped imports) and the TokenScope analyzer/persist module. Closes the fork-lifts-mit epic.

apps/booterm/src/index.ts

@@ -4,6 +4,8 @@ import { loadConfig } from './config.js';
 import { getPool, closeDb } from './db.js';
 import { registerHealthRoutes } from './routes/health.js';
 import { registerTerminalRoutes } from './routes/terminals.js';
+import { registerSessionRoutes } from './routes/sessions.js';
+import { registerSearchRoutes } from './routes/search.js';
 import { registerWsAttachRoute } from './ws/attach.js';
 
 async function main(): Promise<void> {
@@ -33,6 +35,8 @@ async function main(): Promise<void> {
 
   registerHealthRoutes(app);
   registerTerminalRoutes(app, config.TMUX_CONF_PATH);
+  registerSessionRoutes(app);
+  registerSearchRoutes(app, config.TMUX_CONF_PATH);
   registerWsAttachRoute(app, config.TMUX_CONF_PATH);
 
   const shutdown = async (signal: string) => {

apps/booterm/src/pty/registry.ts

@@ -0,0 +1,162 @@
+export interface SessionMeta {
+  paneId: string;
+  sessionId: string;
+  projectPath: string;
+  title?: string;
+  createdAt: Date;
+  lastActivityAt: Date;
+}
+
+const sessions = new Map<string, SessionMeta>();
+
+export function register(
+  sessionId: string,
+  paneId: string,
+  projectPath: string,
+  title?: string,
+): void {
+  const now = new Date();
+  const existing = sessions.get(paneId);
+  if (existing) {
+    existing.lastActivityAt = now;
+    return;
+  }
+  sessions.set(paneId, {
+    paneId,
+    sessionId,
+    projectPath,
+    title,
+    createdAt: now,
+    lastActivityAt: now,
+  });
+}
+
+export function unregister(paneId: string): void {
+  sessions.delete(paneId);
+  ringBuffers.delete(paneId);
+}
+
+export function list(): SessionMeta[] {
+  return Array.from(sessions.values());
+}
+
+export function get(paneId: string): SessionMeta | undefined {
+  return sessions.get(paneId);
+}
+
+// ── Ring buffer for PTY output search ──────────────────────────────────────
+
+export interface SearchMatch {
+  line: number;
+  content: string;
+  contextBefore: string[];
+  contextAfter: string[];
+}
+
+const ringBuffers = new Map<string, string[]>();
+
+/**
+ * Append raw PTY data to the ring buffer for a given pane.
+ * Splits incoming data on newlines and pushes each line into the buffer,
+ * trimming to `maxLines` (default 5000) from the tail.
+ */
+export function appendOutput(
+  paneId: string,
+  data: string,
+  maxLines: number = 5000,
+): void {
+  let buf = ringBuffers.get(paneId);
+  if (!buf) {
+    buf = [];
+    ringBuffers.set(paneId, buf);
+  }
+
+  // Split on newlines — each chunk may contain multiple complete lines and
+  // potentially a trailing partial line (which we store as-is; the next chunk
+  // will either complete it or be another partial).
+  const lines = data.split('\n');
+
+  // The first element of `lines` may be a continuation of the last partial
+  // line from the previous append. If the buffer is non-empty and the last
+  // stored entry is a partial (no trailing newline previously), glue them.
+  // We detect "partial" by checking whether `data` ended with '\n' — if it
+  // did, the last element after split is '' (empty) which we drop.
+  const endedWithNewline = data.endsWith('\n');
+  if (endedWithNewline) {
+    // The final empty-string element is discarded.
+    lines.pop();
+  }
+
+  if (buf.length > 0 && lines.length > 0) {
+    // Concatenate the last partial line in the buffer with the first split
+    // segment. This avoids splitting ANSI sequences or text across chunks.
+    buf[buf.length - 1] = (buf[buf.length - 1] ?? '') + (lines[0] ?? '');
+    lines.shift();
+  }
+
+  for (const line of lines) {
+    buf.push(line);
+  }
+
+  // Trim from head if over maxLines
+  if (buf.length > maxLines) {
+    buf = buf.slice(buf.length - maxLines);
+    ringBuffers.set(paneId, buf);
+  }
+}
+
+/**
+ * Search the ring buffer for a pane using a regex pattern.
+ * Returns matches with optional context lines before and after each match.
+ */
+export function searchRingBuffer(
+  paneId: string,
+  pattern: string,
+  opts?: { limit?: number; context?: number },
+): SearchMatch[] {
+  const buf = ringBuffers.get(paneId);
+  if (!buf || buf.length === 0) return [];
+
+  const limit = opts?.limit ?? 50;
+  const context = opts?.context ?? 0;
+
+  let re: RegExp;
+  try {
+    re = new RegExp(pattern, 'u');
+  } catch {
+    return []; // invalid regex — caller should validate, but be defensive
+  }
+
+  const results: SearchMatch[] = [];
+
+  for (let i = 0; i < buf.length; i++) {
+    if (results.length >= limit) break;
+    if (re.test(buf[i]!)) {
+      const contextBefore: string[] = [];
+      const contextAfter: string[] = [];
+      for (let c = 1; c <= context; c++) {
+        const ci = i - c;
+        if (ci >= 0) contextBefore.unshift(buf[ci]!);
+      }
+      for (let c = 1; c <= context; c++) {
+        const ci = i + c;
+        if (ci < buf.length) contextAfter.push(buf[ci]!);
+      }
+      results.push({
+        line: i + 1, // 1-based line number for display
+        content: buf[i]!,
+        contextBefore,
+        contextAfter,
+      });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Remove the ring buffer for a pane. Called on session kill / pane close.
+ */
+export function clearBuffer(paneId: string): void {
+  ringBuffers.delete(paneId);
+}

apps/booterm/src/routes/search.ts

@@ -0,0 +1,167 @@
+import type { FastifyInstance } from 'fastify';
+import { z } from 'zod';
+import { sanitizeId, tmuxSessionName, capturePane } from '../pty/manager.js';
+import { searchRingBuffer, clearBuffer } from '../pty/registry.js';
+
+const ParamsSchema = z.object({
+  sid: z.string(),
+  pid: z.string(),
+});
+
+const MAX_PATTERN_LENGTH = 200;
+
+// Zod-refined string: reject empty and overly-long patterns to prevent ReDoS
+const PatternQuerySchema = z
+  .string()
+  .min(1, 'pattern is required')
+  .max(MAX_PATTERN_LENGTH, `pattern must not exceed ${MAX_PATTERN_LENGTH} characters`);
+
+const QuerySchema = z.object({
+  pattern: PatternQuerySchema,
+  limit: z.coerce.number().int().min(1).max(500).default(50),
+  context: z.coerce.number().int().min(0).max(50).default(0),
+});
+
+interface SearchMatch {
+  line: number;
+  content: string;
+  contextBefore: string[];
+  contextAfter: string[];
+}
+
+interface SearchResponse {
+  matches: SearchMatch[];
+  total: number;
+  truncated: boolean;
+  source: 'ring' | 'capture';
+}
+
+/**
+ * Search a captured pane buffer using a regex. This is the fallback path
+ * when the ring buffer doesn't have enough matches.
+ */
+function grepBuffer(
+  text: string,
+  pattern: string,
+  limit: number,
+  context: number,
+): SearchMatch[] {
+  let re: RegExp;
+  try {
+    re = new RegExp(pattern, 'u');
+  } catch {
+    return [];
+  }
+
+  const lines = text.split('\n');
+  const results: SearchMatch[] = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    if (results.length >= limit) break;
+    if (re.test(lines[i]!)) {
+      const contextBefore: string[] = [];
+      const contextAfter: string[] = [];
+      for (let c = 1; c <= context; c++) {
+        const ci = i - c;
+        if (ci >= 0) contextBefore.unshift(lines[ci]!);
+      }
+      for (let c = 1; c <= context; c++) {
+        const ci = i + c;
+        if (ci < lines.length) contextAfter.push(lines[ci]!);
+      }
+      results.push({
+        line: i + 1,
+        content: lines[i]!,
+        contextBefore,
+        contextAfter,
+      });
+    }
+  }
+
+  return results;
+}
+
+export function registerSearchRoutes(app: FastifyInstance, tmuxConfPath: string): void {
+  app.get<{
+    Params: { sid: string; pid: string };
+    Querystring: { pattern?: string; limit?: string; context?: string };
+  }>(
+    '/api/term/sessions/:sid/panes/:pid/search',
+    async (req, reply) => {
+      const p = ParamsSchema.safeParse(req.params);
+      if (!p.success) return reply.code(400).send({ error: 'bad_params' });
+
+      const sid = sanitizeId(p.data.sid);
+      const pid = sanitizeId(p.data.pid);
+      if (!sid || !pid) return reply.code(400).send({ error: 'bad_id_format' });
+
+      const q = QuerySchema.safeParse(req.query);
+      if (!q.success) {
+        return reply.code(400).send({
+          error: 'bad_query',
+          details: q.error.flatten().fieldErrors,
+        });
+      }
+
+      const { pattern, limit, context } = q.data;
+
+      // ── Path 1: ring buffer search (fast, no tmux interaction) ──
+      const ringMatches = searchRingBuffer(pid, pattern, { limit, context });
+      if (ringMatches.length >= limit) {
+        return reply.code(200).send({
+          matches: ringMatches,
+          total: ringMatches.length,
+          truncated: ringMatches.length >= limit,
+          source: 'ring' as const,
+        });
+      }
+
+      // ── Path 2: capture-pane + grep fallback (10s timeout) ──
+      const sessionName = tmuxSessionName(pid);
+
+      let capture: string;
+      try {
+        capture = await withTimeout(
+          capturePane(tmuxConfPath, sessionName, 5000),
+          10_000,
+        );
+      } catch (err) {
+        req.log.warn({ err, pid }, 'capture-pane timed out or failed');
+        return reply.code(200).send({
+          matches: ringMatches,
+          total: ringMatches.length,
+          truncated: false,
+          source: 'ring' as const,
+        });
+      }
+
+      if (!capture) {
+        // tmux pane may no longer exist — return whatever ring had
+        return reply.code(200).send({
+          matches: ringMatches,
+          total: ringMatches.length,
+          truncated: false,
+          source: 'ring' as const,
+        });
+      }
+
+      const captureMatches = grepBuffer(capture, pattern, limit, context);
+
+      return reply.code(200).send({
+        matches: captureMatches,
+        total: captureMatches.length,
+        truncated: captureMatches.length >= limit,
+        source: 'capture' as const,
+      });
+    },
+  );
+}
+
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  return Promise.race([
+    promise,
+    new Promise<never>((_, reject) =>
+      setTimeout(() => reject(new Error('timeout')), ms),
+    ),
+  ]);
+}

apps/booterm/src/routes/sessions.ts

@@ -0,0 +1,18 @@
+import type { FastifyInstance } from 'fastify';
+import { list } from '../pty/registry.js';
+
+export function registerSessionRoutes(app: FastifyInstance): void {
+  app.get('/api/term/sessions', async (_req, reply) => {
+    const active = list();
+    return reply.code(200).send({
+      sessions: active.map((s) => ({
+        paneId: s.paneId,
+        sessionId: s.sessionId,
+        projectPath: s.projectPath,
+        title: s.title ?? null,
+        createdAt: s.createdAt.toISOString(),
+        lastActivityAt: s.lastActivityAt.toISOString(),
+      })),
+    });
+  });
+}

apps/booterm/src/ws/attach.ts

@@ -9,6 +9,7 @@ import {
 } from '../pty/manager.js';
 import { attachPty } from '../pty/pty.js';
 import { getUser } from '../auth.js';
+import { register, unregister, appendOutput } from '../pty/registry.js';
 
 export function registerWsAttachRoute(app: FastifyInstance, tmuxConfPath: string): void {
   app.get<{
@@ -57,6 +58,8 @@ export function registerWsAttachRoute(app: FastifyInstance, tmuxConfPath: string
         return;
       }
 
+      register(sid, pid, session.project_path);
+
       let handle: IPty;
       try {
         handle = attachPty({
@@ -103,6 +106,8 @@ export function registerWsAttachRoute(app: FastifyInstance, tmuxConfPath: string
         } catch (err) {
           req.log.warn({ err }, 'ws send failed');
         }
+        // Feed the ring buffer for pattern-based search
+        appendOutput(pid, data);
       };
       handle.onData(onData);
 
@@ -157,6 +162,7 @@ export function registerWsAttachRoute(app: FastifyInstance, tmuxConfPath: string
       // teardown happens via the /kill route called from the frontend when the
       // user closes the pane.
       socket.on('close', () => {
+        unregister(pid);
         try {
           handle.kill();
         } catch {

apps/coder/src/conductor/types.ts

@@ -42,6 +42,14 @@ export type StepKind = 'agent' | 'code' | 'approval';
 
 export type TriggerRule = 'all_success' | 'one_success' | 'all_done';
 
+/** Possible statuses for a flow step (persisted in flow_steps.status). */
+export type StepStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped' | 'cancelled' | 'timed_out';
+
+/** Retry policy for a step that times out. */
+export interface RetryConfig {
+  maxRetries: number;
+}
+
 export interface Step {
   /** unique id within the flow; other steps depend on it by this id */
   id: string;
@@ -59,6 +67,8 @@ export interface Step {
   run: (ctx: StepContext) => string | Promise<string>;
   /** optional guard — when it returns false the step is skipped (e.g. no repo) */
   when?: (ctx: StepContext) => boolean;
+  /** max retries on timeout (0 or unset = no retry) */
+  maxRetries?: number;
 }
 
 export interface Flow {

apps/coder/src/config.ts

@@ -50,6 +50,11 @@ const ConfigSchema = z.object({
   // 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),
+  DEEPSEEK_API_KEY: z.string().optional(),
+  DEEPSEEK_BASE_URL: z.string().url().default('https://api.deepseek.com'),
+  // v2.9.x: flow step timeout (default 5 min). When a 'running' step exceeds
+  // this duration, it is marked 'timed_out' and may be retried.
+  FLOW_STEP_TIMEOUT_MS: z.coerce.number().int().positive().default(300_000),
 });
 
 export type Config = z.infer<typeof ConfigSchema>;

apps/coder/src/index.ts

@@ -28,7 +28,10 @@ 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 { registerAnalyticsRoutes } from './routes/analytics.js';
+import { registerPlanRoutes } from './routes/plans.js';
 import { registerWebSocket } from './routes/ws.js';
+import { updatePlanFromRun } from './services/plan-store.js';
 // Phase 4: dispatcher + agent probe
 import { createDispatcher } from './services/dispatcher.js';
 // Orchestrator (Phase 2): DB-backed flow-runner; advances on the dispatcher's
@@ -228,8 +231,16 @@ async function main() {
 
   // Orchestrator (Phase 2): the flow-runner reacts to the dispatcher's
   // onTaskTerminal hook to advance flow_runs. Created before the dispatcher so its
-  // terminal callback can be wired in.
-  const flowRunner = createFlowRunner({ sql, broker, log: app.log, config });
+  // terminal callback can be wired in. onRunTerminal updates linked plans.
+  const flowRunner = createFlowRunner({
+    sql, broker, log: app.log, config,
+    onRunTerminal: (runId, status) => {
+      updatePlanFromRun(sql, runId, status).catch((err) => {
+        app.log.error({ err: err instanceof Error ? err.message : String(err), runId },
+          'plans: updatePlanFromRun failed');
+      });
+    },
+  });
 
   // Arena SEAM (a): build the local-model set from the live llama-swap model list.
   // Both bare IDs ('qwen3.6-35b') and prefixed IDs ('llama-swap/qwen3.6-35b') are
@@ -382,6 +393,8 @@ async function main() {
   registerProviderRoutes(app, sql, config);
   registerWorktreeSafetyRoutes(app, sql);
   registerLifecycleRoutes(app, sql);
+  registerAnalyticsRoutes(app, sql);
+  registerPlanRoutes(app, sql);
   registerWebSocket(app, sql, broker);
 
   // Graceful shutdown

apps/coder/src/routes/analytics.ts

@@ -0,0 +1,78 @@
+import type { FastifyInstance } from 'fastify';
+import type { Sql } from '../db.js';
+
+// token-analyzer-ui: aggregate token/cost analytics across all agent_sessions.
+// v1 — global view only (no per-project or per-user filtering).
+
+export interface AnalyticsSummary {
+  total_input_tokens: number;
+  total_output_tokens: number;
+  total_cost: number;
+  session_count: number;
+}
+
+export interface SessionAnalyticsRow {
+  session_id: string;
+  session_name: string;
+  total_input_tokens: number;
+  total_output_tokens: number;
+  total_cost: number;
+  last_active_at: string | null;
+}
+
+export interface TokenBreakdownAgg {
+  category: string;
+  total_tokens: number;
+}
+
+export function registerAnalyticsRoutes(app: FastifyInstance, sql: Sql): void {
+  // GET /api/analytics/summary — aggregate totals across all agent_sessions.
+  app.get('/api/analytics/summary', async () => {
+    const [row] = await sql<AnalyticsSummary[]>`
+      SELECT
+        COALESCE(SUM(a.input_tokens), 0)::BIGINT AS total_input_tokens,
+        COALESCE(SUM(a.output_tokens), 0)::BIGINT AS total_output_tokens,
+        COALESCE(SUM(a.cost), 0)::DOUBLE PRECISION AS total_cost,
+        COUNT(DISTINCT c.session_id)::INT AS session_count
+      FROM agent_sessions a
+      JOIN chats c ON c.id = a.chat_id
+    `;
+    return row ?? { total_input_tokens: 0, total_output_tokens: 0, total_cost: 0, session_count: 0 };
+  });
+
+  // GET /api/analytics/sessions — per-session token/cost breakdown.
+  app.get('/api/analytics/sessions', async () => {
+    const rows = await sql<SessionAnalyticsRow[]>`
+      SELECT
+        c.session_id AS session_id,
+        s.name AS session_name,
+        COALESCE(SUM(a.input_tokens), 0)::BIGINT AS total_input_tokens,
+        COALESCE(SUM(a.output_tokens), 0)::BIGINT AS total_output_tokens,
+        COALESCE(SUM(a.cost), 0)::DOUBLE PRECISION AS total_cost,
+        MAX(a.last_active_at) AS last_active_at
+      FROM agent_sessions a
+      JOIN chats c ON c.id = a.chat_id
+      JOIN sessions s ON s.id = c.session_id
+      GROUP BY c.session_id, s.name
+      ORDER BY MAX(a.last_active_at) DESC NULLS LAST
+    `;
+    return { sessions: rows };
+  });
+
+  // GET /api/analytics/token-breakdown — aggregate token_breakdown categories
+  // across all tasks that carry the JSONB field.
+  app.get('/api/analytics/token-breakdown', async () => {
+    const rows = await sql<{ category: string; total_tokens: number }[]>`
+      SELECT
+        key AS category,
+        SUM((value->>0)::BIGINT)::BIGINT AS total_tokens
+      FROM tasks,
+      LATERAL jsonb_each(token_breakdown)
+      WHERE token_breakdown IS NOT NULL
+        AND jsonb_typeof(token_breakdown) = 'object'
+      GROUP BY key
+      ORDER BY total_tokens DESC
+    `;
+    return { categories: rows };
+  });
+}

apps/coder/src/routes/plans.ts

@@ -0,0 +1,134 @@
+/**
+ * Boulder state — plan routes.
+ *
+ * GET   /api/plans?project_id=   — list plans for a project
+ * GET   /api/plans/active?project_id= — list active (in-flight) plans
+ * POST   /api/plans               — create a new plan
+ * PATCH  /api/plans/:id           — update plan progress / status
+ */
+import type { FastifyInstance } from 'fastify';
+import { z } from 'zod';
+import type { Sql } from '../db.js';
+import {
+  createPlan,
+  getPlan,
+  listPlans,
+  listActivePlans,
+  updatePlan,
+} from '../services/plan-store.js';
+
+const CreatePlanBody = z.object({
+  project_id: z.string().uuid(),
+  title: z.string().min(1).max(500),
+  description: z.string().max(10_000).optional(),
+  flow_run_id: z.string().uuid().optional(),
+  metadata: z.record(z.unknown()).optional(),
+});
+
+const ListPlansQuery = z.object({
+  project_id: z.string().uuid(),
+});
+
+const UpdatePlanBody = z.object({
+  title: z.string().min(1).max(500).optional(),
+  description: z.string().max(10_000).nullable().optional(),
+  status: z.enum(['active', 'completed', 'cancelled', 'failed']).optional(),
+  progress_pct: z.number().int().min(0).max(100).optional(),
+  items_total: z.number().int().min(0).optional(),
+  items_completed: z.number().int().min(0).optional(),
+  metadata: z.record(z.unknown()).nullable().optional(),
+});
+
+const PlanIdParam = z.string().uuid();
+
+export function registerPlanRoutes(app: FastifyInstance, sql: Sql): void {
+  // GET /api/plans?project_id= — all plans for a project
+  app.get('/api/plans', async (req, reply) => {
+    const parsed = ListPlansQuery.safeParse(req.query);
+    if (!parsed.success) {
+      reply.code(400);
+      return { error: 'invalid query', details: parsed.error.flatten() };
+    }
+    const plans = await listPlans(sql, parsed.data.project_id);
+    return { plans };
+  });
+
+  // GET /api/plans/active?project_id= — active plans only
+  app.get('/api/plans/active', async (req, reply) => {
+    const parsed = ListPlansQuery.safeParse(req.query);
+    if (!parsed.success) {
+      reply.code(400);
+      return { error: 'invalid query', details: parsed.error.flatten() };
+    }
+    const plans = await listActivePlans(sql, parsed.data.project_id);
+    return { plans };
+  });
+
+  // POST /api/plans — create a new plan
+  app.post('/api/plans', async (req, reply) => {
+    const parsed = CreatePlanBody.safeParse(req.body);
+    if (!parsed.success) {
+      reply.code(400);
+      return { error: 'invalid body', details: parsed.error.flatten() };
+    }
+
+    const { project_id, title, description, flow_run_id, metadata } = parsed.data;
+    const plan = await createPlan(sql, {
+      projectId: project_id,
+      title,
+      description,
+      flowRunId: flow_run_id,
+      metadata,
+    });
+
+    reply.code(201);
+    return { plan };
+  });
+
+  // GET /api/plans/:id — single plan
+  app.get<{ Params: { id: string } }>('/api/plans/:id', async (req, reply) => {
+    const parsedId = PlanIdParam.safeParse(req.params.id);
+    if (!parsedId.success) {
+      reply.code(400);
+      return { error: 'invalid id' };
+    }
+    const plan = await getPlan(sql, parsedId.data);
+    if (!plan) {
+      reply.code(404);
+      return { error: 'plan not found' };
+    }
+    return { plan };
+  });
+
+  // PATCH /api/plans/:id — update plan
+  app.patch<{ Params: { id: string } }>('/api/plans/:id', async (req, reply) => {
+    const parsedId = PlanIdParam.safeParse(req.params.id);
+    if (!parsedId.success) {
+      reply.code(400);
+      return { error: 'invalid id' };
+    }
+
+    const parsed = UpdatePlanBody.safeParse(req.body);
+    if (!parsed.success) {
+      reply.code(400);
+      return { error: 'invalid body', details: parsed.error.flatten() };
+    }
+
+    const { title, description, status, progress_pct, items_total, items_completed, metadata } = parsed.data;
+    const plan = await updatePlan(sql, parsedId.data, {
+      title,
+      description: description === null ? null : description,
+      status,
+      progressPct: progress_pct,
+      itemsTotal: items_total,
+      itemsCompleted: items_completed,
+      metadata: metadata === null ? null : metadata,
+    });
+
+    if (!plan) {
+      reply.code(404);
+      return { error: 'plan not found' };
+    }
+    return { plan };
+  });
+}

apps/coder/src/schema.sql

@@ -266,7 +266,7 @@ CREATE INDEX IF NOT EXISTS claude_session_entries_key_idx ON claude_session_entr
 -- replaces it with the three-value list).
 ALTER TABLE agent_sessions DROP CONSTRAINT IF EXISTS agent_sessions_backend_chk;
 ALTER TABLE agent_sessions ADD CONSTRAINT agent_sessions_backend_chk
-  CHECK (backend IN ('opencode_server', 'acp_warm', 'claude_sdk'));
+  CHECK (backend IN ('opencode_server', 'acp_warm', 'claude_sdk', 'paseo'));
 
 -- LISTEN/NOTIFY fast path: every tasks INSERT (from any call site — routes,
 -- new_task tool, MCP server) fires pg_notify('tasks_new') in the same
@@ -340,11 +340,12 @@ CREATE INDEX IF NOT EXISTS flow_steps_task_id_idx ON flow_steps(task_id);
 -- edits above are no-ops on the existing DB (CREATE TABLE IF NOT EXISTS skips an
 -- existing table) — widen via the repo's DROP-IF-EXISTS → guarded-ADD discipline.
 -- Pure ADD of a new allowed value, so no row UPDATE is needed (no value renamed).
+-- v2.9.x: widen status CHECKs to include 'timed_out' for Task State Machine.
 ALTER TABLE flow_runs DROP CONSTRAINT IF EXISTS flow_runs_status_chk;
 DO $$ BEGIN
   IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'flow_runs_status_chk') THEN
     ALTER TABLE flow_runs ADD CONSTRAINT flow_runs_status_chk
-      CHECK (status IN ('running', 'completed', 'failed', 'cancelled'));
+      CHECK (status IN ('running', 'completed', 'failed', 'cancelled', 'timed_out'));
   END IF;
 END $$;
 
@@ -352,10 +353,14 @@ ALTER TABLE flow_steps DROP CONSTRAINT IF EXISTS flow_steps_status_chk;
 DO $$ BEGIN
   IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'flow_steps_status_chk') THEN
     ALTER TABLE flow_steps ADD CONSTRAINT flow_steps_status_chk
-      CHECK (status IN ('pending', 'running', 'completed', 'failed', 'skipped', 'cancelled'));
+      CHECK (status IN ('pending', 'running', 'completed', 'failed', 'skipped', 'cancelled', 'timed_out'));
   END IF;
 END $$;
 
+-- Task State Machine: retry columns for flow_steps.
+ALTER TABLE flow_steps ADD COLUMN IF NOT EXISTS retry_count INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE flow_steps ADD COLUMN IF NOT EXISTS max_retries INTEGER;
+
 -- Arena: battles + contestants + cross_examinations.
 -- project_id carries no FK (matches tasks.project_id + flow_runs.project_id convention).
 -- winner_contestant_id FK is deferred (forward reference): added via guarded ALTER below.
@@ -438,3 +443,31 @@ CREATE TABLE IF NOT EXISTS flow_step_events (
   created_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp()
 );
 CREATE INDEX IF NOT EXISTS flow_step_events_run_idx ON flow_step_events(run_id);
+
+-- v2.9.0: Boulder state — cross-session plan persistence with auto-resumption.
+-- project_id carries no FK (matches tasks/fow_runs convention).
+-- flow_run_id links the plan to an in-flight orchestrator run for auto-tracking.
+CREATE TABLE IF NOT EXISTS plans (
+  id                UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  project_id        UUID NOT NULL,
+  title             TEXT NOT NULL,
+  description       TEXT,
+  status            TEXT NOT NULL DEFAULT 'active',
+  flow_run_id       UUID REFERENCES flow_runs(id) ON DELETE SET NULL,
+  progress_pct      INTEGER NOT NULL DEFAULT 0,
+  items_total       INTEGER NOT NULL DEFAULT 0,
+  items_completed   INTEGER NOT NULL DEFAULT 0,
+  metadata          JSONB,
+  created_at        TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
+  updated_at        TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
+  CONSTRAINT plans_status_chk CHECK (status IN ('active', 'completed', 'cancelled', 'failed')),
+  CONSTRAINT plans_progress_chk CHECK (progress_pct >= 0 AND progress_pct <= 100),
+  CONSTRAINT plans_items_chk CHECK (items_total >= 0 AND items_completed >= 0 AND items_completed <= items_total)
+);
+
+-- Plan queries by project and status.
+CREATE INDEX IF NOT EXISTS plans_project_status_idx ON plans(project_id, status);
+-- Fast lookup of the plan owning a flow run (for onRunTerminal updates).
+CREATE INDEX IF NOT EXISTS plans_flow_run_id_idx ON plans(flow_run_id);
+-- Plans sorted by recency (for "resume from last" surface).
+CREATE INDEX IF NOT EXISTS plans_project_created_idx ON plans(project_id, created_at DESC);

apps/coder/src/services/__tests__/flow-runner-decisions.test.ts

@@ -52,6 +52,7 @@ const emptyState = (over: Partial<SchedulerState> = {}): SchedulerState => ({
   skipped: new Set(),
   inFlight: new Set(),
   excluded: new Set(),
+  timedOut: new Set(),
   ...over,
 });
 

apps/coder/src/services/__tests__/paseo-client.test.ts

@@ -0,0 +1,195 @@
+import { describe, it, expect, vi } from 'vitest';
+import { PaseoClient, PaseoClientError } from '../paseo-client.js';
+
+/**
+ * Create a PaseoClient whose runCli method is replaced with a mock.
+ * The mock is returned as the second tuple element so tests can
+ * control and inspect it directly.
+ */
+function makeClient(config?: { paseoBin?: string; cliHost?: string }): {
+  client: PaseoClient;
+  mockRunCli: ReturnType<typeof vi.fn>;
+} {
+  const client = new PaseoClient(config);
+  const mockRunCli = vi.fn();
+  (client as any).runCli = mockRunCli;
+  return { client, mockRunCli };
+}
+
+describe('PaseoClient', () => {
+  describe('listAgents', () => {
+    it('returns parsed agent list from paseo ls --json', async () => {
+      const agents = [
+        { id: 'abc-123', shortId: 'abc', name: 'Agent 1', provider: 'opencode', status: 'running' },
+        { id: 'def-456', shortId: 'def', name: 'Agent 2', provider: 'claude', status: 'idle' },
+      ];
+      const { client, mockRunCli } = makeClient();
+      mockRunCli.mockResolvedValue(JSON.stringify(agents));
+
+      const result = await client.listAgents();
+
+      expect(mockRunCli).toHaveBeenCalledWith(['ls', '--json']);
+      expect(result).toEqual(agents);
+    });
+
+    it('throws PaseoClientError on non-JSON output', async () => {
+      const { client, mockRunCli } = makeClient();
+      mockRunCli.mockResolvedValue('not json');
+
+      await expect(client.listAgents()).rejects.toThrow(PaseoClientError);
+      await expect(client.listAgents()).rejects.toThrow(/invalid JSON/);
+    });
+
+    it('propagates runCli rejection as-is', async () => {
+      const { client, mockRunCli } = makeClient();
+      const err = new PaseoClientError('ls failed: connection refused', 'ls', 1, 'connection refused');
+      mockRunCli.mockRejectedValue(err);
+
+      await expect(client.listAgents()).rejects.toThrow(PaseoClientError);
+      await expect(client.listAgents()).rejects.toThrow(/ls failed/);
+    });
+  });
+
+  describe('getAgentStatus', () => {
+    it('returns parsed agent detail from paseo inspect --json', async () => {
+      const detail = {
+        Id: 'abc-123', Name: 'Agent 1', Provider: 'opencode',
+        Status: 'idle', Archived: false,
+        CreatedAt: '2026-01-01T00:00:00Z', UpdatedAt: '2026-01-01T01:00:00Z',
+      };
+      const { client, mockRunCli } = makeClient();
+      mockRunCli.mockResolvedValue(JSON.stringify(detail));
+
+      const result = await client.getAgentStatus('abc-123');
+
+      expect(mockRunCli).toHaveBeenCalledWith(['inspect', '--json', 'abc-123']);
+      expect(result.Id).toBe('abc-123');
+      expect(result.Status).toBe('idle');
+    });
+  });
+
+  describe('health', () => {
+    it('returns ok when paseo ls succeeds', async () => {
+      const { client, mockRunCli } = makeClient();
+      mockRunCli.mockResolvedValue('[]');
+
+      const result = await client.health();
+
+      expect(result).toEqual({ status: 'ok' });
+    });
+
+    it('returns error when runCli throws', async () => {
+      const { client, mockRunCli } = makeClient();
+      mockRunCli.mockRejectedValue(new Error('connection refused'));
+
+      const result = await client.health();
+
+      expect(result).toEqual({ status: 'error' });
+    });
+  });
+
+  describe('importAgent', () => {
+    it('calls paseo import with provider and labels', async () => {
+      const agentResult = { Id: 'new-789', Name: 'Imported', Provider: 'opencode', Status: 'idle' };
+      const { client, mockRunCli } = makeClient();
+      mockRunCli.mockResolvedValue(JSON.stringify(agentResult));
+
+      const result = await client.importAgent('ses-001', 'opencode', {
+        origin: 'boocode',
+        project: 'proj-1',
+      });
+
+      expect(mockRunCli).toHaveBeenCalledWith([
+        'import', '--json',
+        '--provider', 'opencode',
+        '--label', 'origin=boocode',
+        '--label', 'project=proj-1',
+        'ses-001',
+      ]);
+      expect(result.Id).toBe('new-789');
+    });
+
+    it('works without labels', async () => {
+      const { client, mockRunCli } = makeClient();
+      mockRunCli.mockResolvedValue(JSON.stringify({ Id: 'new-789' }));
+
+      const result = await client.importAgent('ses-001', 'claude');
+
+      expect(mockRunCli).toHaveBeenCalledWith([
+        'import', '--json',
+        '--provider', 'claude',
+        'ses-001',
+      ]);
+      expect(result.Id).toBe('new-789');
+    });
+  });
+
+  describe('archiveAgent', () => {
+    it('calls paseo archive --json', async () => {
+      const { client, mockRunCli } = makeClient();
+      mockRunCli.mockResolvedValue('{}');
+
+      await client.archiveAgent('abc-123');
+
+      expect(mockRunCli).toHaveBeenCalledWith(['archive', '--json', 'abc-123']);
+    });
+  });
+
+  describe('sendPrompt', () => {
+    it('sends prompt and parses JSON result', async () => {
+      const sendResult = { text: 'Hello!', ok: true };
+      const { client, mockRunCli } = makeClient();
+      mockRunCli.mockResolvedValue(JSON.stringify(sendResult));
+
+      const result = await client.sendPrompt('abc-123', 'Hello');
+
+      expect(mockRunCli).toHaveBeenCalledWith(['send', '--json', 'abc-123', 'Hello'], undefined);
+      expect(result).toEqual(sendResult);
+    });
+
+    it('falls back to plain text on non-JSON output', async () => {
+      const { client, mockRunCli } = makeClient();
+      mockRunCli.mockResolvedValue('plain text response');
+
+      const result = await client.sendPrompt('abc-123', 'Hi');
+
+      expect(result).toEqual({ text: 'plain text response', ok: true });
+    });
+
+    it('supports --no-wait flag', async () => {
+      const { client, mockRunCli } = makeClient();
+      mockRunCli.mockResolvedValue('{}');
+
+      await client.sendPrompt('abc-123', 'Hi', { noWait: true });
+
+      expect(mockRunCli).toHaveBeenCalledWith([
+        'send', '--json', '--no-wait',
+        'abc-123', 'Hi',
+      ], undefined);
+    });
+  });
+
+  describe('stopAgent', () => {
+    it('calls paseo stop', async () => {
+      const { client, mockRunCli } = makeClient();
+      mockRunCli.mockResolvedValue('');
+
+      await client.stopAgent('abc-123');
+
+      expect(mockRunCli).toHaveBeenCalledWith(['stop', 'abc-123']);
+    });
+  });
+
+  describe('cliHost config', () => {
+    it('includes --host flag in args when cliHost is set', async () => {
+      const { client, mockRunCli } = makeClient({ cliHost: 'tcp://localhost:6767?ssl=true' });
+      mockRunCli.mockResolvedValue('[]');
+
+      await client.listAgents();
+
+      expect(mockRunCli).toHaveBeenCalledWith([
+        'ls', '--json', '--host', 'tcp://localhost:6767?ssl=true',
+      ]);
+    });
+  });
+});

apps/coder/src/services/__tests__/plan-store.test.ts

@@ -0,0 +1,16 @@
+import { describe, it, expect } from 'vitest';
+import { planStatusFromRun } from '../plan-store.js';
+
+describe('planStatusFromRun', () => {
+  it('maps completed to completed', () => {
+    expect(planStatusFromRun('completed')).toBe('completed');
+  });
+
+  it('maps failed to failed', () => {
+    expect(planStatusFromRun('failed')).toBe('failed');
+  });
+
+  it('maps cancelled to cancelled', () => {
+    expect(planStatusFromRun('cancelled')).toBe('cancelled');
+  });
+});

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

@@ -13,7 +13,7 @@ import type { AcpToolSnapshot } from './acp-tool-snapshot.js';
 import type { AgentCommand } from './provider-types.js';
 
 /** Backend transport kind. Mirrors `agent_sessions.backend` CHECK in schema.sql. */
-export type AgentBackendKind = 'opencode_server' | 'acp_warm' | 'claude_sdk';
+export type AgentBackendKind = 'opencode_server' | 'acp_warm' | 'claude_sdk' | 'paseo';
 
 /**
  * Normalized, transport-agnostic events a backend emits during a turn (§2).

apps/coder/src/services/audit-session.ts

@@ -0,0 +1,747 @@
+import { mkdir, readFile, writeFile, readdir, rm, appendFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export const RUNS_REL = '.boo/runs';
+export const DAILY_REL = '.boo/runs/daily';
+export const GUIDELINES_REL = '.boo/guidelines';
+
+export interface SessionJson {
+  session_id: string;
+  task: string;
+  start_time: string;
+  end_time?: string;
+  status: 'in_progress' | 'completed';
+  expected_record_types: string[];
+}
+
+export interface AuditTrailEntry {
+  timestamp: string;
+  record_type: string;
+  action_type: string;
+  tool?: string;
+  files?: string[];
+  detail?: string;
+  input?: string;
+  output?: string;
+}
+
+export interface IndexEntry {
+  id: string;
+  task: string;
+  status: string;
+  record_count: number;
+  start_time: string;
+  max_anomaly_level?: string;
+}
+
+export interface IndexJson {
+  entries: IndexEntry[];
+}
+
+export interface StartSessionResult {
+  sessionId: string;
+  contextSummary: {
+    recentActivity: IndexEntry[];
+    userCorrections: UserCorrectionRecord[];
+    unfinishedSessions: SessionJson[];
+  };
+}
+
+export interface EndSessionResult {
+  sessionId: string;
+  integrity: IntegrityCheck[];
+  correctionCount: number;
+  summaryPath: string;
+}
+
+export interface IntegrityCheck {
+  check: string;
+  passed: boolean;
+  detail?: string;
+}
+
+export interface RecoverResult {
+  level: number;
+  sessionId?: string;
+  task?: string;
+  recentActivity: IndexEntry[];
+  lastTrailEntries: AuditTrailEntry[];
+  userCorrections: UserCorrectionRecord[];
+  conclusions: string[];
+  dailyAnomalies: string[];
+  dailyBacklog: string[];
+  fullTrail?: AuditTrailEntry[];
+  anomalies?: string[];
+}
+
+export interface DailyReport {
+  date: string;
+  sections: {
+    taskOverview: string;
+    operationStats: { label: string; count: number }[];
+    changes: { time: string; target: string; detail: string }[];
+    userFeedback: { feedback: string; resolution: string; persistedTo: string }[];
+    anomalyAlerts: string[];
+    backlogTracking: string[];
+    integritySummary: string;
+  };
+  path: string;
+}
+
+export interface UserCorrectionRecord {
+  record_type: 'conversation';
+  action_type: 'user_correction';
+  priority: 'critical_for_recovery';
+  timestamp: string;
+  original_claim: string;
+  correction: string;
+  principle_extracted: string;
+  persisted_to: string[];
+}
+
+function runsDir(basePath?: string): string {
+  return resolve(basePath ?? process.cwd(), RUNS_REL);
+}
+
+function dailyDir(basePath?: string): string {
+  return resolve(basePath ?? process.cwd(), DAILY_REL);
+}
+
+function sessionDir(sessionId: string, basePath?: string): string {
+  return join(runsDir(basePath), sessionId);
+}
+
+function currentSessionPath(basePath?: string): string {
+  return join(runsDir(basePath), '.current_session');
+}
+
+function indexJsonPath(basePath?: string): string {
+  return join(runsDir(basePath), 'index.json');
+}
+
+function auditBufferPath(basePath?: string): string {
+  return join(runsDir(basePath), 'audit_buffer.jsonl');
+}
+
+function auditPendingPath(basePath?: string): string {
+  return join(runsDir(basePath), 'audit_pending.jsonl');
+}
+
+function trailPath(sessionId: string, basePath?: string): string {
+  return join(sessionDir(sessionId, basePath), 'audit_trail.jsonl');
+}
+
+function sessionJsonPath(sessionId: string, basePath?: string): string {
+  return join(sessionDir(sessionId, basePath), 'session.json');
+}
+
+function summaryPath(sessionId: string, basePath?: string): string {
+  return join(sessionDir(sessionId, basePath), 'session_summary.md');
+}
+
+export function generateSessionId(): string {
+  const now = new Date();
+  const y = now.getFullYear();
+  const m = String(now.getMonth() + 1).padStart(2, '0');
+  const d = String(now.getDate()).padStart(2, '0');
+  const hh = String(now.getHours()).padStart(2, '0');
+  const mm = String(now.getMinutes()).padStart(2, '0');
+  return `adhoc_${y}${m}${d}_${hh}${mm}`;
+}
+
+function isoNow(): string {
+  return new Date().toISOString();
+}
+
+function isoDate(d?: Date): string {
+  const dt = d ?? new Date();
+  return `${dt.getFullYear()}${String(dt.getMonth() + 1).padStart(2, '0')}${String(dt.getDate()).padStart(2, '0')}`;
+}
+
+function isTodayIso(iso: string): boolean {
+  return iso.startsWith(new Date().toISOString().slice(0, 10));
+}
+
+function tryParseJson<T>(raw: string): T | null {
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return null;
+  }
+}
+
+async function ensureDir(p: string): Promise<void> {
+  if (!existsSync(p)) {
+    await mkdir(p, { recursive: true });
+  }
+}
+
+async function readLines(p: string): Promise<string[]> {
+  try {
+    const content = await readFile(p, 'utf-8');
+    return content.split('\n').filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+async function readJsonFile<T>(p: string): Promise<T | null> {
+  try {
+    const raw = await readFile(p, 'utf-8');
+    return tryParseJson<T>(raw);
+  } catch {
+    return null;
+  }
+}
+
+function appendLine(p: string, line: string): Promise<void> {
+  return appendFile(p, line + '\n', 'utf-8');
+}
+
+async function clearFile(p: string): Promise<void> {
+  try {
+    await writeFile(p, '', 'utf-8');
+  } catch {
+    // File may not exist
+  }
+}
+
+export async function getCurrentSession(basePath?: string): Promise<string | null> {
+  try {
+    const raw = await readFile(currentSessionPath(basePath), 'utf-8');
+    return raw.trim();
+  } catch {
+    return null;
+  }
+}
+
+export async function getSessionJson(sessionId: string, basePath?: string): Promise<SessionJson | null> {
+  return readJsonFile<SessionJson>(sessionJsonPath(sessionId, basePath));
+}
+
+export async function getIndex(basePath?: string): Promise<IndexJson | null> {
+  return readJsonFile<IndexJson>(indexJsonPath(basePath));
+}
+
+async function writeIndex(entries: IndexEntry[], basePath?: string): Promise<void> {
+  await ensureDir(runsDir(basePath));
+  await writeFile(indexJsonPath(basePath), JSON.stringify({ entries }, null, 2), 'utf-8');
+}
+
+async function appendIndex(sessionId: string, task: string, basePath?: string): Promise<void> {
+  const existing = await getIndex(basePath);
+  const entry: IndexEntry = {
+    id: sessionId,
+    task,
+    status: 'in_progress',
+    record_count: 0,
+    start_time: isoNow(),
+  };
+  const entries = [entry, ...(existing?.entries ?? [])].slice(0, 100);
+  await writeIndex(entries, basePath);
+}
+
+async function updateIndexStatus(sessionId: string, status: string, basePath?: string): Promise<void> {
+  const idx = await getIndex(basePath);
+  if (!idx) return;
+  for (const e of idx.entries) {
+    if (e.id === sessionId) {
+      e.status = status;
+    }
+  }
+  await writeIndex(idx.entries, basePath);
+}
+
+export async function startSession(task: string, basePath?: string): Promise<StartSessionResult> {
+  const sessionId = generateSessionId();
+  const sDir = sessionDir(sessionId, basePath);
+  await ensureDir(sDir);
+
+  const session: SessionJson = {
+    session_id: sessionId,
+    task,
+    start_time: isoNow(),
+    status: 'in_progress',
+    expected_record_types: ['data', 'change', 'conversation'],
+  };
+
+  await writeFile(sessionJsonPath(sessionId, basePath), JSON.stringify(session, null, 2), 'utf-8');
+  await writeFile(currentSessionPath(basePath), sessionId, 'utf-8');
+  await appendIndex(sessionId, task, basePath);
+
+  // L0 context recovery
+  const idx = await getIndex(basePath);
+  const recentActivity = idx?.entries.slice(0, 5) ?? [];
+
+  // L2 user correction scan
+  const allCorrections = await scanAllTrailsForCorrections(basePath);
+
+  // Check for unfinished sessions
+  const unfinishedSessions = await findUnfinishedSessions(basePath);
+
+  return {
+    sessionId,
+    contextSummary: {
+      recentActivity,
+      userCorrections: allCorrections,
+      unfinishedSessions,
+    },
+  };
+}
+
+async function findUnfinishedSessions(basePath?: string): Promise<SessionJson[]> {
+  const rDir = runsDir(basePath);
+  if (!existsSync(rDir)) return [];
+
+  const entries = await readdir(rDir, { withFileTypes: true });
+  const unfinished: SessionJson[] = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const sess = await getSessionJson(entry.name, basePath);
+    if (sess && sess.status === 'in_progress') {
+      unfinished.push(sess);
+    }
+  }
+
+  return unfinished;
+}
+
+async function scanAllTrailsForCorrections(basePath?: string): Promise<UserCorrectionRecord[]> {
+  const rDir = runsDir(basePath);
+  if (!existsSync(rDir)) return [];
+
+  const entries = await readdir(rDir, { withFileTypes: true });
+  const corrections: UserCorrectionRecord[] = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const lines = await readLines(trailPath(entry.name, basePath));
+    for (const line of lines) {
+      const record = tryParseJson<UserCorrectionRecord>(line);
+      if (record?.action_type === 'user_correction') {
+        corrections.push(record);
+      }
+    }
+  }
+
+  // Also scan audit_pending.jsonl
+  const pendingLines = await readLines(auditPendingPath(basePath));
+  for (const line of pendingLines) {
+    const record = tryParseJson<UserCorrectionRecord>(line);
+    if (record?.action_type === 'user_correction') {
+      corrections.push(record);
+    }
+  }
+
+  return corrections;
+}
+
+export async function endSession(basePath?: string): Promise<EndSessionResult | null> {
+  const sessionId = await getCurrentSession(basePath);
+  if (!sessionId) return null;
+
+  const sDir = sessionDir(sessionId, basePath);
+  await ensureDir(sDir);
+
+  // Collect remaining buffer data
+  const bufferLines = await readLines(auditBufferPath(basePath));
+  const pendingLines = await readLines(auditPendingPath(basePath));
+  const allRemaining = [...bufferLines, ...pendingLines];
+
+  // Append to audit_trail.jsonl
+  const trail = trailPath(sessionId, basePath);
+  if (allRemaining.length > 0) {
+    await appendFile(trail, allRemaining.join('\n') + '\n', 'utf-8');
+  }
+
+  // Clear buffer files
+  await clearFile(auditBufferPath(basePath));
+  await clearFile(auditPendingPath(basePath));
+
+  // Read current trail for stats
+  const trailLines = await readLines(trail);
+
+  // Extract user_correction records
+  const corrections: UserCorrectionRecord[] = [];
+  for (const line of trailLines) {
+    const record = tryParseJson<UserCorrectionRecord>(line);
+    if (record?.action_type === 'user_correction') {
+      corrections.push(record);
+    }
+  }
+
+  // Integrity checks
+  const integrity: IntegrityCheck[] = [
+    {
+      check: 'Audit records exist',
+      passed: trailLines.length > 0,
+      detail: trailLines.length > 0 ? `${trailLines.length} records` : 'No audit records found',
+    },
+    {
+      check: 'File modifications tracked',
+      passed: trailLines.some((l) => {
+        const r = tryParseJson<AuditTrailEntry>(l);
+        return r && (r.tool === 'Write' || r.tool === 'Edit');
+      }),
+      detail: 'Checking for Write/Edit tool entries',
+    },
+    {
+      check: 'User corrections persisted',
+      passed: corrections.every((c) => (c.persisted_to?.length ?? 0) > 0),
+      detail: corrections.length > 0
+        ? `${corrections.length} corrections found, ${corrections.filter((c) => (c.persisted_to?.length ?? 0) > 0).length} persisted`
+        : 'No corrections to persist',
+    },
+  ];
+
+  // Generate session summary
+  const summaryContent = generateSessionSummary(sessionId, trailLines, corrections);
+  const summaryFile = summaryPath(sessionId, basePath);
+  await writeFile(summaryFile, summaryContent, 'utf-8');
+
+  // Update session.json
+  const session = await getSessionJson(sessionId, basePath);
+  if (session) {
+    session.status = 'completed';
+    session.end_time = isoNow();
+    await writeFile(sessionJsonPath(sessionId, basePath), JSON.stringify(session, null, 2), 'utf-8');
+    await updateIndexStatus(sessionId, 'completed', basePath);
+  }
+
+  // Update index.json record count
+  const idx = await getIndex(basePath);
+  if (idx) {
+    for (const e of idx.entries) {
+      if (e.id === sessionId) {
+        e.record_count = trailLines.length;
+        e.status = 'completed';
+      }
+    }
+    await writeIndex(idx.entries, basePath);
+  }
+
+  // Clear .current_session
+  try {
+    await rm(currentSessionPath(basePath));
+  } catch {
+    // Ok if already gone
+  }
+
+  return {
+    sessionId,
+    integrity,
+    correctionCount: corrections.length,
+    summaryPath: summaryFile,
+  };
+}
+
+function generateSessionSummary(
+  sessionId: string,
+  trailLines: string[],
+  corrections: UserCorrectionRecord[],
+): string {
+  const actions: string[] = [];
+  const outputs: string[] = [];
+
+  for (const line of trailLines) {
+    const record = tryParseJson<AuditTrailEntry>(line);
+    if (record) {
+      if (record.action_type) actions.push(record.action_type);
+      if (record.output) outputs.push(record.output);
+    }
+  }
+
+  return [
+    `# Session Summary | ${sessionId}`,
+    '',
+    `## Time: ${isoNow()}`,
+    `## Status: completed`,
+    '',
+    '## Completed work',
+    ...actions.map((a) => `- ${a}`),
+    '',
+    '## Key conclusions',
+    ...outputs.map((o) => `- ${o}`),
+    '',
+    '## User corrections',
+    ...(corrections.length > 0
+      ? corrections.map((c) => `- ${c.original_claim} → ${c.correction} (${c.principle_extracted})`)
+      : ['- None']),
+    '',
+  ].join('\n');
+}
+
+export async function recoverSession(
+  level: number,
+  specificSessionId?: string,
+  basePath?: string,
+): Promise<RecoverResult> {
+  const result: RecoverResult = { level, recentActivity: [], lastTrailEntries: [], userCorrections: [], conclusions: [], dailyAnomalies: [], dailyBacklog: [] };
+
+  // L0: index summary
+  const idx = await getIndex(basePath);
+  result.recentActivity = idx?.entries.slice(0, 5) ?? [];
+
+  if (level === 0) return result;
+
+  // L1: current session + last 3 trail entries
+  let activeSessionId = specificSessionId ?? await getCurrentSession(basePath);
+  if (activeSessionId) {
+    result.sessionId = activeSessionId;
+    const session = await getSessionJson(activeSessionId, basePath);
+    if (session) {
+      result.task = session.task;
+    }
+
+    const trailLines = await readLines(trailPath(activeSessionId, basePath));
+    result.lastTrailEntries = trailLines.slice(-3).map((l) => {
+      const r = tryParseJson<AuditTrailEntry>(l);
+      return r ?? { timestamp: '', record_type: '', action_type: '', input: l, output: l };
+    });
+  }
+
+  if (level === 1) return result;
+
+  // L2: user corrections + conclusions + daily anomalies
+  result.userCorrections = await scanAllTrailsForCorrections(basePath);
+
+  // Extract conclusions from trail entries
+  const allTrailLines = await readLines(trailPath(activeSessionId ?? '', basePath));
+  for (const line of allTrailLines) {
+    const record = tryParseJson<AuditTrailEntry>(line);
+    if (record?.output) {
+      result.conclusions.push(record.output);
+    }
+  }
+
+  // Read daily reports for anomalies + backlog
+  const dDir = dailyDir(basePath);
+  if (existsSync(dDir)) {
+    const dailyFiles = (await readdir(dDir)).filter((f) => f.endsWith('_daily.md')).sort().reverse();
+    if (dailyFiles.length > 0) {
+      const latest = await readFile(join(dDir, dailyFiles[0]!), 'utf-8');
+      const anomalies = latest.match(/## (?:四|4).*?[\s\S]*?(?=##|$)/);
+      if (anomalies) result.dailyAnomalies.push(anomalies[0]);
+      const backlog = latest.match(/## (?:六|6).*?[\s\S]*?(?=##|$)/);
+      if (backlog) result.dailyBacklog.push(backlog[0]);
+    }
+  }
+
+  if (level === 2) return result;
+
+  // L3: full trail + pending
+  if (level >= 3) {
+    if (activeSessionId) {
+      const fullLines = await readLines(trailPath(activeSessionId, basePath));
+      result.fullTrail = fullLines.map((l) => {
+        const r = tryParseJson<AuditTrailEntry>(l);
+        return r ?? { timestamp: '', record_type: '', action_type: '', input: l, output: l };
+      });
+    }
+  }
+
+  return result;
+}
+
+export async function generateDailyReport(
+  targetDate?: string,
+  review?: boolean,
+  basePath?: string,
+): Promise<DailyReport> {
+  const date = targetDate ?? isoDate();
+  const idx = await getIndex(basePath);
+  const rDir = runsDir(basePath);
+
+  const todayEntries = (idx?.entries ?? []).filter((e) => e.start_time.startsWith(date.slice(0, 4) + '-' + date.slice(4, 6) + '-' + date.slice(6, 8)));
+
+  let totalWriteEdit = 0;
+  let totalBash = 0;
+  let totalAuditBlocks = 0;
+  const changes: { time: string; target: string; detail: string }[] = [];
+  const feedback: { feedback: string; resolution: string; persistedTo: string }[] = [];
+  const anomalies: string[] = [];
+
+  for (const entry of todayEntries) {
+    const lines = await readLines(trailPath(entry.id, basePath));
+    for (const line of lines) {
+      const record = tryParseJson<AuditTrailEntry>(line);
+      if (!record) continue;
+      if (record.tool === 'Write' || record.tool === 'Edit') totalWriteEdit++;
+      if (record.tool === 'Bash') totalBash++;
+      if (record.action_type === 'audit_block') totalAuditBlocks++;
+      if (record.tool && (record.tool === 'Write' || record.tool === 'Edit') && record.files) {
+        changes.push({ time: record.timestamp, target: record.files.join(', '), detail: record.detail ?? '' });
+      }
+      if (record.action_type === 'user_correction') {
+        const uc = record as unknown as UserCorrectionRecord;
+        feedback.push({ feedback: uc.original_claim, resolution: uc.correction, persistedTo: (uc.persisted_to ?? []).join(', ') });
+      }
+    }
+  }
+
+  // Check for anomalies.json
+  if (existsSync(rDir)) {
+    const sessionDirs = await readdir(rDir, { withFileTypes: true });
+    for (const d of sessionDirs) {
+      if (!d.isDirectory()) continue;
+      const anomPath = join(rDir, d.name, 'anomalies.json');
+      if (existsSync(anomPath)) {
+        const anomContent = await readFile(anomPath, 'utf-8');
+        anomalies.push(`[${d.name}] ${anomContent.slice(0, 200)}`);
+      }
+    }
+  }
+
+  // Read previous day backlog
+  const prevDate = isoDate(new Date(Date.now() - 86400000));
+  let backlog: string[] = [];
+  const prevDailyPath = join(dailyDir(basePath), `${prevDate}_daily.md`);
+  if (existsSync(prevDailyPath)) {
+    const prevContent = await readFile(prevDailyPath, 'utf-8');
+    const m = prevContent.match(/## (?:六|6|明日待办)[\s\S]*?(?=##|$)/);
+    if (m) backlog = m[0].split('\n').filter((l) => l.trim().startsWith('-')).map((l) => l.replace(/^-\s*/, ''));
+  }
+
+  const reportPath = join(dailyDir(basePath), `${date}_daily.md`);
+  await ensureDir(dailyDir(basePath));
+
+  const sections = {
+    taskOverview: todayEntries.length > 0
+      ? todayEntries.map((e) => `| ${e.id} | ${e.task} | ${e.status} | ${e.record_count} |`).join('\n')
+      : 'No activity',
+    operationStats: [
+      { label: 'Write/Edit operations', count: totalWriteEdit },
+      { label: 'Bash executions', count: totalBash },
+      { label: 'Audit blocks', count: totalAuditBlocks },
+    ],
+    changes,
+    userFeedback: feedback,
+    anomalyAlerts: anomalies,
+    backlogTracking: backlog,
+    integritySummary: [
+      `| All sessions have audit records | ${todayEntries.every((e) => e.record_count > 0) ? '✅' : '⚠️'} |`,
+      `| Audit blocks persisted | ${totalAuditBlocks > 0 ? '✅' : '⚠️'} |`,
+      `| User corrections persisted | ${feedback.every((f) => f.persistedTo.length > 0) ? '✅' : '⚠️'} |`,
+    ].join('\n'),
+  };
+
+  const reportContent = generateDailyReportContent(date, sections);
+  await writeFile(reportPath, reportContent, 'utf-8');
+
+  // If review mode, also generate morning review
+  if (review) {
+    const reviewPath = join(dailyDir(basePath), `${date}_morning_review.md`);
+    const reviewContent = generateMorningReview(sections, date);
+    await writeFile(reviewPath, reviewContent, 'utf-8');
+  }
+
+  return { date, sections, path: reportPath };
+}
+
+function generateDailyReportContent(date: string, sections: DailyReport['sections']): string {
+  return [
+    `# Work Report | ${date}`,
+    '',
+    `> Auto-generated: ${isoNow()}`,
+    `> Data source: .boo/runs/index.json + session audit_trail`,
+    `> Coverage: ${date.slice(0, 4)}-${date.slice(4, 6)}-${date.slice(6, 8)} 00:00 — 23:59`,
+    '',
+    '---',
+    '',
+    '## I. Task Overview',
+    '',
+    '| Session ID | Task | Status | Records |',
+    '|-----------|------|--------|---------|',
+    sections.taskOverview,
+    '',
+    '---',
+    '',
+    '## II. Operation Stats',
+    '',
+    '| Metric | Count |',
+    '|--------|-------|',
+    ...sections.operationStats.map((s) => `| ${s.label} | ${s.count} |`),
+    '',
+    '---',
+    '',
+    '## III. Change Records',
+    '',
+    ...(sections.changes.length > 0
+      ? ['| Time | Target | Detail |', '|------|--------|--------|', ...sections.changes.map((c) => `| ${c.time} | ${c.target} | ${c.detail} |`)]
+      : ['No changes recorded today.']),
+    '',
+    '---',
+    '',
+    '## IV. User Feedback & Corrections',
+    '',
+    ...(sections.userFeedback.length > 0
+      ? ['| Feedback | Resolution | Persisted To |', '|---------|------------|--------------|', ...sections.userFeedback.map((f) => `| ${f.feedback} | ${f.resolution} | ${f.persistedTo} |`)]
+      : ['None.']),
+    '',
+    '---',
+    '',
+    '## V. Anomaly Alerts',
+    '',
+    ...(sections.anomalyAlerts.length > 0 ? sections.anomalyAlerts.map((a) => `- ${a}`) : ['None.']),
+    '',
+    '---',
+    '',
+    '## VI. Backlog Tracking',
+    '',
+    ...(sections.backlogTracking.length > 0 ? sections.backlogTracking.map((b) => `- ${b}`) : ['None.']),
+    '',
+    '---',
+    '',
+    '## VII. Integrity Summary',
+    '',
+    '| Check | Result |',
+    '|-------|--------|',
+    sections.integritySummary,
+    '',
+  ].join('\n');
+}
+
+function generateMorningReview(sections: DailyReport['sections'], date: string): string {
+  const anomalies = sections.anomalyAlerts;
+  const hasUnhandledAnomalies = anomalies.some((a) => !a.includes('resolved'));
+  const hasUnpersistedFeedback = sections.userFeedback.some((f) => !f.persistedTo);
+  const hasIncompleteBacklog = sections.backlogTracking.length > 0;
+
+  return [
+    `# Morning Self-Review | ${date}`,
+    '',
+    `> Generated: ${isoNow()}`,
+    '',
+    '## Self-Correction Check',
+    '',
+    `- Unresolved anomalies: ${hasUnhandledAnomalies ? '⚠️ Yes — needs attention' : '✅ None'}`,
+    `- Unpersisted user feedback: ${hasUnpersistedFeedback ? '⚠️ Needs documentation' : '✅ All persisted'}`,
+    `- Outstanding backlog: ${hasIncompleteBacklog ? '⚠️ Carry-over items' : '✅ Clean slate'}`,
+    '',
+    '## Today\'s Recommended Priorities',
+    '',
+    ...(sections.backlogTracking.length > 0
+      ? sections.backlogTracking.map((b) => `- [ ] ${b} (carry-over)`)
+      : []),
+    '- [ ] Review yesterday\'s user feedback and persist any remaining corrections',
+    '- [ ] Continue highest-priority task from session overview',
+    '',
+  ].join('\n');
+}
+
+export async function ensureBooDirs(basePath?: string): Promise<void> {
+  await ensureDir(runsDir(basePath));
+  await ensureDir(dailyDir(basePath));
+}
+
+export async function writeAuditBuffer(entry: AuditTrailEntry, basePath?: string): Promise<void> {
+  await ensureDir(runsDir(basePath));
+  await appendLine(auditBufferPath(basePath), JSON.stringify(entry));
+}
+
+export async function writeAuditPending(entry: AuditTrailEntry, basePath?: string): Promise<void> {
+  await ensureDir(runsDir(basePath));
+  await appendLine(auditPendingPath(basePath), JSON.stringify(entry));
+}

apps/coder/src/services/backends/paseo.ts

@@ -0,0 +1,254 @@
+/**
+ * v2.10 — PaseoBackend: Paseo agent integration for the agent-pool.
+ *
+ * Wraps the Paseo CLI daemon as an AgentBackend. Each Paseo agent maps to one
+ * (chat_id, agent) pair and is persisted via `paseo import` (which registers
+ * an agent with the Paseo daemon). Prompts are sent via `paseo send`, and
+ * the session is cleaned up via `paseo archive`.
+ *
+ * Paseo is a meta-agent hub — it wraps provider sessions (opencode, claude,
+ * acp, etc.). The `provider` option in `EnsureSessionOpts` selects which
+ * provider Paseo delegates to.
+ *
+ * Backend kind: 'paseo' (must be added to agent_sessions_backend_chk).
+ *
+ * Spec: openspec/changes/v2-10-paseo-integration/design.md.
+ */
+import type { FastifyBaseLogger } from 'fastify';
+import type { Sql } from '../../db.js';
+import { PaseoClient, type PaseoSendResult } from '../paseo-client.js';
+import type {
+  AgentBackend,
+  AgentSessionHandle,
+  EnsureSessionOpts,
+  PromptCtx,
+  TurnResult,
+} from '../agent-backend.js';
+
+/** Default provider to use when Paseo wraps a generic agent. */
+const DEFAULT_PASEO_PROVIDER = 'opencode';
+
+export interface PaseoBackendDeps {
+  sql: Sql;
+  log: FastifyBaseLogger;
+  /** The (chat, agent) this backend serves — its pool identity + DB key. */
+  chatId: string;
+  /** Agent name (e.g. 'opencode', 'claude', 'paseo'). */
+  agent: string;
+  /** Resolved PaseoClient instance. */
+  client: PaseoClient;
+  /** Provider string to pass to `paseo import --provider`. */
+  provider: string;
+}
+
+export class PaseoBackend implements AgentBackend {
+  readonly backend = 'paseo' as const;
+
+  private readonly sql: Sql;
+  private readonly log: FastifyBaseLogger;
+  private readonly chatId: string;
+  private readonly agent: string;
+  private readonly client: PaseoClient;
+  private readonly provider: string;
+
+  /** Map of BooCode sessionId → Paseo agent ID. */
+  private readonly agentIds = new Map<string, string>();
+  /** True between prompt() start and settle. */
+  private busy = false;
+  private up = false;
+
+  constructor(deps: PaseoBackendDeps) {
+    this.sql = deps.sql;
+    this.log = deps.log;
+    this.chatId = deps.chatId;
+    this.agent = deps.agent;
+    this.client = deps.client;
+    this.provider = deps.provider || DEFAULT_PASEO_PROVIDER;
+  }
+
+  /** §2: liveness for the health endpoint + dispatcher fallback decision. */
+  health(): 'up' | 'down' {
+    return this.up ? 'up' : 'down';
+  }
+
+  /** Phase 3: busy iff a turn is in flight (pool never evicts a busy backend). */
+  isBusy(): boolean {
+    return this.busy;
+  }
+
+  // ─── ensureSession: create/import a Paseo agent ─────────────────────────────
+
+  async ensureSession(sessionId: string, opts: EnsureSessionOpts): Promise<AgentSessionHandle> {
+    // Check if we already have a Paseo agent ID for this session.
+    let paseoId = this.agentIds.get(sessionId);
+
+    if (!paseoId) {
+      // Resolve existing agent_session_id from DB (e.g. after a restart).
+      const [row] = await this.sql<{ agent_session_id: string | null }[]>`
+        SELECT agent_session_id FROM agent_sessions
+        WHERE chat_id = ${opts.chatId} AND agent = ${opts.agent} AND backend = 'paseo'
+      `;
+      if (row?.agent_session_id) {
+        paseoId = row.agent_session_id;
+        this.agentIds.set(sessionId, paseoId);
+      }
+    }
+
+    if (!paseoId) {
+      // Import a new Paseo agent. Use the session UUID as the provider session id.
+      const labels: Record<string, string> = {
+        origin: 'boocode',
+        project: opts.projectId,
+        chat: opts.chatId,
+        worktree: opts.worktreeId,
+        agent: this.agent,
+      };
+
+      try {
+        const agent = await this.client.importAgent(sessionId, this.provider, labels);
+        paseoId = agent.Id;
+        this.agentIds.set(sessionId, paseoId);
+        this.log.info(
+          { paseoId, agent: this.agent, chatId: this.chatId },
+          'paseo: imported agent',
+        );
+      } catch (err) {
+        this.log.error(
+          { err: String(err), agent: this.agent, chatId: this.chatId },
+          'paseo: importAgent failed',
+        );
+        throw err;
+      }
+    }
+
+    // Upsert the agent_sessions row.
+    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}, 'paseo', ${paseoId}, NULL, 'active', clock_timestamp())
+      ON CONFLICT (chat_id, agent) DO UPDATE SET
+        session_id = EXCLUDED.session_id,
+        worktree_id = EXCLUDED.worktree_id,
+        backend = 'paseo',
+        agent_session_id = COALESCE(EXCLUDED.agent_session_id, agent_sessions.agent_session_id),
+        server_port = NULL,
+        status = 'active',
+        last_active_at = clock_timestamp()
+    `.catch((err) => {
+      this.log.warn(
+        { err: String(err), chatId: opts.chatId, agent: opts.agent },
+        'paseo: agent_sessions upsert failed (non-fatal)',
+      );
+    });
+
+    this.up = true;
+
+    return {
+      sessionId,
+      agent: opts.agent,
+      backend: 'paseo',
+      chatId: opts.chatId,
+      worktreeId: opts.worktreeId,
+      agentSessionId: paseoId,
+      serverPort: null,
+    };
+  }
+
+  // ─── prompt: send a message to the Paseo agent ─────────────────────────────
+
+  async prompt(handle: AgentSessionHandle, input: string, ctx: PromptCtx): Promise<TurnResult> {
+    const paseoId = handle.agentSessionId;
+    if (!paseoId) {
+      return { ok: false, error: 'paseo: no agent session id in handle' };
+    }
+
+    this.busy = true;
+    try {
+      // Use streamSend for real-time text output via onEvent.
+      const result: PaseoSendResult = await this.client.streamSend(
+        paseoId,
+        input,
+        (event) => {
+          ctx.onEvent(event);
+        },
+        ctx.signal,
+      );
+
+      // Update last_active_at.
+      await this.sql`
+        UPDATE agent_sessions
+        SET last_active_at = clock_timestamp()
+        WHERE chat_id = ${handle.chatId} AND agent = ${handle.agent}
+      `.catch(() => { /* non-fatal */ });
+
+      if (result.error) {
+        return { ok: false, error: result.error };
+      }
+
+      return { ok: true };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      // Check if abortion
+      if (ctx.signal.aborted) {
+        return { ok: false, error: 'cancelled' };
+      }
+      return { ok: false, error: `paseo: ${msg}` };
+    } finally {
+      this.busy = false;
+    }
+  }
+
+  // ─── closeSession: archive the Paseo agent ─────────────────────────────────
+
+  async closeSession(handle: AgentSessionHandle): Promise<void> {
+    const paseoId = handle.agentSessionId;
+    if (!paseoId) return;
+
+    try {
+      await this.client.archiveAgent(paseoId);
+      this.log.info({ paseoId, agent: handle.agent }, 'paseo: archived agent');
+    } catch (err) {
+      this.log.warn(
+        { err: String(err), paseoId, agent: handle.agent },
+        'paseo: archiveAgent failed (non-fatal)',
+      );
+    }
+
+    this.agentIds.delete(handle.sessionId);
+
+    // Update DB row.
+    await this.sql`
+      UPDATE agent_sessions
+      SET status = 'closed', last_active_at = clock_timestamp()
+      WHERE chat_id = ${handle.chatId} AND agent = ${handle.agent}
+    `.catch(() => { /* non-fatal */ });
+  }
+
+  // ─── dispose: archive all tracked agents ───────────────────────────────────
+
+  async dispose(): Promise<void> {
+    const ids = [...this.agentIds.values()];
+    this.agentIds.clear();
+
+    for (const paseoId of ids) {
+      try {
+        await this.client.archiveAgent(paseoId);
+      } catch {
+        // Best-effort cleanup during shutdown.
+      }
+    }
+
+    this.up = false;
+  }
+
+  /** Phase 3: periodic health tick — probes the Paseo daemon. */
+  async tickHealth(_now?: number): Promise<void> {
+    try {
+      const h = await this.client.health();
+      this.up = h.status === 'ok';
+    } catch {
+      this.up = false;
+    }
+  }
+}

apps/coder/src/services/behavioral/generation.ts

@@ -0,0 +1,204 @@
+/**
+ * Schematic generator for behavioral guideline batches.
+ *
+ * Port of boocontext-audit/src/generation.ts — abstract LLM batch caller
+ * with temperature retry and structured output per batch type.
+ */
+
+import { type GenerationInfo } from './matching.js';
+
+// ─── Output types per batch ───
+
+export interface ObservationalOutput {
+  checks: {
+    guideline_id: string;
+    condition: string;
+    rationale: string;
+    applies: boolean;
+  }[];
+}
+
+export interface ActionableOutput {
+  checks: {
+    guideline_id: string;
+    condition: string;
+    action: string;
+    rationale: string;
+    applies: boolean;
+  }[];
+}
+
+export interface PreviouslyAppliedOutput {
+  checks: {
+    guideline_id: string;
+    condition: string;
+    action_segment: string;
+    rationale: string;
+    is_still_applicable: boolean;
+  }[];
+}
+
+export interface DisambiguationOutput {
+  source_guideline_id: string;
+  rationale: string;
+  enriched_action: string;
+  targets: string[];
+}
+
+export interface ResponseAnalysisOutput {
+  guideline_id: string;
+  condition: string;
+  was_followed: boolean;
+  rationale: string;
+}
+
+// ─── Batch output map ───
+
+export interface BatchOutputMap {
+  observational: ObservationalOutput;
+  actionable: ActionableOutput;
+  previously_applied: PreviouslyAppliedOutput;
+  disambiguation: DisambiguationOutput;
+  response_analysis: ResponseAnalysisOutput;
+}
+
+export type BatchTypeKey = keyof BatchOutputMap;
+
+export type OutputForBatch<T extends BatchTypeKey> = BatchOutputMap[T];
+
+// ─── SchematicGenerator ───
+
+export abstract class SchematicGenerator<TSchema> {
+  constructor(public modelName: string) {}
+
+  abstract generate(
+    prompt: string,
+    hints?: Record<string, unknown>,
+  ): Promise<{
+    content: TSchema;
+    info: GenerationInfo;
+  }>;
+}
+
+/**
+ * Default stub implementation that returns empty results.
+ * Replace with a real LLM caller in production.
+ */
+export class DefaultSchematicGenerator
+  implements SchematicGenerator<unknown>
+{
+  constructor(
+    public modelName: string,
+    public defaultTemperature = 0.7,
+  ) {}
+
+  async generate(
+    _prompt: string,
+    hints?: Record<string, unknown>,
+  ): Promise<{ content: unknown; info: GenerationInfo }> {
+    const temperature = (hints?.temperature as number) ?? this.defaultTemperature;
+    return {
+      content: {},
+      info: {
+        model: this.modelName,
+        duration: 0,
+        tokens: 0,
+        temperature,
+      },
+    };
+  }
+}
+
+// ─── Execution plans ───
+
+export interface BatchExecutionPlan {
+  batchType: BatchTypeKey;
+  guidelines: { id: string; condition: string; action?: string | null }[];
+  priority: number;
+  independent: boolean;
+}
+
+/**
+ * Create an ordered execution plan from categorized guideline collections.
+ * Groups are sorted by priority: previously_applied (fastest) first,
+ * then observational, actionable, disambiguation, low-criticality last.
+ */
+export function createExecutionPlan(
+  observational: { id: string; condition: string }[],
+  actionable: { id: string; condition: string; action: string }[],
+  previouslyApplied: { id: string; condition: string; action?: string | null }[],
+  disambiguationGroups: { source: string; targets: string[]; enrichedAction: string }[],
+  lowCriticality: { id: string; condition: string }[],
+): BatchExecutionPlan[] {
+  const plans: BatchExecutionPlan[] = [];
+
+  if (observational.length > 0) {
+    plans.push({
+      batchType: 'observational',
+      guidelines: observational.map((g) => ({ id: g.id, condition: g.condition })),
+      priority: 1,
+      independent: true,
+    });
+  }
+
+  if (actionable.length > 0) {
+    plans.push({
+      batchType: 'actionable',
+      guidelines: actionable.map((g) => ({
+        id: g.id,
+        condition: g.condition,
+        action: g.action,
+      })),
+      priority: 2,
+      independent: true,
+    });
+  }
+
+  if (previouslyApplied.length > 0) {
+    plans.push({
+      batchType: 'previously_applied',
+      guidelines: previouslyApplied.map((g) => ({
+        id: g.id,
+        condition: g.condition,
+        action: g.action,
+      })),
+      priority: 0,
+      independent: true,
+    });
+  }
+
+  if (disambiguationGroups.length > 0) {
+    plans.push({
+      batchType: 'disambiguation',
+      guidelines: disambiguationGroups.map((g) => ({
+        id: g.source,
+        condition: g.enrichedAction,
+      })),
+      priority: 3,
+      independent: true,
+    });
+  }
+
+  if (lowCriticality.length > 0) {
+    plans.push({
+      batchType: 'observational',
+      guidelines: lowCriticality.map((g) => ({ id: g.id, condition: g.condition })),
+      priority: 10,
+      independent: true,
+    });
+  }
+
+  return plans.sort((a, b) => a.priority - b.priority);
+}
+
+/**
+ * Compute retry temperatures: base + 0.2 * attempt.
+ * Provides progressive temperature increases for failed calls.
+ */
+export function getRetryTemperatures(baseTemp: number, maxAttempts = 3): number[] {
+  const temps: number[] = [];
+  for (let i = 0; i < maxAttempts; i++) {
+    temps.push(baseTemp + i * 0.2);
+  }
+  return temps;
+}

apps/coder/src/services/behavioral/index.ts

@@ -0,0 +1,77 @@
+/**
+ * Behavioral engine — multi-batch matcher and relational resolver.
+ *
+ * Import from the existing guideline-service.ts:
+ *   import { MultiBatchMatcher } from './behavioral/matching.js';
+ *   import { RelationalResolver } from './behavioral/resolver.js';
+ */
+
+// matching.ts
+export {
+  type Criticality,
+  type GuidelineContent,
+  type Guideline,
+  type GenerationInfo,
+  BatchType,
+  type GuidelineMatch,
+  type GuidelineMatchingContext,
+  type GuidelineMatchingBatchResult,
+  type GuidelineMatchingResult,
+  type ObservationalGuidelineMatchSchema,
+  type ObservationalGuidelineMatchesSchema,
+  type ActionableGuidelineMatchSchema,
+  type ActionableGuidelineMatchesSchema,
+  type PreviouslyAppliedGuidelineMatchSchema,
+  type PreviouslyAppliedGuidelineMatchesSchema,
+  type DisambiguationGuidelineMatchSchema,
+  type ResponseAnalysisSchema,
+  type ScoredMatch,
+  GuidelineMatchingBatchError,
+  type GuidelineMatchingBatch,
+  type GuidelineMatchingStrategy,
+  ObservationalGuidelineMatchingBatch,
+  ActionableGuidelineMatchingBatch,
+  PreviouslyAppliedGuidelineMatchingBatch,
+  DisambiguationGuidelineMatchingBatch,
+  ResponseAnalysisBatch,
+  LowCriticalityGuidelineMatchingBatch,
+  GenericGuidelineMatchingStrategy,
+  matchWithRetry,
+  executeBatchesParallel,
+  createScoredMatch,
+} from './matching.js';
+
+// resolver.ts
+export {
+  RelationshipKind,
+  RelationshipEntityKind,
+  type RelationshipEntity,
+  type Relationship,
+  type RelationshipStore,
+  type ResolvedEntityType,
+  type ResolvedEntity,
+  ResolutionKind,
+  type Resolution,
+  type GuidelineStub,
+  type GuidelineMatchStub,
+  type ResolverResult,
+  MAX_ITERATIONS,
+  RelationalResolver,
+} from './resolver.js';
+
+// generation.ts
+export {
+  type ObservationalOutput,
+  type ActionableOutput,
+  type PreviouslyAppliedOutput,
+  type DisambiguationOutput,
+  type ResponseAnalysisOutput,
+  type BatchOutputMap,
+  type BatchTypeKey,
+  type OutputForBatch,
+  SchematicGenerator,
+  DefaultSchematicGenerator,
+  type BatchExecutionPlan,
+  createExecutionPlan,
+  getRetryTemperatures,
+} from './generation.js';

apps/coder/src/services/behavioral/matching.ts

@@ -0,0 +1,435 @@
+/**
+ * Multi-batch matcher for behavioral guidelines.
+ *
+ * Port of boocontext-audit/src/matching.ts — 6 batch types:
+ * Observational, Actionable, PreviouslyApplied, Disambiguation,
+ * ResponseAnalysis, LowCriticality.
+ */
+
+// ─── Guideline types (compatible with guideline-service.ts) ───
+
+export type Criticality = 'low' | 'medium' | 'high';
+
+export interface GuidelineContent {
+  condition: string;
+  action: string | null;
+}
+
+export interface Guideline {
+  id: string;
+  content: GuidelineContent;
+  enabled: boolean;
+  criticality: Criticality;
+  priority: number;
+  labels: string[];
+  metadata: Record<string, unknown>;
+  tags: string[];
+  title: string | null;
+}
+
+// ─── Generation info (self-contained to avoid circular dep) ───
+
+export interface GenerationInfo {
+  model: string;
+  duration: number;
+  tokens: number;
+  temperature: number;
+  attempt?: number;
+}
+
+// ─── Batch type enum ───
+
+export enum BatchType {
+  Observational = 'observational',
+  Actionable = 'actionable',
+  PreviouslyApplied = 'previously_applied',
+  Disambiguation = 'disambiguation',
+  ResponseAnalysis = 'response_analysis',
+  LowCriticality = 'low_criticality',
+}
+
+// ─── Match result types ───
+
+export interface GuidelineMatch {
+  guideline: Guideline;
+  score: number;
+  rationale: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface GuidelineMatchingContext {
+  agent: string;
+  session: string;
+  customer: string;
+  contextVariables: Record<string, string>[];
+  interactionHistory: unknown[];
+  terms: string[];
+  capabilities?: string[];
+  stagedEvents?: unknown[];
+  activeJourneys?: unknown[];
+  journeyPaths?: Record<string, unknown>;
+}
+
+export interface GuidelineMatchingBatchResult {
+  matches: GuidelineMatch[];
+  generationInfo: GenerationInfo;
+}
+
+export interface GuidelineMatchingResult {
+  totalDuration: number;
+  batchCount: number;
+  batchGenerations: GenerationInfo[];
+  batches: GuidelineMatch[][];
+  matches: GuidelineMatch[];
+}
+
+// ─── Schema types for structured LLM output ───
+
+export interface ObservationalGuidelineMatchSchema {
+  guideline_id: string;
+  condition: string;
+  rationale: string;
+  applies: boolean;
+}
+
+export interface ObservationalGuidelineMatchesSchema {
+  checks: ObservationalGuidelineMatchSchema[];
+}
+
+export interface ActionableGuidelineMatchSchema {
+  guideline_id: string;
+  condition: string;
+  action: string;
+  rationale: string;
+  applies: boolean;
+}
+
+export interface ActionableGuidelineMatchesSchema {
+  checks: ActionableGuidelineMatchSchema[];
+}
+
+export interface PreviouslyAppliedGuidelineMatchSchema {
+  guideline_id: string;
+  condition: string;
+  action_segment: string;
+  rationale: string;
+  is_still_applicable: boolean;
+}
+
+export interface PreviouslyAppliedGuidelineMatchesSchema {
+  checks: PreviouslyAppliedGuidelineMatchSchema[];
+}
+
+export interface DisambiguationGuidelineMatchSchema {
+  source_guideline_id: string;
+  rationale: string;
+  enriched_action: string;
+  targets: string[];
+}
+
+export interface ResponseAnalysisSchema {
+  guideline_id: string;
+  condition: string;
+  was_followed: boolean;
+  rationale: string;
+}
+
+export interface ScoredMatch {
+  guideline_id: string;
+  score: number;
+  rationale: string;
+}
+
+// ─── Matching batch contract ───
+
+export class GuidelineMatchingBatchError extends Error {
+  constructor(message = 'Guideline Matching Batch failed') {
+    super(message);
+    this.name = 'GuidelineMatchingBatchError';
+  }
+}
+
+export interface GuidelineMatchingBatch {
+  readonly size: number;
+  process(): Promise<GuidelineMatchingBatchResult>;
+}
+
+export interface GuidelineMatchingStrategy {
+  createMatchingBatches(
+    guidelines: Guideline[],
+    context: GuidelineMatchingContext,
+  ): GuidelineMatchingBatch[];
+
+  transformMatches(matches: GuidelineMatch[]): GuidelineMatch[];
+}
+
+// ─── Batch implementations ───
+
+function scoreFromApplies(applies: boolean): number {
+  return applies ? 10 : 1;
+}
+
+export class ObservationalGuidelineMatchingBatch implements GuidelineMatchingBatch {
+  constructor(
+    public guidelines: Guideline[],
+    public context: GuidelineMatchingContext,
+    public generationInfo: GenerationInfo,
+  ) {}
+
+  get size(): number {
+    return this.guidelines.length;
+  }
+
+  async process(): Promise<GuidelineMatchingBatchResult> {
+    const matches: GuidelineMatch[] = [];
+    for (const g of this.guidelines) {
+      if (g.content.action !== null && g.content.action !== undefined) continue;
+      matches.push({
+        guideline: g,
+        score: 10,
+        rationale: `Observational batch evaluated: "${g.content.condition}"`,
+        metadata: { batch_type: BatchType.Observational },
+      });
+    }
+    return { matches, generationInfo: this.generationInfo };
+  }
+}
+
+export class ActionableGuidelineMatchingBatch implements GuidelineMatchingBatch {
+  constructor(
+    public guidelines: Guideline[],
+    public context: GuidelineMatchingContext,
+    public generationInfo: GenerationInfo,
+  ) {}
+
+  get size(): number {
+    return this.guidelines.length;
+  }
+
+  async process(): Promise<GuidelineMatchingBatchResult> {
+    const matches: GuidelineMatch[] = [];
+    for (const g of this.guidelines) {
+      if (g.content.action === null || g.content.action === undefined) continue;
+      if (g.content.action === '') continue;
+      matches.push({
+        guideline: g,
+        score: 10,
+        rationale: `Actionable batch evaluated: when "${g.content.condition}", then "${g.content.action}"`,
+        metadata: { batch_type: BatchType.Actionable },
+      });
+    }
+    return { matches, generationInfo: this.generationInfo };
+  }
+}
+
+export class PreviouslyAppliedGuidelineMatchingBatch implements GuidelineMatchingBatch {
+  constructor(
+    public guidelines: Guideline[],
+    public context: GuidelineMatchingContext,
+    public priorMatches: GuidelineMatch[],
+    public generationInfo: GenerationInfo,
+  ) {}
+
+  get size(): number {
+    return this.guidelines.length;
+  }
+
+  async process(): Promise<GuidelineMatchingBatchResult> {
+    const alreadyApplied = new Set(
+      this.priorMatches.filter((m) => m.score >= 10).map((m) => m.guideline.id),
+    );
+    const matches: GuidelineMatch[] = [];
+    for (const g of this.guidelines) {
+      if (alreadyApplied.has(g.id)) {
+        matches.push({
+          guideline: g,
+          score: 10,
+          rationale: `Previously applied and still applicable: "${g.content.condition}"`,
+          metadata: { batch_type: BatchType.PreviouslyApplied },
+        });
+      }
+    }
+    return { matches, generationInfo: this.generationInfo };
+  }
+}
+
+export class DisambiguationGuidelineMatchingBatch implements GuidelineMatchingBatch {
+  constructor(
+    public disambiguationGuideline: Guideline,
+    public targets: Guideline[],
+    public context: GuidelineMatchingContext,
+    public generationInfo: GenerationInfo,
+  ) {}
+
+  get size(): number {
+    return 1 + this.targets.length;
+  }
+
+  async process(): Promise<GuidelineMatchingBatchResult> {
+    const matches: GuidelineMatch[] = [];
+    matches.push({
+      guideline: this.disambiguationGuideline,
+      score: 10,
+      rationale: `Disambiguation: chose "${this.disambiguationGuideline.content.condition}" over targets`,
+      metadata: {
+        batch_type: BatchType.Disambiguation,
+        disambiguation: {
+          targets: this.targets.map((t) => t.id),
+          enriched_action: this.disambiguationGuideline.content.action ?? '',
+        },
+      },
+    });
+    return { matches, generationInfo: this.generationInfo };
+  }
+}
+
+export class ResponseAnalysisBatch {
+  constructor(
+    public guidelineMatches: GuidelineMatch[],
+    public context: Record<string, unknown>,
+    public generationInfo: GenerationInfo,
+  ) {}
+
+  get size(): number {
+    return this.guidelineMatches.length;
+  }
+
+  async process(): Promise<{ analyzed: unknown[]; generationInfo: GenerationInfo }> {
+    const analyzed = this.guidelineMatches.map((m) => ({
+      guideline: m.guideline,
+      is_previously_applied: m.score >= 10,
+    }));
+    return { analyzed, generationInfo: this.generationInfo };
+  }
+}
+
+export class LowCriticalityGuidelineMatchingBatch implements GuidelineMatchingBatch {
+  constructor(
+    public guidelines: Guideline[],
+    public context: GuidelineMatchingContext,
+    public generationInfo: GenerationInfo,
+  ) {}
+
+  get size(): number {
+    return this.guidelines.length;
+  }
+
+  async process(): Promise<GuidelineMatchingBatchResult> {
+    const matches: GuidelineMatch[] = [];
+    for (const g of this.guidelines) {
+      if (g.criticality !== 'low') continue;
+      matches.push({
+        guideline: g,
+        score: g.content.action ? 10 : 1,
+        rationale: `Low-criticality batch: "${g.content.condition}"`,
+        metadata: { batch_type: BatchType.LowCriticality },
+      });
+    }
+    return { matches, generationInfo: this.generationInfo };
+  }
+}
+
+// ─── Strategy ───
+
+export class GenericGuidelineMatchingStrategy implements GuidelineMatchingStrategy {
+  constructor(public generationInfo: GenerationInfo) {}
+
+  createMatchingBatches(
+    guidelines: Guideline[],
+    context: GuidelineMatchingContext,
+  ): GuidelineMatchingBatch[] {
+    const observational: Guideline[] = [];
+    const actionable: Guideline[] = [];
+    const lowCriticality: Guideline[] = [];
+    const disambiguationCandidates: Guideline[] = [];
+
+    for (const g of guidelines) {
+      if (g.criticality === 'low') {
+        lowCriticality.push(g);
+      } else if (!g.content.action) {
+        disambiguationCandidates.push(g);
+      } else if (g.content.action) {
+        actionable.push(g);
+      } else {
+        observational.push(g);
+      }
+    }
+
+    const batches: GuidelineMatchingBatch[] = [];
+
+    if (observational.length > 0) {
+      batches.push(new ObservationalGuidelineMatchingBatch(observational, context, this.generationInfo));
+    }
+
+    if (actionable.length > 0) {
+      batches.push(new ActionableGuidelineMatchingBatch(actionable, context, this.generationInfo));
+    }
+
+    if (lowCriticality.length > 0) {
+      batches.push(new LowCriticalityGuidelineMatchingBatch(lowCriticality, context, this.generationInfo));
+    }
+
+    return batches;
+  }
+
+  transformMatches(matches: GuidelineMatch[]): GuidelineMatch[] {
+    const seen = new Set<string>();
+    return matches.filter((m) => {
+      const key = m.guideline.id;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+  }
+}
+
+// ─── Utilities ───
+
+export async function matchWithRetry<T>(
+  fn: () => Promise<T>,
+  maxAttempts = 3,
+  _baseTemperature = 0.7,
+): Promise<T> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+      if (attempt < maxAttempts - 1) {
+        // will retry
+      }
+    }
+  }
+  throw lastError;
+}
+
+export async function executeBatchesParallel(
+  batches: GuidelineMatchingBatch[],
+  _generationInfo: GenerationInfo,
+): Promise<GuidelineMatchingResult> {
+  const start = Date.now();
+  const results = await Promise.all(
+    batches.map((batch) => matchWithRetry(() => batch.process())),
+  );
+
+  const allBatches = results.map((r) => r.matches);
+  const allMatches = allBatches.flat();
+  const allGenInfos = results.map((r) => r.generationInfo);
+
+  return {
+    totalDuration: Date.now() - start,
+    batchCount: batches.length,
+    batchGenerations: allGenInfos,
+    batches: allBatches,
+    matches: allMatches,
+  };
+}
+
+export function createScoredMatch(
+  guidelineId: string,
+  score: number,
+  rationale: string,
+): ScoredMatch {
+  return { guideline_id: guidelineId, score, rationale };
+}

apps/coder/src/services/behavioral/resolver.ts

@@ -0,0 +1,355 @@
+/**
+ * Relational resolver for behavioral guidelines.
+ *
+ * Port of boocontext-audit/src/resolver.ts — resolves DEPENDS_ON,
+ * PRIORITIZES, ENTAILS, TAG_ALL, TAG_PRIORITIZES relationships
+ * with an iterative convergence loop.
+ */
+
+// ─── Relationship types (self-contained) ───
+
+export enum RelationshipKind {
+  DEPENDS_ON = 'depends_on',
+  PRIORITIZES = 'prioritizes',
+  ENTAILS = 'entails',
+  TAG_ALL = 'tag_all',
+  TAG_PRIORITIZES = 'tag_prioritizes',
+}
+
+export enum RelationshipEntityKind {
+  GUIDELINE = 'guideline',
+  TAG = 'tag',
+}
+
+export interface RelationshipEntity {
+  id: string;
+  kind: RelationshipEntityKind;
+}
+
+export interface Relationship {
+  id: string;
+  creation_utc: string;
+  source: RelationshipEntity;
+  target: RelationshipEntity;
+  kind: RelationshipKind;
+  group_id?: string;
+}
+
+/**
+ * Minimal relationship store interface.
+ * The resolver only needs listRelationships. Implementations
+ * can back against files, postgres, or in-memory maps.
+ */
+export interface RelationshipStore {
+  listRelationships(
+    kind?: RelationshipKind,
+    sourceId?: string,
+    targetId?: string,
+  ): Promise<Relationship[]>;
+}
+
+// ─── Resolution types ───
+
+export type ResolvedEntityType = 'guideline' | 'journey' | 'tag';
+
+export interface ResolvedEntity {
+  entityType: ResolvedEntityType;
+  entityId: string;
+}
+
+export enum ResolutionKind {
+  NONE = 'none',
+  UNMET_DEPENDENCY = 'unmet_dependency',
+  DEPRIORITIZED = 'deprioritized',
+  ENTAILED = 'entailed',
+}
+
+export interface Resolution {
+  kind: ResolutionKind;
+  description: string;
+  relationshipId?: string;
+  counterparts?: ResolvedEntity[];
+}
+
+export interface GuidelineStub {
+  id: string;
+  priority: number;
+  tags: string[];
+}
+
+export interface GuidelineMatchStub {
+  guideline: GuidelineStub;
+}
+
+export interface ResolverResult {
+  matchedIds: Set<string>;
+  resolutions: Map<string, Resolution[]>;
+  converged: boolean;
+  iterations: number;
+}
+
+// ─── Constants ───
+
+export const MAX_ITERATIONS = 100;
+
+// ─── RelationalResolver ───
+
+export class RelationalResolver {
+  private store: RelationshipStore;
+
+  constructor(store: RelationshipStore) {
+    this.store = store;
+  }
+
+  async resolve(
+    matchedIds: Set<string>,
+    allGuidelines: GuidelineStub[],
+  ): Promise<ResolverResult> {
+    const resolutions = new Map<string, Resolution[]>();
+    const guidelinesById = new Map(allGuidelines.map((g) => [g.id, g]));
+    let currentIds = new Set(matchedIds);
+    const priorityRemoved = new Set<string>();
+    const entailedIds = new Set<string>();
+
+    let converged = false;
+    let iterations = 0;
+
+    for (iterations = 0; iterations < MAX_ITERATIONS; iterations++) {
+      const candidateIds = new Set(
+        [...currentIds].filter((id) => !priorityRemoved.has(id)),
+      );
+
+      const step1Ids = await this.applyDependencies(candidateIds, guidelinesById, resolutions);
+
+      const step2Ids = await this.applyPrioritization(
+        step1Ids,
+        guidelinesById,
+        resolutions,
+        priorityRemoved,
+      );
+
+      const step3Ids = this.applyNumericalPriority(
+        step2Ids,
+        guidelinesById,
+        resolutions,
+        priorityRemoved,
+        entailedIds,
+      );
+
+      const step4Ids = await this.applyEntailment(
+        step3Ids,
+        guidelinesById,
+        resolutions,
+        priorityRemoved,
+        entailedIds,
+      );
+
+      if (this.setsEqual(step4Ids, currentIds)) {
+        converged = true;
+        break;
+      }
+
+      currentIds = step4Ids;
+    }
+
+    for (const id of allGuidelines.map((g) => g.id)) {
+      if (!resolutions.has(id)) {
+        resolutions.set(id, [
+          { kind: ResolutionKind.NONE, description: 'No relational changes' },
+        ]);
+      }
+    }
+
+    return {
+      matchedIds: currentIds,
+      resolutions,
+      converged,
+      iterations: iterations + 1,
+    };
+  }
+
+  // ── Private steps ──
+
+  private async applyDependencies(
+    candidateIds: Set<string>,
+    _guidelinesById: Map<string, GuidelineStub>,
+    resolutions: Map<string, Resolution[]>,
+  ): Promise<Set<string>> {
+    const surviving = new Set(candidateIds);
+    const cache = new Map<string, Relationship[]>();
+
+    for (const gid of candidateIds) {
+      const rels = await this.getRelationshipsFromCache(cache, gid, RelationshipKind.DEPENDS_ON);
+
+      for (const rel of rels) {
+        const targetId = rel.target.id;
+        if (!candidateIds.has(targetId)) {
+          surviving.delete(gid);
+          this.addResolution(resolutions, gid, {
+            kind: ResolutionKind.UNMET_DEPENDENCY,
+            description: `Depends on ${targetId} which is not matched`,
+            relationshipId: rel.id,
+            counterparts: [{ entityType: 'guideline' as const, entityId: targetId }],
+          });
+          break;
+        }
+      }
+    }
+
+    return surviving;
+  }
+
+  private async applyPrioritization(
+    candidateIds: Set<string>,
+    guidelinesById: Map<string, GuidelineStub>,
+    resolutions: Map<string, Resolution[]>,
+    priorityRemoved: Set<string>,
+  ): Promise<Set<string>> {
+    const surviving = new Set(candidateIds);
+    const cache = new Map<string, Relationship[]>();
+
+    for (const gid of candidateIds) {
+      if (priorityRemoved.has(gid)) continue;
+
+      const allRels = await this.getAllRelationships(cache, gid);
+      const priorityRels = allRels.filter((r) => r.kind === RelationshipKind.PRIORITIZES);
+
+      for (const rel of priorityRels) {
+        const sourceId = rel.source.id;
+        if (sourceId !== gid) continue;
+        const targetId = rel.target.id;
+
+        if (candidateIds.has(targetId)) {
+          surviving.delete(targetId);
+          priorityRemoved.add(targetId);
+          this.addResolution(resolutions, targetId, {
+            kind: ResolutionKind.DEPRIORITIZED,
+            description: `Deprioritized by ${gid}`,
+            relationshipId: rel.id,
+            counterparts: [{ entityType: 'guideline' as const, entityId: gid }],
+          });
+        }
+      }
+    }
+
+    return surviving;
+  }
+
+  private applyNumericalPriority(
+    candidateIds: Set<string>,
+    guidelinesById: Map<string, GuidelineStub>,
+    resolutions: Map<string, Resolution[]>,
+    priorityRemoved: Set<string>,
+    entailedIds: Set<string>,
+  ): Set<string> {
+    if (candidateIds.size === 0) return candidateIds;
+
+    const nonEntailed = [...candidateIds].filter((id) => !entailedIds.has(id));
+    const entailed = [...candidateIds].filter((id) => entailedIds.has(id));
+
+    if (nonEntailed.length === 0) return new Set(entailed);
+
+    const priorities = nonEntailed.map((id) => guidelinesById.get(id)?.priority ?? 0);
+    const maxPriority = Math.max(...priorities);
+
+    const surviving = new Set<string>();
+
+    for (const id of nonEntailed) {
+      const priority = guidelinesById.get(id)?.priority ?? 0;
+      if (priority >= maxPriority) {
+        surviving.add(id);
+      } else {
+        priorityRemoved.add(id);
+        this.addResolution(resolutions, id, {
+          kind: ResolutionKind.DEPRIORITIZED,
+          description: `Lower priority (${priority} < ${maxPriority})`,
+        });
+      }
+    }
+
+    for (const id of entailed) {
+      surviving.add(id);
+    }
+
+    return surviving;
+  }
+
+  private async applyEntailment(
+    candidateIds: Set<string>,
+    guidelinesById: Map<string, GuidelineStub>,
+    resolutions: Map<string, Resolution[]>,
+    priorityRemoved: Set<string>,
+    entailedIds: Set<string>,
+  ): Promise<Set<string>> {
+    const result = new Set(candidateIds);
+    const cache = new Map<string, Relationship[]>();
+
+    for (const gid of candidateIds) {
+      if (priorityRemoved.has(gid)) continue;
+
+      const allRels = await this.getAllRelationships(cache, gid);
+      const entailRels = allRels.filter((r) => r.kind === RelationshipKind.ENTAILS);
+
+      for (const rel of entailRels) {
+        const targetId = rel.target.id;
+        if (!guidelinesById.has(targetId)) continue;
+        if (priorityRemoved.has(targetId)) continue;
+        if (entailedIds.has(targetId)) continue;
+
+        result.add(targetId);
+        entailedIds.add(targetId);
+        this.addResolution(resolutions, targetId, {
+          kind: ResolutionKind.ENTAILED,
+          description: `Entailed by ${gid}`,
+          relationshipId: rel.id,
+          counterparts: [{ entityType: 'guideline' as const, entityId: gid }],
+        });
+      }
+    }
+
+    return result;
+  }
+
+  // ── Cache helpers ──
+
+  private async getRelationshipsFromCache(
+    cache: Map<string, Relationship[]>,
+    gid: string,
+    kind: RelationshipKind,
+  ): Promise<Relationship[]> {
+    const key = `${kind}:${gid}`;
+    if (!cache.has(key)) {
+      cache.set(key, await this.store.listRelationships(kind, gid));
+    }
+    return cache.get(key)!;
+  }
+
+  private async getAllRelationships(
+    cache: Map<string, Relationship[]>,
+    gid: string,
+  ): Promise<Relationship[]> {
+    const result: Relationship[] = [];
+    const kinds = Object.values(RelationshipKind) as RelationshipKind[];
+    for (const kind of kinds) {
+      const rels = await this.getRelationshipsFromCache(cache, gid, kind);
+      const targetRels = await this.getRelationshipsFromCache(cache, `target:${gid}`, kind);
+      result.push(...rels, ...targetRels);
+    }
+    return result;
+  }
+
+  private addResolution(
+    resolutions: Map<string, Resolution[]>,
+    id: string,
+    resolution: Resolution,
+  ): void {
+    if (!resolutions.has(id)) resolutions.set(id, []);
+    resolutions.get(id)!.push(resolution);
+  }
+
+  private setsEqual(a: Set<string>, b: Set<string>): boolean {
+    if (a.size !== b.size) return false;
+    for (const item of a) if (!b.has(item)) return false;
+    return true;
+  }
+}

apps/coder/src/services/collision-detector.ts

@@ -0,0 +1,115 @@
+// v2.8 Collision detection — pure functions that find file overlaps between
+// worktrees/agents editing the same files concurrently. Advisory only; writes
+// are never blocked, but the collision info surfaces in the UI and logs.
+//
+// Severity levels:
+//   same_line     — the same file, exact same line region
+//   adjacent_line — the same file, lines touch or are within 5 lines
+//   different_area — the same file, distant lines
+//
+// Pure functions, no side effects. Testable in isolation.
+
+export type ConflictSeverity = 'same_line' | 'adjacent_line' | 'different_area';
+
+export interface ConflictVerdict {
+  filePath: string;
+  worktrees: string[];
+  severity: ConflictSeverity;
+  agents: string[];
+}
+
+/**
+ * Registry entry for a single file change recorded by a worktree.
+ * Stored in the ConflictIndex Map value for each file path.
+ */
+export interface ConflictEntry {
+  worktreeId: string;
+  agent: string;
+  /**
+   * Approximate line range touched by the change. undefined when the change
+   * creates or deletes the file (full-file collision vs. same-line).
+   */
+  lineRange?: { start: number; end: number };
+  status: 'pending' | 'applied' | 'reverted';
+  timestamp: number;
+}
+
+/**
+ * Shape of the conflict index consumed by findConflicts.
+ * File path → set of entries from different worktrees/agents.
+ */
+export type ConflictIndexData = ReadonlyMap<string, ReadonlySet<ConflictEntry>>;
+
+/**
+ * Find file overlaps between `changedFiles` and the conflict index, excluding
+ * the caller's own worktree.
+ *
+ * Returns one ConflictVerdict per file that has entries from other worktrees.
+ * Severity is the highest found (same_line > adjacent_line > different_area).
+ */
+export function findConflicts(
+  changedFiles: string[],
+  worktreeId: string,
+  /** Approximate line range for the proposed changes, keyed by file path */
+  changedRanges: Map<string, { start: number; end: number }>,
+  conflictIndex: ConflictIndexData,
+): ConflictVerdict[] {
+  const verdicts: ConflictVerdict[] = [];
+
+  for (const filePath of changedFiles) {
+    const entries = conflictIndex.get(filePath);
+    if (!entries || entries.size === 0) continue;
+
+    // Filter to entries from OTHER worktrees
+    const otherEntries = [...entries].filter((e) => e.worktreeId !== worktreeId);
+    if (otherEntries.length === 0) continue;
+
+    const myRange = changedRanges.get(filePath);
+    let severity: ConflictSeverity = 'different_area';
+
+    for (const entry of otherEntries) {
+      if (!myRange || !entry.lineRange) {
+        // Full-file changes (create/delete) always hit at least different_area
+        continue;
+      }
+      const sev = lineOverlapSeverity(myRange, entry.lineRange);
+      if (sev === 'same_line') {
+        severity = 'same_line';
+        break; // Can't get higher than this
+      }
+      if (sev === 'adjacent_line' && severity === 'different_area') {
+        severity = 'adjacent_line';
+      }
+    }
+
+    const worktrees = [...new Set(otherEntries.map((e) => e.worktreeId))];
+    const agents = [...new Set(otherEntries.map((e) => e.agent))];
+
+    verdicts.push({ filePath, worktrees, severity, agents });
+  }
+
+  return verdicts;
+}
+
+const ADJACENT_LINE_THRESHOLD = 5;
+
+/**
+ * Determine severity of overlap between two line ranges.
+ */
+function lineOverlapSeverity(
+  a: { start: number; end: number },
+  b: { start: number; end: number },
+): ConflictSeverity {
+  // Same_line: ranges intersect
+  if (a.start <= b.end && b.start <= a.end) {
+    return 'same_line';
+  }
+
+  // Adjacent: ranges are within ADJACENT_LINE_THRESHOLD lines of each other
+  const gap = a.start > b.end ? a.start - b.end : b.start - a.end;
+  if (gap <= ADJACENT_LINE_THRESHOLD) {
+    return 'adjacent_line';
+  }
+
+  return 'different_area';
+}

apps/coder/src/services/conflict-index.ts

@@ -0,0 +1,151 @@
+// v2.8 In-memory conflict index — tracks which worktrees/agents are editing
+// which files so the collision detector can find overlaps.
+//
+// Singleton exported as `conflictIndex`; imported by pending_changes.ts to
+// register changes at queue time and unregister on worktree teardown.
+//
+// NOT persisted — survives only as long as the BooCoder process. Postgres
+// is the durable record (pending_changes table); this is the hot in-memory
+// probe for concurrent edit warnings.
+
+import type { ConflictEntry, ConflictVerdict } from './collision-detector.js';
+import { findConflicts } from './collision-detector.js';
+
+export class ConflictIndex {
+  /**
+   * filePath → Set of ConflictEntry from various worktrees.
+   * A single worktree may have multiple entries for the same file
+   * (several pending edits to the same file in one session).
+   */
+  #map = new Map<string, Set<ConflictEntry>>();
+
+  // ---- mutation -------------------------------------------------------
+
+  /**
+   * Register that `worktreeId` (agent) is touching `filePath`.
+   * Creates an entry in the index so subsequent callers see it as a conflict.
+   */
+  registerChange(
+    filePath: string,
+    worktreeId: string,
+    agent: string,
+    lineRange?: { start: number; end: number },
+  ): void {
+    let entries = this.#map.get(filePath);
+    if (!entries) {
+      entries = new Set();
+      this.#map.set(filePath, entries);
+    }
+    entries.add({
+      worktreeId,
+      agent,
+      lineRange,
+      status: 'pending' as const,
+      timestamp: Date.now(),
+    });
+  }
+
+  /**
+   * Remove all entries for a given worktree. Called on worktree teardown
+   * so stale entries don't trigger false warnings.
+   */
+  removeWorktree(worktreeId: string): void {
+    for (const [filePath, entries] of this.#map) {
+      const before = entries.size;
+      for (const entry of entries) {
+        if (entry.worktreeId === worktreeId) {
+          entries.delete(entry);
+        }
+      }
+      if (entries.size === 0) {
+        this.#map.delete(filePath);
+      }
+    }
+  }
+
+  /**
+   * Remove entries older than `maxAgeMs`. Useful as a periodic cleanup
+   * when worktree teardown was missed (crash, unclean exit).
+   */
+  sweepStale(maxAgeMs: number): number {
+    const cutoff = Date.now() - maxAgeMs;
+    let removed = 0;
+
+    for (const [filePath, entries] of this.#map) {
+      for (const entry of entries) {
+        if (entry.timestamp < cutoff) {
+          entries.delete(entry);
+          removed++;
+        }
+      }
+      if (entries.size === 0) {
+        this.#map.delete(filePath);
+      }
+    }
+
+    return removed;
+  }
+
+  // ---- query ----------------------------------------------------------
+
+  /**
+   * Query the raw ConflictEntry set for a file path. Returns empty set
+   * when there are no entries (never mutated the file).
+   */
+  getEntriesFor(filePath: string): ReadonlySet<ConflictEntry> {
+    return this.#map.get(filePath) ?? new Set();
+  }
+
+  /**
+   * Get all conflict verdicts for a given file path — which other
+   * worktrees are touching it. Returns empty when only one worktree
+   * has entries (no actual conflict).
+   */
+  getConflictsFor(filePath: string): ConflictVerdict[] {
+    const entries = this.#map.get(filePath);
+    if (!entries || entries.size === 0) return [];
+
+    // Determine distinct worktree IDs. If only one, no conflict.
+    const worktreeIds = new Set<string>();
+    for (const e of entries) worktreeIds.add(e.worktreeId);
+    if (worktreeIds.size <= 1) return [];
+
+    // Use the first worktree as the "caller" so findConflicts excludes
+    // its entries and returns only entries from OTHER worktrees.
+    const caller = [...worktreeIds][0]!;
+    return findConflicts(
+      [filePath],
+      caller,
+      new Map(),
+      this.#toIndexData(),
+    );
+  }
+
+  /**
+   * Get conflicts for a set of file changes from a specific worktree.
+   * Delegates to the pure findConflicts function.
+   */
+  query(
+    changedFiles: string[],
+    worktreeId: string,
+    changedRanges: Map<string, { start: number; end: number }>,
+  ): ConflictVerdict[] {
+    return findConflicts(changedFiles, worktreeId, changedRanges, this.#toIndexData());
+  }
+
+  /**
+   * Snapshot the current map for testing/inspection.
+   */
+  snapshot(): Map<string, ReadonlySet<ConflictEntry>> {
+    return new Map(this.#map);
+  }
+
+  // ---- private --------------------------------------------------------
+
+  #toIndexData(): ReadonlyMap<string, ReadonlySet<ConflictEntry>> {
+    return this.#map as ReadonlyMap<string, ReadonlySet<ConflictEntry>>;
+  }
+}
+
+// Singleton — the whole BooCoder process shares one conflict index.
+export const conflictIndex = new ConflictIndex();

apps/coder/src/services/correction-service.ts

@@ -0,0 +1,186 @@
+import { readFile, writeFile, appendFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export interface UserCorrectionRecord {
+  id: string;
+  record_type: 'conversation';
+  action_type: 'user_correction';
+  priority: 'critical_for_recovery';
+  timestamp: string;
+  original_claim: string;
+  correction: string;
+  principle_extracted: string;
+  persisted_to: string[];
+}
+
+const CORRECTIONS_REL = '.boo/corrections/index.json';
+
+function correctionsDir(basePath?: string): string {
+  return resolve(basePath ?? process.cwd(), '.boo/corrections');
+}
+
+function correctionsPath(basePath?: string): string {
+  return resolve(basePath ?? process.cwd(), CORRECTIONS_REL);
+}
+
+function tryParseJson<T>(raw: string): T | null {
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return null;
+  }
+}
+
+export interface CorrectionsIndex {
+  corrections: UserCorrectionRecord[];
+}
+
+async function readCorrections(basePath?: string): Promise<CorrectionsIndex> {
+  try {
+    const raw = await readFile(correctionsPath(basePath), 'utf-8');
+    return tryParseJson<CorrectionsIndex>(raw) ?? { corrections: [] };
+  } catch {
+    return { corrections: [] };
+  }
+}
+
+async function writeCorrections(idx: CorrectionsIndex, basePath?: string): Promise<void> {
+  const dir = correctionsDir(basePath);
+  if (!existsSync(dir)) {
+    const { mkdir } = await import('node:fs/promises');
+    await mkdir(dir, { recursive: true });
+  }
+  await writeFile(correctionsPath(basePath), JSON.stringify(idx, null, 2), 'utf-8');
+}
+
+let idCounter = 0;
+
+function nextId(): string {
+  idCounter++;
+  return `uc_${Date.now()}_${idCounter}`;
+}
+
+function isoNow(): string {
+  return new Date().toISOString();
+}
+
+/**
+ * Record a user correction. Stores it in .boo/corrections/index.json
+ * and returns the record with the assigned id.
+ */
+export async function recordCorrection(
+  originalClaim: string,
+  correction: string,
+  principleExtracted: string,
+  persistedTo: string[] = [],
+  basePath?: string,
+): Promise<UserCorrectionRecord> {
+  const idx = await readCorrections(basePath);
+  const record: UserCorrectionRecord = {
+    id: nextId(),
+    record_type: 'conversation',
+    action_type: 'user_correction',
+    priority: 'critical_for_recovery',
+    timestamp: isoNow(),
+    original_claim: originalClaim,
+    correction,
+    principle_extracted: principleExtracted,
+    persisted_to: persistedTo,
+  };
+  idx.corrections.push(record);
+  await writeCorrections(idx, basePath);
+  return record;
+}
+
+/**
+ * Scan an audit_trail.jsonl file for user_correction records.
+ * Returns all matching records found in the file.
+ */
+export async function scanForCorrections(
+  auditPath: string,
+): Promise<UserCorrectionRecord[]> {
+  try {
+    const raw = await readFile(auditPath, 'utf-8');
+    const lines = raw.split('\n').filter(Boolean);
+    const corrections: UserCorrectionRecord[] = [];
+    for (const line of lines) {
+      const record = tryParseJson<Record<string, unknown>>(line);
+      if (record?.action_type === 'user_correction') {
+        corrections.push(record as unknown as UserCorrectionRecord);
+      }
+    }
+    return corrections;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Check if a proposed action contradicts any known user correction.
+ * Returns an array of contradiction warnings — empty means no contradictions.
+ */
+export function checkContradiction(
+  action: string,
+  corrections: UserCorrectionRecord[],
+): { contradicts: boolean; warnings: { correction: UserCorrectionRecord; reason: string }[] } {
+  const warnings: { correction: UserCorrectionRecord; reason: string }[] = [];
+
+  for (const c of corrections) {
+    // Check if the action mentions the original claim's topic
+    const actionLower = action.toLowerCase();
+    const claimFragments = c.original_claim.toLowerCase().split(/\s+/).filter((w) => w.length > 4);
+
+    // If any significant word from the original claim appears in the proposed action,
+    // flag this as a potential contradiction
+    const matchingFragments = claimFragments.filter((f) => actionLower.includes(f));
+    if (matchingFragments.length >= 2) {
+      warnings.push({
+        correction: c,
+        reason: `Action "${action.slice(0, 60)}" may contradict prior correction: "${c.original_claim}" → "${c.correction}" (principle: ${c.principle_extracted})`,
+      });
+    }
+  }
+
+  return {
+    contradicts: warnings.length > 0,
+    warnings,
+  };
+}
+
+/**
+ * Add a file path to a correction's persisted_to array.
+ */
+export async function markPersisted(
+  correctionId: string,
+  filePath: string,
+  basePath?: string,
+): Promise<UserCorrectionRecord | null> {
+  const idx = await readCorrections(basePath);
+  const record = idx.corrections.find((c) => c.id === correctionId);
+  if (!record) return null;
+
+  if (!record.persisted_to.includes(filePath)) {
+    record.persisted_to.push(filePath);
+  }
+  await writeCorrections(idx, basePath);
+  return record;
+}
+
+/**
+ * Get all stored user corrections.
+ */
+export async function listCorrections(basePath?: string): Promise<UserCorrectionRecord[]> {
+  const idx = await readCorrections(basePath);
+  return idx.corrections;
+}
+
+/**
+ * Append a correction record to an audit_trail.jsonl file (inline storage).
+ */
+export async function appendCorrectionToTrail(
+  trailPath: string,
+  correction: UserCorrectionRecord,
+): Promise<void> {
+  await appendFile(trailPath, JSON.stringify(correction) + '\n', 'utf-8');
+}

apps/coder/src/services/dispatcher.ts

@@ -30,6 +30,7 @@ import {
   type TerminalMessageStatus,
 } from './finalize-message.js';
 import { shouldFailOnMissingAgent } from './flow-runner-decisions.js';
+import { emitHook } from '../plugins/host.js';
 
 interface InferenceRunner {
   enqueue: (
@@ -123,6 +124,22 @@ export function createDispatcher(deps: Deps): {
     publishAgentStatus(broker.publishFrame, sessionId, chatId, agent, status, reason);
   }
 
+  // EmitHook: fire-and-forget turn.end notification. Best-effort — a hook throwing
+  // is silently swallowed so it never blocks the dispatch flow.
+  function emitTurnEnd(
+    sessionId: string,
+    taskId: string,
+    state: string,
+    agent?: string | null,
+    model?: string | null,
+    outputSummary?: string,
+  ): void {
+    void emitHook('turn.end', {
+      sessionId,
+      turnSummary: { taskId, state, agent, model: model ?? undefined, outputSummary },
+    });
+  }
+
   // F1 (OCE-001/OCE-002): finalize a streaming assistant message into a terminal
   // state and publish the matching message_complete frame. Best-effort + idempotent
   // (the helper's `WHERE status='streaming'` guard) — a failure here must never mask
@@ -318,6 +335,7 @@ export function createDispatcher(deps: Deps): {
 
     // Declared before try so the catch block can write it back on the task row.
     let chatId: string | null = null;
+    let sessionId: string | undefined;
 
     try {
       // Mark running
@@ -330,7 +348,6 @@ export function createDispatcher(deps: Deps): {
       // Session setup: reuse a pre-created session (e.g. Q&A arena contestants
       // whose persona is stamped on the session via agent_id) or create a fresh one.
       const model = task.model ?? config.DEFAULT_MODEL;
-      let sessionId: string;
       if (task.session_id) {
         sessionId = task.session_id;
       } else {
@@ -377,6 +394,7 @@ export function createDispatcher(deps: Deps): {
           SET state = 'cancelled', ended_at = clock_timestamp()
           WHERE id = ${taskId}
         `;
+        if (sessionId) emitTurnEnd(sessionId, taskId, 'cancelled', null, task.model);
         return;
       }
 
@@ -399,6 +417,7 @@ export function createDispatcher(deps: Deps): {
           WHERE id = ${taskId}
         `;
         log.info({ taskId, costTokens }, 'dispatcher: task completed (native)');
+        emitTurnEnd(sessionId, taskId, 'completed', null, task.model, summary);
       } else {
         const [msg] = await sql<{ content: string | null }[]>`
           SELECT content FROM messages WHERE id = ${assistantId}
@@ -410,6 +429,7 @@ export function createDispatcher(deps: Deps): {
           WHERE id = ${taskId}
         `;
         log.warn({ taskId, finalStatus }, 'dispatcher: task failed (native)');
+        emitTurnEnd(sessionId, taskId, 'failed', null, task.model, summary);
       }
     } catch (err) {
       const errMsg = err instanceof Error ? err.message : String(err);
@@ -419,6 +439,7 @@ export function createDispatcher(deps: Deps): {
         SET state = 'failed', ended_at = clock_timestamp(), output_summary = ${errMsg.slice(0, 500)}, chat_id = ${chatId}
         WHERE id = ${taskId}
       `.catch(() => {});
+      if (sessionId) emitTurnEnd(sessionId, taskId, 'failed', null, task.model, errMsg);
     }
   }
 
@@ -684,6 +705,7 @@ export function createDispatcher(deps: Deps): {
         await finalizeMessage(sessionId, chatId, assistantId, 'cancelled', task.model, assistantContent);
         await sql`UPDATE tasks SET state = 'cancelled', ended_at = clock_timestamp() WHERE id = ${taskId}`;
         emitAgentStatus(sessionId, chatId, agent, 'idle', stopping ? 'shutdown' : 'cancelled');
+        emitTurnEnd(sessionId, taskId, 'cancelled', agent, task.model);
         await cleanupWorktree(projectPath, taskId);
         clearTaskCommands(taskId);
         return;
@@ -738,6 +760,7 @@ export function createDispatcher(deps: Deps): {
       log.info({ taskId, agent, costTokens: extCostTokens }, 'dispatcher: task completed (external)');
       // #10: external-agent turn completed cleanly.
       emitAgentStatus(sessionId, chatId, agent, 'idle', 'turn_complete');
+      emitTurnEnd(sessionId, taskId, 'completed', agent, task.model, outputSummary);
       clearTaskCommands(taskId);
 
     } catch (err) {
@@ -762,6 +785,7 @@ export function createDispatcher(deps: Deps): {
       // preceded its assignment — guard so the status publish never masks the real
       // error.
       if (chatId) emitAgentStatus(sessionId, chatId, agent, status === 'cancelled' ? 'idle' : 'error', status === 'cancelled' ? 'cancelled' : 'failed');
+      if (sessionId) emitTurnEnd(sessionId, taskId, status, agent, task.model, errMsg);
 
       // Best-effort cleanup
       await cleanupWorktree(projectPath, taskId);
@@ -1030,6 +1054,7 @@ export function createDispatcher(deps: Deps): {
         await finalizeMessage(sessionId, chatId, assistantId, 'cancelled', task.model, assistantContent);
         await sql`UPDATE tasks SET state = 'cancelled', ended_at = clock_timestamp() WHERE id = ${taskId}`;
         emitAgentStatus(sessionId, chatId, agent, 'idle', stopping ? 'shutdown' : 'cancelled');
+        emitTurnEnd(sessionId, taskId, 'cancelled', agent, task.model);
         clearTaskCommands(taskId);
         return; // worktree persists (no cleanup); backend stays warm
       }
@@ -1090,6 +1115,7 @@ export function createDispatcher(deps: Deps): {
         result.ok ? 'idle' : 'error',
         result.ok ? 'turn_complete' : 'failed',
       );
+      emitTurnEnd(sessionId, taskId, finalState, agent, task.model, outputSummary);
       clearTaskCommands(taskId);
     } catch (err) {
       const errMsg = err instanceof Error ? err.message : String(err);
@@ -1104,6 +1130,7 @@ export function createDispatcher(deps: Deps): {
       await finalizeMessage(sessionId, chatId, assistantId, status, task.model);
       // #10: turn crashed.
       if (chatId) emitAgentStatus(sessionId, chatId, agent, status === 'cancelled' ? 'idle' : 'error', status === 'cancelled' ? 'cancelled' : 'crashed');
+      if (sessionId) emitTurnEnd(sessionId, taskId, status, agent, task.model, errMsg);
       clearTaskCommands(taskId);
       // No worktree cleanup (persistent); backend stays warm for the next turn.
     }
@@ -1308,6 +1335,7 @@ export function createDispatcher(deps: Deps): {
         await finalizeMessage(sessionId, chatId, assistantId, 'cancelled', task.model, assistantContent);
         await sql`UPDATE tasks SET state = 'cancelled', ended_at = clock_timestamp() WHERE id = ${taskId}`;
         emitAgentStatus(sessionId, chatId, agent, 'idle', stopping ? 'shutdown' : 'cancelled');
+        emitTurnEnd(sessionId, taskId, 'cancelled', agent, task.model);
         clearTaskCommands(taskId);
         return; // worktree persists (no cleanup); backend stays warm
       }
@@ -1367,6 +1395,7 @@ export function createDispatcher(deps: Deps): {
         result.ok ? 'idle' : 'error',
         result.ok ? 'turn_complete' : 'failed',
       );
+      emitTurnEnd(sessionId, taskId, finalState, agent, task.model, outputSummary);
       clearTaskCommands(taskId);
     } catch (err) {
       const errMsg = err instanceof Error ? err.message : String(err);
@@ -1381,6 +1410,7 @@ export function createDispatcher(deps: Deps): {
       await finalizeMessage(sessionId, chatId, assistantId, status, task.model);
       // #10: turn crashed.
       emitAgentStatus(sessionId, chatId, agent, status === 'cancelled' ? 'idle' : 'error', status === 'cancelled' ? 'cancelled' : 'crashed');
+      emitTurnEnd(sessionId, taskId, status, agent, task.model, errMsg);
       clearTaskCommands(taskId);
       // No worktree cleanup (persistent); backend stays warm for the next turn.
     }
@@ -1576,6 +1606,7 @@ export function createDispatcher(deps: Deps): {
         await finalizeMessage(sessionId, chatId, assistantId, 'cancelled', task.model, assistantContent);
         await sql`UPDATE tasks SET state = 'cancelled', ended_at = clock_timestamp() WHERE id = ${taskId}`;
         emitAgentStatus(sessionId, chatId, agent, 'idle', stopping ? 'shutdown' : 'cancelled');
+        emitTurnEnd(sessionId, taskId, 'cancelled', agent, task.model);
         clearTaskCommands(taskId);
         return; // worktree persists (no cleanup); backend stays warm
       }
@@ -1638,6 +1669,7 @@ export function createDispatcher(deps: Deps): {
         result.ok ? 'idle' : 'error',
         result.ok ? 'turn_complete' : 'failed',
       );
+      emitTurnEnd(sessionId, taskId, finalState, agent, task.model, outputSummary);
       clearTaskCommands(taskId);
     } catch (err) {
       const errMsg = err instanceof Error ? err.message : String(err);
@@ -1652,6 +1684,7 @@ export function createDispatcher(deps: Deps): {
       await finalizeMessage(sessionId, chatId, assistantId, status, task.model);
       // #10: turn crashed.
       emitAgentStatus(sessionId, chatId, agent, status === 'cancelled' ? 'idle' : 'error', status === 'cancelled' ? 'cancelled' : 'crashed');
+      emitTurnEnd(sessionId, taskId, status, agent, task.model, errMsg);
       clearTaskCommands(taskId);
       // No worktree cleanup (persistent); backend stays warm for the next turn.
     }

apps/coder/src/services/flow-runner-decisions.ts

@@ -33,11 +33,13 @@ export interface SchedulerState {
   readonly inFlight: ReadonlySet<string>;
   /** step ids pre-skipped at launch (band/when gating) — never given a row */
   readonly excluded: ReadonlySet<string>;
+  /** step ids that timed out (terminal — no retries remaining or not retriable) */
+  readonly timedOut: ReadonlySet<string>;
 }
 
-/** A dependency is satisfied once it is done, skipped, or excluded. */
+/** A dependency is satisfied once it is done, skipped, excluded, or timed out. */
 function isSatisfied(state: SchedulerState, id: string): boolean {
-  return state.done.has(id) || state.skipped.has(id) || state.excluded.has(id);
+  return state.done.has(id) || state.skipped.has(id) || state.excluded.has(id) || state.timedOut.has(id);
 }
 
 /**
@@ -118,25 +120,50 @@ export function isStuck(flow: Flow, state: SchedulerState): boolean {
  * - 'mark-cancelled': task was cancelled before the callback ran; propagate so
  *                     advance() cancels the run.
  */
+/**
+ * True when the step definition allows retries on timeout.
+ * Pure — no IO.
+ */
+export function isRetriable(step: { maxRetries?: number }): boolean {
+  return (step.maxRetries ?? 0) > 0;
+}
+
+/**
+ * True when the step has retries remaining.
+ * Pure — no IO.
+ */
+export function shouldRetry(maxRetries: number | undefined | null, retryCount: number): boolean {
+  return retryCount < (maxRetries ?? 0);
+}
+
 export type ResumeAction =
   | 'keep'
   | 're-dispatch'
   | 'mark-done'
   | 'mark-failed'
-  | 'mark-cancelled';
+  | 'mark-cancelled'
+  | 'retry';
 
 /**
  * Decide what to do with ONE flow step during startup resume (D-9). Pure.
  *
- * @param status    - flow_steps.status
- * @param taskId    - flow_steps.task_id (null for code steps or unstarted agent steps)
- * @param taskState - tasks.state for taskId, or null if the task row is absent
+ * @param status     - flow_steps.status
+ * @param taskId     - flow_steps.task_id (null for code steps or unstarted agent steps)
+ * @param taskState  - tasks.state for taskId, or null if the task row is absent
+ * @param retryCount - flow_steps.retry_count (default 0)
+ * @param maxRetries - flow_steps.max_retries (null = no retry)
  */
 export function reconcileResumeStep(
   status: string,
   taskId: string | null,
   taskState: string | null,
+  retryCount?: number,
+  maxRetries?: number | null,
 ): ResumeAction {
+  if (status === 'timed_out') {
+    if (shouldRetry(maxRetries, retryCount ?? 0)) return 'retry';
+    return 'mark-failed';
+  }
   if (status !== 'running') return 'keep';
   // Running step: decide by its task's current state.
   if (!taskId || taskState === null) return 're-dispatch'; // task gone or never created
@@ -198,7 +225,7 @@ export function evaluateTriggerRule(
  * decision per step. Pure — no IO.
  */
 export function reconcileRun(
-  steps: ReadonlyArray<{ stepId: string; taskId: string | null; status: string }>,
+  steps: ReadonlyArray<{ stepId: string; taskId: string | null; status: string; retryCount?: number; maxRetries?: number | null }>,
   taskStates: ReadonlyMap<string, string>,
 ): StepResumeDecision[] {
   return steps.map((step) => ({
@@ -207,6 +234,8 @@ export function reconcileRun(
       step.status,
       step.taskId,
       step.taskId ? (taskStates.get(step.taskId) ?? null) : null,
+      step.retryCount,
+      step.maxRetries,
     ),
   }));
 }

apps/coder/src/services/flow-runner.ts

@@ -89,6 +89,8 @@ interface Deps {
   broker: Broker;
   log: FastifyBaseLogger;
   config: Config;
+  /** Fired when a flow run reaches a terminal state (for plan-store integration). */
+  onRunTerminal?: (runId: string, status: 'completed' | 'failed' | 'cancelled') => void;
 }
 
 interface FlowStepRow {
@@ -98,6 +100,9 @@ interface FlowStepRow {
   status: string;
   chat_id: string | null;
   output: string | null;
+  updated_at: string | null;
+  retry_count: number | null;
+  max_retries: number | null;
 }
 
 export function createFlowRunner(deps: Deps): FlowRunner {
@@ -261,7 +266,8 @@ export function createFlowRunner(deps: Deps): FlowRunner {
     const dispatch: DispatchFn = (agent, task) => dispatchSubAgent(run.project_id, model, agent, task);
 
     const rows = await sql<FlowStepRow[]>`
-      SELECT step_id, kind, agent, status, chat_id, output FROM flow_steps WHERE run_id = ${runId}
+      SELECT step_id, kind, agent, status, chat_id, output, updated_at, retry_count, max_retries
+      FROM flow_steps WHERE run_id = ${runId}
     `;
 
     // Re-derive the excluded set (band/when pre-skips) from the flow def + input —
@@ -273,6 +279,7 @@ export function createFlowRunner(deps: Deps): FlowRunner {
     const done = new Set<string>();
     const skipped = new Set<string>();
     const inFlight = new Set<string>();
+    const timedOut = new Set<string>();
     const results: Record<string, string> = {};
     for (const r of rows) {
       switch (r.status) {
@@ -286,6 +293,9 @@ export function createFlowRunner(deps: Deps): FlowRunner {
         case 'running':
           inFlight.add(r.step_id);
           break;
+        case 'timed_out':
+          timedOut.add(r.step_id);
+          break;
         case 'failed':
           // A failed worker makes the deterministic report untrustworthy — fail the
           // whole run (matches the Phase-1 CLI, which throws on a dispatch failure).
@@ -298,10 +308,68 @@ export function createFlowRunner(deps: Deps): FlowRunner {
       }
     }
 
+    // ─── Timeout detection ───────────────────────────────────────────────────────
+    // Check running steps. If a step has been 'running' longer than
+    // FLOW_STEP_TIMEOUT_MS, mark it timed_out or re-dispatch if retriable.
+    const timeoutMs = config.FLOW_STEP_TIMEOUT_MS;
+    const nowDate = new Date();
+    let detectedTimedOut = false;
+    for (const r of rows) {
+      if (r.status !== 'running') continue;
+      if (!r.updated_at) continue;
+      const elapsed = nowDate.getTime() - new Date(r.updated_at).getTime();
+      if (elapsed <= timeoutMs) continue;
+
+      // Step has exceeded the timeout
+      detectedTimedOut = true;
+      const retryCount = r.retry_count ?? 0;
+      const maxRetries = r.max_retries ?? 0;
+
+      if (maxRetries > 0 && retryCount < maxRetries) {
+        // Retriable: re-dispatch the step with an incremented retry_count
+        const step = flow.steps.find((s) => s.id === r.step_id);
+        if (!step || step.kind !== 'agent') {
+          // Non-agent steps can't be retried via dispatch
+          inFlight.delete(r.step_id);
+          await failRun(runId, flow, input, model,
+            `step '${r.step_id}' timed out (non-retriable kind)`, r.step_id);
+          return;
+        }
+        inFlight.delete(r.step_id);
+        await sql`
+          UPDATE flow_steps
+          SET retry_count = ${retryCount + 1}, updated_at = clock_timestamp()
+          WHERE run_id = ${runId} AND step_id = ${r.step_id} AND status = 'running'
+        `;
+        await dispatchAgentStep(runId, run.project_id, model, step, ctx);
+        inFlight.add(r.step_id);
+        log.warn({ runId, stepId: r.step_id, retry: retryCount + 1, maxRetries },
+          'flow-runner: step timed out, retrying');
+      } else {
+        // Not retriable — mark as timed_out, fail the run
+        inFlight.delete(r.step_id);
+        await sql`
+          UPDATE flow_steps SET status = 'timed_out', updated_at = clock_timestamp()
+          WHERE run_id = ${runId} AND step_id = ${r.step_id} AND status = 'running'
+        `;
+        timedOut.add(r.step_id);
+        publishStep(runId, r.step_id, 'timed_out');
+        await failRun(runId, flow, input, model,
+          `step '${r.step_id}' timed out`, r.step_id);
+        return;
+      }
+    }
+
+    // If we modified any steps, re-query so the state sets reflect the latest DB.
+    if (detectedTimedOut) {
+      // Continue with the in-memory state we already adjusted above (inFlight/timedOut
+      // were mutated directly). No re-query needed.
+    }
+
     // Drain ready skips + code steps (synchronous), re-evaluating after each batch,
     // then dispatch the full ready agent wave and wait for their terminal callbacks.
     for (;;) {
-      const state: SchedulerState = { done, skipped, inFlight, excluded };
+      const state: SchedulerState = { done, skipped, inFlight, excluded, timedOut };
 
       if (isRunComplete(flow, state)) {
         await finishRun(runId, flow, input, results, model, dispatch);
@@ -479,6 +547,7 @@ export function createFlowRunner(deps: Deps): FlowRunner {
       WHERE id = ${runId} AND status = 'running'
     `;
     if (updated.count === 0) return; // already terminal (e.g. cancelled) — don't publish
+    deps.onRunTerminal?.(runId, 'completed');
     publishStep(runId, lastAgentStepId(flow, input, model), 'completed', {
       run_status: 'completed',
       report,
@@ -498,6 +567,7 @@ export function createFlowRunner(deps: Deps): FlowRunner {
       WHERE id = ${runId} AND status = 'running'
     `;
     if (updated.count === 0) return;
+    deps.onRunTerminal?.(runId, 'failed');
     const stepId = failedStepId ?? (flow ? lastAgentStepId(flow, input, model) : 'run');
     log.warn({ runId, error }, 'flow-runner: run failed');
     await appendStepEvent(sql, runId, stepId, 'failed', { error });
@@ -512,6 +582,7 @@ export function createFlowRunner(deps: Deps): FlowRunner {
       WHERE id = ${runId} AND status = 'running'
     `;
     if (updated.count === 0) return; // idempotent — already terminal
+    deps.onRunTerminal?.(runId, 'cancelled');
     // Any remaining pending steps are unreachable; mark + publish them so the
     // pane can show them as cancelled rather than stuck in pending.
     const pending = await sql<{ step_id: string; kind: string }[]>`
@@ -540,7 +611,7 @@ export function createFlowRunner(deps: Deps): FlowRunner {
   function publishStep(
     runId: string,
     stepId: string,
-    status: 'running' | 'completed' | 'failed' | 'skipped' | 'cancelled' | 'blocked',
+    status: 'running' | 'completed' | 'failed' | 'skipped' | 'cancelled' | 'blocked' | 'timed_out',
     extra?: { run_status?: 'running' | 'completed' | 'failed' | 'cancelled'; report?: string },
   ): void {
     publishUser({
@@ -678,6 +749,38 @@ export function createFlowRunner(deps: Deps): FlowRunner {
         log.info({ runId, stepId: step.step_id, taskId: task!.id }, 'flow-runner: step re-dispatched on resume');
         break;
       }
+
+      case 'retry': {
+        // Like re-dispatch but increments retry_count and sets status to 'running'.
+        if (!step.input) {
+          await sql`
+            UPDATE flow_steps
+            SET status = 'failed', error = 'retry: no stored prompt',
+                updated_at = clock_timestamp()
+            WHERE run_id = ${runId} AND step_id = ${step.step_id}
+          `;
+          break;
+        }
+        const chatIdR = step.chat_id;
+        const [chatR] = chatIdR
+          ? await sql<{ session_id: string }[]>`SELECT session_id FROM chats WHERE id = ${chatIdR}`
+          : [];
+        const sessionIdR = chatR?.session_id ?? null;
+        const [taskR] = await sql<{ id: string }[]>`
+          INSERT INTO tasks (project_id, input, agent, model, mode_id, session_id, chat_id)
+          VALUES (${projectId}, ${step.input}, 'qwen', ${model}, 'plan', ${sessionIdR}, ${chatIdR})
+          RETURNING id
+        `;
+        await sql`
+          UPDATE flow_steps
+          SET task_id = ${taskR!.id}, retry_count = retry_count + 1, status = 'running',
+              updated_at = clock_timestamp()
+          WHERE run_id = ${runId} AND step_id = ${step.step_id}
+        `;
+        log.info({ runId, stepId: step.step_id, taskId: taskR!.id },
+          'flow-runner: step retried on resume');
+        break;
+      }
     }
   }
 
@@ -692,7 +795,9 @@ export function createFlowRunner(deps: Deps): FlowRunner {
       status: string;
       chat_id: string | null;
       input: string | null;
-    }[]>`SELECT step_id, task_id, status, chat_id, input FROM flow_steps WHERE run_id = ${run.id}`;
+      retry_count: number | null;
+      max_retries: number | null;
+    }[]>`SELECT step_id, task_id, status, chat_id, input, retry_count, max_retries FROM flow_steps WHERE run_id = ${run.id}`;
 
     // Load task states for all referenced tasks in one query.
     const taskIds = rows.map((r) => r.task_id).filter((id): id is string => id !== null);
@@ -705,7 +810,13 @@ export function createFlowRunner(deps: Deps): FlowRunner {
     }
 
     const decisions = reconcileRun(
-      rows.map((r) => ({ stepId: r.step_id, taskId: r.task_id, status: r.status })),
+      rows.map((r) => ({
+        stepId: r.step_id,
+        taskId: r.task_id,
+        status: r.status,
+        retryCount: r.retry_count ?? undefined,
+        maxRetries: r.max_retries,
+      })),
       taskStates,
     );
 
@@ -742,17 +853,18 @@ export function createFlowRunner(deps: Deps): FlowRunner {
       WHERE id = ${runId} AND status = 'running'
     `;
     if (updated.count === 0) return { cancelled: false, taskIds: [] };
+    deps.onRunTerminal?.(runId, 'cancelled');
 
     // Mark all non-terminal steps cancelled and collect in-flight task_ids.
     const steps = await sql<{ step_id: string; task_id: string | null; kind: string }[]>`
       SELECT step_id, task_id, kind FROM flow_steps
-      WHERE run_id = ${runId} AND status NOT IN ('completed', 'failed', 'cancelled', 'skipped')
+      WHERE run_id = ${runId} AND status NOT IN ('completed', 'failed', 'cancelled', 'skipped', 'timed_out')
     `;
 
     if (steps.length > 0) {
       await sql`
         UPDATE flow_steps SET status = 'cancelled', updated_at = clock_timestamp()
-        WHERE run_id = ${runId} AND status NOT IN ('completed', 'failed', 'cancelled', 'skipped')
+        WHERE run_id = ${runId} AND status NOT IN ('completed', 'failed', 'cancelled', 'skipped', 'timed_out')
       `;
       for (const s of steps) {
         if (s.kind === 'agent') publishStep(runId, s.step_id, 'cancelled', { run_status: 'cancelled' });

apps/coder/src/services/frame-emitter.ts

@@ -19,9 +19,10 @@
 import type { Broker } from '@boocode/server/broker';
 import type { WsFrame } from '@boocode/contracts/ws-frames';
 import type { AgentEvent } from './agent-backend.js';
-import { type AcpToolSnapshot, snapshotToWireToolCall } from './acp-tool-snapshot.js';
+import { type AcpToolSnapshot, snapshotToWireToolCall, mapToolLifecycleStatus } from './acp-tool-snapshot.js';
 import { mergeTaskCommands, getTaskCommands } from './agent-commands-cache.js';
 import type { DcpStreamStripper } from './dcp-strip.js';
+import { emitHook } from '../plugins/host.js';
 
 export interface FrameEmitterOpts {
   broker?: Broker;
@@ -91,8 +92,29 @@ export function makeFrameEmitter(opts: FrameEmitterOpts): FrameEmitter {
         }
         break;
       case 'tool_call':
+        toolSnapshots.set(e.toolCall.toolCallId, e.toolCall);
+        if (canStream()) {
+          broker!.publishFrame(sessionId!, {
+            type: 'tool_call',
+            message_id: assistantId!,
+            chat_id: chatId!,
+            tool_call: snapshotToWireToolCall(e.toolCall),
+          } as WsFrame);
+        }
+        break;
       case 'tool_update':
         toolSnapshots.set(e.toolCall.toolCallId, e.toolCall);
+        {
+          const lifecycle = mapToolLifecycleStatus(e.toolCall.status, e.toolCall.rawOutput);
+          if (lifecycle === 'completed' || lifecycle === 'failed') {
+            void emitHook('tool.execute.after', {
+              toolName: e.toolCall.title,
+              args: e.toolCall.rawInput,
+              result: e.toolCall.rawOutput,
+              duration: undefined,
+            });
+          }
+        }
         if (canStream()) {
           broker!.publishFrame(sessionId!, {
             type: 'tool_call',

apps/coder/src/services/guideline-service.ts

@@ -0,0 +1,560 @@
+import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export type Criticality = 'low' | 'medium' | 'high';
+
+export interface GuidelineContent {
+  condition: string;
+  action: string | null;
+  description: string | null;
+}
+
+export interface Guideline {
+  id: string;
+  creationUtc: string;
+  content: GuidelineContent;
+  enabled: boolean;
+  tags: string[];
+  labels: string[];
+  metadata: Record<string, unknown>;
+  criticality: Criticality;
+  title: string | null;
+  priority: number;
+}
+
+export interface CreateGuidelineParams {
+  condition: string;
+  action?: string;
+  description?: string;
+  tags?: string[];
+  labels?: string[];
+  criticality?: Criticality;
+  title?: string;
+  priority?: number;
+}
+
+export interface UpdateGuidelineParams {
+  condition?: string;
+  action?: string | null;
+  description?: string | null;
+  enabled?: boolean;
+  tags?: string[];
+  labels?: string[];
+  metadata?: Record<string, unknown>;
+  criticality?: Criticality;
+  title?: string | null;
+  priority?: number;
+}
+
+export interface ListGuidelinesFilter {
+  tags?: string[];
+  labels?: string[];
+}
+
+interface GuidelineStoreData {
+  version: string;
+  guidelines: Guideline[];
+  migrationLog: string[];
+}
+
+const GUIDELINES_REL = '.boo/guidelines';
+const STORE_FILE = 'guidelines.json';
+const CURRENT_VERSION = 'v0.11.0';
+
+function storeDir(basePath?: string): string {
+  return resolve(basePath ?? process.cwd(), GUIDELINES_REL);
+}
+
+function storePath(basePath?: string): string {
+  return join(storeDir(basePath), STORE_FILE);
+}
+
+function tryParseJson<T>(raw: string): T | null {
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return null;
+  }
+}
+
+let idCounter = 0;
+
+function nextId(): string {
+  idCounter++;
+  return `gl_${Date.now()}_${idCounter}`;
+}
+
+function isoNow(): string {
+  return new Date().toISOString();
+}
+
+async function ensureStoreDir(basePath?: string): Promise<void> {
+  const dir = storeDir(basePath);
+  if (!existsSync(dir)) {
+    await mkdir(dir, { recursive: true });
+  }
+}
+
+const MIGRATIONS: { from: string; to: string; migrate: (data: GuidelineStoreData) => GuidelineStoreData }[] = [
+  {
+    from: 'v0.1.0',
+    to: 'v0.2.0',
+    migrate: (data) => ({
+      ...data,
+      version: 'v0.2.0',
+      guidelines: data.guidelines.map((g) => ({
+        ...g,
+        enabled: g.enabled ?? true,
+      })),
+      migrationLog: [...data.migrationLog, 'v0.1.0→v0.2.0: add enabled field'],
+    }),
+  },
+  {
+    from: 'v0.2.0',
+    to: 'v0.3.0',
+    migrate: (data) => ({
+      ...data,
+      version: 'v0.3.0',
+      migrationLog: [...data.migrationLog, 'v0.2.0→v0.3.0: remove guideline_set'],
+    }),
+  },
+  {
+    from: 'v0.3.0',
+    to: 'v0.4.0',
+    migrate: (data) => ({
+      ...data,
+      version: 'v0.4.0',
+      guidelines: data.guidelines.map((g) => ({
+        ...g,
+        content: {
+          ...g.content,
+          action: g.content.action ?? null,
+          description: g.content.description ?? null,
+        },
+        metadata: g.metadata ?? {},
+      })),
+      migrationLog: [...data.migrationLog, 'v0.3.0→v0.4.0: add optional action, description, metadata'],
+    }),
+  },
+  {
+    from: 'v0.4.0',
+    to: 'v0.5.0',
+    migrate: (data) => ({
+      ...data,
+      version: 'v0.5.0',
+      migrationLog: [...data.migrationLog, 'v0.4.0→v0.5.0: description as optional'],
+    }),
+  },
+  {
+    from: 'v0.5.0',
+    to: 'v0.6.0',
+    migrate: (data) => ({
+      ...data,
+      version: 'v0.6.0',
+      guidelines: data.guidelines.map((g) => ({
+        ...g,
+        criticality: g.criticality ?? 'medium',
+      })),
+      migrationLog: [...data.migrationLog, 'v0.5.0→v0.6.0: add criticality'],
+    }),
+  },
+  {
+    from: 'v0.6.0',
+    to: 'v0.7.0',
+    migrate: (data) => ({
+      ...data,
+      version: 'v0.7.0',
+      migrationLog: [...data.migrationLog, 'v0.6.0→v0.7.0: add composition_mode (optional)'],
+    }),
+  },
+  {
+    from: 'v0.7.0',
+    to: 'v0.8.0',
+    migrate: (data) => ({
+      ...data,
+      version: 'v0.8.0',
+      migrationLog: [...data.migrationLog, 'v0.7.0→v0.8.0: add track (default true)'],
+    }),
+  },
+  {
+    from: 'v0.8.0',
+    to: 'v0.9.0',
+    migrate: (data) => ({
+      ...data,
+      version: 'v0.9.0',
+      guidelines: data.guidelines.map((g) => ({
+        ...g,
+        labels: g.labels ?? [],
+      })),
+      migrationLog: [...data.migrationLog, 'v0.8.0→v0.9.0: add labels'],
+    }),
+  },
+  {
+    from: 'v0.9.0',
+    to: 'v0.10.0',
+    migrate: (data) => ({
+      ...data,
+      version: 'v0.10.0',
+      guidelines: data.guidelines.map((g) => ({
+        ...g,
+        priority: g.priority ?? 0,
+      })),
+      migrationLog: [...data.migrationLog, 'v0.9.0→v0.10.0: add priority'],
+    }),
+  },
+  {
+    from: 'v0.10.0',
+    to: 'v0.11.0',
+    migrate: (data) => ({
+      ...data,
+      version: 'v0.11.0',
+      guidelines: data.guidelines.map((g) => ({
+        ...g,
+        title: g.title ?? null,
+      })),
+      migrationLog: [...data.migrationLog, 'v0.10.0→v0.11.0: add title'],
+    }),
+  },
+];
+
+function applyMigrations(data: GuidelineStoreData): GuidelineStoreData {
+  let current = { ...data };
+  for (const migration of MIGRATIONS) {
+    if (current.version === migration.from) {
+      current = migration.migrate(current);
+    }
+  }
+  return current;
+}
+
+async function readStore(basePath?: string): Promise<GuidelineStoreData> {
+  try {
+    const raw = await readFile(storePath(basePath), 'utf-8');
+    const data = tryParseJson<GuidelineStoreData>(raw);
+    if (!data) return { version: CURRENT_VERSION, guidelines: [], migrationLog: [] };
+    if (data.version !== CURRENT_VERSION) {
+      return applyMigrations(data);
+    }
+    return data;
+  } catch {
+    return { version: CURRENT_VERSION, guidelines: [], migrationLog: [] };
+  }
+}
+
+async function writeStore(data: GuidelineStoreData, basePath?: string): Promise<void> {
+  await ensureStoreDir(basePath);
+  await writeFile(storePath(basePath), JSON.stringify(data, null, 2), 'utf-8');
+}
+
+export async function createGuideline(
+  params: CreateGuidelineParams,
+  basePath?: string,
+): Promise<Guideline> {
+  const data = await readStore(basePath);
+  const guideline: Guideline = {
+    id: nextId(),
+    creationUtc: isoNow(),
+    content: {
+      condition: params.condition,
+      action: params.action ?? null,
+      description: params.description ?? null,
+    },
+    enabled: true,
+    tags: params.tags ?? [],
+    labels: params.labels ?? [],
+    metadata: {},
+    criticality: params.criticality ?? 'medium',
+    title: params.title ?? null,
+    priority: params.priority ?? 0,
+  };
+  data.guidelines.push(guideline);
+  await writeStore(data, basePath);
+  return guideline;
+}
+
+export async function listGuidelines(
+  filter?: ListGuidelinesFilter,
+  basePath?: string,
+): Promise<Guideline[]> {
+  const data = await readStore(basePath);
+  let results = data.guidelines;
+
+  if (filter?.tags && filter.tags.length > 0) {
+    results = results.filter((g) => filter.tags!.some((tag) => g.tags.includes(tag)));
+  }
+
+  if (filter?.labels && filter.labels.length > 0) {
+    results = results.filter((g) => filter.labels!.every((label) => g.labels.includes(label)));
+  }
+
+  return results;
+}
+
+export async function readGuideline(
+  id: string,
+  basePath?: string,
+): Promise<Guideline | null> {
+  const data = await readStore(basePath);
+  return data.guidelines.find((g) => g.id === id) ?? null;
+}
+
+export async function updateGuideline(
+  id: string,
+  params: UpdateGuidelineParams,
+  basePath?: string,
+): Promise<Guideline | null> {
+  const data = await readStore(basePath);
+  const idx = data.guidelines.findIndex((g) => g.id === id);
+  if (idx === -1) return null;
+
+  const existing = data.guidelines[idx]!;
+
+  if (params.condition !== undefined) existing.content.condition = params.condition;
+  if (params.action !== undefined) existing.content.action = params.action;
+  if (params.description !== undefined) existing.content.description = params.description;
+  if (params.enabled !== undefined) existing.enabled = params.enabled;
+  if (params.tags !== undefined) existing.tags = params.tags;
+  if (params.labels !== undefined) existing.labels = params.labels;
+  if (params.metadata !== undefined) existing.metadata = params.metadata;
+  if (params.criticality !== undefined) existing.criticality = params.criticality;
+  if (params.title !== undefined) existing.title = params.title;
+  if (params.priority !== undefined) existing.priority = params.priority;
+
+  data.guidelines[idx] = existing;
+  await writeStore(data, basePath);
+  return existing;
+}
+
+export async function deleteGuideline(
+  id: string,
+  basePath?: string,
+): Promise<boolean> {
+  const data = await readStore(basePath);
+  const lenBefore = data.guidelines.length;
+  data.guidelines = data.guidelines.filter((g) => g.id !== id);
+  if (data.guidelines.length === lenBefore) return false;
+  await writeStore(data, basePath);
+  return true;
+}
+
+export async function findGuideline(
+  content: { condition: string; action?: string },
+  basePath?: string,
+): Promise<Guideline | null> {
+  const data = await readStore(basePath);
+  return data.guidelines.find((g) => {
+    const condMatch = g.content.condition === content.condition;
+    if (!condMatch) return false;
+    if (content.action !== undefined) {
+      return g.content.action === content.action;
+    }
+    return true;
+  }) ?? null;
+}
+
+// ─── Journey → Guideline projection (port of Parlant's JourneyGuidelineProjection) ───
+
+export interface JourneyNode {
+  id: string;
+  action: string;
+  description?: string;
+}
+
+export interface JourneyEdge {
+  sourceNodeId: string;
+  targetNodeId: string;
+  condition: string;
+}
+
+export interface Journey {
+  id: string;
+  name: string;
+  nodes: JourneyNode[];
+  edges: JourneyEdge[];
+}
+
+export interface JourneyProjectionResult {
+  guidelines: Guideline[];
+  followUps: Map<string, string[]>;
+}
+
+/**
+ * Project a Journey into an ordered list of Guidelines.
+ * DFS traversal from root nodes: each (edge, node) pair → one Guideline.
+ * Edge condition becomes guideline condition, node action becomes guideline action.
+ * BFS queue avoids infinite loops via visited set.
+ */
+export function projectJourneyToGuidelines(
+  journey: Journey,
+  baseTags?: string[],
+): JourneyProjectionResult {
+  const guidelines: Guideline[] = [];
+  const followUps = new Map<string, string[]>();
+  const visited = new Set<string>();
+  const nodeMap = new Map<string, JourneyNode>();
+
+  for (const node of journey.nodes) {
+    nodeMap.set(node.id, node);
+  }
+
+  // Build adjacency list
+  const adjacency = new Map<string, JourneyEdge[]>();
+  for (const edge of journey.edges) {
+    const list = adjacency.get(edge.sourceNodeId) ?? [];
+    list.push(edge);
+    adjacency.set(edge.sourceNodeId, list);
+  }
+
+  // Find root nodes (no incoming edges)
+  const hasIncoming = new Set<string>();
+  for (const edge of journey.edges) {
+    hasIncoming.add(edge.targetNodeId);
+  }
+  const roots = journey.nodes
+    .filter((n) => !hasIncoming.has(n.id))
+    .map((n) => n.id);
+
+  const queue: { nodeId: string; fromEdge?: JourneyEdge }[] = [];
+
+  // BFS from roots
+  for (const rootId of roots) {
+    if (!visited.has(rootId)) {
+      queue.push({ nodeId: rootId });
+    }
+  }
+
+  while (queue.length > 0) {
+    const { nodeId, fromEdge } = queue.shift()!;
+    if (visited.has(nodeId)) continue;
+    visited.add(nodeId);
+
+    const node = nodeMap.get(nodeId);
+    if (!node) continue;
+
+    // If we arrived via an edge, create a guideline
+    if (fromEdge) {
+      const guideline = createGuidelineFromJourneyEdge(
+        journey,
+        node,
+        fromEdge,
+        baseTags,
+      );
+      guidelines.push(guideline);
+
+      // Track follow-ups
+      const sourceId = findGuidelineForNode(fromEdge.sourceNodeId, journey.nodes);
+      if (sourceId) {
+        const existing = followUps.get(sourceId) ?? [];
+        existing.push(guideline.id);
+        followUps.set(sourceId, existing);
+      }
+    }
+
+    // Enqueue downstream nodes
+    const outgoingEdges = adjacency.get(nodeId) ?? [];
+    for (const edge of outgoingEdges) {
+      if (!visited.has(edge.targetNodeId)) {
+        queue.push({ nodeId: edge.targetNodeId, fromEdge: edge });
+      }
+    }
+  }
+
+  return { guidelines, followUps };
+}
+
+function findGuidelineForNode(nodeId: string, nodes: JourneyNode[]): string | null {
+  // Placeholder: in a full implementation, map nodeId → guideline id
+  // For now return null — downstream consumers handle missing follow-ups gracefully
+  return null;
+}
+
+function createGuidelineFromJourneyEdge(
+  journey: Journey,
+  targetNode: JourneyNode,
+  edge: JourneyEdge,
+  baseTags?: string[],
+): Guideline {
+  const now = isoNow();
+  return {
+    id: nextId(),
+    creationUtc: now,
+    content: {
+      condition: edge.condition,
+      action: targetNode.action,
+      description: targetNode.description ?? null,
+    },
+    enabled: true,
+    tags: baseTags ?? [journey.name],
+    labels: [],
+    metadata: {
+      journey_id: journey.id,
+      journey_node: targetNode.id,
+      source_edge_id: `${edge.sourceNodeId}→${edge.targetNodeId}`,
+    },
+    criticality: 'medium',
+    title: targetNode.description
+      ? `[${journey.name}] ${targetNode.description.slice(0, 60)}`
+      : null,
+    priority: 0,
+  };
+}
+
+// ─── Backtrack detection ───
+
+export interface BacktrackCheckInput {
+  journeyId: string;
+  currentNodeId: string;
+  previousNodeId: string;
+}
+
+export interface BacktrackCheckResult {
+  journeyId: string;
+  currentNodeId: string;
+  previousNodeId: string;
+  isBacktrack: boolean;
+  recommendation: string | null;
+}
+
+/**
+ * Check if moving from previousNodeId to currentNodeId is a backtrack
+ * (regression to an already-visited node not on a forward path).
+ */
+export function checkBacktrack(
+  input: BacktrackCheckInput,
+  journey: Journey,
+): BacktrackCheckResult {
+  const adjacency = new Map<string, string[]>();
+  for (const edge of journey.edges) {
+    const list = adjacency.get(edge.sourceNodeId) ?? [];
+    list.push(edge.targetNodeId);
+    adjacency.set(edge.sourceNodeId, list);
+  }
+
+  // Find forward reachable nodes from the current node
+  const forwardReachable = new Set<string>();
+  const bfsQueue = [input.currentNodeId];
+  while (bfsQueue.length > 0) {
+    const nid = bfsQueue.shift()!;
+    if (forwardReachable.has(nid)) continue;
+    forwardReachable.add(nid);
+    const next = adjacency.get(nid) ?? [];
+    for (const n of next) {
+      if (!forwardReachable.has(n)) bfsQueue.push(n);
+    }
+  }
+
+  const isBacktrack = input.previousNodeId !== input.currentNodeId
+    && !forwardReachable.has(input.previousNodeId)
+    && input.previousNodeId !== input.currentNodeId;
+
+  return {
+    journeyId: input.journeyId,
+    currentNodeId: input.currentNodeId,
+    previousNodeId: input.previousNodeId,
+    isBacktrack,
+    recommendation: isBacktrack
+      ? `Revisiting node "${input.previousNodeId}" after "${input.currentNodeId}" — this may indicate a regression. Consider whether the forward path from "${input.currentNodeId}" is the correct one.`
+      : null,
+  };
+}

apps/coder/src/services/hashline/constants.ts

@@ -0,0 +1,10 @@
+export const NIBBLE_STR = "ZPMQVRWSNKTXJBYH"
+
+export const HASHLINE_DICT = Array.from({ length: 256 }, (_, i) => {
+  const high = i >>> 4
+  const low = i & 0x0f
+  return `${NIBBLE_STR[high]}${NIBBLE_STR[low]}`
+})
+
+export const HASHLINE_REF_PATTERN = /^([0-9]+)#([ZPMQVRWSNKTXJBYH]{2})$/
+export const HASHLINE_OUTPUT_PATTERN = /^([0-9]+)#([ZPMQVRWSNKTXJBYH]{2})\|(.*)$/

apps/coder/src/services/hashline/hash-computation.ts

@@ -0,0 +1,31 @@
+import { HASHLINE_DICT } from "./constants.js"
+import { hashXxh32 } from "./xxhash32.js"
+
+const RE_SIGNIFICANT = /[\p{L}\p{N}]/u
+
+function computeNormalizedLineHash(lineNumber: number, normalizedContent: string): string {
+  const stripped = normalizedContent
+  const seed = RE_SIGNIFICANT.test(stripped) ? 0 : lineNumber
+  const hash = hashXxh32(stripped, seed)
+  const index = hash % 256
+  return HASHLINE_DICT[index]!
+}
+
+export function computeLineHash(lineNumber: number, content: string): string {
+  return computeNormalizedLineHash(lineNumber, content.replace(/\r/g, "").trimEnd())
+}
+
+export function computeLegacyLineHash(lineNumber: number, content: string): string {
+  return computeNormalizedLineHash(lineNumber, content.replace(/\r/g, "").replace(/\s+/g, ""))
+}
+
+export function formatHashLine(lineNumber: number, content: string): string {
+  const hash = computeLineHash(lineNumber, content)
+  return `${lineNumber}#${hash}|${content}`
+}
+
+export function formatHashLines(content: string): string {
+  if (!content) return ""
+  const lines = content.split("\n")
+  return lines.map((line, index) => formatHashLine(index + 1, line)).join("\n")
+}

apps/coder/src/services/hashline/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Hashline editing core — content-hash anchors for edit_file stale-patch detection.
+ *
+ * Ported from oh-my-openagent/packages/hashline-core/.
+ * Bundles a runtime-aware xxHash32 (Bun fast-path, pure-JS fallback).
+ */
+export { computeLineHash, formatHashLines, formatHashLine, computeLegacyLineHash } from "./hash-computation.js"
+export { parseLineRef, validateLineRef, validateLineRefs, HashlineMismatchError, normalizeLineRef } from "./validation.js"
+export type { LineRef } from "./validation.js"
+export { NIBBLE_STR, HASHLINE_DICT, HASHLINE_REF_PATTERN, HASHLINE_OUTPUT_PATTERN } from "./constants.js"
+export type { ReplaceEdit, AppendEdit, PrependEdit, HashlineEdit } from "./types.js"

apps/coder/src/services/hashline/types.ts

@@ -0,0 +1,20 @@
+export interface ReplaceEdit {
+  op: "replace"
+  pos: string
+  end?: string
+  lines: string | string[]
+}
+
+export interface AppendEdit {
+  op: "append"
+  pos?: string
+  lines: string | string[]
+}
+
+export interface PrependEdit {
+  op: "prepend"
+  pos?: string
+  lines: string | string[]
+}
+
+export type HashlineEdit = ReplaceEdit | AppendEdit | PrependEdit

apps/coder/src/services/hashline/validation.ts

@@ -0,0 +1,192 @@
+import { computeLegacyLineHash, computeLineHash } from "./hash-computation.js"
+import { HASHLINE_REF_PATTERN } from "./constants.js"
+
+export interface LineRef {
+  line: number
+  hash: string
+}
+
+interface HashMismatch {
+  line: number
+  expected: string
+}
+
+const MISMATCH_CONTEXT = 2
+
+const LINE_REF_EXTRACT_PATTERN = /([0-9]+#[ZPMQVRWSNKTXJBYH]{2})/
+
+function isCompatibleLineHash(line: number, content: string, hash: string): boolean {
+  return computeLineHash(line, content) === hash || computeLegacyLineHash(line, content) === hash
+}
+
+export function normalizeLineRef(ref: string): string {
+  const originalTrimmed = ref.trim()
+  let trimmed = originalTrimmed
+  trimmed = trimmed.replace(/^(?:>>>|[+-])\s*/, "")
+  trimmed = trimmed.replace(/\s*#\s*/, "#")
+  trimmed = trimmed.replace(/\|.*$/, "")
+  trimmed = trimmed.trim()
+
+  if (HASHLINE_REF_PATTERN.test(trimmed)) {
+    return trimmed
+  }
+
+  const extracted = trimmed.match(LINE_REF_EXTRACT_PATTERN)
+  if (extracted) {
+    return extracted[1]!
+  }
+
+  return originalTrimmed
+}
+
+export function parseLineRef(ref: string): LineRef {
+  const normalized = normalizeLineRef(ref)
+  const match = normalized.match(HASHLINE_REF_PATTERN)
+  if (match) {
+    return {
+      line: Number.parseInt(match[1]!, 10),
+      hash: match[2]!,
+    }
+  }
+  const hashIdx = normalized.indexOf('#')
+  if (hashIdx > 0) {
+    const prefix = normalized.slice(0, hashIdx)
+    const suffix = normalized.slice(hashIdx + 1)
+    if (!/^\d+$/.test(prefix) && /^[ZPMQVRWSNKTXJBYH]{2}$/.test(suffix)) {
+      throw new Error(
+        `Invalid line reference: "${ref}". "${prefix}" is not a line number. ` +
+          `Use the actual line number from the read output.`
+      )
+    }
+  }
+  throw new Error(
+    `Invalid line reference format: "${ref}". Expected format: "{line_number}#{hash_id}"`
+  )
+}
+
+export function validateLineRef(lines: string[], ref: string): void {
+  const { line, hash } = parseLineRefWithHint(ref, lines)
+
+  if (line < 1 || line > lines.length) {
+    throw new Error(
+      `Line number ${line} out of bounds. File has ${lines.length} lines.`
+    )
+  }
+
+  const content = lines[line - 1]
+  if (content === undefined) {
+    throw new Error(
+      `Line number ${line} out of bounds. File has ${lines.length} lines.`
+    )
+  }
+  if (!isCompatibleLineHash(line, content, hash)) {
+    throw new HashlineMismatchError([{ line, expected: hash }], lines)
+  }
+}
+
+export class HashlineMismatchError extends Error {
+  readonly remaps: ReadonlyMap<string, string>
+
+  constructor(
+    private readonly mismatches: HashMismatch[],
+    private readonly fileLines: string[]
+  ) {
+    super(HashlineMismatchError.formatMessage(mismatches, fileLines))
+    this.name = "HashlineMismatchError"
+    const remaps = new Map<string, string>()
+    for (const mismatch of mismatches) {
+      const content = fileLines[mismatch.line - 1]
+      const actualLine = content ?? ""
+      const actual = computeLineHash(mismatch.line, actualLine)
+      remaps.set(`${mismatch.line}#${mismatch.expected}`, `${mismatch.line}#${actual}`)
+    }
+    this.remaps = remaps
+  }
+
+  static formatMessage(mismatches: HashMismatch[], fileLines: string[]): string {
+    const mismatchByLine = new Map<number, HashMismatch>()
+    for (const mismatch of mismatches) mismatchByLine.set(mismatch.line, mismatch)
+
+    const displayLines = new Set<number>()
+    for (const mismatch of mismatches) {
+      const low = Math.max(1, mismatch.line - MISMATCH_CONTEXT)
+      const high = Math.min(fileLines.length, mismatch.line + MISMATCH_CONTEXT)
+      for (let line = low; line <= high; line++) displayLines.add(line)
+    }
+
+    const sortedLines = [...displayLines].sort((a, b) => a - b)
+    const output: string[] = []
+    output.push(
+      `${mismatches.length} line${mismatches.length > 1 ? "s have" : " has"} changed since last read. ` +
+        "Use updated {line_number}#{hash_id} references below (>>> marks changed lines)."
+    )
+    output.push("")
+
+    let previousLine = -1
+    for (const line of sortedLines) {
+      if (previousLine !== -1 && line > previousLine + 1) {
+        output.push("    ...")
+      }
+      previousLine = line
+
+      const content = fileLines[line - 1] ?? ""
+      const hash = computeLineHash(line, content)
+      const prefix = `${line}#${hash}|${content}`
+      if (mismatchByLine.has(line)) {
+        output.push(`>>> ${prefix}`)
+      } else {
+        output.push(`    ${prefix}`)
+      }
+    }
+
+    return output.join("\n")
+  }
+}
+
+function suggestLineForHash(ref: string, lines: string[]): string | null {
+  const hashMatch = ref.trim().match(/#([ZPMQVRWSNKTXJBYH]{2})$/)
+  if (!hashMatch) return null
+  const hash = hashMatch[1]!
+  for (let i = 0; i < lines.length; i++) {
+    if (isCompatibleLineHash(i + 1, lines[i] ?? "", hash)) {
+      return `Did you mean "${i + 1}#${computeLineHash(i + 1, lines[i] ?? "")}"?`
+    }
+  }
+  return null
+}
+
+function parseLineRefWithHint(ref: string, lines: string[]): LineRef {
+  try {
+    return parseLineRef(ref)
+  } catch (parseError) {
+    const hint = suggestLineForHash(ref, lines)
+    if (hint && parseError instanceof Error) {
+      throw new Error(`${parseError.message} ${hint}`)
+    }
+    throw parseError
+  }
+}
+
+export function validateLineRefs(lines: string[], refs: string[]): void {
+  const mismatches: HashMismatch[] = []
+
+  for (const ref of refs) {
+    const { line, hash } = parseLineRefWithHint(ref, lines)
+
+    if (line < 1 || line > lines.length) {
+      throw new Error(`Line number ${line} out of bounds (file has ${lines.length} lines)`)
+    }
+
+    const content = lines[line - 1]
+    if (content === undefined) {
+      throw new Error(`Line number ${line} out of bounds (file has ${lines.length} lines)`)
+    }
+    if (!isCompatibleLineHash(line, content, hash)) {
+      mismatches.push({ line, expected: hash })
+    }
+  }
+
+  if (mismatches.length > 0) {
+    throw new HashlineMismatchError(mismatches, lines)
+  }
+}

apps/coder/src/services/hashline/xxhash32.ts

@@ -0,0 +1,90 @@
+type BunHashRuntime = { hash: { xxHash32(data: string | Uint8Array, seed: number): number } }
+
+const runtime = globalThis as typeof globalThis & { Bun?: BunHashRuntime }
+const encoder = new TextEncoder()
+
+const PRIME32_1 = 0x9e3779b1
+const PRIME32_2 = 0x85ebca77
+const PRIME32_3 = 0xc2b2ae3d
+const PRIME32_4 = 0x27d4eb2f
+const PRIME32_5 = 0x165667b1
+
+function rotateLeft32(value: number, bits: number): number {
+  return ((value << bits) | (value >>> (32 - bits))) >>> 0
+}
+
+function readUint32LittleEndian(input: Uint8Array, offset: number): number {
+  return (
+    ((input[offset] ?? 0) |
+      ((input[offset + 1] ?? 0) << 8) |
+      ((input[offset + 2] ?? 0) << 16) |
+      ((input[offset + 3] ?? 0) << 24)) >>>
+    0
+  )
+}
+
+function round32(accumulator: number, value: number): number {
+  const added = (accumulator + Math.imul(value, PRIME32_2)) >>> 0
+  return Math.imul(rotateLeft32(added, 13), PRIME32_1) >>> 0
+}
+
+function xxHash32Js(input: Uint8Array, seed: number): number {
+  let offset = 0
+  const length = input.length
+  let hash: number
+
+  if (length >= 16) {
+    const limit = length - 16
+    let value1 = (seed + PRIME32_1 + PRIME32_2) >>> 0
+    let value2 = (seed + PRIME32_2) >>> 0
+    let value3 = seed >>> 0
+    let value4 = (seed - PRIME32_1) >>> 0
+
+    while (offset <= limit) {
+      value1 = round32(value1, readUint32LittleEndian(input, offset))
+      offset += 4
+      value2 = round32(value2, readUint32LittleEndian(input, offset))
+      offset += 4
+      value3 = round32(value3, readUint32LittleEndian(input, offset))
+      offset += 4
+      value4 = round32(value4, readUint32LittleEndian(input, offset))
+      offset += 4
+    }
+
+    hash = (rotateLeft32(value1, 1) + rotateLeft32(value2, 7)) >>> 0
+    hash = (hash + rotateLeft32(value3, 12)) >>> 0
+    hash = (hash + rotateLeft32(value4, 18)) >>> 0
+  } else {
+    hash = (seed + PRIME32_5) >>> 0
+  }
+
+  hash = (hash + length) >>> 0
+
+  while (offset + 4 <= length) {
+    hash = (hash + Math.imul(readUint32LittleEndian(input, offset), PRIME32_3)) >>> 0
+    hash = Math.imul(rotateLeft32(hash, 17), PRIME32_4) >>> 0
+    offset += 4
+  }
+
+  while (offset < length) {
+    hash = (hash + Math.imul(input[offset] ?? 0, PRIME32_5)) >>> 0
+    hash = Math.imul(rotateLeft32(hash, 11), PRIME32_1) >>> 0
+    offset += 1
+  }
+
+  hash = (hash ^ (hash >>> 15)) >>> 0
+  hash = Math.imul(hash, PRIME32_2) >>> 0
+  hash = (hash ^ (hash >>> 13)) >>> 0
+  hash = Math.imul(hash, PRIME32_3) >>> 0
+
+  return (hash ^ (hash >>> 16)) >>> 0
+}
+
+export function hashXxh32(input: string, seed: number): number {
+  const bun = runtime.Bun
+  if (bun !== undefined) {
+    return bun.hash.xxHash32(input, seed)
+  }
+
+  return xxHash32Js(encoder.encode(input), seed >>> 0)
+}

apps/coder/src/services/model-resolution/connected-providers-cache.ts

@@ -0,0 +1,34 @@
+import type { ModelMetadata } from "./provider-cache.js"
+
+export interface ProviderModelsCache {
+  readonly models: Record<string, readonly string[] | readonly ModelMetadata[]>
+  readonly connected: readonly string[]
+  readonly updatedAt: string
+}
+
+export interface ConnectedProvidersAdapter {
+  readConnectedProvidersCache(): string[] | null
+  findProviderModelMetadata(providerID: string, modelID: string): ModelMetadata | undefined
+  readProviderModelsCache(): ProviderModelsCache | null
+}
+
+export function readConnectedProvidersCache(): string[] | null {
+  return null
+}
+
+export function findProviderModelMetadata(
+  _providerID: string,
+  _modelID: string,
+): ModelMetadata | undefined {
+  return undefined
+}
+
+export function readProviderModelsCache(): ProviderModelsCache | null {
+  return null
+}
+
+export const connectedProvidersAdapter: ConnectedProvidersAdapter = {
+  readConnectedProvidersCache,
+  findProviderModelMetadata,
+  readProviderModelsCache,
+}

apps/coder/src/services/model-resolution/fallback-chain-from-models.ts

@@ -0,0 +1,128 @@
+import type { FallbackEntry } from "./model-requirement-types.js"
+import type { FallbackModelObject } from "./fallback-model-object.js"
+import { normalizeFallbackModels } from "./model-resolver.js"
+import { KNOWN_VARIANTS } from "./known-variants.js"
+
+function parseVariantFromModel(rawModel: string): { modelID: string; variant?: string } {
+  if (typeof rawModel !== "string") {
+    return { modelID: "" }
+  }
+  const trimmedModel = rawModel.trim()
+  if (!trimmedModel) {
+    return { modelID: "" }
+  }
+
+  const parenthesizedVariant = trimmedModel.match(/^(.*)\(([^()]+)\)\s*$/)
+  if (parenthesizedVariant) {
+    const modelID = parenthesizedVariant[1]?.trim() ?? ""
+    const variant = parenthesizedVariant[2]?.trim()
+    return variant ? { modelID, variant } : { modelID }
+  }
+
+  const spaceVariant = trimmedModel.match(/^(.*\S)\s+([a-z][a-z0-9_-]*)$/i)
+  if (spaceVariant) {
+    const modelID = spaceVariant[1]?.trim() ?? ""
+    const variant = spaceVariant[2]?.trim().toLowerCase()
+    if (variant && KNOWN_VARIANTS.has(variant)) {
+      return { modelID, variant }
+    }
+  }
+
+  return { modelID: trimmedModel }
+}
+
+export function parseFallbackModelEntry(
+  model: string,
+  contextProviderID: string | undefined,
+  defaultProviderID = "opencode",
+): FallbackEntry | undefined {
+  if (typeof model !== "string") return undefined
+  const trimmed = model.trim()
+  if (!trimmed) return undefined
+
+  const parts = trimmed.split("/")
+  const providerID =
+    parts.length >= 2 ? (parts[0]?.trim() ?? "") : (contextProviderID?.trim() || defaultProviderID)
+  const rawModelID = parts.length >= 2 ? parts.slice(1).join("/").trim() : trimmed
+  if (!providerID || !rawModelID) return undefined
+
+  const parsed = parseVariantFromModel(rawModelID)
+  if (!parsed.modelID) return undefined
+
+  return {
+    providers: [providerID],
+    model: parsed.modelID,
+    variant: parsed.variant,
+  }
+}
+
+export function parseFallbackModelObjectEntry(
+  obj: FallbackModelObject,
+  contextProviderID: string | undefined,
+  defaultProviderID = "opencode",
+): FallbackEntry | undefined {
+  const base = parseFallbackModelEntry(obj.model, contextProviderID, defaultProviderID)
+  if (!base) return undefined
+
+  return {
+    ...base,
+    variant: obj.variant ?? base.variant,
+    reasoningEffort: obj.reasoningEffort,
+    temperature: obj.temperature,
+    top_p: obj.top_p,
+    maxTokens: obj.maxTokens,
+    thinking: obj.thinking,
+  }
+}
+
+/**
+ * Find the most specific FallbackEntry whose `provider/model` is a prefix of
+ * the resolved `provider/modelID`.  Longest match wins so that e.g.
+ * `openai/gpt-5.4-preview` picks the entry for `openai/gpt-5.4-preview` over
+ * the shorter `openai/gpt-5.4`.
+ */
+export function findMostSpecificFallbackEntry(
+  providerID: string,
+  modelID: string,
+  chain: FallbackEntry[],
+): FallbackEntry | undefined {
+  const resolved = `${providerID}/${modelID}`.toLowerCase()
+
+  // Collect entries whose provider/model is a prefix of the resolved model,
+  // together with the length of the matching prefix (longest match wins).
+  const matches: { entry: FallbackEntry; matchLen: number }[] = []
+  for (const entry of chain) {
+    for (const p of entry.providers) {
+      const candidate = `${p}/${entry.model}`.toLowerCase()
+      if (resolved.startsWith(candidate)) {
+        matches.push({ entry, matchLen: candidate.length })
+        break // one match per entry is enough
+      }
+    }
+  }
+
+  if (matches.length === 0) return undefined
+  matches.sort((a, b) => b.matchLen - a.matchLen)
+  return matches[0]!.entry
+}
+
+export function buildFallbackChainFromModels(
+  fallbackModels: string | (string | FallbackModelObject)[] | undefined,
+  contextProviderID: string | undefined,
+  defaultProviderID = "opencode",
+): FallbackEntry[] | undefined {
+  const normalized = normalizeFallbackModels(fallbackModels)
+  if (!normalized || normalized.length === 0) return undefined
+
+  const parsed = normalized
+    .map((entry) => {
+      if (typeof entry === "string") {
+        return parseFallbackModelEntry(entry, contextProviderID, defaultProviderID)
+      }
+      return parseFallbackModelObjectEntry(entry, contextProviderID, defaultProviderID)
+    })
+    .filter((entry): entry is FallbackEntry => entry !== undefined)
+
+  if (parsed.length === 0) return undefined
+  return parsed
+}

apps/coder/src/services/model-resolution/fallback-model-object.ts

@@ -0,0 +1,9 @@
+export type FallbackModelObject = {
+  readonly model: string
+  readonly variant?: string
+  readonly reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"
+  readonly temperature?: number
+  readonly top_p?: number
+  readonly maxTokens?: number
+  readonly thinking?: { readonly type: "enabled" | "disabled"; readonly budgetTokens?: number }
+}

apps/coder/src/services/model-resolution/index.ts

@@ -0,0 +1,80 @@
+export type {
+  FallbackEntry,
+  ModelRequirement,
+} from "./model-requirement-types.js"
+export type {
+  FallbackModelObject,
+} from "./fallback-model-object.js"
+export type {
+  DelegatedModelConfig,
+  ModelResolutionRequest,
+  ModelResolutionProvenance,
+  ModelResolutionResult,
+} from "./model-resolution-types.js"
+export type {
+  ModelResolutionInput,
+  ModelSource,
+  ExtendedModelResolutionInput,
+} from "./model-resolver.js"
+export {
+  resolveModel,
+  resolveModelWithFallback,
+  normalizeFallbackModels,
+  flattenToFallbackModelStrings,
+} from "./model-resolver.js"
+export {
+  normalizeModel,
+  normalizeModelID,
+} from "./model-normalization.js"
+export {
+  fuzzyMatchModel,
+  isModelAvailable,
+} from "./model-availability.js"
+export {
+  transformModelForProvider,
+  transformModelForProviderDisplay,
+} from "./provider-model-id-transform.js"
+export {
+  buildFallbackChainFromModels,
+  parseFallbackModelEntry,
+  parseFallbackModelObjectEntry,
+  findMostSpecificFallbackEntry,
+} from "./fallback-chain-from-models.js"
+export {
+  KNOWN_VARIANTS,
+} from "./known-variants.js"
+export {
+  _setModelResolutionLogImplementationForTesting,
+  resolveModelPipeline,
+} from "./model-resolution-pipeline.js"
+export type {
+  ModelResolutionRequest as PipelineModelResolutionRequest,
+  ModelResolutionProvenance as PipelineModelResolutionProvenance,
+  ModelResolutionResult as PipelineModelResolutionResult,
+  ModelResolutionDeps,
+} from "./model-resolution-pipeline.js"
+export {
+  isRetryableModelError,
+  shouldRetryError,
+  getNextFallback,
+  hasMoreFallbacks,
+  selectFallbackProvider,
+  selectFallbackProviderWithCache,
+} from "./model-error-classifier.js"
+export type {
+  ErrorInfo,
+} from "./model-error-classifier.js"
+export type {
+  ProviderCache,
+  ModelMetadata,
+} from "./provider-cache.js"
+export type {
+  ProviderModelsCache,
+  ConnectedProvidersAdapter,
+} from "./connected-providers-cache.js"
+export {
+  readConnectedProvidersCache,
+  findProviderModelMetadata,
+  readProviderModelsCache,
+  connectedProvidersAdapter,
+} from "./connected-providers-cache.js"

apps/coder/src/services/model-resolution/known-variants.ts

@@ -0,0 +1,16 @@
+/**
+ * Canonical set of recognised variant / effort tokens.
+ * Used by parseFallbackModelEntry (space-suffix detection) and
+ * flattenToFallbackModelStrings (inline-variant stripping).
+ */
+export const KNOWN_VARIANTS = new Set([
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+  "minimal",
+  "none",
+  "auto",
+  "thinking",
+])

apps/coder/src/services/model-resolution/model-availability.ts

@@ -0,0 +1,64 @@
+function normalizeModelName(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/claude-(opus|sonnet|haiku)-(\d+)[.-](\d+)/g, "claude-$1-$2.$3")
+}
+
+export function fuzzyMatchModel(
+  target: string,
+  available: Set<string>,
+  providers?: string[],
+): string | null {
+  if (available.size === 0) {
+    return null
+  }
+
+  const targetNormalized = normalizeModelName(target)
+
+  let candidates = Array.from(available)
+  if (providers && providers.length > 0) {
+    const providerSet = new Set(providers)
+    candidates = candidates.filter((model) => {
+      const [provider] = model.split("/")
+      return providerSet.has(provider!)
+    })
+  }
+
+  if (candidates.length === 0) {
+    return null
+  }
+
+  const matches = candidates.filter((model) =>
+    normalizeModelName(model).includes(targetNormalized),
+  )
+
+  if (matches.length === 0) {
+    return null
+  }
+
+  const exactMatch = matches.find((model) => normalizeModelName(model) === targetNormalized)
+  if (exactMatch) {
+    return exactMatch
+  }
+
+  const exactModelIdMatches = matches.filter((model) => {
+    const modelId = model.split("/").slice(1).join("/")
+    return normalizeModelName(modelId) === targetNormalized
+  })
+  if (exactModelIdMatches.length > 0) {
+    return exactModelIdMatches.reduce((shortest, current) =>
+      current.length < shortest.length ? current : shortest,
+    )
+  }
+
+  return matches.reduce((shortest, current) =>
+    current.length < shortest.length ? current : shortest,
+  )
+}
+
+export function isModelAvailable(
+  targetModel: string,
+  availableModels: Set<string>,
+): boolean {
+  return fuzzyMatchModel(targetModel, availableModels) !== null
+}

apps/coder/src/services/model-resolution/model-error-classifier.ts

@@ -0,0 +1,261 @@
+import type { FallbackEntry } from "./model-requirement-types.js"
+import type { ProviderCache } from "./provider-cache.js"
+import * as connectedProvidersCache from "./connected-providers-cache.js"
+
+/**
+ * Error names that indicate a retryable model error.
+ * These errors halt execution and should trigger fallback retry.
+ */
+const RETRYABLE_ERROR_NAMES = new Set([
+  "providermodelnotfounderror",
+  "ratelimiterror",
+  "modelunavailableerror",
+  "providerconnectionerror",
+  "authenticationerror",
+])
+
+const STOP_ERROR_NAMES = new Set([
+  "quotaexceedederror",
+  "insufficientcreditserror",
+  "freeusagelimiterror",
+])
+
+/**
+ * Error names that should NOT trigger retry.
+ * These errors are typically user-induced or fixable without switching models.
+ */
+const NON_RETRYABLE_ERROR_NAMES = new Set([
+  "messageabortederror",
+  "permissiondeniederror",
+  "contextlengtherror",
+  "timeouterror",
+  "validationerror",
+  "syntaxerror",
+  "usererror",
+])
+
+/**
+ * Message patterns that indicate a retryable error even without a known error name.
+ */
+const RETRYABLE_MESSAGE_PATTERNS = [
+  "rate_limit",
+  "rate limit",
+  "usage_limit_reached",
+  "usage limit has been reached",
+  "quota",
+  "all credentials for model",
+  "cooling down",
+  "exhausted your capacity",
+  "not found",
+  "unavailable",
+  "insufficient",
+  "too many requests",
+  "over limit",
+  "overloaded",
+  "bad gateway",
+  "bad request",
+  "unknown provider",
+  "provider not found",
+  "model_not_supported",
+  "model not supported",
+  "model is not supported",
+  "connection error",
+  "network error",
+  "timeout",
+  "service unavailable",
+  "internal_server_error",
+  "free usage",
+  "usage exceeded",
+  "credit",
+  "balance",
+  "temporarily unavailable",
+  "try again",
+  "请稍后重试",
+  "503",
+  "502",
+  "504",
+  "429",
+  "529",
+  "selected provider is forbidden",
+  "provider is forbidden",
+  // Chinese retryable patterns (Zhipu, etc.)
+  "频率限制",           // "rate limit"
+  "请求过于频繁",       // "too many requests"
+  "暂时不可用",         // "temporarily unavailable"
+  "服务不可用",         // "service unavailable"
+  "server_error",
+  "an error occurred while processing",
+]
+
+/**
+ * Message patterns that indicate a non-retryable STOP error (quota/billing exhaustion).
+ * These take precedence over RETRYABLE_MESSAGE_PATTERNS.
+ */
+const STOP_MESSAGE_PATTERNS = [
+  "quota will reset after",
+  "quota exceeded",
+  "free usage limit",
+  "billing limit",
+  "billing hard limit",
+  "monthly limit",
+  "plan limit",
+  "subscription quota",
+  "subscription limit",
+  "payment required",
+  "out of credits",
+  "credits exhausted",
+  "insufficient credits",
+  "insufficient balance",
+  "credit balance",
+  "usage limit for this month",
+  "exhausted your capacity",
+  // GLM/Z.ai business error codes that indicate permanent quota/billing exhaustion
+  "daily call limit",
+  "daily limit",
+  "usage limit reached for",
+  "in arrears",
+  "fair use policy",
+  "recharge and try",
+  "使用上限",
+  "额度不足",
+  "余额不足",
+  "已耗尽",
+]
+
+const AUTO_RETRY_GATE_PATTERNS = [
+  "rate limit",
+  "cooling down",
+  "credentials for model",
+]
+
+function hasProviderAutoRetrySignal(message: string): boolean {
+  if (!message.includes("retrying in")) {
+    return false
+  }
+  return AUTO_RETRY_GATE_PATTERNS.some((pattern) => message.includes(pattern))
+}
+
+export interface ErrorInfo {
+  name?: string
+  message?: string
+  /** HTTP status code from the provider response (e.g., 429 for rate limit) */
+  statusCode?: number
+}
+
+/**
+ * Determines if an error is a retryable model error.
+ * Returns true if it's a known retryable type OR matches retryable message patterns.
+ */
+export function isRetryableModelError(error: ErrorInfo): boolean {
+  // If we have an error name, check against known lists
+  if (error.name) {
+    const errorNameLower = error.name.toLowerCase()
+    // Explicit non-retryable takes precedence
+    if (NON_RETRYABLE_ERROR_NAMES.has(errorNameLower)) {
+      return false
+    }
+    if (STOP_ERROR_NAMES.has(errorNameLower)) {
+      return false
+    }
+    // Check if it's a known retryable error
+    if (RETRYABLE_ERROR_NAMES.has(errorNameLower)) {
+      return true
+    }
+  }
+
+  // Check message patterns for unknown errors
+  const msg = error.message?.toLowerCase() ?? ""
+
+  // STOP patterns take precedence over retryable patterns
+  if (STOP_MESSAGE_PATTERNS.some((pattern) => msg.includes(pattern))) {
+    return false
+  }
+
+  if (hasProviderAutoRetrySignal(msg)) {
+    return true
+  }
+
+  // HTTP status code check: catches rate-limit errors regardless of message format/language.
+  // Uses the same codes as runtime-fallback config (400 excluded as it is a permanent client error).
+  if (
+    error.statusCode != null &&
+    (error.statusCode === 429 || error.statusCode === 503 || error.statusCode === 529)
+  ) {
+    return true
+  }
+
+  return RETRYABLE_MESSAGE_PATTERNS.some((pattern) => msg.includes(pattern))
+}
+
+/**
+ * Determines if an error should trigger a fallback retry.
+ * Returns true for errors that halt execution.
+ */
+export function shouldRetryError(error: ErrorInfo): boolean {
+  return isRetryableModelError(error)
+}
+
+/**
+ * Gets the next fallback model from the chain based on attempt count.
+ * Returns undefined if all fallbacks have been exhausted.
+ */
+export function getNextFallback(
+  fallbackChain: FallbackEntry[],
+  attemptCount: number,
+): FallbackEntry | undefined {
+  return fallbackChain[attemptCount]
+}
+
+/**
+ * Checks if there are more fallbacks available after the current attempt.
+ */
+export function hasMoreFallbacks(
+  fallbackChain: FallbackEntry[],
+  attemptCount: number,
+): boolean {
+  return attemptCount < fallbackChain.length
+}
+
+/**
+ * Selects the best provider for a fallback entry.
+ * Priority:
+ * 1) First connected provider in the entry's provider preference order
+ * 2) Preferred provider when connected (and entry providers are unavailable)
+ * 3) First provider listed in the fallback entry
+ */
+export function selectFallbackProvider(
+  providers: string[],
+  preferredProviderID?: string,
+): string {
+  return selectFallbackProviderWithCache(
+    providers,
+    connectedProvidersCache,
+    preferredProviderID,
+  )
+}
+
+export function selectFallbackProviderWithCache(
+  providers: string[],
+  providerCache: ProviderCache,
+  preferredProviderID?: string,
+): string {
+  const connectedProviders = providerCache.readConnectedProvidersCache()
+  if (connectedProviders) {
+    const connectedSet = new Set(connectedProviders.map(p => p.toLowerCase()))
+
+    for (const provider of providers) {
+      if (connectedSet.has(provider.toLowerCase())) {
+        return provider
+      }
+    }
+
+    if (
+      preferredProviderID &&
+      connectedSet.has(preferredProviderID.toLowerCase())
+    ) {
+      return preferredProviderID
+    }
+  }
+
+  return providers[0] ?? preferredProviderID ?? "opencode"
+}

apps/coder/src/services/model-resolution/model-normalization.ts

@@ -0,0 +1,8 @@
+export function normalizeModel(model?: string): string | undefined {
+  const trimmed = model?.trim()
+  return trimmed || undefined
+}
+
+export function normalizeModelID(modelID: string): string {
+  return modelID.replace(/\.(\d+)/g, "-$1")
+}

apps/coder/src/services/model-resolution/model-requirement-types.ts

@@ -0,0 +1,18 @@
+export type FallbackEntry = {
+  providers: string[];
+  model: string;
+  variant?: string; // Entry-specific variant (e.g., GPT->high, Opus->max)
+  reasoningEffort?: string;
+  temperature?: number;
+  top_p?: number;
+  maxTokens?: number;
+  thinking?: { type: "enabled" | "disabled"; budgetTokens?: number };
+};
+
+export type ModelRequirement = {
+  fallbackChain: FallbackEntry[];
+  variant?: string; // Default variant (used when entry doesn't specify one)
+  requiresModel?: string; // If set, only activates when this model is available (fuzzy match)
+  requiresAnyModel?: boolean; // If true, requires at least ONE model in fallbackChain to be available (or empty availability treated as unavailable)
+  requiresProvider?: string[]; // If set, only activates when any of these providers is connected
+};

apps/coder/src/services/model-resolution/model-resolution-pipeline.ts

@@ -0,0 +1,256 @@
+import { fuzzyMatchModel } from "./model-availability.js"
+import type { FallbackEntry } from "./model-requirement-types.js"
+import { transformModelForProvider } from "./provider-model-id-transform.js"
+import { normalizeModel } from "./model-normalization.js"
+import type { ProviderCache } from "./provider-cache.js"
+
+type LogImplementation = (message: string, data?: unknown) => void
+
+let logImplementationForTesting: LogImplementation | undefined
+
+function log(message: string, data?: unknown): void {
+  const logImpl = logImplementationForTesting
+  if (!logImpl) {
+    return
+  }
+  if (arguments.length === 1) {
+    logImpl(message)
+    return
+  }
+  logImpl(message, data)
+}
+
+export function _setModelResolutionLogImplementationForTesting(
+  logImplementation: LogImplementation | undefined,
+): void {
+  logImplementationForTesting = logImplementation
+}
+
+export type ModelResolutionRequest = {
+  intent?: {
+    uiSelectedModel?: string
+    userModel?: string
+    userFallbackModels?: string[]
+    categoryDefaultModel?: string
+  }
+  constraints: {
+    availableModels: Set<string>
+    connectedProviders?: string[] | null
+  }
+  policy?: {
+    fallbackChain?: FallbackEntry[]
+    systemDefaultModel?: string
+  }
+}
+
+export type ModelResolutionProvenance =
+  | "override"
+  | "category-default"
+  | "provider-fallback"
+  | "system-default"
+
+export type ModelResolutionResult = {
+  model: string
+  provenance: ModelResolutionProvenance
+  variant?: string
+  attempted?: string[]
+  reason?: string
+}
+
+export type ModelResolutionDeps = {
+  fuzzyMatchModel: (
+    target: string,
+    available: Set<string>,
+    providers?: string[],
+  ) => string | null
+  transformModelForProvider: (provider: string, model: string) => string
+}
+
+const DEFAULT_MODEL_RESOLUTION_DEPS: ModelResolutionDeps = {
+  fuzzyMatchModel,
+  transformModelForProvider,
+}
+
+
+export function resolveModelPipeline(
+  request: ModelResolutionRequest,
+  providerCache: ProviderCache = {
+    readConnectedProvidersCache: () => null,
+    findProviderModelMetadata: () => undefined,
+  },
+  deps: ModelResolutionDeps = DEFAULT_MODEL_RESOLUTION_DEPS,
+): ModelResolutionResult | undefined {
+  const attempted: string[] = []
+  const { intent, constraints, policy } = request
+  const availableModels = constraints.availableModels
+  const fallbackChain = policy?.fallbackChain
+  const systemDefaultModel = policy?.systemDefaultModel
+
+  const normalizedUiModel = normalizeModel(intent?.uiSelectedModel)
+  if (normalizedUiModel) {
+    log("Model resolved via UI selection", { model: normalizedUiModel })
+    return { model: normalizedUiModel, provenance: "override" }
+  }
+
+  const normalizedUserModel = normalizeModel(intent?.userModel)
+  if (normalizedUserModel) {
+    log("Model resolved via config override", { model: normalizedUserModel })
+    return { model: normalizedUserModel, provenance: "override" }
+  }
+
+  const normalizedCategoryDefault = normalizeModel(intent?.categoryDefaultModel)
+  if (normalizedCategoryDefault) {
+    attempted.push(normalizedCategoryDefault)
+    if (availableModels.size > 0) {
+      const parts = normalizedCategoryDefault.split("/")
+      const providerHint = parts.length >= 2 ? [parts[0]!] : undefined
+      const match = deps.fuzzyMatchModel(normalizedCategoryDefault, availableModels, providerHint)
+      if (match) {
+        log("Model resolved via category default (fuzzy matched)", {
+          original: normalizedCategoryDefault,
+          matched: match,
+        })
+        return { model: match, provenance: "category-default", attempted }
+      }
+    } else {
+      const connectedProviders = constraints.connectedProviders ?? providerCache.readConnectedProvidersCache()
+      if (connectedProviders === null) {
+        log("Model resolved via category default (no cache, first run)", {
+          model: normalizedCategoryDefault,
+        })
+        return { model: normalizedCategoryDefault, provenance: "category-default", attempted }
+      }
+      const parts = normalizedCategoryDefault.split("/")
+      if (parts.length >= 2) {
+        const provider = parts[0]!
+        if (connectedProviders.includes(provider)) {
+          const modelName = parts.slice(1).join("/")
+          const transformedModel = `${provider}/${deps.transformModelForProvider(provider, modelName)}`
+          log("Model resolved via category default (connected provider)", {
+            model: transformedModel,
+            original: normalizedCategoryDefault,
+          })
+          return { model: transformedModel, provenance: "category-default", attempted }
+        }
+      }
+    }
+    log("Category default model not available, falling through to fallback chain", {
+      model: normalizedCategoryDefault,
+    })
+  }
+
+  //#when - user configured fallback_models, try them before hardcoded fallback chain
+  const userFallbackModels = intent?.userFallbackModels
+  if (userFallbackModels && userFallbackModels.length > 0) {
+    if (availableModels.size === 0) {
+      const connectedProviders = constraints.connectedProviders ?? providerCache.readConnectedProvidersCache()
+      const connectedSet = connectedProviders ? new Set(connectedProviders) : null
+
+      if (connectedSet !== null) {
+        for (const model of userFallbackModels) {
+          attempted.push(model)
+          const parts = model.split("/")
+          if (parts.length >= 2) {
+            const provider = parts[0]!
+            if (connectedSet.has(provider)) {
+              const modelName = parts.slice(1).join("/")
+              const transformedModel = `${provider}/${deps.transformModelForProvider(provider, modelName)}`
+              log("Model resolved via user fallback_models (connected provider)", { model: transformedModel, original: model })
+              return { model: transformedModel, provenance: "provider-fallback", attempted }
+            }
+          }
+        }
+        log("No connected provider found in user fallback_models, falling through to hardcoded chain")
+      }
+    } else {
+      for (const model of userFallbackModels) {
+        attempted.push(model)
+        const parts = model.split("/")
+        const providerHint = parts.length >= 2 ? [parts[0]!] : undefined
+        const match = deps.fuzzyMatchModel(model, availableModels, providerHint)
+        if (match) {
+          log("Model resolved via user fallback_models (availability confirmed)", { model, match })
+          return { model: match, provenance: "provider-fallback", attempted }
+        }
+      }
+      log("No available model found in user fallback_models, falling through to hardcoded chain")
+    }
+  }
+
+  if (fallbackChain && fallbackChain.length > 0) {
+    if (availableModels.size === 0) {
+      const connectedProviders = constraints.connectedProviders ?? providerCache.readConnectedProvidersCache()
+      const connectedSet = connectedProviders ? new Set(connectedProviders) : null
+
+      if (connectedSet === null) {
+        log("Model fallback chain skipped (no connected providers cache) - falling through to system default")
+      } else {
+        for (const entry of fallbackChain) {
+          for (const provider of entry.providers) {
+            if (connectedSet.has(provider)) {
+              const transformedModelId = deps.transformModelForProvider(provider, entry.model)
+              const model = `${provider}/${transformedModelId}`
+              log("Model resolved via fallback chain (connected provider)", {
+                provider,
+                model: transformedModelId,
+                variant: entry.variant,
+              })
+              return {
+                model,
+                provenance: "provider-fallback",
+                variant: entry.variant,
+                attempted,
+              }
+            }
+          }
+        }
+        log("No connected provider found in fallback chain, falling through to system default")
+      }
+    } else {
+      for (const entry of fallbackChain) {
+        for (const provider of entry.providers) {
+          const fullModel = `${provider}/${entry.model}`
+          const match = deps.fuzzyMatchModel(fullModel, availableModels, [provider])
+          if (match) {
+            log("Model resolved via fallback chain (availability confirmed)", {
+              provider,
+              model: entry.model,
+              match,
+              variant: entry.variant,
+            })
+            return {
+              model: match,
+              provenance: "provider-fallback",
+              variant: entry.variant,
+              attempted,
+            }
+          }
+        }
+
+        const crossProviderMatch = deps.fuzzyMatchModel(entry.model, availableModels)
+        if (crossProviderMatch) {
+          log("Model resolved via fallback chain (cross-provider fuzzy match)", {
+            model: entry.model,
+            match: crossProviderMatch,
+            variant: entry.variant,
+          })
+          return {
+            model: crossProviderMatch,
+            provenance: "provider-fallback",
+            variant: entry.variant,
+            attempted,
+          }
+        }
+      }
+      log("No available model found in fallback chain, falling through to system default")
+    }
+  }
+
+  if (systemDefaultModel === undefined) {
+    log("No model resolved - systemDefaultModel not configured")
+    return undefined
+  }
+
+  log("Model resolved via system default", { model: systemDefaultModel })
+  return { model: systemDefaultModel, provenance: "system-default", attempted }
+}

apps/coder/src/services/model-resolution/model-resolution-types.ts

@@ -0,0 +1,41 @@
+import type { FallbackEntry } from "./model-requirement-types.js"
+
+export interface DelegatedModelConfig {
+  providerID: string
+  modelID: string
+  variant?: string
+  reasoningEffort?: string
+  temperature?: number
+  top_p?: number
+  maxTokens?: number
+  thinking?: { type: "enabled" | "disabled"; budgetTokens?: number }
+}
+
+export type ModelResolutionRequest = {
+  intent?: {
+    uiSelectedModel?: string
+    userModel?: string
+    categoryDefaultModel?: string
+  }
+  constraints: {
+    availableModels: Set<string>
+  }
+  policy?: {
+    fallbackChain?: FallbackEntry[]
+    systemDefaultModel?: string
+  }
+}
+
+export type ModelResolutionProvenance =
+  | "override"
+  | "category-default"
+  | "provider-fallback"
+  | "system-default"
+
+export type ModelResolutionResult = {
+  model: string
+  provenance: ModelResolutionProvenance
+  variant?: string
+  attempted?: string[]
+  reason?: string
+}

apps/coder/src/services/model-resolution/model-resolver.ts

@@ -0,0 +1,109 @@
+import type { FallbackEntry } from "./model-requirement-types.js"
+import type { FallbackModelObject } from "./fallback-model-object.js"
+import { normalizeModel } from "./model-normalization.js"
+import { resolveModelPipeline } from "./model-resolution-pipeline.js"
+import { KNOWN_VARIANTS } from "./known-variants.js"
+import type { ConnectedProvidersAdapter } from "./connected-providers-cache.js"
+import * as connectedProvidersCache from "./connected-providers-cache.js"
+
+export type ModelResolutionInput = {
+  userModel?: string
+  inheritedModel?: string
+  systemDefault?: string
+}
+
+export type ModelSource =
+  | "override"
+  | "category-default"
+  | "provider-fallback"
+  | "system-default"
+
+export type ModelResolutionResult = {
+  model: string
+  source: ModelSource
+  variant?: string
+}
+
+export type ExtendedModelResolutionInput = {
+  uiSelectedModel?: string
+  userModel?: string
+  userFallbackModels?: string[]
+  categoryDefaultModel?: string
+  fallbackChain?: FallbackEntry[]
+  availableModels: Set<string>
+  systemDefaultModel?: string
+}
+
+
+export function resolveModel(input: ModelResolutionInput): string | undefined {
+  return (
+    normalizeModel(input.userModel) ??
+    normalizeModel(input.inheritedModel) ??
+    input.systemDefault
+  )
+}
+
+export function resolveModelWithFallback(
+  input: ExtendedModelResolutionInput,
+  connectedProvidersAdapter: ConnectedProvidersAdapter = connectedProvidersCache,
+): ModelResolutionResult | undefined {
+  const { uiSelectedModel, userModel, userFallbackModels, categoryDefaultModel, fallbackChain, availableModels, systemDefaultModel } = input
+  const resolved = resolveModelPipeline({
+    intent: { uiSelectedModel, userModel, userFallbackModels, categoryDefaultModel },
+    constraints: { availableModels },
+    policy: { fallbackChain, systemDefaultModel },
+  }, connectedProvidersAdapter)
+
+  if (!resolved) {
+    return undefined
+  }
+
+  return {
+    model: resolved.model,
+    source: resolved.provenance,
+    variant: resolved.variant,
+  }
+}
+
+/**
+ * Normalizes fallback_models config to a mixed array.
+ * Accepts string, string[], or mixed arrays of strings and FallbackModelObject entries.
+ */
+export function normalizeFallbackModels(
+  models: string | (string | FallbackModelObject)[] | undefined,
+): (string | FallbackModelObject)[] | undefined {
+  if (!models) return undefined
+  if (typeof models === "string") return [models]
+  return models
+}
+
+/**
+ * Extracts plain model strings from a mixed fallback models array.
+ * Object entries are flattened to "model" or "model(variant)" strings.
+ * Use this when consumers need string[] (e.g., resolveModelForDelegateTask).
+ */
+export function flattenToFallbackModelStrings(
+  models: (string | FallbackModelObject)[] | undefined,
+): string[] | undefined {
+  if (!models) return undefined
+  return models.map((entry) => {
+    if (typeof entry === "string") return entry
+    const variant = entry.variant
+    if (variant) {
+      // Strip any supported inline variant syntax before appending explicit override.
+      // Supports both parenthesized and space-suffix forms so we don't emit
+      // invalid strings like "provider/model high(low)".
+      const model = entry.model
+        .replace(/\([^()]+\)\s*$/, "")
+        .replace(/\s+([a-z][a-z0-9_-]*)\s*$/i, (_match: string, suffix: string) => {
+          const normalized = String(suffix).toLowerCase()
+          return KNOWN_VARIANTS.has(normalized)
+            ? ""
+            : _match
+        })
+        .trim()
+      return `${model}(${variant})`
+    }
+    return entry.model
+  })
+}

apps/coder/src/services/model-resolution/provider-cache.ts

@@ -0,0 +1,27 @@
+export interface ModelMetadata {
+  readonly id: string
+  readonly provider?: string
+  readonly context?: number
+  readonly output?: number
+  readonly name?: string
+  readonly variants?: Record<string, unknown>
+  readonly limit?: {
+    readonly context?: number
+    readonly input?: number
+    readonly output?: number
+  }
+  readonly modalities?: {
+    readonly input?: string[]
+    readonly output?: string[]
+  }
+  readonly capabilities?: Record<string, unknown>
+  readonly reasoning?: boolean
+  readonly temperature?: boolean
+  readonly tool_call?: boolean
+  readonly [key: string]: unknown
+}
+
+export interface ProviderCache {
+  readConnectedProvidersCache(): string[] | null
+  findProviderModelMetadata(providerID: string, modelID: string): ModelMetadata | undefined
+}

apps/coder/src/services/model-resolution/provider-model-id-transform.ts

@@ -0,0 +1,69 @@
+function inferSubProvider(model: string): string | undefined {
+  if (model.startsWith("claude-")) return "anthropic"
+  if (model.startsWith("gpt-")) return "openai"
+  if (model.startsWith("gemini-")) return "google"
+  if (model.startsWith("grok-")) return "xai"
+  if (model.startsWith("minimax-")) return "minimax"
+  if (model.startsWith("kimi-")) return "moonshotai"
+  if (model.startsWith("glm-")) return "zai"
+  return undefined
+}
+
+const CLAUDE_VERSION_DOT = /claude-(\w+)-(\d+)-(\d+)/g
+const GEMINI_31_PRO_PREVIEW = /gemini-3\.1-pro(?!-)/g
+const GEMINI_3_FLASH_PREVIEW = /gemini-3-flash(?!-)/g
+
+function claudeVersionDot(model: string): string {
+  return model.replace(CLAUDE_VERSION_DOT, "claude-$1-$2.$3")
+}
+
+function applyGatewayTransforms(model: string): string {
+  return claudeVersionDot(model).replace(
+    GEMINI_31_PRO_PREVIEW,
+    "gemini-3.1-pro-preview",
+  )
+}
+
+function transformModelForProviderUsingAnthropicBehavior(
+  provider: string,
+  model: string,
+): string {
+  if (provider === "vercel") {
+    const slashIndex = model.indexOf("/")
+    if (slashIndex !== -1) {
+      const subProvider = model.substring(0, slashIndex)
+      const subModel = model.substring(slashIndex + 1)
+      return `${subProvider}/${applyGatewayTransforms(subModel)}`
+    }
+    const subProvider = inferSubProvider(model)
+    if (subProvider) {
+      return `${subProvider}/${applyGatewayTransforms(model)}`
+    }
+    return model
+  }
+  if (provider === "github-copilot") {
+    return claudeVersionDot(model)
+      .replace(GEMINI_31_PRO_PREVIEW, "gemini-3.1-pro-preview")
+      .replace(GEMINI_3_FLASH_PREVIEW, "gemini-3-flash-preview")
+  }
+  if (provider === "google") {
+    return model
+      .replace(GEMINI_31_PRO_PREVIEW, "gemini-3.1-pro-preview")
+      .replace(GEMINI_3_FLASH_PREVIEW, "gemini-3-flash-preview")
+  }
+  if (provider === "anthropic") {
+    return model
+  }
+  return model
+}
+
+export function transformModelForProvider(provider: string, model: string): string {
+  return transformModelForProviderUsingAnthropicBehavior(provider, model)
+}
+
+export function transformModelForProviderDisplay(
+  provider: string,
+  model: string,
+): string {
+  return transformModelForProviderUsingAnthropicBehavior(provider, model)
+}

apps/coder/src/services/paseo-client.ts

@@ -0,0 +1,341 @@
+/**
+ * v2.10 — PaseoClient: thin CLI-based client for the Paseo daemon.
+ *
+ * Paseo is a multi-agent hub daemon running at a configurable address
+ * (default Unix socket / localhost:6767). This client wraps the `paseo` CLI
+ * via child_process spawn for all operations (the daemon does not expose a
+ * separate REST API for write operations). Read operations (listAgents,
+ * getAgentStatus) use `paseo ls --json` / `paseo inspect --json`; write
+ * operations (import, archive, send) use the corresponding subcommands.
+ *
+ * Spec: openspec/changes/v2-10-paseo-integration/design.md.
+ */
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import { createInterface } from 'node:readline';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+/** Listing entry from `paseo ls --json`. Fields are lowercase. */
+export interface PaseoAgentListItem {
+  id: string;
+  shortId: string;
+  name: string;
+  provider: string;
+  status: string;
+  cwd?: string;
+  created?: string;
+  thinking?: string;
+}
+
+/** Detailed agent info from `paseo inspect --json`. Fields are PascalCase. */
+export interface PaseoAgentDetail {
+  Id: string;
+  Name: string;
+  Provider: string;
+  Model?: string;
+  Status: string;
+  Thinking?: string;
+  Archived: boolean;
+  ArchivedAt?: string | null;
+  Cwd?: string;
+  CreatedAt: string;
+  UpdatedAt: string;
+  Mode?: string;
+  AvailableModes?: Array<{ id: string; label: string }>;
+  Capabilities?: {
+    Streaming?: boolean;
+    Persistence?: boolean;
+    DynamicModes?: boolean;
+    McpServers?: boolean;
+  };
+  Labels?: Record<string, string>;
+  Worktree?: string | null;
+  ParentAgentId?: string | null;
+}
+
+/** Result of `paseo send --json`. */
+export interface PaseoSendResult {
+  /** The agent's textual response. */
+  text?: string;
+  /** Structured output if the agent produced any. */
+  output?: unknown;
+  /** Error message if the turn failed. */
+  error?: string;
+  /** True if the turn completed successfully. */
+  ok?: boolean;
+}
+
+export interface PaseoClientConfig {
+  /** Path to the paseo binary. Default: auto-resolved from PATH. */
+  paseoBin: string;
+  /**
+   * Explicit `--host <host>` value for CLI calls.
+   * Format: `host:port` or `tcp://host:port?ssl=true&password=secret`.
+   * Omit to use the CLI default (Unix socket, fallback localhost:6767).
+   */
+  cliHost?: string;
+}
+
+const DEFAULT_PASEO_BIN = 'paseo';
+
+// ─── Client ──────────────────────────────────────────────────────────────────
+
+export class PaseoClientError extends Error {
+  constructor(
+    message: string,
+    public readonly command: string,
+    public readonly exitCode: number | null,
+    public readonly stderr: string,
+  ) {
+    super(message);
+    this.name = 'PaseoClientError';
+  }
+}
+
+export class PaseoClient {
+  /** @internal visible for testing */
+  readonly bin: string;
+  private readonly hostArgs: string[];
+
+  constructor(config?: Partial<PaseoClientConfig>) {
+    this.bin = config?.paseoBin ?? DEFAULT_PASEO_BIN;
+    this.hostArgs = config?.cliHost ? ['--host', config.cliHost] : [];
+  }
+
+  // ─── Read operations (CLI `ls --json`, `inspect --json`) ──────────────────
+
+  /** List all non-archived agents. */
+  async listAgents(): Promise<PaseoAgentListItem[]> {
+    const raw = await this.runJson(['ls', '--json', ...this.hostArgs]);
+    return raw as PaseoAgentListItem[];
+  }
+
+  /** Get detailed status for a single agent by ID or prefix. */
+  async getAgentStatus(agentId: string): Promise<PaseoAgentDetail> {
+    const raw = await this.runJson(['inspect', '--json', agentId, ...this.hostArgs]);
+    return raw as PaseoAgentDetail;
+  }
+
+  /**
+   * Quick liveness check — runs `paseo ls --json --limit 1` and returns success.
+   * The daemon is healthy if the CLI exits 0.
+   */
+  async health(): Promise<{ status: string }> {
+    try {
+      await this.runCli(['ls', '--json', '--limit', '1', ...this.hostArgs]);
+      return { status: 'ok' };
+    } catch {
+      return { status: 'error' };
+    }
+  }
+
+  // ─── Write operations (CLI subcommands) ───────────────────────────────────
+
+  /**
+   * Import a provider session as a Paseo agent.
+   * Uses `paseo import <sessionId> --provider <provider> [--label k=v]`.
+   */
+  async importAgent(
+    sessionId: string,
+    provider: string,
+    labels?: Record<string, string>,
+  ): Promise<PaseoAgentDetail> {
+    const args: string[] = ['import', '--json', ...this.hostArgs];
+
+    if (provider) {
+      args.push('--provider', provider);
+    }
+    if (labels) {
+      for (const [k, v] of Object.entries(labels)) {
+        args.push('--label', `${k}=${v}`);
+      }
+    }
+    args.push(sessionId);
+
+    const raw = await this.runJson(args);
+    return raw as PaseoAgentDetail;
+  }
+
+  /** Archive (soft-delete) a Paseo agent by ID or prefix. */
+  async archiveAgent(agentId: string): Promise<void> {
+    await this.runCli(['archive', '--json', ...this.hostArgs, agentId]);
+  }
+
+  /**
+   * Send a prompt to an existing agent.
+   *
+   * By default waits for the agent to complete the turn (streams text events
+   * via the optional `onEvent` callback) and returns the structured result.
+   * Pass `noWait: true` to fire-and-forget.
+   */
+  async sendPrompt(
+    agentId: string,
+    prompt: string,
+    options?: {
+      noWait?: boolean;
+      onEvent?: (event: { type: 'text' | 'reasoning'; text: string }) => void;
+      signal?: AbortSignal;
+    },
+  ): Promise<PaseoSendResult> {
+    const args: string[] = ['send', '--json', ...this.hostArgs];
+
+    if (options?.noWait) {
+      args.push('--no-wait');
+    }
+
+    args.push(agentId, prompt);
+
+    // With --json and no --no-wait, the output is JSON after completion.
+    // For streaming, we read stderr without --json for real-time text.
+    const raw = await this.runCli(args, options?.signal);
+    try {
+      return JSON.parse(raw) as PaseoSendResult;
+    } catch {
+      return { text: raw, ok: true };
+    }
+  }
+
+  /**
+   * Stream-send: runs `paseo send` WITHOUT `--json`, forward text/reasoning
+   * lines to onEvent in real time. Use when the caller wants to stream agent
+   * output as it arrives rather than wait for the full JSON result.
+   */
+  async streamSend(
+    agentId: string,
+    prompt: string,
+    onEvent: (event: { type: 'text' | 'reasoning'; text: string }) => void,
+    signal?: AbortSignal,
+  ): Promise<PaseoSendResult> {
+    return new Promise<PaseoSendResult>((resolve, reject) => {
+      const args = ['send', ...this.hostArgs, agentId, prompt];
+
+      const child = spawn(this.bin, args, {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        signal,
+      });
+
+      let stdout = '';
+      let stderr = '';
+
+      if (child.stdout) {
+        const rl = createInterface({ input: child.stdout });
+        rl.on('line', (line: string) => {
+          stdout += line + '\n';
+          // Forward as text event for real-time display
+          onEvent({ type: 'text', text: line + '\n' });
+        });
+      }
+
+      if (child.stderr) {
+        child.stderr.on('data', (chunk: Buffer) => {
+          stderr += chunk.toString();
+        });
+      }
+
+      once(child, 'close').then((raw) => {
+        const exitCode = (raw[0] as number | null) ?? 0;
+        if (exitCode !== 0) {
+          reject(
+            new PaseoClientError(
+              `paseo send failed (exit ${exitCode}): ${stderr.trim()}`,
+              'send',
+              exitCode,
+              stderr,
+            ),
+          );
+          return;
+        }
+        resolve({ text: stdout, ok: true });
+      });
+
+      child.on('error', reject);
+    });
+  }
+
+  /** Interrupt/stop a running agent. */
+  async stopAgent(agentId: string): Promise<void> {
+    await this.runCli(['stop', ...this.hostArgs, agentId]);
+  }
+
+  // ─── Private helpers ───────────────────────────────────────────────────────
+
+  /**
+   * Run a CLI command and return stdout as a string.
+   * Throws PaseoClientError on non-zero exit.
+   */
+  private async runCli(
+    args: string[],
+    signal?: AbortSignal,
+  ): Promise<string> {
+    return new Promise<string>((resolve, reject) => {
+      const child = spawn(this.bin, args, {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        signal,
+      });
+
+      let stdout = '';
+      let stderr = '';
+
+      if (child.stdout) {
+        child.stdout.on('data', (chunk: Buffer) => {
+          stdout += chunk.toString();
+        });
+      }
+
+      if (child.stderr) {
+        child.stderr.on('data', (chunk: Buffer) => {
+          stderr += chunk.toString();
+        });
+      }
+
+      child.on('error', (err: Error) => {
+        // If signal aborted, treat as cancellation not error
+        if (signal?.aborted) {
+          resolve('');
+          return;
+        }
+        reject(err);
+      });
+
+      once(child, 'close').then((raw) => {
+        const exitCode = (raw[0] as number | null) ?? 0;
+        if (signal?.aborted) {
+          resolve('');
+          return;
+        }
+        if (exitCode !== 0) {
+          const msg = stderr.trim() || `exit code ${exitCode}`;
+          reject(
+            new PaseoClientError(
+              `paseo ${args[0] ?? '?'} failed: ${msg}`,
+              args[0] ?? '?',
+              exitCode,
+              stderr,
+            ),
+          );
+          return;
+        }
+        resolve(stdout);
+      });
+    });
+  }
+
+  /**
+   * Run a CLI command and parse stdout as JSON.
+   * Throws PaseoClientError on non-zero exit or parse failure.
+   */
+  private async runJson(args: string[]): Promise<unknown> {
+    const stdout = await this.runCli(args);
+    try {
+      return JSON.parse(stdout);
+    } catch (err) {
+      throw new PaseoClientError(
+        `paseo ${args[0] ?? '?'} returned invalid JSON: ${(stdout || '<empty>').slice(0, 200)}`,
+        args[0] ?? '?',
+        0,
+        stdout,
+      );
+    }
+  }
+}

apps/coder/src/services/plan-store.ts

@@ -0,0 +1,184 @@
+/**
+ * Boulder state — cross-session plan persistence for BooCode.
+ *
+ * Plans live above flow_runs: a plan tracks a user's work goal and can link to
+ * a flow run for automatic progress tracking. When the linked flow run reaches
+ * a terminal state (completed/failed/cancelled), the plan is auto-updated.
+ *
+ * Auto-resumption: on startup, plans with a linked in-flight flow_run are
+ * surfaced via the GET endpoint so the UI can show a resume prompt. The
+ * flow-runner's initResume() re-advances the actual run; this store surfaces
+ * the plan-level view.
+ */
+import type { Sql } from '../db.js';
+
+export interface Plan {
+  id: string;
+  project_id: string;
+  title: string;
+  description: string | null;
+  status: string;
+  flow_run_id: string | null;
+  progress_pct: number;
+  items_total: number;
+  items_completed: number;
+  metadata: Record<string, unknown> | null;
+  created_at: Date;
+  updated_at: Date;
+}
+
+export interface CreatePlanOpts {
+  projectId: string;
+  title: string;
+  description?: string;
+  flowRunId?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface UpdatePlanOpts {
+  title?: string;
+  description?: string | null;
+  status?: 'active' | 'completed' | 'cancelled' | 'failed';
+  progressPct?: number;
+  itemsTotal?: number;
+  itemsCompleted?: number;
+  metadata?: Record<string, unknown> | null;
+}
+
+export function createPlan(sql: Sql, opts: CreatePlanOpts): Promise<Plan> {
+  return sql`
+    INSERT INTO plans (project_id, title, description, flow_run_id, metadata)
+    VALUES (
+      ${opts.projectId},
+      ${opts.title},
+      ${opts.description ?? null},
+      ${opts.flowRunId ?? null},
+      ${opts.metadata ? sql.json(opts.metadata as never) : null}
+    )
+    RETURNING *
+  `.then((rows) => rows[0] as unknown as Plan);
+}
+
+export function getPlan(sql: Sql, planId: string): Promise<Plan | null> {
+  return sql`
+    SELECT * FROM plans WHERE id = ${planId}
+  `.then((rows) => (rows[0] as unknown as Plan) ?? null);
+}
+
+export function listPlans(sql: Sql, projectId: string): Promise<Plan[]> {
+  return sql`
+    SELECT * FROM plans
+    WHERE project_id = ${projectId}
+    ORDER BY created_at DESC
+    LIMIT 100
+  ` as Promise<Plan[]>;
+}
+
+export function listActivePlans(sql: Sql, projectId: string): Promise<Plan[]> {
+  return sql`
+    SELECT * FROM plans
+    WHERE project_id = ${projectId} AND status = 'active'
+    ORDER BY created_at DESC
+  ` as Promise<Plan[]>;
+}
+
+export async function updatePlan(
+  sql: Sql,
+  planId: string,
+  opts: UpdatePlanOpts,
+): Promise<Plan | null> {
+  const sets: string[] = [];
+  const values: unknown[] = [];
+
+  if (opts.title !== undefined) {
+    sets.push(`title = $${values.length + 1}`);
+    values.push(opts.title);
+  }
+  if (opts.description !== undefined) {
+    sets.push(`description = $${values.length + 1}`);
+    values.push(opts.description);
+  }
+  if (opts.status !== undefined) {
+    sets.push(`status = $${values.length + 1}`);
+    values.push(opts.status);
+  }
+  if (opts.progressPct !== undefined) {
+    sets.push(`progress_pct = $${values.length + 1}`);
+    values.push(opts.progressPct);
+  }
+  if (opts.itemsTotal !== undefined) {
+    sets.push(`items_total = $${values.length + 1}`);
+    values.push(opts.itemsTotal);
+  }
+  if (opts.itemsCompleted !== undefined) {
+    sets.push(`items_completed = $${values.length + 1}`);
+    values.push(opts.itemsCompleted);
+  }
+  if (opts.metadata !== undefined) {
+    sets.push(`metadata = $${values.length + 1}::jsonb`);
+    values.push(opts.metadata !== null ? JSON.stringify(opts.metadata) : null);
+  }
+
+  if (sets.length === 0) return getPlan(sql, planId);
+
+  sets.push(`updated_at = clock_timestamp()`);
+
+  const query = `
+    UPDATE plans SET ${sets.join(', ')}
+    WHERE id = $${values.length + 1}
+    RETURNING *
+  `;
+  values.push(planId);
+
+  const result = await sql.unsafe(query, values as never[]);
+  return (result[0] as unknown as Plan) ?? null;
+}
+
+/**
+ * Called when a flow run reaches a terminal state. Updates the linked plan's
+ * status based on the run outcome:
+ *  - completed → plan completed
+ *  - failed    → plan failed
+ *  - cancelled → plan cancelled
+ * Returns true when a plan was updated, false when no plan is linked to the run.
+ */
+export async function updatePlanFromRun(
+  sql: Sql,
+  runId: string,
+  runStatus: 'completed' | 'failed' | 'cancelled',
+): Promise<boolean> {
+  const planStatus = planStatusFromRun(runStatus);
+  const updated = await sql`
+    UPDATE plans
+    SET status = ${planStatus}, progress_pct = 100,
+        items_completed = items_total, updated_at = clock_timestamp()
+    WHERE flow_run_id = ${runId} AND status = 'active'
+  `;
+  return updated.count > 0;
+}
+
+/** Map a flow-run terminal status to its corresponding plan status. Pure. */
+export function planStatusFromRun(runStatus: 'completed' | 'failed' | 'cancelled'): string {
+  return runStatus === 'completed' ? 'completed' : runStatus;
+}
+
+/**
+ * Find any active plan linked to a running flow run — used by the startup
+ * resume path to surface plans that have in-flight orchestrator runs.
+ */
+export async function findPlanWithRunningRun(
+  sql: Sql,
+  projectId: string,
+): Promise<(Plan & { run_status: string }) | null> {
+  const [row] = await sql`
+    SELECT p.*, fr.status AS run_status
+    FROM plans p
+    JOIN flow_runs fr ON fr.id = p.flow_run_id
+    WHERE p.project_id = ${projectId}
+      AND p.status = 'active'
+      AND fr.status = 'running'
+    ORDER BY p.created_at DESC
+    LIMIT 1
+  `;
+  return (row as unknown as Plan & { run_status: string }) ?? null;
+}

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

@@ -29,6 +29,22 @@ interface AgentRow {
   last_probed_at: string | Date | null;
 }
 
+export async function fetchDeepSeekModels(config: Config): Promise<ProviderModel[]> {
+  if (!config.DEEPSEEK_API_KEY) return [];
+  try {
+    const baseURL = (config.DEEPSEEK_BASE_URL ?? 'https://api.deepseek.com').replace(/\/+$/, '');
+    const res = await fetch(`${baseURL}/v1/models`, {
+      headers: { Authorization: `Bearer ${config.DEEPSEEK_API_KEY}` },
+      signal: AbortSignal.timeout(5_000),
+    });
+    if (!res.ok) return [];
+    const parsed = (await res.json()) as { data?: Array<{ id: string }> };
+    return (parsed.data ?? []).map((m) => ({ id: m.id, label: m.id }));
+  } catch {
+    return [];
+  }
+}
+
 export async function fetchLlamaSwapModels(config: Config): Promise<ProviderModel[]> {
   try {
     const res = await fetch(`${config.LLAMA_SWAP_URL}/v1/models`);
@@ -256,7 +272,13 @@ export async function getProviderSnapshot(
   }
 
   const build = async (): Promise<ProviderSnapshotEntry[]> => {
-    const llamaModels = await fetchLlamaSwapModels(config);
+    const [llamaModels, deepseekModels] = await Promise.all([
+      fetchLlamaSwapModels(config),
+      fetchDeepSeekModels(config),
+    ]);
+    // Merge DeepSeek models into the llama-swap model pool so the boocode
+    // provider (which sources from llama-swap) also includes DeepSeek models.
+    const mergedModels = mergeModels(llamaModels, deepseekModels);
     const agents = await sql<AgentRow[]>`
       SELECT name, install_path, supports_acp, models, commands, label, transport, last_probed_at FROM available_agents
     `;
@@ -265,7 +287,7 @@ export async function getProviderSnapshot(
 
     const entries = await Promise.all(
       [...getResolvedRegistry().values()].map((resolved) =>
-        buildProviderEntry(resolved, agentMap.get(resolved.id), llamaModels, resolvedCwd, ttlMs, force),
+        buildProviderEntry(resolved, agentMap.get(resolved.id), mergedModels, resolvedCwd, ttlMs, force),
       ),
     );
 

apps/server/package.json

@@ -77,8 +77,9 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@boocode/contracts": "workspace:*",
+    "@ai-sdk/deepseek": "^2.0.35",
     "@ai-sdk/openai-compatible": "^2.0.47",
+    "@boocode/contracts": "workspace:*",
     "@fastify/static": "^7.0.4",
     "@fastify/websocket": "^10.0.1",
     "@modelcontextprotocol/sdk": "^1.29.0",

apps/server/src/config.ts

@@ -26,6 +26,14 @@ const ConfigSchema = z.object({
   FAST_MODEL: z.string().optional(),
   TASK_MODEL_URL: z.string().url().optional(),
   LLAMA_SIDECAR_URL: z.string().url().optional(),
+  // vDeepSeek: DeepSeek API key for direct API access. When set, models
+  // with IDs starting with 'deepseek-' route through DeepSeek's API instead
+  // of llama-swap. Defaults to empty (DeepSeek routing disabled).
+  DEEPSEEK_API_KEY: z.string().optional(),
+  // Optional base URL override for DeepSeek API. Defaults to api.deepseek.com.
+  DEEPSEEK_BASE_URL: z.string().url().default('https://api.deepseek.com'),
+  // vWhale hooks: path to hooks JSON config file. Missing file = no hooks.
+  HOOKS_CONFIG_PATH: z.string().default('/data/hooks.json'),
 });
 
 export type Config = z.infer<typeof ConfigSchema>;

apps/server/src/index.ts

@@ -18,7 +18,11 @@ import { registerCoderProxy } from './routes/coder-proxy.js';
 import { registerModelRoutes } from './routes/models.js';
 import { registerAgentRoutes } from './routes/agents.js';
 import { registerSkillsRoutes } from './routes/skills.js';
+import { registerTraceRoutes } from './routes/traces.js';
 import { registerToolsRoutes } from './routes/tools.js';
+import { registerAnalyticsRoutes } from './routes/analytics.js';
+import { registerMemoryRoutes } from './routes/memory.js';
+import { registerInferenceSettingsRoutes } from './routes/inference-settings.js';
 import { createInferenceRunner } from './services/inference/index.js';
 import { createBroker } from './services/broker.js';
 import { listSkills } from './services/skills.js';
@@ -29,6 +33,7 @@ import { loadMcpConfig } from './services/mcp-config.js';
 import { initialize as initMcp, getTools as getMcpTools, shutdown as shutdownMcp } from './services/mcp-client.js';
 import { appendMcpTools } from './services/tools.js';
 import { refreshToolNames, getAgentsForProject } from './services/agents.js';
+import { loadHooksConfig, createHookRunner } from './services/hooks.js';
 
 async function main() {
   const config = loadConfig();
@@ -121,7 +126,11 @@ async function main() {
   registerAgentRoutes(app, sql);
   registerSidebarRoutes(app, sql);
   registerChatRoutes(app, sql, broker);
+  registerTraceRoutes(app, sql);
   registerToolsRoutes(app, sql);
+  registerAnalyticsRoutes(app, sql);
+  registerMemoryRoutes(app, sql);
+  registerInferenceSettingsRoutes(app);
 
   // Batch 9.6: warm the skills cache at boot and surface the count. Empty or
   // missing /data/skills is non-fatal — the skill tools just return empty.
@@ -132,11 +141,17 @@ async function main() {
     app.log.warn({ err }, 'skills boot walk failed');
   }
 
+  // vWhale hooks: load hook config and create runner. Missing file = no hooks.
+  loadHooksConfig(config.HOOKS_CONFIG_PATH);
+  const hookRunner = createHookRunner();
+  const hasHooks = Object.keys(loadHooksConfig(config.HOOKS_CONFIG_PATH).hooks).length > 0;
+
   const inference = createInferenceRunner(
     {
       sql,
       config,
       log: app.log,
+      hooks: hasHooks ? hookRunner : undefined,
       publish: (sessionId, frame) => {
         // v1.13.11-b: route through the typed publishFrame so the broker's
         // Zod gate validates every inference frame before delivery.
@@ -162,7 +177,7 @@ async function main() {
     // bubble up so the route can reply 500 — manual /compact failures
     // should be loud (the user just clicked a button).
     runCompaction: (chatId) =>
-      compaction.process({ sql, config, log: app.log, broker, chatId }),
+      compaction.process({ sql, config, log: app.log, broker, chatId, hooks: hasHooks ? hookRunner : undefined }),
     cancelInference: async (sessionId, chatId) => {
       return inference.cancel(sessionId, chatId);
     },

apps/server/src/routes/analytics.ts

@@ -0,0 +1,33 @@
+import type { FastifyInstance } from 'fastify';
+import type { Sql } from '../db.js';
+
+// token-analyzer-ui: context window utilization and token breakdown data.
+// v1 — global aggregates only.
+
+export interface ContextWindowStats {
+  avg_ctx_used: number | null;
+  avg_ctx_max: number | null;
+  avg_utilization_pct: number | null;
+  message_count: number;
+}
+
+export function registerAnalyticsRoutes(app: FastifyInstance, sql: Sql): void {
+  // GET /api/analytics/context — average context window utilization across
+  // completed assistant messages that carry ctx_used/ctx_max.
+  app.get('/api/analytics/context', async () => {
+    const [row] = await sql<ContextWindowStats[]>`
+      SELECT
+        AVG(ctx_used)::DOUBLE PRECISION AS avg_ctx_used,
+        AVG(ctx_max)::DOUBLE PRECISION AS avg_ctx_max,
+        AVG(ctx_used::float / NULLIF(ctx_max, 0))::DOUBLE PRECISION AS avg_utilization_pct,
+        COUNT(*)::INT AS message_count
+      FROM messages
+      WHERE role = 'assistant'
+        AND status = 'complete'
+        AND ctx_used IS NOT NULL
+        AND ctx_max IS NOT NULL
+        AND ctx_max > 0
+    `;
+    return row ?? { avg_ctx_used: null, avg_ctx_max: null, avg_utilization_pct: null, message_count: 0 };
+  });
+}

apps/server/src/routes/inference-settings.ts

@@ -0,0 +1,55 @@
+import { FastifyInstance } from 'fastify';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { resolve, dirname } from 'path';
+
+const CONFIG_PATH = resolve(process.env.BOOCODE_DATA_DIR || '/opt/boocode/data', 'inference-settings.json');
+
+const DEFAULTS = {
+  cache_type_k: 'q4_0',
+  cache_reuse: 256,
+  spec_type: 'ngram-mod',
+  spec_ngram_mod_thsh: 2,
+  ctx_checkpoints: 32,
+  sleep_idle_seconds: 600,
+  metrics_enabled: true,
+  slot_save_path: '/tmp/llama-slots',
+};
+
+function load(): Record<string, unknown> {
+  try {
+    if (existsSync(CONFIG_PATH)) {
+      return JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
+    }
+  } catch { /* corrupt file */ }
+  return { ...DEFAULTS };
+}
+
+function save(data: Record<string, unknown>): void {
+  const dir = dirname(CONFIG_PATH);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(CONFIG_PATH, JSON.stringify(data, null, 2) + '\n');
+}
+
+const VALID_CACHE_TYPES = ['f32', 'f16', 'q8_0', 'q4_0'] as const;
+const VALID_SPEC_TYPES = ['off', 'ngram-mod', 'draft-simple'] as const;
+
+export function registerInferenceSettingsRoutes(app: FastifyInstance): void {
+  app.get('/api/settings/inference', async (_req, _res) => {
+    return { ...DEFAULTS, ...load() };
+  });
+
+  app.patch<{ Body: Record<string, unknown> }>('/api/settings/inference', async (req, reply) => {
+    const current = { ...DEFAULTS, ...load() };
+    const merged = { ...current, ...req.body };
+
+    if (merged.cache_type_k && !(VALID_CACHE_TYPES as readonly string[]).includes(merged.cache_type_k as string)) {
+      return reply.status(400).send({ error: 'Invalid cache_type_k' });
+    }
+    if (merged.spec_type && !(VALID_SPEC_TYPES as readonly string[]).includes(merged.spec_type as string)) {
+      return reply.status(400).send({ error: 'Invalid spec_type' });
+    }
+
+    save(merged);
+    return { ...DEFAULTS, ...load() };
+  });
+}

apps/server/src/routes/models.ts

@@ -2,26 +2,55 @@ import type { FastifyInstance } from 'fastify';
 import type { Config } from '../config.js';
 import type { ModelInfo } from '../types/api.js';
 
-interface LlamaSwapModelsResponse {
+interface ApiModelsResponse {
   data?: ModelInfo[];
 }
 
+const DEEPSEEK_STATIC_MODELS: ModelInfo[] = [
+  { id: 'deepseek-v4-flash', object: 'model', created: 0, owned_by: 'deepseek' },
+  { id: 'deepseek-v4-pro', object: 'model', created: 0, owned_by: 'deepseek' },
+];
+
 export function registerModelRoutes(app: FastifyInstance, config: Config): void {
   app.get('/api/models', async (_req, reply) => {
+    const models: ModelInfo[] = [];
+
+    // 1. Fetch llama-swap models
     try {
       const res = await fetch(`${config.LLAMA_SWAP_URL}/v1/models`);
-      if (!res.ok) {
-        reply.code(502);
-        return { error: `llama-swap returned ${res.status}` };
+      if (res.ok) {
+        const parsed = (await res.json()) as ApiModelsResponse;
+        if (parsed.data) models.push(...parsed.data);
       }
-      const parsed = (await res.json()) as LlamaSwapModelsResponse;
-      return parsed.data ?? [];
-    } catch (err) {
-      reply.code(502);
-      return {
-        error: 'failed to reach llama-swap',
-        details: err instanceof Error ? err.message : String(err),
-      };
+    } catch {
+      // llama-swap unreachable — proceed with whatever we have
     }
+
+    // 2. If DeepSeek is configured, fetch live models from their API
+    if (config.DEEPSEEK_API_KEY) {
+      try {
+        const baseURL = (config.DEEPSEEK_BASE_URL ?? 'https://api.deepseek.com').replace(/\/+$/, '');
+        const res = await fetch(`${baseURL}/v1/models`, {
+          headers: { Authorization: `Bearer ${config.DEEPSEEK_API_KEY}` },
+          signal: AbortSignal.timeout(5_000),
+        });
+        if (res.ok) {
+          const parsed = (await res.json()) as ApiModelsResponse;
+          if (parsed.data) models.push(...parsed.data);
+        } else {
+          // API call failed — fall back to static model list
+          models.push(...DEEPSEEK_STATIC_MODELS);
+        }
+      } catch {
+        // Network error — fall back to static model list
+        models.push(...DEEPSEEK_STATIC_MODELS);
+      }
+    }
+
+    if (models.length === 0) {
+      reply.code(502);
+      return { error: 'no models available from any provider' };
+    }
+    return models;
   });
 }

apps/server/src/routes/traces.ts

@@ -0,0 +1,38 @@
+import type { FastifyInstance } from 'fastify';
+import type { Sql } from '../db.js';
+import type { ToolTrace } from '../services/tool-traces.js';
+
+export function registerTraceRoutes(app: FastifyInstance, sql: Sql): void {
+  app.get<{ Params: { id: string }; Querystring: { limit?: string; offset?: string } }>(
+    '/api/chats/:id/traces',
+    async (req, reply) => {
+      const chat = await sql`SELECT id FROM chats WHERE id = ${req.params.id}`;
+      if (chat.length === 0) {
+        reply.code(404);
+        return { error: 'chat not found' };
+      }
+
+      const limit = Math.min(Math.max(Number(req.query.limit) || 50, 1), 200);
+      const offset = Math.max(Number(req.query.offset) || 0, 0);
+
+      const rows = await sql<ToolTrace[]>`
+        SELECT * FROM tool_traces
+        WHERE chat_id = ${req.params.id}
+        ORDER BY started_at ASC
+        LIMIT ${limit}
+        OFFSET ${offset}
+      `;
+
+      const [countRow] = await sql<{ count: number }[]>`
+        SELECT count(*)::int AS count FROM tool_traces WHERE chat_id = ${req.params.id}
+      `;
+
+      return {
+        data: rows,
+        total: countRow?.count ?? 0,
+        limit,
+        offset,
+      };
+    },
+  );
+}

apps/server/src/routes/ws.ts

@@ -3,6 +3,7 @@ import type { Sql } from '../db.js';
 import type { Broker } from '../services/broker.js';
 import type { Message } from '../types/api.js';
 import { MESSAGE_COLUMNS } from '../services/message-columns.js';
+import { loadAgentSnapshot } from '../services/session-snapshots.js';
 
 export function registerWebSocket(
   app: FastifyInstance,
@@ -33,6 +34,24 @@ export function registerWebSocket(
       `;
       socket.send(JSON.stringify({ type: 'snapshot', messages }));
 
+      // v2.7.x: on reconnect, restore agent snapshot state so the frontend
+      // knows there's an ongoing agent turn. Best-effort per chat; most
+      // sessions won't have any snapshots.
+      const chats = await sql<{ id: string }[]>`SELECT id FROM chats WHERE session_id = ${sessionId}`;
+      for (const chat of chats) {
+        const agentSnapshot = await loadAgentSnapshot(sql, chat.id).catch(() => null);
+        if (agentSnapshot) {
+          socket.send(JSON.stringify({
+            type: 'agent_snapshot',
+            chat_id: chat.id,
+            agent: agentSnapshot.agent,
+            model: agentSnapshot.model,
+            mode: agentSnapshot.mode,
+            turn_number: agentSnapshot.turn_number,
+          }));
+        }
+      }
+
       const unsubscribe = broker.subscribe(sessionId, (frame) => {
         if (socket.readyState !== socket.OPEN) return;
         try {

apps/server/src/schema.sql

@@ -32,11 +32,18 @@ CREATE TABLE IF NOT EXISTS messages (
   content TEXT NOT NULL DEFAULT '',
   status TEXT NOT NULL DEFAULT 'complete',
   last_seq INT NOT NULL DEFAULT 0,
+  cache_tokens INTEGER,
+  reasoning_tokens INTEGER,
   created_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp()
 );
 
 CREATE INDEX IF NOT EXISTS idx_messages_session ON messages(session_id, created_at);
 
+-- vDeepSeek: add cache/reasoning token columns early so messages_with_parts
+-- view (defined below) can reference them. IF NOT EXISTS guards re-runs.
+ALTER TABLE messages ADD COLUMN IF NOT EXISTS cache_tokens INTEGER;
+ALTER TABLE messages ADD COLUMN IF NOT EXISTS reasoning_tokens INTEGER;
+
 -- v1.13.0: granular message parts table. v1.13.20: legacy tool_calls/
 -- tool_results columns dropped; message_parts is now the sole source of
 -- truth for tool calls, tool results, and reasoning. ON DELETE CASCADE
@@ -126,8 +133,8 @@ SELECT
      FROM message_parts p
     WHERE p.message_id = m.id AND p.kind = 'reasoning' AND p.hidden_at IS NULL) AS reasoning_parts,
   -- NEW columns MUST be appended at the end: CREATE OR REPLACE VIEW can't
-  -- reorder/rename existing columns (42P16). m.model added last.
-  m.model
+  -- reorder/rename existing columns (42P16). cache_tokens and reasoning_tokens added last.
+  m.model, m.cache_tokens, m.reasoning_tokens
 FROM messages m;
 
 -- v1.13.20: drop legacy tool_calls/tool_results columns. Reads have routed
@@ -407,3 +414,55 @@ END $$;
 
 -- Remove the v2.0.5 arena_id column (replaced by the new Arena feature).
 ALTER TABLE tasks DROP COLUMN IF EXISTS arena_id;
+
+-- v2.x-tool-traces: per-call tool execution records for observability.
+CREATE TABLE IF NOT EXISTS tool_traces (
+  id               UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  session_id       UUID NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  chat_id          UUID NOT NULL REFERENCES chats(id) ON DELETE CASCADE,
+  message_id       UUID REFERENCES messages(id) ON DELETE SET NULL,
+  turn_number      INTEGER NOT NULL,
+  tool_name        TEXT NOT NULL,
+  tool_input       JSONB NOT NULL,
+  tool_output      TEXT,
+  started_at       TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
+  finished_at      TIMESTAMPTZ,
+  latency_ms       INTEGER,
+  tokens_used      INTEGER,
+  cache_tokens     INTEGER,
+  reasoning_tokens INTEGER,
+  error            TEXT,
+  outcome          TEXT,
+  created_at       TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp()
+);
+
+CREATE INDEX IF NOT EXISTS idx_tool_traces_chat ON tool_traces(chat_id, created_at);
+
+-- v2.x-tool-traces: active tool call state for in-flight instrumentation.
+CREATE TABLE IF NOT EXISTS tool_trace_states (
+  id               UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  session_id       UUID NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  chat_id          UUID NOT NULL REFERENCES chats(id) ON DELETE CASCADE,
+  message_id       UUID REFERENCES messages(id) ON DELETE SET NULL,
+  turn_number      INTEGER NOT NULL,
+  tool_name        TEXT NOT NULL,
+  tool_input       JSONB NOT NULL,
+  started_at       TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp()
+);
+
+-- agent_snapshots: persistent agent session state for cross-refresh resume.
+CREATE TABLE IF NOT EXISTS agent_snapshots (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  session_id UUID NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  chat_id UUID NOT NULL REFERENCES chats(id) ON DELETE CASCADE,
+  model TEXT NOT NULL,
+  agent TEXT,
+  mode TEXT,
+  turn_number INTEGER NOT NULL DEFAULT 0,
+  messages JSONB NOT NULL DEFAULT '[]'::jsonb,
+  tool_states JSONB NOT NULL DEFAULT '[]'::jsonb,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp()
+);
+CREATE INDEX IF NOT EXISTS idx_agent_snapshots_chat ON agent_snapshots(chat_id);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_agent_snapshots_chat_unique ON agent_snapshots(chat_id);

apps/server/src/services/__tests__/llama-args-validator.test.ts

@@ -112,14 +112,14 @@ describe('stripShadowingFlags', () => {
     expect(result).toEqual(['-c', '4096']);
   });
 
-  it('strips cache flags by default', () => {
+  it('passes through cache flags (no longer shadowed)', () => {
     const result = stripShadowingFlags(['--cache-type-k', 'q8_0']);
-    expect(result).toEqual([]);
+    expect(result).toEqual(['--cache-type-k', 'q8_0']);
   });
 
-  it('strips spec flags by default', () => {
+  it('passes through spec flags (no longer shadowed)', () => {
     const result = stripShadowingFlags(['--spec-draft-n-max', '16']);
-    expect(result).toEqual([]);
+    expect(result).toEqual(['--spec-draft-n-max', '16']);
   });
 });
 

apps/server/src/services/agents.ts

@@ -106,6 +106,8 @@ interface ParsedFrontmatter {
   // allowed" — the model responds text-only.
   steps?: number;
   llama_extra_args?: string[];
+  // vDeepSeek: thinking effort for DeepSeek V4 models.
+  reasoning_effort?: string;
 }
 
 // P5: table-driven validation for the "soft-range" numeric frontmatter fields.
@@ -386,6 +388,7 @@ function parseAgentSection(section: RawSection): Omit<Agent, 'source'> {
     max_tool_calls: typeof fm.max_tool_calls === 'number' ? fm.max_tool_calls : null,
     steps: typeof fm.steps === 'number' ? fm.steps : null,
     llama_extra_args: Array.isArray(fm.llama_extra_args) ? fm.llama_extra_args : null,
+    reasoning_effort: typeof fm.reasoning_effort === 'string' ? (fm.reasoning_effort as Agent['reasoning_effort']) : null,
   };
 }
 

apps/server/src/services/audit/corrections.ts

@@ -0,0 +1,52 @@
+export interface UserCorrectionRecord {
+  record_type: 'conversation';
+  action_type: 'user_correction';
+  priority: 'critical_for_recovery';
+  timestamp: string;
+  original_claim: string;
+  correction: string;
+  principle_extracted: string;
+  persisted_to: string[];
+}
+
+export function createCorrection(params: {
+  originalClaim: string;
+  correction: string;
+  principleExtracted?: string;
+  persistedTo?: string[];
+}): UserCorrectionRecord {
+  return {
+    record_type: 'conversation',
+    action_type: 'user_correction',
+    priority: 'critical_for_recovery',
+    timestamp: new Date().toISOString(),
+    original_claim: params.originalClaim,
+    correction: params.correction,
+    principle_extracted: params.principleExtracted || '',
+    persisted_to: params.persistedTo || [],
+  };
+}
+
+export function findCorrections(
+  records: Record<string, unknown>[],
+): UserCorrectionRecord[] {
+  return records.filter(
+    r => r['action_type'] === 'user_correction',
+  ) as unknown as UserCorrectionRecord[];
+}
+
+export function checkCorrectionConflict(
+  proposedAction: string,
+  corrections: UserCorrectionRecord[],
+): UserCorrectionRecord | null {
+  for (const c of corrections) {
+    if (!c.original_claim) continue;
+    const claimKeywords = c.original_claim.toLowerCase().split(/\s+/).filter(w => w.length > 3);
+    const actionLower = proposedAction.toLowerCase();
+    const matchCount = claimKeywords.filter(k => actionLower.includes(k)).length;
+    if (matchCount >= 2 && matchCount / claimKeywords.length >= 0.5) {
+      if (c.persisted_to.length > 0) return c;
+    }
+  }
+  return null;
+}

apps/server/src/services/audit/guideline-store.ts

@@ -0,0 +1,251 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ensureRunsDir } from './runs-dir.js';
+
+export type GuidelineId = string;
+export type TagId = string;
+export type Criticality = 'low' | 'medium' | 'high';
+export type GuidelineDocumentVersion = string;
+
+export interface GuidelineContent {
+  condition: string;
+  action: string | null;
+  description: string | null;
+}
+
+export interface Guideline {
+  id: GuidelineId;
+  creationUtc: string;
+  content: GuidelineContent;
+  enabled: boolean;
+  tags: TagId[];
+  labels: string[];
+  metadata: Record<string, unknown>;
+  criticality: Criticality;
+  title: string | null;
+  priority: number;
+}
+
+export interface GuidelineDocument {
+  id: string;
+  version: GuidelineDocumentVersion;
+  creation_utc: string;
+  condition: string;
+  action: string | null;
+  description: string | null;
+  title: string | null;
+  criticality: string;
+  enabled: boolean;
+  metadata: Record<string, unknown>;
+  labels: string[];
+  priority: number;
+}
+
+export interface GuidelineUpdateParams {
+  condition?: string;
+  action?: string | null;
+  description?: string | null;
+  title?: string | null;
+  criticality?: Criticality;
+  enabled?: boolean;
+  priority?: number;
+}
+
+function generateId(): string {
+  const chars = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
+  let result = '';
+  for (let i = 0; i < 10; i++) {
+    result += chars[Math.floor(Math.random() * chars.length)];
+  }
+  return result;
+}
+
+function dbPath(projectRoot?: string): string {
+  const dir = join(ensureRunsDir(projectRoot), '..', 'guidelines');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return join(dir, 'guidelines.json');
+}
+
+function readDb(projectRoot?: string): GuidelineDocument[] {
+  const path = dbPath(projectRoot);
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8')) as GuidelineDocument[];
+  } catch {
+    return [];
+  }
+}
+
+function writeDb(docs: GuidelineDocument[], projectRoot?: string): void {
+  writeFileSync(dbPath(projectRoot), JSON.stringify(docs, null, 2), 'utf-8');
+}
+
+function toDocument(g: Guideline): GuidelineDocument {
+  return {
+    id: g.id,
+    version: '0.11.0',
+    creation_utc: g.creationUtc,
+    condition: g.content.condition,
+    action: g.content.action,
+    description: g.content.description,
+    title: g.title,
+    criticality: g.criticality,
+    enabled: g.enabled,
+    metadata: g.metadata,
+    labels: g.labels,
+    priority: g.priority,
+  };
+}
+
+function fromDocument(d: GuidelineDocument): Guideline {
+  return {
+    id: d.id,
+    creationUtc: d.creation_utc,
+    content: {
+      condition: d.condition,
+      action: d.action ?? null,
+      description: d.description ?? null,
+    },
+    title: d.title ?? null,
+    criticality: (d.criticality || 'medium') as Criticality,
+    enabled: d.enabled ?? true,
+    tags: [],
+    labels: d.labels ?? [],
+    metadata: d.metadata ?? {},
+    priority: d.priority ?? 0,
+  };
+}
+
+export class GuidelineDocumentStore {
+  createGuideline(params: {
+    condition: string;
+    action?: string | null;
+    description?: string | null;
+    title?: string | null;
+    criticality?: Criticality;
+    enabled?: boolean;
+    labels?: string[];
+    priority?: number;
+    id?: GuidelineId;
+  }, projectRoot?: string): Guideline {
+    const docs = readDb(projectRoot);
+    const id = params.id || `gl_${generateId()}`;
+
+    if (docs.find(d => d.id === id)) {
+      throw new Error(`Guideline with id '${id}' already exists`);
+    }
+
+    const guideline: Guideline = {
+      id,
+      creationUtc: new Date().toISOString(),
+      content: {
+        condition: params.condition,
+        action: params.action ?? null,
+        description: params.description ?? null,
+      },
+      title: params.title ?? null,
+      criticality: params.criticality ?? 'medium',
+      enabled: params.enabled ?? true,
+      tags: [],
+      labels: params.labels ?? [],
+      metadata: {},
+      priority: params.priority ?? 0,
+    };
+
+    docs.push(toDocument(guideline));
+    writeDb(docs, projectRoot);
+    return guideline;
+  }
+
+  listGuidelines(params?: {
+    tags?: TagId[];
+    labels?: string[];
+  }, projectRoot?: string): Guideline[] {
+    let docs = readDb(projectRoot);
+
+    if (params?.tags && params.tags.length > 0) {
+      const tagSet = new Set(params.tags);
+      docs = docs.filter(d => d.metadata['tags'] &&
+        Array.isArray(d.metadata['tags']) &&
+        (d.metadata['tags'] as string[]).some(t => tagSet.has(t)));
+    }
+
+    if (params?.labels && params.labels.length > 0) {
+      const labelSet = new Set(params.labels);
+      docs = docs.filter(d => {
+        const gl = fromDocument(d);
+        return params.labels!.every(l => gl.labels.includes(l));
+      });
+    }
+
+    return docs.map(fromDocument);
+  }
+
+  readGuideline(id: GuidelineId, projectRoot?: string): Guideline {
+    const docs = readDb(projectRoot);
+    const doc = docs.find(d => d.id === id);
+    if (!doc) throw new Error(`Guideline '${id}' not found`);
+    return fromDocument(doc);
+  }
+
+  updateGuideline(id: GuidelineId, params: GuidelineUpdateParams, projectRoot?: string): Guideline {
+    const docs = readDb(projectRoot);
+    const idx = docs.findIndex(d => d.id === id);
+    if (idx === -1) throw new Error(`Guideline '${id}' not found`);
+
+    const doc = docs[idx]!;
+    if (params.condition !== undefined) doc.condition = params.condition;
+    if (params.action !== undefined) doc.action = params.action;
+    if (params.description !== undefined) doc.description = params.description;
+    if (params.title !== undefined) doc.title = params.title;
+    if (params.criticality !== undefined) doc.criticality = params.criticality;
+    if (params.enabled !== undefined) doc.enabled = params.enabled;
+    if (params.priority !== undefined) doc.priority = params.priority;
+
+    docs[idx] = doc;
+    writeDb(docs, projectRoot);
+    return fromDocument(doc);
+  }
+
+  deleteGuideline(id: GuidelineId, projectRoot?: string): void {
+    const docs = readDb(projectRoot);
+    const idx = docs.findIndex(d => d.id === id);
+    if (idx === -1) throw new Error(`Guideline '${id}' not found`);
+    docs.splice(idx, 1);
+    writeDb(docs, projectRoot);
+  }
+
+  findGuideline(content: GuidelineContent, projectRoot?: string): Guideline {
+    const docs = readDb(projectRoot);
+    const doc = docs.find(d =>
+      d.condition === content.condition &&
+      (content.action === undefined || d.action === content.action),
+    );
+    if (!doc) throw new Error(`Guideline not found for condition='${content.condition}'`);
+    return fromDocument(doc);
+  }
+
+  upsertLabels(id: GuidelineId, labels: string[], projectRoot?: string): Guideline {
+    const docs = readDb(projectRoot);
+    const idx = docs.findIndex(d => d.id === id);
+    if (idx === -1) throw new Error(`Guideline '${id}' not found`);
+
+    const doc = docs[idx]!;
+    const current = new Set(doc.labels || []);
+    for (const l of labels) current.add(l);
+    doc.labels = [...current];
+    writeDb(docs, projectRoot);
+    return fromDocument(doc);
+  }
+
+  removeLabels(id: GuidelineId, labels: string[], projectRoot?: string): Guideline {
+    const docs = readDb(projectRoot);
+    const idx = docs.findIndex(d => d.id === id);
+    if (idx === -1) throw new Error(`Guideline '${id}' not found`);
+
+    const doc = docs[idx]!;
+    const removeSet = new Set(labels);
+    doc.labels = (doc.labels || []).filter(l => !removeSet.has(l));
+    writeDb(docs, projectRoot);
+    return fromDocument(doc);
+  }
+}

apps/server/src/services/audit/index.ts

@@ -0,0 +1,68 @@
+export {
+  findRunsDir,
+  ensureRunsDir,
+  readCurrentSession,
+  writeCurrentSession,
+  clearCurrentSession,
+  readIndex,
+  writeIndex,
+  updateIndexEntry,
+  findInProgressSessions,
+  INDEX_SCHEMA_VERSION,
+  GITIGNORE_CONTENT,
+} from './runs-dir.js';
+export type { IndexEntry, IndexFile } from './runs-dir.js';
+
+export {
+  generateSessionId,
+  isoNow,
+  createSession,
+  getSessionDir,
+  getActiveSession,
+  readSession,
+  updateSession,
+  endSession,
+  appendToTrail,
+  readTrail,
+  recoverContext,
+  checkUnfinishedSessions,
+  generateSessionSummary,
+} from './session-manager.js';
+export type { SessionJson, RecoverySummary } from './session-manager.js';
+
+export {
+  createCorrection,
+  findCorrections,
+  checkCorrectionConflict,
+} from './corrections.js';
+export type { UserCorrectionRecord } from './corrections.js';
+
+export {
+  GuidelineDocumentStore,
+} from './guideline-store.js';
+export type {
+  GuidelineId,
+  GuidelineContent,
+  Guideline,
+  Criticality,
+  GuidelineUpdateParams,
+  GuidelineDocument,
+} from './guideline-store.js';
+
+export {
+  JourneyStore,
+} from './journey-store.js';
+export type {
+  JourneyId,
+  JourneyNodeId,
+  JourneyEdgeId,
+  Journey,
+  JourneyNode,
+  JourneyEdge,
+} from './journey-store.js';
+
+export {
+  projectJourneyToGuidelines,
+  detectJourneyBacktrack,
+} from './journey-projection.js';
+export type { ProjectedGuideline, BacktrackCheck } from './journey-projection.js';

apps/server/src/services/audit/journey-projection.ts

@@ -0,0 +1,189 @@
+import type {
+  Journey,
+  JourneyNode,
+  JourneyEdge,
+  JourneyNodeId,
+  JourneyEdgeId,
+} from './journey-store.js';
+import type { Guideline, GuidelineId, Criticality } from './guideline-store.js';
+
+export interface ProjectedGuideline {
+  id: GuidelineId;
+  content: {
+    condition: string;
+    action: string | null;
+    description: string | null;
+  };
+  criticality: Criticality;
+  creationUtc: string;
+  enabled: boolean;
+  tags: string[];
+  labels: string[];
+  metadata: Record<string, unknown>;
+}
+
+function formatNodeGuidelineId(nodeId: JourneyNodeId, edgeId?: JourneyEdgeId | null): GuidelineId {
+  return `journey_node:${nodeId}${edgeId ? `:${edgeId}` : ''}` as GuidelineId;
+}
+
+export function projectJourneyToGuidelines(
+  journey: Journey,
+  nodes: JourneyNode[],
+  edges: JourneyEdge[],
+): ProjectedGuideline[] {
+  const nodeMap = new Map<JourneyNodeId, JourneyNode>();
+  for (const n of nodes) nodeMap.set(n.id, n);
+
+  const edgeMap = new Map<JourneyEdgeId, JourneyEdge>();
+  for (const e of edges) edgeMap.set(e.id, e);
+
+  const nodeEdges = new Map<JourneyNodeId, JourneyEdge[]>();
+  for (const e of edges) {
+    const list = nodeEdges.get(e.source) || [];
+    list.push(e);
+    nodeEdges.set(e.source, list);
+  }
+
+  const guidelines: Map<GuidelineId, ProjectedGuideline> = new Map();
+  const nodeIndexes = new Map<JourneyNodeId, number>();
+  let index = 0;
+
+  const queue: Array<{ edgeId: JourneyEdgeId | null; nodeId: JourneyNodeId }> = [];
+  const visited = new Set<string>();
+
+  queue.push({ edgeId: null, nodeId: journey.rootId });
+
+  while (queue.length > 0) {
+    const { edgeId, nodeId } = queue.shift()!;
+    const visitKey = `${edgeId || ''}:${nodeId}`;
+    if (visited.has(visitKey)) continue;
+    visited.add(visitKey);
+
+    const node = nodeMap.get(nodeId);
+    if (!node) continue;
+
+    if (!nodeIndexes.has(nodeId)) {
+      index++;
+      nodeIndexes.set(nodeId, index);
+    }
+
+    const edge = edgeId ? edgeMap.get(edgeId) : undefined;
+
+    const baseJourneyNode: Record<string, unknown> = {
+      follow_ups: [],
+      index: String(nodeIndexes.get(nodeId)),
+      journey_id: journey.id,
+      labels: node.labels,
+      tool_ids: node.tools,
+    };
+
+    const edgeJourneyNode = (edge?.metadata?.['journey_node'] as Record<string, unknown>) || {};
+    const nodeJourneyNode = (node.metadata?.['journey_node'] as Record<string, unknown>) || {};
+
+    const mergedJourneyNode = { ...baseJourneyNode, ...nodeJourneyNode, ...edgeJourneyNode };
+
+    const metadata: Record<string, unknown> = {
+      journey_node: mergedJourneyNode,
+    };
+    for (const [k, v] of Object.entries(node.metadata)) {
+      if (k !== 'journey_node') metadata[k] = v;
+    }
+    if (edge) {
+      for (const [k, v] of Object.entries(edge.metadata)) {
+        if (k !== 'journey_node') metadata[k] = v;
+      }
+    }
+
+    const gid = formatNodeGuidelineId(nodeId, edgeId);
+    const guideline: ProjectedGuideline = {
+      id: gid,
+      content: {
+        condition: (edge?.condition) || '',
+        action: node.action,
+        description: node.description,
+      },
+      criticality: 'high' as Criticality,
+      creationUtc: new Date().toISOString(),
+      enabled: true,
+      tags: journey.tags,
+      labels: [...(node.labels || [])],
+      metadata,
+    };
+
+    guidelines.set(gid, guideline);
+
+    const childEdges = nodeEdges.get(nodeId) || [];
+    for (const childEdge of childEdges) {
+      if (visited.has(`${childEdge.id}:${childEdge.target}`)) continue;
+      queue.push({ edgeId: childEdge.id, nodeId: childEdge.target });
+
+      const childGid = formatNodeGuidelineId(childEdge.target, childEdge.id);
+      const followUps = (guideline.metadata['journey_node'] as Record<string, unknown>)['follow_ups'] as string[];
+      if (!followUps.includes(childGid)) {
+        followUps.push(childGid);
+      }
+    }
+  }
+
+  return [...guidelines.values()];
+}
+
+export interface BacktrackCheck {
+  journeyId: string;
+  currentNodeId: JourneyNodeId;
+  previousNodeId: JourneyNodeId;
+  isBacktrack: boolean;
+  recommendation: string | null;
+}
+
+export function detectJourneyBacktrack(
+  journey: Journey,
+  nodes: JourneyNode[],
+  edges: JourneyEdge[],
+  currentNodeId: JourneyNodeId,
+  previousNodeId: JourneyNodeId,
+): BacktrackCheck {
+  const nodeMap = new Map<JourneyNodeId, JourneyNode>();
+  for (const n of nodes) nodeMap.set(n.id, n);
+
+  const adjacency = new Map<JourneyNodeId, JourneyNodeId[]>();
+  for (const e of edges) {
+    const list = adjacency.get(e.source) || [];
+    list.push(e.target);
+    adjacency.set(e.source, list);
+  }
+
+  const isInForwardPath = (from: JourneyNodeId, target: JourneyNodeId): boolean => {
+    const visitedInner = new Set<JourneyNodeId>();
+    const queueInner: JourneyNodeId[] = [from];
+    while (queueInner.length > 0) {
+      const current = queueInner.shift()!;
+      if (current === target) return true;
+      if (visitedInner.has(current)) continue;
+      visitedInner.add(current);
+      for (const next of adjacency.get(current) || []) {
+        if (!visitedInner.has(next)) queueInner.push(next);
+      }
+    }
+    return false;
+  };
+
+  const fromCurToPrev = isInForwardPath(currentNodeId, previousNodeId);
+  const fromPrevToCur = isInForwardPath(previousNodeId, currentNodeId);
+
+  const isBacktrack = !fromPrevToCur && !fromCurToPrev;
+
+  let recommendation: string | null = null;
+  if (isBacktrack && nodeMap.has(previousNodeId)) {
+    const prevNode = nodeMap.get(previousNodeId)!;
+    recommendation = `Detected potential backtrack from '${currentNodeId}' to '${previousNodeId}' (${prevNode.action || 'no action'}). Consider whether this regression is intentional.`;
+  }
+
+  return {
+    journeyId: journey.id,
+    currentNodeId,
+    previousNodeId,
+    isBacktrack,
+    recommendation,
+  };
+}

apps/server/src/services/audit/journey-store.ts

@@ -0,0 +1,360 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ensureRunsDir } from './runs-dir.js';
+import type { GuidelineId } from './guideline-store.js';
+
+export type JourneyId = string;
+export type JourneyNodeId = string;
+export type JourneyEdgeId = string;
+
+export interface JourneyNode {
+  id: JourneyNodeId;
+  creationUtc: string;
+  action: string | null;
+  tools: string[];
+  metadata: Record<string, unknown>;
+  description: string | null;
+  labels: string[];
+}
+
+export interface JourneyEdge {
+  id: JourneyEdgeId;
+  creationUtc: string;
+  source: JourneyNodeId;
+  target: JourneyNodeId;
+  condition: string | null;
+  metadata: Record<string, unknown>;
+}
+
+export interface Journey {
+  id: JourneyId;
+  creationUtc: string;
+  description: string;
+  triggers: GuidelineId[];
+  title: string;
+  rootId: JourneyNodeId;
+  tags: string[];
+  labels: string[];
+  priority: number;
+}
+
+interface JourneyDocument {
+  id: string;
+  version: string;
+  creation_utc: string;
+  title: string;
+  description: string;
+  root_id: JourneyNodeId;
+  labels: string[];
+  priority: number;
+}
+
+interface NodeDocument {
+  id: string;
+  node_id: JourneyNodeId;
+  journey_id: JourneyId;
+  creation_utc: string;
+  action: string | null;
+  tools: string[];
+  metadata: Record<string, unknown>;
+  description: string | null;
+  labels: string[];
+}
+
+interface EdgeDocument {
+  id: string;
+  journey_id: JourneyId;
+  creation_utc: string;
+  source: JourneyNodeId;
+  target: JourneyNodeId;
+  condition: string | null;
+  metadata: Record<string, unknown>;
+}
+
+interface TriggerDocument {
+  id: string;
+  journey_id: JourneyId;
+  trigger: GuidelineId;
+  creation_utc: string;
+}
+
+function generateId(): string {
+  const chars = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
+  let result = '';
+  for (let i = 0; i < 10; i++) {
+    result += chars[Math.floor(Math.random() * chars.length)];
+  }
+  return result;
+}
+
+function dbPath(name: string, projectRoot?: string): string {
+  const dir = join(ensureRunsDir(projectRoot), '..', 'journeys');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return join(dir, `${name}.json`);
+}
+
+function readCollection<T>(name: string, projectRoot?: string): T[] {
+  try {
+    return JSON.parse(readFileSync(dbPath(name, projectRoot), 'utf-8')) as T[];
+  } catch {
+    return [];
+  }
+}
+
+function writeCollection<T>(name: string, data: T[], projectRoot?: string): void {
+  writeFileSync(dbPath(name, projectRoot), JSON.stringify(data, null, 2), 'utf-8');
+}
+
+export class JourneyStore {
+  createJourney(params: {
+    title: string;
+    description: string;
+    triggers?: GuidelineId[];
+    labels?: string[];
+    priority?: number;
+  }, projectRoot?: string): Journey {
+    const id = `jny_${generateId()}`;
+    const rootId = `node_${generateId()}`;
+    const creationUtc = new Date().toISOString();
+
+    const journey: Journey = {
+      id,
+      creationUtc,
+      description: params.description,
+      triggers: params.triggers || [],
+      title: params.title,
+      rootId,
+      tags: [],
+      labels: params.labels || [],
+      priority: params.priority || 0,
+    };
+
+    const journeys = readCollection<JourneyDocument>('journeys', projectRoot);
+    journeys.push({
+      id,
+      version: '0.7.0',
+      creation_utc: creationUtc,
+      title: params.title,
+      description: params.description,
+      root_id: rootId,
+      labels: params.labels || [],
+      priority: params.priority || 0,
+    });
+    writeCollection('journeys', journeys, projectRoot);
+
+    const root: JourneyNode = {
+      id: rootId,
+      creationUtc,
+      action: null,
+      tools: [],
+      metadata: {},
+      description: null,
+      labels: [],
+    };
+    const nodes = readCollection<NodeDocument>('nodes', projectRoot);
+    nodes.push({
+      id: `nd_${generateId()}`,
+      node_id: rootId,
+      journey_id: id,
+      creation_utc: creationUtc,
+      action: null,
+      tools: [],
+      metadata: {},
+      description: null,
+      labels: [],
+    });
+    writeCollection('nodes', nodes, projectRoot);
+
+    return journey;
+  }
+
+  readJourney(id: JourneyId, projectRoot?: string): Journey {
+    const journeys = readCollection<JourneyDocument>('journeys', projectRoot);
+    const doc = journeys.find(j => j.id === id);
+    if (!doc) throw new Error(`Journey '${id}' not found`);
+
+    const triggers = readCollection<TriggerDocument>('triggers', projectRoot)
+      .filter(t => t.journey_id === id)
+      .map(t => t.trigger);
+
+    return {
+      id: doc.id,
+      creationUtc: doc.creation_utc,
+      description: doc.description,
+      triggers,
+      title: doc.title,
+      rootId: doc.root_id,
+      tags: [],
+      labels: doc.labels || [],
+      priority: doc.priority || 0,
+    };
+  }
+
+  deleteJourney(id: JourneyId, projectRoot?: string): void {
+    let journeys = readCollection<JourneyDocument>('journeys', projectRoot);
+    const idx = journeys.findIndex(j => j.id === id);
+    if (idx === -1) throw new Error(`Journey '${id}' not found`);
+    journeys.splice(idx, 1);
+    writeCollection('journeys', journeys, projectRoot);
+
+    let nodes = readCollection<NodeDocument>('nodes', projectRoot);
+    nodes = nodes.filter(n => n.journey_id !== id);
+    writeCollection('nodes', nodes, projectRoot);
+
+    let edges = readCollection<EdgeDocument>('edges', projectRoot);
+    edges = edges.filter(e => e.journey_id !== id);
+    writeCollection('edges', edges, projectRoot);
+
+    let triggers = readCollection<TriggerDocument>('triggers', projectRoot);
+    triggers = triggers.filter(t => t.journey_id !== id);
+    writeCollection('triggers', triggers, projectRoot);
+  }
+
+  listJourneys(projectRoot?: string): Journey[] {
+    const journeys = readCollection<JourneyDocument>('journeys', projectRoot);
+    return journeys.map(j => this.readJourney(j.id, projectRoot));
+  }
+
+  createNode(journeyId: JourneyId, params: {
+    action?: string | null;
+    tools?: string[];
+    description?: string | null;
+    labels?: string[];
+    id?: JourneyNodeId;
+  }, projectRoot?: string): JourneyNode {
+    const nodeId = params.id || `node_${generateId()}`;
+    const creationUtc = new Date().toISOString();
+
+    const node: JourneyNode = {
+      id: nodeId,
+      creationUtc,
+      action: params.action ?? null,
+      tools: params.tools || [],
+      metadata: {},
+      description: params.description ?? null,
+      labels: params.labels || [],
+    };
+
+    const nodes = readCollection<NodeDocument>('nodes', projectRoot);
+    nodes.push({
+      id: `nd_${generateId()}`,
+      node_id: nodeId,
+      journey_id: journeyId,
+      creation_utc: creationUtc,
+      action: node.action,
+      tools: node.tools,
+      metadata: node.metadata,
+      description: node.description,
+      labels: node.labels,
+    });
+    writeCollection('nodes', nodes, projectRoot);
+
+    return node;
+  }
+
+  listNodes(journeyId: JourneyId, projectRoot?: string): JourneyNode[] {
+    const docs = readCollection<NodeDocument>('nodes', projectRoot)
+      .filter(n => n.journey_id === journeyId);
+
+    const nodes = docs.map(d => ({
+      id: d.node_id,
+      creationUtc: d.creation_utc,
+      action: d.action,
+      tools: d.tools,
+      metadata: d.metadata,
+      description: d.description,
+      labels: d.labels || [],
+    }));
+
+    nodes.push({
+      id: 'end' as JourneyNodeId,
+      creationUtc: new Date().toISOString(),
+      action: null,
+      tools: [],
+      metadata: {},
+      description: null,
+      labels: [],
+    });
+
+    return nodes;
+  }
+
+  createEdge(journeyId: JourneyId, params: {
+    source: JourneyNodeId;
+    target: JourneyNodeId;
+    condition?: string | null;
+  }, projectRoot?: string): JourneyEdge {
+    const creationUtc = new Date().toISOString();
+    const edge: JourneyEdge = {
+      id: `edge_${generateId()}`,
+      creationUtc,
+      source: params.source,
+      target: params.target,
+      condition: params.condition ?? null,
+      metadata: {},
+    };
+
+    const edges = readCollection<EdgeDocument>('edges', projectRoot);
+    edges.push({
+      id: edge.id,
+      journey_id: journeyId,
+      creation_utc: creationUtc,
+      source: params.source,
+      target: params.target,
+      condition: params.condition ?? null,
+      metadata: {},
+    });
+    writeCollection('edges', edges, projectRoot);
+
+    return edge;
+  }
+
+  listEdges(journeyId: JourneyId, nodeId?: JourneyNodeId, projectRoot?: string): JourneyEdge[] {
+    let docs = readCollection<EdgeDocument>('edges', projectRoot)
+      .filter(e => e.journey_id === journeyId);
+
+    if (nodeId) {
+      docs = docs.filter(e => e.source === nodeId || e.target === nodeId);
+    }
+
+    return docs.map(d => ({
+      id: d.id,
+      creationUtc: d.creation_utc,
+      source: d.source,
+      target: d.target,
+      condition: d.condition,
+      metadata: d.metadata,
+    }));
+  }
+
+  deleteEdge(edgeId: JourneyEdgeId, projectRoot?: string): void {
+    let edges = readCollection<EdgeDocument>('edges', projectRoot);
+    const idx = edges.findIndex(e => e.id === edgeId);
+    if (idx === -1) throw new Error(`Edge '${edgeId}' not found`);
+    edges.splice(idx, 1);
+    writeCollection('edges', edges, projectRoot);
+  }
+
+  addTrigger(journeyId: JourneyId, trigger: GuidelineId, projectRoot?: string): boolean {
+    const triggers = readCollection<TriggerDocument>('triggers', projectRoot);
+    if (triggers.find(t => t.journey_id === journeyId && t.trigger === trigger)) {
+      return false;
+    }
+    triggers.push({
+      id: `trg_${generateId()}`,
+      journey_id: journeyId,
+      trigger,
+      creation_utc: new Date().toISOString(),
+    });
+    writeCollection('triggers', triggers, projectRoot);
+    return true;
+  }
+
+  removeTrigger(journeyId: JourneyId, trigger: GuidelineId, projectRoot?: string): boolean {
+    let triggers = readCollection<TriggerDocument>('triggers', projectRoot);
+    const len = triggers.length;
+    triggers = triggers.filter(t => !(t.journey_id === journeyId && t.trigger === trigger));
+    writeCollection('triggers', triggers, projectRoot);
+    return triggers.length < len;
+  }
+}

apps/server/src/services/audit/runs-dir.ts

@@ -0,0 +1,111 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export const INDEX_SCHEMA_VERSION = '1.1';
+export const GITIGNORE_CONTENT = `# boocode audit runs
+/*
+!index.json
+`;
+
+export interface IndexEntry {
+  id: string;
+  type: string;
+  status: string;
+  task?: string;
+  skill?: string;
+  created?: string;
+  last_updated?: string;
+  record_count?: number;
+  anomaly_count?: number;
+  max_anomaly_level?: string;
+}
+
+export interface IndexFile {
+  schema_version: string;
+  entries: IndexEntry[];
+}
+
+function findRunsDirFrom(start: string): string {
+  const explicit = process.env['AUDIT_DOT_DIR']?.trim();
+  const candidates = explicit ? [explicit] : ['.boo'];
+  let cur = resolve(start);
+  while (true) {
+    for (const basename of candidates) {
+      const candidate = join(cur, basename, 'runs');
+      if (existsSync(candidate)) return candidate;
+    }
+    const parent = resolve(cur, '..');
+    if (parent === cur) break;
+    cur = parent;
+  }
+  const defaultBasename = explicit || '.boo';
+  return join(resolve(start), defaultBasename, 'runs');
+}
+
+export function findRunsDir(projectRoot?: string): string {
+  return findRunsDirFrom(projectRoot || process.cwd());
+}
+
+export function ensureRunsDir(projectRoot?: string): string {
+  const dir = findRunsDir(projectRoot);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+    const gitignorePath = join(dir, '.gitignore');
+    if (!existsSync(gitignorePath)) {
+      writeFileSync(gitignorePath, GITIGNORE_CONTENT, 'utf-8');
+    }
+  }
+  return dir;
+}
+
+export function readCurrentSession(projectRoot?: string): string | null {
+  const path = join(ensureRunsDir(projectRoot), '.current_session');
+  try {
+    return readFileSync(path, 'utf-8').trim();
+  } catch {
+    return null;
+  }
+}
+
+export function writeCurrentSession(sessionId: string, projectRoot?: string): void {
+  writeFileSync(join(ensureRunsDir(projectRoot), '.current_session'), sessionId, 'utf-8');
+}
+
+export function clearCurrentSession(projectRoot?: string): void {
+  const path = join(ensureRunsDir(projectRoot), '.current_session');
+  try {
+    writeFileSync(path, '', 'utf-8');
+  } catch {
+    // silent
+  }
+}
+
+export function readIndex(projectRoot?: string): IndexFile {
+  const path = join(ensureRunsDir(projectRoot), 'index.json');
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8')) as IndexFile;
+  } catch {
+    return { schema_version: INDEX_SCHEMA_VERSION, entries: [] };
+  }
+}
+
+export function writeIndex(index: IndexFile, projectRoot?: string): void {
+  const runsDir = ensureRunsDir(projectRoot);
+  writeFileSync(join(runsDir, 'index.json'), JSON.stringify(index, null, 2), 'utf-8');
+}
+
+export function updateIndexEntry(entry: IndexEntry, projectRoot?: string): void {
+  const idx = readIndex(projectRoot);
+  const existing = idx.entries.find(e => e.id === entry.id);
+  if (existing) {
+    Object.assign(existing, entry);
+  } else {
+    idx.entries.push({ ...entry });
+  }
+  writeIndex(idx, projectRoot);
+}
+
+export function findInProgressSessions(projectRoot?: string): IndexEntry[] {
+  const idx = readIndex(projectRoot);
+  return idx.entries.filter(e => e.status === 'in_progress');
+}

apps/server/src/services/audit/session-manager.ts

@@ -0,0 +1,236 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  ensureRunsDir,
+  readCurrentSession,
+  writeCurrentSession,
+  clearCurrentSession,
+  updateIndexEntry,
+  findInProgressSessions,
+  readIndex,
+  type IndexEntry,
+} from './runs-dir.js';
+
+export interface SessionJson {
+  session_id: string;
+  task: string;
+  start_time: string;
+  end_time?: string;
+  status: 'in_progress' | 'completed';
+  expected_record_types?: string[];
+  total_records?: number;
+}
+
+export function generateSessionId(): string {
+  const now = new Date();
+  const y = now.getFullYear();
+  const m = String(now.getMonth() + 1).padStart(2, '0');
+  const d = String(now.getDate()).padStart(2, '0');
+  const h = String(now.getHours()).padStart(2, '0');
+  const min = String(now.getMinutes()).padStart(2, '0');
+  return `adhoc_${y}${m}${d}_${h}${min}`;
+}
+
+export function isoNow(): string {
+  return new Date().toISOString();
+}
+
+export function createSession(
+  task: string,
+  sessionId?: string,
+  projectRoot?: string,
+): string {
+  const sid = sessionId || generateSessionId();
+  const runsDir = ensureRunsDir(projectRoot);
+  const sessionDir = join(runsDir, sid);
+  mkdirSync(sessionDir, { recursive: true });
+
+  const session: SessionJson = {
+    session_id: sid,
+    task,
+    start_time: isoNow(),
+    status: 'in_progress',
+    expected_record_types: ['data', 'change', 'conversation'],
+  };
+
+  writeFileSync(join(sessionDir, 'session.json'), JSON.stringify(session, null, 2), 'utf-8');
+  writeCurrentSession(sid, projectRoot);
+
+  updateIndexEntry({
+    id: sid,
+    type: 'adhoc',
+    status: 'in_progress',
+    task,
+    created: session.start_time,
+    last_updated: session.start_time,
+  }, projectRoot);
+
+  return sid;
+}
+
+export function getSessionDir(sessionId: string, projectRoot?: string): string {
+  return join(ensureRunsDir(projectRoot), sessionId);
+}
+
+export function getActiveSession(projectRoot?: string): SessionJson | null {
+  const sid = readCurrentSession(projectRoot);
+  if (!sid) return null;
+  return readSession(sid, projectRoot);
+}
+
+export function readSession(sessionId: string, projectRoot?: string): SessionJson | null {
+  const path = join(getSessionDir(sessionId, projectRoot), 'session.json');
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8')) as SessionJson;
+  } catch {
+    return null;
+  }
+}
+
+export function updateSession(
+  sessionId: string,
+  updates: Partial<SessionJson>,
+  projectRoot?: string,
+): void {
+  const session = readSession(sessionId, projectRoot) || { session_id: sessionId, task: '', start_time: isoNow(), status: 'in_progress' as const };
+  Object.assign(session, updates);
+  writeFileSync(
+    join(getSessionDir(sessionId, projectRoot), 'session.json'),
+    JSON.stringify(session, null, 2),
+    'utf-8',
+  );
+}
+
+export function endSession(sessionId: string, projectRoot?: string): void {
+  updateSession(sessionId, { status: 'completed', end_time: isoNow() }, projectRoot);
+  updateIndexEntry({ id: sessionId, type: 'adhoc', status: 'completed', last_updated: isoNow() }, projectRoot);
+  clearCurrentSession(projectRoot);
+}
+
+export function appendToTrail(sessionId: string, records: Record<string, unknown>[], projectRoot?: string): void {
+  const trailPath = join(getSessionDir(sessionId, projectRoot), 'audit_trail.jsonl');
+  const lines = records.map(r => JSON.stringify(r)).join('\n') + '\n';
+  appendFileSync(trailPath, lines, 'utf-8');
+}
+
+export function readTrail(sessionId: string, projectRoot?: string): Record<string, unknown>[] {
+  const trailPath = join(getSessionDir(sessionId, projectRoot), 'audit_trail.jsonl');
+  try {
+    const content = readFileSync(trailPath, 'utf-8').trim();
+    if (!content) return [];
+    return content.split('\n').filter(Boolean).map(line => JSON.parse(line) as Record<string, unknown>);
+  } catch {
+    return [];
+  }
+}
+
+export interface RecoverySummary {
+  sessionId: string;
+  task: string;
+  recentActivity: IndexEntry[];
+  userCorrections: Record<string, unknown>[];
+  unresolvedIssues: string[];
+  recommendedPriorities: string[];
+  level: number;
+}
+
+export function recoverContext(
+  sessionId: string,
+  level: number,
+  projectRoot?: string,
+): RecoverySummary {
+  const session = readSession(sessionId, projectRoot);
+  const idx = readIndex(projectRoot);
+  const recentActivity = idx.entries.slice(-5);
+  const trail = readTrail(sessionId, projectRoot);
+  const userCorrections = trail.filter(r => r['action_type'] === 'user_correction');
+
+  const summary: RecoverySummary = {
+    sessionId,
+    task: session?.task || '(unknown)',
+    recentActivity,
+    userCorrections,
+    unresolvedIssues: [],
+    recommendedPriorities: [],
+    level,
+  };
+
+  if (level >= 1) {
+    const last = trail.slice(-3);
+    if (last.length > 0) {
+      summary.recommendedPriorities.push(`Last action: ${JSON.stringify(last[last.length - 1]?.['action'] || 'none')}`);
+    }
+  }
+
+  if (level >= 3) {
+    summary.recommendedPriorities.push(`Full trail: ${trail.length} records`);
+  }
+
+  let checkCount = 0;
+  for (const entry of recentActivity) {
+    if (entry.status === 'in_progress' && entry.id !== sessionId) {
+      summary.unresolvedIssues.push(`Unfinished session: ${entry.id} (${entry.task || 'no task'})`);
+      checkCount++;
+      if (checkCount >= 3) break;
+    }
+  }
+
+  return summary;
+}
+
+export function checkUnfinishedSessions(projectRoot?: string): IndexEntry[] {
+  return findInProgressSessions(projectRoot);
+}
+
+export function generateSessionSummary(sessionId: string, projectRoot?: string): string {
+  const session = readSession(sessionId, projectRoot);
+  const trail = readTrail(sessionId, projectRoot);
+  const corrections = trail.filter(r => r['action_type'] === 'user_correction');
+  const changes = trail.filter(r => r['action'] === 'edit_file' || r['action'] === 'create_file' || r['action'] === 'delete_file');
+
+  const lines: string[] = [
+    `# Session Summary | ${sessionId}`,
+    '',
+    `## Task: ${session?.task || '(unknown)'}`,
+    `## Time: ${session?.start_time || '?'} → ${session?.end_time || 'in_progress'}`,
+    `## Status: ${session?.status || 'unknown'}`,
+    '',
+    '## Completed Work',
+  ];
+
+  for (const r of trail) {
+    if (r['action']) {
+      lines.push(`- ${r['action']}: ${r['detail'] || r['reason'] || '(no detail)'}`);
+    }
+  }
+
+  if (corrections.length > 0) {
+    lines.push('', '## User Corrections');
+    for (const c of corrections) {
+      lines.push(`- Original: ${c['original_claim']}`);
+      lines.push(`  Correction: ${c['correction']}`);
+      if (c['principle_extracted']) {
+        lines.push(`  Principle: ${c['principle_extracted']}`);
+      }
+    }
+  }
+
+  if (changes.length > 0) {
+    lines.push('', '## Files Changed');
+    const fileSet = new Set<string>();
+    for (const c of changes) {
+      const files = c['files'];
+      if (Array.isArray(files)) {
+        for (const f of files) fileSet.add(String(f));
+      }
+    }
+    for (const f of fileSet) lines.push(`- ${f}`);
+  }
+
+  lines.push('', '## Stats');
+  lines.push(`- Total records: ${trail.length}`);
+  lines.push(`- Corrections: ${corrections.length}`);
+  lines.push(`- File changes: ${changes.length}`);
+
+  return lines.join('\n');
+}

apps/server/src/services/boocontext_client.ts

@@ -0,0 +1,110 @@
+/**
+ * v2.7.18: shared MCP client wrapper for the boocontext sidecar.
+ *
+ * Calls into the existing multi-server MCP client infrastructure
+ * (services/mcp-client.ts) which connects to boocontext as a stdio
+ * MCP process defined in data/mcp.json (server name "boocontext",
+ * command: `node /opt/forks/boocontext/dist/standalone.js`).
+ *
+ * The boocontext MCP server is initialized once at app boot in
+ * index.ts via initMcp() and the actual MCP tool call routing is
+ * handled by mcp-client.ts:callTool() — this module is a thin
+ * convenience wrapper that prepends the "boocontext_" server prefix,
+ * normalises the response, and applies inline truncation matching
+ * the same pattern as codecontext_client.ts.
+ *
+ * Usage:
+ *   import { callBoocontext } from './services/boocontext_client.js';
+ *   const resp = await callBoocontext({
+ *     toolName: 'codesight_get_summary',
+ *     args: { directory: '/opt/boocode' },
+ *   });
+ */
+
+import { callTool } from './mcp-client.js';
+import { truncateIfNeeded } from './truncate.js';
+
+// ---- Exported types ----
+
+export interface BoocontextRequest {
+  /** Unprefixed tool name as defined on the boocontext MCP server
+   * (e.g. "codesight_scan", "boocontext_overview", "codesight_get_summary"). */
+  toolName: string;
+  /** Arguments to pass to the tool. */
+  args: Record<string, unknown>;
+}
+
+export interface BoocontextResponse {
+  /** The tool output text. */
+  result: string;
+  /** Whether the result was truncated to fit the inline limit. */
+  truncated: boolean;
+  /** Opaque id pointing at the full pre-slice content on tmpfs, set when
+   * truncated=true and storage succeeded. */
+  outputPath?: string;
+}
+
+// ---- Constants ----
+
+/** Must match the server name in data/mcp.json. */
+const BOOCONTEXT_SERVER_NAME = 'boocontext';
+
+/** Inline truncation limit, matching codecontext_client.ts. */
+const TRUNCATION_LIMIT = 32_000;
+
+// ---- Public API ----
+
+/**
+ * Call a boocontext MCP tool by its unprefixed name.
+ *
+ * Prepends the "boocontext_" server prefix, delegates to the
+ * multi-server MCP client's callTool(), and normalises the response
+ * into a BoocontextResponse with inline truncation.
+ *
+ * @param req   The tool name and arguments.
+ * @param log   Optional Fastify-compatible logger (for debug traces).
+ * @returns     The tool result, possibly truncated.
+ * @throws      If the boocontext server is not connected or the tool
+ *              returns an MCP-level error.
+ */
+export async function callBoocontext(
+  req: BoocontextRequest,
+  log?: { debug?: (obj: object, msg: string) => void; warn?: (obj: object, msg: string) => void },
+): Promise<BoocontextResponse> {
+  const prefixedName = `${BOOCONTEXT_SERVER_NAME}_${req.toolName}`;
+
+  log?.debug?.({ tool: prefixedName }, 'boocontext: calling tool');
+
+  const raw = await callTool(prefixedName, req.args);
+
+  // callTool returns { error: true, output: string } on failure (both
+  // for MCP-level isError and for network/protocol exceptions).
+  if (typeof raw === 'object' && raw !== null && (raw as Record<string, unknown>).error === true) {
+    const errOutput = (raw as Record<string, unknown>).output ?? 'Unknown MCP error';
+    throw new Error(`boocontext error: ${String(errOutput)}`);
+  }
+
+  const result = typeof raw === 'string' ? raw : JSON.stringify(raw);
+
+  // Inline truncation at 32 kB, matching codecontext_client.ts.
+  // The model gets a clear hint about how to narrow the next call
+  // rather than a silent cut.
+  if (result.length > TRUNCATION_LIMIT) {
+    const truncated = result.slice(0, TRUNCATION_LIMIT);
+    const omitted = result.length - TRUNCATION_LIMIT;
+    const slicedWithMarker =
+      `${truncated}\n\n[truncated, ${omitted} chars omitted; narrow with additional filters]`;
+    const wrapped = await truncateIfNeeded({
+      fullContent: result,
+      slicedContent: slicedWithMarker,
+      wasTruncated: true,
+    });
+    return {
+      result: wrapped.content,
+      truncated: wrapped.truncated,
+      ...(wrapped.outputPath ? { outputPath: wrapped.outputPath } : {}),
+    };
+  }
+
+  return { result, truncated: false };
+}

apps/server/src/services/codecontext_client.ts

@@ -1,3 +1,10 @@
+// DEPRECATED (Phase 4, Domain 2, v2.8.14): This HTTP client routes through
+// the Go codecontext sidecar (http://codecontext:8080). Superseded by the
+// boocontext MCP server. New callers should use boocontext MCP tool wrappers
+// directly. Keep this file for backward compatibility — the 16 existing
+// codecontext tool wrappers (under tools/codecontext/) still call through
+// callCodecontext(). Remove after full migration.
+//
 // v1.12 Track B.2: shared HTTP client for the codecontext sidecar. The 8
 // per-tool wrappers under tools/codecontext/ all funnel through callCodecontext
 // — they're thin adapters that supply toolName + args + projectPath. The
@@ -19,6 +26,7 @@
 import { access, copyFile, realpath } from 'node:fs/promises';
 import { isAbsolute, join, resolve, sep } from 'node:path';
 import { truncateIfNeeded } from './truncate.js';
+import { callBoocontext } from './boocontext_client.js';
 
 // v1.13.12 fix: codecontext crashes on empty source files (upstream issue #37)
 // when it can't ignore them. The .codecontextignore.template ships with the
@@ -112,6 +120,16 @@ export async function callCodecontext(
   req: CodecontextRequest,
   fetcher: typeof fetch = fetch,
 ): Promise<CodecontextResponse> {
+  // Phase 4: try boocontext MCP first. Falls back to the HTTP sidecar if the
+  // MCP server is not available or the tool doesn't exist there.
+  try {
+    return await callBoocontext({ toolName: req.toolName, args: req.args });
+  } catch (err) {
+    console.warn(
+      `[codecontext_client] boocontext MCP unavailable for "${req.toolName}", falling back to HTTP sidecar: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
   // Step 1: realpath the project root, then realpath the requested target_dir
   // (defaulting to projectPath when the caller didn't pass one — the 12 wrappers
   // never pass target_dir; tests can override). A non-existent target_dir

apps/server/src/services/compaction.ts

@@ -24,6 +24,8 @@ import { SUMMARY_TEMPLATE } from './compaction-prompt.js';
 import * as modelContextLookup from './model-context.js';
 import { SENTINEL_KINDS } from './inference/sentinels.js';
 import type { OpenAiMessage } from './inference/payload.js';
+import { resolveModelEndpoint } from './inference/provider.js';
+import type { HookRunner } from './hooks.js';
 
 // v1.13.9: ratio-only overflow trigger. Fires compaction at 85% of ctx_max
 // (opencode session/overflow.ts pattern). Replaces the v1.11.0-era
@@ -346,20 +348,22 @@ interface CompletionResult {
   completionTokens: number;
 }
 
-async function callLlamaSwap(
+async function callLlm(
   config: Config,
   model: string,
   messages: OpenAiMessage[],
   log: FastifyBaseLogger,
 ): Promise<CompletionResult> {
-  const res = await fetch(`${config.LLAMA_SWAP_URL}/v1/chat/completions`, {
+  const { url, headers, model: resolvedModel } = resolveModelEndpoint(config, model);
+  const res = await fetch(`${url}/v1/chat/completions`, {
     method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ model, messages, stream: false }),
+    headers,
+    body: JSON.stringify({ model: resolvedModel, messages, stream: false }),
   });
   if (!res.ok) {
     const text = await res.text().catch(() => '');
-    throw new Error(`llama-swap returned ${res.status}: ${text.slice(0, 200)}`);
+    const prefix = model.startsWith('deepseek-') ? 'deepseek' : 'llama-swap';
+    throw new Error(`${prefix} returned ${res.status}: ${text.slice(0, 200)}`);
   }
   const json = (await res.json()) as {
     choices?: Array<{ message?: { content?: string } }>;
@@ -383,6 +387,8 @@ export interface ProcessInput {
   log: FastifyBaseLogger;
   broker: Broker;
   chatId: string;
+  /** vWhale: lifecycle hooks runner. Undefined when no hooks configured. */
+  hooks?: HookRunner;
 }
 
 // Runs one round of anchored rolling compaction on `chatId`. No-ops cleanly
@@ -497,6 +503,17 @@ export async function process(input: ProcessInput): Promise<void> {
     at: new Date().toISOString(),
   });
 
+  // vWhale: PreCompact hook (best-effort, non-blocking).
+  const msgBefore = messages.length;
+  if (input.hooks) {
+    input.hooks.run('PreCompact', {
+      event: 'PreCompact',
+      session_id: sessionId,
+      chat_id: chatId,
+      messages_before: msgBefore,
+    }).catch(() => {});
+  }
+
   // try/finally so the dot ALWAYS drops back to idle, even if the LLM call
   // throws or a downstream DB write fails. The succeeded flag gates the
   // 'compacted' frame + final log: we only signal completion to the UI when
@@ -506,7 +523,7 @@ export async function process(input: ProcessInput): Promise<void> {
   let result: CompletionResult | undefined;
   try {
     // 7. Single completion (no tools). Throws on llama-swap failure.
-    result = await callLlamaSwap(config, session.model, payload, log);
+    result = await callLlm(config, session.model, payload, log);
 
     // 7b. v1.11.3: fetch the model's true context window from llama-swap's
     // /upstream/<model>/props (the streaming completion doesn't carry it).
@@ -558,6 +575,18 @@ export async function process(input: ProcessInput): Promise<void> {
     `;
 
     succeeded = true;
+
+    // vWhale: PostCompact hook (best-effort, non-blocking).
+    if (input.hooks) {
+      input.hooks.run('PostCompact', {
+        event: 'PostCompact',
+        session_id: sessionId,
+        chat_id: chatId,
+        messages_before: msgBefore,
+        messages_after: sel.head.length,
+        summary: (result?.content ?? '').slice(0, 500),
+      }).catch(() => {});
+    }
   } finally {
     // Always restore the dot. Status='idle' (not 'error') even on failure —
     // the caller logs/re-surfaces the error separately; the dot doesn't

apps/server/src/services/hooks.ts

@@ -0,0 +1,299 @@
+/**
+ * vWhale: lifecycle hook runner. Hooks are shell commands that fire at key
+ * points in the inference pipeline. Each hook receives a JSON payload on
+ * stdin and can return JSON on stdout to influence behavior.
+ *
+ * Inspired by Whale's hook system with 11 lifecycle events. BooCode
+ * implements the most relevant subset: PreToolUse, PostToolUse,
+ * UserPromptSubmit, Stop, PreCompact, PostCompact.
+ *
+ * Config: JSON file at HOOKS_CONFIG_PATH (default /data/hooks.json).
+ * Format:
+ * ```json
+ * {
+ *   "hooks": {
+ *     "PreToolUse": [
+ *       { "match": "shell_run", "command": "python3 /data/hooks/check_shell.py", "timeout": 30 }
+ *     ],
+ *     "Stop": [
+ *       { "command": "node /data/hooks/log_turn.mjs" }
+ *     ]
+ *   }
+ * }
+ * ```
+ */
+
+import { spawn } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+import type { FastifyBaseLogger } from 'fastify';
+
+// ─── Events ───────────────────────────────────────────────────────────────
+
+export type HookEvent =
+  | 'PreToolUse'
+  | 'PostToolUse'
+  | 'UserPromptSubmit'
+  | 'Stop'
+  | 'PreCompact'
+  | 'PostCompact';
+
+const ALL_EVENTS: HookEvent[] = [
+  'PreToolUse',
+  'PostToolUse',
+  'UserPromptSubmit',
+  'Stop',
+  'PreCompact',
+  'PostCompact',
+];
+
+// ─── Config ────────────────────────────────────────────────────────────────
+
+export interface HookConfig {
+  /** Glob or exact tool name to match (PreToolUse/PostToolUse only). Omit or '*' for all. */
+  match?: string;
+  /** Shell command to run. Receives JSON payload on stdin. */
+  command: string;
+  /** Timeout in seconds (default 30). */
+  timeout?: number;
+}
+
+export interface HooksConfig {
+  hooks: Partial<Record<HookEvent, HookConfig[]>>;
+}
+
+// ─── Payloads ──────────────────────────────────────────────────────────────
+
+export interface PreToolUsePayload {
+  event: 'PreToolUse';
+  session_id: string;
+  tool_name: string;
+  tool_args: Record<string, unknown>;
+}
+
+export interface PostToolUsePayload {
+  event: 'PostToolUse';
+  session_id: string;
+  tool_name: string;
+  tool_args: Record<string, unknown>;
+  tool_result: unknown;
+  tool_error?: string;
+}
+
+export interface UserPromptSubmitPayload {
+  event: 'UserPromptSubmit';
+  session_id: string;
+  chat_id: string;
+  prompt: string;
+}
+
+export interface StopPayload {
+  event: 'Stop';
+  session_id: string;
+  chat_id: string;
+  last_assistant_text: string;
+  turn: number;
+}
+
+export interface PreCompactPayload {
+  event: 'PreCompact';
+  session_id: string;
+  chat_id: string;
+  messages_before: number;
+}
+
+export interface PostCompactPayload {
+  event: 'PostCompact';
+  session_id: string;
+  chat_id: string;
+  messages_before: number;
+  messages_after: number;
+  summary: string;
+}
+
+export type HookPayload =
+  | PreToolUsePayload
+  | PostToolUsePayload
+  | UserPromptSubmitPayload
+  | StopPayload
+  | PreCompactPayload
+  | PostCompactPayload;
+
+// ─── Response ──────────────────────────────────────────────────────────────
+
+export type HookDecision = 'pass' | 'warn' | 'block';
+
+export interface HookResponse {
+  decision?: HookDecision;
+  reason?: string;
+  /** When present, replaces the original tool args / user prompt. */
+  updated_input?: Record<string, unknown> | string;
+  /** Injected into the model's context for the next turn. */
+  additional_context?: string;
+}
+
+// ─── Runner ────────────────────────────────────────────────────────────────
+
+export interface HookRunner {
+  /** Run all hooks for the given event. Returns the effective response. */
+  run(event: HookEvent, payload: HookPayload, log?: FastifyBaseLogger): Promise<HookResponse>;
+}
+
+let hooksConfig: HooksConfig | null = null;
+let hooksPath: string | null = null;
+
+/** Load hooks config from disk. Missing file = no hooks. Never throws. */
+export function loadHooksConfig(path: string): HooksConfig {
+  hooksPath = path;
+  if (!existsSync(path)) {
+    hooksConfig = { hooks: {} };
+    return hooksConfig;
+  }
+  try {
+    const raw = readFileSync(path, 'utf8');
+    const parsed = JSON.parse(raw) as HooksConfig;
+    hooksConfig = {
+      hooks: { ...parsed.hooks },
+    };
+    // Validate event names
+    for (const event of Object.keys(hooksConfig.hooks)) {
+      if (!ALL_EVENTS.includes(event as HookEvent)) {
+        console.warn(`hooks: unknown event '${event}' in ${path} — ignoring`);
+        delete hooksConfig.hooks[event as HookEvent];
+      }
+    }
+  } catch (err) {
+    console.error(`hooks: failed to load ${path}`, err);
+    hooksConfig = { hooks: {} };
+  }
+  return hooksConfig;
+}
+
+/** Reload the config file (call after a PATCH). */
+export function reloadHooksConfig(): HooksConfig {
+  if (hooksPath) return loadHooksConfig(hooksPath);
+  hooksConfig = { hooks: {} };
+  return hooksConfig;
+}
+
+function getConfig(): HooksConfig {
+  return hooksConfig ?? { hooks: {} };
+}
+
+/** Create a HookRunner for the current config. */
+export function createHookRunner(): HookRunner {
+  return {
+    async run(event, payload, log): Promise<HookResponse> {
+      const configs = getConfig().hooks[event];
+      if (!configs || configs.length === 0) return { decision: 'pass' };
+
+      // Pre-filter by match pattern for tool events
+      const toolName = 'tool_name' in payload ? (payload as PreToolUsePayload).tool_name : undefined;
+
+      let effective: HookResponse = { decision: 'pass' };
+
+      for (const cfg of configs) {
+        // Skip if match doesn't apply
+        if (toolName && cfg.match && cfg.match !== '*' && cfg.match !== toolName) continue;
+
+        const result = await runSingleHook(cfg, payload, log);
+        // Merge decisions: block > warn > pass
+        if (result.decision === 'block') {
+          effective = { ...result, decision: 'block' };
+          break; // block is terminal
+        }
+        if (result.decision === 'warn' && effective.decision !== 'block') {
+          effective = { ...result, decision: 'warn' };
+        }
+        // Merge additional_context and updated_input
+        if (result.additional_context) {
+          effective.additional_context = effective.additional_context
+            ? effective.additional_context + '\n' + result.additional_context
+            : result.additional_context;
+        }
+        if (result.updated_input && !effective.updated_input) {
+          effective.updated_input = result.updated_input;
+        }
+      }
+
+      return effective;
+    },
+  };
+}
+
+async function runSingleHook(
+  cfg: HookConfig,
+  payload: HookPayload,
+  log?: FastifyBaseLogger,
+): Promise<HookResponse> {
+  const timeoutMs = (cfg.timeout ?? 30) * 1000;
+
+  return new Promise((resolve) => {
+    const child = spawn('sh', ['-c', cfg.command], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: timeoutMs,
+      env: { ...process.env },
+    });
+
+    const stdout: Buffer[] = [];
+    const stderr: Buffer[] = [];
+
+    child.stdout.on('data', (chunk: Buffer) => stdout.push(chunk));
+    child.stderr.on('data', (chunk: Buffer) => stderr.push(chunk));
+
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        child.kill('SIGTERM');
+        log?.warn({ event: payload.event, command: cfg.command }, 'hooks: timeout');
+        resolve({ decision: 'warn', reason: 'hook timed out' });
+      }
+    }, timeoutMs);
+
+    child.on('error', (err) => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        log?.warn({ err, event: payload.event }, 'hooks: spawn error');
+        resolve({ decision: 'warn', reason: `hook failed: ${err.message}` });
+      }
+    });
+
+    child.on('close', (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+
+      const out = Buffer.concat(stdout).toString('utf8').trim();
+      const errOut = Buffer.concat(stderr).toString('utf8').trim();
+
+      if (code !== 0 && !out) {
+        log?.warn({ event: payload.event, code, stderr: errOut.slice(0, 200) }, 'hooks: non-zero exit');
+        resolve({ decision: 'warn', reason: `hook exited ${code}` });
+        return;
+      }
+
+      // Parse stdout as JSON response
+      if (out) {
+        try {
+          const parsed = JSON.parse(out) as HookResponse;
+          resolve(parsed);
+          return;
+        } catch {
+          // Not JSON — treat as pass with stdout as context
+          if (out.length > 0) {
+            resolve({ decision: 'pass', additional_context: out });
+            return;
+          }
+        }
+      }
+
+      resolve({ decision: 'pass' });
+    });
+
+    // Write payload to stdin
+    const json = JSON.stringify(payload);
+    child.stdin.write(json);
+    child.stdin.end();
+  });
+}

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

@@ -122,6 +122,8 @@ export async function finalizeStreamedRow(
     completionTokens: number | null;
     promptTokens: number | null;
     startedAt: string | null;
+    cacheTokens?: number | null;
+    reasoningTokens?: number | null;
     beforeComplete?: () => Promise<void>;
   },
 ): Promise<void> {
@@ -137,6 +139,8 @@ export async function finalizeStreamedRow(
         tokens_used = ${opts.completionTokens},
         ctx_used = ${opts.promptTokens},
         ctx_max = ${nCtx},
+        cache_tokens = ${opts.cacheTokens ?? null},
+        reasoning_tokens = ${opts.reasoningTokens ?? null},
         finished_at = clock_timestamp()
     WHERE id = ${opts.messageId}
     RETURNING tokens_used, ctx_used, ctx_max, finished_at
@@ -149,6 +153,8 @@ export async function finalizeStreamedRow(
     tokens_used: updated?.tokens_used ?? null,
     ctx_used: updated?.ctx_used ?? null,
     ctx_max: updated?.ctx_max ?? null,
+    cache_tokens: opts.cacheTokens ?? null,
+    reasoning_tokens: opts.reasoningTokens ?? null,
     started_at: opts.startedAt,
     finished_at: updated?.finished_at ?? null,
     model: opts.model,
@@ -188,7 +194,7 @@ export async function finalizeCompletion(
 ): Promise<void> {
   const { sessionId, chatId, assistantMessageId } = args;
   const content = stripToolMarkup(result.content, { final: true });
-  const { finishReason, promptTokens, completionTokens } = result;
+  const { finishReason, promptTokens, completionTokens, cacheReadTokens, reasoningTokens } = result;
 
   // v1.11.3: see executeToolPhase for the rationale.
   const mctx = await modelContext.getModelContext(session.model);
@@ -203,6 +209,8 @@ export async function finalizeCompletion(
         tokens_used = ${completionTokens},
         ctx_used = ${promptTokens},
         ctx_max = ${nCtx},
+        cache_tokens = ${cacheReadTokens ?? null},
+        reasoning_tokens = ${reasoningTokens ?? null},
         model = ${session.model},
         finished_at = clock_timestamp()
     WHERE id = ${assistantMessageId}
@@ -268,6 +276,8 @@ export async function finalizeCompletion(
     tokens_used: updated?.tokens_used ?? null,
     ctx_used: updated?.ctx_used ?? null,
     ctx_max: updated?.ctx_max ?? null,
+    cache_tokens: cacheReadTokens ?? null,
+    reasoning_tokens: reasoningTokens ?? null,
     started_at: startedAt,
     finished_at: updated?.finished_at ?? null,
     model: session.model,

apps/server/src/services/inference/llama-args-validator.ts

@@ -131,23 +131,13 @@ export function isManagedFlag(flag: string): boolean {
 
 const SHADOW_CONTEXT = ['-c', '--ctx-size'];
 
-const SHADOW_CACHE = ['-ctk', '--cache-type-k', '-ctv', '--cache-type-v'];
+// Empty: agents should be able to opt into cache-type flags (lift analysis
+// found these are high-value features, not safety concerns).
+const SHADOW_CACHE: string[] = [];
 
-const SHADOW_SPEC = [
-  '--spec-default',
-  '--spec-type',
-  '--spec-ngram-size-n',
-  '--spec-ngram-size',
-  '--draft-min',
-  '--draft-max',
-  '--spec-draft-n-max',
-  '--spec-draft-n-min',
-  '--spec-draft-p-min',
-  '--spec-draft-p-split',
-  '--spec-ngram-mod-n-match',
-  '--spec-ngram-mod-n-min',
-  '--spec-ngram-mod-n-max',
-];
+// Empty: ngram speculative decoding is a performance feature agents should
+// be able to enable.
+const SHADOW_SPEC: string[] = [];
 
 const SHADOW_TEMPLATE = [
   '--chat-template',
@@ -160,7 +150,6 @@ const SHADOW_TEMPLATE = [
 // Shadowing flags that take no value — a boolean switch — so the stripper must
 // not also drop the following token.
 const VALUELESS_SHADOW_FLAGS: ReadonlySet<string> = new Set([
-  '--spec-default',
   '--jinja',
   '--no-jinja',
 ]);

apps/server/src/services/inference/provider.ts

@@ -1,4 +1,5 @@
 import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
+import { createDeepSeek } from '@ai-sdk/deepseek';
 import type { LanguageModel } from 'ai';
 
 // v1.13.1-A: AI SDK provider against llama-swap. baseURL is threaded from
@@ -11,6 +12,12 @@ import type { LanguageModel } from 'ai';
 // llama-sidecar instead. A fresh provider is created per call (not cached)
 // because the X-Agent-Flags header varies per agent. The llama-swap path
 // stays cached since it has no per-request headers.
+//
+// vDeepSeek: when the model ID starts with 'deepseek-' and DEEPSEEK_API_KEY
+// is set, route through the official @ai-sdk/deepseek provider (not
+// openai-compatible) so DeepSeek-specific features work: providerMetadata
+// with promptCacheHitTokens/promptCacheMissTokens, reasoning via
+// LanguageModelV4Usage.outputTokens.reasoning, and thinking-mode options.
 
 const swapCache = new Map<string, ReturnType<typeof createOpenAICompatible>>();
 
@@ -41,7 +48,28 @@ function sidecarProvider(
   });
 }
 
-export type InferenceRoute = 'swap' | 'sidecar';
+const DEEPSEEK_MODEL_PREFIX = 'deepseek-';
+
+export function isDeepSeekModel(modelId: string): boolean {
+  return modelId.startsWith(DEEPSEEK_MODEL_PREFIX);
+}
+
+let deepseekProviderCache: ReturnType<typeof createDeepSeek> | null = null;
+
+function getDeepSeekProvider(
+  apiKey: string,
+  baseURL: string,
+): ReturnType<typeof createDeepSeek> {
+  if (!deepseekProviderCache) {
+    deepseekProviderCache = createDeepSeek({
+      apiKey,
+      baseURL,
+    });
+  }
+  return deepseekProviderCache;
+}
+
+export type InferenceRoute = 'swap' | 'sidecar' | 'deepseek';
 
 export interface RoutingInfo {
   route: InferenceRoute;
@@ -55,13 +83,32 @@ interface AgentLike {
 interface ConfigLike {
   LLAMA_SWAP_URL: string;
   LLAMA_SIDECAR_URL?: string;
+  DEEPSEEK_API_KEY?: string;
+  DEEPSEEK_BASE_URL?: string;
 }
 
-export function resolveRoute(agent: AgentLike | null): RoutingInfo {
+export function resolveRoute(
+  agent: AgentLike | null,
+  config?: ConfigLike,
+  modelId?: string,
+): RoutingInfo {
+  // vDeepSeek: if the model starts with deepseek- and DEEPSEEK_API_KEY is set,
+  // route through the DeepSeek provider. Checked first so DeepSeek models
+  // always bypass llama-swap/sidecar even when those are also configured.
+  if (modelId?.startsWith(DEEPSEEK_MODEL_PREFIX) && config?.DEEPSEEK_API_KEY) {
+    return { route: 'deepseek', flags: null };
+  }
+  // When llama_extra_args are explicitly set, route through sidecar with them.
   const flags = agent?.llama_extra_args;
   if (flags && flags.length > 0) {
     return { route: 'sidecar', flags };
   }
+  // When LLAMA_SIDECAR_URL is configured (even without per-agent flags),
+  // route through sidecar to pick up the default base args (cache quant,
+  // spec decoding, slot save, etc.). Fall back to llama-swap otherwise.
+  if (config?.LLAMA_SIDECAR_URL) {
+    return { route: 'sidecar', flags: [] };
+  }
   return { route: 'swap', flags: null };
 }
 
@@ -70,15 +117,46 @@ export function upstreamModel(
   modelId: string,
   agent?: AgentLike | null,
 ): LanguageModel {
-  const { route, flags } = resolveRoute(agent ?? null);
+  const { route, flags } = resolveRoute(agent ?? null, config, modelId);
+  if (route === 'deepseek') {
+    return getDeepSeekProvider(
+      config.DEEPSEEK_API_KEY!,
+      config.DEEPSEEK_BASE_URL ?? 'https://api.deepseek.com',
+    ).chat(modelId);
+  }
   if (route === 'sidecar') {
     const url = config.LLAMA_SIDECAR_URL;
     if (!url) {
-      throw new Error(
-        `Agent has llama_extra_args but LLAMA_SIDECAR_URL is not set`,
-      );
+      throw new Error(`Sidecar route selected but LLAMA_SIDECAR_URL is not set`);
     }
-    return sidecarProvider(url, flags!).chatModel(modelId);
+    return sidecarProvider(url, (flags ?? [])).chatModel(modelId);
   }
   return getSwapProvider(config.LLAMA_SWAP_URL).chatModel(modelId);
 }
+
+/** Resolve the API endpoint for non-streaming calls (compaction, task-model).
+ *  Returns the URL + model + optional auth header for direct fetch() usage. */
+export function resolveModelEndpoint(
+  config: ConfigLike,
+  modelId: string,
+): { url: string; model: string; headers: Record<string, string> } {
+  const baseHeaders: Record<string, string> = { 'Content-Type': 'application/json' };
+  if (modelId.startsWith(DEEPSEEK_MODEL_PREFIX) && config.DEEPSEEK_API_KEY) {
+    const baseURL = (config.DEEPSEEK_BASE_URL ?? 'https://api.deepseek.com').replace(/\/+$/, '');
+    return {
+      url: baseURL,
+      model: modelId,
+      headers: { ...baseHeaders, Authorization: `Bearer ${config.DEEPSEEK_API_KEY}` },
+    };
+  }
+  return {
+    url: config.LLAMA_SWAP_URL.replace(/\/+$/, ''),
+    model: modelId,
+    headers: baseHeaders,
+  };
+}
+
+/** Invalidate the cached DeepSeek provider (e.g. when env vars change at runtime). */
+export function resetDeepSeekProvider(): void {
+  deepseekProviderCache = null;
+}

apps/server/src/services/inference/stream-phase-adapter.ts

@@ -13,7 +13,7 @@ import type { OpenAiMessage } from './payload.js';
 import { extractToolCallBlocks } from './tool-call-parser.js';
 import { classifyStreamError } from './stream-error-classifier.js';
 import type { StreamResult } from './types.js';
-import { upstreamModel } from './provider.js';
+import { isDeepSeekModel, upstreamModel } from './provider.js';
 import {
   jsonSchema,
   streamText,
@@ -51,6 +51,9 @@ export interface StreamOptions {
   dry_base?: number | null;
   dry_allowed_length?: number | null;
   dry_penalty_last_n?: number | null;
+  // vDeepSeek: thinking/reasoning effort. Maps to DeepSeek's reasoning_effort
+  // API param for deepseek-v4-flash / deepseek-v4-pro models.
+  reasoning_effort?: 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 }
 
 // P5: the 10-field sampler-options literal that was copy-pasted at 4 sites
@@ -74,6 +77,7 @@ export function samplerOptsFromAgent(agent: Agent | null): SamplerOpts {
     dry_base: agent?.dry_base ?? undefined,
     dry_allowed_length: agent?.dry_allowed_length ?? undefined,
     dry_penalty_last_n: agent?.dry_penalty_last_n ?? undefined,
+    reasoning_effort: agent?.reasoning_effort ?? undefined,
   };
 }
 
@@ -272,6 +276,19 @@ export async function streamCompletion(
   // before this. They now go through the same extraBody path as the new params.
   const samplerBody = buildSamplerProviderOptions(opts);
 
+  // vDeepSeek: build providerOptions.deepseek for DeepSeek V4 models.
+  let deepseekProviderOptions:
+    | { thinking: { type: 'enabled' | 'disabled' }; reasoningEffort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max' }
+    | undefined;
+  if (isDeepSeekModel(model)) {
+    const dsEffort = opts.reasoning_effort;
+    const thinkingEnabled = dsEffort && dsEffort !== 'off';
+    deepseekProviderOptions = {
+      thinking: { type: thinkingEnabled ? 'enabled' : 'disabled' },
+      ...(thinkingEnabled ? { reasoningEffort: dsEffort } : {}),
+    };
+  }
+
   // F6: per-chunk stall deadline. If the model stops emitting chunks for
   // STALL_TIMEOUT_MS the stallAc fires through AbortSignal.any; the post-loop
   // abort check below then throws AbortError → handleAbortOrError writes
@@ -297,7 +314,14 @@ export async function streamCompletion(
     ...(typeof opts.temperature === 'number' ? { temperature: opts.temperature } : {}),
     ...(typeof opts.top_p === 'number' ? { topP: opts.top_p } : {}),
     ...(typeof opts.presence_penalty === 'number' ? { presencePenalty: opts.presence_penalty } : {}),
-    ...(samplerBody ? { providerOptions: { openaiCompatible: samplerBody } } : {}),
+    ...(samplerBody || deepseekProviderOptions
+      ? {
+          providerOptions: {
+            ...(samplerBody ? { openaiCompatible: samplerBody } : {}),
+            ...(deepseekProviderOptions ? { deepseek: deepseekProviderOptions } : {}),
+          },
+        }
+      : {}),
     abortSignal: effectiveSignal,
   });
 
@@ -401,12 +425,26 @@ export async function streamCompletion(
 
   // Usage lands as a promise on the result; awaiting after fullStream is
   // drained is safe. AI SDK v6 names: `inputTokens` / `outputTokens`.
+  // Some providers (llama-swap via openai-compatible) return plain numbers;
+  // others (deepseek via @ai-sdk/deepseek) return {total, cacheRead, noCache, ...}.
   let promptTokens: number | null = null;
   let completionTokens: number | null = null;
+  let cacheReadTokens: number | null = null;
+  let reasoningTokens: number | null = null;
   try {
     const usage = await result.usage;
-    if (typeof usage.inputTokens === 'number') promptTokens = usage.inputTokens;
-    if (typeof usage.outputTokens === 'number') completionTokens = usage.outputTokens;
+    if (typeof usage.inputTokens === 'number') {
+      promptTokens = usage.inputTokens;
+    } else if (usage.inputTokens && typeof usage.inputTokens === 'object') {
+      promptTokens = (usage.inputTokens as Record<string, number | undefined>).total ?? null;
+      cacheReadTokens = (usage.inputTokens as Record<string, number | undefined>).cacheRead ?? null;
+    }
+    if (typeof usage.outputTokens === 'number') {
+      completionTokens = usage.outputTokens;
+    } else if (usage.outputTokens && typeof usage.outputTokens === 'object') {
+      completionTokens = (usage.outputTokens as Record<string, number | undefined>).total ?? null;
+      reasoningTokens = (usage.outputTokens as Record<string, number | undefined>).reasoning ?? null;
+    }
   } catch {
     // Some providers omit usage on partial streams; leave both null.
   }
@@ -422,6 +460,13 @@ export async function streamCompletion(
     );
   }
 
+  if (cacheReadTokens !== null || reasoningTokens !== null) {
+    ctx.log.debug(
+      { promptTokens, completionTokens, cacheReadTokens, reasoningTokens, model },
+      'streamCompletion: deepseek usage breakdown',
+    );
+  }
+
   return {
     finishReason,
     content,
@@ -429,6 +474,10 @@ export async function streamCompletion(
     promptTokens,
     completionTokens,
     reasoning: reasoningAccumulated,
+    // vDeepSeek: optional usage breakdown populated when the provider returns
+    // structured usage (cache hit tokens, reasoning tokens).
+    cacheReadTokens: cacheReadTokens ?? undefined,
+    reasoningTokens: reasoningTokens ?? undefined,
   };
   } finally {
     // Clear the stall timer whether the stream completes normally, throws, or

apps/server/src/services/inference/tool-input-repair.ts

@@ -0,0 +1,179 @@
+/**
+ * vWhale: schema-based tool input repair. When the model emits tool call args
+ * that don't match the expected types (common with weaker models), apply
+ * heuristic repairs before falling through to the Zod parse.
+ *
+ * Inspired by Whale's RepairToolInputForSpec:
+ *   - Coerce string "true"/"false" → boolean
+ *   - Unwrap markdown autolinks in string fields: <file:///path> → /path
+ *   - Wrap bare values in arrays when schema expects array
+ *   - Convert "42.0" decimal string → "42" for integer fields
+ *   - Recurse into objects to repair nested properties
+ */
+
+export interface ToolInputRepair {
+  field: string;
+  kind: string;
+  detail: string;
+}
+
+const MARKDOWN_AUTOLINK_RE = /^<(?:file|path):\/\/(.+?)>$/;
+
+/**
+ * Attempt to repair tool call args against the tool's JSON Schema.
+ * Returns the (possibly modified) args plus a list of repairs applied.
+ */
+export function repairToolInput(
+  schema: Record<string, unknown> | undefined,
+  args: Record<string, unknown>,
+): { repaired: Record<string, unknown>; repairs: ToolInputRepair[] } {
+  const repairs: ToolInputRepair[] = [];
+  if (!schema || typeof schema !== 'object') {
+    return { repaired: args, repairs };
+  }
+
+  const properties = (schema as Record<string, unknown>).properties as
+    Record<string, unknown> | undefined;
+  if (!properties) {
+    return { repaired: args, repairs };
+  }
+
+  const required = new Set<string>(
+    Array.isArray((schema as Record<string, unknown>).required)
+      ? (schema as Record<string, unknown>).required as string[]
+      : [],
+  );
+
+  const repaired: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(args)) {
+    const propSchema = properties[key] as Record<string, unknown> | undefined;
+    if (propSchema && value !== null && value !== undefined) {
+      repaired[key] = repairValue(key, propSchema, value, repairs, required.has(key));
+    } else {
+      repaired[key] = value;
+    }
+  }
+
+  // Drop keys not in the schema (only for required fields that are missing)
+  // to avoid polluting the model with hallucinated params.
+  for (const key of Object.keys(repaired)) {
+    if (!(key in properties)) {
+      repairs.push({ field: key, kind: 'removed_unknown', detail: `Removed unknown parameter '${key}'` });
+      delete repaired[key];
+    }
+  }
+
+  return { repaired, repairs };
+}
+
+function repairValue(
+  field: string,
+  schema: Record<string, unknown>,
+  value: unknown,
+  repairs: ToolInputRepair[],
+  required: boolean,
+): unknown {
+  const schemaType = schema.type;
+  const isArray = schemaType === 'array' || Array.isArray(schemaType)
+    ? schemaType === 'array' || (Array.isArray(schemaType) && schemaType.includes('array'))
+    : false;
+  const isObject = schemaType === 'object';
+  const isBoolean = schemaType === 'boolean';
+  const isInteger = schemaType === 'integer' || schemaType === 'number';
+  const isString = schemaType === 'string';
+
+  // --- Array repair: wrap bare value or empty object ---
+  if (isArray) {
+    if (!Array.isArray(value)) {
+      if (typeof value === 'string') {
+        // Try parsing as JSON array first
+        try {
+          const parsed = JSON.parse(value);
+          if (Array.isArray(parsed)) {
+            repairs.push({ field, kind: 'parsed_json_array', detail: `Parsed string as JSON array for '${field}'` });
+            return parsed;
+          }
+        } catch { /* not JSON */ }
+      }
+      if (typeof value === 'object' && value !== null && Object.keys(value).length === 0) {
+        if (required) {
+          repairs.push({ field, kind: 'empty_object_to_array', detail: `Converted empty object to empty array for '${field}'` });
+          return [];
+        }
+        repairs.push({ field, kind: 'empty_object_to_undefined', detail: `Removed empty object for optional array '${field}'` });
+        return undefined;
+      }
+      repairs.push({ field, kind: 'wrapped_in_array', detail: `Wrapped bare value in array for '${field}'` });
+      return [value];
+    }
+    // Recurse into array items
+    const itemsSchema = schema.items as Record<string, unknown> | undefined;
+    if (itemsSchema) {
+      return value.map((item, i) => repairValue(`${field}[${i}]`, itemsSchema, item, repairs, required));
+    }
+    return value;
+  }
+
+  // --- Object repair: recurse into properties ---
+  if (isObject && typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    const props = (schema.properties as Record<string, unknown>) ?? {};
+    const repaired: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      const propSchema = props[k] as Record<string, unknown> | undefined;
+      if (propSchema) {
+        repaired[k] = repairValue(`${field}.${k}`, propSchema, v, repairs, required);
+      } else {
+        repaired[k] = v;
+      }
+    }
+    return repaired;
+  }
+
+  // --- String repair: unwrap markdown autolinks ---
+  if (isString && typeof value === 'string') {
+    const match = value.match(MARKDOWN_AUTOLINK_RE);
+    if (match) {
+      repairs.push({ field, kind: 'unwrapped_markdown_link', detail: `Unwrapped markdown autolink for '${field}': ${value}` });
+      return match[1];
+    }
+    return value;
+  }
+
+  // --- Boolean coercion ---
+  if (isBoolean && typeof value === 'string') {
+    const lower = value.toLowerCase();
+    if (lower === 'true') {
+      repairs.push({ field, kind: 'coerced_to_boolean', detail: `Coerced string '${value}' → true for '${field}'` });
+      return true;
+    }
+    if (lower === 'false') {
+      repairs.push({ field, kind: 'coerced_to_boolean', detail: `Coerced string '${value}' → false for '${field}'` });
+      return false;
+    }
+    return value;
+  }
+
+  // --- Integer coercion: "42.0" → 42 ---
+  if (isInteger && typeof value === 'string') {
+    const num = Number(value);
+    if (!Number.isNaN(num)) {
+      repairs.push({ field, kind: 'coerced_to_number', detail: `Coerced string '${value}' → ${num} for '${field}'` });
+      return num;
+    }
+    return value;
+  }
+
+  // --- Integer coercion: boolean → 0/1 ---
+  if (isInteger && typeof value === 'boolean') {
+    repairs.push({ field, kind: 'coerced_boolean_to_integer', detail: `Coerced boolean ${value} → ${value ? 1 : 0} for '${field}'` });
+    return value ? 1 : 0;
+  }
+
+  // --- Empty string to null for optional fields ---
+  if (value === '' && !required) {
+    repairs.push({ field, kind: 'empty_string_to_undefined', detail: `Converted empty string for optional '${field}'` });
+    return undefined;
+  }
+
+  return value;
+}

apps/server/src/services/inference/tool-phase.ts

@@ -6,6 +6,7 @@ import type { ToolExecCtx } from '../tools.js';
 import { matchToolGlob } from '../agents.js';
 import { maybeFlagForCompaction } from './payload.js';
 import { insertParts, partsFromAssistantMessage, partsFromToolMessage } from './parts.js';
+import { getServerPermission } from '../mcp-client.js';
 // v1.13.16: richer unknown-tool error so the model can self-correct when it
 // drifts to a Claude Code tool name (e.g. read_file → suggest view_file).
 // Applies to all unknown tool names, not just <invoke>-derived ones — at the
@@ -17,7 +18,9 @@ import { formatUnknownToolError } from './tool-suggestions.js';
 // prompted about paths we couldn't grant anyway (e.g. /etc/passwd).
 import { resolveGrantRoot } from '../grant_resolver.js';
 import { stripToolMarkup } from './tool-call-parser.js';
+import { repairToolInput } from './tool-input-repair.js';
 import type { FailureKind } from './mistake-tracker.js';
+import { insertToolTrace, updateToolTrace } from '../tool-traces.js';
 import type {
   InferenceContext,
   StreamResult,
@@ -34,6 +37,8 @@ async function executeToolCall(
   toolCall: ToolCall,
   extraRoots: readonly string[],
   toolCtx?: ToolExecCtx,
+  hooks?: import('../hooks.js').HookRunner,
+  sessionId?: string,
 ): Promise<{ output: unknown; truncated: boolean; error?: string; outcome: FailureKind | 'success' }> {
   // v#12 MistakeTracker: every return path carries an `outcome` so the turn
   // loop can detect a run of heterogeneous failures. The failure taxonomy
@@ -48,7 +53,61 @@ async function executeToolCall(
       outcome: 'tool_not_found',
     };
   }
-  const parsed = tool.inputSchema.safeParse(toolCall.args);
+  // MCP permission gate — block deny/ask before any Zod parsing or execution
+  const mcpPerm = getServerPermission(toolCall.name);
+  if (mcpPerm === 'deny') {
+    return { output: null, truncated: false, error: `blocked: MCP server denied tool '${toolCall.name}'`, outcome: 'permission_denied' };
+  }
+  if (mcpPerm === 'ask') {
+    return { output: null, truncated: false, error: `requires approval: tool '${toolCall.name}' needs user approval`, outcome: 'permission_denied' };
+  }
+  // vWhale: schema-based tool input repair. If the Zod parse fails, attempt
+  // heuristic repairs (type coercion, markdown-link unwrapping, array wrapping)
+  // and retry. Logs repairs for debugging.
+  let args = toolCall.args;
+  let parsed = tool.inputSchema.safeParse(args);
+  if (!parsed.success) {
+    const schema = tool.jsonSchema?.function?.parameters;
+    if (schema) {
+      const { repaired: repairedArgs, repairs } = repairToolInput(
+        schema as Record<string, unknown>,
+        args as Record<string, unknown>,
+      );
+      if (repairs.length > 0) {
+        const retry = tool.inputSchema.safeParse(repairedArgs);
+        if (retry.success) {
+          args = repairedArgs;
+          parsed = retry;
+        }
+      }
+    }
+  }
+  // vWhale: PreToolUse hook — can block execution.
+  if (hooks && sessionId) {
+    const hookResult = await hooks.run('PreToolUse', {
+      event: 'PreToolUse',
+      session_id: sessionId,
+      tool_name: toolCall.name,
+      tool_args: args as Record<string, unknown>,
+    });
+    if (hookResult.decision === 'block') {
+      return {
+        output: null,
+        truncated: false,
+        error: `blocked by hook: ${hookResult.reason ?? 'PreToolUse denied'}`,
+        outcome: 'permission_denied',
+      };
+    }
+    // Apply updated_input if the hook rewrote the args
+    if (hookResult.updated_input && typeof hookResult.updated_input === 'object') {
+      const reParsed = tool.inputSchema.safeParse(hookResult.updated_input);
+      if (reParsed.success) {
+        args = hookResult.updated_input as Record<string, unknown>;
+        parsed = reParsed;
+      }
+    }
+  }
+
   if (!parsed.success) {
     // v1.12 Track B.2: enrich the zod-reject path so the model sees a
     // one-line, tool-named hint ("tool 'search_symbols' rejected — query:
@@ -117,6 +176,7 @@ export async function executeToolPhase(
   session: Session,
   projectRoot: string,
   agent?: Agent | null,
+  turnNumber?: number,
 ): Promise<ToolPhaseResult> {
   const { sessionId, chatId, assistantMessageId } = args;
   const content = stripToolMarkup(result.content, { final: true });
@@ -183,6 +243,8 @@ export async function executeToolPhase(
     tokens_used: updated?.tokens_used ?? null,
     ctx_used: updated?.ctx_used ?? null,
     ctx_max: updated?.ctx_max ?? null,
+    cache_tokens: result.cacheReadTokens ?? null,
+    reasoning_tokens: result.reasoningTokens ?? null,
     started_at: startedAt,
     finished_at: updated?.finished_at ?? null,
     model: session.model,
@@ -318,10 +380,64 @@ export async function executeToolPhase(
         });
         return;
       }
-      const tres = await executeToolCall(projectRoot, tc, session.allowed_read_paths, {
-        sql: ctx.sql,
-        sessionId,
+      // tool_trace instrumentation - start
+      const traceId = crypto.randomUUID();
+      const traceStartTime = Date.now();
+      const startedAtIso = new Date().toISOString();
+      insertToolTrace(ctx.sql, {
+        session_id: sessionId,
+        chat_id: chatId,
+        message_id: assistantMessageId,
+        turn_number: turnNumber ?? 0,
+        tool_name: tc.name,
+        tool_input: tc.args as Record<string, unknown>,
+      }).catch(() => {});
+      ctx.publish(sessionId, {
+        type: 'tool_trace_start',
+        trace_id: traceId,
+        message_id: assistantMessageId,
+        chat_id: chatId,
+        tool_name: tc.name,
+        tool_input: tc.args as Record<string, unknown>,
+        started_at: startedAtIso,
       });
+      const tres = await executeToolCall(
+        projectRoot, tc, session.allowed_read_paths,
+        { sql: ctx.sql, sessionId },
+        ctx.hooks, sessionId,
+      );
+      // tool_trace instrumentation - finish
+      const finishedAtIso = new Date().toISOString();
+      const latencyMs = Date.now() - traceStartTime;
+      updateToolTrace(ctx.sql, traceId, {
+        finished_at: finishedAtIso,
+        ...(tres.outcome === 'success' && tres.output != null ? { tool_output: JSON.stringify(tres.output) } : {}),
+        latency_ms: latencyMs,
+        outcome: tres.outcome,
+        ...(tres.error ? { error: tres.error } : {}),
+      }).catch(() => {});
+      ctx.publish(sessionId, {
+        type: 'tool_trace_finish',
+        trace_id: traceId,
+        message_id: assistantMessageId,
+        chat_id: chatId,
+        tool_name: tc.name,
+        finished_at: finishedAtIso,
+        outcome: tres.outcome,
+        latency_ms: latencyMs,
+        ...(tres.error ? { error: tres.error } : {}),
+      });
+      // vWhale: PostToolUse hook (best-effort, non-blocking).
+      if (ctx.hooks) {
+        ctx.hooks.run('PostToolUse', {
+          event: 'PostToolUse',
+          session_id: sessionId,
+          tool_name: tc.name,
+          tool_args: tc.args as Record<string, unknown>,
+          tool_result: tres.output,
+          tool_error: tres.error,
+        }).catch(() => {});
+      }
       // v#12 MistakeTracker: record the real execution outcome (success or a
       // FailureKind). This is the primary signal for heterogeneous-failure
       // detection.

apps/server/src/services/inference/turn.ts

@@ -37,6 +37,12 @@ import type {
   StreamResult,
   TurnArgs,
 } from './types.js';
+import { saveAgentSnapshot } from '../session-snapshots.js';
+// vWhale: auto-fix loop — after write tools, build the project and inject
+// errors. Uses execFile (no shell) against the project root.
+import { execFile } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
 import {
   runCapHitSummary,
   runDoomLoopSummary,
@@ -44,6 +50,71 @@ import {
   insertMistakeRecoverySentinel,
 } from './sentinel-summaries.js';
 
+// vWhale: auto-fix — detect build command from package.json, run it, return
+// error text for injection into next iteration. Best-effort, never throws.
+const BUILD_TIMEOUT_MS = 60_000;
+const BUILD_OUTPUT_CAP = 8_000;
+
+async function detectAndRunBuild(
+  ctx: InferenceContext,
+  projectRoot: string,
+  sessionId: string,
+  chatId: string,
+  model: string,
+  existingNote: string | undefined,
+): Promise<string | undefined> {
+  // Only run for DeepSeek models (local Qwen models don't benefit from build loop).
+  if (!model.startsWith('deepseek-')) return undefined;
+
+  // Detect build command from package.json in project root.
+  const pkgPath = join(projectRoot, 'package.json');
+  if (!existsSync(pkgPath)) return undefined;
+
+  let buildCmd: string | null = null;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as { scripts?: Record<string, string> };
+    if (pkg.scripts?.build) buildCmd = 'build';
+    else if (pkg.scripts?.compile) buildCmd = 'compile';
+    else if (pkg.scripts?.typecheck) buildCmd = 'typecheck';
+  } catch {
+    return undefined;
+  }
+  if (!buildCmd) return undefined;
+
+  // Detect package manager.
+  const hasPnpm = existsSync(join(projectRoot, 'pnpm-lock.yaml'));
+  const hasYarn = existsSync(join(projectRoot, 'yarn.lock'));
+  const pm = hasPnpm ? 'pnpm' : hasYarn ? 'yarn' : 'npm';
+
+  // Run the build.
+  try {
+    const out = await new Promise<string>((resolve, reject) => {
+      execFile(pm, ['run', buildCmd!], { cwd: projectRoot, timeout: BUILD_TIMEOUT_MS, maxBuffer: BUILD_OUTPUT_CAP * 2 },
+        (err, stdout, stderr) => {
+          if (err && (err as NodeJS.ErrnoException).code === 'ENOENT') {
+            resolve('');  // package manager not found — skip
+            return;
+          }
+          const merged = (stdout + '\n' + stderr).trim();
+          resolve(merged.slice(0, BUILD_OUTPUT_CAP));
+        },
+      );
+    });
+
+    if (!out) return undefined;  // build succeeded or no output
+    ctx.log.info({ sessionId, chatId, buildCmd, outputLen: out.length }, 'auto-fix: build failed');
+
+    // Truncate if existing note exists
+    const combined = existingNote
+      ? existingNote + '\n\n--- Build error ---\n' + out.slice(0, BUILD_OUTPUT_CAP - existingNote.length)
+      : '--- Build error ---\n' + out.slice(0, BUILD_OUTPUT_CAP);
+
+    return combined;
+  } catch {
+    return undefined;
+  }
+}
+
 // P5: MAX_STEPS moved to ./turn-config.ts (with resolveTurnConfig). Re-exported
 // here so the public surface (index.ts → './turn.js') is unchanged.
 export { MAX_STEPS } from './turn-config.js';
@@ -144,6 +215,7 @@ export async function runAssistantTurn(
           log: ctx.log,
           broker: ctx.broker,
           chatId,
+          hooks: ctx.hooks,
         });
       } catch (err) {
         ctx.log.warn({ err, chatId }, 'auto-compaction failed; clearing flag and proceeding');
@@ -214,6 +286,16 @@ export async function runAssistantTurn(
 
     // ---- non-tool finish → finalize and exit ----
     if (result.toolCalls.length === 0) {
+      // vWhale: Stop hook (best-effort, non-blocking).
+      if (ctx.hooks) {
+        ctx.hooks.run('Stop', {
+          event: 'Stop',
+          session_id: sessionId,
+          chat_id: chatId,
+          last_assistant_text: result.content.slice(0, 500),
+          turn: stepNumber,
+        }).catch(() => {});
+      }
       await finalizeCompletion(ctx, iterArgs, result, state.startedAt, iterSession);
       break;
     }
@@ -229,7 +311,7 @@ export async function runAssistantTurn(
     // ---- tool phase ----
     let toolPhaseResult: ToolPhaseResult;
     try {
-      toolPhaseResult = await executeToolPhase(ctx, iterArgs, result, state.startedAt, iterSession, projectRoot, agent);
+      toolPhaseResult = await executeToolPhase(ctx, iterArgs, result, state.startedAt, iterSession, projectRoot, agent, stepNumber);
     } catch (err) {
       // Tool phase errors are unexpected (individual tool failures are
       // caught inside executeToolPhase). Log and break.
@@ -249,6 +331,17 @@ export async function runAssistantTurn(
       recordStep(mistakeTracker, o);
     }
 
+    // vWhale: auto-fix — after write tools, attempt build and inject errors.
+    const WRITE_TOOLS = new Set(['edit_file', 'create_file', 'delete_file', 'apply_pending']);
+    const hasWriteTools = toolPhaseResult.toolCalls.some((tc) => WRITE_TOOLS.has(tc.name));
+    if (hasWriteTools) {
+      detectAndRunBuild(ctx, projectRoot, sessionId, chatId, iterSession.model, pendingRecoveryNote)
+        .then((buildError) => {
+          if (buildError) pendingRecoveryNote = buildError;
+        })
+        .catch(() => {});
+    }
+
     // v#12 MistakeTracker: post-tool decision (pure). 'stop' = the tool phase
     // returned a non-'continue' action ('paused' for user input, or
     // 'synthesis_done') — neither a nudge nor an escalate would change the
@@ -309,6 +402,35 @@ export async function runAssistantTurn(
     assistantMessageId = toolPhaseResult.nextAssistantId!;
   }
 
+  // vWhale: Stop hook at post-loop exit (best-effort, non-blocking).
+  if (ctx.hooks) {
+    const loaded = await loadContext(ctx.sql, sessionId, chatId);
+    const lastAssistant = loaded?.history?.slice().reverse().find(
+      (m: import('../../types/api.js').Message) => m.role === 'assistant',
+    );
+    const content = lastAssistant?.content ?? '';
+    ctx.hooks.run('Stop', {
+      event: 'Stop',
+      session_id: sessionId,
+      chat_id: chatId,
+      last_assistant_text: content.slice(0, 500),
+      turn: stepNumber,
+    }).catch(() => {});
+  }
+
+  // ---- persist agent snapshot (best-effort, never blocks inference) ----
+  const snapLoaded = await loadContext(ctx.sql, sessionId, chatId).catch(() => null);
+  if (snapLoaded) {
+    await saveAgentSnapshot(ctx.sql, chatId, {
+      session_id: sessionId,
+      model: snapLoaded.session.model,
+      agent: agent?.name ?? null,
+      mode: null,
+      turn_number: stepNumber,
+      messages: snapLoaded.history.map((m) => ({ role: m.role, content: m.content })),
+    }).catch(() => {});
+  }
+
   // ---- post-loop: step-cap sentinel ----
   // When the loop exits because stepNumber reached effectiveCap, the last
   // iteration's tool phase returned 'continue' with a nextAssistantId that

apps/server/src/services/inference/types.ts

@@ -19,6 +19,7 @@ import type {
   UserStreamFrame,
 } from '../../types/api.js';
 import type { Broker } from '../broker.js';
+import type { HookRunner } from '../hooks.js';
 import type { MistakeState } from './mistake-tracker.js';
 
 export interface StreamPhaseState {
@@ -45,6 +46,9 @@ export interface InferenceFrame {
     | 'error'
     | 'flow_run_started'
     | 'flow_run_step_updated'
+    // tool trace frames
+    | 'tool_trace_start'
+    | 'tool_trace_finish'
     // arena frames
     | 'battle_started'
     | 'contestant_updated'
@@ -77,8 +81,19 @@ export interface InferenceFrame {
   started_at?: string | null;
   finished_at?: string | null;
   model?: string;
+  cache_tokens?: number | null;
+  reasoning_tokens?: number | null;
   session_id?: string;
   name?: string;
+  // tool trace frames
+  trace_id?: string;
+  tool_name?: string;
+  tool_input?: Record<string, unknown>;
+  tool_output?: string | null;
+  latency_ms?: number;
+  outcome?: string;
+  // agent snapshot restore
+  agent?: string | null;
   // orchestrator frames ([D-6])
   run_id?: string;
   flow_name?: string;
@@ -117,6 +132,9 @@ export interface InferenceContext {
   // inference goes through `publish`); keeping a separate field avoids
   // tempting other code paths into bypassing the session-id binding.
   broker: Broker;
+  // vWhale: lifecycle hooks runner. Undefined when no hooks configured.
+  // Hook calls are best-effort — a failing hook never blocks inference.
+  hooks?: HookRunner;
 }
 
 export interface StreamResult {
@@ -128,6 +146,12 @@ export interface StreamResult {
   // v1.13.1-C: reasoning text accumulated across reasoning-delta parts.
   // Empty string when the model doesn't emit reasoning (most cases).
   reasoning: string;
+  // vDeepSeek: optional cache-hit token count from DeepSeek's API.
+  // Only populated when using @ai-sdk/deepseek provider (not llama-swap).
+  cacheReadTokens?: number;
+  // vDeepSeek: optional reasoning token count from DeepSeek's API.
+  // Only populated when using @ai-sdk/deepseek provider (not llama-swap).
+  reasoningTokens?: number;
 }
 
 export interface TurnArgs {

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

@@ -31,11 +31,14 @@ interface McpToolDef {
   annotations?: McpToolAnnotations;
 }
 
+export type McpPermission = 'allow' | 'ask' | 'deny';
+
 interface ServerState {
   client: Client;
   transport: StreamableHTTPClientTransport | StdioClientTransport;
   tools: ToolDef<Record<string, unknown>>[];
   type: 'streamableHttp' | 'stdio';
+  permission: McpPermission;
 }
 
 // ---- Module-level state ----
@@ -137,6 +140,14 @@ export async function callTool(
   }
 }
 
+/** Return the permission level for a given MCP server. Defaults to 'allow' if unknown. */
+export function getServerPermission(prefixedToolName: string): McpPermission {
+  const serverName = toolToServer.get(prefixedToolName);
+  if (!serverName) return 'allow';
+  const state = servers.get(serverName);
+  return state?.permission ?? 'allow';
+}
+
 /** Return all wrapped ToolDefs from all connected servers, flattened. */
 export function getTools(): ToolDef<Record<string, unknown>>[] {
   const all: ToolDef<Record<string, unknown>>[] = [];
@@ -214,7 +225,8 @@ async function connectServer(entry: McpServerEntry): Promise<void> {
     toolToServer.set(wrapped.name, name);
   }
 
-  servers.set(name, { client, transport, tools, type: config.type });
+  const permission = (config as { permission?: McpPermission }).permission ?? 'allow';
+  servers.set(name, { client, transport, tools, type: config.type, permission });
 
   log!.info(
     { server: name, type: config.type, count: tools.length, names: tools.map((t) => t.name) },

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

@@ -17,12 +17,15 @@ import type { FastifyBaseLogger } from 'fastify';
 
 // ---- Zod schema ----
 
+const McpPermissionSchema = z.enum(['allow', 'ask', 'deny']).default('allow');
+
 const McpServerConfigSchema = z.discriminatedUnion('type', [
   z.object({
     type: z.literal('streamableHttp'),
     url: z.string().url(),
     headers: z.record(z.string()).optional(),
     enabled: z.boolean().default(true),
+    permission: McpPermissionSchema,
   }),
   z.object({
     type: z.literal('stdio'),
@@ -30,6 +33,7 @@ const McpServerConfigSchema = z.discriminatedUnion('type', [
     args: z.array(z.string()).default([]),
     env: z.record(z.string()).optional(),
     enabled: z.boolean().default(true),
+    permission: McpPermissionSchema,
   }),
 ]);