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.

Speak to Codex's shared app-server from the Codex worker (#1043)

Deeea9656a770bc
diff --git a/cli/AGENTS.md b/cli/AGENTS.md
index 47a150a2a..7a2d65e13 100644
--- a/cli/AGENTS.md
+++ b/cli/AGENTS.md
@@ -25,7 +25,7 @@ they show as `harnessd`, `harnessd-core` and `harnessd-<process>` (`src/harnessd
|---|---|---|
| master | supervision only (`src/harnessd/`) | by `harness start`, `harness start -f`, or launchd or systemd after `harness service install` |
| core | sessions (`src/core/`) | always |
-| engine-claude, engine-codex | history, last-turn readers, live transcript parsers, runtime profiles/catalogs, screen interpretation, submission verification readings, model control and question navigation | on demand: an attach or read for that engine |
+| engine-claude, engine-codex | history, last-turn readers, live transcript parsers, runtime profiles/catalogs, screen interpretation, submission verification readings, model control, question navigation, and (Codex) the shared app-server connection | on demand: an attach or read for that engine |
| search | session search | always |
| viewers | the harness viewers, their remote streams and rendered surfaces, and the Store | always |
| edge | the shell service, workspaces, usage, the monitor, the project readers, the change-agent handoff, the recaps | always |
diff --git a/cli/e2e/engineNativeControl.e2e.ts b/cli/e2e/engineNativeControl.e2e.ts
new file mode 100644
index 000000000..8410f8453
--- /dev/null
+++ b/cli/e2e/engineNativeControl.e2e.ts
@@ -0,0 +1,176 @@
+/**
+ * Codex's shared app-server, spoken to from the Codex worker: a real private daemon, tmux and supervised
+ * workers, an older fake Codex that shares its server (no --no-daemon), and the server's real loopback
+ * WebSocket reached through the fake CLI's raw-byte `app-server proxy` (harness/sharedCodex.ts).
+ */
+import { execFileSync } from 'node:child_process'
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { afterEach, describe, expect, it, onTestFailed } from 'vitest'
+import { LocalClient } from './harness/client.js'
+import { CLI_ROOT, IsolatedDaemon, until, type DaemonOptions } from './harness/daemon.js'
+import { alive, harnessdProcesses } from './harness/endurance.js'
+import { sharedCodex } from './harness/sharedCodex.js'
+
+type Row = Record<string, any>
+const SUPERVISION = { HARNESSD_SERVICE_INITIAL_BACKOFF_MS: '200', HARNESSD_SERVICE_MAX_BACKOFF_MS: '1000',
+ HARNESSD_SERVICE_HEARTBEAT_TIMEOUT_MS: '4000', HARNESSD_SERVICE_STOP_GRACE_MS: '100' }
+const PARKING = { HARNESSD_SERVICE_PARK_CRASHES: '3', HARNESSD_SERVICE_PARK_RETRY_MS: '120000' }
+
+describe('Codex\'s shared server, from the Codex worker', () => {
+ let daemon: IsolatedDaemon | undefined, client: LocalClient | undefined, server: Awaited<ReturnType<typeof sharedCodex>> | undefined
+ afterEach(async () => { client?.close(); await daemon?.close(); await server?.close(); client = undefined; daemon = undefined; server = undefined })
+
+ /** A Codex agent in a held turn. `shared`: an older Codex with no --no-daemon, whose conversation lives on the
+ * fake shared server; otherwise today's, which Harness launches with --no-daemon to own its conversation. */
+ async function fresh(env: DaemonOptions['env'] = {}, shared = true) {
+ const d = daemon = await IsolatedDaemon.create({ env: { ...SUPERVISION, ...env } })
+ onTestFailed(() => console.log(`---- daemon log\n${d.log().split('\n').slice(-200).join('\n')}`))
+ if (shared) writeFileSync(join(d.root, 'bin', 'codex'), `#!${process.execPath}\nimport(${JSON.stringify(pathToFileURL(join(CLI_ROOT, 'e2e/harness/fakeEngine.mjs')).href)}).then(m => m.run('codex', ${JSON.stringify({ ...d.engineConfig, without: ['--no-daemon'] })}))\n`, { mode: 0o755 })
+ const s = server = await sharedCodex(d.engineConfig.codexHome)
+ await d.start()
+ const c = client = await LocalClient.connect(d)
+ const cwd = join(d.projectsDir, 'codex'); mkdirSync(cwd, { recursive: true })
+ const created = await c.request('agent_create', { engine: 'codex', cwd, bypassPermission: true }, 90_000)
+ expect(created.error, JSON.stringify(created)).toBeUndefined()
+ const agent: Row = await until('the conversation to bind', async () =>
+ (await c.request('agents_list', {})).agents.find((row: Row) => row.id === created.agent.id && row.sessionId) ?? null, 60_000, 200)
+ s.state.threadId = agent.sessionId
+ const started = c.next(frame => frame.type === 'turn_started' && frame.agentId === agent.id, 30_000, 'the held turn')
+ c.send('message', { agentId: agent.id, content: '!hold' })
+ await started
+ const count = (method: string, since = 0) => s.state.requests.slice(since).filter(frame => frame.method === method).length
+ const close = () => c.request('agent_close', { agentId: agent.id, sessionId: agent.sessionId, createdAt: agent.createdAt, mode: 'now' }, 90_000)
+ const pane = async () => (await d.tmux.run('display-message', '-p', '-t', agent.tmuxPane, '#{pane_pid}')).trim()
+ return { d, c, s, agent, count, close, pane }
+ }
+
+ /** This daemon's `codex app-server proxy` clients, as the process table shows them, with their parents. */
+ const proxies = (d: IsolatedDaemon) => execFileSync('ps', ['-A', '-o', 'pid=,ppid=,command='], { encoding: 'utf8' }).split('\n')
+ .map(line => /^\s*(\d+)\s+(\d+)\s+(.*)$/.exec(line)).filter((match): match is RegExpExecArray => !!match)
+ .filter(match => match[3].includes(join(d.root, 'bin', 'codex')) && match[3].includes('app-server proxy'))
+ .map(match => ({ pid: Number(match[1]), parent: Number(match[2]) }))
+ // A replacement process, connected to the core: the worker is back, not merely started.
+ const linked = (d: IsolatedDaemon) => d.log().split('[services] engine-codex connected').length - 1
+ const replacement = async (d: IsolatedDaemon, before: number, connections: number) => until('a replacement Codex worker', () => {
+ const pid = harnessdProcesses(d).get('engine-codex')
+ return pid && pid !== before && alive(pid) && linked(d) > connections ? pid : null
+ }, 30_000, 100)
+ /** Killed until the master parks it, as a worker crashing on every start would be. */
+ async function park(d: IsolatedDaemon) {
+ for (let index = 0; index < 3; index++) {
+ const before = harnessdProcesses(d).get('engine-codex')!
+ process.kill(before, 'SIGKILL')
+ if (index < 2) await until('a replacement Codex worker', () => {
+ const pid = harnessdProcesses(d).get('engine-codex')
+ return pid && pid !== before && alive(pid) ? pid : null
+ }, 15_000, 100)
+ }
+ await until('the Codex worker parked', () => d.log().includes('service engine-codex ended 3 times') || null, 60_000, 200)
+ }
+
+ it('reads activity over the worker\'s connection; with that worker killed, a close sent at once still stops the conversation once', async () => {
+ const { d, c, s, agent, count, close } = await fresh()
+ await until('the activity read at the shared server', () => count('thread/read') > 0 || null, 45_000, 100)
+ await until('verified working activity', async () => (await c.request('agents_list', {})).agents.find((row: Row) => row.id === agent.id)?.activity?.state === 'working' || null, 20_000, 200)
+ const core = d.corePid(), worker = harnessdProcesses(d).get('engine-codex')!
+ // The connection is the worker's: its proxy client is the worker's child, never the core's.
+ expect(proxies(d).map(proxy => proxy.parent)).toEqual([worker])
+ expect(s.state.open).toBe(1)
+ process.kill(worker, 'SIGKILL')
+ // Sent before the worker is back: the close's read refused by the restart waits for it and reads again.
+ const before = s.state.requests.length
+ const result = await close()
+ expect(result.error, JSON.stringify(result)).toBeUndefined()
+ for (const method of ['thread/goal/set', 'turn/interrupt', 'thread/archive', 'thread/unarchive']) expect(count(method, before), method).toBe(1)
+ expect(s.state.loaded).toBe(false)
+ expect(s.state.archived).toBe(false)
+ await until('no client of the killed worker left', () => proxies(d).every(proxy => proxy.parent === harnessdProcesses(d).get('engine-codex')) || null, 10_000, 100)
+ expect(d.corePid()).toBe(core)
+ expect(d.coresStarted()).toBe(1)
+ })
+
+ it('a worker killed while a stop waits on the server sends nothing more, leaves the pane, and a second close stops it once', async () => {
+ const { d, s, count, close, pane } = await fresh()
+ const core = d.corePid(), worker = harnessdProcesses(d).get('engine-codex')!, panePid = await pane()
+ s.state.hold = 'thread/turns/list'
+ const first = close()
+ await until('the stop waiting on the server', () => count('thread/turns/list') > 0 || null, 45_000, 50)
+ const connections = linked(d)
+ process.kill(worker, 'SIGKILL')
+ const refused = await first
+ expect(refused.error, JSON.stringify(refused)).toBeDefined()
+ const killedAt = s.state.requests.length
+ s.release()
+ await replacement(d, worker, connections)
+ // Nothing of the stopped attempt reaches the server after its worker went: no interrupt, no archive.
+ for (const method of ['turn/interrupt', 'thread/archive', 'thread/unarchive']) expect(count(method), method).toBe(0)
+ expect(await pane()).toBe(panePid)
+ const result = await close()
+ expect(result.error, JSON.stringify(result)).toBeUndefined()
+ for (const method of ['turn/interrupt', 'thread/archive', 'thread/unarchive']) expect(count(method), method).toBe(1)
+ expect(count('thread/goal/set', killedAt)).toBe(1)
+ expect(s.state.loaded).toBe(false)
+ expect(d.corePid()).toBe(core)
+ expect(d.coresStarted()).toBe(1)
+ })
+
+ it('a worker killed between archive and unarchive: the next worker returns the thread\'s history, once', async () => {
+ const { d, s, count, close, pane } = await fresh()
+ const worker = harnessdProcesses(d).get('engine-codex')!, panePid = await pane()
+ s.state.hold = 'thread/archive'
+ const first = close()
+ await until('the archive sent', () => s.state.archived || null, 45_000, 50)
+ const connections = linked(d)
+ process.kill(worker, 'SIGKILL')
+ const refused = await first
+ expect(refused.error, JSON.stringify(refused)).toBeDefined()
+ expect(await pane()).toBe(panePid)
+ await replacement(d, worker, connections)
+ await until('the archived history returned', () => !s.state.archived || null, 30_000, 100)
+ expect(count('thread/unarchive')).toBe(1)
+ await until('the repair logged', () => d.log().includes('restored the history of codex conversation') || null, 10_000, 100)
+ // Forgotten once done: another restart repairs nothing more.
+ const again = harnessdProcesses(d).get('engine-codex')!, more = linked(d)
+ process.kill(again, 'SIGKILL')
+ await replacement(d, again, more)
+ await new Promise(resolve => setTimeout(resolve, 500))
+ expect(count('thread/unarchive')).toBe(1)
+ })
+
+ it('with the Codex worker parked, Stop still stops an agent that owns its conversation, needing no worker', async () => {
+ const { d, c, agent, pane } = await fresh(PARKING, false)
+ const core = d.corePid(), panePid = Number(await pane())
+ await park(d)
+ const stopped = await c.request('agent_delete', { agentId: agent.id }, 90_000)
+ expect(stopped.error, JSON.stringify(stopped)).toBeUndefined()
+ await until('the agent gone', async () => !(await c.request('agents_list', {})).agents.some((row: Row) => row.id === agent.id) || null, 30_000, 200)
+ await until('its process ended', () => !alive(panePid) || null, 30_000, 100)
+ expect(d.corePid()).toBe(core)
+ expect(d.coresStarted()).toBe(1)
+ })
+
+ it('with the Codex worker parked, a conversation on the shared server is not reported stopped: the pane stays, and it is logged', async () => {
+ const { d, c, s, agent, count, pane } = await fresh(PARKING)
+ const panePid = await pane()
+ await park(d)
+ const before = s.state.requests.length
+ const refused = await c.request('agent_delete', { agentId: agent.id }, 90_000)
+ expect(refused.error, JSON.stringify(refused)).toBeDefined()
+ expect(d.log()).toContain('the codex worker did not answer the stop')
+ expect(await pane()).toBe(panePid)
+ expect((await c.request('agents_list', {})).agents.some((row: Row) => row.id === agent.id)).toBe(true)
+ expect(count('thread/archive', before)).toBe(0)
+ expect(d.coresStarted()).toBe(1)
+ })
+
+ it('closes with the control in the core\'s own process in explicit inline mode', async () => {
+ const { d, s, count, close } = await fresh({ HARNESSD_SERVICES: 'none' })
+ const result = await close()
+ expect(result.error, JSON.stringify(result)).toBeUndefined()
+ for (const method of ['thread/goal/set', 'turn/interrupt', 'thread/archive', 'thread/unarchive']) expect(count(method), method).toBe(1)
+ expect(s.state.loaded).toBe(false)
+ expect(harnessdProcesses(d).get('engine-codex')).toBeUndefined()
+ })
+})
diff --git a/cli/e2e/harness/sharedCodex.ts b/cli/e2e/harness/sharedCodex.ts
index 94b2b4f2d..296e73157 100644
--- a/cli/e2e/harness/sharedCodex.ts
+++ b/cli/e2e/harness/sharedCodex.ts
@@ -14,22 +14,34 @@ export async function sharedCodex(home: string) {
mkdirSync(join(home, 'app-server-daemon'), { recursive: true })
writeFileSync(join(home, 'app-server-daemon', 'daemon.pid'), JSON.stringify({ pid: process.pid, processStartTime: start }))
writeFileSync(join(home, 'app-server-daemon', 'fake-proxy.json'), JSON.stringify({ port: address.port }))
- const state = { threadId: '', loaded: true, requests: [] as Array<{ method: string; params?: Record<string, unknown> }> }
- server.on('connection', socket => socket.on('message', bytes => {
- const frame = JSON.parse(String(bytes)) as { id?: number; method: string; params?: Record<string, unknown> }
- state.requests.push(frame)
- if (frame.id === undefined) return
- let result: Record<string, unknown> = {}
- if (frame.method === 'initialize') result = { codexHome: home }
- else if (frame.params?.threadId !== state.threadId) {
- socket.send(JSON.stringify({ id: frame.id, error: { message: 'unknown fixture thread' } })); return
- } else if (frame.method === 'thread/read') result = { thread: { id: state.threadId, status: { type: state.loaded ? 'active' : 'notLoaded' } } }
- else if (frame.method === 'thread/goal/get') result = { goal: { status: 'active' } }
- else if (frame.method === 'thread/turns/list') result = { data: [{ id: 'held-turn', status: 'inProgress' }] }
- else if (frame.method === 'thread/archive') state.loaded = false
- socket.send(JSON.stringify({ id: frame.id, result }))
- }))
- return { state, async close() {
+ // `open` counts the clients connected now. A request named in `hold` is answered only once `release()` is
+ // called: a test can stop whoever asked while the server still owes the answer.
+ // `archived`: a thread/archive with no thread/unarchive after it (the thread's history hidden from sessions).
+ const state = { threadId: '', loaded: true, archived: false, open: 0, hold: null as string | null,
+ requests: [] as Array<{ method: string; params?: Record<string, unknown> }> }
+ const held: Array<() => void> = []
+ server.on('connection', socket => {
+ state.open++
+ socket.on('close', () => { state.open-- })
+ socket.on('message', bytes => {
+ const frame = JSON.parse(String(bytes)) as { id?: number; method: string; params?: Record<string, unknown> }
+ state.requests.push(frame)
+ if (frame.id === undefined) return
+ let result: Record<string, unknown> = {}
+ if (frame.method === 'initialize') result = { codexHome: home }
+ else if (frame.params?.threadId !== state.threadId) {
+ socket.send(JSON.stringify({ id: frame.id, error: { message: 'unknown fixture thread' } })); return
+ } else if (frame.method === 'thread/read') result = { thread: { id: state.threadId, status: { type: state.loaded ? 'active' : 'notLoaded' } } }
+ else if (frame.method === 'thread/goal/get') result = { goal: { status: 'active' } }
+ else if (frame.method === 'thread/turns/list') result = { data: [{ id: 'held-turn', status: 'inProgress' }] }
+ else if (frame.method === 'thread/archive') { state.loaded = false; state.archived = true }
+ else if (frame.method === 'thread/unarchive') state.archived = false
+ const answer = () => { if (socket.readyState === socket.OPEN) socket.send(JSON.stringify({ id: frame.id, result })) }
+ if (frame.method === state.hold) held.push(answer)
+ else answer()
+ })
+ })
+ return { state, release() { state.hold = null; for (const answer of held.splice(0)) answer() }, async close() {
for (const socket of server.clients) socket.terminate()
await new Promise<void>(resolve => server.close(() => resolve()))
} }
diff --git a/cli/src/architecture.spec.ts b/cli/src/architecture.spec.ts
index 26f6e4e72..086bc8697 100644
--- a/cli/src/architecture.spec.ts
+++ b/cli/src/architecture.spec.ts
@@ -143,9 +143,9 @@ const SERVICE_MAY_IMPORT: Record<string, string> = {
/** 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)\.ts$/,
+ /^engines\/(claude|codex)\/(screen|composer|activity|stoppedGoal|modelControl|modelPicker|questionControl|submission|nativeControl)\.ts$/,
/^lib\/(askQuestion|runtimeProfileController|composerScreen|teamWriteHold|messageHold|terminalActivity|codexTurnRecovery)\.ts$/,
- /^engines\/(screens|modelControls|questionControls|submissions)\.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.
/^engines\/kit\/nativeSubmission\.ts$/,
// A worker's request handlers, the submission readers' among them, run in the engine's own process.
@@ -223,9 +223,10 @@ describe('the daemon\'s shape', () => {
}
})
- it('screen and submission transports and input authority do not load native screen or submission readers', () => {
+ it('screen, submission and native-control brokers and input authority do not load the engines\' native code', () => {
for (const entry of ['core/input.ts', 'core/questions.ts', 'core/engines/screens.ts', 'core/engines/screenTransport.ts',
- 'core/deviceInput.ts', 'lib/sessionInput.ts', 'core/engines/submissions.ts', 'core/engines/submissionTransport.ts']) {
+ 'core/deviceInput.ts', 'lib/sessionInput.ts', 'core/engines/submissions.ts', 'core/engines/submissionTransport.ts',
+ 'core/engines/nativeControls.ts', 'core/turns/activity.ts']) {
expect([...closureOf(entry).keys()].filter(file => /^engines\/(claude|codex)\//.test(file)), entry).toEqual([])
}
})
diff --git a/cli/src/core/AGENTS.md b/cli/src/core/AGENTS.md
index c508e86a7..9261542f1 100644
--- a/cli/src/core/AGENTS.md
+++ b/cli/src/core/AGENTS.md
@@ -37,7 +37,7 @@ questions. Everything else is a service ([../services/AGENTS.md](../services/AGE
validates bounded replies, retains acknowledged cursors and owns binding/turn state. The explicit
inline/older-master compatibility path is the only live parser or runtime profile implementation
composition in core. Screen reads are bounded and fenced to the worker connection and session binding
- ([screen boundary](../../../docs/design/2026-10-08-engine-screen.md)). Core keeps accepted profiles and control authority; native model drivers run in workers through [revocable control grants](../../../docs/design/2026-10-08-engine-model-control.md), and so does question navigation ([question control](../../../docs/design/2026-10-08-engine-question-control.md)). Whether a typed prompt was taken is read there too: core keeps the writer, every Enter and the verdict ([submission](../../../docs/design/2026-10-08-engine-submission.md)). See [runtime profiles](../../../docs/design/2026-10-08-engine-runtime.md).
+ ([screen boundary](../../../docs/design/2026-10-08-engine-screen.md)). Core keeps accepted profiles and control authority; native model drivers run in workers through [revocable control grants](../../../docs/design/2026-10-08-engine-model-control.md), and so does question navigation ([question control](../../../docs/design/2026-10-08-engine-question-control.md)). Whether a typed prompt was taken is read there too: core keeps the writer, every Enter and the verdict ([submission](../../../docs/design/2026-10-08-engine-submission.md)). Codex's shared app-server is spoken to from its worker under a stop grant; core keeps the process table, identity and the stop's decisions ([native control](../../../docs/design/2026-10-08-engine-native-control.md)). See [runtime profiles](../../../docs/design/2026-10-08-engine-runtime.md).
- `input.ts`, `questions.ts`: messages into a pane; an agent's question and its answer. Core matches an answer to the
question on screen and holds the lease; Claude Code's and Codex's keys for each approved step come from their engine
worker through a revocable grant (`engines/questionControls.ts`).
diff --git a/cli/src/core/agents/close.spec.ts b/cli/src/core/agents/close.spec.ts
index 6a8573934..986656a31 100644
--- a/cli/src/core/agents/close.spec.ts
+++ b/cli/src/core/agents/close.spec.ts
@@ -3,7 +3,7 @@ import { screenFor } from '../../engines/screens.js'
import { afterEach, describe, expect, it, vi } from 'vitest'
import { inspectCloseActivity, type CloseAgentServiceDeps } from '../../lib/closeAgentService.js'
import { projectDisplayName, type RegisteredSession } from '../../lib/registry.js'
-import { createAgentClosing, createCloseRequests, type ClosingDeps } from './close.js'
+import { CLOSE_READ_RECONNECT_MS, createAgentClosing, createCloseRequests, type ClosingDeps } from './close.js'
// The real close service, recording what it was built with so its callbacks can be driven directly.
vi.mock('../../lib/closeAgentService.js', async (real) => {
@@ -30,6 +30,7 @@ function setup(over: Partial<ClosingDeps> = {}, advertised: RegisteredSession[]
sessionCheckpoints: { save: vi.fn(async () => {}) } as unknown as ClosingDeps['sessionCheckpoints'],
stopAgent: vi.fn(async () => {}),
announceSession: vi.fn(),
+ engineReady: vi.fn(async () => {}),
...over,
}
const closing = createAgentClosing(deps)
@@ -64,6 +65,31 @@ describe('closing agents no window shows', () => {
await close.activity(row({ sessionId: '' }))
expect(deps.watcher.pollSession).not.toHaveBeenCalled()
})
+
+ it.each(['ENGINE_STALE_REPLY', 'ENGINE_UNAVAILABLE'])('reads once more after %s, once the restarted worker is linked again', async code => {
+ vi.spyOn(console, 'log').mockImplementation(() => {})
+ const pollSession = vi.fn().mockRejectedValueOnce(Object.assign(new Error(code), { code })).mockResolvedValue(undefined)
+ const { deps, close } = setup({ watcher: { pollSession } as unknown as ClosingDeps['watcher'] })
+ expect(await close.activity(row({ engine: 'codex' }))).toBe('idle')
+ expect(deps.engineReady).toHaveBeenCalledWith('codex', CLOSE_READ_RECONNECT_MS)
+ expect(pollSession).toHaveBeenCalledTimes(2)
+ })
+
+ it('reads only once more, and never retries a failure that is not a worker\'s restart', async () => {
+ vi.spyOn(console, 'log').mockImplementation(() => {})
+ const stale = Object.assign(new Error('stale'), { code: 'ENGINE_STALE_REPLY' })
+ const twice = vi.fn().mockRejectedValue(stale)
+ const again = setup({ watcher: { pollSession: twice } as unknown as ClosingDeps['watcher'] })
+ await expect(again.close.activity(row())).rejects.toBe(stale)
+ expect(twice).toHaveBeenCalledTimes(2)
+ for (const error of [new Error('disk gone'), null]) {
+ const other = vi.fn().mockRejectedValue(error)
+ const once = setup({ watcher: { pollSession: other } as unknown as ClosingDeps['watcher'] })
+ await expect(once.close.activity(row())).rejects.toBe(error)
+ expect(other).toHaveBeenCalledOnce()
+ expect(once.deps.engineReady).not.toHaveBeenCalled()
+ }
+ })
})
describe('the checkpoint around a close', () => {
diff --git a/cli/src/core/agents/close.ts b/cli/src/core/agents/close.ts
index 60c7fd369..d4abd3afa 100644
--- a/cli/src/core/agents/close.ts
+++ b/cli/src/core/agents/close.ts
@@ -7,6 +7,7 @@ import type { ScreenReader } from '../../lib/screenReader.js'
*/
import { CloseAgentService, inspectCloseActivity, type CloseAgentServiceDeps, type CloseMode } from '../../lib/closeAgentService.js'
import type { OpenTabProtection } from '../../lib/openTabProtection.js'
+import { sid } from '../../lib/log.js'
import { projectDisplayName, type registry } from '../../lib/registry.js'
import type { SessionCheckpointStore } from '../../lib/sessionCheckpoint.js'
import type { TerminalBackendCoordinator } from '../../lib/terminalBackendCoordinator.js'
@@ -25,17 +26,37 @@ export interface ClosingDeps {
sessionCheckpoints: Pick<SessionCheckpointStore, 'save'>
stopAgent: CloseAgentServiceDeps['stop']
announceSession: CloseAgentServiceDeps['changed']
+ /** Once the engine's worker is linked again, or the wait is over (core/engines/engineLinks.ts). */
+ engineReady: (engine: string, ms: number) => Promise<void>
}
+/** How long a close waits for an engine worker that restarted under its read, before reading once more. */
+export const CLOSE_READ_RECONNECT_MS = 10_000
+
export function createAgentClosing({
readScreen, registry, cleanupTabs, watcher, captureTerminal, sessionTurnState, openQuestions, terminals, sessionCheckpoints,
- stopAgent, announceSession,
+ stopAgent, announceSession, engineReady,
}: ClosingDeps) {
+ /**
+ * Read what the transcript has that the tail has not delivered yet. A close sent just as the engine's worker
+ * restarted found its live read refused as stale (seen end to end: ENGINE_STALE_REPLY, the close failed).
+ * A read is idempotent: wait for the worker's new link, within the close's own bound, and read once more.
+ */
+ const drain = async (s: { sessionId: string; engine: string }): Promise<void> => {
+ try { await watcher.pollSession(s.sessionId) }
+ catch (error) {
+ const code = (error as { code?: unknown } | null)?.code
+ if (code !== 'ENGINE_STALE_REPLY' && code !== 'ENGINE_UNAVAILABLE') throw error
+ console.log(`[close] ${sid(s.sessionId)} its ${s.engine} worker was replaced under the read (${code}); reading again once it is back`)
+ await engineReady(s.engine, CLOSE_READ_RECONNECT_MS)
+ await watcher.pollSession(s.sessionId)
+ }
+ }
const closeAgentService = new CloseAgentService({
registry,
openTabs: cleanupTabs,
activity: async s => {
- if (s.sessionId) await watcher.pollSession(s.sessionId)
+ if (s.sessionId) await drain(s)
const screen = await captureTerminal(s.agentId, 80)
return inspectCloseActivity(s, await readScreen(s, screen), sessionTurnState(s.sessionId), openQuestions.has(s.sessionId))
},
diff --git a/cli/src/core/agents/lifecycle.spec.ts b/cli/src/core/agents/lifecycle.spec.ts
index 71cbe73a4..608cd0a91 100644
--- a/cli/src/core/agents/lifecycle.spec.ts
+++ b/cli/src/core/agents/lifecycle.spec.ts
@@ -35,6 +35,7 @@ function setup(over: Partial<LifecycleDeps> = {}) {
forgetSession: vi.fn(),
markDeleted: vi.fn(),
clearDeleted: vi.fn(),
+ stopNative: vi.fn(async () => {}),
sessionCheckpoints: {} as never,
mirror: { deleteHistory: vi.fn() },
sessionSearch: { deleteHistory: vi.fn() },
@@ -62,7 +63,7 @@ describe('stopping, purging and resuming an agent', () => {
expect(createStopAgentService).toHaveBeenCalledWith({
registry: deps.registry, stoppedAgents: deps.stoppedAgents, restartJobs: deps.restartJobs, stopJobs: lifecycle.stopJobs,
tmuxBackend: null, agentReconciler: deps.agentReconciler, forgetSession: deps.forgetSession,
- markDeleted: deps.markDeleted, clearDeleted: deps.clearDeleted,
+ markDeleted: deps.markDeleted, clearDeleted: deps.clearDeleted, stopNative: deps.stopNative,
})
expect(lifecycle.stopAgent).toBe(vi.mocked(createStopAgentService).mock.results[0].value)
expect(createResumeAgentService).toHaveBeenCalledWith({
diff --git a/cli/src/core/agents/lifecycle.ts b/cli/src/core/agents/lifecycle.ts
index 9e84cdc3e..55624b54d 100644
--- a/cli/src/core/agents/lifecycle.ts
+++ b/cli/src/core/agents/lifecycle.ts
@@ -21,6 +21,7 @@ export interface LifecycleDeps {
tmuxBackend: StopAgentServiceDeps['tmuxBackend'] & ResumeAgentServiceDeps['tmuxBackend']
agentReconciler: StopAgentServiceDeps['agentReconciler']
forgetSession: StopAgentServiceDeps['forgetSession']
+ stopNative: StopAgentServiceDeps['stopNative']
markDeleted: typeof markDeletedFn
clearDeleted: typeof clearDeletedFn
sessionCheckpoints: SessionCheckpointStore
@@ -41,7 +42,7 @@ export interface LifecycleDeps {
}
export function createAgentLifecycle({
- registry, stoppedAgents, restartJobs, tmuxBackend, agentReconciler, forgetSession, markDeleted, clearDeleted,
+ registry, stoppedAgents, restartJobs, tmuxBackend, agentReconciler, forgetSession, markDeleted, clearDeleted, stopNative,
sessionCheckpoints, mirror, sessionSearch, send, pinnedControls, retainExitedSession, announceSession,
relaunchOverrides, prepareSessionResume, refreshGridWebSearch, attachDsh, attachSession, relaunchMarks,
}: LifecycleDeps) {
@@ -53,7 +54,7 @@ export function createAgentLifecycle({
const stopJobs = new Map<string, Promise<void>>()
const stopAgent = createStopAgentService({
registry, stoppedAgents, restartJobs, stopJobs, tmuxBackend, agentReconciler,
- forgetSession, markDeleted, clearDeleted,
+ forgetSession, markDeleted, clearDeleted, stopNative,
})
const purgeAgentService = new PurgeAgentService({
live: id => registry.byAgent(id), sessions: () => [...registry.list(), ...stoppedAgents.list()],
diff --git a/cli/src/core/engines/engineLinks.spec.ts b/cli/src/core/engines/engineLinks.spec.ts
new file mode 100644
index 000000000..2cc50fa9e
--- /dev/null
+++ b/cli/src/core/engines/engineLinks.spec.ts
@@ -0,0 +1,31 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { createEngineLinks } from './engineLinks.js'
+
+afterEach(() => vi.useRealTimers())
+
+describe('engine worker links', () => {
+ it('is ready at once for a linked worker, and for an engine with none', async () => {
+ const links = createEngineLinks()
+ links.connected('engine-codex')
+ await links.ready('codex', 10_000)
+ await links.ready('cursor', 10_000)
+ })
+
+ it('waits for the worker to link again, or for its bound, whichever comes first', async () => {
+ vi.useFakeTimers()
+ const links = createEngineLinks()
+ links.connected('engine-codex'); links.disconnected('engine-codex')
+ const woken = vi.fn(), timed = vi.fn()
+ void links.ready('codex', 10_000).then(woken)
+ void links.ready('claude', 10_000).then(timed)
+ void links.ready('codex', 10_000).then(woken)
+ links.connected('engine-codex')
+ await vi.advanceTimersByTimeAsync(0)
+ expect(woken).toHaveBeenCalledTimes(2)
+ expect(timed).not.toHaveBeenCalled()
+ await vi.advanceTimersByTimeAsync(10_000)
+ expect(timed).toHaveBeenCalledOnce()
+ // A worker linking with nobody waiting wakes nothing.
+ links.connected('engine-claude')
+ })
+})
diff --git a/cli/src/core/engines/engineLinks.ts b/cli/src/core/engines/engineLinks.ts
new file mode 100644
index 000000000..1f2abc945
--- /dev/null
+++ b/cli/src/core/engines/engineLinks.ts
@@ -0,0 +1,30 @@
+/**
+ * Whether each engine worker is linked to the core right now, and a bounded wait for one to be. A read
+ * refused because its worker restarted under it (`ENGINE_STALE_REPLY`, `ENGINE_UNAVAILABLE`) can wait here for
+ * the new link and be made again: a read is idempotent. A write is never retried this way.
+ */
+import { readerEngine, READER_SERVICES } from '../../engines/worker/protocol.js'
+
+export function createEngineLinks() {
+ const linked = new Set<string>()
+ const waiting = new Map<string, Array<() => void>>()
+ return {
+ connected(service: string): void {
+ linked.add(service)
+ for (const wake of waiting.get(service)?.splice(0) ?? []) wake()
+ },
+ disconnected(service: string): void { linked.delete(service) },
+ /** Once the engine's worker is linked, or after `ms`, whichever comes first. */
+ ready(engine: string, ms: number): Promise<void> {
+ if (!readerEngine(engine) || linked.has(READER_SERVICES[engine])) return Promise.resolve()
+ const service = READER_SERVICES[engine]
+ return new Promise<void>(resolve => {
+ const timer = setTimeout(wake, ms)
+ function wake() { clearTimeout(timer); resolve() }
+ waiting.set(service, [...waiting.get(service) ?? [], wake])
+ })
+ },
+ }
+}
+
+export type EngineLinks = ReturnType<typeof createEngineLinks>
diff --git a/cli/src/core/engines/nativeControls.spec.ts b/cli/src/core/engines/nativeControls.spec.ts
new file mode 100644
index 000000000..875dbbde4
--- /dev/null
+++ b/cli/src/core/engines/nativeControls.spec.ts
@@ -0,0 +1,272 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { launch as codexLaunch } from '../../engines/codex/launch.js'
+import type { EngineNativeControl, NativeConversation, NativeStopHost } from '../../engines/facets/nativeControl.js'
+import { NATIVE_UNCONFIRMED } from '../../engines/worker/nativeControlHost.js'
+import { NATIVE_ACTIVITY, NATIVE_CONTROL_CAPABILITIES, NATIVE_CONTROL_HOST, NATIVE_RECOVER, NATIVE_STOP,
+ NATIVE_STOP_QUERIES } from '../../engines/worker/nativeControlProtocol.js'
+import { engineNativeControlRequests } from '../../engines/worker/nativeControlRequests.js'
+import type { RegisteredSession } from '../../lib/registry.js'
+import { argvTokens, type ProcessRow } from '../../lib/tmux.js'
+import { createNativeControls, type NativeControlsDeps } from './nativeControls.js'
+
+const server = codexLaunch.sharedServer!
+const identity = { pid: 41, startMarker: 'born', executable: 'codex' }
+const row = (over: Partial<RegisteredSession> = {}) => ({ agentId: 'agent', sessionId: 'thread', engine: 'codex', active: true,
+ runtimes: [], processIdentity: identity, ...over }) as unknown as RegisteredSession
+const daemon = { pid: 90, parentPid: 1, executable: 'codex', startMarker: 'Thu Oct 1', args: 'codex app-server' }
+const table = (args = 'codex resume thread'): ProcessRow[] => [{ ...identity, parentPid: 1, args }, daemon]
+const conversation: NativeConversation = { home: '/fixture/codex', sessionId: 'thread' }
+const pidFile = JSON.stringify({ pid: 90, processStartTime: 'Thu Oct 1 ' })
+const who = { owner: true, local: true }
+
+/** A control that records what it was asked, and runs a script against core's answers. */
+function control(script: (host: NativeStopHost) => Promise<void> = async host => { await host.current() }) {
+ const asked: NativeConversation[] = []
+ const value: EngineNativeControl = {
+ activity: vi.fn(async (c: NativeConversation) => { asked.push(c); return 'working' as const }),
+ stop: vi.fn(async (c: NativeConversation, host: NativeStopHost) => { asked.push(c); await script(host) }),
+ recover: vi.fn(async () => {}),
+ close: vi.fn(),
+ }
+ return { value, asked }
+}
+
+/** The core's broker, with the real worker requests behind its links: the worker's questions come back to it. */
+function isolated(engine: EngineNativeControl, over: Partial<NativeControlsDeps> = {}) {
+ let core: ReturnType<typeof createNativeControls>
+ const requests = engineNativeControlRequests('codex', { load: async () => engine, recycle: vi.fn(),
+ query: async (query, payload) => core.answer('engine-codex', query, payload) ?? { error: 'DENIED' } })
+ // Calls in flight, which a lost link fails at once, as the core's service links do.
+ const inFlight = new Set<(error: Error) => void>()
+ const call = vi.fn((_service: string, method: string, payload: Record<string, unknown>) => new Promise<Record<string, unknown>>((resolve, reject) => {
+ inFlight.add(reject)
+ Promise.resolve(requests[method]({ ...payload, requestId: 'core-route' }, who)).then(reply => resolve(reply as Record<string, unknown>), reject)
+ .finally(() => inFlight.delete(reject))
+ }))
+ const log = vi.fn()
+ core = createNativeControls({ call, servers: { codex: server }, handles: () => true, inline: () => undefined, rows: async () => table(),
+ home: () => '/fixture/codex', argv: argvTokens, readFile: async () => pidFile, log, ...over })
+ core.connected('engine-codex')
+ const drop = () => { for (const reject of inFlight) reject(new Error('link lost')); inFlight.clear(); core.disconnected('engine-codex') }
+ return { core, call, log, drop, methods: () => call.mock.calls.map(c => c[1]) }
+}
+
+afterEach(() => { vi.useRealTimers(); vi.restoreAllMocks() })
+
+describe('Codex\'s shared server, from the core', () => {
+ it('asks the worker about a shared conversation only, and nothing for a client that owns its own or works remotely', async () => {
+ const engine = control()
+ const t = isolated(engine.value)
+ expect(await t.core.activity(row())).toBe('working')
+ expect(engine.asked).toEqual([conversation])
+ expect(t.methods()).toEqual([NATIVE_CONTROL_CAPABILITIES, NATIVE_ACTIVITY])
+ // An argv too short to hold a script is read as the CLI's own: its first option still decides.
+ expect(await isolated(engine.value, { rows: async () => table('') }).core.activity(row())).toBe('working')
+ expect(await isolated(engine.value, { rows: async () => table('node') }).core.activity(row())).toBe('working')
+ for (const args of ['codex --no-daemon resume thread', 'node /bin/codex.js --no-daemon resume thread', 'codex --remote=ws://x resume thread']) {
+ const other = isolated(engine.value, { rows: async () => table(args) })
+ expect(await other.core.activity(row())).toBe('unknown')
+ expect(other.call).not.toHaveBeenCalled()
+ }
+ expect(await t.core.activity(row({ engine: 'claude' }))).toBe('unknown')
+ expect(await t.core.activity(row({ processIdentity: undefined }))).toBe('unknown')
+ expect(await t.core.activity(row({ processIdentity: { ...identity, executable: 'node' } }))).toBe('unknown')
+ expect(t.call).toHaveBeenCalledTimes(2)
+ expect(engine.asked).toHaveLength(3)
+ })
+
+ it('reads the process table once in two seconds, and takes a failed or malformed reading as unknown', async () => {
+ let now = 0
+ const read = vi.fn(async () => table())
+ const engine = control()
+ const t = isolated(engine.value, { rows: read, now: () => now })
+ await Promise.all([t.core.activity(row()), t.core.activity(row())])
+ expect(read).toHaveBeenCalledOnce()
+ now = 2_001
+ await t.core.activity(row())
+ expect(read).toHaveBeenCalledTimes(2)
+ vi.mocked(engine.value.activity).mockResolvedValueOnce('sleeping' as never)
+ expect(await t.core.activity(row())).toBe('unknown')
+ vi.mocked(engine.value.activity).mockRejectedValueOnce(new Error('server gone'))
+ expect(await t.core.activity(row())).toBe('unknown')
+ const relative = isolated(engine.value, { home: () => 'codex' })
+ expect(await relative.core.activity(row())).toBe('unknown')
+ expect(relative.call).not.toHaveBeenCalled()
+ })
+
+ it('stops a client that owns its conversation, or whose server is gone, with no worker at all', async () => {
+ const engine = control()
+ const down = { call: async () => ({ error: 'SERVICE_UNAVAILABLE' }) }
+ // Launched by Harness with --no-daemon: nothing of it is on any server. A stop needs no worker for it.
+ await isolated(engine.value, { ...down, rows: async () => table('node /bin/codex --no-daemon resume thread') }).core.stop(row(), () => true)
+ // No record of a server in the store, or its recorded process no longer running.
+ await isolated(engine.value, { ...down, readFile: async () => { throw Object.assign(new Error('none'), { code: 'ENOENT' }) } }).core.stop(row(), () => true)
+ await isolated(engine.value, { ...down, rows: async () => [table()[0]] }).core.stop(row(), () => true)
+ await isolated(engine.value, { ...down, readFile: async () => JSON.stringify({ pid: 90, processStartTime: 'later' }) }).core.stop(row(), () => true)
+ await isolated(engine.value).core.stop(row({ engine: 'claude' }), () => true)
+ expect(engine.value.stop).not.toHaveBeenCalled()
+ })
+
+ it('refuses in the engine\'s own words what core can tell alone', async () => {
+ const engine = control()
+ await expect(isolated(engine.value, { rows: async () => table('codex resume --remote ws://x thread') }).core.stop(row(), () => true)).rejects.toThrow(server.messages.remote)
+ await expect(isolated(engine.value, { rows: async () => null }).core.stop(row(), () => true)).rejects.toThrow(server.messages.unverified)
+ await expect(isolated(engine.value).core.stop(row({ sessionId: '' }), () => true)).rejects.toThrow(server.messages.unidentified)
+ await expect(isolated(engine.value, { readFile: async () => '{"pid":0}' }).core.stop(row(), () => true)).rejects.toThrow('Invalid Codex server identity')
+ await expect(isolated(engine.value, { readFile: async () => { throw new Error('EACCES') } }).core.stop(row(), () => true)).rejects.toThrow('EACCES')
+ await expect(isolated(engine.value, { home: () => 'relative' }).core.stop(row(), () => true)).rejects.toThrow(NATIVE_UNCONFIRMED)
+ // An unbound chat proved unused needs no server; the proof is core's, and so is the last check.
+ const unused = vi.fn(async () => true)
+ await isolated(engine.value).core.stop(row({ sessionId: '' }), () => true, unused)
+ expect(unused).toHaveBeenCalledWith(row({ sessionId: '' }))
+ await expect(isolated(engine.value).core.stop(row({ sessionId: '' }), () => false, unused)).rejects.toThrow('cancelled')
+ // An exited client that never bound a conversation: nothing on any server is its.
+ const exited = row({ sessionId: '', processIdentity: { pid: 7, startMarker: 'gone', executable: 'codex' } })
+ await isolated(engine.value).core.stop(exited, () => true)
+ await expect(isolated(engine.value).core.stop(exited, () => false)).rejects.toThrow('cancelled')
+ expect(engine.value.stop).not.toHaveBeenCalled()
+ })
+
+ it('unloads a shared conversation through the worker under a grant, gone after', async () => {
+ const answers: unknown[] = []
+ let t!: ReturnType<typeof isolated>
+ const engine = control(async host => {
+ // Another engine's worker coming and going leaves this grant alone.
+ t.core.disconnected('engine-claude'); t.core.connected('engine-claude')
+ answers.push(await host.current(), await host.pending(), await host.settled())
+ })
+ t = isolated(engine.value)
+ await t.core.stop(row(), () => true)
+ expect(answers).toEqual([true, true, true])
+ expect(engine.asked).toEqual([conversation])
+ expect(t.methods()).toEqual([NATIVE_CONTROL_CAPABILITIES, NATIVE_STOP])
+ const token = t.call.mock.calls[1][2].token as string
+ expect(t.core.answer('engine-codex', NATIVE_CONTROL_HOST, { version: 1, token, action: { kind: 'current' } })).toEqual({ version: 1, error: 'ANSWER_FAILED' })
+ })
+
+ it('carries the engine\'s refusal to the person; a worker that does not answer is logged and never confirms', async () => {
+ const refused = control(async () => { throw new Error('Codex returned a different conversation') })
+ await expect(isolated(refused.value).core.stop(row(), () => true)).rejects.toThrow('different conversation')
+ const hostile = control(async () => { throw new Error('\x1b]0;owned\x07') })
+ await expect(isolated(hostile.value).core.stop(row(), () => true)).rejects.toThrow(NATIVE_UNCONFIRMED)
+ const down = isolated(control().value, { call: async () => ({ error: 'SERVICE_UNAVAILABLE' }) })
+ await expect(down.core.stop(row(), () => true)).rejects.toThrow(NATIVE_UNCONFIRMED)
+ expect(down.log).toHaveBeenCalledWith(expect.stringContaining('the codex worker did not answer the stop'))
+ })
+
+ it('revokes the stop when it is no longer wanted, and refuses every question after, a check that throws included', async () => {
+ let current = true
+ const after: unknown[] = []
+ const engine = control(async host => {
+ current = false
+ if (!await host.pending()) {
+ after.push(await host.current().catch(error => error.message))
+ throw new Error('The close request was cancelled or the session changed')
+ }
+ })
+ const t = isolated(engine.value)
+ await expect(t.core.stop(row(), () => current)).rejects.toThrow('cancelled')
+ expect(after).toEqual([NATIVE_UNCONFIRMED])
+ // Refused before its step, the stop leaves nothing to repair.
+ t.core.disconnected('engine-codex'); t.core.connected('engine-codex')
+ expect(t.methods()).not.toContain(NATIVE_RECOVER)
+ const throwing = control(async host => { await host.current() })
+ await expect(isolated(throwing.value).core.stop(row(), () => { throw new Error('registry gone') })).rejects.toThrow(NATIVE_UNCONFIRMED)
+ })
+
+ it('answers only its own grant, for the service it was given to, within its count', async () => {
+ let t!: ReturnType<typeof isolated>
+ const results: unknown[] = []
+ const engine = control(async () => {
+ const token = t.call.mock.calls.find(call => call[1] === NATIVE_STOP)![2].token as string
+ const ask = (action: unknown, service = 'engine-codex', value = token) =>
+ t.core.answer(service, NATIVE_CONTROL_HOST, { version: 1, token: value, action, query: NATIVE_CONTROL_HOST })
+ results.push(ask({ kind: 'current' }, 'engine-claude'), ask({ kind: 'current' }, 'engine-codex', 'f'.repeat(64)),
+ ask({ kind: 'delete' }), ask({ kind: 'current' }))
+ })
+ t = isolated(engine.value)
+ await t.core.stop(row(), () => true)
+ expect(results.map(result => (result as Record<string, unknown>).error ?? (result as Record<string, unknown>).value))
+ .toEqual(['ANSWER_FAILED', 'ANSWER_FAILED', 'ANSWER_FAILED', true])
+ expect(t.core.answer('engine-codex', 'engine.questionControl', {})).toBeNull()
+ const chatty = control(async host => { for (let n = 0; n <= NATIVE_STOP_QUERIES; n++) await host.current() })
+ await expect(isolated(chatty.value).core.stop(row(), () => true)).rejects.toThrow(NATIVE_UNCONFIRMED)
+ })
+
+ it('undoes, once, through the next worker, a step a lost worker took and never undid', async () => {
+ let t!: ReturnType<typeof isolated>
+ // The worker notes its archive, then is lost before the unarchive: its link replaced under the stop.
+ const engine = control(async host => {
+ await host.pending()
+ t.drop(); t.core.connected('engine-claude')
+ await new Promise(() => {})
+ })
+ t = isolated(engine.value)
+ await expect(t.core.stop(row(), () => true)).rejects.toThrow(NATIVE_UNCONFIRMED)
+ t.core.connected('engine-codex')
+ await vi.waitFor(() => expect(engine.value.recover).toHaveBeenCalledWith(conversation))
+ await vi.waitFor(() => expect(t.log).toHaveBeenCalledWith(expect.stringContaining('restored the history of codex conversation')))
+ // Once: a later link asks nothing more.
+ t.core.disconnected('engine-codex'); t.core.connected('engine-codex')
+ await new Promise(resolve => setTimeout(resolve, 0))
+ expect(engine.value.recover).toHaveBeenCalledOnce()
+ })
+
+ it('logs a repair that failed, or that no worker could be asked for, and forgets it either way', async () => {
+ for (const [failure, words] of [['refused', 'could not restore'], ['unreachable', 'could not ask']] as const) {
+ let t!: ReturnType<typeof isolated>
+ const engine = control(async host => {
+ await host.pending()
+ t.drop()
+ await new Promise(() => {})
+ })
+ if (failure === 'refused') vi.mocked(engine.value.recover).mockRejectedValue(new Error('not archived'))
+ t = isolated(engine.value)
+ await expect(t.core.stop(row(), () => true)).rejects.toThrow(NATIVE_UNCONFIRMED)
+ if (failure === 'unreachable') t.call.mockImplementation(async () => ({ error: 'SERVICE_UNAVAILABLE' }))
+ t.core.connected('engine-codex')
+ await vi.waitFor(() => expect(t.log).toHaveBeenCalledWith(expect.stringContaining(words)))
+ }
+ })
+
+ it('leaves nothing to repair once the worker undid its step, or answered at all', async () => {
+ const settled = control(async host => { await host.pending(); await host.settled() })
+ const t = isolated(settled.value)
+ await t.core.stop(row(), () => true)
+ const refused = control(async host => { await host.pending(); throw new Error('Codex could not archive') })
+ const u = isolated(refused.value)
+ await expect(u.core.stop(row(), () => true)).rejects.toThrow('could not archive')
+ for (const each of [t, u]) { each.core.disconnected('engine-codex'); each.core.connected('engine-codex') }
+ await new Promise(resolve => setTimeout(resolve, 0))
+ expect(settled.value.recover).not.toHaveBeenCalled()
+ expect(refused.value.recover).not.toHaveBeenCalled()
+ })
+
+ it('runs the control in process only when composed so, bounded the same way, and closes it at shutdown', async () => {
+ vi.useFakeTimers()
+ const engine = control(() => new Promise(() => {}))
+ const deps = { servers: { codex: server }, handles: () => false, inline: () => engine.value, rows: async () => table(), home: () => '/fixture/codex',
+ argv: argvTokens, readFile: async () => pidFile, call: vi.fn(), log: vi.fn() }
+ const core = createNativeControls(deps)
+ expect(await core.activity(row())).toBe('working')
+ const stuck = expect(core.stop(row(), () => true)).rejects.toThrow(NATIVE_UNCONFIRMED)
+ await vi.advanceTimersByTimeAsync(60_001)
+ await stuck
+ vi.useRealTimers()
+ vi.mocked(engine.value.stop).mockImplementationOnce(async (_c, host) => { await host.pending(); throw 'not an error' })
+ await expect(core.stop(row(), () => true)).rejects.toThrow(NATIVE_UNCONFIRMED)
+ // In process there is no worker to lose: nothing is kept to repair.
+ core.connected('engine-codex')
+ expect(engine.value.recover).not.toHaveBeenCalled()
+ core.close()
+ expect(engine.value.close).toHaveBeenCalledOnce()
+ const none = createNativeControls({ ...deps, inline: () => undefined })
+ expect(await none.activity(row())).toBe('unknown')
+ await expect(none.stop(row(), () => true)).rejects.toThrow(NATIVE_UNCONFIRMED)
+ none.close()
+ const logged = vi.spyOn(console, 'log').mockImplementation(() => {})
+ const quiet = createNativeControls({ ...deps, handles: () => true, inline: () => undefined, log: undefined, call: async () => ({ error: 'SERVICE_UNAVAILABLE' }) })
+ await expect(quiet.stop(row(), () => true)).rejects.toThrow(NATIVE_UNCONFIRMED)
+ expect(logged).toHaveBeenCalledWith(expect.stringContaining('did not answer the stop'))
+ })
+})
diff --git a/cli/src/lib/codexSessionLifecycle.spec.ts b/cli/src/core/engines/nativeControls.stop.spec.ts
similarity index 90%
rename from cli/src/lib/codexSessionLifecycle.spec.ts
rename to cli/src/core/engines/nativeControls.stop.spec.ts
index ffa2b4dce..15e1ce04b 100644
--- a/cli/src/lib/codexSessionLifecycle.spec.ts
+++ b/cli/src/core/engines/nativeControls.stop.spec.ts
@@ -1,6 +1,24 @@
+/**
+ * The stop of a shared Codex conversation, end to end inside one process: the core's broker (rows, identity,
+ * the grant's answers) with Codex's own control in process. These are the recorded cases of the former
+ * lib/codexSessionLifecycle.ts, unchanged: the move into the worker keeps every outcome and message.
+ */
import { afterEach, beforeEach, expect, it, vi } from 'vitest'
-import { stopSharedCodexSession, type CodexStopDeps } from './codexSessionLifecycle.js'
-import { registry, type RegisteredSession } from './registry.js'
+import type { CodexControl } from '../../engines/codex/nativeControl.js'
+import { registry, type RegisteredSession } from '../../lib/registry.js'
+import type { ProcessRow } from '../../lib/tmux.js'
+import { composedCodex } from '../../testing/inlineNativeControls.js'
+
+interface CodexStopDeps {
+ daemonIdentity(home: string): Promise<{ pid: number; processStartTime: string } | null>
+ rows(): Promise<ProcessRow[] | null>
+ connect(home: string): Promise<CodexControl>
+}
+/** The former entry point, composed of the pieces it was split into. */
+function stopSharedCodexSession(session: RegisteredSession, current: () => boolean, deps: CodexStopDeps,
+ confirmUnusedConversation?: (session: RegisteredSession) => Promise<boolean>): Promise<void> {
+ return composedCodex(deps).stop(session, current, confirmUnusedConversation)
+}
let row: RegisteredSession
let deps: CodexStopDeps
let request: ReturnType<typeof vi.fn<(method: string, params?: Record<string, unknown>) => Promise<any>>>
diff --git a/cli/src/core/engines/nativeControls.ts b/cli/src/core/engines/nativeControls.ts
new file mode 100644
index 000000000..cb4e9d11d
--- /dev/null
+++ b/cli/src/core/engines/nativeControls.ts
@@ -0,0 +1,237 @@
+/**
+ * Core's side of an engine's own control connection (Codex's shared app-server), which runs in the engine's
+ * worker. Core decides from what it holds and the engine's declared contract (`SharedServerContract`):
+ * the process table, the session's identity and store, whether its client owns its conversation, whether the
+ * server runs, whether an unbound chat was never used. Only a conversation established to be on a running
+ * server goes to the worker, which asks core before each effect under a single-use grant; only core signals
+ * the client afterwards. Moved from lib/codexSessionLifecycle.ts, whose outcomes and messages it keeps.
+ */
+import { randomBytes } from 'node:crypto'
+import { basename, join } from 'node:path'
+import type { EngineNativeControl, NativeConversation } from '../../engines/facets/nativeControl.js'
+import type { SharedServerContract } from '../../engines/facets/launch.js'
+import { createNativeStopHost, NATIVE_UNCONFIRMED } from '../../engines/worker/nativeControlHost.js'
+import { boundConversation, nativeActivity, nativeConversation, nativeEnvelope, nativeMessage, nativeStopAction, nativeStopAnswer,
+ NATIVE_ACTIVITY, NATIVE_ACTIVITY_IN_FLIGHT, NATIVE_ACTIVITY_QUEUED, NATIVE_ACTIVITY_WAIT_MS, NATIVE_CONTROL_CAPABILITIES,
+ NATIVE_CONTROL_HOST, NATIVE_CONTROL_VERSION, NATIVE_RECOVER, NATIVE_RECOVER_WAIT_MS, NATIVE_REPLY_BYTES, NATIVE_STOP,
+ NATIVE_STOP_IN_FLIGHT, NATIVE_STOP_QUERIES, NATIVE_STOP_WAIT_MS, type NativeStopAnswer } from '../../engines/worker/nativeControlProtocol.js'
+import { READER_SERVICES, type ReaderEngine } from '../../engines/worker/protocol.js'
+import { sid } from '../../lib/log.js'
+import type { RegisteredSession } from '../../lib/registry.js'
+import { sameProcessIdentity } from '../../lib/terminalRuntime.js'
+import type { ProcessRow } from '../../lib/tmux.js'
+import type { ActivityState } from '../../lib/turnActivity.js'
+import { boundedControl } from './controlTransport.js'
+import { createSnapshotTransport, type SnapshotTransportDeps } from './snapshotTransport.js'
+
+export interface NativeControlsDeps extends SnapshotTransportDeps {
+ /** The engines whose CLI can leave work on a server of their own, as their launch contracts declare. */
+ servers: Readonly<Record<string, SharedServerContract>>
+ /** The engine's control runs in its supervised worker. */
+ handles(engine: string): boolean
+ /** Explicit inline mode and older masters only; a failed worker never selects it. */
+ inline(engine: string): EngineNativeControl | undefined
+ /** The process table, or null when it could not be read. */
+ rows(): Promise<ProcessRow[] | null>
+ /** The engine's store for this session (its CODEX_HOME). */
+ home(session: RegisteredSession): string
+ /** A process's command line as its argv (lib/tmux.ts argvTokens), passed in: the process table's reader
+ * is the terminal layer's, and this broker loads none of it. */
+ argv(args: string): string[]
+ readFile(path: string): Promise<string>
+ log?(message: string): void
+ now?(): number
+}
+
+const CANCELLED = 'The close request was cancelled or the session changed'
+
+interface Grant {
+ service: string
+ engine: ReaderEngine
+ conversation: NativeConversation
+ current(): boolean
+ queries: number
+}
+
+export function createNativeControls(deps: NativeControlsDeps) {
+ const now = deps.now ?? (() => performance.now())
+ const log = deps.log ?? ((message: string) => console.log(message))
+ const kind = { version: NATIVE_CONTROL_VERSION, capabilities: NATIVE_CONTROL_CAPABILITIES, capability: 'nativeControl', replyBytes: NATIVE_REPLY_BYTES }
+ const reads = createSnapshotTransport(deps, { ...kind, inFlight: NATIVE_ACTIVITY_IN_FLIGHT, queued: NATIVE_ACTIVITY_QUEUED, waitMs: NATIVE_ACTIVITY_WAIT_MS })
+ // Stops are rare and each holds a grant: refused beyond four at once rather than queued behind each other.
+ const stops = createSnapshotTransport(deps, { ...kind, inFlight: NATIVE_STOP_IN_FLIGHT, queued: 0, waitMs: NATIVE_STOP_WAIT_MS })
+ const recoveries = createSnapshotTransport(deps, { ...kind, inFlight: NATIVE_STOP_IN_FLIGHT, queued: NATIVE_ACTIVITY_QUEUED, waitMs: NATIVE_RECOVER_WAIT_MS })
+ const grants = new Map<string, Grant>()
+ /** A step a stop said it was taking that must be undone if cut off (Codex's archive), by grant. */
+ const repairs = new Map<string, { service: string; engine: ReaderEngine; conversation: NativeConversation }>()
+ let rowsAt = -Infinity
+ let rowsRead: Promise<ProcessRow[] | null> | undefined
+
+ /** The engine process core holds for the session: its identity and executable, never a name or an argv match. */
+ const ownerOf = (session: RegisteredSession, rows: ProcessRow[] | null) => rows?.find(row => sameProcessIdentity(row, session.processIdentity)
+ && row.executable === session.processIdentity!.executable)
+ /** How the client was started, read from its argv by the engine's declared flags. */
+ const startedAs = (server: SharedServerContract, owner: ProcessRow) => {
+ const args = deps.argv(owner.args)
+ // An interpreter running the CLI's script (`node …/codex.js`): its options start after the script.
+ const option = /^node(?:\.exe)?$/.test(basename(args[0] ?? '')) && server.scripts.includes(basename(args[1] ?? '')) ? 2 : 1
+ // Harness inserts the owned flag as the FIRST option, before resume/fork or prompt
+ // text. A prompt merely mentioning it is not proof of ownership.
+ return {
+ owned: args[option] === server.ownedFlag,
+ remote: args.slice(option).some(arg => arg === server.remoteFlag || arg.startsWith(`${server.remoteFlag}=`)),
+ }
+ }
+ /** The server's own record of its process, in the store; null when it keeps none (older or process-owned). */
+ const serverProcess = async (server: SharedServerContract, home: string): Promise<{ pid: number; startedAt: string } | null> => {
+ let text: string
+ try { text = await deps.readFile(join(home, server.pidFile)) }
+ catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null; throw error }
+ const value = JSON.parse(text)
+ if (!Number.isSafeInteger(value.pid) || value.pid <= 0 || typeof value.processStartTime !== 'string') throw new Error('Invalid Codex server identity')
+ return { pid: value.pid, startedAt: value.processStartTime }
+ }
+ const sameStart = (a: string, b: string) => a.trim().replace(/\s+/g, ' ') === b.trim().replace(/\s+/g, ' ')
+
+ /** A stop's question, answered under its grant; anything outside it is refused and ends the grant. */
+ const answer = (service: string, query: string, payload: Record<string, unknown>): Record<string, unknown> | null => {
+ if (query !== NATIVE_CONTROL_HOST) return null
+ const denied = { version: NATIVE_CONTROL_VERSION, error: 'ANSWER_FAILED' }
+ if (!nativeEnvelope(payload, ['query', 'token', 'action']) || typeof payload.token !== 'string' || !nativeStopAction(payload.action)) return denied
+ const token = payload.token, grant = grants.get(token), action = payload.action
+ if (!grant || grant.service !== service) return denied
+ if (++grant.queries > NATIVE_STOP_QUERIES) { grants.delete(token); return denied }
+ // The step is undone, or was never taken: nothing is left to repair.
+ if (action.kind === 'settled') { repairs.delete(token); return { version: NATIVE_CONTROL_VERSION, value: true } }
+ let value: boolean
+ try { value = grant.current() } catch { grants.delete(token); return denied }
+ // No longer wanted: this stop may do nothing more, whatever it asks next.
+ if (!value) grants.delete(token)
+ // Noted before the step is taken: if this worker is lost before `settled`, the next one undoes it.
+ else if (action.kind === 'pending') repairs.set(token, { service: grant.service, engine: grant.engine, conversation: grant.conversation })
+ return { version: NATIVE_CONTROL_VERSION, value }
+ }
+
+ /** What a lost worker's stop may have left, undone once through the worker that replaced it. */
+ const recover = async (token: string): Promise<void> => {
+ const repair = repairs.get(token)!
+ repairs.delete(token)
+ const what = `${repair.engine} conversation ${sid(repair.conversation.sessionId)}`
+ try {
+ const done = await recoveries.read(repair.engine, NATIVE_RECOVER, { conversation: repair.conversation }, value => typeof value === 'boolean')
+ log(done ? `[stop] restored the history of ${what}, which a lost worker's stop had archived`
+ : `[stop] could not restore the history of ${what}; it may still be archived on its server`)
+ } catch { log(`[stop] could not ask the engine's worker to restore ${what}; it may still be archived on its server`) }
+ }
+
+ return {
+ answer,
+
+ /** What the engine's server says a conversation is doing; unknown whenever it cannot say. */
+ async activity(session: RegisteredSession): Promise<ActivityState> {
+ const server = deps.servers[session.engine]
+ if (!server || !session.processIdentity) return 'unknown'
+ if (!rowsRead || now() - rowsAt > 2_000) { rowsAt = now(); rowsRead = deps.rows() }
+ const owner = ownerOf(session, await rowsRead)
+ if (!owner) return 'unknown'
+ const started = startedAs(server, owner)
+ const conversation = { home: deps.home(session), sessionId: session.sessionId }
+ if (started.owned || started.remote || !nativeConversation(conversation)) return 'unknown'
+ try {
+ const state = deps.handles(session.engine)
+ ? await reads.read(session.engine, NATIVE_ACTIVITY, { conversation }, nativeActivity) as ActivityState
+ : await deps.inline(session.engine)?.activity(conversation)
+ return state ?? 'unknown'
+ } catch { return 'unknown' }
+ },
+
+ /**
+ * Called AFTER a checkpoint and BEFORE signalling the terminal: unload the session's conversation from its
+ * engine's server when it is on one. Throws the person's message when the client must not be signalled.
+ * Every decision but the server's protocol is core's, so a stop needs the engine's worker only for a
+ * conversation that is on a running server, as the former code needed the server's connection only then.
+ */
+ async stop(session: RegisteredSession, current: () => boolean, confirmUnusedConversation?: (session: RegisteredSession) => Promise<boolean>): Promise<void> {
+ const server = deps.servers[session.engine]
+ if (!server) return
+ const rows = await deps.rows()
+ if (!rows) throw new Error(server.messages.unverified)
+ const guard = () => { if (!current()) throw new Error(CANCELLED) }
+ // Close can beat discovery's exit reconciliation: the client has already
+ // returned to its shell, with no conversation ever bound. Its checkpoint is
+ // saved, and an unrelated shared server is not a reason to keep that pane.
+ // Missing/recycled process identity and previously bound conversations still
+ // need the normal verification below.
+ if (session.processIdentity && !rows.some(row => row.pid === session.processIdentity!.pid)
+ && !session.sessionId && !session.transcriptPath && session.boundAt == null && !session.resumeOnly) {
+ guard()
+ return
+ }
+ const owner = ownerOf(session, rows)
+ if (owner) {
+ const started = startedAs(server, owner)
+ // A remote app-server is not controlled by this machine's profile. Do not
+ // report its work stopped merely because its local terminal was closed.
+ if (started.remote) throw new Error(server.messages.remote)
+ if (started.owned) return
+ }
+ const home = deps.home(session)
+ const daemon = await serverProcess(server, home)
+ if (!daemon) return // Older/process-owned engine has no detached writer.
+ if (!rows.some(row => row.pid === daemon.pid && sameStart(row.startMarker, daemon.startedAt))) return
+ if (!session.sessionId) {
+ // An unused TUI has no conversation to unload. Close supplies fresh proof
+ // of its empty composer after saving the screen; Pause and uncertain
+ // discovery still require an exact conversation identity.
+ if (owner && await confirmUnusedConversation?.(session)) {
+ guard()
+ return
+ }
+ throw new Error(server.messages.unidentified)
+ }
+ const conversation = { home, sessionId: session.sessionId }
+ if (!boundConversation(conversation)) throw new Error(NATIVE_UNCONFIRMED)
+ const engine = session.engine as ReaderEngine, service = READER_SERVICES[engine]
+ const token = randomBytes(32).toString('hex')
+ grants.set(token, { service, engine, conversation, current, queries: 0 })
+ let answered: NativeStopAnswer | null = null
+ try {
+ if (deps.handles(engine)) answered = await stops.read(engine, NATIVE_STOP, { token, conversation }, nativeStopAnswer) as NativeStopAnswer
+ else {
+ const control = deps.inline(engine)
+ if (!control) throw new Error(NATIVE_UNCONFIRMED)
+ const host = createNativeStopHost(async action => answer(service, NATIVE_CONTROL_HOST, { version: NATIVE_CONTROL_VERSION, token, action })!)
+ answered = await boundedControl(control.stop(conversation, host).then(() => ({ stopped: true as const }),
+ (error: unknown) => ({ refused: error instanceof Error && nativeMessage(error.message) ? error.message : NATIVE_UNCONFIRMED })),
+ NATIVE_STOP_WAIT_MS, () => new Error(NATIVE_UNCONFIRMED))
+ }
+ } catch {
+ // The worker did not answer: as when the former in-process connection to the server failed, the
+ // stop is not confirmed and the client is not signalled. A step it noted stays to be undone.
+ log(`[stop] ${sid(session.agentId)} the ${engine} worker did not answer the stop; its conversation is not confirmed stopped, and its pane stays`)
+ }
+ finally {
+ grants.delete(token)
+ // Answered, the worker made its own attempt to undo its step; only a lost one leaves it to repair.
+ if (answered || !deps.handles(engine)) repairs.delete(token)
+ }
+ if (!answered) throw new Error(NATIVE_UNCONFIRMED)
+ if ('refused' in answered) throw new Error(answered.refused)
+ },
+
+ connected(service: string): void {
+ reads.connected(service); stops.connected(service); recoveries.connected(service); revoke(service)
+ for (const [token, repair] of repairs) if (repair.service === service) void recover(token)
+ },
+ disconnected(service: string): void { reads.disconnected(service); stops.disconnected(service); recoveries.disconnected(service); revoke(service) },
+ /** The inline control's connections, as the core shuts down; a worker's close with its process. */
+ close(): void { for (const engine of Object.keys(deps.servers)) deps.inline(engine)?.close() },
+ }
+
+ /** A stop never continues on a replaced connection: its grant goes with the one that asked. */
+ function revoke(service: string): void {
+ for (const [token, grant] of grants) if (grant.service === service) grants.delete(token)
+ }
+}
+
+export type NativeControls = ReturnType<typeof createNativeControls>
diff --git a/cli/src/core/main.ts b/cli/src/core/main.ts
index f9c82712f..4246a0564 100644
--- a/cli/src/core/main.ts
+++ b/cli/src/core/main.ts
@@ -7,6 +7,10 @@ import { createScreenTransport } from './engines/screenTransport.js'
import { legacyScreen } from '../lib/legacyScreen.js'
import { masterRunsEngineScreen } from '../harnessd/services.js'
import { createSubmissions } from './engines/submissions.js'
+import { createNativeControls } from './engines/nativeControls.js'
+import { createEngineLinks } from './engines/engineLinks.js'
+import { engineLaunches } from '../engines/launches.js'
+import { masterRunsEngineNativeControl } from '../harnessd/services.js'
import { submissionPolicy } from '../engines/submissionPolicies.js'
import { createSubmissionTransport } from './engines/submissionTransport.js'
import { masterRunsEngineSubmission } from '../harnessd/services.js'
@@ -22,6 +26,7 @@ import { masterRunsEngineSubmission } from '../harnessd/services.js'
* the core with `__run`.
*/
import { readFileSync, writeFileSync, openSync, existsSync, rmSync, statSync } from 'fs'
+import { readFile } from 'node:fs/promises'
import { join } from 'path'
import { execFile, spawn } from 'child_process'
import { createServer, type Server } from 'http'
@@ -76,7 +81,8 @@ import { rememberSavedApis } from '../lib/apiModels.js'
import { prepareApiInstructions } from '../lib/apiInstructions.js'
import type { AgentDshContext } from '../lib/agentFrame.js'
import type { AgentGridTarget, GridAnnotation } from '../lib/gridAnnotation.js'
-import { clearPaneRemainOnExit, lookupPaneEngineProcess, resolvePaneEngineProcess, tmuxPaneInfo, tmuxPaneState } from '../lib/tmux.js'
+import { sessionCodexHome } from '../lib/engineHomes.js'
+import { argvTokens, clearPaneRemainOnExit, lookupPaneEngineProcess, processRows, resolvePaneEngineProcess, tmuxPaneInfo, tmuxPaneState } from '../lib/tmux.js'
import { ALL_TERMINAL_BACKENDS } from '../config/terminalConfig.js'
import { TerminalBackendCoordinator } from '../lib/terminalBackendCoordinator.js'
import { TerminalStreamManager } from '../lib/terminalStreamManager.js'
@@ -560,9 +566,11 @@ async function runForeground(session: AuthSession | null): Promise<void> {
const screenHosted = masterRunsEngineScreen(process.env, process.ppid)
const isolatedScreen = (engine: string): boolean => screenHosted && isolatedLive(engine)
const submissionHosted = masterRunsEngineSubmission(process.env, process.ppid)
+ const nativeControlHosted = masterRunsEngineNativeControl(process.env, process.ppid)
+ const isolatedNativeControl = (engine: string): boolean => nativeControlHosted && isolatedLive(engine)
const isolatedSubmission = (engine: string): boolean => submissionHosted && isolatedLive(engine)
const isolatedRuntime = (engine: string): boolean => runtimeHosted && isolatedLive(engine)
- const inline = KNOWN_SERVICES.some((name) => !outOfProcess.has(name)) || !runtimeHosted || !screenHosted || !modelControlHosted || !questionControlHosted || !submissionHosted
+ const inline = KNOWN_SERVICES.some((name) => !outOfProcess.has(name)) || !runtimeHosted || !screenHosted || !modelControlHosted || !questionControlHosted || !submissionHosted || !nativeControlHosted
? await import('../services/inline.js') : null
let serviceLinksRef: ServiceLinks | null = null
const runtimeTransport = createRuntimeTransport({
@@ -578,6 +586,15 @@ async function runForeground(session: AuthSession | null): Promise<void> {
})
const submissions = createSubmissions({ policy: submissionPolicy, handles: isolatedSubmission, transport: submissionTransport, resolve: id => registry.resolve(id),
inline: engine => inline?.submissionFor(engine) })
+ // Codex's shared app-server, spoken to from its worker: core identifies the conversation and decides.
+ const nativeControls = createNativeControls({
+ call: (service, type, payload, waitMs) => serviceLinksRef?.call(service, type, payload, waitMs) ?? Promise.resolve({ error: 'SERVICE_UNAVAILABLE' }),
+ servers: Object.fromEntries(Object.entries(engineLaunches).flatMap(([name, launch]) => 'sharedServer' in launch && launch.sharedServer ? [[name, launch.sharedServer]] : [])),
+ handles: isolatedNativeControl, inline: engine => isolatedNativeControl(engine) ? undefined : inline?.nativeControlFor(engine),
+ rows: processRows, home: session => sessionCodexHome(session), argv: argvTokens, readFile: path => readFile(path, 'utf8'),
+ })
+ // Which engine workers are linked now: a close's read refused by a restart waits here for the new link.
+ const engineLinks = createEngineLinks()
const runtimeProfiles = createRuntimeProfiles({
legacy: new LegacyRuntimeProfileManager(engine => isolatedRuntime(engine) ? undefined : inline?.runtimeFor(engine)),
handles: isolatedRuntime,
@@ -976,8 +993,8 @@ async function runForeground(session: AuthSession | null): Promise<void> {
bySession: (sessionId) => registry.bySession(sessionId),
sessionTurnOpen,
drain: (sessionId) => watcher.pollSession(sessionId),
+ nativeActivity: (session) => nativeControls.activity(session),
})
- const codexActivity = activity.codexActivity
const runtimeActivity = activity.runtimeActivity
const turnActivity = activity.turnActivity
activityFrameContextRef = activity.activityFrame
@@ -1224,7 +1241,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {
onDemand: new Set([...experiments, ...DEVICES_ON_DEMAND, ...Object.values(READER_SERVICES), 'models', 'gateway', 'shell']),
want: (service) => experimentHooks.want(service),
// The gateway's first: its `backend` reads (the device key log) were refused below as NOT_AN_EXPERIMENT.
- answer: async (service, query, payload) => await questionControls.answer(service, query, payload) ?? await modelControls.answer(service, query, payload) ?? engineReaders.answer(service) ?? (service === 'gateway' && gatewayLink ? gatewayLink.answer(query, payload) : null) ?? deliveries.answer(service, query, payload)
+ answer: async (service, query, payload) => await questionControls.answer(service, query, payload) ?? await modelControls.answer(service, query, payload) ?? await nativeControls.answer(service, query, payload) ?? engineReaders.answer(service) ?? (service === 'gateway' && gatewayLink ? gatewayLink.answer(query, payload) : null) ?? deliveries.answer(service, query, payload)
?? await answerExperimentQuery(coreApi, experiments, service, query, payload)
?? await terminalWatch.answer(service, query, payload)
?? (service === 'orchestrator' ? orchestratorLink.answer(query, payload) : null)
@@ -1248,6 +1265,8 @@ async function runForeground(session: AuthSession | null): Promise<void> {
runtimeTransport.connected(service)
screenTransport.connected(service)
submissionTransport.connected(service)
+ nativeControls.connected(service)
+ engineLinks.connected(service)
modelControls.connected(service)
questionControls.connected(service)
if (service === 'gateway') gatewayLink?.connected()
@@ -1262,6 +1281,8 @@ async function runForeground(session: AuthSession | null): Promise<void> {
runtimeTransport.disconnected(service)
screenTransport.disconnected(service)
submissionTransport.disconnected(service)
+ nativeControls.disconnected(service)
+ engineLinks.disconnected(service)
modelControls.disconnected(service)
questionControls.disconnected(service)
if (service === 'gateway') gatewayLink?.disconnected()
@@ -2266,6 +2287,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {
forgetSession,
markDeleted,
clearDeleted,
+ stopNative: (session, current, confirmUnused) => nativeControls.stop(session, current, confirmUnused),
sessionCheckpoints,
mirror,
sessionSearch,
@@ -2299,6 +2321,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {
sessionCheckpoints,
stopAgent,
announceSession,
+ engineReady: (engine, ms) => engineLinks.ready(engine, ms),
})
backend.closeAgentService = closing.closeAgentService
backend.closeAgentService.start()
@@ -2381,7 +2404,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {
['the hook connections', () => (hookServer as unknown as { closeAllConnections?: () => void }).closeAllConnections?.()],
['Share', () => ports.sharing?.stop()],
['the local websocket', () => localWsServer.close()], ['the hook server', () => hookServer.close()],
- ['the local socket', () => localSocket?.close()], ['Codex activity', () => codexActivity.close()],
+ ['the local socket', () => localSocket?.close()], ['Codex activity', () => nativeControls.close()],
// The serial ports, the lane and the voice router's worker: a port held through the handoff makes the
// next daemon's dial, and esptool, fail as if the hardware had died.
['the devices', () => ports.devices?.stop()],
@@ -2432,7 +2455,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {
await localSocket?.close()
await localWsServer.close()
hookServer.close()
- codexActivity.close()
+ nativeControls.close()
await ports.viewers?.stop()
await gateway.stop()
await backend.stop()
diff --git a/cli/src/core/turns/activity.spec.ts b/cli/src/core/turns/activity.spec.ts
index 448a6c307..faf15119e 100644
--- a/cli/src/core/turns/activity.spec.ts
+++ b/cli/src/core/turns/activity.spec.ts
@@ -17,6 +17,7 @@ function setup(over: Partial<TurnActivityDeps> = {}) {
bySession: (sessionId) => sessions.get(sessionId),
sessionTurnOpen: (sessionId) => sessionId === 's1',
drain: vi.fn(async () => {}),
+ nativeActivity: vi.fn(async () => 'idle' as const),
...over,
}
return { deps, readers: createTurnActivity(deps) }
@@ -42,12 +43,11 @@ describe('turn activity', () => {
expect(await turn.probe('s2')).toBe('unknown')
})
- it('reads Codex\'s activity from Codex, and every other runtime from what its pane shows', async () => {
+ it('reads Codex\'s activity from its own server (through its worker), and every other runtime from what its pane shows', async () => {
const { deps, readers } = setup()
const runtime = given(readers.runtimeActivity)
- const codex = vi.spyOn(readers.codexActivity, 'read').mockResolvedValue('idle' as never)
expect(await runtime.codex(live)).toBe('idle')
- expect(codex).toHaveBeenCalledWith(live)
+ expect(deps.nativeActivity).toHaveBeenCalledWith(live)
expect(await runtime.capture(live)).toBe('screen')
expect(deps.terminals.capture).toHaveBeenCalledWith(live, { mode: 'visible', ansi: true })
vi.mocked(deps.terminals.capture).mockResolvedValueOnce({ state: 'failed', reason: 'no pane' })
diff --git a/cli/src/core/turns/activity.ts b/cli/src/core/turns/activity.ts
index 979463662..8d24b1e6c 100644
--- a/cli/src/core/turns/activity.ts
+++ b/cli/src/core/turns/activity.ts
@@ -8,7 +8,8 @@ import type { ScreenReader } from '../../lib/screenReader.js'
*/
import { isTerminalEngine } from '../../engines/types.js'
import type { RegisteredSession } from '../../lib/registry.js'
-import { CodexActivityReader, RuntimeActivityReader, activityRuntimeKey } from '../../lib/runtimeActivity.js'
+import { RuntimeActivityReader, activityRuntimeKey } from '../../lib/runtimeActivity.js'
+import type { ActivityState } from '../../lib/turnActivity.js'
import type { TerminalBackendCoordinator } from '../../lib/terminalBackendCoordinator.js'
import { TurnActivity, type ActivityFrame } from '../../lib/turnActivity.js'
@@ -19,13 +20,14 @@ export interface TurnActivityDeps {
sessionTurnOpen: (sessionId: string) => boolean
/** Read whatever the session's transcript has that the tail has not delivered yet (Watcher.pollSession). */
drain: (sessionId: string) => Promise<void>
+ /** What the engine's own server says (Codex's app-server, read in its worker: core/engines/nativeControls.ts). */
+ nativeActivity: (session: RegisteredSession) => Promise<ActivityState>
}
-export function createTurnActivity({ readScreen, terminals, bySession, sessionTurnOpen, drain }: TurnActivityDeps) {
- const codexActivity = new CodexActivityReader()
+export function createTurnActivity({ readScreen, terminals, bySession, sessionTurnOpen, drain, nativeActivity }: TurnActivityDeps) {
const runtimeActivity = new RuntimeActivityReader({
readScreen,
- codex: session => codexActivity.read(session),
+ codex: session => nativeActivity(session),
capture: async session => {
const screen = await terminals.capture(session, { mode: 'visible', ansi: true })
return screen.state === 'succeeded' ? screen.value : null
@@ -45,7 +47,7 @@ export function createTurnActivity({ readScreen, terminals, bySession, sessionTu
/** The activity the app shows for an agent; none for a plain terminal. */
const activityFrame = (session: RegisteredSession): ActivityFrame | null =>
isTerminalEngine(session.engine) ? null : turnActivity.snapshot(session.sessionId) ?? null
- return { codexActivity, runtimeActivity, turnActivity, activityFrame }
+ return { runtimeActivity, turnActivity, activityFrame }
}
export type TurnActivityReaders = ReturnType<typeof createTurnActivity>
diff --git a/cli/src/engines/README.md b/cli/src/engines/README.md
index 90c3f972b..f934638a4 100644
--- a/cli/src/engines/README.md
+++ b/cli/src/engines/README.md
@@ -18,10 +18,11 @@ that stream.
launch contracts, history/last-turn readers and hook behavior behind `Engine` (`engine.ts`). `registry.ts`
selects those engines; `launches.ts` and `hooks.ts` expose their respective facets without loading history
readers. Hook transport, process binding and event delivery stay with core. Claude Code and Codex history/last-turn reads,
-live transcript parsing, runtime profiles/catalogs, screen interpretation, submission readings, model-control drivers and question navigation run on demand in supervised workers;
+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
[question control](../../../docs/design/2026-10-08-engine-question-control.md),
[submission](../../../docs/design/2026-10-08-engine-submission.md),
+[native control](../../../docs/design/2026-10-08-engine-native-control.md),
[model control](../../../docs/design/2026-10-08-engine-model-control.md),
[screen interpretation](../../../docs/design/2026-10-08-engine-screen.md),
[runtime profiles](../../../docs/design/2026-10-08-engine-runtime.md) and the
diff --git a/cli/src/engines/codex/launch.ts b/cli/src/engines/codex/launch.ts
index ae88b503b..d53a65f86 100644
--- a/cli/src/engines/codex/launch.ts
+++ b/cli/src/engines/codex/launch.ts
@@ -27,4 +27,14 @@ export const launch: EngineLaunch = {
permissionModes, bypassPermission: permissionModes.auto,
firstPromptArgs: [], resumeArgs: ['resume'], forkArgs: { lead: ['fork'] },
instructionFiles: ['AGENTS.override.md', 'AGENTS.md'], envArgs: codexEnvArgs,
+ // Older Codex shares one app-server per CODEX_HOME, which owns work independently of its terminal client.
+ // New Harness launches opt out with --no-daemon (lib/engineLaunch.ts), as the first option.
+ sharedServer: {
+ ownedFlag: '--no-daemon', remoteFlag: '--remote', scripts: ['codex', 'codex.js'], pidFile: 'app-server-daemon/daemon.pid',
+ messages: {
+ unverified: 'Could not verify the Codex server before stopping',
+ remote: 'Stop this conversation on its remote Codex server before closing its terminal',
+ unidentified: 'Could not identify the conversation on the Codex server; the session is still open',
+ },
+ },
}
diff --git a/cli/src/engines/codex/nativeControl.ts b/cli/src/engines/codex/nativeControl.ts
new file mode 100644
index 000000000..7517f4c32
--- /dev/null
+++ b/cli/src/engines/codex/nativeControl.ts
@@ -0,0 +1,166 @@
+/** Codex's shared app-server owns work independently of its terminal client.
+ * Never kill that server: unload only the confirmed conversation, leaving its
+ * history available and all other clients running. New Harness launches opt out
+ * of sharing, but sessions opened before an upgrade still need this path.
+ * Moved from lib/codexSessionLifecycle.ts and lib/runtimeActivity.ts into the Codex worker. Core establishes
+ * from its own evidence and the launch contract that a conversation is on the server (core/engines/
+ * nativeControls.ts); this speaks the server's protocol for it (engines/facets/nativeControl.ts). */
+import { spawn } from 'node:child_process'
+import { Duplex } from 'node:stream'
+import { realpath } from 'node:fs/promises'
+import WebSocket from 'ws'
+import { engineBin } from '../../lib/engineBin.js'
+import type { EngineNativeControl, NativeConversation } from '../facets/nativeControl.js'
+
+export interface CodexControl {
+ request(method: string, params: Record<string, unknown>): Promise<any>
+ close(): void
+}
+
+/** The CLI resolves its own socket location. It does not start a server. `proxy`
+ * carries raw WebSocket bytes (not JSONL), as documented by Codex app-server. */
+export async function connectCodexControl(home: string): Promise<CodexControl> {
+ const child = spawn(engineBin('codex'), ['app-server', 'proxy'], {
+ env: { ...process.env, CODEX_HOME: home }, stdio: ['pipe', 'pipe', 'ignore'],
+ })
+ const pipe = Duplex.from({ readable: child.stdout, writable: child.stdin })
+ const ws = new WebSocket('ws://localhost/', { createConnection: () => pipe as any,
+ handshakeTimeout: 3_000, maxPayload: 2 << 20, perMessageDeflate: false })
+ let nextId = 0
+ const pending = new Map<number, { resolve(value: unknown): void; reject(error: Error): void; timer: ReturnType<typeof setTimeout> }>()
+ const fail = (error: Error) => {
+ for (const entry of pending.values()) { clearTimeout(entry.timer); entry.reject(error) }
+ pending.clear()
+ }
+ const close = () => { fail(new Error('Codex control connection closed')); ws.terminate(); pipe.destroy(); child.kill() }
+ child.on('error', error => { fail(error); ws.terminate() })
+ child.on('exit', () => { fail(new Error('Codex control proxy exited')); ws.terminate() })
+ pipe.on('error', error => { fail(error); ws.terminate() })
+ ws.on('error', fail)
+ ws.on('close', () => { fail(new Error('Codex control connection closed')); pipe.destroy(); child.kill() })
+ ws.on('message', bytes => {
+ try {
+ const frame = JSON.parse(String(bytes))
+ const entry = pending.get(frame.id)
+ if (!entry) return
+ pending.delete(frame.id); clearTimeout(entry.timer)
+ if (frame.error) entry.reject(new Error(`Codex could not ${String(frame.error.message ?? 'complete the request').slice(0, 300)}`))
+ else entry.resolve(frame.result)
+ } catch { fail(new Error('Invalid Codex control response')); ws.terminate() }
+ })
+ const request: CodexControl['request'] = (method, params) => new Promise((resolve, reject) => {
+ if (ws.readyState !== WebSocket.OPEN) { reject(new Error('Codex control is unavailable')); return }
+ const id = ++nextId
+ const timer = setTimeout(() => { pending.delete(id); reject(new Error('Codex control request timed out')) }, 5_000)
+ pending.set(id, { resolve, reject, timer })
+ ws.send(JSON.stringify({ id, method, params }), error => {
+ if (error) { clearTimeout(timer); pending.delete(id); reject(error) }
+ })
+ })
+ try {
+ await new Promise<void>((resolve, reject) => {
+ ws.once('open', resolve); ws.once('error', reject)
+ ws.once('close', () => reject(new Error('Codex control connection closed')))
+ })
+ const initialized = await request('initialize', { clientInfo: { name: 'harness', version: '1' }, capabilities: { experimentalApi: true } })
+ if (typeof initialized?.codexHome !== 'string' || await realpath(initialized.codexHome) !== await realpath(home)) {
+ throw new Error('Codex returned a different session store')
+ }
+ ws.send(JSON.stringify({ method: 'initialized' }))
+ return { request, close }
+ } catch (error) { close(); throw error }
+}
+
+export interface CodexNativeDeps {
+ connect(home: string): Promise<CodexControl>
+ now(): number
+}
+
+export function createNativeControl(deps: CodexNativeDeps = { connect: connectCodexControl, now: () => performance.now() }): EngineNativeControl {
+ // Read-only activity connections, shared by profile. Never launch/resume a thread or
+ // start an app-server to inspect it. An unrelated server's notLoaded is unknown.
+ const controls = new Map<string, Promise<CodexControl>>()
+ const retryAt = new Map<string, number>()
+ return {
+ async activity({ home, sessionId }: NativeConversation) {
+ if ((retryAt.get(home) ?? 0) > deps.now()) return 'unknown'
+ let connection = controls.get(home)
+ if (!connection) { connection = deps.connect(home); controls.set(home, connection) }
+ try {
+ const control = await connection
+ const read = await control.request('thread/read', { threadId: sessionId })
+ if (read?.thread?.id !== sessionId) return 'unknown'
+ if (read.thread.status?.type === 'active') return 'working'
+ if (read.thread.status?.type === 'idle') return 'idle'
+ return 'unknown'
+ } catch {
+ // An old/process-owned engine may share its profile with another server.
+ // Do not keep spawning a failed proxy for every session every five seconds.
+ if (controls.get(home) === connection) controls.delete(home)
+ void connection.then(control => control.close()).catch(() => {})
+ retryAt.set(home, deps.now() + 60_000)
+ return 'unknown'
+ }
+ },
+
+ /** Called AFTER a checkpoint and BEFORE signalling the terminal, for a conversation core established is on
+ * a running server. There is no polling, model call, archive deletion or machine-wide daemon shutdown here. */
+ async stop({ home, sessionId }, host) {
+ const cancelled = () => new Error('The close request was cancelled or the session changed')
+ const guard = async () => { if (!await host.current()) throw cancelled() }
+ const control = await deps.connect(home)
+ try {
+ await guard()
+ const read = await control.request('thread/read', { threadId: sessionId })
+ if (read?.thread?.id !== sessionId) throw new Error('Codex returned a different conversation')
+ if (read.thread.status?.type === 'notLoaded') return
+ // A process-owned session can share its profile with an unrelated daemon;
+ // thread/read reports notLoaded there and none of the calls below occur.
+ const goal = await control.request('thread/goal/get', { threadId: sessionId })
+ await guard()
+ if (goal?.goal?.status === 'active') {
+ await control.request('thread/goal/set', { threadId: sessionId, status: 'paused' })
+ }
+ await guard()
+ const turns = await control.request('thread/turns/list', { threadId: sessionId, limit: 1, itemsView: 'summary' })
+ await guard()
+ const active = turns?.data?.find((turn: any) => turn.status === 'inProgress')
+ if (active) await control.request('turn/interrupt', { threadId: sessionId, turnId: active.id })
+ // Core notes the archive before it is sent: cut off before its unarchive, this worker gone, core asks
+ // the next one to return the history (recover, below). It is the guard here, too.
+ if (!await host.pending()) throw cancelled()
+ // Archive is the public operation that unloads a thread. Unarchive moves
+ // only its saved history back; it does not restart the thread. Always undo
+ // the archive even if the user reopens while its response is in flight.
+ let archiveError: unknown
+ try { await control.request('thread/archive', { threadId: sessionId }) }
+ catch (error) { archiveError = error }
+ // A timed-out reply does not prove the archive failed to happen. Always
+ // attempt to return the history to sessions before reporting the error.
+ try { await control.request('thread/unarchive', { threadId: sessionId }) }
+ catch (error) { throw archiveError ?? error }
+ await host.settled()
+ if (archiveError) throw archiveError
+ await guard()
+ const after = await control.request('thread/read', { threadId: sessionId })
+ if (after?.thread?.id !== sessionId || after.thread.status?.type !== 'notLoaded') {
+ throw new Error('Could not confirm the Codex conversation stopped; its pane remains open')
+ }
+ } finally { control.close() }
+ },
+
+ /** The history of a thread a lost worker archived and never unarchived, returned once. */
+ async recover({ home, sessionId }) {
+ const control = await deps.connect(home)
+ try { await control.request('thread/unarchive', { threadId: sessionId }) }
+ finally { control.close() }
+ },
+
+ close() {
+ for (const control of controls.values()) void control.then(value => value.close()).catch(() => {})
+ controls.clear()
+ },
+ }
+}
+
+export const nativeControl = createNativeControl()
diff --git a/cli/src/engines/engine.ts b/cli/src/engines/engine.ts
index a30fba004..9f6a995d7 100644
--- a/cli/src/engines/engine.ts
+++ b/cli/src/engines/engine.ts
@@ -1,5 +1,6 @@
import type { EngineQuestionControl } from './facets/questionControl.js'
import type { EngineSubmission } from './facets/submission.js'
+import type { EngineNativeControl } from './facets/nativeControl.js'
import type { EngineScreen } from './facets/screen.js'
import type { EngineModelControl } from './facets/modelControl.js'
import type { ProcessEngine } from './types.js'
@@ -21,4 +22,6 @@ export interface Engine {
readonly modelControl: EngineModelControl
readonly questionControl: EngineQuestionControl
readonly submission: EngineSubmission
+ /** Only an engine whose CLI leaves work on a server of its own (Codex). */
+ readonly nativeControl?: EngineNativeControl
}
diff --git a/cli/src/engines/facets/launch.ts b/cli/src/engines/facets/launch.ts
index 37a16add1..55c402946 100644
--- a/cli/src/engines/facets/launch.ts
+++ b/cli/src/engines/facets/launch.ts
@@ -1,3 +1,22 @@
+/**
+ * An engine whose CLI can leave work on a server of its own, shared per store (Codex's app-server). Declared
+ * data: core decides from it, with no worker, whether a client's conversation lives on that server at all,
+ * and the server's protocol is the engine worker's (facets/nativeControl.ts). Copied from the former
+ * lib/codexSessionLifecycle.ts, which read these facts in core before the move.
+ */
+export interface SharedServerContract {
+ /** Harness puts this first among the options of a client that owns its conversation in its own process. */
+ ownedFlag: string
+ /** A client given this option (or `<flag>=…`) works on a remote server, which no local stop reaches. */
+ remoteFlag: string
+ /** The script's basenames when an interpreter (node) runs the CLI: its options start after the script. */
+ scripts: readonly string[]
+ /** Where, in the store, the server records its process, as JSON `{ pid, processStartTime }`. */
+ pidFile: string
+ /** What the person is told when the stop cannot go on, in the engine's own words. */
+ messages: { unverified: string; remote: string; unidentified: string }
+}
+
/** Literal argv contracts copied from the existing launch paths. No engine version behavior changes. */
export interface EngineLaunch {
permissionModes: Readonly<Record<string, readonly string[]>>
@@ -8,4 +27,5 @@ export interface EngineLaunch {
instructionFiles: readonly string[]
contextArgs?: (contextFile: string) => string[]
envArgs?: (env: Record<string, string>) => string[]
+ sharedServer?: SharedServerContract
}
diff --git a/cli/src/engines/facets/nativeControl.ts b/cli/src/engines/facets/nativeControl.ts
new file mode 100644
index 000000000..175f8cfcd
--- /dev/null
+++ b/cli/src/engines/facets/nativeControl.ts
@@ -0,0 +1,38 @@
+/**
+ * An engine's own control connection to the server that runs its conversations (Codex's shared app-server),
+ * run in the engine's worker. Core decides everything it can from what it holds and the engine's declared
+ * contract (facets/launch.ts `SharedServerContract`): the process table, the session's identity and store,
+ * whether a client owns its conversation, whether the server runs, whether an unbound chat was never used.
+ * The engine speaks its protocol, and only for a conversation core has established is on the server.
+ */
+
+/** A conversation core established is on the engine's server: its store, and its id ('' when none was bound). */
+export interface NativeConversation {
+ home: string
+ sessionId: string
+}
+
+export type NativeActivity = 'working' | 'idle' | 'unknown'
+
+/** What core lets one stop ask and tell. Every answer is core's; a no revokes the stop. */
+export interface NativeStopHost {
+ /** Still the same session, and still wanted. */
+ current(): Promise<boolean>
+ /** About to take a step that must be undone if the stop is cut off before its undo (Codex's archive): core
+ * notes it, to undo it through the next worker if this one is lost. Also asks `current`. */
+ pending(): Promise<boolean>
+ /** That step is undone or never happened: nothing is left to repair. */
+ settled(): Promise<boolean>
+}
+
+export interface EngineNativeControl {
+ /** What the engine's server says the conversation is doing; unknown whenever it cannot say. */
+ activity(conversation: NativeConversation): Promise<NativeActivity>
+ /** Unload the conversation from the server before its client is signalled. Throws, with the person's
+ * message, when the client must not be signalled: the work may still be running. */
+ stop(conversation: NativeConversation, host: NativeStopHost): Promise<void>
+ /** Undo what a stop cut off after `pending` may have left (Codex: return the archived thread's history). */
+ recover(conversation: NativeConversation): Promise<void>
+ /** Close every connection this control holds. */
+ close(): void
+}
diff --git a/cli/src/engines/nativeControls.ts b/cli/src/engines/nativeControls.ts
new file mode 100644
index 000000000..c81b6bc03
--- /dev/null
+++ b/cli/src/engines/nativeControls.ts
@@ -0,0 +1,3 @@
+/** Explicit inline composition; supervised core does not import the native control client. */
+import { nativeControl as codex } from './codex/nativeControl.js'
+export const nativeControlFor = (engine: string) => engine === 'codex' ? codex : undefined
diff --git a/cli/src/engines/registry.ts b/cli/src/engines/registry.ts
index 0d0d3b4af..e5baa7a07 100644
--- a/cli/src/engines/registry.ts
+++ b/cli/src/engines/registry.ts
@@ -3,6 +3,7 @@ import { questionControl as codexQuestionControl } from './codex/questionControl
import { screen as claudeScreen } from './claude/screen.js'
import { submission as claudeSubmission } from './claude/submission.js'
import { submission as codexSubmission } from './codex/submission.js'
+import { nativeControl as codexNativeControl } from './codex/nativeControl.js'
import { modelControl as claudeModelControl } from './claude/modelControl.js'
import { modelControl as codexModelControl } from './codex/modelControl.js'
import { screen as codexScreen } from './codex/screen.js'
@@ -19,7 +20,7 @@ import { runtime as codexRuntime } from './codex/runtimeProfile.js'
/** Only the migrated engines. Others keep their existing handlers until their own small batch. */
const engines = {
claude: { name: 'claude', launch: engineLaunches.claude, transcript: claudeTranscript, hooks: engineHooks.claude, live: claudeLive, runtime: claudeRuntime, screen: claudeScreen, modelControl: claudeModelControl, questionControl: claudeQuestionControl, submission: claudeSubmission },
- codex: { name: 'codex', launch: engineLaunches.codex, transcript: codexTranscript, hooks: engineHooks.codex, live: codexLive, runtime: codexRuntime, screen: codexScreen, modelControl: codexModelControl, questionControl: codexQuestionControl, submission: codexSubmission },
+ codex: { name: 'codex', launch: engineLaunches.codex, transcript: codexTranscript, hooks: engineHooks.codex, live: codexLive, runtime: codexRuntime, screen: codexScreen, modelControl: codexModelControl, questionControl: codexQuestionControl, submission: codexSubmission, nativeControl: codexNativeControl },
} satisfies Record<string, Engine>
type MigratedEngine = keyof typeof engines
export function engineFor(name: string | null | undefined): Engine | undefined {
diff --git a/cli/src/engines/worker/nativeControlHost.ts b/cli/src/engines/worker/nativeControlHost.ts
new file mode 100644
index 000000000..60e893479
--- /dev/null
+++ b/cli/src/engines/worker/nativeControlHost.ts
@@ -0,0 +1,15 @@
+import type { NativeStopHost } from '../facets/nativeControl.js'
+import { nativeEnvelope, type NativeStopAction } from './nativeControlProtocol.js'
+
+/** The person's message when core could not be asked: the stop is not confirmed, so the pane stays. */
+export const NATIVE_UNCONFIRMED = 'Could not confirm the conversation stopped on its engine\'s server; its pane remains open'
+
+/** A stop's questions to core, one at a time, each answered yes or no; anything else ends the stop. */
+export function createNativeStopHost(ask: (action: NativeStopAction) => Promise<Record<string, unknown>>): NativeStopHost {
+ const call = async (action: NativeStopAction) => {
+ const reply = await ask(action)
+ if (!nativeEnvelope(reply, ['value', 'error']) || reply.error !== undefined || typeof reply.value !== 'boolean') throw new Error(NATIVE_UNCONFIRMED)
+ return reply.value
+ }
+ return { current: () => call({ kind: 'current' }), pending: () => call({ kind: 'pending' }), settled: () => call({ kind: 'settled' }) }
+}
diff --git a/cli/src/engines/worker/nativeControlProtocol.ts b/cli/src/engines/worker/nativeControlProtocol.ts
new file mode 100644
index 000000000..9b44a2e6c
--- /dev/null
+++ b/cli/src/engines/worker/nativeControlProtocol.ts
@@ -0,0 +1,61 @@
+/**
+ * Private native-control messages: an engine's own connection to its conversation server, run in its
+ * worker. Core sends a conversation it established is on that server; a stop asks core before each effect.
+ */
+import { isAbsolute } from 'node:path'
+import type { NativeActivity, NativeConversation } from '../facets/nativeControl.js'
+import { record } from './protocol.js'
+import { controlEnvelope, controlFields as fields } from './controlWire.js'
+
+export const NATIVE_CONTROL_VERSION = 1
+export const NATIVE_CONTROL_CAPABILITIES = 'engine_native_control_capabilities'
+export const NATIVE_ACTIVITY = 'engine_native_activity'
+export const NATIVE_STOP = 'engine_native_stop'
+/** Undo what a stop cut off with its worker may have left: once, on the next worker's connection. */
+export const NATIVE_RECOVER = 'engine_native_recover'
+/** The query a stop asks core through, under its grant. */
+export const NATIVE_CONTROL_HOST = 'engine.nativeControl'
+/** A cold read connects (3 s handshake), initializes and reads (5 s each): above that the worker is stuck. */
+export const NATIVE_ACTIVITY_WAIT_MS = 15_000
+export const NATIVE_ACTIVITY_IN_FLIGHT = 8
+export const NATIVE_ACTIVITY_QUEUED = 64
+/** A connect and at most eight requests of 5 s each, with core's answers between them. */
+export const NATIVE_STOP_WAIT_MS = 60_000
+export const NATIVE_STOP_IN_FLIGHT = 4
+/** A connect and one request of 5 s each. */
+export const NATIVE_RECOVER_WAIT_MS = 15_000
+/** Core's answer to one question. */
+export const NATIVE_QUERY_MS = 10_000
+export const NATIVE_STOP_QUERIES = 32
+export const NATIVE_REPLY_BYTES = 4 * 1024
+const MESSAGE_CHARS = 600
+
+const text = (value: unknown, max: number): value is string => typeof value === 'string' && value.length <= max && !value.includes('\0')
+export const nativeEnvelope = (payload: Record<string, unknown>, names: string[]) => controlEnvelope(payload, NATIVE_CONTROL_VERSION, names)
+
+export function nativeConversation(value: unknown): value is NativeConversation {
+ return record(value) && fields(value, ['home', 'sessionId']) && text(value.home, 4096) && isAbsolute(value.home)
+ && text(value.sessionId, 200)
+}
+/** A stop or a recovery acts on a bound conversation only. */
+export const boundConversation = (value: unknown): value is NativeConversation => nativeConversation(value) && value.sessionId !== ''
+
+export function nativeActivity(value: unknown): value is NativeActivity {
+ return value === 'working' || value === 'idle' || value === 'unknown'
+}
+
+/** What a person is told of a refused stop: a line of text, never terminal control. */
+export function nativeMessage(value: unknown): value is string {
+ return typeof value === 'string' && value.length > 0 && value.length <= MESSAGE_CHARS && !/[\x00-\x1f\x7f]/.test(value)
+}
+
+export type NativeStopAnswer = { stopped: true } | { refused: string }
+export function nativeStopAnswer(value: unknown): value is NativeStopAnswer {
+ return record(value) && (fields(value, ['stopped']) && value.stopped === true || fields(value, ['refused']) && nativeMessage(value.refused))
+ && Object.keys(value).length === 1
+}
+
+export type NativeStopAction = { kind: 'current' } | { kind: 'pending' } | { kind: 'settled' }
+export function nativeStopAction(value: unknown): value is NativeStopAction {
+ return record(value) && fields(value, ['kind']) && (value.kind === 'current' || value.kind === 'pending' || value.kind === 'settled')
+}
diff --git a/cli/src/engines/worker/nativeControlRequests.spec.ts b/cli/src/engines/worker/nativeControlRequests.spec.ts
new file mode 100644
index 000000000..5a4e26773
--- /dev/null
+++ b/cli/src/engines/worker/nativeControlRequests.spec.ts
@@ -0,0 +1,130 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { EngineNativeControl, NativeStopHost } from '../facets/nativeControl.js'
+import { NATIVE_UNCONFIRMED } from './nativeControlHost.js'
+import { boundConversation, NATIVE_ACTIVITY, NATIVE_CONTROL_CAPABILITIES, NATIVE_CONTROL_HOST, NATIVE_QUERY_MS, NATIVE_RECOVER, NATIVE_STOP,
+ NATIVE_STOP_IN_FLIGHT, NATIVE_STOP_WAIT_MS, nativeConversation, nativeStopAction, nativeStopAnswer } from './nativeControlProtocol.js'
+import { engineNativeControlRequests } from './nativeControlRequests.js'
+
+const who = { owner: true, local: true }
+const conversation = { home: '/fixture/codex', sessionId: 'thread' }
+const token = 'a'.repeat(64)
+const stop = { version: 1, token, conversation }
+const refused = (message: string) => ({ version: 1, answer: { refused: message } })
+afterEach(() => { vi.useRealTimers(); vi.restoreAllMocks() })
+
+function setup(run: (host: NativeStopHost) => Promise<void> = async host => { await host.current() }, value = true) {
+ const control: EngineNativeControl = {
+ activity: vi.fn(async () => 'idle' as const), stop: vi.fn(async (_c, host) => run(host)), recover: vi.fn(async () => {}), close: vi.fn(),
+ }
+ const query = vi.fn(async (_query: string, _payload: Record<string, unknown>): Promise<Record<string, unknown>> => ({ version: 1, value }))
+ const load = vi.fn(async () => control), recycle = vi.fn()
+ return { control, query, load, recycle, requests: engineNativeControlRequests('codex', { query, load, recycle }) }
+}
+
+describe('the Codex worker\'s control connection', () => {
+ it('reads activity as a snapshot, and loads the control once, only when first asked', async () => {
+ const t = setup()
+ expect(await t.requests[NATIVE_CONTROL_CAPABILITIES]({ version: 1 }, who)).toEqual({ version: 1, nativeControl: 1, engine: 'codex' })
+ expect(t.load).not.toHaveBeenCalled()
+ expect(await t.requests[NATIVE_ACTIVITY]({ version: 1, conversation }, who)).toEqual({ version: 1, answer: 'idle' })
+ expect(await t.requests[NATIVE_STOP](stop, who)).toEqual({ version: 1, answer: { stopped: true } })
+ expect(await t.requests[NATIVE_RECOVER]({ version: 1, conversation }, who)).toEqual({ version: 1, answer: true })
+ vi.mocked(t.control.recover).mockRejectedValueOnce(new Error('not archived'))
+ expect(await t.requests[NATIVE_RECOVER]({ version: 1, conversation }, who)).toEqual({ version: 1, answer: false })
+ // A recovery, like a stop, acts on a bound conversation only.
+ expect(await t.requests[NATIVE_RECOVER]({ version: 1, conversation: { ...conversation, sessionId: '' } }, who)).toEqual({ version: 1, error: 'ENGINE_INVALID_REQUEST' })
+ expect(t.load).toHaveBeenCalledOnce()
+ expect(t.query).toHaveBeenCalledWith(NATIVE_CONTROL_HOST, { version: 1, token, action: { kind: 'current' } })
+ })
+
+ it('takes a stop only from core, privately, for a conversation it can name, four at a time', async () => {
+ const t = setup(() => new Promise(() => {}))
+ for (const asker of [{ owner: false, local: true }, { owner: true, local: false }, { ...who, connection: 'client' }]) {
+ expect(await t.requests[NATIVE_STOP](stop, asker)).toEqual({ version: 1, error: 'ENGINE_INVALID_REQUEST' })
+ }
+ for (const payload of [{ ...stop, version: 2 }, { ...stop, token: 'short' }, { ...stop, conversation: { ...conversation, home: 'relative' } },
+ { ...stop, pane: '%1' }, { ...stop, conversation: { ...conversation, owner: ['codex'] } }, { ...stop, conversation: { ...conversation, sessionId: '' } }]) {
+ expect(await t.requests[NATIVE_STOP](payload, who)).toEqual({ version: 1, error: 'ENGINE_INVALID_REQUEST' })
+ }
+ expect(await t.requests[NATIVE_STOP](stop, who, AbortSignal.abort())).toEqual({ version: 1, error: 'ENGINE_INVALID_REQUEST' })
+ for (let n = 0; n < NATIVE_STOP_IN_FLIGHT; n++) void t.requests[NATIVE_STOP](stop, who)
+ expect(await t.requests[NATIVE_STOP](stop, who)).toEqual({ version: 1, error: 'ENGINE_BUSY' })
+ })
+
+ it('carries a refusal\'s message, and nothing that is not a line of text', async () => {
+ const t = setup(async () => { throw new Error('Codex returned a different conversation') })
+ expect(await t.requests[NATIVE_STOP](stop, who)).toEqual(refused('Codex returned a different conversation'))
+ for (const thrown of [new Error('\x1b[2Jcleared'), new Error('x'.repeat(601)), 'not an error']) {
+ const u = setup(async () => { throw thrown })
+ expect(await u.requests[NATIVE_STOP](stop, who)).toEqual(refused(NATIVE_UNCONFIRMED))
+ }
+ // An answer core will not give ends the stop: the control is told it could not ask.
+ const denied = setup(async host => { await host.current() })
+ denied.query.mockResolvedValueOnce({ version: 1, error: 'ANSWER_FAILED' })
+ expect(await denied.requests[NATIVE_STOP](stop, who)).toEqual(refused(NATIVE_UNCONFIRMED))
+ })
+
+ it('ends a stop when its connection closes, its deadline passes (recycling this worker) or core does not answer', async () => {
+ vi.useFakeTimers()
+ const closed = new AbortController()
+ const asked: unknown[] = []
+ const t = setup(async host => {
+ closed.abort()
+ asked.push(await host.current().catch(error => error.message))
+ })
+ expect(await t.requests[NATIVE_STOP](stop, who, closed.signal)).toEqual(refused(NATIVE_UNCONFIRMED))
+ await vi.advanceTimersByTimeAsync(0)
+ expect(asked).toEqual([NATIVE_UNCONFIRMED])
+ expect(t.query).not.toHaveBeenCalled()
+
+ const stuck = setup(() => new Promise(() => {}))
+ const pending = stuck.requests[NATIVE_STOP](stop, who)
+ await vi.advanceTimersByTimeAsync(NATIVE_STOP_WAIT_MS)
+ expect(await pending).toEqual(refused(NATIVE_UNCONFIRMED))
+ expect(stuck.recycle).toHaveBeenCalledOnce()
+
+ const silent = setup(async host => { await host.current() })
+ silent.query.mockImplementation(() => new Promise(() => {}))
+ const waiting = silent.requests[NATIVE_STOP](stop, who)
+ await vi.advanceTimersByTimeAsync(NATIVE_QUERY_MS)
+ expect(await waiting).toEqual(refused(NATIVE_UNCONFIRMED))
+ expect(silent.recycle).not.toHaveBeenCalled()
+ })
+
+ it('takes an answer that arrives after the stop was ended as authorizing nothing', async () => {
+ let release!: (value: Record<string, unknown>) => void
+ const closed = new AbortController()
+ const after = vi.fn()
+ const t = setup(async host => { if (await host.current()) after() })
+ t.query.mockImplementation(() => new Promise(resolve => { release = resolve }))
+ const pending = t.requests[NATIVE_STOP](stop, who, closed.signal)
+ await vi.waitFor(() => expect(release).toBeTypeOf('function'))
+ closed.abort()
+ expect(await pending).toEqual(refused(NATIVE_UNCONFIRMED))
+ release({ version: 1, value: true })
+ await new Promise(resolve => setTimeout(resolve, 0))
+ expect(after).not.toHaveBeenCalled()
+ })
+
+ it('retries a control that failed to load, and refuses a stop the connection ended while it loaded', async () => {
+ const control: EngineNativeControl = { activity: vi.fn(), stop: vi.fn(async () => {}), recover: vi.fn(), close: vi.fn() }
+ const load = vi.fn().mockRejectedValueOnce(new Error('import failed')).mockResolvedValue(control)
+ const requests = engineNativeControlRequests('codex', { query: vi.fn(), load })
+ expect(await requests[NATIVE_STOP](stop, who)).toEqual(refused(NATIVE_UNCONFIRMED))
+ expect(await requests[NATIVE_STOP](stop, who)).toEqual({ version: 1, answer: { stopped: true } })
+ const closed = new AbortController()
+ const slow = engineNativeControlRequests('codex', { query: vi.fn(), load: async () => { closed.abort(); return control } })
+ expect(await slow[NATIVE_STOP](stop, who, closed.signal)).toEqual(refused(NATIVE_UNCONFIRMED))
+ })
+
+ it('validates every message shape it shares with core', () => {
+ expect(nativeConversation({ ...conversation, sessionId: '' })).toBe(true)
+ expect(boundConversation({ ...conversation, sessionId: '' })).toBe(false)
+ for (const value of [null, { ...conversation, extra: 1 }, { ...conversation, home: '/a\0b' }, { ...conversation, sessionId: 'x'.repeat(201) }])
+ expect(nativeConversation(value)).toBe(false)
+ expect(nativeStopAnswer({ stopped: true })).toBe(true)
+ for (const value of [{ stopped: false }, { refused: '' }, { stopped: true, refused: 'x' }, []]) expect(nativeStopAnswer(value)).toBe(false)
+ for (const kind of ['current', 'pending', 'settled']) expect(nativeStopAction({ kind })).toBe(true)
+ for (const value of [{ kind: 'current', extra: 1 }, { kind: 'running', pid: 90 }, { kind: 'kill' }, 'current']) expect(nativeStopAction(value)).toBe(false)
+ })
+})
diff --git a/cli/src/engines/worker/nativeControlRequests.ts b/cli/src/engines/worker/nativeControlRequests.ts
new file mode 100644
index 000000000..23d2216dc
--- /dev/null
+++ b/cli/src/engines/worker/nativeControlRequests.ts
@@ -0,0 +1,93 @@
+import type { ServiceRequests } from '../../core/api.js'
+import type { EngineNativeControl } from '../facets/nativeControl.js'
+import { controlToken } from './controlWire.js'
+import { createNativeStopHost, NATIVE_UNCONFIRMED } from './nativeControlHost.js'
+import { boundConversation, nativeActivity, nativeConversation, nativeEnvelope, nativeMessage, NATIVE_ACTIVITY, NATIVE_ACTIVITY_IN_FLIGHT,
+ NATIVE_ACTIVITY_WAIT_MS, NATIVE_CONTROL_CAPABILITIES, NATIVE_CONTROL_HOST, NATIVE_CONTROL_VERSION, NATIVE_QUERY_MS,
+ NATIVE_RECOVER, NATIVE_RECOVER_WAIT_MS, NATIVE_REPLY_BYTES, NATIVE_STOP, NATIVE_STOP_IN_FLIGHT, NATIVE_STOP_WAIT_MS } from './nativeControlProtocol.js'
+import { snapshotRequests } from './snapshotRequests.js'
+
+const loadControl = { codex: async () => (await import('../codex/nativeControl.js')).nativeControl }
+export interface NativeControlRequestDeps {
+ query(query: string, payload: Record<string, unknown>): Promise<Record<string, unknown>>
+ load?: () => Promise<EngineNativeControl>
+ recycle?: () => void
+}
+
+/**
+ * The engine's control connection, in its worker. An activity read is a snapshot like a screen's. A stop
+ * runs under core's grant: it asks core before each effect, and ends when core stops answering, the
+ * connection that sent it closes, or its deadline passes, which also recycles this worker.
+ */
+export function engineNativeControlRequests(engine: keyof typeof loadControl, deps: NativeControlRequestDeps): ServiceRequests {
+ let loaded: Promise<EngineNativeControl> | null = null
+ const load = () => loaded ??= (deps.load ?? loadControl[engine])().catch(error => { loaded = null; throw error })
+ const recycle = () => (deps.recycle ?? (() => process.exit(1)))()
+ const reads = snapshotRequests<EngineNativeControl>({
+ engine, version: NATIVE_CONTROL_VERSION, capabilities: NATIVE_CONTROL_CAPABILITIES, capability: 'nativeControl',
+ inFlight: NATIVE_ACTIVITY_IN_FLIGHT, waitMs: NATIVE_ACTIVITY_WAIT_MS, replyBytes: NATIVE_REPLY_BYTES, load, recycle,
+ methods: {
+ [NATIVE_ACTIVITY]: {
+ fields: ['conversation'], accepts: payload => nativeConversation(payload.conversation),
+ answer: (control, payload) => control.activity(payload.conversation as never),
+ valid: answer => nativeActivity(answer),
+ },
+ },
+ })
+ // A recovery is one effect, rare, bounded: its own budget, so a slow one never starves activity reads.
+ const recoveries = snapshotRequests<EngineNativeControl>({
+ engine, version: NATIVE_CONTROL_VERSION, capabilities: NATIVE_CONTROL_CAPABILITIES, capability: 'nativeControl',
+ inFlight: NATIVE_STOP_IN_FLIGHT, waitMs: NATIVE_RECOVER_WAIT_MS, replyBytes: NATIVE_REPLY_BYTES, load, recycle,
+ methods: {
+ [NATIVE_RECOVER]: {
+ fields: ['conversation'], accepts: payload => boundConversation(payload.conversation),
+ answer: async (control, payload) => { try { await control.recover(payload.conversation as never); return true } catch { return false } },
+ valid: answer => typeof answer === 'boolean',
+ },
+ },
+ })
+ let pending = 0
+ const failure = () => ({ version: NATIVE_CONTROL_VERSION, error: 'ENGINE_INVALID_REQUEST' })
+ const stop: ServiceRequests[string] = async (payload, asker, closed) => {
+ if (!asker.owner || !asker.local || asker.connection !== undefined || closed?.aborted) return failure()
+ if (!nativeEnvelope(payload, ['token', 'conversation']) || !controlToken(payload.token) || !boundConversation(payload.conversation)) return failure()
+ if (pending >= NATIVE_STOP_IN_FLIGHT) return { version: NATIVE_CONTROL_VERSION, error: 'ENGINE_BUSY' }
+ const conversation = payload.conversation, token = payload.token
+ pending++
+ let active = true
+ let timer: ReturnType<typeof setTimeout> | undefined
+ let abort: (() => void) | undefined
+ const refused = (message: string) => ({ version: NATIVE_CONTROL_VERSION, answer: { refused: message } })
+ const ended = new Promise<Record<string, unknown>>(resolve => {
+ abort = () => { active = false; resolve(refused(NATIVE_UNCONFIRMED)) }
+ closed?.addEventListener('abort', abort, { once: true })
+ timer = setTimeout(() => { abort!(); recycle() }, NATIVE_STOP_WAIT_MS)
+ })
+ const host = createNativeStopHost(async action => {
+ if (!active) throw new Error(NATIVE_UNCONFIRMED)
+ let timeout: ReturnType<typeof setTimeout> | undefined
+ try {
+ const reply = await Promise.race([deps.query(NATIVE_CONTROL_HOST, { version: NATIVE_CONTROL_VERSION, token, action }),
+ new Promise<never>((_, reject) => { timeout = setTimeout(() => reject(new Error(NATIVE_UNCONFIRMED)), NATIVE_QUERY_MS) })])
+ // Revoked while core answered: its answer authorizes nothing more.
+ if (!active) throw new Error(NATIVE_UNCONFIRMED)
+ return reply
+ } catch (error) { active = false; throw error }
+ finally { clearTimeout(timeout) }
+ })
+ try {
+ return await Promise.race([ended, (async () => {
+ const control = await load()
+ if (!active) return refused(NATIVE_UNCONFIRMED)
+ try { await control.stop(conversation, host) }
+ catch (error) {
+ const message = error instanceof Error ? error.message : ''
+ return refused(nativeMessage(message) ? message : NATIVE_UNCONFIRMED)
+ }
+ return active ? { version: NATIVE_CONTROL_VERSION, answer: { stopped: true } } : refused(NATIVE_UNCONFIRMED)
+ })()])
+ } catch { return refused(NATIVE_UNCONFIRMED) }
+ finally { active = false; clearTimeout(timer); closed?.removeEventListener('abort', abort!); pending-- }
+ }
+ return { ...reads, [NATIVE_RECOVER]: recoveries[NATIVE_RECOVER], [NATIVE_STOP]: stop }
+}
diff --git a/cli/src/engines/worker/process.ts b/cli/src/engines/worker/process.ts
index 3926a9f37..045fbe604 100644
--- a/cli/src/engines/worker/process.ts
+++ b/cli/src/engines/worker/process.ts
@@ -11,6 +11,7 @@ import type { EngineTranscript, HistoryAsk, TranscriptSession } from '../facets/
import { engineLiveRequests } from './liveRequests.js'
import { engineScreenRequests } from './screenRequests.js'
import { engineSubmissionRequests } from './submissionRequests.js'
+import { engineNativeControlRequests } from './nativeControlRequests.js'
import { engineRuntimeRequests } from './runtimeRequests.js'
import {
EngineReadError, record, READER_HISTORY, READER_IN_FLIGHT, READER_LAST_TURN, READER_REPLY_BYTES,
@@ -96,7 +97,9 @@ export function runEngineReader(engine: ReaderEngine, options: EngineProcessOpti
query: (query, payload) => core ? core.query(query, payload) : Promise.reject(new Error('core disconnected')),
}), ...engineQuestionControlRequests(engine, {
query: (query, payload) => core ? core.query(query, payload) : Promise.reject(new Error('core disconnected')),
- }) },
+ }), ...(engine === 'codex' ? engineNativeControlRequests(engine, {
+ query: (query, payload) => core ? core.query(query, payload) : Promise.reject(new Error('core disconnected')),
+ }) : {}) },
onConnected: connected => { core = connected }, onDisconnected: () => { core = null },
})
}
diff --git a/cli/src/engines/worker/snapshotRequests.ts b/cli/src/engines/worker/snapshotRequests.ts
index 0fde43e8c..1cae59a9c 100644
--- a/cli/src/engines/worker/snapshotRequests.ts
+++ b/cli/src/engines/worker/snapshotRequests.ts
@@ -9,7 +9,7 @@ export interface SnapshotMethod<A> {
/** The payload's own fields; `version` and the link's `requestId` are always allowed beside them. */
fields: readonly string[]
accepts(payload: Record<string, unknown>): boolean
- answer(adapter: A, payload: Record<string, unknown>): unknown
+ answer(adapter: A, payload: Record<string, unknown>): unknown | Promise<unknown>
valid(answer: unknown, payload: Record<string, unknown>): boolean
}
@@ -50,7 +50,8 @@ export function snapshotRequests<A>(spec: SnapshotSpec<A>): ServiceRequests {
return await Promise.race([deadline, (async () => {
const adapter = await (loaded ??= spec.load().catch(error => { loaded = null; throw error }))
if (closed?.aborted) return failure('ENGINE_UNAVAILABLE')
- const answer = method.answer(adapter, payload)
+ const answer = await method.answer(adapter, payload)
+ if (closed?.aborted) return failure('ENGINE_UNAVAILABLE')
const reply = { version: spec.version, answer }
if (Buffer.byteLength(JSON.stringify(reply)) > spec.replyBytes) return failure('ENGINE_REPLY_TOO_LARGE')
return method.valid(answer, payload) ? reply : failure('ENGINE_INVALID_REPLY')
diff --git a/cli/src/harnessd/services.spec.ts b/cli/src/harnessd/services.spec.ts
index ed28c3797..43d5f5343 100644
--- a/cli/src/harnessd/services.spec.ts
+++ b/cli/src/harnessd/services.spec.ts
@@ -1,6 +1,6 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import {
- DEFAULT_SERVICE_OPTIONS, ENGINE_LIVE_ENV, ENGINE_RUNTIME_ENV, ENGINE_SCREEN_ENV, ENGINE_MODEL_CONTROL_ENV, masterRunsEngineModelControl, ENGINE_QUESTION_CONTROL_ENV, masterRunsEngineQuestionControl, ENGINE_SUBMISSION_ENV, masterRunsEngineSubmission, KNOWN_SERVICES, SERVICE_HOSTS, SERVICE_PROCESSES_ENV, ServiceSupervisor, UPDATER_HOST, masterRunsLiveEngines, masterRunsEngineRuntime, masterRunsEngineScreen, serviceOptions, serviceProcessesEnv, serviceSpecs, servicesTheMasterRuns,
+ DEFAULT_SERVICE_OPTIONS, ENGINE_LIVE_ENV, ENGINE_RUNTIME_ENV, ENGINE_SCREEN_ENV, ENGINE_MODEL_CONTROL_ENV, masterRunsEngineModelControl, ENGINE_QUESTION_CONTROL_ENV, masterRunsEngineQuestionControl, ENGINE_SUBMISSION_ENV, masterRunsEngineSubmission, ENGINE_NATIVE_CONTROL_ENV, masterRunsEngineNativeControl, KNOWN_SERVICES, SERVICE_HOSTS, SERVICE_PROCESSES_ENV, ServiceSupervisor, UPDATER_HOST, masterRunsLiveEngines, masterRunsEngineRuntime, masterRunsEngineScreen, serviceOptions, serviceProcessesEnv, serviceSpecs, servicesTheMasterRuns,
type ServiceSpec, type ServiceSupervisorOptions,
} from './services.js'
import type { CoreHandle } from './supervisor.js'
@@ -472,15 +472,15 @@ describe('which services the core leaves to its master', () => {
it('is what the master says it runs, told in a form a core from before the list reads too', () => {
const specs = serviceSpecs({ HARNESSD_SERVICES: 'search,workspaces' }, SERVICE_HOSTS)
- expect(serviceProcessesEnv(specs, 42)).toEqual({ [SERVICE_PROCESSES_ENV]: 'search,workspaces', HARNESSD_SERVICES: 'search,workspaces', [ENGINE_LIVE_ENV]: '42:1', [ENGINE_RUNTIME_ENV]: '42:1', [ENGINE_SCREEN_ENV]: '42:1', [ENGINE_MODEL_CONTROL_ENV]: '42:1', [ENGINE_QUESTION_CONTROL_ENV]: '42:1', [ENGINE_SUBMISSION_ENV]: '42:1' })
+ expect(serviceProcessesEnv(specs, 42)).toEqual({ [SERVICE_PROCESSES_ENV]: 'search,workspaces', HARNESSD_SERVICES: 'search,workspaces', [ENGINE_LIVE_ENV]: '42:1', [ENGINE_RUNTIME_ENV]: '42:1', [ENGINE_SCREEN_ENV]: '42:1', [ENGINE_MODEL_CONTROL_ENV]: '42:1', [ENGINE_QUESTION_CONTROL_ENV]: '42:1', [ENGINE_SUBMISSION_ENV]: '42:1', [ENGINE_NATIVE_CONTROL_ENV]: '42:1' })
// A process named as one of its services is named whole: the viewers' process runs the Store beside them.
expect(serviceProcessesEnv(serviceSpecs({ HARNESSD_SERVICES: 'viewers' }, SERVICE_HOSTS), 42)).toMatchObject({ [SERVICE_PROCESSES_ENV]: 'viewers,store' })
expect(serviceProcessesEnv(serviceSpecs({ HARNESSD_SERVICES: 'store' }, SERVICE_HOSTS), 42)).toMatchObject({ [SERVICE_PROCESSES_ENV]: 'store' })
// By service, not by process: a core from before the edge host routes the services it knows of it.
const hosted = serviceSpecs({ HARNESSD_SERVICES: 'edge' }, SERVICE_HOSTS)
- expect(serviceProcessesEnv(hosted, 42)).toEqual({ [SERVICE_PROCESSES_ENV]: 'workspaces,usage,monitor,projects,handoff,recaps,windowNames,shell', HARNESSD_SERVICES: 'workspaces,usage,monitor,projects,handoff,recaps,windowNames,shell', [ENGINE_LIVE_ENV]: '42:1', [ENGINE_RUNTIME_ENV]: '42:1', [ENGINE_SCREEN_ENV]: '42:1', [ENGINE_MODEL_CONTROL_ENV]: '42:1', [ENGINE_QUESTION_CONTROL_ENV]: '42:1', [ENGINE_SUBMISSION_ENV]: '42:1' })
+ expect(serviceProcessesEnv(hosted, 42)).toEqual({ [SERVICE_PROCESSES_ENV]: 'workspaces,usage,monitor,projects,handoff,recaps,windowNames,shell', HARNESSD_SERVICES: 'workspaces,usage,monitor,projects,handoff,recaps,windowNames,shell', [ENGINE_LIVE_ENV]: '42:1', [ENGINE_RUNTIME_ENV]: '42:1', [ENGINE_SCREEN_ENV]: '42:1', [ENGINE_MODEL_CONTROL_ENV]: '42:1', [ENGINE_QUESTION_CONTROL_ENV]: '42:1', [ENGINE_SUBMISSION_ENV]: '42:1', [ENGINE_NATIVE_CONTROL_ENV]: '42:1' })
expect([...servicesTheMasterRuns({ ...supervised, ...serviceProcessesEnv(hosted, 42) }, known)]).toEqual(['workspaces'])
- expect(serviceProcessesEnv([], 42)).toEqual({ [SERVICE_PROCESSES_ENV]: '', HARNESSD_SERVICES: 'none', [ENGINE_LIVE_ENV]: '42:1', [ENGINE_RUNTIME_ENV]: '42:1', [ENGINE_SCREEN_ENV]: '42:1', [ENGINE_MODEL_CONTROL_ENV]: '42:1', [ENGINE_QUESTION_CONTROL_ENV]: '42:1', [ENGINE_SUBMISSION_ENV]: '42:1' })
+ expect(serviceProcessesEnv([], 42)).toEqual({ [SERVICE_PROCESSES_ENV]: '', HARNESSD_SERVICES: 'none', [ENGINE_LIVE_ENV]: '42:1', [ENGINE_RUNTIME_ENV]: '42:1', [ENGINE_SCREEN_ENV]: '42:1', [ENGINE_MODEL_CONTROL_ENV]: '42:1', [ENGINE_QUESTION_CONTROL_ENV]: '42:1', [ENGINE_SUBMISSION_ENV]: '42:1', [ENGINE_NATIVE_CONTROL_ENV]: '42:1' })
expect([...servicesTheMasterRuns({ ...supervised, ...serviceProcessesEnv(specs, 42) }, known)]).toEqual(['search', 'workspaces'])
expect([...servicesTheMasterRuns({ ...supervised, ...serviceProcessesEnv([], 42) }, known)]).toEqual([])
// What the master says wins over whatever HARNESSD_SERVICES the core inherited; names it does not know are its own.
@@ -539,6 +539,16 @@ describe('which services the core leaves to its master', () => {
expect(masterRunsEngineScreen({ ...env, HARNESSD_SERVICE_TOKEN: undefined }, 42)).toBe(false)
})
+ it('negotiates native control connections only from a capable supervising parent', () => {
+ const env = { ...supervised, ...serviceProcessesEnv([], 42) }
+ expect(masterRunsEngineNativeControl(env, 42)).toBe(true)
+ expect(masterRunsEngineNativeControl(env, 43)).toBe(false)
+ // An older master never set it: the core composes the inline control, as it does for the others.
+ expect(masterRunsEngineNativeControl({ ...env, [ENGINE_NATIVE_CONTROL_ENV]: undefined }, 42)).toBe(false)
+ expect(masterRunsEngineNativeControl({ ...env, [ENGINE_LIVE_ENV]: undefined }, 42)).toBe(false)
+ expect(masterRunsEngineNativeControl({ ...env, HARNESSD_SERVICE_TOKEN: undefined }, 42)).toBe(false)
+ })
+
it('negotiates submission readers only from a capable supervising parent', () => {
const env = { ...supervised, ...serviceProcessesEnv([], 42) }
expect(masterRunsEngineSubmission(env, 42)).toBe(true)
diff --git a/cli/src/harnessd/services.ts b/cli/src/harnessd/services.ts
index 5ba66ff8d..beb6b8f08 100644
--- a/cli/src/harnessd/services.ts
+++ b/cli/src/harnessd/services.ts
@@ -463,6 +463,7 @@ export const ENGINE_SCREEN_ENV = 'HARNESSD_ENGINE_SCREEN'
export const ENGINE_MODEL_CONTROL_ENV = 'HARNESSD_ENGINE_MODEL_CONTROL'
export const ENGINE_QUESTION_CONTROL_ENV = 'HARNESSD_ENGINE_QUESTION_CONTROL'
export const ENGINE_SUBMISSION_ENV = 'HARNESSD_ENGINE_SUBMISSION'
+export const ENGINE_NATIVE_CONTROL_ENV = 'HARNESSD_ENGINE_NATIVE_CONTROL'
/**
* What a master puts in its core's environment about the services it runs in their own processes: the
@@ -474,7 +475,7 @@ export function serviceProcessesEnv(specs: readonly ServiceSpec[], masterPid: nu
// The services, not the processes: a core knows what it routes by service, and one from before the
// edge host still finds the services it knows here (workspaces) and runs the rest itself.
const names = specs.flatMap((spec) => spec.services).join(',')
- return { [SERVICE_PROCESSES_ENV]: names, HARNESSD_SERVICES: names || 'none', [ENGINE_LIVE_ENV]: `${masterPid}:1`, [ENGINE_RUNTIME_ENV]: `${masterPid}:1`, [ENGINE_SCREEN_ENV]: `${masterPid}:1`, [ENGINE_MODEL_CONTROL_ENV]: `${masterPid}:1`, [ENGINE_QUESTION_CONTROL_ENV]: `${masterPid}:1`, [ENGINE_SUBMISSION_ENV]: `${masterPid}:1` }
+ return { [SERVICE_PROCESSES_ENV]: names, HARNESSD_SERVICES: names || 'none', [ENGINE_LIVE_ENV]: `${masterPid}:1`, [ENGINE_RUNTIME_ENV]: `${masterPid}:1`, [ENGINE_SCREEN_ENV]: `${masterPid}:1`, [ENGINE_MODEL_CONTROL_ENV]: `${masterPid}:1`, [ENGINE_QUESTION_CONTROL_ENV]: `${masterPid}:1`, [ENGINE_SUBMISSION_ENV]: `${masterPid}:1`, [ENGINE_NATIVE_CONTROL_ENV]: `${masterPid}:1` }
}
/** An older master may inherit a newer master's environment after rollback. Trust only this parent. */
@@ -543,3 +544,8 @@ export function masterRunsEngineQuestionControl(env: NodeJS.ProcessEnv, parentPi
export function masterRunsEngineSubmission(env: NodeJS.ProcessEnv, parentPid: number): boolean {
return masterRunsLiveEngines(env, parentPid) && env[ENGINE_SUBMISSION_ENV] === `${parentPid}:1`
}
+
+/** A new core must not send an older worker host a stop its Codex worker cannot speak. */
+export function masterRunsEngineNativeControl(env: NodeJS.ProcessEnv, parentPid: number): boolean {
+ return masterRunsLiveEngines(env, parentPid) && env[ENGINE_NATIVE_CONTROL_ENV] === `${parentPid}:1`
+}
diff --git a/cli/src/lib/codexSessionLifecycle.ts b/cli/src/lib/codexSessionLifecycle.ts
deleted file mode 100644
index 799088e05..000000000
--- a/cli/src/lib/codexSessionLifecycle.ts
+++ /dev/null
@@ -1,175 +0,0 @@
-/** Codex's shared app-server owns work independently of its terminal client.
- * Never kill that server: unload only the confirmed conversation, leaving its
- * history available and all other clients running. New Harness launches opt out
- * of sharing, but sessions opened before an upgrade still need this path. */
-import { spawn } from 'node:child_process'
-import { Duplex } from 'node:stream'
-import { readFile, realpath } from 'node:fs/promises'
-import { basename, join } from 'node:path'
-import WebSocket from 'ws'
-import { sessionCodexHome } from './engineHomes.js'
-import { engineBin } from './engineBin.js'
-import { argvTokens, processRows, type ProcessRow } from './tmux.js'
-import { sameProcessIdentity } from './terminalRuntime.js'
-import type { RegisteredSession } from './registry.js'
-
-export interface CodexControl {
- request(method: string, params: Record<string, unknown>): Promise<any>
- close(): void
-}
-
-/** The CLI resolves its own socket location. It does not start a server. `proxy`
- * carries raw WebSocket bytes (not JSONL), as documented by Codex app-server. */
-export async function connectCodexControl(home: string): Promise<CodexControl> {
- const child = spawn(engineBin('codex'), ['app-server', 'proxy'], {
- env: { ...process.env, CODEX_HOME: home }, stdio: ['pipe', 'pipe', 'ignore'],
- })
- const pipe = Duplex.from({ readable: child.stdout, writable: child.stdin })
- const ws = new WebSocket('ws://localhost/', { createConnection: () => pipe as any,
- handshakeTimeout: 3_000, maxPayload: 2 << 20, perMessageDeflate: false })
- let nextId = 0
- const pending = new Map<number, { resolve(value: unknown): void; reject(error: Error): void; timer: ReturnType<typeof setTimeout> }>()
- const fail = (error: Error) => {
- for (const entry of pending.values()) { clearTimeout(entry.timer); entry.reject(error) }
- pending.clear()
- }
- const close = () => { fail(new Error('Codex control connection closed')); ws.terminate(); pipe.destroy(); child.kill() }
- child.on('error', error => { fail(error); ws.terminate() })
- child.on('exit', () => { fail(new Error('Codex control proxy exited')); ws.terminate() })
- pipe.on('error', error => { fail(error); ws.terminate() })
- ws.on('error', fail)
- ws.on('close', () => { fail(new Error('Codex control connection closed')); pipe.destroy(); child.kill() })
- ws.on('message', bytes => {
- try {
- const frame = JSON.parse(String(bytes))
- const entry = pending.get(frame.id)
- if (!entry) return
- pending.delete(frame.id); clearTimeout(entry.timer)
- if (frame.error) entry.reject(new Error(`Codex could not ${String(frame.error.message ?? 'complete the request').slice(0, 300)}`))
- else entry.resolve(frame.result)
- } catch { fail(new Error('Invalid Codex control response')); ws.terminate() }
- })
- const request: CodexControl['request'] = (method, params) => new Promise((resolve, reject) => {
- if (ws.readyState !== WebSocket.OPEN) { reject(new Error('Codex control is unavailable')); return }
- const id = ++nextId
- const timer = setTimeout(() => { pending.delete(id); reject(new Error('Codex control request timed out')) }, 5_000)
- pending.set(id, { resolve, reject, timer })
- ws.send(JSON.stringify({ id, method, params }), error => {
- if (error) { clearTimeout(timer); pending.delete(id); reject(error) }
- })
- })
- try {
- await new Promise<void>((resolve, reject) => {
- ws.once('open', resolve); ws.once('error', reject)
- ws.once('close', () => reject(new Error('Codex control connection closed')))
- })
- const initialized = await request('initialize', { clientInfo: { name: 'harness', version: '1' }, capabilities: { experimentalApi: true } })
- if (typeof initialized?.codexHome !== 'string' || await realpath(initialized.codexHome) !== await realpath(home)) {
- throw new Error('Codex returned a different session store')
- }
- ws.send(JSON.stringify({ method: 'initialized' }))
- return { request, close }
- } catch (error) { close(); throw error }
-}
-
-async function daemonIdentity(home: string): Promise<{ pid: number; processStartTime: string } | null> {
- try {
- const value = JSON.parse(await readFile(join(home, 'app-server-daemon', 'daemon.pid'), 'utf8'))
- if (!Number.isSafeInteger(value.pid) || value.pid <= 0 || typeof value.processStartTime !== 'string') throw new Error('Invalid Codex server identity')
- return value
- } catch (error) {
- if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
- throw error
- }
-}
-
-export interface CodexStopDeps {
- daemonIdentity(home: string): Promise<{ pid: number; processStartTime: string } | null>
- rows(): Promise<ProcessRow[] | null>
- connect(home: string): Promise<CodexControl>
-}
-
-/** Called AFTER a checkpoint and BEFORE signalling the terminal. There is no
- * polling, model call, archive deletion or machine-wide daemon shutdown here. */
-export async function stopSharedCodexSession(session: RegisteredSession, current: () => boolean,
- deps: CodexStopDeps = { daemonIdentity, rows: processRows, connect: connectCodexControl },
- confirmUnusedConversation?: (session: RegisteredSession) => Promise<boolean>): Promise<void> {
- if (session.engine !== 'codex') return
- const home = sessionCodexHome(session)
- const rows = await deps.rows()
- if (!rows) throw new Error('Could not verify the Codex server before stopping')
- const guard = () => { if (!current()) throw new Error('The close request was cancelled or the session changed') }
- // Close can beat discovery's exit reconciliation: the client has already
- // returned to its shell, with no conversation ever bound. Its checkpoint is
- // saved, and an unrelated shared server is not a reason to keep that pane.
- // Missing/recycled process identity and previously bound conversations still
- // need the normal verification below.
- if (session.processIdentity && !rows.some(row => row.pid === session.processIdentity!.pid)
- && !session.sessionId && !session.transcriptPath && session.boundAt == null && !session.resumeOnly) {
- guard()
- return
- }
- const owner = rows.find(row => sameProcessIdentity(row, session.processIdentity) && row.executable === session.processIdentity?.executable)
- if (owner) {
- const args = argvTokens(owner.args)
- // Harness inserts this as the FIRST option, before resume/fork or prompt
- // text. A prompt merely mentioning --no-daemon is not proof of ownership.
- const option = /^node(?:\.exe)?$/.test(basename(args[0] ?? '')) && /(?:^|\/)codex(?:\.js)?$/.test(args[1] ?? '') ? 2 : 1
- // A remote app-server is not controlled by this machine's profile. Do not
- // report its work stopped merely because its local terminal was closed.
- if (args.slice(option).some(arg => arg === '--remote' || arg.startsWith('--remote='))) {
- throw new Error('Stop this conversation on its remote Codex server before closing its terminal')
- }
- if (args[option] === '--no-daemon') return
- }
- const daemon = await deps.daemonIdentity(home)
- if (!daemon) return // Older/process-owned Codex has no detached writer.
- const normalize = (value: string) => value.trim().replace(/\s+/g, ' ')
- if (!rows.some(row => row.pid === daemon.pid && normalize(row.startMarker) === normalize(daemon.processStartTime))) return
- if (!session.sessionId) {
- // An unused TUI has no conversation to unload. Close supplies fresh proof
- // of its empty composer after saving the screen; Pause and uncertain
- // discovery still require an exact conversation identity.
- if (owner && await confirmUnusedConversation?.(session)) {
- guard()
- return
- }
- throw new Error('Could not identify the conversation on the Codex server; the session is still open')
- }
- const control = await deps.connect(home)
- try {
- guard()
- const read = await control.request('thread/read', { threadId: session.sessionId })
- if (read?.thread?.id !== session.sessionId) throw new Error('Codex returned a different conversation')
- if (read.thread.status?.type === 'notLoaded') return
- // A process-owned session can share its profile with an unrelated daemon;
- // thread/read reports notLoaded there and none of the calls below occur.
- const goal = await control.request('thread/goal/get', { threadId: session.sessionId })
- guard()
- if (goal?.goal?.status === 'active') {
- await control.request('thread/goal/set', { threadId: session.sessionId, status: 'paused' })
- }
- guard()
- const turns = await control.request('thread/turns/list', { threadId: session.sessionId, limit: 1, itemsView: 'summary' })
- guard()
- const active = turns?.data?.find((turn: any) => turn.status === 'inProgress')
- if (active) await control.request('turn/interrupt', { threadId: session.sessionId, turnId: active.id })
- guard()
- // Archive is the public operation that unloads a thread. Unarchive moves
- // only its saved history back; it does not restart the thread. Always undo
- // the archive even if the user reopens while its response is in flight.
- let archiveError: unknown
- try { await control.request('thread/archive', { threadId: session.sessionId }) }
- catch (error) { archiveError = error }
- // A timed-out reply does not prove the archive failed to happen. Always
- // attempt to return the history to sessions before reporting the error.
- try { await control.request('thread/unarchive', { threadId: session.sessionId }) }
- catch (error) { throw archiveError ?? error }
- if (archiveError) throw archiveError
- guard()
- const after = await control.request('thread/read', { threadId: session.sessionId })
- if (after?.thread?.id !== session.sessionId || after.thread.status?.type !== 'notLoaded') {
- throw new Error('Could not confirm the Codex conversation stopped; its pane remains open')
- }
- } finally { control.close() }
-}
diff --git a/cli/src/lib/engineHomeReaders.spec.ts b/cli/src/lib/engineHomeReaders.spec.ts
index f64047c20..b035e1fa0 100644
--- a/cli/src/lib/engineHomeReaders.spec.ts
+++ b/cli/src/lib/engineHomeReaders.spec.ts
@@ -2,8 +2,7 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, expect, it, vi } from 'vitest'
-import { CodexActivityReader } from './runtimeActivity.js'
-import { stopSharedCodexSession } from './codexSessionLifecycle.js'
+import { composedCodex } from '../testing/inlineNativeControls.js'
import { createHarnessResourcesReader } from './harnessResources.js'
import type { RegisteredSession } from './registry.js'
@@ -28,7 +27,7 @@ afterEach(() => {
it('reads live activity from the login shell Codex server, keeping an explicit agent profile', async () => {
const home = movedHome()
const connect = vi.fn(async (_home: string) => ({ request: async () => ({ thread: { id: 'conversation', status: { type: 'active' } } }), close: () => {} }))
- const reader = new CodexActivityReader({ connect, now: () => 1000,
+ const reader = composedCodex({ connect, now: () => 1000,
rows: async () => [{ ...session().processIdentity!, parentPid: 1, args: 'codex resume conversation' }],
})
try {
@@ -44,11 +43,11 @@ it('stops the shared conversation in the login shell Codex home instead of overl
const home = movedHome()
const request = vi.fn(async () => ({ thread: { id: 'conversation', status: { type: 'notLoaded' } } }))
const connect = vi.fn(async (_home: string) => ({ request, close: () => {} }))
- await stopSharedCodexSession(session(), () => true, {
- daemonIdentity: async path => path === home ? { pid: 90, processStartTime: start } : null,
+ await composedCodex({
+ daemonIdentity: async (path: string) => path === home ? { pid: 90, processStartTime: start } : null,
rows: async () => [{ pid: 90, parentPid: 1, executable: 'codex', args: 'codex app-server', startMarker: start }],
connect,
- })
+ }).stop(session(), () => true)
expect(connect).toHaveBeenCalledWith(home)
expect(request).toHaveBeenCalledWith('thread/read', { threadId: 'conversation' })
})
diff --git a/cli/src/lib/runtimeActivity.spec.ts b/cli/src/lib/runtimeActivity.spec.ts
index e90d2dbb3..8fd85be5d 100644
--- a/cli/src/lib/runtimeActivity.spec.ts
+++ b/cli/src/lib/runtimeActivity.spec.ts
@@ -1,6 +1,7 @@
import { readInlineScreen } from '../testing/inlineScreen.js'
import { afterEach, describe, expect, it, vi } from 'vitest'
-import { CodexActivityReader, RuntimeActivityReader } from './runtimeActivity.js'
+import { RuntimeActivityReader } from './runtimeActivity.js'
+import { composedCodex } from '../testing/inlineNativeControls.js'
import { registry, type RegisteredSession } from './registry.js'
function session(): RegisteredSession {
@@ -16,7 +17,8 @@ function control() {
const close = vi.fn()
const rows = vi.fn(async () => [{ ...row.processIdentity!, parentPid: 1, args: 'codex resume conversation' }])
const connect = vi.fn(async () => ({ request, close }))
- const reader = new CodexActivityReader({ connect, rows, now: () => now })
+ // Codex's activity, read by its own control (in its worker) on the conversation the core identified.
+ const reader = composedCodex({ connect, rows, now: () => now })
return { reader, row, request, close, rows, connect, advance: () => { now += 60_001 } }
}
describe('Codex activity RPC', () => {
diff --git a/cli/src/lib/runtimeActivity.ts b/cli/src/lib/runtimeActivity.ts
index b28406afc..72d4264a9 100644
--- a/cli/src/lib/runtimeActivity.ts
+++ b/cli/src/lib/runtimeActivity.ts
@@ -1,9 +1,4 @@
-import { basename } from 'node:path'
-import { sessionCodexHome } from './engineHomes.js'
import type { ScreenReader } from './screenReader.js'
-import { connectCodexControl, type CodexControl } from './codexSessionLifecycle.js'
-import { argvTokens, processRows, type ProcessRow } from './tmux.js'
-import { sameProcessIdentity } from './terminalRuntime.js'
import type { RegisteredSession } from './registry.js'
import type { ActivityState } from './turnActivity.js'
@@ -11,58 +6,13 @@ export function activityRuntimeKey(session: RegisteredSession): string {
return JSON.stringify([session.agentId, session.sessionId, session.primaryRuntimeKey, session.processIdentity])
}
-/** Read-only connections, shared by profile. Never launch/resume a thread or
- * start an app-server to inspect it. An unrelated server's notLoaded is unknown. */
-export class CodexActivityReader {
- private readonly controls = new Map<string, Promise<CodexControl>>()
- private readonly retryAt = new Map<string, number>()
- private rowsAt = -Infinity
- private rows?: Promise<ProcessRow[] | null>
- constructor(private readonly deps = { connect: connectCodexControl, rows: processRows, now: () => performance.now() }) {}
- async read(session: RegisteredSession): Promise<ActivityState> {
- if (session.engine !== 'codex' || !session.processIdentity) return 'unknown'
- const home = sessionCodexHome(session)
- if ((this.retryAt.get(home) ?? 0) > this.deps.now()) return 'unknown'
- if (!this.rows || this.deps.now() - this.rowsAt > 2_000) {
- this.rowsAt = this.deps.now(); this.rows = this.deps.rows()
- }
- const rows = await this.rows
- const owner = rows?.find(row => sameProcessIdentity(row, session.processIdentity)
- && row.executable === session.processIdentity!.executable)
- if (!owner) return 'unknown'
- const args = argvTokens(owner.args)
- const option = /^node(?:\.exe)?$/.test(basename(args[0] ?? '')) && /(?:^|\/)codex(?:\.js)?$/.test(args[1] ?? '') ? 2 : 1
- if (args[option] === '--no-daemon' || args.slice(option).some(arg => arg === '--remote' || arg.startsWith('--remote='))) return 'unknown'
- let connection = this.controls.get(home)
- if (!connection) { connection = this.deps.connect(home); this.controls.set(home, connection) }
- try {
- const control = await connection
- const read = await control.request('thread/read', { threadId: session.sessionId })
- if (read?.thread?.id !== session.sessionId) return 'unknown'
- if (read.thread.status?.type === 'active') return 'working'
- if (read.thread.status?.type === 'idle') return 'idle'
- return 'unknown'
- } catch {
- // An old/process-owned engine may share its profile with another server.
- // Do not keep spawning a failed proxy for every session every five seconds.
- if (this.controls.get(home) === connection) this.controls.delete(home)
- void connection.then(control => control.close()).catch(() => {})
- this.retryAt.set(home, this.deps.now() + 60_000)
- return 'unknown'
- }
- }
- close(): void {
- for (const control of this.controls.values()) void control.then(value => value.close()).catch(() => {})
- this.controls.clear()
- }
-}
-
/** A positive, changing live busy indicator can confirm an otherwise quiet
* process-owned engine. Missing/unrecognized UI is always unknown. */
export class RuntimeActivityReader {
private readonly footers = new Map<string, { runtime: string; indicator: string | null; stopped: boolean }>()
constructor(private readonly deps: {
readScreen: ScreenReader
+ /** The engine's own server's answer (Codex's, from its worker: core/engines/nativeControls.ts). */
codex(session: RegisteredSession): Promise<ActivityState>
capture(session: RegisteredSession): Promise<string | null>
}) {}
diff --git a/cli/src/lib/stopAgentService.spec.ts b/cli/src/lib/stopAgentService.spec.ts
index a1d8bbfec..070b052ba 100644
--- a/cli/src/lib/stopAgentService.spec.ts
+++ b/cli/src/lib/stopAgentService.spec.ts
@@ -1,12 +1,10 @@
import { afterEach, beforeEach, expect, it, vi } from 'vitest'
-import { stopSharedCodexSession } from './codexSessionLifecycle.js'
import { captureResumeIdentity } from './captureResumeIdentity.js'
import { createStopAgentService, type StopAgentServiceDeps } from './stopAgentService.js'
import { registry, type RegisteredSession } from './registry.js'
import { stoppedAgents } from './stoppedAgents.js'
import { AgentRestartCoordinator } from './restartAgent.js'
import { checkPidRuntime, terminateDeletedAgent } from './deleteAgentFallback.js'
-vi.mock('./codexSessionLifecycle.js', () => ({ stopSharedCodexSession: vi.fn(async () => {}) }))
vi.mock('./captureResumeIdentity.js', () => ({ captureResumeIdentity: vi.fn(async session => session) }))
vi.mock('./deleteAgentFallback.js', () => ({ checkPidRuntime: vi.fn(), terminateDeletedAgent: vi.fn() }))
let row: RegisteredSession
@@ -20,6 +18,7 @@ beforeEach(() => {
tmuxBackend: { kill: vi.fn(async () => ({ state: 'succeeded' as const, dispatch: 'executed' as const })) },
agentReconciler: { suppress: vi.fn(), holdRoute: vi.fn(), releaseRoute: vi.fn(), trigger: vi.fn(async () => {}) },
forgetSession: vi.fn(id => registry.removeAgent(id)), markDeleted: vi.fn(), clearDeleted: vi.fn(),
+ stopNative: vi.fn(async () => {}),
}
vi.mocked(terminateDeletedAgent).mockResolvedValue('gone')
})
@@ -208,7 +207,7 @@ it('keeps the newer hook binding that arrives during capture', async () => {
it('checks cancellation at the shared-server boundary and never signals after a failure there', async () => {
let current = true
- vi.mocked(stopSharedCodexSession).mockImplementationOnce(async (_row, guard) => {
+ vi.mocked(deps.stopNative).mockImplementationOnce(async (_row, guard) => {
expect(guard()).toBe(true); current = false; expect(guard()).toBe(false)
throw new Error('shared server could not stop')
})
diff --git a/cli/src/lib/stopAgentService.ts b/cli/src/lib/stopAgentService.ts
index b105b868a..f1d1ad09b 100644
--- a/cli/src/lib/stopAgentService.ts
+++ b/cli/src/lib/stopAgentService.ts
@@ -1,5 +1,4 @@
/** Stop retains the logical session before retiring its process and terminal. */
-import { stopSharedCodexSession } from './codexSessionLifecycle.js'
import { captureResumeIdentity } from './captureResumeIdentity.js'
import { isTerminalEngine } from '../engines/types.js'
import type { registry as liveRegistry, RegisteredSession } from './registry.js'
@@ -25,6 +24,11 @@ export interface StopAgentServiceDeps {
forgetSession(agentId: string, options: { force: true }): void
markDeleted(agentId: string): void
clearDeleted(agentId: string): void
+ /**
+ * Unload the conversation from its engine's own server (Codex's shared app-server) before its client is
+ * signalled: core/engines/nativeControls.ts, the engine's worker speaking its protocol under a grant.
+ */
+ stopNative(session: RegisteredSession, current: () => boolean, confirmUnusedConversation?: (session: RegisteredSession) => Promise<boolean>): Promise<void>
}
export class AgentStopError extends Error {
readonly code = 'STOP_UNCONFIRMED'
@@ -51,7 +55,7 @@ const runtimeIdentity = (entry: RegisteredSession | undefined, withProcess = tru
export function createStopAgentService(deps: StopAgentServiceDeps) {
const { registry, stoppedAgents, restartJobs, stopJobs, tmuxBackend, agentReconciler,
- forgetSession, markDeleted, clearDeleted } = deps
+ forgetSession, markDeleted, clearDeleted, stopNative } = deps
return (target: string, options: StopAgentOptions = {}) => {
const sessionId = registry.resolve(target)?.agentId ?? target
const existing = stopJobs.get(sessionId)
@@ -92,8 +96,7 @@ export function createStopAgentService(deps: StopAgentServiceDeps) {
try {
markDeleted(sessionId)
if (s.sessionId) markDeleted(s.sessionId)
- await stopSharedCodexSession(s, () => sameTarget() && options.current?.() !== false,
- undefined, options.confirmUnusedConversation)
+ await stopNative(s, () => sameTarget() && options.current?.() !== false, options.confirmUnusedConversation)
// Keep the terminal alive while the engine handles SIGTERM and flushes
// its native store. Killing tmux in parallel can deliver SIGHUP first.
const termination = await (isTerminalEngine(s.engine) ? Promise.resolve('gone' as const)
diff --git a/cli/src/lib/terminalClose.real.spec.ts b/cli/src/lib/terminalClose.real.spec.ts
index 1715aa3c1..f2b5d53b2 100644
--- a/cli/src/lib/terminalClose.real.spec.ts
+++ b/cli/src/lib/terminalClose.real.spec.ts
@@ -1,4 +1,5 @@
import { screenFor } from '../engines/screens.js'
+import { inlineNativeControls } from '../testing/inlineNativeControls.js'
import { readFile, readdir, stat } from 'node:fs/promises'
import { join } from 'node:path'
import { expect, it, vi } from 'vitest'
@@ -62,7 +63,7 @@ it.runIf(process.env.RUN_REAL_TMUX_DISCOVERY === '1')('saves and closes an inact
const stop = createStopAgentService({ registry, stoppedAgents,
restartJobs: new AgentRestartCoordinator(), stopJobs: new Map(), tmuxBackend: backend,
agentReconciler: { suppress() {}, holdRoute() {}, releaseRoute() {}, trigger: async () => {} },
- forgetSession: id => registry.removeAgent(id), markDeleted() {}, clearDeleted() {},
+ forgetSession: id => registry.removeAgent(id), markDeleted() {}, clearDeleted() {}, stopNative: inlineNativeControls().stop,
})
close = new CloseAgentService({ registry, stop, changed() {},
activity: async session => inspectCloseActivity(session, await control.captureTerminal(session.agentId), undefined, false),
diff --git a/cli/src/lib/unusedCodexClose.spec.ts b/cli/src/lib/unusedCodexClose.spec.ts
index 574bf60cb..aec292b9b 100644
--- a/cli/src/lib/unusedCodexClose.spec.ts
+++ b/cli/src/lib/unusedCodexClose.spec.ts
@@ -8,6 +8,7 @@ import { stoppedAgents } from './stoppedAgents.js'
import { AgentRestartCoordinator } from './restartAgent.js'
import { CloseAgentService, inspectCloseActivity as inspectCloseReading } from './closeAgentService.js'
import { createStopAgentService } from './stopAgentService.js'
+import { inlineNativeControls } from '../testing/inlineNativeControls.js'
import { SessionCheckpointStore } from './sessionCheckpoint.js'
import { processRows } from './tmux.js'
import { checkPidRuntime, terminateDeletedAgent } from './deleteAgentFallback.js'
@@ -52,6 +53,8 @@ beforeEach(() => {
tmuxBackend: { kill: killPane },
agentReconciler: { suppress: vi.fn(), holdRoute: vi.fn(), releaseRoute: vi.fn(), trigger: vi.fn(async () => {}) },
forgetSession: id => registry.removeAgent(id), markDeleted: vi.fn(), clearDeleted: vi.fn(),
+ // The real chain: the core's broker, Codex's own control in process, the process table mocked above.
+ stopNative: inlineNativeControls({ rows: processRows }).stop,
})
checkpointDirectory = join(env.ADAPTER_DATA_DIR, 'unused-checkpoints', row.agentId)
const checkpoints = new SessionCheckpointStore(checkpointDirectory)
diff --git a/cli/src/services/AGENTS.md b/cli/src/services/AGENTS.md
index e67d0cb6e..16ab47e7e 100644
--- a/cli/src/services/AGENTS.md
+++ b/cli/src/services/AGENTS.md
@@ -51,7 +51,7 @@ that process. A process per risk, not per feature (`SERVICE_HOSTS` in `src/harne
| Process | Services | Why its own | Started |
|---|---|---|---|
-| `engine-claude`, `engine-codex` | history, live parsers, runtime profiles, screens, submission readings, model control and question navigation (`src/engines/worker/`) | engine behavior outside core; snapshots and revocable model- and question-control grants | on demand |
+| `engine-claude`, `engine-codex` | history, live parsers, runtime profiles, screens, submission readings, model control, question navigation and Codex's app-server connection (`src/engines/worker/`) | engine behavior outside core; snapshots and revocable model- and question-control grants | on demand |
| `search` | search | native `node:sqlite`, the index's memory | always |
| `viewers` | viewers, store | the viewer servers, the remote viewer streams and rendered surfaces, minutes-long installs | always |
| `edge` | workspaces, usage, monitor, projects, handoff, recaps, windowNames, shell | light pure-JS services: isolated from the core, not from each other | always |
diff --git a/cli/src/services/inline.spec.ts b/cli/src/services/inline.spec.ts
index 052a63fe2..db30b336f 100644
--- a/cli/src/services/inline.spec.ts
+++ b/cli/src/services/inline.spec.ts
@@ -2,6 +2,7 @@ import { questionControlFor } from '../engines/questionControls.js'
import { modelControlFor } from '../engines/modelControls.js'
import { screenFor } from '../engines/screens.js'
import { submissionFor } from '../engines/submissions.js'
+import { nativeControlFor } from '../engines/nativeControls.js'
import { describe, expect, it } from 'vitest'
import { engineTranscriptFor } from '../engines/transcripts.js'
import { liveFor } from '../engines/live.js'
@@ -29,6 +30,6 @@ import { startWorkspaces } from './workspaces.js'
describe('the services the core runs in its own process only when they do not run in theirs', () => {
it('are their own starts, unchanged: the same services either way', () => {
- expect({ ...inline }).toEqual({ engineTranscriptFor, liveFor, runtimeFor, screenFor, submissionFor, modelControlFor, questionControlFor, startCommandBar, startDevices, startHandoff, startGateway, startModels, startMonitor, startOrchestrator, startProjects, startRecaps, startSearch, startSharing, startShell, startStore, startTeamsInCore, startUsage, startViewers, startWifi, startWindowNames, startWorkspaces })
+ expect({ ...inline }).toEqual({ engineTranscriptFor, liveFor, runtimeFor, screenFor, submissionFor, nativeControlFor, modelControlFor, questionControlFor, startCommandBar, startDevices, startHandoff, startGateway, startModels, startMonitor, startOrchestrator, startProjects, startRecaps, startSearch, startSharing, startShell, startStore, startTeamsInCore, startUsage, startViewers, startWifi, startWindowNames, startWorkspaces })
})
})
diff --git a/cli/src/services/inline.ts b/cli/src/services/inline.ts
index 241f815ba..2e52bb869 100644
--- a/cli/src/services/inline.ts
+++ b/cli/src/services/inline.ts
@@ -17,6 +17,7 @@ export { engineTranscriptFor } from '../engines/transcripts.js'
export { liveFor } from '../engines/live.js'
export { screenFor } from '../engines/screens.js'
export { submissionFor } from '../engines/submissions.js'
+export { nativeControlFor } from '../engines/nativeControls.js'
export { modelControlFor } from '../engines/modelControls.js'
export { runtimeFor } from '../engines/runtime.js'
export { startGateway } from '../gateway/start.js'
diff --git a/cli/src/testing/inlineNativeControls.ts b/cli/src/testing/inlineNativeControls.ts
new file mode 100644
index 000000000..3fb8570d9
--- /dev/null
+++ b/cli/src/testing/inlineNativeControls.ts
@@ -0,0 +1,32 @@
+/** The core's native-control broker with the engines' own controls in process, for unit hosts. */
+import { readFile } from 'node:fs/promises'
+import { createNativeControls, type NativeControlsDeps } from '../core/engines/nativeControls.js'
+import { nativeControlFor } from '../engines/nativeControls.js'
+import { createNativeControl, type CodexNativeDeps } from '../engines/codex/nativeControl.js'
+import { launch as codexLaunch } from '../engines/codex/launch.js'
+import { sessionCodexHome } from '../lib/engineHomes.js'
+import { argvTokens, processRows } from '../lib/tmux.js'
+
+export function inlineNativeControls(over: Partial<NativeControlsDeps> = {}) {
+ return createNativeControls({ call: async () => ({ error: 'SERVICE_UNAVAILABLE' }), servers: { codex: codexLaunch.sharedServer! },
+ handles: () => false, inline: nativeControlFor, rows: processRows, home: session => sessionCodexHome(session), argv: argvTokens,
+ readFile: path => readFile(path, 'utf8'), log: () => {}, ...over })
+}
+
+/**
+ * Codex's control and the core's broker composed in one process over injected connections and files, as the
+ * former lib/codexSessionLifecycle.ts and CodexActivityReader were: their recorded cases run against this.
+ */
+export function composedCodex(deps: Pick<CodexNativeDeps, 'connect'> & Partial<Pick<CodexNativeDeps, 'now'>> & Pick<NativeControlsDeps, 'rows'>
+ & { daemonIdentity?(home: string): Promise<{ pid: number; processStartTime: string } | null> }) {
+ const now = deps.now ?? (() => performance.now())
+ const control = createNativeControl({ connect: deps.connect, now })
+ // The server's record, as the former code's injected reader gave it: none is the file's absence.
+ const readFile = async (path: string) => {
+ const identity = await deps.daemonIdentity?.(path.slice(0, -codexLaunch.sharedServer!.pidFile.length - 1)) ?? null
+ if (!identity) throw Object.assign(new Error('ENOENT'), { code: 'ENOENT' })
+ return JSON.stringify(identity)
+ }
+ const core = inlineNativeControls({ inline: () => control, rows: deps.rows, now, readFile })
+ return { read: core.activity, stop: core.stop, close: core.close }
+}
diff --git a/docs/design/2026-10-05-engine-interface.md b/docs/design/2026-10-05-engine-interface.md
index 8ca5b4e29..cf66b490f 100644
--- a/docs/design/2026-10-05-engine-interface.md
+++ b/docs/design/2026-10-05-engine-interface.md
@@ -13,10 +13,11 @@
> transport, process binding, prompt timestamps and event delivery. Discovery/resume, live ingestion,
> screen/input, models and one-shot handling remain to migrate.
> Since then, Claude Code's and Codex's transcript readers (#1015), live parsing (#1017, #1019), runtime
-> profiles (#1022), screen interpretation (#1027), model controls (#1038), question navigation and the
-> readings behind submission verification run in their supervised engine workers. Still in core for them:
-> hook admission and installers, engine-specific launch, discovery and resume, and native control
-> connections; [the remaining facets](2026-10-08-engine-remaining-facets.md) maps them and their order.
+> profiles (#1022), screen interpretation (#1027), model controls (#1038), question navigation, the
+> readings behind submission verification and Codex's shared app-server connection run in their
+> supervised engine workers. Still in core for them: hook admission and installers, and engine-specific
+> launch, discovery and resume; [the remaining facets](2026-10-08-engine-remaining-facets.md) maps them
+> and their order.
> The older all-engine branches (`engine-interface-1..5`, `engine-lane-*`, draft PR #842) are retained as
> reference work; they are not the implementation currently landing. The phased plan below is the
> target architecture, not a claim that all facets or engine isolation are already complete.
diff --git a/docs/design/2026-10-08-engine-native-control.md b/docs/design/2026-10-08-engine-native-control.md
new file mode 100644
index 000000000..361c51c55
--- /dev/null
+++ b/docs/design/2026-10-08-engine-native-control.md
@@ -0,0 +1,108 @@
+# Engine native control connections
+
+Codex's connection to its shared app-server now runs in the Codex worker, through
+`Engine.nativeControl`. That covers the `codex app-server proxy` client, the JSON-RPC protocol, the
+activity pool and the stop's sequence of requests. Before this batch the core spawned that child and
+kept its socket open. Now the core spawns no engine child and keeps no engine socket.
+
+Stopping an agent is session control, so every decision that needs no server stays in core. Core reads
+those decisions from the process table, the session's identity and store, and Codex's declared
+contract. A stop needs the Codex worker only for a conversation that is on a running shared server.
+The former code needed a server connection in exactly that case, too.
+
+## What moved, and what core reads itself
+
+| Was in `lib/codexSessionLifecycle.ts` / `CodexActivityReader` | Now |
+| --- | --- |
+| The `--no-daemon`, `--remote` and npm-wrapper argv rules | Core, from Codex's declared launch data (`EngineLaunch.sharedServer`: owned flag, remote flag, script names) |
+| The server's pid file (`app-server-daemon/daemon.pid`) and whether that process runs | Core: the file path is declared data; the process table is core's |
+| The unbound-chat proof, the early return for an exited client, cancellation | Core, unchanged |
+| The person's messages for these outcomes | Declared with the contract (`messages`), unchanged text |
+| `connectCodexControl`; `thread/read`; pause goal, interrupt turn, archive and unarchive, confirm `notLoaded` | The Codex worker (`engines/codex/nativeControl.ts`) |
+| The activity pool per home, with its 60 s backoff | The Codex worker |
+
+Core's side is `core/engines/nativeControls.ts`. It passes the worker only `{ home, sessionId }`, and
+only for a conversation it has established is on a running server.
+
+## The stop grant
+
+A stop runs under a single-use grant. Before each effect the worker asks core one of three things:
+
+- **`current`:** is the stop still wanted? A no revokes the grant.
+- **`pending`:** the worker is about to archive; is the stop still wanted? Core notes the archive, so
+ that it can be undone if this worker is lost before its unarchive.
+- **`settled`:** the unarchive was sent, so nothing is left to undo.
+
+A grant allows at most 32 questions. It is revoked on a refusal, a replaced connection, the deadline
+or completion.
+
+**Repair.** A stop that got no reply from its worker may have left a thread archived. Core keeps a note
+of any archive the stop marked `pending` and never marked `settled`. On the next connection of that
+worker, core asks it once to `recover` the thread (unarchive it), bounded at 15 s. Core logs the
+outcome and forgets the note either way. A stop that did get a reply needs no repair: that worker
+already made its own unarchive attempt. In inline mode nothing is kept, because there is no worker to
+lose.
+
+## When the worker does not answer
+
+**Stops that need no server** go ahead with no worker:
+
+- a client launched with `--no-daemon`;
+- a store with no server record;
+- a server process that is not running;
+- an unbound chat proved unused;
+- an exited client that never bound a conversation.
+
+**A conversation on a running shared server** with a worker that does not answer (parked, crashed, past
+its deadline) behaves as the former in-process code did when its connection to the server failed:
+
+- The stop is not confirmed, and it throws.
+- The client is not signalled, and its pane stays.
+- Core logs `the codex worker did not answer the stop`.
+
+**Activity** with no worker is `unknown`.
+
+**A close sent just after the Codex worker restarted** used to fail with `ENGINE_STALE_REPLY`: its
+first read went to the transcript tail through the worker being replaced. A read is idempotent, so the
+close now waits up to 10 s for the worker's new link (`core/engines/engineLinks.ts`) and reads once
+more. Writes are never retried this way.
+
+## Bounds
+
+| Bound | Value |
+| --- | --- |
+| Activity read | 15 s deadline, 8 in flight, 64 queued; past the deadline the worker is recycled |
+| Stop | 60 s deadline, 4 in flight, none queued; past the deadline the worker is recycled |
+| Recover | 15 s deadline |
+| One question to core | 10 s |
+| Reply | 4 KiB; a refusal is one line of at most 600 characters, with no control characters |
+
+The parent-bound `HARNESSD_ENGINE_NATIVE_CONTROL=<master-pid>:1` capability selects the worker.
+Explicit inline mode and older masters compose the same control in process
+(`services/inline.ts` `nativeControlFor`), and the core closes its connections at shutdown.
+
+## Validation
+
+- **Recorded cases.** The former `codexSessionLifecycle.spec.ts` and the `CodexActivityReader` cases
+ run unchanged against the composed pieces: `core/engines/nativeControls.stop.spec.ts`,
+ `lib/runtimeActivity.spec.ts`, `lib/engineHomeReaders.spec.ts`. So does the real close chain in
+ `lib/unusedCodexClose.spec.ts`.
+- **New unit tests.** They cover:
+ - the broker: decisions with no worker, the grant's answers, revocation, the count limit, the repair
+ on reconnect (done, refused, unreachable), refusal text, a worker that does not answer, inline
+ bounds;
+ - the worker requests: bounds, abort, deadline, recycle, late answers, load retry, recover;
+ - the close's single retried read and the engine links.
+- **`e2e/engineNativeControl.e2e.ts`** runs against the fake shared server:
+ - Activity runs over the worker's own proxy child. A close sent the moment that worker is killed
+ still stops the conversation, once.
+ - A worker killed while a stop waits on the server leaves the pane, and nothing more reaches the
+ server. A second close then stops the conversation once.
+ - A worker killed between archive and unarchive: the next worker unarchives the thread once, and a
+ later restart repairs nothing more.
+ - With the Codex worker parked, Stop ends a `--no-daemon` agent.
+ - With the Codex worker parked, Stop of a shared-server conversation fails closed: the pane stays,
+ the agent stays, and the failure is logged.
+ - Explicit inline mode closes through the core's own control.
+- **Unchanged suites.** `e2e/enginehomes.e2e.ts` (the moved shared server: activity, resources, close)
+ runs unchanged.
diff --git a/docs/design/2026-10-08-engine-remaining-facets.md b/docs/design/2026-10-08-engine-remaining-facets.md
index 1b487e722..6eac101bd 100644
--- a/docs/design/2026-10-08-engine-remaining-facets.md
+++ b/docs/design/2026-10-08-engine-remaining-facets.md
@@ -62,7 +62,9 @@ imports:
Splitting the shared functions into `engines/kit` frees another 1,000 to 2,000 lines.
-## (d) Native control connections
+## (d) Native control connections: done in the batch after (a)
+
+See [engine native control](2026-10-08-engine-native-control.md). The map below is as it stood before it.
| File | Engine-specific behavior | Stays in core | Can move | Risk |
| --- | --- | --- | --- | --- |