feat(coder): add model resolution core + multi-batch matcher

Model resolution (from oh-my-openagent/model-core): 6-step priority
resolution pipeline (UI select -> user config -> category default ->
user fallback -> policy chain -> system default), provider fallback
chains, fuzzy model matching, error classification, provider-specific
model ID transforms. 14 files, zero runtime deps.

Multi-batch matcher (from boocontext-audit): 6 batch types
(Observational, Actionable, PreviouslyApplied, Disambiguation,
ResponseAnalysis, LowCriticality) for behavioral guideline evaluation.
RelationalResolver with iterative convergence (DEPENDS_ON,
PRIORITIZES, ENTAILS, TAG_ALL, TAG_PRIORITIZES). SchematicGenerator
abstract class with retry and execution plans. 4 files.

.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)

.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

apps/booterm/src/index.ts

@@ -4,6 +4,7 @@ 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 { registerWsAttachRoute } from './ws/attach.js';
 
 async function main(): Promise<void> {
@@ -33,6 +34,7 @@ async function main(): Promise<void> {
 
   registerHealthRoutes(app);
   registerTerminalRoutes(app, config.TMUX_CONF_PATH);
+  registerSessionRoutes(app);
   registerWsAttachRoute(app, config.TMUX_CONF_PATH);
 
   const shutdown = async (signal: string) => {

apps/booterm/src/pty/registry.ts

@@ -0,0 +1,44 @@
+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);
+}
+
+export function list(): SessionMeta[] {
+  return Array.from(sessions.values());
+}
+
+export function get(paneId: string): SessionMeta | undefined {
+  return sessions.get(paneId);
+}

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 } 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({
@@ -157,6 +160,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/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/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/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/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/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/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/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 = [
+// Empty: ngram speculative decoding is a performance feature agents should
-  '--spec-default',
+// be able to enable.
-  '--spec-type',
+const SHADOW_SPEC: string[] = [];
-  '--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',
-];
 
 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',
 ]);

codecontext/Dockerfile

@@ -17,18 +17,22 @@ COPY go.mod ./
 COPY shim.go ./
 RUN CGO_ENABLED=0 GOOS=linux go build -o /build/shim-bin ./
 
-# Stage 2: boocontext MCP builder
+# Stage 2: boocontext MCP builder (pnpm project)
 FROM node:20-alpine AS boocontext-builder
 WORKDIR /build/boocontext
 RUN apk add --no-cache git python3 make g++ ca-certificates
+RUN npm install -g pnpm@9 --silent
 COPY fork.tar.gz /build/fork.tar.gz
 RUN mkdir -p /build/boocontext && tar -xzf /build/fork.tar.gz -C /build/boocontext
 WORKDIR /build/boocontext
-RUN npm ci && npm run build
+RUN pnpm install --frozen-lockfile && pnpm run build
 
 # Stage 3: Runtime
 FROM alpine:3.20
-RUN apk add --no-cache ca-certificates nodejs uv
+# uv intentionally not installed — container network blocks astral.sh.
+# tree-sitter-analyzer child server (uvx) won't start in-container, but
+# boocontext logs a graceful warning; TSA-backed tools fall through.
+RUN apk add --no-cache ca-certificates nodejs
 COPY --from=shim-builder /build/shim-bin /usr/local/bin/shim
 COPY --from=boocontext-builder /build/boocontext/dist /usr/local/lib/boocontext/dist
 COPY --from=boocontext-builder /build/boocontext/node_modules /usr/local/lib/boocontext/node_modules

codecontext/openspec/codesight-merge.md

@@ -0,0 +1,90 @@
+# codecontext — codesight feature merge
+
+Port codesight's highest-value analysis capabilities into codecontext as 4 new MCP tools. All work in `/opt/forks/codecontext` (Go). BooCode wrapper tools in a follow-up batch.
+
+## New tools
+
+### 1. `get_blast_radius` (Tier 1)
+
+**Input:** `file_path` (required), `target_dir` (optional)
+**Output:** markdown listing all files, routes, and symbols that depend (transitively) on the given file.
+
+Algorithm: build a reverse adjacency map from `s.graph.Edges` (filter by `type == "imports"`), then BFS outward from the target file's node. Report each affected file with its symbol count and distance from the source.
+
+Codesight reference: `detectors/blast-radius.ts` (128 lines). The Go port is simpler — codecontext already has the edge graph; codesight had to build its own.
+
+~50 lines of Go (handler + BFS).
+
+### 2. `get_hot_files` (Tier 1)
+
+**Input:** `target_dir` (optional), `limit` (optional, default 20)
+**Output:** ranked list of most-imported files with import count.
+
+Algorithm: count incoming `"imports"` edges per file node. Sort descending. Return top N.
+
+Codesight reference: `detectors/graph.ts` hot-files metric. codecontext's `identifyHotspotFiles()` at `relationships.go:286` already computes this — the tool just needs to expose it.
+
+~30 lines of Go (handler + sort).
+
+### 3. `get_routes` (Tier 2)
+
+**Input:** `target_dir` (optional), `framework` (optional filter — "fastify", "express", etc.)
+**Output:** structured list of HTTP routes with method, path, file, line number, middleware, tags.
+
+Algorithm: for each TypeScript/JavaScript file in the graph, re-parse the AST via `gb.parser.ParseFile()` and walk the tree for call expressions matching framework-specific patterns:
+
+**Fastify patterns** (primary — Sam's stack):
+- `app.get('/path', handler)` / `app.post(...)` / etc.
+- `app.route({ method: 'GET', url: '/path', handler })` (object form)
+- `app.register(plugin)` (plugin registration — note but don't trace into)
+
+**Express patterns** (secondary — common in analyzed projects):
+- `router.get('/path', ...middleware, handler)`
+- `app.use('/prefix', router)`
+
+Tag inference: scan handler body for common patterns (SQL queries → `db` tag, auth checks → `auth` tag, cache reads → `cache` tag). Simplified version of codesight's 30-framework tagger — only Fastify + Express for now.
+
+Codesight reference: `detectors/routes.ts` (1969 lines) + `ast/extract-routes.ts` (14690 lines). The Go port is ~200 lines targeting only 2 frameworks.
+
+### 4. `get_middleware` (Tier 2)
+
+**Input:** `target_dir` (optional)
+**Output:** list of detected middleware with type (auth, cors, rate-limit, validation, error-handler, logging), file, line.
+
+Algorithm: for each file, scan for common middleware registration patterns:
+- `app.register(fastifyCors, ...)` → CORS
+- `app.addHook('preHandler', authCheck)` → auth
+- `app.setErrorHandler(...)` → error-handler
+- Import-name heuristics: `@fastify/cors` → CORS, `@fastify/rate-limit` → rate-limit
+
+Codesight reference: `detectors/middleware.ts` (217 lines). Go port: ~80 lines, Fastify-focused.
+
+## Architecture
+
+All 4 tools register in `internal/mcp/server.go:registerTools()` following the existing pattern (`mcp.AddTool`).
+
+Tools 1-2 (blast radius, hot files) operate on the existing `CodeGraph` — no re-parsing needed. They read `s.graph.Edges` and `s.graph.Files` under `s.graphMu.RLock()`.
+
+Tools 3-4 (routes, middleware) need AST access. The current pipeline discards ASTs after symbol extraction. Two options:
+- **(a) Re-parse on demand:** when `get_routes` is called, iterate TypeScript files in `s.graph.Files`, call `s.analyzer.parser.ParseFile()` for each, walk the AST. Slower but no structural change.
+- **(b) Cache route/middleware data during analysis:** modify `processFile()` in `graph_analysis.go` to extract routes alongside symbols, store in a new `FileNode.Routes` field. Faster on repeated calls but requires graph-builder changes.
+
+**Recommendation: (a) for this batch.** Re-parse is acceptable because route extraction runs on human timescale (one tool call, not per-token), and most projects have <50 route files. Optimize to (b) later if needed.
+
+New Go files:
+- `internal/mcp/blast_radius.go` — handler + BFS
+- `internal/mcp/hot_files.go` — handler + sort
+- `internal/mcp/routes.go` — handler + AST route extraction for Fastify + Express
+- `internal/mcp/middleware.go` — handler + middleware pattern detection
+
+## Hard rules
+
+- Go code. Tree-sitter for AST parsing (already in the project).
+- No new Go deps (tree-sitter + MCP SDK already present).
+- `go build ./...` clean. `go test ./...` passing.
+- Test coverage: at least one test per new tool exercising the happy path.
+- Don't modify existing tool behavior.
+
+## Estimate
+
+~400 lines of Go across 4 new files + registration in server.go. Blast radius and hot files are trivial (graph queries). Routes and middleware are the bulk (AST walking + pattern matching).

data/AGENTS.md

@@ -17,7 +17,7 @@ top_p: 0.95
 top_k: 20
 min_p: 0.0
 presence_penalty: 0.0
-tools: [find_files, get_codebase_overview, get_dependencies, get_file_analysis, get_framework_analysis, get_semantic_neighborhoods, get_symbol_info, grep, list_dir, search_symbols, view_file, watch_changes, request_read_access, view_truncated_output, ask_user_input, git_status, get_blast_radius, get_hot_files, get_middleware, get_routes]
+tools: [find_files, get_blast_radius, get_codebase_overview, get_dependencies, get_file_analysis, get_framework_analysis, get_hot_files, get_middleware, get_routes, get_semantic_neighborhoods, get_symbol_info, git_status, grep, list_dir, request_read_access, search_symbols, view_file, view_truncated_output]
 description: Reviews code for bugs, security issues, and maintainability. Read-only.
 ---
 You review code. Find real problems, not style nits.
@@ -56,7 +56,7 @@ top_p: 0.95
 top_k: 20
 min_p: 0.0
 presence_penalty: 0.0
-tools: [find_files, get_codebase_overview, get_dependencies, get_file_analysis, get_framework_analysis, get_semantic_neighborhoods, get_symbol_info, grep, list_dir, search_symbols, view_file, watch_changes, request_read_access, view_truncated_output, ask_user_input, git_status, get_blast_radius, get_hot_files, get_middleware, get_routes]
+tools: [ask_user_input, find_files, get_blast_radius, get_codebase_overview, get_dependencies, get_file_analysis, get_framework_analysis, get_hot_files, get_semantic_neighborhoods, get_symbol_info, git_status, grep, list_dir, request_read_access, search_symbols, view_file, view_truncated_output, watch_changes]
 description: Diagnoses bugs from error messages, logs, or described symptoms.
 ---
 You diagnose bugs. Form a hypothesis, prove it with evidence from the code.
@@ -82,7 +82,7 @@ top_k: 20
 min_p: 0.0
 presence_penalty: 0.0
 steps: 5
-tools: [find_files, get_codebase_overview, get_dependencies, get_file_analysis, get_framework_analysis, get_semantic_neighborhoods, get_symbol_info, grep, list_dir, search_symbols, view_file, watch_changes, request_read_access, view_truncated_output, ask_user_input, git_status, get_blast_radius, get_hot_files, get_middleware, get_routes]
+tools: [find_files, get_blast_radius, get_codebase_overview, get_dependencies, get_file_analysis, get_framework_analysis, get_hot_files, get_middleware, get_routes, get_semantic_neighborhoods, get_symbol_info, git_status, grep, list_dir, request_read_access, search_symbols, view_file, view_truncated_output, watch_changes]
 description: Proposes refactors for clarity, deduplication, or decoupling. Read-only — outputs plans, not edits.
 ---
 You propose refactors. You do not apply them. The user applies via OpenCode or Claude Code.
@@ -125,7 +125,7 @@ top_k: 20
 min_p: 0.0
 presence_penalty: 1.5
 steps: 20
-tools: [find_files, get_codebase_overview, get_dependencies, get_file_analysis, get_framework_analysis, get_semantic_neighborhoods, get_symbol_info, grep, list_dir, search_symbols, view_file, watch_changes, request_read_access, view_truncated_output, ask_user_input, git_status, get_blast_radius, get_hot_files, get_middleware, get_routes]
+tools: [find_files, get_blast_radius, get_codebase_overview, get_dependencies, get_file_analysis, get_framework_analysis, get_hot_files, get_middleware, get_routes, get_semantic_neighborhoods, get_symbol_info, git_status, grep, list_dir, request_read_access, search_symbols, view_file, view_truncated_output, watch_changes, web_fetch, web_search]
 description: Designs new features, modules, or architectural changes. Outputs a build plan.
 ---
 You design. You produce build plans, not code.
@@ -167,7 +167,7 @@ top_p: 0.95
 top_k: 20
 min_p: 0.0
 presence_penalty: 0.0
-tools: [find_files, get_codebase_overview, get_dependencies, get_file_analysis, get_framework_analysis, get_semantic_neighborhoods, get_symbol_info, grep, list_dir, search_symbols, view_file, watch_changes, request_read_access, view_truncated_output, ask_user_input, git_status, get_blast_radius, get_hot_files, get_middleware, get_routes]
+tools: [find_files, get_codebase_overview, get_dependencies, get_file_analysis, grep, list_dir, request_read_access, search_symbols, view_file, view_truncated_output]
 description: Audits code for security vulnerabilities. Read-only.
 ---
 You audit for security issues. Concrete findings only, no generic warnings.
@@ -212,7 +212,7 @@ top_p: 0.95
 top_k: 20
 min_p: 0.0
 presence_penalty: 0.0
-tools: [view_file, list_dir, grep, find_files]
+tools: [find_files, get_codebase_overview, grep, list_dir, view_file]
 description: Builds prompts for OpenCode, Claude Code, or BooCode dispatch.
 ---
 You write prompts that another coding agent will execute. Your output is the prompt, not the work.
@@ -250,7 +250,7 @@ top_p: 0.95
 top_k: 20
 min_p: 0.0
 presence_penalty: 0.0
-tools: [find_files, get_codebase_overview, get_dependencies, get_file_analysis, get_framework_analysis, get_semantic_neighborhoods, get_symbol_info, grep, list_dir, search_symbols, view_file, watch_changes, request_read_access, view_truncated_output, ask_user_input, git_status, get_blast_radius, get_hot_files, get_middleware, get_routes]
+tools: [find_files, get_blast_radius, get_codebase_overview, get_dependencies, get_file_analysis, get_framework_analysis, get_hot_files, get_middleware, get_routes, get_semantic_neighborhoods, get_symbol_info, grep, list_dir, request_read_access, search_symbols, view_file, view_truncated_output, watch_changes]
 description: Discovers and maps unfamiliar codebases. Reads architecture, traces data flow, identifies key symbols.
 ---
 You map codebases. Start broad, then drill into specifics.
@@ -278,7 +278,7 @@ top_k: 20
 min_p: 0.0
 presence_penalty: 0.0
 steps: 10
-tools: [find_files, get_codebase_overview, get_dependencies, get_file_analysis, get_framework_analysis, get_semantic_neighborhoods, get_symbol_info, grep, list_dir, search_symbols, view_file, watch_changes, request_read_access, view_truncated_output, ask_user_input, git_status, get_blast_radius, get_hot_files, get_middleware, get_routes]
+tools: [ask_user_input, find_files, get_blast_radius, get_codebase_overview, get_dependencies, get_file_analysis, get_framework_analysis, get_hot_files, get_middleware, get_routes, get_semantic_neighborhoods, get_symbol_info, git_status, grep, list_dir, request_read_access, search_symbols, view_file, watch_changes]
 description: Produces actionable step plans from requirements. Read-only — never modifies files.
 ---
 You produce actionable step plans. You do not modify files.

data/mcp.example.json

@@ -8,16 +8,11 @@
       },
       "enabled": false
     },
-    "boocontext": {
+    "type-inject": {
       "type": "stdio",
-      "command": "node",
+      "command": "npx",
-      "args": ["/opt/forks/boocontext/dist/index.js"],
+      "args": ["-y", "@nick-vi/type-inject-mcp"],
-      "env": {
+      "enabled": true
-        "TYPE_INJECT_MCP_PATH": "/opt/forks/type-inject/packages/mcp/dist/index.js",
-        "TREE_SITTER_MCP_CMD": "uvx",
-        "TREE_SITTER_MCP_ARGS": "--from tree-sitter-analyzer[mcp] tree-sitter-analyzer-mcp"
-      },
-      "enabled": false
     }
   }
 }

data/skills/boocode/audit-end/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: audit-end
+description: End an audit session with integrity checks and summary. Use when the user says "/end", "done", "pause", or when the current task is complete.
+---
+
+# /end — Audit Session End + Integrity Check
+
+## Trigger
+
+```
+/end
+```
+
+## Steps
+
+### 1. Determine current session
+
+Read `.boo/runs/.current_session` for session_id.
+
+If missing:
+- Check for `auto_` sessions (hook-created)
+- If none, report "No active session"
+
+### 2. Collect audit data
+
+Sources:
+- `.boo/runs/audit_buffer.jsonl` — hook-recorded Write/Edit/Bash ops
+- `.boo/runs/audit_pending.jsonl` — agent [AUDIT] blocks
+- `.boo/runs/{session_id}/audit_trail.jsonl` — previously flushed records
+
+Steps:
+1. Read buffer + pending remaining data
+2. Append to `audit_trail.jsonl`
+3. Clear buffer + pending files
+
+### 3. Extract user corrections
+
+Scan audit_trail for `user_correction` records:
+
+```json
+{
+  "record_type": "conversation",
+  "action_type": "user_correction",
+  "priority": "critical_for_recovery",
+  "timestamp": "<ISO 8601>",
+  "original_claim": "<what agent said>",
+  "correction": "<what user corrected>",
+  "principle_extracted": "<general principle>",
+  "persisted_to": ["CLAUDE.md", ".boo/guidelines/..."]
+}
+```
+
+### 4. Integrity checks
+
+| Check | Condition | Fail |
+|-------|-----------|------|
+| Has records | audit_trail lines > 0 | ⚠️ "Zero audit records" |
+| Files covered | Write/Edit entries exist for modified files | ⚠️ List uncovered files |
+| Corrections persisted | persisted_to is non-empty for each correction | ⚠️ Remind to persist |
+
+Output:
+```
+=== Session Audit Check ===
+Session: <id>
+Task: <task>
+Duration: <start → end>
+
+[✅] Records: N
+[⚠️] Files not in audit: <list>
+[✅] Corrections persisted: M
+```
+
+### 5. Generate session summary
+
+Write `.boo/runs/{session_id}/session_summary.md`:
+
+```
+# Session Summary | <id>
+## Task: <description>
+## Time: <start → end>
+## Status: completed
+
+## Completed
+- <action list>
+
+## User Corrections
+- <correction records>
+
+## Stats
+- Records: N
+- Corrections: M
+```
+
+### 6. Update state
+
+- Set `session.json status = "completed", end_time = now()`
+- Update `index.json` entry
+- Clear `.current_session`
+
+## Notes
+
+- Save even if checks find problems — recording > perfection
+- ⚠️ = don't block save; ❌ = warn user, still save
+- /end itself may trigger one more Stop hook flush — normal

data/skills/boocode/audit-recover/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: audit-recover
+description: Restore lost context from audit trail. Use when unsure of prior decisions, can't remember what was discussed, or the user says "/recover". Do not guess — check the records.
+---
+
+# /recover — Context Recovery
+
+## Trigger
+
+```
+/recover              # L0+L1+L2 (current session)
+/recover full         # L3 (full trail)
+/recover {session_id} # specific session
+```
+
+## Core principle
+
+**When uncertain, check the audit trail. Do not work from memory.**
+Recovering from records is the only reliable way to avoid repeating corrected mistakes.
+
+## When to trigger
+
+| Signal | What to do |
+|--------|-----------|
+| Can't recall session details | Run /recover |
+| Unsure about current task | Run /recover |
+| About to propose something possibly corrected | Run /recover, check corrections |
+| Answer is vague, missing specifics | Run /recover full |
+
+## Steps
+
+### Graded loading
+
+**Level 0 — Index (~200t)**
+
+Read `.boo/runs/index.json` → last 5 entries (id, task, status)
+
+**Level 1 — Task state (~500t)**
+
+Read `.current_session` → session_id
+Read `session.json` → task, start_time
+Read last 3 `audit_trail.jsonl` entries → "where am I"
+
+**Level 2 — User corrections (~1000t) ⚠️ HIGHEST PRIORITY**
+
+Scan all audit_trail files for `user_correction` records
+Scan for `conclusion` entries
+Read latest daily report §4 (anomalies) + §6 (backlog)
+
+**Level 3 — Full context (~3000t, /recover full only)**
+
+Full `audit_trail.jsonl`
+Full `audit_pending.jsonl`
+
+### Output
+
+```
+=== Context Recovery Report ===
+Source: .boo/runs/<session_id>/
+Level: L2
+
+Task: <session.task>
+Status: <last action>
+
+⚠️ User corrections (must follow):
+  1. <timestamp> Original: "..."
+     Correction: "..."
+     Principle: <principle>
+
+Key conclusions:
+  - <...>
+
+Open issues:
+  - <...>
+
+⚠️ Recovered from audit trail, not memory.
+```
+
+## Notes
+
+- Corrections have highest priority — don't contradict them
+- If current plan contradicts corrections, correct the plan
+- Keep output concise — don't copy entire trail into context
+- Recover "why" and "don't" before "what was done"

