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.1 KB
Raw Blame
import { nativeConversationFixture } from '../testing/nativeConversationEvidence.js'
import { execFile, execFileSync } from 'node:child_process'
import { constants } from 'node:buffer'
import { mkdirSync, mkdtempSync, realpathSync, renameSync, rmSync, truncateSync, utimesSync, writeFileSync } from 'node:fs'
import * as fs from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { dirname, join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { identityBytes, identityEntries, identityScanBudget } from '../engines/kit/identityScan.js'
import type { RegisteredSession } from './registry.js'
import type { StopAgentServiceDeps } from './stopAgentService.js'

// These cases exercise count/byte bounds and changing ownership, not host fsync speed.
// homeAdoption.spec.ts separately advances this clock to prove the work deadline holds.
vi.mock('node:perf_hooks', async original => ({ ...await original<object>(), performance: { now: () => 0 } }))

vi.mock('node:fs/promises', async original => {
  const actual = await original<typeof import('node:fs/promises')>()
  return { ...actual, open: vi.fn(actual.open), opendir: vi.fn(actual.opendir), stat: vi.fn(actual.stat),
    readdir: vi.fn(actual.readdir), readlink: vi.fn(actual.readlink) }
})
vi.mock('node:child_process', async original => {
  const actual = await original<typeof import('node:child_process')>()
  return { ...actual, execFile: vi.fn(actual.execFile) }
})
vi.mock('./processTable.js', async original => ({ ...await original<object>(), processRows: vi.fn() }))
vi.mock('../engines/kit/nativeDescriptors.js', async original => ({ ...await original<object>(), readDescriptorEvidence: vi.fn() }))
vi.mock('./processEvidence.js', async () => {
  const { nativeConversationFixture } = await import('../testing/nativeConversationEvidence.js')
  const { processRows } = await import('./processTable.js')
  const { readDescriptorEvidence } = await import('../engines/kit/nativeDescriptors.js')
  return { readProcessEvidence: (...args: Parameters<typeof import('./processEvidence.js')['readProcessEvidence']>) => {
    const sources = nativeConversationFixture(async () => [], processRows)
    sources.descriptors = readDescriptorEvidence
    return sources.processes(...args)
  } }
})
vi.mock('./deleteAgentFallback.js', () => ({ checkPidRuntime: vi.fn(), terminateDeletedAgent: vi.fn() }))

const START = Date.parse('2026-10-09T00:00:00Z')
const CWD = '/workspace'
const SID = '11111111-2222-4333-8444-555555555555'
const OTHER = 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee'
let root: string
let repair: typeof import('./sessionRepair.js')
const body = (cwd = CWD) => JSON.stringify({ cwd, isSidechain: false }) + '\n'
function file(path: string, text: string, time = START): string {
  mkdirSync(dirname(path), { recursive: true })
  writeFileSync(path, text)
  utimesSync(path, time / 1000, time / 1000)
  return path
}
const transcript = (name = SID, cwd = CWD, time = START) => file(join(root, 'claude', 'projects', 'work', `${name}.jsonl`), body(cwd), time)
const record = (text: string, home = join(root, 'claude')) => file(join(home, 'sessions', '77.json'), text)
const validRecord = (id = SID) => JSON.stringify({ pid: 77, procStart: new Date(START).toISOString(), cwd: CWD, sessionId: id })

beforeEach(async () => {
  const actual = await vi.importActual<typeof import('node:fs/promises')>('node:fs/promises')
  vi.mocked(fs.open).mockReset().mockImplementation(actual.open)
  vi.mocked(fs.opendir).mockReset().mockImplementation(actual.opendir)
  vi.mocked(fs.stat).mockReset().mockImplementation(actual.stat)
  vi.mocked(fs.readdir).mockReset().mockImplementation(actual.readdir)
  vi.mocked(fs.readlink).mockReset().mockImplementation(actual.readlink)
  const processes = await vi.importActual<typeof import('node:child_process')>('node:child_process')
  vi.mocked(execFile).mockReset().mockImplementation(processes.execFile)
  root = realpathSync(mkdtempSync(join(tmpdir(), 'identity-bounds-')))
  const homes = { HOME: join(root, 'home'), ADAPTER_DATA_DIR: join(root, 'data'),
    CLAUDE_PROJECTS_DIR: join(root, 'claude', 'projects'), CODEX_HOME: join(root, 'codex'),
    COPILOT_HOME: join(root, 'copilot'), GROK_HOME: join(root, 'grok'), PI_HOME: join(root, 'pi'), MUSE_HOME: join(root, 'muse') }
  for (const [name, value] of Object.entries(homes)) vi.stubEnv(name, value)
  vi.stubEnv('CLAUDE_CONFIG_DIR', '')
  vi.resetModules()
  repair = await import('./sessionRepair.js')
})
afterEach(() => { vi.restoreAllMocks(); vi.unstubAllEnvs(); rmSync(root, { recursive: true, force: true }) })
const scan = () => repair.findLiveSession('claude', CWD, START, { bornOnly: true })

describe('complete bounded evidence before choosing a conversation', () => {
  it('never makes a hidden second candidate unique by retaining only the newest 400 files', async () => {
    transcript('visible', CWD, START + 2000)
    transcript('hidden', CWD, START)
    for (let i = 0; i < 399; i++) transcript(`other-${i}`, '/elsewhere', START + 1000)
    await expect(scan()).rejects.toThrow('transcript count limit')
  })

  it('shares the file budget across moved homes', async () => {
    const moved = join(root, 'moved')
    for (let i = 0; i < 200; i++) transcript(`other-${i}`, '/elsewhere')
    for (let i = 0; i < 200; i++) file(join(moved, 'projects', 'work', `${i}.jsonl`), body('/elsewhere'))
    transcript('visible')
    const homes = await import('./engineHomes.js')
    homes.adoptEngineHomes({ CLAUDE_CONFIG_DIR: moved }, { claudeHome: join(root, 'claude'), codexHome: join(root, 'codex') })
    await expect(scan()).rejects.toThrow('transcript count limit')
  })

  it('holds a shallow candidate if an unknown deeper subtree cannot be inspected', async () => {
    transcript('visible')
    file(join(root, 'claude', 'projects', 'a', 'b', 'c', 'd', 'e', 'hidden.jsonl'), body())
    await expect(scan()).rejects.toThrow('depth limit')
  })

  it('excludes declared subagent folders before applying depth bounds', async () => {
    const path = transcript()
    file(join(root, 'claude', 'projects', 'work', 'subagents', 'a', 'b', 'c', 'd', 'child.jsonl'), body())
    await expect(scan()).resolves.toEqual({ sessionId: SID, transcriptPath: path })
  })

  it('binds a Muse session whatever folders it keeps beside its transcript', async () => {
    // Muse Code 1.4 keeps folders of its own beside `session.jsonl` (`tool-outputs/`, `approval-review/`, …), one
    // level below the 4 the tree allows: walked into, each held every Muse pane on "the transcript depth limit was reached".
    const work = join(root, 'work')
    mkdirSync(work)
    const folder = join(root, 'muse', 'sessions', '2026', '10', '09', SID)
    const path = file(join(folder, 'session.jsonl'), [
      JSON.stringify({ payload: { record: { workspace_root: work } } }),
      JSON.stringify({ payload: { kind: 'run', event: { kind: 'started', prompt: 'hi' } } }),
    ].join('\n') + '\n', START + 5_000)
    file(join(folder, 'tool-outputs', 'call_1.txt'), 'output')
    file(join(folder, 'approval-review', 'note.txt'), 'x')
    file(join(folder, 'a-folder-muse-adds-next', 'deeper', 'x.jsonl'), body())
    file(join(folder, 'subagent', 'child', 'session.jsonl'), 'x')
    await expect(repair.findLiveSession('muse', work, START)).resolves.toEqual({ sessionId: SID, transcriptPath: path })
  })

  it('binds a Muse 1.4 session whose transcript opens with a retained permission frame', async () => {
    const work = join(root, 'work')
    mkdirSync(work)
    const folder = join(root, 'muse', 'sessions', '2026', '10', '09', SID)
    const path = file(join(folder, 'session.jsonl'), [
      JSON.stringify({ retained_frame: 'session_permission_transaction', frame_schema_version: 1, children: [] }),
      JSON.stringify({ payload: { kind: 'session', record: { workspace_root: work } } }),
      JSON.stringify({ payload: { kind: 'run', event: { kind: 'started', prompt: 'hi' } } }),
    ].join('\n') + '\n', START + 5_000)
    await expect(repair.findLiveSession('muse', work, START)).resolves.toEqual({ sessionId: SID, transcriptPath: path })
  })

  it('holds on an unreadable subtree and recovers on a later complete scan', async () => {
    const path = transcript()
    const hidden = join(root, 'claude', 'projects', 'unknown'); mkdirSync(hidden)
    const actual = await vi.importActual<typeof import('node:fs/promises')>('node:fs/promises')
    vi.mocked(fs.opendir).mockImplementation(async (path, options) => {
      if (String(path) === hidden) throw Object.assign(new Error('fixture denied'), { code: 'EACCES' })
      return actual.opendir(path, options)
    })
    await expect(scan()).rejects.toThrow('directory could not be read')
    vi.mocked(fs.opendir).mockImplementation(actual.opendir)
    await expect(scan()).resolves.toEqual({ sessionId: SID, transcriptPath: path })
  })

  it('bounds directory iteration itself and closes its iterator on exhaustion', async () => {
    let reads = 0, closed = false
    const directory = { async *[Symbol.asyncIterator]() {
      try { while (true) { reads++; yield { name: `unrelated-${reads}` } } }
      finally { closed = true }
    } }
    vi.mocked(fs.opendir).mockResolvedValueOnce(directory as never)
    await expect((async () => { for await (const _entry of identityEntries('/fixture', identityScanBudget())) { /* consume */ } })())
      .rejects.toThrow('directory entry limit')
    expect(reads).toBe(4096)
    expect(closed).toBe(true)
    expect(fs.opendir).toHaveBeenLastCalledWith('/fixture', { bufferSize: 32 })
  })

  it.each(['read error', 'byte limit', 'line limit', 'unknown sidechain', 'empty', 'partial'])('does not choose a sibling when another header has %s', async mode => {
    transcript('sibling')
    const path = transcript('unknown')
    if (mode === 'empty') file(path, '')
    if (mode === 'partial') file(path, '{"cwd":"/workspace')
    if (mode === 'byte limit') file(path, ' '.repeat(256 * 1024) + body())
    if (mode === 'line limit') file(path, '{}\n'.repeat(20) + body())
    if (mode === 'unknown sidechain') file(path, JSON.stringify({ cwd: CWD }) + '\n' + '{}\n'.repeat(20) + '{"isSidechain":true}\n')
    if (mode === 'read error') {
      const actual = await vi.importActual<typeof import('node:fs/promises')>('node:fs/promises')
      vi.mocked(fs.open).mockImplementation(async (name, flags, mode) => {
        if (String(name) === path) throw Object.assign(new Error('fixture denied'), { code: 'EACCES' })
        return actual.open(name, flags, mode)
      })
    }
    await expect(scan()).rejects.toThrow('Conversation identity is held')
  })

  it.each([
    ['a long session opening with checkpoint snapshots', 60, 88 * 1024, 'resolves'],
    ['snapshots past the byte bound', 400, 88 * 1024, 'held'],
  ] as const)('reads past %s to its cwd', async (_name, count, bytes, outcome) => {
    const path = transcript()
    const snapshot = JSON.stringify({ type: 'file-history-snapshot', messageId: 'm', snapshot: { trackedFileBackups: 'x'.repeat(bytes) } }) + '\n'
    const head = ['ai-title', 'agent-name', 'mode', 'permission-mode'].map(type => JSON.stringify({ type, sessionId: 'resumed' }) + '\n').join('')
    file(join(root, 'claude', 'projects', 'work', 'resumed.jsonl'), head + snapshot.repeat(count) + body('/elsewhere') + 'later\n')
    if (outcome === 'resolves') await expect(scan()).resolves.toEqual({ sessionId: SID, transcriptPath: path })
    else await expect(scan()).rejects.toThrow('header exceeds the read limit')
  })

  it('still holds on a large record that is not a skipped snapshot', async () => {
    transcript()
    file(join(root, 'claude', 'projects', 'work', 'big.jsonl'), JSON.stringify({ type: 'user', text: 'x'.repeat(300 * 1024) }) + '\n' + body('/elsewhere'))
    await expect(scan()).rejects.toThrow('header exceeds the read limit')
  })

  it('can exclude a confirmed different cwd without reading its remaining history', async () => {
    const path = transcript()
    file(join(root, 'claude', 'projects', 'other.jsonl'), JSON.stringify({ cwd: '/elsewhere' }) + '\n' + 'x'.repeat(2 * 1024 * 1024))
    await expect(scan()).resolves.toEqual({ sessionId: SID, transcriptPath: path })
  })

  it.each(['claude', 'codex', 'codex-profile'])('rechecks %s home authority after an awaited native lookup', async mode => {
    const moved = join(root, 'new-home')
    const homes = await import('./engineHomes.js')
    const codex = mode !== 'claude'
    const header = (id: string) => JSON.stringify({ type: 'session_meta', payload: { id, cwd: CWD } }) + '\n'
    const own = codex ? file(join(root, 'codex', 'sessions', `rollout-${SID}.jsonl`), header(SID)) : transcript()
    const other = codex ? file(join(moved, 'sessions', `rollout-${OTHER}.jsonl`), header(OTHER))
      : file(join(moved, 'projects', 'work', `${OTHER}.jsonl`), body())
    if (codex) {
      const { processRows } = await import('./processTable.js')
      const { readDescriptorEvidence } = await import('../engines/kit/nativeDescriptors.js')
      vi.mocked(processRows).mockResolvedValue([{ pid: 77, parentPid: 1, executable: 'codex', args: 'codex', startMarker: new Date(START).toString() }])
      vi.mocked(readDescriptorEvidence).mockImplementation(nativeConversationFixture(async () => [own, other]).descriptors)
    }
    const actual = await vi.importActual<typeof import('node:fs/promises')>('node:fs/promises')
    let adopted = false
    vi.mocked(fs.open).mockImplementation(async (name, flags, mode) => {
      if (String(name) === own && !adopted) {
        adopted = true
        homes.adoptEngineHomes(codex ? { CODEX_HOME: moved } : { CLAUDE_CONFIG_DIR: moved },
          { claudeHome: join(root, 'claude'), codexHome: join(root, 'codex') })
      }
      return actual.open(name, flags, mode)
    })
    const result = codex ? repair.findLiveSession('codex', CWD, START,
      { pid: 77, ...(mode === 'codex-profile' ? { codexHome: join(root, 'codex') } : {}) }) : scan()
    if (mode === 'codex-profile') await expect(result).resolves.toEqual({ sessionId: SID, transcriptPath: own })
    else await expect(result).rejects.toThrow('known session homes changed')
    expect(adopted).toBe(true)
  })
})

describe('bounded native metadata', () => {
  it.each(['empty', 'partial', 'line limit'])('holds Copilot with a %s competing header', async mode => {
    const header = JSON.stringify({ type: 'session.start', data: { context: { cwd: CWD } } }) + '\n'
    file(join(root, 'copilot', 'session-state', SID, 'events.jsonl'), header)
    file(join(root, 'copilot', 'session-state', OTHER, 'events.jsonl'), mode === 'empty' ? ''
      : mode === 'partial' ? '{"type":"session.start","data":' : '{}\n'.repeat(5) + header)
    await expect(repair.findLiveSession('copilot', CWD, START)).rejects.toThrow('identity is held')
  })

  it.each(['empty', 'partial', 'oversized', 'read error'])('holds Codex with a %s competing rollout, including process-owned files', async mode => {
    const home = join(root, 'codex', 'sessions')
    const header = (id: string) => JSON.stringify({ type: 'session_meta', payload: { id, cwd: CWD } }) + '\n'
    const own = file(join(home, `rollout-${SID}.jsonl`), header(SID))
    const other = file(join(home, `rollout-${OTHER}.jsonl`), mode === 'empty' ? ''
      : mode === 'partial' ? '{"type":"session_meta","payload":' : ' '.repeat(128 * 1024) + header(OTHER))
    if (mode === 'read error') {
      const actual = await vi.importActual<typeof import('node:fs/promises')>('node:fs/promises')
      vi.mocked(fs.open).mockImplementation(async (name, flags, mode) => {
        if (String(name) === other) throw Object.assign(new Error('fixture denied'), { code: 'EACCES' })
        return actual.open(name, flags, mode)
      })
    }
    await expect(repair.findLiveSession('codex', CWD, START)).rejects.toThrow('identity is held')
    await expect(repair.openFileSessionOf('codex', 77, home, CWD, { sources: nativeConversationFixture(async () => [own, other]) })).rejects.toThrow('identity is held')
  })

  it.each(['empty', 'workspace', 'run'])('holds Muse with a partly written %s identity beside a complete run', async mode => {
    const base = join(root, 'muse', 'sessions', '2026', '10', '09')
    const header = JSON.stringify({ payload: { record: { workspace_root: CWD } } }) + '\n'
    const run = JSON.stringify({ payload: { kind: 'run', event: { kind: 'started' } } }) + '\n'
    file(join(base, SID, 'session.jsonl'), header + run)
    file(join(base, OTHER, 'session.jsonl'), mode === 'empty' ? '' : mode === 'workspace' ? '{"payload":' : header + '{"payload":')
    await expect(repair.findLiveSession('muse', CWD, START)).rejects.toThrow('identity is held')
  })

  it('reads Copilot opening records without loading a history larger than a JS string', async () => {
    const path = file(join(root, 'copilot', 'session-state', SID, 'events.jsonl'),
      JSON.stringify({ type: 'session.start', data: { context: { cwd: CWD } } }) + '\n')
    truncateSync(path, constants.MAX_STRING_LENGTH + 4096)
    await expect(repair.findLiveSession('copilot', CWD, START)).resolves.toEqual({ sessionId: SID, transcriptPath: path })
  })

  it('holds Copilot when its first identity record exceeds the bounded prefix', async () => {
    file(join(root, 'copilot', 'session-state', SID, 'events.jsonl'), ' '.repeat(256 * 1024) + JSON.stringify({ type: 'session.start', data: { context: { cwd: CWD } } }))
    await expect(repair.findLiveSession('copilot', CWD, START)).rejects.toThrow('header exceeds the read limit')
  })

  it('rejects an oversized Grok sidecar instead of matching a truncated directory', async () => {
    const group = join(root, 'grok', 'sessions', 'hashed')
    file(join(group, SID, 'updates.jsonl'), '{}\n')
    file(join(group, '.cwd'), CWD + ' '.repeat(64 * 1024))
    await expect(repair.findLiveSession('grok', CWD, START)).rejects.toThrow('native record exceeds')
  })

  it.each(['missing', 'relative'])('holds a Grok hash folder with a %s working directory', async mode => {
    file(join(root, 'grok', 'sessions', encodeURIComponent(CWD), SID, 'updates.jsonl'), '{}\n')
    const group = join(root, 'grok', 'sessions', 'hashed')
    file(join(group, OTHER, 'updates.jsonl'), '{}\n')
    if (mode === 'relative') file(join(group, '.cwd'), 'relative')
    await expect(repair.findLiveSession('grok', CWD, START)).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
  })

  it('holds a native record removed between opening and verifying its path', async () => {
    const path = record(validRecord())
    const actual = await vi.importActual<typeof import('node:fs/promises')>('node:fs/promises')
    const handle = await actual.open(path, 'r')
    const original = handle.read.bind(handle)
    vi.spyOn(handle, 'read').mockImplementationOnce((async (...args: Parameters<typeof handle.read>) => {
      const result = await Reflect.apply(original, handle, args)
      rmSync(path)
      return result
    }) as typeof handle.read)
    vi.mocked(fs.open).mockResolvedValueOnce(handle)
    await expect(repair.processSessionOf('claude', 77, CWD, START)).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
    expect(handle.fd).toBe(-1)
  })

  it.each(['malformed', 'oversized', 'read error', 'missing transcript'])('does not fall back to a sibling after a %s process record', async mode => {
    transcript(OTHER)
    const path = record(mode === 'malformed' ? '{' : mode === 'oversized' ? validRecord() + ' '.repeat(64 * 1024) : validRecord())
    if (mode === 'read error') {
      const actual = await vi.importActual<typeof import('node:fs/promises')>('node:fs/promises')
      vi.mocked(fs.open).mockImplementation(async (name, flags, mode) => {
        if (String(name) === path) throw Object.assign(new Error('fixture denied'), { code: 'EACCES' })
        return actual.open(name, flags, mode)
      })
    }
    const found = repair.findLiveSession('claude', CWD, START, { pid: 77 })
    // A valid record whose conversation is not written yet names no session: still never the sibling's.
    if (mode === 'missing transcript') await expect(found).resolves.toBeNull()
    else await expect(found).rejects.toThrow('Conversation identity is held')
  })

  it.each(['unreadable', 'conflicting'])('does not accept the first home before checking a %s moved-home record', async mode => {
    transcript(); record(validRecord())
    const moved = join(root, 'moved')
    file(join(moved, 'projects', 'work', `${OTHER}.jsonl`), body())
    record(mode === 'unreadable' ? '{' : validRecord(OTHER), moved)
    const homes = await import('./engineHomes.js')
    homes.adoptEngineHomes({ CLAUDE_CONFIG_DIR: moved }, { claudeHome: join(root, 'claude'), codexHome: join(root, 'codex') })
    await expect(repair.processSessionOf('claude', 77, CWD, START)).rejects.toThrow('Conversation identity is held')
  })

  it.each([{ procStart: '' }, { procStart: 'garbage' }, { cwd: '' }, { cwd: 'relative' }, { cwd: '/another/workspace' }])(
    'does not fall back after invalid or contradictory current process evidence %j', async fields => {
      transcript(OTHER)
      record(JSON.stringify({ ...JSON.parse(validRecord()), ...fields }))
      await expect(repair.findLiveSession('claude', CWD, START, { pid: 77 })).rejects.toThrow('identity is held')
    })

  it.each(['initial', 'validation'])('rechecks the authoritative claim after later homes in the %s pass', async pass => {
    transcript(); transcript(OTHER)
    const first = record(validRecord())
    const moved = join(root, 'moved')
    const later = record(JSON.stringify({ ...JSON.parse(validRecord()), pid: 88 }), moved)
    const homes = await import('./engineHomes.js')
    homes.adoptEngineHomes({ CLAUDE_CONFIG_DIR: moved }, { claudeHome: join(root, 'claude'), codexHome: join(root, 'codex') })
    const actual = await vi.importActual<typeof import('node:fs/promises')>('node:fs/promises')
    let reads = 0
    vi.mocked(fs.open).mockImplementation(async (name, flags, mode) => {
      if (String(name) === later && ++reads === (pass === 'initial' ? 1 : 3)) writeFileSync(first, validRecord(OTHER))
      return actual.open(name, flags, mode)
    })
    await expect(repair.processSessionOf('claude', 77, CWD, START)).rejects.toThrow('process records changed')
  })

  it.each(['scan', 'process'])('bounds %s probes even when every saved home is missing', async kind => {
    file(join(root, 'data', 'engine-homes.json'), JSON.stringify({
      claude: Array.from({ length: 65 }, (_, i) => join(root, `missing-${i}`)),
    }))
    await expect(kind === 'scan' ? scan() : repair.processSessionOf('claude', 77, CWD, START))
      .rejects.toThrow('known session-home limit')
    expect(fs.opendir).not.toHaveBeenCalled()
    expect(fs.open).not.toHaveBeenCalled()
  })

  it('holds when the saved home set changes while the authoritative record is rechecked', async () => {
    transcript(); const path = record(validRecord())
    const actual = await vi.importActual<typeof import('node:fs/promises')>('node:fs/promises')
    let reads = 0
    vi.mocked(fs.open).mockImplementation(async (name, flags, mode) => {
      if (String(name) === path && ++reads === 3) {
        file(join(root, 'data', 'engine-homes.json'), JSON.stringify({ claude: [join(root, 'new-home')] }))
      }
      return actual.open(name, flags, mode)
    })
    await expect(repair.processSessionOf('claude', 77, CWD, START)).rejects.toThrow('known session homes changed')
  })

  it('rejects an atomically replaced identity even when its old descriptor stays readable', async () => {
    const path = file(join(root, 'record'), 'before')
    const replacement = file(join(root, 'replacement'), 'after!')
    const actual = await vi.importActual<typeof import('node:fs/promises')>('node:fs/promises')
    const handle = await actual.open(path, 'r')
    let opened = false
    vi.mocked(fs.open).mockImplementation(async (name, flags, mode) => {
      if (String(name) === path) {
        if (!opened) { opened = true; return handle }
        renameSync(replacement, path)
      }
      return actual.open(name, flags, mode)
    })
    await expect(identityBytes(path, 64)).rejects.toThrow(/changed during|replaced during/)
    expect(handle.fd).toBe(-1)
  })

  it('rejects nonregular native records without waiting for a FIFO writer', async () => {
    const path = join(root, 'fifo')
    execFileSync('mkfifo', [path])
    await expect(identityBytes(path, 64)).rejects.toThrow('not a regular file')
  })

  it('rejects a file changing or ending during the read and closes the descriptor', async () => {
    const path = file(join(root, 'record'), 'complete')
    const actual = await vi.importActual<typeof import('node:fs/promises')>('node:fs/promises')
    for (const mode of ['changed', 'ended']) {
      const handle = await actual.open(path, 'r')
      const original = handle.read.bind(handle)
      vi.spyOn(handle, 'read').mockImplementationOnce((async (...args: Parameters<typeof handle.read>) => {
        if (mode === 'ended') return { bytesRead: 0, buffer: args[0] }
        const result = await Reflect.apply(original, handle, args)
        writeFileSync(path, 'changed and longer')
        return result
      }) as typeof handle.read)
      vi.mocked(fs.open).mockResolvedValueOnce(handle)
      await expect(identityBytes(path, 64)).rejects.toThrow(mode === 'changed' ? 'changed during' : 'ended during')
      expect(handle.fd).toBe(-1)
    }
  })
})

it.each(['Stop', 'checkpointed Stop', 'unknown process', 'unknown descriptors', 'Claude record switch', 'Claude new record'])('%s holds before saving, signalling or retiring when real native identity is incomplete', async action => {
  transcript(OTHER); record('{')
  const row = { agentId: 'fixture-agent', engine: 'claude', sessionId: '', cwd: CWD, registeredAt: 1,
    runtimes: [{ backend: 'tmux', paneId: '%77' }],
    processIdentity: { pid: 77, executable: 'claude', startMarker: new Date(START).toISOString() },
  } as RegisteredSession
  const tmux = await import('./processTable.js')
  vi.mocked(tmux.processRows).mockResolvedValue([{ ...row.processIdentity!, parentPid: 1, args: 'claude' }])
  let reason = 'process record is incomplete'
  if (action === 'Claude record switch' || action === 'Claude new record') {
    transcript()
    if (action === 'Claude record switch') record(validRecord())
    else rmSync(join(root, 'claude', 'sessions', '77.json'))
    let probes = 0
    vi.mocked(tmux.processRows).mockImplementation(async () => {
      // Same pid, generation, executable and argv. Only the native conversation switches
      // during the final asynchronous process probe, after the first selected record proof.
      if (++probes === 2) { await Promise.resolve(); record(validRecord(OTHER)) }
      return [{ ...row.processIdentity!, parentPid: 1, args: 'claude' }]
    })
    reason = action === 'Claude new record' ? 'native path or alias changed' : 'process records changed'
  }
  if (action === 'unknown process') { vi.mocked(tmux.processRows).mockResolvedValue(null); reason = 'process graph is incomplete' }
  if (action === 'unknown descriptors') {
    row.engine = 'codex'
    const { readDescriptorEvidence } = await import('../engines/kit/nativeDescriptors.js')
    const { IdentityReadUnavailable } = await import('../engines/kit/identityScan.js')
    vi.mocked(readDescriptorEvidence).mockRejectedValueOnce(new IdentityReadUnavailable('the descriptor probe is incomplete'))
    reason = 'descriptor probe is incomplete'
  }
  const { AgentRestartCoordinator } = await import('./restartAgent.js')
  const { createStopAgentService } = await import('./stopAgentService.js')
  const { terminateDeletedAgent } = await import('./deleteAgentFallback.js')
  const checkpoint = vi.fn(), save = vi.fn(), kill = vi.fn()
  const deps: StopAgentServiceDeps = {
    registry: { resolve: () => row }, stoppedAgents: { save } as unknown as StopAgentServiceDeps['stoppedAgents'],
    restartJobs: new AgentRestartCoordinator(), stopJobs: new Map(), backendFor: () => ({ kill }),
    agentReconciler: { suppress: vi.fn(), holdRoute: vi.fn(), releaseRoute: vi.fn(), trigger: vi.fn() },
    forgetSession: vi.fn(), markDeleted: vi.fn(), clearDeleted: vi.fn(), stopNative: vi.fn(),
  }
  await expect(createStopAgentService(deps)(row.agentId, action === 'checkpointed Stop' ? { checkpoint } : {}))
    .rejects.toThrow(reason)
  expect(save).not.toHaveBeenCalled(); expect(checkpoint).not.toHaveBeenCalled()
  expect(deps.stopNative).not.toHaveBeenCalled(); expect(terminateDeletedAgent).not.toHaveBeenCalled()
  expect(kill).not.toHaveBeenCalled(); expect(deps.forgetSession).not.toHaveBeenCalled()
  expect(deps.markDeleted).not.toHaveBeenCalled(); expect(deps.registry.resolve(row.agentId)).toBe(row)
  expect(deps.stopJobs.size).toBe(0)
})


it('retains lossless descriptor identity when numeric stat values round two inodes together', async () => {
  const path = file(join(root, 'large-inode'), 'exact')
  const actual = await vi.importActual<typeof import('node:fs/promises')>('node:fs/promises')
  const original = await actual.stat(path)
  const version = { ...original, dev: 5, ino: 9007199254740992, fileKey: { device: 5n, inode: 9007199254740992n } }
  expect(Number(9007199254740993n)).toBe(version.ino)
  vi.mocked(fs.open).mockImplementation(async (...args) => {
    const handle = await actual.open(...args)
    vi.spyOn(handle, 'stat').mockImplementation(async (options?: { bigint?: boolean }) => options?.bigint
      ? { ...original, dev: 5n, ino: 9007199254740993n } as never
      : { ...original, dev: 5, ino: version.ino, isFile: () => true } as never)
    return handle
  })
  await expect(identityBytes(path, 64, version)).rejects.toThrow('not the file held by the process')
})