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 { afterEach, beforeEach, expect, it, vi } from 'vitest'
import { captureResumeIdentity } from './captureResumeIdentity.js'
import { createStopAgentService, type StopAgentServiceDeps } from './stopAgentService.js'
import { registry, type RegisteredSession } from './registry.js'
import { setAgentSignaller } from './processSignals.js'
import { stoppedAgents } from './stoppedAgents.js'
import { AgentRestartCoordinator } from './restartAgent.js'
import { checkPidRuntime, terminateDeletedAgent } from './deleteAgentFallback.js'
import { createForgetSession } from '../core/agents/forget.js'
import { env } from '../config/env.js'
import { controlTranscriptEvidence } from '../engines/transcriptBindings.js'
import { IdentityReadUnavailable, ObservedConversationUnavailable } from '../engines/kit/identityScan.js'
vi.mock('./captureResumeIdentity.js', () => ({ captureResumeIdentity: vi.fn(async session => session) }))
vi.mock('../engines/transcriptBindings.js', async original => ({ ...await original<object>(),
  controlTranscriptEvidence: vi.fn(),
}))
vi.mock('./deleteAgentFallback.js', () => ({ checkPidRuntime: vi.fn(), terminateDeletedAgent: vi.fn() }))
vi.mock('../core/engines/cursorTasks.js', () => ({ removePendingCursorTasks: vi.fn(async () => {}) }))
let row: RegisteredSession
let deps: StopAgentServiceDeps
// The tmux pane's backend; a pty host's is only there when a case adds it (`withPtyHost`).
const tmuxKill = vi.fn<NonNullable<ReturnType<StopAgentServiceDeps['backendFor']>>['kill']>()
const ptyKill = vi.fn<NonNullable<ReturnType<StopAgentServiceDeps['backendFor']>>['kill']>()
const withPtyHost = () => { deps.backendFor = runtime => ({ kill: runtime.backend === 'tmux' ? tmuxKill : ptyKill }) }
const pty = { backend: 'ptyhost' as const, instance: 'p1', paneId: '%1' }
beforeEach(() => {
  vi.clearAllMocks()
  vi.mocked(controlTranscriptEvidence).mockReset().mockImplementation((_engine, _id, path) => ({ path, verify: vi.fn() }))
  vi.mocked(captureResumeIdentity).mockReset().mockImplementation(async session => session)
  row = registry.openPendingAgent({ engine: 'codex', runtimes: [{ backend: 'tmux', paneId: '%44' }], cwd: '/tmp' })!
  Object.assign(row, { sessionId: 'saved', processIdentity: { pid: 77, executable: 'codex', startMarker: 'fixture' } })
  deps = { registry, stoppedAgents, restartJobs: new AgentRestartCoordinator(), stopJobs: new Map(),
    backendFor: runtime => runtime.backend === 'tmux' ? { kill: tmuxKill } : undefined,
    agentReconciler: { suppress: vi.fn(), holdRoute: vi.fn(), releaseRoute: vi.fn(), trigger: vi.fn(async () => {}) },
    forgetSession: vi.fn(id => registry.removeAgent(id)), markDeleted: vi.fn(), clearDeleted: vi.fn(),
    stopNative: vi.fn(async () => {}),
  }
  vi.mocked(terminateDeletedAgent).mockResolvedValue('gone')
  tmuxKill.mockReset().mockResolvedValue({ state: 'succeeded', dispatch: 'executed' })
  ptyKill.mockReset().mockResolvedValue({ state: 'succeeded', dispatch: 'executed' })
})
afterEach(() => { vi.restoreAllMocks(); for (const entry of registry.list()) registry.removeAgent(entry.agentId) })

