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.

38.6 KB
Raw Blame
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterAll, afterEach, beforeEach, expect, it, vi } from 'vitest'
import { externalReservations, type ExternalResumeIntent } from '../../lib/externalResume.js'
import { externalUnavailable, type ExternalSessionAnswer, type ExternalSessionRequest } from '../../lib/externalSessionWire.js'
import type { RegisteredSession } from '../../lib/registry.js'
import { claudeProvider } from '../../lib/sessionSearch/externals/claude.js'
import type { ProcessView, RunningProcess } from '../../lib/sessionSearch/externals/types.js'
import { createExternalSessions } from '../../services/externalSessions.js'
import { createExternalResumes, type ExternalResumeDeps } from './externalResume.js'
import { stopExternalOwner } from './externalOwner.js'
import { moveHeldLine } from '../../lib/hostMove/moveAgent.js'
vi.mock('./externalOwner.js', () => ({ stopExternalOwner: vi.fn(async () => false) }))

const cwd = mkdtempSync(join(tmpdir(), 'external-resume-'))
afterAll(() => rmSync(cwd, { recursive: true, force: true }))
const controllers: ReturnType<typeof createExternalResumes>[] = []
beforeEach(() => { vi.useFakeTimers(); vi.setSystemTime(1000); vi.spyOn(console, 'warn').mockImplementation(() => {}) })
afterEach(() => { for (const controller of controllers.splice(0)) controller.stop(); vi.restoreAllMocks(); vi.useRealTimers() })
const fact = { sessionId: 'conversation', engine: 'claude' as const, cwd, title: 'Named conversation', origin: 'terminal' as const, mtime: 1, transcriptPath: join(cwd, 'conversation.jsonl') }
const processOwner = { pid: 7, engine: 'claude' as const, tty: '/dev/fixture-terminal', record: '/fixture/record' }
const free = (request: ExternalSessionRequest): ExternalSessionAnswer => ({ ok: true, request, session: { ...fact, sessionId: request.sessionId }, owner: null, generation: null, busy: false })
const held = (request: ExternalSessionRequest, busy = false): ExternalSessionAnswer => ({ ...free(request), owner: processOwner, generation: 'ps:1', busy,
  ...(busy ? { busyConfirmed: true } : {}) }) as ExternalSessionAnswer
const input = (extra = {}) => ({ engine: 'claude', cwd, bypassPermission: false, permissionMode: null, grid: null, codexHome: null, dsh: null,
  prompt: null, name: null, agent: null, resumeSessionId: 'conversation', takeOver: null, ...extra }) as Parameters<ReturnType<typeof createExternalResumes>['create']>[0]
const defer = <T>() => { let resolve!: (value: T) => void; const promise = new Promise<T>(yes => { resolve = yes }); return { promise, resolve } }

function setup() {
  const rows = new Map<string, RegisteredSession>(), panes = new Map<string, string>()
  let next = 0, cancelled = false
  const conflict: ExternalResumeDeps['registry']['externalConflict'] = (ids, except) => [...rows.values()].find(row => row.agentId !== except && externalReservations(row).some(id => ids.includes(id)))
  const registry: ExternalResumeDeps['registry'] = {
    byAgent: id => rows.get(id), list: () => [...rows.values()], externalConflict: conflict,
    openPendingAgent: vi.fn(given => {
      if (conflict(externalReservations({ sessionId: '', externalResume: given.externalResume }))) return null
      const row = { ...given, schemaVersion: 2, agentId: `agent-${++next}`, sessionId: '', registeredAt: 1,
        boundAt: null, processIdentity: null, active: false, launch: { state: 'held', service: 'search', detail: externalUnavailable().detail },
        tmuxPane: given.runtimes[0].backend === 'tmux' ? given.runtimes[0].paneId : '',
      } as RegisteredSession
      rows.set(row.agentId, row); return row
    }),
    setExternalResume: vi.fn((id, intent) => {
      const old = rows.get(id)
      if (!old || conflict(externalReservations({ sessionId: intent.phase === 'admitted' ? intent.session!.sessionId : '', externalResume: intent }), id)) return null
      const row = { ...old, externalResume: structuredClone(intent), ...(intent.phase === 'admitted' ? { sessionId: intent.session!.sessionId, cwd: intent.session!.cwd, resumeOnly: true as const } : {}) }
      rows.set(id, row); return row
    }),
    setLaunch: vi.fn((id, launch) => { const row = rows.get(id); if (!row) return null; row.launch = launch; return row }),
    finishExternalCancellation: vi.fn(id => rows.delete(id)),
  }
  let paneSequence = 0
  const create = vi.fn<NonNullable<ExternalResumeDeps['backend']>['create']>(async request => {
    if (request.current?.() === false) return { state: 'failed', dispatch: 'not_started', reason: 'cancelled' }
    const paneId = `%${++paneSequence}`
    panes.set(paneId, request.command!.at(-1)!)
    return { state: 'succeeded', dispatch: 'executed', runtime: { backend: 'tmux', paneId } }
  })
  const killHeld = vi.fn<NonNullable<NonNullable<ExternalResumeDeps['backend']>['killHeld']>>(async (runtime, token, current) => {
    if (!current() || panes.has(runtime.paneId) && panes.get(runtime.paneId) !== token) return { state: 'failed', dispatch: 'not_started', reason: 'pane changed' }
    panes.delete(runtime.paneId); return { state: 'succeeded', dispatch: 'executed' }
  })
  const inspect = vi.fn(async (request: ExternalSessionRequest) => free(request))
  const deps: ExternalResumeDeps = {
    registry, backend: { create, killHeld }, inspect, generation: () => 1,
    // Each pane's own backend: here the one adoption panes open on, while there is one.
    backendFor: vi.fn(() => deps.backend ?? undefined),
    stopped: vi.fn(() => []), cancelled: () => cancelled,
    waiting: vi.fn(async row => panes.get(row.tmuxPane) === row.externalResume?.token),
    preflight: vi.fn(async () => null), announce: vi.fn(), launch: vi.fn(),
    forget: vi.fn(id => { expect(rows.has(id)).toBe(false) }),
    stopOwner: vi.fn(async (_owner, control) => {
      if (!control.current() || !await control.same()) return false
      control.beforeSignal?.('SIGTERM'); control.afterSignal?.('SIGTERM')
      inspect.mockImplementation(async request => free(request))
      return true
    }),
  }
  const controller = createExternalResumes(deps); controllers.push(controller); controller.open()
  const stage = async (extra = {}) => {
    const result = await controller.create(input(extra))
    if (!result.ok) throw new Error(result.error)
    return result.session.agentId
  }
  return { deps, registry, rows, panes, inspect, create, killHeld, controller, stage, cancelWork: () => { cancelled = true } }
}

