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.

Claude Code's and Codex's discovery: declared contracts the kit applies in core (#1051)

Deed4df7d39a74a
diff --git a/cli/src/architecture.spec.ts b/cli/src/architecture.spec.ts
index 070e64a2e..9fd8c0086 100644
--- a/cli/src/architecture.spec.ts
+++ b/cli/src/architecture.spec.ts
@@ -141,6 +141,12 @@ const SERVICE_MAY_IMPORT: Record<string, string> = {
'services/workspaces.ts → ../lib/registry.js': 'sessionDisplayTitle, a pure helper',
}
+/** Claude Code's and Codex's declared contracts that core reads in line, and the rollout reader the registry keeps
+ * until (c4): what a launch's or discovery's closure may reach of the two engines. */
+const LAUNCH_CONTRACTS = new Set(['engines/claude/launch.ts', 'engines/codex/launch.ts'])
+const DECLARED = new Set(['engines/claude/hookContract.ts', 'engines/codex/hookContract.ts', 'engines/claude/discoveryContract.ts',
+ 'engines/codex/discoveryContract.ts', 'engines/codex/rollout.ts'])
+
/** What is not the core's, by path: each goes to a service or its own process, in the plan's order. */
const EDGE: RegExp[] = [
/^engines\/(claude|codex)\/(screen|composer|activity|stoppedGoal|modelControl|modelPicker|questionControl|submission|nativeControl)\.ts$/,
@@ -152,6 +158,8 @@ const EDGE: RegExp[] = [
/^engines\/codex\/ownLoginProvider\.ts$/, /^lib\/codexStartupRetry\.ts$/,
// So is their launch preparation: folder trust and the resume repair are declared, and the kit applies them.
/^engines\/codex\/portableHistory\.ts$/, /^lib\/claudeTrust\.ts$/,
+ // And what discovery reads off their processes and transcripts (discoveryContract.ts, applied by the kit).
+ /^lib\/(claudeProject|codexHomeProbe)\.ts$/,
/^lib\/(askQuestion|runtimeProfileController|composerScreen|teamWriteHold|messageHold|terminalActivity|codexTurnRecovery)\.ts$/,
/^engines\/(screens|modelControls|questionControls|submissions|nativeControls)\.ts$/,
// Claude Code's and Codex's reading of their composer: shared by the two, loaded only by their workers.
@@ -248,6 +256,17 @@ describe('the daemon\'s shape', () => {
expect([...closureOf('engines/hooks.ts').keys()].filter(file => contracts.has(file)).sort()).toEqual([...contracts].sort())
})
+ it('discovery loads the engines\' declared contracts alone', () => {
+ // The pass and what it reads off a process, the grid's model, the start-up repair, and the registry, which
+ // still holds Codex's rollout reader for its load-time repair until (c4).
+ for (const entry of ['lib/tmux.ts', 'lib/terminalAgentDiscovery.ts', 'lib/gridAssignment.ts', 'lib/cwdRepair.ts', 'lib/registry.ts',
+ 'engines/discoveries.ts', 'engines/kit/processFacts.ts', 'engines/kit/projectFolder.ts']) {
+ expect([...closureOf(entry).keys()].filter(file => /^engines\/(claude|codex)\//.test(file) && !DECLARED.has(file) && !LAUNCH_CONTRACTS.has(file)), entry).toEqual([])
+ }
+ expect([...closureOf('engines/discoveries.ts').keys()].filter(file => /^engines\/(claude|codex)\//.test(file)).sort())
+ .toEqual(['engines/claude/discoveryContract.ts', 'engines/codex/discoveryContract.ts'])
+ })
+
it('building a launch loads the engines\' declared launch contracts alone', () => {
const contracts = new Set(['engines/claude/launch.ts', 'engines/codex/launch.ts'])
// The builders: the argv and its script, a relaunch's overrides, a harness's flags.
@@ -259,7 +278,7 @@ describe('the daemon\'s shape', () => {
expect([...closureOf('lib/engineLaunch.ts').keys()].filter(file => contracts.has(file)).sort()).toEqual([...contracts].sort())
// The launches themselves reach the registry too, whose hook admission reads the hook contracts and whose
// load-time repair still reads Codex rollouts (rollout.ts, a later step of the plan). Nothing else of the two.
- const declared = new Set([...contracts, 'engines/claude/hookContract.ts', 'engines/codex/hookContract.ts', 'engines/codex/rollout.ts'])
+ const declared = new Set([...contracts, ...DECLARED])
for (const entry of ['core/agents/create.ts', 'core/agents/fork.ts', 'core/agents/restart.ts', 'core/agents/swap.ts',
'core/agents/launch.ts', 'core/agents/launches.ts', 'lib/resumeAgentService.ts']) {
expect([...closureOf(entry).keys()].filter(file => /^engines\/(claude|codex)\//.test(file) && !declared.has(file)), entry).toEqual([])
diff --git a/cli/src/core/main.ts b/cli/src/core/main.ts
index 4246a0564..f411d0fb0 100644
--- a/cli/src/core/main.ts
+++ b/cli/src/core/main.ts
@@ -67,7 +67,7 @@ import { createRetainExitedSession } from '../lib/retainExitedSession.js'
import { createKeepAbandonedConversation } from '../lib/keepAbandonedConversation.js'
import { OpenTabProtection } from '../lib/openTabProtection.js'
import { sessionCheckpoints } from '../lib/sessionCheckpoint.js'
-import { repairClaudeCwd } from '../lib/cwdRepair.js'
+import { repairProjectCwds } from '../lib/cwdRepair.js'
import { stoppedAgents } from '../lib/stoppedAgents.js'
import { ExternalSessions, OpenSessions } from '../lib/sessionSearch/external.js'
import { externalProviders } from '../lib/sessionSearch/externals/index.js'
@@ -1939,7 +1939,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {
// Best effort: an archive directory that cannot be listed, or a row that cannot be rewritten, is a
// line in the log, never a daemon that does not come up.
try {
- const repaired = await repairClaudeCwd({ registry, stoppedAgents, log: (message) => console.log(message) })
+ const repaired = await repairProjectCwds({ registry, stoppedAgents, log: (message) => console.log(message) })
if (repaired.registry || repaired.archived) console.log(`[repair] cwd · ${repaired.registry} live · ${repaired.archived} saved`)
} catch (error) {
console.warn(`[repair] cwd repair skipped · ${error instanceof Error ? error.message : error}`)
diff --git a/cli/src/engines/README.md b/cli/src/engines/README.md
index 4e4cc33c7..cfe0c55ed 100644
--- a/cli/src/engines/README.md
+++ b/cli/src/engines/README.md
@@ -22,7 +22,8 @@ readers. Hook transport, process binding and event delivery stay with core. Thei
worker ([hooks](../../../docs/design/2026-10-08-engine-hooks.md)). So are their launch specifics (`claude/launch.ts`,
`codex/launch.ts`): Codex's pane startup probe and retry, its own-login provider, the harness context and env
flags, folder trust and the resume repair, applied by `kit/launchStartup.ts`, `kit/launchArgs.ts`,
-`kit/folderTrust.ts` and `kit/resumeRepair.ts` ([launch](../../../docs/design/2026-10-08-engine-launch.md)). Claude Code and Codex history/last-turn reads,
+`kit/folderTrust.ts` and `kit/resumeRepair.ts`, and what discovery reads off their processes and transcripts
+(`claude/discoveryContract.ts`, `codex/discoveryContract.ts`, `kit/processFacts.ts`, `kit/projectFolder.ts`) ([launch](../../../docs/design/2026-10-08-engine-launch.md)). Claude Code and Codex history/last-turn reads,
live transcript parsing, runtime profiles/catalogs, screen interpretation, submission readings, model-control drivers, question navigation and Codex's app-server connection run on demand in supervised workers;
the other facets still run in core. Explicit inline mode and older masters retain inline implementations. See
[hooks](../../../docs/design/2026-10-08-engine-hooks.md),
diff --git a/cli/src/engines/__fixtures__/discovery.golden.json b/cli/src/engines/__fixtures__/discovery.golden.json
new file mode 100644
index 000000000..80e9c01ec
--- /dev/null
+++ b/cli/src/engines/__fixtures__/discovery.golden.json
@@ -0,0 +1,350 @@
+{
+"process": {
+ "claude · claude": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "claude · claude --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "claude · claude resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "claude · claude --help": {"matched":{},"ambiguous":false},
+ "claude · claude --version": {"matched":{},"ambiguous":false},
+ "Claude · Claude": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "Claude · Claude --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "Claude · Claude resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "Claude · Claude --help": {"matched":{},"ambiguous":false},
+ "Claude · Claude --version": {"matched":{},"ambiguous":false},
+ "CLAUDE · CLAUDE": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "CLAUDE · CLAUDE --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "CLAUDE · CLAUDE resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "CLAUDE · CLAUDE --help": {"matched":{},"ambiguous":false},
+ "CLAUDE · CLAUDE --version": {"matched":{},"ambiguous":false},
+ "claude-helper · claude-helper": {"matched":{},"ambiguous":false},
+ "claude-helper · claude-helper --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "claude-helper · claude-helper resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "claude-helper · claude-helper --help": {"matched":{},"ambiguous":false},
+ "claude-helper · claude-helper --version": {"matched":{},"ambiguous":false},
+ "claudex · claudex": {"matched":{},"ambiguous":false},
+ "claudex · claudex --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "claudex · claudex resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "claudex · claudex --help": {"matched":{},"ambiguous":false},
+ "claudex · claudex --version": {"matched":{},"ambiguous":false},
+ "/usr/local/bin/claude · /usr/local/bin/claude": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "/usr/local/bin/claude · /usr/local/bin/claude --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "/usr/local/bin/claude · /usr/local/bin/claude resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "/usr/local/bin/claude · /usr/local/bin/claude --help": {"matched":{},"ambiguous":false},
+ "/usr/local/bin/claude · /usr/local/bin/claude --version": {"matched":{},"ambiguous":false},
+ "/opt/homebrew/bin/claude · /opt/homebrew/bin/claude": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "/opt/homebrew/bin/claude · /opt/homebrew/bin/claude --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "/opt/homebrew/bin/claude · /opt/homebrew/bin/claude resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "/opt/homebrew/bin/claude · /opt/homebrew/bin/claude --help": {"matched":{},"ambiguous":false},
+ "/opt/homebrew/bin/claude · /opt/homebrew/bin/claude --version": {"matched":{},"ambiguous":false},
+ "/opt/home/.local/share/claude/versions/2.1.246 · /opt/home/.local/share/claude/versions/2.1.246": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "/opt/home/.local/share/claude/versions/2.1.246 · /opt/home/.local/share/claude/versions/2.1.246 --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "/opt/home/.local/share/claude/versions/2.1.246 · /opt/home/.local/share/claude/versions/2.1.246 resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "/opt/home/.local/share/claude/versions/2.1.246 · /opt/home/.local/share/claude/versions/2.1.246 --help": {"matched":{},"ambiguous":false},
+ "/opt/home/.local/share/claude/versions/2.1.246 · /opt/home/.local/share/claude/versions/2.1.246 --version": {"matched":{},"ambiguous":false},
+ "/opt/home/.local/share/Claude/versions/2.1.246 · /opt/home/.local/share/Claude/versions/2.1.246": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "/opt/home/.local/share/Claude/versions/2.1.246 · /opt/home/.local/share/Claude/versions/2.1.246 --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "/opt/home/.local/share/Claude/versions/2.1.246 · /opt/home/.local/share/Claude/versions/2.1.246 resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "/opt/home/.local/share/Claude/versions/2.1.246 · /opt/home/.local/share/Claude/versions/2.1.246 --help": {"matched":{},"ambiguous":false},
+ "/opt/home/.local/share/Claude/versions/2.1.246 · /opt/home/.local/share/Claude/versions/2.1.246 --version": {"matched":{},"ambiguous":false},
+ "2.1.246 · 2.1.246": {"matched":{},"ambiguous":false},
+ "2.1.246 · 2.1.246 --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "2.1.246 · 2.1.246 resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "2.1.246 · 2.1.246 --help": {"matched":{},"ambiguous":false},
+ "2.1.246 · 2.1.246 --version": {"matched":{},"ambiguous":false},
+ "/opt/claude/versions/2.1.246 · /opt/claude/versions/2.1.246": {"matched":{},"ambiguous":false},
+ "/opt/claude/versions/2.1.246 · /opt/claude/versions/2.1.246 --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "/opt/claude/versions/2.1.246 · /opt/claude/versions/2.1.246 resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "/opt/claude/versions/2.1.246 · /opt/claude/versions/2.1.246 --help": {"matched":{},"ambiguous":false},
+ "/opt/claude/versions/2.1.246 · /opt/claude/versions/2.1.246 --version": {"matched":{},"ambiguous":false},
+ "/opt/home/.local/share/claude/versions/2.1.246/extra · /opt/home/.local/share/claude/versions/2.1.246/extra": {"matched":{},"ambiguous":false},
+ "/opt/home/.local/share/claude/versions/2.1.246/extra · /opt/home/.local/share/claude/versions/2.1.246/extra --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "/opt/home/.local/share/claude/versions/2.1.246/extra · /opt/home/.local/share/claude/versions/2.1.246/extra resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "/opt/home/.local/share/claude/versions/2.1.246/extra · /opt/home/.local/share/claude/versions/2.1.246/extra --help": {"matched":{},"ambiguous":false},
+ "/opt/home/.local/share/claude/versions/2.1.246/extra · /opt/home/.local/share/claude/versions/2.1.246/extra --version": {"matched":{},"ambiguous":false},
+ "C:\\home\\.local\\share\\claude\\versions\\2.1.2 · C:\\home\\.local\\share\\claude\\versions\\2.1.2": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "C:\\home\\.local\\share\\claude\\versions\\2.1.2 · C:\\home\\.local\\share\\claude\\versions\\2.1.2 --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "C:\\home\\.local\\share\\claude\\versions\\2.1.2 · C:\\home\\.local\\share\\claude\\versions\\2.1.2 resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "C:\\home\\.local\\share\\claude\\versions\\2.1.2 · C:\\home\\.local\\share\\claude\\versions\\2.1.2 --help": {"matched":{},"ambiguous":false},
+ "C:\\home\\.local\\share\\claude\\versions\\2.1.2 · C:\\home\\.local\\share\\claude\\versions\\2.1.2 --version": {"matched":{},"ambiguous":false},
+ "codex · codex": {"matched":{"codex":"3 native-or-process-name"},"ambiguous":false},
+ "codex · codex --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"codex":"3 native-or-process-name"},"ambiguous":false},
+ "codex · codex resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"codex":"3 native-or-process-name"},"ambiguous":false},
+ "codex · codex --help": {"matched":{},"ambiguous":false},
+ "codex · codex --version": {"matched":{},"ambiguous":false},
+ "Codex · Codex": {"matched":{"codex":"3 native-or-process-name"},"ambiguous":false},
+ "Codex · Codex --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"codex":"3 native-or-process-name"},"ambiguous":false},
+ "Codex · Codex resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"codex":"3 native-or-process-name"},"ambiguous":false},
+ "Codex · Codex --help": {"matched":{},"ambiguous":false},
+ "Codex · Codex --version": {"matched":{},"ambiguous":false},
+ "codex-aarch64-apple-darwin · codex-aarch64-apple-darwin": {"matched":{"codex":"3 native-or-process-name"},"ambiguous":false},
+ "codex-aarch64-apple-darwin · codex-aarch64-apple-darwin --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"codex":"3 native-or-process-name"},"ambiguous":false},
+ "codex-aarch64-apple-darwin · codex-aarch64-apple-darwin resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"codex":"3 native-or-process-name"},"ambiguous":false},
+ "codex-aarch64-apple-darwin · codex-aarch64-apple-darwin --help": {"matched":{},"ambiguous":false},
+ "codex-aarch64-apple-darwin · codex-aarch64-apple-darwin --version": {"matched":{},"ambiguous":false},
+ "codex-x86_64-unknown-linux-musl · codex-x86_64-unknown-linux-musl": {"matched":{"codex":"3 native-or-process-name"},"ambiguous":false},
+ "codex-x86_64-unknown-linux-musl · codex-x86_64-unknown-linux-musl --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"codex":"3 native-or-process-name"},"ambiguous":false},
+ "codex-x86_64-unknown-linux-musl · codex-x86_64-unknown-linux-musl resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"codex":"3 native-or-process-name"},"ambiguous":false},
+ "codex-x86_64-unknown-linux-musl · codex-x86_64-unknown-linux-musl --help": {"matched":{},"ambiguous":false},
+ "codex-x86_64-unknown-linux-musl · codex-x86_64-unknown-linux-musl --version": {"matched":{},"ambiguous":false},
+ "codex-x86_64-unknown-linux-gnu · codex-x86_64-unknown-linux-gnu": {"matched":{"codex":"3 native-or-process-name"},"ambiguous":false},
+ "codex-x86_64-unknown-linux-gnu · codex-x86_64-unknown-linux-gnu --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"codex":"3 native-or-process-name"},"ambiguous":false},
+ "codex-x86_64-unknown-linux-gnu · codex-x86_64-unknown-linux-gnu resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"codex":"3 native-or-process-name"},"ambiguous":false},
+ "codex-x86_64-unknown-linux-gnu · codex-x86_64-unknown-linux-gnu --help": {"matched":{},"ambiguous":false},
+ "codex-x86_64-unknown-linux-gnu · codex-x86_64-unknown-linux-gnu --version": {"matched":{},"ambiguous":false},
+ "codex-x86_64-pc-windows-msvc · codex-x86_64-pc-windows-msvc": {"matched":{},"ambiguous":false},
+ "codex-x86_64-pc-windows-msvc · codex-x86_64-pc-windows-msvc --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "codex-x86_64-pc-windows-msvc · codex-x86_64-pc-windows-msvc resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "codex-x86_64-pc-windows-msvc · codex-x86_64-pc-windows-msvc --help": {"matched":{},"ambiguous":false},
+ "codex-x86_64-pc-windows-msvc · codex-x86_64-pc-windows-msvc --version": {"matched":{},"ambiguous":false},
+ "codex-arm64-apple-darwin · codex-arm64-apple-darwin": {"matched":{},"ambiguous":false},
+ "codex-arm64-apple-darwin · codex-arm64-apple-darwin --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "codex-arm64-apple-darwin · codex-arm64-apple-darwin resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "codex-arm64-apple-darwin · codex-arm64-apple-darwin --help": {"matched":{},"ambiguous":false},
+ "codex-arm64-apple-darwin · codex-arm64-apple-darwin --version": {"matched":{},"ambiguous":false},
+ "/opt/homebrew/bin/codex · /opt/homebrew/bin/codex": {"matched":{"codex":"3 native-or-process-name"},"ambiguous":false},
+ "/opt/homebrew/bin/codex · /opt/homebrew/bin/codex --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"codex":"3 native-or-process-name"},"ambiguous":false},
+ "/opt/homebrew/bin/codex · /opt/homebrew/bin/codex resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"codex":"3 native-or-process-name"},"ambiguous":false},
+ "/opt/homebrew/bin/codex · /opt/homebrew/bin/codex --help": {"matched":{},"ambiguous":false},
+ "/opt/homebrew/bin/codex · /opt/homebrew/bin/codex --version": {"matched":{},"ambiguous":false},
+ "codexa · codexa": {"matched":{},"ambiguous":false},
+ "codexa · codexa --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "codexa · codexa resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "codexa · codexa --help": {"matched":{},"ambiguous":false},
+ "codexa · codexa --version": {"matched":{},"ambiguous":false},
+ "node · node": {"matched":{},"ambiguous":false},
+ "node · node --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "node · node resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "node · node --help": {"matched":{},"ambiguous":false},
+ "node · node --version": {"matched":{},"ambiguous":false},
+ "bun · bun": {"matched":{},"ambiguous":false},
+ "bun · bun --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "bun · bun resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "bun · bun --help": {"matched":{},"ambiguous":false},
+ "bun · bun --version": {"matched":{},"ambiguous":false},
+ "python3 · python3": {"matched":{},"ambiguous":false},
+ "python3 · python3 --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "python3 · python3 resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "python3 · python3 --help": {"matched":{},"ambiguous":false},
+ "python3 · python3 --version": {"matched":{},"ambiguous":false},
+ "bash · bash": {"matched":{},"ambiguous":false},
+ "bash · bash --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "bash · bash resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "bash · bash --help": {"matched":{},"ambiguous":false},
+ "bash · bash --version": {"matched":{},"ambiguous":false},
+ "zsh · zsh": {"matched":{},"ambiguous":false},
+ "zsh · zsh --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "zsh · zsh resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":false},
+ "zsh · zsh --help": {"matched":{},"ambiguous":false},
+ "zsh · zsh --version": {"matched":{},"ambiguous":false},
+ "agent · agent": {"matched":{},"ambiguous":true},
+ "agent · agent --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":true},
+ "agent · agent resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{},"ambiguous":true},
+ "agent · agent --help": {"matched":{},"ambiguous":false},
+ "agent · agent --version": {"matched":{},"ambiguous":false},
+ "cursor-agent · cursor-agent": {"matched":{"cursor":"3 native-or-process-name"},"ambiguous":false},
+ "cursor-agent · cursor-agent --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"cursor":"3 native-or-process-name"},"ambiguous":false},
+ "cursor-agent · cursor-agent resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"cursor":"3 native-or-process-name"},"ambiguous":false},
+ "cursor-agent · cursor-agent --help": {"matched":{},"ambiguous":false},
+ "cursor-agent · cursor-agent --version": {"matched":{},"ambiguous":false},
+ "opencode · opencode": {"matched":{"opencode":"3 native-or-process-name"},"ambiguous":false},
+ "opencode · opencode --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"opencode":"3 native-or-process-name"},"ambiguous":false},
+ "opencode · opencode resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"opencode":"3 native-or-process-name"},"ambiguous":false},
+ "opencode · opencode --help": {"matched":{},"ambiguous":false},
+ "opencode · opencode --version": {"matched":{},"ambiguous":false},
+ "pi · pi": {"matched":{"pi":"3 native-or-process-name"},"ambiguous":false},
+ "pi · pi --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"pi":"3 native-or-process-name"},"ambiguous":false},
+ "pi · pi resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"pi":"3 native-or-process-name"},"ambiguous":false},
+ "pi · pi --help": {"matched":{},"ambiguous":false},
+ "pi · pi --version": {"matched":{},"ambiguous":false},
+ "hermes · hermes": {"matched":{"hermes":"3 native-or-process-name"},"ambiguous":false},
+ "hermes · hermes --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"hermes":"3 native-or-process-name"},"ambiguous":false},
+ "hermes · hermes resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"hermes":"3 native-or-process-name"},"ambiguous":false},
+ "hermes · hermes --help": {"matched":{},"ambiguous":false},
+ "hermes · hermes --version": {"matched":{},"ambiguous":false},
+ "cmd · cmd": {"matched":{"commandcode":"3 native-or-process-name"},"ambiguous":false},
+ "cmd · cmd --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"commandcode":"3 native-or-process-name"},"ambiguous":false},
+ "cmd · cmd resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"commandcode":"3 native-or-process-name"},"ambiguous":false},
+ "cmd · cmd --help": {"matched":{},"ambiguous":false},
+ "cmd · cmd --version": {"matched":{},"ambiguous":false},
+ "muse · muse": {"matched":{"muse":"3 native-or-process-name"},"ambiguous":false},
+ "muse · muse --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"muse":"3 native-or-process-name"},"ambiguous":false},
+ "muse · muse resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"muse":"3 native-or-process-name"},"ambiguous":false},
+ "muse · muse --help": {"matched":{},"ambiguous":false},
+ "muse · muse --version": {"matched":{},"ambiguous":false},
+ "amp · amp": {"matched":{"amp":"3 native-or-process-name"},"ambiguous":false},
+ "amp · amp --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"amp":"3 native-or-process-name"},"ambiguous":false},
+ "amp · amp resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"amp":"3 native-or-process-name"},"ambiguous":false},
+ "amp · amp --help": {"matched":{},"ambiguous":false},
+ "amp · amp --version": {"matched":{},"ambiguous":false},
+ "kilo · kilo": {"matched":{"kilo":"3 native-or-process-name"},"ambiguous":false},
+ "kilo · kilo --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"kilo":"3 native-or-process-name"},"ambiguous":false},
+ "kilo · kilo resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"kilo":"3 native-or-process-name"},"ambiguous":false},
+ "kilo · kilo --help": {"matched":{},"ambiguous":false},
+ "kilo · kilo --version": {"matched":{},"ambiguous":false},
+ "grok · grok": {"matched":{"grok":"3 native-or-process-name"},"ambiguous":false},
+ "grok · grok --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"grok":"3 native-or-process-name"},"ambiguous":false},
+ "grok · grok resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"grok":"3 native-or-process-name"},"ambiguous":false},
+ "grok · grok --help": {"matched":{},"ambiguous":false},
+ "grok · grok --version": {"matched":{},"ambiguous":false},
+ "agy · agy": {"matched":{"agy":"3 native-or-process-name"},"ambiguous":false},
+ "agy · agy --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"agy":"3 native-or-process-name"},"ambiguous":false},
+ "agy · agy resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"agy":"3 native-or-process-name"},"ambiguous":false},
+ "agy · agy --help": {"matched":{},"ambiguous":false},
+ "agy · agy --version": {"matched":{},"ambiguous":false},
+ "copilot · copilot": {"matched":{"copilot":"3 native-or-process-name"},"ambiguous":false},
+ "copilot · copilot --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"copilot":"3 native-or-process-name"},"ambiguous":false},
+ "copilot · copilot resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"copilot":"3 native-or-process-name"},"ambiguous":false},
+ "copilot · copilot --help": {"matched":{},"ambiguous":false},
+ "copilot · copilot --version": {"matched":{},"ambiguous":false},
+ "devin · devin": {"matched":{"devin":"3 native-or-process-name"},"ambiguous":false},
+ "devin · devin --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"devin":"3 native-or-process-name"},"ambiguous":false},
+ "devin · devin resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"devin":"3 native-or-process-name"},"ambiguous":false},
+ "devin · devin --help": {"matched":{},"ambiguous":false},
+ "devin · devin --version": {"matched":{},"ambiguous":false},
+ "node · node /opt/lib/node_modules/@anthropic-ai/claude-code/cli.js": {"matched":{"claude":"2 package-entrypoint"},"ambiguous":false},
+ "node · node /opt/lib/node_modules/@anthropic-ai/claude-code/cli.js --resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"claude":"2 package-entrypoint"},"ambiguous":false},
+ "node · node --require /opt/x.js /opt/lib/node_modules/@anthropic-ai/claude-code/cli.js": {"matched":{"claude":"2 package-entrypoint"},"ambiguous":false},
+ "node · node C:\\npm\\node_modules\\@anthropic-ai\\claude-code\\cli.js": {"matched":{"claude":"2 package-entrypoint"},"ambiguous":false},
+ "node · node /opt/lib/node_modules/@anthropic-ai/claude-code/cli.js --help": {"matched":{},"ambiguous":false},
+ "node · node /opt/lib/node_modules/@anthropic-ai/claude-code/cli.mjs": {"matched":{},"ambiguous":false},
+ "node · node /opt/lib/node_modules/@openai/codex/bin/codex.js": {"matched":{"codex":"2 package-entrypoint"},"ambiguous":false},
+ "node · node /opt/lib/node_modules/@openai/codex/bin/codex.js --no-daemon resume 01234567-89ab-cdef-0123-456789abcdef": {"matched":{"codex":"2 package-entrypoint"},"ambiguous":false},
+ "node · node /opt/lib/node_modules/@openai/codex/bin/codex": {"matched":{"codex":"3 native-or-process-name"},"ambiguous":false},
+ "node · node C:\\npm\\node_modules\\@openai\\codex\\bin\\codex.js": {"matched":{"codex":"2 package-entrypoint"},"ambiguous":false},
+ "node · node /opt/lib/node_modules/@openai/codex/bin/codex.js --help": {"matched":{},"ambiguous":false},
+ "node · node /opt/lib/node_modules/@openai/codex-sdk/bin/codex.js": {"matched":{},"ambiguous":false},
+ "bun · bun /opt/.bun/install/global/node_modules/@openai/codex/bin/codex.js": {"matched":{"codex":"2 package-entrypoint"},"ambiguous":false},
+ "node · node -e \"require('@openai/codex/bin/codex.js')\"": {"matched":{},"ambiguous":false},
+ "node · node /opt/lib/node_modules/@github/copilot/npm-loader.js": {"matched":{"copilot":"2 package-entrypoint"},"ambiguous":false},
+ "node · node /opt/cursor-agent/versions/2026.1/index.js": {"matched":{"cursor":"3 native-or-process-name"},"ambiguous":false},
+ "python3 · python3 /opt/hermes-agent/hermes": {"matched":{"hermes":"3 native-or-process-name"},"ambiguous":false},
+ "claude · claude -p \"summarise\" --output-format json": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "node · /opt/home/.local/share/claude/versions/2.1.246 --resume x": {"matched":{"claude":"3 native-or-process-name"},"ambiguous":false},
+ "bash · bash -c claude": {"matched":{},"ambiguous":false},
+ "zsh · zsh -lic . /tmp/launch.sh harness-engine /work claude --resume x": {"matched":{},"ambiguous":false},
+ "codex · codex app-server --managed-daemon": {"matched":{"codex":"3 native-or-process-name"},"ambiguous":false}
+},
+"argv": {
+ "claude": {},
+ "claude --resume 01234567-89ab-cdef-0123-456789abcdef": {"claude":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"cursor":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"hermes":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"commandcode":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"devin":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"grok":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"copilot":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false}},
+ "claude -r 01234567-89ab-cdef-0123-456789abcdef": {"claude":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"hermes":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"commandcode":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"devin":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"grok":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false}},
+ "claude --resume=01234567-89ab-cdef-0123-456789abcdef": {"claude":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"cursor":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"hermes":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"commandcode":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"devin":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"grok":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"copilot":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false}},
+ "claude --RESUME 01234567-89ab-cdef-0123-456789abcdef": {"claude":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"cursor":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"hermes":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"commandcode":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"devin":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"grok":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"copilot":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false}},
+ "claude -R 01234567-89ab-cdef-0123-456789abcdef": {"claude":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"hermes":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"commandcode":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"devin":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"grok":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false}},
+ "claude --resume 01234567-89AB-CDEF-0123-456789ABCDEF": {"claude":{"resumed":"01234567-89AB-CDEF-0123-456789ABCDEF","mode":null,"approves":false},"cursor":{"resumed":"01234567-89AB-CDEF-0123-456789ABCDEF","mode":null,"approves":false},"hermes":{"resumed":"01234567-89AB-CDEF-0123-456789ABCDEF","mode":null,"approves":false},"commandcode":{"resumed":"01234567-89AB-CDEF-0123-456789ABCDEF","mode":null,"approves":false},"grok":{"resumed":"01234567-89AB-CDEF-0123-456789ABCDEF","mode":null,"approves":false},"copilot":{"resumed":"01234567-89AB-CDEF-0123-456789ABCDEF","mode":null,"approves":false}},
+ "claude --resume 01234567-89ab-cdef-0123-456789abcdef --fork-session": {"cursor":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"hermes":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"commandcode":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"devin":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"grok":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"copilot":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false}},
+ "claude --fork-session --resume 01234567-89ab-cdef-0123-456789abcdef": {"cursor":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"hermes":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"commandcode":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"devin":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"grok":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"copilot":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false}},
+ "claude --resume \"01234567-89ab-cdef-0123-456789abcdef\"": {},
+ "claude --resume 0123456789abcde": {},
+ "claude --resume 0123456789abcdef": {"claude":{"resumed":"0123456789abcdef","mode":null,"approves":false},"cursor":{"resumed":"0123456789abcdef","mode":null,"approves":false},"commandcode":{"resumed":"0123456789abcdef","mode":null,"approves":false},"grok":{"resumed":"0123456789abcdef","mode":null,"approves":false},"copilot":{"resumed":"0123456789abcdef","mode":null,"approves":false}},
+ "claude --resume 01234567-89ab-cdef-0123-456789abcdef": {"claude":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"cursor":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"hermes":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"commandcode":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"devin":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"grok":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"copilot":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false}},
+ "claude --resume\t01234567-89ab-cdef-0123-456789abcdef": {"claude":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"cursor":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"hermes":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"commandcode":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"devin":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"grok":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"copilot":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false}},
+ "claude --resume my-session-name": {"devin":{"resumed":"my-session-name","mode":null,"approves":false}},
+ "claude -p \"--resume 01234567-89ab-cdef-0123-456789abcdef\"": {},
+ "claude --continue": {},
+ "codex resume 01234567-89ab-cdef-0123-456789abcdef": {"codex":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"muse":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false}},
+ "codex --no-daemon resume 01234567-89ab-cdef-0123-456789abcdef": {"codex":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"muse":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false}},
+ "codex resume --last": {},
+ "codex fork 01234567-89ab-cdef-0123-456789abcdef": {},
+ "codex resume=01234567-89ab-cdef-0123-456789abcdef": {"codex":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"muse":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false}},
+ "codex --approve-for-me resume 01234567-89ab-cdef-0123-456789abcdef": {"codex":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":"auto","approves":true},"muse":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false}},
+ "codex exec \"resume 01234567-89ab-cdef-0123-456789abcdef\"": {},
+ "codex resume 0123": {},
+ "node /opt/codex.js resume 01234567-89ab-cdef-0123-456789abcdef": {"codex":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"muse":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false}},
+ "cursor-agent --resume 01234567-89ab-cdef-0123-456789abcdef": {"claude":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"cursor":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"hermes":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"commandcode":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"devin":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"grok":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"copilot":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false}},
+ "opencode --session ses_abc123 --fork": {},
+ "opencode -s ses_abc123": {"opencode":{"resumed":"ses_abc123","mode":null,"approves":false},"kilo":{"resumed":"ses_abc123","mode":null,"approves":false}},
+ "pi --session 01234567-89ab-cdef-0123-456789abcdef": {"pi":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false},"commandcode":{"resumed":"01234567-89ab-cdef-0123-456789abcdef","mode":null,"approves":false}},
+ "hermes --resume 20260728_115628_f2c86a": {"hermes":{"resumed":"20260728_115628_f2c86a","mode":null,"approves":false}},
+ "devin -r brisk-otter": {"devin":{"resumed":"brisk-otter","mode":null,"approves":false}},
+ "amp threads continue T-0123456789abcdef01": {"amp":{"resumed":"T-0123456789abcdef01","mode":null,"approves":false}},
+ "claude --permission-mode auto": {"claude":{"resumed":null,"mode":"auto","approves":true}},
+ "claude --permission-mode acceptEdits": {"claude":{"resumed":null,"mode":"acceptEdits","approves":false}},
+ "claude --permission-mode=plan": {"claude":{"resumed":null,"mode":"plan","approves":false}},
+ "claude --dangerously-skip-permissions": {"claude":{"resumed":null,"mode":"full","approves":true}},
+ "claude --dangerously-skip-permissions --permission-mode auto": {"claude":{"resumed":null,"mode":"full","approves":true}},
+ "claude -p \"--dangerously-skip-permissions\"": {"claude":{"resumed":null,"mode":"full","approves":true}},
+ "codex --approve-for-me": {"codex":{"resumed":null,"mode":"auto","approves":true}},
+ "codex --sandbox read-only": {"codex":{"resumed":null,"mode":"readOnly","approves":false}},
+ "codex --dangerously-bypass-approvals-and-sandbox": {"codex":{"resumed":null,"mode":"full","approves":true}},
+ "codex --sandbox=read-only": {"codex":{"resumed":null,"mode":"readOnly","approves":false}}
+},
+"grid": {
+ "argv with a model": {"codex":{"baseUrl":"https://grid.example/relay/v1","model":"gpt-5"},"cursor":{"baseUrl":"https://grid.example/relay/v1","model":null},"opencode":{"baseUrl":"https://grid.example/relay/v1","model":null},"pi":{"baseUrl":"https://grid.example/relay/v1","model":null},"commandcode":{"baseUrl":"https://grid.example/relay/v1","model":null},"devin":{"baseUrl":"https://grid.example/relay/v1","model":null},"muse":{"baseUrl":"https://grid.example/relay/v1","model":null},"amp":{"baseUrl":"https://grid.example/relay/v1","model":null},"kilo":{"baseUrl":"https://grid.example/relay/v1","model":null},"agy":{"baseUrl":"https://grid.example/relay/v1","model":null},"terminal":{"baseUrl":"https://grid.example/relay/v1","model":null}},
+ "argv, unquoted url": {"codex":{"baseUrl":"https://grid.example/relay/v1","model":"gpt-5"},"cursor":{"baseUrl":"https://grid.example/relay/v1","model":null},"opencode":{"baseUrl":"https://grid.example/relay/v1","model":null},"pi":{"baseUrl":"https://grid.example/relay/v1","model":null},"commandcode":{"baseUrl":"https://grid.example/relay/v1","model":null},"devin":{"baseUrl":"https://grid.example/relay/v1","model":null},"muse":{"baseUrl":"https://grid.example/relay/v1","model":null},"amp":{"baseUrl":"https://grid.example/relay/v1","model":null},"kilo":{"baseUrl":"https://grid.example/relay/v1","model":null},"agy":{"baseUrl":"https://grid.example/relay/v1","model":null},"terminal":{"baseUrl":"https://grid.example/relay/v1","model":null}},
+ "argv, no model": {"codex":{"baseUrl":"https://grid.example/relay/v1","model":null},"cursor":{"baseUrl":"https://grid.example/relay/v1","model":null},"opencode":{"baseUrl":"https://grid.example/relay/v1","model":null},"pi":{"baseUrl":"https://grid.example/relay/v1","model":null},"commandcode":{"baseUrl":"https://grid.example/relay/v1","model":null},"devin":{"baseUrl":"https://grid.example/relay/v1","model":null},"muse":{"baseUrl":"https://grid.example/relay/v1","model":null},"amp":{"baseUrl":"https://grid.example/relay/v1","model":null},"kilo":{"baseUrl":"https://grid.example/relay/v1","model":null},"agy":{"baseUrl":"https://grid.example/relay/v1","model":null},"terminal":{"baseUrl":"https://grid.example/relay/v1","model":null}},
+ "argv, the router": {"codex":{"baseUrl":"https://grid.example/relay/v1","model":"Auto"},"cursor":{"baseUrl":"https://grid.example/relay/v1","model":null},"opencode":{"baseUrl":"https://grid.example/relay/v1","model":null},"pi":{"baseUrl":"https://grid.example/relay/v1","model":null},"commandcode":{"baseUrl":"https://grid.example/relay/v1","model":null},"devin":{"baseUrl":"https://grid.example/relay/v1","model":null},"muse":{"baseUrl":"https://grid.example/relay/v1","model":null},"amp":{"baseUrl":"https://grid.example/relay/v1","model":null},"kilo":{"baseUrl":"https://grid.example/relay/v1","model":null},"agy":{"baseUrl":"https://grid.example/relay/v1","model":null},"terminal":{"baseUrl":"https://grid.example/relay/v1","model":null}},
+ "argv, a model in a prompt": {"codex":{"baseUrl":"https://grid.example/relay/v1","model":null},"cursor":{"baseUrl":"https://grid.example/relay/v1","model":null},"opencode":{"baseUrl":"https://grid.example/relay/v1","model":null},"pi":{"baseUrl":"https://grid.example/relay/v1","model":null},"commandcode":{"baseUrl":"https://grid.example/relay/v1","model":null},"devin":{"baseUrl":"https://grid.example/relay/v1","model":null},"muse":{"baseUrl":"https://grid.example/relay/v1","model":null},"amp":{"baseUrl":"https://grid.example/relay/v1","model":null},"kilo":{"baseUrl":"https://grid.example/relay/v1","model":null},"agy":{"baseUrl":"https://grid.example/relay/v1","model":null},"terminal":{"baseUrl":"https://grid.example/relay/v1","model":null}},
+ "argv, not a relay": {},
+ "environment": {"claude":{"baseUrl":"https://grid.example/relay/v1","model":"qwen"},"hermes":{"baseUrl":"https://grid.example/relay/v1","model":null}},
+ "nothing": {}
+},
+"profile": {
+ "unset": {},
+ "the default": {},
+ "another profile": {"codex":"/profiles/work"},
+ "the default through a link": {},
+ "the default with a trailing dot": {},
+ "relative": {},
+ "a control character": {},
+ "DEL": {},
+ "too long": {},
+ "just long enough": {"codex":"/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
+ "empty": {},
+ "the daemon's own default": {"codex":"/profiles/other"},
+ "another engine's variable": {}
+},
+"project": {
+ "transcript · first line": {"isProjectTranscript":true,"cwdOf":"<root>/my work/repo.v2","cwdOfCutShort":null,"belongs":{"<root>/my work/repo.v2":true,"<root>/my work/repo.v2/sub dir":false,"<root>/linked-work":true,"<root>/my work/repo.v2/":true,"/elsewhere":false,"<root>/my-work/repo-v2":true}},
+ "transcript · drifted first, then home": {"isProjectTranscript":true,"cwdOf":"<root>/my work/repo.v2","cwdOfCutShort":null,"belongs":{"<root>/my work/repo.v2":true,"<root>/my work/repo.v2/sub dir":false,"<root>/linked-work":true,"<root>/my work/repo.v2/":true,"/elsewhere":false,"<root>/my-work/repo-v2":true}},
+ "transcript · no matching line": {"isProjectTranscript":true,"cwdOf":null,"cwdOfCutShort":null,"belongs":{"<root>/my work/repo.v2":true,"<root>/my work/repo.v2/sub dir":false,"<root>/linked-work":true,"<root>/my work/repo.v2/":true,"/elsewhere":false,"<root>/my-work/repo-v2":true}},
+ "transcript · a cwd that is not text": {"isProjectTranscript":true,"cwdOf":"<root>/my work/repo.v2","cwdOfCutShort":null,"belongs":{"<root>/my work/repo.v2":true,"<root>/my work/repo.v2/sub dir":false,"<root>/linked-work":true,"<root>/my work/repo.v2/":true,"/elsewhere":false,"<root>/my-work/repo-v2":true}},
+ "transcript · invalid JSON lines": {"isProjectTranscript":true,"cwdOf":"<root>/my work/repo.v2","cwdOfCutShort":null,"belongs":{"<root>/my work/repo.v2":true,"<root>/my work/repo.v2/sub dir":false,"<root>/linked-work":true,"<root>/my work/repo.v2/":true,"/elsewhere":false,"<root>/my-work/repo-v2":true}},
+ "transcript · cwd mentioned in text only": {"isProjectTranscript":true,"cwdOf":null,"cwdOfCutShort":null,"belongs":{"<root>/my work/repo.v2":true,"<root>/my work/repo.v2/sub dir":false,"<root>/linked-work":true,"<root>/my work/repo.v2/":true,"/elsewhere":false,"<root>/my-work/repo-v2":true}},
+ "transcript · no final newline": {"isProjectTranscript":true,"cwdOf":"<root>/my work/repo.v2","cwdOfCutShort":null,"belongs":{"<root>/my work/repo.v2":true,"<root>/my work/repo.v2/sub dir":false,"<root>/linked-work":true,"<root>/my work/repo.v2/":true,"/elsewhere":false,"<root>/my-work/repo-v2":true}},
+ "transcript · empty": {"isProjectTranscript":true,"cwdOf":null,"cwdOfCutShort":null,"belongs":{"<root>/my work/repo.v2":true,"<root>/my work/repo.v2/sub dir":false,"<root>/linked-work":true,"<root>/my work/repo.v2/":true,"/elsewhere":false,"<root>/my-work/repo-v2":true}},
+ "transcript · past one read": {"isProjectTranscript":true,"cwdOf":"<root>/my work/repo.v2","cwdOfCutShort":null,"belongs":{"<root>/my work/repo.v2":true,"<root>/my work/repo.v2/sub dir":false,"<root>/linked-work":true,"<root>/my work/repo.v2/":true,"/elsewhere":false,"<root>/my-work/repo-v2":true}},
+ "transcript · missing": {"isProjectTranscript":true,"cwdOf":null,"cwdOfCutShort":null,"belongs":{"<root>/my work/repo.v2":true,"<root>/my work/repo.v2/sub dir":false,"<root>/linked-work":true,"<root>/my work/repo.v2/":true,"/elsewhere":false,"<root>/my-work/repo-v2":true}},
+ "transcript · a character across reads": {"cwdOf":"<root>/café ✓"},
+ "transcript · outside a project directory": {"isProjectTranscript":false,"cwdOf":null},
+ "directory names": {"/":"-","/a b/c.d":"-a-b-c-d","/a_b-c":"-a-b-c","relative/x":"relative-x","/café":"-caf-","C:\\x\\y":"C--x-y","":""},
+ "no rule · codex": null,
+ "no rule · cursor": null,
+ "no rule · opencode": null,
+ "no rule · pi": null,
+ "no rule · hermes": null,
+ "no rule · commandcode": null,
+ "no rule · devin": null,
+ "no rule · muse": null,
+ "no rule · amp": null,
+ "no rule · kilo": null,
+ "no rule · grok": null,
+ "no rule · agy": null,
+ "no rule · copilot": null,
+ "repair · a drifted claude row": {"folder":"<root>/my work/repo.v2","logged":[]},
+ "repair · a claude row at home": {"folder":null,"logged":[]},
+ "repair · a claude row through a link": {"folder":null,"logged":[]},
+ "repair · a claude row whose transcript names none": {"folder":null,"logged":["[repair] abcdef01 cwd <root>/my work/repo.v2/sub dir is not its transcript's project folder, and the transcript names no matching folder — left as is"]},
+ "repair · a claude row whose transcript is elsewhere": {"folder":null,"logged":[]},
+ "repair · a claude row with no transcript": {"folder":null,"logged":[]},
+ "repair · a claude row with no cwd": {"folder":null,"logged":[]},
+ "repair · a codex row": {"folder":null,"logged":[]},
+ "repair · a terminal row": {"folder":null,"logged":[]}
+},
+"linux": {
+"process": {
+
+},
+"argv": {
+
+},
+"grid": {
+
+},
+"profile": {
+
+},
+"project": {
+
+}
+}
+}
diff --git a/cli/src/engines/claude/discoveryContract.ts b/cli/src/engines/claude/discoveryContract.ts
new file mode 100644
index 000000000..7c3988894
--- /dev/null
+++ b/cli/src/engines/claude/discoveryContract.ts
@@ -0,0 +1,26 @@
+import type { DiscoveryContract } from '../facets/discovery.js'
+
+/**
+ * Claude Code's discovery, declared: data only, which core applies with the kit (engines/discoveries.ts).
+ * Copied from the former tables of lib/tmux.ts, its claudeNativeInstallPath, and lib/claudeProject.ts.
+ */
+export const discovery: DiscoveryContract = {
+ process: {
+ basenames: [/^claude$/],
+ entrypoints: [/@anthropic-ai[\/\\]claude-code[\/\\]cli\.js$/],
+ // The native installer exposes `~/.local/bin/claude` as a symlink to a binary named only by its version
+ // (`~/.local/share/claude/versions/2.1.246`). During early startup both `comm` and argv[0] can still
+ // name that target, before Claude rewrites either one to `claude`.
+ versionedInstall: '.local/share/claude/versions',
+ },
+ // `--fork-session` writes a NEW session, so that argv names the PARENT and must not bind.
+ resumeArgs: { flags: ['--resume', '-r'], id: /^[0-9a-f-]{16,}$/i, unless: ['--fork-session'] },
+ /**
+ * Claude writes `<projects>/<mangled launch dir>/<sessionId>.jsonl` and never moves the file: a session
+ * resumed or forked from elsewhere still lives, and keeps writing, under the folder it was first started
+ * in. A line's `cwd` follows every Bash `cd`, so it is the folder only when it maps to the file's own
+ * directory name. The mangling is lossy, but exact in one direction. The scan cap is for the
+ * pathological file, since this can run while an engine is blocked on its startup hook.
+ */
+ projectFolder: { mangle: /[^A-Za-z0-9]/g, with: '-', marker: '-', field: 'cwd', scanBytes: 2 * 1024 * 1024 },
+}
diff --git a/cli/src/engines/codex/discoveryContract.ts b/cli/src/engines/codex/discoveryContract.ts
new file mode 100644
index 000000000..ffeab76af
--- /dev/null
+++ b/cli/src/engines/codex/discoveryContract.ts
@@ -0,0 +1,23 @@
+import type { DiscoveryContract } from '../facets/discovery.js'
+
+/**
+ * Codex's discovery, declared: data only, which core applies with the kit (engines/discoveries.ts). Copied
+ * from the former tables of lib/tmux.ts and lib/gridAssignment.ts, and lib/codexHomeProbe.ts.
+ */
+export const discovery: DiscoveryContract = {
+ process: {
+ basenames: [/^codex$/, /^codex-(?:aarch64|x86_64)-(?:apple-darwin|unknown-linux-(?:gnu|musl))$/],
+ entrypoints: [/@openai[\/\\]codex[\/\\]bin[\/\\]codex(?:\.js)?$/],
+ },
+ // `codex fork <id>` never matched `resume`: a fork's id is its parent's.
+ resumeArgs: { flags: ['resume'], id: /^[0-9a-f-]{16,}$/i },
+ // Codex omits `-m` when no model was picked.
+ modelInArgv: true,
+ /**
+ * A codex pane the daemon did not create (started by hand, or a row discovery had to mint again) has no
+ * profile carried from `agent_create`. Its transcript lives under `<CODEX_HOME>/sessions`, so without this
+ * the hook's transcript path fails validation against the default profile and session repair scans the
+ * wrong root.
+ */
+ profile: { variable: 'CODEX_HOME', setting: 'CODEX_HOME' },
+}
diff --git a/cli/src/engines/discoveries.ts b/cli/src/engines/discoveries.ts
new file mode 100644
index 000000000..7842a8f27
--- /dev/null
+++ b/cli/src/engines/discoveries.ts
@@ -0,0 +1,86 @@
+/**
+ * What discovery reads off an engine's process and transcripts, composed from each engine's declared
+ * discovery contract (engines/{claude,codex}/discoveryContract.ts) and the kit's mechanics, so the discovery
+ * pass (lib/tmux.ts, lib/terminalAgentDiscovery.ts), the registry and the start-up repair name no engine.
+ * All of it runs in core, in line: binding a session never waits on an engine worker.
+ */
+import { env } from '../config/env.js'
+import { readProcessEnv } from '../lib/processEnv.js'
+import type { ProcessIdentity } from '../lib/registry.js'
+import { discovery as claude } from './claude/discoveryContract.js'
+import { discovery as codex } from './codex/discoveryContract.js'
+import type { DiscoveryContract } from './facets/discovery.js'
+import { profileFromEnv, versionedInstallMatcher } from './kit/processFacts.js'
+import { isProjectTranscript, projectDirectoryName, projectMatches, transcriptFolder } from './kit/projectFolder.js'
+import type { AgentEngine } from './types.js'
+
+export const discoveryContracts = { claude, codex } satisfies Record<string, DiscoveryContract>
+type MigratedEngine = keyof typeof discoveryContracts
+
+/** An engine's discovery contract, for an engine that declares one. */
+export function discoveryContract(engine: AgentEngine | string): DiscoveryContract | undefined {
+ return Object.hasOwn(discoveryContracts, engine) ? discoveryContracts[engine as MigratedEngine] : undefined
+}
+
+/** Compatibility tables take their migrated entries from the same contract. */
+export function discoveryField<K extends keyof DiscoveryContract>(key: K): Record<MigratedEngine, DiscoveryContract[K]> {
+ return Object.fromEntries(Object.entries(discoveryContracts).map(([name, contract]) => [name, contract[key]])) as Record<MigratedEngine, DiscoveryContract[K]>
+}
+
+/** The engines whose contract says `key`. */
+export function enginesDeclaring(key: 'modelInArgv'): AgentEngine[] {
+ return (Object.keys(discoveryContracts) as MigratedEngine[]).filter((engine) => discoveryContracts[engine][key])
+}
+
+/**
+ * Whether a value (an executable or entrypoint) is the engine's native binary named only by its version, for
+ * an engine that declares such an install; undefined for the rest. Compiled once, and looked up as a plain
+ * property: every discovery pass asks this of every process row, for every engine. Measured on a fixed table
+ * of 1,941 processes and 60 panes, two Map lookups per call cost the pass about 4%; this is within noise.
+ */
+export const versionedInstalls: Readonly<Partial<Record<AgentEngine, (value: string) => boolean>>> = Object.fromEntries(
+ Object.entries(discoveryContracts).flatMap(([engine, contract]) =>
+ contract.process.versionedInstall ? [[engine, versionedInstallMatcher(contract.process.versionedInstall)]] : []))
+
+/**
+ * The engine home a process runs under, read off its environment, when it is not this machine's default: a
+ * path, `null` for the default (or an engine with no such profile), never a guess. `defaultHome` overrides
+ * the daemon's own, for a caller that already holds it.
+ */
+export function profileHomeFromEnv(engine: AgentEngine, processEnv: Record<string, string>, defaultHome?: string): string | null {
+ const profile = discoveryContract(engine)?.profile
+ return profile ? profileFromEnv(profile, processEnv, defaultHome ?? env[profile.setting]) : null
+}
+
+/** The same, read from the live process: `undefined` when it could not be read, which never overwrites what
+ * the registry knows. One cached environment read per process, as the grid probe makes. */
+export async function probeProfileHome(identity: ProcessIdentity, engine: AgentEngine): Promise<string | null | undefined> {
+ if (!discoveryContract(engine)?.profile) return null
+ const processEnv = await readProcessEnv(identity)
+ if (!processEnv) return undefined
+ return profileHomeFromEnv(engine, processEnv)
+}
+
+/** Which folder a transcript belongs to, for an engine that keeps transcripts by the folder they began in. */
+export interface TranscriptProject {
+ /** Whether the transcript sits in a project directory at all. */
+ isProjectTranscript(transcriptPath: string): boolean
+ /** Whether `cwd` is the folder this transcript belongs to, as given or as its real path. */
+ belongs(cwd: string, transcriptPath: string): boolean
+ /** The folder the transcript names for itself, read from it; null when it names none. */
+ cwdOf(transcriptPath: string, limit?: number): string | null
+ /** The project directory's name for a folder. */
+ directoryOf(cwd: string): string
+}
+
+/** The project-folder rule of `engine`'s transcripts; null for an engine with no such rule. */
+export function transcriptProject(engine: AgentEngine | string): TranscriptProject | null {
+ const rule = discoveryContract(engine)?.projectFolder
+ if (!rule) return null
+ return {
+ isProjectTranscript: (transcriptPath) => isProjectTranscript(rule, transcriptPath),
+ belongs: (cwd, transcriptPath) => projectMatches(rule, cwd, transcriptPath),
+ cwdOf: (transcriptPath, limit) => transcriptFolder(rule, transcriptPath, limit),
+ directoryOf: (cwd) => projectDirectoryName(rule, cwd),
+ }
+}
diff --git a/cli/src/engines/discovery.golden.spec.ts b/cli/src/engines/discovery.golden.spec.ts
new file mode 100644
index 000000000..bdb2cae2d
--- /dev/null
+++ b/cli/src/engines/discovery.golden.spec.ts
@@ -0,0 +1,327 @@
+/**
+ * What discovery reads off a process and a transcript, answer for answer, recorded from the code as it stood
+ * before Claude Code's and Codex's discovery specifics became declared data applied by the kit
+ * (docs/design/2026-10-08-engine-launch.md, (c3)):
+ *
+ * - a corpus of process rows (native names, platform builds, npm and bun entrypoints, Claude's versioned
+ * native install, help probes, Windows paths, decoys and every other engine's) against every engine:
+ * the match score and its evidence, and whether the row is an unresolved `agent`;
+ * - argv against every engine: the session id it resumes, and the permission mode and approval it names;
+ * - a grid launch's argv and environment: the model it was pointed at;
+ * - a process environment: the profile home it runs under;
+ * - Claude Code transcripts: whether one sits in a project directory, which folder it belongs to, the folder
+ * it names for itself (past one read, a character across reads, a limit), and the folder a row with a
+ * drifted cwd is put back in at start-up.
+ *
+ * Every rule here runs on every discovery pass, or as the registry loads. Each case runs with `process.platform`
+ * pinned to darwin and to linux, whichever machine runs the spec, and linux's are stored where they differ.
+ *
+ * `RECORD_DISCOVERY_GOLDEN=1` writes the fixture. Record it again only for a change meant to alter what
+ * discovery finds, and say so in that change.
+ */
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { env } from '../config/env.js'
+import { repairedCwd } from '../lib/cwdRepair.js'
+import type { AgentCommandOwnershipSnapshot } from '../lib/engineBin.js'
+import { classifyGridAssignment } from '../lib/gridAssignment.js'
+import type { RegisteredSession } from '../lib/registry.js'
+import { ambiguousAgentProcess, bypassPermissionActive, engineProcessMatch, permissionModeFromArgv, resumeSessionId, type ProcessRow } from '../lib/tmux.js'
+import { profileHomeFromEnv, transcriptProject } from './discoveries.js'
+import { ENGINES, PROCESS_ENGINES } from './types.js'
+
+const GOLDEN = fileURLToPath(new URL('./__fixtures__/discovery.golden.json', import.meta.url))
+const RECORD = process.env.RECORD_DISCOVERY_GOLDEN === '1'
+
+/** No engine installed as far as file identity goes: the rules alone decide. */
+const OWNERSHIP: AgentCommandOwnershipSnapshot = {
+ cursorFileKeys: new Set(), grokFileKeys: new Set(), conflictingFileKeys: new Set(),
+ agentCandidates: [], cursorAgentCandidates: [], grokCandidates: [],
+}
+const ENGINE_PATHS = ['CLAUDE_PATH', 'CURSOR_PATH', 'OPENCODE_PATH', 'PI_PATH', 'HERMES_PATH', 'COMMANDCODE_PATH', 'DEVIN_PATH', 'MUSE_PATH',
+ 'AMP_PATH', 'KILO_PATH', 'GROK_PATH', 'AGY_PATH', 'COPILOT_PATH'] as const
+const config = env as unknown as Record<string, string | undefined>
+const saved: Record<string, string | undefined> = {}
+let root = ''
+
+beforeAll(() => {
+ root = realpathSync(mkdtempSync(join(tmpdir(), 'discovery-golden-')))
+ for (const name of ENGINE_PATHS) { saved[name] = config[name]; config[name] = undefined }
+ saved.CODEX_PATH = process.env.CODEX_PATH
+ delete process.env.CODEX_PATH
+})
+afterAll(() => {
+ for (const name of ENGINE_PATHS) config[name] = saved[name]
+ if (saved.CODEX_PATH !== undefined) process.env.CODEX_PATH = saved.CODEX_PATH
+ rmSync(root, { recursive: true, force: true })
+})
+
+const UUID = '01234567-89ab-cdef-0123-456789abcdef'
+
+// ------------------------------------------------------------------------------------------- process rows
+
+const EXECUTABLES = [
+ 'claude', 'Claude', 'CLAUDE', 'claude-helper', 'claudex', '/usr/local/bin/claude', '/opt/homebrew/bin/claude',
+ '/opt/home/.local/share/claude/versions/2.1.246', '/opt/home/.local/share/Claude/versions/2.1.246', '2.1.246',
+ '/opt/claude/versions/2.1.246', '/opt/home/.local/share/claude/versions/2.1.246/extra', 'C:\\home\\.local\\share\\claude\\versions\\2.1.2',
+ 'codex', 'Codex', 'codex-aarch64-apple-darwin', 'codex-x86_64-unknown-linux-musl', 'codex-x86_64-unknown-linux-gnu',
+ 'codex-x86_64-pc-windows-msvc', 'codex-arm64-apple-darwin', '/opt/homebrew/bin/codex', 'codexa',
+ 'node', 'bun', 'python3', 'bash', 'zsh', 'agent', 'cursor-agent', 'opencode', 'pi', 'hermes', 'cmd', 'muse', 'amp', 'kilo',
+ 'grok', 'agy', 'copilot', 'devin',
+]
+const ARGS: Array<(exe: string) => string> = [
+ (exe) => exe,
+ (exe) => `${exe} --resume ${UUID}`,
+ (exe) => `${exe} resume ${UUID}`,
+ (exe) => `${exe} --help`,
+ (exe) => `${exe} --version`,
+]
+const ENTRYPOINT_ROWS: Array<Pick<ProcessRow, 'executable' | 'args'>> = [
+ { executable: 'node', args: 'node /opt/lib/node_modules/@anthropic-ai/claude-code/cli.js' },
+ { executable: 'node', args: `node /opt/lib/node_modules/@anthropic-ai/claude-code/cli.js --resume ${UUID}` },
+ { executable: 'node', args: 'node --require /opt/x.js /opt/lib/node_modules/@anthropic-ai/claude-code/cli.js' },
+ { executable: 'node', args: 'node C:\\npm\\node_modules\\@anthropic-ai\\claude-code\\cli.js' },
+ { executable: 'node', args: 'node /opt/lib/node_modules/@anthropic-ai/claude-code/cli.js --help' },
+ { executable: 'node', args: 'node /opt/lib/node_modules/@anthropic-ai/claude-code/cli.mjs' },
+ { executable: 'node', args: 'node /opt/lib/node_modules/@openai/codex/bin/codex.js' },
+ { executable: 'node', args: `node /opt/lib/node_modules/@openai/codex/bin/codex.js --no-daemon resume ${UUID}` },
+ { executable: 'node', args: 'node /opt/lib/node_modules/@openai/codex/bin/codex' },
+ { executable: 'node', args: 'node C:\\npm\\node_modules\\@openai\\codex\\bin\\codex.js' },
+ { executable: 'node', args: 'node /opt/lib/node_modules/@openai/codex/bin/codex.js --help' },
+ { executable: 'node', args: 'node /opt/lib/node_modules/@openai/codex-sdk/bin/codex.js' },
+ { executable: 'bun', args: 'bun /opt/.bun/install/global/node_modules/@openai/codex/bin/codex.js' },
+ { executable: 'node', args: 'node -e "require(\'@openai/codex/bin/codex.js\')"' },
+ { executable: 'node', args: 'node /opt/lib/node_modules/@github/copilot/npm-loader.js' },
+ { executable: 'node', args: 'node /opt/cursor-agent/versions/2026.1/index.js' },
+ { executable: 'python3', args: 'python3 /opt/hermes-agent/hermes' },
+ { executable: 'claude', args: 'claude -p "summarise" --output-format json' },
+ { executable: '/opt/home/.local/share/claude/versions/2.1.246', args: `/opt/home/.local/share/claude/versions/2.1.246 --resume ${UUID}` },
+ { executable: 'node', args: '/opt/home/.local/share/claude/versions/2.1.246 --resume x' },
+ { executable: 'bash', args: 'bash -c claude' },
+ { executable: 'zsh', args: 'zsh -lic . /tmp/launch.sh harness-engine /work claude --resume x' },
+ { executable: 'agent', args: 'agent' },
+ { executable: 'codex', args: 'codex app-server --managed-daemon' },
+]
+
+function processCases(): Record<string, unknown> {
+ const rows: Array<Pick<ProcessRow, 'executable' | 'args'>> = [
+ ...EXECUTABLES.flatMap((exe) => ARGS.map((args) => ({ executable: exe, args: args(exe) }))),
+ ...ENTRYPOINT_ROWS,
+ ]
+ const cases: Record<string, unknown> = {}
+ for (const row of rows) {
+ const key = `${row.executable} · ${row.args}`
+ const matched = Object.fromEntries(ENGINES.flatMap((engine) => {
+ const match = engineProcessMatch(row, engine, OWNERSHIP)
+ return match.score > 0 ? [[engine, `${match.score} ${match.evidence}`]] : []
+ }))
+ cases[key] = { matched, ambiguous: ambiguousAgentProcess(row, OWNERSHIP) }
+ }
+ return cases
+}
+
+// ------------------------------------------------------------------------------------------------- argv
+
+const ARGV = [
+ 'claude', `claude --resume ${UUID}`, `claude -r ${UUID}`, `claude --resume=${UUID}`, `claude --RESUME ${UUID}`, `claude -R ${UUID}`,
+ `claude --resume ${UUID.toUpperCase()}`, `claude --resume ${UUID} --fork-session`, `claude --fork-session --resume ${UUID}`,
+ `claude --resume "${UUID}"`, 'claude --resume 0123456789abcde', 'claude --resume 0123456789abcdef', `claude --resume ${UUID}`,
+ `claude --resume\t${UUID}`, 'claude --resume my-session-name', `claude -p "--resume ${UUID}"`, `claude --continue`,
+ `codex resume ${UUID}`, `codex --no-daemon resume ${UUID}`, `codex resume --last`, `codex fork ${UUID}`, `codex resume=${UUID}`,
+ `codex --approve-for-me resume ${UUID}`, `codex exec "resume ${UUID}"`, 'codex resume 0123',
+ `node /opt/codex.js resume ${UUID}`, `cursor-agent --resume ${UUID}`, `opencode --session ses_abc123 --fork`, `opencode -s ses_abc123`,
+ `pi --session ${UUID}`, 'hermes --resume 20260728_115628_f2c86a', 'devin -r brisk-otter', 'amp threads continue T-0123456789abcdef01',
+ 'claude --permission-mode auto', 'claude --permission-mode acceptEdits', 'claude --permission-mode=plan', 'claude --dangerously-skip-permissions',
+ 'claude --dangerously-skip-permissions --permission-mode auto', 'claude -p "--dangerously-skip-permissions"',
+ 'codex --approve-for-me', 'codex --sandbox read-only', 'codex --dangerously-bypass-approvals-and-sandbox', 'codex --sandbox=read-only',
+]
+
+function argvCases(): Record<string, unknown> {
+ const cases: Record<string, unknown> = {}
+ for (const args of ARGV) {
+ cases[args] = Object.fromEntries(ENGINES.flatMap((engine) => {
+ const resumed = resumeSessionId(engine, args)
+ const mode = permissionModeFromArgv(engine, args)
+ const approves = bypassPermissionActive(engine, args)
+ return resumed || mode || approves ? [[engine, { resumed, mode, approves }]] : []
+ }))
+ }
+ return cases
+}
+
+// ------------------------------------------------------------------------------------------- grid model
+
+const RELAY = 'https://grid.example/relay/v1'
+function gridCases(): Record<string, unknown> {
+ const shapes: Array<[string, Record<string, string>, string]> = [
+ ['argv with a model', {}, `codex -c model_providers.grid.base_url="${RELAY}" -m gpt-5`],
+ ['argv, unquoted url', {}, `codex -c model_providers.grid.base_url=${RELAY} -m gpt-5`],
+ ['argv, no model', {}, `codex -c model_providers.grid.base_url="${RELAY}"`],
+ ['argv, the router', {}, `grok -c model_providers.grid.base_url="${RELAY}" -m Auto`],
+ ['argv, a model in a prompt', {}, `codex -c model_providers.grid.base_url="${RELAY}" "-m nope"`],
+ ['argv, not a relay', {}, 'codex -c model_providers.x.base_url="https://api.openai.com/v1" -m gpt-5'],
+ ['environment', { ANTHROPIC_BASE_URL: RELAY, ANTHROPIC_MODEL: 'qwen', OPENAI_BASE_URL: RELAY, OPENAI_MODEL: 'qwen' }, 'claude -m other'],
+ ['nothing', {}, 'codex -m gpt-5'],
+ ]
+ const cases: Record<string, unknown> = {}
+ for (const [name, environment, args] of shapes) {
+ cases[name] = Object.fromEntries(ENGINES.flatMap((engine) => {
+ const found = classifyGridAssignment(engine, environment, args)
+ return found ? [[engine, found]] : []
+ }))
+ }
+ return cases
+}
+
+// ---------------------------------------------------------------------------------------------- profiles
+
+function profileCases(): Record<string, unknown> {
+ const real = join(root, 'codex-real')
+ mkdirSync(real, { recursive: true })
+ if (!existsSync(join(root, 'codex-link'))) symlinkSync(real, join(root, 'codex-link'))
+ const shapes: Record<string, [Record<string, string>, string | undefined]> = {
+ 'unset': [{}, '/daemon/.codex'],
+ 'the default': [{ CODEX_HOME: '/daemon/.codex' }, '/daemon/.codex'],
+ 'another profile': [{ CODEX_HOME: '/profiles/work' }, '/daemon/.codex'],
+ 'the default through a link': [{ CODEX_HOME: join(root, 'codex-link') }, real],
+ 'the default with a trailing dot': [{ CODEX_HOME: join(real, '.') }, real],
+ 'relative': [{ CODEX_HOME: 'relative/codex' }, '/daemon/.codex'],
+ 'a control character': [{ CODEX_HOME: '/bad\nline' }, '/daemon/.codex'],
+ 'DEL': [{ CODEX_HOME: '/bad\x7fdel' }, '/daemon/.codex'],
+ 'too long': [{ CODEX_HOME: `/${'x'.repeat(4096)}` }, '/daemon/.codex'],
+ 'just long enough': [{ CODEX_HOME: `/${'x'.repeat(4095)}` }, '/daemon/.codex'],
+ 'empty': [{ CODEX_HOME: '' }, '/daemon/.codex'],
+ 'the daemon\'s own default': [{ CODEX_HOME: '/profiles/other' }, undefined],
+ 'another engine\'s variable': [{ CLAUDE_CONFIG_DIR: '/profiles/claude' }, '/daemon/.codex'],
+ }
+ const cases: Record<string, unknown> = {}
+ for (const [name, [environment, defaultHome]] of Object.entries(shapes)) {
+ cases[name] = Object.fromEntries(ENGINES.flatMap((engine) => {
+ const found = profileHomeFromEnv(engine, environment, defaultHome)
+ return found !== null ? [[engine, found.split(root).join('<root>')]] : []
+ }))
+ }
+ return cases
+}
+
+// ---------------------------------------------------------------------------------- transcript projects
+
+function projectCases(): Record<string, unknown> {
+ const project = transcriptProject('claude')!
+ const work = join(root, 'my work', 'repo.v2')
+ const sub = join(work, 'sub dir')
+ mkdirSync(sub, { recursive: true })
+ if (!existsSync(join(root, 'linked-work'))) symlinkSync(work, join(root, 'linked-work'))
+ const projects = join(root, 'projects')
+ const dir = join(projects, project.directoryOf(work))
+ mkdirSync(dir, { recursive: true })
+ const line = (cwd: unknown, extra: Record<string, unknown> = {}) => JSON.stringify({ type: 'user', cwd, ...extra })
+ const files: Record<string, string | Buffer> = {
+ 'first line': `${line(work)}\n`,
+ 'drifted first, then home': `${line(sub)}\n${line('/tmp')}\n${line(work)}\n`,
+ 'no matching line': `${line(sub)}\n${line('/elsewhere')}\n`,
+ 'a cwd that is not text': `${line(42)}\n${line(null)}\n${line(work)}\n`,
+ 'invalid JSON lines': `{"cwd": broken\n${line(work)}\n`,
+ 'cwd mentioned in text only': `${JSON.stringify({ type: 'assistant', text: `"cwd":"${work}"` })}\n`,
+ 'no final newline': line(work),
+ 'empty': '',
+ 'past one read': `${line(sub, { pad: 'é'.repeat(40_000) })}\n${line(work)}\n`,
+ }
+ for (const [name, text] of Object.entries(files)) writeFileSync(join(dir, `${name}.jsonl`), text)
+ // A three-byte character across the first 64 KiB read, in the line that names the folder.
+ const unicodeWork = join(root, 'caf\u00e9 \u2713')
+ mkdirSync(unicodeWork, { recursive: true })
+ const unicodeDir = join(projects, project.directoryOf(unicodeWork))
+ mkdirSync(unicodeDir, { recursive: true })
+ const head = `${line(sub, { pad: 'a'.repeat(65_536 - 40) })}\n`
+ writeFileSync(join(unicodeDir, 'split.jsonl'), `${head}${line(unicodeWork)}\n`)
+ const outside = join(root, 'not-a-project', 'x.jsonl')
+ mkdirSync(join(root, 'not-a-project'), { recursive: true })
+ writeFileSync(outside, `${line(work)}\n`)
+ const norm = (value: unknown): unknown => JSON.parse(JSON.stringify(value).split(project.directoryOf(root)).join('<mangled-root>').split(root).join('<root>'))
+
+ const cases: Record<string, unknown> = {}
+ for (const name of [...Object.keys(files), 'missing']) {
+ const path = join(dir, `${name}.jsonl`)
+ cases[`transcript · ${name}`] = norm({
+ isProjectTranscript: project.isProjectTranscript(path),
+ cwdOf: project.cwdOf(path),
+ // A read cap shorter than the line that names the folder finds nothing. 16 bytes ends inside any line's
+ // `{"cwd":"…` on every host; 100 ended inside it only where the temp root is long (macOS), not on Linux CI.
+ cwdOfCutShort: project.cwdOf(path, 16),
+ belongs: Object.fromEntries([work, sub, join(root, 'linked-work'), `${work}/`, '/elsewhere', join(root, 'my-work', 'repo-v2')]
+ .map((cwd) => [cwd.split(root).join('<root>'), project.belongs(cwd, path)])),
+ })
+ }
+ cases['transcript · a character across reads'] = norm({ cwdOf: project.cwdOf(join(unicodeDir, 'split.jsonl')) })
+ cases['transcript · outside a project directory'] = norm({ isProjectTranscript: project.isProjectTranscript(outside), cwdOf: project.cwdOf(outside) })
+ cases['directory names'] = norm(Object.fromEntries(['/', '/a b/c.d', '/a_b-c', 'relative/x', '/caf\u00e9', 'C:\\x\\y', ''].map((cwd) => [cwd, project.directoryOf(cwd)])))
+ for (const engine of PROCESS_ENGINES.filter((name) => name !== 'claude')) cases[`no rule · ${engine}`] = transcriptProject(engine)
+
+ // The start-up repair of a row whose cwd drifted from its transcript's folder.
+ const row = (over: Partial<RegisteredSession>): RegisteredSession => ({ agentId: 'abcdef0123456789', engine: 'claude', cwd: sub, transcriptPath: join(dir, 'first line.jsonl'), ...over }) as RegisteredSession
+ const rows: Record<string, RegisteredSession> = {
+ 'a drifted claude row': row({}),
+ 'a claude row at home': row({ cwd: work }),
+ 'a claude row through a link': row({ cwd: join(root, 'linked-work') }),
+ 'a claude row whose transcript names none': row({ transcriptPath: join(dir, 'no matching line.jsonl') }),
+ 'a claude row whose transcript is elsewhere': row({ transcriptPath: outside }),
+ 'a claude row with no transcript': row({ transcriptPath: null }),
+ 'a claude row with no cwd': row({ cwd: '' }),
+ 'a codex row': row({ engine: 'codex' }),
+ 'a terminal row': row({ engine: 'terminal' }),
+ }
+ for (const [name, value] of Object.entries(rows)) {
+ const logged: string[] = []
+ cases[`repair · ${name}`] = norm({ folder: repairedCwd(value, (message) => logged.push(message)), logged })
+ }
+ return cases
+}
+
+type Sections = Record<string, Record<string, unknown>>
+const PLATFORMS = ['darwin', 'linux'] as const
+
+/** Every section, with `process.platform` reading `platform`. */
+function sectionsOn(platform: (typeof PLATFORMS)[number]): Sections {
+ const real = Object.getOwnPropertyDescriptor(process, 'platform')!
+ Object.defineProperty(process, 'platform', { ...real, value: platform })
+ try {
+ return { process: processCases(), argv: argvCases(), grid: gridCases(), profile: profileCases(), project: projectCases() }
+ } finally { Object.defineProperty(process, 'platform', real) }
+}
+
+describe('discovery finds what it did before Claude Code and Codex declared it', () => {
+ it('process rows, argv, grid models, profiles and transcript projects match the record, on darwin and linux', () => {
+ const darwin = sectionsOn('darwin')
+ const linux = sectionsOn('linux')
+ const linuxDiffers = Object.fromEntries(Object.entries(linux).map(([section, cases]) => [section,
+ Object.fromEntries(Object.entries(cases).filter(([key, value]) => JSON.stringify(value) !== JSON.stringify(darwin[section]![key])))]))
+ if (RECORD) {
+ const block = (cases: Record<string, unknown>): string => Object.entries(cases).map(([key, value]) => ` ${JSON.stringify(key)}: ${JSON.stringify(value)}`).join(',\n')
+ const sections = (all: Sections): string => Object.entries(all).map(([section, cases]) => `${JSON.stringify(section)}: {\n${block(cases)}\n}`).join(',\n')
+ writeFileSync(GOLDEN, `{\n${sections(darwin)},\n"linux": {\n${sections(linuxDiffers)}\n}\n}\n`)
+ return
+ }
+ const { linux: linuxGolden, ...darwinGolden } = JSON.parse(readFileSync(GOLDEN, 'utf8')) as Sections & { linux: Sections }
+ for (const [platform, actual, golden] of [
+ ['darwin', darwin, darwinGolden],
+ ['linux', linux, Object.fromEntries(Object.entries(darwinGolden).map(([section, cases]) => [section, { ...cases, ...linuxGolden[section] }]))],
+ ] as const) {
+ expect(Object.keys(actual), platform).toEqual(Object.keys(golden))
+ for (const [section, cases] of Object.entries(golden)) {
+ expect(Object.keys(actual[section]!).sort(), `${platform} · ${section}`).toEqual(Object.keys(cases).sort())
+ for (const [key, value] of Object.entries(cases)) expect(actual[section]![key], `${platform} · ${section} · ${key}`).toEqual(value)
+ }
+ }
+ })
+
+ it('records no machine-specific path', () => {
+ const text = readFileSync(GOLDEN, 'utf8')
+ expect(text).not.toContain('discovery-golden-')
+ expect(text).not.toContain(root)
+ expect(text).not.toMatch(/\/Users\/|\/home\/runner/)
+ })
+})
diff --git a/cli/src/engines/facets/discovery.ts b/cli/src/engines/facets/discovery.ts
new file mode 100644
index 000000000..660ea4a53
--- /dev/null
+++ b/cli/src/engines/facets/discovery.ts
@@ -0,0 +1,40 @@
+import type { FolderSetting } from './hooks.js'
+
+/**
+ * How core recognises an engine's process and reads its facts off argv, environment and transcript paths.
+ * Declared data, applied in core by the kit (kit/processFacts.ts, kit/projectFolder.ts) on every discovery
+ * pass, as the registry loads and at start-up. Session binding never waits on an engine worker
+ * (docs/design/2026-10-08-engine-launch.md, (c3)).
+ */
+export interface DiscoveryContract {
+ process: {
+ /** Vendor-supported native names, matched against the executable's and the entrypoint's basenames. */
+ basenames: readonly RegExp[]
+ /** Launcher and package entrypoints, independent of install prefix. */
+ entrypoints: readonly RegExp[]
+ /**
+ * A native install whose binary is named only by its version, in a folder of versions at this path
+ * (lowercase, `/`-separated, under any prefix). Never a bare version: an unrelated process called
+ * `2.1.246` is not evidence.
+ */
+ versionedInstall?: string
+ }
+ /**
+ * How the engine names an existing session on its command line: the flags, what its ids look like (a
+ * filter: a flag that takes a name must not register a title), and the flags under which the named id is
+ * a parent's (a fork writes a new session) and must not bind.
+ */
+ resumeArgs: { flags: readonly string[]; id: RegExp; unless?: readonly string[] }
+ /** A grid launch writes the model into argv as `-m <model>`. */
+ modelInArgv?: boolean
+ /** The engine home a process carries in `variable` when launched under a profile, and the setting naming
+ * this machine's default. */
+ profile?: { variable: string; setting: FolderSetting }
+ /**
+ * Transcripts kept by the folder the session began in, `<root>/<folder's directory name>/<id>`, never
+ * moved: the directory name is the folder with every character `mangle` matches replaced by `with`, and
+ * starts with `marker` (as every absolute folder's does). A transcript names its folder on a line whose
+ * `field` maps to the directory's name, within the first `scanBytes`.
+ */
+ projectFolder?: { mangle: RegExp; with: string; marker: string; field: string; scanBytes: number }
+}
diff --git a/cli/src/lib/codexHomeProbe.spec.ts b/cli/src/engines/kit/processFacts.spec.ts
similarity index 74%
rename from cli/src/lib/codexHomeProbe.spec.ts
rename to cli/src/engines/kit/processFacts.spec.ts
index 362739adf..449a22ccd 100644
--- a/cli/src/lib/codexHomeProbe.spec.ts
+++ b/cli/src/engines/kit/processFacts.spec.ts
@@ -2,7 +2,12 @@ import { describe, expect, it } from 'vitest'
import { mkdtempSync, rmSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
-import { codexHomeFromEnv } from './codexHomeProbe.js'
+import type { AgentEngine } from '../types.js'
+import { profileHomeFromEnv } from '../discoveries.js'
+
+// The former lib/codexHomeProbe.spec.ts, its cases unchanged, against Codex's declared profile (`profile` in
+// codex/discoveryContract.ts) applied by the kit, through the composition discovery calls.
+const codexHomeFromEnv = (engine: AgentEngine, processEnv: Record<string, string>, defaultHome?: string) => profileHomeFromEnv(engine, processEnv, defaultHome)
describe('codexHomeFromEnv', () => {
const DEFAULT = '/home/u/.codex'
diff --git a/cli/src/engines/kit/processFacts.ts b/cli/src/engines/kit/processFacts.ts
new file mode 100644
index 000000000..357220bd8
--- /dev/null
+++ b/cli/src/engines/kit/processFacts.ts
@@ -0,0 +1,35 @@
+/**
+ * Facts read off a live process, as an engine's discovery contract declares them (facets/discovery.ts).
+ * Moved from lib/tmux.ts (Claude's native install) and lib/codexHomeProbe.ts, whose every answer this
+ * reproduces (engines/discovery.golden.spec.ts). Read on every discovery pass, so a declaration is compiled
+ * once, not per row.
+ */
+import { realpathSync } from 'node:fs'
+import { isAbsolute } from 'node:path'
+import type { DiscoveryContract } from '../facets/discovery.js'
+
+const escape = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+/**
+ * Whether a path is a binary in the declared folder of versions, under any prefix, whatever its separators
+ * and case. Compiled once per declaration.
+ */
+export function versionedInstallMatcher(path: string): (value: string) => boolean {
+ const pattern = new RegExp(`(?:^|/)${escape(path)}/[^/]+$`)
+ return (value) => pattern.test(value.replace(/\\/g, '/').toLowerCase())
+}
+
+function canonical(path: string): string {
+ try { return realpathSync(path) } catch { return path }
+}
+
+/**
+ * The profile home a process carries in its environment, when it is not the machine's default: a path,
+ * or `null` for the default, an unset variable, or one that is relative, too long or holds a control
+ * character (never a guess). Compared through real paths, as the same folder may be named two ways.
+ */
+export function profileFromEnv(profile: NonNullable<DiscoveryContract['profile']>, processEnv: Record<string, string>, defaultHome: string): string | null {
+ const home = processEnv[profile.variable]
+ if (!home || !isAbsolute(home) || home.length > 4096 || /[\x00-\x1f\x7f]/.test(home)) return null
+ return canonical(home) === canonical(defaultHome) ? null : home
+}
diff --git a/cli/src/lib/claudeProject.spec.ts b/cli/src/engines/kit/projectFolder.spec.ts
similarity index 89%
rename from cli/src/lib/claudeProject.spec.ts
rename to cli/src/engines/kit/projectFolder.spec.ts
index 9c76e4bde..1715b06db 100644
--- a/cli/src/lib/claudeProject.spec.ts
+++ b/cli/src/engines/kit/projectFolder.spec.ts
@@ -2,7 +2,15 @@ import { describe, it, expect, afterEach } from 'vitest'
import { mkdtempSync, mkdirSync, rmSync, symlinkSync, writeFileSync, realpathSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
-import { claudeProjectMatches, claudeTranscriptCwd, isClaudeProjectTranscript, mangleClaudeProjectDir } from './claudeProject.js'
+import { transcriptProject } from '../discoveries.js'
+
+// The former lib/claudeProject.spec.ts, its cases unchanged, against Claude Code's declared rule (`projectFolder` in
+// claude/discoveryContract.ts) applied by the kit, through the composition the registry and repair call.
+const claude = transcriptProject('claude')!
+const mangleClaudeProjectDir = claude.directoryOf
+const claudeProjectMatches = claude.belongs
+const claudeTranscriptCwd = (transcriptPath: string, limit?: number) => claude.cwdOf(transcriptPath, limit)
+const isClaudeProjectTranscript = claude.isProjectTranscript
const dirs: string[] = []
const scratch = (): string => { const d = mkdtempSync(join(tmpdir(), 'claude-project-')); dirs.push(d); return d }
diff --git a/cli/src/engines/kit/projectFolder.ts b/cli/src/engines/kit/projectFolder.ts
new file mode 100644
index 000000000..8ab074eef
--- /dev/null
+++ b/cli/src/engines/kit/projectFolder.ts
@@ -0,0 +1,85 @@
+/**
+ * Which folder a transcript belongs to, for an engine that keeps transcripts by the folder they began in
+ * (facets/discovery.ts `projectFolder`). Moved from lib/claudeProject.ts, whose every answer this reproduces
+ * (engines/discovery.golden.spec.ts).
+ *
+ * The registry's `cwd` is where a resume, restore or restart `cd`s before exec'ing the engine, so it must be
+ * the folder the transcript belongs to, not wherever the shell last went. These answer that from the
+ * transcript's location alone: the mapping is lossy, but exact in one direction, so a cwd either maps to the
+ * directory name or it does not.
+ */
+import { closeSync, openSync, readSync, realpathSync } from 'node:fs'
+import { basename, dirname } from 'node:path'
+import { StringDecoder } from 'node:string_decoder'
+import type { DiscoveryContract } from '../facets/discovery.js'
+
+type Rule = NonNullable<DiscoveryContract['projectFolder']>
+
+/** The project directory's name for a folder. */
+export function projectDirectoryName(rule: Rule, cwd: string): string {
+ return cwd.replace(rule.mangle, rule.with)
+}
+
+/** Whether the transcript sits in a project directory at all: a spec's temp dir or another engine's layout
+ * does not, and is never read. */
+export function isProjectTranscript(rule: Rule, transcriptPath: string): boolean {
+ return basename(dirname(transcriptPath)).startsWith(rule.marker)
+}
+
+/** Whether `cwd` is the folder this transcript belongs to. Checked as given and as its real path: the
+ * transcript carries `process.cwd()` (physical, `/private/tmp/…`) while a row written from a picker may say
+ * `/tmp/…`. */
+export function projectMatches(rule: Rule, cwd: string, transcriptPath: string): boolean {
+ const project = basename(dirname(transcriptPath))
+ if (projectDirectoryName(rule, cwd) === project) return true
+ try { return projectDirectoryName(rule, realpathSync(cwd)) === project } catch { return false }
+}
+
+/**
+ * The folder a transcript belongs to, read from the transcript: the first line whose folder field maps to
+ * the file's own directory name. Null when no line does within the scan cap (an old transcript whose folder
+ * was renamed since), when the file cannot be read, or when it is not in a project directory. Exact by
+ * construction: a fork copies its source's history, and a `/clear` rotation can open on a drifted line, and
+ * both still resolve to the directory the file lives in.
+ */
+export function transcriptFolder(rule: Rule, transcriptPath: string, limit = rule.scanBytes): string | null {
+ if (!isProjectTranscript(rule, transcriptPath)) return null
+ const project = basename(dirname(transcriptPath))
+ let fd: number
+ try { fd = openSync(transcriptPath, 'r') } catch { return null }
+ try {
+ const chunk = Buffer.allocUnsafe(64 * 1024)
+ // A multi-byte character split across two chunks must not become U+FFFD: a cwd with one in it
+ // would then fail to match on exactly the line that named the folder.
+ const decoder = new StringDecoder('utf8')
+ let carry = ''
+ let read = 0
+ while (read < limit) {
+ let n: number
+ try { n = readSync(fd, chunk, 0, Math.min(chunk.length, limit - read), read) } catch { return null }
+ if (n <= 0) break
+ read += n
+ const text = carry + decoder.write(chunk.subarray(0, n))
+ const lines = text.split('\n')
+ carry = lines.pop() ?? ''
+ for (const line of lines) {
+ const cwd = lineFolder(rule, line, project)
+ if (cwd) return cwd
+ }
+ }
+ carry += decoder.end()
+ return carry ? lineFolder(rule, carry, project) : null
+ } finally {
+ closeSync(fd)
+ }
+}
+
+function lineFolder(rule: Rule, line: string, project: string): string | null {
+ // Cheap reject before parsing: most lines (tool results, assistant text) are large and carry the folder
+ // only as one field among many; the ones without the key never need JSON.parse.
+ if (!line.includes(`"${rule.field}"`)) return null
+ let record: unknown
+ try { record = JSON.parse(line) } catch { return null }
+ const cwd = (record as Record<string, unknown> | null)?.[rule.field]
+ return typeof cwd === 'string' && cwd && projectDirectoryName(rule, cwd) === project ? cwd : null
+}
diff --git a/cli/src/lib/claudeProject.ts b/cli/src/lib/claudeProject.ts
deleted file mode 100644
index f9614a51c..000000000
--- a/cli/src/lib/claudeProject.ts
+++ /dev/null
@@ -1,91 +0,0 @@
-/**
- * Which folder a Claude Code transcript belongs to.
- *
- * Claude writes `{CLAUDE_PROJECTS_DIR}/<mangled launch dir>/<sessionId>.jsonl` (see paths.ts) and never
- * moves the file: a session resumed or forked from elsewhere still lives, and keeps writing, under the
- * folder it was first started in. The `cwd` on each transcript LINE is something else — the session's
- * tracked shell directory, which follows every Bash `cd` — so a line's cwd can name a subfolder, a
- * sibling repo or a temp dir while the file's own directory still says where the project is.
- *
- * The registry's `cwd` is where a resume, restore or restart `cd`s before exec'ing the engine, so it
- * must be the folder the transcript belongs to, not wherever the shell last went. These helpers answer
- * that from the transcript's location alone: the mangling is lossy, but exact in one direction, so a
- * cwd either round-trips to the directory name or it does not.
- */
-import { closeSync, openSync, readSync, realpathSync } from 'node:fs'
-import { basename, dirname } from 'node:path'
-import { StringDecoder } from 'node:string_decoder'
-
-/** Claude's project directory name for a folder: every non-alphanumeric character becomes `-`. */
-export function mangleClaudeProjectDir(cwd: string): string {
- return cwd.replace(/[^A-Za-z0-9]/g, '-')
-}
-
-/** Whether the transcript sits in a Claude project directory at all. A mangled absolute path always
- * starts with `-`; a spec's temp dir or another engine's layout does not, and is never read. */
-export function isClaudeProjectTranscript(transcriptPath: string): boolean {
- return basename(dirname(transcriptPath)).startsWith('-')
-}
-
-/** Whether `cwd` is the folder this transcript belongs to. Checked as given and as its real path: the
- * transcript carries `process.cwd()` (physical, `/private/tmp/…`) while a row written from a picker
- * may say `/tmp/…`. */
-export function claudeProjectMatches(cwd: string, transcriptPath: string): boolean {
- const project = basename(dirname(transcriptPath))
- if (mangleClaudeProjectDir(cwd) === project) return true
- try { return mangleClaudeProjectDir(realpathSync(cwd)) === project } catch { return false }
-}
-
-/** How much of a transcript is read looking for its folder. The matching line is on the first few lines
- * of every file seen so far; the cap is for the pathological one, since this can run while an engine
- * is blocked on its startup hook. */
-export const CLAUDE_TRANSCRIPT_SCAN_BYTES = 2 * 1024 * 1024
-
-/**
- * The folder a transcript belongs to, read from the transcript: the first line whose `cwd` mangles to
- * the file's own directory name. Null when no line does within the scan cap (an old transcript whose
- * folder was renamed since), when the file cannot be read, or when it is not in a Claude project
- * directory. Exact by construction — a fork copies its source's history, and a `/clear` rotation can
- * open on a drifted line, and both still resolve to the directory the file lives in.
- */
-export function claudeTranscriptCwd(transcriptPath: string, limit = CLAUDE_TRANSCRIPT_SCAN_BYTES): string | null {
- if (!isClaudeProjectTranscript(transcriptPath)) return null
- const project = basename(dirname(transcriptPath))
- let fd: number
- try { fd = openSync(transcriptPath, 'r') } catch { return null }
- try {
- const chunk = Buffer.allocUnsafe(64 * 1024)
- // A multi-byte character split across two chunks must not become U+FFFD: a cwd with one in it
- // would then fail to match on exactly the line that named the folder.
- const decoder = new StringDecoder('utf8')
- let carry = ''
- let read = 0
- while (read < limit) {
- let n: number
- try { n = readSync(fd, chunk, 0, Math.min(chunk.length, limit - read), read) } catch { return null }
- if (n <= 0) break
- read += n
- const text = carry + decoder.write(chunk.subarray(0, n))
- const lines = text.split('\n')
- carry = lines.pop() ?? ''
- for (const line of lines) {
- const cwd = lineCwd(line, project)
- if (cwd) return cwd
- }
- }
- carry += decoder.end()
- return carry ? lineCwd(carry, project) : null
- } finally {
- closeSync(fd)
- }
-}
-
-function lineCwd(line: string, project: string): string | null {
- // Cheap reject before parsing: most lines (tool results, assistant text) are large and carry a cwd
- // only as one field among many; the ones without the key never need JSON.parse.
- if (!line.includes('"cwd"')) return null
- let record: unknown
- try { record = JSON.parse(line) } catch { return null }
- const cwd = (record as { cwd?: unknown } | null)?.cwd
- return typeof cwd === 'string' && cwd && mangleClaudeProjectDir(cwd) === project ? cwd : null
-}
diff --git a/cli/src/lib/codexHomeProbe.ts b/cli/src/lib/codexHomeProbe.ts
deleted file mode 100644
index ad1b28f96..000000000
--- a/cli/src/lib/codexHomeProbe.ts
+++ /dev/null
@@ -1,39 +0,0 @@
-/**
- * Which Codex profile a live `codex` process was launched under, read off its environment.
- *
- * The registry's `codexHome` is chosen at `agent_create` and carried forward — but a codex pane the
- * daemon did not create (started by hand, or a row discovery had to mint again) has nothing to carry.
- * Its transcript lives under `<CODEX_HOME>/sessions`, so without this the hook's transcript path fails
- * `validTranscriptPath` against the default profile and session repair scans the wrong root. Same
- * cached env read `probeGridAssignment` uses: one `ps` per process for its whole life.
- *
- * Three answers, same contract as the grid probe: a path when the process runs under a non-default
- * profile, `null` when it runs under the machine's default (or CODEX_HOME is unset), and `undefined`
- * when the process could not be read — which must never overwrite what the registry already knows.
- */
-
-import { realpathSync } from 'node:fs'
-import { isAbsolute } from 'node:path'
-import { env } from '../config/env.js'
-import type { AgentEngine } from '../engines/types.js'
-import { readProcessEnv } from './processEnv.js'
-import type { ProcessIdentity } from './registry.js'
-
-function canonical(path: string): string {
- try { return realpathSync(path) } catch { return path }
-}
-
-/** Pure half, for specs and for callers that already hold the environment. */
-export function codexHomeFromEnv(engine: AgentEngine, processEnv: Record<string, string>, defaultHome = env.CODEX_HOME): string | null {
- if (engine !== 'codex') return null
- const home = processEnv.CODEX_HOME
- if (!home || !isAbsolute(home) || home.length > 4096 || /[\x00-\x1f\x7f]/.test(home)) return null
- return canonical(home) === canonical(defaultHome) ? null : home
-}
-
-export async function probeCodexHome(identity: ProcessIdentity, engine: AgentEngine): Promise<string | null | undefined> {
- if (engine !== 'codex') return null
- const processEnv = await readProcessEnv(identity)
- if (!processEnv) return undefined
- return codexHomeFromEnv(engine, processEnv)
-}
diff --git a/cli/src/lib/cwdRepair.spec.ts b/cli/src/lib/cwdRepair.spec.ts
index 51a4a3765..a36900eab 100644
--- a/cli/src/lib/cwdRepair.spec.ts
+++ b/cli/src/lib/cwdRepair.spec.ts
@@ -30,7 +30,7 @@ function transcript(project: string, sessionId: string, cwds: string[]): string
async function fixture() {
const { registry } = await import('./registry.js')
const { StoppedAgentStore } = await import('./stoppedAgents.js')
- const { repairClaudeCwd } = await import('./cwdRepair.js')
+ const { repairProjectCwds: repairClaudeCwd } = await import('./cwdRepair.js')
const store = new StoppedAgentStore(join(directory, 'stopped-agents'))
const project = join(directory, 'repo')
mkdirSync(join(project, 'cli'), { recursive: true })
@@ -48,7 +48,7 @@ async function fixture() {
return { registry, store, repairClaudeCwd, project, open, bind, logs, log: (m: string) => { logs.push(m) } }
}
-describe('repairClaudeCwd', () => {
+describe('repairProjectCwds (Claude Code rows)', () => {
it('moves drifted live and archived rows to their transcript folder, leaves the rest alone, and is idempotent', async () => {
const { registry, store, repairClaudeCwd, project, open, bind, logs, log } = await fixture()
// Drifted: the row says the subfolder, the transcript lives under the project and names it on line 3.
diff --git a/cli/src/lib/cwdRepair.ts b/cli/src/lib/cwdRepair.ts
index a8c6a33b2..90429992a 100644
--- a/cli/src/lib/cwdRepair.ts
+++ b/cli/src/lib/cwdRepair.ts
@@ -1,5 +1,6 @@
/**
- * Put Claude rows back in the folder their transcript belongs to.
+ * Put rows back in the folder their transcript belongs to, for an engine that keeps transcripts by the folder
+ * they began in (Claude Code: `projectFolder` in its discovery contract, engines/discoveries.ts).
*
* Until `register` stopped taking the hook's cwd on every prompt (registry.ts), a Claude row's `cwd`
* followed the session's shell into whatever subfolder, sibling repo or temp dir the agent last
@@ -8,7 +9,7 @@
* the corrected code would still relaunch them in the wrong place. So it puts them right first, before
* `restoreAgents` recreates a single pane.
*
- * The proof is the transcript's own location (claudeProject.ts): a row whose cwd does not round-trip to
+ * The proof is the transcript's own location (engines/kit/projectFolder.ts): a row whose cwd does not round-trip to
* the project directory its transcript lives in is moved to the folder the transcript names. A row whose
* transcript names no such folder (renamed since; a bridge file with no cwd line) is left alone and said
* so, once per boot. Cheap and idempotent — only mismatching rows read a transcript, and a repaired row
@@ -16,7 +17,7 @@
* keep.
*/
import type { RegisteredSession } from './registry.js'
-import { claudeProjectMatches, claudeTranscriptCwd, isClaudeProjectTranscript } from './claudeProject.js'
+import { transcriptProject } from '../engines/discoveries.js'
export interface CwdRepairDeps {
registry: {
@@ -36,9 +37,10 @@ export interface CwdRepairSummary { registry: number; archived: number }
/** The folder a row should be in, or null when the row is fine or nothing can prove otherwise. */
export function repairedCwd(row: RegisteredSession, log: (message: string) => void): string | null {
- if (row.engine !== 'claude' || !row.cwd || !row.transcriptPath || !isClaudeProjectTranscript(row.transcriptPath)) return null
- if (claudeProjectMatches(row.cwd, row.transcriptPath)) return null
- const folder = claudeTranscriptCwd(row.transcriptPath)
+ const project = transcriptProject(row.engine)
+ if (!project || !row.cwd || !row.transcriptPath || !project.isProjectTranscript(row.transcriptPath)) return null
+ if (project.belongs(row.cwd, row.transcriptPath)) return null
+ const folder = project.cwdOf(row.transcriptPath)
if (!folder) {
log(`[repair] ${row.agentId.slice(0, 8)} cwd ${row.cwd} is not its transcript's project folder, and the transcript names no matching folder — left as is`)
return null
@@ -46,7 +48,7 @@ export function repairedCwd(row: RegisteredSession, log: (message: string) => vo
return folder === row.cwd ? null : folder
}
-export async function repairClaudeCwd(deps: CwdRepairDeps): Promise<CwdRepairSummary> {
+export async function repairProjectCwds(deps: CwdRepairDeps): Promise<CwdRepairSummary> {
const summary: CwdRepairSummary = { registry: 0, archived: 0 }
// Folders proved so far, by agent: what a transcript-less fork (its history lives in the source's
// file, not one of its own) inherits from the row it was forked from.
@@ -54,7 +56,7 @@ export async function repairClaudeCwd(deps: CwdRepairDeps): Promise<CwdRepairSum
const forks: RegisteredSession[] = []
const inherit = (row: RegisteredSession): string | null => {
const source = row.forkedFrom?.agentId
- if (!source || row.transcriptPath || row.engine !== 'claude' || !row.cwd) return null
+ if (!source || row.transcriptPath || !transcriptProject(row.engine) || !row.cwd) return null
const folder = proved.get(source)
return folder && folder !== row.cwd ? folder : null
}
diff --git a/cli/src/lib/gridAssignment.ts b/cli/src/lib/gridAssignment.ts
index 106f15a7a..f1374d3e8 100644
--- a/cli/src/lib/gridAssignment.ts
+++ b/cli/src/lib/gridAssignment.ts
@@ -21,6 +21,7 @@
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'
import type { AgentEngine } from '../engines/types.js'
+import { enginesDeclaring } from '../engines/discoveries.js'
import { anthropicBaseUrl, GRID_ROUTER_MODEL, relayBaseUrl } from './gridLaunch.js'
import { readProcessEnv } from './processEnv.js'
import type { ProcessIdentity } from './registry.js'
@@ -52,13 +53,14 @@ const MODEL_VAR: Partial<Record<AgentEngine, string>> = {
}
/**
- * Engines whose model was written into argv as `-m <model>` rather than an environment variable.
+ * Engines whose model was written into argv as `-m <model>` rather than an environment variable: Codex's
+ * discovery contract declares it (`modelInArgv`).
*
* Codex omits the flag when no model was picked; grok always carries one, because its grid credential
* rides on a declared model block and "let the grid route" is therefore spelled `-m Auto` rather than
* by leaving the flag off. [classifyGridAssignment] maps that id back to null.
*/
-const MODEL_IN_ARGV = new Set<AgentEngine>(['codex', 'grok'])
+const MODEL_IN_ARGV = new Set<AgentEngine>([...enginesDeclaring('modelInArgv'), 'grok'])
/**
* Pi's endpoint is in neither its environment nor its argv — it is in the `models.json` inside the
diff --git a/cli/src/lib/registry.ts b/cli/src/lib/registry.ts
index 3be2fd093..0a3a9dcfa 100644
--- a/cli/src/lib/registry.ts
+++ b/cli/src/lib/registry.ts
@@ -17,7 +17,7 @@ import { DSH_ID_RE } from '../dsh/id.js'
import { AGENT_NAME_RE } from './engineLaunch.js'
import { resumesConversation } from './resumeCapability.js'
import { namingTitle } from './sessionTitle.js'
-import { claudeProjectMatches, claudeTranscriptCwd, isClaudeProjectTranscript } from './claudeProject.js'
+import { transcriptProject } from '../engines/discoveries.js'
import { automaticAgentName, engineLabel, isAutomaticName } from './agentNames.js'
import {
closeSync,
@@ -1595,11 +1595,13 @@ class Registry {
// Even a first bind can carry a drifted cwd (a fork inherits its source's; `claude --resume` typed
// from a subfolder). Claude's transcript never moves from the project dir it was started in, so a
// cwd that does not round-trip to that directory name is not this session's folder — the row's own
- // is kept when it does, else the transcript names the folder itself (claudeProject.ts).
- const cwd = !sameSession && engine === 'claude' && effectiveTranscriptPath && input.cwd
- && isClaudeProjectTranscript(effectiveTranscriptPath) && !claudeProjectMatches(input.cwd, effectiveTranscriptPath)
- ? (existing?.cwd && claudeProjectMatches(existing.cwd, effectiveTranscriptPath) ? existing.cwd
- : claudeTranscriptCwd(effectiveTranscriptPath) ?? input.cwd)
+ // is kept when it does, else the transcript names the folder itself (`projectFolder` in Claude Code's
+ // discovery contract, engines/kit/projectFolder.ts).
+ const project = !sameSession && effectiveTranscriptPath && input.cwd ? transcriptProject(engine) : null
+ const cwd = project && effectiveTranscriptPath && input.cwd
+ && project.isProjectTranscript(effectiveTranscriptPath) && !project.belongs(input.cwd, effectiveTranscriptPath)
+ ? (existing?.cwd && project.belongs(existing.cwd, effectiveTranscriptPath) ? existing.cwd
+ : project.cwdOf(effectiveTranscriptPath) ?? input.cwd)
: baseCwd
const entry: RegisteredSession = {
schemaVersion: 2,
diff --git a/cli/src/lib/terminalAgentDiscovery.codexHome.spec.ts b/cli/src/lib/terminalAgentDiscovery.codexHome.spec.ts
index 5b1ae8254..dba49b475 100644
--- a/cli/src/lib/terminalAgentDiscovery.codexHome.spec.ts
+++ b/cli/src/lib/terminalAgentDiscovery.codexHome.spec.ts
@@ -7,17 +7,17 @@ import type { TerminalRootObservation, TerminalRuntimeRef } from './terminalType
* The Codex profile a process runs under rides the LIVE discovery path, pinned the same way `grid`
* is in `terminalAgentDiscovery.grid.spec.ts`: a probe wired on the wrong function stays green while
* every discovered codex row arrives with `codexHome` undefined — and its transcript then fails
- * validation against the default profile. `codexHomeProbe.spec.ts` covers what the probe reads.
+ * validation against the default profile. `engines/kit/processFacts.spec.ts` covers what the probe reads.
*/
const probeGatewayRuntime = vi.hoisted(() => vi.fn())
const probeGridAssignment = vi.hoisted(() => vi.fn())
-const probeCodexHome = vi.hoisted(() => vi.fn())
+const probeProfileHome = vi.hoisted(() => vi.fn())
const processRows = vi.hoisted(() => vi.fn())
vi.mock('./gatewayRuntime.js', () => ({ probeGatewayRuntime }))
vi.mock('./gridAssignment.js', () => ({ probeGridAssignment }))
-vi.mock('./codexHomeProbe.js', () => ({ probeCodexHome }))
+vi.mock('../engines/discoveries.js', async (real) => ({ ...await real<object>(), probeProfileHome }))
vi.mock('./tmux.js', async (importOriginal) => ({
...await importOriginal<typeof import('./tmux.js')>(),
processRows,
@@ -41,14 +41,14 @@ beforeEach(() => {
probeGatewayRuntime.mockResolvedValue({ kind: null })
probeGridAssignment.mockReset()
probeGridAssignment.mockResolvedValue(null)
- probeCodexHome.mockReset()
+ probeProfileHome.mockReset()
processRows.mockReset()
})
describe('Codex profile on the live terminal discovery path', () => {
it('reports the profile off the process, and the probe decides for every engine', async () => {
processRows.mockResolvedValue([row(10, 1, 'bash'), row(30, 10, 'codex'), row(20, 1, 'bash'), row(40, 20, 'claude')])
- probeCodexHome.mockImplementation(async (_identity: unknown, engine: string) => engine === 'codex' ? '/home/u/.codex-work' : null)
+ probeProfileHome.mockImplementation(async (_identity: unknown, engine: string) => engine === 'codex' ? '/home/u/.codex-work' : null)
const probe = await probeTerminalAgents(
[backendWith([{ runtime: TMUX_RUNTIME, rootPid: 10, cwd: '/work' }, { runtime: OTHER_RUNTIME, rootPid: 20, cwd: '/work' }])],
['tmux'],
@@ -56,13 +56,13 @@ describe('Codex profile on the live terminal discovery path', () => {
)
const byEngine = Object.fromEntries(probe.agents.map((agent) => [agent.engine, agent.codexHome]))
expect(byEngine).toEqual({ codex: '/home/u/.codex-work', claude: null })
- expect(probeCodexHome).toHaveBeenCalledTimes(2)
- for (const [identity] of probeCodexHome.mock.calls) expect(identity).toMatchObject({ startMarker: START })
+ expect(probeProfileHome).toHaveBeenCalledTimes(2)
+ for (const [identity] of probeProfileHome.mock.calls) expect(identity).toMatchObject({ startMarker: START })
})
it('passes an unreadable probe through as undefined, so the registry keeps what it knew', async () => {
processRows.mockResolvedValue([row(10, 1, 'bash'), row(30, 10, 'codex')])
- probeCodexHome.mockResolvedValue(undefined)
+ probeProfileHome.mockResolvedValue(undefined)
const probe = await probeTerminalAgents([backendWith([{ runtime: TMUX_RUNTIME, rootPid: 10, cwd: '/work' }])], ['tmux'], 999)
expect(probe.agents[0]).toHaveProperty('codexHome', undefined)
})
diff --git a/cli/src/lib/terminalAgentDiscovery.ts b/cli/src/lib/terminalAgentDiscovery.ts
index 7b5d5fe4f..6220f7aa3 100644
--- a/cli/src/lib/terminalAgentDiscovery.ts
+++ b/cli/src/lib/terminalAgentDiscovery.ts
@@ -7,7 +7,7 @@ import {
} from './engineBin.js'
import { probeGatewayRuntime } from './gatewayRuntime.js'
import { probeGridAssignment, type GridAssignment } from './gridAssignment.js'
-import { probeCodexHome } from './codexHomeProbe.js'
+import { probeProfileHome } from '../engines/discoveries.js'
import { probeHermesHome } from '../engines/hermes/homeProbe.js'
import { probeDsh } from '../dsh/probe.js'
import type { TerminalBackend } from './terminalBackend.js'
@@ -57,7 +57,7 @@ export interface DiscoveredTerminalAgent {
/**
* Codex only: the CODEX_HOME profile the process was launched under, when it is not this machine's
* default. null = the default profile (or not Codex); undefined = the probe could not read the
- * process, and the registry keeps what it already knows. See `codexHomeProbe.ts`.
+ * process, and the registry keeps what it already knows. See `probeProfileHome` (engines/discoveries.ts).
*/
codexHome?: string | null
/**
@@ -263,7 +263,7 @@ export async function probeTerminalAgents(
// Same process, same cached read — the grid costs no extra `ps`.
agent.grid = await probeGridAssignment(agent.processIdentity, agent.engine, agent.args)
// And, for Codex, the profile it runs under — a fact about the process the row cannot otherwise learn.
- agent.codexHome = await probeCodexHome(agent.processIdentity, agent.engine)
+ agent.codexHome = await probeProfileHome(agent.processIdentity, agent.engine)
// …and, for Hermes, the home — same cached read, and it beats looking the session up in every store.
agent.hermesHome = await probeHermesHome(agent.processIdentity, agent.engine)
// And the DSH it was created as — same read, so a pane the daemon did not create is labelled too.
diff --git a/cli/src/lib/tmux.ts b/cli/src/lib/tmux.ts
index 25894ac5d..68dd1315f 100644
--- a/cli/src/lib/tmux.ts
+++ b/cli/src/lib/tmux.ts
@@ -16,6 +16,7 @@ import {
} from './engineBin.js'
import { BYPASS_PERMISSION_FLAGS, PERMISSION_MODES, permissionModeApproves } from './engineLaunch.js'
import { ENGINE_EXIT_PANE_OPTION } from './engineExitOption.js'
+import { discoveryField, versionedInstalls } from '../engines/discoveries.js'
import { psEnv } from './childLocale.js'
import { processStartTicks } from './processLiveness.js'
import { nativeProcessImages } from './nativeProcessImages.js'
@@ -641,34 +642,15 @@ function commTruncatedPrefixOf(seen: string, want: string): boolean {
return Buffer.byteLength(seen) === 15 && want.length > seen.length && want.startsWith(seen)
}
-/**
- * Claude's native installer exposes `~/.local/bin/claude` as a symlink to a binary whose basename is
- * only its version (`~/.local/share/claude/versions/2.1.246`). During early startup both `comm` and
- * argv[0] can still contain that target path, before Claude rewrites either one to `claude`.
- *
- * Match the vendor-specific install layout, never a bare semver: an unrelated process called
- * `2.1.246` is not evidence that Claude is running.
- */
-function claudeNativeInstallPath(value: string): boolean {
- const normalized = value.replace(/\\/g, '/').toLowerCase()
- return /(?:^|\/)\.local\/share\/claude\/versions\/[^/]+$/.test(normalized)
-}
-
interface EngineProcessSignature {
basenames: readonly RegExp[]
entrypoints: readonly RegExp[]
}
-/** Vendor-supported native names and launcher/package entrypoints, independent of install prefix. */
+/** Vendor-supported native names and launcher/package entrypoints, independent of install prefix. Claude Code's
+ * and Codex's are their discovery contracts' (engines/discoveries.ts). */
export const ENGINE_PROCESS_SIGNATURES: Readonly<Record<RegisteredSession['engine'], EngineProcessSignature>> = {
- claude: {
- basenames: [/^claude$/],
- entrypoints: [/@anthropic-ai[\/\\]claude-code[\/\\]cli\.js$/],
- },
- codex: {
- basenames: [/^codex$/, /^codex-(?:aarch64|x86_64)-(?:apple-darwin|unknown-linux-(?:gnu|musl))$/],
- entrypoints: [/@openai[\/\\]codex[\/\\]bin[\/\\]codex(?:\.js)?$/],
- },
+ ...discoveryField('process'),
cursor: {
basenames: [/^cursor-agent$/],
entrypoints: [/cursor-agent[\/\\]versions[\/\\][^/\\]+[\/\\]index\.js$/],
@@ -754,8 +736,9 @@ function heuristicEngineProcessMatchScore(
if (signature.basenames.some((pattern) => pattern.test(executable) || pattern.test(entrybase))) return 3
if (signature.entrypoints.some((pattern) => pattern.test(entrypoint))) return 2
- // Native Claude exposes a version-only target; only the vendor layout makes that name meaningful.
- if (engine === 'claude' && (claudeNativeInstallPath(row.executable) || claudeNativeInstallPath(entrypoint))) return 3
+ // A native binary named only by its version (Claude Code's): only the vendor layout makes that name meaningful.
+ const versioned = versionedInstalls[engine]
+ if (versioned && (versioned(row.executable) || versioned(entrypoint))) return 3
if (engine === 'cursor') {
return agentAliasOwner([row.imageFileKey, row.entrypointFileKey], ownership) === 'cursor' ? 4 : 0
@@ -884,10 +867,11 @@ function selectEngineProcess(
*
* The id pattern is a filter, not decoration: `-r` on Command Code takes "a name (use quotes for
* multi-word names)", so a title would otherwise be registered as a session id.
+ *
+ * Claude Code's and Codex's entries are their discovery contracts' (`resumeArgs`, engines/discoveries.ts).
*/
-const RESUME_ARGS: Partial<Record<RegisteredSession['engine'], { flags: string[]; id: RegExp; unless?: string[] }>> = {
- claude: { flags: ['--resume', '-r'], id: /^[0-9a-f-]{16,}$/i, unless: ['--fork-session'] },
- codex: { flags: ['resume'], id: /^[0-9a-f-]{16,}$/i },
+const RESUME_ARGS: Partial<Record<RegisteredSession['engine'], { flags: readonly string[]; id: RegExp; unless?: readonly string[] }>> = {
+ ...discoveryField('resumeArgs'),
cursor: { flags: ['--resume'], id: /^[0-9a-f-]{16,}$/i },
// `--fork` continues from the id but writes a NEW session, so the id in argv is the parent's.
opencode: { flags: ['--session', '-s'], id: /^ses_[A-Za-z0-9]+$/, unless: ['--fork'] },
diff --git a/cli/src/startupOrder.spec.ts b/cli/src/startupOrder.spec.ts
index f8d5e750a..50219aca3 100644
--- a/cli/src/startupOrder.spec.ts
+++ b/cli/src/startupOrder.spec.ts
@@ -84,7 +84,7 @@ function callArguments(source: string, call: string): { text: string; at: number
}
/** Every call whose dependencies run DURING start-up, before `runForeground` has finished its body. */
-const STARTUP_CALLS = ['await repairClaudeCwd({', 'await restoreAgents({']
+const STARTUP_CALLS = ['await repairProjectCwds({', 'await restoreAgents({']
/** What the prologue is allowed to do before the master's update is listened for: nothing that can throw. */
const PROLOGUE_CALLS = new Set(['installTimestampedConsole'])
diff --git a/docs/design/2026-10-08-engine-launch.md b/docs/design/2026-10-08-engine-launch.md
index 5a834015f..8ffc17797 100644
--- a/docs/design/2026-10-08-engine-launch.md
+++ b/docs/design/2026-10-08-engine-launch.md
@@ -7,7 +7,7 @@ declares what it needs as data on its launch contract (`Engine.launch`, `engines
Shared mechanics in `engines/kit` read that data, and core runs them in line.
(c) is too large to land as one change. It is split into five sub-batches, each green on its own. This
-document records (c1) and (c2), which are done, and plans the other three.
+document records (c1), (c2) and (c3), which are done, and plans the other two.
## (c1) Launch argv and the pane script: done
@@ -171,6 +171,80 @@ lost its own walk (16 lines). **Came in:** `kit/resumeRepair.ts` (259), `kit/fol
They reach no Claude Code or Codex file but the declared contracts and `rollout.ts`, the registry's until (c4).
+## (c3) Discovery and process matching: done
+
+Discovery runs on every pass, as the registry loads and at start-up. A new facet, `DiscoveryContract`
+(`engines/facets/discovery.ts`), declares what core reads off each engine's process and transcripts. Each engine
+declares it in `engines/{claude,codex}/discoveryContract.ts`, and `engines/discoveries.ts` composes what callers use.
+
+| Was | Now |
+| --- | --- |
+| Claude Code's and Codex's rows of `ENGINE_PROCESS_SIGNATURES` in `lib/tmux.ts` | `process.basenames` and `process.entrypoints`, spread into the table for every engine |
+| `claudeNativeInstallPath` in `lib/tmux.ts` | `process.versionedInstall` (`.local/share/claude/versions`), compiled once by `kit/processFacts.ts` and looked up as a plain property |
+| Claude Code's and Codex's rows of `RESUME_ARGS` in `lib/tmux.ts` | `resumeArgs`: the flags, the id's shape, and the flags under which the id is a parent's |
+| `codex` in `lib/gridAssignment.ts` `MODEL_IN_ARGV` | `modelInArgv` |
+| `lib/codexHomeProbe.ts` | `profile`: the variable a process carries and the setting naming the default. `kit/processFacts.ts` `profileFromEnv` reads it; `discoveries.ts` `probeProfileHome` is what the pass calls. |
+| `lib/claudeProject.ts`, and the `engine === 'claude'` checks in `lib/cwdRepair.ts` and `registry.register` | `projectFolder`: how a folder maps to a directory name, the marker, the field and the scan cap. `kit/projectFolder.ts` applies it; `discoveries.ts` `transcriptProject(engine)` is null for an engine with no such rule. `repairClaudeCwd` became `repairProjectCwds`. |
+
+### The same answers
+
+**Golden record.** `engines/discovery.golden.spec.ts` was recorded in its own commit, through a composition of the
+former code. It holds:
+
+- **222 process rows against every engine:** the score and evidence, and whether the row is an unresolved `agent`.
+ The rows cover native names, platform builds, npm and bun entrypoints, Claude's versioned native install and
+ decoys of it, help and version probes, Windows paths, and every other engine's.
+- **43 command lines against every engine:** the session resumed, and the permission mode and approval named.
+- **8 grid launches:** the model.
+- **13 environments:** the profile home.
+- **35 transcript cases:** whether a transcript is in a project directory, which folders it belongs to, the folder
+ it names for itself (past one read, with a character across reads, within a limit), and the start-up repair.
+
+Every case runs with `process.platform` pinned to darwin and to linux, and linux's are stored where they differ
+(none). The spec passes unchanged against the kit, and 12 one-line mutations each fail it:
+
+- Claude's install path, fork flag, resume flags, project marker and folder field;
+- Codex's model rule, profile variable and platform builds;
+- the kit's length bound, separator handling, real-path check and decoder.
+
+The former `claudeProject` and `codexHomeProbe` specs run their cases unchanged against the composition.
+
+### The discovery pass's time
+
+`discoverTerminalAgentsFromSnapshot` was timed on one fixed process table: 1,941 processes, with 60 panes running
+Claude Code (native, npm and the versioned install), Codex (native, npm and a platform build), OpenCode, Cursor, Pi
+and Hermes. Each pane runs helpers below it, and 1,400 unrelated processes sit beside them. The table was built
+once, with no file-identity evidence. Each run made 400 passes after 50 warm-up ones, and five runs alternated
+between the former code and this change on the same machine.
+
+| | Median of run medians | Runs' medians | Runs' minimums |
+| --- | --- | --- | --- |
+| Before (`f6abddcf6`) | 10.14 ms | 9.90 – 10.73 ms | 9.70 – 10.41 ms |
+| After | 10.31 ms | 10.17 – 10.83 ms | 9.91 – 10.50 ms |
+
+The difference, under 2%, is within the runs' spread. A first version that looked the versioned install up in a
+`Map` twice per row and engine cost about 4% in the same comparison, and is not what landed.
+
+### Core closure
+
+| | Lines | Files |
+| --- | --- | --- |
+| Before ((c2)) | 73,370 | 391 |
+| After | 73,488 | 394 |
+
+**Left:** `lib/claudeProject.ts` (92 lines) and `lib/codexHomeProbe.ts` (40). `lib/tmux.ts` is 16 lines shorter.
+**Came in:**
+
+- the two contracts (51 lines of data);
+- `engines/discoveries.ts` (87);
+- `kit/processFacts.ts` (36);
+- `kit/projectFolder.ts` (86).
+
+`architecture.spec.ts` lists the two removed files as edge files. A new closure test checks that the discovery modules
+reach no Claude Code or Codex file except the declared contracts and `rollout.ts`, which the registry holds until (c4):
+`tmux.ts`, `terminalAgentDiscovery.ts`, `gridAssignment.ts`, `cwdRepair.ts`, the registry, the composition and both
+kit modules.
+
## The plan for the rest of (c)
The sub-batches are ordered by risk: pure functions first, then async writes, then the hot and synchronous
@@ -178,8 +252,7 @@ paths. Each one records today's behavior in a golden spec first, in its own comm
| | Scope | Why it is in this place | Golden proof |
| --- | --- | --- | --- |
-| **(c3) Discovery and process matching** | `lib/tmux.ts` process signatures and `RESUME_ARGS`, `claudeNativeInstallPath`, `lib/gridAssignment.ts` `MODEL_IN_ARGV`, `lib/codexHomeProbe.ts`, `lib/claudeProject.ts`, `lib/cwdRepair.ts`, and the moved homes in `lib/engineHomes.ts` (with the `CODEX_HOME` env literal at create and relaunch). | This is static data, but it is read for every process row on every discovery pass, and a wrong answer adopts or drops agents. | A recorded classification of a corpus of process rows: executable, argv, environment → engine, session, bypass, model, home. |
-| **(c4) Registry load and session identity** | The registry's Codex child-rollout repair (`lib/registry.ts` with `engines/codex/rollout.ts`), `lib/sessionRepair.ts` (about 190 of 716 lines), `lib/captureResumeIdentity.ts`, `lib/handoffDiscovery.ts`. | Synchronous, at load before any worker exists, and on the hook path. A wrong answer loses bindings at every restart. It goes after (c3) because it reuses (c3)'s homes. | Recorded transcripts and pid records → binding, session id and repair, read with the same bounds. |
+| **(c4) Registry load and session identity** | The registry's Codex child-rollout repair (`lib/registry.ts` with `engines/codex/rollout.ts`), `lib/sessionRepair.ts` (about 190 of 716 lines), `lib/captureResumeIdentity.ts`, `lib/handoffDiscovery.ts`, and the moved engine homes of `lib/engineHomes.ts` (with the `CODEX_HOME` env literal at create and relaunch), which the registry and session repair read. | Synchronous, at load before any worker exists, and on the hook path. A wrong answer loses bindings at every restart. The moved homes go with it, since the registry and session repair are what read them. | Recorded transcripts and pid records → binding, session id and repair, read with the same bounds. |
| **(c5) Adoption readers and shared normalizers** | `lib/sessionSearch/externals/{claude,codex}.ts`, `lib/transcriptPages.ts`, `lib/transcriptReader.ts` and `lib/transcriptActivity.ts`. Also splitting the functions `engines/claude/normalize.ts` and `engines/codex/{normalizer,subagent}.ts` share with other engines into `engines/kit`. | The largest (1,000 to 2,000 lines) but async. Listing and paging sessions for adoption is not session control. Those readers may run in a worker, as long as adoption fails safe when it is down: refused with a reason, never a wrong session. | The adoption and paging specs, unchanged, plus a recorded corpus of transcripts → pages. |
**Out of (c).** These stay as they are, as tables over every engine:
diff --git a/docs/design/2026-10-08-engine-remaining-facets.md b/docs/design/2026-10-08-engine-remaining-facets.md
index cee3acdba..61147305e 100644
--- a/docs/design/2026-10-08-engine-remaining-facets.md
+++ b/docs/design/2026-10-08-engine-remaining-facets.md
@@ -47,7 +47,9 @@ About 230 lines would leave. Transport, credential, routes and `registry.registe
Split into five sub-batches. See [engine launch](2026-10-08-engine-launch.md), which records (c1) and (c2)
and plans (c3) to (c5). (c1) is done: the Codex pane script's startup probe and retry, its own-login provider,
and the two engines' context and env flags are now declared data, applied by `engines/kit`. (c2) is done too:
-folder trust, the resume repair and the instruction-file fallbacks. Like (b), nothing moved into a worker.
+folder trust, the resume repair and the instruction-file fallbacks. So is (c3): process signatures, resume ids, the
+profile home and the project folder of a transcript, read on every discovery pass. Like (b), nothing moved into a
+worker.
The map below is as it stood before (c1).
| File | Engine-specific behavior | Stays in core | Can move | Risk |
@@ -116,7 +118,7 @@ About 220 lines would leave, and with them core's only native child process and
closure, and a few dozen lines of declared data come in.
4. **(c) Launch, discovery and resume.** The largest. It has the most synchronous call sites (registry
load, discovery tables, argv). It is split by risk into (c1) launch argv and the pane script (done),
- (c2) launch preparation (trust writes and the resume repair, done), (c3) discovery and process matching,
+ (c2) launch preparation (trust writes and the resume repair, done), (c3) discovery and process matching (done),
(c4) registry load and session identity, and (c5) adoption readers and the shared normalizers
([engine launch](2026-10-08-engine-launch.md)). Session control stays worker-free throughout, as in (b).