it('saves history before removing the runtime, joins concurrent stops, and clears confirmed reservations', async () => {
  const token = stoppedAgents.beginResume(row.agentId); expect(token).toBeTruthy()
  const original = row.agentId
  vi.mocked(deps.forgetSession).mockImplementation(id => { expect(stoppedAgents.get(id)?.sessionId).toBe('saved'); registry.removeAgent(id) })
  const stop = createStopAgentService(deps); const one = stop(original); expect(stop(original)).toBe(one); await one
  expect(stoppedAgents.get(original)).toMatchObject({ active: false, sessionId: 'saved' })
  expect(registry.byAgent(original)).toBeUndefined(); expect(deps.stopJobs.size).toBe(0)
  expect(stoppedAgents.beginResume(original)).not.toBeNull(); expect(deps.agentReconciler.suppress).toHaveBeenCalledWith(row)
})
it('missing identities are harmless and never allocate or signal anything', async () => {
  await createStopAgentService(deps)('missing'); expect(deps.forgetSession).not.toHaveBeenCalled(); expect(terminateDeletedAgent).not.toHaveBeenCalled()
})
it.each(['forget', 'checkpoint'] as const)('retains a captured Pi resume path through a pathless %s save', async stage => {
  Object.assign(row, { engine: 'pi', transcriptPath: null,
    processIdentity: { pid: 77, executable: 'pi', startMarker: 'fixture' } })
  vi.mocked(captureResumeIdentity).mockImplementation(async session => ({ ...session,
    transcriptPath: '/fixture/native.jsonl', source: 'stop-repair' }))
  deps.forgetSession = createForgetSession({
    registry, stoppedAgents, 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: env.ADAPTER_DATA_DIR,
  })
  await createStopAgentService(deps)(row.agentId, { checkpoint: async (_session, phase) => {
    if (stage === 'checkpoint' && phase === 'before') {
      // A hook can save the same live row while Close awaits its checkpoint, before tombstones exist.
      expect(row.transcriptPath).toBeNull()
      stoppedAgents.save({ ...row, title: 'Hook arrived' })
      expect(stoppedAgents.get(row.agentId)?.transcriptPath).toBe('/fixture/native.jsonl')
    }
  } })
  expect(registry.byAgent(row.agentId)).toBeUndefined()
  expect(stoppedAgents.get(row.agentId)).toMatchObject({ sessionId: row.sessionId,
    transcriptPath: '/fixture/native.jsonl', active: false })
})
it('cancels immediately, then joins the core pane commit before capturing the runtime to stop', async () => {
  let committed!: () => void
  deps.settlePane = vi.fn(() => new Promise<void>(done => { committed = done }))
  const stopping = createStopAgentService(deps)(row.agentId)
  expect(deps.stopJobs.has(row.agentId)).toBe(true)
  await vi.waitFor(() => expect(deps.settlePane).toHaveBeenCalledWith(row.agentId))
  expect(captureResumeIdentity).not.toHaveBeenCalled()
  row.runtimes = [{ backend: 'tmux', paneId: '%90' }]
  committed()
  await stopping
  expect(tmuxKill).toHaveBeenCalledWith({ backend: 'tmux', paneId: '%90' }, expect.any(Function))
})
it('storage failure leaves the live process and registry untouched', async () => {
  vi.spyOn(stoppedAgents, 'save').mockImplementation(() => { throw new Error('disk full') })
  await expect(createStopAgentService(deps)(row.agentId)).rejects.toThrow('disk full')
  expect(registry.byAgent(row.agentId)).toBe(row); expect(tmuxKill).not.toHaveBeenCalled(); expect(deps.markDeleted).not.toHaveBeenCalled()
})
it('preserves an unexpected evidence failure without signalling or hiding its cause', async () => {
  row.transcriptPath = '/fixture/history.jsonl'
  vi.mocked(controlTranscriptEvidence).mockReturnValue({ path: row.transcriptPath,
    verify: () => { throw new Error('Evidence implementation unavailable') } })
  await expect(createStopAgentService(deps)(row.agentId)).rejects.toThrow('Evidence implementation unavailable')
  expect(terminateDeletedAgent).not.toHaveBeenCalled()
  expect(deps.forgetSession).not.toHaveBeenCalled()
})
// A guest's harness runs as the guest's own OS user: the owner's daemon can neither read its process's descriptors
// (the native control probe) nor signal it (EPERM). Measured on a Mac sharing with a guest, 2026-10-22: closing the
// owner's tmux pane ended the guest's process.
it('stops a guest harness by closing its pane, without the native probe or a signal, once its process has left', async () => {
  Object.assign(row, { guest: '[email protected]' })
  vi.mocked(captureResumeIdentity).mockRejectedValue(new IdentityReadUnavailable('the native control probe did not complete'))
  vi.mocked(checkPidRuntime).mockResolvedValueOnce({ state: 'alive' }).mockResolvedValue({ state: 'gone', reason: 'saved process identity is no longer running' })
  deps.wait = vi.fn(async () => {})
  await createStopAgentService(deps)(row.agentId)
  expect(captureResumeIdentity).not.toHaveBeenCalled()
  expect(deps.stopNative).not.toHaveBeenCalled()
  expect(terminateDeletedAgent).not.toHaveBeenCalled()
  expect(tmuxKill).toHaveBeenCalledOnce()
  expect(checkPidRuntime).toHaveBeenCalledTimes(2)
  expect(stoppedAgents.get(row.agentId)).toMatchObject({ active: false, sessionId: 'saved' })
  expect(registry.byAgent(row.agentId)).toBeUndefined()
})
it('keeps a guest harness whose process is still running after its pane closed', async () => {
  Object.assign(row, { guest: '[email protected]' })
  vi.mocked(checkPidRuntime).mockResolvedValue({ state: 'alive' })
  deps.wait = vi.fn(async () => {})
  await expect(createStopAgentService(deps)(row.agentId)).rejects.toThrow('Could not confirm that the harness stopped')
  expect(tmuxKill).toHaveBeenCalledOnce()
  expect(deps.forgetSession).not.toHaveBeenCalled()
  expect(registry.byAgent(row.agentId)).toBe(row)
})
it('checks the saved guest process after its pane removes the registry row, without claiming the changed stop completed', async () => {
  vi.useFakeTimers()
  Object.assign(row, { guest: '[email protected]' })
  const identity = { ...row.processIdentity! }
  tmuxKill.mockImplementationOnce(async () => {
    registry.removeAgent(row.agentId)
    return { state: 'succeeded', dispatch: 'executed' }
  })
  vi.mocked(checkPidRuntime).mockResolvedValueOnce({ state: 'alive' })
    .mockResolvedValue({ state: 'gone', reason: 'guest exited after its pane closed' })
  try {
    const result = expect(createStopAgentService(deps)(row.agentId)).rejects.toThrow('The harness changed while pausing')
    await vi.advanceTimersByTimeAsync(250)
    await result
    expect(checkPidRuntime).toHaveBeenCalledTimes(2)
    for (const [session] of vi.mocked(checkPidRuntime).mock.calls) expect(session.processIdentity).toEqual(identity)
    expect(deps.forgetSession).not.toHaveBeenCalled()
    expect(terminateDeletedAgent).not.toHaveBeenCalled()
    expect(stoppedAgents.get(row.agentId)?.sessionId).toBe('saved')
  } finally { vi.useRealTimers() }
})
it('waits for the process a starting guest harness gained while it was saved', async () => {
  // Stopped before its engine was seen, which the pane's watcher binds while the screen is saved: an older copy of the
  // row has no process, which reads as gone at once.
  Object.assign(row, { guest: '[email protected]', processIdentity: undefined })
  const engine = { pid: 91, executable: 'claude', startMarker: 'guest' }
  vi.mocked(checkPidRuntime).mockImplementation(async s => s.processIdentity ? { state: 'alive' } : { state: 'gone', reason: 'none' })
  deps.wait = vi.fn(async () => {})
  await expect(createStopAgentService(deps)(row.agentId, { checkpoint: async (_s, phase) => {
    if (phase === 'before') row.processIdentity = engine
  } })).rejects.toThrow('Could not confirm that the harness stopped')
  expect(vi.mocked(checkPidRuntime).mock.calls.every(([s]) => s.processIdentity?.pid === 91)).toBe(true)
  expect(registry.byAgent(row.agentId)).toBe(row)
})
// A close of a harness still starting that waited in vain for its first conversation (closeAgentService.ts).
it('stops a harness that never bound a conversation without one, only when its close asks', async () => {
  Object.assign(row, { sessionId: '', transcriptPath: null, boundAt: null })
  vi.mocked(captureResumeIdentity).mockRejectedValue(new IdentityReadUnavailable('the native control descriptor type is unavailable'))
  await expect(createStopAgentService(deps)(row.agentId)).rejects.toThrow('descriptor type is unavailable')
  expect(registry.byAgent(row.agentId)).toBe(row)
  const unkept = vi.fn()
  await createStopAgentService(deps)(row.agentId, { withoutConversation: unkept })
  expect(unkept).toHaveBeenCalledOnce()
  expect(stoppedAgents.get(row.agentId)).toMatchObject({ active: false, sessionId: '' })
  expect(registry.byAgent(row.agentId)).toBeUndefined()
})
it.each(['a bound conversation', 'a known transcript', 'a bind time', 'a conversation seen live', 'another failure'] as const)('never lets go of %s that cannot be read', async kind => {
  Object.assign(row, { sessionId: kind === 'a bound conversation' ? 'saved' : '', transcriptPath: kind === 'a known transcript' ? '/fixture/t.jsonl' : null,
    boundAt: kind === 'a bind time' ? 1 : null })
  vi.mocked(captureResumeIdentity).mockRejectedValue(kind === 'another failure' ? new Error('disk gone')
    : kind === 'a conversation seen live' ? new ObservedConversationUnavailable('Conversation identity is held: the observed conversation file is unavailable.')
    : new IdentityReadUnavailable('the transcript is unreadable'))
  const unkept = vi.fn()
  await expect(createStopAgentService(deps)(row.agentId, { withoutConversation: unkept })).rejects.toThrow()
  expect(unkept).not.toHaveBeenCalled()
  expect(registry.byAgent(row.agentId)).toBe(row)
})
it.each(['before', 'after'] as const)('honors cancellation at the %s checkpoint before retiring the terminal', async phase => {
  let current = true
  await expect(createStopAgentService(deps)(row.agentId, {
    current: () => current,
    checkpoint: async (_, at) => { if (at === phase) current = false },
  })).rejects.toThrow('changed')
  expect(tmuxKill).not.toHaveBeenCalled()
  expect(deps.forgetSession).not.toHaveBeenCalled()
  if (phase === 'before') expect(terminateDeletedAgent).not.toHaveBeenCalled()
})
it('backs up final flushed history after graceful exit and before closing the pane', async () => {
  const order: string[] = []
  vi.mocked(terminateDeletedAgent).mockImplementation(async () => { order.push('exit'); return 'terminated' })
  tmuxKill.mockImplementation(async () => { order.push('pane'); return { state: 'succeeded', dispatch: 'executed' } })
  await createStopAgentService(deps)(row.agentId, { checkpoint: async (_, phase) => { order.push(phase) } })
  expect(order).toEqual(['before', 'exit', 'after', 'pane'])
})
it.each(['terminal', 'without tmux', 'failed process', 'failed tmux'] as const)('retains work when stopping %s', async mode => {
  stoppedAgents.beginResume(row.agentId)
  if (mode === 'terminal') Object.assign(row, { engine: 'terminal', sessionId: '', processIdentity: null })
  if (mode === 'without tmux') { deps.backendFor = () => undefined; Object.assign(row, { runtimes: [{ backend: 'ptyhost', instance: 'p1', paneId: '%1' }], tmuxPane: '%1', primaryRuntimeKey: 'ptyhost\u0000p1\u0000%1' }) }
  if (mode === 'failed process') vi.mocked(terminateDeletedAgent).mockResolvedValue('failed')
  if (mode === 'failed tmux') tmuxKill.mockResolvedValue({ state: 'unknown', dispatch: 'possibly_executed', reason: 'fixture' })
  const stopping = createStopAgentService(deps)(row.agentId)
  if (mode === 'failed process' || mode === 'failed tmux') {
    await expect(stopping).rejects.toThrow('Could not confirm')
    expect(registry.byAgent(row.agentId)).toBe(row)
    expect(deps.forgetSession).not.toHaveBeenCalled()
    expect(deps.agentReconciler.suppress).not.toHaveBeenCalled()
  } else await stopping
  expect(stoppedAgents.get(row.agentId)).not.toBeNull(); expect(deps.agentReconciler.trigger).toHaveBeenCalledOnce()
  expect(stoppedAgents.beginResume(row.agentId) === null).toBe(mode === 'failed process' || mode === 'failed tmux')
})