it('opens no conversation of an agent a stopped move may still run beside, by its id or an alias the search names', async () => {
  for (const [asked, aliases] of [['conversation', []], ['other', ['conversation']]] as const) {
    const test = setup()
    test.deps.heldConversation = (sessionId) => sessionId === 'conversation' ? 'a1' : null
    test.inspect.mockImplementation(async (request) => ({ ...free(request), session: { ...fact, sessionId: request.sessionId, aliases: [...aliases] } }) as ExternalSessionAnswer)
    const warn = vi.mocked(console.warn)
    warn.mockClear()
    expect(await test.controller.create(input({ resumeSessionId: asked }))).toMatchObject({ ok: false, error: 'AGENT_BUSY' })
    expect(test.create).not.toHaveBeenCalled()
    expect(test.rows.size).toBe(0)
    expect(warn).toHaveBeenCalledWith(moveHeldLine('a1'))
  }
})

it('persists an inert held intent during search outage, then admits and launches the exact conversation', async () => {
  const test = setup(); test.inspect.mockResolvedValue(externalUnavailable('Reader unavailable.'))
  const id = await test.stage({ name: 'Mine', codexHome: '/fixture/profile' })
  await test.controller.settled()
  expect(test.rows.get(id)).toMatchObject({ sessionId: '', cwd: null, defaultName: 'Mine', launch: { state: 'held', detail: 'Reader unavailable.' }, externalResume: { phase: 'waiting' } })
  expect(test.deps.preflight).not.toHaveBeenCalled(); expect(test.deps.launch).not.toHaveBeenCalled()
  test.inspect.mockImplementation(async request => free(request))
  await vi.advanceTimersByTimeAsync(2000); await test.controller.settled()
  expect(test.rows.get(id)).toMatchObject({ sessionId: 'conversation', cwd, resumeOnly: true, externalResume: { phase: 'admitted' } })
  expect(test.deps.launch).toHaveBeenCalledOnce()
  test.inspect.mockRejectedValue(new Error('search died again'))
  await vi.advanceTimersByTimeAsync(4000)
  expect(test.deps.launch).toHaveBeenCalledOnce()
  expect(await test.controller.cancel(test.rows.get(id)!)).toBe(false)
})

it('preserves known refusals before creating a pane, but holds thrown or malformed observations', async () => {
  for (const value of [externalUnavailable(), { nonsense: true }, new Error('search failed')]) {
    const test = setup()
    if (value instanceof Error) test.inspect.mockRejectedValue(value)
    else test.inspect.mockResolvedValue(value as ExternalSessionAnswer)
    const id = await test.stage(); await test.controller.settled()
    expect(test.rows.get(id)?.launch?.state).toBe('held')
  }
  const test = setup(); test.inspect.mockImplementation(async request => ({ ...free(request), session: null }))
  expect(await test.controller.create(input())).toMatchObject({ ok: false, error: 'SESSION_NOT_FOUND' })
  expect(test.create).not.toHaveBeenCalled()
  expect(await test.controller.create(input({ engine: 'terminal' }))).toMatchObject({ error: 'INVALID_SESSION' })
  test.deps.backend = null
  expect(await test.controller.create(input())).toMatchObject({ error: 'TMUX_UNAVAILABLE' })
  // The configured backend's own code where there is none (Windows: the pty host).
  test.deps.noBackendCode = 'PTY_HOST_UNAVAILABLE'
  expect(await test.controller.create(input())).toMatchObject({ error: 'PTY_HOST_UNAVAILABLE' })
  // A backend that cannot close a waiting pane by its token is still tmux's refusal, as before.
  test.deps.backend = { create: test.create } as never
  expect(await test.controller.create(input())).toMatchObject({ error: 'TMUX_UNAVAILABLE' })
})

