feat(mcp): add type-inject MCP server for TypeScript type recovery

Registers @nick-vi/type-inject-mcp as a stdio MCP server via npx.
Provides lookup_type and list_types tools for TypeScript type
recovery — solves the 0% TS type recovery gap in codecontext.

.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/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/inference/llama-args-validator.ts

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

data/mcp.example.json

@@ -7,6 +7,12 @@
         "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
       },
       "enabled": false
+    },
+    "type-inject": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@nick-vi/type-inject-mcp"],
+      "enabled": true
     }
   }
 }

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';
+}

packages/ion/src/schema/index.ts

@@ -0,0 +1,111 @@
+// ---------------------------------------------------------------------------
+// Ion Schema Layer — Public API
+// ---------------------------------------------------------------------------
+
+// retry.ts
+export {
+  stepRetryConfigSchema,
+  type StepRetryConfig,
+} from './retry.js';
+
+// loop.ts
+export {
+  loopNodeConfigSchema,
+  type LoopNodeConfig,
+} from './loop.js';
+
+// trigger-rule.ts
+export {
+  triggerRuleSchema,
+  TRIGGER_RULES,
+  DEFAULT_TRIGGER_RULE,
+  type TriggerRule,
+} from './trigger-rule.js';
+
+// dag-node.ts
+export {
+  effortLevelSchema,
+  type EffortLevel,
+  thinkingConfigSchema,
+  type ThinkingConfig,
+  approvalOnRejectSchema,
+  type ApprovalOnReject,
+  dagNodeBaseSchema,
+  type DagNodeBase,
+  commandNodeSchema,
+  promptNodeSchema,
+  bashNodeSchema,
+  scriptNodeSchema,
+  loopNodeSchema,
+  approvalNodeSchema,
+  cancelNodeSchema,
+  type CommandNode,
+  type PromptNode,
+  type BashNode,
+  type ScriptNode,
+  type LoopNode,
+  type ApprovalNode,
+  type CancelNode,
+  dagNodeSchema,
+  type DagNode,
+  isBashNode,
+  isLoopNode,
+  isApprovalNode,
+  isCancelNode,
+  isScriptNode,
+  isPromptNode,
+  isCommandNode,
+} from './dag-node.js';
+
+// workflow.ts
+export {
+  modelReasoningEffortSchema,
+  type ModelReasoningEffort,
+  webSearchModeSchema,
+  type WebSearchMode,
+  workflowRequirementSchema,
+  type WorkflowRequirement,
+  workflowWorktreePolicySchema,
+  type WorkflowWorktreePolicy,
+  sandboxConfigSchema,
+  type SandboxConfig,
+  providerOverridesSchema,
+  type ProviderOverrides,
+  workflowBaseSchema,
+  type WorkflowBase,
+  workflowDefinitionSchema,
+  type WorkflowDefinition,
+  WorkflowSourceSchema,
+  type WorkflowSource,
+  workflowExecutionResultSchema,
+  type WorkflowExecutionResult,
+  workflowWithSourceSchema,
+  type WorkflowWithSource,
+  workflowLoadErrorSchema,
+  type WorkflowLoadError,
+  workflowLoadResultSchema,
+  type WorkflowLoadResult,
+  loadCommandResultSchema,
+  type LoadCommandResult,
+} from './workflow.js';
+
+// workflow-run.ts
+export {
+  WorkflowRunStatusSchema,
+  type WorkflowRunStatus,
+  TERMINAL_WORKFLOW_STATUSES,
+  RESUMABLE_WORKFLOW_STATUSES,
+  NodeStateSchema,
+  type NodeState,
+  ApprovalContextSchema,
+  type ApprovalContext,
+  WorkflowRunSchema,
+  type WorkflowRun,
+} from './workflow-run.js';
+
+// node-output.ts
+export {
+  nodeOutputSchema,
+  type NodeOutput,
+  type NodeExecutionResult,
+} from './node-output.js';

packages/ion/src/schema/loop.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+
+/**
+ * Configuration for a loop-type DAG node.
+ *
+ * The loop repeatedly invokes the model with the given prompt until the
+ * `until` condition is satisfied or `max_iterations` is reached.
+ * When `interactive` is true, a human gate must approve each iteration.
+ */
+export const loopNodeConfigSchema = z
+  .object({
+    /** The prompt sent to the model on each iteration. */
+    prompt: z.string().min(1, 'loop prompt must not be empty'),
+
+    /** Natural-language condition that must be true for the loop to exit. */
+    until: z.string().min(1, 'loop until condition must not be empty'),
+
+    /** Maximum iterations before the loop is force-stopped. */
+    max_iterations: z
+      .number()
+      .int()
+      .positive('max_iterations must be a positive integer'),
+
+    /** Whether each iteration starts with a fresh context window. */
+    fresh_context: z.boolean().default(false),
+
+    /** Optional bash command whose exit code is used as the until-check. */
+    until_bash: z.string().optional(),
+
+    /** When true, a human must approve each iteration before it proceeds. */
+    interactive: z.boolean().optional(),
+
+    /** Message shown to the human gate when interactive is true. */
+    gate_message: z.string().optional(),
+  })
+  .superRefine((config, ctx) => {
+    if (config.interactive && !config.gate_message) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'gate_message is required when interactive is true',
+        path: ['gate_message'],
+      });
+    }
+  });
+
+export type LoopNodeConfig = z.infer<typeof loopNodeConfigSchema>;

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

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+
+/**
+ * Output produced by a single DAG node after execution.
+ *
+ * Captures the result text, structured fields, and execution metadata
+ * so downstream nodes can reference outputs via `$nodeId.output` syntax.
+ */
+export const nodeOutputSchema = z.object({
+  /** The node id that produced this output. */
+  nodeId: z.string(),
+
+  /** Current state of the node execution. */
+  state: z.enum(['pending', 'running', 'completed', 'failed', 'skipped']),
+
+  /** The raw text output from the node (alias for text for backward compat). */
+  output: z.string().default(''),
+
+  /** The raw text output from the node. */
+  text: z.string().optional(),
+
+  /** Structured output fields (when output_format is defined). */
+  fields: z.record(z.unknown()).optional(),
+
+  /** Error message if the node failed. */
+  error: z.string().optional(),
+
+  /** Token usage or cost metadata. */
+  costUsd: z.number().optional(),
+});
+
+export type NodeOutput = z.infer<typeof nodeOutputSchema>;
+
+/**
+ * Result of executing a single node within the DAG.
+ *
+ * Internal to the engine — not persisted directly but used to build
+ * the nodeOutputs map that flows between layers.
+ */
+export interface NodeExecutionResult {
+  state: 'completed' | 'failed' | 'skipped';
+  output?: string;
+  fields?: Record<string, unknown>;
+  error?: string;
+  costUsd?: number;
+}

