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
import { describe, expect, it, vi } from 'vitest'
import { AgentRestartCoordinator, bypassPermissionFor, restartAgent, type RestartAgentDeps } from './restartAgent.js'
import type { ProcessIdentity } from './registry.js'
const IDENTITY: ProcessIdentity = { pid: 555, executable: 'claude', startMarker: 'Mon Aug 3 09:05:00 2026' }
interface Overrides {
holdOpen?: RestartAgentDeps['holdOpen']
terminate?: RestartAgentDeps['terminate']
respawn?: RestartAgentDeps['respawn']
waitForProcess?: RestartAgentDeps['waitForProcess']
buildArgv?: RestartAgentDeps['buildArgv']
prepareResume?: RestartAgentDeps['prepareResume']
stopConflictingJob?: RestartAgentDeps['stopConflictingJob']
}
/** Every primitive records its own call, even when overridden — so `calls` always reflects the real
* order regardless of which primitive a test customizes the return value of. */
function deps(over: Overrides = {}): RestartAgentDeps & { calls: string[] } {
const calls: string[] = []
const holdOpenImpl = over.holdOpen ?? (async () => ({ ok: true }))
const terminateImpl = over.terminate ?? (async () => 'terminated' as const)
const respawnImpl = over.respawn ?? (async () => ({ ok: true }))
const waitForProcessImpl = over.waitForProcess ?? (async () => IDENTITY)
const buildArgvImpl = over.buildArgv ?? (() => ['claude'])
return {
calls,
...(over.prepareResume ? { prepareResume: async () => { calls.push('prepareResume'); await over.prepareResume!() } } : {}),
...(over.stopConflictingJob ? { stopConflictingJob: async () => { calls.push('stopConflictingJob'); await over.stopConflictingJob!() } } : {}),
holdOpen: async () => { calls.push('holdOpen'); return holdOpenImpl() },
terminate: async (checkAfterMs) => { calls.push('terminate'); return terminateImpl(checkAfterMs) },
respawn: async (argv) => { calls.push('respawn'); return respawnImpl(argv) },
waitForProcess: async () => { calls.push('waitForProcess'); return waitForProcessImpl() },
buildArgv: (opts) => { calls.push('buildArgv'); return buildArgvImpl(opts) },
log: () => {},
keepAbandoned: () => { calls.push('keepAbandoned') },
}
}
describe('restartAgent', () => {
it('prepares history after its writer stops and before the resume launch', async () => {
const d = deps({ prepareResume: vi.fn() })
await restartAgent({ engine: 'codex', sessionId: 's1' }, false, d)
expect(d.calls).toEqual(['holdOpen', 'terminate', 'prepareResume', 'buildArgv', 'respawn', 'waitForProcess'])
})
it('resumes the prepared fork of a moved conversation, once its writer has stopped', async () => {
const seen: unknown[] = []
const d = deps({ buildArgv: (opts) => { seen.push(opts); return ['codex'] } })
const prepareFork = vi.fn(async () => { seen.push(d.calls.includes('terminate')); return 'prepared' })
const outcome = await restartAgent({ engine: 'codex', sessionId: 's1', continueInFork: true }, false, { ...d, prepareFork })
expect(outcome.ok).toBe(true)
expect(seen).toEqual([true, { bypassPermission: false, resumeSessionId: 'prepared' }])
})
it('continues the moved conversation in a plain fork when preparing it fails', async () => {
const seen: unknown[] = []
const logs: string[] = []
const d = deps({ buildArgv: (opts) => { seen.push(opts); return ['codex'] } })
const outcome = await restartAgent({ engine: 'codex', sessionId: 's1', continueInFork: true }, false,
{ ...d, log: (message) => logs.push(message), prepareFork: async () => { throw new Error('grid is down') } })
expect(outcome.ok).toBe(true)
expect(seen.at(-1)).toEqual({ bypassPermission: false, forkSessionId: 's1' })
expect(logs.join()).toContain('grid is down')
})
it('never prepares history while the old writer may still be alive', async () => {
const prepareResume = vi.fn()
const d = deps({ terminate: async () => 'failed', prepareResume })
await restartAgent({ engine: 'codex', sessionId: 's1' }, false, d)
expect(prepareResume).not.toHaveBeenCalled()
})
it('does not fall back to a fresh conversation if preparing history fails', async () => {
const d = deps({ prepareResume: () => { throw new Error('rollout changed') } })
const outcome = await restartAgent({ engine: 'codex', sessionId: 's1' }, false, d)
expect(outcome).toEqual({ ok: false, detail: 'could not prepare codex session for resume: rollout changed' })
expect(d.calls).toEqual(['holdOpen', 'terminate', 'prepareResume'])
})
it('stops a conflicting background job after history preparation and before the resume argv is built', async () => {
const stopConflictingJob = vi.fn()
const d = deps({ stopConflictingJob })
await restartAgent({ engine: 'claude', sessionId: 's1' }, false, d)
expect(d.calls).toEqual(['holdOpen', 'terminate', 'stopConflictingJob', 'buildArgv', 'respawn', 'waitForProcess'])
expect(stopConflictingJob).toHaveBeenCalledTimes(1)
})
it('never checks for a background job on a fresh launch (no session id to resume)', async () => {
const stopConflictingJob = vi.fn()
const d = deps({ stopConflictingJob, waitForProcess: async () => null })
await restartAgent({ engine: 'claude', sessionId: '' }, false, d)
expect(stopConflictingJob).not.toHaveBeenCalled()
})
it('does nothing extra for an engine with no background-job check wired (the dep is simply absent)', async () => {
const d = deps()
expect(d.stopConflictingJob).toBeUndefined()
const outcome = await restartAgent({ engine: 'codex', sessionId: 's1' }, false, d)
expect(outcome.ok).toBe(true)
expect(d.calls).toEqual(['holdOpen', 'terminate', 'buildArgv', 'respawn', 'waitForProcess'])
})
it('does not prepare a fresh launch or repeat preparation on the fresh fallback', async () => {
const prepareResume = vi.fn()
const d = deps({ prepareResume, waitForProcess: async () => null })
await restartAgent({ engine: 'codex', sessionId: '' }, false, d)
expect(prepareResume).not.toHaveBeenCalled()
await restartAgent({ engine: 'codex', sessionId: 's1' }, false, d)
expect(prepareResume).toHaveBeenCalledTimes(1)
})
it('holds the pane open, kills, respawns, and verifies — in that order', async () => {
const d = deps()
const outcome = await restartAgent({ engine: 'claude', sessionId: 's1' }, false, d)
expect(outcome).toEqual({ ok: true, processIdentity: IDENTITY, resumed: true })
expect(d.calls).toEqual(['holdOpen', 'terminate', 'buildArgv', 'respawn', 'waitForProcess'])
})
it('stops nothing when the respawn would be refused, as on a tmux too old for the relaunch\'s environment', async () => {
const d = { ...deps(), respawnRefusal: async () => 'this machine\'s tmux is older than 3.0, the first version that can give a respawned pane its own environment. Upgrade tmux.' }
const outcome = await restartAgent({ engine: 'codex', sessionId: 's1' }, false, d)
expect(outcome).toEqual({ ok: false, detail: 'this machine\'s tmux is older than 3.0, the first version that can give a respawned pane its own environment. Upgrade tmux. Nothing was stopped.' })
expect(d.calls).toEqual([])
// Asked, and not refused: the restart goes on as before.
const allowed = { ...deps(), respawnRefusal: async () => null }
expect(await restartAgent({ engine: 'codex', sessionId: 's1' }, false, allowed)).toMatchObject({ ok: true })
expect(allowed.calls).toEqual(['holdOpen', 'terminate', 'buildArgv', 'respawn', 'waitForProcess'])
})
it('stops nothing when the relaunch is refused on this platform, and asks with the resume it would launch', async () => {
const asked: unknown[] = []
const d = { ...deps(), launchRefusal: (opts: unknown) => { asked.push(opts); return 'Harness cannot start codex on Windows with these arguments.' } }
expect(await restartAgent({ engine: 'codex', sessionId: 's1' }, true, d)).toEqual({
ok: false, error: 'ENGINE_LAUNCH_REFUSED', detail: 'Harness cannot start codex on Windows with these arguments. Nothing was stopped.',
})
expect(d.calls).toEqual([])
expect(asked).toEqual([{ bypassPermission: true, resumeSessionId: 's1' }])
const fresh = { ...deps(), launchRefusal: (opts: unknown) => { asked.push(opts); return null } }
expect(await restartAgent({ engine: 'codex', sessionId: '' }, false, fresh)).toMatchObject({ ok: true })
expect(asked.at(-1)).toEqual({ bypassPermission: false })
})
it('never respawns when holdOpen fails to re-arm the pane', async () => {
const d = deps({ holdOpen: async () => ({ ok: false, reason: 'tmux unreachable' }) })
const outcome = await restartAgent({ engine: 'claude', sessionId: 's1' }, false, d)
expect(outcome).toEqual({ ok: false, detail: 'tmux unreachable' })
expect(d.calls).toEqual(['holdOpen'])
})
it('never respawns over a kill that could not be confirmed (not-ours)', async () => {
const d = deps({ terminate: async () => 'not-ours' })
const outcome = await restartAgent({ engine: 'claude', sessionId: 's1' }, false, d)
expect(outcome.ok).toBe(false)
expect(d.calls).toEqual(['holdOpen', 'terminate'])
})
it('never respawns over a kill that failed', async () => {
const d = deps({ terminate: async () => 'failed' })
const outcome = await restartAgent({ engine: 'claude', sessionId: 's1' }, false, d)
expect(outcome.ok).toBe(false)
expect(d.calls).toEqual(['holdOpen', 'terminate'])
})
it.each([new Error('The conversation is still held on its server'), 'server unavailable'])('reports a refused native stop without respawning or falling back: %s', async error => {
const d = deps({ terminate: async () => { throw error } })
const outcome = await restartAgent({ engine: 'codex', sessionId: 's1' }, false, d)
expect(outcome).toEqual({ ok: false, detail: `could not stop the running codex session: ${error instanceof Error ? error.message : error}` })
expect(d.calls).toEqual(['holdOpen', 'terminate'])
})
it('treats "gone" (the process had already exited) as a confirmed kill, safe to respawn over', async () => {
const d = deps({ terminate: async () => 'gone' })
const outcome = await restartAgent({ engine: 'claude', sessionId: 's1' }, false, d)
expect(outcome.ok).toBe(true)
})
it('passes the resolved sessionId as resumeSessionId on the first attempt', async () => {
const argvCalls: Array<{ bypassPermission: boolean; resumeSessionId?: string }> = []
const d = deps({ buildArgv: (opts) => { argvCalls.push(opts); return ['claude'] } })
await restartAgent({ engine: 'claude', sessionId: 'sess-42' }, true, d)
expect(argvCalls).toEqual([{ bypassPermission: true, resumeSessionId: 'sess-42' }])
// It reopened the conversation: nothing was left behind.
expect(d.calls).not.toContain('keepAbandoned')
})
it('continues in a fork of the conversation when asked to, with its history prepared, and leaves nothing behind', async () => {
const argvCalls: Array<{ bypassPermission: boolean; resumeSessionId?: string; forkSessionId?: string }> = []
const d = deps({ buildArgv: (opts) => { argvCalls.push(opts); return ['codex'] }, prepareResume: () => {} })
const outcome = await restartAgent({ engine: 'codex', sessionId: 'sess-42', continueInFork: true }, false, d)
expect(argvCalls).toEqual([{ bypassPermission: false, forkSessionId: 'sess-42' }])
expect(outcome).toEqual({ ok: true, processIdentity: IDENTITY, resumed: true })
expect(d.calls).toContain('prepareResume')
// The fork carries the whole conversation: no stopped harness is kept for the one it came from.
expect(d.calls).not.toContain('keepAbandoned')
})
it('asks whether the fork it would launch is refused, before anything is stopped', async () => {
const asked: Array<{ bypassPermission: boolean; resumeSessionId?: string; forkSessionId?: string }> = []
const d = { ...deps(), launchRefusal: (opts: { bypassPermission: boolean; resumeSessionId?: string; forkSessionId?: string }) => { asked.push(opts); return null } }
await restartAgent({ engine: 'codex', sessionId: 'sess-42', continueInFork: true }, false, d)
expect(asked).toEqual([{ bypassPermission: false, forkSessionId: 'sess-42' }])
})
it('falls back to a fresh relaunch when the fork never comes up, keeping the conversation it could not continue', async () => {
let attempt = 0
const argvCalls: Array<{ bypassPermission: boolean; resumeSessionId?: string; forkSessionId?: string }> = []
const d = deps({
buildArgv: (opts) => { argvCalls.push(opts); return ['codex'] },
waitForProcess: async () => { attempt += 1; return attempt === 1 ? null : IDENTITY },
})
const outcome = await restartAgent({ engine: 'codex', sessionId: 'sess-42', continueInFork: true }, false, d)
expect(argvCalls).toEqual([{ bypassPermission: false, forkSessionId: 'sess-42' }, { bypassPermission: false }])
expect(outcome).toEqual({ ok: true, processIdentity: IDENTITY, resumed: false })
expect(d.calls.at(-1)).toBe('keepAbandoned')
})
it('launches fresh (no resumeSessionId) when the session has none', async () => {
const argvCalls: Array<{ bypassPermission: boolean; resumeSessionId?: string }> = []
const d = deps({ buildArgv: (opts) => { argvCalls.push(opts); return ['claude'] } })
const outcome = await restartAgent({ engine: 'claude', sessionId: '' }, false, d)
expect(argvCalls).toEqual([{ bypassPermission: false }])
expect(outcome).toMatchObject({ ok: true, resumed: false })
})
it('falls back to a fresh relaunch when the resumed relaunch never produces a recognizable process', async () => {
let attempt = 0
const argvCalls: Array<{ bypassPermission: boolean; resumeSessionId?: string }> = []
const d = deps({
buildArgv: (opts) => { argvCalls.push(opts); return ['claude'] },
waitForProcess: async () => { attempt += 1; return attempt === 1 ? null : IDENTITY },
})
const outcome = await restartAgent({ engine: 'claude', sessionId: 'sess-42' }, false, d)
expect(argvCalls).toEqual([
{ bypassPermission: false, resumeSessionId: 'sess-42' },
{ bypassPermission: false },
])
expect(outcome).toEqual({ ok: true, processIdentity: IDENTITY, resumed: false })
// The conversation it could not reopen is kept, once the fresh start is up.
expect(d.calls.at(-1)).toBe('keepAbandoned')
// respawn + waitForProcess ran twice (once per attempt); holdOpen/terminate ran once.
expect(d.calls.filter((c) => c === 'respawn')).toHaveLength(2)
expect(d.calls.filter((c) => c === 'holdOpen')).toHaveLength(1)
expect(d.calls.filter((c) => c === 'terminate')).toHaveLength(1)
})
it('keeps a strict imported conversation bound when its resume cannot be verified', async () => {
const buildArgv = vi.fn(() => ['claude', '--resume', 'imported'])
const d = deps({ buildArgv, waitForProcess: async () => null })
expect(await restartAgent({ engine: 'claude', sessionId: 'imported', resumeOnly: true }, false, d)).toMatchObject({ ok: false })
expect(buildArgv).toHaveBeenCalledExactlyOnceWith({ bypassPermission: false, resumeSessionId: 'imported' })
expect(d.calls.filter(call => call === 'respawn')).toHaveLength(1)
expect(d.calls).not.toContain('keepAbandoned')
})
it('fails outright when even the fresh fallback relaunch never comes up', async () => {
const d = deps({ waitForProcess: async () => null })
const outcome = await restartAgent({ engine: 'codex', sessionId: 'sess-1' }, false, d)
expect(outcome).toEqual({ ok: false, detail: 'codex did not come back up after restart' })
// Nothing runs in a new conversation, so the row still holds the one it was in: nothing to keep.
expect(d.calls).not.toContain('keepAbandoned')
})
it('never retries a resume fallback for an engine with no session to resume in the first place', async () => {
let respawnCalls = 0
const d = deps({
respawn: async () => { respawnCalls += 1; return { ok: true } },
waitForProcess: async () => null,
})
await restartAgent({ engine: 'claude', sessionId: '' }, false, d)
expect(respawnCalls).toBe(1) // no resume attempt to fall back FROM
})
it('does not poll for a process when respawn-pane itself fails', async () => {
const d = deps({ respawn: async () => ({ ok: false, reason: 'tmux respawn-pane did not complete' }) })
const outcome = await restartAgent({ engine: 'claude', sessionId: 's1' }, false, d)
expect(outcome.ok).toBe(false)
expect(d.calls).not.toContain('waitForProcess')
})
})
describe('restart cancellation', () => {
for (const phase of ['before', 'hold', 'terminate', 'prepare', 'respawn', 'wait'] as const) {
it(`does not continue process replacement after cancellation at ${phase}`, async () => {
let current = phase !== 'before'
const stopAt = (at: string) => { if (phase === at) current = false }
const d = deps({
holdOpen: async () => { stopAt('hold'); return { ok: true } },
terminate: async () => { stopAt('terminate'); return 'terminated' },
prepareResume: async () => { stopAt('prepare') },
respawn: async () => { stopAt('respawn'); return { ok: true } },
waitForProcess: async () => { stopAt('wait'); return null },
})
const result = await restartAgent({ engine: 'codex', sessionId: 's1' }, false, { ...d, isCurrent: () => current })
expect(result).toEqual({ ok: false, detail: 'the harness changed or stopped during restart' })
expect(d.calls.filter((call) => call === 'respawn')).toHaveLength(['respawn', 'wait'].includes(phase) ? 1 : 0)
if (phase === 'before') expect(d.calls).toEqual([])
if (phase === 'hold') expect(d.calls).toEqual(['holdOpen'])
})
}
it('does not retain epochs for rejected unknown restart or resume IDs', async () => {
const coordinator = new AgentRestartCoordinator()
const before = coordinator.revision('known')
for (const operation of ['restart', 'resume']) for (let i = 0; i < 20; i++) {
const id = `${operation}-${i}`
await coordinator.run(id, async () => ({ ok: false, error: 'AGENT_NOT_FOUND' }), operation)
coordinator.cancel(id)
}
expect(coordinator.revision('next observed')).toBe(before + 1)
})
// Asked with other launch words, a second restart would be answered by the first's launch and its words would be lost
// (or, saved beside it, differ from what launched): it is refused instead, and only the same words join.
it('joins an overlapping restart only when it asks for the same launch words, and refuses one that asks for others', async () => {
const coordinator = new AgentRestartCoordinator()
let finish!: () => void
const handler = vi.fn(async () => { await new Promise<void>((resolve) => { finish = resolve }); return { ok: false, error: 'fixture' } as const })
const first = coordinator.run('a', handler, 'restart', '["--chrome"]')
expect(coordinator.run('a', handler, 'restart', '["--chrome"]')).toBe(first)
expect(await coordinator.run('a', handler, 'restart', '["--other"]')).toMatchObject({ ok: false, error: 'AGENT_BUSY' })
expect(await coordinator.run('a', handler, 'restart')).toMatchObject({ ok: false, error: 'AGENT_BUSY' })
expect(coordinator.operation('a')).toBe('restart')
finish()
await first
expect(handler).toHaveBeenCalledTimes(1)
})
it('joins overlapping restarts but leaves other agents independent', async () => {
const coordinator = new AgentRestartCoordinator()
const initial = coordinator.revision('a')
expect(initial).toBeGreaterThan(0)
expect(coordinator.operation('a')).toBeUndefined()
let finish!: () => void
const handler = vi.fn(async () => { await new Promise<void>((resolve) => { finish = resolve }); return { ok: false, error: 'fixture' } as const })
const first = coordinator.run('a', handler)
expect(coordinator.revision('a')).toBe(initial + 1)
expect(coordinator.operation('a')).toBe('restart')
expect(coordinator.run('a', handler)).toBe(first)
expect(await coordinator.run('b', async () => ({ ok: false, error: 'other' }))).toEqual({ ok: false, error: 'other' })
finish()
await first
expect(coordinator.revision('a')).toBe(initial + 1)
expect(handler).toHaveBeenCalledTimes(1)
expect(await coordinator.run('a', async () => ({ ok: false, error: 'fresh' }))).toEqual({ ok: false, error: 'fresh' })
expect(coordinator.revision('a')).toBeGreaterThan(initial + 1)
const old = coordinator.revision('a')
coordinator.forget('a')
expect(coordinator.revision('a')).toBeGreaterThan(old)
})
it('Stop cancels before dispatch and during an outstanding step', async () => {
const coordinator = new AgentRestartCoordinator()
const untouched = vi.fn(async () => ({ ok: false, error: 'unexpected' } as const))
const first = coordinator.run('a', untouched)
coordinator.cancel('a')
expect(await first).toEqual({ ok: false, error: 'AGENT_CHANGED' })
expect(untouched).not.toHaveBeenCalled()
let finish!: () => void
let isCurrent!: () => boolean
const second = coordinator.run('a', async (current) => {
isCurrent = current
await new Promise<void>((resolve) => { finish = resolve })
return { ok: false, error: 'old receipt' }
})
await Promise.resolve()
coordinator.cancel('a')
expect(isCurrent()).toBe(false)
expect(coordinator.run('a', untouched)).toBe(second)
finish()
expect(await second).toEqual({ ok: false, error: 'AGENT_CHANGED' })
expect(untouched).not.toHaveBeenCalled()
})
it('a thrown restart releases the coordinator for a new explicit attempt', async () => {
const coordinator = new AgentRestartCoordinator()
await expect(coordinator.run('a', async () => { throw new Error('lost') })).rejects.toThrow('lost')
expect(await coordinator.run('a', async () => ({ ok: false, error: 'fresh' }))).toEqual({ ok: false, error: 'fresh' })
})
})
describe('bypassPermissionFor', () => {
const probe = () => {
const fn = vi.fn(async () => true)
return fn
}
it('answers from the recorded mode without touching the live process', async () => {
const live = probe()
await expect(bypassPermissionFor({ permissionMode: 'full' }, live)).resolves.toBe(true)
await expect(bypassPermissionFor({ permissionMode: 'auto', bypassPermission: false }, live)).resolves.toBe(true)
// Plan is not a yes, whatever the boolean beside it says.
await expect(bypassPermissionFor({ permissionMode: 'plan', bypassPermission: true }, live)).resolves.toBe(false)
await expect(bypassPermissionFor({ permissionMode: 'ask' }, live)).resolves.toBe(false)
expect(live).not.toHaveBeenCalled()
})
it('falls back to the recorded flag, then to the live process only for a row that has neither', async () => {
const live = probe()
await expect(bypassPermissionFor({ bypassPermission: true }, live)).resolves.toBe(true)
await expect(bypassPermissionFor({ bypassPermission: false }, live)).resolves.toBe(false)
expect(live).not.toHaveBeenCalled()
await expect(bypassPermissionFor({}, live)).resolves.toBe(true)
expect(live).toHaveBeenCalledTimes(1)
})
// Swarm v3 (task #4215): a Swarm agent's mode is its person's choice, or none. One Harness started in full mode, cleared
// since, still runs with that flag: read back, its restart or retarget came back in Auto, which nobody chose.
it('never asks a Swarm agent\'s live process: with no mode it relaunches approving nothing', async () => {
const live = probe()
const swarmSkill = { role: 'coordinator' as const, key: 'swarm-lead' }
await expect(bypassPermissionFor({ swarmSkill }, live)).resolves.toBe(false)
expect(live).not.toHaveBeenCalled()
// The mode its person chose still counts.
await expect(bypassPermissionFor({ swarmSkill, permissionMode: 'full' }, live)).resolves.toBe(true)
})
})