it('holds busy waits outside the shared restore queue, pins ownership and journals actual interruption', async () => {
  const test = setup(); test.inspect.mockImplementation(async request => held(request, true))
  const id = await test.stage({ takeOver: 'wait' }); await test.controller.settled()
  expect(test.rows.get(id)?.launch).toMatchObject({ state: 'held', detail: expect.stringContaining('current turn') })
  expect(test.deps.stopOwner).not.toHaveBeenCalled()
  test.inspect.mockImplementation(async request => held(request, false))
  await vi.advanceTimersByTimeAsync(2000); await test.controller.settled()
  expect(test.rows.get(id)?.externalResume).toMatchObject({ phase: 'admitted', signal: 'sent' })
  expect(test.rows.get(id)?.externalResume?.continue).toBeUndefined()
  const now = setup(); now.inspect.mockImplementation(async request => held(request, true))
  const busy = await now.stage({ takeOver: 'now' }); await now.controller.settled()
  expect(now.rows.get(busy)?.externalResume).toMatchObject({ phase: 'admitted', signal: 'sent', continue: true })
})

it('never transfers takeover permission to a replacement owner or interrupts work under idle consent', async () => {
  const test = setup(), waiting = defer<null>()
  test.inspect.mockImplementation(async request => held(request))
  vi.mocked(test.deps.preflight).mockReturnValueOnce(waiting.promise)
  const id = await test.stage({ takeOver: 'idle' })
  await vi.waitFor(() => expect(test.deps.preflight).toHaveBeenCalled())
  test.inspect.mockImplementation(async request => held(request, true))
  waiting.resolve(null); await test.controller.settled()
  expect(test.rows.get(id)?.externalResume?.signal).toBeUndefined()
  expect(test.rows.get(id)?.externalResume?.phase).toBe('quitting')
  expect(test.deps.launch).not.toHaveBeenCalled()
  test.inspect.mockImplementation(async request => ({ ...held(request), owner: { ...processOwner, pid: 8 }, generation: 'ps:2' }) as ExternalSessionAnswer)
  await vi.advanceTimersByTimeAsync(2000); await test.controller.settled()
  expect(test.rows.get(id)?.launch).toMatchObject({ detail: expect.stringContaining('another process') })
  expect(test.deps.stopOwner).toHaveBeenCalledTimes(1)
})

it('checks the prepared executable after durably saving a signal intent before touching its original owner', async () => {
  const actual = await vi.importActual<typeof import('./externalOwner.js')>('./externalOwner.js')
  const test = setup(), kill = vi.fn()
  let nativeCurrent = true
  test.inspect.mockImplementation(async request => held(request))
  vi.mocked(test.deps.preflight).mockResolvedValue({ current: () => nativeCurrent })
  const save = vi.mocked(test.registry.setExternalResume).getMockImplementation()!
  vi.mocked(test.registry.setExternalResume).mockImplementation((id, intent) => {
    const row = save(id, intent)
    if (intent.signal === 'prepared') nativeCurrent = false
    return row
  })
  test.deps.stopOwner = (owner, control) => actual.stopExternalOwner(owner, {
    ...control, generation: () => 'ps:1', exists: () => true,
    job: async () => null, kill, sleep: async () => {},
  })
  const id = await test.stage({ takeOver: 'idle' }); await test.controller.settled()
  expect(kill).not.toHaveBeenCalled()
  expect(test.deps.launch).not.toHaveBeenCalled()
  expect(test.rows.get(id)?.externalResume).toMatchObject({ phase: 'quitting', signal: 'prepared' })
})

it('holds admission when native preparation changes during the last search read', async () => {
  const test = setup()
  let prepared = false, current = true
  vi.mocked(test.deps.preflight).mockImplementation(async () => { prepared = true; return { current: () => current } })
  test.inspect.mockImplementation(async request => { if (prepared) current = false; return free(request) })
  const id = await test.stage(); await test.controller.settled()
  expect(test.rows.get(id)?.launch).toMatchObject({ state: 'held', detail: expect.stringContaining('native launch') })
  expect(test.rows.get(id)?.externalResume?.phase).toBe('waiting')
  expect(test.deps.launch).not.toHaveBeenCalled()
})

it('does not take over a terminal when its completed native preparation is already obsolete', async () => {
  const test = setup(); test.inspect.mockImplementation(async request => held(request))
  vi.mocked(test.deps.preflight).mockResolvedValue({ current: () => false })
  const id = await test.stage({ takeOver: 'idle' }); await test.controller.settled()
  expect(test.deps.stopOwner).not.toHaveBeenCalled()
  expect(test.deps.launch).not.toHaveBeenCalled()
  expect(test.rows.get(id)?.launch?.state).toBe('held')
})

it('explicit takeover of unknown activity never manufactures a continuation prompt', async () => {
  const test = setup()
  test.inspect.mockImplementation(async request => ({ ...held(request), busy: true }))
  const id = await test.stage({ takeOver: 'now' }); await test.controller.settled()
  expect(test.rows.get(id)?.externalResume).toMatchObject({ phase: 'admitted', signal: 'sent' })
  expect(test.rows.get(id)?.externalResume?.continue).toBeUndefined()
})