it('does not publish a stopped row until the exact process and terminal have both stopped', async () => {
  let finishProcess!: () => void
  let finishPane!: () => void
  vi.mocked(terminateDeletedAgent).mockImplementation(() => new Promise(resolve => { finishProcess = () => resolve('terminated') }))
  tmuxKill.mockImplementation(() => new Promise(resolve => { finishPane = () => resolve({ state: 'succeeded', dispatch: 'executed' }) }))
  const stop = createStopAgentService(deps)
  const stopping = stop(row.agentId)
  await vi.waitFor(() => expect(finishProcess).toBeTypeOf('function'))
  expect(registry.byAgent(row.agentId)).toBe(row)
  expect(deps.forgetSession).not.toHaveBeenCalled()
  expect(tmuxKill).not.toHaveBeenCalled()
  finishProcess()
  await vi.waitFor(() => expect(finishPane).toBeTypeOf('function'))
  expect(deps.forgetSession).not.toHaveBeenCalled()
  expect(stop(row.agentId)).toBe(stopping)
  finishPane()
  await stopping
  expect(deps.forgetSession).toHaveBeenCalledOnce()
  expect(deps.agentReconciler.holdRoute).toHaveBeenCalledOnce()
  expect(deps.agentReconciler.releaseRoute).toHaveBeenCalledOnce()
})