packages/ion/src/schema/retry.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+
+/**
+ * Retry configuration for a DAG node step.
+ *
+ * Controls how many times a step can be re-attempted on failure,
+ * the delay between attempts, and which classes of errors trigger a retry.
+ */
+export const stepRetryConfigSchema = z.object({
+  /** Maximum number of retry attempts (1–5 inclusive). */
+  max_attempts: z
+    .number()
+    .int()
+    .min(1, 'max_attempts must be at least 1')
+    .max(5, 'max_attempts must be at most 5'),
+
+  /** Milliseconds to wait between retry attempts (1000–60000). */
+  delay_ms: z
+    .number()
+    .int()
+    .min(1000, 'delay_ms must be at least 1000')
+    .max(60000, 'delay_ms must be at most 60000')
+    .optional(),
+
+  /** Which errors trigger a retry. Defaults to 'transient'. */
+  on_error: z
+    .enum(['transient', 'all'])
+    .default('transient'),
+});
+
+export type StepRetryConfig = z.infer<typeof stepRetryConfigSchema>;

packages/ion/src/schema/trigger-rule.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+
+/**
+ * Trigger rule for a DAG node.
+ *
+ * Determines when a node should run based on the completion status of its
+ * dependencies. Mirrors Airflow's trigger rules.
+ */
+export const triggerRuleSchema = z.enum([
+  /** All dependencies must have completed successfully. */
+  'all_success',
+  /** At least one dependency must have completed successfully. */
+  'one_success',
+  /** All dependencies must have finished (any status). */
+  'all_done',
+  /** No dependency failed AND at least one succeeded. */
+  'none_failed_min_one_success',
+]);
+
+export type TriggerRule = z.infer<typeof triggerRuleSchema>;
+
+/** All valid trigger rule values. */
+export const TRIGGER_RULES: TriggerRule[] = triggerRuleSchema.options;
+
+/** Default trigger rule used when none is specified. */
+export const DEFAULT_TRIGGER_RULE: TriggerRule = 'all_success';

packages/ion/src/schema/workflow-run.ts

@@ -0,0 +1,109 @@
+import { z } from 'zod';
+import { approvalOnRejectSchema } from './dag-node.js';
+
+// ---------------------------------------------------------------------------
+// Workflow run status
+// ---------------------------------------------------------------------------
+
+export const WorkflowRunStatusSchema = z.enum([
+  'pending',
+  'running',
+  'paused',
+  'completed',
+  'failed',
+  'cancelled',
+]);
+
+export type WorkflowRunStatus = z.infer<typeof WorkflowRunStatusSchema>;
+
+/** Statuses that indicate the run has finished (no further transitions). */
+export const TERMINAL_WORKFLOW_STATUSES = WorkflowRunStatusSchema.options.filter(
+  (s): s is 'completed' | 'failed' | 'cancelled' =>
+    s === 'completed' || s === 'failed' || s === 'cancelled',
+);
+
+/** Statuses from which a run can be resumed. */
+export const RESUMABLE_WORKFLOW_STATUSES = WorkflowRunStatusSchema.options.filter(
+  (s): s is 'paused' | 'failed' =>
+    s === 'paused' || s === 'failed',
+);
+
+// ---------------------------------------------------------------------------
+// Node state
+// ---------------------------------------------------------------------------
+
+export const NodeStateSchema = z.enum([
+  'pending',
+  'running',
+  'completed',
+  'failed',
+  'skipped',
+]);
+
+export type NodeState = z.infer<typeof NodeStateSchema>;
+
+// NOTE: NodeOutput type is in node-output.ts — re-exported via schema/index.ts
+
+// ---------------------------------------------------------------------------
+// Approval context
+// ---------------------------------------------------------------------------
+
+export const ApprovalContextSchema = z.object({
+  /** Discriminator for the approval type. */
+  type: z.literal('approval'),
+
+  /** The node that is waiting for approval. */
+  nodeId: z.string().min(1, 'nodeId must not be empty'),
+
+  /** Message shown to the approver. */
+  message: z.string().min(1, 'approval message must not be empty'),
+
+  /** Whether the approver's response should be captured. */
+  capture_response: z.boolean().default(false),
+
+  /** What to do when the approval is rejected. */
+  on_reject: approvalOnRejectSchema.optional(),
+});
+
+export type ApprovalContext = z.infer<typeof ApprovalContextSchema>;
+
+// ---------------------------------------------------------------------------
+// Workflow run
+// ---------------------------------------------------------------------------
+
+export const WorkflowRunSchema = z.object({
+  /** Unique run identifier. */
+  id: z.string().min(1, 'run id must not be empty'),
+
+  /** Name of the workflow being run. */
+  workflow_name: z.string().min(1, 'workflow_name must not be empty'),
+
+  /** Current status of the run. */
+  status: WorkflowRunStatusSchema,
+
+  /** Conversation this run belongs to. */
+  conversation_id: z.string().min(1, 'conversation_id must not be empty'),
+
+  /** Codebase this run operates on. */
+  codebase_id: z.string().min(1, 'codebase_id must not be empty'),
+
+  /** The user message that triggered this run. */
+  user_message: z.string().optional(),
+
+  /** Working directory path for the run. */
+  working_path: z.string().optional(),
+
+  /** Timestamp when the run was created. */
+  created_at: z.string().datetime(),
+
+  /** Timestamp when the run started executing. */
+  started_at: z.string().datetime().optional(),
+
+  /** Arbitrary metadata attached to the run. */
+  metadata: z.record(z.string(), z.unknown()).default({}),
+
+  /** Parent conversation ID for nested runs. */
+  parent_conversation_id: z.string().optional(),
+});
+
+export type WorkflowRun = z.infer<typeof WorkflowRunSchema>;

packages/ion/src/schema/workflow.ts