it.each([null, 'idle', 'wait'] as const)('holds unknown activity with %s consent and names the missing evidence', async takeOver => {
  const test = setup(); test.inspect.mockImplementation(async request => ({ ...held(request), busy: true }))
  const id = await test.stage({ takeOver }); await test.controller.settled()
  expect(test.rows.get(id)?.launch).toMatchObject({ state: 'held', detail: expect.stringContaining('verify whether') })
  expect(test.deps.stopOwner).not.toHaveBeenCalled(); expect(test.deps.launch).not.toHaveBeenCalled()
  test.inspect.mockImplementation(async request => held(request, true))
  if (takeOver !== 'wait') expect(await test.controller.create(input({ resumeSessionId: 'another', takeOver }))).toMatchObject({ error: 'SESSION_BUSY_IN_TERMINAL' })
})

it.each(['pane', 'cancelled-pane', 'unavailable', 'missing'] as const)('withholds every signal when the last %s observation cannot prove ownership', async point => {
  const test = setup(); test.inspect.mockImplementation(async request => held(request))
  vi.mocked(test.deps.stopOwner!).mockImplementation(async (_owner, control) => {
    if (point === 'pane') vi.mocked(test.deps.waiting).mockResolvedValue(false)
    else if (point === 'cancelled-pane') vi.mocked(test.deps.waiting).mockImplementation(async () => { test.cancelWork(); return true })
    else test.inspect.mockImplementation(async request => point === 'unavailable' ? externalUnavailable() : { ...free(request), session: null })
    expect(await control.same()).toBe(false)
    return false
  })
  const id = await test.stage({ takeOver: 'idle' }); await test.controller.settled()
  expect(test.rows.get(id)?.externalResume?.signal).toBeUndefined()
  expect(test.deps.launch).not.toHaveBeenCalled()
})

it('rechecks reservations and metadata before signalling and before committing a free admission', async () => {
  for (const mode of ['reserved', 'archived', 'cwd', 'record', 'args', 'busy', 'unavailable'] as const) {
    const test = setup(), waiting = defer<null>()
    test.inspect.mockImplementation(async request => held(request))
    vi.mocked(test.deps.preflight).mockReturnValueOnce(waiting.promise)
    const id = await test.stage({ takeOver: 'idle' })
    await vi.waitFor(() => expect(test.deps.preflight).toHaveBeenCalled())
    if (mode === 'reserved') test.rows.set('other', { agentId: 'other', sessionId: 'conversation' } as RegisteredSession)
    else test.inspect.mockImplementation(async request => mode === 'unavailable' ? externalUnavailable() : ({ ...held(request),
      busy: mode === 'busy', session: { ...fact, ...(mode === 'archived' ? { archived: true } : {}),
        ...(mode === 'cwd' ? { cwd: join(cwd, 'changed') } : {}), ...(mode === 'record' ? { transcriptPath: '/fixture/other' } : {}),
        ...(mode === 'args' ? { launchArgs: ['--unapproved'] } : {}) } }) as ExternalSessionAnswer)
    waiting.resolve(null); await test.controller.settled()
    expect(test.rows.get(id)?.externalResume?.phase).not.toBe('admitted')
    expect(test.rows.get(id)?.externalResume?.signal).toBeUndefined()
    expect(test.deps.launch).not.toHaveBeenCalled()
    test.controller.stop()
  }
  for (const mode of ['owner', 'metadata', 'archived', 'unavailable'] as const) {
    const test = setup(), waiting = defer<null>()
    vi.mocked(test.deps.preflight).mockReturnValueOnce(waiting.promise)
    const id = await test.stage()
    await vi.waitFor(() => expect(test.deps.preflight).toHaveBeenCalled())
    test.inspect.mockImplementation(async request => mode === 'unavailable' ? externalUnavailable() : mode === 'owner' ? held(request) :
      ({ ...free(request), session: { ...fact, ...(mode === 'metadata' ? { transcriptPath: '/fixture/changed' } : { archived: true }) } }))
    waiting.resolve(null); await test.controller.settled()
    expect(test.rows.get(id)?.externalResume?.phase).toBe('waiting')
    expect(test.deps.launch).not.toHaveBeenCalled()
    test.controller.stop()
  }
})

it.each(['binding', 'stopped'] as const)('a new %s fences signals even after the final owner read, and holds without another service read', async kind => {
  const test = setup(); test.inspect.mockImplementation(async request => held(request))
  vi.mocked(test.deps.stopOwner!).mockImplementation(async (_owner, control) => {
    expect(await control.same()).toBe(true)
    if (kind === 'binding') test.rows.set('other', { agentId: 'other', sessionId: 'conversation' } as RegisteredSession)
    else vi.mocked(test.deps.stopped).mockReturnValue([{ sessionId: 'conversation' }])
    expect(control.current()).toBe(false)
    expect(() => control.beforeSignal?.('SIGTERM')).toThrow('Signal intent could not be saved')
    return false
  })
  const id = await test.stage({ takeOver: 'idle' }); await test.controller.settled()
  expect(test.rows.get(id)?.externalResume?.signal).toBeUndefined()
  test.inspect.mockClear()
  await vi.advanceTimersByTimeAsync(4000); await test.controller.settled()
  expect(test.inspect).not.toHaveBeenCalled()
  expect(test.rows.get(id)?.launch).toMatchObject({ state: 'held', detail: expect.stringContaining('another harness') })
  expect(test.deps.launch).not.toHaveBeenCalled()
})

