The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
The core-boundary plan and the engine-interface plan are on main, with their status (#939)
Dee5f3fec86a8f0
diff --git a/docs/design/2026-10-05-engine-interface.md b/docs/design/2026-10-05-engine-interface.mdnew file mode 100644index 000000000..8d1a1fe33--- /dev/null+++ b/docs/design/2026-10-05-engine-interface.md@@ -0,0 +1,1200 @@+# Engines behind one interface++> **Status, 2026-10-07: paused by the owner.** Steps 1–5 and lanes S, B, H, L and I+O+U are on unmerged+> branches (`engine-interface-1..5`, `engine-lane-*`), and step 1 is in draft PR #842. Claude Code and+> Codex come first when it resumes; the owner names the next engine.+++Status: plan, approved for implementation on 2026-10-05. Scope: `cli/` (the daemon, harnessd).++**In short.**++- **What is there now.** Shared code decides per engine in **365 branch lines across 62 files** (the+ brief's grep finds 405; 40 are not engine behaviour). Counted with a parser, **113 of the 310 files**+ in `src/core`, `src/lib`, `cli.ts` and `backendSocket.ts` name an engine: 698 string literals, 273 table+ keys, 182 imports from engine folders. The core's own transcript modules hold 69 of the branch lines.+ The one engine interface, `EngineAdapter`, has no implementation.+- **The interface.** One `Engine` per engine, made of a manifest and eight optional facets: launch,+ transcript, sessions, screen, input, hooks, models, one-shot. 132 members in all (74 methods,+ 58 data fields), about 20 of them required; shared code uses a fallback for every optional member that+ is missing, and the same fallback when it throws.+- **Placement.** Each engine's folder holds all of its behaviour, Claude Code's included (it has none+ today); shared pieces go to `src/engines/kit/`, named by the engines that use them. Shared code asks+ `src/engines/registry.ts`.+- **Loading and isolation.** Manifests load with the daemon; Claude Code and Codex are built in; the+ other twelve load on first use. Every call goes through one guard, so a throw degrades that agent's+ feature and nothing else. In a single-file bundle lazy loading saves about a megabyte, not tens; its+ main value is that a broken engine can no longer stop the daemon from starting.+- **The rule.** `src/engineNames.spec.ts` parses shared code and fails on any engine name, as a+ ratchet from today's counts down to zero.+- **Migration.** 31 steps in four phases, each green on its own with the e2e suite as proof for Claude+ Code and Codex and pinned unit tests for the rest. Steps 6 to 20 run as nine parallel lanes. Nothing+ before step 21 touches the files other branches are changing now. About 42 agent-days, 4-5 weeks of+ calendar with the lanes in parallel.+- **Found on the way.** Fifteen things that are wrong today (section 9.4), among them a terminal row+ that disables the hook script's registry read, a restart that records the grid from the wrong+ argument, and Codex model switching closed above 0.145.+++## 1. Why++Harness drives fourteen agent CLIs in tmux panes: Claude Code, Codex, Cursor, OpenCode, pi, Hermes,+Kilo, Devin, Amp, agy, Grok, Copilot, Command Code and Muse. The code calls each one an engine.++The only engine interface in the tree is `EngineAdapter` in `src/engines/types.ts`. It has one method,+`createNormalizer`, and nothing implements it: no engine object exists, and no caller asks for one.+Everything an engine does differently is decided by a branch on its name in shared code: which binary to+run, the flags to launch and resume it, how to read its screen, its hooks, its models, where its+transcripts live, how to repair a session after a restart, and how to search its history. The engines+README says so plainly ("This is not a plugin API") and lists the twenty-odd shared files a new engine+has to touch.++That costs three things.++1. **The core is not engine-agnostic.** The core's own transcript modules (`core/transcripts/history.ts`,+ `attach.ts`, `lastTurn.ts`, `ingest.ts`, `normalizers.ts`, `databaseHistory.ts`) import from all thirteen+ engine folders and branch on the name 69 times between them (the core as a whole: 103). A change to one engine's reading is a change to the core, held to+ the core's bar and reviewed as one.+2. **One engine can take every agent down.** An engine's code runs in the core's process with no wall+ around it. A throw in a pane parser runs on the core's event loop. A module that throws while it is+ being loaded stops the daemon from starting at all, for every agent of every engine, because every+ engine is imported at start.+3. **Claude Code is the silent default.** It has no folder. Its reader, normalizer, question parser and+ paths are the `else` branch in shared code, so an engine that is not named in a branch gets Claude+ Code's behaviour. That has shipped as bugs twice already: Muse and Amp history panes opened empty,+ because the history request fell through to Claude Code's line cursor and normalizer+ (`core/transcripts/history.ts`, the comment above the Muse case).++The owner wants the core lean, small and engine-agnostic, and the refactor itself is approved. This plan+is how to get there in steps that each land green on their own.++## 2. How the branches were counted++The brief's own grep, over `cli/src` without specs:++```+grep -rnE "engine === '|engine !== '|case '(claude|codex|cursor|opencode|pi|hermes|kilo|devin|amp|agy|grok|copilot|commandcode|muse)'" src | grep -v '\.spec\.ts'+```++finds **405 lines in 76 files** on `main` at `31b4a0c27`. Read line by line, 40 of them are not per-engine behaviour:++| Kind | Lines | Files | Example |+|---|---:|---:|---|+| Per-engine behaviour | 365 | 62 | `if (s.engine === 'kilo') return lastKiloTurnText(…)` |+| `terminal` checks (the plain shell, a core concept) | 15 | 11 | `if (engine === 'terminal') throw …` |+| Local-model runtimes, not agent engines (`ollama`, `grid`, `lm-studio`, `llama.cpp`) | 14 | 2 | `lib/appModels.ts`, `lib/localModels.ts` |+| Type guards (`typeof engine !== 'string'`) | 10 | 8 | `core/agents/launches.ts:95` |+| A comment | 1 | 1 | `lib/terminalAgentReconciler.ts:382` |++The grep misses most of what shared code knows about engines, because most of it is not written as+`engine === '…'`. Counted with the TypeScript compiler's parser over the files the rule in section 7+covers (`src/core`, `src/lib`, `src/cli.ts`, `src/backendSocket.ts`; 310 files without specs), **113 of+the 310 files name an engine**:++| What | Count | Notes |+|---|---:|---|+| String literals equal to an engine name | 698 | every comparison, `case`, list member and map key written as a string |+| Keys of tables keyed by engine, and reads of them | 273 | `BYPASS_PERMISSION_FLAGS = { claude: …, codex: … }`, `dbs.opencode`; 17 tables are typed `Record<AgentEngine, …>` |+| Imports from an engine's folder | 182 | `core/transcripts/history.ts` alone imports from all thirteen engine folders |+| Engine-named identifiers, distinct per file | 876 | `preTrustCodexProject`, `CLAUDE_PROJECTS_DIR`, `codexHome`; `cursor`, `pi` and `amp` are left out because they are ordinary words in this code (a terminal cursor, a page cursor) |++Outside that scope another 12 files name an engine (`config/env.ts`, `hookServer.ts`, `watcher/`,+`cable/`, `teams/`, `dsh/`, `testing/`): 39 literals, 17 table keys, 4 imports, 58 identifiers.++Engine knowledge also sits in shared folders as whole modules: 22 engine-named files outside+`src/engines`, about 4,000 lines (`lib/claudeTrust.ts`, `lib/codexProfiles.ts`, `core/turns/agyBackstop.ts`,+`core/engines/cursorTasks.ts`, the twelve search adapters in `lib/sessionSearch/externals/`, and others),+and in two engine-specific fields of the persisted session row, `codexHome` and `hermesHome`, which about+30 shared files read.++Which engines the 365 behaviour lines name: Codex 68, Claude Code 55, Cursor 45, OpenCode 31, Grok 31,+Command Code 30, pi 26, agy 23, Copilot 23, Hermes 22, Kilo 19, Devin 19, Amp 16, Muse 14. Claude Code's+count understates its share, because its behaviour is mostly the unnamed `else`.++The scripts that produced these numbers are in the appendix; the rule test in section 7 is the same+scan, kept in the suite.++## 3. Inventory, by what is decided++Twelve groups. Each row is one decision: what it decides, where (the file and line on `main` at+`31b4a0c27`), which engines it names and what each gets, and what an engine not named gets. "Lines" counts+explicit branch lines (comparisons and `case` labels); "hits" counts the implicit forms (table entries,+list members, engine-named helpers, engine env vars, imports from an engine's folder). The two overlap+in a few places, and a row's numbers are about its own sites, so the groups do not add up to section+2's totals exactly; the rule test's per-file baseline is the exact measure.++### 3.1 Identity, binary and install (lines 36, hits about 90)++| Decision | Where | Engines → value | Default |+|---|---|---|---|+| The command a person types | `lib/engineBin.ts:21` `ENGINE_CLI_COMMANDS` | cursor `cursor-agent`, commandcode `cmd`, the rest their own name | terminal `''` |+| The env var that overrides the path | `engineBin.ts:394` `enginePathOverride`, 14 cases | `CLAUDE_PATH` … `COPILOT_PATH`; codex reads `process.env.CODEX_PATH`, which is not in the env schema | none |+| The launch binary | `engineBin.ts:414` `engineBin`, 14 cases | override, else the command | — |+| Names discovery accepts | `engineBin.ts:71` `ENGINE_CLI_ALIASES` | cursor and grok both `agent`; hermes `hermes-agent`; commandcode `cmd`, `command-code`, `commandcode`; kilo `kilocode` | own name |+| Extra fallback executables | `engineBin.ts:188` | cursor `~/.local/bin/agent`; grok `$GROK_HOME/bin/grok` first | the install paths |+| Who owns the shared `agent` file | `engineBin.ts:224-326` (ownership snapshot, `agentAliasOwner`, `cursorRuntimeBin`) | cursor or grok, by install layout | — |+| One-shot binaries | `engineBin.ts:342` `opencodeBin`; `lib/oneshot.ts` `claudeBin`, `piBin`, `commandCodeBin`, `kiloBin` | each its own resolver; Command Code's defaults to `commandcode` while everything else runs `cmd` | — |+| Install recipe | `lib/engineInstall.ts:38` `ENGINE_INSTALL`, 14 entries | npm, curl, brew recipes | terminal none |+| Skip the install when a path is set | `core/agents/create.ts:238`, `fork.ts:92`, `restart.ts:42`, `lib/resumeAgentService.ts:253`, `cli.ts:3334`, `lib/engineProbe.ts:96` | the same expression six times | — |+| Display label | `lib/agentNames.ts:15` `ENGINE_LABELS` | `Claude`, `Antigravity` (agy), `Command Code` … | the raw name |+| Engine env vars and their defaults | `config/env.ts` 145-310: 21 home and data folders, 13 path overrides | per engine | — |++### 3.2 Recognising an engine in a pane (lines 13, hits about 50)++| Decision | Where | Engines → value | Default |+|---|---|---|---|+| Process name and entrypoint | `lib/tmux.ts:600` `ENGINE_PROCESS_SIGNATURES` | 22 basename and 14 entrypoint patterns | terminal empty |+| Engine-specific evidence | `tmux.ts:662-704` `heuristicEngineProcessMatchScore` | agy: the IDE's `.app` binary is vetoed; commandcode `⌘` title; cursor package entrypoint; hermes inline launcher; claude native install path | the signature alone |+| An unresolved `agent` blocks the pane | `tmux.ts:764` `ambiguousAgentProcess`, `tmux.ts:193` | cursor, grok | — |+| A hook hint settles the alias | `lib/terminalAgentDiscovery.ts:141` | cursor, grok | — |+| The session id in a resume argv | `tmux.ts:825` `RESUME_ARGS`, 14 entries | `--resume`, `resume`, `--session`, `--conversation`, `threads continue` | null |+| The permission mode in a live argv | `tmux.ts:867-904`, reading `engineLaunch.ts`'s tables | claude, codex, cursor, opencode | — |+| A per-agent home read off the process | `lib/codexHomeProbe.ts:27`; `engines/hermes/homeProbe.ts:19` | codex `CODEX_HOME`, hermes `HERMES_HOME` | none |+| The TUI owns its scrollback | `lib/terminalStreamManager.ts:1132` | grok | false |++### 3.3 Homes and profiles (lines 6, hits about 60)++| Decision | Where | Engines → value | Default |+|---|---|---|---|+| A home moved by the user's shell | `lib/engineHomes.ts` (whole file); `core/engines/hooks.ts:188-199`; `lib/registry.ts:792-793` | claude `CLAUDE_CONFIG_DIR`, codex `CODEX_HOME` | not adopted |+| Codex profiles: list and link | `lib/codexProfiles.ts`, `lib/codexProfileDiscovery.ts` (517 lines); `backendSocket.ts:2197-2218`, `:1962` `supportsCodexHome` | codex | — |+| Hermes home per session and per profile | `lib/hermesHome.ts`; `engines/hermes/home.ts`; read by `hookServer.ts`, `sessionCheckpoint.ts`, `purgeAgentService.ts`, `sessionRepair.ts`, `hooks.ts` | hermes | the default home |+| Engine-specific fields on the session row | `RegisteredSession.codexHome`, `.hermesHome`; `registry.ts:1962-1981` setters; about 30 files read them | codex, hermes | — |+| A shared server's CPU and memory | `lib/harnessResources.ts:66-87` | codex `app-server-daemon` | none |++### 3.4 Launching, resuming and forking (lines 30, hits about 300)++| Decision | Where | Engines → value | Default |+|---|---|---|---|+| Permission modes and their flags | `lib/engineLaunch.ts:56` `PERMISSION_MODES`; the legacy yes/no flag `BYPASS_PERMISSION_FLAGS` `:23` equals each `auto` entry | claude (`auto`, `acceptEdits`, `plan`, `ask`, `full`), codex (`auto`, `readOnly`, `ask`, `full`), cursor and opencode (`auto`, `ask`) | no modes; any mode refused |+| Opening with a first prompt | `engineLaunch.ts:94` `FIRST_PROMPT_ARGS` | opencode `--prompt`, claude and codex positional, hermes `chat -q` | `PROMPT_UNSUPPORTED` |+| A named agent | `engineLaunch.ts:156`, `:194`; `core/agents/launches.ts:183` | opencode v1 `--agent` | `AGENT_UNSUPPORTED` |+| Resume | `engineLaunch.ts:313` `LAUNCH_RESUME_FLAG`, 14 entries | flag or subcommand per engine | a fresh start (never happens today: all 14 have one) |+| Native fork | `engineLaunch.ts:341` | claude `--resume id --fork-session`, codex `fork id` | a handoff fork if it takes a first prompt, else refused |+| The launch script | `engineLaunch.ts:482`, `:555-561`, `:578-620` | codex: `/bin/sh` fallback, `--no-daemon` probe, startup retries | the generic wrapper |+| Project pre-trust | `core/agents/launches.ts:258-262`, `:283-284`; `core/agents/create.ts:175-176`; `lib/claudeTrust.ts` | claude `~/.claude.json`, codex `config.toml` | nothing |+| Instruction files | `dsh/adapters.ts:34-49`; `dsh/runtime.ts:100`, `:105`; `lib/apiInstructions.ts:23` | claude `CLAUDE.md`; codex `AGENTS.override.md`; hermes `.hermes.md`; agy `GEMINI.md`; … | `AGENTS.md` |+| Harness context argv | `dsh/adapters.ts:35-39` | claude and pi `--append-system-prompt`; codex `-c shell_environment_policy.set` | none |+| Subscription model on relaunch | `lib/subscriptionModel.ts:49` | claude `ANTHROPIC_MODEL`, codex and hermes `-m`, opencode `-m` on v1 | none |+| House model and permission env | `lib/harnessDefaults.ts:15-43` | opencode `OPENCODE_CONFIG_CONTENT` | unchanged env |+| Grid (local models) launch | `lib/gridLaunch.ts:650` `GRID_ENGINE_CONTRACTS`, `:1001` refusals, `:1062` web search | claude, codex, opencode, hermes, grok, pi, copilot; refused for the rest | `GRID_ENGINE_UNSUPPORTED` |+| Grid read back from a process | `lib/gridAssignment.ts:37-61`, `:134`, `:269-270` | base-URL and model vars per engine; codex's argv parser is the fallback for all | null |+| Codex profile home, own login, resume repair, stop | `launches.ts:133`, `create.ts:231`, `:289`, `fork.ts:126`, `launchOverrides.ts:211`, `:249`; `core/agents/launch.ts:93`; `lib/codexSessionLifecycle.ts:96` | codex | — |+| A resumed session's model | `core/agents/retarget.ts:126-135`, `:201-215` | opencode (writes its store) | — |+| Plugin reinstall before a create | `core/agents/create.ts:234` | opencode | — |+| Machine facts for one engine | `cli.ts:3225-3226`; `opencodeMajorVersion()` at `launches.ts:183`, `create.ts:248`, `fork.ts:95`, `retarget.ts:128` | opencode major version, hermes system-managed | — |++### 3.5 Hooks (lines 32, hits about 70, plus about 1,100 engine lines in `lib/hooks.ts`)++| Decision | Where | Engines → value | Default |+|---|---|---|---|+| Which hooks to install | `core/engines/hooks.ts:202-216`; `lib/hooks.ts` 13 installers and the plugin sources | 13 engines; plugins for opencode, kilo, pi, amp | muse: none |+| Install in a moved or per-profile home | `core/engines/hooks.ts:189-201`; `create.ts:231`; `launchOverrides.ts:252` | claude, codex | ignored |+| The hook command line | `lib/hooks.ts:62-93`, `:423`, `:738` | `--engine` omitted for claude; every engine's home baked into every command | — |+| Accept a hook on pane evidence without process ancestry | `hookServer.ts:48` | cursor | ancestry only |+| Correct the transcript announced after a cross-folder resume | `hookServer.ts:317-324` | claude | as posted |+| Reject or hold a SessionStart | `hookServer.ts:527-540`, `:357-386` | codex sub-agent rollouts rejected; hermes held until its store names the session | register at once |+| A turn-start hook opens the turn | `core/turns/turnHooks.ts:50-56` | commandcode | ignored |+| A tool-start hook is a sub-agent | `turnHooks.ts:57-59`; `core/engines/cursorTasks.ts` | cursor `Task` | ignored |+| What a Stop hook does | `turnHooks.ts:60-216`, seven branches | claude, cursor, commandcode, devin, copilot, agy (`waiting` arms a backstop), grok (errors only) | ignored |+| The agy idle backstop | `core/turns/agyBackstop.ts` | agy | — |+| Clean-up on forget and cancel | `core/agents/forget.ts:84-87`; `core/turns/cancel.ts:48` | agy, cursor; run for every engine | — |+| Cursor transcript discovery and task replay | `cli.ts:2075-2100`, `:3387-3393`, shutdown at `:3745-3758` and `:3862-3871` | cursor | — |+| Claude cwd repair at boot | `cli.ts:3269` | claude | — |+| An engine with no `engine` in its hook body | `hookServer.ts:319`, `:336`, `:508`; `funnel.ts:132`; `cli.ts:4046`; `backendSocket.ts:2242`; `notify.mjs:85` | assumed claude | — |+| The hook script itself | `hook/notify.mjs`, about 65 branch lines | per-engine payloads, endpoints, filters, transcript paths, a second copy of process matching | — |++### 3.6 Binding a pane to a conversation (lines 20, hits about 20)++| Decision | Where | Engines → value | Default |+|---|---|---|---|+| A repeated SessionStart re-folds the transcript | `core/agents/bind.ts:123-125` | not for cursor, agy, copilot | yes |+| Replay the transcript from its start at bind | `bind.ts:158`; `cli.ts:2093` | cursor | no |+| The conversation changed inside one process | `bind.ts:204-248` | copilot `/resume`; claude `continued-in` | — |+| The transcript of a session named on the command line | `bind.ts:264-274`; `lib/sessionRepair.ts:566-602`; `registry.ts:1560-1572` | three places covering different engines (section 9) | null |+| A resume with no transcript is dropped | `bind.ts:277` | cursor, grok, claude, codex | kept |+| May bind with no transcript path | `registry.ts:1018` (load), `:1494` (register) | two lists that disagree | a path is required |+| Session-id shape | `registry.ts:1489-1493` | grok, agy, copilot: UUID | any |+| A Codex sub-agent rollout is never a session | `registry.ts:992-1013`, `:1499`; `hookServer.ts:527`; `notify.mjs:1346` | codex, three times | — |+| Claude's transcript folder decides the cwd | `registry.ts:1578`; `lib/cwdRepair.ts:39`, `:57` | claude | the hook's cwd |+| How `projectDir` is named | `registry.ts:1608` | grok, agy, copilot: from the cwd | the transcript's folder |+| An unknown persisted engine | `registry.ts:351-355` | becomes claude | — |++### 3.7 Reading the transcript in the core (lines 72, hits about 80)++| Decision | Where | Engines → value | Default |+|---|---|---|---|+| How a session is attached | `core/transcripts/attach.ts:179-373`, 13 branches | claude, codex fold from the end; opencode, kilo, hermes, devin start a database reader; the rest fold a capped tail | Claude Code's normalizer |+| Read the footer once at attach | `attach.ts:254`, `:270`, `:298`, `:306`, `:362` | cursor, opencode 100 lines; grok, agy, devin 60 | no |+| Settle a folded turn that has no end record | `attach.ts:311-326` | agy from the pane, copilot from the records | the fold's answer |+| Which normalizer a live line goes through | `core/transcripts/ingest.ts:64-119` | ten branches | Claude Code's |+| A line that announces a failed turn | `ingest.ts:71`, `:111` | codex `task_complete` error, commandcode run error | none |+| One map of state per engine | `core/transcripts/normalizers.ts`: 14 maps, five fan-out functions | — | — |+| The last turn, for the recap | `core/transcripts/lastTurn.ts:43-63` | four database reads, codex rollout, claude backward, eight capped tails | Claude Code's raw lines |+| History pages (`session_get`) | `core/transcripts/history.ts:194-339`, 24 lines | claude, codex paged; four databases windowed; cursor, pi, commandcode windowed; muse, amp, grok, agy, copilot whole | Claude Code's raw window |+| Sub-agent totals and liveness | `history.ts:109`; `core/turns/recaps.ts:89-96` | Claude's `subagents/` folder, applied to every engine | — |+| A database conversation, whole | `core/transcripts/databaseHistory.ts:22-26` | opencode, kilo, devin, hermes | none |+| The live tail's mode | `watcher/watcher.ts:140`, `:341`, `:428-456` | cursor re-reads and diffs (it rewrites in place) | append |+| Paging rules and cursors | `lib/transcriptPages.ts:358-419` | claude record id, codex line index | — |+| Attach rules from the end | `lib/attachTranscript.ts:291`, `:308` | claude, codex | — |+| Claude Code's normalizer | `lib/normalize.ts` (977 lines) | claude, as the shared default | — |++### 3.8 Where conversations live: repair, checkpoint, purge, titles, search (lines 78, hits about 120, plus 2,876 lines of search adapters)++| Decision | Where | Engines → value | Default |+|---|---|---|---|+| Transcript roots | `registry.ts:758` `TRANSCRIPT_ROOT`, `:791` moved homes | ten folders; null for the four database engines | — |+| A path shape a transcript must have | `registry.ts:806` | cursor | none |+| A transcript path to expect from an id | `registry.ts:1560-1572` | commandcode, grok, agy, copilot | null |+| Find a live process's session after a restart | `lib/sessionRepair.ts:275-429`, 13 cases | pid records (claude, codex, copilot, agy), folder scans, SQL on four stores | cursor: null |+| A transcript continued in a new session | `sessionRepair.ts:524-560` | claude | — |+| Export a database conversation for a checkpoint | `lib/sessionCheckpoint.ts:19-47`, `:109-114` | the four databases; pi writes lazily | — |+| Plan deleting a conversation | `lib/purgeAgentService.ts:40-78` | the four databases (opencode `session_v2` too); file-name shapes per engine | — |+| Data that must never be inside a deletable worktree | `lib/worktreeDeletion.ts:89-92` | 14 homes | — |+| An empty new chat, and busy footers, at close | `lib/closeAgentService.ts:26`, `:40` | claude, codex | unknown |+| Database engines are not found for a handoff | `lib/handoffDiscovery.ts:26`, `:39-51` | four databases; claude uses its pid record only | — |+| Cleaning a terminal title, product names, the engine's own title | `lib/sessionTitle.ts:23-110` | codex index and status; opencode and kilo prefixes | trim |+| Tool calls, work and output stats from rows | `lib/sessionWork.ts:336-362`; `lib/agentOutputStats.ts:186-206` | claude, codex, twice | nothing |+| Records that count as activity | `lib/transcriptActivity.ts:31`, `:97` | claude, codex | null |+| Search: the line normalizer per engine | `lib/sessionSearch/transcript.ts:33-63` | ten engines | header only |+| Search: conversations Harness did not start | `lib/sessionSearch/externals/` (12 files, 2,876 lines, 13 providers; opencode's serves kilo) | every engine but amp | — |++### 3.9 Reading the screen (lines 34, hits about 40)++| Decision | Where | Engines → value | Default |+|---|---|---|---|+| Which reader reads a dialog | `lib/askQuestion.ts:182-229` `parseEngineQuestionPane` | eleven readers | the numbered-row reader (claude, commandcode, and pi and terminal when asked) |+| Whether a pane is polled for questions | `askQuestion.ts:1063` | 13 engines | pi not |+| The key that submits a multi-select | `askQuestion.ts:295` | devin `Enter` | `Tab` |+| Keys that select a row | `askQuestion.ts:673-676` | amp, codex, kilo (redundant with row data) | the digit |+| The composer's prompt marker | `lib/runtimeProfileController.ts:287-292` | cursor `→`, devin `❭›❯`, opencode `┃` (never reached) | `[›❯]` |+| Which reader inspects the pane | `runtimeProfileController.ts:294-320` | pi, opencode and copilot (gutter box), grok | the marker reader |+| Plan mode on screen | `runtimeProfileController.ts:311` | codex `plan mode` | `plan mode on` |+| The dial's busy label | `cable/terminalActivity.ts:9-29`; the same gate at `cli.ts:3938` | claude, codex | none |+| Is the agent working | `lib/runtimeActivity.ts:16-77` (`CodexActivityReader`) | codex app-server; claude and codex pane | unknown |+| Team writes wait for a multi-line draft | `teams/preflight.ts:17`, `:24` | claude, codex, cursor, hermes | no |++### 3.10 Typing into the pane (lines 30, hits about 25)++| Decision | Where | Engines → value | Default |+|---|---|---|---|+| How long to wait before checking a submit | `lib/sessionInput.ts:568-592`, 13 constants | claude 3000 ms; five engines 2500; five 6000; agy 8000 | 1500 |+| Typing while a turn runs | `sessionInput.ts:67` | claude, codex | held in the daemon's queue |+| How a submit is confirmed | `sessionInput.ts:595-726` | cursor reads its composer; nine engines trust the transcript; commandcode reads `esc to interrupt` | the composer (devin lands here, though its comment says otherwise) |+| Clear the composer, settle after a turn | `sessionInput.ts:337`, `:362`, `:431`, `:495` | cursor `C-u`, 750 ms | nothing |+| Claude's pasted-content wrapper | `sessionInput.ts:299`; `teams/promptScope.ts:9`, `:71` | claude | the exact text |+| Harness's paste opens the turn | `core/input.ts:93` | commandcode | — |+| `/goal` and `/loop` | `lib/goalCommand.ts:22`, `:29` | claude both; codex `/goal` | neither |+| Device input route and busy mode | `lib/autonomous-device/input.ts:7`, `:109`, `:187` | claude native queue; codex steering from 0.106 | the legacy route |+| Device error wording | `lib/deviceErrors.ts:26` | claude; codex's usage-limit rewrite applied to every engine | generic |++### 3.11 Models and effort (lines 45, hits about 60, plus about 3,000 engine lines)++| Decision | Where | Engines → value | Default |+|---|---|---|---|+| Engines a profile id may name | `lib/runtimeProfile.ts:133` `PROFILE_RE` | 14 names in a regex | fails to parse |+| Valid effort words | `runtimeProfile.ts:134-140` | the union of seven engines' sets | — |+| May the model be switched | `runtimeProfile.ts:255-270` | claude from 2.1.153; codex 0.144 and 0.145 only | view-only |+| The model catalog | `runtimeProfile.ts:1150-1157` | claude aliases, codex `models_cache.json` (seven other builders are never called) | none |+| Model, effort, mode from a transcript record | `runtimeProfile.ts:712-764` | codex, cursor, commandcode, grok readers | Claude Code's reader, run on every other engine's records |+| From config files | `runtimeProfile.ts:772-861` | hermes, muse, amp, commandcode, claude; catalog warm-up for opencode, kilo, devin | none |+| From the pane | `runtimeProfile.ts:863-1034` | ten readers | Claude Code's header regexes, run on copilot, muse, amp |+| Which engines are polled | `cli.ts:3429` (commandcode config, 10 s), `:3450` (six engines' panes, 15 s) | — | reconcile every 5 min |+| Reported model normalised | `runtimeProfile.ts:1049-1050` | claude aliases | as read |+| Refusals before a switch | `runtimeProfileController.ts:658-676` | codex effort and plan mode | — |+| The keys that apply a switch | `runtimeProfileController.ts:680-709` | claude and codex live; six more drivers kept on purpose but unreachable (owner, 2026-07-31) | cursor's driver |+| Account rate limits | `lib/accountUsage.ts` | claude, codex | — |++### 3.12 One-shots, voice routing and token usage (lines 17, hits about 60)++| Decision | Where | Engines → value | Default |+|---|---|---|---|+| How a one-shot prompt runs | `lib/oneshot.ts:860-880`, seven worker classes; `runGrokOneShot` | claude, codex, cursor, opencode, kilo, pi, commandcode; grok on argv | none |+| Which engines are pre-warmed | `lib/disposableOneShotPool.ts:1-189` (seven keys in four places); `oneshot.ts:995` (kilo missing) | seven | — |+| The voice router's engine and model | `lib/voiceRouter.ts:60`, `:93`, `:108-134`, `:480` | priority claude > codex > … > grok; claude `VOICE_ROUTE_MODEL` | not chosen |+| Token usage | `lib/agentTokenUsage.ts:44-132`, `:283`; `core/turns/funnel.ts:102` | claude, codex from the transcript; opencode from its store | none |+| Device result evidence | `lib/autonomous-device/resultEvidence.ts:25-98`; `service.ts:109`, `:616` | claude, codex | not evidence-managed |++### 3.13 Not engine behaviour, and left alone++`'terminal'` checks (the plain shell is a core concept: about 40 sites across the reports), `typeof engine`+guards and `ENGINES.includes` validation (about 15), and the local-model runtimes `ollama`, `grid`,+`lm-studio` and `llama.cpp` in `lib/appModels.ts` and `lib/localModels.ts` (14 lines), which are not agent+engines at all. Shared vocabulary that is deliberately merged across engines also stays shared: the+dialog footers in `lib/dialogEnd.ts`, the approval and row wording in `askQuestion.ts`, and the prompt+wrappers search strips; they recognise any engine's text because the dialog above the live one can be+any engine's.++## 4. The interface++One `Engine` object per engine, made of small facets. A facet is one job (launching, reading the+transcript, reading the screen, …), so a caller depends on the one facet it uses, and an engine that+lacks a whole job (no hooks, no database, no model picker) leaves the facet out instead of answering+`null` from twenty methods. Every facet is optional except the manifest; every member of a facet is+optional unless marked required. What shared code does when a member is missing is written beside it,+and is the same fallback the guard in section 6 uses when the member throws.++Two rules shaped every signature:++- **Written against the code as it is.** Each member replaces branches listed in section 3, with the+ types those branches use today (`RegisteredSession`, `LiveEvent`, `QuestionView`, `RuntimeState`,+ `EngineInstallRecipe`, `GridEngineLaunch`, …). Where the same decision is made in several places that+ disagree (section 9), the member is defined once and the disagreement is listed as a fix for after the+ moves, not resolved silently during one.+- **Data where the code is a table, a method where it is behaviour.** Commands, aliases, flags, install+ recipes, labels, timings and capability flags are fields; tests can enumerate them, and the manifest+ can be loaded without loading behaviour.++```ts+// src/engines/engine.ts+export interface Engine {+ readonly name: ProcessEngine+ readonly manifest: EngineManifest // required: loaded with the daemon (section 6)+ readonly launch?: EngineLaunch // starting, resuming and forking the CLI+ readonly transcript?: EngineTranscript // reading what it writes: live, at attach, history, last turn+ readonly sessions?: EngineSessions // where conversations live; binding, repair, purge, search+ readonly screen?: EngineScreen // reading the pane: dialogs, footers, activity+ readonly input?: EngineInput // typing into the pane+ readonly hooks?: EngineHooks // hooks and plugins, and what each hook event means+ readonly models?: EngineModels // model and effort: read, list, switch+ readonly oneShot?: EngineOneShot // a prompt outside a session: recaps, voice routing+}+```++### 4.1 The manifest (required, loaded with the daemon)++```ts+export interface EngineManifest {+ readonly label: string // 'Claude', 'Antigravity' (agentNames.ts ENGINE_LABELS)+ readonly command: string // 'claude', 'cursor-agent', 'cmd' (engineBin.ts ENGINE_CLI_COMMANDS)+ readonly pathEnv: string // 'CLAUDE_PATH'; the launch binary is process.env[pathEnv] || command+ readonly aliases: readonly string[] // names discovery accepts (ENGINE_CLI_ALIASES)+ readonly sharedAliases?: readonly string[] // cursor and grok: ['agent']; drives the alias-ownership rules+ fallbackExecutables?(): readonly string[] // cursor: ~/.local/bin/agent; grok: $GROK_HOME/bin/grok first+ claimsAliasTarget?(realPath: string): boolean // cursor: the versions/<v>/cursor-agent layout+ readonly install: EngineInstallRecipe // (engineInstall.ts ENGINE_INSTALL)+ readonly process: { // recognising it in a pane (tmux.ts)+ readonly signature: { basenames: readonly RegExp[]; entrypoints: readonly RegExp[] }+ veto?(row: ProcessMatchRow, at: ProcessMatchContext): boolean // agy: the IDE's .app binary is not agy+ evidence?(row: ProcessMatchRow, at: ProcessMatchContext): 0 | 2 | 3 // claude, cursor, hermes, commandcode+ readonly resumeInArgv?: { flags: readonly string[]; id: RegExp; unless?: readonly string[] } // (tmux.ts RESUME_ARGS)+ }+ readonly home?: { // a non-default home for this engine (codex, hermes, claude)+ readonly env: string // 'CODEX_HOME'+ default(): string+ readonly perAgent?: boolean // read off the process and kept on the row (codex, hermes)+ readonly adoptsMovedHome?: boolean // a home moved by the user's shell (claude, codex)+ }+ readonly history: 'file' | 'database' // opencode, kilo, hermes, devin keep a database+ readonly transcriptRequired: boolean // may it bind with no transcript path; replaces four lists (section 9)+ readonly sessionIdPattern?: RegExp // grok, agy, copilot: a UUID+ readonly hookStyle: 'shell' | 'plugin' | 'none'+ readonly tuiOwnsScrollback?: boolean // grok+ readonly search?: () => Promise<SearchProvider> // the search process's reader, loaded only there+}+```++`transcriptRequired` and `sessionIdPattern` are in the manifest, not in the sessions facet, because the+registry checks them in `load()`, at boot, before any engine has been loaded.++Shared code builds from the manifests what it builds from twelve-way tables today: the launch binary+(`engineBin`), the alias-ownership snapshot, the process match, the install recipe unless a path+override is set (one helper instead of six copies), the hook validator's engine list, and the label.++### 4.2 Launch++```ts+export interface EngineLaunch {+ readonly permissionModes?: Readonly<Record<string, readonly string[]>> // claude, codex, cursor, opencode; the+ // legacy yes/no flag is permissionModes.auto (they are equal today)+ readonly firstPromptArgs?: readonly string[] // opencode ['--prompt'], claude [], codex [], hermes ['chat','-q'];+ // absent: PROMPT_UNSUPPORTED+ namedAgentArgs?(agent: string, machine: EngineMachine): readonly string[] | null // opencode v1; null: unsupported here+ readonly resumeArgs?: { args: readonly string[]; position: 'flag' | 'subcommand' } // all 14 today+ readonly forkArgs?: { lead: readonly string[]; after?: readonly string[] } // claude, codex; absent: handoff fork+ readonly launchScript?: { requiresShell?: boolean; functions(): string; invoke(tmuxBinary: string | null): string } // codex+ readonly instructions: { files: readonly string[]; createAs: string; importsAgentsMd?: boolean } // required+ contextArgs?(contextFile: string): string[] // claude, pi (dsh/adapters.ts)+ envArgs?(env: Record<string, string>): string[] // codex+ readonly projectTrust?: { trusts(path: string, home?: string): boolean; record(cwd: string, home?: string): 'trusted' | 'already' | 'skipped' } // claude, codex+ subscriptionModel?(model: string, machine: EngineMachine): SubscriptionModelLaunch | null // claude, codex, hermes, opencode+ readonly grid?: { build(o: GridLaunchOverride, m: EngineMachine): GridEngineLaunch; requiresModel?: boolean;+ webSearchUnsupportedReason?(m: EngineMachine): string | null; conflictingEnv?: readonly string[] }+ | { refused: string } // absent: GRID_ENGINE_UNSUPPORTED with the default reason+ readGridAssignment?(env: Record<string, string>, args: string): Promise<GridAssignment | null>+ readonly profileHome?: { installHooks(port: number, home: string): void } // codex: CODEX_HOME per agent; absent: refuse codexHome+ ownLoginArgs?(home: string | null | undefined): string[] // codex -c model_provider=…+ freshLaunchEnv?(env: Record<string, string>, permissionMode: string): Record<string, string> // opencode house model+ permissionEnv?(env: Record<string, string>, permissionMode: string): Record<string, string>+ beforeCreate?(ctx: { hookPort: number }): void // opencode reinstalls its plugin+ machineFacts?(): Partial<EngineMachine> // opencode major version, hermes system-managed+ prepareResume?(row: RegisteredSession): { repairedItems: number; repairedBytes?: number; backupPath?: string } // codex rollout repair+ beforeStop?(row: RegisteredSession, current: () => boolean): Promise<void> // codex shared app-server unload+ readonly resumedSessionModel?: { // opencode: set a resumed session's model in its store+ preflight(m: EngineMachine): { error: string; detail: string } | null+ apply(i: { sessionId: string; model: string; cwd?: string; checkCatalog: boolean; machine: EngineMachine }): Promise<{ ok: true } | { ok: false; code: string; detail: string }>+ }+}+/** Facts about this machine that some engine's launch needs; composed from every loaded engine's machineFacts. */+export type EngineMachine = Readonly<Record<string, unknown>>+```++### 4.3 Transcript++```ts+export interface EngineTranscript {+ /** The per-session state that folds lines into events (today's normalizers and database readers). */+ createSession(session: RegisteredSession, ctx: TranscriptContext): EngineSession+ readonly attach: {+ readonly from: 'end' | 'start' | 'store' // claude, codex read from the end; database engines poll+ rules?(fields: (line: string) => readonly RuntimeField[]): AttachRules // 'end' only+ readonly paneLinesAtAttach?: number // cursor, opencode 100; grok, agy, devin 60: chips from the footer+ settleFoldedTurn?(at: { lines: readonly string[]; pane: string | null }): boolean // agy (pane idle), copilot (records)+ }+ readonly tail?: 'append' | 'rewrite' // cursor rewrites its transcript in place+ turnAbortedBy?(line: string): { message: string; deviceMessage?: string } | null // codex, commandcode+ lastTurnText?(session: RegisteredSession): Promise<LastTurnText | null> // all 14; absent: null+ historyPage?(session: RegisteredSession, ask: { limit?: number; before?: string }, ctx: HistoryContext): Promise<HistoryAnswer>+ storedConversation?(session: RegisteredSession): Promise<readonly LiveEvent[]> // the 4 database engines+ submittedPrompt?(text: string): string // claude: strip the <pasted_content> wrapper+ subagentActive?(transcriptPath: string, agentId: string): boolean // claude's subagents/ folder+ readonly usage?: TokenUsageReader // claude, codex (transcript); opencode (store)+ toolEvents?(row: Record<string, unknown>): Iterable<ToolEvent> // claude, codex: work and output stats+ activityAt?(row: Record<string, unknown>): number | null // claude, codex: records that count as activity+ deviceEvidence?(io: DeviceEvidenceIO): { ingest(row: Record<string, unknown>): void } // claude, codex+}++export interface EngineSession {+ ingest(line: string): LiveEvent[] // file engines; a database reader polls instead+ readonly turnOpen: boolean+ closeTurn(): LiveEvent[] | void+ abortTurn?(): LiveEvent[] // copilot, agy, grok on a failed Stop+ openTurn?(userMessage?: string): LiveEvent[] // commandcode: Harness's own paste opens the turn+ start?(): Promise<void> // database readers begin polling+ stop?(): void+ readonly thinkingPrefix?: string // set by a fold from the end (claude, codex)+}++export interface HistoryAnswer {+ events: SessionEvent[]; timestamp: string; hasMore?: boolean; oldestCursor?: string | null+ staleCursor?: true; truncated?: true+}+```++`TranscriptContext` is what the core lends a session: `emit`, `announceTurnAborted`, the data folder.+`HistoryContext` lends the one `TranscriptPager` the core owns, so its line indexes stay shared.++### 4.4 Sessions++```ts+export interface EngineSessions {+ readonly store: FileStore | DatabaseStore+ readonly resetOnSessionStart?: boolean // a repeated SessionStart re-folds; default true; cursor, agy, copilot false+ readonly replayTranscriptOnBind?: boolean // cursor+ isSubagent?(transcriptPath: string): boolean // codex: a sub-agent rollout is never a session (three copies today)+ repairOnLoad?(sessionId: string, transcriptPath: string, home?: string | null): string | null | undefined // codex parent rollout+ findLive?(q: { cwd: string; startedAtMs: number; bornOnly?: boolean; pid?: number; home?: string }): Promise<RepairedSession | null>+ // rebinding after a restart: 12 engines; cursor has none+ sessionForPid?(pid: number, cwd: string, startedAtMs: number): Promise<RepairedSession | null> // claude's pid record+ locate?(sessionId: string, at: { cwd?: string | null; home?: string | null }): Promise<string | null>+ // the transcript of a known id: one member for three places that disagree+ followSessionSwitch?(agent: RegisteredSession, observed: DiscoveredTerminalAgent): Promise<SessionSwitch | null>+ // copilot /resume in process; claude continued-in+ provenCwd?(transcriptPath: string, cwd: string): string | null // claude: the transcript's folder decides+ readonly projectDirFromCwd?: boolean // grok, agy, copilot+ readonly titles?: { clean?(title: string, cwd?: string | null): string; productNames?: readonly string[];+ ownTitle?(sessionId: string, home?: string | null): string | null } // codex index and status line+ readonly close?: { emptyUntilBound?: boolean; busyFooter?: RegExp } // claude, codex+ dataRoots?(): string[] // folders a worktree deletion must never contain+}++export interface FileStore {+ readonly kind: 'file'+ roots(home?: string | null): string[] // TRANSCRIPT_ROOT, and a moved or per-agent home+ acceptsPath?(realPath: string): boolean // cursor's agent-transcripts/<id>/<id>.jsonl+ expectedPath?(sessionId: string, cwd: string | null): string | null // commandcode, grok, agy, copilot+ fileMatchesSession?(path: string, sessionId: string): boolean // purge+ readonly writesLazily?: boolean // pi announces its id before it writes the file+}++export interface DatabaseStore {+ readonly kind: 'database'+ databasePath(session: SessionRef): string | Promise<string> // hermes: per profile home+ readonly exportSelections: readonly (readonly [table: string, where: string])[] // checkpoint+ deletionPlan(query: (sql: string) => Promise<SqliteRow[]>, idLiteral: string): Promise<{ sessionTable: string; children: [string, string][] }>+}+```++Session search keeps its own contract (`ExternalProvider` in `lib/sessionSearch/externals/types.ts`, which+is already engine-agnostic in its consumers) and reaches each engine's adapter through+`manifest.search`. Each process builds its own providers from the factory, because they hold caches. An+engine's search module may import its normalizer and its store reader, never `src/core`: the search+process today loads 98 modules (about 25,000 lines); importing every module under `src/engines` would add+32 files and about 3,900 lines, none of them core, which is acceptable, and per-engine search modules keep+it lower still.++### 4.5 Screen and input++```ts+export interface EngineScreen {+ readonly paintsDialogs: boolean // polled for questions: 13 engines, not pi+ readDialog?(capture: string): PaneView // absent: the numbered-row reader from kit/ (claude, commandcode)+ inspect?(capture: string): PaneInspection // idle, draft, dialog, plan; absent: the marker reader from kit/+ readonly promptMarker?: RegExp // cursor →, devin ❭›❯; default [›❯]+ readonly planMode?: RegExp // codex 'plan mode'; default 'plan mode on'+ activity?(screen: string): { label: string; indicator: string } | null // the dial's busy label: claude, codex+ probeActivity?(session: RegisteredSession): Promise<ActivityState> // codex app-server thread/read+ stoppedGoal?(screen: string | null): boolean // codex+ composerHolds?(capture: string, content: string): boolean+ workingOnScreen?(capture: string, content: string): boolean // commandcode, cursor+ readonly composer?: { marker: RegExp; multilineDraft?: boolean; firstLineTextIsPlaceholder?: boolean } // team drafts+}++export interface EngineInput {+ readonly submitVerifyMs?: number // claude 3000; opencode, kilo, pi, hermes, devin 2500;+ // commandcode, muse, amp, grok, copilot 6000; agy 8000; default 1500+ readonly typesWhileBusy?: boolean // claude, codex+ readonly submitEvidence?: 'pane' | 'transcript' | 'composer-echo' // default 'pane'; cursor 'composer-echo'+ readonly clearComposerKey?: string // cursor 'C-u', before a paste and after its echo+ readonly turnEndSettleMs?: number // cursor 750+ readonly commands?: { goal?: boolean; loop?: boolean } // /goal: claude, codex; /loop: claude+ deviceBusyMode?(cliVersion: string | undefined): 'native_queue' | 'steering' | 'native_input' // claude, codex+ errorText?(message: string): string | null // device error wording+}+```++### 4.6 Hooks++```ts+export interface EngineHooks {+ install(port: number): void // 13 engines; muse has none+ installIn?(port: number, home: string): void // claude, codex: a moved or per-profile home+ readonly trustPaneWithoutAncestry?: boolean // cursor+ admit?(body: HookBody): Promise<HookAdmission> // codex rejects sub-agents; hermes holds until its store says+ transcriptFor?(body: HookBody, agent: RegisteredSession | undefined): string | undefined // claude after a cross-folder resume+ onTurnStart?(ctx: HookTurnContext, sessionId: string): void // commandcode+ onToolStart?(ctx: HookTurnContext, body: ToolStartBody): void // cursor Task sub-agents+ onStop?(ctx: HookTurnContext, body: { sessionId: string; status?: string }): Promise<void> // claude, cursor,+ // commandcode, devin, copilot, agy, grok; absent: ignored+ start?(ctx: EngineRuntimeContext): void // cursor transcript discovery and task replay; claude cwd repair+ stop?(): void+ forgetSession?(sessionId: string): void // agy idle watch, cursor sub-agents and pending tasks+ cancelTurn?(sessionId: string): void // cursor+}+```++`HookTurnContext` is the core's side: the session's `EngineSession`, `drain`, `emit`,+`announceTurnAborted`, `noteEngineStopped`, `captureTerminal`, the grace period. The four Stop handlers+that repeat "drain, wait, drain, close" use one helper from `kit/`.++### 4.7 Models++```ts+export interface EngineModels {+ readonly efforts: ReadonlySet<string> // required when present; validates a profile against its own engine+ readTranscript?(raw: Record<string, unknown>, state: RuntimeState, ctx: RuntimeReadContext): void+ readonly readsTranscriptFromEnd?: boolean // claude, codex+ readConfig?(session: RegisteredSession, state: Readonly<RuntimeState>): Promise<Partial<Pick<RuntimeState, 'model' | 'effort'>> | null>+ warmCatalog?(session: RegisteredSession): Promise<void>+ readPane?(pane: string, ctx: PaneReadContext): PaneObservation | null+ readonly pollPaneMs?: number // devin, cursor, grok, agy, opencode, kilo: 15000+ readonly pollConfigMs?: number // commandcode: 10000+ canonicalModel?(model: string): string // claude: claude-opus-5… → opus+ fallbackEffort?(model: string, cliVersion: string | null): string | null+ forget?(sessionId: string): void+ readonly switching?: { // claude and codex only (owner, 2026-07-31)+ supports(session: RegisteredSession): boolean+ models(session: RegisteredSession, state: Readonly<RuntimeState>): Promise<RuntimeModelOption[]>+ effortAllowed?(model: string, effort: string): boolean+ readonly refuseInPlanMode?: boolean+ readonly opensPicker: boolean+ apply(session: RegisteredSession, target: RuntimeProfile, current: RuntimeProfile | null, options: RuntimeModelOption[], io: RuntimeControlIO): Promise<void>+ }+ readonly accountUsage?: { provider: UsageProviderId; read(deps: AccountUsageDeps): Promise<AccountUsageReading> } // claude, codex+}+```++### 4.8 One-shot++```ts+export interface EngineOneShot {+ readonly prewarm: boolean // claude, codex, cursor, opencode, pi, commandcode, kilo; grok false+ createWorker?(o: { cwd: string; model?: string; effort?: OneShotOptions['effort'] }): Promise<DisposableWorker<OneShotOptions, OneShotResult>>+ run?(o: OneShotOptions): Promise<OneShotResult> // grok: argv, not a worker+ readonly routerRank?: number // voice router priority: claude 1 … grok 8+ routerModel?(): string // claude: VOICE_ROUTE_MODEL+}+```++### 4.9 Size, and what each engine fills in++Counted from the blocks above: **132 top-level members in 13 interfaces (nine facets, the manifest, the+session object and the two stores), 74 methods and 58 data fields**, plus a few nested members (the+process match, the attach strategy, model switching). About 20 are required: `name`, the manifest's+identity fields (`label`, `command`, `pathEnv`, `aliases`, `install`, the process signature, `history`,+`transcriptRequired`, `hookStyle`), and inside a facet that is present, its core (`createSession` and+`attach`, `store`, `paintsDialogs`, `efforts`, `prewarm`, `install`, the session's `ingest`, `turnOpen` and+`closeTurn`). The rest are optional, because for each of them at least one engine has nothing to say.++That is larger than "a few small interfaces", and it is the honest size: it is what the code decides+per engine today, minus the decisions that turned out to be duplicates. Most engines fill far fewer+members than that. What each engine fills, in short:++| Engine | Launch | Transcript (attach; history) | Store | Screen and input | Hooks | Models | One-shot |+|---|---|---|---|---|---|---|---|+| claude | modes, first prompt, fork, trust, `CLAUDE.md`, grid, subscription | from the end; pages | file; pid record; continuation; cwd proof | kit dialog reader; types while busy; 3000 ms; `/goal`, `/loop`; busy label | install, `installIn`, `onStop`, `transcriptFor` | switching from 2.1.153; transcript, config and pane readers | yes, rank 1 |+| codex | modes, first prompt, fork, launch script, profile home, own login, resume repair, stop unload, grid | from the end; pages; failed-turn lines | file; sub-agent check; rollout repair on load | dialog labels; types while busy; plan mode; activity probe; stopped goal | install, `installIn`, `admit` | switching on 0.144 and 0.145; catalog cache | yes, rank 2 |+| cursor | modes (`auto`, `ask`) | capped tail; rewritten in place; footer at attach; windowed | file, path shape | permission rows; composer echo, `C-u`, 750 ms settle | install, `onStop`, `onToolStart`, pane trust, start, forget, cancel | pane reader, polled | yes |+| opencode | modes, first prompt, named agent (v1), house env, plugin reinstall, grid, subscription, session model | database reader; footer at attach; windowed | database (with `session_v2`) | review and question readers; transcript-confirmed submit | plugin | pane reader, polled; catalog | yes |+| pi | context argv, grid | capped tail; windowed | file, written lazily | not polled for dialogs; gutter-free footer reader | extension | pane reader | yes |+| hermes | first prompt, grid, subscription | database reader (per profile home); windowed | database | framed dialog reader | install, `admit` (holds) | config and pane readers | no |+| commandcode | — | capped tail; failed-turn lines; windowed | file, expected path | kit dialog reader; `esc to interrupt`; 6000 ms | install, `onTurnStart`, `onStop` | config polled every 10 s; pane reader | yes |+| devin | — | database reader with turn abort; footer at attach; windowed | database | its own rows, `Enter` submits | install, `onStop` | pane reader, polled | no |+| muse | — | capped tail; whole page | file | its own dialog reader; 6000 ms | none | config reader | no |+| amp | — | capped tail of the plugin's file; history from Amp's export | file (plugin-written) | unnumbered rows walked with `Down`; 6000 ms | plugin | mode reported as the model | no |+| kilo | — | database reader; windowed | database | horizontal rows walked with `Right` | plugin | pane reader, polled | yes |+| grok | grid | capped tail; footer at attach; whole page | file, UUID ids, expected path | `(●)` rows; owns its scrollback | install, `onStop` (errors) | transcript and pane readers, polled | argv, rank 8 |+| agy | `GEMINI.md` | capped tail; footer at attach; settled from the pane; whole page | file, UUID ids, expected path | its own dialog reader; 8000 ms | install, `onStop` (`waiting` backstop) | pane reader, polled | no |+| copilot | grid (model required) | capped tail; settled from the records; whole page | file, UUID ids, session switch in process | dialog with its subject folded in; 6000 ms | install, `onStop` | — | no |++Every engine also fills the manifest and `resumeArgs` (all fourteen resume today).++## 5. Where the code goes++```+src/engines/+ engine.ts the Engine interface and its facets (types only)+ facets/ one file of types per facet, so parallel steps edit different files+ registry.ts MANIFESTS (eager) · engineFor · loadEngine+ guard.ts engineOf: every call wrapped, with its fallback; onDegraded+ kit/ engine-agnostic pieces engines compose: history windowing for files and+ databases, the numbered-row dialog reader, "drain, wait, close" for Stop hooks,+ the gutter-box pane reader. Never names an engine.+ types.ts ENGINES, AgentEngine, ProcessEngine, isTerminalEngine (as today)+ claude/ codex/ built in+ cursor/ opencode/ pi/ hermes/ kilo/ devin/ amp/ agy/ grok/ copilot/ commandcode/ muse/+ manifest.ts loaded with the daemon+ index.ts the Engine: imports its facet files+ transcript.ts sessions.ts screen.ts input.ts launch.ts hooks.ts models.ts oneShot.ts+ search.ts imported only by the search process+ normalizer.ts reader.ts askQuestion.ts runtimeProfile.ts … (the files each folder has today)+```++This is the layout at the end. While the moves run, `index.ts` does not exist yet and each facet has a+table file in `src/engines/` instead (section 8.1, rule 5), so that parallel lanes do not all edit the+same fourteen files.++**One file per facet in each engine folder.** Each migration step adds one facet to every engine. If+the facets lived in one `index.ts` per engine, every parallel step would edit the same fourteen files.+With a file per facet, a step adds `screen.ts` to each folder and one line to each `index.ts`; the first+step writes every `index.ts` with all facet lines present and commented out, one blank line apart, so+two steps that each uncomment one line never touch adjacent lines and git merges them cleanly.++**The kit is not a default.** When two or more engines share a piece today (the numbered-row dialog+reader serves Claude Code, Command Code, Codex and Hermes; OpenCode and Copilot share the gutter-box+footer reader; four Stop hooks repeat "drain, wait, drain, close"), that piece goes to `kit/` and each+engine that uses it says so in its own folder. No engine gets anything it does not name. That replaces+the `else` branch that gives an unnamed engine Claude Code's behaviour.++**Claude Code's folder, `src/engines/claude/`.** Claude Code has no folder today. Its behaviour is the+default in shared code, so its folder is assembled from pieces that are spread out:++| Piece | Today | Goes to |+|---|---|---|+| The transcript normalizer: `transformLine`, `messagesToEvents`, `lineToEvents`, `TurnState`, `windowRawLines`, `claudePageLine`, `startsClaudeTurn`, `claudeToolLinks`, `selectClaudeRecapLine`, `lastTurnTextFromRawLines`, `SubagentStats` | `lib/normalize.ts` (977 lines, imported by 44 files) | `claude/normalizer.ts`; the event types (`LiveEvent`, `SessionEvent`, `LastTurnText`) and `foldTranscript`/`TranscriptFold` stay in `lib/normalize.ts`, which shrinks to the shared part |+| Attach rules read from the end | `claudeAttachRules` in `lib/attachTranscript.ts` | `claude/transcript.ts` (the attach machinery stays in lib) |+| History pages | `TranscriptPager.claude` in `lib/transcriptPages.ts` | the pager takes `PageRules` from the engine; the rules go to `claude/transcript.ts` |+| Sub-agent transcripts (`<session>/subagents/agent-<id>.jsonl`) | `enrichSubagentStats` in `core/transcripts/history.ts`, `subagentActive` in `core/turns/recaps.ts` | `claude/transcript.ts` |+| Last turn for the recap | `core/transcripts/lastTurn.ts`, the `claude` line | `claude/transcript.ts` |+| Project pre-trust | `lib/claudeTrust.ts`, `lib/claudeProject.ts` | `claude/launch.ts` |+| Transcript roots, resume lookup, continuation, cwd repair | `lib/registry.ts`, `lib/sessionRepair.ts`, `lib/cwdRepair.ts`, `lib/captureResumeIdentity.ts` | `claude/sessions.ts` |+| Hooks: settings.json events, the Stop handling | `lib/hooks.ts` `installSessionHooks`, `core/turns/turnHooks.ts` the default branch, `hookServer.ts` `knownTranscriptFor` | `claude/hooks.ts` |+| The question dialog | the default branch of `parseEngineQuestionPane` (`parseQuestionPane`) | `kit/` (it is shared with three engines); `claude/screen.ts` names it |+| Pasted-content wrapper, busy footer, native queue | `lib/sessionInput.ts`, `teams/promptScope.ts`, `cable/terminalActivity.ts`, `lib/autonomous-device/*` | `claude/input.ts`, `claude/screen.ts` |+| Models and effort | `RuntimeProfileManager.claudeModels`, `claudeAliasForModel`, `claudeEfforts` in `lib/runtimeProfile.ts` | `claude/models.ts` |+| Recap one-shot, `/goal` and `/loop`, instruction file name | `lib/oneshot.ts`, `lib/goalCommand.ts`, `dsh/runtime.ts`, `lib/apiInstructions.ts` | `claude/oneShot.ts`, `claude/launch.ts` |+| Account usage | `lib/accountUsage.ts` `readClaude` | `claude/models.ts` |+| Search adapter | `lib/sessionSearch/externals/claude.ts` | `claude/search.ts` |++Codex already has a folder; its pieces in shared code (`lib/codexProfiles.ts`, `codexProfileDiscovery.ts`,+`codexHomeProbe.ts`, `codexSessionLifecycle.ts`, `codexStartupRetry.ts`, `codexTurnRecovery.ts`,+`CodexActivityReader` in `lib/runtimeActivity.ts`, `codexAttachRules`, `TranscriptPager.codex`) move into+it the same way.++**What stays in lib.** The machinery that is generic today and only takes engine rules as arguments:+`attachTranscript.ts` (`AttachRules`), `transcriptPages.ts` (`PageRules`), `transcriptTail.ts`,+`tmuxCapture.ts`, the watcher's two tail modes. These already have the right shape; the rules move, the+machinery stays.++**What stays a field of the session row.** `codexHome` and `hermesHome` are engine-specific fields of+the persisted registry, on the wire (`agent_create.codexHome`, `engines_probe.supportsCodexHome`) and in+about 30 shared files. During the moves they stay, read only by the engine that owns each. Renaming them+to one generic `engineHome` is a data migration of `registry.json` and of the wire, so it is its own late+step, done additively (read both, write both, then drop the old) and never inside a move.++## 6. Loading and isolation++### 6.1 Two halves: a manifest loaded with the daemon, the engine loaded on first use++Some questions have to be answered for every engine before any agent of it exists. Discovery scans+every pane for every engine's process. The hook server checks that a posted engine name is one it+knows. The New Harness picker lists every engine, with its install recipe. None of that can wait for an+import. So each engine is split in two:++- **`manifest.ts`**, loaded with the daemon: the `EngineManifest` of section 4.1. Data and a few small+ pure functions (the process score). It imports nothing but types and `config/env.ts`.+- **`index.ts`**, loaded on first use: the `Engine` with every facet.++`src/engines/registry.ts` holds both:++```ts+export const MANIFESTS: Readonly<Record<ProcessEngine, EngineManifest>> // eager, every engine++/** The engine, if it is loaded. Synchronous, for the call sites that are (a pane parse, a key table). */+export function engineFor(name: string | null | undefined): Engine | undefined+/** Load it. Claude Code and Codex resolve at once; the rest import their folder the first time. */+export function loadEngine(name: ProcessEngine): Promise<Engine | undefined>+```++Claude Code and Codex are imported statically: they are what almost every machine runs, the e2e suite+drives them, and their absence would be a bug, not a choice. The other twelve are+`() => import('./cursor/index.js')` and so on.++**Where loading happens.** An engine is loaded at the four places an agent of it first becomes known,+all of which are already asynchronous: a hook's registration (`hookServer.ts`), discovery identifying a+pane (`core/agents/discovery.ts`), a create or resume request (`core/agents/launches.ts`), and the boot+restore of saved agents (before their attaches run). `attachSession` also awaits `loadEngine` first, as+a backstop. After that every synchronous call site finds the engine loaded. If one does not (a race+not foreseen here), `engineFor` returns undefined and the call takes its fallback from section 6.3, the+same as an engine without that facet, and logs it: never a throw.++### 6.2 What lazy loading buys, measured++The release is one esbuild ESM file with no code splitting (`build-bundle.mjs`). Built with a metafile+on 2026-10-05, the thirteen engine folders are 139 KB of the 3.34 MB bundle (4.2%), and the search+adapters another 56 KB (1.7%). Engine code still in `lib/` (the twelve-way tables, the hook installers+and their embedded plugin sources, the pane readers) is perhaps as much again.++Inside one bundle, a dynamic `import()` does not keep code out of the file. esbuild wraps the module in+an initialiser that runs on first import, so what is saved is the module's evaluation: its top-level+tables, regular expressions and classes, and the bytecode V8 would compile for them. For twelve engines+that is on the order of a megabyte of heap, not tens. To keep the code out of memory entirely the+bundle would need `splitting: true`, which ships chunk files beside `cli.js`; `upload-cli.sh` ships+`cli.js` and `notify.mjs` and nothing else, and the self-updater swaps one file. That is a release+format change and is not part of this plan.++So lazy loading is worth doing for a smaller memory gain than the name suggests, and for two better+reasons:++1. **Isolation at load.** Today a module that throws while it is evaluated stops the daemon from+ starting, for every agent. A lazily loaded engine that throws fails `loadEngine` for that engine+ only: its agents are degraded (section 6.3), and every other agent runs.+2. **A smaller start.** The core evaluates two engines at start instead of fourteen, and the step that+ introduces lazy loading measures the difference (heap after start, with and without, in the e2e+ harness) so the number in this section is replaced by a measured one.++The search service runs in its own process, and imports only what it needs: each engine's search+adapter is its own module (`engines/<x>/search.ts`), reached through the manifest+(`manifest.search?: () => Promise<SearchProvider>`), so the search process never loads an engine's+pane readers or launch code.++### 6.3 The guard: a throw degrades one agent, never the core++Every call from shared code into an engine goes through one wrapper, `src/engines/guard.ts`, applied+where the engine is looked up. Call sites never hold an unguarded engine, so they need no try/catch of+their own, and a new call site cannot forget one.++```ts+/** The engine for this agent, with every method wrapped. Never throws; a throw inside is reported and+ * answered with the method's fallback. */+export function engineOf(agent: { agentId: string; engine: string }): GuardedEngine+export function onDegraded(listener: (d: Degraded) => void): () => void++interface Degraded { agentId: string; engine: ProcessEngine; facet: string; method: string; message: string; at: number }+```++The wrapper catches synchronous throws and rejected promises, logs them once per agent and method per+minute (a parser that throws on every poll would otherwise fill the log), counts them, and emits+`Degraded`. The core turns that into an additive event on the agent (`agent_degraded`, with the facet),+so a window can say "Harness can't read this agent's questions" instead of failing silently. The+fallbacks are declared once, beside the interface, the way `core/api.ts` declares each port's fallback+beside the port.++What degraded means, method by method:++| Facet, method | Fallback when the engine lacks it or throws | What the person sees |+|---|---|---|+| `transcript.createSession` | none: the agent is not followed | the pane works; no live stream, no turns, a degraded badge |+| `transcript` session `ingest(line)` | `[]` for that line (today's per-line catch in `ingest.ts`, kept) | a gap in the stream; turns may stay open until the next boundary |+| `transcript.lastTurnText` | `null` | no recap text for that turn |+| `transcript.historyPage` | the request fails with `ENGINE_FAILED`, as a failed store read does today | the history pane shows an error and can retry |+| `transcript.settleFoldedTurn` | the fold's own answer | a finished turn may show as working after a restart |+| `screen.readDialog` | `null` (no dialog) | no question card; the dialog is still answerable in the pane |+| `screen.inspect` | `null` | empty chips; a model switch is refused with a reason |+| `screen.activity` | `null` | no busy label on the dial |+| `input.*` (data) | the shared default | today's default behaviour |+| `launch.argv` | the create fails with `ENGINE_FAILED` and the message | the request is refused with a reason; no pane is opened |+| `hooks.install` | skipped | the agent is found by discovery instead of by its hook |+| `hooks.admit` | admit as posted | as today for an engine with no check |+| `turnHooks.onStop` and `onToolStart` | the hook is ignored | the turn closes from the transcript, or stays open (as without hooks) |+| `sessions.find*`, `sessions.repair` | `null` | the agent stays unbound; the reconciler tries again |+| `sessions.purge`, `sessions.checkpoint` | `{ bytes: 0 }` / no checkpoint | the purge reports nothing freed |+| `models.catalog` | `[]` | no model picker |+| `models.set` | the request fails with `ENGINE_FAILED` | the switch is refused with the reason |+| `oneShot.run` | skipped | no recap for that turn |+| `search` adapter | that engine's results are missing; the reply says `partial: true` | search finds the other engines |+| `manifest.process.score` | `0` | a pane of that engine is not recognised until the next scan |+| `loadEngine` | `undefined` for that engine | every agent of that engine is degraded; others run |++Stateful pieces (the per-session normalizer, the database readers' pollers) are wrapped the same way:+the object an engine returns is wrapped method by method. A reader whose poll throws three times in a+row is stopped and its agent degraded, instead of throwing every second for ever.++## 7. The rule test++`src/engineNames.spec.ts`, beside `architecture.spec.ts` and written the same way: it parses each file+with the TypeScript compiler and fails with a message that says where the code belongs.++**What it checks.** In shared code (`src/core`, `src/lib`, `src/cli.ts`, `src/backendSocket.ts`; the+step after the last move adds `src/watcher`, `src/hookServer.ts`, `src/cable`, `src/teams`, `src/dsh`,+`src/services` and `src/device`), without specs:++1. no string literal equal to an engine name (`'codex'`), which catches comparisons, `case` labels,+ lists, sets and quoted keys;+2. no object key or property read named after an engine (`{ claude: … }`, `dbs.opencode`); for+ `cursor`, `pi` and `amp`, which are ordinary words here, only inside an object that has another+ engine's key;+3. no import from `src/engines/<engine>/`; shared code imports `src/engines/registry.ts`,+ `engine.ts`, `guard.ts` and `types.ts` only;+4. no identifier named after an engine (`preTrustCodexProject`, `CODEX_HOME`, `codexHome`), except+ `cursor`, `pi` and `amp` for the same reason.++`'terminal'` is not an engine for this rule: the plain shell is a core concept, and the rule asks for+`isTerminalEngine()` instead of the literal.++**How it lands before the code is clean.** As a ratchet. The first step writes today's count per file+into `src/engineNames.baseline.json`, and the test fails when a file's count goes up or a file not in the baseline names an+engine. Steps do not edit the baseline, so parallel branches never conflict in it; after a batch of steps+merges, one commit regenerates it (`ENGINE_NAMES_BASELINE=write npx vitest run src/engineNames.spec.ts`)+and a reviewer sees the numbers fall. When every+count is zero the baseline file is deleted and the test becomes the plain rule. The test also fails if+the baseline names a file that no longer exists, the way `architecture.spec.ts` fails on an exception+that is no longer needed.++**What it counts, measured.** The committed rule (step 1) counts 2,073 engine names in 115 files on+`main` at `3e67738fe`, summing per file the literals, keys and imports and the distinct engine-named+identifiers. Section 2's figures (2,029 in 113 files) came from a prototype of the same scan on the+older `31b4a0c27`, with a slightly looser identifier pattern; the baseline file is the measure. After+step 1 the count is 1,996 in 113 files (`core/transcripts/lastTurn.ts` 50 and `databaseHistory.ts` 24 go+to zero, `cli.ts` 58 to 55); after step 2, 1,898 in 112 (`core/transcripts/history.ts` 95 to zero,+`cli.ts` to 52).++**Why a parser and not a grep.** The grep in section 2 finds 405 lines, 40 of which are not engine+behaviour, and misses tables, keys, imports and engine-named helpers entirely; a wider grep cannot tell+`'cursor'` the engine from a pagination cursor, or code from a comment. The parser sees literals, keys,+imports and identifiers as what they are.+++## 8. Migration++### 8.1 Rules for every step++1. **A step moves code; it does not change behaviour.** Each step moves one group of decisions behind+ the interface, for every engine at once, verbatim where it can be. A bug found while moving is+ written down (section 9) and fixed in its own change after the move, never inside it. The two steps+ that do change behaviour (the guard, step 5, and lazy loading, step 26) are steps of their own.+2. **Pin before moving.** For every engine without a fake in the e2e suite, the step's first commit+ adds or confirms unit tests that pin today's answer through the shared entry point (the history+ request, the last-turn reader, the dialog parser, …). The move must pass them unchanged, apart from+ wiring (a store path that used to be passed in and is now resolved by the engine). Several shared+ specs already pin every engine this way through module mocks (`core/transcripts/history.spec.ts`,+ `lastTurn.spec.ts`); since the engine files import the same engine modules, those mocks keep pinning+ across the move.+3. **The bar for each step:** `tsc`; `npm run test:core` and `npm run test:harnessd` at 100% per file;+ the full unit suite; the e2e files that exercise the moved code, from the bundle+ (`E2E_BUNDLE=1 E2E_WORKERS=2`); the rule test's counts do not rise.+4. **One group at a time, every engine at once.** Why not engine by engine: moving Claude Code's+ behaviour everywhere, then Codex's, would touch every shared file fourteen times and leave each call+ site half-branching, half-interface while it happened; the core would be more tangled in the middle+ than it is now. Group by group touches each call site once, gives each step a small set of files, and+ lets the e2e suite prove the Claude Code and Codex half of every step while the pinned unit tests+ prove the other twelve. Claude Code and Codex still come first in the sense that matters: they are+ the engines the first steps are proven on end to end, the two built into the registry from step 1,+ and the first two folders written in full.+5. **While the moves run, facets are tables.** Each facet has a table file in `src/engines/`+ (`transcripts.ts`, `screens.ts`, …) mapping every engine to its facet object, and `registry.ts`+ assembles an `Engine` from the tables. A lane adds its own table file, its facet files in each engine+ folder, and one line each in `engine.ts` and `registry.ts`; those two lines are the only lines+ parallel lanes share, and a lane that merges second keeps both. The per-engine `index.ts` of section 5+ arrives with lazy loading (step 26), which has to assemble each engine as one module anyway.+6. **Files other branches are changing now are left to the end:** `lib/engineLaunch.ts` (the launch+ script), `teams/preflight.ts` (screen footers), `lib/hooks.ts`, `hook/notify.mjs` and+ `e2e/harness/fakeEngine.mjs`, `lib/tmux.ts` and `lib/tmuxBackend.ts`, the registry's title code, and+ `lib/selfUpdate.ts`. Steps 1 to 20 touch none of them. Where a decision lives in one of those files, its+ callers keep calling the old function, now a one-line wrapper over the registry, until the file is+ free (for example `parseEngineQuestionPane(engine, capture)` and `inspectRuntimePane(engine, capture)`,+ which `teams/preflight.ts` calls).++### 8.2 The steps++Sizes are lines touched, roughly, including specs. Risk is the chance the move changes something a+person sees, given the proof listed.++**Phase A: the core's transcripts (sequential; each needs the one before).**++| # | Step | Files | Size | Risk | Proof |+|---|---|---|---|---|---|+| 1 | The registry, the transcript facet and the rule test; the last turn and the database conversation behind the facet | new: `src/engines/{engine.ts, registry.ts, transcripts.ts, facets/transcript.ts, kit/lastTurn.ts}`, `src/engines/<14>/transcript.ts` (Claude Code's folder is created), `src/engineNames.spec.ts` and its baseline; changed: `core/transcripts/lastTurn.ts`, `databaseHistory.ts`, their specs, `cli.ts` (3 lines of wiring), `engines/README.md` | +700 / −80 | low | `lastTurn.spec.ts` and `databaseHistory.spec.ts` assertions unchanged but for store paths; per-engine pins for the four stores' paths; e2e `fleet` (a dial makes recaps read the last turn), `services`, `serviceProcesses` (the search process reads stored conversations through the registry), `core` |+| 2 | History pages (`session_get`) behind `transcript.historyPage` | `core/transcripts/history.ts` and spec, `src/engines/<14>/transcript.ts`, new `kit/history.ts` (database, windowed-file and whole-file pages), `cli.ts` (deps of `createHistory`) | +550 / −320 | medium: reply shapes | `history.spec.ts` assertions unchanged; e2e `history`, `bounded`, `compaction`, `compat`, `windows`, `rotation`, `forks`, `paused`, `races`, `clockjump` |+| 3 | One table of engine sessions instead of fourteen maps; live ingest behind `createSession` and `turnAbortedBy` | `core/transcripts/normalizers.ts`, `ingest.ts` and specs; the map readers: `core/turns/turnHooks.ts`, `core/turns/funnel.ts` (a type), `core/input.ts`, `core/turns/agyBackstop.ts`, `core/engines/cursorTasks.ts`, `cli.ts` (`:2047-2049`, `:2153`, `:2162`, `:2370`); `src/engines/<14>/transcript.ts` | +450 / −380 | medium: the live path | specs of each; e2e `turns`, `core`, `lifecycle`, `content`, `questions`, `ends`, `chaos` |+| 4 | Attach behind `transcript.attach` | `core/transcripts/attach.ts` and spec; `lib/attachTranscript.ts` (Claude Code's and Codex's rules move out, the machinery stays), `testing/transcriptOracle.ts`; `src/engines/<14>/transcript.ts`; `cli.ts` (attach deps) | +500 / −400 | high: attach is where most races were found | `attach.spec.ts`; `attachTranscript.real.spec.ts` (opt-in, real transcripts); e2e `bounded`, `compaction`, `machine`, `terminal`, `recovery`, `frozen`, `clockjump`, `migration`, `startup` |+| 5 | The guard: every call through `engineOf`, fallbacks, `agent_degraded` | new `src/engines/guard.ts`; `registry.ts`; the call sites of steps 1-4; `core/agents/events.ts` (the additive event); `cli.ts` | +350 / −60 | low; a behaviour change by design (a throw is contained) | unit tests that make each facet method throw and check the fallback and the event; e2e `core`, `robustness` |++**Phase B: everything else that avoids the busy files (parallel lanes; start after step 5).**++The nine lanes (S, I, M, O, U, H, B, Q, L) can run at the same time on separate branches: within a lane the steps+are in order, and between lanes the files are disjoint except for one line each in `engine.ts`,+`registry.ts` and, where noted, a few wiring lines in `cli.ts` in regions no other lane touches. Lane M's+second step waits for lane S's step 7 (both edit `lib/runtimeProfileController.ts`); lane Q waits for lane+B's step 14 (`lib/sessionRepair.ts` imports the pi search adapter).++| # | Lane | Step | Files | Size | Risk | Proof |+|---|---|---|---|---|---|---|+| 6 | S | Dialogs: which reader, polling, multi-select key, row keys | `lib/askQuestion.ts` (dispatch; `parseEngineQuestionPane` stays as a wrapper), new `kit/dialogs.ts` (the numbered-row reader and its helpers, out of `askQuestion.ts` so engines can import them without a cycle), `src/engines/<14>/screen.ts`, `core/transcripts/attach.ts` (`pollsQuestions`) | +500 / −250 | medium | `askQuestion*.spec.ts` with every engine's fixture in `lib/__fixtures__/question-*.txt` and `permission-*.txt`, unchanged; e2e `questions`, `questions-edges`, `compat` |+| 7 | S | Pane inspection, plan mode, the dial's busy label, the activity probe | `lib/runtimeProfileController.ts` (the `inspect*` readers only; `inspectRuntimePane` stays as a wrapper), new `kit/gutterBox.ts`, `cable/terminalActivity.ts`, `lib/runtimeActivity.ts`, `lib/codexTurnRecovery.ts` → `engines/codex/`, `core/turns/activity.ts`, `cli.ts:3938` | +450 / −350 | medium | `runtimeProfileController.spec.ts` (inspection), `terminalActivity`, `runtimeActivity` specs; e2e `turns`, `stall`, `fleet` |+| 8 | I | Typing: submit windows and confirmation, typing while busy, composer clearing, the pasted-content wrapper, Command Code's paste-opened turn, `/goal` and `/loop`, device input modes and error wording | `lib/sessionInput.ts`, `core/input.ts`, `lib/goalCommand.ts`, `teams/promptScope.ts`, `lib/autonomous-device/{input,service,resultEvidence}.ts`, `lib/deviceErrors.ts`, `src/engines/<14>/input.ts` | +450 / −300 | medium | `sessionInput*.spec.ts`, device specs; e2e `content`, `input-safety`, `races`, `fleet`, `teamsProcess` |+| 9 | M | Reading model and effort: profile ids, effort sets, transcript, config and pane readers, polling intervals, normalising | `lib/runtimeProfile.ts` (the readers; the manager stays), `src/engines/<14>/models.ts`, `cli.ts:3426-3458` (pollers driven by the facet) | +1,300 / −1,100 | medium | `runtimeProfile*.spec.ts`, `commandcodeModel.spec.ts`; e2e `compat` (model chips), `services` |+| 10 | M (after 7) | Switching: the gate, catalogs, refusals, the key sequences (the unreachable drivers move with their engines unchanged), account usage | `lib/runtimeProfileController.ts`, `lib/runtimeProfile.ts` (catalogs), `lib/accountUsage.ts`, `src/engines/<14>/models.ts` | +900 / −800 | medium | `runtimeProfileController.spec.ts`; e2e `compat`, `services` |+| 11 | O | One-shots and the voice router | `lib/oneshot.ts` (workers move; the pool and `runDirect` stay), `lib/disposableOneShotPool.ts` (a `Map` keyed by engine), `lib/voiceRouter.ts`, `src/engines/<8>/oneShot.ts` | +900 / −850 | low | `oneshot`, `voiceRouter`, `grokOneShot`, `kiloOneShot` specs |+| 12 | U | Rows read from transcripts: token usage, work, output stats, activity | `lib/agentTokenUsage.ts`, `lib/sessionWork.ts`, `lib/agentOutputStats.ts`, `lib/transcriptActivity.ts`, `core/turns/funnel.ts:102`, `src/engines/{claude,codex,opencode}/transcript.ts` | +250 / −200 | low | their specs; e2e `windows`, `history` (last activity) |+| 13a | H | Turn hooks: Stop, turn start, tool start; the agy backstop and Cursor's tasks become the engines' own | `core/turns/turnHooks.ts`, `core/turns/agyBackstop.ts` → `engines/agy/`, `core/engines/cursorTasks.ts` → `engines/cursor/`, `core/agents/forget.ts`, `core/turns/cancel.ts`, new `kit/stop.ts`, `cli.ts` (`:2161-2169`, `:2370-2386`, `:2644-2649`), `src/engines/<7>/hooks.ts` | +450 / −400 | medium | `turnHooks.spec.ts`; e2e `turns`, `ends`, `compaction`, `stall` |+| 13b | H | The hook server's engine decisions and the install dispatch (installers imported from `lib/hooks.ts`, which is not edited) | `hookServer.ts`, `core/engines/hooks.ts`, `src/engines/<13>/hooks.ts` | +300 / −200 | medium | `hookServer.spec.ts`, `core/engines/hooks.spec.ts`; e2e `core`, `robustness`, `startup` |+| 13c | H | Cursor's discovery and replay as `hooks.start`, `stop`, `forgetSession`; the watcher's tail mode from the facet | `cli.ts` (`:2075-2100`, `:3387-3393`, the two shutdowns), `watcher/watcher.ts`, `src/engines/cursor/` | +200 / −180 | medium (no e2e for Cursor) | watcher and Cursor specs; `localE2e.spec.ts` (opt-in, real Cursor) |+| 14 | B | Binding and repair: the live-session finders, the transcript of a known id (three places become one member), session switches, continuation, cwd proof, resume identity, handoff discovery, close | `core/agents/bind.ts`, `lib/sessionRepair.ts`, `lib/captureResumeIdentity.ts`, `lib/cwdRepair.ts`, `lib/handoffDiscovery.ts`, `lib/closeAgentService.ts`, `core/agents/discovery.ts`, `src/engines/<14>/sessions.ts` | +700 / −600 | high: restart and resume | `sessionRepair`, `captureResumeIdentity`, `bind` specs, `npm run test:resume`; e2e `recovery`, `machine`, `migration`, `orphan`, `forks`, `ends` |+| 15 | B | Database stores: checkpoint, purge, worktree safety, handoff | `lib/sessionCheckpoint.ts`, `lib/purgeAgentService.ts`, `lib/worktreeDeletion.ts`, `lib/sqliteAvailability.ts`, `lib/agentHandoff.ts:67`, `src/engines/{opencode,kilo,hermes,devin}/sessions.ts` | +250 / −200 | medium | their specs, with pins for each store's tables; e2e `ends`, `folders` |+| 16 | B (after the title branch lands) | Titles: cleaning, product names, Codex's own title | `lib/sessionTitle.ts`, `src/engines/{codex,opencode,kilo}/sessions.ts` | +100 / −80 | low | `sessionTitle.spec.ts`; e2e `windows`, `hostname` |+| 17 | Q (after 14) | Search: line normalizers and the 13 providers move to `engines/<x>/search.ts`, reached through `manifest.search` | `lib/sessionSearch/{transcript,indexer,sessionTurns}.ts`, `lib/sessionSearch/externals/*` (moves; `support.ts`, `types.ts`, `external.ts` stay), `services/searchProcess.ts`, `cli.ts:1815-1817` | +3,000 / −2,950, nearly all `git mv` | low | the externals specs move with their files; e2e `services`, `serviceProcesses` |+| 18 | L | Workspace: pre-trust, instruction files, harness context argv | `lib/claudeTrust.ts`, `lib/claudeProject.ts` → `engines/claude/`, `core/agents/launches.ts`, `core/agents/create.ts:175`, `dsh/adapters.ts`, `dsh/runtime.ts`, `lib/apiInstructions.ts`, `src/engines/<14>/launch.ts` | +350 / −250 | medium | `claudeTrust`, `dsh` specs; e2e `folders`, `dotfiles`, `shells` |+| 19 | L | Grid, subscription model, house env, Codex profile home and own login, resume repair, stop unload, a resumed session's model | `lib/gridLaunch.ts`, `lib/gridWebMcp.ts`, `lib/gridAssignment.ts`, `lib/subscriptionModel.ts`, `lib/harnessDefaults.ts`, `lib/launchOverrides.ts`, `lib/codexSessionLifecycle.ts` → `engines/codex/`, `core/agents/{launch,create,fork,retarget}.ts`, `lib/stopAgentService.ts` | +1,000 / −900 | medium | grid and launch specs; e2e `enginehomes`, `updates`, `forks` |+| 20 | L | The manifest: binary, aliases, install, labels, homes, Codex profiles, shared-server attribution | `lib/engineBin.ts`, `lib/engineInstall.ts`, `lib/agentNames.ts`, `lib/engineHomes.ts`, `lib/codexHomeProbe.ts`, `lib/hermesHome.ts`, `lib/codexProfiles.ts` and `codexProfileDiscovery.ts` → `engines/codex/`, `lib/harnessResources.ts`, `lib/terminalStreamManager.ts:1132`, `lib/terminalAgentDiscovery.ts:141`, `backendSocket.ts:1962`, `:2197-2218` | +900 / −800 | medium | `engineBin`, `engineInstall`, `engineHomes`, discovery specs; e2e `enginehomes`, `cli`, `updates`, `startup` |++**Phase C: the busy files, once their branches have landed (parallel with each other).**++| # | Step | Files | Size | Risk | Proof |+|---|---|---|---|---|---|+| 21 | Launch argv: permission modes, first prompt, named agent, resume, fork, the Codex launch script | `lib/engineLaunch.ts`, `src/engines/<14>/launch.ts` | +450 / −350 | high | `engineLaunch.spec.ts`, `engineShellStartup.spec.ts`; e2e `updates`, `updateHostile`, `shells`, `dotfiles`, `lifecycle` |+| 22 | Process recognition and the argv read-backs | `lib/tmux.ts` (`ENGINE_PROCESS_SIGNATURES`, evidence, `RESUME_ARGS`, permission read-back), manifests | +350 / −300 | high: discovery | tmux specs; `test:tmux-real` on a machine with the engines; e2e `tmuxmoves`, `orphan`, `startup`, `twodaemons` |+| 23 | Hook installers and plugin sources | `lib/hooks.ts` (about 1,100 lines move), `src/engines/<13>/hooks.ts` | +1,200 / −1,150 | medium | `hooks.spec.ts`; e2e (the fakes install real hooks) |+| 24 | Transcript roots, accept-lists, session-id shapes, expected paths, load repair | `lib/registry.ts` (away from the title code), manifests and stores | +250 / −200 | high: what loads at boot | `registry.spec.ts`; e2e `migration`, `machine`, `recovery` |+| 25 | Team drafts | `teams/preflight.ts` (`screen.composer`) | +60 / −40 | low | preflight specs; e2e `teamsProcess` |++`hook/notify.mjs` is not in the plan's moves: it is a standalone script copied beside the bundle, it+cannot import TypeScript, and it is the engines' hook client rather than shared daemon code. Its+engine knowledge (about 700 lines) drifts from the daemon's (section 9). The fix is a later, separate+decision: build it from TypeScript so it imports the manifests.++**Phase D: finishing (sequential).**++| # | Step | Files | Size | Risk | Proof |+|---|---|---|---|---|---|+| 26 | Lazy loading: each engine's `manifest.ts` and `index.ts`; the tables become loaders; load points; a heap measurement | `src/engines/**` (index files, tables removed), `registry.ts`, the four load points (`hookServer.ts`, `core/agents/discovery.ts`, `core/agents/launches.ts`, boot restore in `cli.ts`), `core/transcripts/attach.ts` | +400 / −300 | medium: a missed load point degrades an agent instead of failing | a spec that a non-built-in engine is not evaluated at start; an e2e that starts a daemon and checks heap and module evaluation; the full e2e suite |+| 27 | The rule becomes absolute and covers every shared folder | `src/engineNames.spec.ts`; the baseline file deleted | +40 / −150 | none | the spec |+| 28 | The fixes found by the inventory, one change each (section 9) | per fix | small each | per fix | a test that fails without each fix |+| 29 | One `engineHome` on the row instead of `codexHome` and `hermesHome` | `lib/registry.ts`, the wire (additive: read both, write both, then drop the old), about 30 readers | +300 / −250 | medium: persisted data | registry migration specs; e2e `migration` |++### 8.3 What step 1 is, exactly++Step 1 is the smallest change that puts the registry in the tree and proves the pattern end to end.++- `src/engines/engine.ts`: `Engine` with `name` and `transcript`; `facets/transcript.ts` with the two+ members step 1 fills, `lastTurnText` and `storedConversation`.+- `src/engines/registry.ts`: `engineFor(name)`, built from `transcripts.ts`, the table of every engine's+ transcript facet.+- `src/engines/claude/transcript.ts`: Claude Code's folder, starting with its last turn (read backward+ from the end, as `core/transcripts/lastTurn.ts` does today).+- `src/engines/<13 others>/transcript.ts`: each engine's last turn, and for OpenCode, Kilo, Hermes and+ Devin their stored conversation, each resolving its own store (the same `env` paths `cli.ts` passes+ today).+- `core/transcripts/lastTurn.ts` asks the engine; `core/transcripts/databaseHistory.ts` asks the+ engine. Neither names an engine any more.+- `src/engineNames.spec.ts` and its baseline.++One case changes on paper and not in practice: today an engine the reader does not name falls back to+Claude Code's raw-line reader. The only such engine is `terminal`, and a terminal row never has a session+id or a transcript (`registry.releaseBinding` clears both), so the reader never reaches it. After step 1+an engine without the facet has no last turn, which is the rule for every facet.++## 9. Effort and risks++### 9.1 Effort++About 17,000 lines touched across 31 steps (29 numbered; step 13 is three), of which about 3,000 are+file moves (search) and about 9,500 are code moved from shared files into engine folders. Shared code+loses roughly 8,000 lines net; the engine folders gain them.++| Phase | Steps | Agent-days | Calendar |+|---|---|---|---|+| A, the core's transcripts | 1-5 | 6 | 6 days, sequential |+| B, everything that avoids busy files | 6-20 | 19 | 6-7 days with three or four lanes at once |+| C, the busy files | 21-25 | 8 | 3 days, once those branches land |+| D, lazy loading, the absolute rule, fixes, the home rename | 26-29 | 9 | 5 days |+| **Total** | **31** | **about 42** | **about 4-5 weeks** |++An agent-day here includes the bar: the targeted e2e files from the bundle take 15-40 minutes per run,+and a high-risk step will run them more than once. The real limit is review: 31 pull requests plus the+fixes, each of which someone has to read. Phase B's lanes are what make the calendar short; run+sequentially the same work is about eight weeks.++### 9.2 What the e2e suite cannot prove++The e2e suite has fakes for Claude Code and Codex only. For the other twelve engines a move is proven+by unit tests that pin today's answers on recorded fixtures, and that has limits:++- **Discovery and hooks against real binaries.** Process signatures, the `agent` alias between Cursor+ and Grok, hook payloads and plugin behaviour are only proven by `npm run test:tmux-real` and by hand+ on a machine with the engines installed. Steps 22 and 23 should each end with that run, and with a+ turn on every installed engine (the tile goes processing, done, summary), as the engines README asks.+- **Database engines.** OpenCode, Kilo, Hermes and Devin are read through SQLite schemas the fixtures+ freeze. A schema an engine changed since its fixture was recorded passes every test. Steps 2, 4 and 15+ rely on the fixtures; a real-store opt-in spec (like `attachTranscript.real.spec.ts`) would close+ part of it.+- **Timing.** Submit windows, pane polls and footer reads are data after the moves, so a move cannot+ change them by accident, but nothing proves the values are still right for each engine's current+ release.+- **Mocks pin routing, not behaviour.** Several pinning specs mock the engine modules they route to,+ so they prove each engine is asked the same question with the same arguments, not that the answer is+ still right. Each engine's own normalizer and parser specs, replaying its recorded session, prove the+ rest.++Worth considering before Phase C: a third fake engine that replays a recorded session of any file engine+(its transcript fixture into its transcript folder, its captured pane into the pane), so attach, ingest,+history and turn lifecycle are proven end to end for the file engines too. About two to three days.++### 9.3 Risks++- **The interface is wide.** 132 members is what the code decides today. Some will turn out to be the+ same decision twice, and some engines' members will change shape as their code moves; the types in+ section 4 are the target each lane starts from, not frozen. Each lane's review should check its facet+ against what the code actually needed.+- **Attach and binding are where the races were.** Steps 4 and 14 move the code most of the e2e rounds+ fixed. They are verbatim moves for that reason, and their proof is the full set of e2e files that+ found those races, run from the bundle, more than once.+- **Import cycles.** Engine code must import only `src/engines` and leaf `lib` modules, never+ `src/core`. One cycle exists already: `engines/cursor/discovery.ts` imports `validTranscriptPath` from+ `lib/registry.ts`, and `lib/registry.ts` imports engine modules. ESM cycles fail quietly (a binding is+ undefined during evaluation), and the rule test cannot see them; step 1 adds a check that the registry+ module evaluates without a cycle, and step 24 removes the existing one.+- **A missed load point** after step 26 degrades an agent instead of failing loudly. The degraded event+ makes it visible; the step's e2e checks every load point.+- **The facet tables are temporary.** Step 26 replaces them with per-engine modules. Until then the+ registry statically imports every engine, as the daemon does today, so nothing is lost meanwhile.+- **Kept dead code.** About 485 lines of model-switch drivers for six engines are unreachable but kept+ on purpose (the owner's switching policy has changed twice, `runtimeProfileController.spec.ts`). They+ move with their engines unchanged. Whether to delete them is the owner's call, not this plan's.+- **The ratchet meets other branches.** Until the rule test is on `main`, a rebase can bring in engine+ names other changes added (#816 added two to `lib/runtimeProfileController.ts` while step 1 was+ waiting), and the rebase refreshes the baseline. Once it is on `main`, any branch in flight that adds+ an engine name to shared code fails it, which is the point; say so to whoever has branches open when+ step 1 merges, and point them at the engine's folder.+- **Wire names stay.** `codex_profiles_list`, `supportsCodexHome`, the `codexHome` field of+ `agent_create`, and the refusal code `CODEX_CLI_TOO_OLD` (sent for every engine) are part of the+ protocol the apps speak. The moves keep them; only step 29 renames anything, additively.++### 9.4 What the inventory found that is wrong today++These are fixes for step 28, each its own change with its own test, never folded into a move. The ones+marked "checked" I confirmed in the code myself; the rest come from the inventory's reading and need the+same check before they are fixed.++1. **One terminal row disables the hook script's reading of the registry** (checked).+ `hook/notify.mjs:1123` `REGISTRY_ENGINES` lists the fourteen engines and not `terminal`;+ `validV2Registry` (`:1150`) rejects the whole registry when any row fails, and terminal rows are+ written with `schemaVersion: 2`.+2. **A restart records the grid wrongly** (checked). `core/agents/restart.ts:182` passes+ `processIdentity.executable` as the `args` of `probeGridAssignment`, and Codex and pi read the grid+ from argv; `retarget.ts:236` reportedly does the same.+3. **Command Code's recap worker runs a binary that may not exist** (checked). `lib/oneshot.ts:781`+ defaults to `commandcode`; the launch command and the install recipe use `cmd`.+4. **Codex model switching is closed above 0.145** (checked). `lib/runtimeProfile.ts:269` allows exactly+ 0.144 and 0.145, and the line before it is duplicated; Claude Code's gate is open upward. Current Codex+ is 0.160, so switching is refused for it today. Opening the gate alone would not be enough: 0.160's+ picker labels its model rows differently, and the controller would refuse every model (section 9.5).+ Left as it is until the owner decides.+5. **"May this engine bind without a transcript" is answered four ways:** `registry.ts:1018` (load),+ `:1494` (register), `core/agents/bind.ts:277`, `notify.mjs:1216`. Grok, agy and Copilot may bind with+ no path at register and are unbound at the next load.+6. **"The transcript of a known session id" is answered in three places with different engines**+ (`bind.ts:264-274`, `sessionRepair.ts:566-602`, `registry.ts:1560-1572`); a pi resume binds with no+ path, and `captureResumeIdentity` finds nothing for seven engines.+7. **Devin's submit is confirmed the wrong way.** Its comment (`sessionInput.ts:30-32`) says it is+ confirmed from its store like OpenCode; the list at `:630` leaves it out, so it reads a composer whose+ marker `❭` the regex does not contain.+8. **Claude Code's readers run on other engines.** `runtimeProfile.ts:740` sends pi, Copilot, Muse, agy+ records through Claude Code's transcript reader (its `Set model to` pattern runs on their text), and+ `:1007` runs Claude Code's header patterns on Copilot, Muse and Amp panes.+9. **Instruction files are chosen in three places:** `lib/apiInstructions.ts:23` branches on `gemini`,+ which is not an engine, and ignores agy's `GEMINI.md` and Hermes's `.hermes.md` that `dsh/adapters.ts`+ knows.+10. **Codex's trust ignores its home:** `lib/claudeTrust.ts:87`, `:111` write `~/.codex/config.toml`+ whatever `CODEX_HOME` or the agent's profile says.+11. **A fork skips the relaunch overrides** (`core/agents/fork.ts`): no own-login provider for Codex, and+ OpenCode's house environment is lost on fork, resume and restore.+12. **Database knowledge exists five times and disagrees:** OpenCode's `session_v2` is purged but not+ checkpointed; Hermes's store is found three different ways.+13. **Search finds conversations that resume then refuses:** moved homes, Pi's configurable session+ folder and Codex's `archived_sessions` are searched but not accepted by `validTranscriptPath`.+14. **Defaults disagree:** `harness new` defaults to Claude Code, `DEFAULT_HARNESS_ENGINE` is OpenCode,+ and an unknown engine in a saved registry loads as Claude Code (`registry.ts:354`).+15. **Dead code** that the moves should not carry: `tmuxAgentDiscovery.ts`'s reconciler (about 320+ lines), `lib/sessions.ts` (about 125), `installedEngineBin`, `INSTALLABLE_ENGINES`,+ `readStartupProfile`, seven never-called catalog builders, the Muse hook path in `notify.mjs`, the+ unreachable OpenCode prompt marker, and `EngineAdapter` itself. Deleting them is a step-28 change+ each, before or after the move of their group, never during it.++### 9.5 Codex 0.160's model picker against what the controller types++Read from the Codex source at `rust-v0.160.0`, against `rust-v0.145.0`, the last release the gate allows+(`codex-rs/tui/src/chatwidget/model_popups.rs`, `bottom_pane/list_selection_view.rs`, the picker+snapshots in `chatwidget/snapshots/`, and `protocol/src/protocol.rs`). The controller's side is+`setCodex` and the four `parseCodex*` readers in `lib/runtimeProfileController.ts`.++| Step | What the controller relies on | 0.160 | Holds? |+|---|---|---|---|+| Open | `/model` opens "Pick a quick auto mode or browse all models" or "Select Model and Effort" | both titles unchanged | yes |+| Quick menu | rows keyed by their first slug-like token; an `All models` row | rows are now display names (`Auto Fast`); `All models` unchanged | the `All models` route only |+| Model rows | `parseCodexModelRows` keys each row by its first token and looks up the target's slug (`gpt-5.6-sol`) | rows are the catalog's display names: `GPT-6.1-Sol (default)`, `GPT-5.6 Luna (current)`; 0.145 showed slugs | **no**: every lookup misses (a name with a space does not even parse), so the switch is refused with `MODEL_UNAVAILABLE`. It fails closed: no wrong model is picked |+| Effort rows | title "Select Reasoning Level for"; `Low`, `Medium`, `High`, `Extra high`, `More reasoning…`; `(default)` | title now ends in the display name; rows unchanged; a new `Persistent` row | yes (the new row is ignored) |+| Advanced | "Advanced Reasoning"; `Max`, `Ultra` | unchanged | yes |+| Keys | a digit selects the row and accepts it | a digit still selects and accepts the primary action, which applies the choice and saves it as the default, as 0.145's did; 0.160 adds `s` for "this session only" | yes |+| Confirm | `event_msg` `thread_settings_applied` with `model`, `reasoning_effort`, `collaboration_mode` | the same fields, two added (`thread_id`, `runtime_workspace_roots`) | yes, except that a `persistent` effort is not in `CODEX_EFFORTS`, so its chip would not show |++Two more things change under the controller. The picker now shows its cached models at once and+refreshes them in place when the server answers (`AppEvent::FetchModels`), so the rows read from the pane+can be renumbered before the digit lands; the controller should re-read the pane after the refresh, or+match by name rather than by number. And an account restricted to the reserve model (`gpt-reserve`, shown+as "Luna Reserve") gets a different picker altogether.++So for 0.160 the controller has to match model rows by display name. Harness already reads each model's+`display_name` from `models_cache.json` for the picker it offers (`runtimeProfile.ts` `codexModels`), so+the fix is contained: look rows up by the target's display name, and open the gate. It is a behaviour+change and belongs after the models lane (step 10), with a captured 0.160 pane as its fixture. The e2e+fake Codex reports 0.159.0, which the gate refuses, so no e2e run exercises a Codex model switch today.++## Appendix: reproducing the counts++All counts are on `main` at `31b4a0c27`, run from `cli/`, without spec files.++- The brief's grep, and its split (section 2): the command in section 2; the 40 lines that are not engine+ behaviour are listed by kind in the table there.+- The parser counts (section 2 and the rule's baseline): `src/engineNames.spec.ts` (step 1) is the scan.+ It walks the scoped folders, parses each file with `typescript`, and counts string literals equal to an+ engine name, object keys and property reads named after an engine (`cursor`, `pi` and `amp` only inside+ an object with another engine's key), imports whose path enters `src/engines/<engine>/`, and distinct+ identifiers that start or contain a capitalised engine name or start `CODEX_`, `CLAUDE_` and so on+ (excluding `cursor`, `pi` and `amp`).+- The bundle shares (section 6.2): `build-bundle.mjs`'s esbuild settings with `metafile: true`, summing+ `bytesInOutput` per input path: 3,338,145 bytes in all, `src/engines/*` 138,924 bytes,+ `src/lib/sessionSearch/externals` 55,983 bytes.+- The inventory tables (section 3): read from the code by file, with each decision's lines; the lines+ are on `31b4a0c27` and will move.+diff --git a/docs/design/2026-10-06-core-boundary-next.md b/docs/design/2026-10-06-core-boundary-next.mdnew file mode 100644index 000000000..c9ab7fb2d--- /dev/null+++ b/docs/design/2026-10-06-core-boundary-next.md@@ -0,0 +1,610 @@+# The core boundary, next++> **Status, 2026-10-07.** Steps 1–11 have landed, except where noted. The core's closure, measured by+> `cli/src/architecture.spec.ts`, went from 114,622 lines in 488 files (walked from `cli.ts`) to 75,746+> lines in 345 files.+>+> | Step | Landed as | Note |+> |---|---|---|+> | 1 The core's own entry, and its size test | #871 | |+> | 2 Dead code | #845 | |+> | 3 Slow work off the event loop | #826 | |+> | 4 Requests into services | #851 | Left behind: the command bar (#927, #937) and the change-agent handoff (#931) |+> | 5 Several services per process, the edge host | #875 | |+> | 6 The Store into the viewers' process | #879 | |+> | 7 Models in its own process | #896 | Found: routed requests were cut off at 30 s (`LONG_ANSWERS`) |+> | 8 The experimental host, move only | #921, #924, #932, #933 | On-demand processes per experiment: orchestrator, Tab collaboration, Share |+> | 9 Devices in their own process | #918, #928, #929 | Per-device guards in one devices process; the Wi-Fi device on the gateway |+> | 10 The relay: the gateway process | #899, #905, #911 | |+> | 11 The unsupervised handoff | #895 | `harness start -f` runs the master; the updater leaves the core in #925 |+>+> What still loads in the core and isn't session machinery: the engines' own code (the engine-interface+> refactor, docs/design/2026-10-05-engine-interface.md, is paused), and the in-flight moves above. The+> core's process still parses all of cli.js, so its memory falls only with a lean core bundle (in+> progress).+++A plan, not a change. It takes stock of everything that still runs in the core's process and is not+session handling, decides where each piece goes, and orders the moves so that each lands green on its+own. The design it continues is [2026-10-03-harnessd.md](2026-10-03-harnessd.md); what changed+since the last release is in [2026-10-04-harnessd-before-after.md](2026-10-04-harnessd-before-after.md).+Paths are under `cli/src/`; line numbers are from `main` at 3ac2aea57.++The owner's direction, verbatim: "the goal is to build a stable, safe, reliable daemon core.+everything else lives outside of the daemon as subsystems/services. stable at core. extendible at the+edges via subsystems." The core owns sessions only: agents, terminals, transcripts, turns, input and+questions ([../../cli/AGENTS.md](../../cli/AGENTS.md)).++## In short++- **The core's process loads 111,892 lines in 472 files today.** Files that are session handling and+ its plumbing come to about 66,700 of them, and about 6,000 inside those (the CLI's commands in+ `cli.ts`, the relay half of the socket, feature wiring) leave too. The rest is a dozen other areas,+ the biggest being the devices (9,800), the relay and E2EE (7,350), the models (6,400) and the CLI's+ own commands (6,200, there only because `cli.ts` is both the CLI and the daemon).+- **Target: at most 61,000 lines in the core's import closure,** about 45% smaller, with no file from+ any service's folder in it. It is enforced by a test that walks the imports as this count did, with+ a budget lowered at every step.+- **Seven service processes at the end,** two of them on demand: relay, devices, models, search,+ viewers with the Store, an edge host for the light services, and an experimental host that starts+ only when an experimental feature is used. At about 50 MiB each after the lean work, that is+ about 250 MiB always on and 350 MiB at most.+- **First, five steps that move nothing risky:** give the core an entry of its own and the test that+ measures it; delete what is dead; take the slow work off the core's event loop; move the request+ handlers that only answer the apps out of the socket's switch; and let one process host several light+ services. The relay, the largest and most coupled move, comes last.+- **Defects found on the way,** some to fix before anything moves: a 15 s synchronous canary and a+ 120 s synchronous `tar` on the core's event loop, the orchestrator built on every daemon at its first+ turn end, device code unguarded on the per-transcript-line path, and a reconcile pass with no+ deadline (see [Found on the way](#found-on-the-way)).++## How it was measured++The core is what `harness __run` loads: `cli.ts`, whose `runForeground` (lines 1576–4152, 2,577+lines) is the composition root, and everything it imports. The count follows every static and+dynamic `import` under `cli/src`, leaves out `import type` (types cost nothing at run time) and test+files, and puts each file in one area by what it is for. The walk is the one the proposed test makes+([The target, and its test](#the-target-and-its-test)).++Three caveats keep the numbers honest:++- **`cli.ts` is also the CLI.** About 3,160 of its 5,739 lines are commands (`harness login`, `grid+ setup`, `link`, …) that `__run` loads and never calls. Their imports, with the master's and the+ services' own entries, add 6,214 lines in 37 files that the core's process never runs.+- **A file can be two things.** `backendSocket.ts` (2,353) is the local client hub and request+ dispatch, which are core, and the upstream relay link, about 1,000 lines, which is not.+ `hookServer.ts` (938) binds sessions in about 430 lines and serves other routes in about 340.+ Such files are counted where most of them belong, and split in the text.+- **One bundle.** A service in its own process loads the same bundle today. Leaving the core's+ closure is what makes a separate entry per process possible; until then, moving code out changes+ what the core runs, not what it loads.++The four inventories behind this plan read every call site; their evidence is cited inline as+`file:line`.++## The core today, by area++| Area | Lines | Files | Where it goes |+| --- | ---: | ---: | --- |+| Sessions: agents, terminals, transcripts, turns, input, questions, and their plumbing | 66,700 | 262 | stays (less about 6,000 lines inside mixed files) |+| Relay and E2EE (backend link, pairing, trust group, device log, P2P terminals, remote relay pool) | 7,350 | 21 | relay process |+| Devices (USB dial, Wi-Fi device, firmware push, voice router) | 9,800 | 40 | devices process |+| Models (Grid, local models, API connections, Codex profiles, the managed Grid pin) | 6,400 | 26 | models process |+| The CLI's own commands, and the master's and services' entries | 6,200 | 37 | leaves the core's entry |+| Session search, the index half | 2,200 | 7 | search process (done) |+| Light features (account usage, machine monitor, command bar, "Change agent" handoff) | 3,000 | 15 | edge host |+| Teams (Tab collaboration) and the orchestrator | 2,200 | 16 | experimental host |+| Sharing (Share) | 780 | 7 | experimental host |+| Workspaces, git context and previews | 1,750 | 13 | edge host |+| Fleet (the machine list, the lane to other machines, the router) | 1,800 | 4 | devices process, with its main caller |+| Store installs | 1,440 | 11 | viewers process |+| Viewers and verdicts | 1,290 | 8 | viewers process (done) |+| Updaters (the CLI's, hn's) | 660 | 4 | stay for now; later one updater service under the master |+| The web dashboard (`webui.ts`) | 270 | 1 | delete, if unused (below) |++"Sessions" holds more than the six areas' own folders, by decision: the engines' adapters and+normalizers (10,241), the launch builders (Grid's environment and argv, the DSH workspace and snapshot,+API launches: about 3,840), the runtime profiles (each agent's model and effort, 3,090), the commander+mirror (each turn's recap and asks, 1,022), discovery and restore (2,860), the hook routes and hook+install, and the readers of other engines' sessions that adoption uses (3,635, half of+`lib/sessionSearch`). Each is argued below.++## Inventory++For each area: what the core calls it for, what it needs from the core, what a person notices if it+dies, and the decision. "Hot" means per transcript line, per turn event, per keystroke or terminal+byte, or per frame sent to the apps; everything else is per request, per timer or at start.++### Relay and E2EE — its own process (the "gateway")++- **Lines.** `lib/e2ee/*` (4,647, less `deviceDisplay.ts`, a CLI command), `lib/remoteRelay.ts` (1,249),+ `lib/terminalP2p.ts` (806), `lib/stunSelect.ts` (338), `lib/wsLiveness.ts`, `lib/remoteViewerProxy.ts`+ (285), `lib/viewerForwarder.ts`, `lib/ownerCommands.ts`, and about 1,000 lines of `backendSocket.ts`:+ the constructor, connect and backoff (827–969), the outbound queue (992–1163, 1223–1241,+ 1363–1428), P2P routing (1243–1319), reply sealing (1430–1482) and the gates and backend control+ frames in `dispatchDown` (1504–1712).+- **The core calls it, hot and synchronous.** Every event the funnel sends is sealed in pure JS on+ the core's thread (`funnel.ts:128` → `send` → `e2ee.wrapUp`, `backendSocket.ts:1001`), as is every+ terminal frame of a remote connection (`:1062–1101`, `:1369`) and every remote request and reply.+ Occasional: `relayPool.acquire` on `machine_select` (`localWsServer.ts:428–450`), pairing over the+ hook server's HTTP (`cli.ts:2688–2758`), the trust group and the device log every 10 minutes+ (`cli.ts:3000–3012`), and `connect()` at start when signed in (`cli.ts:3710`).+- **It needs from the core.** None of it goes through `CoreApi`: it uses `BackendSocket`'s members+ directly: the local clients and `sendLocal` for device-key notices (`cli.ts:2964–2986`),+ `terminalStreams.closeConnection` on link loss, and three callbacks (`onRevoked`, `onMachineMeta`,+ `onCommanderJoin`). Each connection's session role decides `Asker.owner`.+- **If it dies.** The phone, the web, other desktops, Share observers and the Wi-Fi device lose this+ machine; local windows and agents should not. Today it runs inside the core, so a throw in+ `wrapUp` aborts the funnel's batch for everyone (the funnel's `outside()` guard does not cover+ `clients.send`), and werift's pure-JS WebRTC stack and the crypto run on the core's event loop.+ Signed out, the daemon never dials (`cli.ts:3709`), yet seals and queues every event up to 2,000 and+ then drops them (`backendSocket.ts:124`, `:1223`).+- **Decision: its own process,** the gateway. It holds the upstream connection, the E2EE manager and+ its stores, pairing, the trust group and device log, P2P with STUN, the remote relay pool with the+ viewer proxy, and the Share relay transport. The core speaks plaintext to it over the local socket,+ and each remote client becomes a connection the gateway registers with the asker stamped. What the+ move must handle:+ - one more local hop on the remote hot paths (events, terminal bytes), and none for local windows;+ - the synchronous reads the core makes (commander counts, each connection's role and label, the+ Grid name, the machine's name) answered from what the gateway reports, the viewers' pattern;+ - the backend's control frames (`machine_revoked`, `machine_meta`, desk, machines and device-key+ changes, a client gone) becoming typed events the core accepts only on the master-tokened link;+ - the local socket handing a window's connection to another machine over to the gateway+ (`localWsServer.ts:428`).+- **Account and cloud proxies go with it, or to the edge host.** `proxyBackend` (`cli.ts:2496–2533`,+ 20 callers), the machine-list cache (`cli.ts:2589–2635`) and Grid-name minting are async, already+ time-limited and need nothing from the core but the session token.+- **What looks like cloud sync and is not.** The commander mirror (`lib/commander.ts`, each turn's+ recap, asks and busy state, which heartbeats, cancel, fork and `CoreApi.turns` read; hot, every event+ batch, `funnel.ts:168`), `sessionSync.ts` (agent frames), `machineNames.ts`, `computerIdentity.ts`+ and `agentNotifications.ts` are turn and agent state. They stay. Only `commanderReplay.ts` and+ `deviceRecentTrim.ts`, which shape what goes up the link, leave with the gateway.++### Devices — its own process++- **Lines.** `cable/*` (5,561), `device/machineList.ts` (294), `lib/autonomous-device/*` less the pane+ writer lock (1,960), `lib/harnessDevices.ts`, `lib/deviceRecap.ts`, and the voice router+ (`lib/voiceRouter.ts` 492 with `lib/oneshot.ts` 1,034 and `lib/disposableOneShotPool.ts` 318,+ which nothing else uses). `devices/client.ts` and `lib/flash.ts` are CLI commands.+- **The core calls it, hot.** Every transcript line, synchronously and unguarded+ (`core/transcripts/ingest.ts:58–61`, `attach.ts:161`); every pane write (`core/input.ts:62, 120`);+ every card for the Wi-Fi device, teed to the dial, heartbeats included+ (`backendSocket.ts:1134` → `cli.ts:4084–4114`); presence reads on every mirror card+ (`cli.ts:1999–2003`). In the background, an `ioreg` spawn every 2 s with nothing plugged in; with a+ dial, an agent sync every second and a pane capture every 3 s. The voice router is fed on every+ bind and forget, keeps a warm engine process while a device is connected+ (`setVoiceRouterDeviceConnected`, `cli.ts:3481`) and answers `voice_route` on the asking+ connection's ordered chain for up to about 12 s (`backendSocket.ts:2002`).+- **It needs from the core.** The dial already reaches the fleet's router through `ports.fleet` and+ the core through `CoreApi`, but also bypasses both: the registry (`cableHost.ts:22`), an+ `AuthSessionManager` of its own (`cableHost.ts:95–120`, a credential) and `backend.sendLocal` for+ the `dial_*` frames. The Wi-Fi device uses closures (`cli.ts:4027–4057`), the core's E2EE manager+ and the hook server's pairing routes.+- **If it dies.** The dial and the Wi-Fi device stop; nothing else should. Runtime faults are+ contained (serial reopen, the `devices()` guard), but a corrupt state file makes the Wi-Fi device's+ constructors throw, unguarded (`direct.ts:37–40`, `cli.ts:4027, 4060`), and that puts the whole core+ into safe mode. A native crash in the serial code costs every session.+- **Decision: its own process,** the singleton owner of the serial ports (`O_EXLOCK` already makes the+ port single-owner, `serial.ts:166`). This is D1's remainder and D2 in the harnessd design, sized there+ at about fifteen calls from the core and twenty-five back. The pane writer lock+ (`lib/autonomous-device/input.ts`, 310) and the card text (`deviceErrors.ts`) are the core's and+ move into `core/input.ts` first. The fleet's router moves into this process too: its synchronous+ readers (`machineOf`, `knows`, `describe`, `cableHost.ts:414–578`) are the dial's, and ⌘K's calls+ are already asynchronous. The Wi-Fi device stays in the core's process behind `serviceHost` until+ the gateway exists, since it rides the E2EE sessions, then joins this process. The voice router comes+ here because its workers are engine processes and its callers are the dial and the fleet.++### Models — its own process++- **Lines.** The Grid service code (`gridAttach`, `gridCredentials`, `gridDerive`, `gridEnsure`,+ `gridExec`, `gridFleetRpc`, `gridHandoff`, `gridInstall`, `gridMcpUrl`, `gridModels` 793,+ `gridModelsPayload`, `gridPicture`, `gridPresence`, `gridReader`, `gridTarget`, `gridWake`: 3,333),+ `localModels.ts` (1,199), `appModels`, `newAgentModel`, the API connections (`apiConnections`,+ `apiModels`, `apiInstructions`), the Codex profiles (519) and `runtimeInstall.ts` (351, the managed+ Grid pin), with `services/models.ts` (316).+- **What stays in the core, and why.** The launch builders (`gridLaunch` 1,121, `gridConfigDir`,+ `gridWebMcp`, `harnessWebTools`, `launchOverrides`, `subscriptionModel`), the process probes+ (`gridAssignment`, `gatewayRuntime`) and `core/agents/retarget.ts`. Create, restart, restore and+ retarget build an engine's command line from them, and restart and restore need no service at all:+ the registry row keeps `gridLaunch` (the credential included), `gridWebSearch`,+ `subscriptionModel`, `codexHome` and the DSH snapshot. The runtime profiles stay too+ (`runtimeProfile` 1,786, `runtimeProfileController` 1,304): they read the model and effort from+ every transcript line (`ingest.ts:62`) and pane footer, and type `/model` into the pane.+- **The core calls it.** Hot: the keystroke prewarm (`cli.ts:2022–2028`, guarded and debounced) and+ `gridAnnotation()` on every agent frame, read straight off the module's singleton+ (`agentFrame.ts:232`, unguarded). Per discovery pass: the cached probes. Per create: the model target+ (`launches.ts:243, 304`), `ensureGrid` for the Model Manager (`create.ts:156–162`). Per request, in+ the socket's own switch, against rule 1 of `cli/AGENTS.md`: `api_connections`, `codex_profiles_*`,+ `grid_fleet_*` and `agent_retarget`'s target resolution. Every 10 minutes: the Grid pin.+- **It needs from the core.** `core.account` and two client pushes, through `CoreApi` already. But+ its state is a module singleton the socket, `agentFrame.ts` and `launches.ts` read in process,+ bypassing `ports.models`.+- **If it dies.** Model pictures and the Model Manager go; agents keep working on what they were+ launched with. A throw is contained by the service host; a hang is not, and there is one:+ `ensureManagedGrid` runs `tar` (up to 120 s) and `grid --version` (up to 60 s) synchronously on the+ core's event loop (`runtimeInstall.ts:52–54, 135`) whenever the pin moves, freezing every terminal+ for that long.+- **Decision: its own process,** after every direct read goes through the port: the annotation pushed+ by the service and cached in the core, the target resolution asynchronous with a `FAIL` fallback,+ the prewarm sent only when the cached annotation says the machine is asleep (so no keystroke crosses+ a process), and the Model Manager's run requests given a connection-closed notice. The API and+ Codex-profile requests move into it as declared requests. The core keeps reading `apis` and+ `codexHome` from their files and the row at relaunch, so a restart never waits on models.++### Session search — done, and the half that is not search++`services/search.ts` runs in its own process with `HARNESSD_SERVICES` (default on the+`services-default` branch). Only its index half (about 2,200 lines) is search. The readers of other+engines' stored sessions (`lib/sessionSearch/external.ts` and `externals/*`, 3,635 lines) are used by+the core itself: adoption (`cli.ts:1817`, `core/agents/adopt.ts:41–106`), create+(`stopSessionOwner`, `create.ts:38`) and repair (`sessionRepair.ts:29`). **Decision:** the readers+become a library beside the engines' adapters, which both the core and search import; nothing else+moves. In the core's process today, search's `node:sqlite` queries run on the core's thread, and a+native crash there costs every session: the reason to make its own process the default.++### Store and DSH — the Store to the viewers' process; the launch path stays++- **Three parts.** The launch path (`installed`, `manifest`, `launch`, `runtime`, `adapters`,+ `compatibility`, `materialize`, `probe`, `shell`: 1,024) is how create, relaunch and fork prepare a+ harness agent's workspace and snapshot; it stays, as a file contract the core reads. The Store+ (`catalog`, `install`, `update`, `updates`, `registry`, `wire`, `service`, `lock`, `builtins`: 1,501,+ with `services/store.ts` and `storeProxy.ts`) installs and updates harnesses. The viewers+ (`viewer`, `viewerLedger`, `verdict`, `artifacts`: 741) already run in their own process.+- **Decision.** The Store joins the viewers' process: it has no port, its installs take minutes, and+ installs are already locked across processes (`dsh/lock.ts`). It needs a service-to-core kind for+ the install status push, `ensureBundledCoreHarnesses` moved into its start, and the Wi-Fi device's+ bypass (`autonomous-device/storeRuntime.ts:12`) routed through it. The viewer forwarder and the+ interactive viewers (headless Chrome) follow the viewers once relay frames can reach them.++### Teams (Tab collaboration) and the orchestrator — the experimental host++- **Lines.** `teams/*` (1,705 less the CLI commands), the team half of `backendSocket.ts` (345–430,+ 1728–1753), `cli.ts:3683–3695`, `core/teamsLink.ts`, `services/teamsProcess.ts`; `orchestrator/*`+ (746) and its construction inside the socket (`backendSocket.ts:435–577`).+- **The core calls teams, hot.** The prompt scopes see every keystroke for every agent, whether or not+ Tab collaboration is on (`terminalStreamManager.ts:651, 726`), every message written+ (`sessionInput.ts:448, 514`) and every turn start (`funnel.ts:134`); they already run in their own+ process with `HARNESSD_SERVICES=teams`. But the rest of teams (`TeamService`, the mailbox, the+ channel directory) runs in the core and polls the backend's tab channels every 15 s on every daemon+ (`channels.ts:42–50`).+- **The core calls the orchestrator, hot, and it should not exist yet.** `send()` feeds it every frame+ sent to the apps, `text_delta` included (`backendSocket.ts:994–996`), "only once open". But+ `isSubagentSession` asks its `roleOf` at every turn end (`core/turns/recaps.ts:63–68`), and `roleOf`+ constructs the service (`backendSocket.ts:432–435`): a `mkdirSync`, a directory read and a+ synchronous parse of every saved run, on every daemon, after its first turn. If that load throws,+ it throws out of `send()` and out of the funnel, and the apps stop receiving frames.+- **Decision: move only, to one experimental host.** Teams' service, mailbox and channels join the+ prompt scopes; the orchestrator gets a port (`roleOf` answered from a cache the service reports,+ never by building it; frames filtered in the core to director agents and four event types). Both+ need one new `CoreApi` member they share with the device: send a turn with a delivery id, hear its+ delivery, cancel it. `serviceRouter` runs after the socket's early `team`, `orchestrator` and `pair`+ branches (`backendSocket.ts:1728, 1775, 1786, 1835`): each move deletes its early branch.++### Sharing (Share) — the experimental host++`sharing/*` (776) is built on every daemon (`cli.ts:2539–2560`), with a 1 s authorization timer and a+30 s publish, though Share is off by default in the app. It reads panes through a second+`TerminalStreamManager` of its own (`owner.ts:39–46`), seals every byte for every observer, and spawns+headless Chrome for shared viewers (`viewer.ts:38–60`). **Decision, move only:** first behind+`serviceHost`, then in the experimental host, once `CoreApi` has a read-only terminal subscription,+with observers arriving through the gateway. The Chrome capture belongs with the viewers. Its timers+then run only while the experimental host does.++### Workspaces, git context and previews — the edge host++The service already runs in its own process (`HARNESSD_SERVICES=workspaces`). Five requests still live+in the socket: `git_pull_request`, `git_project_info`, `project_preview` (detached), `fs_list_dir`+(synchronous `readdirSync`, `backendSocket.ts:2188`) and `agent_read_file` (awaited on the request+chain, `:2220`). They move into the service, which needs a `CoreApi` lookup by agent or session id+and the work ledger. The git context on every agent frame (`agentFrame.ts:186–197`: the project, the+branch history, up to eight git lookups, cached) stays in the core, or becomes a reported cache.+`projectFolder`, `openFiles`, `projectFiles` and `worktreeDeletion` are launch and purge code: core.++### Light features — the edge host++- **Account usage** (`usage_read`, `accountUsage.ts`): per request, detached, reads the vendor+ Keychain through `security` (`accountUsage.ts:161–175`). A service with no port; first decide+ whether reading the Keychain is "holding a credential".+- **The machine monitor** (`harnessResources`, `machineHardware`, `machineResources`,+ `macosProcessGpu`, `harnessTelemetry`: 716): `machine_resources` and the `monitor` part of+ `agents_list` spawn `ps`, `nvidia-smi` and `ioreg`, and parse up to 8 MB of `ioreg` output on the+ core's thread at every Monitor poll (`macosProcessGpu.ts:97`). A service, with a port and an empty+ fallback for the list's merge.+- **The command bar** (`commandBar`, `commandBarHttp`: 287) answers `/api/command-bar/*` on the hook+ server and `command_bar` on the socket; it reads its own OpenRouter key. A service with no port; the+ HTTP route forwards to it.+- **"Change agent" handoff** (`agentHandoff` 952, `handoffDiscovery`, `core/agents/handoff.ts`): writes+ a handoff file for another engine; detached, bounded to 5 s. A service for `agent_handoff_prepare`,+ with `CoreApi` additions (stopped agents, recaps by session).+- **Token usage, titles and output stats stay:** they are built from transcripts and read on every+ agent frame.++### The hook server — the session routes stay, the rest leaves++- **Session routes stay** (about 430 lines): `session-start` (SessionStart and UserPromptSubmit),+ `turn-stop`, `turn-start`, `tool-start`, `session-end`. They bind sessions, answer inside the+ engine's 500 ms budget and touch the registry. `lib/hooks.ts` (1,193, which installs the engines'+ hooks and holds their plugin sources) and `core/engines/hooks.ts` stay: create installs Codex's+ hooks synchronously (`create.ts:231`).+- **The server stays as transport.** It is the core's control port: the local WebSocket for the+ desktop and hn is attached to it (`cli.ts:3051`), as are `/api/status` and the safe-mode status.+- **The other routes leave** (about 340 lines, with their bodies at `cli.ts:2658–2856`): the command+ bar, the backend proxies (machines, `auth/me`, the auth handoff, shares, the desk, experimental+ settings, the Store), and pairing and the trust group. They move through one adapter in the hook+ server that turns an HTTP route into a service request, keeping the URLs the CLI and the desktop+ use. Pairing waits for the E2EE manager to leave `BackendSocket`.++### The local WebSocket server (the desktop and hn) — stays, less about 400 lines++`localWsServer.ts` (781), `terminalStreamManager.ts` (1,374), `tmuxStream.ts` (821) and+`terminalBinary.ts` (317) stream panes to the desktop and hn: every keystroke goes from the socket to+tmux, and every output byte is compressed on the core's thread (`terminalStreamManager.ts:192`). That+is terminals, and stays. About 400 lines of `localWsServer.ts` are not: the dial and app callbacks,+⌘K and the voice route, the remote relay pool and the Share relay. They become events on ports.+`lib/ownerCommands.ts` mixes the command bar with the fleet's `route_task` and `route_send` and is a+`BackendSocket` slot, against rule 2: the command bar goes to the edge host, the routing to the fleet.+The retired `daemon_*` frames are refused there (`localWsServer.ts:19–21, 650–681`) and stay until no+app sends them.++### Discovery and reconcile — stays, with a deadline++`terminalAgentReconciler.ts`, `tmuxAgentDiscovery.ts`, `terminalAgentDiscovery.ts`,+`core/agents/discovery.ts`, `core/agents/adopt.ts`, `sessionRepair.ts`, `restoreAgents.ts` (2,860):+they decide which agents exist and are alive, which is session handling. Two things to fix in place:+a pass has no deadline (`reconcileOnce`), so a stuck one blocks every hook (each awaits+`triggerHint`, `core/engines/hooks.ts:117`) and holds a registry transaction open so nothing saves;+and about 285 lines of `tmuxAgentDiscovery.ts` (212–497) are reached only from tests.++### Updaters — stay for now; the unsupervised handoff goes++The CLI's self-update (`selfUpdate.ts`, 485) and hn's (`tui/update.ts`, `install.ts`) tick every+60 s. The CLI's runs its canary with `spawnSync`, up to 15 s, on the core's event loop+(`selfUpdate.ts:192`): terminal bytes, hooks and heartbeats stop meanwhile. Under the master a core+staging an update just exits 75 and the master does the rest (`supervisor.ts:147, 418`), so the+spawn, supervise and roll-back handoff in `runForeground` (about 180 lines) runs only unsupervised+(`harness start -f`, `HARNESS_NO_MASTER=1`). **Decision:** make the canary asynchronous now; make+`-f` run the master in the foreground, as launchd does, and delete the handoff; later, one updater+for the CLI and hn under the master's supervision, so that safe mode is "no core started" rather than+"a broken core runs its updater". The master's no-network rule means the updater is a service, not+the master.++### Companions and Coding memory — already out; the refusals stay until no app sends them++Since #684 they are a package (`companions/`) that nothing starts. What remains in the daemon is the+refusal of their requests: `pair` and `PLATE_REQUEST` (`backendSocket.ts:1786–1791`),+`daemon_plate_get` (`localWsServer.ts:650–658`), the `pair` frame types and `admitRelayedPairFrame`+in `lib/e2ee/applicationFrames.ts:23–42, 62, 100`, and `'builtin:pair'` in `isHiddenBuiltin`+(`dsh/builtins.ts:61`). The desktop still sends `pair` (verb `memory`) and `daemon_plate_get`, so the+refusals stay until it does not.++### The Devices tab — moves with the dial++`harness_devices_list` and `harness_device_settings` (`backendSocket.ts:2289–2299`, through+`lib/harnessDevices.ts`), the `dialStatus` push and the bundled Devices harness+(`ensureBundledDevices`, `cli.ts:1954`). Nothing hot. They go with whoever owns the cable; the bundled+install goes to the Store.++### The web dashboard — delete if unused++`webui.ts` (269) serves `GET /`. Its port is sent to the web (`e2ee/manager.ts:487`), but no app,+website or backend reads it. Confirm, then delete.++### What stays, and why++| In the core | Why it cannot leave |+| --- | --- |+| Registry, stopped agents, create, fork, restart, retarget, resume, stop, close, purge | The agent lifecycle is session handling |+| tmux backend, terminal streams to the desktop and hn (`terminalStreamManager`, `tmuxStream`, `terminalBinary`, `localWsServer`) | Every keystroke and output byte; a process hop would add latency to typing |+| Engine adapters and normalizers (10,241) | Transcripts |+| Attach, ingest, history, the watcher | Transcripts |+| Activity, funnel, heartbeats, cancel, recap excerpts, the commander mirror | Turns: each turn's last answer and asks, which heartbeats, cancel, fork and notifications read |+| Runtime profiles | The agent's model and effort, read from every transcript line and pane footer |+| Input and its pane writer lock, questions | Input and questions |+| Discovery, reconcile, restore after reboot | Decide which agents exist |+| The hook session routes and hook install | Bind sessions; create installs hooks |+| Launch builders: Grid environment and argv, DSH launch path, API launches, Codex homes | Restart and restore must work with every service down |+| The local socket, the request gate, `serviceHost`, `serviceLinks`, each service's link | Transport and the boundary itself |++## The target shape++| Process | Holds | Why its own | Started |+| --- | --- | --- | --- |+| **core** | Sessions, as above | Must never go down | always |+| **relay** (the gateway) | Backend link, E2EE, pairing, trust group, device log, P2P, remote relay pool, viewer proxy; account proxies | Network, crypto and WebRTC in pure JS; the attack surface | always (signed in) |+| **devices** | USB dial, Wi-Fi device, firmware push, voice router, the fleet's router and lane, Devices tab requests | Native serial code; one owner per port; spawns engine workers | on demand (below) |+| **models** | Grid, local models, API connections, Codex profiles, the Grid pin | Downloads, model servers, long installs | always |+| **search** | Session index | `node:sqlite`, memory | always (done) |+| **viewers** | Viewer servers, verdicts, Store installs; later headless Chrome | Spawns servers and Chrome; minutes-long installs | always (done) |+| **edge host** | Workspaces, account usage, machine monitor, command bar, handoff | Light, pure JS, request-only: isolated from the core, not from each other | always |+| **experimental host** | Teams and Tab collaboration, the orchestrator, Share, and Companions and Coding memory when they return | Experimental code never shares a process with stable code | on demand (below) |++**Grouping, and what isolation it keeps.** A process per risk, not per feature. Native crashes+(serial, `sqlite`), memory (the index, model downloads), child-process herds (viewer servers, Chrome,+engine workers) and the network each get their own process, because each is a way one feature can+take another down. The edge host's services are pure JavaScript answering requests: a fault in one+can cost the others in its host, never the core, and the master restarts the host. The experimental+host keeps experiments away from both. That needs one new capability, a process hosting several+services (`harness __service workspaces,usage,monitor,…`), which `services/process.ts` and+`harnessd/services.ts` grow in step 5.++**Memory.** About 50 MiB per process after the lean work (the harnessd design measured 40 MiB for an+idle Node and up to 125 MiB for one that loads today's whole bundle). Today, with the+`services-default` branch, the core runs four: search, viewers, workspaces and teams, about 200 MiB.+The target is five always on (relay, models, search, viewers, edge host: about 250 MiB) and two on+demand: devices (about 50 MiB more for someone with a dial or a Wi-Fi device) and the experimental+host (about 50 MiB more for someone using an experiment). Merging workspaces into the edge host and+teams into the experimental host is what keeps the always-on count at five.++**On demand.** The master starts a service only when it has work: the devices when a dial is plugged+in or a Wi-Fi device is paired, the experimental host when the account turns an experiment on or an+app sends one of its requests. Today the dial's USB watch is itself the devices' code (an `ioreg`+spawn every 2 s); the cheap watch would run in the edge host and ask the master to start the devices.+This is a decision for the owner (below); without it, both run always, at 350 MiB in all.++## The order++Each step is one pull request that keeps every client working, with its end-to-end proof, and lowers+the core's budget in the size test. The first five move nothing risky.++1. **The core's own entry, and the test that measures it.** `runForeground` and the helpers only it+ uses move verbatim from `cli.ts` into `src/core/main.ts`; `cli.ts` keeps the commands and calls it+ for `__run`. The master's and services' entries leave the core's closure the same way. Then the+ size test (below) starts with the budget at the new number, about 103,000 lines, and the list of+ today's exceptions to the edge-folder rule. No behaviour changes; the unit and e2e suites prove it.+ (Moving code into a service in the core's process, as step 4 does, changes no number: the closure+ shrinks only when a service runs in its own process and the core stops importing it, step 5 on.)+2. **Delete what is dead.** `tmuxAgentDiscovery.ts:212–497` and `adoptVerified` (reached only from+ tests), `readStartupProfile` (`runtimeProfile.ts:626`), the spec-only exports in `gatewayRuntime`,+ `gridAssignment`, `apiModels`, `subscriptionModel` and `dsh/*`, the herdr hints the hook server still+ accepts (`hookServer.ts:212`), the `voice_route` case if the backend's legacy `deviceWs.ts:1379` is+ its only sender (the gate already refuses it unsealed), `speaking` if nothing sends it, and the+ comments that describe deleted code. About 600 lines.+3. **Take slow work off the core's event loop.** Each is a defect in a stable core, fixed in place:+ the canary asynchronous (`selfUpdate.ts:192`); `ensureManagedGrid` asynchronous+ (`runtimeInstall.ts:54, 135`); `viewerLedger`'s `ps` asynchronous; the `ioreg` parse off the+ request path; `orchestratorRoleOf` answering "no role" without building the service; the device's+ `observeTranscript` and the runtime profiles' `ingest` guarded on the per-line path; the Wi-Fi+ device's constructors guarded; a deadline on each reconcile pass and on a hook's wait for one;+ signed out, no sealing and no queue. Each with a test that fails without it. Experimental features+ are left as they are (move only): their always-on timers leave with them in step 8.+4. **Requests out of the socket's switch, into services in the core's process.** `usage_read`,+ `machine_resources` and the list's monitor merge, the command bar (both doors), `agent_handoff_prepare`,+ `api_connections` and `codex_profiles_*` (into models), and the five workspace requests. Each is a+ declared request of its service (`services/AGENTS.md`), so the switch shrinks and nothing about+ processes changes. About 1,500 lines leave `backendSocket.ts` and `runForeground`.+5. **One process, several services.** The master starts `harness __service <a>,<b>` and+ `services/process.ts` hosts each on its own core link and token, with the heartbeat and memory+ budget per process. The in-process start paths move into `services/inline.ts`, loaded only with+ `HARNESSD_SERVICES=none`, so a service that runs in its own process by default (search and the+ viewers already) leaves the core's closure. Then the edge host: workspaces, usage, monitor, command+ bar and handoff, proven by `e2e/serviceProcesses.e2e.ts`'s kill, hang, leak and crash loop against+ the host.+6. **The Store into the viewers' process,** with the install-status push and the bundled installs.+7. **Models in its own process.** First every direct read of the `gridModels` singleton through the+ port (the annotation cache, the asynchronous target, the prewarm gated on "asleep", the push+ payloads), then `models` in `KNOWN_SERVICES`. Proven with the Model Manager and a create on a grid+ while models is killed: the create answers `GRID_UNAVAILABLE` and every running agent works on.+8. **The experimental host, move only.** Teams' service, mailbox and channels beside the prompt scopes;+ the orchestrator with its port; Share behind `serviceHost`, started when on. The shared `CoreApi`+ member for delivered turns lands first, in its own change. No feature changes; the teams and+ orchestrator e2e files pass as they are.+9. **Devices in their own process** (D1's remainder, then D2): the pane lock and card text into the+ core first; the card tee as a stream with questions replayed on connect; presence cached in the+ core; `clients.sendToWindow` in `CoreApi`; the fleet's router beside the dial; the voice router.+ Proven with the fake dial on a pseudo-terminal and the two-machine fleet from D0.+10. **The relay, in three steps.** R1: the upstream link out of `BackendSocket` behind an interface,+ and the E2EE manager out of it, still in process; sealing guarded. R2: the gateway process, with+ remote clients registered through it, the cached reads and the control-frame events. R3: the+ Wi-Fi device into the devices process over the gateway, Share's observers through it, and the+ fleet's lane signed and sealed through `core.account` and the gateway instead of the credential+ it holds today (`services/fleet.ts:39–62`). Proven with the fake backend and the two-machine+ fleet (`e2e/harness/fakeBackend.ts`, `e2e/fleet.e2e.ts`).+11. **The unsupervised handoff goes**, and with it about 180 lines of `runForeground`, once `-f`+ runs the master in the foreground.++What the budget should read after each step, roughly: 103,000 after step 1, 102,000 after steps 2+to 4, 93,000 after step 5, 92,000 after step 6, 85,000 after step 7, 82,000 after step 8, 71,000+after step 9, 62,000 after step 10, and 61,000 at the end.++## Experimental features: move only++Settings → Experimental lists the Focus-bar creature, the Share button and the Devices tab (account+experiments), Coding memory (local to the computer) and Tab collaboration. None of them is worked on+here: each moves with its code as it is, and its existing tests pass unchanged. Their timers that run+on every daemon today (Share's, the tab-channel poll) move with them; on demand, the experimental host+is what makes them cost nothing for someone who does not use an experiment.++| Experiment | In the daemon today | The move |+| --- | --- | --- |+| Focus-bar creature (Companions) | Refusals only: `pair`, `daemon_plate_get`, frame types in `applicationFrames.ts` | Nothing to move. When Companions returns, it is a service in the experimental host that declares `pair`, `pair_*` and `daemon_plate_get`, and the core deletes its refusals (`daemon_plate_get` is intercepted in `localWsServer.ts` before routing, so it needs routing too) |+| Coding memory | The `pair` refusal (verb `memory`) | As Companions; Memory never depends on Companions |+| Share | `sharing/*`, built on every daemon, with its timers | Behind `serviceHost`, then the experimental host as it is (step 8); observers through the gateway (step 10) |+| Tab collaboration (teams) | Prompt scopes (own process possible), team service, mailbox, channel poll, team branches in the socket | The rest of teams joins the prompt scopes in the experimental host (step 8); the early `team` branch in the socket goes |+| Devices tab | Two requests, the status push, the bundled harness | With the dial (step 9); the bundled install with the Store (step 6) |++Two things are not features and still need care: every keystroke goes to the prompt scopes whether or+not Tab collaboration is on, and the Wi-Fi device and the orchestrator share one delivery path with+teams. A pure move keeps the keystrokes flowing (batched across the process, never gated: gating is+a feature change) and lands the delivery member once for all three.++## The target, and its test++**The core's import closure is at most 61,000 lines, with no file from a service's folder in it.**+Today it is 111,892. The test belongs in `src/architecture.spec.ts` beside the existing walls:++- It walks the imports from `src/core/main.ts` (step 1) exactly as this plan's count did: every+ static and dynamic `import` under `src`, without `import type` or tests. That is the code the core's+ process runs. The one edge it does not follow is the dynamic import of `services/inline.ts`+ (step 5), which runs services in the core's process only with `HARNESSD_SERVICES=none`.+- It fails when the walk's lines exceed `CORE_CLOSURE_BUDGET`. Each step that moves code out lowers the+ budget to the new number in the same change, so the core cannot grow back. A change that must grow+ it says why in the budget's comment, as `RUN_FOREGROUND_BUDGET` does.+- It fails when the walk reaches an edge folder (`lib/e2ee`, `cable`, `device`, `lib/autonomous-device`,+ `sharing`, `teams`, `orchestrator`, the Grid service files, `lib/localModels.ts`, the Store and viewer+ parts of `dsh`, the index half of `lib/sessionSearch`, `services/*` implementations), except through+ an exception listed by file, each with the step that removes it. Like the services' exception list+ today, an exception no longer needed fails the test, so the list only shrinks.+- The core reaches a service only through its link and its manifest (name, request types, port+ fallbacks), never its implementation. `HARNESSD_SERVICES=none` stays as a debugging switch until+ every service has run out of process by default for a release, and then goes, with+ `services/inline.ts`.+- `RUN_FOREGROUND_BUDGET` and `BACKEND_SOCKET_BUDGET` follow the same ratchet; at the end about 1,500+ and 800 lines.++The 61,000 is the sum of what stays: about 66,700 lines of files that stay whole, less the commands+in `cli.ts` (the core's entry is about 2,900 lines of it), less the parts of the socket, the hook+server and the local WebSocket server that leave (about 2,200), less the feature wiring in+`runForeground` (about 900), the dead code (about 600) and the unsupervised update handoff (about+180), plus about 600 lines of new links: about 60,600.++## Found on the way++Fix in place, in step 3 unless noted.++- `selfUpdate.ts:192`: the canary's `spawnSync` blocks the core's event loop for up to 15 s.+- `runtimeInstall.ts:54, 135`: `execFileSync` of `tar` (120 s) and `grid --version` (60 s) on the core's+ event loop at every Grid pin move.+- `backendSocket.ts:432–435`: `orchestratorRoleOf` builds the orchestrator at the first turn end of+ every daemon, with synchronous disk reads; if it throws, the apps stop receiving frames.+- `core/transcripts/ingest.ts:58–62`: the device's transcript observer and the runtime profiles'+ ingest run unguarded on every transcript line.+- `cli.ts:4027, 4060`: the Wi-Fi device's constructors throw on a corrupt state file, unguarded, and+ put the whole core in safe mode.+- `reconcileOnce` has no deadline: a stuck pass stops every hook from binding and every registry save.+- `backendSocket.ts:124, 1223`: signed out, every event is sealed and queued for a link that never opens.+- `channels.ts:42–50`: the tab-channel poll runs every 15 s on every daemon, Tab collaboration or not;+ Share's timers likewise (`sharing/owner.ts:47–53`). Not fixed here (move only): they leave the core+ with the experimental host (step 8).+- `services/fleet.ts:39–62`: the fleet service is handed the `AuthSessionManager` and the E2EE+ identity, against "a service holds no credential" (step 10).+- `cableHost.ts:95–120`: the dial's host holds an `AuthSessionManager` of its own (step 9).+- The relaunch takes the private Grid name from `backend.gridName()`, not the row: a restore before+ `machine_meta` arrives may drop `HARNESS_PRIVATE_GRID` (unconfirmed; worth an e2e check).+- `restartForUpdate` does not stop the cable or the fleet as `shutdown` does: unsupervised, the old+ process holds the serial port while it waits on its child (gone with step 11).+- `hook/notify.mjs`: a 4xx or 5xx from a core that is up still triggers the hook's offline registry+ write, racing the core (`notify.mjs:1393, 1547`; round 35 stopped the timeout case).++## Open decisions++1. **On-demand services.** Start the devices and the experimental host only when used (250 MiB always+ on), or run all seven always (350 MiB)?+2. **Where the fleet lives.** Beside the dial (its synchronous reader, as proposed) or in the gateway+ (its lane is a relay client)? Either way its credentials go through `core.account`.+3. **Credentials.** Services ask `core.account` for every token (today's rule), or the gateway and the+ account proxies refresh the session themselves, which the file lock (`authSession.ts:149–186`)+ already makes safe? And whether reading the vendor Keychain for account usage counts as holding a+ credential.+4. **The lane follows the dial** (from the harnessd design): with no dial, ⌘K never sees another+ machine. Opening the lane for ⌘K changes what the backend counts as watching each machine.+5. **Keystrokes to the prompt scopes** cross a process once teams leaves: batched, or gated on Tab+ collaboration being on (a feature change, so not in a move-only step).++## Appendix: the count++The walk: start at the core's entry; for each file, read every `import … from '…'`, `export … from+'…'`, `import '…'` and `import('…')` that is not `import type`; resolve relative specifiers (`.js` to+`.ts`, `index.ts`); keep files under `cli/src` that are not tests; sum their lines. Run on 3ac2aea57+from `cli/src/cli.ts`, it gives 472 files and 111,892 lines. The area of each file, and whether it+stays, leaves or is a CLI command, is the table above; the classification is by path, file by file,+corrected where the inventories found a file serving another area than its name says.