@@ -0,0 +1,246 @@
+import { z } from 'zod';
+import { dagNodeSchema, effortLevelSchema, thinkingConfigSchema } from './dag-node.js';
+
+// ---------------------------------------------------------------------------
+// Model reasoning effort
+// ---------------------------------------------------------------------------
+
+export const modelReasoningEffortSchema = z.enum(['low', 'medium', 'high']);
+
+export type ModelReasoningEffort = z.infer<typeof modelReasoningEffortSchema>;
+
+// ---------------------------------------------------------------------------
+// Web search mode
+// ---------------------------------------------------------------------------
+
+export const webSearchModeSchema = z.enum(['off', 'auto', 'on']);
+
+export type WebSearchMode = z.infer<typeof webSearchModeSchema>;
+
+// ---------------------------------------------------------------------------
+// Workflow requirement
+// ---------------------------------------------------------------------------
+
+export const workflowRequirementSchema = z.object({
+  /** Human-readable name of the requirement. */
+  name: z.string().min(1, 'requirement name must not be empty'),
+
+  /** Short description of what the requirement enforces. */
+  description: z.string().optional(),
+});
+
+export type WorkflowRequirement = z.infer<typeof workflowRequirementSchema>;
+
+// ---------------------------------------------------------------------------
+// Worktree policy
+// ---------------------------------------------------------------------------
+
+export const workflowWorktreePolicySchema = z.object({
+  /** Whether worktree isolation is enabled for this workflow. */
+  enabled: z.boolean().optional(),
+});
+
+export type WorkflowWorktreePolicy = z.infer<typeof workflowWorktreePolicySchema>;
+
+// ---------------------------------------------------------------------------
+// Sandbox config
+// ---------------------------------------------------------------------------
+
+export const sandboxConfigSchema = z.object({
+  /** Whether sandboxing is enabled. */
+  enabled: z.boolean().default(false),
+
+  /** Docker image to use for sandboxing. */
+  image: z.string().optional(),
+
+  /** Memory limit in megabytes. */
+  memory_mb: z.number().int().positive().optional(),
+
+  /** CPU limit in cores. */
+  cpu_cores: z.number().positive().optional(),
+
+  /** Network access inside the sandbox. */
+  network: z.boolean().default(false),
+});
+
+export type SandboxConfig = z.infer<typeof sandboxConfigSchema>;
+
+// ---------------------------------------------------------------------------
+// Provider overrides
+// ---------------------------------------------------------------------------
+
+export const providerOverridesSchema = z.record(
+  z.string(),
+  z.object({
+    model: z.string().optional(),
+    base_url: z.string().optional(),
+    api_key_env: z.string().optional(),
+  }),
+);
+
+export type ProviderOverrides = z.infer<typeof providerOverridesSchema>;
+
+// ---------------------------------------------------------------------------
+// Workflow base schema (shared between definition and metadata)
+// ---------------------------------------------------------------------------
+
+export const workflowBaseSchema = z.object({
+  /** Human-readable workflow name. */
+  name: z.string().min(1, 'workflow name must not be empty'),
+
+  /** Short description of what the workflow does. */
+  description: z.string().optional(),
+
+  /** Default provider for all nodes. */
+  provider: z.string().optional(),
+
+  /** Default model for all nodes. */
+  model: z.string().optional(),
+
+  /** Reasoning effort level for the model. */
+  modelReasoningEffort: modelReasoningEffortSchema.optional(),
+
+  /** Web search mode for the model. */
+  webSearchMode: webSearchModeSchema.optional(),
+
+  /** Whether the workflow can pause for human input. */
+  interactive: z.boolean().default(false),
+
+  /** Default effort level for all nodes. */
+  effort: effortLevelSchema.optional(),
+
+  /** Default thinking configuration for all nodes. */
+  thinking: thinkingConfigSchema.optional(),
+
+  /** Fallback model when the primary model is unavailable. */
+  fallbackModel: z.string().optional(),
+
+  /** Tags for categorisation and filtering. */
+  tags: z.array(z.string()).default([]),
+
+  /** Requirements that must be met before the workflow can run. */
+  requires: z.array(workflowRequirementSchema).default([]),
+
+  /** Whether this workflow modifies the git checkout. */
+  mutates_checkout: z.boolean().default(false),
+
+  /** Whether to persist conversation sessions between runs. */
+  persist_sessions: z.boolean().default(false),
+
+  /** Per-provider configuration overrides. */
+  provider_overrides: providerOverridesSchema.optional(),
+
+  /** Sandbox configuration for the workflow. */
+  sandbox: sandboxConfigSchema.optional(),
+
+  /** Worktree policy for the workflow. */
+  worktree: workflowWorktreePolicySchema.optional(),
+});
+
+export type WorkflowBase = z.infer<typeof workflowBaseSchema>;
+
+// ---------------------------------------------------------------------------
+// Full workflow definition (base + nodes)
+// ---------------------------------------------------------------------------
+
+export const workflowDefinitionSchema = workflowBaseSchema.extend({
+  /** The DAG nodes that make up this workflow. */
+  nodes: z.array(dagNodeSchema),
+});
+
+export type WorkflowDefinition = z.infer<typeof workflowDefinitionSchema>;
+
+// ---------------------------------------------------------------------------
+// Workflow source
+// ---------------------------------------------------------------------------
+
+export const WorkflowSourceSchema = z.enum(['bundled', 'global', 'project']);
+
+export type WorkflowSource = z.infer<typeof WorkflowSourceSchema>;
+
+// ---------------------------------------------------------------------------
+// Workflow execution result
+// ---------------------------------------------------------------------------
+
+export const workflowExecutionResultSchema = z.discriminatedUnion('status', [
+  z.object({
+    status: z.literal('success'),
+    output: z.string(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+  }),
+  z.object({
+    status: z.literal('fail'),
+    error: z.string(),
+    node_id: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+  }),
+  z.object({
+    status: z.literal('paused'),
+    node_id: z.string(),
+    reason: z.string(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+  }),
+]);
+
+export type WorkflowExecutionResult = z.infer<typeof workflowExecutionResultSchema>;
+
+// ---------------------------------------------------------------------------
+// Workflow with source metadata
+// ---------------------------------------------------------------------------
+
+export const workflowWithSourceSchema = z.object({
+  definition: workflowDefinitionSchema,
+  source: WorkflowSourceSchema,
+  path: z.string().optional(),
+});
+
+export type WorkflowWithSource = z.infer<typeof workflowWithSourceSchema>;
+
+// ---------------------------------------------------------------------------
+// Workflow load error
+// ---------------------------------------------------------------------------
+
+export const workflowLoadErrorSchema = z.object({
+  message: z.string(),
+  path: z.string().optional(),
+  cause: z.unknown().optional(),
+});
+
+export type WorkflowLoadError = z.infer<typeof workflowLoadErrorSchema>;
+
+// ---------------------------------------------------------------------------
+// Workflow load result (success or error)
+// ---------------------------------------------------------------------------
+
+export const workflowLoadResultSchema = z.union([
+  workflowWithSourceSchema,
+  workflowLoadErrorSchema,
+]);
+
+export type WorkflowLoadResult = z.infer<typeof workflowLoadResultSchema>;
+
+// ---------------------------------------------------------------------------
+// Load command result
+// ---------------------------------------------------------------------------
+
+export const loadCommandResultSchema = z.discriminatedUnion('status', [
+  z.object({
+    status: z.literal('success'),
+    definition: workflowDefinitionSchema,
+    source: WorkflowSourceSchema,
+    path: z.string().optional(),
+  }),
+  z.object({
+    status: z.literal('fail'),
+    reason: z.enum([
+      'not_found',
+      'parse_error',
+      'validation_error',
+      'permission_denied',
+    ]),
+    message: z.string(),
+    path: z.string().optional(),
+  }),
+]);
+
+export type LoadCommandResult = z.infer<typeof loadCommandResultSchema>;

packages/ion/src/store/fs-store.ts

@@ -0,0 +1,249 @@
+/**
+ * Filesystem-backed workflow store.
+ *
+ * Stores each run as `{basePath}/{runId}/run.json` and
+ * `{basePath}/{runId}/events.jsonl`. Thread-safe writes use atomic
+ * rename (write to temp file, then rename).
+ */
+
+import { mkdir, writeFile, readFile, readdir, rename, unlink } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { nanoid } from 'nanoid';
+
+import type {
+  IWorkflowStore,
+  WorkflowRun,
+  WorkflowEvent,
+  WorkflowRunStatus,
+  CreateWorkflowRunData,
+} from '../engine/deps.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const ACTIVE_STATUSES: WorkflowRunStatus[] = ['pending', 'running'];
+
+function parseRun(raw: string): WorkflowRun {
+  const obj = JSON.parse(raw);
+  return {
+    ...obj,
+    createdAt: new Date(obj.createdAt),
+    updatedAt: new Date(obj.updatedAt),
+  };
+}
+
+function serializeRun(run: WorkflowRun): string {
+  return JSON.stringify(
+    {
+      ...run,
+      createdAt: run.createdAt.toISOString(),
+      updatedAt: run.updatedAt.toISOString(),
+    },
+    null,
+    2,
+  );
+}
+
+function parseEvent(line: string): WorkflowEvent {
+  const obj = JSON.parse(line);
+  return {
+    ...obj,
+    createdAt: new Date(obj.createdAt),
+  };
+}
+
+function serializeEvent(event: WorkflowEvent): string {
+  return JSON.stringify({
+    ...event,
+    createdAt: event.createdAt.toISOString(),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Atomic write helper
+// ---------------------------------------------------------------------------
+
+async function atomicWrite(filePath: string, data: string): Promise<void> {
+  const tmp = `${filePath}.${nanoid(8)}.tmp`;
+  await writeFile(tmp, data, 'utf-8');
+  await rename(tmp, filePath);
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createFsStore(basePath: string): IWorkflowStore {
+  // Ensure base directory exists on first write — no side effects at import.
+
+  const store: IWorkflowStore = {
+    // -- Run lifecycle -------------------------------------------------------
+
+    async createWorkflowRun(data: CreateWorkflowRunData): Promise<WorkflowRun> {
+      const id = nanoid();
+      const now = new Date();
+      const run: WorkflowRun = {
+        id,
+        workflowPath: data.workflowPath,
+        workflowName: data.workflowName,
+        status: 'pending',
+        trigger: data.trigger,
+        input: data.input,
+        createdAt: now,
+        updatedAt: now,
+      };
+
+      const runDir = join(basePath, id);
+      await mkdir(runDir, { recursive: true });
+      await atomicWrite(join(runDir, 'run.json'), serializeRun(run));
+      // Create empty events file
+      await atomicWrite(join(runDir, 'events.jsonl'), '');
+
+      return run;
+    },
+
+    async getWorkflowRun(id: string): Promise<WorkflowRun | null> {
+      const filePath = join(basePath, id, 'run.json');
+      if (!existsSync(filePath)) return null;
+      const raw = await readFile(filePath, 'utf-8');
+      return parseRun(raw);
+    },
+
+    async updateWorkflowRun(
+      id: string,
+      data: Partial<WorkflowRun>,
+    ): Promise<WorkflowRun> {
+      const existing = await store.getWorkflowRun(id);
+      if (!existing) throw new Error(`WorkflowRun not found: ${id}`);
+
+      const updated: WorkflowRun = {
+        ...existing,
+        ...data,
+        id: existing.id, // id is immutable
+        updatedAt: new Date(),
+      };
+
+      await atomicWrite(
+        join(basePath, id, 'run.json'),
+        serializeRun(updated),
+      );
+      return updated;
+    },
+
+    async failWorkflowRun(id: string, error: string): Promise<WorkflowRun> {
+      return store.updateWorkflowRun(id, {
+        status: 'failed',
+        error,
+      } as Partial<WorkflowRun>);
+    },
+
+    async getWorkflowRunStatus(
+      id: string,
+    ): Promise<WorkflowRunStatus | null> {
+      const run = await store.getWorkflowRun(id);
+      return run?.status ?? null;
+    },
+
+    // -- Events --------------------------------------------------------------
+
+    async createWorkflowEvent(
+      event: Omit<WorkflowEvent, 'id' | 'createdAt'>,
+    ): Promise<WorkflowEvent> {
+      const full: WorkflowEvent = {
+        ...event,
+        id: nanoid(),
+        createdAt: new Date(),
+      };
+
+      const eventsPath = join(basePath, event.runId, 'events.jsonl');
+      // Ensure directory exists
+      if (!existsSync(join(basePath, event.runId))) {
+        await mkdir(join(basePath, event.runId), { recursive: true });
+      }
+
+      const line = serializeEvent(full) + '\n';
+      // Append — not atomic for appends, but each line is self-contained
+      const existing = existsSync(eventsPath)
+        ? await readFile(eventsPath, 'utf-8').catch(() => '')
+        : '';
+      await atomicWrite(eventsPath, existing + line);
+
+      return full;
+    },
+
+    async getCompletedDagNodeOutputs(
+      runId: string,
+    ): Promise<Record<string, Record<string, unknown>>> {
+      const eventsPath = join(basePath, runId, 'events.jsonl');
+      if (!existsSync(eventsPath)) return {};
+
+      const raw = await readFile(eventsPath, 'utf-8');
+      const lines = raw.split('\n').filter(Boolean);
+
+      const outputs: Record<string, Record<string, unknown>> = {};
+      for (const line of lines) {
+        const event = parseEvent(line);
+        if (event.type === 'node_complete' && event.nodeId && event.data?.output) {
+          outputs[event.nodeId] = event.data.output as Record<string, unknown>;
+        }
+      }
+
+      return outputs;
+    },
+
+    // -- Active runs ---------------------------------------------------------
+
+    async getActiveWorkflowRunByPath(
+      path: string,
+      opts?: { excludeId?: string },
+    ): Promise<WorkflowRun | null> {
+      if (!existsSync(basePath)) return null;
+
+      const entries = await readdir(basePath, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const runPath = join(basePath, entry.name, 'run.json');
+        if (!existsSync(runPath)) continue;
+
+        const raw = await readFile(runPath, 'utf-8');
+        const run = parseRun(raw);
+
+        if (run.workflowPath !== path) continue;
+        if (!ACTIVE_STATUSES.includes(run.status)) continue;
+        if (opts?.excludeId && run.id === opts.excludeId) continue;
+
+        return run;
+      }
+
+      return null;
+    },
+
+    // -- Codebase ------------------------------------------------------------
+
+    async getCodebase(
+      _id: string,
+    ): Promise<Record<string, unknown> | null> {
+      // Filesystem store does not persist codebase records
+      return null;
+    },
+
+    async getCodebaseEnvVars(
+      _id: string,
+    ): Promise<Record<string, string>> {
+      // Filesystem store does not persist codebase env vars
+      return {};
+    },
+
+    // -- Resumption ----------------------------------------------------------
+
+    async resumeWorkflowRun(id: string): Promise<WorkflowRun> {
+      return store.updateWorkflowRun(id, {
+        status: 'running',
+      } as Partial<WorkflowRun>);
+    },
+  };
+
+  return store;
+}

packages/ion/src/store/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Store module — persistence backends for the Ion workflow engine.
+ *
+ * Provides three store implementations:
+ * - `createFsStore` — filesystem-backed (JSON files + JSONL events)
+ * - `createSqliteStore` — SQLite-backed (better-sqlite3, optional dep)
+ * - `createPostgresStore` — Postgres-backed (postgres.js, optional dep)
+ *
+ * All implement the `IWorkflowStore` interface from `../engine/deps.js`.
+ */
+
+export { createFsStore } from './fs-store.js';
+export { createSqliteStore } from './sqlite-store.js';
+export { createPostgresStore } from './pg-store.js';
+
+export type {
+  IWorkflowStore,
+  WorkflowRun,
+  WorkflowEvent,
+  WorkflowRunStatus,
+  CreateWorkflowRunData,
+} from './types.js';

packages/ion/src/store/optional-deps.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Type declarations for optional store dependencies.
+ *
+ * These modules are optional — they may not be installed.
+ * We declare just enough types here for the store implementations to compile
+ * without requiring the actual packages.
+ */
+
+declare module 'better-sqlite3' {
+  interface RunResult {
+    changes: number;
+    lastInsertRowid: number | bigint;
+  }
+
+  interface Statement {
+    run(...params: unknown[]): RunResult;
+    get(...params: unknown[]): unknown;
+    all(...params: unknown[]): unknown[];
+  }
+
+  class Database {
+    constructor(filename: string, options?: unknown);
+    prepare(sql: string): Statement;
+    exec(sql: string): Database;
+    pragma(pragma: string): unknown;
+    close(): void;
+  }
+
+  export default Database;
+}
+
+declare module 'postgres' {
+  interface Sql {
+    <T = unknown>(
+      strings: TemplateStringsArray,
+      ...values: unknown[]
+    ): Promise<T[]>;
+    unsafe(sql: string, params?: unknown[]): Promise<unknown[]>;
+    json(data: unknown): unknown;
+    end(): Promise<void>;
+  }
+
+  function postgres(connectionString: string): Sql;
+
+  export default postgres;
+}

packages/ion/src/store/pg-store.ts

@@ -0,0 +1,309 @@
+/**
+ * Postgres-backed workflow store.
+ *
+ * Uses postgres.js for async, connection-pooled persistence.
+ * The dependency is optional — a helpful error is thrown if not installed.
+ */
+
+import { nanoid } from 'nanoid';
+
+import type {
+  IWorkflowStore,
+  WorkflowRun,
+  WorkflowEvent,
+  WorkflowRunStatus,
+  CreateWorkflowRunData,
+} from '../engine/deps.js';
+
+// ---------------------------------------------------------------------------
+// Optional dependency loading
+// ---------------------------------------------------------------------------
+
+async function loadPostgres(): Promise<typeof import('postgres')> {
+  try {
+    return await import('postgres');
+  } catch {
+    throw new Error(
+      'postgres is not installed. Install it with: npm install postgres',
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+
+const SCHEMA_SQL = `
+  CREATE TABLE IF NOT EXISTS workflow_runs (
+    id TEXT PRIMARY KEY,
+    workflow_path TEXT NOT NULL,
+    workflow_name TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending',
+    trigger TEXT NOT NULL,
+    input JSONB NOT NULL DEFAULT '{}',
+    output JSONB,
+    error TEXT,
+    created_at TIMESTAMPTZ NOT NULL,
+    updated_at TIMESTAMPTZ NOT NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS workflow_events (
+    id TEXT PRIMARY KEY,
+    run_id TEXT NOT NULL REFERENCES workflow_runs(id),
+    node_id TEXT,
+    type TEXT NOT NULL,
+    data JSONB NOT NULL DEFAULT '{}',
+    created_at TIMESTAMPTZ NOT NULL
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_workflow_runs_path_status
+    ON workflow_runs(workflow_path, status);
+
+  CREATE INDEX IF NOT EXISTS idx_workflow_events_run_id
+    ON workflow_events(run_id);
+`;
+
+// ---------------------------------------------------------------------------
+// Row mappers
+// ---------------------------------------------------------------------------
+
+interface RunRow {
+  id: string;
+  workflow_path: string;
+  workflow_name: string;
+  status: string;
+  trigger: string;
+  input: unknown;
+  output: unknown;
+  error: string | null;
+  created_at: Date | string;
+  updated_at: Date | string;
+}
+
+interface EventRow {
+  id: string;
+  run_id: string;
+  node_id: string | null;
+  type: string;
+  data: unknown;
+  created_at: Date | string;
+}
+
+function rowToRun(row: RunRow): WorkflowRun {
+  return {
+    id: row.id,
+    workflowPath: row.workflow_path,
+    workflowName: row.workflow_name,
+    status: row.status as WorkflowRunStatus,
+    trigger: row.trigger,
+    input: (row.input ?? {}) as Record<string, unknown>,
+    output: row.output
+      ? (row.output as Record<string, unknown>)
+      : undefined,
+    error: row.error ?? undefined,
+    createdAt: new Date(row.created_at),
+    updatedAt: new Date(row.updated_at),
+  };
+}
+
+function rowToEvent(row: EventRow): WorkflowEvent {
+  return {
+    id: row.id,
+    runId: row.run_id,
+    nodeId: row.node_id ?? undefined,
+    type: row.type,
+    data: (row.data ?? {}) as Record<string, unknown>,
+    createdAt: new Date(row.created_at),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export async function createPostgresStore(
+  connectionString: string,
+): Promise<IWorkflowStore> {
+  const mod = await loadPostgres();
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const sql: any = mod.default
+    ? mod.default(connectionString)
+    : (mod as any)(connectionString);
+
+  // Initialize schema
+  await sql.unsafe(SCHEMA_SQL);
+
+  const ACTIVE_STATUSES: WorkflowRunStatus[] = ['pending', 'running'];
+
+  const store: IWorkflowStore = {
+    // -- Run lifecycle -------------------------------------------------------
+
+    async createWorkflowRun(data: CreateWorkflowRunData): Promise<WorkflowRun> {
+      const id = nanoid();
+      const now = new Date();
+
+      const rows = await sql`
+        INSERT INTO workflow_runs (id, workflow_path, workflow_name, status, trigger, input, created_at, updated_at)
+        VALUES (${id}, ${data.workflowPath}, ${data.workflowName}, 'pending', ${data.trigger}, ${sql.json(data.input)}, ${now.toISOString()}, ${now.toISOString()})
+        RETURNING *
+      `;
+
+      return rowToRun(rows[0] as RunRow);
+    },
+
+    async getWorkflowRun(id: string): Promise<WorkflowRun | null> {
+      const rows = await sql`
+        SELECT * FROM workflow_runs WHERE id = ${id}
+      `;
+      if (rows.length === 0) return null;
+      return rowToRun(rows[0] as RunRow);
+    },
+
+    async updateWorkflowRun(
+      id: string,
+      data: Partial<WorkflowRun>,
+    ): Promise<WorkflowRun> {
+      const existing = await store.getWorkflowRun(id);
+      if (!existing) throw new Error(`WorkflowRun not found: ${id}`);
+
+      const now = new Date().toISOString();
+      const sets: string[] = ['updated_at = $1'];
+      const values: unknown[] = [now];
+      let paramIdx = 2;
+
+      if (data.status !== undefined) {
+        sets.push(`status = $${paramIdx++}`);
+        values.push(data.status);
+      }
+      if (data.output !== undefined) {
+        sets.push(`output = $${paramIdx++}`);
+        values.push(JSON.stringify(data.output));
+      }
+      if (data.error !== undefined) {
+        sets.push(`error = $${paramIdx++}`);
+        values.push(data.error);
+      }
+      if (data.workflowPath !== undefined) {
+        sets.push(`workflow_path = $${paramIdx++}`);
+        values.push(data.workflowPath);
+      }
+      if (data.workflowName !== undefined) {
+        sets.push(`workflow_name = $${paramIdx++}`);
+        values.push(data.workflowName);
+      }
+      if (data.trigger !== undefined) {
+        sets.push(`trigger = $${paramIdx++}`);
+        values.push(data.trigger);
+      }
+      if (data.input !== undefined) {
+        sets.push(`input = $${paramIdx++}`);
+        values.push(JSON.stringify(data.input));
+      }
+
+      values.push(id);
+      const query = `UPDATE workflow_runs SET ${sets.join(', ')} WHERE id = $${paramIdx}`;
+
+      await sql.unsafe(query, values);
+
+      const updated = await store.getWorkflowRun(id);
+      return updated!;
+    },
+
+    async failWorkflowRun(id: string, error: string): Promise<WorkflowRun> {
+      return store.updateWorkflowRun(id, {
+        status: 'failed',
+        error,
+      } as Partial<WorkflowRun>);
+    },
+
+    async getWorkflowRunStatus(
+      id: string,
+    ): Promise<WorkflowRunStatus | null> {
+      const rows = await sql`
+        SELECT status FROM workflow_runs WHERE id = ${id}
+      `;
+      if (rows.length === 0) return null;
+      return (rows[0] as { status: string }).status as WorkflowRunStatus;
+    },
+
+    // -- Events --------------------------------------------------------------
+
+    async createWorkflowEvent(
+      event: Omit<WorkflowEvent, 'id' | 'createdAt'>,
+    ): Promise<WorkflowEvent> {
+      const id = nanoid();
+      const now = new Date();
+
+      const rows = await sql`
+        INSERT INTO workflow_events (id, run_id, node_id, type, data, created_at)
+        VALUES (${id}, ${event.runId}, ${event.nodeId ?? null}, ${event.type}, ${sql.json(event.data)}, ${now.toISOString()})
+        RETURNING *
+      `;
+
+      return rowToEvent(rows[0] as EventRow);
+    },
+
+    async getCompletedDagNodeOutputs(
+      runId: string,
+    ): Promise<Record<string, Record<string, unknown>>> {
+      const rows = await sql`
+        SELECT node_id, data FROM workflow_events
+        WHERE run_id = ${runId} AND type = 'node_complete' AND node_id IS NOT NULL
+      `;
+
+      const outputs: Record<string, Record<string, unknown>> = {};
+      for (const row of rows) {
+        const r = row as { node_id: string; data: unknown };
+        const parsed = (r.data ?? {}) as Record<string, unknown>;
+        if (parsed.output) {
+          outputs[r.node_id] = parsed.output as Record<string, unknown>;
+        }
+      }
+
+      return outputs;
+    },
+
+    // -- Active runs ---------------------------------------------------------
+
+    async getActiveWorkflowRunByPath(
+      path: string,
+      opts?: { excludeId?: string },
+    ): Promise<WorkflowRun | null> {
+      const excludeId = opts?.excludeId;
+      const rows = await sql`
+        SELECT * FROM workflow_runs
+        WHERE workflow_path = ${path}
+          AND status IN ${sql(ACTIVE_STATUSES)}
+          ${excludeId ? sql`AND id != ${excludeId}` : sql``}
+        LIMIT 1
+      `;
+
+      if (rows.length === 0) return null;
+      return rowToRun(rows[0] as RunRow);
+    },
+
+    // -- Codebase ------------------------------------------------------------
+
+    async getCodebase(
+      _id: string,
+    ): Promise<Record<string, unknown> | null> {
+      return null;
+    },
+
+    async getCodebaseEnvVars(
+      _id: string,
+    ): Promise<Record<string, string>> {
+      return {};
+    },
+
+    // -- Resumption ----------------------------------------------------------
+
+    async resumeWorkflowRun(id: string): Promise<WorkflowRun> {
+      return store.updateWorkflowRun(id, {
+        status: 'running',
+      } as Partial<WorkflowRun>);
+    },
+  };
+
+  return store;
+}

packages/ion/src/store/sqlite-store.ts

@@ -0,0 +1,336 @@
+/**
+ * SQLite-backed workflow store.
+ *
+ * Uses better-sqlite3 for synchronous, file-based persistence.
+ * The dependency is optional — a helpful error is thrown if not installed.
+ */
+
+import { nanoid } from 'nanoid';
+
+import type {
+  IWorkflowStore,
+  WorkflowRun,
+  WorkflowEvent,
+  WorkflowRunStatus,
+  CreateWorkflowRunData,
+} from '../engine/deps.js';
+
+// ---------------------------------------------------------------------------
+// Optional dependency loading
+// ---------------------------------------------------------------------------
+
+async function loadBetterSqlite3(): Promise<typeof import('better-sqlite3')> {
+  try {
+    return await import('better-sqlite3');
+  } catch {
+    throw new Error(
+      'better-sqlite3 is not installed. Install it with: npm install better-sqlite3',
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+
+const SCHEMA_SQL = `
+  CREATE TABLE IF NOT EXISTS workflow_runs (
+    id TEXT PRIMARY KEY,
+    workflow_path TEXT NOT NULL,
+    workflow_name TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending',
+    trigger TEXT NOT NULL,
+    input TEXT NOT NULL DEFAULT '{}',
+    output TEXT,
+    error TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS workflow_events (
+    id TEXT PRIMARY KEY,
+    run_id TEXT NOT NULL,
+    node_id TEXT,
+    type TEXT NOT NULL,
+    data TEXT NOT NULL DEFAULT '{}',
+    created_at TEXT NOT NULL,
+    FOREIGN KEY (run_id) REFERENCES workflow_runs(id)
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_workflow_runs_path_status
+    ON workflow_runs(workflow_path, status);
+
+  CREATE INDEX IF NOT EXISTS idx_workflow_events_run_id
+    ON workflow_events(run_id);
+`;
+
+// ---------------------------------------------------------------------------
+// Row mappers
+// ---------------------------------------------------------------------------
+
+interface RunRow {
+  id: string;
+  workflow_path: string;
+  workflow_name: string;
+  status: string;
+  trigger: string;
+  input: string;
+  output: string | null;
+  error: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+interface EventRow {
+  id: string;
+  run_id: string;
+  node_id: string | null;
+  type: string;
+  data: string;
+  created_at: string;
+}
+
+function rowToRun(row: RunRow): WorkflowRun {
+  return {
+    id: row.id,
+    workflowPath: row.workflow_path,
+    workflowName: row.workflow_name,
+    status: row.status as WorkflowRunStatus,
+    trigger: row.trigger,
+    input: JSON.parse(row.input),
+    output: row.output ? JSON.parse(row.output) : undefined,
+    error: row.error ?? undefined,
+    createdAt: new Date(row.created_at),
+    updatedAt: new Date(row.updated_at),
+  };
+}
+
+function rowToEvent(row: EventRow): WorkflowEvent {
+  return {
+    id: row.id,
+    runId: row.run_id,
+    nodeId: row.node_id ?? undefined,
+    type: row.type,
+    data: JSON.parse(row.data),
+    createdAt: new Date(row.created_at),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export async function createSqliteStore(
+  dbPath: string,
+): Promise<IWorkflowStore> {
+  const mod = await loadBetterSqlite3();
+  const DatabaseCtor = mod.default ?? mod;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const db: any = new DatabaseCtor(dbPath);
+
+  // Enable WAL mode for better concurrent read performance
+  db.pragma('journal_mode = WAL');
+
+  // Initialize schema
+  db.exec(SCHEMA_SQL);
+
+  const ACTIVE_STATUSES: WorkflowRunStatus[] = ['pending', 'running'];
+
+  const store: IWorkflowStore = {
+    // -- Run lifecycle -------------------------------------------------------
+
+    createWorkflowRun(data: CreateWorkflowRunData): Promise<WorkflowRun> {
+      const id = nanoid();
+      const now = new Date().toISOString();
+      const inputJson = JSON.stringify(data.input);
+
+      db.prepare(
+        `INSERT INTO workflow_runs (id, workflow_path, workflow_name, status, trigger, input, created_at, updated_at)
+         VALUES (?, ?, ?, 'pending', ?, ?, ?, ?)`,
+      ).run(
+        id,
+        data.workflowPath,
+        data.workflowName,
+        data.trigger,
+        inputJson,
+        now,
+        now,
+      );
+
+      return Promise.resolve({
+        id,
+        workflowPath: data.workflowPath,
+        workflowName: data.workflowName,
+        status: 'pending',
+        trigger: data.trigger,
+        input: data.input,
+        createdAt: new Date(now),
+        updatedAt: new Date(now),
+      });
+    },
+
+    getWorkflowRun(id: string): Promise<WorkflowRun | null> {
+      const row = db
+        .prepare('SELECT * FROM workflow_runs WHERE id = ?')
+        .get(id) as RunRow | undefined;
+      if (!row) return Promise.resolve(null);
+      return Promise.resolve(rowToRun(row));
+    },
+
+    updateWorkflowRun(
+      id: string,
+      data: Partial<WorkflowRun>,
+    ): Promise<WorkflowRun> {
+      const existing = db
+        .prepare('SELECT * FROM workflow_runs WHERE id = ?')
+        .get(id) as RunRow | undefined;
+      if (!existing) throw new Error(`WorkflowRun not found: ${id}`);
+
+      const now = new Date().toISOString();
+      const sets: string[] = ['updated_at = ?'];
+      const values: unknown[] = [now];
+
+      if (data.status !== undefined) {
+        sets.push('status = ?');
+        values.push(data.status);
+      }
+      if (data.output !== undefined) {
+        sets.push('output = ?');
+        values.push(JSON.stringify(data.output));
+      }
+      if (data.error !== undefined) {
+        sets.push('error = ?');
+        values.push(data.error);
+      }
+      if (data.workflowPath !== undefined) {
+        sets.push('workflow_path = ?');
+        values.push(data.workflowPath);
+      }
+      if (data.workflowName !== undefined) {
+        sets.push('workflow_name = ?');
+        values.push(data.workflowName);
+      }
+      if (data.trigger !== undefined) {
+        sets.push('trigger = ?');
+        values.push(data.trigger);
+      }
+      if (data.input !== undefined) {
+        sets.push('input = ?');
+        values.push(JSON.stringify(data.input));
+      }
+
+      values.push(id);
+      db.prepare(
+        `UPDATE workflow_runs SET ${sets.join(', ')} WHERE id = ?`,
+      ).run(...values);
+
+      const updated = db
+        .prepare('SELECT * FROM workflow_runs WHERE id = ?')
+        .get(id) as RunRow;
+      return Promise.resolve(rowToRun(updated));
+    },
+
+    failWorkflowRun(id: string, error: string): Promise<WorkflowRun> {
+      return store.updateWorkflowRun(id, {
+        status: 'failed',
+        error,
+      } as Partial<WorkflowRun>);
+    },
+
+    getWorkflowRunStatus(id: string): Promise<WorkflowRunStatus | null> {
+      const row = db
+        .prepare('SELECT status FROM workflow_runs WHERE id = ?')
+        .get(id) as { status: string } | undefined;
+      if (!row) return Promise.resolve(null);
+      return Promise.resolve(row.status as WorkflowRunStatus);
+    },
+
+    // -- Events --------------------------------------------------------------
+
+    createWorkflowEvent(
+      event: Omit<WorkflowEvent, 'id' | 'createdAt'>,
+    ): Promise<WorkflowEvent> {
+      const id = nanoid();
+      const now = new Date().toISOString();
+      const dataJson = JSON.stringify(event.data);
+
+      db.prepare(
+        `INSERT INTO workflow_events (id, run_id, node_id, type, data, created_at)
+         VALUES (?, ?, ?, ?, ?, ?)`,
+      ).run(id, event.runId, event.nodeId ?? null, event.type, dataJson, now);
+
+      return Promise.resolve({
+        id,
+        runId: event.runId,
+        nodeId: event.nodeId,
+        type: event.type,
+        data: event.data,
+        createdAt: new Date(now),
+      });
+    },
+
+    getCompletedDagNodeOutputs(
+      runId: string,
+    ): Promise<Record<string, Record<string, unknown>>> {
+      const rows = db
+        .prepare(
+          `SELECT node_id, data FROM workflow_events
+           WHERE run_id = ? AND type = 'node_complete' AND node_id IS NOT NULL`,
+        )
+        .all(runId) as { node_id: string; data: string }[];
+
+      const outputs: Record<string, Record<string, unknown>> = {};
+      for (const row of rows) {
+        const parsed = JSON.parse(row.data);
+        if (parsed.output) {
+          outputs[row.node_id] = parsed.output as Record<string, unknown>;
+        }
+      }
+
+      return Promise.resolve(outputs);
+    },
+
+    // -- Active runs ---------------------------------------------------------
+
+    getActiveWorkflowRunByPath(
+      path: string,
+      opts?: { excludeId?: string },
+    ): Promise<WorkflowRun | null> {
+      const statuses = ACTIVE_STATUSES;
+      const placeholders = statuses.map(() => '?').join(', ');
+      let query = `SELECT * FROM workflow_runs WHERE workflow_path = ? AND status IN (${placeholders})`;
+      const params: unknown[] = [path, ...statuses];
+
+      if (opts?.excludeId) {
+        query += ' AND id != ?';
+        params.push(opts.excludeId);
+      }
+
+      query += ' LIMIT 1';
+
+      const row = db.prepare(query).get(...params) as RunRow | undefined;
+      if (!row) return Promise.resolve(null);
+      return Promise.resolve(rowToRun(row));
+    },
+
+    // -- Codebase ------------------------------------------------------------
+
+    getCodebase(_id: string): Promise<Record<string, unknown> | null> {
+      return Promise.resolve(null);
+    },
+
+    getCodebaseEnvVars(_id: string): Promise<Record<string, string>> {
+      return Promise.resolve({});
+    },
+
+    // -- Resumption ----------------------------------------------------------
+
+    resumeWorkflowRun(id: string): Promise<WorkflowRun> {
+      return store.updateWorkflowRun(id, {
+        status: 'running',
+      } as Partial<WorkflowRun>);
+    },
+  };
+
+  return store;
+}

packages/ion/src/store/types.ts

@@ -0,0 +1,14 @@
+/**
+ * Store type re-exports.
+ *
+ * Re-exports the workflow store types from the engine dependency interfaces
+ * so consumers can import them from the store module directly.
+ */
+
+export type {
+  IWorkflowStore,
+  WorkflowRun,
+  WorkflowEvent,
+  WorkflowRunStatus,
+  CreateWorkflowRunData,
+} from '../engine/deps.js';

packages/ion/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["src/**/__tests__/**", "**/*.test.ts"]
+}

packages/ion/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['src/**/*.test.ts'],
+  },
+});