it('Stop cancels a slow read without waiting, closes only its inert pane and durably removes before forgetting', async () => {
  const test = setup(), reading = defer<ExternalSessionAnswer>()
  test.inspect.mockResolvedValueOnce(externalUnavailable()).mockReturnValueOnce(reading.promise)
  const id = await test.stage()
  await vi.waitFor(() => expect(test.inspect).toHaveBeenCalledTimes(2))
  expect(await test.controller.cancel(test.rows.get(id)!)).toBe(true)
  expect(test.registry.finishExternalCancellation).toHaveBeenCalledWith(id)
  expect(test.deps.forget).toHaveBeenCalledWith(id)
  reading.resolve(free({ sessionId: 'conversation', engine: 'claude' })); await test.controller.settled()
  expect(test.rows.size).toBe(0); expect(test.deps.launch).not.toHaveBeenCalled(); expect(test.deps.stopOwner).not.toHaveBeenCalled()
})

it('keeps cancellation durable when the pane was replaced, and cleans it after a crash without asking search', async () => {
  const test = setup(); test.inspect.mockResolvedValue(externalUnavailable())
  const id = await test.stage(); await test.controller.settled()
  const row = test.rows.get(id)!; test.panes.set(row.tmuxPane, 'replacement')
  await expect(test.controller.cancel(row)).rejects.toThrow('stays cancelled')
  expect(test.rows.get(id)?.externalResume?.phase).toBe('cancelled')
  test.inspect.mockClear(); test.controller.stop()
  test.panes.delete(row.tmuxPane)
  const reboot = createExternalResumes(test.deps); controllers.push(reboot); reboot.open(); await reboot.settled()
  expect(test.inspect).not.toHaveBeenCalled(); expect(test.rows.has(id)).toBe(false)
})

it('four held requests cannot starve a later free conversation', async () => {
  const test = setup(); test.inspect.mockImplementation(async request => request.sessionId.startsWith('busy') ? held(request, true) : free(request))
  for (let i = 0; i < 4; i++) await test.stage({ resumeSessionId: `busy-${i}`, takeOver: 'wait' })
  const ready = await test.stage({ resumeSessionId: 'free-later' })
  await vi.advanceTimersByTimeAsync(4000); await test.controller.settled()
  expect(test.rows.get(ready)?.externalResume?.phase).toBe('admitted')
  for (const row of test.rows.values()) if (row.agentId !== ready) expect(row.externalResume?.phase).toBe('waiting')
})

it('fences Stop, changed routes, permission changes, unexpected processes and a replaced waiting shell', async () => {
  for (const change of ['stop', 'route', 'permission', 'process', 'pane'] as const) {
    const test = setup(), waiting = defer<null>()
    vi.mocked(test.deps.preflight).mockReturnValueOnce(waiting.promise)
    const id = await test.stage()
    await vi.waitFor(() => expect(test.deps.preflight).toHaveBeenCalled())
    const row = test.rows.get(id)!
    if (change === 'stop') test.cancelWork()
    if (change === 'route') row.runtimes = [{ backend: 'tmux', paneId: '%99' }]
    if (change === 'permission') row.permissionMode = 'auto'
    if (change === 'process') row.processIdentity = { pid: 8, executable: 'other', startMarker: 'ps:2' }
    if (change === 'pane') test.panes.set(row.tmuxPane, 'replacement')
    waiting.resolve(null); await test.controller.settled()
    expect(test.deps.launch).not.toHaveBeenCalled()
    test.controller.stop()
  }
})

it('does no admission before readiness or after shutdown, including an already-running create read', async () => {
  const test = setup(), ready = createExternalResumes(test.deps); controllers.push(ready)
  expect(await ready.create(input())).toMatchObject({ error: 'CORE_NOT_READY' })
  ready.wake(); expect(test.create).not.toHaveBeenCalled()
  const reading = defer<ExternalSessionAnswer>(); test.inspect.mockReturnValue(reading.promise)
  const creating = test.controller.create(input()); await Promise.resolve()
  test.controller.stop(); reading.resolve(free({ sessionId: 'conversation', engine: 'claude' }))
  expect(await creating).toMatchObject({ error: 'CORE_NOT_READY' })
  expect(test.create).not.toHaveBeenCalled()
})

