Skip to content

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

The resume, orchestrator, sharing, remote-viewer and portability coverage gates run in CI, at 100%. (#853)

Dee3121dc6c94ed
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 329a8d2ce..a747a2439 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -351,6 +351,37 @@ jobs:
- name: Require complete harnessd and core coverage
run: npm run test:harnessd && npm run test:core
+ # The other per-file 100% coverage gates in cli/package.json, beside cli-contracts' harnessd and core
+ # ones, on a runner of their own so the CI run takes no longer. They used to run only when somebody
+ # remembered: test:resume had slipped to 93% of stoppedAgents.ts and test:orchestrator below 100% by
+ # 5 October 2026 without anyone noticing. One step per gate, so a red run names the gate.
+ # test:local-models is not here yet: it is at 95% of localModels.ts and needs its own tests first.
+ cli-coverage-gates:
+ if: ${{ contains(fromJSON('["full","cli"]'), inputs.scope || 'full') }}
+ runs-on: ubuntu-latest
+ timeout-minutes: 15
+ defaults:
+ run:
+ working-directory: cli
+ steps:
+ - uses: actions/checkout@v7
+ - uses: actions/setup-node@v7
+ with:
+ node-version: ${{ env.CLI_NODE_VERSION }}
+ cache: npm
+ cache-dependency-path: cli/package-lock.json
+ - run: npm ci --no-audit --no-fund
+ - name: Stopped harnesses, stop and resume
+ run: npm run test:resume
+ - name: Orchestrator
+ run: npm run test:orchestrator
+ - name: Sharing
+ run: npm run test:sharing
+ - name: Remote viewers
+ run: npm run test:remote-viewers
+ - name: Harness portability
+ run: npm run test:portability
+
cli-tests:
if: ${{ contains(fromJSON('["full","cli"]'), inputs.scope || 'full') }}
strategy:
diff --git a/cli/src/lib/captureResumeIdentity.spec.ts b/cli/src/lib/captureResumeIdentity.spec.ts
index 000382890..ff0c60941 100644
--- a/cli/src/lib/captureResumeIdentity.spec.ts
+++ b/cli/src/lib/captureResumeIdentity.spec.ts
@@ -58,6 +58,16 @@ it('looks up a preallocated Pi session ID in its own project before stopping', a
vi.mocked(findResumedTranscript).mockResolvedValue('/first-reply.jsonl')
expect(await captureResumeIdentity(row)).toMatchObject({ sessionId: 'preallocated', transcriptPath: '/first-reply.jsonl' })
})
+// Pi keeps its sessions by project folder, and a row restored from an older record can have lost its
+// folder. The lookup is asked with no folder rather than a null one, and its refusal ("the Pi conversation
+// location is unavailable", sessionRepair) reaches the caller: Stop is then refused (stopAgentService),
+// rather than killing an engine whose conversation could never be found again.
+it('passes on the lookup\'s refusal for a Pi session whose project folder was not recorded', async () => {
+ Object.assign(row, { engine: 'pi', sessionId: 'preallocated', transcriptPath: null, cwd: null })
+ vi.mocked(findResumedTranscript).mockRejectedValue(new Error('The Pi conversation location is unavailable.'))
+ await expect(captureResumeIdentity(row)).rejects.toThrow('The Pi conversation location is unavailable.')
+ expect(findResumedTranscript).toHaveBeenCalledWith('pi', 'preallocated', { codexHome: undefined, cwd: undefined })
+})
it.each(['identity', 'cwd', 'unknown', 'gone', 'pid', 'executable', 'start'])('refuses missing or changed process evidence: %s', async mode => {
if (mode === 'identity') row.processIdentity = null
if (mode === 'cwd') row.cwd = null
diff --git a/cli/src/lib/resumeAgentService.spec.ts b/cli/src/lib/resumeAgentService.spec.ts
index 6683f4401..84851e0ca 100644
--- a/cli/src/lib/resumeAgentService.spec.ts
+++ b/cli/src/lib/resumeAgentService.spec.ts
@@ -11,7 +11,7 @@ import { AgentRestartCoordinator } from './restartAgent.js'
import { checkPidRuntime } from './deleteAgentFallback.js'
import { listTmuxPanes } from './tmuxAgentDiscovery.js'
import { checkSessionRuntime, clearPaneRemainOnExit, resolvePaneEngineProcess, tmuxPaneState } from './tmux.js'
-import { buildEngineLaunchArgv, refusePermissionFlagIfUnsupported } from './engineLaunch.js'
+import { buildEngineLaunchArgv, dropPermissionFlagIfUnsupported, refusePermissionFlagIfUnsupported } from './engineLaunch.js'
import { enginePathOverride } from './engineBin.js'
import { installedDsh } from '../dsh/installed.js'
@@ -450,3 +450,56 @@ describe('existing runtime and readiness verification', () => {
expect(deps.retainExitedSession).toHaveBeenCalledWith(expect.objectContaining({ agentId: saved.agentId }), kept)
})
})
+
+describe('resume edges the desk sees', () => {
+ // The probe proves a new process, and the row must record it before anyone is told the harness is up:
+ // an engine that is "ready" with no recorded process cannot be attached to or stopped.
+ it('does not confirm a resume off a process the registry cannot record, and keeps its reservation', async () => {
+ vi.mocked(resolvePaneEngineProcess).mockResolvedValue({ ...identity, pid: 0 })
+ expect(await start()).toMatchObject({ ok: false, error: 'AGENT_CHANGED' })
+ expect(registry.byAgent(saved.agentId)?.launch?.state).not.toBe('ready')
+ expect(deps.stoppedAgents.beginResume(saved.agentId)).toBeNull()
+ })
+
+ // A verdict another path set on the row (a hook's mismatch guard) is reported as itself, and said in the
+ // log as it is, with no "undefined" where a reason would be.
+ it('reports a failure the row was given elsewhere, without a reason, as itself', async () => {
+ const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+ vi.mocked(resolvePaneEngineProcess).mockImplementation(async () => {
+ registry.setLaunch(saved.agentId, { state: 'failed', error: 'RESUME_MISMATCH' } as never)
+ return null
+ })
+ const result = await start()
+ expect(result).toMatchObject({ ok: false, error: 'RESUME_MISMATCH' })
+ expect(registry.byAgent(saved.agentId)?.launch).toMatchObject({ state: 'failed', error: 'RESUME_MISMATCH' })
+ const said = log.mock.calls.map(([line]) => String(line)).find((line) => line.startsWith('[resume]') && line.includes('RESUME_MISMATCH'))
+ expect(said).toBe(`[resume] ${saved.agentId.slice(0, 8)} RESUME_MISMATCH · engine=codex`)
+ })
+
+ // Asking the engine whether it takes the chosen permission flag can take a while (its --help); a Stop
+ // or another Open in that time wins, and this one allocates nothing.
+ it('allocates nothing when the harness changes while the engine is asked about the permission flag', async () => {
+ vi.mocked(refusePermissionFlagIfUnsupported).mockImplementation(async () => { deps.restartJobs.cancel(saved.agentId); return null })
+ expect(await createResumeAgentService(deps)(saved.agentId, 'ask')).toMatchObject({ ok: false, error: 'AGENT_CHANGED' })
+ expect(create).not.toHaveBeenCalled()
+ })
+
+ // An engine downgraded since the pause no longer takes the saved permission flag (openharness#285): the
+ // harness still comes back, in Ask, and the log says how to get the saved mode back.
+ it.each([
+ ['plan', false, 'plan'],
+ [undefined, true, 'Auto'],
+ ] as const)('resumes in Ask when the engine no longer takes the saved %s flag, and says how to get it back', async (mode, bypass, named) => {
+ rewrite({ permissionMode: mode, bypassPermission: bypass })
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+ vi.mocked(dropPermissionFlagIfUnsupported).mockResolvedValueOnce({
+ choice: { permissionMode: null, bypassPermission: false }, droppedFlag: '--permission-mode',
+ })
+ expect(await start()).toMatchObject({ ok: true, resumed: true })
+ expect(buildEngineLaunchArgv).toHaveBeenCalledWith('codex', expect.objectContaining({ bypassPermission: false }))
+ expect(vi.mocked(buildEngineLaunchArgv).mock.calls[0][1]).not.toHaveProperty('permissionMode')
+ expect(warn).toHaveBeenCalledWith(`[resume] ${saved.agentId.slice(0, 8)} · codex does not take --permission-mode`
+ + ` · resuming in Ask · update codex to get ${named} back`)
+ })
+})
+
diff --git a/cli/src/lib/resumeAgentService.ts b/cli/src/lib/resumeAgentService.ts
index d9112d177..fac74e53c 100644
--- a/cli/src/lib/resumeAgentService.ts
+++ b/cli/src/lib/resumeAgentService.ts
@@ -101,11 +101,12 @@ export function createResumeAgentService(deps: ResumeAgentServiceDeps) {
// else coming. A row left `starting` reads as "Starting" for ever, is made dormant without
// being retained by discovery's `onExited`, and is refused by the desk's own resume receipt —
// asking WHICH proof confirmed it got that wrong in both directions, so ask the row instead.
- const confirmed = registry.byAgent(saved.agentId)
- const ready = confirmed?.launch?.state === 'ready'
+ // `ownsRoute()` read this row just above, and nothing since has yielded: it is still registered.
+ const confirmed = registry.byAgent(saved.agentId)!
+ const ready = confirmed.launch?.state === 'ready'
? confirmed
- : registry.setLaunch(saved.agentId, { state: 'ready' }) ?? result.session
- const hooked = (confirmed?.lastHookAt ?? 0) > 0
+ : registry.setLaunch(saved.agentId, { state: 'ready' })!
+ const hooked = confirmed.lastHookAt > 0
console.log(`[resume] ${sid(saved.agentId)} confirmed · engine=${saved.engine}`
+ ` · hook=${hooked ? 'yes' : 'no'} · ${result.resumed ? 'same conversation' : 'fresh'}`)
announceSession(ready)
diff --git a/cli/src/lib/resumeStoppedAgent.spec.ts b/cli/src/lib/resumeStoppedAgent.spec.ts
index 1b3a9b675..8202072b0 100644
--- a/cli/src/lib/resumeStoppedAgent.spec.ts
+++ b/cli/src/lib/resumeStoppedAgent.spec.ts
@@ -89,6 +89,17 @@ describe('Enter resumes stopped work', () => {
describe('resume runtime verification', () => {
+ // Another client stopped or deleted the live harness while this one checked its runtime: the row this
+ // request was about is gone, and nothing it learned about it may be acted on.
+ it('reports the harness changed when its live row is gone after the runtime check, and acts on nothing', async () => {
+ const deps = fixture()
+ deps.live.mockReturnValue(saved)
+ deps.checkLive.mockImplementation(async () => { deps.live.mockReturnValue(undefined); return { state: 'gone', reason: 'fixture' } })
+ await expect(resumeStoppedAgent(deps)).resolves.toMatchObject({ ok: false, error: 'AGENT_CHANGED' })
+ expect(deps.retain).not.toHaveBeenCalled()
+ expect(deps.launch).not.toHaveBeenCalled()
+ })
+
it.each(['unknown', 'gone'] as const)('never calls a %s registry row a successful attachment', async state => {
const deps = fixture()
deps.live.mockReturnValue(saved)
diff --git a/cli/src/lib/stoppedAgents.spec.ts b/cli/src/lib/stoppedAgents.spec.ts
index 270695bfc..0c0802b53 100644
--- a/cli/src/lib/stoppedAgents.spec.ts
+++ b/cli/src/lib/stoppedAgents.spec.ts
@@ -435,3 +435,53 @@ it('lists the id of every saved record, unreadable ones included, and none befor
expect(store.ids().sort()).toEqual([saved.agentId, 'broken'].sort())
expect(store.list().map((s) => s.agentId)).toEqual([saved.agentId])
})
+
+// The handoff asks whether any stopped record holds a conversation (handoffDiscovery `ownedByOther`) and
+// fails closed when it cannot tell. An unreadable folder answered "no records" would let a handoff bind a
+// conversation a stopped harness still owns.
+it('says it cannot list the records when the folder cannot be read, never that there are none', async () => {
+ const { saved, store } = await fixture()
+ store.save(saved)
+ chmodSync(join(directory, 'stopped-agents'), 0o000)
+ try {
+ // Root reads through any mode: there is no unreadable folder to show.
+ if (process.getuid?.() !== 0) expect(() => store.ids()).toThrow(expect.objectContaining({ code: 'EACCES' }))
+ } finally { chmodSync(join(directory, 'stopped-agents'), 0o700) }
+ // A file where the folder should be is not "none yet" either.
+ const elsewhere = new (await import('./stoppedAgents.js')).StoppedAgentStore(join(directory, 'stopped-agents', `${saved.agentId}.json`))
+ expect(() => elsewhere.ids()).toThrow(expect.objectContaining({ code: 'ENOTDIR' }))
+})
+
+// Purging a stopped harness's saved session (purgeAgentService) is the one permanent deletion: Stop keeps
+// the record, this removes it.
+it('permanently deletes a stopped record, at once for every reader, and refuses an identity that is not one', async () => {
+ const { saved, StoppedAgentStore, store } = await fixture()
+ store.save(saved)
+ store.save({ ...saved, agentId: 'kept' })
+ // Warm the catalog, as a status snapshot does: the deletion must not be served from it afterwards.
+ expect(store.list().map((row) => row.agentId).sort()).toEqual([saved.agentId, 'kept'].sort())
+ store.remove(saved.agentId)
+ expect(store.get(saved.agentId)).toBeNull()
+ expect(store.list().map((row) => row.agentId)).toEqual(['kept'])
+ expect(store.ids()).toEqual(['kept'])
+ expect(new StoppedAgentStore(join(directory, 'stopped-agents')).get(saved.agentId)).toBeNull()
+ // Removing it again, or one never saved, is nothing to do; a path is never an identity.
+ expect(() => store.remove(saved.agentId)).not.toThrow()
+ expect(() => store.remove('never-saved')).not.toThrow()
+ expect(() => store.remove('../kept')).toThrow('Invalid stopped harness identity.')
+ expect(store.get('kept')?.agentId).toBe('kept')
+})
+
+// Only a harness identity names a record: a name in the folder that is not one is never read as a saved
+// harness, and an identity that is a path never reaches outside the folder.
+it('lists only files named by a harness identity, and never looks outside its folder for a reservation', async () => {
+ const { saved, store } = await fixture()
+ store.save(saved)
+ const base = join(directory, 'stopped-agents')
+ writeFileSync(join(base, 'not an id.json'), JSON.stringify({ version: 1, session: { ...saved, agentId: 'not an id' } }), { mode: 0o600 })
+ expect(store.list().map((row) => row.agentId)).toEqual([saved.agentId])
+ // A reservation beside the folder, where `../escape` would point.
+ writeFileSync(join(directory, 'escape.resume'), '{}', { mode: 0o600 })
+ expect(store.resumeReservedAt('../escape')).toBeNull()
+ expect(store.resumeReservedAt(saved.agentId)).toBeNull()
+})
diff --git a/cli/src/orchestrator/service.spec.ts b/cli/src/orchestrator/service.spec.ts
index 60b9e331a..6aeec2a99 100644
--- a/cli/src/orchestrator/service.spec.ts
+++ b/cli/src/orchestrator/service.spec.ts
@@ -4,7 +4,7 @@ import { tmpdir } from 'node:os'
import { join } from 'node:path'
import * as filesystem from 'node:fs/promises'
import * as privateState from '../lib/secureState.js'
-import { OrchestratorService, type OrchestratorDependencies } from './service.js'
+import { OrchestratorService, hasSavedProjects, type OrchestratorDependencies } from './service.js'
import { OrchestratorError, type Task } from './model.js'
import { orchestratorRequest } from './wire.js'
@@ -501,3 +501,28 @@ describe('durable orchestrator lifecycle', () => {
expect(service.snapshot(id).state).toBe('completed')
}, 30_000)
})
+
+// The daemon asks a project's role of every turn that ends (backendSocket), and asks this first so that a
+// machine that never used the orchestrator never builds the service, its folder or its reads.
+describe('whether a machine has a saved project, asked without building the service', () => {
+ it('answers from the folder alone: none without a saved run, one with a run file, and one when it cannot tell', () => {
+ const root = realpathSync(mkdtempSync(join(tmpdir(), 'orchestrator-saved-')))
+ try {
+ const folder = join(root, 'orchestrator')
+ expect(hasSavedProjects(folder)).toBe(false)
+ mkdirSync(folder)
+ expect(hasSavedProjects(folder)).toBe(false)
+ // Files that are not a run's `<32 hex>.json` are not a project.
+ writeFileSync(join(folder, 'notes.json'), '{}')
+ writeFileSync(join(folder, `${'a'.repeat(32)}.json.tmp`), '{}')
+ expect(hasSavedProjects(folder)).toBe(false)
+ writeFileSync(join(folder, `${'0123456789abcdef'.repeat(2)}.json`), '{}')
+ expect(hasSavedProjects(folder)).toBe(true)
+ // A folder that cannot be listed counts as one, so the service is built and reports it.
+ const file = join(root, 'not-a-folder')
+ writeFileSync(file, '')
+ expect(hasSavedProjects(file)).toBe(true)
+ } finally { rmSync(root, { recursive: true, force: true }) }
+ })
+})
+
diff --git a/docs/validation-and-release.md b/docs/validation-and-release.md
index a2f103587..faf2aafb6 100644
--- a/docs/validation-and-release.md
+++ b/docs/validation-and-release.md
@@ -27,7 +27,9 @@ two commands each spawning every CPU is not useful parallelism.
Manual **CI → Run workflow** accepts `scope`: `cli`, `tui`, `backend`, `desktop`, or `full`
(the default). `cli` includes typecheck, all CLI tests, updater coverage, release
-bundle checks, and the serial/login-shell OS/Node matrix. `tui` includes its native
+bundle checks, the serial/login-shell OS/Node matrix, and the per-file 100% coverage
+gates (`test:core`, `test:harnessd`, `test:resume`, `test:orchestrator`, `test:sharing`,
+`test:remote-viewers`, `test:portability`). `tui` includes its native
CLI integration tests. Select `full` for cross-component changes or uncertain impact.
The workflow remains on demand; this change does not introduce new required gates.
diff --git a/scripts/record-ci-validation.py b/scripts/record-ci-validation.py
index 7f44aca23..b3e6ff70d 100644
--- a/scripts/record-ci-validation.py
+++ b/scripts/record-ci-validation.py
@@ -18,7 +18,7 @@ import sys
import time
import zipfile
-CLI_JOBS = {"cli-contracts", "typecheck-test"} | {f"cli-tests ({i})" for i in range(1, 5)} | {
+CLI_JOBS = {"cli-contracts", "cli-coverage-gates", "typecheck-test"} | {f"cli-tests ({i})" for i in range(1, 5)} | {
f"serial-native ({system}, {node})" for system in ["ubuntu-latest", "macos-latest"] for node in ["20.19.0", "22.23.2"]
} | {f"process-images-native ({system})" for system in ["macos-15", "macos-15-intel"]}
TUI_JOBS = {"tui-test (ubuntu-latest, x86_64-unknown-linux-musl)", "tui-test (ubuntu-24.04-arm, aarch64-unknown-linux-musl)"}