it.each(['process', 'pane'] as const)('a rejected %s check retains history, releases its route and permits a safe retry', async side => {
  if (side === 'process') vi.mocked(terminateDeletedAgent).mockRejectedValueOnce(new Error('probe failed'))
  else tmuxKill.mockRejectedValueOnce(new Error('transport failed'))
  const stop = createStopAgentService(deps)
  await expect(stop(row.agentId)).rejects.toThrow('Could not confirm')
  expect(deps.stopJobs.size).toBe(0)
  expect(registry.byAgent(row.agentId)).toBe(row)
  expect(deps.agentReconciler.releaseRoute).toHaveBeenCalledOnce()
  expect(deps.clearDeleted).toHaveBeenCalledWith(row.agentId)
  await stop(row.agentId)
  expect(registry.byAgent(row.agentId)).toBeUndefined()
})

it.each(['no backend', 'no tmux route'] as const)('cannot confirm stopping a shell with %s', async mode => {
  row.engine = 'terminal'
  if (mode === 'no backend') deps.backendFor = () => undefined
  else row.runtimes = [{ backend: 'ptyhost', instance: 'p1', paneId: '%1' }]
  await expect(createStopAgentService(deps)(row.agentId)).rejects.toThrow('Could not confirm')
  expect(deps.forgetSession).not.toHaveBeenCalled()
})