it('holds storage/preflight failures and known late refusals without launching or losing intent', async () => {
  for (const mode of ['storage', 'null-commit', 'preflight', 'throws', 'late-missing'] as const) {
    const test = setup()
    if (mode === 'storage') vi.mocked(test.registry.setExternalResume).mockImplementation(() => { throw new Error('disk full') })
    if (mode === 'null-commit') vi.mocked(test.registry.setExternalResume).mockReturnValue(null)
    if (mode === 'preflight') vi.mocked(test.deps.preflight).mockResolvedValue({ detail: 'Engine unavailable.' })
    if (mode === 'throws') vi.mocked(test.deps.preflight).mockRejectedValue(new Error('preparation unreadable'))
    if (mode === 'late-missing') test.inspect.mockImplementationOnce(async request => free(request)).mockImplementation(async request => ({ ...free(request), session: null }))
    const id = await test.stage(); await test.controller.settled()
    expect(test.rows.get(id)?.externalResume?.phase).toBe('waiting'); expect(test.deps.launch).not.toHaveBeenCalled()
    test.controller.stop()
  }
})

it('does not begin stopping an owner when the quitting journal cannot commit', async () => {
  const test = setup(); test.inspect.mockImplementation(async request => held(request))
  const save = test.registry.setExternalResume
  test.registry.setExternalResume = (id, intent) => intent.phase === 'quitting' ? null : save(id, intent)
  const id = await test.stage({ takeOver: 'idle' }); await test.controller.settled()
  expect(test.rows.get(id)?.externalResume?.phase).toBe('waiting')
  expect(test.deps.stopOwner).not.toHaveBeenCalled()
  expect(test.deps.launch).not.toHaveBeenCalled()
})

it('reserves stopped conversations before any pane exists and cleans up an allocation whose durable claim fails', async () => {
  const test = setup()
  vi.mocked(test.deps.stopped).mockReturnValue([{ sessionId: 'conversation' }])
  expect(await test.controller.create(input())).toMatchObject({ error: 'SESSION_IN_HARNESS' })
  expect(test.create).not.toHaveBeenCalled()
  vi.mocked(test.deps.stopped).mockReturnValue([])
  vi.mocked(test.registry.openPendingAgent).mockReturnValue(null)
  expect(await test.controller.create(input())).toMatchObject({ ok: false })
  expect(test.panes.size).toBe(0)
  expect(test.killHeld).toHaveBeenCalledTimes(3)
  expect(test.deps.launch).not.toHaveBeenCalled()
})

it('opens and cancels an adoption on a ptyhost pane through that pane\'s own backend', async () => {
  const test = setup(); test.inspect.mockResolvedValue(externalUnavailable())
  const pty = { backend: 'ptyhost' as const, instance: 'p1', paneId: '%3' }
  test.create.mockImplementationOnce(async request => {
    test.panes.set(pty.paneId, request.command!.at(-1)!)
    return { state: 'succeeded', dispatch: 'executed', runtime: pty }
  })
  const id = await test.stage(); await test.controller.settled()
  expect(test.rows.get(id)!.runtimes).toEqual([pty])
  const ptyKill = vi.fn(async (..._args: unknown[]) => ({ state: 'succeeded' as const, dispatch: 'executed' as const }))
  vi.mocked(test.deps.backendFor).mockImplementation(runtime => runtime.backend === 'ptyhost' ? { killHeld: ptyKill } : undefined)
  expect(await test.controller.cancel(test.rows.get(id)!)).toBe(true)
  expect(ptyKill).toHaveBeenCalledExactlyOnceWith(pty, test.rows.get(id)?.externalResume?.token ?? expect.any(String), expect.any(Function))
  expect(test.killHeld).not.toHaveBeenCalled()
  expect(test.deps.forget).toHaveBeenCalledWith(id)
})

it('refuses to cancel when any of its panes is on a backend that cannot close a held pane', async () => {
  const test = setup(); test.inspect.mockResolvedValue(externalUnavailable())
  const id = await test.stage(); await test.controller.settled()
  const row = test.rows.get(id)!
  row.runtimes = [...row.runtimes, { backend: 'ptyhost', instance: 'p1', paneId: '%3' }]
  vi.mocked(test.deps.backendFor).mockImplementation(runtime => runtime.backend === 'tmux' ? test.deps.backend! : { })
  await expect(test.controller.cancel(row)).rejects.toThrow('The waiting pane could not be verified.')
  expect(test.killHeld).not.toHaveBeenCalled()
  expect(test.rows.has(id)).toBe(true)
})

it('refuses every unverified cancellation boundary without forgetting or archiving its intent', async () => {
  for (const failure of ['changed', 'save', 'tmux', 'route', 'commit', 'replaced-during-close'] as const) {
    const test = setup(); test.inspect.mockResolvedValue(externalUnavailable())
    const id = await test.stage(); await test.controller.settled()
    const row = test.rows.get(id)!
    if (failure === 'save') vi.mocked(test.registry.setExternalResume).mockReturnValue(null)
    if (failure === 'tmux') test.deps.backend = null
    if (failure === 'route') row.runtimes = []
    if (failure === 'commit') vi.mocked(test.registry.finishExternalCancellation).mockReturnValue(false)
    if (failure === 'replaced-during-close') test.killHeld.mockImplementation(async () => {
      test.rows.get(id)!.runtimes = [{ backend: 'tmux', paneId: '%99' }]
      return { state: 'succeeded', dispatch: 'executed' }
    })
    await expect(test.controller.cancel(row, () => failure !== 'changed')).rejects.toThrow()
    expect(test.deps.forget).not.toHaveBeenCalled()
    expect(test.rows.has(id)).toBe(true)
    test.controller.stop()
  }
})

