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.

23.5 KB
Raw Blame
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)
  })
})