// A pty host pane is closed by its own backend, as a tmux pane is by tmux: the host's kill ends the pane's whole
// process group (a Job object on Windows), which is what leaves nothing of the stopped harness running.
it.each(['codex', 'terminal'] as const)('stops a pty host %s through its own backend, never asking tmux', async engine => {
  withPtyHost()
  Object.assign(row, { runtimes: [pty], tmuxPane: '%1', primaryRuntimeKey: 'ptyhost\u0000p1\u0000%1',
    ...(engine === 'terminal' ? { engine, sessionId: '', processIdentity: null } : {}) })
  await createStopAgentService(deps)(row.agentId)
  expect(ptyKill).toHaveBeenCalledExactlyOnceWith(pty, expect.any(Function))
  expect(tmuxKill).not.toHaveBeenCalled()
  expect(registry.byAgent(row.agentId)).toBeUndefined()
  expect(stoppedAgents.get(row.agentId)).toMatchObject({ active: false })
})
it('closes each pane of a mixed row on its own backend, the tmux one as before', async () => {
  withPtyHost()
  const tmux = { backend: 'tmux' as const, paneId: '%44' }
  row.runtimes = [pty, tmux]
  await createStopAgentService(deps)(row.agentId)
  expect(tmuxKill).toHaveBeenCalledExactlyOnceWith(tmux, expect.any(Function))
  expect(ptyKill).toHaveBeenCalledExactlyOnceWith(pty, expect.any(Function))
  expect(registry.byAgent(row.agentId)).toBeUndefined()
})
it.each(['failed', 'changed'] as const)('keeps a pty host harness whose pane close %s', async mode => {
  withPtyHost()
  row.runtimes = [pty]
  ptyKill.mockImplementation(async (_runtime, current) => {
    if (mode === 'changed') row.sessionId = 'different-conversation'
    // The original Close permission travels to the host's kill, as it does to tmux's.
    return current?.() === false ? { state: 'failed', dispatch: 'not_started', reason: 'changed' } : { state: 'unknown', dispatch: 'possibly_executed', reason: 'fixture' }
  })
  await expect(createStopAgentService(deps)(row.agentId)).rejects.toThrow('Could not confirm')
  expect(registry.byAgent(row.agentId)).toBe(row)
  expect(deps.forgetSession).not.toHaveBeenCalled()
})

