Skip to content

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.

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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.