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.

29.7 KB
Raw Blame
import { mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, utimesSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { basename, dirname, join } from 'node:path'
import { afterEach, beforeEach, expect, it, vi } from 'vitest'

const faults = vi.hoisted(() => ({
  copied: undefined as (() => void | Promise<void>) | undefined,
  inspectedCheckpoint: undefined as (() => void) | undefined,
  openingSource: undefined as (() => () => void) | undefined,
  sourceFailure: undefined as 'open' | 'stat' | 'read' | 'close' | undefined,
}))
vi.mock('node:fs/promises', async original => {
  const actual = await original<typeof import('node:fs/promises')>()
  return { ...actual, copyFile: async (...args: Parameters<typeof actual.copyFile>) => {
    const restore = faults.openingSource?.()
    try { await actual.copyFile(...args) } finally { restore?.() }
    await faults.copied?.()
  }, open: async (...args: Parameters<typeof actual.open>) => {
    const source = String(args[0]).endsWith('.jsonl')
    if (source && faults.sourceFailure === 'open') throw Error('Source open unavailable')
    const restore = source ? faults.openingSource?.() : undefined
    const handle = await actual.open(...args).finally(() => restore?.())
    if (source) {
      const stat = handle.stat.bind(handle), read = handle.read.bind(handle), close = handle.close.bind(handle)
      handle.close = async () => {
        await close()
        if (faults.sourceFailure === 'close') throw Error('Source close unavailable')
      }
      handle.stat = (async (...values: Parameters<typeof stat>) => {
        if (faults.sourceFailure === 'stat') throw Error('Source stat unavailable')
        return stat(...values)
      }) as typeof handle.stat
      handle.read = (async (...values: Parameters<typeof read>) => {
        if (faults.sourceFailure === 'read') throw Error('Source read unavailable')
        return read(...values)
      }) as typeof handle.read
    }
    if (String(args[0]).endsWith('.history.tmp')) {
      const write = handle.write.bind(handle)
      handle.write = (async (...values: Parameters<typeof write>) => {
        const result = await write(...values)
        await faults.copied?.()
        return result
      }) as typeof handle.write
    }
    return handle
  }, lstat: async (...args: Parameters<typeof actual.lstat>) => {
    const result = await actual.lstat(...args)
    if (String(args[0]).endsWith('.history')) faults.inspectedCheckpoint?.()
    return result
  } }
})
vi.mock('node:child_process', () => {
  const forbidden = () => { throw Error('Host binaries are forbidden in the transcript authority fixture') }
  return { exec: forbidden, execSync: forbidden, execFile: forbidden, execFileSync: forbidden,
    spawn: forbidden, spawnSync: forbidden, fork: forbidden }
})
vi.mock('./loginShellEnv.js', () => ({ loginShellEnvironment: () => ({}) }))
vi.mock('./bootId.js', async original => ({ ...await original<object>(), currentBootId: () => 'fixture-boot', bootChanged: () => false }))
vi.mock('./processLiveness.js', async original => ({ ...await original<object>(),
  processLockIdentity: () => ({ startMarker: 'fixture-start', generationMarker: 'fixture-generation' }), lockOwnerAlive: () => true,
}))
vi.mock('./deleteAgentFallback.js', () => ({ checkPidRuntime: vi.fn(), terminateDeletedAgent: vi.fn(async () => 'gone') }))
vi.mock('./engineLaunch.js', async original => ({ ...await original<object>(),
  buildEngineLaunchArgv: () => ['<engine>'], dropPermissionFlagIfUnsupported: vi.fn(),
}))
vi.mock('./engineBin.js', async original => ({ ...await original<object>(), enginePathOverride: () => '<engine>' }))
vi.mock('../core/engines/cursorTasks.js', () => ({ removePendingCursorTasks: vi.fn(async () => {}) }))

const A = 'aaaaaaaa-1111-4111-8111-aaaaaaaaaaaa', B = 'bbbbbbbb-2222-4222-8222-bbbbbbbbbbbb'
let root: string, transcript: string, directory: string
let registry: typeof import('./registry.js')['registry']
let row: import('./registry.js').RegisteredSession
let capture: typeof import('./captureResumeIdentity.js')['captureResumeIdentity']
let checkpoints: import('./sessionCheckpoint.js').SessionCheckpointStore
const header = (id = A) => JSON.stringify({ type: 'session_meta', payload: { id, cwd: root, source: 'cli' } }) + '\n'
const files = () => Object.fromEntries(readdirSync(directory).map(name => [name, readFileSync(join(directory, name), 'utf8')]))

beforeEach(async () => {
  root = realpathSync(mkdtempSync(join(tmpdir(), 'control-transcript-')))
  faults.copied = undefined; faults.inspectedCheckpoint = undefined; faults.openingSource = undefined; faults.sourceFailure = undefined
  for (const name of ['HOME', 'ADAPTER_DATA_DIR', 'ADAPTER_RUNTIME_DIR', 'CODEX_HOME', 'CLAUDE_CONFIG_DIR',
    'PI_HOME', 'XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'XDG_STATE_HOME']) {
    const path = join(root, name); mkdirSync(path, { recursive: true, mode: 0o700 }); vi.stubEnv(name, path)
  }
  vi.stubEnv('USERPROFILE', join(root, 'HOME'))
  vi.stubEnv('CLAUDE_PROJECTS_DIR', join(root, 'CLAUDE_CONFIG_DIR', 'projects'))
  mkdirSync(join(root, 'CODEX_HOME', 'sessions'))
  writeFileSync(join(root, 'ADAPTER_DATA_DIR', 'engine-homes.json'), '{}')
  transcript = join(root, 'CODEX_HOME', 'sessions', `rollout-${A}.jsonl`)
  writeFileSync(transcript, header())
  directory = join(root, 'checkpoints')
  vi.resetModules()
  vi.mocked((await import('./deleteAgentFallback.js')).terminateDeletedAgent).mockReset().mockResolvedValue('gone')
  ;({ registry } = await import('./registry.js'))
  capture = (await import('./captureResumeIdentity.js')).captureResumeIdentity
  checkpoints = new (await import('./sessionCheckpoint.js')).SessionCheckpointStore(directory)
  row = registry.openPendingAgent({ engine: 'codex', cwd: root, runtimes: [{ backend: 'tmux', paneId: '%1' }] })!
  Object.assign(row, { sessionId: A, transcriptPath: transcript,
    processIdentity: { pid: 7001, executable: '<codex>', startMarker: 'fixture-start' } })
  registry.flush()
})
afterEach(() => {
  faults.copied = undefined; faults.inspectedCheckpoint = undefined; faults.openingSource = undefined; faults.sourceFailure = undefined
  vi.restoreAllMocks(); vi.unstubAllEnvs(); vi.resetModules()
  rmSync(root, { recursive: true, force: true })
})

it.each(['different conversation', 'partial header'])('holds capture of a saved %s before Stop can archive it', async state => {
  writeFileSync(transcript, state === 'partial header' ? '{partial' : header(B))
  await expect(capture(row)).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
  expect(registry.byAgent(row.agentId)?.sessionId).toBe(A)
})

it.each(['different conversation', 'partial header', 'unreadable catalog'])('keeps the prior checkpoint and draft when its source has %s', async state => {
  await checkpoints.save(row, { screen: 'Original unsent draft' })
  const before = files()
  if (state === 'unreadable catalog') writeFileSync(join(root, 'ADAPTER_DATA_DIR', 'engine-homes.json'), '{partial')
  else writeFileSync(transcript, state === 'partial header' ? '{partial' : header(B))
  await expect(checkpoints.save(row, { screen: 'Must not replace the prior draft' })).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
  expect(files()).toEqual(before)
})

it.each(['header', 'catalog'])('rechecks the native %s after asynchronous copying before publishing a checkpoint', async changed => {
  utimesSync(transcript, 1, 1)
  await checkpoints.save(row, { screen: 'Original draft' })
  const before = files()
  // Force another checkpoint without changing its native header or identity.
  writeFileSync(transcript, header() + '{"type":"event_msg"}\n')
  utimesSync(transcript, 2, 2)
  faults.copied = () => {
    if (changed === 'catalog') writeFileSync(join(root, 'ADAPTER_DATA_DIR', 'engine-homes.json'), '{partial')
    else {
      writeFileSync(transcript, header(B) + '{"type":"event_msg"}\n')
      // Same inode, byte count and timestamp do not prove the same native conversation.
      utimesSync(transcript, 2, 2)
    }
  }
  await expect(checkpoints.save(row, { screen: 'New draft' })).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
  expect(files()).toEqual(before)
})

it('rechecks native identity after inspecting an otherwise reusable checkpoint', async () => {
  await checkpoints.save(row, { screen: 'Original draft' })
  const before = files()
  faults.inspectedCheckpoint = () => writeFileSync(transcript, header(B))
  await expect(checkpoints.save(row, { screen: 'New draft' })).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
  expect(files()).toEqual(before)
})

it('holds a source descriptor opened through an ancestor that moves away and back', async () => {
  await checkpoints.save(row, { screen: 'Original draft' })
  const before = files()
  writeFileSync(transcript, header() + '{"turn":"new content"}\n')
  const sourceDirectory = dirname(transcript), parked = sourceDirectory + '-parked', other = sourceDirectory + '-other'
  mkdirSync(other)
  writeFileSync(join(other, basename(transcript)), header() + '{"turn":"wrong file!"}\n')
  faults.openingSource = () => {
    faults.openingSource = undefined
    renameSync(sourceDirectory, parked); renameSync(other, sourceDirectory)
    return () => { renameSync(sourceDirectory, other); renameSync(parked, sourceDirectory) }
  }
  await expect(checkpoints.save(row, { screen: 'New draft' })).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
  expect(files()).toEqual(before)
  expect(readFileSync(transcript, 'utf8')).toContain('new content')
})

it('copies a newly appended body rather than reusing history inspected before an await', async () => {
  await checkpoints.save(row)
  faults.inspectedCheckpoint = () => {
    faults.inspectedCheckpoint = undefined
    writeFileSync(transcript, header() + '{"turn":"flushed during checkpoint lookup"}\n')
  }
  await checkpoints.save(row)
  expect(Object.values(files()).some(contents => contents === readFileSync(transcript, 'utf8'))).toBe(true)
})

it('does not reuse same-sized history rewritten in place with a restored modification time', async () => {
  writeFileSync(transcript, header() + '{"turn":"first"}\n')
  utimesSync(transcript, 1, 1)
  await checkpoints.save(row)
  writeFileSync(transcript, header() + '{"turn":"later"}\n')
  utimesSync(transcript, 1, 1)
  await checkpoints.save(row)
  expect(Object.values(files()).some(contents => contents === readFileSync(transcript, 'utf8'))).toBe(true)
})

it.each(['open', 'stat', 'read', 'close'] as const)('holds an unavailable source %s without replacing saved history or draft', async stage => {
  await checkpoints.save(row, { screen: 'Original draft' })
  const before = files()
  writeFileSync(transcript, header() + '{"turn":"new content"}\n')
  faults.sourceFailure = stage
  await expect(checkpoints.save(row, { screen: 'New draft' })).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
  expect(files()).toEqual(before)
})

it('keeps the prior draft if closing an otherwise reusable source descriptor fails', async () => {
  await checkpoints.save(row, { screen: 'Original draft' })
  const before = files()
  faults.sourceFailure = 'close'
  await expect(checkpoints.save(row, { screen: 'New draft' })).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
  expect(files()).toEqual(before)
})

it('keeps a fresh lookup budget after a slow copy instead of expiring otherwise valid history', async () => {
  faults.copied = async () => { await new Promise(resolve => setTimeout(resolve, 350)) }
  await expect(checkpoints.save(row, { screen: 'The unsent draft' })).resolves.toBeUndefined()
  expect(Object.values(files()).some(contents => contents === header())).toBe(true)
})

it('refuses a physically replaced transcript even when its new header names the same conversation', async () => {
  const { controlTranscriptEvidence } = await import('../engines/transcriptBindings.js')
  const proof = controlTranscriptEvidence('codex', A, transcript)
  const replacement = transcript + '.replacement'
  writeFileSync(replacement, header()); renameSync(replacement, transcript)
  expect(() => proof.verify()).toThrow('replaced during the operation')
})

it('accepts an appended body with a fresh complete header after a long wait', async () => {
  const { controlTranscriptEvidence } = await import('../engines/transcriptBindings.js')
  const proof = controlTranscriptEvidence('codex', A, transcript)
  await new Promise(resolve => setTimeout(resolve, 350))
  writeFileSync(transcript, header() + '{"type":"event_msg"}\n')
  expect(() => proof.verify()).not.toThrow()
})

it.each(['claude', 'pi'] as const)('eagerly checks the saved %s opening without a worker', async engine => {
  const folder = engine === 'claude' ? join(root, 'CLAUDE_CONFIG_DIR', 'projects', 'fixture')
    : join(root, 'PI_HOME', 'agent', 'sessions', 'fixture')
  mkdirSync(folder, { recursive: true })
  transcript = join(folder, `${A}.jsonl`)
  const opening = (id: string, extra: object = {}) => JSON.stringify(engine === 'claude'
    ? { type: 'user', sessionId: id, cwd: root, isSidechain: false, ...extra }
    : { type: 'session', id, cwd: root, ...extra }) + '\n'
  Object.assign(row, { engine, transcriptPath: transcript })
  writeFileSync(transcript, opening(A))
  await checkpoints.save(row, { screen: 'Original draft' })
  const before = files()
  for (const contents of [opening(B), '{partial', opening(A, engine === 'claude' ? { isSidechain: true } : { cwd: dirname(root) })]) {
    writeFileSync(transcript, contents)
    await expect(capture(row)).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
    await expect(checkpoints.save(row, { screen: 'New draft' })).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
    expect(files()).toEqual(before)
  }
  writeFileSync(transcript, (engine === 'claude' ? '{"type":"queue-operation"}\n' : '') + opening(A))
  await expect(capture(row)).resolves.toMatchObject({ sessionId: A, transcriptPath: transcript })
})

it.each(['claude', 'pi'] as const)('does not let a different physical %s file lend its valid opening to a saved path', async engine => {
  const { NativeFiles } = await import('../engines/kit/nativeFiles.js')
  const { controlTranscriptEvidence } = await import('../engines/transcriptBindings.js')
  const parent = engine === 'claude' ? join(root, 'CLAUDE_CONFIG_DIR', 'projects') : join(root, 'PI_HOME', 'agent', 'sessions')
  const folder = join(parent, 'source'), parked = join(parent, 'parked'), other = join(parent, 'other')
  mkdirSync(folder, { recursive: true }); mkdirSync(other)
  const opening = (id: string) => JSON.stringify(engine === 'claude'
    ? { type: 'user', sessionId: id, cwd: root, isSidechain: false } : { type: 'session', id, cwd: root }) + '\n'
  const path = join(folder, `${A}.jsonl`)
  writeFileSync(path, opening(B)); writeFileSync(join(other, `${A}.jsonl`), opening(A))
  const readOpening = NativeFiles.prototype.opening, verify = NativeFiles.prototype.verify
  const swapped = new Set<import('../engines/kit/nativeFiles.js').NativeFiles>()
  let moved = false
  const restore = () => { if (moved) { renameSync(folder, other); renameSync(parked, folder); moved = false } }
  vi.spyOn(NativeFiles.prototype, 'opening').mockImplementation(function (this: import('../engines/kit/nativeFiles.js').NativeFiles, selected, rule) {
    renameSync(folder, parked); renameSync(other, folder); moved = true; swapped.add(this)
    return readOpening.call(this, selected, rule)
  })
  vi.spyOn(NativeFiles.prototype, 'verify').mockImplementation(function (this: import('../engines/kit/nativeFiles.js').NativeFiles, selected) {
    verify.call(this, selected)
    if (swapped.has(this)) restore()
  })
  try { expect(() => controlTranscriptEvidence(engine, A, path, undefined, root)).toThrow(expect.objectContaining({ code: 'IDENTITY_UNAVAILABLE' })) }
  finally { restore() }
  expect(readFileSync(path, 'utf8')).toBe(opening(B))
})

it('preserves a repaired parent through Stop and the final real forget archive', async () => {
  const { createStopAgentService } = await import('./stopAgentService.js')
  const { createForgetSession } = await import('../core/agents/forget.js')
  const { StoppedAgentStore } = await import('./stoppedAgents.js')
  const { AgentRestartCoordinator } = await import('./restartAgent.js')
  const parent = transcript, child = join(dirname(parent), `rollout-${B}.jsonl`)
  writeFileSync(child, JSON.stringify({ type: 'session_meta', payload: { id: B, cwd: root,
    source: { subagent: { thread_spawn: { parent_thread_id: A } } } } }) + '\n')
  row.transcriptPath = child
  const stopped = new StoppedAgentStore(join(root, 'stopped'))
  const forget = createForgetSession({ registry, stoppedAgents: stopped, syncRecapPool: vi.fn(), normalizers: { forget: vi.fn() },
    forgetAttach: vi.fn(), turnStartedAt: new Map(), prompts: new Map(), neverFoldedHistory: new Set(), replayedFirstTurn: new Set(),
    clearAgyIdleWatch: vi.fn(), cursorDiscovery: { remove: vi.fn() }, cursorSubagents: { forget: vi.fn() },
    runtimeProfiles: { forget: vi.fn() }, watcher: { removeSession: vi.fn(async () => {}) },
    stopHeartbeat: vi.fn(), input: { forget: vi.fn() }, deviceInput: { forget: vi.fn() },
    detachDsh: vi.fn(), mirror: { forget: vi.fn() }, clients: { send: vi.fn(), sendCommander: vi.fn() },
    dataDir: join(root, 'ADAPTER_DATA_DIR') })
  const stop = createStopAgentService({ registry, stoppedAgents: stopped, restartJobs: new AgentRestartCoordinator(),
    stopJobs: new Map(), backendFor: () => ({ kill: vi.fn(async () => ({ state: 'succeeded' as const, dispatch: 'executed' as const })) }),
    agentReconciler: { suppress: vi.fn(), holdRoute: vi.fn(), releaseRoute: vi.fn(), trigger: vi.fn(async () => {}) },
    forgetSession: forget, markDeleted: vi.fn(), clearDeleted: vi.fn(), stopNative: async () => {} })
  const checkpoint = async (session: typeof row) => {
    expect(session.transcriptPath).toBe(parent)
    stopped.save({ ...row, title: 'A hook saved the stale child path' })
  }
  // Other Linux shard fixtures create/remove siblings under /tmp. The native
  // reader correctly refuses an ancestor changed during enumeration; retry the
  // untouched Stop just as its caller can, rather than treating that hold as loss.
  for (let attempt = 0; ; attempt++) {
    try { await stop(row.agentId, { checkpoint }); break }
    catch (error) {
      if (attempt >= 2) throw error
      expect(error).toMatchObject({ code: 'IDENTITY_UNAVAILABLE',
        message: 'Conversation identity is held: a binding directory or ancestor changed during enumeration.' })
      expect(registry.byAgent(row.agentId)?.sessionId).toBe(A)
      await new Promise(done => setTimeout(done, 10))
    }
  }
  expect(registry.byAgent(row.agentId)).toBeUndefined()
  expect(stopped.get(row.agentId)).toMatchObject({ active: false, sessionId: A, transcriptPath: parent })
})

it('retains a typed Stop hold when the native broker contains a failed grant check', async () => {
  const { createNativeControls } = await import('../core/engines/nativeControls.js')
  const { engineNativeControlRequests } = await import('../engines/worker/nativeControlRequests.js')
  const { launch } = await import('../engines/codex/launch.js')
  const { argvTokens } = await import('./processTable.js')
  const { createStopAgentService } = await import('./stopAgentService.js')
  const { StoppedAgentStore } = await import('./stoppedAgents.js')
  const { AgentRestartCoordinator } = await import('./restartAgent.js')
  const { terminateDeletedAgent } = await import('./deleteAgentFallback.js')
  const mutation = vi.fn()
  let core!: ReturnType<typeof createNativeControls>
  const requests = engineNativeControlRequests('codex', { load: async () => ({ activity: async () => 'working',
    stop: async (_conversation, host) => { writeFileSync(transcript, header(B)); if (await host.current()) mutation() },
    recover: async () => {}, close: () => {} }), recycle: vi.fn(),
    query: async (query, payload) => core.answer('engine-codex', query, payload) ?? { error: 'DENIED' } })
  core = createNativeControls({ call: async (_service, method, payload) =>
    requests[method]({ ...payload, requestId: 'fixture-request' }, { owner: true, local: true }) as Promise<Record<string, unknown>>,
    handles: () => true, inline: () => undefined, servers: { codex: launch.sharedServer! }, home: () => join(root, 'CODEX_HOME'),
    rows: async () => [{ ...row.processIdentity!, parentPid: 1, args: `codex resume ${A}` },
      { pid: 90, parentPid: 1, executable: 'codex', startMarker: 'server-birth', args: 'codex app-server' }],
    argv: argvTokens, readFile: async () => JSON.stringify({ pid: 90, processStartTime: 'server-birth' }), log: vi.fn() })
  core.connected('engine-codex')
  const kill = vi.fn(async () => ({ state: 'succeeded' as const, dispatch: 'executed' as const })), forget = vi.fn()
  const stop = createStopAgentService({ registry, stoppedAgents: new StoppedAgentStore(join(root, 'stopped')),
    restartJobs: new AgentRestartCoordinator(), stopJobs: new Map(), backendFor: () => ({ kill }),
    agentReconciler: { suppress: vi.fn(), holdRoute: vi.fn(), releaseRoute: vi.fn(), trigger: vi.fn(async () => {}) },
    forgetSession: forget, markDeleted: vi.fn(), clearDeleted: vi.fn(), stopNative: core.stop })
  await expect(stop(row.agentId)).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
  expect(mutation).not.toHaveBeenCalled(); expect(terminateDeletedAgent).not.toHaveBeenCalled()
  expect(kill).not.toHaveBeenCalled(); expect(forget).not.toHaveBeenCalled()
})

it.each(['checkpoint', 'native drain'])('holds Stop when its transcript changes during the %s await', async phase => {
  const { createStopAgentService } = await import('./stopAgentService.js')
  const { StoppedAgentStore } = await import('./stoppedAgents.js')
  const { AgentRestartCoordinator } = await import('./restartAgent.js')
  const { terminateDeletedAgent } = await import('./deleteAgentFallback.js')
  vi.mocked(terminateDeletedAgent).mockClear()
  const kill = vi.fn(async () => ({ state: 'succeeded' as const, dispatch: 'executed' as const }))
  const forget = vi.fn()
  const stopNative = vi.fn(async () => { if (phase === 'native drain') writeFileSync(transcript, header(B)) })
  const stop = createStopAgentService({ registry, stoppedAgents: new StoppedAgentStore(join(root, 'stopped')),
    restartJobs: new AgentRestartCoordinator(), stopJobs: new Map(), backendFor: () => ({ kill }),
    agentReconciler: { suppress: vi.fn(), holdRoute: vi.fn(), releaseRoute: vi.fn(), trigger: vi.fn(async () => {}) },
    forgetSession: forget, markDeleted: vi.fn(), clearDeleted: vi.fn(), stopNative })
  await expect(stop(row.agentId, { checkpoint: async () => {
    if (phase === 'checkpoint') writeFileSync(transcript, header(B))
  } })).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
  expect(terminateDeletedAgent).not.toHaveBeenCalled()
  expect(kill).not.toHaveBeenCalled()
  expect(forget).not.toHaveBeenCalled()
  expect(registry.byAgent(row.agentId)?.sessionId).toBe(A)
  if (phase === 'checkpoint') expect(stopNative).not.toHaveBeenCalled()
})

it.each(['binding', 'process birth', 'native grant', 'contained grant', 'process signal', 'pane completion'] as const)(
  'keeps Stop authority at the %s boundary', async phase => {
    const { createStopAgentService } = await import('./stopAgentService.js')
    const { StoppedAgentStore } = await import('./stoppedAgents.js')
    const { AgentRestartCoordinator } = await import('./restartAgent.js')
    const { terminateDeletedAgent } = await import('./deleteAgentFallback.js')
    if (phase === 'process birth') row.processIdentity!.startTicks = 1
    const signal = vi.spyOn(process, 'kill').mockReturnValue(true)
    const realTermination = (await vi.importActual<typeof import('./deleteAgentFallback.js')>('./deleteAgentFallback.js')).terminateDeletedAgent
    vi.mocked(terminateDeletedAgent).mockImplementationOnce(async (session, dependencies) => {
      if (phase === 'process signal') return realTermination(session, { ...dependencies,
        sleep: async () => {}, checkRuntime: async () => { writeFileSync(transcript, header(B)); return { state: 'alive' } },
      })
      return 'gone'
    })
    const kill = vi.fn(async () => {
      if (phase === 'pane completion') writeFileSync(transcript, header(B))
      return { state: 'succeeded' as const, dispatch: 'executed' as const }
    })
    const forget = vi.fn(), nativeMutation = vi.fn()
    const stop = createStopAgentService({ registry, stoppedAgents: new StoppedAgentStore(join(root, 'stopped')),
      restartJobs: new AgentRestartCoordinator(), stopJobs: new Map(), backendFor: () => ({ kill }),
      agentReconciler: { suppress: vi.fn(), holdRoute: vi.fn(), releaseRoute: vi.fn(), trigger: vi.fn(async () => {}) },
      forgetSession: forget, markDeleted: vi.fn(), clearDeleted: vi.fn(), stopNative: async (_session, current) => {
        if (phase === 'native grant' || phase === 'contained grant') writeFileSync(transcript, header(B))
        if (phase === 'contained grant') { try { current() } catch {} return }
        if (current()) nativeMutation()
      } })
    await expect(stop(row.agentId, { checkpoint: async (_session, when) => {
      if (phase === 'binding' && when === 'before') registry.byAgent(row.agentId)!.boundAt = 2
      if (phase === 'process birth' && when === 'before') registry.byAgent(row.agentId)!.processIdentity!.startTicks = 2
    } })).rejects.toMatchObject({ code: phase === 'binding' || phase === 'process birth' ? 'STOP_UNCONFIRMED' : 'IDENTITY_UNAVAILABLE' })
    expect(signal).not.toHaveBeenCalled()
    expect(forget).not.toHaveBeenCalled()
    if (phase !== 'pane completion') expect(kill).not.toHaveBeenCalled()
    if (phase === 'native grant' || phase === 'contained grant' || phase === 'binding' || phase === 'process birth') expect(nativeMutation).not.toHaveBeenCalled()
  })

it.each(['before', 'configuration', 'history repair', 'permission', 'tmux dispatch', 'conversation ownership', 'allocation'] as const)(
  'holds Resume when its native conversation changes during %s', async phase => {
    const { createResumeAgentService } = await import('./resumeAgentService.js')
    const { StoppedAgentStore } = await import('./stoppedAgents.js')
    const { AgentRestartCoordinator } = await import('./restartAgent.js')
    const { checkPidRuntime } = await import('./deleteAgentFallback.js')
    const { dropPermissionFlagIfUnsupported } = await import('./engineLaunch.js')
    const { TmuxBackend } = await import('./tmuxBackend.js')
    const { tmuxFeaturesOf } = await import('./tmuxVersion.js')
    vi.mocked(checkPidRuntime).mockResolvedValue({ state: 'gone', reason: 'fixture process ended' })
    vi.mocked(dropPermissionFlagIfUnsupported).mockImplementation(async (_engine, choice) => {
      if (phase === 'permission') writeFileSync(transcript, header(B))
      return { choice, droppedFlag: null }
    })
    registry.removeAgent(row.agentId)
    const stopped = new StoppedAgentStore(join(root, 'stopped')); stopped.save(row)
    const writeConfiguration = vi.fn()
    const prepare = vi.fn(() => { if (phase === 'history repair') writeFileSync(transcript, header(B)) })
    const create = vi.fn(async () => {
      writeFileSync(transcript, header(B))
      return { state: 'succeeded' as const, dispatch: 'executed' as const, runtime: { backend: 'tmux' as const, paneId: '%99' } }
    })
    const kill = vi.fn(async () => ({ state: 'succeeded' as const, dispatch: 'executed' as const }))
    const announce = vi.fn()
    let newOwner: string | undefined
    const backend = phase === 'tmux dispatch' || phase === 'conversation ownership' ? new TmuxBackend(undefined, () => 'fixture-owner', () => {}, async () => {
      // The backend has accepted the request, but has not crossed its actual process-dispatch gate.
      if (phase === 'conversation ownership') {
        const other = registry.openPendingAgent({ engine: 'codex', cwd: root, runtimes: [{ backend: 'tmux', paneId: '%88' }] })!
        const admitted = registry.register({ engine: 'codex', cwd: root, tmuxPane: '%88', sessionId: A, transcriptPath: transcript })!
        expect(admitted.entry.agentId).toBe(other.agentId)
        newOwner = other.agentId
      } else writeFileSync(transcript, header(B))
      return tmuxFeaturesOf({ major: 3, minor: 7 })
    }) : { create, kill, releaseHold: vi.fn(async () => {}), paneState: vi.fn(async () => 'unknown' as const), rootProcess: vi.fn(async () => null),
      inventory: vi.fn(async () => ({ state: 'available' as const, roots: [] })) }
    const resume = createResumeAgentService({ registry, stoppedAgents: stopped, restartJobs: new AgentRestartCoordinator(),
      stopJobs: new Map(), pinnedControls: new Set(), createBackend: backend, backendFor: () => backend,
      retainExitedSession: vi.fn(), announceSession: announce,
      relaunchOverrides: async (_session, _source, current) => {
        await Promise.resolve()
        if (phase === 'configuration') writeFileSync(transcript, header(B))
        if (current()) writeConfiguration()
        return { ok: true, overrides: { env: {}, extraArgs: [], clearEnv: [] } }
      },
      prepareSessionResume: prepare, refreshGridWebSearch: vi.fn(), clearDeleted: vi.fn(), attachDsh: vi.fn(),
      attachSession: vi.fn(async () => true),
    })
    if (phase === 'before') writeFileSync(transcript, header(B))
    await expect(resume(row.agentId)).resolves.toMatchObject({ ok: false,
      error: phase === 'allocation' ? 'RESUME_UNCONFIRMED' : 'IDENTITY_UNAVAILABLE',
      detail: expect.stringContaining(phase === 'conversation ownership' ? 'another live harness' : 'different conversation') })
    expect(registry.byAgent(row.agentId)).toBeUndefined()
    expect(announce).not.toHaveBeenCalled()
    expect(stopped.get(row.agentId)?.sessionId).toBe(A)
    if (newOwner) expect(registry.bySession(A)?.agentId).toBe(newOwner)
    if (phase === 'before' || phase === 'configuration') {
      expect(writeConfiguration).not.toHaveBeenCalled()
      expect(prepare).not.toHaveBeenCalled()
    }
    if (phase === 'allocation') expect(kill).toHaveBeenCalledExactlyOnceWith({ backend: 'tmux', paneId: '%99' })
    else { expect(create).not.toHaveBeenCalled(); expect(stopped.resumeReservedAt(row.agentId)).toBeNull() }
  },
)