it('holds a conversation whose evidence fails at the pane close, as at every earlier boundary', async () => {
  row.transcriptPath = '/fixture/history.jsonl'
  let closing = false
  vi.mocked(controlTranscriptEvidence).mockReturnValue({ path: row.transcriptPath, verify: () => {
    if (closing) throw new IdentityReadUnavailable('the transcript changed while closing')
  } })
  tmuxKill.mockImplementation(async (_runtime, current) => { closing = true; current?.(); return { state: 'succeeded', dispatch: 'executed' } })
  await expect(createStopAgentService(deps)(row.agentId)).rejects.toBeInstanceOf(IdentityReadUnavailable)
  expect(registry.byAgent(row.agentId)).toBe(row)
  expect(deps.forgetSession).not.toHaveBeenCalled()
})
it.each(['removed', 'replaced', 'conversation', 'route'] as const)('does not remove a target %s during termination', async mode => {
  vi.mocked(terminateDeletedAgent).mockImplementation(async () => {
    if (mode === 'removed') registry.removeAgent(row.agentId)
    else if (mode === 'conversation') row.sessionId = 'different-conversation'
    else if (mode === 'route') row.runtimes = [{ backend: 'tmux', paneId: '%88' }]
    else row.processIdentity = { ...row.processIdentity!, pid: 88 }
    return 'terminated'
  })
  await expect(createStopAgentService(deps)(row.agentId)).rejects.toThrow('changed while pausing')
  expect(tmuxKill).not.toHaveBeenCalled()
  expect(deps.forgetSession).not.toHaveBeenCalled()
})
it.each(['capture', 'termination'] as const)('stops an agent still starting when its engine is identified during %s', async stage => {
  // Created, not yet bound to a process: the stop's snapshot has none.
  row.processIdentity = null
  const launched = { pid: 91, executable: 'codex', startMarker: 'launched' }
  if (stage === 'capture') vi.mocked(captureResumeIdentity).mockImplementation(async session => { row.processIdentity = launched; return session })
  else vi.mocked(terminateDeletedAgent).mockImplementation(async () => { row.processIdentity = launched; return 'terminated' })
  await createStopAgentService(deps)(row.agentId)
  expect(registry.byAgent(row.agentId)).toBeUndefined()
  expect(tmuxKill).toHaveBeenCalledOnce()
  // Identified before termination: that exact process is the one checked and signalled.
  if (stage === 'capture') expect(vi.mocked(terminateDeletedAgent).mock.calls[0][0].processIdentity).toEqual(launched)
})
it('still refuses a starting agent whose pane or conversation changed under the stop', async () => {
  row.processIdentity = null
  vi.mocked(terminateDeletedAgent).mockImplementation(async () => { row.runtimes = [{ backend: 'tmux', paneId: '%89' }]; return 'gone' })
  await expect(createStopAgentService(deps)(row.agentId)).rejects.toThrow('changed while pausing')
  expect(tmuxKill).not.toHaveBeenCalled()
})
it.each(['capture', 'termination'] as const)('accepts a hook rebuilding the same process during %s', async stage => {
  const replacement = { ...row, title: 'Updated title',
    processIdentity: { startMarker: 'fixture', executable: 'codex', pid: 77 },
    runtimes: row.runtimes.map(runtime => ({ ...runtime })),
  }
  const rebuild = () => { vi.spyOn(registry, 'resolve').mockReturnValue(replacement) }
  if (stage === 'capture') vi.mocked(captureResumeIdentity).mockImplementation(async session => { rebuild(); return session })
  else vi.mocked(terminateDeletedAgent).mockImplementation(async () => { rebuild(); return 'terminated' })
  await createStopAgentService(deps)(row.agentId)
  expect(deps.forgetSession).toHaveBeenCalledExactlyOnceWith(row.agentId, { force: true, captured: expect.objectContaining({ sessionId: 'saved' }) })
  expect(registry.byAgent(row.agentId)).toBeUndefined()
  expect(stoppedAgents.get(row.agentId)?.sessionId).toBe('saved')
})
it('routes the stop signal through the agent signaller', async () => {
  const injected = vi.fn(); setAgentSignaller(injected)
  vi.mocked(terminateDeletedAgent).mockImplementation(async (entry, actions) => { actions.kill(78, 'SIGKILL'); return 'terminated' })
  try { await createStopAgentService(deps)(row.agentId) } finally { setAgentSignaller(null) }
  expect(injected).toHaveBeenCalledExactlyOnceWith(78, 'SIGKILL')
})
it('only signals through the validated process deleter and does not erase a newer stop job', async () => {
  const signal = vi.spyOn(process, 'kill').mockReturnValue(true)
  vi.mocked(terminateDeletedAgent).mockImplementation(async (entry, actions) => {
    await actions.checkRuntime(entry); actions.kill(77, 'SIGTERM'); await actions.sleep(1); actions.log('fixture stop')
    deps.stopJobs.set(row.agentId, Promise.resolve()); return 'terminated'
  })
  row.runtimes.push({ backend: 'ptyhost', instance: 'p1', paneId: '%2' })
  await createStopAgentService(deps)(row.agentId)
  expect(signal).toHaveBeenCalledExactlyOnceWith(77, 'SIGTERM'); expect(deps.stopJobs.has(row.agentId)).toBe(true)
  expect(tmuxKill).toHaveBeenCalledExactlyOnceWith({ backend: 'tmux', paneId: '%44' }, expect.any(Function))
})

