Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

CLI: a launch waits for the Desktop's engine download; Store requests wait through its restart (#1394)

Dee4a4a2e2a7a9d
diff --git a/cli/e2e/endurance.e2e.ts b/cli/e2e/endurance.e2e.ts
index 6cda5938b..2a710f25c 100644
--- a/cli/e2e/endurance.e2e.ts
+++ b/cli/e2e/endurance.e2e.ts
@@ -33,6 +33,7 @@ import { IsolatedDaemon, until } from './harness/daemon.js'
import { Desk } from './harness/desk.js'
import { alive, everyPid, forget, harnessdProcesses, slopes, startSampler, strays, tmuxClients, TurnLedger, type Sample } from './harness/endurance.js'
import { askAndAnswer, compareAnswers, engineAnswers, QUESTION_KINDS, summarizeAnswers, type QuestionEngine, type QuestionOutcome } from './harness/questionWork.js'
+import { ON_DEMAND_START_MS } from '../src/core/serviceLinks.js'
const ON = process.env.SOAK === '1'
function knob(name: string, fallback: number, min: number, max: number): number {
@@ -51,6 +52,9 @@ const SEED = knob('SOAK_SEED', 20261007, 0, 0xffffffff)
const OUT = process.env.SOAK_OUT ?? (ON ? mkdtempSync(join(tmpdir(), 'harness-soak-')) : '')
/** How long a request to a service that is down may take to be answered: at once, not after its wait. */
const FAST_MS = 5_000
+/** The Store's list instead waits for the viewers' process to come back, as long as a start (core/serviceLinks.ts
+ * `waitsThroughRestart`): a window's Store was answered unavailable while the master restarted it (2026-10-16). */
+const DOWN_MS: Record<string, number> = { viewers: ON_DEMAND_START_MS + FAST_MS }
const PROTOCOL = 3
const MARK = /soak-[a-z0-9]+-\d+/
@@ -409,7 +413,7 @@ describe.skipIf(!ON)('the daemon over time, every service in its own process', (
const starts = (name: string) => [...d.log().matchAll(new RegExp(`\\[harnessd\\] service ${name} started \\(pid (\\d+)\\)`, 'g'))].map((match) => Number(match[1]))
const linked = (name: string) => d.log().split(`[services] ${LINKS[name]} connected`).length - 1
- /** Asked while it is down: answered at once. Frozen: answered by the time the master has found it hung
+ /** Asked while it is down: answered at once, or for the Store's list once its process is back (`DOWN_MS`). Frozen: answered by the time the master has found it hung
* and killed it, never left waiting. Back: answered by it again. */
const probe = async (name: string, phase: 'down' | 'frozen' | 'back'): Promise<void> => {
const spec = PROBES[name]
@@ -417,7 +421,7 @@ describe.skipIf(!ON)('the daemon over time, every service in its own process', (
const asked = Date.now()
const answer = await waker.request(spec.type, spec.payload, 60_000).catch((error) => ({ error: `no answer: ${String(error)}` }))
const ms = Date.now() - asked
- if (phase === 'down' && ms > FAST_MS) findings.lines.push(`${name} down: ${spec.type} answered after ${ms} ms: ${JSON.stringify(answer).slice(0, 160)}`)
+ if (phase === 'down' && ms > (DOWN_MS[name] ?? FAST_MS)) findings.lines.push(`${name} down: ${spec.type} answered after ${ms} ms: ${JSON.stringify(answer).slice(0, 160)}`)
if (!acceptable(name, answer) && (phase === 'back' || !down(answer))) findings.lines.push(`${name} ${phase}: ${spec.type}: ${JSON.stringify(answer).slice(0, 160)}`)
events[events.length - 1][`${phase}Ms`] = ms
}
diff --git a/cli/e2e/freshMachineEngines.e2e.ts b/cli/e2e/freshMachineEngines.e2e.ts
index 0263bb39d..9a903ee2b 100644
--- a/cli/e2e/freshMachineEngines.e2e.ts
+++ b/cli/e2e/freshMachineEngines.e2e.ts
@@ -10,6 +10,8 @@
* unconfirmed after a minute.
* - A Codex that is not there at all is installed by Harness for a new project (2026-10-12): `harness new` waits for
* the install and then starts it, or says why it could not be installed, and leaves no folder behind either way.
+ * - A Codex the Desktop is still downloading as a brand-new Mac sets up (2026-10-16) is waited for: neither installed
+ * a second time beside it nor refused for the executable npm has linked and not yet finished.
*
* An agent starts harnesses only once the account lets it (Settings ▸ Experimental, off by default): the MCP case signs
* in to the fake backend, whose account has that on.
@@ -47,8 +49,8 @@ async function agentsMayStart(): Promise<{ env: Record<string, string>; signIn:
}
}
-/** `harness <args>` from a terminal, not a pane. */
-function harness(d: IsolatedDaemon, args: string[]): Promise<{ code: number; out: string; err: string; ms: number }> {
+/** `harness <args>` from a terminal, not a pane; `said` hears its standard error as it comes. */
+function harness(d: IsolatedDaemon, args: string[], said: (err: string) => void = () => {}): Promise<{ code: number; out: string; err: string; ms: number }> {
const began = Date.now()
return new Promise((done) => {
const child = spawn(process.execPath, ['--import', 'tsx', 'src/cli.ts', ...args], {
@@ -56,7 +58,7 @@ function harness(d: IsolatedDaemon, args: string[]): Promise<{ code: number; out
})
let out = '', err = ''
child.stdout.on('data', (chunk) => { out += chunk })
- child.stderr.on('data', (chunk) => { err += chunk })
+ child.stderr.on('data', (chunk) => { err += chunk; said(err) })
child.on('close', (code) => done({ code: code ?? -1, out, err, ms: Date.now() - began }))
})
}
@@ -238,6 +240,48 @@ it('installs a missing Codex for a new project and starts it there, or says why
} finally { client.close() }
}, 180_000)
+it('waits for the Desktop\'s own download of Codex, rather than installing it beside it or refusing what it has written so far', async (context) => {
+ if (notBare()) context.skip()
+ const d = await boot((d) => {
+ withoutCodex(d)
+ // Every npm the daemon or a pane runs, said where the test can read it.
+ const npm = join(d.root, 'bin', 'npm'), script = readFileSync(npm, 'utf8').split('\n')
+ writeFileSync(npm, [script[0], `printf '%s\\n' "$*" >> ${JSON.stringify(join(d.root, 'npm-calls'))}`, ...script.slice(1)].join('\n'), { mode: 0o755 })
+ })
+ const home = d.env.HOME!, bin = join(home, '.local', 'bin'), run = join(home, '.harness', 'run')
+ mkdirSync(bin, { recursive: true }); mkdirSync(run, { recursive: true })
+ // What npm has linked before it has written the package the launcher needs (a brand-new Mac, 2026-10-16).
+ writeFileSync(join(bin, 'codex'), `#!${process.execPath}\nconsole.error("Error: Cannot find module '@openai/codex-darwin-arm64'");\nprocess.exit(1)\n`, { mode: 0o755 })
+ // The Desktop's download as it runs it (desktop/lib/bootstrap/agent_prefetch.dart): a shell named harness-download,
+ // its pid in the marker, which it removes once done. It finishes once the launch has been seen held for it, however
+ // long the CLI and the daemon took to get there.
+ const marker = join(run, 'downloading-codex'), release = join(d.root, 'download-may-finish')
+ const download = spawn('/bin/sh', ['-c', `while [ ! -f ${JSON.stringify(release)} ]; do sleep 0.2; done; `
+ + `cp ${JSON.stringify(join(d.root, 'codex-package'))} ${JSON.stringify(join(bin, 'codex'))}; rm -f ${JSON.stringify(marker)}; exit $?`,
+ 'harness-download'], { stdio: 'ignore' })
+ try {
+ writeFileSync(marker, String(download.pid))
+ const started = await harness(d, ['new', 'codex', 'scratch1', '--name', 'cx', '--', 'Reply with pong'],
+ (err) => { if (err.includes('Downloading Codex.')) writeFileSync(release, '') })
+ expect(started.code, started.out + started.err).toBe(0)
+ // Said first, as the hold it is; the download's last write may leave the next look a moment to settle.
+ expect(started.err.trim().split('\n')[0]).toBe('Downloading Codex. The harness starts once it is downloaded.')
+ expect(started.err).not.toContain('cannot run')
+ expect(started.out).toContain(`Created cx on this computer in ${join(home, 'harnesses', 'scratch1')}.`)
+ } finally { download.kill('SIGKILL') }
+ // Nothing installed it a second time.
+ const npmCalls = existsSync(join(d.root, 'npm-calls')) ? readFileSync(join(d.root, 'npm-calls'), 'utf8') : ''
+ expect(npmCalls).not.toMatch(/^install/m)
+ const client = await LocalClient.connect(d)
+ try {
+ const agents = await until('Codex to bind its conversation in its new project', async () => {
+ const rows = (await client.request<{ agents: Array<Record<string, any>> }>('agents_list', { includeStopped: true }, 30_000)).agents
+ return rows.length === 1 && rows[0]!.sessionId && rows[0]!.status === 'active' ? rows : null
+ }, 60_000, 500)
+ expect(agents[0]).toMatchObject({ name: 'cx' })
+ } finally { client.close() }
+}, 180_000)
+
/** `harness mcp` as Codex starts it: requests in on stdin, answers by id from stdout. */
function mcp(d: IsolatedDaemon) {
const child = spawn(process.execPath, ['--import', 'tsx', 'src/cli.ts', 'mcp'], { cwd: CLI_ROOT, env: { ...d.env, TMUX_PANE: '' }, stdio: ['pipe', 'pipe', 'pipe'] })
diff --git a/cli/e2e/storeProcess.e2e.ts b/cli/e2e/storeProcess.e2e.ts
index 6bd367cf7..30d3c01ed 100644
--- a/cli/e2e/storeProcess.e2e.ts
+++ b/cli/e2e/storeProcess.e2e.ts
@@ -5,8 +5,8 @@
* repository runs there, its progress reaches the window as `dsh_install_status` through the core, and an
* agent created on the harness the moment the install answers finds it installed, though the core keeps
* the installed index for two seconds (dsh/installed.ts). Whatever happens to the process costs the Store
- * and the viewers alone: killed, a list asked meanwhile is answered SERVICE_UNAVAILABLE at once, agents go
- * on, and the master brings it back.
+ * and the viewers alone: killed, a list asked meanwhile waits for the master to bring it back, within a start's
+ * wait (core/serviceLinks.ts `waitsThroughRestart`), and agents go on.
*/
import { execFileSync } from 'node:child_process'
import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
@@ -47,6 +47,7 @@ const viewersPid = (d: IsolatedDaemon): number | null => {
return started.length ? Number(started[started.length - 1][1]) : null
}
const connected = (d: IsolatedDaemon) => d.log().split('[services] store connected').length - 1
+const disconnected = (d: IsolatedDaemon) => d.log().split('[services] store disconnected').length - 1
const row = async (client: LocalClient, agentId: string) =>
((await client.request<{ agents: Array<Record<string, any>> }>('agents_list', { includeStopped: true }, 30_000)).agents)
.find((agent) => agent.id === agentId)
@@ -128,14 +129,18 @@ describe('the Store in its own process, beside the viewers', () => {
client.close()
})
- it('killed outright: asked meanwhile it says so at once, agents go on, and the master brings it back', async () => {
+ it('killed outright: asked meanwhile it waits for the master to bring it back, within a start, and agents go on', async () => {
const d = await fresh()
const client = await LocalClient.connect(d)
const agent = await create(d, client, 'store-killed')
- const pid = viewersPid(d)!
+ const pid = viewersPid(d)!, gone = disconnected(d)
process.kill(pid, 'SIGKILL')
+ await until('the core to see the Store go', () => disconnected(d) > gone || null, 10_000, 50)
+ // Asked while it is down: held while the master restarts it (core/serviceLinks.ts `waitsThroughRestart`) and
+ // answered by it once it is back. It was answered SERVICE_UNAVAILABLE at once (7 Store lists on 2026-10-16).
const listed = await client.request('dsh_list', {}, 30_000)
- if (listed.error) expect(listed).toMatchObject({ error: 'SERVICE_UNAVAILABLE', service: 'store', retryable: true })
+ expect(listed.error, JSON.stringify(listed)).toBeUndefined()
+ expect(Array.isArray(listed.dsh)).toBe(true)
await turn(client, agent.id, 'while the Store was gone')
await until('the Store to be back', () => connected(d) >= 2 || null, 30_000, 200)
await until('the Store to list again', async () => Array.isArray((await client.request('dsh_list', {}, 60_000)).dsh) || null, 60_000, 500)
diff --git a/cli/src/core/agents/launches.spec.ts b/cli/src/core/agents/launches.spec.ts
index b757e18b2..e15350dba 100644
--- a/cli/src/core/agents/launches.spec.ts
+++ b/cli/src/core/agents/launches.spec.ts
@@ -6,6 +6,8 @@ import { installedDsh } from '../../dsh/installed.js'
import { dshSupportedEngines } from '../../dsh/manifest.js'
import { loadEngine } from '../../engines/inProcess.js'
import { opencodeMajorVersion } from '../../engines/launchControl.js'
+import type { NativeLaunchResult } from '../../engines/nativeLaunch.js'
+import { createNativeLaunchPreparer } from '../../engines/prepareNativeLaunch.js'
import { AgentCreationReceiptError, AgentCreationReceipts, creationFingerprint, type AgentCreationOutcome } from '../../lib/agentCreationReceipt.js'
import type { AgentFrame } from '../../lib/agentFrame.js'
import { MAX_FIRST_PROMPT_CHARS, permissionModeApproves, permissionModeFlags, supportsFirstPrompt, supportsNamedAgent } from '../../lib/engineLaunch.js'
@@ -619,6 +621,44 @@ describe('agent_create with a receipt', () => {
await vi.waitFor(() => expect(replies[0]).toMatchObject({ state: 'pending', held: { service: 'install', detail: 'Installing Codex. The harness starts once it is installed.' } }))
})
+ it('holds a create while Desktop Harness downloads its engine, and creates it once by itself when the download ends', async () => {
+ // A brand-new Mac (2026-10-16): the Desktop sends agent_create as soon as its own download of Codex is under way.
+ // The launch is held as an install, tried again every two seconds with nobody asking, and dispatched once.
+ let downloading = true, clock = Date.now()
+ vi.spyOn(Date, 'now').mockImplementation(() => clock)
+ const missing: NativeLaunchResult = { ok: false, error: 'NATIVE_LAUNCH_HELD', unavailable: 'native', detail: 'Not installed',
+ install: { command: 'fixture-installer', source: 'fixture', executable: { names: ['codex'] } }, environment: { HOME: '/fixture/home' } }
+ const inspect = vi.fn(async (): Promise<NativeLaunchResult> => downloading ? missing : { ok: true, launch: {} as never })
+ const ensure = vi.fn()
+ // Read as it is asked: an attempt keeps the answer it was given, whatever the test says after.
+ const downloadingNow = vi.fn(async () => downloading)
+ const prepareEngine = createNativeLaunchPreparer({ installations: { ensure, status: vi.fn(async () => null) }, inspect, downloading: downloadingNow })
+ const dispatch = vi.fn(async () => ({ ok: true as const, session: session('new-agent') }))
+ const prepareCreate = vi.fn<NonNullable<LaunchRequestDeps['prepareCreate']>>(async () => ({ ok: true, dispatch }))
+ const { ask, replies, requests, deps } = setup({ prepareCreate, prepareEngine })
+ await ask({ engine: 'codex', projectSource: 'new', projectName: 'scratch1', creationId: CREATION })
+ await vi.waitFor(() => expect(replies[0]).toMatchObject({ state: 'pending',
+ held: { service: 'install', detail: 'Downloading Codex. The harness starts once it is downloaded.' } }))
+ requests.open()
+ // Still downloading: asked again and held again, nothing installed beside it, no folder, nothing created.
+ clock += 3_000; await requests.recover()
+ await vi.waitFor(() => expect(inspect).toHaveBeenCalledTimes(2))
+ await vi.waitFor(() => expect(downloadingNow).toHaveBeenCalledTimes(2))
+ expect(deps.receipts.status(CREATION)).toMatchObject({ state: 'pending', held: { service: 'install' } })
+ expect(prepareProjectFolder).not.toHaveBeenCalled()
+ // The download ends: the next pass creates it.
+ downloading = false
+ clock += 3_000; await requests.recover()
+ await vi.waitFor(() => expect(dispatch).toHaveBeenCalledOnce())
+ await vi.waitFor(() => expect(deps.receipts.status(CREATION)).toEqual({ state: 'created', agentId: 'new-agent' }))
+ // Once: later passes find nothing to do.
+ for (let pass = 0; pass < 3; pass++) { clock += 3_000; await requests.recover() }
+ await settle()
+ expect(dispatch).toHaveBeenCalledOnce()
+ expect(prepareProjectFolder).toHaveBeenCalledOnce()
+ expect(ensure).not.toHaveBeenCalled()
+ })
+
it('trusts only a folder it just made empty, or a worktree of a repository the engine already trusts', async () => {
vi.spyOn(console, 'warn').mockImplementation(() => {})
const { ask, replies } = setup()
diff --git a/cli/src/core/main.ts b/cli/src/core/main.ts
index b84ec184c..a05b98f6b 100644
--- a/cli/src/core/main.ts
+++ b/cli/src/core/main.ts
@@ -10,6 +10,7 @@ import { opencodeMajorVersion } from '../engines/launchControl.js'
import { inspectNativeLaunch, type NativeLaunch } from '../engines/nativeLaunch.js'
import { nativeHookLocations } from '../engines/kit/nativeLocations.js'
import { createNativeLaunchPreparer } from '../engines/prepareNativeLaunch.js'
+import { engineDownloading } from '../engines/kit/downloadMarker.js'
import { createNativeInstallations } from '../engines/kit/nativeInstall.js'
import { publishGridConfigDir } from '../lib/publishedGridConfig.js'
import { masterRunsEngineScreen } from '../harnessd/services.js'
@@ -1405,6 +1406,9 @@ async function runForeground(session: AuthSession | null): Promise<void> {
// can beat that host's connection. Hold it through the same bounded startup gate; after any disconnect, fail
// promptly as before. Under a master from before, Agent Messages' own process starts at its first request this way.
onDemand: new Set([...experiments, ...DEVICES_ON_DEMAND, ...VIEWERS_ON_DEMAND, ...Object.values(READER_SERVICES), 'models', 'gateway', 'shell', 'messages']),
+ // But the Store's requests wait through its process's restart too: a window's Store list was answered unavailable
+ // while the master restarted the viewers (core/serviceLinks.ts `waitsThroughRestart`).
+ waitsThroughRestart: new Set(['store']),
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, authority) => 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)
@@ -2169,6 +2173,8 @@ async function runForeground(session: AuthSession | null): Promise<void> {
inspect: (engine, source) => inspectNativeLaunch(engine, source, {
confirmHome: (engine, home) => { confirmHomes({ [sessionStoreContracts[engine].sessions.moved.variable]: home }) },
}),
+ // The Desktop's own download of the engine on a fresh computer: a launch waits for it rather than installing beside it.
+ downloading: (engine) => engineDownloading(engine),
})
const launchOverridesDeps: LaunchOverridesDeps = {
publishConfig: publishGridConfigDir,
diff --git a/cli/src/core/serviceLinks.spec.ts b/cli/src/core/serviceLinks.spec.ts
index 6aa853a02..4fafdf199 100644
--- a/cli/src/core/serviceLinks.spec.ts
+++ b/cli/src/core/serviceLinks.spec.ts
@@ -1,5 +1,5 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { createServiceLinks, HELD_MAX, ON_DEMAND_START_MS, type ServiceFrame } from './serviceLinks.js'
+import { createServiceLinks, HELD_MAX, ON_DEMAND_START_MS, RESTART_HELD_MAX, type ServiceFrame } from './serviceLinks.js'
const TOKEN = 'a'.repeat(48)
const ASKER = { local: false, owner: true }
@@ -194,6 +194,70 @@ describe('service links', () => {
expect(search).toHaveBeenCalledWith({ error: 'SERVICE_UNAVAILABLE', service: 'search', retryable: true })
})
+ it('holds a request for the Store while its process restarts and delivers it once it is back; one past its wait is refused', async () => {
+ // 2026-10-16, a day of six updates: a window's Store list asked while the master restarted the viewers' process
+ // was answered SERVICE_UNAVAILABLE at once, 7 times.
+ const want = vi.fn()
+ const unavailable = (service: string) => ({ error: 'SERVICE_UNAVAILABLE', service, retryable: true })
+ const links = make({ owned: { store: ['dsh_list'], devices: ['harness_devices_list'] }, onDemand: new Set(['store', 'devices']),
+ waitsThroughRestart: new Set(['store']), want, startWaitMs: 20_000, timeoutMs: 30_000 })
+ links.accept('store', TOKEN, sink(), vi.fn())!.closed()
+ // Asked while it is down: held, and asked for again, since a master that re-executed for an update leaves a
+ // process on demand off until it is asked for.
+ const listed = vi.fn()
+ links.route('dsh_list', {}, ASKER, listed)
+ expect(listed).not.toHaveBeenCalled()
+ expect(want).toHaveBeenCalledWith('store')
+ vi.advanceTimersByTime(3_000)
+ const store = sink()
+ const link = links.accept('store', TOKEN, store, vi.fn())!
+ expect(store.sent).toEqual([{ type: 'dsh_list', payload: { requestId: 'route-1' }, asker: ASKER }])
+ link.receive({ type: 'dsh_list_result', payload: { requestId: 'route-1', dsh: [] } })
+ expect(listed).toHaveBeenCalledWith({ dsh: [] })
+ // Gone again, and not back within the start wait: refused then, and what comes after at once, until it is back.
+ link.closed()
+ const late = vi.fn(), next = vi.fn()
+ links.route('dsh_list', {}, ASKER, late)
+ vi.advanceTimersByTime(19_999)
+ expect(late).not.toHaveBeenCalled()
+ vi.advanceTimersByTime(1)
+ expect(late).toHaveBeenCalledWith(unavailable('store'))
+ links.route('dsh_list', {}, ASKER, next)
+ expect(next).toHaveBeenCalledWith(unavailable('store'))
+ // Back, then gone: waited for again, and a request with a shorter wait of its own only for that wait.
+ links.accept('store', TOKEN, sink(), vi.fn())!.closed()
+ const waited = vi.fn()
+ links.route('dsh_list', {}, ASKER, waited)
+ const launch = links.call('store', 'dshLaunch', {}, 5_000)
+ vi.advanceTimersByTime(5_000)
+ await expect(launch).resolves.toEqual(unavailable('store'))
+ expect(waited).not.toHaveBeenCalled()
+ // Any other service on demand is refused at once while it is down, as before.
+ links.accept('devices', TOKEN, sink(), vi.fn())!.closed()
+ const devices = vi.fn()
+ links.route('harness_devices_list', {}, ASKER, devices)
+ expect(devices).toHaveBeenCalledWith(unavailable('devices'))
+ })
+
+ it('holds a bounded number of requests for a service to come back, and refuses the rest at once', () => {
+ const links = make({ owned: { store: ['dsh_list'], search: ['session_search'] }, onDemand: new Set(['store']),
+ waitsThroughRestart: new Set(['store']), want: vi.fn() })
+ links.accept('store', TOKEN, sink(), vi.fn())!.closed()
+ // What waits on another service is not counted against this one.
+ links.accept('search', TOKEN, sink(), vi.fn())
+ const searching = vi.fn()
+ for (let n = 0; n < RESTART_HELD_MAX; n++) links.route('session_search', {}, ASKER, searching)
+ const held = vi.fn(), over = vi.fn()
+ for (let n = 0; n < RESTART_HELD_MAX; n++) links.route('dsh_list', {}, ASKER, held)
+ links.route('dsh_list', {}, ASKER, over)
+ expect(held).not.toHaveBeenCalled()
+ expect(searching).not.toHaveBeenCalled()
+ expect(over).toHaveBeenCalledWith({ error: 'SERVICE_UNAVAILABLE', service: 'store', retryable: true })
+ const store = sink()
+ links.accept('store', TOKEN, store, vi.fn())
+ expect(store.sent).toHaveLength(RESTART_HELD_MAX)
+ })
+
it('waits as long as a call says it may (a pairing), and answers SERVICE_UNAVAILABLE after', async () => {
const links = make({ owned: { gateway: [] } })
links.accept('gateway', TOKEN, sink(), vi.fn())
diff --git a/cli/src/core/serviceLinks.ts b/cli/src/core/serviceLinks.ts
index 1f0b4bb40..3033a6fd0 100644
--- a/cli/src/core/serviceLinks.ts
+++ b/cli/src/core/serviceLinks.ts
@@ -6,7 +6,8 @@
* alike, so no other local process can stand in for one. The core then routes the requests the service
* answers to it and relays each answer back to the client that asked; a request that finds the service
* down, or not answering in time, is answered SERVICE_UNAVAILABLE with `retryable: true` — the core never
- * waits on a service in line. A routed request carries the connection it came over (`Asker.connection`),
+ * waits on a service in line. A service on demand is waited for as it starts, and the Store as it comes back
+ * too, each request for a bounded time and none of them in line (`onDemand`, `waitsThroughRestart`). A routed request carries the connection it came over (`Asker.connection`),
* and the core says when that connection closes (`closeConnection`). The core tells a service what it
* needs to know with `notify`, and answers the few questions a service may ask it (`service_query`),
* nothing more.
@@ -66,8 +67,12 @@ export interface ServiceLinksOptions {
* devices (core/devicesWake.ts), models (core/modelsWake.ts) and the viewers and the Store (core/viewersWake.ts). A request for one that has not connected yet
* asks for it (`want`) and waits for it to connect, for its own wait or `startWaitMs`, whichever is shorter,
* and then for its answer, for its own wait. One that has connected and is down again is answered as any
- * service is, at once; so is one that did not connect in time, until it does. */
+ * service is, at once, unless it is in `waitsThroughRestart`; so is one that did not connect in time, until it does. */
onDemand?: ReadonlySet<string>
+ /** Of those, the ones whose requests also wait for them to come back after they connected and went (a crash, a
+ * kill, the master's restart for an update), as a first start is waited for: asked for again, within the same
+ * start wait and then the request's own, at most `RESTART_HELD_MAX` at a time for each. The Store's (core/main.ts). */
+ waitsThroughRestart?: ReadonlySet<string>
/** How long a request waits for its service on demand to connect (`ON_DEMAND_START_MS`). */
startWaitMs?: number
/** Ask the master for a process on demand (harnessd/coreLink.ts `want`). */
@@ -107,6 +112,11 @@ export const HELD_MAX = 1_000
* set-up, a download), which a request for a models that cannot start must not wait on its connection. */
export const ON_DEMAND_START_MS = 20_000
+/** The most requests held at once for one service to come back after it went (`waitsThroughRestart`); past it,
+ * a request is answered SERVICE_UNAVAILABLE at once, as before. A window asks the Store a few things at a time
+ * (its list, an install): this is many windows' worth, and all a service that does not come back can pile up. */
+export const RESTART_HELD_MAX = 100
+
/** Who asks when the core itself asks a service (`call`): this machine's owner, on this machine. */
const THE_CORE: Asker = { local: true, owner: true }
@@ -125,7 +135,7 @@ export function createServiceLinks(options: ServiceLinksOptions) {
const seen = new Set<string>()
/** Asked for and not connected within a request's wait: the master could not start it (it ends as it starts,
* and is parked). Its requests are answered at once, as a service that is down is, instead of each waiting
- * the whole wait again (⌘K's 25 s, found end to end with the devices crashing on every start). */
+ * the whole wait again (⌘K's 25 s, found end to end with the devices crashing on every start), until it connects. */
const unstarted = new Set<string>()
const waiting = new Map<string, Waiting>()
/** What a service must hear even if it is down when it is said (a purge's forgetting), delivered on
@@ -146,6 +156,14 @@ export function createServiceLinks(options: ServiceLinksOptions) {
entry.reply(result)
}
+ /** How many requests wait for `service`, which is down: all of them wait for it to connect, since what was sent to
+ * it was answered as it went (`closed`, and `accept` for a replaced connection). */
+ const heldFor = (service: string): number => {
+ let count = 0
+ for (const entry of waiting.values()) if (entry.service === service) count++
+ return count
+ }
+
/** How long an answer from `service` to `type` is waited for: its own wait when it has one. */
const waitFor = (service: string, type: string): number => {
const waits = options.waits?.[service]
@@ -156,7 +174,15 @@ export function createServiceLinks(options: ServiceLinksOptions) {
* not connected is asked for, and the request goes once it connects: off, it costs nothing until asked. */
const ask = (service: string, type: string, payload: Record<string, unknown>, asker: Asker, reply: (result: Record<string, unknown>) => void, waitMs?: number): void => {
const link = links.get(service)
- const starting = !link && !!options.onDemand?.has(service) && !seen.has(service) && !unstarted.has(service)
+ const awaited = !link && !!options.onDemand?.has(service) && !unstarted.has(service)
+ // Coming back after it connected: the Store, while the master restarts the viewers' process (a crash, an update's
+ // handover), answered the windows' Store list SERVICE_UNAVAILABLE at once (7 times on 2026-10-16, a day of six
+ // updates). Held as a first start is, in time and in number: a process that does not come back holds at most
+ // RESTART_HELD_MAX requests for one start wait, and none after it (`unstarted`). The other services are refused at
+ // once while down, as their callers expect: a viewer's rendered frame, an engine worker's answer, ⌘K's route
+ // (e2e/viewersProcess, engineQuestionControl and devicesProcess).
+ const starting = awaited && (!seen.has(service)
+ || (!!options.waitsThroughRestart?.has(service) && heldFor(service) < RESTART_HELD_MAX))
if (!link && !starting) { reply(unavailable(service)); return }
const id = newId()
const frame: ServiceFrame = { type, payload: { ...payload, requestId: id }, asker }
@@ -187,6 +213,8 @@ export function createServiceLinks(options: ServiceLinksOptions) {
const connected: Connected = { sink, close }
links.set(service, connected)
seen.add(service)
+ // Back: the next time it goes, it is waited for again.
+ unstarted.delete(service)
log(`[services] ${service} connected`)
// Found by QA on a quiet machine: a cold Share received its request before `connected`, so it
// read agents without a core connection and answered HARNESS_NOT_FOUND. Welcome it first.
diff --git a/cli/src/engines/kit/downloadMarker.spec.ts b/cli/src/engines/kit/downloadMarker.spec.ts
new file mode 100644
index 000000000..e6f26cd06
--- /dev/null
+++ b/cli/src/engines/kit/downloadMarker.spec.ts
@@ -0,0 +1,70 @@
+/**
+ * The Desktop's download marker as the daemon reads it, the pane's check exactly (lib/engineLaunch.ts
+ * `harness_wait_download`): real files in a private home and real processes, never the person's `~/.harness`.
+ */
+import { execFileSync, spawn, type ChildProcess } from 'node:child_process'
+import { mkdirSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, expect, it } from 'vitest'
+import { DOWNLOAD_HOLD_MS, engineDownloading } from './downloadMarker.js'
+
+let home: string, run: string
+const children: ChildProcess[] = []
+beforeEach(() => { home = mkdtempSync(join(tmpdir(), 'download-marker-')); run = join(home, '.harness', 'run'); mkdirSync(run, { recursive: true }) })
+afterEach(() => { for (const child of children.splice(0)) child.kill('SIGKILL'); rmSync(home, { recursive: true, force: true }) })
+
+/** As the Desktop starts its download: `sh -c '<script>; exit $?' harness-download`, the name its $0. */
+async function download(): Promise<number> {
+ const child = spawn('/bin/sh', ['-c', 'sleep 30; exit $?', 'harness-download'], { stdio: 'ignore' })
+ children.push(child)
+ await new Promise(done => child.once('spawn', done))
+ return child.pid!
+}
+const mark = (text: string, engine = 'codex') => writeFileSync(join(run, `downloading-${engine}`), text)
+
+it('is a live process the marker names whose command line names the download, for that engine alone', async () => {
+ const pid = await download()
+ mark(String(pid))
+ expect(await engineDownloading('codex', home)).toBe(true)
+ expect(await engineDownloading('claude', home)).toBe(false)
+ // The pane reads it through `$(cat …)`, which drops trailing newlines.
+ mark(`${pid}\n`)
+ expect(await engineDownloading('codex', home)).toBe(true)
+})
+
+it('is no download for a missing, malformed, oversized or stale marker, or one that is not a file', async () => {
+ const pid = await download()
+ expect(await engineDownloading('codex', home)).toBe(false)
+ for (const text of ['', ' 12', `${pid}x`, '-1', '0', '12345678901', `${pid}\n${pid}`]) {
+ mark(text)
+ expect(await engineDownloading('codex', home), JSON.stringify(text)).toBe(false)
+ }
+ mark(`${pid}`.padEnd(40, '\n'))
+ expect(await engineDownloading('codex', home)).toBe(false)
+ // Older than a pane waits for a download.
+ mark(String(pid))
+ const old = (Date.now() - DOWNLOAD_HOLD_MS - 60_000) / 1000
+ utimesSync(join(run, 'downloading-codex'), old, old)
+ expect(await engineDownloading('codex', home)).toBe(false)
+ expect(await engineDownloading('codex', home, () => Date.now() - DOWNLOAD_HOLD_MS)).toBe(true)
+ // A folder, and a FIFO with no writer, which must not hold the read.
+ rmSync(join(run, 'downloading-codex'))
+ mkdirSync(join(run, 'downloading-codex'))
+ expect(await engineDownloading('codex', home)).toBe(false)
+ execFileSync('mkfifo', [join(run, 'downloading-claude')])
+ expect(await engineDownloading('claude', home)).toBe(false)
+})
+
+it('is no download for a process that is gone, another user\'s, or anything but the download', async () => {
+ const ended = spawn('/bin/sh', ['-c', 'exit 0', 'harness-download'], { stdio: 'ignore' })
+ await new Promise(done => ended.once('exit', done))
+ mark(String(ended.pid))
+ expect(await engineDownloading('codex', home)).toBe(false)
+ // pid 1 is the system's: signalling it is refused, as `kill -0` is refused it (and as root, it is not the download).
+ mark('1')
+ expect(await engineDownloading('codex', home)).toBe(false)
+ // A stale marker's pid taken over by another process: this test's runner.
+ mark(String(process.pid))
+ expect(await engineDownloading('codex', home)).toBe(false)
+})
diff --git a/cli/src/engines/kit/downloadMarker.ts b/cli/src/engines/kit/downloadMarker.ts
new file mode 100644
index 000000000..66b305dd8
--- /dev/null
+++ b/cli/src/engines/kit/downloadMarker.ts
@@ -0,0 +1,74 @@
+/**
+ * Desktop Harness downloading an engine beside a fresh computer's setup (desktop/lib/bootstrap/agent_prefetch.dart):
+ * OpenCode with its curl recipe, Codex and Claude Code with one `npm install -g` into `~/.local`. While a download
+ * runs, it names its process in `~/.harness/run/downloading-<engine>`, and the CLI tells the Desktop it waits for
+ * downloads (`waitsForDownload`, backendSocket.ts), so the Desktop sends `agent_create` as soon as that marker is
+ * there. A pane's shell waits for the download it names (lib/engineLaunch.ts `harness_wait_download`), but the
+ * daemon's own launch preparation (engines/prepareNativeLaunch.ts) inspected the engine and installed it without
+ * reading the marker. It probed an executable npm had linked and not yet finished and refused the launch as
+ * ENGINE_CANNOT_RUN, with no installer of its own to hold it for; or it dispatched an installer of its own beside the
+ * Desktop's npm, whose shell waits for the download only while no executable is there at all, takes a half-written
+ * one for installed, and fails after ten minutes (ENGINE_INSTALL_FAILED). Failed agent starts from the Desktop went
+ * from 6 to 25 on 2026-10-16, a sign-up surge of brand-new Macs.
+ *
+ * The same check as the pane's: a numeric pid in the marker, a live process with it, whose command line names the
+ * download (`harness-download`, the Desktop's `downloadName`), so a stale marker whose pid now belongs to something
+ * else is ignored. Cheap and bounded: a 32-byte read, a signal 0, and one `ps` of at most two seconds off the core's
+ * thread, only while a marker with a live pid exists. Anything it cannot read is no download: today's behaviour.
+ */
+import { execFile } from 'node:child_process'
+import { constants } from 'node:fs'
+import { open } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { probeExecFile } from '../../lib/offThreadExec.js'
+import type { AgentEngine } from '../types.js'
+
+/** The download's own word for itself on its command line (agent_prefetch.dart `downloadName`). */
+export const DOWNLOAD_NAME = 'harness-download'
+
+/** A marker older than this is no longer waited for: the pane gives up on a download after ten minutes (it then
+ * says the engine is still downloading), and the daemon's launch then goes on as before, through its own
+ * installer, which waits for the same download in its shell and ends there. */
+export const DOWNLOAD_HOLD_MS = 600_000
+
+/** Whether Desktop Harness is downloading `engine` now. Never rejects. */
+export async function engineDownloading(engine: AgentEngine, home: string = homedir(), now: () => number = Date.now): Promise<boolean> {
+ const pid = await markedPid(join(home, '.harness', 'run', `downloading-${engine.replace(/[^a-z0-9-]/g, '')}`), now)
+ if (pid === null) return false
+ // As `kill -0`: a process of another user answers EPERM, which the pane's check reads as gone too.
+ try { process.kill(pid, 0) } catch { return false }
+ return (await commandLine(pid))?.includes(DOWNLOAD_NAME) ?? false
+}
+
+async function markedPid(file: string, now: () => number): Promise<number | null> {
+ let handle: Awaited<ReturnType<typeof open>> | undefined
+ try {
+ // Non-blocking: a FIFO in the marker's place must not keep a thread waiting for a writer.
+ handle = await open(file, constants.O_RDONLY | constants.O_NONBLOCK)
+ const info = await handle.stat()
+ if (!info.isFile() || info.size > 32 || now() - info.mtimeMs > DOWNLOAD_HOLD_MS) return null
+ const bytes = Buffer.alloc(32)
+ const { bytesRead } = await handle.read(bytes, 0, bytes.length, 0)
+ // The Desktop writes the pid alone; `$(cat …)` in the pane drops trailing newlines, and so does this.
+ const text = bytes.subarray(0, bytesRead).toString('utf8').replace(/\n+$/, '')
+ if (!/^[0-9]{1,10}$/.test(text)) return null
+ const pid = Number(text)
+ // 0 would ask about this process group, never a download.
+ return pid > 0 ? pid : null
+ } catch {
+ return null
+ } finally {
+ await handle?.close().catch(() => {})
+ }
+}
+
+/** `ps -p <pid> -o command=`, as the pane asks it: the whole command line when it does not print to a terminal. */
+function commandLine(pid: number): Promise<string | null> {
+ return new Promise((resolve) => {
+ try {
+ probeExecFile(execFile)('ps', ['-p', String(pid), '-o', 'command='], { timeout: 2_000, killSignal: 'SIGKILL', maxBuffer: 1 << 20 },
+ (error, stdout) => resolve(error ? null : stdout))
+ } catch { resolve(null) }
+ })
+}
diff --git a/cli/src/engines/prepareNativeLaunch.spec.ts b/cli/src/engines/prepareNativeLaunch.spec.ts
index b69bf9785..70d09a068 100644
--- a/cli/src/engines/prepareNativeLaunch.spec.ts
+++ b/cli/src/engines/prepareNativeLaunch.spec.ts
@@ -1,14 +1,21 @@
-import { expect, it, vi } from 'vitest'
+import { spawn, type ChildProcess } from 'node:child_process'
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { engineDownloading } from './kit/downloadMarker.js'
import { createNativeLaunchPreparer } from './prepareNativeLaunch.js'
import type { NativeLaunch, NativeLaunchResult } from './nativeLaunch.js'
const absent: NativeLaunchResult = { ok: false, error: 'NATIVE_LAUNCH_HELD', unavailable: 'native', detail: 'Not installed',
install: { command: 'fixture-installer', source: 'fixture', executable: { names: ['fixture'] } }, environment: { HOME: '/fixture/home', PATH: '/fixture/bin' } }
const ready: NativeLaunchResult = { ok: true, launch: { current: () => true } as NativeLaunch }
+/** No Desktop download running. */
+const none = async () => false
it('installs under the saved request and requires a fresh post-install snapshot', async () => {
const ensure = vi.fn().mockResolvedValueOnce({ complete: false, detail: 'Installation in progress' }).mockResolvedValue({ complete: true })
const inspect = vi.fn().mockResolvedValueOnce(absent).mockResolvedValueOnce(absent).mockResolvedValue(ready)
- const prepare = createNativeLaunchPreparer({ installations: { ensure, status: vi.fn(async () => null) }, inspect })
+ const prepare = createNativeLaunchPreparer({ downloading: none, installations: { ensure, status: vi.fn(async () => null) }, inspect })
const authority = { id: 'fixture-request', current: () => true }
expect(await prepare('opencode', {}, authority)).toMatchObject({ ok: false, detail: 'Installation in progress' })
expect(await prepare('opencode', {}, authority)).toBe(ready)
@@ -18,7 +25,7 @@ it('installs under the saved request and requires a fresh post-install snapshot'
it('does not install on uncertain executable evidence and revokes every asynchronous continuation', async () => {
const ensure = vi.fn().mockResolvedValue({ complete: true })
const inspect = vi.fn().mockResolvedValue({ ok: false, error: 'NATIVE_LAUNCH_HELD', unavailable: 'native', detail: 'Unreadable executable' })
- const prepare = createNativeLaunchPreparer({ installations: { ensure, status: vi.fn(async () => null) }, inspect })
+ const prepare = createNativeLaunchPreparer({ downloading: none, installations: { ensure, status: vi.fn(async () => null) }, inspect })
let current = true
const authority = { id: 'fixture-request', current: () => current }
expect(await prepare('codex', {}, authority)).toMatchObject({ detail: 'Unreadable executable' })
@@ -44,7 +51,7 @@ it('does not mistake a newly visible executable for its still-running installer
const ensure = vi.fn(async () => ({ complete: false as const, detail: 'Installing' }))
const status = vi.fn().mockResolvedValueOnce({ complete: false, detail: 'Installer still unconfirmed' }).mockResolvedValue({ complete: true })
const inspect = vi.fn().mockResolvedValueOnce(absent).mockResolvedValue(ready)
- const prepare = createNativeLaunchPreparer({ installations: { ensure, status }, inspect })
+ const prepare = createNativeLaunchPreparer({ downloading: none, installations: { ensure, status }, inspect })
const authority = { id: 'fixture-original-request', current: () => true }
expect(await prepare('codex', {}, authority)).toMatchObject({ ok: false, detail: 'Installing' })
expect(await prepare('codex', {}, authority)).toMatchObject({ ok: false, detail: 'Installer still unconfirmed' })
@@ -56,7 +63,7 @@ it('does not mistake a newly visible executable for its still-running installer
it('holds an executable that cannot run while its installer is unsettled, and refuses it only after', async () => {
const broken: NativeLaunchResult = { ok: false, error: 'NATIVE_LAUNCH_HELD', unavailable: 'native', detail: 'Codex is installed but cannot run: fixture', refusal: 'ENGINE_CANNOT_RUN' }
const status = vi.fn().mockResolvedValueOnce({ complete: false, detail: 'Waiting for the saved installer to settle.' }).mockResolvedValue(null)
- const prepare = createNativeLaunchPreparer({ installations: { ensure: vi.fn(), status }, inspect: vi.fn(async () => broken) })
+ const prepare = createNativeLaunchPreparer({ downloading: none, installations: { ensure: vi.fn(), status }, inspect: vi.fn(async () => broken) })
const authority = { id: 'fixture-request', current: () => true }
expect(await prepare('codex', {}, authority)).toEqual({ ok: false, error: 'NATIVE_LAUNCH_HELD', unavailable: 'native', detail: 'Waiting for the saved installer to settle.' })
expect(await prepare('codex', {}, authority)).toBe(broken)
@@ -68,7 +75,7 @@ it('names the engine it is installing, and refuses a launch whose own installer
const status = vi.fn().mockResolvedValueOnce({ complete: false, running: true, detail: 'Waiting for the saved installer to settle.' })
.mockResolvedValueOnce({ complete: false, failed: true, detail: 'its installer exited with status 1' })
const inspect = vi.fn().mockResolvedValueOnce(absent).mockResolvedValueOnce(absent).mockResolvedValue(ready)
- const prepare = createNativeLaunchPreparer({ installations: { ensure, status }, inspect })
+ const prepare = createNativeLaunchPreparer({ downloading: none, installations: { ensure, status }, inspect })
const authority = { id: 'fixture-request', current: () => true }
const installing = { ok: false, error: 'NATIVE_LAUNCH_HELD', unavailable: 'native', installing: true,
detail: 'Installing Claude Code. The harness starts once it is installed.' }
@@ -79,3 +86,95 @@ it('names the engine it is installing, and refuses a launch whose own installer
expect(await prepare('claude', {}, authority)).toEqual(installing)
expect(await prepare('codex', {}, authority)).toMatchObject({ refusal: 'ENGINE_INSTALL_FAILED', detail: 'Codex could not be installed: its installer exited with status 1' })
})
+
+/**
+ * Desktop Harness downloading the engine as a fresh computer sets up (desktop/lib/bootstrap/agent_prefetch.dart),
+ * with real markers in a private home and real processes: the Desktop's npm named on its command line, one that
+ * took over a stale marker's pid, one that is gone. Never the person's own `~/.harness`.
+ */
+describe('while Desktop Harness downloads the engine', () => {
+ let home: string
+ const children: ChildProcess[] = []
+ beforeEach(() => { home = mkdtempSync(join(tmpdir(), 'prepare-download-')); mkdirSync(join(home, '.harness', 'run'), { recursive: true }) })
+ afterEach(() => { for (const child of children.splice(0)) child.kill('SIGKILL'); rmSync(home, { recursive: true, force: true }) })
+ /** A process that runs until the test ends, named as the Desktop names its download, or not. */
+ const running = async (...argv: string[]): Promise<number> => {
+ const child = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)', ...argv], { stdio: 'ignore' })
+ children.push(child)
+ await new Promise(done => child.once('spawn', done))
+ return child.pid!
+ }
+ const mark = (engine: string, pid: number) => writeFileSync(join(home, '.harness', 'run', `downloading-${engine}`), String(pid))
+ const gone = async (): Promise<number> => {
+ const child = spawn(process.execPath, ['-e', '', 'harness-download'], { stdio: 'ignore' })
+ await new Promise(done => child.once('exit', done))
+ return child.pid!
+ }
+ const prepare = (inspect: () => Promise<NativeLaunchResult>, ensure = vi.fn(async () => ({ complete: true as const }))) => ({
+ ensure,
+ prepare: createNativeLaunchPreparer({ installations: { ensure, status: vi.fn(async () => null) }, inspect: vi.fn(inspect),
+ downloading: engine => engineDownloading(engine, home) }),
+ })
+ const authority = { id: 'fixture-request', current: () => true }
+ const downloading = { ok: false, error: 'NATIVE_LAUNCH_HELD', unavailable: 'native', installing: true,
+ detail: 'Downloading Codex. The harness starts once it is downloaded.' }
+
+ it('holds a missing engine as an install while the download runs, and installs nothing beside it', async () => {
+ mark('codex', await running('harness-download'))
+ const { prepare: launch, ensure } = prepare(async () => absent)
+ expect(await launch('codex', {}, authority)).toEqual(downloading)
+ expect(ensure).not.toHaveBeenCalled()
+ })
+
+ it('holds an engine that fails its check while the download runs, rather than refusing what npm has written so far', async () => {
+ mark('claude', await running('harness-download'))
+ const broken: NativeLaunchResult = { ok: false, error: 'NATIVE_LAUNCH_HELD', unavailable: 'native',
+ detail: 'Claude Code is installed but cannot run: Error: Cannot find module', refusal: 'ENGINE_CANNOT_RUN' }
+ const { prepare: launch } = prepare(async () => broken)
+ expect(await launch('claude', {}, authority)).toEqual({ ...downloading, detail: 'Downloading Claude Code. The harness starts once it is downloaded.' })
+ // The download is another engine's: this one is refused as before.
+ expect(await launch('codex', {}, authority)).toBe(broken)
+ })
+
+ it('holds what a probe that began during the download says against it, even when the download has ended since', async () => {
+ // The probe started while npm was writing; npm finished and the Desktop removed its marker before it answered.
+ const broken: NativeLaunchResult = { ok: false, error: 'NATIVE_LAUNCH_HELD', unavailable: 'native',
+ detail: 'Codex is installed but cannot run: Error: Cannot find module', refusal: 'ENGINE_CANNOT_RUN' }
+ const marker = join(home, '.harness', 'run', 'downloading-codex')
+ mark('codex', await running('harness-download'))
+ const ensure = vi.fn(async () => ({ complete: true as const }))
+ for (const answer of [broken, absent]) {
+ const launch = createNativeLaunchPreparer({ installations: { ensure, status: vi.fn(async () => null) },
+ inspect: async () => { rmSync(marker); return answer }, downloading: engine => engineDownloading(engine, home) })
+ expect(await launch('codex', {}, authority)).toEqual(downloading)
+ mark('codex', await running('harness-download'))
+ }
+ expect(ensure).not.toHaveBeenCalled()
+ // A check that cannot answer is no download: as before.
+ const unanswered = createNativeLaunchPreparer({ installations: { ensure, status: vi.fn(async () => null) }, inspect: async () => broken,
+ downloading: async () => { throw Error('fixture') } })
+ expect(await unanswered('codex', {}, authority)).toBe(broken)
+ })
+
+ it('goes on as before for a marker whose process is gone or is not the download', async () => {
+ const { prepare: launch, ensure } = prepare(async () => absent)
+ mark('codex', await gone())
+ await launch('codex', {}, authority)
+ expect(ensure).toHaveBeenCalledOnce()
+ // A stale marker's pid taken over by another process.
+ mark('codex', await running('something-else'))
+ await launch('codex', {}, authority)
+ expect(ensure).toHaveBeenCalledTimes(2)
+ })
+
+ it.each([true, false])('neither holds nor installs for a request whose authority went while it looked (downloading: %s)', async (live) => {
+ mark('codex', live ? await running('harness-download') : await gone())
+ let current = true
+ const ensure = vi.fn()
+ const launch = createNativeLaunchPreparer({ installations: { ensure, status: vi.fn(async () => null) }, inspect: async () => absent,
+ downloading: async engine => { const answer = await engineDownloading(engine, home); current = false; return answer } })
+ expect(await launch('codex', {}, { id: 'fixture-request', current: () => current }))
+ .toEqual({ ok: false, error: 'NATIVE_LAUNCH_HELD', unavailable: 'native', detail: 'Waiting for the original launch request’s authority.' })
+ expect(ensure).not.toHaveBeenCalled()
+ })
+})
diff --git a/cli/src/engines/prepareNativeLaunch.ts b/cli/src/engines/prepareNativeLaunch.ts
index 73bacc2fc..8caba6b66 100644
--- a/cli/src/engines/prepareNativeLaunch.ts
+++ b/cli/src/engines/prepareNativeLaunch.ts
@@ -6,13 +6,16 @@ import type { AgentEngine } from './types.js'
/** Installation is its own durable effect. It never contains the agent argv or
* first prompt, and completing it still requires fresh executable evidence. */
-export function createNativeLaunchPreparer({ installations, inspect = inspectNativeLaunch }: {
+export function createNativeLaunchPreparer({ installations, inspect = inspectNativeLaunch, downloading }: {
installations: Pick<ReturnType<typeof createNativeInstallations>, 'ensure' | 'status'>
inspect?: typeof inspectNativeLaunch
+ /** Whether Desktop Harness is downloading the engine now (kit/downloadMarker.ts `engineDownloading`). */
+ downloading: (engine: AgentEngine) => Promise<boolean>
}) {
return async (engine: AgentEngine, source: NativeLaunchSource, authority: Pick<CreationAuthority, 'id' | 'current'>): Promise<NativeLaunchResult> => {
source = { ...source }
const held = (detail: string): Extract<NativeLaunchResult, { ok: false }> => ({ ok: false, error: 'NATIVE_LAUNCH_HELD', unavailable: 'native', detail })
+ const stale = () => held('Waiting for the original launch request’s authority.')
// What an unfinished installation means for this launch, in words a person waiting reads: an installer at work
// says which engine (`harness new` waits longer for it, lib/newCommand.ts); this request's own failed installer
// is a refusal with its reason, never a hold that says the launch continues (a fresh Ubuntu VM, 2026-10-12).
@@ -20,23 +23,41 @@ export function createNativeLaunchPreparer({ installations, inspect = inspectNat
installation.failed ? { ...held(`${engineName(engine)} could not be installed: ${installation.detail}`), refusal: 'ENGINE_INSTALL_FAILED' }
: installation.running ? { ...held(`Installing ${engineName(engine)}. The harness starts once it is installed.`), installing: true }
: held(installation.detail)
- if (!authority.current()) return held('Waiting for the original launch request’s authority.')
+ // Desktop Harness is downloading this engine on a fresh computer (kit/downloadMarker.ts): a missing engine, or one
+ // whose check fails, is that download not finished yet. Held as an install (`installing`, which `harness new` waits
+ // for as long) and tried again until the download ends, rather than installed beside it or refused for what it has
+ // written so far, which failed Desktop launches on brand-new Macs (6 to 25 on 2026-10-16). Asked as the look
+ // begins and again after it: a probe that began while the download was writing is no evidence against it, even
+ // when the download has ended by the time the probe answers (the next attempt looks again, afresh). A ready engine
+ // costs that one look at a marker that is not there.
+ const downloadHold = (): NativeLaunchResult => authority.current()
+ ? { ...held(`Downloading ${engineName(engine)}. The harness starts once it is downloaded.`), installing: true } : stale()
+ if (!authority.current()) return stale()
+ // Read before the look starts, not beside it: a look that began first could see the half-written engine while
+ // the marker was there and answer after the marker had gone, and the read beside it, still opening the file,
+ // saw no marker either (PR CI, #1394). No marker costs one failed open; a live one, its `ps`.
+ const before = await downloading(engine).catch(() => false)
+ const downloaded = async () => before || await downloading(engine).catch(() => false)
const found = await inspect(engine, source)
- if (!authority.current()) return held('Waiting for the original launch request’s authority.')
+ if (!authority.current()) return stale()
if (found.ok || found.refusal) {
// A helper can create the executable before finishing its other writes.
// Consult durable history on every ready path, including after a core crash.
// An executable that fails meanwhile may be one such half-written install:
// held while its installer is unsettled, refused only after.
const obligation = await installations.status(engine, authority.id, authority.current)
- if (!authority.current()) return held('Waiting for the original launch request’s authority.')
- return obligation && !obligation.complete ? unfinished(obligation) : found
+ if (!authority.current()) return stale()
+ if (obligation && !obligation.complete) return unfinished(obligation)
+ if (found.ok) return found
+ return await downloaded() ? downloadHold() : found
}
if (!found.install || !found.environment) return found
+ if (await downloaded()) return downloadHold()
+ if (!authority.current()) return stale()
const installed = await installations.ensure(engine, found.install, found.environment, authority.id, authority.current)
if (!installed.complete) return unfinished(installed)
- if (!authority.current()) return held('Waiting for the original launch request’s authority.')
+ if (!authority.current()) return stale()
const prepared = await inspect(engine, source)
- return authority.current() ? prepared : held('Waiting for the original launch request’s authority.')
+ return authority.current() ? prepared : stale()
}
}
diff --git a/cli/src/services/AGENTS.md b/cli/src/services/AGENTS.md
index 92af82042..37b5845ae 100644
--- a/cli/src/services/AGENTS.md
+++ b/cli/src/services/AGENTS.md
@@ -101,7 +101,8 @@ master too old to run it starts it beside itself, still in its own process (`src
with the master's token, reconnecting after core restarts. `<host>.crash` and `<host>.leak`, or a
service's own, crash or leak the whole process: it is one process.
- `src/core/serviceLinks.ts` is the core's side: it routes those requests to the process, answers
- `SERVICE_UNAVAILABLE` while it is down, and holds what the service must not miss.
+ `SERVICE_UNAVAILABLE` while it is down, and holds what the service must not miss. The Store's requests
+ (`waitsThroughRestart`) wait for its process to come back instead, bounded as a first start's wait is.
- `src/services/searchProcess.ts` is the example to copy. `e2e/serviceProcesses.e2e.ts` is the proof
to copy: killed, hung (SIGSTOP), leaking, crashing on every start.
- A port the core calls asynchronously, answered when it is read, can be a request to the process: the
diff --git a/docs/design/2026-10-03-harnessd.md b/docs/design/2026-10-03-harnessd.md
index 119f0b6da..f60163ad1 100644
--- a/docs/design/2026-10-03-harnessd.md
+++ b/docs/design/2026-10-03-harnessd.md
@@ -624,8 +624,9 @@ Done so far:
times in ten minutes, trying it again after thirty. A service reaches the core through its local
socket under a service role, with a token the master gives both on every boot
(`cli/src/core/serviceLinks.ts`, `cli/src/services/process.ts`). The core routes the service's
- requests to it and answers `SERVICE_UNAVAILABLE` at once while it is down, holds what it must hear
- (a purge's forgetting) until it is back, and never waits on it. Search is the first:
+ requests to it and answers `SERVICE_UNAVAILABLE` at once while it is down (the Store's requests wait for
+ its process to come back instead, as long as a start: 2026-10-17), holds what it must hear (a purge's
+ forgetting) until it is back, and never waits on it in line. Search is the first:
`cli/src/services/searchProcess.ts` runs the same index on a core API built in its own process.
`e2e/serviceProcesses.e2e.ts` proves on the real daemon that search killed, hung (stopped), leaking
or crashing on every start costs search alone: the core never restarts and agents keep working.