data/skills/boocode/audit-report-daily/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: audit-report-daily
+description: Generate a daily work report from audit data. Every number traces to a source file. Use when user says "/report-daily", "daily report", "what did I do today".
+---
+
+# /report-daily — Audit-Driven Daily Report
+
+## Trigger
+
+```
+/report-daily              # today
+/report-daily 20260319     # specific date
+/report-daily review       # with morning self-review
+```
+
+## Data Sources
+
+| Section | Source |
+|---------|--------|
+| Task overview | `.boo/runs/index.json` |
+| Operation stats | `*/audit_trail.jsonl` tool records |
+| Changes | trail entries with edit/create/delete |
+| User feedback | `user_correction` entries in trail |
+| Anomalies | `*/anomalies.json` |
+| Backlog | previous day's daily report §6 |
+
+Every number must trace to a file. Do not fill from memory.
+
+## Steps
+
+### 1. Collect data
+
+1. Read index.json, filter sessions for target date
+2. Read each session's audit_trail.jsonl
+3. Read pending (unflushed data)
+4. Read previous day's report §6 (backlog) if exists
+
+### 2. Generate report
+
+Write to `.boo/runs/daily/{YYYYMMDD}_daily.md`:
+
+```
+# Daily Report | <DATE>
+
+> Source: .boo/runs/index.json + audit_trails
+
+## 1. Task Overview
+| # | Type | Session | Task | Status | Records |
+
+## 2. Operation Stats
+| Metric | Count |
+|--------|-------|
+| Write/Edit | N |
+| Bash | N |
+| AUDIT blocks | N |
+
+## 3. Changes
+| Time | File | Change |
+
+## 4. User Feedback & Corrections
+| Feedback | Persisted To |
+
+## 5. Anomaly Alerts
+- <alerts from anomalies.json>
+
+## 6. Backlog
+- previous day's todos
+- current status
+
+## 7. Integrity
+- All sessions have records: ✅/❌
+- Corrections persisted: ✅/❌
+```
+
+### 3. If /report-daily review
+
+After report, additionally:
+1. Check: yesterday's anomalies all addressed?
+2. Check: user feedback converted to improvements?
+3. Check: backlog items completed?
+4. Write `.boo/runs/daily/{YYYYMMDD}_morning_review.md`
+5. Output recommended priorities for today
+
+```
+=== Morning Self-Review ===
+Trend: <up/down/flat compared to last 3 days>
+Anomalies resolved: N/M
+Backlog cleared: N/M
+
+Recommended priorities:
+1. <...>
+2. <...>
+```
+
+## Notes
+
+- If no sessions today, generate empty report with "No activity"
+- Report itself should write one [AUDIT] block
+- Historical reports are append-only — corrections go in new report
+- Every number must cite its source file

data/skills/boocode/audit-start/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: audit-start
+description: Create an audit session with context recovery. Use when beginning a new task, before making changes, or when the user says "/start". Ensures all subsequent work is tracked in a recoverable session.
+---
+
+# /start — Audit Session + Context Recovery
+
+## Trigger
+
+```
+/start "task description"
+```
+
+## Why
+
+Every work session should be tracked. Without a session:
+- Hooks output to an auto_ session with no task description
+- /end can't run integrity checks
+- Daily reports lack task context
+
+/start costs one directory + one JSON file. The return is traceability.
+
+## Steps
+
+### 1. Create the session
+
+1. Generate `session_id = adhoc_YYYYMMDD_HHMM`
+2. `mkdir -p .boo/runs/{session_id}`
+3. Write `session.json`:
+   ```json
+   {
+     "session_id": "<id>",
+     "task": "<user description>",
+     "start_time": "<ISO 8601>",
+     "status": "in_progress",
+     "expected_record_types": ["data", "change", "conversation"]
+   }
+   ```
+4. Write `.boo/runs/.current_session` with session_id (hook handshake)
+
+### 2. Context recovery
+
+**Level 0 — Index**:
+- Read `.boo/runs/index.json` → last 5 entries (id, task, status)
+
+**Level 2 — User corrections (critical)**:
+- Scan recent `audit_trail.jsonl` files for `user_correction` records
+- These must be surfaced first — repeating corrected mistakes wastes effort
+
+**Level 1 — Task state**:
+- Read latest `.boo/runs/daily/*_daily.md` if it exists (§4 anomalies, §6 backlog)
+- Read latest `*_morning_review.md` if it exists
+
+### 3. Check unfinished sessions
+
+- Scan `.boo/runs/` session dirs for `session.json` with `status: "in_progress"`
+- If found, propose: continue existing session or start fresh
+
+### 4. Output recovery summary
+
+```
+Audit session: adhoc_20260320_1400
+Task: <description>
+
+Context recovery:
+
+Recent activity:
+  - <last 3 completed tasks>
+
+⚠️ User corrections (must follow):
+  - <all user_correction records>
+
+Unresolved:
+  - <unfinished sessions, open alerts>
+
+Today's priorities:
+  - <recommendations>
+```
+
+## Notes
+
+- If `.boo/runs/` doesn't exist, create it
+- If no history, start clean — no errors
+- session_id stays constant for the whole session; all [AUDIT] blocks share it
+- If `.current_session` already points at an active session, ask before replacing

data/skills/boocode/command-end/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: command-end
+description: End the current audit session, flush remaining buffer data, run integrity checks, and generate a session summary. Use when finishing a task, taking a break, or ending work. Examples: "end", "finish session", "end session", "wrap up", "/end".
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - Write
+---
+
+# /end — Audit Session End + Integrity Check
+
+## Trigger
+
+```
+/end
+```
+
+## Steps
+
+### 1. Find current session
+
+Read `.boo/runs/.current_session` for the session_id.
+
+If absent, check for auto-created sessions. If none, report "No active session."
+
+### 2. Collect remaining audit data
+
+Read `.boo/runs/audit_buffer.jsonl` and `audit_pending.jsonl` for any data the Stop hook hasn't flushed yet. Append both to `.boo/runs/{session_id}/audit_trail.jsonl`, then clear the buffer files.
+
+### 3. Extract user corrections
+
+Scan `audit_trail.jsonl` for `user_correction` entries. Each should have a non-empty `persisted_to` array. If any are unpersisted, flag them.
+
+### 4. Integrity checks
+
+| Check | Source | Pass | Fail |
+|-------|--------|------|------|
+| Has records | trail line count | > 0 | Warn |
+| Files tracked | tool=Write/Edit entries | Every changed file has an entry | Warn |
+| Corrections persisted | user_correction entries | persisted_to non-empty | Warn |
+
+### 5. Generate summary
+
+Write `.boo/runs/{session_id}/session_summary.md`:
+
+```markdown
+# Session Summary | {session_id}
+## Task: {description}
+## Time: {start} → {end}
+## Status: completed
+
+Completed work: {action list}
+Key conclusions: {output entries}
+User corrections: {correction records}
+```
+
+### 6. Close
+
+Update `session.json`: status=completed, end_time=now. Update `index.json`. Delete `.current_session`.

data/skills/boocode/command-recover/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: command-recover
+description: Recover lost context from audit session records. Use when you can't remember earlier discussion, aren't sure about task progress, or need to check what the user has corrected before. Also use when your answers feel vague — don't guess, recover. Examples: "recover", "what was I doing", "recap", "what did we discuss", "/recover".
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+---
+
+# /recover — Context Recovery
+
+## Trigger
+
+```
+/recover              # L0+L1+L2 (current session)
+/recover full         # L3 (full audit_trail)
+/recover {session_id} # Specific session
+```
+
+## When to use
+
+**Do not work from memory — query the audit trail when:**
+- You can't recall what was decided earlier
+- Unsure what phase the task is in
+- About to propose something the user may have already corrected
+- Answers feel generic (missing file names, specific numbers)
+
+## Graded loading
+
+### L0 — Index (~200t)
+Read `.boo/runs/index.json` → last 5 entries (id, task, status)
+
+### L1 — Task state (~500t)
+Read `.current_session` → session.json → last 3 audit_trail entries
+
+### L2 — User corrections + decisions (~1000t) ⚠️ MOST IMPORTANT
+Scan ALL audit_trails for `user_correction` records + conclusions
+Read daily report §4 (anomalies) + §6 (backlog)
+
+### L3 — Full context (~3000t, /recover full only)
+Complete audit_trail.jsonl + audit_pending.jsonl
+
+## Output
+
+```
+=== Context Recovery Report ===
+Level: L2
+Source: .boo/runs/{session_id}/
+
+Current task: {description}
+Progress: {last action}
+
+USER CORRECTIONS (must follow):
+  1. [{time}] {original claim} → {correction}
+     Principle: {principle_extracted}
+
+Key conclusions: ...
+Unresolved: ...
+
+Source: audit records (not memory)
+```

data/skills/boocode/command-report-daily/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: command-report-daily
+description: Generate a data-driven daily work report from audit session records. Every number is traceable to `.boo/runs/` files. Use for daily standup, progress tracking, or morning review. Examples: "daily report", "report today", "what did I do today", "generate report", "/report-daily".
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - Write
+---
+
+# /report-daily — Audit-Driven Work Report
+
+## Trigger
+
+```
+/report-daily              # Today
+/report-daily 20260319     # Specific date
+/report-daily review       # Report + morning self-review
+```
+
+## Data sources (every number must be traceable)
+
+| Section | Source |
+|---------|--------|
+| Task overview | `.boo/runs/index.json` |
+| Operation stats | `*/audit_trail.jsonl` tool records |
+| Changes | trail entries with Write/Edit |
+| User feedback | user_correction entries |
+| Anomalies | `*/anomalies.json` (if any) |
+| Backlog | previous day's daily report |
+
+## Sections
+
+### I. Task Overview
+Table of today's sessions with status and record count.
+
+### II. Operation Stats
+Write/Edit count, Bash count, Audit block count.
+
+### III. Change Records
+Timeline of file modifications with timestamps.
+
+### IV. User Feedback & Corrections
+User corrections made today, with persistence status.
+
+### V. Anomaly Alerts
+Unresolved issues flagged across sessions.
+
+### VI. Backlog Tracking
+Carry-over items from yesterday.
+
+### VII. Integrity Summary
+Health checks for all sessions.
+
+## Output
+
+Save to `.boo/runs/daily/{YYYYMMDD}_daily.md`.
+
+### Review variant (`review`)
+
+After the report, also generate `.boo/runs/daily/{YYYYMMDD}_morning_review.md` with:
+- Self-correction check (anomalies resolved? feedback persisted? backlog handled?)
+- Recommended priorities for today
+
+## Notes
+
+- If no sessions for the date, generate an empty report labeled "No activity"
+- Reports are append-only — correct errors with a follow-up report, never edit
+- Record one [AUDIT] block for report generation itself

data/skills/boocode/command-start/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: command-start
+description: Create an audit session with context recovery before starting work. Use when beginning a new task, analysis, or code modification — establishes a session for tracking tool usage, user corrections, and decisions. Examples: "start", "begin session", "start work", "/start 'migrate database schema'".
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - Write
+---
+
+# /start — Audit Session Start + Context Recovery
+
+## Trigger
+
+```
+/start "task description"
+```
+
+## Why
+
+Every task should run in an audit session. Without one:
+- Tool-use data goes to unnamed sessions with no task context
+- `/end` can't run integrity checks
+- Daily reports miss task descriptions
+
+## Steps
+
+### 1. Create session
+
+Generate `session_id = adhoc_YYYYMMDD_HHMM`, create `.boo/runs/{session_id}/`, write `session.json`:
+
+```json
+{
+  "session_id": "adhoc_20260320_1400",
+  "task": "task description",
+  "start_time": "ISO 8601",
+  "status": "in_progress",
+  "expected_record_types": ["data", "change", "conversation"]
+}
+```
+
+Write session_id to `.boo/runs/.current_session` (the Stop hook reads this for buffer archiving).
+
+### 2. Context recovery (L0 + L2)
+
+**L0 — Index summary**: read `.boo/runs/index.json`, last 5 entries.
+
+**L2 — User corrections (critical)**: scan all `audit_trail.jsonl` and `audit_pending.jsonl` for `user_correction` records — these must be restored first to avoid repeating mistakes.
+
+**Check for unfinished sessions**: scan `.boo/runs/adhoc_*/session.json` for `status: "in_progress"`. If found, prompt the user to continue the old session instead.
+
+### 3. Output summary
+
+```
+Session created: adhoc_20260320_1400
+Task: {description}
+
+Context recovery:
+  Recent activity: {last 3 completed tasks}
+  User corrections (must follow): {all user_correction records}
+  Unresolved issues: {open anomalies/alerts}
+  Today's priorities: {from morning review}
+
+All [AUDIT] blocks use batch_id = {session_id}
+```
+
+### 4. Notes
+
+- If `.boo/runs/` doesn't exist, create it and skip recovery
+- If `.current_session` already points to an in_progress session, prompt before creating a new one
+- The session_id stays constant for the whole session — all [AUDIT] blocks share it