it.each(['claude', 'codex'] as const)('captures an unbound %s conversation before deleting its process', async engine => {
  Object.assign(row, { engine, sessionId: '', transcriptPath: null })
  vi.mocked(captureResumeIdentity).mockImplementation(async session => {
    expect(registry.byAgent(row.agentId)).toBe(row)
    expect(tmuxKill).not.toHaveBeenCalled()
    return { ...session, sessionId: 'recovered', transcriptPath: '/history.jsonl', boundAt: 1, source: 'stop-repair' }
  })
  await createStopAgentService(deps)(row.agentId)
  expect(stoppedAgents.get(row.agentId)).toMatchObject({ engine, sessionId: 'recovered', transcriptPath: '/history.jsonl' })
  expect(deps.markDeleted).toHaveBeenCalledWith('recovered')
})
it.each(['removed', 'replaced'] as const)('does not stop a process that was %s during identity capture', async mode => {
  vi.mocked(captureResumeIdentity).mockImplementation(async session => {
    if (mode === 'removed') registry.removeAgent(row.agentId)
    else row.processIdentity = { ...row.processIdentity!, pid: 88 }
    return session
  })
  await expect(createStopAgentService(deps)(row.agentId)).rejects.toThrow('Harness changed')
  expect(tmuxKill).not.toHaveBeenCalled()
  expect(terminateDeletedAgent).not.toHaveBeenCalled()
  expect(stoppedAgents.get(row.agentId)).toBeNull()
})
it('keeps the newer hook binding that arrives during capture', async () => {
  row.sessionId = ''
  vi.mocked(captureResumeIdentity).mockImplementation(async session => {
    row.sessionId = 'latest'
    return { ...session, sessionId: 'older' }
  })
  await createStopAgentService(deps)(row.agentId)
  expect(stoppedAgents.get(row.agentId)?.sessionId).toBe('latest')
})

