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.

39.0 KB
Raw Blame
import { mkdtempSync, rmSync } from 'node:fs'
import { homedir, tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { engineBin, enginePathOverride } from '../../lib/engineBin.js'
import { engineInstallRecipe } from '../../lib/engineInstall.js'
import { buildEngineLaunchArgv, commandAvailableInInteractiveShell } from '../../lib/engineLaunch.js'
import { probeGatewayRuntime } from '../../lib/gatewayRuntime.js'
import type { RegisteredSession } from '../../lib/registry.js'
import { AgentRestartCoordinator, bypassPermissionFor, restartAgent } from '../../lib/restartAgent.js'
import { terminalRouteKey } from '../../lib/terminalRuntime.js'
import { processLaunchArgs } from '../../lib/processTable.js'
import { workspaceMissing } from '../../lib/workspaceCheck.js'
import { createAgentRestarter, type RestartDeps } from './restart.js'
import { createLaunchAuthority } from './launchAuthority.js'
import { createSwarmSkillAdoption } from '../../superTabs/inCore/adoption.js'
import { RETENTION_LAPSE_MS, retainContributions, retainedHarnesses } from '../../superTabs/retention.js'
import { GUEST_HARNESS_REFUSAL } from '../guestPolicy.js'
import { TerminalAgentReconciler } from '../../lib/terminalAgentReconciler.js'

vi.mock('../../lib/engineBin.js', async (real) => ({ ...await real<object>(), enginePathOverride: vi.fn(() => undefined) }))
vi.mock('../../lib/engineLaunch.js', async (real) => ({
  ...await real<object>(),
  buildEngineLaunchArgv: vi.fn(() => ['zsh', '-l']),
  commandAvailableInInteractiveShell: vi.fn(async () => true),
}))
vi.mock('../../lib/gatewayRuntime.js', async (real) => ({ ...await real<object>(), probeGatewayRuntime: vi.fn(async () => ({ kind: 'none' })) }))
vi.mock('../../lib/restartAgent.js', async (real) => ({
  ...await real<object>(),
  bypassPermissionFor: vi.fn(async (_s: unknown, live: () => Promise<boolean>) => live()),
  restartAgent: vi.fn(async () => ({ ok: true, resumed: true, processIdentity: { pid: 2, startMarker: 'new', executable: '/bin/claude' } })),
}))
vi.mock('../../lib/processTable.js', async (real) => ({
  ...await real<object>(),
  processLaunchArgs: vi.fn(async () => '/bin/claude --model opus -c model_provider=grid'),
}))
vi.mock('../../lib/workspaceCheck.js', () => ({ workspaceMissing: vi.fn(() => null) }))

const runtime = { backend: 'tmux' as const, paneId: '%4' }
/** The pane's backend handing the pane back to its default disposal (`TerminalBackend.releaseHold`). */
const releaseHold = vi.fn(async (..._args: unknown[]) => {})
const routeKey = terminalRouteKey(runtime as never)
const newProcess = { pid: 2, startMarker: 'new', executable: '/bin/claude' }
const agent = (over: Partial<RegisteredSession> = {}): RegisteredSession => ({
  agentId: 'a1', sessionId: 's1', engine: 'claude', cwd: '/work', tmuxPane: '%4', runtimes: [runtime], processIdentity: { pid: 1, startMarker: 'old' }, ...over,
}) as unknown as RegisteredSession
const terminal = (over: Partial<RegisteredSession> = {}) => agent({ engine: 'terminal', processIdentity: undefined, ...over } as Partial<RegisteredSession>)

/** `row` is what the registry resolves and reads back; `refreshed` is what it reads after the swap
 *  (null: the row vanished mid-restart). `live` goes false to make the operation stale. */
function setup(row: RegisteredSession | null = agent(), over: Partial<RestartDeps> = {}, refreshed: RegisteredSession | null = row) {
  const state = { live: true }
  const tmuxBackend = { name: 'tmux', holdOpen: vi.fn(), respawn: vi.fn(async () => ({ state: 'succeeded' })), releaseHold }
  const deps: RestartDeps = {
    restartJobs: { run: vi.fn((_id: string, job: (current: () => boolean) => unknown) => job(() => state.live)) } as never,
    registry: {
      resolve: vi.fn(() => row ?? undefined),
      byAgent: vi.fn(() => refreshed ?? undefined),
      updateProcessIdentity: vi.fn(),
      setActive: vi.fn(),
      setLaunchArgs: vi.fn(() => true),
    } as unknown as RestartDeps['registry'],
    purgeBusy: vi.fn(() => false),
    stopJobs: new Map(),
    pinnedControls: new Set(),
    terminals: { backendFor: vi.fn((runtime: { backend: string }) => runtime.backend === 'tmux' ? tmuxBackend : undefined) } as unknown as RestartDeps['terminals'],
    sameRestartTarget: vi.fn(() => true),
    agentReconciler: { holdRoute: vi.fn((key: string) => () => deps.agentReconciler.releaseRoute(key)), releaseRoute: vi.fn() },
    terminalHintMachineName: () => 'studio',
    announceSession: vi.fn(),
    refreshGridAssignment: vi.fn(),
    relaunchOverrides: vi.fn(async () => ({ ok: true, overrides: { env: { GRID_KEY: 'k' } } })) as never,
    downgradedPermission: vi.fn(async (_s, bypass: boolean) => ({ bypassPermission: bypass, permissionMode: 'auto' })) as never,
    refreshGridWebSearch: vi.fn() as never,
    liveBypassPermission: vi.fn(async () => true),
    paneSwapDeps: vi.fn(() => ({ swap: true })) as never,
    restartHeld: vi.fn(() => null),
    ...over,
  }
  return { deps, state, tmuxBackend, restart: createAgentRestarter(deps) }
}

const changed = { ok: false, error: 'AGENT_CHANGED', detail: 'The harness changed or stopped during restart.' }

describe('restarting an agent', () => {
  beforeEach(() => { vi.spyOn(console, 'log').mockImplementation(() => {}) })
  afterEach(() => { vi.restoreAllMocks(); vi.clearAllMocks() })

  it.each(['terminal', 'claude'] as const)('keeps a slow %s restart hidden from discovery until publication', async engine => {
    vi.useFakeTimers()
    const onDiscovered = vi.fn()
    const reconciler = new TerminalAgentReconciler({ current: () => [], backends: [], backendOrder: ['tmux'],
      onDiscovered, onObserved: vi.fn(), onDormant: vi.fn(), onRemoved: vi.fn(),
      probe: async () => ({ processTableAvailable: true, ambiguousPlacements: new Set(),
        targets: [{ instanceId: 'tmux:default', result: { state: 'available', roots: [{ runtime, rootPid: 1, cwd: '/work' }] } }],
        agents: [{ engine: 'claude', cwd: '/work', processIdentity: newProcess,
          args: 'claude', resumeSessionId: null, runtimes: [runtime], primaryRuntimeKey: routeKey }],
      }),
    })
    let finish!: () => void
    const run = setup(engine === 'terminal' ? terminal() : agent(), { agentReconciler: reconciler })
    if (engine === 'terminal') run.tmuxBackend.respawn.mockImplementationOnce(() => new Promise(done => {
      finish = () => done({ state: 'succeeded' })
    }))
    else vi.mocked(restartAgent).mockImplementationOnce(() => new Promise(done => {
      finish = () => done({ ok: true, resumed: true, processIdentity: newProcess })
    }))
    const pending = run.restart('a1')
    try {
      await vi.waitFor(() => expect(finish).toBeTypeOf('function'))
      await vi.advanceTimersByTimeAsync(30_001)
      await reconciler.trigger()
      expect(onDiscovered).not.toHaveBeenCalled()
      finish()
      expect(await pending).toMatchObject({ ok: true })
      expect(run.deps.announceSession).toHaveBeenCalled()
      await reconciler.trigger()
      expect(onDiscovered).toHaveBeenCalledOnce()
    } finally { finish?.(); await pending; vi.useRealTimers() }
  })

  it.each(['terminal', 'claude'] as const)('a cancelled %s restart cannot release a newer Stop hold', async engine => {
    const onDiscovered = vi.fn()
    const reconciler = new TerminalAgentReconciler({ current: () => [], backends: [], backendOrder: ['tmux'],
      onDiscovered, onObserved: vi.fn(), onDormant: vi.fn(), onRemoved: vi.fn(),
      probe: async () => ({ processTableAvailable: true, ambiguousPlacements: new Set(),
        targets: [{ instanceId: 'tmux:default', result: { state: 'available', roots: [{ runtime, rootPid: 1, cwd: '/work' }] } }],
        agents: [{ engine: 'claude', cwd: '/work', processIdentity: newProcess,
          args: 'claude', resumeSessionId: null, runtimes: [runtime], primaryRuntimeKey: routeKey }],
      }),
    })
    const run = setup(engine === 'terminal' ? terminal() : agent(), { agentReconciler: reconciler })
    let releaseStop!: () => void
    const stop = () => { run.state.live = false; releaseStop = reconciler.holdRoute(routeKey) }
    if (engine === 'terminal') run.tmuxBackend.respawn.mockImplementationOnce(async () => { stop(); return { state: 'succeeded' } })
    else vi.mocked(restartAgent).mockImplementationOnce(async () => { stop(); return { ok: false, detail: 'cancelled' } })
    try {
      expect(await run.restart('a1')).toMatchObject({ error: 'AGENT_CHANGED' })
      await reconciler.trigger()
      expect(onDiscovered).not.toHaveBeenCalled()
      releaseStop()
      await reconciler.trigger()
      expect(onDiscovered).toHaveBeenCalledOnce()
    } finally { releaseStop?.() }
  })

  it('adopts an old role before native inspection and relaunch', async () => {
    const skill = { role: 'coordinator' as const, key: 'a1' }
    const run = setup(agent(), { adoptSwarmSkill: async row => ({ ...row, swarmSkill: skill }) })
    expect(await run.restart('a1')).toMatchObject({ ok: true })
    expect(run.deps.relaunchOverrides).toHaveBeenCalledWith(expect.objectContaining({ swarmSkill: skill }),
      expect.objectContaining({ swarmSkill: skill }), expect.any(Function), undefined)
  })

  it('does not restart if role adoption loses the session binding', async () => {
    const run = setup(agent(), { adoptSwarmSkill: async () => null })
    expect(await run.restart('a1')).toMatchObject({ error: 'AGENT_CHANGED' })
    expect(run.deps.relaunchOverrides).not.toHaveBeenCalled()
    expect(restartAgent).not.toHaveBeenCalled()
  })

  it('restarts when an unrelated registry field changes during a no-role lookup', async () => {
    const session = agent({ registeredAt: 1 })
    const authority = createLaunchAuthority({ byAgent: () => session, revision: () => 0, cancelled: () => false })
    const adoptSwarmSkill = createSwarmSkillAdoption({
      authority, save: vi.fn(), candidate: () => true,
      role: async () => { session.dsh = 'changed-during-lookup'; return null },
    })
    const run = setup(session, { adoptSwarmSkill })
    expect(await run.restart('a1')).toMatchObject({ ok: true })
    expect(restartAgent).toHaveBeenCalledOnce()
  })

  // Security review 2 of #2255: a Mac offline over a week has a lapsed local roster, which once restarted an old Buddy
  // without its role.
  it('restarts an old Buddy with its role after the local roster lapsed', async () => {
    const data = mkdtempSync(join(tmpdir(), 'restart-roster-'))
    try {
      retainContributions(data, 'machine', [{ tabId: 'tab', agent: { harnessId: 'a1', machineId: 'machine' } }], Date.now() - RETENTION_LAPSE_MS - 60_000)
      const session = agent({ startedBy: 'agent' })
      const role = vi.fn(async () => ({ role: 'buddy' as const }))
      const adoptSwarmSkill = createSwarmSkillAdoption({ role, save: vi.fn(), candidate: id => retainedHarnesses(data).has(id),
        authority: createLaunchAuthority({ byAgent: () => session, revision: () => 0, cancelled: () => false }) })
      const run = setup(session, { adoptSwarmSkill })
      expect(await run.restart('a1')).toMatchObject({ ok: true })
      expect(role).toHaveBeenCalledOnce()
      expect(run.deps.relaunchOverrides).toHaveBeenCalledWith(expect.objectContaining({ swarmSkill: { role: 'buddy', key: 'a1' } }),
        expect.anything(), expect.any(Function), undefined)
    } finally { rmSync(data, { recursive: true, force: true }) }
  })

  it.each(['starting', 'held'] as const)('does not replace an unbound native %s launch with a generic fresh restart', async state => {
    const run = setup(agent({ sessionId: '', launch: state === 'starting' ? { state, nativeToken: 'original' }
      : { state, nativeToken: 'original', service: 'native', detail: 'Original request held' } }))
    expect(await run.restart('a1')).toMatchObject({ ok: false, error: 'NATIVE_LAUNCH_HELD' })
    expect(run.deps.restartHeld).not.toHaveBeenCalled()
    expect(run.deps.relaunchOverrides).not.toHaveBeenCalled()
    expect(restartAgent).not.toHaveBeenCalled()
  })

  it.each(['inspection', 'permission', 'snapshot'] as const)('preserves the live process when restart loses %s evidence', async stage => {
    let nativeCurrent = true
    const launch = { current: () => nativeCurrent } as never
    const run = setup(agent(), {
      native: async () => { if (stage === 'inspection') run.state.live = false; return { ok: true, launch } },
      relaunchOverrides: async () => ({ ok: true, overrides: { native: launch, env: {}, extraArgs: [], clearEnv: [] } }),
      downgradedPermission: async () => {
        if (stage === 'snapshot') nativeCurrent = false
        return { bypassPermission: false, ...(stage === 'permission' ? { nativeHold: 'Waiting for native flags.' } : {}) }
      },
    })
    expect(await run.restart('a1')).toMatchObject({ ok: false, error: stage === 'inspection' ? 'AGENT_CHANGED' : 'NATIVE_LAUNCH_HELD' })
    expect(restartAgent).not.toHaveBeenCalled()
    expect(run.deps.registry.updateProcessIdentity).not.toHaveBeenCalled()
  })

  it('holds native installation before killing the live process, without an independent shell probe', async () => {
    const native = vi.fn(async () => ({ ok: false as const, error: 'NATIVE_LAUNCH_HELD' as const, unavailable: 'native' as const, detail: 'Waiting for installation' }))
    const run = setup(agent(), { native })
    expect(await run.restart('a1')).toMatchObject({ unavailable: 'native' })
    expect(commandAvailableInInteractiveShell).not.toHaveBeenCalled()
    expect(run.deps.relaunchOverrides).not.toHaveBeenCalled()
    expect(restartAgent).not.toHaveBeenCalled()
  })

  it('passes its one native snapshot through restart preparation and permission checks', async () => {
    const launch = { current: () => true } as never
    const run = setup(agent(), { native: async () => ({ ok: true, launch }),
      relaunchOverrides: vi.fn(async () => ({ ok: true as const, overrides: { native: launch, env: {}, extraArgs: [], clearEnv: [] } })),
    })
    expect(await run.restart('a1')).toMatchObject({ ok: true })
    expect(commandAvailableInInteractiveShell).not.toHaveBeenCalled()
    expect(run.deps.relaunchOverrides).toHaveBeenCalledWith(expect.any(Object), expect.any(Object), expect.any(Function), launch)
    expect(run.deps.downgradedPermission).toHaveBeenCalledWith(expect.any(Object), true, 'restart', launch)
  })

  it('answers a relaunch refused on Windows by its own code, having stopped nothing', async () => {
    vi.mocked(restartAgent).mockResolvedValueOnce({ ok: false, error: 'ENGINE_LAUNCH_REFUSED', detail: 'Harness cannot start claude on Windows. Nothing was stopped.' })
    expect(await setup(agent()).restart('a1')).toEqual({ ok: false, error: 'ENGINE_LAUNCH_REFUSED', detail: 'Harness cannot start claude on Windows. Nothing was stopped.' })
  })

  it('never starts a fresh conversation when an admitted external resume fails', async () => {
    const actual = await vi.importActual<typeof import('../../lib/restartAgent.js')>('../../lib/restartAgent.js')
    vi.mocked(restartAgent).mockImplementationOnce(actual.restartAgent)
    const respawn = vi.fn(async () => ({ ok: true }))
    const keepAbandoned = vi.fn(), buildArgv = vi.fn(options => ['fixture-engine', options.resumeSessionId ?? 'fresh'])
    const run = setup(agent({ resumeOnly: true }), { paneSwapDeps: () => ({
      holdOpen: async () => ({ ok: true }), terminate: async () => 'gone', respawn,
      waitForProcess: async () => null, buildArgv, keepAbandoned, log: () => {},
    }) })
    expect(await run.restart('a1')).toMatchObject({ ok: false, error: 'RESTART_FAILED' })
    expect(respawn).toHaveBeenCalledExactlyOnceWith(['fixture-engine', 's1'])
    expect(keepAbandoned).not.toHaveBeenCalled()
    expect(run.deps.registry.updateProcessIdentity).not.toHaveBeenCalled()
  })

  describe('with new launch words', () => {
    const WORDS = ['--chrome']

    it('builds the relaunch with them and saves them on the record only after the engine is back', async () => {
      const order: string[] = []
      const run = setup(agent(), {
        relaunchOverrides: vi.fn(async () => { order.push('build'); return { ok: true as const, overrides: { env: {}, extraArgs: [], clearEnv: [] } } }),
      })
      vi.mocked(run.deps.registry.setLaunchArgs).mockImplementation(() => { order.push('save'); return true })
      vi.mocked(restartAgent).mockImplementationOnce(async () => { order.push('restart'); return { ok: true, resumed: true, processIdentity: newProcess } })
      expect(await run.restart('a1', WORDS)).toMatchObject({ ok: true })
      expect(run.deps.relaunchOverrides).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ agentId: 'a1', launchArgs: WORDS }), expect.any(Function), undefined)
      expect(order).toEqual(['build', 'restart', 'save'])
      expect(run.deps.registry.setLaunchArgs).toHaveBeenCalledExactlyOnceWith('a1', WORDS)
      // Asked as its own variant of a restart, so another ask with other words is not answered by this launch.
      expect(run.deps.restartJobs.run).toHaveBeenCalledWith('a1', expect.any(Function), 'restart', JSON.stringify(WORDS))
    })

    it('clears them with an empty list: built without, and removed from the record once the engine is back', async () => {
      const run = setup(agent({ launchArgs: ['--old'] } as Partial<RegisteredSession>))
      expect(await run.restart('a1', [])).toMatchObject({ ok: true })
      expect(run.deps.relaunchOverrides).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ launchArgs: [] }), expect.any(Function), undefined)
      expect(run.deps.registry.setLaunchArgs).toHaveBeenCalledExactlyOnceWith('a1', [])
    })

    it('without them, relaunches from the row itself and never writes the record', async () => {
      const row = agent({ launchArgs: ['--saved'] } as Partial<RegisteredSession>)
      const run = setup(row)
      expect(await run.restart('a1')).toMatchObject({ ok: true })
      expect(run.deps.relaunchOverrides).toHaveBeenCalledWith(row, row, expect.any(Function), undefined)
      expect(run.deps.registry.setLaunchArgs).not.toHaveBeenCalled()
      expect(run.deps.restartJobs.run).toHaveBeenCalledWith('a1', expect.any(Function), 'restart', undefined)
    })

    // Every way a restart can end without the engine back saves nothing: the record keeps the flags that last worked.
    it.each([
      ['busy', () => setup(agent(), { purgeBusy: () => true })],
      ['no live process', () => setup(agent({ processIdentity: undefined } as Partial<RegisteredSession>))],
      ['the agent changed under it', () => setup(agent(), { sameRestartTarget: vi.fn(() => false) })],
      ['launch preparation refused', () => setup(agent(), { relaunchOverrides: vi.fn(async () => ({ ok: false as const, error: 'GRID_UNAVAILABLE', detail: 'x' })) })],
      ['the engine did not start', () => {
        vi.mocked(restartAgent).mockResolvedValueOnce({ ok: false, error: 'RESTART_FAILED', detail: 'did not come up' } as never)
        return setup(agent())
      }],
    ])('saves nothing when the restart ends %s', async (_why, make) => {
      const run = make()
      expect(await run.restart('a1', WORDS)).toMatchObject({ ok: false })
      expect(run.deps.registry.setLaunchArgs).not.toHaveBeenCalled()
    })

    // The coordinator joins asks of the same words and refuses the others, so the record is what the one launch used.
    it('two overlapping restarts with different words: one launches and is saved, the other is refused and saves nothing', async () => {
      let release!: () => void
      vi.mocked(restartAgent).mockImplementationOnce(async () => {
        await new Promise<void>((resolve) => { release = resolve })
        return { ok: true, resumed: true, processIdentity: newProcess }
      })
      const run = setup(agent(), { restartJobs: new AgentRestartCoordinator() })
      const first = run.restart('a1', ['--first'])
      await vi.waitFor(() => expect(release).toBeDefined())
      expect(await run.restart('a1', ['--second'])).toMatchObject({ ok: false, error: 'AGENT_BUSY' })
      const joined = run.restart('a1', ['--first'])
      release()
      expect(await first).toMatchObject({ ok: true })
      expect(await joined).toMatchObject({ ok: true })
      expect(run.deps.registry.setLaunchArgs).toHaveBeenCalledExactlyOnceWith('a1', ['--first'])
      expect(restartAgent).toHaveBeenCalledOnce()
    })
  })

  describe('refusals before anything is touched', () => {
    it('for an agent being purged, stopped or answered, and for one that is not there', async () => {
      expect(await setup(agent(), { purgeBusy: () => true }).restart('a1')).toEqual({ ok: false, error: 'AGENT_BUSY' })
      expect(await setup(agent(), { stopJobs: new Map([['a1', Promise.resolve()]]) }).restart('a1')).toEqual({ ok: false, error: 'AGENT_BUSY' })
      expect(await setup(agent(), { pinnedControls: new Set(['a1']) }).restart('a1')).toEqual({ ok: false, error: 'AGENT_BUSY' })
      expect(await setup(null).restart('a1')).toEqual({ ok: false, error: 'AGENT_NOT_FOUND' })
    })

    it('for an agent a stopped move may still run beside, held this start, with the move\'s line', async () => {
      const log = vi.spyOn(console, 'warn').mockImplementation(() => {})
      const held = vi.fn(() => ({ ok: false, error: 'HELD' }))
      const run = setup(agent(), { moveHeld: (id) => id === 'a1', restartHeld: held as never })
      expect(await run.restart('a1')).toMatchObject({ ok: false, error: 'AGENT_BUSY' })
      // Neither a swap nor a held agent's launch runs: either would start a second engine on the conversation.
      expect(held).not.toHaveBeenCalled()
      expect(restartAgent).not.toHaveBeenCalled()
      expect(log).toHaveBeenCalledWith('[terminal] move a1: held until the next start: a pane its stopped move left was not confirmed closed')
      log.mockRestore()
    })

    it('for a guest\'s harness, which a relaunch would run as the owner', async () => {
      const run = setup(agent({ guest: '[email protected]' }))
      expect(await run.restart('a1')).toEqual(GUEST_HARNESS_REFUSAL)
    })

    it('for an agent held for a service, its launch, now, with nothing of a swap touched', async () => {
      const launched = { ok: true as const, session: agent(), resumed: true }
      const run = setup(agent({ processIdentity: undefined, tmuxPane: '%4' } as Partial<RegisteredSession>), { restartHeld: vi.fn(() => Promise.resolve(launched)) })
      expect(await run.restart('a1')).toBe(launched)
      expect(run.deps.restartHeld).toHaveBeenCalledWith('a1')
      expect(run.deps.relaunchOverrides).not.toHaveBeenCalled()
      expect(run.tmuxBackend.respawn).not.toHaveBeenCalled()
    })

    it('for an agent with no tmux pane, or no tmux at all', async () => {
      expect(await setup(agent({ tmuxPane: undefined, runtimes: [] })).restart('a1')).toEqual({ ok: false, error: 'RESTART_UNSUPPORTED_BACKEND' })
      expect(await setup(agent(), { terminals: { backendFor: () => undefined } }).restart('a1')).toEqual({ ok: false, error: 'RESTART_UNSUPPORTED_BACKEND' })
    })

    it('for an agent on a ptyhost pane only, though its `tmuxPane` names that pane\'s id, with no ptyhost backend', async () => {
      const run = setup(agent({ runtimes: [{ backend: 'ptyhost', instance: 'p1', paneId: '%4' }] }))
      expect(await run.restart('a1')).toEqual({ ok: false, error: 'RESTART_UNSUPPORTED_BACKEND' })
      expect(run.tmuxBackend.respawn).not.toHaveBeenCalled()
    })

    it('for an agent whose backend has no restart primitives, whatever its name', async () => {
      const pty = { backend: 'ptyhost' as const, instance: 'p1', paneId: '%3' }
      const bare = { name: 'ptyhost', respawn: vi.fn(), releaseHold: vi.fn() }
      const run = setup(agent({ runtimes: [pty] }), { terminals: { backendFor: () => bare as never } })
      expect(await run.restart('a1')).toEqual({ ok: false, error: 'RESTART_UNSUPPORTED_BACKEND' })
      expect(bare.respawn).not.toHaveBeenCalled()
      expect(run.tmuxBackend.respawn).not.toHaveBeenCalled()
    })

    it('for an operation already overtaken, or an agent that is no longer the one asked about', async () => {
      const stale = setup()
      stale.state.live = false
      expect(await stale.restart('a1')).toEqual(changed)
      const replaced = setup(agent(), { sameRestartTarget: vi.fn(() => false) })
      expect(await replaced.restart('a1')).toEqual(changed)
      expect(replaced.deps.sameRestartTarget).toHaveBeenCalledWith(agent())
      expect(replaced.deps.agentReconciler.holdRoute).not.toHaveBeenCalled()
    })

    it('for a folder that is gone, before the old process is killed', async () => {
      vi.mocked(workspaceMissing).mockReturnValueOnce({ ok: false, error: 'CWD_NOT_FOUND', detail: 'gone' } as never)
      const run = setup()
      expect(await run.restart('a1')).toEqual({ ok: false, error: 'CWD_NOT_FOUND', detail: 'gone' })
      expect(workspaceMissing).toHaveBeenCalledWith('/work')
      expect(run.deps.relaunchOverrides).not.toHaveBeenCalled()
      expect(restartAgent).not.toHaveBeenCalled()
    })

    it('for an engine uninstalled since the agent started, before anything is touched, and the agent goes on', async () => {
      vi.spyOn(console, 'warn').mockImplementation(() => {})
      vi.mocked(commandAvailableInInteractiveShell).mockResolvedValueOnce(false)
      const run = setup()
      expect(await run.restart('a1')).toEqual({
        ok: false, error: 'ENGINE_NOT_INSTALLED', detail: 'claude is not installed. Install it, then restart again. Nothing was stopped.',
      })
      // Asked as create asks: the launch's own command, and the install recipe unless a path was set.
      expect(commandAvailableInInteractiveShell).toHaveBeenCalledWith(engineBin('claude'), undefined, engineInstallRecipe('claude'))
      expect(console.warn).toHaveBeenCalledWith('[restart] a1 refused · claude is not installed')
      expect(run.deps.relaunchOverrides).not.toHaveBeenCalled()
      expect(run.deps.agentReconciler.holdRoute).not.toHaveBeenCalled()
      expect(restartAgent).not.toHaveBeenCalled()

      vi.mocked(enginePathOverride).mockReturnValueOnce('/opt/claude')
      vi.mocked(commandAvailableInInteractiveShell).mockResolvedValueOnce(false)
      expect(await setup().restart('a1')).toMatchObject({ ok: false, error: 'ENGINE_NOT_INSTALLED' })
      expect(vi.mocked(commandAvailableInInteractiveShell).mock.calls[1][2]).toBeUndefined()
    })

    it('but not on a no from a shell that gave up: a slow rc file is not a missing engine', async () => {
      // The check starts at 0, and the shell's no comes at 5s, when the probe gives up waiting for it.
      const clock = vi.spyOn(Date, 'now').mockReturnValue(0)
      vi.mocked(commandAvailableInInteractiveShell).mockImplementationOnce(async () => { clock.mockReturnValue(5_000); return false })
      const run = setup()
      expect(await run.restart('a1')).toEqual({ ok: true, session: agent(), resumed: true })
      expect(restartAgent).toHaveBeenCalled()
    })

    it('and stops, touching nothing, when the operation is overtaken while the engine is looked for', async () => {
      const run = setup()
      vi.mocked(commandAvailableInInteractiveShell).mockImplementationOnce(async () => { run.state.live = false; return false })
      expect(await run.restart('a1')).toEqual(changed)
      expect(run.deps.relaunchOverrides).not.toHaveBeenCalled()
      expect(restartAgent).not.toHaveBeenCalled()
    })

    it('for an engine with no process to replace, or a launch it cannot honour', async () => {
      expect(await setup(agent({ processIdentity: undefined } as Partial<RegisteredSession>)).restart('a1')).toEqual({ ok: false, error: 'NO_ACTIVE_PROCESS' })
      const refused = setup(agent(), { relaunchOverrides: vi.fn(async () => ({ ok: false, error: 'API_UNAVAILABLE', detail: 'removed' })) as never })
      expect(await refused.restart('a1')).toEqual({ ok: false, error: 'API_UNAVAILABLE', detail: 'removed' })
      expect(refused.deps.agentReconciler.holdRoute).not.toHaveBeenCalled()
      expect(restartAgent).not.toHaveBeenCalled()
    })
  })

  describe('one job per agent', () => {
    it('keyed by the agent a session id resolves to, or by the id as given when nothing resolves', async () => {
      const run = setup(agent())
      await run.restart('s1')
      expect(run.deps.restartJobs.run).toHaveBeenCalledWith('a1', expect.any(Function), 'restart', undefined)
      const missing = setup(null)
      await missing.restart('ghost')
      expect(missing.deps.restartJobs.run).toHaveBeenCalledWith('ghost', expect.any(Function), 'restart', undefined)
    })

    it('so a second restart of the same agent joins the first through the real coordinator', async () => {
      const restartJobs = new AgentRestartCoordinator()
      const run = setup(terminal(), { restartJobs })
      const [first, second] = await Promise.all([run.restart('a1'), run.restart('a1')])
      expect(second).toBe(first)
      expect(run.tmuxBackend.respawn).toHaveBeenCalledTimes(1)
      expect(restartJobs.busy('a1')).toBe(false)
    })
  })

  describe('on a ptyhost pane', () => {
    const pty = { backend: 'ptyhost' as const, instance: 'p1', paneId: '%3' }
    const ptyBackend = () => ({ name: 'ptyhost', holdOpen: vi.fn(), respawn: vi.fn(async () => ({ state: 'succeeded' })), releaseHold: vi.fn(async () => {}) })

    it('restarts a terminal through that pane\'s own backend; tmux is never asked', async () => {
      const backend = ptyBackend()
      const run = setup(terminal({ runtimes: [pty] }), { terminals: { backendFor: vi.fn(() => backend as never) } })
      expect(await run.restart('a1')).toMatchObject({ ok: true, resumed: false })
      expect(run.deps.terminals.backendFor).toHaveBeenCalledWith(pty)
      expect(backend.respawn).toHaveBeenCalledExactlyOnceWith(pty, { command: ['zsh', '-l'], cwd: homedir() })
      expect(backend.releaseHold).toHaveBeenCalledWith(pty)
      expect(run.tmuxBackend.respawn).not.toHaveBeenCalled()
      expect(releaseHold).not.toHaveBeenCalled()
      expect(run.deps.agentReconciler.holdRoute).toHaveBeenCalledWith(terminalRouteKey(pty), null)
    })

    it('swaps an engine in that pane and hands it back to that backend', async () => {
      const backend = ptyBackend()
      const row = agent({ runtimes: [pty] })
      const run = setup(row, { terminals: { backendFor: () => backend as never } })
      expect(await run.restart('a1')).toMatchObject({ ok: true, resumed: true })
      expect(run.deps.paneSwapDeps).toHaveBeenCalledWith(row, { backend, runtime: pty }, { env: { GRID_KEY: 'k' } }, 'auto', expect.any(Function))
      expect(backend.releaseHold).toHaveBeenCalledWith(pty)
      expect(releaseHold).not.toHaveBeenCalled()
      expect(run.deps.agentReconciler.releaseRoute).toHaveBeenCalledWith(terminalRouteKey(pty))
    })
  })

  describe('a terminal', () => {
    it('restarts in its tmux pane, not the pane `tmuxPane` projects from a ptyhost runtime sorted first', async () => {
      const tmux5 = { backend: 'tmux' as const, paneId: '%5' }
      const run = setup(terminal({ runtimes: [{ backend: 'ptyhost', instance: 'p1', paneId: '%4' }, tmux5] }))
      expect(await run.restart('a1')).toMatchObject({ ok: true })
      expect(run.tmuxBackend.respawn).toHaveBeenCalledExactlyOnceWith(tmux5, expect.anything())
      expect(run.deps.agentReconciler.holdRoute).toHaveBeenCalledWith(terminalRouteKey(tmux5), null)
    })

    it('restarts as a fresh shell in the same pane, opened like a new terminal tile', async () => {
      const run = setup(terminal())
      expect(await run.restart('a1')).toEqual({ ok: true, session: terminal(), resumed: false })
      expect(buildEngineLaunchArgv).toHaveBeenCalledWith('terminal', { cwd: '/work', terminalHint: { machineName: 'studio' } })
      expect(run.tmuxBackend.respawn).toHaveBeenCalledWith(runtime, { command: ['zsh', '-l'], cwd: homedir() })
      expect(releaseHold).toHaveBeenCalledWith(runtime)
      expect(run.deps.registry.setActive).toHaveBeenCalledWith('a1', true)
      expect(run.deps.announceSession).toHaveBeenCalledWith(terminal())
      expect(console.log).toHaveBeenCalledWith('[restart] a1 terminal · fresh shell')
      expect(run.deps.agentReconciler.holdRoute).toHaveBeenCalledWith(routeKey, null)
      expect(run.deps.agentReconciler.releaseRoute).toHaveBeenCalledWith(routeKey)
      expect(run.deps.relaunchOverrides).not.toHaveBeenCalled()
    })

    it('on Windows, starts the shell in its folder, which no launch script enters there', async () => {
      const platform = Object.getOwnPropertyDescriptor(process, 'platform')!
      const run = setup(terminal())
      try {
        Object.defineProperty(process, 'platform', { ...platform, value: 'win32' })
        expect(await run.restart('a1')).toMatchObject({ ok: true })
      } finally { Object.defineProperty(process, 'platform', platform) }
      expect(run.tmuxBackend.respawn).toHaveBeenCalledWith(runtime, { command: ['zsh', '-l'], cwd: '/work' })
    })

    it('with no folder of its own, opens without one', async () => {
      await setup(terminal({ cwd: undefined })).restart('a1')
      expect(buildEngineLaunchArgv).toHaveBeenCalledWith('terminal', { terminalHint: { machineName: 'studio' } })
    })

    it('says why tmux would not respawn it, and lets the route go', async () => {
      const run = setup(terminal())
      run.tmuxBackend.respawn.mockResolvedValueOnce({ state: 'failed', reason: 'pane gone' } as never)
      expect(await run.restart('a1')).toEqual({ ok: false, error: 'RESTART_FAILED', detail: 'pane gone' })
      expect(releaseHold).not.toHaveBeenCalled()
      expect(run.deps.agentReconciler.releaseRoute).toHaveBeenCalledWith(routeKey)
    })

    it('stops at whichever step finds the operation overtaken', async () => {
      const respawned = setup(terminal())
      respawned.tmuxBackend.respawn.mockImplementationOnce(async () => { respawned.state.live = false; return { state: 'succeeded' } })
      expect(await respawned.restart('a1')).toEqual(changed)
      expect(releaseHold).not.toHaveBeenCalled()
      expect(respawned.deps.agentReconciler.releaseRoute).toHaveBeenCalledWith(routeKey)

      const cleared = setup(terminal())
      releaseHold.mockImplementationOnce(async () => { cleared.state.live = false })
      expect(await cleared.restart('a1')).toEqual(changed)
      expect(cleared.deps.registry.setActive).not.toHaveBeenCalled()
    })

    it('fails, without announcing, when the row vanished mid-restart', async () => {
      const run = setup(terminal(), {}, null)
      expect(await run.restart('a1')).toEqual({ ok: false, error: 'RESTART_FAILED', detail: 'agent vanished from the registry mid-restart' })
      expect(run.deps.announceSession).not.toHaveBeenCalled()
    })
  })

  describe('an engine', () => {
    it('comes back in the same pane with its launch, its permission and its conversation', async () => {
      const run = setup()
      expect(await run.restart('a1')).toEqual({ ok: true, session: agent(), resumed: true })
      expect(bypassPermissionFor).toHaveBeenCalledWith(agent(), expect.any(Function))
      expect(run.deps.liveBypassPermission).toHaveBeenCalledWith(agent())
      expect(run.deps.downgradedPermission).toHaveBeenCalledWith(agent(), true, 'restart', undefined)
      expect(run.deps.paneSwapDeps).toHaveBeenCalledWith(agent(), { backend: run.tmuxBackend, runtime }, { env: { GRID_KEY: 'k' } }, 'auto', expect.any(Function))
      const [target, bypass, swapDeps] = vi.mocked(restartAgent).mock.calls[0]
      expect(target).toEqual({ engine: 'claude', sessionId: 's1' })
      expect(bypass).toBe(true)
      expect(swapDeps).toMatchObject({ swap: true })
      expect(swapDeps.isCurrent?.()).toBe(true)
      expect(run.deps.refreshGridWebSearch).toHaveBeenCalledWith('a1', { env: { GRID_KEY: 'k' } })
      expect(probeGatewayRuntime).toHaveBeenCalledWith(newProcess)
      // Its command line, where a Codex or pi grid's address and model are: never its executable alone.
      expect(run.deps.registry.updateProcessIdentity).toHaveBeenCalledWith('a1', newProcess, 'none')
      expect(run.deps.registry.setActive).toHaveBeenCalledWith('a1', true)
      expect(releaseHold).toHaveBeenCalledWith(runtime)
      expect(run.deps.announceSession).toHaveBeenCalledWith(agent())
      expect(run.deps.refreshGridAssignment).toHaveBeenCalledWith(agent())
      expect(console.log).toHaveBeenCalledWith('[restart] a1 claude · resumed')
      expect(run.deps.agentReconciler.holdRoute).toHaveBeenCalledWith(routeKey, null)
      expect(run.deps.agentReconciler.releaseRoute).toHaveBeenCalledWith(routeKey)
    })

    it('without a mode or a yes, launches with no mode and no bypass; a fresh session on a grid says both', async () => {
      const grid = agent({ gridLaunch: { networkName: 'Home' } } as Partial<RegisteredSession>)
      const run = setup(grid, { downgradedPermission: vi.fn(async () => ({ bypassPermission: false })) as never })
      vi.mocked(restartAgent).mockResolvedValueOnce({ ok: true, resumed: false, processIdentity: newProcess } as never)
      expect(await run.restart('a1')).toEqual({ ok: true, session: grid, resumed: false })
      expect(run.deps.paneSwapDeps).toHaveBeenCalledWith(grid, { backend: run.tmuxBackend, runtime }, { env: { GRID_KEY: 'k' } }, null, expect.any(Function))
      expect(vi.mocked(restartAgent).mock.calls[0][1]).toBe(false)
      expect(console.log).toHaveBeenCalledWith('[restart] a1 claude · fresh session · grid Home')
    })

    it('says why the swap failed, and lets the route go', async () => {
      vi.mocked(restartAgent).mockResolvedValueOnce({ ok: false, detail: 'could not re-arm the pane' } as never)
      const run = setup()
      expect(await run.restart('a1')).toEqual({ ok: false, error: 'RESTART_FAILED', detail: 'could not re-arm the pane' })
      expect(run.deps.refreshGridWebSearch).not.toHaveBeenCalled()
      expect(run.deps.agentReconciler.releaseRoute).toHaveBeenCalledWith(routeKey)
    })

    it('stops at whichever step finds the operation overtaken', async () => {
      const built = setup()
      vi.mocked(built.deps.relaunchOverrides).mockImplementationOnce(async () => { built.state.live = false; return { ok: true, overrides: {} } as never })
      expect(await built.restart('a1')).toEqual(changed)
      expect(built.deps.agentReconciler.holdRoute).not.toHaveBeenCalled()

      const swapped = setup()
      vi.mocked(restartAgent).mockImplementationOnce(async () => { swapped.state.live = false; return { ok: true, resumed: true, processIdentity: newProcess } as never })
      expect(await swapped.restart('a1')).toEqual(changed)
      expect(swapped.deps.refreshGridWebSearch).not.toHaveBeenCalled()
      expect(swapped.deps.agentReconciler.releaseRoute).toHaveBeenCalledWith(routeKey)

      const probed = setup()
      vi.mocked(probeGatewayRuntime).mockImplementationOnce(async () => { probed.state.live = false; return { kind: 'none' } as never })
      expect(await probed.restart('a1')).toEqual(changed)
      expect(probed.deps.registry.updateProcessIdentity).not.toHaveBeenCalled()

      const cleared = setup()
      releaseHold.mockImplementationOnce(async () => { cleared.state.live = false })
      expect(await cleared.restart('a1')).toEqual(changed)
      expect(cleared.deps.announceSession).not.toHaveBeenCalled()
    })

    it('fails, without announcing, when the row vanished mid-restart', async () => {
      const run = setup(agent(), {}, null)
      expect(await run.restart('a1')).toEqual({ ok: false, error: 'RESTART_FAILED', detail: 'agent vanished from the registry mid-restart' })
      expect(run.deps.announceSession).not.toHaveBeenCalled()
      expect(run.deps.agentReconciler.releaseRoute).toHaveBeenCalledWith(routeKey)
    })
  })
})