data/skills/boocode/self-healing/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: self-healing
+description: "Active runtime recovery for coding agents: when something breaks mid-task, diagnose the root cause, write a fix, VERIFY by re-running the broken thing, then file a `HEAL-` entry to `.learnings/HEALS.md` with proof. Use whenever a command, test, build, or lint fails or exits non-zero; on missing tooling, dependency/lockfile mismatch, wrong runtime version, venv or permission errors, port conflicts, dirty git state, or a missing `.env`; when the agent needs a helper or one-off script that doesn't exist yet; when an external API, tool, or MCP errors or rate-limits; or when a test flakes. Search `HEALS.md` by `Pattern-Key` first — most heals are recurrences, so increment `Recurrence-Count` instead of duplicating. Verify is mandatory: mark `pending-verify` honestly if sandboxed, `abandoned` if the fix can't be made to work. Pairs with `self-improvement` (which promotes recurring heals to durable memory) but owns the verify-before-persist discipline self-improvement doesn't."
+---
+
+# Self-Healing
+
+Active runtime recovery for coding agents. When something breaks, run the loop: **diagnose → patch → verify → file**. Leave behind a reusable, verified artifact instead of a swept-under-the-rug failure.
+
+The premise mirrors [browser-use/browser-harness](https://github.com/browser-use/browser-harness): *the harness improves itself every run*. An agent that hits a gap doesn't fail — it writes the fix during execution, verifies it works, and files the durable artifact for future runs. Coding tasks deserve the same loop.
+
+## What this skill is for
+
+When a coding agent hits a wall mid-task, the default failure modes are:
+
+1. **Paper over it** — "let me try a different approach" — and lose the recovery
+2. **Pretend the fix worked** — without re-running the broken thing
+3. **Symptom-fix** — skip the test, swallow the error, retry until green
+
+All three turn a one-time failure into a recurrence. The next agent on the same project hits the same wall.
+
+This skill enforces one discipline: **verify before persist**. A patch isn't real until you've re-run the failing operation and watched it succeed. When it does, file the verified fix so the next run benefits.
+
+## Relationship to self-improvement
+
+These two skills are deliberately split. Run both — they feed each other but don't overlap.
+
+| Aspect      | `self-healing` (this skill)                                          | `self-improvement`                                            |
+| ----------- | -------------------------------------------------------------------- | ------------------------------------------------------------- |
+| **When**    | During execution, failure is live                                    | After the fact, at natural breakpoints                        |
+| **Verb**    | Heal now — restore working state                                     | Remember for later — accumulate knowledge                     |
+| **Outcome** | Verified patch + (optional) reusable artifact                        | Logged learning, correction, request                          |
+| **Verify**  | **Mandatory** — no persist without proof                             | Not required                                                  |
+| **Files**   | `.learnings/HEALS.md` + `.learnings/heals/<HEAL-ID>/` (lazy)         | `.learnings/ERRORS.md`, `LEARNINGS.md`, `FEATURE_REQUESTS.md` |
+| **Trigger** | Failure observed mid-task                                            | Correction, knowledge gap, feature request, recurrence        |
+
+**Boundary rule:** if you're capturing a fact, a correction, or a wish — that's `self-improvement`. If you're applying and verifying a fix to a live failure — that's `self-healing`.
+
+## The Heal Loop
+
+```
+  ● failure observed
+  │
+  ● 1. DIAGNOSE  capture context — command, error, env, what was attempted
+  │              search HEALS.md for the same Pattern-Key first
+  │              (most heals are recurrences; don't reinvent)
+  │
+  ● 2. PATCH     write the fix — script, helper, env tweak, alt command
+  │              artifacts → .learnings/heals/<HEAL-ID>/  (only if needed)
+  │
+  ● 3. VERIFY    re-run the failing op — must succeed
+  │              ↻ if still failing: refine and retry, cap at 3 attempts
+  │              ✗ if uncrackable: file Status: abandoned with notes
+  │
+  ● 4. FILE      write HEAL-YYYYMMDD-XXX to .learnings/HEALS.md
+  │              with Pattern-Key, status, verification proof
+  │
+  ✓ working state restored, heal persisted
+
+  (conditional) PROMOTE  if Pattern-Key recurrence ≥ 3 across distinct tasks,
+                           append a Handoff block → self-improvement promotes to memory
+```
+
+If you abandon a heal mid-loop, don't pretend it succeeded. File a `HEAL-` entry with `Status: abandoned` and notes on what didn't work. The next agent learns from the dead end too.
+
+## When to trigger
+
+Self-healing fires on **active failures during execution** — the agent has just observed something not working and needs to make it work to continue. Five shapes:
+
+### 1. Tool failure (command / test / build / lint)
+Any invocation exits non-zero or produces wrong output. Don't acknowledge and retry verbatim — diagnose, patch, verify.
+
+*Examples:* `npm install` errors when a `pnpm-lock.yaml` is present (switch tool); `pytest` fails with `ModuleNotFoundError` (activate the venv); `tsc` flags a stale type (regenerate the client); `eslint` reports a config error (install the missing parser).
+
+### 2. Missing capability / tool gap
+The agent needs something that doesn't exist yet — a script, a helper, a wrapper, a glue function. Write it in the moment. This is the closest analog to browser-harness's `agent_helpers.py`.
+
+*Examples:* dedupe a CSV by custom key (write a small Python helper); bootstrap 12 microservices the same way (write `scripts/bootstrap-all.sh`); bulk-rename branches matching a pattern (write a `gh`-based shell helper).
+
+### 3. Environment issue
+The local environment isn't what the project expects. Detect, patch, verify.
+
+*Examples:* runtime version mismatch (`nvm use`, `pyenv local`, `rustup override`); stale dependency cache after a branch switch; dirty git state blocking a checkout; missing `.env` (copy from `.env.example` and surface gaps).
+
+### 4. External service / API change
+A service the agent depends on returns something unexpected. Find a workaround and capture it.
+
+*Examples:* an MCP tool returns `InputValidationError` because the schema changed (patch the call shape); a public API hits a rate limit (back off, switch endpoint, batch); an upstream lib bumped a default and broke a script (pin the version).
+
+### 5. About-to-retry-the-same-broken-approach
+The agent catches itself about to redo the failing step. That self-recognition is a heal forming — capture the alternate approach as the patch.
+
+### Detection signals to watch for
+
+- Non-zero exit codes
+- Stack traces in tool output
+- The same operation failing twice with the same error
+- "I'll try a different approach" — capture it as a heal
+- `command not found` / `module not found` / `permission denied`
+- Stale assertions, snapshot mismatches, type errors that weren't there before
+- "Weird" output that suggests environmental rather than logical bugs
+
+## HEAL Entry Format
+
+Append to `.learnings/HEALS.md` (create if missing):
+
+```markdown
+## [HEAL-YYYYMMDD-XXX] short_kebab_name
+
+**Logged**: ISO-8601 timestamp
+**Status**: verified | pending-verify | abandoned
+**Trigger**: tool-failure | missing-capability | env-issue | external-change | <free-form>
+**Active-Context**: (optional) — current skill, task phase, or workflow stage; omit if not applicable
+**Area**: free-form tag — what part of the system (`build`, `tests`, `ci`, `auth`, `data-pipeline`, `mobile`, ...)
+**Priority**: low | medium | high | critical
+
+### Failure
+What broke — concrete: the command, the error message, the action that was blocked. Include exit codes and verbatim error lines.
+
+### Diagnosis
+The root cause as understood after investigation. Why the obvious approach didn't work. Not a guess — what was actually verified during the heal.
+
+### Fix
+The patch that was applied. Verbatim commands, code snippets, or pointers to files under `.learnings/heals/<HEAL-ID>/`. Keep it minimal — just enough to reproduce.
+
+### Verification
+What was run after the fix and what it returned. Exit code, output snippet, test pass count. **This is the proof.** Without it, the entry is `pending-verify` or `abandoned`.
+
+### Artifacts
+(omit this section if no files were generated; otherwise list relative paths under `.learnings/heals/<HEAL-ID>/`)
+
+### Metadata
+- Related Files: path/to/file.ext
+- See Also: HEAL-... | LRN-... | ERR-... (related entries)
+- Pattern-Key: lower.snake.case key for recurrence detection (e.g. `env.lockfile_mismatch`)
+- Recurrence-Count: 1
+- First-Seen / Last-Seen: YYYY-MM-DD
+
+---
+```
+
+### Field guidance
+
+- **Status** — `verified` = the verify step passed. `pending-verify` = patch applied but couldn't be fully proven (sandboxed/offline/CI-only) — surface to the user. `abandoned` = patch didn't work or diagnosis was wrong — document what was tried.
+- **Trigger** — free-form is fine. The listed values are common shapes; what matters is that the failure shape is described enough for future agents to match against.
+- **Active-Context** — optional. Use it if your environment has a meaningful "what was I doing" tag (an active skill, a current task phase, a build stage, an agent role). Skip if not applicable. The browser-harness analog is the per-domain scoping of `domain-skills/<site>/`.
+- **Area** — free-form. Pick whatever helps future agents find this. `frontend`, `data-pipeline`, `ci`, `auth`, `terraform`, `mobile`, `embedded` — anything that fits your project shape.
+- **Pattern-Key** — lower.snake.case, stable, reusable across projects. Two heals with the same key are recurrences. `env.lockfile_mismatch` is good; `fixed_thing_tuesday` isn't.
+
+## ID generation
+
+Format: `HEAL-YYYYMMDD-XXX`. `XXX` is sequential 3-digit or 3-char random alphanumeric. Examples: `HEAL-20260524-001`, `HEAL-20260524-A7B`.
+
+## Artifacts directory (lazy)
+
+Only create `.learnings/heals/<HEAL-ID>/` when the heal generated something worth preserving. One-line fixes don't need a folder; the HEAL entry text is enough. Abandoned heals with no applied patch also skip the folder.
+
+```
+.learnings/
+├── HEALS.md
+├── ERRORS.md / LEARNINGS.md / FEATURE_REQUESTS.md  (self-improvement)
+└── heals/
+    └── HEAL-20260524-001/
+        ├── helper.sh
+        ├── patch.diff
+        └── notes.md
+```
+
+**Put here:** generated scripts/helpers, patch files, supplementary notes, output captures that document the diagnosis.
+**Don't put here:** project source changes (those go in the project tree, referenced via Related Files); secrets; output already captured in the HEAL text.
+
+## Verification rules
+
+Verify is the load-bearing wall. The whole point of self-healing over self-improvement is that the fix is *proven*, not theorized.
+
+### What counts as proof
+
+| Failure shape                         | Verification                                                       |
+| ------------------------------------- | ------------------------------------------------------------------ |
+| Tool / command / test / build / lint  | Re-run the original invocation; expect exit 0 / pass               |
+| Missing capability                    | Invoke the helper end-to-end on a real input; expect the intent    |
+| Environment drift                     | Re-run the operation that triggered the diagnosis                  |
+| External service workaround           | Re-run the failed call with the patch; expect a usable response    |
+
+### Sandboxed / offline / CI-only failures
+
+When you genuinely can't run the verify step (no network, no real remote, sandboxed shell, CI-only reproduction), file `Status: pending-verify` with:
+
+- The exact command the user / CI should run
+- The acceptance criteria — what counts as proof
+- A simulated proof if you can construct one (e.g. a dry-run mode, a stub of the failing call, a sandbox script)
+
+`pending-verify` is honest. Faking `verified` is the failure mode this skill exists to prevent.
+
+### When to invest in a proof script
+
+Most heals don't need a separate proof script — the verify step is just re-running the failing thing. Build a proper proof script when:
+
+- The heal generates a reusable helper that needs to be exercised across cases
+- The failure can't be reproduced live but can be reproduced in a sandbox (clean git repo, mock service, fake input)
+- You expect the heal to be re-applied across projects — the proof script then doubles as a regression check
+
+### If verification fails
+
+1. **Once** — refine the patch and retry. First diagnosis is often wrong.
+2. **Twice** — step back and reconsider the diagnosis. Maybe the root cause is elsewhere.
+3. **Three times** — stop. File `Status: abandoned` with notes on what you tried. Surface to the user. Don't flail.
+
+### What does NOT count as verification
+
+- "It looks right" / "I think this should work"
+- Re-running a *different* command than the one that originally failed
+- Suppressing the failure (`|| true`, `--ignore-errors`) — that's hiding
+- Skipping or deleting the failing test — that's regression
+- Passing because the cache was warm from before the fix
+
+### Reversibility
+
+Prefer reversible patches. If your heal modifies project files, capture the diff in `patch.diff`. If the heal is destructive (deletes generated files, rewrites locks), note it explicitly — a future agent reading the HEAL needs to know what was destroyed.
+
+## Recurrence and promotion
+
+Most heals are recurrences. Before filing a new HEAL, search:
+
+```bash
+grep -n "Pattern-Key: <your-pattern-key>" .learnings/HEALS.md
+```
+
+If found:
+
+- Increment `Recurrence-Count`
+- Update `Last-Seen`
+- Add the current occurrence as a See Also link
+- **Do not** create a duplicate entry
+
+### Promotion threshold
+
+Add a `Handoff` block to an existing entry when **all** are true:
+
+- `Recurrence-Count >= 3`
+- Seen across at least 2 distinct tasks
+- The fix is generalizable (not project-specific in a way that's already in a memory file)
+
+```markdown
+### Handoff
+- **Promoted To**: self-improvement at YYYY-MM-DD
+- **Promotion Target**: CLAUDE.md | AGENTS.md | .github/copilot-instructions.md | new-skill
+- **Distilled Rule**: One-line prevention guidance derived from the heal
+```
+
+Then `self-improvement` (or a learning aggregator) takes over: distills the rule, writes it into the right context file, or extracts a reusable skill. The HEAL stays for traceability.
+
+## Anti-patterns
+
+1. **Logging without verifying.** A HEAL filed before the fix is proven turns this into noisier self-improvement. If verify hasn't passed, the entry is `pending-verify` or `abandoned`.
+2. **Healing the symptom, not the cause.** A failing test isn't healed by skipping it (`pytest.skip`, `it.skip`, `xit`). A flaky CI isn't healed by `--retry`. Find the root cause; if you can't, abandon honestly.
+3. **Generating a new fix without trying existing ones first.** Search `HEALS.md` by Pattern-Key. Most heals are recurrences.
+4. **Inventing helpers when the project already has them.** Look in `scripts/`, `Makefile`, `justfile`, `package.json`, `pyproject.toml` first. Heal = write what's missing, not what's there.
+5. **Scope creep.** A heal is scoped to one failure. Cleanup belongs in a quality pass; refactors are features. Scope creep makes heals unreviewable.
+6. **Empty artifact folders.** Don't create `.learnings/heals/<HEAL-ID>/` if nothing goes in it.
+
+## Best practices
+
+1. **Heal eagerly, file always.** Even abandoned heals teach the next agent what doesn't work.
+2. **Verify before persist.** The non-negotiable rule.
+3. **Minimal and reversible patches.** A 3-line fix is a heal; a 300-line refactor is a feature.
+4. **Stable Pattern-Keys.** `env.node_version_mismatch` is reusable; `fixed_the_thing_on_tuesday` isn't.
+5. **Reference, don't duplicate.** Cross-link related HEAL/LRN/ERR via See Also.
+6. **Hand off recurrences.** A heal seen 3 times deserves to be in the project's permanent memory.
+7. **Don't gate the main tree on heal artifacts.** Files under `.learnings/heals/` are reference material; if a script becomes load-bearing, promote it to `scripts/`.
+
+## Setup
+
+```bash
+mkdir -p .learnings        # heals/ is lazy — created only when artifacts exist
+touch .learnings/HEALS.md
+```
+
+Gitignore choices match `self-improvement`. Keep heals local (`.learnings/` in `.gitignore`) or share them as team knowledge (don't gitignore — they become reviewable durable context).
+
+## Multi-agent use
+
+The skill is agent-agnostic. The `.learnings/HEALS.md` format is plain markdown — any agent (Claude Code, BooCode agents, OpenCode, Copilot, Cursor, Aider, ...) can read and write it.
+
+## See also
+
+- [`references/examples.md`](references/examples.md) — canonical HEAL entry shapes (command failure, missing capability, env drift, external API workaround, abandoned heal)

data/skills/boocode/self-healing/eval.yaml

@@ -0,0 +1,35 @@
+skill: self-healing
+tasks:
+  - prompt: "I'm in a project root that has pnpm-lock.yaml present but no package-lock.json. I just tried to run `npm install` and it failed. Get me to a working state so I can keep working — I have other things to do, just unblock me. After fixing it, make sure future agents in this project know what happened."
+    grader:
+      - the response invokes the self-healing skill
+      - the response diagnoses pnpm vs npm mismatch as the root cause
+      - the response runs pnpm install successfully
+      - the response files a HEAL entry to .learnings/HEALS.md with Status: verified
+      - the HEAL entry has Trigger: tool-failure
+      - the HEAL entry has a Pattern-Key resembling env.lockfile_mismatch
+      - the HEAL entry includes the verification output
+  - prompt: "I need to bulk-rename 8 git branches in this repo from `feat-XXX-name` to `feat/XXX-name`. There's no existing script for this and `gh` doesn't have a bulk-rename. Write what's needed, prove it works on a dry run, and capture the work so it's not lost if I need it again."
+    grader:
+      - the response invokes the self-healing skill
+      - the response recognizes this as a missing-capability heal
+      - the response writes a helper script under .learnings/heals/HEAL-<date>-<seq>/
+      - the response runs a dry-run verification
+      - the response files a HEAL entry with Status: verified and Trigger: missing-capability
+      - the HEAL entry references the helper script in the Artifacts section
+  - prompt: "I just ran `pytest` and got `ModuleNotFoundError: No module named 'pydantic'`. There's already a `.learnings/HEALS.md` in this project with a prior heal for a similar venv-not-activated issue. Fix this, and do the right thing with the heal records."
+    grader:
+      - the response invokes the self-healing skill
+      - the response searches HEALS.md first (using find-similar-heals.sh or grep) before writing a new fix
+      - the response finds the existing HEAL entry and applies its fix (activate venv)
+      - the response increments Recurrence-Count on the existing entry
+      - the response updates Last-Seen on the existing entry
+      - the response does NOT create a duplicate HEAL entry
+  - prompt: "A test in this repo is failing intermittently — the snapshot for `Card.test.tsx` flakes. I've already tried fixing it once by stubbing the date; it passes twice then flakes again because there's a UUID that's also non-deterministic. I don't have time to refactor the Card component to inject dependencies. Just do the right thing — get me to a state that's honest about what's known and not known, and don't pretend the heal worked."
+    grader:
+      - the response invokes the self-healing skill
+      - the response diagnoses that the initial patch attempt was incomplete
+      - the response files a HEAL entry with Status: abandoned
+      - the HEAL entry documents what was tried and why it failed
+      - the response does NOT mark anything as verified
+      - the response surfaces the situation honestly to the user

data/skills/boocode/self-healing/references/examples.md

@@ -0,0 +1,248 @@
+# Self-Healing Examples
+
+Concrete HEAL entries showing the format applied to real failure shapes. Use these as templates when filing your own heals. All examples use the iteration-2 schema (free-form `Trigger` / `Area`, optional `Active-Context`, no `Source` field, lazy artifact folders).
+
+---
+
+## Example 1 — Tool failure (lockfile mismatch)
+
+```markdown
+## [HEAL-20260524-001] npm_install_pnpm_lockfile
+
+**Logged**: 2026-05-24T14:22:01Z
+**Status**: verified
+**Trigger**: tool-failure
+**Area**: build
+**Priority**: medium
+
+### Failure
+`npm install` exited 1 with `npm ERR! code EUSAGE` and a notice that `pnpm-lock.yaml` is present but `package-lock.json` is missing. The project uses pnpm workspaces; npm refuses to install against a pnpm lockfile.
+
+### Diagnosis
+Project root contains `pnpm-lock.yaml`. The README and CI both invoke `pnpm`. `npm` was a habit from previous projects, not the actual project's package manager.
+
+### Fix
+Use pnpm instead:
+```bash
+pnpm install
+```
+
+### Verification
+```
+$ pnpm install
+Lockfile is up to date, resolution step is skipped
+Already up to date
+✓ Done in 1.4s
+```
+Exit 0.
+
+### Metadata
+- Related Files: package.json, pnpm-lock.yaml
+- See Also: (none yet)
+- Pattern-Key: env.lockfile_mismatch
+- Recurrence-Count: 1
+- First-Seen: 2026-05-24
+- Last-Seen: 2026-05-24
+
+---
+```
+
+Pattern-Key `env.lockfile_mismatch` is reusable across projects (yarn.lock, bun.lockb, etc.). At Recurrence ≥ 3, this should be promoted to `CLAUDE.md` or `AGENTS.md` as a verification step.
+
+No Artifacts section — the fix is a tool swap, no files generated. Lazy folder pattern: nothing to put in `.learnings/heals/HEAL-20260524-001/`, so the folder isn't created.
+
+---
+
+## Example 2 — Missing capability (helper written on the fly)
+
+```markdown
+## [HEAL-20260524-002] bulk_rename_branches_helper
+
+**Logged**: 2026-05-24T15:10:44Z
+**Status**: verified
+**Trigger**: missing-capability
+**Area**: ci
+**Priority**: low
+
+### Failure
+Need to rename 12 feature branches from `feat-XXX-name` to `feat/XXX-name`. No existing project script handles this; `gh` doesn't have a bulk-rename primitive.
+
+### Diagnosis
+This is glue work, not a project bug. A small shell helper using `gh api` per branch is the right level — not worth a top-level script, but worth keeping the file for the next time someone asks.
+
+### Fix
+Wrote `.learnings/heals/HEAL-20260524-002/rename-branches.sh`:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+git fetch --all
+for branch in $(git branch -r | grep 'origin/feat-' | sed 's|origin/||'); do
+  new="${branch/feat-/feat/}"
+  echo "$branch → $new"
+  gh api -X POST "repos/{owner}/{repo}/git/refs" \
+    -f "ref=refs/heads/$new" \
+    -f "sha=$(git rev-parse "origin/$branch")"
+  gh api -X DELETE "repos/{owner}/{repo}/git/refs/heads/$branch"
+done
+```
+
+### Verification
+Dry-run (commented out the API calls) printed the 12 expected mappings.
+Live run renamed all 12; `git branch -r | grep 'feat-' | wc -l` returns 0.
+
+### Artifacts
+- `.learnings/heals/HEAL-20260524-002/rename-branches.sh`
+
+### Metadata
+- Related Files: (none — operates on git refs)
+- See Also: (none)
+- Pattern-Key: tool.gh.bulk_branch_rename
+- Recurrence-Count: 1
+- First-Seen: 2026-05-24
+- Last-Seen: 2026-05-24
+
+---
+```
+
+Helper script lives under `.learnings/heals/<HEAL-ID>/` — referenceable, but not assumed to be load-bearing. If it gets reused frequently, promote to `scripts/`.
+
+---
+
+## Example 3 — Environment issue (runtime version)
+
+```markdown
+## [HEAL-20260524-003] nvm_use_project_node
+
+**Logged**: 2026-05-24T16:01:12Z
+**Status**: verified
+**Trigger**: env-issue
+**Active-Context**: verify-gate
+**Area**: tests
+**Priority**: medium
+
+### Failure
+`pnpm test` exited 1 with `engine "node" is incompatible with this module. Expected version "^20.10.0". Got "18.19.0"`.
+
+### Diagnosis
+`.nvmrc` requests node 20.10.0; current shell has 18.19.0 from a previous project context. The shell's nvm wasn't switched after `cd`-ing into the repo.
+
+### Fix
+```bash
+nvm use   # reads .nvmrc
+```
+
+### Verification
+```
+$ node --version
+v20.10.0
+$ pnpm test
+✓ 47 tests passed
+```
+
+### Metadata
+- Related Files: .nvmrc, package.json
+- See Also: (none)
+- Pattern-Key: env.node_version_mismatch
+- Recurrence-Count: 1
+- First-Seen: 2026-05-24
+- Last-Seen: 2026-05-24
+
+---
+```
+
+`Active-Context: verify-gate` because that's the workflow phase the agent was in when the test step blew up. An upstream context loader could surface this entry next time `verify-gate` runs in a node project. If you don't have an analogous concept in your pipeline, omit the field.
+
+---
+
+## Example 4 — External service workaround
+
+```markdown
+## [HEAL-20260524-004] gh_api_rate_limit_backoff
+
+**Logged**: 2026-05-24T17:33:08Z
+**Status**: verified
+**Trigger**: external-change
+**Area**: ci
+**Priority**: high
+
+### Failure
+Looping `gh api repos/.../issues` over 200 issues started returning `403 rate limit exceeded` after ~60 calls. Unauthenticated burst limit (abuse detection on rapid successive calls).
+
+### Diagnosis
+Script was using `gh api` REST without batching. `gh` is authenticated but the secondary rate limit fires on rapid successive calls — not the primary 5000/hour limit. Switching to a single paginated GraphQL query bypasses the secondary limit entirely.
+
+### Fix
+```bash
+gh api graphql -f query='
+  query($owner:String!,$repo:String!,$cursor:String) {
+    repository(owner:$owner,name:$repo) {
+      issues(first:100,after:$cursor) { ... }
+    }
+  }' -F owner=... -F repo=...
+```
+Took ~3 calls total instead of 200.
+
+### Verification
+Full run completed in 4.8s, no 403s, all 200 issues retrieved. Compared output against a sample of the original per-issue calls — fields match.
+
+### Artifacts
+- `.learnings/heals/HEAL-20260524-004/fetch-issues.sh`
+
+### Metadata
+- Related Files: (none — ad-hoc query)
+- See Also: (none)
+- Pattern-Key: api.gh.rate_limit
+- Recurrence-Count: 1
+- First-Seen: 2026-05-24
+- Last-Seen: 2026-05-24
+
+---
+```
+
+---
+
+## Example 5 — Abandoned heal (diagnosis was wrong)
+
+```markdown
+## [HEAL-20260524-005] vitest_flaky_snapshot
+
+**Logged**: 2026-05-24T18:14:22Z
+**Status**: abandoned
+**Trigger**: tool-failure
+**Active-Context**: verify-gate
+**Area**: tests
+**Priority**: medium
+
+### Failure
+`vitest` snapshot test `Card > renders default` flaked twice in three runs. Diff showed a timestamp string differing by ~3 seconds.
+
+### Diagnosis (initial — wrong)
+Assumed flake was timezone drift in the snapshot fixture. Patched the fixture to use a fixed `Date.now()` stub.
+
+### Diagnosis (current — correct)
+The snapshot depends on multiple non-deterministic values: timestamp AND a `crypto.randomUUID()`. The clock stub addressed only one of them. The UUID is still random per render, so the snapshot keeps drifting on subsequent runs.
+
+### Fix (attempted)
+Added `vi.useFakeTimers({ now: 1700000000000 })` to the test setup.
+
+### Verification
+Test passed twice, then flaked again on the third run — same `Card > renders default`, different diff (this time the UUID changed). Original diagnosis was incomplete.
+
+### Abandonment notes
+The right fix is to make the component deterministic via dependency injection (pass a `clock` and `idGen` prop), not to stub globally. That's a real change to the component contract — out of scope for a heal. Filed `FEAT-20260524-001` via self-improvement; surfaced to the user.
+
+### Metadata
+- Related Files: src/components/Card.tsx, src/components/Card.test.tsx
+- See Also: FEAT-20260524-001
+- Pattern-Key: tests.flaky_snapshot_multi_nondeterminism
+- Recurrence-Count: 1
+- First-Seen: 2026-05-24
+- Last-Seen: 2026-05-24
+
+---
+```
+
+Abandoned heals are first-class. They document a dead end so the next agent doesn't re-walk it. The handoff to a `FEAT-` entry via self-improvement is the right next step when the real fix is a feature, not a heal.
+
+No Artifacts section — the attempted patch was reverted; nothing reusable was generated.

data/skills/boocode/self-healing/scripts/detect-failure.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# detect-failure.sh — PostToolUse hook for Bash invocations.
+# Reads the tool result JSON on stdin (per Claude Code hook spec); if exit_code != 0,
+# emits a system reminder pointing the agent at self-healing.
+#
+# Wire up in .claude/settings.json:
+#   "hooks": {
+#     "PostToolUse": [{ "matcher": "Bash",
+#       "hooks": [{ "type": "command",
+#         "command": "./data/skills/boocode/self-healing/scripts/detect-failure.sh" }] }]
+#   }
+
+set -euo pipefail
+
+# Hook payload arrives on stdin. We tolerate either jq-style JSON or raw text.
+PAYLOAD="$(cat || true)"
+
+# Try to parse exit_code; fall through silently on parse failure.
+EXIT_CODE=$(printf '%s' "$PAYLOAD" | python3 -c '
+import json, sys
+try:
+    data = json.loads(sys.stdin.read() or "{}")
+    # Common shapes: {"tool_result": {"exit_code": N}}, {"exit_code": N}, {"output": "...", "exit_code": N}
+    for path in (("tool_result","exit_code"), ("exit_code",), ("result","exit_code")):
+        d = data
+        ok = True
+        for k in path:
+            if isinstance(d, dict) and k in d:
+                d = d[k]
+            else:
+                ok = False
+                break
+        if ok and isinstance(d, int):
+            print(d)
+            sys.exit(0)
+except Exception:
+    pass
+print(0)
+' 2>/dev/null || echo 0)
+
+if [[ "$EXIT_CODE" != "0" ]]; then
+  cat <<'EOF'
+<self-healing-trigger>
+A Bash command just exited non-zero. This is a heal opportunity.
+
+Before retrying the same command verbatim:
+  1. DIAGNOSE — read the error; identify the root cause (env? missing dep? wrong tool?)
+  2. Search .learnings/HEALS.md for a matching Pattern-Key (don't re-solve a solved problem)
+  3. PATCH — write the fix (or apply a known one)
+  4. VERIFY — re-run the command; require exit 0
+  5. FILE — append a HEAL entry to .learnings/HEALS.md via data/skills/boocode/self-healing/scripts/new-heal.sh
+</self-healing-trigger>
+EOF
+fi

data/skills/boocode/self-healing/scripts/find-similar-heals.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# find-similar-heals.sh — Search existing heals before generating a new fix.
+# Usage: ./find-similar-heals.sh <pattern-key-or-keyword>
+#
+# Prints matching HEAL entries with their Pattern-Key, Status, and Recurrence-Count
+# so the agent can decide whether to re-apply an existing fix or write a new one.
+
+set -euo pipefail
+
+QUERY="${1:-}"
+HEALS_FILE="$(pwd)/.learnings/HEALS.md"
+
+if [[ -z "$QUERY" ]]; then
+  echo "usage: $0 <pattern-key-or-keyword>" >&2
+  exit 2
+fi
+
+if [[ ! -f "$HEALS_FILE" ]]; then
+  echo "(no .learnings/HEALS.md yet — no prior heals to consult)"
+  exit 0
+fi
+
+# Find HEAL section headers that contain the query in their body (Pattern-Key, name, or text).
+python3 - <<PY "$QUERY" "$HEALS_FILE"
+import sys, re
+query, path = sys.argv[1].lower(), sys.argv[2]
+with open(path) as f:
+    text = f.read()
+# Split into entries by ^## [HEAL-...]
+entries = re.split(r"(?m)^## \[HEAL-", text)[1:]
+hits = []
+for body in entries:
+    if query in body.lower():
+        head = body.splitlines()[0]
+        pk = re.search(r"Pattern-Key:\s*(\S+)", body)
+        status = re.search(r"Status\*\*:\s*(\S+)", body) or re.search(r"Status:\s*(\S+)", body)
+        rc = re.search(r"Recurrence-Count:\s*(\d+)", body)
+        hits.append({
+            "id": "HEAL-" + head.split("]")[0],
+            "name": head.split("]", 1)[1].strip() if "]" in head else head,
+            "pattern_key": pk.group(1) if pk else "?",
+            "status": status.group(1) if status else "?",
+            "recurrence": rc.group(1) if rc else "1",
+        })
+if not hits:
+    print(f"(no heals match '{query}')")
+else:
+    print(f"Found {len(hits)} matching heal(s):\n")
+    for h in hits:
+        print(f"  {h['id']} {h['name']}")
+        print(f"    pattern={h['pattern_key']}  status={h['status']}  recurrence={h['recurrence']}")
+PY

data/skills/boocode/self-healing/scripts/new-heal.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# new-heal.sh — Initialize a new HEAL-<date>-<seq> entry skeleton.
+# Usage: ./new-heal.sh <short_kebab_name> [trigger]
+#   trigger: tool-failure | missing-capability | env-issue | external-change | <free-form>
+#
+# Appends a templated HEAL entry to .learnings/HEALS.md and prints the HEAL-ID.
+# Does NOT create .learnings/heals/<HEAL-ID>/ — that folder is lazy, created
+# only when artifacts are written.
+
+set -euo pipefail
+
+NAME="${1:-}"
+TRIGGER="${2:-tool-failure}"
+
+if [[ -z "$NAME" ]]; then
+  echo "usage: $0 <short_kebab_name> [trigger]" >&2
+  exit 2
+fi
+
+LEARNINGS_DIR="$(pwd)/.learnings"
+HEALS_FILE="$LEARNINGS_DIR/HEALS.md"
+mkdir -p "$LEARNINGS_DIR"
+
+DATE="$(date +%Y%m%d)"
+SEQ=$(grep -c "^## \[HEAL-${DATE}-" "$HEALS_FILE" 2>/dev/null || echo 0)
+NEXT=$(printf "%03d" $((SEQ + 1)))
+HEAL_ID="HEAL-${DATE}-${NEXT}"
+
+# Active-Context is optional. The agent / harness can set ACTIVE_CONTEXT in env.
+ACTIVE_CONTEXT="${ACTIVE_CONTEXT:-}"
+ACTIVE_LINE=""
+if [[ -n "$ACTIVE_CONTEXT" ]]; then
+  ACTIVE_LINE="**Active-Context**: $ACTIVE_CONTEXT
+"
+fi
+
+cat >> "$HEALS_FILE" <<EOF
+
+## [$HEAL_ID] $NAME
+
+**Logged**: $(date -u +%Y-%m-%dT%H:%M:%SZ)
+**Status**: pending-verify
+**Trigger**: $TRIGGER
+${ACTIVE_LINE}**Area**: TODO
+**Priority**: medium
+
+### Failure
+TODO — concrete error, command, exit code
+
+### Diagnosis
+TODO — root cause after investigation
+
+### Fix
+TODO — patch applied (commands, snippets, or pointers to .learnings/heals/$HEAL_ID/ if files were generated)
+
+### Verification
+TODO — what was run after the fix, what it returned. **Update Status to "verified" only after this passes.**
+
+### Metadata
+- Related Files: TODO
+- See Also: TODO
+- Pattern-Key: TODO
+- Recurrence-Count: 1
+- First-Seen: $(date +%Y-%m-%d)
+- Last-Seen: $(date +%Y-%m-%d)
+
+---
+EOF
+
+# stdout = the HEAL-ID alone, so `ID=$(new-heal.sh ...)` captures it cleanly.
+# Human guidance goes to stderr.
+echo "$HEAL_ID"
+echo "$HEALS_FILE" >&2
+echo "(create .learnings/heals/$HEAL_ID/ only if you generate artifacts to put there)" >&2

data/skills/boocode/verify-gate/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: verify-gate
+description: "Runs project compile, test, and lint commands between implementation and quality review. Gates simplify-and-harden behind machine verification. If checks fail, enters a fix loop with diagnostics. If checks pass, signals ready for quality pass. Use after any implementation work completes and before signaling done. Essential for the inner loop's verify step."
+---
+
+# Verify Gate
+
+Machine verification gate between implementation and quality review. Runs the project's compile, test, and lint commands. If any fail, enters a fix loop. If all pass, unblocks the quality pass.
+
+This is the inner loop's **verify** step. Without it, the agent hands off code with zero machine signal about whether it actually works.
+
+## When to Use
+
+- After any implementation work completes, before signaling "done"
+- Before running simplify-and-harden or quality review
+- After fixing audit findings from code review
+- Any time you want a machine-verified green signal
+
+## Pipeline Position
+
+```
+[implementation] → verify-gate → [quality review / simplify-and-harden]
+                   ↻ fix loop — on failure, diagnose and retry
+```
+
+## Step 1: Discover Project Commands
+
+Read the project's configuration to find verification commands. Check these sources in order:
+
+1. **Project instruction files** (`CLAUDE.md`, `data/AGENTS.md`) — look for a `## Verification` or `## Test Commands` section
+2. **package.json** — `scripts.test`, `scripts.lint`, `scripts.typecheck`, `scripts.build`. BooCode uses pnpm, so prefer `pnpm run <script>` when `pnpm-lock.yaml` is present.
+3. **Makefile** / **Justfile** — `test`, `lint`, `check`, `build` targets
+4. **Cargo.toml** — `cargo build`, `cargo test`, `cargo clippy`
+5. **pyproject.toml** / **setup.cfg** — `pytest`, `mypy`, `ruff`
+6. **go.mod** — `go build ./...`, `go test ./...`, `go vet ./...`
+7. **deno.json** / **deno.jsonc** — `deno task <name>` for any defined tasks
+
+If no commands are discoverable, ask the user once and suggest they add a `## Verification` section to `CLAUDE.md` for future sessions:
+
+```markdown
+## Verification
+
+- Build: `pnpm run build`
+- Test: `pnpm test`
+- Lint: `pnpm run lint`
+- Type check: `npx tsc -p apps/server/tsconfig.json --noEmit`
+```
+
+## Step 2: Run Verification
+
+Run discovered commands in this order. Stop at the first failure category.
+
+### Phase 1: Compile / Type Check
+Run the build or type-check command. These catch structural errors before wasting time on tests.
+
+```
+Exit 0 → proceed to Phase 2
+Exit non-zero → enter fix loop with compiler output
+```
+
+### Phase 2: Tests
+Run the test command. Scope to changed files if the test runner supports it.
+
+```
+Exit 0 → proceed to Phase 3
+Exit non-zero → enter fix loop with test output
+```
+
+### Phase 3: Lint (optional, skippable with --skip-lint)
+Run the lint command. Lint failures are lower severity but still worth catching.
+
+```
+Exit 0 → all phases green, gate passes
+Exit non-zero → enter fix loop with lint output
+```
+
+## Step 3: Fix Loop
+
+When a phase fails:
+
+1. **Read the output.** Parse the error output for actionable diagnostics — file paths, line numbers, error messages.
+2. **Scope the fix.** Only fix what the verification caught. Do not refactor, improve, or touch unrelated code.
+3. **Apply the fix.** Make the minimal change to resolve the failure.
+4. **Re-run the failed phase.** Not all phases — just the one that failed.
+5. **If it passes**, continue to the next phase.
+6. **If it fails again**, increment the attempt counter.
+
+### Fix Loop Limits
+
+- **Default max attempts:** 3 per phase (configurable via `--fix-limit N`)
+- **Counter increments on every attempt**, even if the error changes. Fixing Error A and uncovering Error B counts as attempt 2, not attempt 1. The counter tracks fix attempts, not unique errors.
+- **If limit reached:** Stop. Report what failed, what was tried, and the remaining error output. Do not guess further — signal to the user that manual intervention is needed.
+- **Total budget:** The fix loop should not exceed 20% of the original implementation effort. If fixes are snowballing, stop and report.
+
+## Step 4: Gate Signal
+
+When all phases pass:
+
+```markdown
+## Verify Gate: PASSED
+
+- Build: passed
+- Tests: passed (N tests, M suites)
+- Lint: passed (or skipped)
+
+Ready for quality review.
+```
+
+When the fix loop is exhausted:
+
+```markdown
+## Verify Gate: BLOCKED
+
+- Build: passed
+- Tests: FAILED (attempt 3/3)
+  - [file:line] error description
+  - [file:line] error description
+- Lint: not reached
+
+Fix loop exhausted. Manual intervention needed before quality review.
+```
+
+## Integration with Other Skills
+
+### boocode simplify-and-harden / quality review
+verify-gate should gate any quality pass. Run verify-gate first; only proceed to review if the gate passes.
+
+### self-healing (if available)
+On any failure during the verify run, consider handing the diagnostics to a self-healing loop (diagnose → patch → verify → persist). Verify-gate then re-runs the checks. Up to 3 heal attempts per phase before abandoning.
+
+### self-improvement
+If a recurring error pattern emerges across verify runs, capture it in `CLAUDE.md` or as a new skill under `data/skills/boocode/` so future verify-gate runs don't rediscover the same fix.
+
+## What This Skill Does NOT Do
+
+- Does not review code quality (that's a separate review pass)
+- Does not check security
+- Does not verify spec compliance
+- Does not modify test files or add new tests
+- Does not run tests for code it didn't change (unless the test runner doesn't support scoping)
+
+## Configuration
+
+If the project has a `verify-gate` section in `CLAUDE.md` or `data/AGENTS.md`:
+
+```yaml
+## Verify Gate Config
+
+build: pnpm run build
+test: pnpm test
+lint: pnpm run lint
+type_check: npx tsc -p apps/server/tsconfig.json --noEmit
+fix_limit: 3
+skip_lint: false
+test_scope: changed  # changed | all
+```
+
+If no configuration exists, discover commands automatically (Step 1) and suggest persisting them.
+
+### Custom Verification Steps
+
+Projects with custom invariants can define additional verification phases. These run as extra phases after the standard compile/test/lint checks.
+
+Example — a project that needs API schema validation:
+
+```yaml
+## Verify Gate Config
+
+custom_checks:
+  - name: validate-schema
+    command: python scripts/validate_schema.py --strict
+  - name: check-no-legacy-imports
+    command: grep -r "from legacy" src/ --include="*.py" && exit 1 || exit 0
+```
+
+When custom checks are defined, verify-gate runs them as **Phase 4** after lint. Each check's exit code determines pass/fail. Failed checks enter the same fix loop as standard phases.
+
+This moves project-specific invariants from "knowledge in your head" to "knowledge in the harness" — exactly where the agent can reach it.

docker-compose.yml

@@ -110,7 +110,7 @@ services:
       - "127.0.0.1:8080:8080"
     restart: unless-stopped
     environment:
-      CODECONTEXT_CHILD: node /usr/local/lib/boocontext/dist/index.js
+      CODECONTEXT_CHILD: node /usr/local/lib/boocontext/dist/index.js --mcp
       TYPE_INJECT_MCP_PATH: /opt/type-inject/packages/mcp/dist/index.js
       TREE_SITTER_MCP_CMD: uvx
       TREE_SITTER_MCP_ARGS: --from tree-sitter-analyzer[mcp] tree-sitter-analyzer-mcp

packages/ion/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@boocode/ion",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./schema": {
+      "types": "./dist/schema/index.d.ts",
+      "default": "./dist/schema/index.js"
+    },
+    "./engine": {
+      "types": "./dist/engine/index.d.ts",
+      "default": "./dist/engine/index.js"
+    },
+    "./store": {
+      "types": "./dist/store/index.d.ts",
+      "default": "./dist/store/index.js"
+    },
+    "./format": {
+      "types": "./dist/format/index.d.ts",
+      "default": "./dist/format/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli/index.d.ts",
+      "default": "./dist/cli/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@types/node": "^25.9.2",
+    "js-yaml": "^4.1.0",
+    "nanoid": "^5.0.9",
+    "ulid": "^2.3.0",
+    "zod": "^3.25.76"
+  },
+  "optionalDependencies": {
+    "better-sqlite3": "^11.0.0",
+    "postgres": "^3.4.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/js-yaml": "^4.0.9",
+    "typescript": "^5.5.0",
+    "vitest": "^3.2.4"
+  },
+  "license": "MIT"
+}

packages/ion/src/cli/commands/abandon.ts

@@ -0,0 +1,55 @@
+/**
+ * `workflow abandon` — Cancel a non-terminal workflow run.
+ *
+ * Marks the run as cancelled. Only works on runs that are not
+ * already in a terminal state (completed, failed, cancelled).
+ *
+ * @example
+ *   workflow abandon abc123
+ *   workflow abandon abc123 --json
+ */
+
+import type { CliOptions } from '../utils.js';
+import { printJson } from '../utils.js';
+
+// ---------------------------------------------------------------------------
+// Stub: engine integration (not implemented yet)
+// ---------------------------------------------------------------------------
+
+interface AbandonResult {
+  runId: string;
+  abandoned: boolean;
+  message: string;
+}
+
+async function abandonWorkflowRun(_runId: string): Promise<AbandonResult> {
+  throw new Error('not implemented yet: abandonWorkflowRun');
+}
+
+// ---------------------------------------------------------------------------
+// Command handler
+// ---------------------------------------------------------------------------
+
+export async function abandonCommand(
+  args: string[],
+  options: CliOptions,
+): Promise<void> {
+  if (args.length === 0) {
+    throw new Error('Missing required argument: <run-id>\n\nUsage: workflow abandon <run-id> [--json]');
+  }
+
+  const runId = args[0]!;
+
+  const result = await abandonWorkflowRun(runId);
+
+  if (options.json) {
+    printJson(result);
+    return;
+  }
+
+  if (result.abandoned) {
+    console.log(`⊘ Run ${result.runId} abandoned (cancelled).`);
+  } else {
+    console.log(`Failed to abandon run ${result.runId}: ${result.message}`);
+  }
+}

packages/ion/src/cli/commands/approve.ts

@@ -0,0 +1,60 @@
+/**
+ * `workflow approve` — Approve a paused workflow run.
+ *
+ * @example
+ *   workflow approve abc123
+ *   workflow approve abc123 "Looks good" --json
+ */
+
+import type { CliOptions } from '../utils.js';
+import { printJson } from '../utils.js';
+
+// ---------------------------------------------------------------------------
+// Stub: engine integration (not implemented yet)
+// ---------------------------------------------------------------------------
+
+interface ApproveResult {
+  runId: string;
+  approved: boolean;
+  comment?: string;
+  message: string;
+}
+
+async function approveWorkflowRun(
+  _runId: string,
+  _comment?: string,
+): Promise<ApproveResult> {
+  throw new Error('not implemented yet: approveWorkflowRun');
+}
+
+// ---------------------------------------------------------------------------
+// Command handler
+// ---------------------------------------------------------------------------
+
+export async function approveCommand(
+  args: string[],
+  options: CliOptions,
+): Promise<void> {
+  if (args.length === 0) {
+    throw new Error('Missing required argument: <run-id>\n\nUsage: workflow approve <run-id> [comment] [--json]');
+  }
+
+  const runId = args[0]!;
+  const comment = args.length > 1 ? args.slice(1).join(' ') : undefined;
+
+  const result = await approveWorkflowRun(runId, comment);
+
+  if (options.json) {
+    printJson(result);
+    return;
+  }
+
+  if (result.approved) {
+    console.log(`✓ Run ${result.runId} approved.`);
+    if (result.comment) {
+      console.log(`  Comment: ${result.comment}`);
+    }
+  } else {
+    console.log(`✗ Failed to approve run ${result.runId}: ${result.message}`);
+  }
+}

packages/ion/src/cli/commands/cleanup.ts

@@ -0,0 +1,74 @@
+/**
+ * `workflow cleanup` — Remove old workflow run artifacts.
+ *
+ * Default retention: 7 days. Removes run data older than the specified
+ * number of days.
+ *
+ * @example
+ *   workflow cleanup
+ *   workflow cleanup 30 --json
+ */
+
+import type { CliOptions } from '../utils.js';
+import { printJson } from '../utils.js';
+
+// ---------------------------------------------------------------------------
+// Stub: engine integration (not implemented yet)
+// ---------------------------------------------------------------------------
+
+interface CleanupResult {
+  removedRuns: number;
+  removedEvents: number;
+  freedBytes: number;
+  retentionDays: number;
+}
+
+async function cleanupWorkflowRuns(
+  _days: number,
+  _cwd?: string,
+): Promise<CleanupResult> {
+  throw new Error('not implemented yet: cleanupWorkflowRuns');
+}
+
+// ---------------------------------------------------------------------------
+// Command handler
+// ---------------------------------------------------------------------------
+
+export async function cleanupCommand(
+  args: string[],
+  options: CliOptions,
+): Promise<void> {
+  // First positional arg is the number of days (default 7).
+  const days = args.length > 0 ? parseInt(args[0]!, 10) : 7;
+
+  if (isNaN(days) || days < 1) {
+    throw new Error(`Invalid retention days: ${args[0]}. Must be a positive integer.`);
+  }
+
+  const result = await cleanupWorkflowRuns(days, options.cwd);
+
+  if (options.json) {
+    printJson(result);
+    return;
+  }
+
+  console.log(`Cleanup complete (retention: ${result.retentionDays} days).`);
+  console.log(`  Runs removed: ${result.removedRuns}`);
+  console.log(`  Events removed: ${result.removedEvents}`);
+  console.log(`  Space freed: ${formatBytes(result.freedBytes)}`);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 B';
+  const units = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.min(
+    Math.floor(Math.log(bytes) / Math.log(1024)),
+    units.length - 1,
+  );
+  const value = bytes / Math.pow(1024, i);
+  return `${value.toFixed(i === 0 ? 0 : 1)} ${units[i]}`;
+}

packages/ion/src/cli/commands/convert.ts

@@ -0,0 +1,62 @@
+/**
+ * `workflow convert` — Convert a .sop.md file to a YAML workflow definition.
+ *
+ * Reads the SOP markdown file, parses its structure, and outputs
+ * a corresponding YAML workflow definition.
+ *
+ * @example
+ *   workflow convert deploy.sop.md
+ *   workflow convert deploy.sop.md --output workflows/deploy.yaml
+ */
+
+import type { CliOptions } from '../utils.js';
+import { printJson } from '../utils.js';
+
+// ---------------------------------------------------------------------------
+// Stub: engine integration (not implemented yet)
+// ---------------------------------------------------------------------------
+
+interface ConvertResult {
+  inputFile: string;
+  outputFile: string;
+  workflowName: string;
+  nodeCount: number;
+}
+
+async function convertSopToYaml(
+  _inputPath: string,
+  _outputPath?: string,
+): Promise<ConvertResult> {
+  throw new Error('not implemented yet: convertSopToYaml');
+}
+
+// ---------------------------------------------------------------------------
+// Command handler
+// ---------------------------------------------------------------------------
+
+export async function convertCommand(
+  args: string[],
+  options: CliOptions,
+): Promise<void> {
+  if (args.length === 0) {
+    throw new Error('Missing required argument: <file.sop.md>\n\nUsage: workflow convert <file.sop.md> [--output <path>]');
+  }
+
+  const inputPath = args[0]!;
+
+  if (!inputPath.endsWith('.sop.md')) {
+    throw new Error(`Input file must end with .sop.md, got: ${inputPath}`);
+  }
+
+  const result = await convertSopToYaml(inputPath, options.output);
+
+  if (options.json) {
+    printJson(result);
+    return;
+  }
+
+  console.log(`Converted: ${result.inputFile}`);
+  console.log(`  Output: ${result.outputFile}`);
+  console.log(`  Workflow: ${result.workflowName}`);
+  console.log(`  Nodes: ${result.nodeCount}`);
+}

packages/ion/src/cli/commands/list.ts

@@ -0,0 +1,59 @@
+/**
+ * `workflow list` — List all available workflows.
+ *
+ * Discovers workflows from both bundled and project sources and displays
+ * them in a formatted table (or JSON with --json).
+ *
+ * @example
+ *   workflow list
+ *   workflow list --json
+ */
+
+import type { CliOptions } from '../utils.js';
+import { printTable, printJson } from '../utils.js';
+
+// ---------------------------------------------------------------------------
+// Stub: engine integration (not implemented yet)
+// ---------------------------------------------------------------------------
+
+interface WorkflowEntry {
+  name: string;
+  description: string;
+  source: 'bundled' | 'project';
+}
+
+async function discoverWorkflows(_cwd?: string): Promise<WorkflowEntry[]> {
+  throw new Error('not implemented yet: discoverWorkflows');
+}
+
+// ---------------------------------------------------------------------------
+// Command handler
+// ---------------------------------------------------------------------------
+
+export async function listCommand(
+  _args: string[],
+  options: CliOptions,
+): Promise<void> {
+  const workflows = await discoverWorkflows(options.cwd);
+
+  if (options.json) {
+    printJson(workflows);
+    return;
+  }
+
+  console.log('Available workflows:');
+  console.log('');
+
+  printTable(
+    workflows.map((w) => ({
+      name: w.name,
+      description: w.description,
+      source: w.source,
+    })),
+    [
+      { header: 'Name', field: 'name', minWidth: 20 },
+      { header: 'Description', field: 'description', minWidth: 30 },
+      { header: 'Source', field: 'source', minWidth: 10 },
+    ],
+  );
+}

packages/ion/src/cli/commands/reject.ts

@@ -0,0 +1,62 @@
+/**
+ * `workflow reject` — Reject a paused workflow run.
+ *
+ * Sets $REJECTION_REASON with the provided reason string.
+ *
+ * @example
+ *   workflow reject abc123
+ *   workflow reject abc123 "Not compliant" --json
+ */
+
+import type { CliOptions } from '../utils.js';
+import { printJson } from '../utils.js';
+
+// ---------------------------------------------------------------------------
+// Stub: engine integration (not implemented yet)
+// ---------------------------------------------------------------------------
+
+interface RejectResult {
+  runId: string;
+  rejected: boolean;
+  reason?: string;
+  message: string;
+}
+
+async function rejectWorkflowRun(
+  _runId: string,
+  _reason?: string,
+): Promise<RejectResult> {
+  throw new Error('not implemented yet: rejectWorkflowRun');
+}
+
+// ---------------------------------------------------------------------------
+// Command handler
+// ---------------------------------------------------------------------------
+
+export async function rejectCommand(
+  args: string[],
+  options: CliOptions,
+): Promise<void> {
+  if (args.length === 0) {
+    throw new Error('Missing required argument: <run-id>\n\nUsage: workflow reject <run-id> [reason] [--json]');
+  }
+
+  const runId = args[0]!;
+  const reason = args.length > 1 ? args.slice(1).join(' ') : undefined;
+
+  const result = await rejectWorkflowRun(runId, reason);
+
+  if (options.json) {
+    printJson(result);
+    return;
+  }
+
+  if (result.rejected) {
+    console.log(`✗ Run ${result.runId} rejected.`);
+    if (result.reason) {
+      console.log(`  Reason: ${result.reason}`);
+    }
+  } else {
+    console.log(`Failed to reject run ${result.runId}: ${result.message}`);
+  }
+}

packages/ion/src/cli/commands/resume.ts

@@ -0,0 +1,55 @@
+/**
+ * `workflow resume` — Resume a failed workflow run.
+ *
+ * Skips completed nodes and re-executes from the failure point.
+ *
+ * @example
+ *   workflow resume abc123
+ *   workflow resume abc123 --json
+ */
+
+import type { CliOptions } from '../utils.js';
+import { printJson } from '../utils.js';
+
+// ---------------------------------------------------------------------------
+// Stub: engine integration (not implemented yet)
+// ---------------------------------------------------------------------------
+
+interface ResumeResult {
+  runId: string;
+  resumed: boolean;
+  message: string;
+}
+
+async function resumeWorkflowRun(_runId: string): Promise<ResumeResult> {
+  throw new Error('not implemented yet: resumeWorkflowRun');
+}
+
+// ---------------------------------------------------------------------------
+// Command handler
+// ---------------------------------------------------------------------------
+
+export async function resumeCommand(
+  args: string[],
+  options: CliOptions,
+): Promise<void> {
+  if (args.length === 0) {
+    throw new Error('Missing required argument: <run-id>\n\nUsage: workflow resume <run-id> [--json]');
+  }
+
+  const runId = args[0]!;
+
+  const result = await resumeWorkflowRun(runId);
+
+  if (options.json) {
+    printJson(result);
+    return;
+  }
+
+  if (result.resumed) {
+    console.log(`↻ Run ${result.runId} resumed.`);
+    console.log(`  ${result.message}`);
+  } else {
+    console.log(`Failed to resume run ${result.runId}: ${result.message}`);
+  }
+}

packages/ion/src/cli/commands/run.ts

@@ -0,0 +1,94 @@
+/**
+ * `workflow run` — Execute a workflow by name.
+ *
+ * Resolves the workflow, passes message args, and shows real-time progress.
+ * With --detach, runs in background and returns the run ID immediately.
+ *
+ * @example
+ *   workflow run deploy
+ *   workflow run deploy --cwd /tmp/project --json
+ *   workflow run deploy --detach
+ */
+
+import type { CliOptions } from '../utils.js';
+import { printJson } from '../utils.js';
+
+// ---------------------------------------------------------------------------
+// Stub: engine integration (not implemented yet)
+// ---------------------------------------------------------------------------
+
+interface WorkflowRunResult {
+  id: string;
+  workflowName: string;
+  status: string;
+  output?: Record<string, unknown>;
+  error?: string;
+  startedAt: string;
+  completedAt?: string;
+}
+
+async function resolveWorkflow(
+  _name: string,
+  _cwd?: string,
+): Promise<unknown> {
+  throw new Error('not implemented yet: resolveWorkflow');
+}
+
+async function executeWorkflow(
+  _workflow: unknown,
+  _messageArgs: string[],
+  _options: { cwd?: string; detach?: boolean },
+): Promise<WorkflowRunResult> {
+  throw new Error('not implemented yet: executeWorkflow');
+}
+
+// ---------------------------------------------------------------------------
+// Command handler
+// ---------------------------------------------------------------------------
+
+export async function runCommand(
+  args: string[],
+  options: CliOptions,
+): Promise<void> {
+  if (args.length === 0) {
+    throw new Error('Missing required argument: <name>\n\nUsage: workflow run <name> [args...] [--cwd <path>] [--detach] [--json]');
+  }
+
+  const workflowName = args[0]!;
+  const messageArgs = args.slice(1);
+  const detach = options.json ? false : false; // --detach is a flag, not in CliOptions yet
+
+  // Parse --detach from raw args (it's a boolean flag).
+  // This is handled by the arg parser in the main entry point,
+  // but since CliOptions doesn't have detach, we check process.argv.
+  const isDetach = process.argv.includes('--detach');
+
+  const workflow = await resolveWorkflow(workflowName, options.cwd);
+  const result = await executeWorkflow(workflow, messageArgs, {
+    cwd: options.cwd,
+    detach: isDetach,
+  });
+
+  if (options.json) {
+    printJson(result);
+    return;
+  }
+
+  if (isDetach) {
+    console.log(`Workflow started in background.`);
+    console.log(`Run ID: ${result.id}`);
+    console.log(`Workflow: ${result.workflowName}`);
+    console.log(`Status: ${result.status}`);
+  } else {
+    console.log(`Workflow run completed.`);
+    console.log(`  Run ID: ${result.id}`);
+    console.log(`  Workflow: ${result.workflowName}`);
+    console.log(`  Status: ${result.status}`);
+    if (result.output) {
+      console.log(`  Output: ${JSON.stringify(result.output)}`);
+    }
+    if (result.error) {
+      console.log(`  Error: ${result.error}`);
+    }
+  }
+}

packages/ion/src/cli/commands/runs.ts

@@ -0,0 +1,91 @@
+/**
+ * `workflow runs` — List recent workflow runs with filters.
+ *
+ * @example
+ *   workflow runs
+ *   workflow runs --status failed --limit 10 --json
+ *   workflow runs --all
+ */
+
+import type { CliOptions } from '../utils.js';
+import { printTable, printJson, formatTimestamp, formatDuration } from '../utils.js';
+
+// ---------------------------------------------------------------------------
+// Stub: engine integration (not implemented yet)
+// ---------------------------------------------------------------------------
+
+interface RunRecord {
+  id: string;
+  workflowName: string;
+  status: string;
+  startedAt: string;
+  duration?: number; // ms, absent if still running
+  currentNode?: string;
+}
+
+async function listWorkflowRuns(_filters: {
+  status?: string;
+  limit?: number;
+  all?: boolean;
+  cwd?: string;
+}): Promise<RunRecord[]> {
+  throw new Error('not implemented yet: listWorkflowRuns');
+}
+
+// ---------------------------------------------------------------------------
+// Command handler
+// ---------------------------------------------------------------------------
+
+export async function runsCommand(
+  args: string[],
+  options: CliOptions,
+): Promise<void> {
+  // Parse --status, --limit, --all from args/options.
+  // These are already extracted by parseArgs into options.
+  const status = typeof (options as Record<string, unknown>).status === 'string'
+    ? (options as Record<string, unknown>).status as string
+    : undefined;
+  const limit = typeof (options as Record<string, unknown>).limit === 'string'
+    ? parseInt((options as Record<string, unknown>).limit as string, 10)
+    : 50;
+  const all = (options as Record<string, unknown>).all === true;
+
+  const runs = await listWorkflowRuns({
+    status,
+    limit,
+    all,
+    cwd: options.cwd,
+  });
+
+  if (options.json) {
+    printJson(runs);
+    return;
+  }
+
+  if (runs.length === 0) {
+    console.log('No workflow runs found.');
+    return;
+  }
+
+  console.log(`Showing ${runs.length} run(s):`);
+  console.log('');
+
+  printTable(
+    runs.map((r) => ({
+      id: r.id,
+      workflow: r.workflowName,
+      status: r.status,
+      started: formatTimestamp(new Date(r.startedAt)),
+      duration: r.duration != null ? formatDuration(r.duration) : '-',
+      currentNode: r.currentNode ?? '-',
+    })),
+    [
+      { header: 'ID', field: 'id', minWidth: 26 },
+      { header: 'Workflow', field: 'workflow', minWidth: 20 },
+      { header: 'Status', field: 'status', minWidth: 10 },
+      { header: 'Started', field: 'started', minWidth: 19 },
+      { header: 'Duration', field: 'duration', minWidth: 10 },
+      { header: 'Node', field: 'currentNode', minWidth: 15 },
+    ],
+  );
+}

packages/ion/src/cli/commands/status.ts

@@ -0,0 +1,67 @@
+/**
+ * `workflow status` — Show active (running + paused) workflow runs.
+ *
+ * @example
+ *   workflow status
+ *   workflow status --json
+ */
+
+import type { CliOptions } from '../utils.js';
+import { printTable, printJson, formatDuration } from '../utils.js';
+
+// ---------------------------------------------------------------------------
+// Stub: engine integration (not implemented yet)
+// ---------------------------------------------------------------------------
+
+interface ActiveRun {
+  id: string;
+  workflowName: string;
+  status: string;
+  duration: number; // ms
+  currentNode?: string;
+}
+
+async function getActiveRuns(_cwd?: string): Promise<ActiveRun[]> {
+  throw new Error('not implemented yet: getActiveRuns');
+}
+
+// ---------------------------------------------------------------------------
+// Command handler
+// ---------------------------------------------------------------------------
+
+export async function statusCommand(
+  _args: string[],
+  options: CliOptions,
+): Promise<void> {
+  const runs = await getActiveRuns(options.cwd);
+
+  if (options.json) {
+    printJson(runs);
+    return;
+  }
+
+  if (runs.length === 0) {
+    console.log('No active workflow runs.');
+    return;
+  }
+
+  console.log('Active workflow runs:');
+  console.log('');
+
+  printTable(
+    runs.map((r) => ({
+      id: r.id,
+      workflow: r.workflowName,
+      status: r.status,
+      duration: formatDuration(r.duration),
+      currentNode: r.currentNode ?? '-',
+    })),
+    [
+      { header: 'ID', field: 'id', minWidth: 26 },
+      { header: 'Workflow', field: 'workflow', minWidth: 20 },
+      { header: 'Status', field: 'status', minWidth: 10 },
+      { header: 'Duration', field: 'duration', minWidth: 10 },
+      { header: 'Current Node', field: 'currentNode', minWidth: 15 },
+    ],
+  );
+}

packages/ion/src/cli/commands/validate.ts

@@ -0,0 +1,66 @@
+/**
+ * `workflow validate` — Validate a workflow definition without executing.
+ *
+ * Loads the workflow, runs schema validation, and reports any errors.
+ *
+ * @example
+ *   workflow validate deploy
+ *   workflow validate deploy --json
+ */
+
+import type { CliOptions } from '../utils.js';
+import { printJson } from '../utils.js';
+
+// ---------------------------------------------------------------------------
+// Stub: engine integration (not implemented yet)
+// ---------------------------------------------------------------------------
+
+interface ValidationError {
+  path: string;
+  message: string;
+}
+
+interface ValidateResult {
+  valid: boolean;
+  errors: ValidationError[];
+  workflowName: string;
+}
+
+async function validateWorkflow(
+  _name: string,
+  _cwd?: string,
+): Promise<ValidateResult> {
+  throw new Error('not implemented yet: validateWorkflow');
+}
+
+// ---------------------------------------------------------------------------
+// Command handler
+// ---------------------------------------------------------------------------
+
+export async function validateCommand(
+  args: string[],
+  options: CliOptions,
+): Promise<void> {
+  if (args.length === 0) {
+    throw new Error('Missing required argument: <name>\n\nUsage: workflow validate <name> [--json]');
+  }
+
+  const workflowName = args[0]!;
+
+  const result = await validateWorkflow(workflowName, options.cwd);
+
+  if (options.json) {
+    printJson(result);
+    return;
+  }
+
+  if (result.valid) {
+    console.log(`✓ Workflow "${result.workflowName}" is valid.`);
+  } else {
+    console.log(`✗ Workflow "${result.workflowName}" has ${result.errors.length} error(s):`);
+    console.log('');
+    for (const err of result.errors) {
+      console.log(`  ${err.path}: ${err.message}`);
+    }
+  }
+}

packages/ion/src/cli/index.ts

@@ -0,0 +1,207 @@
+/**
+ * Ion workflow engine CLI entry point.
+ *
+ * Pure Node.js CLI using process.argv parsing — no external argparse library.
+ * Routes subcommands to their respective handler modules.
+ *
+ * @example
+ *   node dist/cli/index.js workflow list --json
+ *   node dist/cli/index.js workflow run deploy --cwd /tmp/project
+ */
+
+import { parseArgs, buildCliOptions, printJson } from './utils.js';
+import type { CliOptions } from './utils.js';
+
+import { listCommand } from './commands/list.js';
+import { runCommand } from './commands/run.js';
+import { statusCommand } from './commands/status.js';
+import { runsCommand } from './commands/runs.js';
+import { approveCommand } from './commands/approve.js';
+import { rejectCommand } from './commands/reject.js';
+import { resumeCommand } from './commands/resume.js';
+import { abandonCommand } from './commands/abandon.js';
+import { cleanupCommand } from './commands/cleanup.js';
+import { validateCommand } from './commands/validate.js';
+import { convertCommand } from './commands/convert.js';
+
+// ---------------------------------------------------------------------------
+// Command registry
+// ---------------------------------------------------------------------------
+
+interface CommandEntry {
+  name: string;
+  description: string;
+  usage: string;
+  handler: (args: string[], options: CliOptions) => Promise<void>;
+}
+
+const COMMANDS: CommandEntry[] = [
+  {
+    name: 'list',
+    description: 'List all available workflows',
+    usage: 'workflow list [--json]',
+    handler: listCommand,
+  },
+  {
+    name: 'run',
+    description: 'Execute a workflow by name',
+    usage: 'workflow run <name> [args...] [--cwd <path>] [--detach] [--json]',
+    handler: runCommand,
+  },
+  {
+    name: 'status',
+    description: 'Show active (running + paused) workflow runs',
+    usage: 'workflow status [--json]',
+    handler: statusCommand,
+  },
+  {
+    name: 'runs',
+    description: 'List recent workflow runs with filters',
+    usage: 'workflow runs [--status <status>] [--limit N] [--all] [--json]',
+    handler: runsCommand,
+  },
+  {
+    name: 'approve',
+    description: 'Approve a paused workflow run',
+    usage: 'workflow approve <run-id> [comment] [--json]',
+    handler: approveCommand,
+  },
+  {
+    name: 'reject',
+    description: 'Reject a paused workflow run',
+    usage: 'workflow reject <run-id> [reason] [--json]',
+    handler: rejectCommand,
+  },
+  {
+    name: 'resume',
+    description: 'Resume a failed workflow run',
+    usage: 'workflow resume <run-id> [--json]',
+    handler: resumeCommand,
+  },
+  {
+    name: 'abandon',
+    description: 'Cancel a non-terminal workflow run',
+    usage: 'workflow abandon <run-id> [--json]',
+    handler: abandonCommand,
+  },
+  {
+    name: 'cleanup',
+    description: 'Remove old workflow run artifacts',
+    usage: 'workflow cleanup [days] [--json]',
+    handler: cleanupCommand,
+  },
+  {
+    name: 'validate',
+    description: 'Validate a workflow definition without executing',
+    usage: 'workflow validate <name> [--json]',
+    handler: validateCommand,
+  },
+  {
+    name: 'convert',
+    description: 'Convert a .sop.md file to a YAML workflow definition',
+    usage: 'workflow convert <file.sop.md> [--output <path>]',
+    handler: convertCommand,
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Help output
+// ---------------------------------------------------------------------------
+
+function printHelp(): void {
+  console.log('');
+  console.log('Ion — Workflow Engine CLI');
+  console.log('');
+  console.log('Usage:');
+  console.log('  workflow <command> [options]');
+  console.log('');
+  console.log('Commands:');
+
+  const maxNameLen = Math.max(...COMMANDS.map((c) => c.name.length));
+  for (const cmd of COMMANDS) {
+    const padded = cmd.name.padEnd(maxNameLen + 2);
+    console.log(`  ${padded}${cmd.description}`);
+  }
+
+  console.log('');
+  console.log('Global options:');
+  console.log('  --json          Output as JSON (suppresses all other output)');
+  console.log('  --cwd <path>    Set working directory');
+  console.log('  --store <path>  Path to workflow store');
+  console.log('  --db-path <p>   Path to database file');
+  console.log('');
+  console.log('Run "workflow <command> --help" for command-specific usage.');
+  console.log('');
+}
+
+function printCommandHelp(cmd: CommandEntry): void {
+  console.log('');
+  console.log(`workflow ${cmd.name}`);
+  console.log('');
+  console.log(`  ${cmd.description}`);
+  console.log('');
+  console.log('Usage:');
+  console.log(`  ${cmd.usage}`);
+  console.log('');
+}
+
+// ---------------------------------------------------------------------------
+// Main entry
+// ---------------------------------------------------------------------------
+
+export async function main(argv: string[] = process.argv.slice(2)): Promise<void> {
+  const { args, options } = parseArgs(argv);
+  const cliOptions = buildCliOptions(options);
+
+  // --help with no command → general help
+  if (args.length === 0 || options.help === true) {
+    printHelp();
+    process.exit(0);
+  }
+
+  const commandName = args[0];
+  const commandArgs = args.slice(1);
+
+  // --help after a command name → command-specific help
+  if (options.help) {
+    const cmd = COMMANDS.find((c) => c.name === commandName);
+    if (cmd) {
+      printCommandHelp(cmd);
+    } else {
+      console.error(`Unknown command: ${commandName}`);
+      printHelp();
+    }
+    process.exit(0);
+  }
+
+  const command = COMMANDS.find((c) => c.name === commandName);
+
+  if (!command) {
+    console.error(`Unknown command: ${commandName}`);
+    printHelp();
+    process.exit(1);
+    return; // unreachable, but satisfies TS control flow
+  }
+
+  try {
+    await command.handler(commandArgs, cliOptions);
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (cliOptions.json) {
+      printJson({ error: message });
+    } else {
+      console.error(`Error: ${message}`);
+    }
+    process.exit(1);
+  }
+}
+
+// Run when executed directly (not imported).
+// In ESM, check import.meta.url to detect direct execution.
+const _directRun = typeof import.meta !== 'undefined' && import.meta.url;
+if (_directRun) {
+  main().catch((err: unknown) => {
+    console.error(err);
+    process.exit(1);
+  });
+}

packages/ion/src/cli/utils.ts

@@ -0,0 +1,239 @@
+/**
+ * CLI utility functions for the Ion workflow engine.
+ *
+ * Provides formatting, table rendering, and JSON output helpers
+ * used across all CLI commands.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface CliOptions {
+  /** Working directory override. */
+  cwd?: string;
+  /** Output as JSON (suppresses all other output). */
+  json?: boolean;
+  /** Path to the workflow store database. */
+  store?: string;
+  /** Path to the database file. */
+  dbPath?: string;
+  /** Output file path (for convert command). */
+  output?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Duration formatting
+// ---------------------------------------------------------------------------
+
+/**
+ * Format a duration in milliseconds into a human-readable string.
+ *
+ * @example
+ *   formatDuration(90500) // "1m 30s"
+ *   formatDuration(3661000) // "1h 1m"
+ *   formatDuration(500) // "0s"
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 0) ms = 0;
+
+  const seconds = Math.floor(ms / 1000) % 60;
+  const minutes = Math.floor(ms / 60000) % 60;
+  const hours = Math.floor(ms / 3600000);
+
+  if (hours > 0) {
+    return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
+  }
+  if (minutes > 0) {
+    return seconds > 0 ? `${minutes}m ${seconds}s` : `${minutes}m`;
+  }
+  return `${seconds}s`;
+}
+
+// ---------------------------------------------------------------------------
+// Timestamp formatting
+// ---------------------------------------------------------------------------
+
+/**
+ * Format a Date into an ISO-like timestamp suitable for CLI display.
+ *
+ * @example
+ *   formatTimestamp(new Date('2025-06-07T14:30:00Z'))
+ *   // "2025-06-07 14:30:00"
+ */
+export function formatTimestamp(date: Date): string {
+  const y = date.getFullYear();
+  const mo = String(date.getMonth() + 1).padStart(2, '0');
+  const d = String(date.getDate()).padStart(2, '0');
+  const h = String(date.getHours()).padStart(2, '0');
+  const mi = String(date.getMinutes()).padStart(2, '0');
+  const s = String(date.getSeconds()).padStart(2, '0');
+  return `${y}-${mo}-${d} ${h}:${mi}:${s}`;
+}
+
+// ---------------------------------------------------------------------------
+// String truncation
+// ---------------------------------------------------------------------------
+
+/**
+ * Truncate a string to `max` characters, appending an ellipsis if truncated.
+ *
+ * @example
+ *   truncate('hello world', 8) // "hello..."
+ *   truncate('hi', 8) // "hi"
+ */
+export function truncate(str: string, max: number): string {
+  if (str.length <= max) return str;
+  if (max <= 3) return str.slice(0, max);
+  return str.slice(0, max - 3) + '...';
+}
+
+// ---------------------------------------------------------------------------
+// Table rendering
+// ---------------------------------------------------------------------------
+
+export interface TableColumn {
+  /** Column header label. */
+  header: string;
+  /** Minimum column width. */
+  minWidth?: number;
+  /** Field name to extract from each row object. */
+  field: string;
+}
+
+/**
+ * Print a formatted table to stdout.
+ *
+ * @param rows   - Array of row objects.
+ * @param columns - Column definitions with header labels and field names.
+ *
+ * @example
+ *   printTable(
+ *     [{ name: 'deploy', desc: 'Deploy app' }],
+ *     [{ header: 'Name', field: 'name' }, { header: 'Description', field: 'desc' }],
+ *   )
+ */
+export function printTable(
+  rows: Record<string, unknown>[],
+  columns: TableColumn[],
+): void {
+  if (rows.length === 0) {
+    console.log('(no results)');
+    return;
+  }
+
+  // Compute column widths.
+  const widths: number[] = columns.map((col) => {
+    const headerLen = col.header.length;
+    const dataLen = Math.max(
+      ...rows.map((row) => {
+        const val = row[col.field];
+        const str = val === undefined || val === null ? '' : String(val);
+        return str.length;
+      }),
+      0,
+    );
+    const min = col.minWidth ?? 0;
+    return Math.max(headerLen, dataLen, min);
+  });
+
+  // Header row.
+  const headerLine = columns
+    .map((col, i) => col.header.padEnd(widths[i]!))
+    .join('  ');
+  console.log(headerLine);
+
+  // Separator.
+  const sepLine = widths.map((w) => '-'.repeat(w)).join('  ');
+  console.log(sepLine);
+
+  // Data rows.
+  for (const row of rows) {
+    const line = columns
+      .map((col, i) => {
+        const val = row[col.field];
+        const str = val === undefined || val === null ? '' : String(val);
+        return str.padEnd(widths[i]!);
+      })
+      .join('  ');
+    console.log(line);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// JSON output
+// ---------------------------------------------------------------------------
+
+/**
+ * Print a data structure as formatted JSON to stdout.
+ * Uses 2-space indentation.
+ */
+export function printJson(data: unknown): void {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse CLI arguments into positional args and named options.
+ *
+ * Supports `--flag` (boolean) and `--key value` (string) formats.
+ * Everything after `--` is treated as positional.
+ *
+ * @example
+ *   parseArgs(['run', 'deploy', '--json', '--cwd', '/tmp'])
+ *   // { args: ['run', 'deploy'], options: { json: true, cwd: '/tmp' } }
+ */
+export function parseArgs(argv: string[]): {
+  args: string[];
+  options: Record<string, string | boolean>;
+} {
+  const args: string[] = [];
+  const options: Record<string, string | boolean> = {};
+  let i = 0;
+
+  while (i < argv.length) {
+    const token = argv[i]!;
+
+    if (token === '--') {
+      args.push(...argv.slice(i + 1));
+      break;
+    }
+
+    if (token.startsWith('--')) {
+      const key = token.slice(2);
+      const next = argv[i + 1];
+
+      if (next && !next.startsWith('--')) {
+        options[key] = next;
+        i += 2;
+      } else {
+        options[key] = true;
+        i += 1;
+      }
+    } else {
+      args.push(token);
+      i += 1;
+    }
+  }
+
+  return { args, options };
+}
+
+/**
+ * Build a CliOptions object from parsed options.
+ * Extracts known CLI flags into their typed fields.
+ */
+export function buildCliOptions(
+  options: Record<string, string | boolean>,
+): CliOptions {
+  return {
+    cwd: typeof options.cwd === 'string' ? options.cwd : undefined,
+    json: options.json === true,
+    store: typeof options.store === 'string' ? options.store : undefined,
+    dbPath: typeof options['db-path'] === 'string' ? options['db-path'] : undefined,
+    output: typeof options.output === 'string' ? options.output : undefined,
+  };
+}

packages/ion/src/engine/__tests__/command-validation.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from 'vitest';
+import { isValidCommandName } from '../command-validation.js';
+
+describe('isValidCommandName', () => {
+  describe('valid command names', () => {
+    it('accepts simple lowercase names', () => {
+      expect(isValidCommandName('assist')).toBe(true);
+    });
+
+    it('accepts kebab-case names', () => {
+      expect(isValidCommandName('code-review')).toBe(true);
+    });
+
+    it('accepts names with numbers', () => {
+      expect(isValidCommandName('deploy-v2')).toBe(true);
+    });
+
+    it('accepts single character names', () => {
+      expect(isValidCommandName('a')).toBe(true);
+    });
+
+    it('accepts names with only numbers', () => {
+      expect(isValidCommandName('123')).toBe(true);
+    });
+
+    it('accepts names with mixed alphanumeric and hyphens', () => {
+      expect(isValidCommandName('a1-b2-c3')).toBe(true);
+    });
+
+    it('accepts names starting with numbers', () => {
+      expect(isValidCommandName('2fa-verify')).toBe(true);
+    });
+  });
+
+  describe('invalid command names', () => {
+    it('rejects uppercase letters', () => {
+      expect(isValidCommandName('Assist')).toBe(false);
+      expect(isValidCommandName('CODE-REVIEW')).toBe(false);
+    });
+
+    it('rejects leading hyphens', () => {
+      expect(isValidCommandName('-assist')).toBe(false);
+    });
+
+    it('rejects trailing hyphens', () => {
+      expect(isValidCommandName('assist-')).toBe(false);
+    });
+
+    it('rejects double hyphens', () => {
+      expect(isValidCommandName('code--review')).toBe(false);
+    });
+
+    it('rejects empty strings', () => {
+      expect(isValidCommandName('')).toBe(false);
+    });
+
+    it('rejects underscores', () => {
+      expect(isValidCommandName('code_review')).toBe(false);
+    });
+
+    it('rejects spaces', () => {
+      expect(isValidCommandName('code review')).toBe(false);
+    });
+
+    it('rejects special characters', () => {
+      expect(isValidCommandName('code.review')).toBe(false);
+      expect(isValidCommandName('code@review')).toBe(false);
+    });
+  });
+});

packages/ion/src/engine/__tests__/condition-evaluator.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect } from 'vitest';
+import { evaluateCondition, ConditionError } from '../condition-evaluator.js';
+
+describe('evaluateCondition', () => {
+  describe('simple boolean conditions', () => {
+    it('evaluates boolean true in a comparison', () => {
+      expect(evaluateCondition('true == true', {})).toBe(true);
+    });
+
+    it('evaluates boolean false in a comparison', () => {
+      expect(evaluateCondition('false == false', {})).toBe(true);
+    });
+
+    it('evaluates true != false', () => {
+      expect(evaluateCondition('true != false', {})).toBe(true);
+    });
+
+    it('evaluates boolean via node reference', () => {
+      const outputs = { flag: { output: true } };
+      expect(evaluateCondition('$flag.output == true', outputs)).toBe(true);
+    });
+  });
+
+  describe('string equality with node references', () => {
+    it('evaluates $nodeId.output == "value" as true when matching', () => {
+      const outputs = { analysis: { output: 'done' } };
+      expect(evaluateCondition('$analysis.output == "done"', outputs)).toBe(true);
+    });
+
+    it('evaluates $nodeId.output == "value" as false when not matching', () => {
+      const outputs = { analysis: { output: 'pending' } };
+      expect(evaluateCondition('$analysis.output == "done"', outputs)).toBe(false);
+    });
+
+    it('evaluates $nodeId.output != "value" correctly', () => {
+      const outputs = { analysis: { output: 'pending' } };
+      expect(evaluateCondition('$analysis.output != "done"', outputs)).toBe(true);
+    });
+  });
+
+  describe('numeric comparisons', () => {
+    it('evaluates $score.output > 5 as true', () => {
+      const outputs = { score: { output: 10 } };
+      expect(evaluateCondition('$score.output > 5', outputs)).toBe(true);
+    });
+
+    it('evaluates $score.output > 5 as false when score is lower', () => {
+      const outputs = { score: { output: 3 } };
+      expect(evaluateCondition('$score.output > 5', outputs)).toBe(false);
+    });
+
+    it('evaluates >= comparison', () => {
+      const outputs = { score: { output: 5 } };
+      expect(evaluateCondition('$score.output >= 5', outputs)).toBe(true);
+    });
+
+    it('evaluates < comparison', () => {
+      const outputs = { score: { output: 3 } };
+      expect(evaluateCondition('$score.output < 5', outputs)).toBe(true);
+    });
+
+    it('evaluates <= comparison', () => {
+      const outputs = { score: { output: 5 } };
+      expect(evaluateCondition('$score.output <= 5', outputs)).toBe(true);
+    });
+  });
+
+  describe('AND/OR compounds', () => {
+    it('evaluates AND compound: both true', () => {
+      const outputs = { a: { output: 'x' }, b: { output: 'y' } };
+      expect(evaluateCondition('$a.output == "x" AND $b.output == "y"', outputs)).toBe(true);
+    });
+
+    it('evaluates AND compound: one false', () => {
+      const outputs = { a: { output: 'x' }, b: { output: 'z' } };
+      expect(evaluateCondition('$a.output == "x" AND $b.output == "y"', outputs)).toBe(false);
+    });
+
+    it('evaluates OR compound: one true', () => {
+      const outputs = { a: { output: 'x' }, b: { output: 'z' } };
+      expect(evaluateCondition('$a.output == "x" OR $b.output == "y"', outputs)).toBe(true);
+    });
+
+    it('evaluates OR compound: both false', () => {
+      const outputs = { a: { output: 'z' }, b: { output: 'z' } };
+      expect(evaluateCondition('$a.output == "x" OR $b.output == "y"', outputs)).toBe(false);
+    });
+
+    it('evaluates mixed AND/OR with correct precedence', () => {
+      const outputs = { a: { output: 'x' }, b: { output: 'y' }, c: { output: 'z' } };
+      // false AND true OR true => false OR true => true (AND binds tighter)
+      expect(evaluateCondition('$a.output == "wrong" AND $b.output == "y" OR $c.output == "z"', outputs)).toBe(true);
+    });
+  });
+
+  describe('parenthesized expressions', () => {
+    it('evaluates parenthesized expressions', () => {
+      const outputs = { a: { output: 'x' }, b: { output: 'y' } };
+      expect(evaluateCondition('($a.output == "x" OR $a.output == "z") AND $b.output == "y"', outputs)).toBe(true);
+    });
+  });
+
+  describe('error handling', () => {
+    it('throws ConditionError on invalid expressions', () => {
+      expect(() => evaluateCondition('!!!invalid', {})).toThrow(ConditionError);
+    });
+
+    it('throws ConditionError on missing node reference', () => {
+      expect(() => evaluateCondition('$missing.output == "x"', {})).toThrow(ConditionError);
+    });
+
+    it('throws ConditionError on node reference without field', () => {
+      expect(() => evaluateCondition('$analysis == "x"', {})).toThrow(ConditionError);
+    });
+
+    it('throws ConditionError on unterminated string', () => {
+      expect(() => evaluateCondition('"unterminated', {})).toThrow(ConditionError);
+    });
+  });
+
+  describe('whitespace handling', () => {
+    it('handles extra whitespace around operators', () => {
+      const outputs = { a: { output: 'x' } };
+      expect(evaluateCondition('  $a.output  ==  "x"  ', outputs)).toBe(true);
+    });
+  });
+
+  describe('quoted strings with special characters', () => {
+    it('handles double-quoted strings with spaces', () => {
+      const outputs = { msg: { output: 'hello world' } };
+      expect(evaluateCondition('$msg.output == "hello world"', outputs)).toBe(true);
+    });
+
+    it('handles single-quoted strings', () => {
+      const outputs = { msg: { output: 'hello' } };
+      expect(evaluateCondition("$msg.output == 'hello'", outputs)).toBe(true);
+    });
+  });
+
+  describe('empty condition', () => {
+    it('returns true for empty string', () => {
+      expect(evaluateCondition('', {})).toBe(true);
+    });
+
+    it('returns true for whitespace-only string', () => {
+      expect(evaluateCondition('   ', {})).toBe(true);
+    });
+  });
+});

packages/ion/src/engine/__tests__/output-ref.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect } from 'vitest';
+import {
+  resolveNodeOutputField,
+  declaredFieldsFromSchema,
+  OutputRefError,
+} from '../output-ref.js';
+
+describe('resolveNodeOutputField', () => {
+  describe('with declared schema match', () => {
+    it('returns value when field exists in output and schema', () => {
+      const declaredFields = new Set(['name', 'status']);
+      const output = { name: 'test-result', status: 'completed' };
+      const result = resolveNodeOutputField(output, 'node-1', 'name', declaredFields);
+      expect(result).toEqual({ kind: 'value', value: 'test-result' });
+    });
+
+    it('returns JSON-serialized value for non-string fields', () => {
+      const declaredFields = new Set(['count']);
+      const output = { count: 42 };
+      const result = resolveNodeOutputField(output, 'node-1', 'count', declaredFields);
+      expect(result).toEqual({ kind: 'value', value: '42' });
+    });
+
+    it('returns JSON-serialized value for object fields', () => {
+      const declaredFields = new Set(['data']);
+      const output = { data: { key: 'val' } };
+      const result = resolveNodeOutputField(output, 'node-1', 'data', declaredFields);
+      expect(result).toEqual({ kind: 'value', value: '{"key":"val"}' });
+    });
+  });
+
+  describe('with schemaless JSON output', () => {
+    it('returns value when field exists in output without schema', () => {
+      const output = { dynamic_field: 'hello' };
+      const result = resolveNodeOutputField(output, 'node-1', 'dynamic_field');
+      expect(result).toEqual({ kind: 'value', value: 'hello' });
+    });
+
+    it('returns JSON-serialized number without schema', () => {
+      const output = { score: 99 };
+      const result = resolveNodeOutputField(output, 'node-1', 'score');
+      expect(result).toEqual({ kind: 'value', value: '99' });
+    });
+  });
+
+  describe('missing optional field', () => {
+    it('returns empty when field is declared in schema but missing from output', () => {
+      const declaredFields = new Set(['name', 'optional_field']);
+      const output = { name: 'test' };
+      const result = resolveNodeOutputField(output, 'node-1', 'optional_field', declaredFields);
+      expect(result).toEqual({ kind: 'empty', value: '' });
+    });
+
+    it('returns empty when field exists but value is null', () => {
+      const declaredFields = new Set(['name']);
+      const output = { name: null };
+      const result = resolveNodeOutputField(output, 'node-1', 'name', declaredFields);
+      expect(result).toEqual({ kind: 'empty', value: '' });
+    });
+
+    it('returns empty when field exists but value is undefined', () => {
+      const declaredFields = new Set(['name']);
+      const output = { name: undefined };
+      const result = resolveNodeOutputField(output, 'node-1', 'name', declaredFields);
+      expect(result).toEqual({ kind: 'empty', value: '' });
+    });
+  });
+
+  describe('missing required field', () => {
+    it('throws OutputRefError when field is not declared and not in output', () => {
+      const output = { name: 'test' };
+      expect(() => resolveNodeOutputField(output, 'node-1', 'nonexistent')).toThrow(OutputRefError);
+    });
+
+    it('throws OutputRefError with nodeId and field info', () => {
+      const output = { name: 'test' };
+      try {
+        resolveNodeOutputField(output, 'my-node', 'missing_field');
+        expect.unreachable('Should have thrown');
+      } catch (err) {
+        expect(err).toBeInstanceOf(OutputRefError);
+        if (err instanceof OutputRefError) {
+          expect(err.nodeId).toBe('my-node');
+          expect(err.field).toBe('missing_field');
+        }
+      }
+    });
+
+    it('includes available fields in error message', () => {
+      const output = { name: 'test', status: 'ok' };
+      try {
+        resolveNodeOutputField(output, 'node-1', 'nonexistent');
+        expect.unreachable('Should have thrown');
+      } catch (err) {
+        expect(err).toBeInstanceOf(OutputRefError);
+        if (err instanceof OutputRefError) {
+          expect(err.message).toContain('name');
+          expect(err.message).toContain('status');
+        }
+      }
+    });
+  });
+});
+
+describe('declaredFieldsFromSchema', () => {
+  it('extracts fields from a valid JSON Schema object', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        count: { type: 'number' },
+      },
+    };
+    const fields = declaredFieldsFromSchema(schema);
+    expect(fields).toEqual(new Set(['name', 'count']));
+  });
+
+  it('returns empty set for undefined schema', () => {
+    const fields = declaredFieldsFromSchema(undefined);
+    expect(fields).toEqual(new Set());
+  });
+
+  it('returns empty set for string schema', () => {
+    const fields = declaredFieldsFromSchema('just a string description');
+    expect(fields).toEqual(new Set());
+  });
+
+  it('returns empty set for schema without properties', () => {
+    const fields = declaredFieldsFromSchema({ type: 'object' });
+    expect(fields).toEqual(new Set());
+  });
+});

packages/ion/src/engine/command-validation.ts

@@ -0,0 +1,27 @@
+/**
+ * Command name validation for the Ion workflow engine.
+ *
+ * Command names must be lowercase kebab-case: lowercase alphanumeric
+ * segments separated by single hyphens.
+ */
+
+/** Pattern for valid command names: lowercase kebab-case. */
+const COMMAND_NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+/**
+ * Validate a command name.
+ *
+ * Valid names match the pattern: `^[a-z0-9]+(-[a-z0-9]+)*$`
+ * - Lowercase alphanumeric segments
+ * - Segments separated by single hyphens
+ * - No leading or trailing hyphens
+ * - No consecutive hyphens
+ *
+ * @returns `true` if the name is valid, `false` otherwise.
+ */
+export function isValidCommandName(name: string): boolean {
+  if (name.length === 0) {
+    return false;
+  }
+  return COMMAND_NAME_PATTERN.test(name);
+}

packages/ion/src/engine/condition-evaluator.ts

@@ -0,0 +1,427 @@
+/**
+ * Condition evaluator for the Ion workflow engine.
+ *
+ * Parses and evaluates `when:` conditions that reference node outputs.
+ * Supports comparison operators, AND/OR compounds, and literal values.
+ *
+ * Grammar (informal):
+ *   condition    = orExpr
+ *   orExpr       = andExpr ( "OR" andExpr )*
+ *   andExpr      = comparison ( "AND" comparison )*
+ *   comparison   = value operator value
+ *   value        = nodeRef | literal
+ *   nodeRef      = "$" nodeId "." field
+ *   literal      = number | boolean | quotedString
+ *   operator     = "==" | "!=" | "<" | ">" | "<=" | ">="
+ */
+
+import { resolveNodeOutputField, OutputRefError } from './output-ref.js';
+
+// ---------------------------------------------------------------------------
+// Error type
+// ---------------------------------------------------------------------------
+
+export class ConditionError extends Error {
+  public readonly expression: string;
+
+  constructor(expression: string, message: string) {
+    super(`Condition evaluation error in "${expression}": ${message}`);
+    this.name = 'ConditionError';
+    this.expression = expression;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Token types
+// ---------------------------------------------------------------------------
+
+type TokenType =
+  | 'NODE_REF'   // $nodeId.field
+  | 'NUMBER'     // 42, 3.14
+  | 'BOOLEAN'    // true, false
+  | 'STRING'     // "hello" or 'hello'
+  | 'OPERATOR'   // ==, !=, <, >, <=, >=
+  | 'AND'        // AND keyword
+  | 'OR'         // OR keyword
+  | 'LPAREN'     // (
+  | 'RPAREN'     // )
+  | 'EOF';
+
+interface Token {
+  type: TokenType;
+  value: string;
+}
+
+// ---------------------------------------------------------------------------
+// Tokenizer
+// ---------------------------------------------------------------------------
+
+const OPERATORS = new Set(['==', '!=', '<=', '>=', '<', '>']);
+
+function tokenize(expression: string): Token[] {
+  const tokens: Token[] = [];
+  let pos = 0;
+
+  while (pos < expression.length) {
+    // Skip whitespace.
+    if (/\s/.test(expression[pos]!)) {
+      pos++;
+      continue;
+    }
+
+    // Parentheses.
+    if (expression[pos] === '(') {
+      tokens.push({ type: 'LPAREN', value: '(' });
+      pos++;
+      continue;
+    }
+    if (expression[pos] === ')') {
+      tokens.push({ type: 'RPAREN', value: ')' });
+      pos++;
+      continue;
+    }
+
+    // Node reference: $nodeId.field
+    if (expression[pos] === '$') {
+      const start = pos;
+      pos++; // skip $
+      let field = '';
+      // Read the nodeId (alphanumeric, underscores, hyphens).
+      while (pos < expression.length && /[\w-]/.test(expression[pos]!)) {
+        pos++;
+      }
+      const nodeId = expression.slice(start + 1, pos);
+      if (nodeId.length === 0) {
+        throw new ConditionError(expression, `Expected node identifier after $ at position ${start}`);
+      }
+      // Expect a dot then field name.
+      if (expression[pos] !== '.') {
+        throw new ConditionError(expression, `Expected "." after node reference $${nodeId} at position ${pos}`);
+      }
+      pos++; // skip dot
+      const fieldStart = pos;
+      while (pos < expression.length && /[\w-]/.test(expression[pos]!)) {
+        pos++;
+      }
+      field = expression.slice(fieldStart, pos);
+      if (field.length === 0) {
+        throw new ConditionError(expression, `Expected field name after $${nodeId}. at position ${fieldStart}`);
+      }
+      tokens.push({ type: 'NODE_REF', value: `${nodeId}.${field}` });
+      continue;
+    }
+
+    // Quoted string.
+    if (expression[pos] === '"' || expression[pos] === "'") {
+      const quote = expression[pos]!;
+      const start = pos;
+      pos++;
+      let str = '';
+      while (pos < expression.length && expression[pos] !== quote) {
+        if (expression[pos] === '\\' && pos + 1 < expression.length) {
+          pos++; // skip escape
+          str += expression[pos]!;
+        } else {
+          str += expression[pos]!;
+        }
+        pos++;
+      }
+      if (pos >= expression.length) {
+        throw new ConditionError(expression, `Unterminated string starting at position ${start}`);
+      }
+      pos++; // skip closing quote
+      tokens.push({ type: 'STRING', value: str });
+      continue;
+    }
+
+    // Two-character operators.
+    if (pos + 1 < expression.length) {
+      const twoChar = expression.slice(pos, pos + 2);
+      if (OPERATORS.has(twoChar)) {
+        tokens.push({ type: 'OPERATOR', value: twoChar });
+        pos += 2;
+        continue;
+      }
+    }
+
+    // Single-character operators.
+    const oneChar = expression[pos]!;
+    if (OPERATORS.has(oneChar)) {
+      tokens.push({ type: 'OPERATOR', value: oneChar });
+      pos++;
+      continue;
+    }
+
+    // AND / OR keywords.
+    const remaining = expression.slice(pos);
+    const andMatch = remaining.match(/^AND(?=\s|\(|$)/i);
+    if (andMatch) {
+      tokens.push({ type: 'AND', value: 'AND' });
+      pos += 3;
+      continue;
+    }
+    const orMatch = remaining.match(/^OR(?=\s|\(|$)/i);
+    if (orMatch) {
+      tokens.push({ type: 'OR', value: 'OR' });
+      pos += 2;
+      continue;
+    }
+
+    // Boolean literals.
+    const trueMatch = remaining.match(/^true(?=\s|\)|$)/i);
+    if (trueMatch) {
+      tokens.push({ type: 'BOOLEAN', value: 'true' });
+      pos += 4;
+      continue;
+    }
+    const falseMatch = remaining.match(/^false(?=\s|\)|$)/i);
+    if (falseMatch) {
+      tokens.push({ type: 'BOOLEAN', value: 'false' });
+      pos += 5;
+      continue;
+    }
+
+    // Number literal.
+    const numMatch = remaining.match(/^(-?\d+\.?\d*)/);
+    if (numMatch && numMatch[1] !== undefined) {
+      tokens.push({ type: 'NUMBER', value: numMatch[1] });
+      pos += numMatch[1].length;
+      continue;
+    }
+
+    throw new ConditionError(
+      expression,
+      `Unexpected character "${expression[pos]}" at position ${pos}`,
+    );
+  }
+
+  tokens.push({ type: 'EOF', value: '' });
+  return tokens;
+}
+
+// ---------------------------------------------------------------------------
+// Parser (recursive descent)
+// ---------------------------------------------------------------------------
+
+class ConditionParser {
+  private pos = 0;
+
+  constructor(
+    private tokens: Token[],
+    private expression: string,
+    private nodeOutputs: Record<string, Record<string, unknown>>,
+  ) {}
+
+  parse(): boolean {
+    const result = this.parseOr();
+    if (this.tokens[this.pos]!.type !== 'EOF') {
+      throw new ConditionError(
+        this.expression,
+        `Unexpected token "${this.tokens[this.pos]!.value}" after expression`,
+      );
+    }
+    return result;
+  }
+
+  // orExpr = andExpr ( "OR" andExpr )*
+  private parseOr(): boolean {
+    let result = this.parseAnd();
+    while (this.tokens[this.pos]!.type === 'OR') {
+      this.pos++; // consume OR
+      const right = this.parseAnd();
+      result = result || right;
+    }
+    return result;
+  }
+
+  // andExpr = comparison ( "AND" comparison )*
+  private parseAnd(): boolean {
+    let result = this.parseComparison();
+    while (this.tokens[this.pos]!.type === 'AND') {
+      this.pos++; // consume AND
+      const right = this.parseComparison();
+      result = result && right;
+    }
+    return result;
+  }
+
+  // comparison = value operator value | "(" orExpr ")"
+  private parseComparison(): boolean {
+    // Parenthesized expression.
+    if (this.tokens[this.pos]!.type === 'LPAREN') {
+      this.pos++; // consume (
+      const result = this.parseOr();
+      if (this.tokens[this.pos]!.type !== 'RPAREN') {
+        throw new ConditionError(this.expression, 'Expected closing ")"');
+      }
+      this.pos++; // consume )
+      return result;
+    }
+
+    // value operator value
+    const left = this.resolveValue();
+    const opToken = this.tokens[this.pos]!;
+
+    if (opToken.type !== 'OPERATOR') {
+      throw new ConditionError(
+        this.expression,
+        `Expected comparison operator, got "${opToken.value}" (${opToken.type})`,
+      );
+    }
+
+    this.pos++; // consume operator
+    const right = this.resolveValue();
+
+    return this.compare(left, opToken.value, right);
+  }
+
+  private resolveValue(): string | number | boolean {
+    const token = this.tokens[this.pos]!;
+
+    switch (token.type) {
+      case 'NODE_REF': {
+        this.pos++;
+        const dotIndex = token.value.indexOf('.');
+        if (dotIndex === -1) {
+          throw new ConditionError(
+            this.expression,
+            `Invalid node reference: ${token.value}`,
+          );
+        }
+        const nodeId = token.value.slice(0, dotIndex);
+        const field = token.value.slice(dotIndex + 1);
+
+        const output = this.nodeOutputs[nodeId];
+        if (!output) {
+          throw new ConditionError(
+            this.expression,
+            `Node "${nodeId}" has no output available. Available nodes: ${Object.keys(this.nodeOutputs).join(', ') || '(none)'}`,
+          );
+        }
+
+        try {
+          const result = resolveNodeOutputField(output, nodeId, field);
+          // For comparison, we need the raw value, not the stringified version.
+          const rawValue = output[field];
+          if (typeof rawValue === 'number') return rawValue;
+          if (typeof rawValue === 'boolean') return rawValue;
+          return result.value;
+        } catch (err) {
+          if (err instanceof OutputRefError) {
+            throw new ConditionError(this.expression, err.message);
+          }
+          throw err;
+        }
+      }
+
+      case 'NUMBER': {
+        this.pos++;
+        const num = Number(token.value);
+        if (Number.isNaN(num)) {
+          throw new ConditionError(
+            this.expression,
+            `Invalid number literal: ${token.value}`,
+          );
+        }
+        return num;
+      }
+
+      case 'BOOLEAN': {
+        this.pos++;
+        return token.value.toLowerCase() === 'true';
+      }
+
+      case 'STRING': {
+        this.pos++;
+        return token.value;
+      }
+
+      default:
+        throw new ConditionError(
+          this.expression,
+          `Expected value (node reference, number, boolean, or string), got "${token.value}" (${token.type})`,
+        );
+    }
+  }
+
+  private compare(
+    left: string | number | boolean,
+    op: string,
+    right: string | number | boolean,
+  ): boolean {
+    // Coerce types for comparison.
+    const leftNum = typeof left === 'number' ? left : Number(left);
+    const rightNum = typeof right === 'number' ? right : Number(right);
+
+    switch (op) {
+      case '==':
+        return left === right;
+      case '!=':
+        return left !== right;
+      case '<':
+        if (!Number.isNaN(leftNum) && !Number.isNaN(rightNum)) {
+          return leftNum < rightNum;
+        }
+        return String(left) < String(right);
+      case '>':
+        if (!Number.isNaN(leftNum) && !Number.isNaN(rightNum)) {
+          return leftNum > rightNum;
+        }
+        return String(left) > String(right);
+      case '<=':
+        if (!Number.isNaN(leftNum) && !Number.isNaN(rightNum)) {
+          return leftNum <= rightNum;
+        }
+        return String(left) <= String(right);
+      case '>=':
+        if (!Number.isNaN(leftNum) && !Number.isNaN(rightNum)) {
+          return leftNum >= rightNum;
+        }
+        return String(left) >= String(right);
+      default:
+        throw new ConditionError(this.expression, `Unknown operator: ${op}`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluate a `when:` condition expression against node outputs.
+ *
+ * Supports:
+ * - Node output references: `$nodeId.field`
+ * - Comparison operators: `==`, `!=`, `<`, `>`, `<=`, `>=`
+ * - Logical compounds: `AND`, `OR`
+ * - Parenthesized sub-expressions
+ * - Literal values: numbers, booleans, quoted strings
+ *
+ * Returns `true` or `false`. Throws `ConditionError` on parse failure (fail-closed).
+ */
+export function evaluateCondition(
+  expression: string,
+  nodeOutputs: Record<string, Record<string, unknown>>,
+): boolean {
+  if (!expression || expression.trim().length === 0) {
+    // Empty condition is always true (no guard = proceed).
+    return true;
+  }
+
+  const trimmed = expression.trim();
+  const tokens = tokenize(trimmed);
+  const parser = new ConditionParser(tokens, trimmed, nodeOutputs);
+
+  try {
+    return parser.parse();
+  } catch (err) {
+    if (err instanceof ConditionError) {
+      throw err;
+    }
+    throw new ConditionError(
+      trimmed,
+      `Unexpected error: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}

packages/ion/src/engine/deps.ts

@@ -0,0 +1,199 @@
+/**
+ * Dependency injection interfaces for the Ion workflow engine.
+ *
+ * These interfaces define the contracts that the engine requires from its
+ * runtime environment. Concrete implementations are provided by the
+ * platform layer (CLI, server, etc.).
+ */
+
+// ---------------------------------------------------------------------------
+// Workflow platform — messaging back to the conversation channel
+// ---------------------------------------------------------------------------
+
+export interface IWorkflowPlatform {
+  /** Send a text message to the conversation channel. */
+  sendMessage(
+    conversationId: string,
+    message: string,
+    metadata?: Record<string, unknown>,
+  ): Promise<void>;
+
+  /** Whether the platform supports streaming responses. */
+  getStreamingMode(): boolean;
+
+  /** Optional structured event emission (e.g. approval requests). */
+  sendStructuredEvent?(
+    conversationId: string,
+    event: Record<string, unknown>,
+  ): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Workflow configuration — per-workflow settings
+// ---------------------------------------------------------------------------
+
+/** Configuration for a single AI provider. */
+export interface ProviderConfig {
+  /** Provider identifier (e.g. "openai", "anthropic"). */
+  provider: string;
+  /** Model name (e.g. "gpt-4o", "claude-sonnet-4-20250514"). */
+  model?: string;
+  /** Additional provider-specific options. */
+  options?: Record<string, unknown>;
+}
+
+/** Folder-level command configuration. */
+export interface CommandFolderConfig {
+  /** Path to the commands folder. */
+  path: string;
+  /** Whether commands are enabled by default. */
+  enabled?: boolean;
+}
+
+export interface WorkflowConfig {
+  /** Default assistant identifier. */
+  assistant: string;
+  /** Named provider configurations keyed by provider id. */
+  assistants: Record<string, ProviderConfig>;
+  /** Environment variables available to the workflow. */
+  envVars: Record<string, string>;
+  /** Command folder configuration. */
+  commands: CommandFolderConfig;
+  /** Base git branch for the workflow (optional). */
+  baseBranch?: string;
+  /** Path to documentation directory (optional). */
+  docsPath?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Workflow store — persistence interface (will move to store/ later)
+// ---------------------------------------------------------------------------
+
+/** Minimal data required to create a workflow run. */
+export interface CreateWorkflowRunData {
+  workflowPath: string;
+  workflowName: string;
+  trigger: string;
+  input: Record<string, unknown>;
+}
+
+/** Status of a workflow run. */
+export type WorkflowRunStatus =
+  | 'pending'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'cancelled';
+
+/** A persisted workflow run record. */
+export interface WorkflowRun {
+  id: string;
+  workflowPath: string;
+  workflowName: string;
+  status: WorkflowRunStatus;
+  trigger: string;
+  input: Record<string, unknown>;
+  output?: Record<string, unknown>;
+  error?: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/** A single event within a workflow run (node start/complete/etc.). */
+export interface WorkflowEvent {
+  id: string;
+  runId: string;
+  nodeId?: string;
+  type: string;
+  data: Record<string, unknown>;
+  createdAt: Date;
+}
+
+export interface IWorkflowStore {
+  // -- Run lifecycle -------------------------------------------------------
+
+  /** Create a new workflow run. */
+  createWorkflowRun(data: CreateWorkflowRunData): Promise<WorkflowRun>;
+
+  /** Retrieve a workflow run by id. */
+  getWorkflowRun(id: string): Promise<WorkflowRun | null>;
+
+  /** Update a workflow run. */
+  updateWorkflowRun(
+    id: string,
+    data: Partial<WorkflowRun>,
+  ): Promise<WorkflowRun>;
+
+  /** Mark a workflow run as failed. */
+  failWorkflowRun(id: string, error: string): Promise<WorkflowRun>;
+
+  /** Get the current status of a workflow run. */
+  getWorkflowRunStatus(id: string): Promise<WorkflowRunStatus | null>;
+
+  // -- Events --------------------------------------------------------------
+
+  /** Record a workflow event. */
+  createWorkflowEvent(event: Omit<WorkflowEvent, 'id' | 'createdAt'>): Promise<WorkflowEvent>;
+
+  /** Get completed DAG node outputs for a run. */
+  getCompletedDagNodeOutputs(
+    runId: string,
+  ): Promise<Record<string, Record<string, unknown>>>;
+
+  // -- Active runs ---------------------------------------------------------
+
+  /** Find an active (non-terminal) run for a given workflow path. */
+  getActiveWorkflowRunByPath(
+    path: string,
+    opts?: { excludeId?: string },
+  ): Promise<WorkflowRun | null>;
+
+  // -- Codebase ------------------------------------------------------------
+
+  /** Get a codebase record by id. */
+  getCodebase(id: string): Promise<Record<string, unknown> | null>;
+
+  /** Get environment variables for a codebase. */
+  getCodebaseEnvVars(id: string): Promise<Record<string, string>>;
+
+  // -- Resumption ----------------------------------------------------------
+
+  /** Resume a paused workflow run. */
+  resumeWorkflowRun(id: string): Promise<WorkflowRun>;
+}
+
+// ---------------------------------------------------------------------------
+// Agent provider — creates AI agent instances
+// ---------------------------------------------------------------------------
+
+export interface IAgentProvider {
+  /** Provider identifier. */
+  readonly providerId: string;
+
+  /** Send a prompt and return the response. */
+  sendPrompt(prompt: string, options?: Record<string, unknown>): Promise<string>;
+}
+
+// ---------------------------------------------------------------------------
+// Workflow dependencies — the full DI container
+// ---------------------------------------------------------------------------
+
+export interface WorkflowDeps {
+  /** Persistence store. */
+  store: IWorkflowStore;
+
+  /** Load workflow config from a working directory. */
+  loadConfig(cwd: string): Promise<WorkflowConfig>;
+
+  /** Get an agent provider by its provider id. */
+  getAgentProvider(providerId: string): IAgentProvider;
+
+  /** Resolve a bot-level GitHub token (optional). */
+  resolveBotGitHubToken?(): Promise<string | undefined>;
+
+  /** Get the user-level GitHub token (optional). */
+  getUserGithubToken?(): Promise<string | undefined>;
+
+  /** Whether per-user GitHub token resolution is enabled (optional). */
+  isPerUserGitHubEnabled?(): boolean;
+}

packages/ion/src/engine/event-emitter.ts

@@ -0,0 +1,214 @@
+/**
+ * Typed event emitter for the Ion workflow engine.
+ *
+ * Provides a singleton event bus for workflow lifecycle events.
+ * Supports both global and run-scoped subscriptions.
+ */
+
+// ---------------------------------------------------------------------------
+// Event types
+// ---------------------------------------------------------------------------
+
+export type WorkflowEventType =
+  | 'workflow_started'
+  | 'workflow_completed'
+  | 'workflow_failed'
+  | 'workflow_cancelled'
+  | 'node_started'
+  | 'node_completed'
+  | 'node_failed'
+  | 'node_skipped'
+  | 'loop_iteration_started'
+  | 'loop_iteration_completed'
+  | 'approval_pending';
+
+// ---------------------------------------------------------------------------
+// Event shapes
+// ---------------------------------------------------------------------------
+
+export interface WorkflowEventBase {
+  /** Discriminator for the event type. */
+  type: WorkflowEventType;
+  /** The workflow run id. */
+  runId: string;
+  /** The node id (when applicable). */
+  nodeId?: string;
+  /** The workflow name. */
+  workflowName?: string;
+  /** Error message (for failure events). */
+  error?: string;
+  /** Human-readable step name. */
+  stepName?: string;
+  /** Arbitrary metadata attached to the event. */
+  metadata?: Record<string, unknown>;
+}
+
+/** Specific shapes for strongly-typed event handling. */
+export interface WorkflowStartedEvent extends WorkflowEventBase {
+  type: 'workflow_started';
+  workflowName: string;
+}
+
+export interface WorkflowCompletedEvent extends WorkflowEventBase {
+  type: 'workflow_completed';
+  workflowName: string;
+}
+
+export interface WorkflowFailedEvent extends WorkflowEventBase {
+  type: 'workflow_failed';
+  error: string;
+}
+
+export interface WorkflowCancelledEvent extends WorkflowEventBase {
+  type: 'workflow_cancelled';
+}
+
+export interface NodeStartedEvent extends WorkflowEventBase {
+  type: 'node_started';
+  nodeId: string;
+  stepName?: string;
+}
+
+export interface NodeCompletedEvent extends WorkflowEventBase {
+  type: 'node_completed';
+  nodeId: string;
+  stepName?: string;
+}
+
+export interface NodeFailedEvent extends WorkflowEventBase {
+  type: 'node_failed';
+  nodeId: string;
+  error: string;
+}
+
+export interface NodeSkippedEvent extends WorkflowEventBase {
+  type: 'node_skipped';
+  nodeId: string;
+  stepName?: string;
+}
+
+export interface LoopIterationStartedEvent extends WorkflowEventBase {
+  type: 'loop_iteration_started';
+  nodeId: string;
+  metadata?: { iteration: number };
+}
+
+export interface LoopIterationCompletedEvent extends WorkflowEventBase {
+  type: 'loop_iteration_completed';
+  nodeId: string;
+  metadata?: { iteration: number };
+}
+
+export interface ApprovalPendingEvent extends WorkflowEventBase {
+  type: 'approval_pending';
+  nodeId: string;
+  metadata?: { approver?: string; reason?: string };
+}
+
+export type WorkflowEvent =
+  | WorkflowStartedEvent
+  | WorkflowCompletedEvent
+  | WorkflowFailedEvent
+  | WorkflowCancelledEvent
+  | NodeStartedEvent
+  | NodeCompletedEvent
+  | NodeFailedEvent
+  | NodeSkippedEvent
+  | LoopIterationStartedEvent
+  | LoopIterationCompletedEvent
+  | ApprovalPendingEvent;
+
+// ---------------------------------------------------------------------------
+// Event handler type
+// ---------------------------------------------------------------------------
+
+export type WorkflowEventHandler = (event: WorkflowEvent) => void;
+
+// ---------------------------------------------------------------------------
+// WorkflowEventEmitter — singleton event bus
+// ---------------------------------------------------------------------------
+
+export class WorkflowEventEmitter {
+  private listeners: Set<WorkflowEventHandler> = new Set();
+  private runListeners: Map<string, Set<WorkflowEventHandler>> = new Map();
+
+  /** Subscribe to all workflow events. */
+  subscribe(handler: WorkflowEventHandler): () => void {
+    this.listeners.add(handler);
+    return () => {
+      this.listeners.delete(handler);
+    };
+  }
+
+  /** Unsubscribe a handler from all events. */
+  unsubscribe(handler: WorkflowEventHandler): void {
+    this.listeners.delete(handler);
+  }
+
+  /** Emit an event to all subscribers (global + run-scoped). */
+  emit(event: WorkflowEvent): void {
+    for (const handler of this.listeners) {
+      try {
+        handler(event);
+      } catch {
+        // Swallow handler errors to prevent cascading failures.
+      }
+    }
+
+    // Also notify run-scoped listeners.
+    const runHandlers = this.runListeners.get(event.runId);
+    if (runHandlers) {
+      for (const handler of runHandlers) {
+        try {
+          handler(event);
+        } catch {
+          // Swallow handler errors to prevent cascading failures.
+        }
+      }
+    }
+  }
+
+  /** Remove all global listeners and run-scoped listeners. */
+  clear(): void {
+    this.listeners.clear();
+    this.runListeners.clear();
+  }
+
+  // -- Run-scoped subscriptions ------------------------------------------------
+
+  /** Register a run-scoped event listener. */
+  registerRun(runId: string, handler: WorkflowEventHandler): () => void {
+    let handlers = this.runListeners.get(runId);
+    if (!handlers) {
+      handlers = new Set();
+      this.runListeners.set(runId, handlers);
+    }
+    handlers.add(handler);
+
+    return () => {
+      handlers!.delete(handler);
+      if (handlers!.size === 0) {
+        this.runListeners.delete(runId);
+      }
+    };
+  }
+
+  /** Unregister all listeners for a specific run. */
+  unregisterRun(runId: string): void {
+    this.runListeners.delete(runId);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Singleton factory
+// ---------------------------------------------------------------------------
+
+let instance: WorkflowEventEmitter | undefined;
+
+/** Get the singleton WorkflowEventEmitter instance. */
+export function getWorkflowEventEmitter(): WorkflowEventEmitter {
+  if (!instance) {
+    instance = new WorkflowEventEmitter();
+  }
+  return instance;
+}

packages/ion/src/engine/executor-shared.ts

@@ -0,0 +1,251 @@
+/**
+ * Shared executor utilities for the Ion workflow engine.
+ *
+ * Pure functions for variable substitution, error classification,
+ * message helpers, and completion signal detection.
+ */
+
+import type { IWorkflowPlatform } from './deps.js';
+
+// ---------------------------------------------------------------------------
+// Variable substitution
+// ---------------------------------------------------------------------------
+
+/** Well-known workflow variable names. */
+const WORKFLOW_VARIABLES = [
+  '$WORKFLOW_ID',
+  '$USER_MESSAGE',
+  '$ARGUMENTS',
+  '$ARTIFACTS_DIR',
+  '$BASE_BRANCH',
+  '$DOCS_DIR',
+  '$CONTEXT',
+  '$EXTERNAL_CONTEXT',
+  '$LOOP_USER_INPUT',
+  '$REJECTION_REASON',
+] as const;
+
+export type WorkflowVariableName = (typeof WORKFLOW_VARIABLES)[number];
+
+/** Context object providing values for workflow variable substitution. */
+export interface VariableContext {
+  WORKFLOW_ID?: string;
+  USER_MESSAGE?: string;
+  ARGUMENTS?: string;
+  ARTIFACTS_DIR?: string;
+  BASE_BRANCH?: string;
+  DOCS_DIR?: string;
+  CONTEXT?: string;
+  EXTERNAL_CONTEXT?: string;
+  LOOP_USER_INPUT?: string;
+  REJECTION_REASON?: string;
+}
+
+/**
+ * Substitute workflow variables in a string.
+ *
+ * Replaces known `$VARIABLE` tokens with values from the context.
+ * Unknown `$VARIABLE` tokens are left as-is (not removed).
+ */
+export function substituteWorkflowVariables(
+  template: string,
+  context: VariableContext,
+): string {
+  let result = template;
+
+  // Map variable names to their context keys.
+  const mapping: Record<string, string | undefined> = {
+    $WORKFLOW_ID: context.WORKFLOW_ID,
+    $USER_MESSAGE: context.USER_MESSAGE,
+    $ARGUMENTS: context.ARGUMENTS,
+    $ARTIFACTS_DIR: context.ARTIFACTS_DIR,
+    $BASE_BRANCH: context.BASE_BRANCH,
+    $DOCS_DIR: context.DOCS_DIR,
+    $CONTEXT: context.CONTEXT,
+    $EXTERNAL_CONTEXT: context.EXTERNAL_CONTEXT,
+    $LOOP_USER_INPUT: context.LOOP_USER_INPUT,
+    $REJECTION_REASON: context.REJECTION_REASON,
+  };
+
+  for (const [variable, value] of Object.entries(mapping)) {
+    if (value !== undefined) {
+      // Replace all occurrences of the variable.
+      result = result.split(variable).join(value);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Build a prompt by substituting workflow variables and appending
+ * issue context if provided.
+ */
+export function buildPromptWithContext(
+  template: string,
+  context: VariableContext,
+  issueContext?: string,
+): string {
+  let prompt = substituteWorkflowVariables(template, context);
+
+  if (issueContext && issueContext.length > 0) {
+    prompt += `\n\n---\nIssue Context:\n${issueContext}`;
+  }
+
+  return prompt;
+}
+
+// ---------------------------------------------------------------------------
+// Error classification
+// ---------------------------------------------------------------------------
+
+export type ErrorClassification = 'FATAL' | 'TRANSIENT' | 'UNKNOWN';
+
+/** Patterns that indicate a fatal (non-retryable) error. */
+const FATAL_PATTERNS: readonly RegExp[] = [
+  /auth(?:entication|orization)?\s*(?:fail|error|denied|invalid)/i,
+  /permission\s*(?:denied|error|fail)/i,
+  /insufficient\s*(?:credit|quota|permission)/i,
+  /api\s*key\s*(?:invalid|expired|missing)/i,
+  /forbidden/i,
+  /unauthorized/i,
+  /account\s*(?:suspended|disabled|deactivated)/i,
+];
+
+/** Patterns that indicate a transient (retryable) error. */
+const TRANSIENT_PATTERNS: readonly RegExp[] = [
+  /timeout/i,
+  /timed?\s*out/i,
+  /network\s*(?:error|fail|unreachable)/i,
+  /connection\s*(?:reset|refused|dropped|lost)/i,
+  /econnreset/i,
+  /econnrefused/i,
+  /rate\s*limit/i,
+  /too\s*many\s*requests/i,
+  /service\s*(?:unavailable|temporarily\s*unavailable)/i,
+  /503/i,
+  /502/i,
+  /retry/i,
+];
+
+/**
+ * Classify an error as FATAL, TRANSIENT, or UNKNOWN based on its message.
+ *
+ * FATAL errors should not be retried (auth, permission, credit issues).
+ * TRANSIENT errors may succeed on retry (network, timeout, rate limit).
+ * UNKNOWN errors have no recognized pattern.
+ */
+export function classifyError(error: Error | string): ErrorClassification {
+  const message = typeof error === 'string' ? error : error.message;
+
+  for (const pattern of FATAL_PATTERNS) {
+    if (pattern.test(message)) {
+      return 'FATAL';
+    }
+  }
+
+  for (const pattern of TRANSIENT_PATTERNS) {
+    if (pattern.test(message)) {
+      return 'TRANSIENT';
+    }
+  }
+
+  return 'UNKNOWN';
+}
+
+// ---------------------------------------------------------------------------
+// Platform message helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Safely send a message via the platform interface.
+ *
+ * Returns `true` if the message was sent successfully, `false` otherwise.
+ * Logs failures but does not throw.
+ */
+export async function safeSendMessage(
+  platform: IWorkflowPlatform,
+  conversationId: string,
+  message: string,
+  metadata?: Record<string, unknown>,
+): Promise<boolean> {
+  try {
+    await platform.sendMessage(conversationId, message, metadata);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Completion signal detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect whether an output contains the expected completion signal.
+ *
+ * The `until` string is the marker that signals the node has finished
+ * producing its output. Returns `true` if the marker is found.
+ */
+export function detectCompletionSignal(
+  output: string,
+  until: string,
+): boolean {
+  if (!until || until.length === 0) {
+    // No completion marker configured — always consider complete.
+    return true;
+  }
+  return output.includes(until);
+}
+
+/**
+ * Strip the completion marker from the output.
+ *
+ * Removes the `until` string from the output if present.
+ * Does not trim or modify whitespace beyond removing the marker.
+ */
+export function stripCompletionTags(output: string, until: string): string {
+  if (!until || until.length === 0) {
+    return output;
+  }
+  return output.split(until).join('');
+}
+
+// ---------------------------------------------------------------------------
+// Subprocess failure formatting
+// ---------------------------------------------------------------------------
+
+export interface SubprocessFailure {
+  exitCode: number | null;
+  stderr: string;
+  command?: string;
+}
+
+/**
+ * Format a subprocess failure into a human-readable error string.
+ *
+ * Includes the command (if provided), exit code, and stderr output.
+ */
+export function formatSubprocessFailure(failure: SubprocessFailure): string {
+  const parts: string[] = [];
+
+  if (failure.command) {
+    parts.push(`Command: ${failure.command}`);
+  }
+
+  if (failure.exitCode !== null) {
+    parts.push(`Exit code: ${failure.exitCode}`);
+  }
+
+  if (failure.stderr && failure.stderr.length > 0) {
+    // Truncate very long stderr to keep error messages manageable.
+    const maxStderr = 2048;
+    const stderr =
+      failure.stderr.length > maxStderr
+        ? failure.stderr.slice(0, maxStderr) + '... (truncated)'
+        : failure.stderr;
+    parts.push(`Stderr:\n${stderr}`);
+  }
+
+  return parts.length > 0 ? parts.join('\n') : 'Subprocess failed with no details';
+}

packages/ion/src/engine/executor.ts

@@ -0,0 +1,373 @@
+/**
+ * Top-level workflow executor for the Ion engine.
+ *
+ * Orchestrates the full lifecycle of a workflow run:
+ * - Load configuration and resolve provider/model
+ * - Create or resume a WorkflowRun
+ * - Path-lock guard (prevent concurrent runs on the same working path)
+ * - Pre-create artifacts directory
+ * - Delegate to executeDagWorkflow for DAG traversal
+ * - Update run status on completion/failure
+ * - Emit events and notify the user
+ */
+
+import { mkdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+import type { WorkflowDefinition } from '../schema/index.js';
+import type {
+  IWorkflowPlatform,
+  IWorkflowStore,
+  WorkflowDeps,
+  WorkflowConfig,
+  WorkflowRun,
+  CreateWorkflowRunData,
+} from './deps.js';
+import { executeDagWorkflow, type DagWorkflowResult } from './dag-executor.js';
+import { safeSendMessage } from './utils.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Options for workflow execution. */
+export interface WorkflowExecutionOptions {
+  /** Whether to resume a previously failed/paused run. */
+  resume?: boolean;
+  /** Additional input variables for the workflow. */
+  input?: Record<string, unknown>;
+  /** Override the provider id. */
+  provider?: string;
+  /** Override the model. */
+  model?: string;
+  /** Codebase id for scoped paths. */
+  codebaseId?: string;
+}
+
+/** Result of a workflow execution. */
+export interface WorkflowExecutionResult {
+  /** The workflow run record. */
+  run: WorkflowRun;
+  /** The DAG execution result. */
+  dagResult?: DagWorkflowResult;
+  /** Whether the execution was successful. */
+  success: boolean;
+  /** Error message if execution failed. */
+  error?: string;
+}
+
+/** Hydrated resumable run data. */
+export interface HydratedResumableRun {
+  /** The pre-created or resumed workflow run. */
+  preCreatedRun: WorkflowRun;
+  /** Prior completed node outputs from the previous run. */
+  priorCompletedNodes: Record<string, Record<string, unknown>>;
+}
+
+/** Resolved project paths for a workflow run. */
+export interface ProjectPaths {
+  /** Directory for workflow artifacts. */
+  artifactsDir: string;
+  /** Directory for workflow logs. */
+  logDir: string;
+}
+
+// ---------------------------------------------------------------------------
+// Main executor
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a workflow from start to finish.
+ *
+ * This is the primary entry point for running a workflow. It handles:
+ * 1. Loading configuration
+ * 2. Resolving provider and model
+ * 3. Creating or resuming a WorkflowRun
+ * 4. Path-lock guard
+ * 5. Pre-creating the artifacts directory
+ * 6. Delegating to executeDagWorkflow
+ * 7. Updating run status on completion/failure
+ *
+ * @param deps - Dependency injection container.
+ * @param platform - Platform interface for messaging.
+ * @param conversationId - Conversation channel id.
+ * @param cwd - Working directory for the workflow.
+ * @param workflow - The workflow definition.
+ * @param userMessage - The triggering user message (stored as input).
+ * @param opts - Execution options.
+ * @returns WorkflowExecutionResult with run, dag result, and success status.
+ */
+export async function executeWorkflow(
+  deps: WorkflowDeps,
+  platform: IWorkflowPlatform,
+  conversationId: string,
+  cwd: string,
+  workflow: WorkflowDefinition,
+  userMessage: string,
+  opts: WorkflowExecutionOptions = {},
+): Promise<WorkflowExecutionResult> {
+  // 1. Load configuration
+  let config: WorkflowConfig;
+  try {
+    config = await deps.loadConfig(cwd);
+  } catch (err) {
+    return {
+      run: createFailedRun(workflow, err),
+      success: false,
+      error: `Failed to load configuration: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  // 2. Resolve provider and model
+  const providerId = opts.provider ?? workflow.provider ?? config.assistant;
+  const model = opts.model ?? workflow.model ?? config.assistants[providerId]?.model;
+
+  // 3. Create or resume a workflow run
+  let workflowRun: WorkflowRun;
+  let priorCompletedNodes: Record<string, Record<string, unknown>> | undefined;
+
+  if (opts.resume) {
+    // Try to find an existing run to resume
+    const existingRun = await deps.store.getActiveWorkflowRunByPath(workflow.name);
+    if (existingRun) {
+      const hydrated = await hydrateResumableRun(deps, existingRun);
+      workflowRun = hydrated.preCreatedRun;
+      priorCompletedNodes = hydrated.priorCompletedNodes;
+    } else {
+      // No existing run — create a new one
+      workflowRun = await createNewRun(deps, workflow, userMessage, opts);
+    }
+  } else {
+    // 4. Path-lock guard: check no other run is active
+    const activeRun = await deps.store.getActiveWorkflowRunByPath(workflow.name);
+    if (activeRun) {
+      const errorMsg = `Workflow "${workflow.name}" already has an active run (${activeRun.id}). Wait for it to complete or cancel it first.`;
+      await safeSendMessage(platform, conversationId, `❌ ${errorMsg}`);
+      return {
+        run: createFailedRun(workflow, new Error(errorMsg)),
+        success: false,
+        error: errorMsg,
+      };
+    }
+
+    workflowRun = await createNewRun(deps, workflow, userMessage, opts);
+  }
+
+  // 5. Pre-create artifacts directory
+  const paths = resolveProjectPaths(deps, cwd, workflowRun.id, opts.codebaseId);
+  try {
+    await mkdir(paths.artifactsDir, { recursive: true });
+    await mkdir(paths.logDir, { recursive: true });
+  } catch (err) {
+    // Artifacts dir creation is best-effort
+  }
+
+  // 6. Set status to running
+  try {
+    workflowRun = await deps.store.updateWorkflowRun(workflowRun.id, {
+      status: 'running',
+    });
+  } catch (err) {
+    return {
+      run: workflowRun,
+      success: false,
+      error: `Failed to set workflow run status to running: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  // 7. Notify user
+  await safeSendMessage(
+    platform,
+    conversationId,
+    `🚀 Starting workflow "${workflow.name}" (run ${workflowRun.id})`,
+  );
+
+  // 8. Execute the DAG
+  let dagResult: DagWorkflowResult | undefined;
+  try {
+    dagResult = await executeDagWorkflow(
+      deps,
+      platform,
+      conversationId,
+      cwd,
+      workflow,
+      workflowRun,
+      priorCompletedNodes,
+    );
+
+    // 9. Update run status on completion
+    if (dagResult.success) {
+      workflowRun = await deps.store.updateWorkflowRun(workflowRun.id, {
+        status: 'completed',
+        output: Object.fromEntries(dagResult.nodeOutputs),
+      });
+
+      await safeSendMessage(
+        platform,
+        conversationId,
+        `✅ Workflow "${workflow.name}" completed successfully\n${dagResult.summary}`,
+      );
+    } else {
+      workflowRun = await deps.store.failWorkflowRun(
+        workflowRun.id,
+        dagResult.error ?? 'Workflow failed',
+      );
+
+      await safeSendMessage(
+        platform,
+        conversationId,
+        `❌ Workflow "${workflow.name}" failed: ${dagResult.error}`,
+      );
+    }
+
+    return {
+      run: workflowRun,
+      dagResult,
+      success: dagResult.success,
+      error: dagResult.error,
+    };
+  } catch (err) {
+    // Unhandled error — update DB and notify
+    const errorMsg = err instanceof Error ? err.message : String(err);
+
+    try {
+      workflowRun = await deps.store.failWorkflowRun(workflowRun.id, errorMsg);
+    } catch {
+      // Best-effort DB update
+    }
+
+    await safeSendMessage(
+      platform,
+      conversationId,
+      `❌ Workflow "${workflow.name}" failed with error: ${errorMsg}`,
+    );
+
+    // Emit error event
+    try {
+      await deps.store.createWorkflowEvent({
+        runId: workflowRun.id,
+        type: 'workflow_failed',
+        data: { error: errorMsg },
+      });
+    } catch {
+      // Best-effort event emission
+    }
+
+    return {
+      run: workflowRun,
+      success: false,
+      error: errorMsg,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Resume support
+// ---------------------------------------------------------------------------
+
+/**
+ * Hydrate a resumable workflow run.
+ *
+ * Loads completed node outputs from the previous run and sets the
+ * run status back to 'running' so execution can continue.
+ *
+ * @param deps - Dependency injection container.
+ * @param candidate - The existing workflow run to resume.
+ * @returns Hydrated run with prior completed nodes.
+ */
+export async function hydrateResumableRun(
+  deps: WorkflowDeps,
+  candidate: WorkflowRun,
+): Promise<HydratedResumableRun> {
+  // Load completed node outputs from the previous run
+  const priorCompletedNodes = await deps.store.getCompletedDagNodeOutputs(candidate.id);
+
+  // Resume the workflow run (set status back to 'running')
+  const preCreatedRun = await deps.store.resumeWorkflowRun(candidate.id);
+
+  return {
+    preCreatedRun,
+    priorCompletedNodes,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Project paths
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve project paths for a workflow run.
+ *
+ * Uses codebase-scoped paths if a codebaseId is provided,
+ * otherwise falls back to cwd-based paths.
+ *
+ * @param deps - Dependency injection container.
+ * @param cwd - Working directory.
+ * @param workflowRunId - The workflow run id.
+ * @param codebaseId - Optional codebase id for scoped paths.
+ * @returns Resolved artifacts and log directories.
+ */
+export function resolveProjectPaths(
+  _deps: WorkflowDeps,
+  cwd: string,
+  workflowRunId: string,
+  codebaseId?: string,
+): ProjectPaths {
+  if (codebaseId) {
+    // Codebase-scoped paths
+    return {
+      artifactsDir: resolve(cwd, '.ion', 'codebases', codebaseId, 'artifacts', workflowRunId),
+      logDir: resolve(cwd, '.ion', 'codebases', codebaseId, 'logs', workflowRunId),
+    };
+  }
+
+  // Cwd-based paths (default)
+  return {
+    artifactsDir: resolve(cwd, '.ion', 'artifacts', workflowRunId),
+    logDir: resolve(cwd, '.ion', 'logs', workflowRunId),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a new workflow run in the store.
+ */
+async function createNewRun(
+  deps: WorkflowDeps,
+  workflow: WorkflowDefinition,
+  userMessage: string,
+  opts: WorkflowExecutionOptions,
+): Promise<WorkflowRun> {
+  const data: CreateWorkflowRunData = {
+    workflowPath: workflow.name,
+    workflowName: workflow.name,
+    trigger: 'manual',
+    input: {
+      message: userMessage,
+      ...(opts.input ?? {}),
+    },
+  };
+
+  return deps.store.createWorkflowRun(data);
+}
+
+/**
+ * Create a minimal failed run object for error cases where
+ * the store is not available.
+ */
+function createFailedRun(workflow: WorkflowDefinition, error: unknown): WorkflowRun {
+  return {
+    id: 'error',
+    workflowPath: workflow.name,
+    workflowName: workflow.name,
+    status: 'failed',
+    trigger: 'manual',
+    input: {},
+    error: error instanceof Error ? error.message : String(error),
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+}