perf(llama): unshadow cache-type + spec-decoding flags for agent opt-in

KV cache quantization (--cache-type-k q4_0) and ngram speculative decoding
(--spec-type ngram-mod) are high-value llama.cpp features that improve VRAM
usage and tokens/sec. Removing them from the shadowing lists allows agents
to enable them via llama_extra_args.

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

.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/coder/src/index.ts

@@ -28,6 +28,7 @@ import { registerArenaRoutes } from './routes/arena.js';
 import { registerProviderRoutes } from './routes/providers.js';
 import { registerWorktreeSafetyRoutes } from './routes/worktree-safety.js';
 import { registerLifecycleRoutes } from './routes/lifecycle.js';
+import { registerAnalyticsRoutes } from './routes/analytics.js';
 import { registerWebSocket } from './routes/ws.js';
 // Phase 4: dispatcher + agent probe
 import { createDispatcher } from './services/dispatcher.js';
@@ -382,6 +383,7 @@ async function main() {
   registerProviderRoutes(app, sql, config);
   registerWorktreeSafetyRoutes(app, sql);
   registerLifecycleRoutes(app, sql);
+  registerAnalyticsRoutes(app, sql);
   registerWebSocket(app, sql, broker);
 
   // Graceful shutdown

apps/coder/src/routes/analytics.ts

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

apps/coder/src/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/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/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/pending_changes.ts

@@ -4,7 +4,6 @@ import { randomBytes } from 'node:crypto';
 import type { Sql } from '../db.js';
 import { resolveWritePath } from './write_guard.js';
 import { locateMatch } from './fuzzy-match.js';
-import { validateEditResult, formatGuardError } from './edit-guards.js';
 
 /**
  * Write a file atomically: stage to a sibling temp file, then rename over the
@@ -286,10 +285,6 @@ export async function applyOne(
             );
           }
           if (plan.kind === 'apply') {
-            const guard = validateEditResult(toLf(raw), plan.updated, change.file_path);
-            if (!guard.ok) {
-              throw new Error(formatGuardError(guard, change.file_path));
-            }
             const out = eol === '\r\n' ? plan.updated.replaceAll('\n', '\r\n') : plan.updated;
             await writeFileAtomic(change.file_path, out);
           } else {

apps/server/src/index.ts

@@ -19,6 +19,8 @@ import { registerModelRoutes } from './routes/models.js';
 import { registerAgentRoutes } from './routes/agents.js';
 import { registerSkillsRoutes } from './routes/skills.js';
 import { registerToolsRoutes } from './routes/tools.js';
+import { registerAnalyticsRoutes } from './routes/analytics.js';
+import { registerInferenceSettingsRoutes } from './routes/inference-settings.js';
 import { createInferenceRunner } from './services/inference/index.js';
 import { createBroker } from './services/broker.js';
 import { listSkills } from './services/skills.js';
@@ -122,6 +124,8 @@ async function main() {
   registerSidebarRoutes(app, sql);
   registerChatRoutes(app, sql, broker);
   registerToolsRoutes(app, sql);
+  registerAnalyticsRoutes(app, sql);
+  registerInferenceSettingsRoutes(app);
 
   // Batch 9.6: warm the skills cache at boot and surface the count. Empty or
   // missing /data/skills is non-fatal — the skill tools just return empty.

apps/server/src/routes/analytics.ts

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

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

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

apps/server/src/routes/projects.ts

@@ -1,6 +1,6 @@
 import type { FastifyInstance } from 'fastify';
 import { z } from 'zod';
-import { realpath, stat, readdir, access } from 'node:fs/promises';
+import { realpath, stat, readdir, access, writeFile, rename } from 'node:fs/promises';
 import { basename, resolve, sep } from 'node:path';
 import type { Sql } from '../db.js';
 import type { Config } from '../config.js';
@@ -473,7 +473,7 @@ export function registerProjectRoutes(
   // Always includes auto_mode (the dirty-state-derived mode) so the client can
   // show a suggestion when a pinned mode diverges from what would be auto-selected.
   // Returns { git_repo: false } when the path is not a git repository.
-  app.get<{ Params: { id: string }; Querystring: { mode?: string } }>(
+  app.get<{ Params: { id: string }; Querystring: { mode?: string; whitespace?: string } }>(
     '/api/projects/:id/git/diff',
     async (req, reply) => {
       const { id } = req.params;
@@ -504,7 +504,8 @@ export function registerProjectRoutes(
         rawMode === 'uncommitted' ? 'uncommitted' :
         auto_mode; // no mode param → auto-select (FIX 1)
 
-      const result = await getGitDiff(projectRoot, mode);
+      const ignoreWhitespace = req.query.whitespace === '1';
+      const result = await getGitDiff(projectRoot, mode, ignoreWhitespace);
       if (result === null) {
         return { git_repo: false, mode, auto_mode, base_label: null, in_progress_op: null, files: [] };
       }
@@ -541,6 +542,11 @@ export function registerProjectRoutes(
     ).min(1),
   });
 
+  const WriteFileBody = z.object({
+    path: z.string().min(1),
+    content: z.string(),
+  });
+
   // POST /api/projects/:id/git/stage — stage whole files
   app.post<{ Params: { id: string } }>(
     '/api/projects/:id/git/stage',
@@ -637,6 +643,38 @@ export function registerProjectRoutes(
     },
   );
 
+  // POST /api/projects/:id/write_file — write a file atomically
+  app.post<{ Params: { id: string } }>(
+    '/api/projects/:id/write_file',
+    async (req, reply) => {
+      const body = WriteFileBody.safeParse(req.body);
+      if (!body.success) { reply.code(400); return { error: body.error.message }; }
+      const { id } = req.params;
+      const projectPath = await selectProjectPath(sql, id);
+      if (!projectPath) { reply.code(404); return { error: 'not found' }; }
+      let root: string;
+      try { root = await resolveProjectRoot(projectPath); }
+      catch (err) { if (err instanceof PathScopeError) { reply.code(404); return { error: (err as Error).message }; } throw err; }
+      const target = body.data.path.startsWith('/') ? body.data.path : resolve(root, body.data.path);
+      // Validate path stays within project root
+      const realTarget = await realpath(target).catch(() => target);
+      if (!realTarget.startsWith(root + sep) && realTarget !== root) {
+        reply.code(403);
+        return { error: 'path escapes project root' };
+      }
+      const tmp = target + '.tmp';
+      try {
+        await writeFile(tmp, body.data.content, 'utf-8');
+        await rename(tmp, target);
+        return { ok: true };
+      } catch (err) {
+        // Clean up tmp on failure
+        await access(tmp).then(() => rename(tmp, target + '.bak').catch(() => {})).catch(() => {});
+        throw err;
+      }
+    },
+  );
+
   // GET /api/projects/:id/files
   app.get<{ Params: { id: string } }>(
     '/api/projects/:id/files',

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

@@ -271,7 +271,9 @@ function buildNumstatMap(
 async function getUncommittedDiff(
   gitRoot: string,
   inProgress: string | null,
+  ignoreWhitespace = false,
 ): Promise<GitDiffResult> {
+  const ws = ignoreWhitespace ? ['-w'] : [];
   const hasCommits = (await runGit(['rev-parse', '--verify', 'HEAD'], gitRoot)) !== null;
 
   const [nameStatusOut, cachedNameStatusOut, untrackedOut, numstatOut, diffOut, cachedDiffOut] =
@@ -284,10 +286,10 @@ async function getUncommittedDiff(
         : runGit(['diff', '--cached', '--name-status'], gitRoot),
       runGit(['ls-files', '--others', '--exclude-standard'], gitRoot),
       hasCommits ? runGit(['diff', '--numstat', 'HEAD'], gitRoot) : Promise.resolve(''),
-      hasCommits ? runGit(['diff', 'HEAD'], gitRoot) : Promise.resolve(''),
+      hasCommits ? runGit(['diff', ...ws, 'HEAD'], gitRoot) : Promise.resolve(''),
       hasCommits
-        ? runGit(['diff', '--cached', 'HEAD'], gitRoot)
+        ? runGit(['diff', ...ws, '--cached', 'HEAD'], gitRoot)
-        : runGit(['diff', '--cached'], gitRoot),
+        : runGit(['diff', ...ws, '--cached'], gitRoot),
     ]);
 
   const allChanged = parseNameStatus(nameStatusOut ?? '');
@@ -347,11 +349,13 @@ async function getCommittedDiff(
   base: string,
   label: string,
   inProgress: string | null,
+  ignoreWhitespace = false,
 ): Promise<GitDiffResult> {
+  const ws = ignoreWhitespace ? ['-w'] : [];
   const [nameStatusOut, numstatOut, diffOut] = await Promise.all([
     runGit(['diff', '--name-status', base, 'HEAD'], gitRoot),
     runGit(['diff', '--numstat', base, 'HEAD'], gitRoot),
-    runGit(['diff', base, 'HEAD'], gitRoot),
+    runGit(['diff', ...ws, base, 'HEAD'], gitRoot),
   ]);
 
   const allChanged = parseNameStatus(nameStatusOut ?? '');
@@ -383,23 +387,23 @@ async function getCommittedDiff(
  * the directory is not a git repository. On a null committed-mode base, falls
  * back to uncommitted and labels the result accordingly.
  */
-export async function getGitDiff(cwd: string, mode: GitDiffMode): Promise<GitDiffResult | null> {
+export async function getGitDiff(cwd: string, mode: GitDiffMode, ignoreWhitespace?: boolean): Promise<GitDiffResult | null> {
   const gitRoot = await resolveGitRoot(cwd);
   if (!gitRoot) return null;
 
   const inProgress = await detectInProgress(gitRoot);
 
   if (mode === 'uncommitted') {
-    return getUncommittedDiff(gitRoot, inProgress);
+    return getUncommittedDiff(gitRoot, inProgress, ignoreWhitespace ?? false);
   }
 
   const { base, label } = await resolveCommittedBase(gitRoot);
   if (!base) {
     // Fall back to uncommitted with a descriptive label
-    const result = await getUncommittedDiff(gitRoot, inProgress);
+    const result = await getUncommittedDiff(gitRoot, inProgress, ignoreWhitespace ?? false);
     return { ...result, base_label: label };
   }
-  return getCommittedDiff(gitRoot, base, label, inProgress);
+  return getCommittedDiff(gitRoot, base, label, inProgress, ignoreWhitespace ?? false);
 }
 
 // ── Phase 2: Write helpers ─────────────────────────────────────────────────

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',
 ]);

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

@@ -57,11 +57,21 @@ interface ConfigLike {
   LLAMA_SIDECAR_URL?: string;
 }
 
