The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
Speak to Codex's shared app-server from the Codex worker (#1043)
Deeea9656a770bc
diff --git a/cli/AGENTS.md b/cli/AGENTS.mdindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.mdindex 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/AGEvalidates bounded replies, retains acknowledged cursors and owns binding/turn state. The explicitinline/older-master compatibility path is the only live parser or runtime profile implementationcomposition 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 thequestion on screen and holds the lease; Claude Code's and Codex's keys for each approved step come from their engineworker through a revocable grant (`engines/questionControls.ts`).diff --git a/cli/src/core/agents/close.spec.ts b/cli/src/core/agents/close.spec.tsindex 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.tsindex 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.tsindex 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.tsindex 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 markDeletedFnclearDeleted: typeof clearDeletedFnsessionCheckpoints: 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tssimilarity index 90%rename from cli/src/lib/codexSessionLifecycle.spec.tsrename to cli/src/core/engines/nativeControls.stop.spec.tsindex 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: RegisteredSessionlet deps: CodexStopDepslet 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.tsnew file mode 100644index 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.tsindex 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') : nulllet serviceLinksRef: ServiceLinks | null = nullconst 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.codexActivityconst runtimeActivity = activity.runtimeActivityconst turnActivity = activity.turnActivityactivityFrameContextRef = 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.closeAgentServicebackend.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.tsindex 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.tsindex 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.mdindex 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 historyreaders. 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 thediff --git a/cli/src/engines/codex/launch.ts b/cli/src/engines/codex/launch.tsindex 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.tsnew file mode 100644index 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.tsindex 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: EngineModelControlreadonly questionControl: EngineQuestionControlreadonly 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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 : undefineddiff --git a/cli/src/engines/registry.ts b/cli/src/engines/registry.tsindex 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/questionControlimport { 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 enginesexport function engineFor(name: string | null | undefined): Engine | undefined {diff --git a/cli/src/engines/worker/nativeControlHost.ts b/cli/src/engines/worker/nativeControlHost.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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: EngineProcessOptiquery: (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.tsindex 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.tsindex 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.tsindex 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, parentPiexport 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.tsdeleted file mode 100644index 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.tsindex 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 overlconst 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 }): voidmarkDeleted(agentId: string): voidclearDeleted(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 = truexport function createStopAgentService(deps: StopAgentServiceDeps) {const { registry, stoppedAgents, restartJobs, stopJobs, tmuxBackend, agentReconciler,- forgetSession, markDeleted, clearDeleted } = deps+ forgetSession, markDeleted, clearDeleted, stopNative } = depsreturn (target: string, options: StopAgentOptions = {}) => {const sessionId = registry.resolve(target)?.agentId ?? targetconst 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.tsindex 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 inactconst 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.tsindex 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.mdindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.mdindex 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.mdnew file mode 100644index 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.mdindex 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 || --- | --- | --- | --- | --- |