it('requires an inert pane before any observation and discards a check after Stop or a newer route', async () => {
  for (const kind of ['unverified', 'cancelled-during-check', 'process-already-found', 'no-longer-held', 'lost-row'] as const) {
    const test = setup(); test.inspect.mockResolvedValue(externalUnavailable())
    const id = await test.stage(); await test.controller.settled()
    const row = test.rows.get(id)!
    if (kind === 'process-already-found') row.processIdentity = { pid: 8, executable: 'fixture', startMarker: 'fixture' }
    if (kind === 'no-longer-held') row.launch = { state: 'starting' }
    if (kind === 'unverified' || kind === 'lost-row') vi.mocked(test.deps.waiting).mockResolvedValue(false)
    if (kind === 'lost-row') vi.mocked(test.registry.setLaunch).mockReturnValue(null)
    if (kind === 'cancelled-during-check') vi.mocked(test.deps.waiting).mockImplementation(async () => { test.cancelWork(); return true })
    test.inspect.mockClear()
    await vi.advanceTimersByTimeAsync(2000); await test.controller.settled()
    expect(test.inspect).not.toHaveBeenCalled()
    expect(test.deps.launch).not.toHaveBeenCalled()
    test.controller.stop()
  }
})

it('keeps exact signal intent and receipt failures from admitting an external conversation', async () => {
  for (const failure of ['before', 'after', 'cancel-before', 'cancel-then-false', 'cancel-then-true', 'kill'] as const) {
    const test = setup(); test.inspect.mockImplementation(async request => held(request))
    vi.mocked(test.deps.stopOwner!).mockImplementation(async (_owner, control) => {
      expect(await control.same()).toBe(true)
      if (failure === 'kill') { control.beforeSignal?.('SIGKILL'); control.afterSignal?.('SIGKILL'); return false }
      if (failure === 'cancel-then-false' || failure === 'cancel-then-true') { test.cancelWork(); return failure === 'cancel-then-true' }
      if (failure === 'before') vi.mocked(test.registry.setExternalResume).mockReturnValue(null)
      if (failure === 'cancel-before') test.cancelWork()
      control.beforeSignal?.('SIGTERM')
      if (failure === 'after') vi.mocked(test.registry.setExternalResume).mockReturnValue(null)
      control.afterSignal?.('SIGTERM')
      return true
    })
    const id = await test.stage({ takeOver: 'idle' }); await test.controller.settled()
    expect(test.rows.get(id)?.externalResume?.phase).toBe('quitting')
    expect(test.deps.launch).not.toHaveBeenCalled()
    if (failure === 'after') expect(test.rows.get(id)?.externalResume?.signal).toBe('prepared')
    test.controller.stop()
  }
  const test = setup(); test.inspect.mockImplementation(async request => held(request)); test.deps.stopOwner = undefined
  await test.stage({ takeOver: 'idle' }); await test.controller.settled()
  expect(stopExternalOwner).toHaveBeenCalled()
  expect(test.deps.launch).not.toHaveBeenCalled()
})

it('fences the last read, the last pane check, and a failed final durable admission', async () => {
  for (const point of ['read', 'pane', 'commit'] as const) {
    const test = setup()
    let calls = 0
    test.inspect.mockImplementation(async request => { if (++calls === 3 && point === 'read') test.cancelWork(); return free(request) })
    let paneChecks = 0
    vi.mocked(test.deps.waiting).mockImplementation(async () => { if (++paneChecks === 2 && point === 'pane') test.cancelWork(); return true })
    const persist = test.registry.setExternalResume
    if (point === 'commit') test.registry.setExternalResume = (id, intent) => intent.phase === 'admitted' ? null : persist(id, intent)
    await test.stage(); await test.controller.settled()
    expect(test.deps.launch).not.toHaveBeenCalled()
    test.controller.stop()
  }
})

it('limits concurrent intents after reboot and lets later ones proceed after the reads finish', async () => {
  const test = setup(); test.inspect.mockResolvedValue(externalUnavailable())
  const id = await test.stage(); await test.controller.settled(); test.controller.stop()
  const sample = test.rows.get(id)!
  for (let i = 1; i <= 5; i++) {
    const agentId = `saved-${i}`, pane = `%${i + 10}`
    const intent = { ...sample.externalResume!, request: { engine: 'claude' as const, sessionId: `saved-conversation-${i}` } }
    test.rows.set(agentId, { ...sample, agentId, tmuxPane: pane, runtimes: [{ backend: 'tmux', paneId: pane }], externalResume: intent })
    test.panes.set(pane, intent.token)
  }
  const reads: Array<() => void> = []
  test.inspect.mockClear().mockImplementation(request => new Promise(resolve => { reads.push(() => resolve(free(request))) }))
  const reboot = createExternalResumes(test.deps); controllers.push(reboot); reboot.open()
  await vi.waitFor(() => expect(reads.length).toBe(4))
  reboot.wake()
  expect(test.inspect).toHaveBeenCalledTimes(4)
  test.inspect.mockImplementation(async request => free(request))
  for (const finish of reads) finish()
  await reboot.settled()
  await vi.advanceTimersByTimeAsync(2000); await reboot.settled()
  expect([...test.rows.values()].every(row => row.externalResume?.phase === 'admitted')).toBe(true)
})