it('checks cancellation at the shared-server boundary and never signals after a failure there', async () => {
  let current = true
  vi.mocked(deps.stopNative).mockImplementationOnce(async (_row, guard) => {
    expect(guard()).toBe(true); current = false; expect(guard()).toBe(false)
    throw new Error('shared server could not stop')
  })
  await expect(createStopAgentService(deps)(row.agentId, { current: () => current })).rejects.toThrow('shared server')
  expect(terminateDeletedAgent).not.toHaveBeenCalled()
  expect(tmuxKill).not.toHaveBeenCalled()
  expect(deps.clearDeleted).toHaveBeenCalledWith(row.agentId)
})
it('does not signal a process replaced at the actual kill boundary', async () => {
  vi.mocked(terminateDeletedAgent).mockImplementationOnce(async (_row, actions) => {
    row.processIdentity!.startMarker = 'replacement'
    actions.kill(77, 'SIGTERM')
    return 'gone'
  })
  await expect(createStopAgentService(deps)(row.agentId)).rejects.toThrow('Could not confirm')
  expect(tmuxKill).not.toHaveBeenCalled()
})
it('does not forget a new agent published while its old pane was being retired', async () => {
  tmuxKill.mockImplementationOnce(async () => {
    row.processIdentity!.startMarker = 'replacement'
    return { state: 'succeeded', dispatch: 'executed' }
  })
  await expect(createStopAgentService(deps)(row.agentId)).rejects.toThrow('changed while pausing')
  expect(deps.forgetSession).not.toHaveBeenCalled()
})

it('cancels an external intent through core without archiving, signalling or waiting for search', async () => {
  Object.assign(row, { sessionId: '', processIdentity: null, launch: { state: 'held', service: 'search', detail: 'Reader unavailable' },
    externalResume: { phase: 'waiting' } })
  deps.cancelExternal = vi.fn(async (entry, current) => { expect(entry).toBe(row); expect(current()).toBe(true); return true })
  const save = vi.spyOn(stoppedAgents, 'save')
  await createStopAgentService(deps)(row.agentId)
  expect(deps.cancelExternal).toHaveBeenCalledOnce()
  expect(save).not.toHaveBeenCalled()
  expect(captureResumeIdentity).not.toHaveBeenCalled()
  expect(terminateDeletedAgent).not.toHaveBeenCalled()
  expect(deps.stopNative).not.toHaveBeenCalled()
  expect(tmuxKill).not.toHaveBeenCalled()
  expect(deps.forgetSession).not.toHaveBeenCalled()
})

it.each(['missing', 'refused', 'error', 'unknown', 'cancelled'] as const)('keeps an external intent intact when cancellation is %s', async failure => {
  Object.assign(row, { sessionId: '', processIdentity: null, launch: { state: 'held', service: 'search', detail: 'Reader unavailable' },
    externalResume: { phase: 'waiting' } })
  if (failure !== 'missing') deps.cancelExternal = vi.fn(async (_entry, current) => {
    if (failure === 'error') throw new Error('Journal is unavailable')
    if (failure === 'unknown') throw 'unavailable'
    if (failure === 'cancelled') { expect(current()).toBe(false); return current() }
    return false
  })
  const save = vi.spyOn(stoppedAgents, 'save')
  await expect(createStopAgentService(deps)(row.agentId, { current: () => failure !== 'cancelled' }))
    .rejects.toMatchObject({ code: 'STOP_UNCONFIRMED', message: failure === 'error' ? 'Journal is unavailable'
      : failure === 'unknown' ? 'Adoption could not be cancelled.' : 'Adoption cancellation is unavailable.' })
  expect(registry.byAgent(row.agentId)).toBe(row)
  expect(deps.stopJobs.size).toBe(0)
  expect(save).not.toHaveBeenCalled()
  expect(captureResumeIdentity).not.toHaveBeenCalled()
  expect(terminateDeletedAgent).not.toHaveBeenCalled()
  expect(deps.stopNative).not.toHaveBeenCalled()
  expect(tmuxKill).not.toHaveBeenCalled()
  expect(deps.forgetSession).not.toHaveBeenCalled()
})