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
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.ymlindex 329a8d2ce..a747a2439 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -351,6 +351,37 @@ jobs:- name: Require complete harnessd and core coveragerun: 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.tsindex 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', avi.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 = nullif (mode === 'cwd') row.cwd = nulldiff --git a/cli/src/lib/resumeAgentService.spec.ts b/cli/src/lib/resumeAgentService.spec.tsindex 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.tsindex 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 > 0console.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.tsindex 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.tsindex 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 beforexpect(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.tsindex 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.mdindex 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 nativeCLI 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.pyindex 7f44aca23..b3e6ff70d 100644--- a/scripts/record-ci-validation.py+++ b/scripts/record-ci-validation.py@@ -18,7 +18,7 @@ import sysimport timeimport 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)"}