it('ignores a late preparation exception after shutdown', async () => {
  const test = setup()
  let reject!: (error: Error) => void
  vi.mocked(test.deps.preflight).mockImplementation(() => new Promise((_resolve, no) => { reject = no }))
  const id = await test.stage()
  await vi.waitFor(() => expect(test.deps.preflight).toHaveBeenCalled())
  test.controller.stop(); reject(new Error('late failure')); await test.controller.settled()
  expect(test.rows.get(id)?.externalResume?.phase).toBe('waiting')
  expect(test.deps.launch).not.toHaveBeenCalled()
})

it.each(['idle', 'wait'] as const)('does not signal a turn that starts during the pane probe under %s consent', async takeOver => {
  const test = setup(), pane = defer<boolean>()
  test.inspect.mockImplementation(async request => held(request, false))
  vi.mocked(test.deps.waiting).mockResolvedValueOnce(true).mockReturnValueOnce(pane.promise)
  const id = await test.stage({ takeOver })
  await vi.waitFor(() => expect(test.deps.waiting).toHaveBeenCalledTimes(2))
  test.inspect.mockImplementation(async request => held(request, true))
  pane.resolve(true); await test.controller.settled()
  expect(test.rows.get(id)?.externalResume).toMatchObject({ phase: 'quitting' })
  expect(test.rows.get(id)?.externalResume?.signal).toBeUndefined()
  expect(test.deps.launch).not.toHaveBeenCalled()
})

it('does not admit a conversation acquired externally while its final pane probe waits', async () => {
  const test = setup(), pane = defer<boolean>()
  vi.mocked(test.deps.waiting).mockResolvedValueOnce(true).mockReturnValueOnce(pane.promise)
  const id = await test.stage()
  await vi.waitFor(() => expect(test.deps.waiting).toHaveBeenCalledTimes(2))
  test.inspect.mockImplementation(async request => held(request, false))
  pane.resolve(true); await test.controller.settled()
  expect(test.rows.get(id)?.externalResume?.phase).toBe('waiting')
  expect(test.rows.get(id)?.sessionId).toBe('')
  expect(test.deps.launch).not.toHaveBeenCalled()
})

it('launches a conversation held behind a record-less Claude in its folder once that process goes, and never waits on one elsewhere', async () => {
  // CLI 0.3.70: "[restore] held · search · launched 0 of 4 · 4 still waiting" behind two old TUIs with no record.
  // The real search reader answers here, over a private Claude home and a fake process table.
  const home = mkdtempSync(join(tmpdir(), 'external-resume-claude-'))
  try {
    const project = join(home, 'project'), elsewhere = join(home, 'elsewhere'), conversation = '33333333-3333-4333-8333-333333333333'
    mkdirSync(project); mkdirSync(elsewhere); mkdirSync(join(home, 'projects', 'project'), { recursive: true })
    writeFileSync(join(home, 'projects', 'project', `${conversation}.jsonl`), JSON.stringify({
      type: 'user', sessionId: conversation, cwd: project, entrypoint: 'cli', message: { role: 'user', content: 'Fixture' } }) + '\n')
    const tui = (pid: number): RunningProcess => ({ pid, ppid: 1, executable: 'claude', args: 'claude --append-system-prompt "be brief"', started: 1 })
    let processes = [tui(201), tui(202)]
    const cwds = new Map([[201, elsewhere], [202, project]])
    const reader = createExternalSessions({ providers: [claudeProvider({ projectsDir: join(home, 'projects'), home })], generation: () => null,
      open: { ttys: async () => new Map(), harnessTtys: async () => new Set(), view: (): ProcessView => {
        const listed = processes
        return { list: async () => listed, alive: pid => listed.some(row => row.pid === pid), openFiles: async () => new Map(),
          openFilesOf: async () => new Map(), cwds: async pids => new Map([...cwds].filter(([pid]) => pids.includes(pid))) }
      } } })
    const test = setup(); test.inspect.mockImplementation(request => reader.inspect(request))
    const id = await test.stage({ resumeSessionId: conversation, cwd: project })
    await test.controller.settled()
    expect(test.rows.get(id)).toMatchObject({ launch: { state: 'held', service: 'search', detail: "The conversation's current owner could not be verified." },
      externalResume: { phase: 'waiting' } })
    expect(test.deps.launch).not.toHaveBeenCalled()
    // The one in the conversation's folder quits; the one elsewhere runs on and holds nothing here.
    processes = [tui(201)]
    await vi.advanceTimersByTimeAsync(2000); await test.controller.settled()
    expect(test.rows.get(id)).toMatchObject({ sessionId: conversation, cwd: project, resumeOnly: true, externalResume: { phase: 'admitted' } })
    expect(test.deps.launch).toHaveBeenCalledOnce()
    await vi.advanceTimersByTimeAsync(4000)
    expect(test.deps.launch).toHaveBeenCalledOnce()
  } finally { rmSync(home, { recursive: true, force: true }) }
})