-export function resolveRoute(agent: AgentLike | null): RoutingInfo {
+export function resolveRoute(
+  agent: AgentLike | null,
+  config?: ConfigLike,
+): RoutingInfo {
+  // When llama_extra_args are explicitly set, route through sidecar with them.
   const flags = agent?.llama_extra_args;
   if (flags && flags.length > 0) {
     return { route: 'sidecar', flags };
   }
+  // When LLAMA_SIDECAR_URL is configured (even without per-agent flags),
+  // route through sidecar to pick up the default base args (cache quant,
+  // spec decoding, slot save, etc.). Fall back to llama-swap otherwise.
+  if (config?.LLAMA_SIDECAR_URL) {
+    return { route: 'sidecar', flags: [] };
+  }
   return { route: 'swap', flags: null };
 }
 
@@ -70,15 +80,13 @@ export function upstreamModel(
   modelId: string,
   agent?: AgentLike | null,
 ): LanguageModel {
-  const { route, flags } = resolveRoute(agent ?? null);
+  const { route, flags } = resolveRoute(agent ?? null, config);
   if (route === 'sidecar') {
     const url = config.LLAMA_SIDECAR_URL;
     if (!url) {
-      throw new Error(
+      throw new Error(`Sidecar route selected but LLAMA_SIDECAR_URL is not set`);
-        `Agent has llama_extra_args but LLAMA_SIDECAR_URL is not set`,
-      );
     }
-    return sidecarProvider(url, flags!).chatModel(modelId);
+    return sidecarProvider(url, (flags ?? [])).chatModel(modelId);
   }
   return getSwapProvider(config.LLAMA_SWAP_URL).chatModel(modelId);
 }

apps/web/src/App.tsx

@@ -7,6 +7,8 @@ import { Home } from '@/pages/Home';
 import { Project } from '@/pages/Project';
 import { Session } from '@/pages/Session';
 import { Settings } from '@/pages/Settings';
+import { Analytics } from '@/pages/Analytics';
+import { Results } from '@/pages/Results';
 import { Toaster } from '@/components/ui/sonner';
 import { useUserEvents } from '@/hooks/useUserEvents';
 import { useCoderUserEvents } from '@/hooks/useCoderUserEvents';
@@ -95,6 +97,8 @@ function AppShell() {
             <Route path="/project/:id" element={<Project />} />
             <Route path="/session/:id" element={<Session />} />
             <Route path="/settings" element={<Settings />} />
+            <Route path="/analytics" element={<Analytics />} />
+            <Route path="/results" element={<Results />} />
           </Routes>
         </main>
         <MobileRightRailBackdrop />

apps/web/src/api/client.ts

@@ -30,6 +30,10 @@ import type {
   BattleShape,
   ContestantShape,
   CrossExaminationShape,
+  AnalyticsSummary,
+  SessionAnalyticsRow,
+  ContextWindowStats,
+  TokenBreakdownAgg,
 } from './types';
 
 // v2.6 Phase 1-UX §9b: chat-scoped agent-session rows. Returned by
@@ -159,12 +163,13 @@ export const api = {
       request<{ files: string[] }>(`/api/projects/${id}/files`),
     git: (id: string) =>
       request<GitMeta>(`/api/projects/${id}/git`),
-    gitDiff: (id: string, mode: GitDiffMode | null) =>
+    gitDiff: (id: string, mode: GitDiffMode | null, hideWhitespace?: boolean) => {
-      request<GitDiffResult>(
+      const params: string[] = [];
-        mode !== null
+      if (mode !== null) params.push(`mode=${mode}`);
-          ? `/api/projects/${id}/git/diff?mode=${mode}`
+      if (hideWhitespace) params.push('whitespace=1');
-          : `/api/projects/${id}/git/diff`,
+      const qs = params.length > 0 ? `?${params.join('&')}` : '';
-      ),
+      return request<GitDiffResult>(`/api/projects/${id}/git/diff${qs}`);
+    },
     gitStage: (id: string, files: string[]) =>
       request<{ ok: boolean }>(`/api/projects/${id}/git/stage`, {
         method: 'POST',
@@ -185,6 +190,11 @@ export const api = {
         method: 'POST',
         body: JSON.stringify({ files }),
       }),
+    writeFile: (id: string, filePath: string, content: string) =>
+      request<{ ok: boolean }>(`/api/projects/${id}/write_file`, {
+        method: 'POST',
+        body: JSON.stringify({ path: filePath, content }),
+      }),
   },
 
   sessions: {
@@ -590,6 +600,14 @@ export const api = {
     costStats: () => request<{ stats: ToolCostStat[] }>('/api/tools/cost_stats'),
   },
 
+  // token-analyzer-ui: analytics aggregate endpoints.
+  analytics: {
+    summary: () => request<AnalyticsSummary>('/api/coder/analytics/summary'),
+    sessions: () => request<{ sessions: SessionAnalyticsRow[] }>('/api/coder/analytics/sessions'),
+    context: () => request<ContextWindowStats>('/api/analytics/context'),
+    tokenBreakdown: () => request<{ categories: TokenBreakdownAgg[] }>('/api/coder/analytics/token-breakdown'),
+  },
+
   settings: {
     get: () => request<Record<string, unknown>>('/api/settings'),
     patch: (body: Record<string, unknown>) =>

apps/web/src/api/types.ts

@@ -627,3 +627,32 @@ export type WsFrame =
       analysis_ready?: boolean;
       cross_exam_id?: string;
     };
+
+// token-analyzer-ui: aggregate token/cost analytics types.
+export interface AnalyticsSummary {
+  total_input_tokens: number;
+  total_output_tokens: number;
+  total_cost: number;
+  session_count: number;
+}
+
+export interface SessionAnalyticsRow {
+  session_id: string;
+  session_name: string;
+  total_input_tokens: number;
+  total_output_tokens: number;
+  total_cost: number;
+  last_active_at: string | null;
+}
+
+export interface ContextWindowStats {
+  avg_ctx_used: number | null;
+  avg_ctx_max: number | null;
+  avg_utilization_pct: number | null;
+  message_count: number;
+}
+
+export interface TokenBreakdownAgg {
+  category: string;
+  total_tokens: number;
+}

apps/web/src/components/DiffSplitView.tsx

@@ -0,0 +1,206 @@
+import { useMemo, useRef, useEffect, useState } from 'react';
+import { codeToHtml } from 'shiki';
+import type { GitDiffFile } from '@/api/types';
+import { parseDiff, buildSplitRows, reconstructNewContent, type SplitRow } from '@/utils/diff-layout';
+import { inferLanguage } from '@/lib/attachments';
+import { cn } from '@/lib/utils';
+
+interface DiffSplitViewProps {
+  file: GitDiffFile;
+  wrapLines?: boolean;
+}
+
+/** Side-by-side split diff renderer. Left = deletions, right = additions. */
+export function DiffSplitView({ file, wrapLines = false }: DiffSplitViewProps) {
+  // ── Edge cases (rendered before hooks) ──────────────────────────────────
+  if (file.is_binary) {
+    return <p className="text-xs text-muted-foreground italic px-2 py-1">Binary file</p>;
+  }
+  if (file.is_too_large) {
+    return <p className="text-xs text-muted-foreground italic px-2 py-1">Diff too large to display</p>;
+  }
+  if (file.change_type === 'untracked' && !file.diff_body) {
+    return <p className="text-xs text-muted-foreground italic px-2 py-1">Untracked file</p>;
+  }
+  if (!file.diff_body) {
+    return <p className="text-xs text-muted-foreground italic px-2 py-1">No diff content</p>;
+  }
+
+  return <DiffSplitViewInner file={file} wrapLines={wrapLines} />;
+}
+
+/**
+ * Inner component — assumes file.diff_body is non-null.
+ * Separated so the early-return edge cases above don't violate rules of hooks.
+ */
+function DiffSplitViewInner({ file, wrapLines }: { file: GitDiffFile; wrapLines: boolean }) {
+  // ── Parse diff ───────────────────────────────────────────────────────────
+  const parsed = useMemo(() => parseDiff(file.diff_body!), [file.diff_body]);
+  const parsedFile = parsed[0];
+
+  const rows = useMemo(() => {
+    if (!parsedFile) return [] as SplitRow[];
+    return buildSplitRows(parsedFile);
+  }, [parsedFile]);
+
+  const newContent = useMemo(() => {
+    if (!parsedFile) return '';
+    return reconstructNewContent(parsedFile.hunks);
+  }, [parsedFile]);
+
+  // ── Syntax highlighting ──────────────────────────────────────────────────
+  const [highlightedLines, setHighlightedLines] = useState<string[] | null>(null);
+  const [highlighting, setHighlighting] = useState(false);
+  const highlightKeyRef = useRef<string | null>(null);
+
+  useEffect(() => {
+    if (!newContent) return;
+    if (highlightKeyRef.current === newContent) return;
+    highlightKeyRef.current = newContent;
+
+    let cancelled = false;
+    setHighlighting(true);
+    setHighlightedLines(null);
+
+    const lang = inferLanguage(file.path) ?? 'plaintext';
+
+    void codeToHtml(newContent, { lang, theme: 'github-dark' })
+      .then((html) => {
+        if (cancelled) return;
+        const container = document.createElement('div');
+        // eslint-disable-next-line no-unsanitized/property
+        container.innerHTML = html;
+        const codeEl = container.querySelector('code');
+        if (codeEl) {
+          const lineSpans = codeEl.querySelectorAll('.line');
+          setHighlightedLines(Array.from(lineSpans, (span) => span.innerHTML));
+        } else {
+          setHighlightedLines(null);
+        }
+      })
+      .catch(() => {
+        if (!cancelled) setHighlightedLines(null);
+      })
+      .finally(() => {
+        if (!cancelled) setHighlighting(false);
+      });
+
+    return () => { cancelled = true; };
+  }, [newContent, file.path]);
+
+  // ── Build new-line-number → highlighted-HTML map ───────────────────────
+  // Walk the hunks counting only add/context lines (which form the new file)
+  // and map each 1-based new-line-number to its highlighted HTML string.
+  const newLineHtmlMap = useMemo(() => {
+    if (!highlightedLines || !parsedFile) return new Map<number, string>();
+    const map = new Map<number, string>();
+    let idx = 0;
+    for (const hunk of parsedFile.hunks) {
+      let newLineNo = hunk.newStart;
+      for (const line of hunk.lines) {
+        if (line.type === 'header') continue;
+        if (line.type === 'add' || line.type === 'context') {
+          if (idx < highlightedLines.length) {
+            map.set(newLineNo, highlightedLines[idx]!);
+          }
+          idx++;
+          newLineNo++;
+        }
+      }
+    }
+    return map;
+  }, [highlightedLines, parsedFile]);
+
+  // ── Render ───────────────────────────────────────────────────────────────
+  return (
+    <div className={cn('text-[11px] font-mono overflow-x-auto', wrapLines && 'break-all')}>
+      {highlighting && (
+        <p className="text-xs text-muted-foreground px-2 py-1">Highlighting…</p>
+      )}
+      <table className="w-full border-collapse">
+        <colgroup>
+          <col className="w-[40px]" />
+          <col />
+          <col className="w-px" />
+          <col className="w-[40px]" />
+          <col />
+        </colgroup>
+        <tbody>
+          {rows.map((row, idx) => {
+            if (row.kind === 'header') {
+              return (
+                <tr key={`h-${idx}`} className="bg-muted/30">
+                  <td
+                    colSpan={5}
+                    className="text-muted-foreground text-[11px] px-2 py-0.5 select-none"
+                  >
+                    {row.content}
+                  </td>
+                </tr>
+              );
+            }
+
+            const left = row.left;
+            const right = row.right;
+
+            const leftBg = left?.type === 'remove' ? 'bg-red-950/30' : '';
+            const rightBg = right?.type === 'add' ? 'bg-green-950/30' : '';
+
+            const leftHtml = left?.lineNumber != null ? newLineHtmlMap.get(left.lineNumber) : undefined;
+            const rightHtml = right?.lineNumber != null ? newLineHtmlMap.get(right.lineNumber) : undefined;
+
+            return (
+              <tr key={`p-${idx}`} className="hover:bg-muted/10">
+                <td className={cn(leftBg, 'border-r border-border/20 align-top')}>
+                  <span className="text-muted-foreground text-right pr-1 select-none text-[11px] block">
+                    {left?.lineNumber ?? ''}
+                  </span>
+                </td>
+                <td className={cn(leftBg, 'align-top')}>
+                  <div
+                    className={cn(
+                      'pl-2 text-[11px]',
+                      wrapLines ? 'whitespace-pre-wrap break-all' : 'whitespace-pre',
+                    )}
+                  >
+                    {left ? (
+                      leftHtml ? (
+                        // eslint-disable-next-line no-unsanitized/property
+                        <span dangerouslySetInnerHTML={{ __html: leftHtml }} />
+                      ) : (
+                        <span>{left.content}</span>
+                      )
+                    ) : null}
+                  </div>
+                </td>
+                <td className="border-l border-border/30 w-px p-0" />
+                <td className={cn(rightBg, 'border-r border-border/20 align-top')}>
+                  <span className="text-muted-foreground text-right pr-1 select-none text-[11px] block">
+                    {right?.lineNumber ?? ''}
+                  </span>
+                </td>
+                <td className={cn(rightBg, 'align-top')}>
+                  <div
+                    className={cn(
+                      'pl-2 text-[11px]',
+                      wrapLines ? 'whitespace-pre-wrap break-all' : 'whitespace-pre',
+                    )}
+                  >
+                    {right ? (
+                      rightHtml ? (
+                        // eslint-disable-next-line no-unsanitized/property
+                        <span dangerouslySetInnerHTML={{ __html: rightHtml }} />
+                      ) : (
+                        <span>{right.content}</span>
+                      )
+                    ) : null}
+                  </div>
+                </td>
+              </tr>
+            );
+          })}
+        </tbody>
+      </table>
+    </div>
+  );
+}

apps/web/src/components/GitDiffView.tsx

@@ -1,8 +1,13 @@
-import { useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { ChevronDown, ChevronRight, GitBranch, RefreshCw, Trash2 } from 'lucide-react';
+import { ChevronDown, ChevronRight, Columns2, GitBranch, ListChevronsDownUp, ListChevronsUpDown, AlignJustify, Pilcrow, RefreshCw, Trash2, WrapText } from 'lucide-react';
 import { codeToHtml } from 'shiki';
 import type { GitDiffFile, GitDiffMode, GitDiffResult, GitDiscardFileInfo } from '@/api/types';
 import { cn } from '@/lib/utils';
+import { DiffSplitView } from './DiffSplitView';
+import { InlineReviewGutterCell } from './InlineReviewGutterCell';
+import { InlineReviewEditor } from './InlineReviewEditor';
+import { InlineReviewThread } from './InlineReviewThread';
+import { useDiffComments } from '@/stores/useDiffCommentStore';
 
 interface WriteProps {
   mutating: boolean;
@@ -18,12 +23,19 @@ interface Props extends WriteProps {
   loading: boolean;
   error: string | null;
   mode: GitDiffMode;
+  sessionId?: string;
   onSelectMode: (m: GitDiffMode) => void;
   onRefresh: () => void;
   /** FIX 4: non-null when the repo's dirty state suggests a different mode than the pinned one. */
   modeSuggestion?: GitDiffMode | null;
   /** FIX 5: pending-changes count from the Coder pane — shown in empty state as a hint. */
   pendingCount?: number;
+  layout: 'unified' | 'split';
+  wrapLines: boolean;
+  hideWhitespace: boolean;
+  onLayoutChange: (layout: 'unified' | 'split') => void;
+  onWrapLinesChange: (wrap: boolean) => void;
+  onHideWhitespaceChange: (hide: boolean) => void;
 }
 
 const CHANGE_TYPE_LABELS: Record<string, string> = {
@@ -99,6 +111,12 @@ function FileDiffRow({
   onStage,
   onUnstage,
   onDiscardRequest,
+  layout,
+  wrapLines,
+  expanded,
+  onToggleExpand,
+  sessionId,
+  diffMode,
 }: {
   file: GitDiffFile;
   uncommitted: boolean;
@@ -106,11 +124,21 @@ function FileDiffRow({
   onStage: (path: string) => void;
   onUnstage: (path: string) => void;
   onDiscardRequest: (file: GitDiffFile) => void;
+  layout: 'unified' | 'split';
+  wrapLines: boolean;
+  expanded: boolean;
+  onToggleExpand: (path: string) => void;
+  sessionId?: string;
+  diffMode?: string;
 }) {
-  const [expanded, setExpanded] = useState(false);
   const [html, setHtml] = useState<string | null>(null);
   const [highlighting, setHighlighting] = useState(false);
   const highlightRef = useRef<HTMLDivElement | null>(null);
+  const [showEditor, setShowEditor] = useState(false);
+  const commentKey = `${file.path}:${file.change_type}`;
+  const diffModeVal = diffMode ?? '';
+  const { comments, addComment, updateComment, deleteComment } = useDiffComments(sessionId ?? '', diffModeVal);
+  const fileComments = comments.get(commentKey) ?? [];
 
   useEffect(() => {
     if (!expanded || !file.diff_body) return;
@@ -136,13 +164,27 @@ function FileDiffRow({
   const typeColor = CHANGE_TYPE_COLORS[file.change_type] ?? 'text-muted-foreground';
   const displayPath = file.old_path ? `${file.old_path} → ${file.path}` : file.path;
 
+  const handleAddComment = (body: string) => {
+    const comment = { id: crypto.randomUUID(), body, createdAt: Date.now(), updatedAt: Date.now() };
+    addComment(commentKey, comment);
+    setShowEditor(false);
+  };
+
+  const handleEditComment = (id: string, body: string) => {
+    updateComment(commentKey, id, body);
+  };
+
+  const handleDeleteComment = (id: string) => {
+    deleteComment(commentKey, id);
+  };
+
   return (
     <li className="border-b border-border/30 last:border-0">
       <div className="flex items-center group">
         <button
           type="button"
           className="flex-1 flex items-center gap-1.5 px-2 py-1.5 text-xs hover:bg-muted/40 text-left max-md:min-h-[44px] min-w-0"
-          onClick={() => setExpanded((p) => !p)}
+          onClick={() => onToggleExpand(file.path)}
           aria-expanded={expanded}
         >
           {expanded
@@ -203,23 +245,54 @@ function FileDiffRow({
             <p className="text-xs text-muted-foreground italic px-2 py-1">Untracked — not yet staged</p>
           )}
           {!file.is_binary && !file.is_too_large && file.diff_body && (
-            <>
+            layout === 'split' ? (
-              {highlighting && (
+              <DiffSplitView file={file} wrapLines={wrapLines} />
-                <p className="text-xs text-muted-foreground px-2 py-1">Highlighting…</p>
+            ) : (
-              )}
+              <>
-              {!highlighting && html !== null ? (
+                {highlighting && (
-                <div
+                  <p className="text-xs text-muted-foreground px-2 py-1">Highlighting…</p>
-                  ref={highlightRef}
+                )}
-                  className="text-[11px] overflow-x-auto rounded bg-[#0d1117] [&_pre]:!p-2 [&_pre]:!m-0 [&_pre]:overflow-x-auto"
+                {!highlighting && html !== null ? (
+                  <div
+                    ref={highlightRef}
+                    className="text-[11px] overflow-x-auto rounded bg-[#0d1117] [&_pre]:!p-2 [&_pre]:!m-0 [&_pre]:overflow-x-auto"
+                  />
+                ) : (
+                  !highlighting && (
+                    <pre className={cn(
+                      'text-[11px] overflow-x-auto rounded bg-muted/30 p-2',
+                      wrapLines ? 'whitespace-pre-wrap break-all' : 'whitespace-pre',
+                    )}>
+                      {file.diff_body}
+                    </pre>
+                  )
+                )}
+                {/* Comment button */}
+                <div className="flex items-center gap-1 mt-1">
+                  <button
+                    type="button"
+                    onClick={() => setShowEditor(!showEditor)}
+                    className="text-[10px] text-muted-foreground hover:text-foreground flex items-center gap-0.5 px-1 py-0.5 rounded hover:bg-muted/40"
+                  >
+                    <span>{showEditor ? 'Cancel' : 'Comment'}</span>
+                  </button>
+                  <span className="text-[10px] text-muted-foreground/50">
+                    {fileComments.length > 0 && `${fileComments.length} comment${fileComments.length > 1 ? 's' : ''}`}
+                  </span>
+                </div>
+                {showEditor && (
+                  <InlineReviewEditor
+                    onSave={handleAddComment}
+                    onCancel={() => setShowEditor(false)}
+                  />
+                )}
+                <InlineReviewThread
+                  comments={fileComments}
+                  onEditComment={handleEditComment}
+                  onDeleteComment={handleDeleteComment}
                 />
-              ) : (
+              </>
-                !highlighting && (
+            )
-                  <pre className="text-[11px] overflow-x-auto rounded bg-muted/30 p-2 whitespace-pre">
-                    {file.diff_body}
-                  </pre>
-                )
-              )}
-            </>
           )}
         </div>
       )}
@@ -242,11 +315,41 @@ export function GitDiffView({
   onDiscard,
   modeSuggestion,
   pendingCount,
+  layout,
+  wrapLines,
+  hideWhitespace,
+  onLayoutChange,
+  onWrapLinesChange,
+  onHideWhitespaceChange,
+  sessionId,
 }: Props) {
   const [commitMessage, setCommitMessage] = useState('');
   const [discardTarget, setDiscardTarget] = useState<DiscardConfirmState | null>(null);
   const [lastAction, setLastAction] = useState<string | null>(null);
   const lastActionTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const [expandedFiles, setExpandedFiles] = useState<Set<string>>(new Set());
+
+  const allExpandedComputed = useMemo(
+    () => result !== null && (result.files?.length ?? 0) > 0 && result.files.every((f) => expandedFiles.has(f.path)),
+    [result, expandedFiles],
+  );
+
+  const handleExpandAllChange = useCallback((expand: boolean) => {
+    if (expand && result?.files) {
+      setExpandedFiles(new Set(result.files.map((f) => f.path)));
+    } else {
+      setExpandedFiles(new Set());
+    }
+  }, [result?.files]);
+
+  const handleToggleExpand = useCallback((path: string) => {
+    setExpandedFiles((prev) => {
+      const next = new Set(prev);
+      if (next.has(path)) next.delete(path);
+      else next.add(path);
+      return next;
+    });
+  }, []);
 
   function flashAction(msg: string) {
     setLastAction(msg);
@@ -378,6 +481,83 @@ export function GitDiffView({
         </button>
       </div>
 
+      {/* Diff toolbar */}
+      <div className="flex items-center gap-1 px-2 py-1 border-b shrink-0">
+        <button
+          type="button"
+          onClick={() => onLayoutChange('unified')}
+          className={cn(
+            'text-xs px-2 py-0.5 rounded flex items-center gap-1 max-md:min-h-[44px]',
+            layout === 'unified'
+              ? 'bg-muted text-foreground font-medium'
+              : 'text-muted-foreground hover:text-foreground',
+          )}
+          title="Unified diff"
+        >
+          <AlignJustify size={12} />
+          Unified
+        </button>
+        <button
+          type="button"
+          onClick={() => onLayoutChange('split')}
+          className={cn(
+            'text-xs px-2 py-0.5 rounded flex items-center gap-1 max-md:min-h-[44px]',
+            layout === 'split'
+              ? 'bg-muted text-foreground font-medium'
+              : 'text-muted-foreground hover:text-foreground',
+          )}
+          title="Split diff"
+        >
+          <Columns2 size={12} />
+          Split
+        </button>
+        <button
+          type="button"
+          onClick={() => onHideWhitespaceChange(!hideWhitespace)}
+          className={cn(
+            'p-1 rounded max-md:min-h-[44px] max-md:min-w-[44px]',
+            hideWhitespace
+              ? 'bg-muted text-foreground font-medium'
+              : 'text-muted-foreground hover:text-foreground',
+          )}
+          title={hideWhitespace ? 'Show whitespace' : 'Hide whitespace'}
+        >
+          <Pilcrow size={12} />
+        </button>
+        <button
+          type="button"
+          onClick={() => onWrapLinesChange(!wrapLines)}
+          className={cn(
+            'p-1 rounded max-md:min-h-[44px] max-md:min-w-[44px]',
+            wrapLines
+              ? 'bg-muted text-foreground font-medium'
+              : 'text-muted-foreground hover:text-foreground',
+          )}
+          title={wrapLines ? 'Unwrap lines' : 'Wrap lines'}
+        >
+          <WrapText size={12} />
+        </button>
+        <div className="flex-1" />
+        <button
+          type="button"
+          onClick={() => handleExpandAllChange(!allExpandedComputed)}
+          className="p-1 rounded hover:bg-muted text-muted-foreground hover:text-foreground max-md:min-h-[44px] max-md:min-w-[44px]"
+          title={allExpandedComputed ? 'Collapse all' : 'Expand all'}
+        >
+          {allExpandedComputed ? <ListChevronsDownUp size={12} /> : <ListChevronsUpDown size={12} />}
+        </button>
+        <button
+          type="button"
+          onClick={onRefresh}
+          disabled={loading || mutating}
+          className="p-1 rounded hover:bg-muted text-muted-foreground disabled:opacity-40 max-md:min-h-[44px] max-md:min-w-[44px]"
+          aria-label="Refresh diff"
+          title="Refresh"
+        >
+          <RefreshCw size={12} />
+        </button>
+      </div>
+
       {/* Committed-mode base label */}
       {result.mode === 'committed' && base_label && (
         <div className="px-2 py-1 text-[10px] text-muted-foreground border-b flex items-center gap-1 shrink-0">
@@ -445,6 +625,12 @@ export function GitDiffView({
                 onStage={handleStage}
                 onUnstage={handleUnstage}
                 onDiscardRequest={handleDiscardRequest}
+                layout={layout}
+                wrapLines={wrapLines}
+                expanded={expandedFiles.has(file.path)}
+                onToggleExpand={handleToggleExpand}
+                sessionId={sessionId}
+                diffMode={mode}
               />
             ))}
           </ul>

apps/web/src/components/InferenceSettings.tsx

@@ -0,0 +1,271 @@
+import { useEffect, useState } from 'react';
+import { toast } from 'sonner';
+import { Button } from '@/components/ui/button';
+import { Database, Zap, Clock, BarChart3, Folder } from 'lucide-react';
+
+interface InferenceConfig {
+  cache_type_k: string;
+  cache_reuse: number;
+  spec_type: string;
+  spec_ngram_mod_thsh: number;
+  ctx_checkpoints: number;
+  sleep_idle_seconds: number;
+  metrics_enabled: boolean;
+  slot_save_path: string;
+}
+
+const DEFAULTS: InferenceConfig = {
+  cache_type_k: 'q4_0',
+  cache_reuse: 256,
+  spec_type: 'ngram-mod',
+  spec_ngram_mod_thsh: 2,
+  ctx_checkpoints: 32,
+  sleep_idle_seconds: 600,
+  metrics_enabled: true,
+  slot_save_path: '/tmp/llama-slots',
+};
+
+function Switch({ checked, onCheckedChange, id }: {
+  checked: boolean;
+  onCheckedChange: (v: boolean) => void;
+  id?: string;
+}) {
+  return (
+    <button
+      id={id}
+      type="button"
+      role="switch"
+      aria-checked={checked}
+      onClick={() => onCheckedChange(!checked)}
+      className={`relative inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full transition-colors ${
+        checked ? 'bg-primary' : 'bg-muted'
+      }`}
+    >
+      <span className={`inline-block h-4 w-4 transform rounded-full bg-background transition-transform ${
+        checked ? 'translate-x-[1.125rem]' : 'translate-x-0.5'
+      }`} />
+    </button>
+  );
+}
+
+function Loader() {
+  return <div className="text-sm text-muted-foreground py-8 text-center">Loading inference settings...</div>;
+}
+
+export function InferenceSettings() {
+  const [config, setConfig] = useState<InferenceConfig | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [saving, setSaving] = useState(false);
+
+  useEffect(() => {
+    fetch('/api/settings/inference')
+      .then((r) => (r.ok ? r.json() : Promise.reject()))
+      .then((data) => setConfig(data as InferenceConfig))
+      .catch(() => {
+        setConfig({ ...DEFAULTS });
+        toast.error('Could not load inference config — loading defaults');
+      })
+      .finally(() => setLoading(false));
+  }, []);
+
+  function update<K extends keyof InferenceConfig>(key: K, value: InferenceConfig[K]) {
+    setConfig((prev) => (prev ? { ...prev, [key]: value } : prev));
+  }
+
+  async function save() {
+    if (!config || saving) return;
+    setSaving(true);
+    try {
+      const res = await fetch('/api/settings/inference', {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(config),
+      });
+      if (!res.ok) throw new Error('Save failed');
+      const updated = (await res.json()) as InferenceConfig;
+      setConfig(updated);
+      toast.success('Inference settings saved');
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : 'Save failed');
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  if (loading) return <Loader />;
+  if (!config) return <div className="text-sm text-destructive py-8 text-center">Failed to load</div>;
+
+  return (
+    <div className="space-y-6">
+      <div className="space-y-1.5">
+        <div className="flex items-center gap-2">
+          <Database className="size-3.5 text-muted-foreground" />
+          <label className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+            KV Cache Quantization
+          </label>
+        </div>
+        <select
+          value={config.cache_type_k}
+          onChange={(e) => update('cache_type_k', e.target.value)}
+          className="w-full bg-background border border-border rounded px-2 py-1.5 text-sm outline-none focus:border-ring"
+        >
+          <option value="f32">f32 (full precision)</option>
+          <option value="f16">f16 (half)</option>
+          <option value="q8_0">q8_0 (8-bit)</option>
+          <option value="q4_0">q4_0 (4-bit) — recommended</option>
+        </select>
+        <p className="text-xs text-muted-foreground/80">
+          Format for the attention KV cache. Lower = less VRAM. q4_0 gives ~4x savings.
+        </p>
+      </div>
+
+      <div className="space-y-1.5">
+        <div className="flex items-center gap-2">
+          <Zap className="size-3.5 text-muted-foreground" />
+          <label className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+            Prompt Caching
+          </label>
+        </div>
+        <div className="flex items-center gap-3">
+          <input
+            type="number"
+            min={0}
+            max={4096}
+            value={config.cache_reuse}
+            onChange={(e) => update('cache_reuse', Number(e.target.value))}
+            className="w-32 bg-background border border-border rounded px-2 py-1.5 text-sm outline-none focus:border-ring"
+          />
+          <span className="text-xs text-muted-foreground">
+            {config.cache_reuse > 0 ? 'On (min chunk size in tokens)' : 'Disabled'}
+          </span>
+        </div>
+        <p className="text-xs text-muted-foreground/80">
+          Reuses KV cache across turns when prompt prefix matches. 256 is a good default.
+          0 = disabled. The local equivalent of prompt caching.
+        </p>
+      </div>
+
+      <div className="space-y-1.5">
+        <div className="flex items-center gap-2">
+          <Zap className="size-3.5 text-muted-foreground" />
+          <label className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+            Speculative Decoding
+          </label>
+        </div>
+        <select
+          value={config.spec_type}
+          onChange={(e) => update('spec_type', e.target.value)}
+          className="w-full bg-background border border-border rounded px-2 py-1.5 text-sm outline-none focus:border-ring"
+        >
+          <option value="off">Off</option>
+          <option value="ngram-mod">N-gram (lightweight, ~16MB)</option>
+          <option value="draft-simple">Draft model (requires separate model)</option>
+        </select>
+        {config.spec_type === 'ngram-mod' && (
+          <div className="mt-2 flex items-center gap-3">
+            <input
+              type="number"
+              min={1}
+              max={10}
+              value={config.spec_ngram_mod_thsh}
+              onChange={(e) => update('spec_ngram_mod_thsh', Number(e.target.value))}
+              className="w-24 bg-background border border-border rounded px-2 py-1.5 text-sm outline-none focus:border-ring"
+            />
+            <span className="text-xs text-muted-foreground">Match threshold (2 = default)</span>
+          </div>
+        )}
+        <p className="text-xs text-muted-foreground/80">
+          Predicts tokens ahead with a small model; main model verifies in batch.
+          2-3x speedup on repetitive/code tasks.
+        </p>
+      </div>
+
+      <div className="space-y-1.5">
+        <label className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+          Context Checkpoints
+        </label>
+        <div className="flex items-center gap-3">
+          <input
+            type="number"
+            min={0}
+            max={128}
+            value={config.ctx_checkpoints}
+            onChange={(e) => update('ctx_checkpoints', Number(e.target.value))}
+            className="w-24 bg-background border border-border rounded px-2 py-1.5 text-sm outline-none focus:border-ring"
+          />
+          <span className="text-xs text-muted-foreground">
+            {config.ctx_checkpoints > 0 ? `Max ${config.ctx_checkpoints} checkpoints per slot` : 'Disabled'}
+          </span>
+        </div>
+        <p className="text-xs text-muted-foreground/80">
+          Prevents context overflow on long conversations. Default: 32.
+        </p>
+      </div>
+
+      <div className="space-y-1.5">
+        <div className="flex items-center gap-2">
+          <Clock className="size-3.5 text-muted-foreground" />
+          <label className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+            Auto-sleep Timeout
+          </label>
+        </div>
+        <div className="flex items-center gap-3">
+          <input
+            type="number"
+            min={-1}
+            max={86400}
+            value={config.sleep_idle_seconds}
+            onChange={(e) => update('sleep_idle_seconds', Number(e.target.value))}
+            className="w-24 bg-background border border-border rounded px-2 py-1.5 text-sm outline-none focus:border-ring"
+          />
+          <span className="text-xs text-muted-foreground">seconds</span>
+        </div>
+        <p className="text-xs text-muted-foreground/80">
+          GPU auto-sleeps after N seconds idle. -1 = disabled. 600 = 10 min.
+        </p>
+      </div>
+
+      <div className="space-y-1.5">
+        <div className="flex items-center justify-between gap-3">
+          <div className="flex items-center gap-2">
+            <BarChart3 className="size-3.5 text-muted-foreground" />
+            <label className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+              Prometheus Metrics
+            </label>
+          </div>
+          <Switch
+            checked={config.metrics_enabled}
+            onCheckedChange={(v) => update('metrics_enabled', v)}
+          />
+        </div>
+        <p className="text-xs text-muted-foreground/80">
+          Enable /metrics endpoint for Prometheus monitoring (token rates, latency).
+        </p>
+      </div>
+
+      <div className="space-y-1.5">
+        <div className="flex items-center gap-2">
+          <Folder className="size-3.5 text-muted-foreground" />
+          <label className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+            Slot KV Cache Path
+          </label>
+        </div>
+        <input
+          type="text"
+          value={config.slot_save_path}
+          onChange={(e) => update('slot_save_path', e.target.value)}
+          className="w-full bg-background border border-border rounded px-2 py-1.5 text-sm font-mono outline-none focus:border-ring"
+        />
+        <p className="text-xs text-muted-foreground/80">
+          Directory for disk-persistent KV cache. Idle slot caches are saved here.
+        </p>
+      </div>
+
+      <div className="flex justify-end border-t pt-4">
+        <Button onClick={() => void save()} disabled={saving}>
+          {saving ? 'Saving...' : 'Save Settings'}
+        </Button>
+      </div>
+    </div>
+  );
+}

apps/web/src/components/InlineReviewEditor.tsx

@@ -0,0 +1,60 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+interface InlineReviewEditorProps {
+  initialBody?: string;
+  onSave: (body: string) => void;
+  onCancel: () => void;
+}
+
+export function InlineReviewEditor({ initialBody = '', onSave, onCancel }: InlineReviewEditorProps) {
+  const [text, setText] = useState(initialBody);
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+
+  useEffect(() => {
+    textareaRef.current?.focus();
+  }, []);
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        e.stopPropagation();
+        onCancel();
+      }
+      if ((e.metaKey || e.ctrlKey) && e.key === 'Enter' && text.trim()) {
+        onSave(text.trim());
+      }
+    },
+    [onCancel, onSave, text],
+  );
+
+  return (
+    <div className="mx-2 my-1 rounded border border-border/80 bg-popover p-2 shadow-sm">
+      <textarea
+        ref={textareaRef}
+        value={text}
+        onChange={(e) => setText(e.target.value)}
+        onKeyDown={handleKeyDown}
+        placeholder="Add a comment..."
+        rows={3}
+        className="w-full resize-none bg-transparent text-[13px] text-foreground placeholder:text-muted-foreground/60 outline-none"
+      />
+      <div className="flex items-center justify-end gap-1.5 mt-1.5 border-t border-border/40 pt-1.5">
+        <button
+          type="button"
+          onClick={onCancel}
+          className="text-xs px-2 py-1 rounded hover:bg-muted text-muted-foreground"
+        >
+          Cancel
+        </button>
+        <button
+          type="button"
+          disabled={!text.trim()}
+          onClick={() => onSave(text.trim())}
+          className="text-xs px-2 py-1 rounded bg-primary text-primary-foreground hover:bg-primary/90 disabled:opacity-40"
+        >
+          Save
+        </button>
+      </div>
+    </div>
+  );
+}

apps/web/src/components/InlineReviewGutterCell.tsx

@@ -0,0 +1,43 @@
+import { cn } from '@/lib/utils';
+import { Plus } from 'lucide-react';
+
+interface InlineReviewGutterCellProps {
+  lineNumber: number | null;
+  type: 'add' | 'remove' | 'context' | 'header' | null;
+  hasComments: boolean;
+  canComment: boolean;
+  onClick?: () => void;
+}
+
+export function InlineReviewGutterCell({
+  lineNumber,
+  type,
+  hasComments,
+  canComment,
+  onClick,
+}: InlineReviewGutterCellProps) {
+  return (
+    <div
+      className={cn(
+        'relative flex items-center justify-end pr-1 min-w-[40px] h-5 text-[11px] font-mono select-none',
+        type === 'add' && 'bg-green-950/30',
+        type === 'remove' && 'bg-red-950/30',
+        type === 'context' && 'bg-muted/10',
+        canComment && 'cursor-pointer group',
+      )}
+      onClick={canComment ? onClick : undefined}
+    >
+      <span className="text-muted-foreground/70">
+        {lineNumber != null ? lineNumber : ''}
+      </span>
+      {canComment && (
+        <span className="absolute left-0.5 hidden group-hover:flex items-center justify-center w-4 h-4 rounded text-muted-foreground hover:text-foreground">
+          <Plus size={12} />
+        </span>
+      )}
+      {hasComments && (
+        <span className="absolute left-0.5 w-1.5 h-1.5 rounded-full bg-blue-400" />
+      )}
+    </div>
+  );
+}

apps/web/src/components/InlineReviewThread.tsx

@@ -0,0 +1,92 @@
+import { useState } from 'react';
+import { MessageSquare, Pencil, Trash2 } from 'lucide-react';
+import type { DiffComment } from '@/stores/useDiffCommentStore';
+import { InlineReviewEditor } from './InlineReviewEditor';
+
+interface InlineReviewThreadProps {
+  comments: DiffComment[];
+  onEditComment: (id: string, body: string) => void;
+  onDeleteComment: (id: string) => void;
+}
+
+export function InlineReviewThread({
+  comments,
+  onEditComment,
+  onDeleteComment,
+}: InlineReviewThreadProps) {
+  const [expanded, setExpanded] = useState(true);
+  const [editingId, setEditingId] = useState<string | null>(null);
+  const [editBody, setEditBody] = useState('');
+
+  if (comments.length === 0) return null;
+
+  const handleStartEdit = (id: string, body: string) => {
+    setEditingId(id);
+    setEditBody(body);
+  };
+
+  const handleSaveEdit = (body: string) => {
+    if (editingId) {
+      onEditComment(editingId, body);
+      setEditingId(null);
+    }
+  };
+
+  const handleCancelEdit = () => {
+    setEditingId(null);
+  };
+
+  return (
+    <div className="ml-1 border-l-2 border-blue-400/40 pl-2 my-1">
+      <button
+        type="button"
+        onClick={() => setExpanded(!expanded)}
+        className="flex items-center gap-1 text-[10px] text-muted-foreground hover:text-foreground mb-0.5"
+      >
+        <MessageSquare size={10} />
+        <span>{comments.length} comment{comments.length > 1 ? 's' : ''}</span>
+        <span className="text-[9px]">{expanded ? '▲' : '▼'}</span>
+      </button>
+
+      {expanded && (
+        <div className="space-y-1">
+          {comments.map((comment) => (
+            <div key={comment.id} className="text-xs">
+              {editingId === comment.id ? (
+                <InlineReviewEditor
+                  initialBody={editBody}
+                  onSave={handleSaveEdit}
+                  onCancel={handleCancelEdit}
+                />
+              ) : (
+                <div className="flex items-start gap-1 group">
+                  <span className="flex-1 text-foreground/90 leading-relaxed whitespace-pre-wrap">
+                    {comment.body}
+                  </span>
+                  <div className="hidden group-hover:flex items-center gap-0.5 shrink-0 mt-0.5">
+                    <button
+                      type="button"
+                      onClick={() => handleStartEdit(comment.id, comment.body)}
+                      className="p-0.5 rounded hover:bg-muted text-muted-foreground"
+                      title="Edit"
+                    >
+                      <Pencil size={10} />
+                    </button>
+                    <button
+                      type="button"
+                      onClick={() => onDeleteComment(comment.id)}
+                      className="p-0.5 rounded hover:bg-muted text-muted-foreground hover:text-destructive"
+                      title="Delete"
+                    >
+                      <Trash2 size={10} />
+                    </button>
+                  </div>
+                </div>
+              )}
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

apps/web/src/components/ProjectSidebar.tsx

@@ -1,6 +1,6 @@
 import { useEffect, useMemo, useRef, useState } from 'react';
 import { NavLink, useLocation, useNavigate } from 'react-router-dom';
-import { ChevronRight, ExternalLink, Folder, MessageSquare, Plus, Settings as SettingsIcon, X, Code } from 'lucide-react';
+import { BarChart3, ChevronRight, ExternalLink, Folder, MessageSquare, Plus, ScrollText, Settings as SettingsIcon, X, Code } from 'lucide-react';
 import { toast } from 'sonner';
 import { Button } from '@/components/ui/button';
 import mascot from '@/assets/brand/banner-mascot.png';
@@ -519,11 +519,40 @@ export function ProjectSidebar() {
           })}
       </nav>
 
-      {/* v1.9: bottom-pinned Settings button. In a session, opens/focuses the
+      {/* bottom-pinned nav buttons. Results → Analytics → Settings. */}
-          workspace settings pane via the sessionEvents bus (Session.tsx owns
+      <div className="border-t shrink-0 p-2 space-y-0.5">
-          the panesHook). Outside a session there's no workspace to mount the
+        <NavLink
-          pane in, so we navigate to /settings (themes page) instead. */}
+          to="/results"
-      <div className="border-t shrink-0 p-2">
+          onClick={() => { if (isMobile) setDrawerOpen(false); }}
+          className={({ isActive }) =>
+            `w-full flex items-center gap-2 px-2 py-1.5 rounded-md text-sm hover:bg-sidebar-accent/60 text-sidebar-foreground ${
+              isActive ? 'bg-sidebar-accent text-sidebar-accent-foreground' : ''
+            }`
+          }
+          aria-label="Results"
+        >
+          <ScrollText className="size-3.5 shrink-0 opacity-70" />
+          <span className="flex-1 text-left">Results</span>
+        </NavLink>
+
+        <NavLink
+          to="/analytics"
+          onClick={() => { if (isMobile) setDrawerOpen(false); }}
+          className={({ isActive }) =>
+            `w-full flex items-center gap-2 px-2 py-1.5 rounded-md text-sm hover:bg-sidebar-accent/60 text-sidebar-foreground ${
+              isActive ? 'bg-sidebar-accent text-sidebar-accent-foreground' : ''
+            }`
+          }
+          aria-label="Token Analytics"
+        >
+          <BarChart3 className="size-3.5 shrink-0 opacity-70" />
+          <span className="flex-1 text-left">Token Analytics</span>
+        </NavLink>
+
+        {/* v1.9: bottom-pinned Settings button. In a session, opens/focuses the
+            workspace settings pane via the sessionEvents bus (Session.tsx owns
+            the panesHook). Outside a session there's no workspace to mount the
+            pane in, so we navigate to /settings (themes page) instead. */}
         <button
           type="button"
           onClick={() => {

apps/web/src/components/RightRail.tsx

@@ -8,6 +8,7 @@ import { useRightRailDrawer } from '@/hooks/useRightRailDrawer';
 import { useViewport } from '@/hooks/useViewport';
 import { useProjectGit } from '@/hooks/useProjectGit';
 import { useGitDiff } from '@/hooks/useGitDiff';
+import { useDiffPreferences } from '@/hooks/useDiffPreferences';
 import { FileViewerOverlay } from '@/components/FileViewerOverlay';
 import { GitDiffView } from '@/components/GitDiffView';
 import { Input } from '@/components/ui/input';
@@ -90,6 +91,15 @@ export function RightRail({ projectId, sessionId }: Props) {
   const [creating, setCreating] = useState(false);
   const [createError, setCreateError] = useState<string | null>(null);
 
+  // Diff toolbar state (integration with expandedPaths pending)
+  const { preferences: diffPrefs, updatePreferences: updateDiffPrefs } = useDiffPreferences();
+
+  // File editing state
+  const [editingFile, setEditingFile] = useState<string | null>(null);
+  const [editContent, setEditContent] = useState('');
+  const [editLoading, setEditLoading] = useState(false);
+  const [editError, setEditError] = useState<string | null>(null);
+
   const openNewFile = useCallback(() => {
     setNewFilePath('');
     setNewFileContent('');
@@ -167,6 +177,44 @@ export function RightRail({ projectId, sessionId }: Props) {
     });
   }
 
+  async function startEdit(path: string) {
+    setEditingFile(path);
+    setEditLoading(true);
+    setEditError(null);
+    try {
+      const result = await api.projects.viewFile(projectId, path);
+      setEditContent(result.content);
+    } catch {
+      setEditError('Failed to load file');
+      setEditingFile(null);
+    } finally {
+      setEditLoading(false);
+    }
+  }
+
+  async function saveEdit() {
+    if (!editingFile) return;
+    try {
+      await api.projects.writeFile(projectId, editingFile, editContent);
+      setEditingFile(null);
+      setEditContent('');
+      sessionEvents.emit({ type: 'git_diff_refresh' });
+    } catch {
+      setEditError('Failed to save file');
+    }
+  }
+
+  function cancelEdit() {
+    setEditingFile(null);
+    setEditContent('');
+    setEditError(null);
+  }
+
+  // Cancel edit when switching tabs
+  useEffect(() => {
+    if (tab !== 'files') cancelEdit();
+  }, [tab]);
+
   async function openFile(path: string) {
     try {
       const result = await api.projects.viewFile(projectId, path);
@@ -323,6 +371,30 @@ export function RightRail({ projectId, sessionId }: Props) {
                 ) : (
                   <div className="text-xs text-muted-foreground px-2 py-4 text-center">No matches</div>
                 )
+              ) : editingFile ? (
+                <div className="flex flex-col flex-1 overflow-hidden p-2 gap-2">
+                  <div className="text-xs font-mono truncate text-muted-foreground">{editingFile}</div>
+                  {editLoading ? (
+                    <div className="flex-1 flex items-center justify-center text-xs text-muted-foreground">Loading...</div>
+                  ) : (
+                    <>
+                      <textarea
+                        value={editContent}
+                        onChange={(e) => setEditContent(e.target.value)}
+                        className="flex-1 font-mono text-xs p-2 rounded border bg-background resize-none outline-none focus:ring-1 focus:ring-ring"
+                        onKeyDown={(e) => {
+                          if ((e.metaKey || e.ctrlKey) && e.key === 'Enter') saveEdit();
+                          if (e.key === 'Escape') cancelEdit();
+                        }}
+                      />
+                      {editError && <p className="text-xs text-destructive">{editError}</p>}
+                      <div className="flex items-center gap-2 justify-end">
+                        <button type="button" onClick={cancelEdit} className="text-xs px-2 py-1 rounded border hover:bg-muted">Cancel</button>
+                        <button type="button" onClick={saveEdit} className="text-xs px-3 py-1 rounded bg-primary text-primary-foreground hover:bg-primary/90">Save</button>
+                      </div>
+                    </>
+                  )}
+                </div>
               ) : (
                 <TreeLevel
                   parentPath=""
@@ -332,6 +404,7 @@ export function RightRail({ projectId, sessionId }: Props) {
                   depth={0}
                   onToggleDir={toggleDir}
                   onSelectFile={(path) => void openFile(path)}
+                  onEditFile={startEdit}
                 />
               )}
             </div>
@@ -345,6 +418,7 @@ export function RightRail({ projectId, sessionId }: Props) {
             loading={gitLoading}
             error={gitError}
             mode={gitMode}
+            sessionId={sessionId}
             onSelectMode={selectMode}
             onRefresh={refreshDiff}
             mutating={gitMutating}
@@ -355,6 +429,12 @@ export function RightRail({ projectId, sessionId }: Props) {
             onDiscard={gitDiscard}
             modeSuggestion={gitModeSuggestion}
             pendingCount={pendingCount}
+            layout={diffPrefs.layout}
+            wrapLines={diffPrefs.wrapLines}
+            hideWhitespace={diffPrefs.hideWhitespace}
+            onLayoutChange={(layout) => updateDiffPrefs({ layout })}
+            onWrapLinesChange={(wrapLines) => updateDiffPrefs({ wrapLines })}
+            onHideWhitespaceChange={(hideWhitespace) => updateDiffPrefs({ hideWhitespace })}
           />
         )}
       </aside>
@@ -421,9 +501,10 @@ interface TreeLevelProps {
   depth: number;
   onToggleDir: (dirPath: string) => void;
   onSelectFile: (path: string) => void;
+  onEditFile?: (path: string) => void;
 }
 
-function TreeLevel({ parentPath, entries, cache, expanded, depth, onToggleDir, onSelectFile }: TreeLevelProps) {
+function TreeLevel({ parentPath, entries, cache, expanded, depth, onToggleDir, onSelectFile, onEditFile }: TreeLevelProps) {
   const sorted = useMemo(() => {
     const copy = [...entries];
     copy.sort((a, b) => {
@@ -447,6 +528,9 @@ function TreeLevel({ parentPath, entries, cache, expanded, depth, onToggleDir, o
                 if (entry.kind === 'dir') onToggleDir(fullPath);
                 else onSelectFile(fullPath);
               }}
+              onDoubleClick={() => {
+                if (entry.kind === 'file') onEditFile?.(fullPath);
+              }}
             >
               {entry.kind === 'dir' ? (
                 isExpanded ? <ChevronDown size={10} className="shrink-0" /> : <ChevronRight size={10} className="shrink-0" />
@@ -469,6 +553,7 @@ function TreeLevel({ parentPath, entries, cache, expanded, depth, onToggleDir, o
                 depth={depth + 1}
                 onToggleDir={onToggleDir}
                 onSelectFile={onSelectFile}
+                onEditFile={onEditFile}
               />
             )}
           </li>

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

@@ -423,6 +423,7 @@ export function ArenaPane({ state, onClose }: Props) {
               duration_ms: null,
               tokens_per_sec: null,
               cost_tokens: null,
+              token_breakdown: null,
               result_path: null,
               error: null,
               created_at: new Date().toISOString(),

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

@@ -1,5 +1,5 @@
 import { useEffect, useState } from 'react';
-import { Archive, FolderOpen, Maximize2, Minimize2, Trash2, X } from 'lucide-react';
+import { Archive, FolderOpen, Maximize2, Minimize2, Trash2, X, Database, Zap, Clock, BarChart3, Folder } from 'lucide-react';
 import { toast } from 'sonner';
 import { api } from '@/api/client';
 import type { Project, Session } from '@/api/types';
@@ -15,10 +15,11 @@ import {
 } from '@/components/ui/dialog';
 import { ModelPicker } from '@/components/ModelPicker';
 import { ThemePicker } from '@/components/ThemePicker';
+import { InferenceSettings as InferenceSettingsComponent } from '@/components/InferenceSettings';
 import { ProvidersSettings } from '@/components/coder/ProvidersSettings';
 import { cn } from '@/lib/utils';
 
-type Section = 'session' | 'project' | 'theme' | 'providers';
+type Section = 'session' | 'project' | 'theme' | 'providers' | 'inference';
 
 interface Props {
   session: Session;
@@ -74,7 +75,7 @@ export function SettingsPane({ session, project, maximized, onToggleMaximize, on
     <div className="flex flex-col h-full min-h-0">
       <div className="flex items-center gap-2 border-b border-border bg-muted/20 px-3 py-1.5 shrink-0">
         <div className="flex items-center gap-1 flex-1 min-w-0">
-          {(['session', 'project', 'theme', 'providers'] as const).map((s) => (
+          {(['session', 'project', 'theme', 'providers', 'inference'] as const).map((s) => (
             <button
               key={s}
               type="button"
@@ -118,6 +119,7 @@ export function SettingsPane({ session, project, maximized, onToggleMaximize, on
           {activeSection === 'project' && <ProjectSection project={project} />}
           {activeSection === 'theme' && <ThemePicker />}
           {activeSection === 'providers' && <ProvidersSettings />}
+          {activeSection === 'inference' && <InferenceSettingsComponent />}
         </div>
       </div>
     </div>
@@ -599,3 +601,249 @@ function ProjectSection({ project }: { project: Project }) {
     </div>
   );
 }
+
+interface InferenceSettings {
+  cacheTypeK: string;
+  cacheReuse: number;
+  specType: string;
+  ctxCheckpoints: number;
+  sleepIdleSeconds: number;
+  metrics: boolean;
+  slotSavePath: string;
+}
+
+const INFERENCE_DEFAULTS: InferenceSettings = {
+  cacheTypeK: 'q4_0',
+  cacheReuse: 256,
+  specType: 'ngram-mod',
+  ctxCheckpoints: 32,
+  sleepIdleSeconds: 600,
+  metrics: true,
+  slotSavePath: '/tmp/llama-slots',
+};
+
+const STORAGE_KEY = 'boocode-inference-settings';
+
+function InferenceSettings() {
+  const [settings, setSettings] = useState<InferenceSettings>(INFERENCE_DEFAULTS);
+  const [saving, setSaving] = useState(false);
+  const [loaded, setLoaded] = useState(false);
+
+  useEffect(() => {
+    try {
+      const stored = localStorage.getItem(STORAGE_KEY);
+      if (stored) {
+        const parsed = JSON.parse(stored);
+        setSettings({ ...INFERENCE_DEFAULTS, ...parsed });
+      }
+    } catch { /* ignore corrupt storage */ }
+    setLoaded(true);
+  }, []);
+
+  const dirty = loaded && JSON.stringify(settings) !== (() => {
+    try {
+      const stored = localStorage.getItem(STORAGE_KEY);
+      return stored ? JSON.stringify({ ...INFERENCE_DEFAULTS, ...JSON.parse(stored) }) : JSON.stringify(INFERENCE_DEFAULTS);
+    } catch { return JSON.stringify(INFERENCE_DEFAULTS); }
+  })();
+
+  function update<K extends keyof InferenceSettings>(key: K, value: InferenceSettings[K]) {
+    setSettings(prev => ({ ...prev, [key]: value }));
+  }
+
+  async function save() {
+    if (saving) return;
+    setSaving(true);
+    try {
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(settings));
+      // Simulate API delay
+      await new Promise(r => setTimeout(r, 300));
+      toast.success('Inference settings saved. Restart sidecar to apply.');
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : 'save failed');
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  async function resetDefaults() {
+    if (saving) return;
+    setSaving(true);
+    try {
+      setSettings(INFERENCE_DEFAULTS);
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(INFERENCE_DEFAULTS));
+      await new Promise(r => setTimeout(r, 300));
+      toast.success('Reset to defaults');
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : 'reset failed');
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  if (!loaded) return null;
+
+  return (
+    <div className="space-y-6">
+      <div className="space-y-1.5">
+        <div className="flex items-center gap-2">
+          <Database className="size-3.5 text-muted-foreground" />
+          <label htmlFor="cache-type-k" className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+            KV Cache Quantization
+          </label>
+        </div>
+        <select
+          id="cache-type-k"
+          value={settings.cacheTypeK}
+          onChange={(e) => update('cacheTypeK', e.target.value)}
+          className="w-full bg-background border border-border rounded px-2 py-1.5 text-sm outline-none focus:border-ring"
+        >
+          <option value="f32">f32 — 32-bit (max quality)</option>
+          <option value="f16">f16 — 16-bit (balanced)</option>
+          <option value="q8_0">q8_0 — 8-bit (efficient)</option>
+          <option value="q4_0">q4_0 — 4-bit (max efficiency)</option>
+        </select>
+        <p className="text-xs text-muted-foreground italic">
+          Compresses the attention cache. Lower = less VRAM usage.
+        </p>
+      </div>
+
+      <div className="space-y-1.5">
+        <div className="flex items-center gap-2">
+          <Zap className="size-3.5 text-muted-foreground" />
+          <label htmlFor="cache-reuse" className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+            Cache Reuse (Prompt Caching)
+          </label>
+        </div>
+        <input
+          id="cache-reuse"
+          type="number"
+          min={0}
+          step={64}
+          value={settings.cacheReuse}
+          onChange={(e) => update('cacheReuse', parseInt(e.target.value) || 0)}
+          className="w-full bg-background border border-border rounded px-2 py-1.5 text-sm outline-none focus:border-ring"
+        />
+        <p className="text-xs text-muted-foreground italic">
+          Minimum chunk size in tokens to reuse across turns. 0 = disabled.
+        </p>
+      </div>
+
+      <div className="space-y-1.5">
+        <div className="flex items-center gap-2">
+          <Zap className="size-3.5 text-muted-foreground" />
+          <label htmlFor="spec-type" className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+            Speculative Decoding
+          </label>
+        </div>
+        <select
+          id="spec-type"
+          value={settings.specType}
+          onChange={(e) => update('specType', e.target.value)}
+          className="w-full bg-background border border-border rounded px-2 py-1.5 text-sm outline-none focus:border-ring"
+        >
+          <option value="off">Off</option>
+          <option value="ngram-mod">ngram-mod — Lightweight (~16MB, no draft model)</option>
+          <option value="draft-simple">draft-simple — Requires separate draft model</option>
+        </select>
+        <p className="text-xs text-muted-foreground italic">
+          Predicts tokens ahead using a small model. Main model verifies in batch for 2-3x speedup.
+        </p>
+      </div>
+
+      <div className="space-y-1.5">
+        <div className="flex items-center gap-2">
+          <Database className="size-3.5 text-muted-foreground" />
+          <label htmlFor="ctx-checkpoints" className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+            Context Checkpoints
+          </label>
+        </div>
+        <input
+          id="ctx-checkpoints"
+          type="number"
+          min={0}
+          max={256}
+          value={settings.ctxCheckpoints}
+          onChange={(e) => update('ctxCheckpoints', parseInt(e.target.value) || 0)}
+          className="w-full bg-background border border-border rounded px-2 py-1.5 text-sm outline-none focus:border-ring"
+        />
+        <p className="text-xs text-muted-foreground italic">
+          Max checkpoints per slot. 0 = disabled.
+        </p>
+      </div>
+
+      <div className="space-y-1.5">
+        <div className="flex items-center gap-2">
+          <Clock className="size-3.5 text-muted-foreground" />
+          <label htmlFor="sleep-idle" className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+            Sleep Idle
+          </label>
+        </div>
+        <input
+          id="sleep-idle"
+          type="number"
+          min={-1}
+          step={60}
+          value={settings.sleepIdleSeconds}
+          onChange={(e) => update('sleepIdleSeconds', parseInt(e.target.value) || -1)}
+          className="w-full bg-background border border-border rounded px-2 py-1.5 text-sm outline-none focus:border-ring"
+        />
+        <p className="text-xs text-muted-foreground italic">
+          Auto-sleep after N seconds idle. -1 = disabled.
+        </p>
+      </div>
+
+      <div className="space-y-1.5">
+        <div className="flex items-center justify-between gap-3">
+          <div className="flex items-center gap-2">
+            <BarChart3 className="size-3.5 text-muted-foreground" />
+            <label htmlFor="metrics" className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+              Metrics Endpoint
+            </label>
+          </div>
+          <Switch
+            id="metrics"
+            checked={settings.metrics}
+            onCheckedChange={(v) => update('metrics', v)}
+          />
+        </div>
+        <p className="text-xs text-muted-foreground italic">
+          Exposes Prometheus /metrics endpoint for observability.
+        </p>
+      </div>
+
+      <div className="space-y-1.5">
+        <div className="flex items-center gap-2">
+          <Folder className="size-3.5 text-muted-foreground" />
+          <label htmlFor="slot-save-path" className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+            Slot Save Path
+          </label>
+        </div>
+        <input
+          id="slot-save-path"
+          type="text"
+          value={settings.slotSavePath}
+          onChange={(e) => update('slotSavePath', e.target.value)}
+          className="w-full bg-background border border-border rounded px-2 py-1.5 text-sm font-mono outline-none focus:border-ring"
+        />
+        <p className="text-xs text-muted-foreground italic">
+          Directory for disk-persistent KV cache. Must be writable.
+        </p>
+      </div>
+
+      <div className="flex justify-between gap-2 border-t pt-4">
+        <Button variant="outline" onClick={() => void resetDefaults()} disabled={saving}>
+          Reset to defaults
+        </Button>
+        <Button onClick={() => void save()} disabled={!dirty || saving}>
+          {saving ? 'Saving…' : 'Save'}
+        </Button>
+      </div>
+
+      <p className="text-xs text-muted-foreground border-t pt-4">
+        Changes apply to new llama-server processes. Restart the sidecar to apply.
+        These settings are stored locally in your browser.
+      </p>
+    </div>
+  );
+}

apps/web/src/hooks/useDiffPreferences.ts

@@ -0,0 +1,68 @@
+import { useCallback, useEffect, useState } from 'react';
+
+export interface DiffPreferences {
+  layout: 'unified' | 'split';
+  wrapLines: boolean;
+  hideWhitespace: boolean;
+}
+
+const DEFAULT_PREFERENCES: DiffPreferences = {
+  layout: 'unified',
+  wrapLines: false,
+  hideWhitespace: false,
+};
+
+const STORAGE_KEY = 'boocode.diff.preferences';
+
+function loadPreferences(): DiffPreferences {
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored) {
+      const parsed = JSON.parse(stored) as Partial<DiffPreferences>;
+      return {
+        layout: parsed.layout ?? DEFAULT_PREFERENCES.layout,
+        wrapLines: parsed.wrapLines ?? DEFAULT_PREFERENCES.wrapLines,
+        hideWhitespace: parsed.hideWhitespace ?? DEFAULT_PREFERENCES.hideWhitespace,
+      };
+    }
+  } catch {
+    // ignore parse errors
+  }
+  return DEFAULT_PREFERENCES;
+}
+
+function savePreferences(prefs: DiffPreferences): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(prefs));
+  } catch {
+    // ignore storage errors
+  }
+}
+
+export function useDiffPreferences(): {
+  preferences: DiffPreferences;
+  updatePreferences: (updates: Partial<DiffPreferences>) => void;
+  resetPreferences: () => void;
+} {
+  const [preferences, setPreferences] = useState<DiffPreferences>(loadPreferences);
+
+  // Sync from localStorage on mount (handles multi-tab changes if we add a storage listener later)
+  useEffect(() => {
+    setPreferences(loadPreferences());
+  }, []);
+
+  const updatePreferences = useCallback((updates: Partial<DiffPreferences>) => {
+    setPreferences((prev) => {
+      const next = { ...prev, ...updates };
+      savePreferences(next);
+      return next;
+    });
+  }, []);
+
+  const resetPreferences = useCallback(() => {
+    setPreferences(DEFAULT_PREFERENCES);
+    savePreferences(DEFAULT_PREFERENCES);
+  }, []);
+
+  return { preferences, updatePreferences, resetPreferences };
+}

apps/web/src/hooks/useGitDiff.ts

@@ -3,7 +3,7 @@ import { api } from '@/api/client';
 import type { GitDiffMode, GitDiffResult, GitDiscardFileInfo } from '@/api/types';
 import { sessionEvents } from './sessionEvents';
 
-export function useGitDiff(projectId: string | null | undefined) {
+export function useGitDiff(projectId: string | null | undefined, hideWhitespace = false) {
   const [mode, setMode] = useState<GitDiffMode>('uncommitted');
   const [pinned, setPinned] = useState(false);
   const [result, setResult] = useState<GitDiffResult | null>(null);
@@ -23,7 +23,7 @@ export function useGitDiff(projectId: string | null | undefined) {
     // FIX 1: when not pinned, omit mode param so the server auto-selects based on
     // dirty state (dirty → uncommitted, clean → committed).
     api.projects
-      .gitDiff(projectId, pinned ? mode : null)
+      .gitDiff(projectId, pinned ? mode : null, hideWhitespace)
       .then((r) => {
         if (!pinned) {
           setMode(r.mode);
@@ -43,7 +43,7 @@ export function useGitDiff(projectId: string | null | undefined) {
         inFlightRef.current = false;
         setLoading(false);
       });
-  }, [projectId, mode, pinned]);
+  }, [projectId, mode, pinned, hideWhitespace]);
 
   // Re-run refresh when mode changes (user pinned a new mode).
   useEffect(() => {
@@ -52,7 +52,7 @@ export function useGitDiff(projectId: string | null | undefined) {
       return;
     }
     refresh();
-  }, [projectId, mode]); // eslint-disable-line react-hooks/exhaustive-deps
+  }, [projectId, mode, hideWhitespace]); // eslint-disable-line react-hooks/exhaustive-deps
 
   // Subscribe to git_diff_refresh events (tab open, message_complete, manual).
   useEffect(() => {

apps/web/src/pages/Analytics.tsx

@@ -0,0 +1,454 @@
+import { useEffect, useState } from 'react';
+import { ArrowLeft, BarChart3, Wifi, Wrench, Layers } from 'lucide-react';
+import { useNavigate } from 'react-router-dom';
+import { api } from '@/api/client';
+import type {
+  AnalyticsSummary,
+  SessionAnalyticsRow,
+  ToolCostStat,
+  ContextWindowStats,
+  TokenBreakdownAgg,
+} from '@/api/types';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { Button } from '@/components/ui/button';
+import { cn } from '@/lib/utils';
+
+// --- Independent section data fetcher ---
+// Each section manages its own loading/error/data state so one failure doesn't
+// block the rest of the page.
+
+function useFetch<T>(fetcher: () => Promise<T>): {
+  data: T | null;
+  loading: boolean;
+  error: string | null;
+  retry: () => void;
+} {
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  function load() {
+    setLoading(true);
+    setError(null);
+    fetcher()
+      .then(setData)
+      .catch((err: unknown) => {
+        setError(err instanceof Error ? err.message : 'failed to load data');
+      })
+      .finally(() => setLoading(false));
+  }
+
+  useEffect(() => { load(); }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  return { data, loading, error, retry: load };
+}
+
+// --- Skeleton pulse placeholder ---
+function SkeletonBar({ className }: { className?: string }) {
+  return <div className={cn('animate-pulse rounded bg-muted/40', className)} />;
+}
+
+// --- Number formatting ---
+function formatNumber(n: number | null | undefined): string {
+  if (n == null) return '—';
+  return n.toLocaleString();
+}
+
+function formatCost(n: number | null | undefined): string {
+  if (n == null) return '—';
+  if (n < 0.001) return `$${(n * 1000).toFixed(2)}m`;
+  if (n < 0.01) return `$${n.toFixed(4)}`;
+  return `$${n.toFixed(3)}`;
+}
+
+function formatPct(n: number | null | undefined): string {
+  if (n == null) return '—';
+  return `${(n * 100).toFixed(1)}%`;
+}
+
+function formatDate(iso: string | null | undefined): string {
+  if (!iso) return '—';
+  return new Date(iso).toLocaleDateString(undefined, {
+    month: 'short',
+    day: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+  });
+}
+
+// --- Summary Cards ---
+function SummaryCards({ summary }: { summary: AnalyticsSummary }) {
+  const cards = [
+    {
+      label: 'Total Input Tokens',
+      value: formatNumber(summary.total_input_tokens),
+      icon: BarChart3,
+      color: 'text-blue-500',
+    },
+    {
+      label: 'Total Output Tokens',
+      value: formatNumber(summary.total_output_tokens),
+      icon: BarChart3,
+      color: 'text-green-500',
+    },
+    {
+      label: 'Total Cost',
+      value: formatCost(summary.total_cost),
+      icon: Wifi,
+      color: 'text-amber-500',
+    },
+    {
+      label: 'Sessions Tracked',
+      value: formatNumber(summary.session_count),
+      icon: Layers,
+      color: 'text-purple-500',
+    },
+  ];
+
+  return (
+    <div className="grid grid-cols-2 md:grid-cols-4 gap-4">
+      {cards.map((c) => (
+        <Card key={c.label} size="sm">
+          <CardContent className="flex items-start gap-3 pt-3">
+            <c.icon className={cn('size-5 shrink-0 mt-0.5', c.color)} />
+            <div className="min-w-0">
+              <div className="text-lg font-semibold tabular-nums">{c.value}</div>
+              <div className="text-xs text-muted-foreground mt-0.5">{c.label}</div>
+            </div>
+          </CardContent>
+        </Card>
+      ))}
+    </div>
+  );
+}
+
+function SummaryCardsSkeleton() {
+  return (
+    <div className="grid grid-cols-2 md:grid-cols-4 gap-4">
+      {[0, 1, 2, 3].map((i) => (
+        <Card key={i} size="sm">
+          <CardContent className="pt-3">
+            <SkeletonBar className="h-5 w-20 mb-2" />
+            <SkeletonBar className="h-3 w-24" />
+          </CardContent>
+        </Card>
+      ))}
+    </div>
+  );
+}
+
+// --- Section wrappers ---
+function SectionCard({
+  title,
+  loading,
+  error,
+  onRetry,
+  children,
+}: {
+  title: string;
+  loading: boolean;
+  error: string | null;
+  onRetry: () => void;
+  children: React.ReactNode;
+}) {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>{title}</CardTitle>
+      </CardHeader>
+      <CardContent>
+        {loading ? (
+          <div className="space-y-2">
+            <SkeletonBar className="h-4 w-full" />
+            <SkeletonBar className="h-4 w-3/4" />
+            <SkeletonBar className="h-4 w-1/2" />
+          </div>
+        ) : error ? (
+          <div className="flex items-center gap-3 text-sm">
+            <span className="text-destructive">{error}</span>
+            <Button size="sm" variant="outline" onClick={onRetry}>
+              Retry
+            </Button>
+          </div>
+        ) : (
+          children
+        )}
+      </CardContent>
+    </Card>
+  );
+}
+
+function EmptyState({ message }: { message: string }) {
+  return <p className="text-sm text-muted-foreground py-2">{message}</p>;
+}
+
+// --- Per-Session Token Table ---
+function SessionTable({ sessions }: { sessions: SessionAnalyticsRow[] }) {
+  if (sessions.length === 0) {
+    return <EmptyState message="No session token data available yet. Token data is collected as agent sessions run." />;
+  }
+
+  return (
+    <div className="overflow-x-auto">
+      <table className="w-full text-sm">
+        <thead>
+          <tr className="border-b text-left text-muted-foreground text-xs uppercase tracking-wide">
+            <th className="py-2 pr-4 font-medium">Session</th>
+            <th className="py-2 pr-4 font-medium tabular-nums text-right">Input</th>
+            <th className="py-2 pr-4 font-medium tabular-nums text-right">Output</th>
+            <th className="py-2 pr-4 font-medium tabular-nums text-right">Cost</th>
+            <th className="py-2 font-medium tabular-nums text-right">Last Active</th>
+          </tr>
+        </thead>
+        <tbody>
+          {sessions.map((s) => (
+            <tr key={s.session_id} className="border-b last:border-0 hover:bg-muted/30">
+              <td className="py-2 pr-4 truncate max-w-[200px]" title={s.session_name}>
+                {s.session_name || 'Untitled'}
+              </td>
+              <td className="py-2 pr-4 tabular-nums text-right">{formatNumber(s.total_input_tokens)}</td>
+              <td className="py-2 pr-4 tabular-nums text-right">{formatNumber(s.total_output_tokens)}</td>
+              <td className="py-2 pr-4 tabular-nums text-right">{formatCost(s.total_cost)}</td>
+              <td className="py-2 tabular-nums text-right text-muted-foreground">{formatDate(s.last_active_at)}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+
+// --- Per-Tool Cost Table ---
+function ToolTable({ stats }: { stats: ToolCostStat[] }) {
+  if (stats.length === 0) {
+    return <EmptyState message="No tool cost data available yet. Stats accumulate after tool calls are made." />;
+  }
+
+  return (
+    <div className="overflow-x-auto">
+      <table className="w-full text-sm">
+        <thead>
+          <tr className="border-b text-left text-muted-foreground text-xs uppercase tracking-wide">
+            <th className="py-2 pr-4 font-medium">Tool</th>
+            <th className="py-2 pr-4 font-medium tabular-nums text-right">Calls</th>
+            <th className="py-2 pr-4 font-medium tabular-nums text-right">Avg Prompt</th>
+            <th className="py-2 pr-4 font-medium tabular-nums text-right">Avg Completion</th>
+            <th className="py-2 font-medium tabular-nums text-right">Avg Total</th>
+          </tr>
+        </thead>
+        <tbody>
+          {stats.map((t) => (
+            <tr key={t.tool_name} className="border-b last:border-0 hover:bg-muted/30">
+              <td className="py-2 pr-4 flex items-center gap-2">
+                <Wrench className="size-3.5 shrink-0 text-muted-foreground" />
+                <span className="truncate max-w-[200px]" title={t.tool_name}>{t.tool_name}</span>
+              </td>
+              <td className="py-2 pr-4 tabular-nums text-right">{t.n_calls}</td>
+              <td className="py-2 pr-4 tabular-nums text-right">{formatNumber(t.mean_prompt_tokens)}</td>
+              <td className="py-2 pr-4 tabular-nums text-right">{formatNumber(t.mean_completion_tokens)}</td>
+              <td className="py-2 tabular-nums text-right">{formatNumber(t.mean_prompt_tokens + t.mean_completion_tokens)}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+
+// --- Context Window Utilization ---
+function ContextSection({ stats }: { stats: ContextWindowStats }) {
+  if (stats.message_count === 0) {
+    return <EmptyState message="No context window data available yet. Data is captured during inference." />;
+  }
+
+  return (
+    <div className="grid grid-cols-1 sm:grid-cols-3 gap-4">
+      <div>
+        <div className="text-xs text-muted-foreground">Avg Context Used</div>
+        <div className="text-lg font-semibold tabular-nums mt-1">{formatNumber(Math.round(stats.avg_ctx_used ?? 0))}</div>
+      </div>
+      <div>
+        <div className="text-xs text-muted-foreground">Avg Context Limit</div>
+        <div className="text-lg font-semibold tabular-nums mt-1">{formatNumber(Math.round(stats.avg_ctx_max ?? 0))}</div>
+      </div>
+      <div>
+        <div className="text-xs text-muted-foreground">Avg Utilization</div>
+        <div className="text-lg font-semibold tabular-nums mt-1">{formatPct(stats.avg_utilization_pct)}</div>
+      </div>
+      <div className="sm:col-span-3">
+        <div className="text-xs text-muted-foreground mb-1">Based on {formatNumber(stats.message_count)} completed assistant messages</div>
+        <div className="h-2 rounded-full bg-muted overflow-hidden">
+          <div
+            className="h-full rounded-full bg-primary transition-all"
+            style={{
+              width: stats.avg_utilization_pct != null
+                ? `${Math.min(stats.avg_utilization_pct * 100, 100)}%`
+                : '0%',
+            }}
+          />
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// --- Token Category Breakdown (CSS stacked bar) ---
+const CATEGORY_COLORS: Record<string, string> = {
+  system: 'bg-blue-500',
+  user: 'bg-green-500',
+  assistant: 'bg-amber-500',
+  tools: 'bg-purple-500',
+  reasoning: 'bg-rose-500',
+};
+
+const CATEGORY_LABELS: Record<string, string> = {
+  system: 'System',
+  user: 'User',
+  assistant: 'Assistant',
+  tools: 'Tools',
+  reasoning: 'Reasoning',
+};
+
+function TokenBreakdownSection({ categories }: { categories: TokenBreakdownAgg[] }) {
+  if (categories.length === 0) {
+    return <EmptyState message="No token breakdown data available. Breakdown is captured for arena contestants and certain task types." />;
+  }
+
+  const total = categories.reduce((sum, c) => sum + c.total_tokens, 0);
+  if (total === 0) return <EmptyState message="Token breakdown totals are zero." />;
+
+  // Sort in a consistent order
+  const order = ['system', 'user', 'assistant', 'tools', 'reasoning'];
+  const sorted = [...categories].sort(
+    (a, b) => order.indexOf(a.category) - order.indexOf(b.category),
+  );
+
+  return (
+    <div className="space-y-3">
+      <div className="h-4 rounded-full bg-muted overflow-hidden flex">
+        {sorted.map((c) => {
+          const pct = (c.total_tokens / total) * 100;
+          if (pct < 1) return null;
+          return (
+            <div
+              key={c.category}
+              className={cn('h-full first:rounded-l-full last:rounded-r-full', CATEGORY_COLORS[c.category] ?? 'bg-gray-400')}
+              style={{ width: `${pct}%` }}
+              title={`${CATEGORY_LABELS[c.category] ?? c.category}: ${formatNumber(c.total_tokens)} (${pct.toFixed(1)}%)`}
+            />
+          );
+        })}
+      </div>
+      <div className="flex flex-wrap gap-x-4 gap-y-1 text-xs">
+        {sorted.map((c) => {
+          const pct = (c.total_tokens / total) * 100;
+          return (
+            <div key={c.category} className="flex items-center gap-1.5">
+              <span className={cn('size-2.5 rounded-sm', CATEGORY_COLORS[c.category] ?? 'bg-gray-400')} />
+              <span className="text-muted-foreground">{CATEGORY_LABELS[c.category] ?? c.category}</span>
+              <span className="font-medium tabular-nums">{pct.toFixed(1)}%</span>
+              <span className="text-muted-foreground tabular-nums">({formatNumber(c.total_tokens)})</span>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+// --- Main Page ---
+export function Analytics() {
+  const navigate = useNavigate();
+
+  const summary = useFetch(() => api.analytics.summary());
+  const sessions = useFetch(() => api.analytics.sessions().then((r) => r.sessions));
+  const tools = useFetch(() => api.tools.costStats().then((r) => r.stats));
+  const context = useFetch(() => api.analytics.context());
+  const breakdown = useFetch(() => api.analytics.tokenBreakdown().then((r) => r.categories));
+
+  function handleBack() {
+    if (window.history.length > 1) {
+      navigate(-1);
+    } else {
+      navigate('/');
+    }
+  }
+
+  return (
+    <div className="flex-1 overflow-y-auto">
+      <div className="max-w-[1000px] mx-auto w-full px-6 py-6 space-y-8">
+        <header className="space-y-2">
+          <button
+            type="button"
+            onClick={handleBack}
+            className="inline-flex items-center gap-1 text-sm text-muted-foreground hover:text-foreground -ml-1 px-1 py-0.5 rounded"
+            aria-label="Back"
+          >
+            <ArrowLeft className="size-4" />
+            <span>Back</span>
+          </button>
+          <div>
+            <h1 className="text-xl font-semibold">Token Analytics</h1>
+            <p className="text-sm text-muted-foreground mt-1">
+              Aggregate token usage, cost, and context window data across all sessions.
+            </p>
+          </div>
+        </header>
+
+        {/* Summary Cards */}
+        {summary.loading ? (
+          <SummaryCardsSkeleton />
+        ) : summary.error ? (
+          <div className="flex items-center gap-3 text-sm">
+            <span className="text-destructive">{summary.error}</span>
+            <Button size="sm" variant="outline" onClick={summary.retry}>
+              Retry
+            </Button>
+          </div>
+        ) : summary.data ? (
+          <SummaryCards summary={summary.data} />
+        ) : null}
+
+        {/* Per-Session Token Breakdown */}
+        <SectionCard
+          title="Per-Session Token Usage"
+          loading={sessions.loading}
+          error={sessions.error}
+          onRetry={sessions.retry}
+        >
+          {sessions.data && <SessionTable sessions={sessions.data} />}
+        </SectionCard>
+
+        {/* Per-Tool Cost Breakdown */}
+        <SectionCard
+          title="Per-Tool Token Cost"
+          loading={tools.loading}
+          error={tools.error}
+          onRetry={tools.retry}
+        >
+          {tools.data && <ToolTable stats={tools.data} />}
+        </SectionCard>
+
+        {/* Context Window Utilization */}
+        <SectionCard
+          title="Context Window Utilization"
+          loading={context.loading}
+          error={context.error}
+          onRetry={context.retry}
+        >
+          {context.data && <ContextSection stats={context.data} />}
+        </SectionCard>
+
+        {/* Token Category Breakdown */}
+        <SectionCard
+          title="Token Breakdown by Category"
+          loading={breakdown.loading}
+          error={breakdown.error}
+          onRetry={breakdown.retry}
+        >
+          {breakdown.data && <TokenBreakdownSection categories={breakdown.data} />}
+        </SectionCard>
+      </div>
+    </div>
+  );
+}

apps/web/src/pages/Results.tsx

@@ -0,0 +1,510 @@
+import { useEffect, useMemo, useState } from 'react';
+import { ArrowLeft, Beaker, CheckCircle2, FileText, ScrollText, Swords, XCircle } from 'lucide-react';
+import { useNavigate } from 'react-router-dom';
+import { api } from '@/api/client';
+import type { BattleShape, FlowRunRow } from '@/api/types';
+import { Card, CardContent } from '@/components/ui/card';
+import { Button } from '@/components/ui/button';
+import { useSidebar } from '@/hooks/useSidebar';
+import { cn } from '@/lib/utils';
+
+// ─── Independent section data fetcher (same pattern as Analytics.tsx) ────────
+
+function useFetch<T>(fetcher: () => Promise<T>): {
+  data: T | null;
+  loading: boolean;
+  error: string | null;
+  retry: () => void;
+} {
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  function load() {
+    setLoading(true);
+    setError(null);
+    fetcher()
+      .then(setData)
+      .catch((err: unknown) => {
+        setError(err instanceof Error ? err.message : 'failed to load data');
+      })
+      .finally(() => setLoading(false));
+  }
+
+  useEffect(() => { load(); }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  return { data, loading, error, retry: load };
+}
+
+// ─── Skeleton ────────────────────────────────────────────────────────────────
+
+function SkeletonBar({ className }: { className?: string }) {
+  return <div className={cn('animate-pulse rounded bg-muted/40', className)} />;
+}
+
+// ─── Formatters ──────────────────────────────────────────────────────────────
+
+function formatDate(iso: string | null | undefined): string {
+  if (!iso) return '—';
+  return new Date(iso).toLocaleDateString(undefined, {
+    month: 'short',
+    day: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+  });
+}
+
+function formatDuration(startIso: string, endIso?: string | null): string {
+  const start = new Date(startIso).getTime();
+  const end = endIso ? new Date(endIso).getTime() : Date.now();
+  const ms = end - start;
+  if (ms < 0) return '—';
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m${String(s % 60).padStart(2, '0')}s`;
+  return `${Math.floor(s / 3600)}h${String(Math.floor((s % 3600) / 60)).padStart(2, '0')}m`;
+}
+
+function truncate(str: string, max: number): string {
+  if (str.length <= max) return str;
+  return str.slice(0, max) + '…';
+}
+
+// ─── Status dot (shared visual language with OrchestratorPane/ArenaPane) ──────
+
+type DotStatus = 'running' | 'completed' | 'failed' | 'cancelled' | 'pending';
+
+function StatusDot({ status }: { status: DotStatus }) {
+  if (status === 'running') {
+    return (
+      <span
+        aria-label="running"
+        className="inline-block w-2.5 h-2.5 rounded-full border-2 border-emerald-500 border-t-transparent animate-spin shrink-0"
+      />
+    );
+  }
+  const cls =
+    status === 'completed'
+      ? 'bg-emerald-500'
+      : status === 'failed'
+        ? 'bg-destructive'
+        : status === 'cancelled'
+          ? 'bg-muted-foreground/20'
+          : 'bg-muted-foreground/40'; // pending
+  return <span aria-label={status} className={cn('inline-block w-2 h-2 rounded-full shrink-0', cls)} />;
+}
+
+// ─── Tab bar ─────────────────────────────────────────────────────────────────
+
+type TabId = 'runs' | 'battles';
+
+function TabBar({ active, onChange }: { active: TabId; onChange: (t: TabId) => void }) {
+  return (
+    <div className="flex gap-1 border-b pb-px">
+      {[
+        { id: 'runs' as TabId, label: 'Analysis Runs', icon: FileText },
+        { id: 'battles' as TabId, label: 'Arena Battles', icon: Swords },
+      ].map((tab) => (
+        <button
+          key={tab.id}
+          type="button"
+          onClick={() => onChange(tab.id)}
+          className={cn(
+            'flex items-center gap-1.5 px-3 py-1.5 text-sm rounded-t-md border border-b-0 -mb-px transition-colors',
+            active === tab.id
+              ? 'bg-background border-border text-foreground'
+              : 'border-transparent text-muted-foreground hover:text-foreground hover:bg-muted/30',
+          )}
+        >
+          <tab.icon className="size-3.5" />
+          <span>{tab.label}</span>
+        </button>
+      ))}
+    </div>
+  );
+}
+
+// ─── Empty state ─────────────────────────────────────────────────────────────
+
+function EmptyState({ message }: { message: string }) {
+  return <p className="text-sm text-muted-foreground py-8 text-center">{message}</p>;
+}
+
+// ─── Project selector ────────────────────────────────────────────────────────
+
+function ProjectSelector({
+  projects,
+  value,
+  onChange,
+}: {
+  projects: Array<{ id: string; name: string }>;
+  value: string;
+  onChange: (id: string) => void;
+}) {
+  return (
+    <select
+      value={value}
+      onChange={(e) => onChange(e.target.value)}
+      className="text-sm bg-muted/30 border border-border rounded px-2 py-1 text-foreground"
+    >
+      {projects.map((p) => (
+        <option key={p.id} value={p.id}>
+          {p.name}
+        </option>
+      ))}
+    </select>
+  );
+}
+
+// ─── Analysis Runs tab ───────────────────────────────────────────────────────
+
+function AnalysisRunsTab({ projectId }: { projectId: string }) {
+  const { data, loading, error, retry } = useFetch(() => api.runs.list(projectId).then((r) => r.runs));
+
+  const [selectedRun, setSelectedRun] = useState<FlowRunRow | null>(null);
+
+  if (loading) {
+    return (
+      <div className="space-y-2 pt-4">
+        {[0, 1, 2, 3].map((i) => (
+          <SkeletonBar key={i} className="h-12 w-full" />
+        ))}
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className="flex items-center gap-3 text-sm pt-4">
+        <span className="text-destructive">{error}</span>
+        <Button size="sm" variant="outline" onClick={retry}>
+          Retry
+        </Button>
+      </div>
+    );
+  }
+
+  if (!data || data.length === 0) {
+    return <EmptyState message="No analysis runs yet. Start one from the Workflow button in any chat." />;
+  }
+
+  return (
+    <div className="pt-4 space-y-2">
+      {data.map((run) => (
+        <div key={run.id}>
+          <button
+            type="button"
+            onClick={() => setSelectedRun(selectedRun?.id === run.id ? null : run)}
+            className={cn(
+              'w-full flex items-center gap-3 px-3 py-2 rounded-md text-sm text-left transition-colors hover:bg-muted/30',
+              selectedRun?.id === run.id && 'bg-muted/40',
+            )}
+          >
+            <StatusDot status={run.status as DotStatus} />
+            <span className="font-medium min-w-0 flex-1 truncate">
+              {run.flow_name}
+              <span className="text-muted-foreground font-normal ml-1.5 text-xs uppercase">
+                {run.band}
+              </span>
+            </span>
+            <span className="text-xs text-muted-foreground tabular-nums hidden sm:block">
+              {run.model ? run.model.split('/').pop() : '—'}
+            </span>
+            <span className="text-xs text-muted-foreground tabular-nums whitespace-nowrap">
+              {formatDuration(run.created_at, run.updated_at)}
+            </span>
+            <span className="text-xs text-muted-foreground whitespace-nowrap">
+              {formatDate(run.created_at)}
+            </span>
+            {run.error && (
+              <span className="text-destructive" title={run.error}>
+                <XCircle className="size-3.5" />
+              </span>
+            )}
+            {run.status === 'completed' && run.report && (
+              <FileText className="size-3.5 text-muted-foreground shrink-0" />
+            )}
+          </button>
+
+          {/* Expanded detail — report preview */}
+          {selectedRun?.id === run.id && run.status === 'completed' && run.report && (
+            <div className="ml-8 mr-2 mb-2 p-3 rounded-md bg-muted/20 border border-border/50 text-xs leading-relaxed max-h-60 overflow-y-auto whitespace-pre-wrap font-mono">
+              {truncate(run.report, 3000)}
+            </div>
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+// ─── Arena Battles tab ───────────────────────────────────────────────────────
+
+function ArenaBattlesTab({ projectId }: { projectId: string }) {
+  const { data, loading, error, retry } = useFetch(() => api.battles.list(projectId).then((r) => r.battles));
+
+  const [selectedBattle, setSelectedBattle] = useState<BattleShape | null>(null);
+
+  if (loading) {
+    return (
+      <div className="space-y-2 pt-4">
+        {[0, 1, 2, 3].map((i) => (
+          <SkeletonBar key={i} className="h-12 w-full" />
+        ))}
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className="flex items-center gap-3 text-sm pt-4">
+        <span className="text-destructive">{error}</span>
+        <Button size="sm" variant="outline" onClick={retry}>
+          Retry
+        </Button>
+      </div>
+    );
+  }
+
+  if (!data || data.length === 0) {
+    return <EmptyState message="No arena battles yet. Start one from the Arena button in any chat." />;
+  }
+
+  return (
+    <div className="pt-4 space-y-2">
+      {data.map((battle) => {
+        const hasAnalysis = battle.status === 'completed' && battle.results_path;
+        return (
+          <div key={battle.id}>
+            <button
+              type="button"
+              onClick={() => setSelectedBattle(selectedBattle?.id === battle.id ? null : battle)}
+              className={cn(
+                'w-full flex items-center gap-3 px-3 py-2 rounded-md text-sm text-left transition-colors hover:bg-muted/30',
+                selectedBattle?.id === battle.id && 'bg-muted/40',
+              )}
+            >
+              <StatusDot status={
+                battle.status === 'completed' ? 'completed'
+                : battle.status === 'failed' ? 'failed'
+                : battle.status === 'cancelled' ? 'cancelled'
+                : 'running'
+              } />
+              <span className="font-medium min-w-0 flex-1 truncate">
+                {battle.battle_type === 'coding' ? 'Coding Battle' : 'Q&A Battle'}
+                <span className="text-muted-foreground font-normal ml-1.5 text-xs">
+                  {truncate(battle.prompt, 60)}
+                </span>
+              </span>
+              {battle.winner_contestant_id && (
+                <span className="text-xs text-emerald-600 dark:text-emerald-400 flex items-center gap-1">
+                  <CheckCircle2 className="size-3" />
+                  Winner
+                </span>
+              )}
+              {battle.error && (
+                <span className="text-destructive" title={battle.error}>
+                  <XCircle className="size-3.5" />
+                </span>
+              )}
+              <span className="text-xs text-muted-foreground whitespace-nowrap hidden sm:block">
+                {formatDate(battle.created_at)}
+              </span>
+              {hasAnalysis && (
+                <Beaker className="size-3.5 text-muted-foreground shrink-0" />
+              )}
+            </button>
+
+            {/* Expanded detail — analysis preview */}
+            {selectedBattle?.id === battle.id && hasAnalysis && (
+              <div className="ml-8 mr-2 mb-2">
+                <AnalysisPreview battleId={battle.id} />
+              </div>
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+// ─── Battle analysis preview (fetches analysis.md on expand) ─────────────────
+
+function AnalysisPreview({ battleId }: { battleId: string }) {
+  const { data, loading, error, retry } = useFetch(() => api.battles.getAnalysis(battleId).then((r) => r.text));
+
+  if (loading) {
+    return (
+      <div className="space-y-2 p-3 rounded-md bg-muted/20 border border-border/50">
+        <SkeletonBar className="h-3 w-full" />
+        <SkeletonBar className="h-3 w-3/4" />
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className="flex items-center gap-3 p-3 rounded-md bg-muted/20 border border-border/50 text-xs">
+        <span className="text-destructive">{error}</span>
+        <Button size="sm" variant="outline" onClick={retry}>
+          Retry
+        </Button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="p-3 rounded-md bg-muted/20 border border-border/50 text-xs leading-relaxed max-h-60 overflow-y-auto whitespace-pre-wrap font-mono">
+      {data ? truncate(data, 3000) : 'No analysis available.'}
+    </div>
+  );
+}
+
+// ─── Summary strip ───────────────────────────────────────────────────────────
+
+function SummaryCards({
+  runs,
+  battles,
+}: {
+  runs: FlowRunRow[] | null;
+  battles: BattleShape[] | null;
+}) {
+  const totalRuns = runs?.length ?? 0;
+  const completedRuns = runs?.filter((r) => r.status === 'completed').length ?? 0;
+  const totalBattles = battles?.length ?? 0;
+  const completedBattles = battles?.filter((b) => b.status === 'completed').length ?? 0;
+
+  const cards = [
+    { label: 'Total Runs', value: totalRuns, icon: FileText, color: 'text-blue-500' },
+    { label: 'Completed Runs', value: completedRuns, icon: CheckCircle2, color: 'text-emerald-500' },
+    { label: 'Total Battles', value: totalBattles, icon: Swords, color: 'text-violet-500' },
+    { label: 'Completed Battles', value: completedBattles, icon: CheckCircle2, color: 'text-emerald-500' },
+  ];
+
+  return (
+    <div className="grid grid-cols-2 md:grid-cols-4 gap-3">
+      {cards.map((c) => (
+        <Card key={c.label} size="sm">
+          <CardContent className="flex items-start gap-3 pt-3">
+            <c.icon className={cn('size-4 shrink-0 mt-0.5', c.color)} />
+            <div className="min-w-0">
+              <div className="text-lg font-semibold tabular-nums">{c.value}</div>
+              <div className="text-xs text-muted-foreground mt-0.5">{c.label}</div>
+            </div>
+          </CardContent>
+        </Card>
+      ))}
+    </div>
+  );
+}
+
+function SummaryCardsSkeleton() {
+  return (
+    <div className="grid grid-cols-2 md:grid-cols-4 gap-3">
+      {[0, 1, 2, 3].map((i) => (
+        <Card key={i} size="sm">
+          <CardContent className="pt-3">
+            <SkeletonBar className="h-5 w-16 mb-2" />
+            <SkeletonBar className="h-3 w-20" />
+          </CardContent>
+        </Card>
+      ))}
+    </div>
+  );
+}
+
+// ─── Main Page ───────────────────────────────────────────────────────────────
+
+export function Results() {
+  const navigate = useNavigate();
+  const { data: sidebar, activeSession } = useSidebar();
+
+  const [tab, setTab] = useState<TabId>('runs');
+  const [projectId, setProjectId] = useState<string | null>(null);
+
+  // Derive default project from active session or first project.
+  const projects = useMemo(() => {
+    return sidebar?.projects?.map((p: { id: string; name: string }) => p) ?? [];
+  }, [sidebar]);
+
+  useEffect(() => {
+    if (!projectId && projects.length > 0) {
+      // Prefer active session's project, else first project.
+      const defaultId = activeSession?.project_id ?? projects[0]!.id;
+      setProjectId(defaultId);
+    }
+  }, [projects, activeSession, projectId]);
+
+  function handleBack() {
+    if (window.history.length > 1) {
+      navigate(-1);
+    } else {
+      navigate('/');
+    }
+  }
+
+  const runsFetch = useFetch(
+    projectId ? () => api.runs.list(projectId).then((r) => r.runs) : () => Promise.resolve([] as FlowRunRow[]),
+  );
+  const battlesFetch = useFetch(
+    projectId ? () => api.battles.list(projectId).then((r) => r.battles) : () => Promise.resolve([] as BattleShape[]),
+  );
+
+  const summaryLoading = runsFetch.loading && battlesFetch.loading;
+
+  return (
+    <div className="flex-1 overflow-y-auto">
+      <div className="max-w-[1000px] mx-auto w-full px-6 py-6 space-y-6">
+        {/* Header */}
+        <header className="space-y-2">
+          <button
+            type="button"
+            onClick={handleBack}
+            className="inline-flex items-center gap-1 text-sm text-muted-foreground hover:text-foreground -ml-1 px-1 py-0.5 rounded"
+            aria-label="Back"
+          >
+            <ArrowLeft className="size-4" />
+            <span>Back</span>
+          </button>
+          <div className="flex items-center justify-between gap-4">
+            <div>
+              <h1 className="text-xl font-semibold flex items-center gap-2">
+                <ScrollText className="size-5" />
+                Results
+              </h1>
+              <p className="text-sm text-muted-foreground mt-1">
+                Completed orchestrator runs and arena battles.
+              </p>
+            </div>
+            {projects.length > 0 && projectId && (
+              <ProjectSelector
+                projects={projects}
+                value={projectId}
+                onChange={setProjectId}
+              />
+            )}
+          </div>
+        </header>
+
+        {/* Summary Cards */}
+        {summaryLoading ? (
+          <SummaryCardsSkeleton />
+        ) : (
+          <SummaryCards runs={runsFetch.data} battles={battlesFetch.data} />
+        )}
+
+        {/* Tab bar */}
+        <TabBar active={tab} onChange={setTab} />
+
+        {/* Tab content */}
+        {!projectId ? (
+          <EmptyState message="Select a project to view results." />
+        ) : tab === 'runs' ? (
+          <AnalysisRunsTab projectId={projectId} />
+        ) : (
+          <ArenaBattlesTab projectId={projectId} />
+        )}
+      </div>
+    </div>
+  );
+}

apps/web/src/stores/useDiffCommentStore.ts

@@ -0,0 +1,92 @@
+import { useState, useEffect, useCallback } from 'react';
+
+export interface DiffComment {
+  id: string;
+  body: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface DiffCommentTarget {
+  filePath: string;
+  side: 'old' | 'new';
+  lineNumber: number;
+}
+
+function loadFromStorage(key: string): Map<string, DiffComment[]> {
+  try {
+    const raw = localStorage.getItem(key);
+    if (!raw) return new Map();
+    const parsed = JSON.parse(raw);
+    return new Map(Object.entries(parsed));
+  } catch {
+    return new Map();
+  }
+}
+
+function saveToStorage(key: string, map: Map<string, DiffComment[]>) {
+  const obj: Record<string, DiffComment[]> = {};
+  for (const [k, v] of map) obj[k] = v;
+  localStorage.setItem(key, JSON.stringify(obj));
+}
+
+export function useDiffComments(sessionId: string, mode: string) {
+  const storageKey = `boocode.diff.comments.${sessionId}.${mode}`;
+  const [comments, setComments] = useState<Map<string, DiffComment[]>>(() =>
+    loadFromStorage(storageKey)
+  );
+
+  useEffect(() => {
+    saveToStorage(storageKey, comments);
+  }, [storageKey, comments]);
+
+  const addComment = useCallback(
+    (key: string, comment: DiffComment) => {
+      setComments((prev) => {
+        const next = new Map(prev);
+        const list = next.get(key) ?? [];
+        next.set(key, [...list, comment]);
+        return next;
+      });
+    },
+    []
+  );
+
+  const updateComment = useCallback(
+    (key: string, id: string, body: string) => {
+      setComments((prev) => {
+        const next = new Map(prev);
+        const list = next.get(key);
+        if (!list) return prev;
+        next.set(
+          key,
+          list.map((c) =>
+            c.id === id ? { ...c, body, updatedAt: Date.now() } : c
+          )
+        );
+        return next;
+      });
+    },
+    []
+  );
+
+  const deleteComment = useCallback(
+    (key: string, id: string) => {
+      setComments((prev) => {
+        const next = new Map(prev);
+        const list = next.get(key);
+        if (!list) return prev;
+        const filtered = list.filter((c) => c.id !== id);
+        if (filtered.length === 0) {
+          next.delete(key);
+        } else {
+          next.set(key, filtered);
+        }
+        return next;
+      });
+    },
+    []
+  );
+
+  return { comments, addComment, updateComment, deleteComment };
+}

apps/web/src/utils/diff-layout.ts

@@ -0,0 +1,284 @@
+/**
+ * Pure utilities for parsing unified diff text and building display structures
+ * for both unified and side-by-side (split) diff views.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type DiffLineType = 'add' | 'remove' | 'context' | 'header';
+
+export interface DiffLine {
+  type: DiffLineType;
+  content: string;
+}
+
+export interface DiffHunk {
+  oldStart: number;
+  oldCount: number;
+  newStart: number;
+  newCount: number;
+  lines: DiffLine[];
+}
+
+export interface ParsedDiffFile {
+  path: string;
+  hunks: DiffHunk[];
+}
+
+/** A single cell in the split (side-by-side) view */
+export interface SplitDisplayLine {
+  type: DiffLineType;
+  content: string;
+  lineNumber: number | null;
+}
+
+/** A row in the split view — either a hunk header or a left/right pair */
+export type SplitRow =
+  | { kind: 'header'; content: string }
+  | { kind: 'pair'; left: SplitDisplayLine | null; right: SplitDisplayLine | null };
+
+// ---------------------------------------------------------------------------
+// parseDiff
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse unified diff text into an array of ParsedDiffFile objects.
+ *
+ * Splits on `diff --git` headers, extracts file paths from `+++ b/<path>`
+ * (falling back to `--- a/<path>`), and classifies each line within hunks.
+ */
+export function parseDiff(diffBody: string): ParsedDiffFile[] {
+  if (!diffBody || diffBody.trim().length === 0) {
+    return [];
+  }
+
+  const files: ParsedDiffFile[] = [];
+  const sections = diffBody.split(/^diff --git /m).filter(Boolean);
+
+  for (const section of sections) {
+    const lines = section.split('\n');
+    const path = extractPath(lines);
+    const hunks = parseSectionBody(lines);
+    files.push({ path, hunks });
+  }
+
+  return files;
+}
+
+// ---------------------------------------------------------------------------
+// buildSplitRows
+// ---------------------------------------------------------------------------
+
+/**
+ * Build side-by-side (split) display rows from a parsed diff file.
+ *
+ * For each hunk:
+ * - Emits a header row (`@@ -... +... @@`)
+ * - Buffers consecutive removals and additions
+ * - On a context line (or hunk end), flushes buffered removals/additions as
+ *   paired rows (left = removal or null, right = addition or null)
+ * - Context lines become paired rows with identical content on both sides
+ */
+export function buildSplitRows(file: ParsedDiffFile): SplitRow[] {
+  const rows: SplitRow[] = [];
+
+  for (const hunk of file.hunks) {
+    // Header row
+    const headerLine = hunk.lines.find((l) => l.type === 'header');
+    rows.push({ kind: 'header', content: headerLine?.content ?? '@@' });
+
+    let oldLineNo = hunk.oldStart;
+    let newLineNo = hunk.newStart;
+
+    let pendingRemovals: SplitDisplayLine[] = [];
+    let pendingAdditions: SplitDisplayLine[] = [];
+
+    const flushPending = (): void => {
+      const pairCount = Math.max(pendingRemovals.length, pendingAdditions.length);
+      for (let i = 0; i < pairCount; i++) {
+        rows.push({
+          kind: 'pair',
+          left: pendingRemovals[i] ?? null,
+          right: pendingAdditions[i] ?? null,
+        });
+      }
+      pendingRemovals = [];
+      pendingAdditions = [];
+    };
+
+    for (const line of hunk.lines) {
+      if (line.type === 'header') continue;
+
+      if (line.type === 'remove') {
+        pendingRemovals.push({
+          type: 'remove',
+          content: line.content,
+          lineNumber: oldLineNo++,
+        });
+        continue;
+      }
+
+      if (line.type === 'add') {
+        pendingAdditions.push({
+          type: 'add',
+          content: line.content,
+          lineNumber: newLineNo++,
+        });
+        continue;
+      }
+
+      // Context line — flush any pending changes first
+      flushPending();
+
+      rows.push({
+        kind: 'pair',
+        left: {
+          type: 'context',
+          content: line.content,
+          lineNumber: oldLineNo++,
+        },
+        right: {
+          type: 'context',
+          content: line.content,
+          lineNumber: newLineNo++,
+        },
+      });
+    }
+
+    // Flush any trailing removals/additions at hunk end
+    flushPending();
+  }
+
+  return rows;
+}
+
+// ---------------------------------------------------------------------------
+// reconstructNewContent
+// ---------------------------------------------------------------------------
+
+/**
+ * Reconstruct the "new" file content from diff hunks by concatenating
+ * addition and context lines. Useful for syntax-highlighting the split
+ * view's right column.
+ */
+export function reconstructNewContent(hunks: DiffHunk[]): string {
+  const lines: string[] = [];
+
+  for (const hunk of hunks) {
+    for (const line of hunk.lines) {
+      if (line.type === 'add' || line.type === 'context') {
+        lines.push(line.content);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/** Extract file path from `+++ b/<path>` or `--- a/<path>` metadata lines. */
+function extractPath(lines: string[]): string {
+  // Try +++ b/<path> first (most reliable for the "new" side)
+  const newLine = lines.find((l) => l.startsWith('+++ '));
+  if (newLine) {
+    const raw = newLine.slice(4).replace(/\t.*$/, '').trimEnd();
+    if (raw !== '/dev/null') {
+      return stripPrefix(raw);
+    }
+  }
+
+  // Fall back to --- a/<path>
+  const oldLine = lines.find((l) => l.startsWith('--- '));
+  if (oldLine) {
+    const raw = oldLine.slice(4).replace(/\t.*$/, '').trimEnd();
+    if (raw !== '/dev/null') {
+      return stripPrefix(raw);
+    }
+  }
+
+  // Last resort: parse the first line (e.g. "a/path b/path")
+  const firstLine = lines[0] ?? '';
+  const match = firstLine.match(/^a\/(.+)\s+b\/(.+)$/);
+  if (match) return match[2]!;
+
+  return 'unknown';
+}
+
+/** Strip the `a/` or `b/` prefix that git adds to diff paths. */
+function stripPrefix(path: string): string {
+  if (path.startsWith('b/') || path.startsWith('a/')) {
+    return path.slice(2);
+  }
+  return path;
+}
+
+/** Parse hunk headers and line content from a diff section body. */
+function parseSectionBody(lines: string[]): DiffHunk[] {
+  const hunks: DiffHunk[] = [];
+  let currentHunk: DiffHunk | null = null;
+
+  // Start at index 1 to skip the first line (the "a/path b/path" header from
+  // the `diff --git` split)
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i]!;
+
+    if (isMetadataLine(line)) continue;
+
+    const newHunk = parseHunkHeader(line);
+    if (newHunk) {
+      if (currentHunk) hunks.push(currentHunk);
+      currentHunk = newHunk;
+      continue;
+    }
+
+    if (!currentHunk) continue;
+
+    if (line.startsWith('+')) {
+      currentHunk.lines.push({ type: 'add', content: line.slice(1) });
+    } else if (line.startsWith('-')) {
+      currentHunk.lines.push({ type: 'remove', content: line.slice(1) });
+    } else if (line.startsWith(' ')) {
+      currentHunk.lines.push({ type: 'context', content: line.slice(1) });
+    } else if (line.length > 0 && !line.startsWith('\\')) {
+      currentHunk.lines.push({ type: 'context', content: line });
+    }
+  }
+
+  if (currentHunk) hunks.push(currentHunk);
+  return hunks;
+}
+
+/** Parse a `@@ -oldStart,oldCount +newStart,newCount @@` header line. */
+function parseHunkHeader(line: string): DiffHunk | null {
+  const match = line.match(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/);
+  if (!match) return null;
+
+  return {
+    oldStart: parseInt(match[1]!, 10),
+    oldCount: parseInt(match[2] ?? '1', 10),
+    newStart: parseInt(match[3]!, 10),
+    newCount: parseInt(match[4] ?? '1', 10),
+    lines: [
+      {
+        type: 'header',
+        content: line.match(/^(@@ .+? @@)/)?.[1] ?? line,
+      },
+    ],
+  };
+}
+
+/** Check if a line is diff metadata (not content). */
+function isMetadataLine(line: string): boolean {
+  return (
+    line.startsWith('index ') ||
+    line.startsWith('--- ') ||
+    line.startsWith('+++ ') ||
+    line.startsWith('new file mode') ||
+    line.startsWith('deleted file mode')
+  );
+}

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/mcp.example.json

@@ -7,17 +7,6 @@
         "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
       },
       "enabled": false
-    },
-    "boocontext": {
-      "type": "stdio",
-      "command": "node",
-      "args": ["/opt/forks/boocontext/dist/index.js"],
-      "env": {
-        "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

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(),
+  };
+}

packages/ion/src/engine/index.ts

@@ -0,0 +1,63 @@
+/**
+ * Engine barrel exports.
+ *
+ * Re-exports everything from the engine submodules.
+ */
+
+// Dependencies and types
+export type {
+  IWorkflowPlatform,
+  IWorkflowStore,
+  IAgentProvider,
+  WorkflowDeps,
+  WorkflowConfig,
+  ProviderConfig,
+  CommandFolderConfig,
+  CreateWorkflowRunData,
+  WorkflowEvent,
+} from './deps.js';
+
+// DAG executor
+export {
+  buildTopologicalLayers,
+  checkTriggerRule,
+  executeNodeInternal,
+  executeScriptNode,
+  handleApprovalNode,
+  handleLoopNode,
+  executeDagWorkflow,
+} from './dag-executor.js';
+export type { DagWorkflowResult } from './dag-executor.js';
+
+// Top-level executor
+export {
+  executeWorkflow,
+  hydrateResumableRun,
+  resolveProjectPaths,
+} from './executor.js';
+export type {
+  WorkflowExecutionOptions,
+  WorkflowExecutionResult,
+  HydratedResumableRun,
+  ProjectPaths,
+} from './executor.js';
+
+// Utilities
+export {
+  substituteWorkflowVariables,
+  substituteNodeOutputRefs,
+  buildPromptWithContext,
+  evaluateCondition,
+  classifyError,
+  safeSendMessage,
+  formatSubprocessFailure,
+  sleep,
+  retryWithBackoff,
+  resolveNodeOutputField,
+  OutputRefError,
+  DagCycleError,
+  NodeTimeoutError,
+  ApprovalRejectedError,
+  LoopMaxIterationsError,
+} from './utils.js';
+export type { ErrorCategory } from './utils.js';

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

@@ -0,0 +1,228 @@
+/**
+ * Provider/model resolution for the Ion workflow engine.
+ *
+ * Maps model references (aliases, tier presets, or literal specs)
+ * to concrete AI model configurations.
+ */
+
+import type { ProviderConfig } from './deps.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A concrete model specification with all fields resolved. */
+export interface LiteralModelSpec {
+  /** The AI provider (e.g. "openai", "anthropic"). */
+  provider: string;
+  /** The model identifier (e.g. "gpt-4o", "claude-sonnet-4-20250514"). */
+  model: string;
+  /** Optional effort level (e.g. "low", "medium", "high"). */
+  effort?: string;
+  /** Optional thinking/reasoning configuration. */
+  thinking?: {
+    type: string;
+    budgetTokens?: number;
+  };
+}
+
+/** A preset that maps an alias to a concrete model configuration. */
+export interface ModelAliasPreset {
+  /** The provider for this preset. */
+  provider: string;
+  /** The model identifier. */
+  model: string;
+  /** Optional effort level. */
+  effort?: string;
+  /** Optional thinking configuration. */
+  thinking?: {
+    type: string;
+    budgetTokens?: number;
+  };
+}
+
+/** Tier definitions for an AI profile. */
+export interface AiProfileTiers {
+  /** Fast/cheap tier. */
+  fast?: ModelAliasPreset;
+  /** Balanced tier. */
+  balanced?: ModelAliasPreset;
+  /** Powerful/expensive tier. */
+  powerful?: ModelAliasPreset;
+}
+
+/** An AI profile with tiers and named aliases. */
+export interface AiProfile {
+  /** The default provider. */
+  defaultProvider: string;
+  /** Named provider configurations. */
+  providers: Record<string, ProviderConfig>;
+  /** Tier presets. */
+  tiers: AiProfileTiers;
+  /** Named aliases mapping to presets. */
+  aliases: Record<string, ModelAliasPreset>;
+}
+
+/** Options for building an AI profile. */
+export interface BuildAiProfileOptions {
+  /** The default assistant/provider id. */
+  assistant: string;
+  /** Named provider configurations. */
+  assistants: Record<string, ProviderConfig>;
+  /** Optional model overrides from workflow config. */
+  modelOverrides?: Record<string, ModelAliasPreset>;
+}
+
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if a model spec is a literal (fully resolved) spec.
+ *
+ * A literal spec has a `provider` and `model` field directly.
+ */
+export function isLiteralSpec(
+  spec: unknown,
+): spec is LiteralModelSpec {
+  if (typeof spec !== 'object' || spec === null) {
+    return false;
+  }
+  const obj = spec as Record<string, unknown>;
+  return typeof obj['provider'] === 'string' && typeof obj['model'] === 'string';
+}
+
+// ---------------------------------------------------------------------------
+// Profile builder
+// ---------------------------------------------------------------------------
+
+/** Default tier presets for common providers. */
+const DEFAULT_TIERS: Record<string, AiProfileTiers> = {
+  openai: {
+    fast: { provider: 'openai', model: 'gpt-4o-mini' },
+    balanced: { provider: 'openai', model: 'gpt-4o' },
+    powerful: { provider: 'openai', model: 'o1' },
+  },
+  anthropic: {
+    fast: { provider: 'anthropic', model: 'claude-haiku-4-20250414' },
+    balanced: { provider: 'anthropic', model: 'claude-sonnet-4-20250514' },
+    powerful: {
+      provider: 'anthropic',
+      model: 'claude-opus-4-20250514',
+      thinking: { type: 'enabled', budgetTokens: 10000 },
+    },
+  },
+};
+
+/**
+ * Build an AI profile from workflow configuration.
+ *
+ * Merges default tier presets with any model overrides from the config.
+ */
+export function buildAiProfile(
+  opts: BuildAiProfileOptions,
+): AiProfile {
+  const providers = { ...opts.assistants };
+
+  // Determine the default provider from the assistant config.
+  const defaultProviderConfig = providers[opts.assistant];
+  const defaultProvider = defaultProviderConfig?.provider ?? opts.assistant;
+
+  // Start with default tiers for the default provider.
+  const baseTiers = DEFAULT_TIERS[defaultProvider] ?? {};
+
+  // Apply model overrides if provided.
+  const tiers: AiProfileTiers = { ...baseTiers };
+  if (opts.modelOverrides) {
+    for (const [key, preset] of Object.entries(opts.modelOverrides)) {
+      if (key === 'fast' || key === 'balanced' || key === 'powerful') {
+        tiers[key] = preset;
+      }
+    }
+  }
+
+  // Build aliases from overrides and tiers.
+  const aliases: Record<string, ModelAliasPreset> = {};
+
+  // Tier-based aliases.
+  if (tiers.fast) aliases['fast'] = tiers.fast;
+  if (tiers.balanced) aliases['balanced'] = tiers.balanced;
+  if (tiers.powerful) aliases['powerful'] = tiers.powerful;
+
+  // Custom overrides as aliases.
+  if (opts.modelOverrides) {
+    for (const [key, preset] of Object.entries(opts.modelOverrides)) {
+      if (key !== 'fast' && key !== 'balanced' && key !== 'powerful') {
+        aliases[key] = preset;
+      }
+    }
+  }
+
+  return {
+    defaultProvider,
+    providers,
+    tiers,
+    aliases,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Model resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a model reference to a literal model spec.
+ *
+ * A model reference can be:
+ * - A literal spec (has `provider` and `model` fields) → returned as-is
+ * - A tier name ("fast", "balanced", "powerful") → resolved from profile tiers
+ * - A named alias → resolved from profile aliases
+ * - A provider-prefixed reference ("openai/gpt-4o") → parsed into a spec
+ * - A bare model name → resolved using the default provider
+ *
+ * Throws if the reference cannot be resolved.
+ */
+export function resolveModelSpec(
+  profile: AiProfile,
+  modelRef: string | LiteralModelSpec,
+): LiteralModelSpec {
+  // Already a literal spec.
+  if (typeof modelRef !== 'string') {
+    if (isLiteralSpec(modelRef)) {
+      return modelRef;
+    }
+    throw new Error(`Invalid model spec: ${JSON.stringify(modelRef)}`);
+  }
+
+  // Check aliases first (includes tier aliases).
+  const alias = profile.aliases[modelRef];
+  if (alias) {
+    return {
+      provider: alias.provider,
+      model: alias.model,
+      effort: alias.effort,
+      thinking: alias.thinking,
+    };
+  }
+
+  // Provider-prefixed reference: "provider/model"
+  if (modelRef.includes('/')) {
+    const slashIndex = modelRef.indexOf('/');
+    const provider = modelRef.slice(0, slashIndex)!;
+    const model = modelRef.slice(slashIndex + 1);
+
+    if (!provider || !model) {
+      throw new Error(
+        `Invalid provider-prefixed model reference: "${modelRef}". Expected format "provider/model".`,
+      );
+    }
+
+    return { provider, model };
+  }
+
+  // Bare model name — use default provider.
+  return {
+    provider: profile.defaultProvider,
+    model: modelRef,
+  };
+}

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

@@ -0,0 +1,122 @@
+/**
+ * Node output reference resolution for the Ion workflow engine.
+ *
+ * Resolves `$nodeId.field` references in workflow conditions and prompts,
+ * with strict schema-aware validation and descriptive errors.
+ */
+
+// ---------------------------------------------------------------------------
+// Output reference result
+// ---------------------------------------------------------------------------
+
+export type OutputRefKind = 'value' | 'empty';
+
+export interface OutputRefResult {
+  /** Whether the field had a value or was empty. */
+  kind: OutputRefKind;
+  /** The resolved value (empty string for missing optional fields). */
+  value: string;
+}
+
+// ---------------------------------------------------------------------------
+// OutputRefError
+// ---------------------------------------------------------------------------
+
+export class OutputRefError extends Error {
+  public readonly nodeId: string;
+  public readonly field: string;
+
+  constructor(nodeId: string, field: string, message: string) {
+    super(`Output reference error for node "${nodeId}".${field}: ${message}`);
+    this.name = 'OutputRefError';
+    this.nodeId = nodeId;
+    this.field = field;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Schema helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract declared field names from an output_format schema.
+ *
+ * The output_format can be:
+ * - A JSON Schema object with `properties` (standard)
+ * - A string describing the format (treated as having no declared fields)
+ * - Undefined (no schema)
+ *
+ * Returns a Set of field names that are declared in the schema.
+ */
+export function declaredFieldsFromSchema(
+  outputFormat: Record<string, unknown> | string | undefined,
+): Set<string> {
+  if (!outputFormat || typeof outputFormat === 'string') {
+    return new Set();
+  }
+
+  const properties = outputFormat['properties'];
+  if (properties && typeof properties === 'object' && properties !== null) {
+    return new Set(Object.keys(properties as Record<string, unknown>));
+  }
+
+  return new Set();
+}
+
+// ---------------------------------------------------------------------------
+// Node output resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a specific field from a node's output.
+ *
+ * Behavior:
+ * - If the field is present in the output, returns `{ kind: 'value', value }`.
+ * - If the field is declared in the schema but not present in the output,
+ *   returns `{ kind: 'empty', value: '' }` (optional field not set).
+ * - If the field is NOT declared in the schema AND not in the output,
+ *   throws `OutputRefError` (undeclared reference).
+ * - If the field is NOT declared in the schema but IS in the output,
+ *   returns `{ kind: 'value', value }` (dynamic output).
+ *
+ * The `declaredFields` parameter should come from `declaredFieldsFromSchema()`.
+ */
+export function resolveNodeOutputField(
+  nodeOutput: Record<string, unknown>,
+  nodeId: string,
+  field: string,
+  declaredFields?: Set<string>,
+): OutputRefResult {
+  // Check if the field exists in the output.
+  if (field in nodeOutput) {
+    const rawValue = nodeOutput[field];
+
+    // Convert the value to a string.
+    if (rawValue === null || rawValue === undefined) {
+      // Field key exists but value is nullish — treat as empty.
+      return { kind: 'empty', value: '' };
+    }
+
+    if (typeof rawValue === 'string') {
+      return { kind: 'value', value: rawValue };
+    }
+
+    // Non-string values are JSON-serialized.
+    return { kind: 'value', value: JSON.stringify(rawValue) };
+  }
+
+  // Field is not in the output. Check if it was declared in the schema.
+  const isDeclared = declaredFields?.has(field) ?? false;
+
+  if (isDeclared) {
+    // Declared but not present — optional field not set.
+    return { kind: 'empty', value: '' };
+  }
+
+  // Not declared and not present — this is an error.
+  throw new OutputRefError(
+    nodeId,
+    field,
+    `Field "${field}" is not declared in the output schema and is not present in the node output. Available fields: ${Object.keys(nodeOutput).join(', ') || '(none)'}`,
+  );
+}

packages/ion/src/engine/utils.ts

@@ -0,0 +1,372 @@
+/**
+ * Utility functions for the Ion workflow engine.
+ *
+ * Provides variable substitution, condition evaluation, error classification,
+ * and safe messaging helpers used by the DAG executor and top-level executor.
+ */
+
+import type { NodeOutput } from '../schema/index.js';
+
+// ---------------------------------------------------------------------------
+// Variable substitution
+// ---------------------------------------------------------------------------
+
+/**
+ * Substitute workflow-level variables in a string.
+ *
+ * Replaces `${VAR_NAME}` patterns with values from the provided variables map.
+ * Supports nested dot-notation access (e.g. `${env.API_KEY}`).
+ */
+export function substituteWorkflowVariables(
+  template: string,
+  variables: Record<string, unknown>,
+): string {
+  return template.replace(/\$\{([^}]+)\}/g, (_match, path: string) => {
+    const parts = path.split('.');
+    let current: unknown = variables;
+    for (const part of parts) {
+      if (current == null || typeof current !== 'object') return '';
+      current = (current as Record<string, unknown>)[part];
+    }
+    return current != null ? String(current) : '';
+  });
+}
+
+/**
+ * Regex pattern for node output references: `$nodeId.output` or `$nodeId.output.field`.
+ */
+const NODE_OUTPUT_REF_REGEX =
+  /\$([a-zA-Z_][\w-]*)\.output(?:\.([a-zA-Z_][\w]*))?/g;
+
+/**
+ * Substitute node output references in a prompt string.
+ *
+ * Resolves `$nodeId.output` → full text output, and
+ * `$nodeId.output.field` → specific structured field.
+ *
+ * @param prompt - The prompt template containing references.
+ * @param nodeOutputs - Map of node id → NodeOutput.
+ * @param escapedForBash - If true, escapes special bash characters in the output.
+ */
+export function substituteNodeOutputRefs(
+  prompt: string,
+  nodeOutputs: Map<string, NodeOutput>,
+  escapedForBash = false,
+): string {
+  return prompt.replace(NODE_OUTPUT_REF_REGEX, (_match, nodeId: string, field?: string) => {
+    const output = nodeOutputs.get(nodeId);
+    if (!output) {
+      throw new OutputRefError(
+        `Node output reference $${nodeId}.output not found. ` +
+          `Available nodes: ${[...nodeOutputs.keys()].join(', ')}`,
+      );
+    }
+
+    let value: string;
+    if (field) {
+      value = resolveNodeOutputField(output, field);
+    } else {
+      value = output.text ?? '';
+    }
+
+    if (escapedForBash) {
+      value = value.replace(/(["'$`\\!])/g, '\\$1');
+    }
+
+    return value;
+  });
+}
+
+/**
+ * Resolve a specific field from a node's structured output.
+ *
+ * @throws OutputRefError if the field doesn't exist or output has no fields.
+ */
+export function resolveNodeOutputField(output: NodeOutput, field: string): string {
+  if (!output.fields || !(field in output.fields)) {
+    throw new OutputRefError(
+      `Node ${output.nodeId} output does not have field "${field}". ` +
+        `Available fields: ${output.fields ? Object.keys(output.fields).join(', ') : '(none)'}`,
+    );
+  }
+  const value = output.fields[field];
+  return value != null ? String(value) : '';
+}
+
+/**
+ * Build a complete prompt string with context injection.
+ *
+ * Applies workflow variable substitution and node output reference
+ * substitution to produce the final prompt sent to the AI provider.
+ */
+export function buildPromptWithContext(
+  prompt: string,
+  variables: Record<string, unknown>,
+  nodeOutputs: Map<string, NodeOutput>,
+  escapedForBash = false,
+): string {
+  let result = substituteWorkflowVariables(prompt, variables);
+  result = substituteNodeOutputRefs(result, nodeOutputs, escapedForBash);
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Condition evaluation
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluate a condition expression against the current workflow context.
+ *
+ * Supports simple expressions:
+ * - Truthy/falsy string check (empty string = false)
+ * - Comparison: `==`, `!=`, `>`, `<`, `>=`, `<=`
+ * - Boolean literals: `true`, `false`
+ * - Variable references: `${var}` resolved before evaluation
+ *
+ * @param condition - The condition string to evaluate.
+ * @param variables - Workflow variables for substitution.
+ * @returns Whether the condition is truthy.
+ */
+export function evaluateCondition(
+  condition: string | undefined,
+  variables: Record<string, unknown>,
+): boolean {
+  if (condition === undefined || condition === '') return true;
+
+  // Substitute variables first
+  const resolved = substituteWorkflowVariables(condition, variables).trim();
+
+  // Boolean literals
+  if (resolved === 'true') return true;
+  if (resolved === 'false') return false;
+
+  // Empty after substitution = falsy
+  if (resolved === '') return false;
+
+  // Comparison operators
+  const comparisonMatch = resolved.match(/^(.+?)\s*(==|!=|>=|<=|>|<)\s*(.+)$/);
+  if (comparisonMatch) {
+    const [, left, op, right] = comparisonMatch;
+    const leftVal = left!.trim();
+    const rightVal = right!.trim();
+
+    switch (op) {
+      case '==':
+        return leftVal === rightVal;
+      case '!=':
+        return leftVal !== rightVal;
+      case '>=':
+        return parseFloat(leftVal) >= parseFloat(rightVal);
+      case '<=':
+        return parseFloat(leftVal) <= parseFloat(rightVal);
+      case '>':
+        return parseFloat(leftVal) > parseFloat(rightVal);
+      case '<':
+        return parseFloat(leftVal) < parseFloat(rightVal);
+    }
+  }
+
+  // Default: non-empty string is truthy
+  return resolved.length > 0;
+}
+
+// ---------------------------------------------------------------------------
+// Error classification
+// ---------------------------------------------------------------------------
+
+/** Error categories for classification. */
+export type ErrorCategory = 'transient' | 'permanent' | 'timeout' | 'rate_limit' | 'unknown';
+
+/**
+ * Classify an error into a category for retry decisions.
+ */
+export function classifyError(error: unknown): ErrorCategory {
+  if (error instanceof Error) {
+    const msg = error.message.toLowerCase();
+
+    // Timeout errors
+    if (
+      msg.includes('timeout') ||
+      msg.includes('timed out') ||
+      msg.includes('aborted') ||
+      error.name === 'AbortError' ||
+      error.name === 'TimeoutError'
+    ) {
+      return 'timeout';
+    }
+
+    // Rate limiting
+    if (
+      msg.includes('rate limit') ||
+      msg.includes('429') ||
+      msg.includes('too many requests')
+    ) {
+      return 'rate_limit';
+    }
+
+    // Permanent errors
+    if (
+      msg.includes('authentication') ||
+      msg.includes('unauthorized') ||
+      msg.includes('forbidden') ||
+      msg.includes('401') ||
+      msg.includes('403') ||
+      msg.includes('invalid api key') ||
+      msg.includes('permission denied')
+    ) {
+      return 'permanent';
+    }
+
+    // Transient errors
+    if (
+      msg.includes('network') ||
+      msg.includes('econnreset') ||
+      msg.includes('econnrefused') ||
+      msg.includes('enotfound') ||
+      msg.includes('socket hang up') ||
+      msg.includes('500') ||
+      msg.includes('502') ||
+      msg.includes('503') ||
+      msg.includes('504') ||
+      msg.includes('internal server error') ||
+      msg.includes('bad gateway') ||
+      msg.includes('service unavailable') ||
+      msg.includes('gateway timeout')
+    ) {
+      return 'transient';
+    }
+  }
+
+  return 'unknown';
+}
+
+// ---------------------------------------------------------------------------
+// Safe messaging
+// ---------------------------------------------------------------------------
+
+/**
+ * Safely send a message to the platform, swallowing errors.
+ *
+ * Used for non-critical notifications where failure should not
+ * abort the workflow.
+ */
+export async function safeSendMessage(
+  platform: { sendMessage: (convId: string, msg: string, meta?: Record<string, unknown>) => Promise<void> },
+  conversationId: string,
+  message: string,
+  metadata?: Record<string, unknown>,
+): Promise<void> {
+  try {
+    await platform.sendMessage(conversationId, message, metadata);
+  } catch {
+    // Swallow — this is a best-effort notification
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Custom errors
+// ---------------------------------------------------------------------------
+
+/** Thrown when a node output reference cannot be resolved. */
+export class OutputRefError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'OutputRefError';
+  }
+}
+
+/** Thrown when a cycle is detected in the DAG. */
+export class DagCycleError extends Error {
+  constructor(nodeCount: number, layerSum: number) {
+    super(
+      `Cycle detected in DAG: ${nodeCount} nodes but only ${layerSum} reachable via topological sort`,
+    );
+    this.name = 'DagCycleError';
+  }
+}
+
+/** Thrown when a node execution times out. */
+export class NodeTimeoutError extends Error {
+  constructor(nodeId: string, timeoutMs: number) {
+    super(`Node "${nodeId}" timed out after ${timeoutMs}ms`);
+    this.name = 'NodeTimeoutError';
+  }
+}
+
+/** Thrown when an approval is rejected. */
+export class ApprovalRejectedError extends Error {
+  constructor(nodeId: string, reason?: string) {
+    super(`Approval rejected for node "${nodeId}"${reason ? `: ${reason}` : ''}`);
+    this.name = 'ApprovalRejectedError';
+  }
+}
+
+/** Thrown when a loop exceeds its maximum iterations. */
+export class LoopMaxIterationsError extends Error {
+  constructor(nodeId: string, iterations: number) {
+    super(`Loop node "${nodeId}" exceeded max iterations (${iterations})`);
+    this.name = 'LoopMaxIterationsError';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Subprocess formatting
+// ---------------------------------------------------------------------------
+
+/**
+ * Format a subprocess failure into a human-readable error message.
+ */
+export function formatSubprocessFailure(
+  command: string,
+  exitCode: number | null,
+  stdout: string,
+  stderr: string,
+): string {
+  const parts: string[] = [];
+  parts.push(`Command failed: ${command}`);
+  if (exitCode != null) parts.push(`Exit code: ${exitCode}`);
+  if (stderr.trim()) parts.push(`stderr: ${stderr.trim()}`);
+  if (stdout.trim()) parts.push(`stdout: ${stdout.trim()}`);
+  return parts.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Misc helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Sleep for a given number of milliseconds.
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Retry a function with exponential backoff.
+ *
+ * @param fn - The function to retry.
+ * @param maxAttempts - Maximum number of attempts.
+ * @param baseDelayMs - Base delay between retries in ms.
+ * @param shouldRetry - Optional predicate to decide if a retry is warranted.
+ */
+export async function retryWithBackoff<T>(
+  fn: () => Promise<T>,
+  maxAttempts: number,
+  baseDelayMs = 1000,
+  shouldRetry?: (error: unknown) => boolean,
+): Promise<T> {
+  let lastError: unknown;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (shouldRetry && !shouldRetry(error)) throw error;
+      if (attempt < maxAttempts) {
+        const delay = baseDelayMs * Math.pow(2, attempt - 1);
+        await sleep(delay);
+      }
+    }
+  }
+  throw lastError;
+}

packages/ion/src/format/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Ion workflow engine — format module.
+ *
+ * Re-exports the SOP markdown parser, YAML converter, and file discovery
+ * utilities so consumers can import from a single entry point:
+ *
+ * ```ts
+ * import { parseSopContent, convertSopToWorkflowYaml, discoverSopFiles } from '@boocode/ion/format';
+ * ```
+ */
+
+export {
+  parseSopContent,
+  type SopDocument,
+  type SopParameter,
+  type SopStep,
+} from './sop-parser.js';
+
+export { convertSopToWorkflowYaml } from './sop-to-yaml.js';
+
+export { discoverSopFiles } from './sop-discovery.js';
+export type { GlobFn } from './sop-discovery.js';

packages/ion/src/format/sop-discovery.ts

@@ -0,0 +1,78 @@
+/**
+ * SOP file discovery for the Ion workflow engine.
+ *
+ * Locates `.sop.md` files by delegating file-system traversal to a
+ * caller-provided glob function. This keeps the module pure (no Node
+ * dependency) and easily testable.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * A function that resolves a glob pattern to an array of absolute paths.
+ *
+ * The caller typically provides an implementation backed by `node:fs/promises`
+ * or a test double.
+ */
+export type GlobFn = (pattern: string) => Promise<string[]>;
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Default search directories (in priority order, relative to cwd). */
+const SEARCH_DIRS = ['.archon/workflows', '.'];
+
+/** Glob pattern for SOP markdown files. */
+const SOP_GLOB = '**/*.sop.md';
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Discover all `.sop.md` files in the given working directory.
+ *
+ * Searches `.archon/workflows/` first, then the project root, and returns
+ * absolute paths to every matching file. Duplicate paths are de-duplicated.
+ *
+ * @param cwd    - The working directory to search from.
+ * @param globFn - A function that resolves a glob pattern to file paths.
+ *                 Typically backed by `glob` from `node:fs/promises` or a
+ *                 similar library.
+ * @returns An array of absolute file paths to discovered `.sop.md` files,
+ *          sorted deterministically.
+ */
+export async function discoverSopFiles(
+  cwd: string,
+  globFn: GlobFn,
+): Promise<string[]> {
+  const seen = new Set<string>();
+  const results: string[] = [];
+
+  for (const dir of SEARCH_DIRS) {
+    const pattern =
+      dir === '.' ? `${cwd}/${SOP_GLOB}` : `${cwd}/${dir}/${SOP_GLOB}`;
+
+    let paths: string[];
+    try {
+      paths = await globFn(pattern);
+    } catch {
+      // Glob errors (e.g. directory doesn't exist) are non-fatal.
+      continue;
+    }
+
+    // Sort for deterministic output and de-duplicate
+    paths.sort();
+    for (const p of paths) {
+      if (!seen.has(p)) {
+        seen.add(p);
+        results.push(p);
+      }
+    }
+  }
+
+  return results;
+}

packages/ion/src/format/sop-parser.ts

@@ -0,0 +1,203 @@
+/**
+ * SOP Markdown parser for the Ion workflow engine.
+ *
+ * Parses `.sop.md` files (Agent SOP format) into structured `SopDocument`
+ * objects that can be converted to YAML workflow definitions.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A single parameter declared in the SOP's Parameters section. */
+export interface SopParameter {
+  /** Parameter name (camelCase by convention). */
+  name: string;
+  /** Whether the parameter is required or optional. */
+  type: 'required' | 'optional';
+  /** Default value (only present when type is 'optional'). */
+  default?: string;
+  /** Human-readable description of the parameter. */
+  description: string;
+}
+
+/** A single step declared in the SOP's Steps section. */
+export interface SopStep {
+  /** Step number (1-based). */
+  number: number;
+  /** Short human-readable step name. */
+  name: string;
+  /** Full body text of the step (may be multi-line). */
+  body: string;
+  /** Constraints text extracted from the step, if any. */
+  constraints?: string;
+}
+
+/** The fully-parsed SOP document. */
+export interface SopDocument {
+  /** Title extracted from the first `# heading`. */
+  title: string;
+  /** Overview section content. */
+  overview: string;
+  /** Parsed parameters (empty array if section absent). */
+  parameters: SopParameter[];
+  /** Parsed steps (empty array if section absent). */
+  steps: SopStep[];
+  /** Optional examples section content. */
+  examples?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract a section body from markdown text.
+ *
+ * A section starts with `## <Title>` and ends at the next `## ` or `# `
+ * heading (or end of string).
+ */
+function extractSection(markdown: string, heading: string): string | null {
+  const pattern = new RegExp(
+    `^##\\s+${escapeRegex(heading)}\\s*\\n([\\s\\S]*?)(?=\\n##|\\n#|$)`,
+    'm',
+  );
+  const match = markdown.match(pattern);
+  return match?.[1]?.trim() ?? null;
+}
+
+/** Escape special regex characters in a literal string. */
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// ---------------------------------------------------------------------------
+// Section parsers
+// ---------------------------------------------------------------------------
+
+/** Parse the Parameters section into structured `SopParameter` objects. */
+function parseParameters(raw: string): SopParameter[] {
+  const parameters: SopParameter[] = [];
+  // Match lines like: - **paramName** (required): Description here
+  //                   - **paramName** (optional, default: value): Description here
+  const paramRegex =
+    /^-\s+\*\*(\w+)\*\*\s+\((required|optional)(?:,\s*default:\s*([^)]+))?\):\s+(.+)$/gm;
+
+  let match: RegExpExecArray | null;
+  while ((match = paramRegex.exec(raw)) !== null) {
+    const name = match[1]!;
+    const type = match[2]! as 'required' | 'optional';
+    const defaultVal = match[3]; // may be undefined (optional group)
+    const description = match[4]!;
+
+    const param: SopParameter = {
+      name,
+      type,
+      description,
+    };
+    if (defaultVal !== undefined) {
+      param.default = defaultVal.trim();
+    }
+    parameters.push(param);
+  }
+
+  return parameters;
+}
+
+/** Parse the Steps section into structured `SopStep` objects. */
+function parseSteps(raw: string): SopStep[] {
+  const steps: SopStep[] = [];
+
+  // Find all ### sub-headings like "### 1. Step Name"
+  const stepHeadingRegex = /^###\s+(\d+)\.\s+(.+)$/gm;
+
+  // Collect heading positions: [startIndex, endIndex, number, name]
+  const headings: { number: number; name: string; start: number; end: number }[] = [];
+
+  let match: RegExpExecArray | null;
+  while ((match = stepHeadingRegex.exec(raw)) !== null) {
+    headings.push({
+      number: parseInt(match[1]!, 10),
+      name: match[2]!.trim(),
+      start: match.index,
+      end: -1, // filled in below
+    });
+  }
+
+  // Set end positions: each heading ends where the next one starts, or at EOF
+  for (let i = 0; i < headings.length; i++) {
+    const heading = headings[i]!;
+    heading.end =
+      i + 1 < headings.length ? headings[i + 1]!.start : raw.length;
+  }
+
+  for (const heading of headings) {
+    // The body starts after the heading line itself
+    const headingLineEnd = raw.indexOf('\n', heading.start);
+    const bodyStart = headingLineEnd === -1 ? raw.length : headingLineEnd + 1;
+    const sectionText = raw.slice(bodyStart, heading.end).trim();
+
+    // Extract constraints if present
+    const constraintsMatch = sectionText.match(
+      /\*\*Constraints:\*\*\s*\n([\s\S]*?)(?=\n###|\n##|$)/,
+    );
+    const constraints = constraintsMatch?.[1]?.trim();
+
+    // Body is everything before the Constraints heading (or the whole text)
+    let body: string;
+    if (constraintsMatch?.index !== undefined) {
+      body = sectionText.slice(0, constraintsMatch.index).trim();
+    } else {
+      body = sectionText;
+    }
+
+    steps.push({
+      number: heading.number,
+      name: heading.name,
+      body,
+      ...(constraints ? { constraints } : {}),
+    });
+  }
+
+  return steps;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a `.sop.md` markdown string into a structured `SopDocument`.
+ *
+ * @param markdown - The raw markdown content of a `.sop.md` file.
+ * @returns A parsed `SopDocument` with title, overview, parameters, steps,
+ *          and optional examples.
+ */
+export function parseSopContent(markdown: string): SopDocument {
+  // --- Title (first h1) ---
+  const titleMatch = markdown.match(/^#\s+(.+)$/m);
+  const title = titleMatch?.[1]?.trim() ?? 'Untitled SOP';
+
+  // --- Overview ---
+  const overviewRaw = extractSection(markdown, 'Overview');
+  const overview = overviewRaw ?? '';
+
+  // --- Parameters ---
+  const parametersRaw = extractSection(markdown, 'Parameters');
+  const parameters = parametersRaw ? parseParameters(parametersRaw) : [];
+
+  // --- Steps ---
+  const stepsRaw = extractSection(markdown, 'Steps');
+  const steps = stepsRaw ? parseSteps(stepsRaw) : [];
+
+  // --- Examples (optional) ---
+  const examplesRaw = extractSection(markdown, 'Examples');
+
+  return {
+    title,
+    overview,
+    parameters,
+    steps,
+    ...(examplesRaw !== null ? { examples: examplesRaw } : {}),
+  };
+}

packages/ion/src/format/sop-to-yaml.ts

@@ -0,0 +1,102 @@
+/**
+ * SOP-to-YAML converter for the Ion workflow engine.
+ *
+ * Converts a parsed `SopDocument` into a YAML workflow definition string
+ * that can be fed back into the Ion YAML loader.
+ */
+
+import type { SopDocument } from './sop-parser.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Convert a title string to kebab-case for use as a YAML identifier. */
+function toKebabCase(title: string): string {
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-') // non-alphanumeric → hyphen
+    .replace(/^-+|-+$/g, ''); // strip leading/trailing hyphens
+}
+
+/**
+ * Indent every line of a multi-line string by the given number of spaces.
+ * Empty lines are preserved without extra indentation.
+ */
+function indentBlock(text: string, spaces: number): string {
+  const prefix = ' '.repeat(spaces);
+  return text
+    .split('\n')
+    .map((line) => (line.length > 0 ? prefix + line : line))
+    .join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a parsed `SopDocument` into a YAML workflow definition string.
+ *
+ * The output is valid YAML that can be loaded by the Ion YAML loader.
+ * Steps become sequential prompt nodes with `depends_on` linking.
+ * Constraints are appended to the prompt body as plain text.
+ * Only `prompt:` nodes are emitted — SOP is conversation-only.
+ *
+ * @param sop - The parsed SOP document.
+ * @returns A YAML string representing the workflow.
+ */
+export function convertSopToWorkflowYaml(sop: SopDocument): string {
+  const name = toKebabCase(sop.title);
+  const lines: string[] = [];
+
+  // --- Header comment with parameter info ---
+  if (sop.parameters.length > 0) {
+    lines.push('# Parameters:');
+    for (const param of sop.parameters) {
+      const tag = param.type === 'required' ? 'required' : 'optional';
+      const defaultPart = param.default ? `, default: ${param.default}` : '';
+      lines.push(`#   ${param.name} (${tag}${defaultPart}): ${param.description}`);
+    }
+    lines.push('');
+  }
+
+  // --- Top-level fields ---
+  lines.push(`name: ${name}`);
+  lines.push(`description: |`);
+  lines.push(indentBlock(sop.overview || 'No description provided.', 2));
+  lines.push('');
+
+  // --- Nodes ---
+  lines.push('nodes:');
+
+  for (let i = 0; i < sop.steps.length; i++) {
+    const step = sop.steps[i]!;
+    const stepId = `step_${step.number}`;
+    const isFirst = i === 0;
+
+    // Build the prompt body: step body + constraints (if any)
+    let promptBody = step.body;
+    if (step.constraints) {
+      promptBody += `\n\nConstraints:\n${step.constraints}`;
+    }
+
+    lines.push(`  - id: ${stepId}`);
+    lines.push(`    prompt: |`);
+    lines.push(indentBlock(promptBody, 6));
+
+    if (isFirst) {
+      lines.push(`    depends_on: []`);
+    } else {
+      const prevStep = sop.steps[i - 1]!;
+      lines.push(`    depends_on: [step_${prevStep.number}]`);
+    }
+
+    // Blank line between nodes (but not after the last one)
+    if (i < sop.steps.length - 1) {
+      lines.push('');
+    }
+  }
+
+  return lines.join('\n') + '\n';
+}

packages/ion/src/index.ts

@@ -0,0 +1,152 @@
+// Schema layer — types and validation
+export type {
+  StepRetryConfig,
+  LoopNodeConfig,
+  TriggerRule,
+  EffortLevel,
+  ThinkingConfig,
+  ApprovalOnReject,
+  DagNodeBase,
+  CommandNode,
+  PromptNode,
+  BashNode,
+  ScriptNode,
+  LoopNode,
+  ApprovalNode,
+  CancelNode,
+  DagNode,
+  ModelReasoningEffort,
+  WebSearchMode,
+  WorkflowRequirement,
+  WorkflowWorktreePolicy,
+  SandboxConfig,
+  ProviderOverrides,
+  WorkflowBase,
+  WorkflowDefinition,
+  WorkflowSource,
+  WorkflowExecutionResult as SchemaWorkflowExecutionResult,
+  WorkflowWithSource,
+  WorkflowLoadError,
+  WorkflowLoadResult,
+  LoadCommandResult,
+  WorkflowRunStatus,
+  NodeState,
+  NodeOutput,
+  ApprovalContext,
+  WorkflowRun,
+  NodeExecutionResult,
+} from './schema/index.js';
+
+export {
+  stepRetryConfigSchema,
+  loopNodeConfigSchema,
+  triggerRuleSchema,
+  TRIGGER_RULES,
+  DEFAULT_TRIGGER_RULE,
+  effortLevelSchema,
+  thinkingConfigSchema,
+  approvalOnRejectSchema,
+  dagNodeBaseSchema,
+  commandNodeSchema,
+  promptNodeSchema,
+  bashNodeSchema,
+  scriptNodeSchema,
+  loopNodeSchema,
+  approvalNodeSchema,
+  cancelNodeSchema,
+  dagNodeSchema,
+  isBashNode,
+  isLoopNode,
+  isApprovalNode,
+  isCancelNode,
+  isScriptNode,
+  isPromptNode,
+  isCommandNode,
+  modelReasoningEffortSchema,
+  webSearchModeSchema,
+  workflowRequirementSchema,
+  workflowWorktreePolicySchema,
+  sandboxConfigSchema,
+  providerOverridesSchema,
+  workflowBaseSchema,
+  workflowDefinitionSchema,
+  WorkflowSourceSchema,
+  workflowExecutionResultSchema,
+  workflowWithSourceSchema,
+  workflowLoadErrorSchema,
+  workflowLoadResultSchema,
+  loadCommandResultSchema,
+  WorkflowRunStatusSchema,
+  TERMINAL_WORKFLOW_STATUSES,
+  RESUMABLE_WORKFLOW_STATUSES,
+  NodeStateSchema,
+  ApprovalContextSchema,
+  WorkflowRunSchema,
+  nodeOutputSchema,
+} from './schema/index.js';
+
+// Engine — core execution logic
+export type {
+  IWorkflowPlatform,
+  IWorkflowStore,
+  IAgentProvider,
+  WorkflowDeps,
+  WorkflowConfig,
+  ProviderConfig,
+  CommandFolderConfig,
+  CreateWorkflowRunData,
+  WorkflowEvent,
+  DagWorkflowResult,
+  WorkflowExecutionOptions,
+  HydratedResumableRun,
+  ProjectPaths,
+  ErrorCategory,
+} from './engine/index.js';
+
+export {
+  buildTopologicalLayers,
+  checkTriggerRule,
+  executeNodeInternal,
+  executeScriptNode,
+  handleApprovalNode,
+  handleLoopNode,
+  executeDagWorkflow,
+  executeWorkflow,
+  hydrateResumableRun,
+  resolveProjectPaths,
+  substituteWorkflowVariables,
+  substituteNodeOutputRefs,
+  buildPromptWithContext,
+  evaluateCondition,
+  classifyError,
+  safeSendMessage,
+  formatSubprocessFailure,
+  resolveNodeOutputField,
+  OutputRefError,
+  DagCycleError,
+  NodeTimeoutError,
+  ApprovalRejectedError,
+  LoopMaxIterationsError,
+} from './engine/index.js';
+
+// Storage backends
+export {
+  createFsStore,
+  createSqliteStore,
+  createPostgresStore,
+} from './store/index.js';
+export type {
+  IWorkflowStore as StoreIWorkflowStore,
+} from './store/index.js';
+
+// Format — markdown transpiler
+export {
+  parseSopContent,
+  convertSopToWorkflowYaml,
+  discoverSopFiles,
+} from './format/index.js';
+export type {
+  SopDocument,
+  SopParameter,
+  SopStep,
+} from './format/index.js';

packages/ion/src/schema/__tests__/dag-node.test.ts

@@ -0,0 +1,377 @@
+import { describe, it, expect } from 'vitest';
+import {
+  dagNodeSchema,
+  promptNodeSchema,
+  commandNodeSchema,
+  bashNodeSchema,
+  scriptNodeSchema,
+  loopNodeSchema,
+  approvalNodeSchema,
+  cancelNodeSchema,
+  loopNodeConfigSchema,
+  stepRetryConfigSchema,
+  triggerRuleSchema,
+  isBashNode,
+  isLoopNode,
+  isApprovalNode,
+  isCancelNode,
+  isScriptNode,
+  isPromptNode,
+  isCommandNode,
+  effortLevelSchema,
+  thinkingConfigSchema,
+  approvalOnRejectSchema,
+  dagNodeBaseSchema,
+} from '../index.js';
+import type {
+  DagNode,
+  PromptNode,
+  CommandNode,
+  BashNode,
+  ScriptNode,
+  LoopNode,
+  ApprovalNode,
+  CancelNode,
+} from '../index.js';
+
+const validBase = {
+  id: 'test-node',
+  depends_on: [],
+};
+
+describe('dagNodeSchema', () => {
+  it('validates a prompt node', () => {
+    const node = { ...validBase, kind: 'prompt' as const, prompt: 'Do the thing' };
+    const result = dagNodeSchema.safeParse(node);
+    expect(result.success).toBe(true);
+  });
+
+  it('validates a command node', () => {
+    const node = { ...validBase, kind: 'command' as const, command: 'echo hello' };
+    const result = dagNodeSchema.safeParse(node);
+    expect(result.success).toBe(true);
+  });
+
+  it('validates a bash node', () => {
+    const node = { ...validBase, kind: 'bash' as const, bash: 'echo hello' };
+    const result = dagNodeSchema.safeParse(node);
+    expect(result.success).toBe(true);
+  });
+
+  it('validates a script node', () => {
+    const node = { ...validBase, kind: 'script' as const, script: 'print(1)', runtime: 'bun' as const };
+    const result = dagNodeSchema.safeParse(node);
+    expect(result.success).toBe(true);
+  });
+
+  it('validates a loop node', () => {
+    const node = {
+      ...validBase,
+      kind: 'loop' as const,
+      config: { prompt: 'iterate', until: 'done', max_iterations: 5 },
+    };
+    const result = dagNodeSchema.safeParse(node);
+    expect(result.success).toBe(true);
+  });
+
+  it('validates an approval node', () => {
+    const node = { ...validBase, kind: 'approval' as const, message: 'Approve this?' };
+    const result = dagNodeSchema.safeParse(node);
+    expect(result.success).toBe(true);
+  });
+
+  it('validates a cancel node', () => {
+    const node = { ...validBase, kind: 'cancel' as const };
+    const result = dagNodeSchema.safeParse(node);
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects a node with no kind field', () => {
+    const result = dagNodeSchema.safeParse({ id: 'x', prompt: 'y' });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects a node with an invalid kind', () => {
+    const result = dagNodeSchema.safeParse({ ...validBase, kind: 'unknown' });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('node type unique fields', () => {
+  it('prompt node requires prompt or command_file', () => {
+    const result = promptNodeSchema.safeParse({ ...validBase, kind: 'prompt' });
+    expect(result.success).toBe(true);
+  });
+
+  it('command node requires command', () => {
+    const result = commandNodeSchema.safeParse({ ...validBase, kind: 'command' });
+    expect(result.success).toBe(false);
+  });
+
+  it('bash node requires bash', () => {
+    const result = bashNodeSchema.safeParse({ ...validBase, kind: 'bash' });
+    expect(result.success).toBe(false);
+  });
+
+  it('script node requires script and runtime', () => {
+    const noScript = scriptNodeSchema.safeParse({ ...validBase, kind: 'script', runtime: 'bun' });
+    expect(noScript.success).toBe(false);
+
+    const noRuntime = scriptNodeSchema.safeParse({ ...validBase, kind: 'script', script: 'print(1)' });
+    expect(noRuntime.success).toBe(false);
+
+    const valid = scriptNodeSchema.safeParse({
+      ...validBase,
+      kind: 'script',
+      script: 'print(1)',
+      runtime: 'bun',
+    });
+    expect(valid.success).toBe(true);
+  });
+
+  it('loop node requires config', () => {
+    const result = loopNodeSchema.safeParse({ ...validBase, kind: 'loop' });
+    expect(result.success).toBe(false);
+  });
+
+  it('approval node requires message', () => {
+    const result = approvalNodeSchema.safeParse({ ...validBase, kind: 'approval' });
+    expect(result.success).toBe(false);
+  });
+
+  it('cancel node does not require reason', () => {
+    const result = cancelNodeSchema.safeParse({ ...validBase, kind: 'cancel' });
+    expect(result.success).toBe(true);
+  });
+});
+
+describe('loopNodeConfigSchema', () => {
+  it('validates a minimal config', () => {
+    const result = loopNodeConfigSchema.safeParse({
+      prompt: 'iterate',
+      until: 'done',
+      max_iterations: 5,
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects empty prompt', () => {
+    const result = loopNodeConfigSchema.safeParse({
+      prompt: '',
+      until: 'done',
+      max_iterations: 5,
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects empty until', () => {
+    const result = loopNodeConfigSchema.safeParse({
+      prompt: 'iterate',
+      until: '',
+      max_iterations: 5,
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects non-positive max_iterations', () => {
+    const zeroResult = loopNodeConfigSchema.safeParse({
+      prompt: 'iterate',
+      until: 'done',
+      max_iterations: 0,
+    });
+    expect(zeroResult.success).toBe(false);
+
+    const negResult = loopNodeConfigSchema.safeParse({
+      prompt: 'iterate',
+      until: 'done',
+      max_iterations: -1,
+    });
+    expect(negResult.success).toBe(false);
+  });
+
+  it('requires gate_message when interactive is true', () => {
+    const noGate = loopNodeConfigSchema.safeParse({
+      prompt: 'iterate',
+      until: 'done',
+      max_iterations: 5,
+      interactive: true,
+    });
+    expect(noGate.success).toBe(false);
+
+    const withGate = loopNodeConfigSchema.safeParse({
+      prompt: 'iterate',
+      until: 'done',
+      max_iterations: 5,
+      interactive: true,
+      gate_message: 'Approve this iteration?',
+    });
+    expect(withGate.success).toBe(true);
+  });
+
+  it('allows interactive=false without gate_message', () => {
+    const result = loopNodeConfigSchema.safeParse({
+      prompt: 'iterate',
+      until: 'done',
+      max_iterations: 5,
+      interactive: false,
+    });
+    expect(result.success).toBe(true);
+  });
+});
+
+describe('stepRetryConfigSchema', () => {
+  it('validates a minimal retry config', () => {
+    const result = stepRetryConfigSchema.safeParse({ max_attempts: 3 });
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects max_attempts below 1', () => {
+    const result = stepRetryConfigSchema.safeParse({ max_attempts: 0 });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects max_attempts above 5', () => {
+    const result = stepRetryConfigSchema.safeParse({ max_attempts: 6 });
+    expect(result.success).toBe(false);
+  });
+
+  it('accepts max_attempts at boundaries (1 and 5)', () => {
+    expect(stepRetryConfigSchema.safeParse({ max_attempts: 1 }).success).toBe(true);
+    expect(stepRetryConfigSchema.safeParse({ max_attempts: 5 }).success).toBe(true);
+  });
+
+  it('rejects delay_ms below 1000', () => {
+    const result = stepRetryConfigSchema.safeParse({ max_attempts: 2, delay_ms: 500 });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects delay_ms above 60000', () => {
+    const result = stepRetryConfigSchema.safeParse({ max_attempts: 2, delay_ms: 70000 });
+    expect(result.success).toBe(false);
+  });
+
+  it('accepts delay_ms at boundaries (1000 and 60000)', () => {
+    expect(stepRetryConfigSchema.safeParse({ max_attempts: 2, delay_ms: 1000 }).success).toBe(true);
+    expect(stepRetryConfigSchema.safeParse({ max_attempts: 2, delay_ms: 60000 }).success).toBe(true);
+  });
+
+  it('defaults on_error to transient', () => {
+    const result = stepRetryConfigSchema.parse({ max_attempts: 2 });
+    expect(result.on_error).toBe('transient');
+  });
+});
+
+describe('triggerRuleSchema', () => {
+  it('validates all trigger rules', () => {
+    const rules = ['all_success', 'one_success', 'all_done', 'none_failed_min_one_success'];
+    for (const rule of rules) {
+      expect(triggerRuleSchema.safeParse(rule).success).toBe(true);
+    }
+  });
+
+  it('rejects invalid trigger rules', () => {
+    const result = triggerRuleSchema.safeParse('invalid_rule');
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('type guards', () => {
+  const nodes: DagNode[] = [
+    { ...validBase, kind: 'prompt', prompt: 'test' } as PromptNode,
+    { ...validBase, kind: 'command', command: 'echo' } as CommandNode,
+    { ...validBase, kind: 'bash', bash: 'echo' } as BashNode,
+    { ...validBase, kind: 'script', script: 'print(1)', runtime: 'bun' } as ScriptNode,
+    { ...validBase, kind: 'loop', config: { prompt: 'x', until: 'y', max_iterations: 3 } } as LoopNode,
+    { ...validBase, kind: 'approval', message: 'ok?' } as ApprovalNode,
+    { ...validBase, kind: 'cancel' } as CancelNode,
+  ];
+
+  it('isPromptNode identifies prompt nodes', () => {
+    expect(isPromptNode(nodes[0])).toBe(true);
+    expect(isPromptNode(nodes[1])).toBe(false);
+  });
+
+  it('isCommandNode identifies command nodes', () => {
+    expect(isCommandNode(nodes[1])).toBe(true);
+    expect(isCommandNode(nodes[0])).toBe(false);
+  });
+
+  it('isBashNode identifies bash nodes', () => {
+    expect(isBashNode(nodes[2])).toBe(true);
+    expect(isBashNode(nodes[0])).toBe(false);
+  });
+
+  it('isScriptNode identifies script nodes', () => {
+    expect(isScriptNode(nodes[3])).toBe(true);
+    expect(isScriptNode(nodes[0])).toBe(false);
+  });
+
+  it('isLoopNode identifies loop nodes', () => {
+    expect(isLoopNode(nodes[4])).toBe(true);
+    expect(isLoopNode(nodes[0])).toBe(false);
+  });
+
+  it('isApprovalNode identifies approval nodes', () => {
+    expect(isApprovalNode(nodes[5])).toBe(true);
+    expect(isApprovalNode(nodes[0])).toBe(false);
+  });
+
+  it('isCancelNode identifies cancel nodes', () => {
+    expect(isCancelNode(nodes[6])).toBe(true);
+    expect(isCancelNode(nodes[0])).toBe(false);
+  });
+});
+
+describe('effortLevelSchema', () => {
+  it('validates all effort levels', () => {
+    expect(effortLevelSchema.safeParse('low').success).toBe(true);
+    expect(effortLevelSchema.safeParse('medium').success).toBe(true);
+    expect(effortLevelSchema.safeParse('high').success).toBe(true);
+  });
+
+  it('rejects invalid effort levels', () => {
+    expect(effortLevelSchema.safeParse('extreme').success).toBe(false);
+  });
+});
+
+describe('thinkingConfigSchema', () => {
+  it('validates a minimal thinking config', () => {
+    const result = thinkingConfigSchema.safeParse({});
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.enabled).toBe(false);
+    }
+  });
+
+  it('validates a full thinking config', () => {
+    const result = thinkingConfigSchema.safeParse({ enabled: true, max_tokens: 4096 });
+    expect(result.success).toBe(true);
+  });
+});
+
+describe('approvalOnRejectSchema', () => {
+  it('validates all on-reject actions', () => {
+    expect(approvalOnRejectSchema.safeParse('retry').success).toBe(true);
+    expect(approvalOnRejectSchema.safeParse('fail').success).toBe(true);
+    expect(approvalOnRejectSchema.safeParse('skip').success).toBe(true);
+  });
+
+  it('rejects invalid on-reject actions', () => {
+    expect(approvalOnRejectSchema.safeParse('restart').success).toBe(false);
+  });
+});
+
+describe('dagNodeBaseSchema', () => {
+  it('validates a minimal base node', () => {
+    const result = dagNodeBaseSchema.safeParse({
+      id: 'node-1',
+      kind: 'prompt',
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('defaults depends_on to empty array', () => {
+    const result = dagNodeBaseSchema.parse({ id: 'node-1', kind: 'prompt' });
+    expect(result.depends_on).toEqual([]);
+  });
+});

packages/ion/src/schema/dag-node.ts

@@ -0,0 +1,273 @@
+import { z } from 'zod';
+import { stepRetryConfigSchema } from './retry.js';
+import { loopNodeConfigSchema } from './loop.js';
+import { triggerRuleSchema } from './trigger-rule.js';
+
+// ---------------------------------------------------------------------------
+// Effort level
+// ---------------------------------------------------------------------------
+
+/** Effort level for AI model calls. */
+export const effortLevelSchema = z.enum(['low', 'medium', 'high']);
+
+export type EffortLevel = z.infer<typeof effortLevelSchema>;
+
+// ---------------------------------------------------------------------------
+// Thinking configuration
+// ---------------------------------------------------------------------------
+
+/** Configuration for extended thinking / chain-of-thought. */
+export const thinkingConfigSchema = z.object({
+  /** Whether thinking is enabled. */
+  enabled: z.boolean().default(false),
+  /** Maximum thinking tokens. */
+  max_tokens: z.number().int().positive().optional(),
+});
+
+export type ThinkingConfig = z.infer<typeof thinkingConfigSchema>;
+
+// ---------------------------------------------------------------------------
+// Approval on-reject action
+// ---------------------------------------------------------------------------
+
+/** What to do when an approval node is rejected. */
+export const approvalOnRejectSchema = z.enum(['retry', 'fail', 'skip']);
+
+export type ApprovalOnReject = z.infer<typeof approvalOnRejectSchema>;
+
+// ---------------------------------------------------------------------------
+// Base DAG node
+// ---------------------------------------------------------------------------
+
+/** The kind of a DAG node determines how it executes. */
+export const dagNodeKindSchema = z.enum([
+  'prompt',
+  'command',
+  'bash',
+  'script',
+  'approval',
+  'loop',
+  'cancel',
+]);
+
+/** Base fields shared by all DAG node types. */
+export const dagNodeBaseSchema = z.object({
+  id: z.string(),
+  kind: dagNodeKindSchema,
+  name: z.string().optional(),
+  when: z.string().optional(),
+  depends_on: z.array(z.string()).default([]),
+  trigger_rule: triggerRuleSchema.optional(),
+  retry: stepRetryConfigSchema.optional(),
+  env: z.record(z.string()).optional(),
+});
+
+export type DagNodeBase = z.infer<typeof dagNodeBaseSchema>;
+
+export type DagNodeKind = z.infer<typeof dagNodeKindSchema>;
+
+// ---------------------------------------------------------------------------
+// Prompt node — sends a prompt to an AI provider
+// ---------------------------------------------------------------------------
+
+export const promptNodeSchema = z.object({
+  id: z.string(),
+  kind: z.literal('prompt'),
+  /** Human-readable name for display. */
+  name: z.string().optional(),
+  /** The prompt text (inline). Mutually exclusive with command_file. */
+  prompt: z.string().optional(),
+  /** Path to a command file containing the prompt. */
+  command_file: z.string().optional(),
+  /** Provider id to use (overrides workflow default). */
+  provider: z.string().optional(),
+  /** Model override for the provider. */
+  model: z.string().optional(),
+  /** Structured output format definition. */
+  output_format: z
+    .record(z.unknown())
+    .optional(),
+  /** Condition expression; node runs only when truthy. */
+  when: z.string().optional(),
+  /** Node ids this node depends on. */
+  depends_on: z.array(z.string()).default([]),
+  /** Trigger rule for evaluating dependency states. */
+  trigger_rule: triggerRuleSchema.optional(),
+  /** Retry configuration. */
+  retry: stepRetryConfigSchema.optional(),
+  /** Idle timeout in milliseconds. */
+  idle_timeout_ms: z.number().positive().optional(),
+  /** Environment variable overrides for this node. */
+  env: z.record(z.string()).optional(),
+});
+
+// ---------------------------------------------------------------------------
+// Command node — runs a shell command
+// ---------------------------------------------------------------------------
+
+export const commandNodeSchema = z.object({
+  id: z.string(),
+  kind: z.literal('command'),
+  name: z.string().optional(),
+  /** The command string to execute. */
+  command: z.string(),
+  /** Working directory override. */
+  cwd: z.string().optional(),
+  when: z.string().optional(),
+  depends_on: z.array(z.string()).default([]),
+  trigger_rule: triggerRuleSchema.optional(),
+  retry: stepRetryConfigSchema.optional(),
+  env: z.record(z.string()).optional(),
+});
+
+// ---------------------------------------------------------------------------
+// Bash node — runs a bash script
+// ---------------------------------------------------------------------------
+
+export const bashNodeSchema = z.object({
+  id: z.string(),
+  kind: z.literal('bash'),
+  name: z.string().optional(),
+  /** Bash script content to execute. */
+  bash: z.string(),
+  /** Timeout in milliseconds. */
+  timeout_ms: z.number().positive().optional(),
+  when: z.string().optional(),
+  depends_on: z.array(z.string()).default([]),
+  trigger_rule: triggerRuleSchema.optional(),
+  retry: stepRetryConfigSchema.optional(),
+  env: z.record(z.string()).optional(),
+});
+
+// ---------------------------------------------------------------------------
+// Script node — runs a script with a specific runtime
+// ---------------------------------------------------------------------------
+
+export const scriptNodeSchema = z.object({
+  id: z.string(),
+  kind: z.literal('script'),
+  name: z.string().optional(),
+  /** Script content to execute. */
+  script: z.string(),
+  /** Runtime: 'bun' or 'uv'. */
+  runtime: z.enum(['bun', 'uv']),
+  /** Dependencies to install before running. */
+  deps: z.array(z.string()).default([]),
+  /** Timeout in milliseconds. */
+  timeout_ms: z.number().positive().optional(),
+  when: z.string().optional(),
+  depends_on: z.array(z.string()).default([]),
+  trigger_rule: triggerRuleSchema.optional(),
+  retry: stepRetryConfigSchema.optional(),
+  env: z.record(z.string()).optional(),
+});
+
+// ---------------------------------------------------------------------------
+// Approval node — pauses for human approval
+// ---------------------------------------------------------------------------
+
+export const approvalNodeSchema = z.object({
+  id: z.string(),
+  kind: z.literal('approval'),
+  name: z.string().optional(),
+  /** Message shown to the approver. */
+  message: z.string(),
+  /** Prompt to execute if the approval is rejected. */
+  on_reject: z.string().optional(),
+  when: z.string().optional(),
+  depends_on: z.array(z.string()).default([]),
+  trigger_rule: triggerRuleSchema.optional(),
+  env: z.record(z.string()).optional(),
+});
+
+// ---------------------------------------------------------------------------
+// Loop node — iterates until a condition is met
+// ---------------------------------------------------------------------------
+
+export const loopNodeSchema = z.object({
+  id: z.string(),
+  kind: z.literal('loop'),
+  name: z.string().optional(),
+  /** Loop configuration (prompt, until, max_iterations, etc.). */
+  config: loopNodeConfigSchema,
+  /** Provider id to use (overrides workflow default). */
+  provider: z.string().optional(),
+  /** Model override for the provider. */
+  model: z.string().optional(),
+  when: z.string().optional(),
+  depends_on: z.array(z.string()).default([]),
+  trigger_rule: triggerRuleSchema.optional(),
+  retry: stepRetryConfigSchema.optional(),
+  env: z.record(z.string()).optional(),
+});
+
+// ---------------------------------------------------------------------------
+// Cancel node — cancels the workflow
+// ---------------------------------------------------------------------------
+
+export const cancelNodeSchema = z.object({
+  id: z.string(),
+  kind: z.literal('cancel'),
+  name: z.string().optional(),
+  /** Reason for cancellation. */
+  reason: z.string().optional(),
+  when: z.string().optional(),
+  depends_on: z.array(z.string()).default([]),
+  trigger_rule: triggerRuleSchema.optional(),
+  env: z.record(z.string()).optional(),
+});
+
+// ---------------------------------------------------------------------------
+// Union type — any DAG node
+// ---------------------------------------------------------------------------
+
+export const dagNodeSchema = z.discriminatedUnion('kind', [
+  promptNodeSchema,
+  commandNodeSchema,
+  bashNodeSchema,
+  scriptNodeSchema,
+  approvalNodeSchema,
+  loopNodeSchema,
+  cancelNodeSchema,
+]);
+
+export type DagNode = z.infer<typeof dagNodeSchema>;
+export type PromptNode = z.infer<typeof promptNodeSchema>;
+export type CommandNode = z.infer<typeof commandNodeSchema>;
+export type BashNode = z.infer<typeof bashNodeSchema>;
+export type ScriptNode = z.infer<typeof scriptNodeSchema>;
+export type ApprovalNode = z.infer<typeof approvalNodeSchema>;
+export type LoopNode = z.infer<typeof loopNodeSchema>;
+export type CancelNode = z.infer<typeof cancelNodeSchema>;
+
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+
+export function isBashNode(node: DagNode): node is BashNode {
+  return node.kind === 'bash';
+}
+
+export function isScriptNode(node: DagNode): node is ScriptNode {
+  return node.kind === 'script';
+}
+
+export function isLoopNode(node: DagNode): node is LoopNode {
+  return node.kind === 'loop';
+}
+
+export function isApprovalNode(node: DagNode): node is ApprovalNode {
+  return node.kind === 'approval';
+}
+
+export function isCancelNode(node: DagNode): node is CancelNode {
+  return node.kind === 'cancel';
+}
+
+export function isPromptNode(node: DagNode): node is PromptNode {
+  return node.kind === 'prompt';
+}
+
+export function isCommandNode(node: DagNode): node is CommandNode {
+  return node.kind === 'command';
+}