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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { transcriptOf, processSessionOf } from '../../engines/identities.js'
import { loadEngine } from '../../engines/inProcess.js'
import { continuationOf } from '../../engines/sessionFiles.js'
import { isRecentlyDeleted } from '../../lib/deletedSessions.js'
import type { RegisteredSession } from '../../lib/registry.js'
import { findLiveSession, findResumedTranscript } from '../../lib/sessionRepair.js'
import type { DiscoveredTerminalAgent } from '../../lib/terminalAgentDiscovery.js'
import { TerminalAgentReconciler } from '../../lib/terminalAgentReconciler.js'
import { createBinding, statBirthMs, type BindDeps, type RegisteredMeta } from './bind.js'
vi.mock('../../engines/identities.js', () => ({ transcriptOf: vi.fn(), processSessionOf: vi.fn() }))
vi.mock('../../engines/cursor/contract.js', async (real) => ({ ...await real<object>(), cursorDataDir: () => '/cursor' }))
// The optional loader may be unavailable; identity must still be usable.
vi.mock('../../engines/inProcess.js', async (real) => {
const actual = await real<typeof import('../../engines/inProcess.js')>()
return { ...actual, loadEngine: vi.fn(actual.loadEngine) }
})
vi.mock('../../lib/deletedSessions.js', () => ({ isRecentlyDeleted: vi.fn(() => false) }))
vi.mock('../../engines/sessionFiles.js', () => ({ continuationOf: vi.fn(async () => null) }))
vi.mock('../../lib/sessionRepair.js', () => ({
findLiveSession: vi.fn(async () => null),
findResumedTranscript: vi.fn(async () => '/t/resumed.jsonl'),
}))
const dirs: string[] = []
/** Every engine lookup back to its default answer, calls forgotten, before each test. */
function resetLookups() {
vi.mocked(transcriptOf).mockReset().mockImplementation(async engine => `/t/${engine}.jsonl`)
vi.mocked(processSessionOf).mockReset().mockResolvedValue(null)
vi.mocked(loadEngine).mockClear()
vi.mocked(isRecentlyDeleted).mockReset().mockReturnValue(false)
vi.mocked(continuationOf).mockReset().mockResolvedValue(null)
vi.mocked(findLiveSession).mockReset().mockResolvedValue(null)
vi.mocked(findResumedTranscript).mockReset().mockResolvedValue('/t/resumed.jsonl')
}
beforeEach(resetLookups)
const agent = (over: Partial<RegisteredSession> = {}): RegisteredSession =>
({ agentId: 'a1', sessionId: 's1', engine: 'claude', registeredAt: 0, ...over }) as RegisteredSession
const meta = (over: Partial<RegisteredMeta> = {}): RegisteredMeta => ({ isNew: false, evicted: null, rebound: null, ...over })
function setup(over: Partial<BindDeps> = {}) {
const byAgent = new Map<string, RegisteredSession>()
const bySession = new Map<string, RegisteredSession>()
const deps: BindDeps = {
registry: {
inheritName: vi.fn(),
unbindSession: vi.fn(() => true),
byAgent: vi.fn((agentId: string) => byAgent.get(agentId) ?? vi.mocked(deps.registry.register).mock.results.at(-1)?.value?.entry),
byProcess: vi.fn(() => undefined),
register: vi.fn(() => null),
setIdentityHold: vi.fn((id: string, reason?: string) => {
const row = byAgent.get(id) ?? vi.mocked(deps.registry.byProcess).mock.results.at(-1)?.value
if (!row || row.identityHold === reason) return false
if (reason) row.identityHold = reason
else delete row.identityHold
return true
}),
revalidateBinding: vi.fn((id: string) => {
const row = byAgent.get(id) ?? vi.mocked(deps.registry.byProcess).mock.results.at(-1)?.value
if (row) delete row.identityHold
return row ?? null
}),
has: vi.fn(() => false),
bySession: vi.fn((sessionId: string) => bySession.get(sessionId)),
} as unknown as BindDeps['registry'],
mirror: { inheritSummary: vi.fn() },
forgetSession: vi.fn(),
clients: { send: vi.fn() },
attachSession: vi.fn(async () => true),
announceSession: vi.fn(),
stoppedAgents: { save: vi.fn(), finishResume: vi.fn(), get: vi.fn(() => null) },
syncRecapPool: vi.fn(),
input: { forget: vi.fn() },
deviceInput: { forget: vi.fn() },
homes: { copilot: '/copilot', grok: '/grok', agy: '/agy' },
...over,
}
return { deps, byAgent, bySession, binding: createBinding(deps) }
}
function registered(run: ReturnType<typeof setup>, entry: RegisteredSession, meta: RegisteredMeta): Promise<void> {
run.byAgent.set(entry.agentId, entry)
return run.binding.handleRegistered(entry, meta)
}
describe('binding a registered session to its agent', () => {
beforeEach(() => { vi.spyOn(console, 'log').mockImplementation(() => {}) })
afterEach(() => {
vi.restoreAllMocks()
for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true })
})
it('attaches a new session, archives it as the agent\'s, names it and tells the app', async () => {
const run = setup()
const entry = agent({ boundAt: Date.parse('2026-10-04T10:00:00Z') })
run.byAgent.set('a1', entry)
await registered(run, entry, meta({ isNew: true }))
expect(run.deps.attachSession).toHaveBeenCalledWith(entry, true, false, false)
expect(run.deps.stoppedAgents.save).toHaveBeenCalledWith(entry)
expect(run.deps.syncRecapPool).toHaveBeenCalled()
expect(run.deps.registry.inheritName).toHaveBeenCalledWith('a1', 's1')
expect(run.deps.announceSession).toHaveBeenCalledWith(entry)
expect(run.deps.clients.send).toHaveBeenCalledWith({
type: 'session_synced',
payload: { sessionId: 's1', agentId: 'a1', title: expect.any(String), createdAt: '2026-10-04T10:00:00.000Z' },
})
})
// A conversation new to this harness takes it from any stopped harness it came from (conversationOwners.ts).
it('settles who owns a newly bound conversation, and only a newly bound one; a failure never stops the bind', async () => {
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
const owners = { settle: vi.fn(() => []) }
const run = setup({ owners })
const entry = agent({ boundAt: Date.parse('2026-10-04T10:00:00Z') })
await registered(run, entry, meta({ isNew: true }))
expect(owners.settle).toHaveBeenCalledWith(['claude\u0000\u0000\u0000s1'])
await registered(run, entry, meta({ isNew: false }))
expect(owners.settle).toHaveBeenCalledTimes(1)
owners.settle.mockImplementationOnce(() => { throw new Error('stopped store unreadable') })
await registered(run, entry, meta({ isNew: true }))
owners.settle.mockImplementationOnce(() => { throw 'plain' })
await registered(run, entry, meta({ isNew: true }))
expect(warn).toHaveBeenCalledWith('[agent] a1 could not settle who owns s1: stopped store unreadable')
expect(warn).toHaveBeenCalledWith('[agent] a1 could not settle who owns s1: plain')
// Each new binding is still announced after a failed settle (the one that was not new announces nothing).
expect(run.deps.announceSession).toHaveBeenCalledTimes(3)
})
it('still tells the app of a binding when the record it resumes from cannot be saved, as on a full disk', async () => {
const error = vi.spyOn(console, 'error').mockImplementation(() => {})
const run = setup()
const entry = agent({ boundAt: Date.parse('2026-10-04T10:00:00Z'), resumeOnly: true })
run.byAgent.set('a1', entry)
vi.mocked(run.deps.stoppedAgents.save).mockImplementationOnce(() => { throw Object.assign(new Error('ENOSPC: no space left on device'), { code: 'ENOSPC' }) })
await registered(run, entry, meta({ isNew: true }))
expect(error).toHaveBeenCalledWith('[agent] a1 could not save the record it resumes from: ENOSPC: no space left on device')
expect(run.deps.stoppedAgents.finishResume).toHaveBeenCalledWith('a1')
expect(run.deps.announceSession).toHaveBeenCalledWith(entry)
expect(run.deps.clients.send).toHaveBeenCalledWith(expect.objectContaining({ type: 'session_synced' }))
vi.mocked(run.deps.stoppedAgents.save).mockImplementationOnce(() => { throw 'disk gone' })
await registered(run, entry, meta({ isNew: true }))
expect(error).toHaveBeenLastCalledWith('[agent] a1 could not save the record it resumes from: disk gone')
})
it('completes a resumed binding while its optional attachment stays pending', async () => {
const run = setup({ attachSession: vi.fn(() => new Promise<boolean>(() => {})) })
const entry = agent({ resumeOnly: true })
void registered(run, entry, meta({ isNew: true }))
expect(run.deps.stoppedAgents.save).toHaveBeenCalledWith(entry)
expect(run.deps.stoppedAgents.finishResume).toHaveBeenCalledWith('a1')
expect(run.deps.registry.inheritName).toHaveBeenCalledWith('a1', 's1')
expect(run.deps.announceSession).toHaveBeenCalledWith(entry)
expect(run.deps.clients.send).toHaveBeenCalledWith(expect.objectContaining({ type: 'session_synced' }))
expect(run.deps.attachSession).toHaveBeenCalledOnce()
})
it.each([true, false])('ignores a superseded attachment completing with %s', async attached => {
let finish!: (attached: boolean) => void
const run = setup({ attachSession: vi.fn(() => new Promise<boolean>(resolve => { finish = resolve })) })
const first = agent()
const pending = registered(run, first, meta({ isNew: true }))
vi.mocked(run.deps.attachSession).mockResolvedValueOnce(true)
// Mutate the row as the real registry does while the first attachment is still reading.
first.sessionId = 's2'
await registered(run, first, meta({ isNew: true }))
vi.mocked(run.deps.clients.send).mockClear()
vi.mocked(run.deps.announceSession).mockClear()
vi.mocked(run.deps.stoppedAgents.save).mockClear()
vi.mocked(run.deps.registry.inheritName).mockClear()
finish(attached); await pending
expect(run.deps.clients.send).not.toHaveBeenCalled()
expect(run.deps.announceSession).not.toHaveBeenCalled()
expect(run.deps.stoppedAgents.save).not.toHaveBeenCalled()
expect(run.deps.registry.inheritName).not.toHaveBeenCalled()
expect(run.deps.registry.unbindSession).not.toHaveBeenCalled()
})
it('does not start an optional reader if the binding changes during the transcript birth read', async () => {
const run = setup()
const home = mkdtempSync(join(tmpdir(), 'binding-stat-')); dirs.push(home)
const path = join(home, 'transcript.jsonl'); writeFileSync(path, '{}\n')
const entry = agent({ transcriptPath: path })
const pending = registered(run, entry, meta({ isNew: true }))
entry.sessionId = 'replacement'
await pending
expect(run.deps.attachSession).not.toHaveBeenCalled()
expect(run.deps.clients.send).toHaveBeenCalledExactlyOnceWith(expect.objectContaining({
type: 'session_synced', payload: expect.objectContaining({ sessionId: 's1' }),
}))
})
it('stops after the attach for a session it already had, and finishes a resume it was waiting for', async () => {
const run = setup()
const entry = agent({ resumeOnly: true } as Partial<RegisteredSession>)
run.byAgent.set('a1', entry)
await registered(run, entry, meta())
expect(run.deps.stoppedAgents.finishResume).toHaveBeenCalledWith('a1')
expect(run.deps.announceSession).not.toHaveBeenCalled()
// Bound elsewhere by the time the attach finished: not this agent's session to archive.
run.byAgent.set('a1', agent({ sessionId: 'other' }))
vi.mocked(run.deps.stoppedAgents.save).mockClear()
await run.binding.handleRegistered(agent(), meta())
expect(run.deps.stoppedAgents.save).not.toHaveBeenCalled()
})
it('unbinds a session whose pane is gone and re-announces its agent', async () => {
const run = setup({ attachSession: vi.fn(async () => false) })
const entry = agent()
await registered(run, entry, meta({ isNew: true }))
expect(run.deps.registry.unbindSession).toHaveBeenCalledWith('s1')
expect(run.deps.announceSession).toHaveBeenCalledWith(entry)
expect(run.deps.syncRecapPool).toHaveBeenCalled()
})
it('keeps the verified conversation when a native exit beats its pending startup attach', async () => {
let finish!: (attached: boolean) => void
const run = setup({ attachSession: vi.fn(() => new Promise<boolean>(resolve => { finish = resolve })) })
const entry = agent({ processIdentity: { pid: 42, startMarker: '2026-10-06T10:00:00Z', executable: 'claude' } })
const pending = registered(run, entry, meta({ isNew: true, hookEvent: 'SessionStart' }))
await vi.waitFor(() => expect(run.deps.attachSession).toHaveBeenCalled())
finish(false)
await pending
expect(run.deps.registry.unbindSession).not.toHaveBeenCalled()
expect(entry.sessionId).toBe('s1')
expect(run.deps.announceSession).toHaveBeenCalledWith(entry)
expect(run.deps.stoppedAgents.save).toHaveBeenCalledWith(entry)
expect(run.deps.clients.send).toHaveBeenCalledWith(expect.objectContaining({ type: 'session_synced' }))
})
it('keeps the binding of an agent a stop or a restart owns: its pane reads as gone only because of it', async () => {
// The old engine's late SessionStart, registered as a stop or a restart ended that engine. Unbound,
// the stop gave up with its engine already signalled, and a queued restart found nothing to resume.
const run = setup({ attachSession: vi.fn(async () => false) })
const changing = vi.fn((agentId: string) => agentId === 'a1')
run.binding.whileChanging(changing)
const entry = agent()
await registered(run, entry, meta())
expect(changing).toHaveBeenCalledWith('a1')
expect(run.deps.registry.unbindSession).not.toHaveBeenCalled()
expect(run.deps.announceSession).toHaveBeenCalledWith(entry)
// An agent nothing owns is unbound as before.
await registered(run, agent({ agentId: 'a2', sessionId: 's2' }), meta())
expect(run.deps.registry.unbindSession).toHaveBeenCalledWith('s2')
})
it('hands a rebound agent its name and recap, and lets the stale session go', async () => {
const run = setup()
await registered(run, agent({ sessionId: 's2' }), meta({ rebound: 's1' }))
expect(run.deps.registry.inheritName).toHaveBeenCalledWith('s1', 's2')
expect(run.deps.mirror.inheritSummary).toHaveBeenCalledWith('s1', 's2')
expect(run.deps.forgetSession).toHaveBeenCalledWith('s1', { force: true, keepAgent: true })
expect(run.deps.clients.send).toHaveBeenCalledWith({ type: 'session_reset', payload: { staleSessionId: 's1' } })
})
it('forgets an evicted session and an agent the bind emptied out', async () => {
const run = setup()
await registered(run, agent(), meta({ evicted: 's0', orphaned: { agentId: 'a0', sessionId: 's0' } }))
expect(vi.mocked(run.deps.forgetSession).mock.calls).toEqual([
['s0', { force: true }],
['a0', { force: true, agentId: 'a0' }],
])
})
it('gives a fork the recap of its source once its own session reports in', async () => {
const run = setup()
run.binding.pendingForkInherit.set('a1', 'source-s')
await registered(run, agent({ sessionId: '' }), meta())
expect(run.deps.mirror.inheritSummary).not.toHaveBeenCalled()
await registered(run, agent(), meta())
expect(run.deps.mirror.inheritSummary).toHaveBeenCalledWith('source-s', 's1')
expect(run.binding.pendingForkInherit.has('a1')).toBe(false)
})
it('resets on a SessionStart, except for engines that announce one turn more than once', async () => {
const run = setup()
for (const engine of ['claude', 'cursor', 'agy', 'copilot']) {
await registered(run, agent({ engine } as Partial<RegisteredSession>), meta({ hookEvent: 'SessionStart' }))
}
expect(vi.mocked(run.deps.attachSession).mock.calls.map((call) => [call[0].engine, call[1], call[2]])).toEqual([
['claude', true, false], ['cursor', false, true], ['agy', false, false], ['copilot', false, false],
])
})
it('replays a transcript born after its agent from the start, judged by the file\'s birth', async () => {
const run = setup()
const dir = mkdtempSync(join(tmpdir(), 'core-bind-'))
dirs.push(dir)
const born = join(dir, 'session.jsonl')
writeFileSync(born, '{}\n')
await registered(run, agent({ transcriptPath: born, registeredAt: Date.now() - 60_000 }), meta())
await registered(run, agent({ transcriptPath: join(dir, 'missing.jsonl'), registeredAt: Date.now() - 60_000 }), meta())
expect(vi.mocked(run.deps.attachSession).mock.calls.map((call) => call[3])).toEqual([true, false])
})
it('never replays the conversation a resume put back, and judges a new session in that agent like any other', async () => {
const run = setup()
const dir = mkdtempSync(join(tmpdir(), 'core-bind-'))
dirs.push(dir)
const born = join(dir, 'session.jsonl')
writeFileSync(born, '{}\n')
// A resume keeps the row's original registeredAt, so the transcript reads as born after its agent.
const resumed = agent({ transcriptPath: born, registeredAt: Date.now() - 60_000, resumeOnly: true } as Partial<RegisteredSession>)
vi.mocked(run.deps.stoppedAgents.get).mockReturnValue(agent({ sessionId: 's1' }))
await registered(run, resumed, meta())
expect(run.deps.stoppedAgents.get).toHaveBeenCalledWith('a1')
// `/clear` after the resume: a session the stopped record does not hold.
await registered(run, { ...resumed, sessionId: 's2' }, meta())
// A resumed row with no stopped record left to compare against.
vi.mocked(run.deps.stoppedAgents.get).mockReturnValue(null)
await registered(run, resumed, meta())
expect(vi.mocked(run.deps.attachSession).mock.calls.map((call) => call[3])).toEqual([false, true, true])
})
})
describe('binding a running process to its session', () => {
const observed = (over: Partial<DiscoveredTerminalAgent> = {}): DiscoveredTerminalAgent => ({
engine: 'claude',
cwd: '/work',
runtimes: [],
primaryRuntimeKey: 'tmux:%0',
processIdentity: { pid: 42, startMarker: '2026-10-04T10:00:00Z' },
...over,
}) as DiscoveredTerminalAgent
beforeEach(() => { vi.spyOn(console, 'log').mockImplementation(() => {}) })
afterEach(() => { vi.restoreAllMocks(); vi.useRealTimers() })
it('ignores a process no agent runs, and a resume still launching', async () => {
const run = setup()
await run.binding.bindObservedAgent(observed())
vi.mocked(run.deps.registry.byProcess).mockReturnValue(agent({ resumeOnly: true, launch: { state: 'starting' } } as Partial<RegisteredSession>))
await run.binding.bindObservedAgent(observed())
expect(run.deps.registry.register).not.toHaveBeenCalled()
})
it('does not wait for optional transcript attachment before completing binding', async () => {
const run = setup({ attachSession: vi.fn(() => new Promise<boolean>(() => {})) })
vi.mocked(run.deps.registry.byProcess).mockReturnValue(agent({ sessionId: '' }))
vi.mocked(run.deps.registry.register).mockReturnValue({ entry: agent(), ...meta({ isNew: true }) } as never)
let done = false
void run.binding.bindObservedAgent(observed({ resumeSessionId: 'resumed' })).then(() => { done = true })
await vi.waitFor(() => expect(done).toBe(true), { timeout: 1000 })
expect(run.deps.registry.register).toHaveBeenCalledOnce()
expect(run.deps.attachSession).toHaveBeenCalledOnce()
})
it.each([new Error('saved header is incomplete'), 'saved header is incomplete'])(
'keeps a saved binding visibly held until its own evidence recovers: %s', async error => {
const run = setup(), row = agent({ transcriptPath: '/t/s1.jsonl', identityHold: 'previous hold' })
vi.mocked(run.deps.registry.byProcess).mockReturnValue(row)
vi.mocked(run.deps.registry.revalidateBinding).mockImplementationOnce(() => { throw error })
.mockImplementationOnce(() => { throw error })
await run.binding.bindObservedAgent(observed())
await run.binding.bindObservedAgent(observed())
expect(row).toMatchObject({ sessionId: 's1', transcriptPath: '/t/s1.jsonl', identityHold: 'saved header is incomplete' })
expect(run.deps.announceSession).toHaveBeenCalledOnce()
expect(continuationOf).not.toHaveBeenCalled()
expect(run.deps.registry.unbindSession).not.toHaveBeenCalled()
expect(run.deps.stoppedAgents.save).not.toHaveBeenCalled()
await run.binding.bindObservedAgent(observed())
expect(row).not.toHaveProperty('identityHold')
expect(run.deps.announceSession).toHaveBeenCalledTimes(2)
expect(continuationOf).toHaveBeenCalledOnce()
})
it('does not follow a saved binding removed while its retry commits', async () => {
const run = setup(), row = agent({ transcriptPath: '/t/s1.jsonl', identityHold: 'unavailable' })
vi.mocked(run.deps.registry.byProcess).mockReturnValue(row)
vi.mocked(run.deps.registry.revalidateBinding).mockReturnValue(null)
await run.binding.bindObservedAgent(observed())
expect(run.deps.announceSession).not.toHaveBeenCalled()
expect(continuationOf).not.toHaveBeenCalled()
})
it.each(['repaired', 'same', 'absent'] as const)('updates transcript attachment after a held binding is conclusively %s', async outcome => {
const run = setup(), row = agent({ transcriptPath: '/t/child.jsonl', identityHold: 'unavailable' })
run.byAgent.set(row.agentId, row)
vi.mocked(run.deps.registry.byProcess).mockReturnValue(row)
vi.mocked(run.deps.registry.revalidateBinding).mockImplementation(() => {
Object.assign(row, { sessionId: outcome === 'absent' ? '' : 's1', transcriptPath: outcome === 'absent' ? null : outcome === 'same' ? row.transcriptPath : '/t/parent.jsonl' })
delete row.identityHold
return row
})
await run.binding.bindObservedAgent(observed())
if (outcome === 'absent') {
expect(run.deps.forgetSession).toHaveBeenCalledWith('s1', { force: true, keepAgent: true, agentId: 'a1' })
expect(run.deps.stoppedAgents.save).not.toHaveBeenCalled()
} else {
await vi.waitFor(() => expect(run.deps.attachSession).toHaveBeenCalledWith(row, true, false, false))
expect(run.deps.forgetSession).not.toHaveBeenCalled()
}
expect(run.deps.announceSession).toHaveBeenCalledWith(row)
})
it.each(['changing', 'deleted'] as const)('does not retry a binding whose process is %s', async state => {
const run = setup(), row = agent({ transcriptPath: '/t/s1.jsonl', identityHold: 'unavailable' })
vi.mocked(run.deps.registry.byProcess).mockReturnValue(row)
if (state === 'changing') run.binding.whileChanging(() => true)
else vi.mocked(isRecentlyDeleted).mockReturnValue(true)
await run.binding.bindObservedAgent(observed())
expect(run.deps.registry.revalidateBinding).not.toHaveBeenCalled()
expect(continuationOf).not.toHaveBeenCalled()
})
it('contains a registration failure, keeps the reason, and retries an unbound process', async () => {
const run = setup(), row = agent({ sessionId: '', identityHold: 'waiting for first transcript' })
vi.mocked(run.deps.registry.byProcess).mockReturnValue(row)
vi.mocked(run.deps.registry.register).mockImplementationOnce(() => { throw new Error('binding evidence changed') })
await run.binding.bindObservedAgent(observed({ resumeSessionId: 'resumed' }))
expect(row).toMatchObject({ sessionId: '', identityHold: 'binding evidence changed' })
expect(run.deps.registry.revalidateBinding).not.toHaveBeenCalled()
expect(run.deps.stoppedAgents.save).not.toHaveBeenCalled()
vi.mocked(run.deps.registry.register).mockReturnValue({ entry: agent(), ...meta({ isNew: true }) } as never)
await run.binding.bindObservedAgent(observed({ resumeSessionId: 'resumed' }))
expect(run.deps.attachSession).toHaveBeenCalledOnce()
})
it.each([new Error('identity read limit'), 'identity read limit'])('holds only the unreadable native identity and finishes the discovery/readiness pass: %s', async error => {
const run = setup()
const rows = [agent({ engine: 'muse', agentId: 'held', sessionId: '', runtimes: [], active: true,
processIdentity: { pid: 42, executable: 'muse', startMarker: '2026-10-09T00:00:00Z' } }),
agent({ engine: 'codex', agentId: 'next', sessionId: '', runtimes: [], active: true,
processIdentity: { pid: 43, executable: 'codex', startMarker: '2026-10-09T00:00:00Z' } })]
for (const row of rows) run.byAgent.set(row.agentId, row)
vi.mocked(run.deps.registry.byProcess).mockImplementation(engine => rows.find(row => row.engine === engine))
vi.mocked(findLiveSession).mockImplementation(async engine => {
if (engine === 'muse') throw error
return { sessionId: 'found', transcriptPath: '/t/found.jsonl' }
})
vi.mocked(run.deps.registry.register).mockImplementation(request => {
Object.assign(rows[1]!, { sessionId: request.sessionId, transcriptPath: request.transcriptPath })
return { entry: rows[1]!, ...meta({ isNew: true }) } as never
})
const onProbeStatus = vi.fn(), onRemoved = vi.fn(), onDormant = vi.fn()
const reconciler = new TerminalAgentReconciler({
current: () => rows, backends: [], backendOrder: ['tmux'], onProbeStatus, onRemoved, onDormant,
onDiscovered: run.binding.bindObservedAgent, onObserved: run.binding.bindObservedAgent,
probe: async () => ({ processTableAvailable: true, targets: [], ambiguousPlacements: new Set(),
agents: rows.map(row => observed({ engine: row.engine, processIdentity: row.processIdentity! })) }),
})
try {
await expect(reconciler.start(60_000)).resolves.toBeUndefined()
expect(rows[0]!.sessionId).toBe('')
expect(rows[1]!.sessionId).toBe('found')
expect(run.deps.registry.register).toHaveBeenCalledOnce()
expect(run.deps.stoppedAgents.save).toHaveBeenCalledExactlyOnceWith(rows[1])
expect(onRemoved).not.toHaveBeenCalled(); expect(onDormant).not.toHaveBeenCalled()
expect(onProbeStatus).toHaveBeenCalledWith({ ready: true, error: null })
expect(console.log).toHaveBeenCalledWith('[discovery] held binding held · identity read limit')
} finally { reconciler.stop() }
})
it.each(['copilot-process', 'copilot-transcript', 'continuation', 'cursor-resume', 'grok-resume',
'agy-resume', 'copilot-resume', 'claude-resume', 'codex-resume'] as const)(
'isolates %s failure from readiness and retries the same live binding', async kind => {
const run = setup()
const engine = kind === 'continuation' ? 'claude' : kind.split('-')[0] as DiscoveredTerminalAgent['engine']
const alreadyBound = kind === 'continuation' || kind === 'copilot-process' || kind === 'copilot-transcript'
const rows = [agent({ engine, agentId: 'held', sessionId: alreadyBound ? 'previous' : '',
transcriptPath: alreadyBound ? '/t/previous.jsonl' : undefined, runtimes: [], active: true,
processIdentity: { pid: 42, executable: engine, startMarker: '2026-10-09T00:00:00Z' } }),
agent({ engine: 'codex', agentId: 'next', sessionId: '', runtimes: [], active: true,
processIdentity: { pid: 43, executable: 'codex', startMarker: '2026-10-09T00:00:00Z' } })]
for (const row of rows) run.byAgent.set(row.agentId, row)
vi.mocked(run.deps.registry.byProcess).mockImplementation((_, identity) => rows.find(row => row.processIdentity?.pid === identity.pid))
vi.mocked(findLiveSession).mockResolvedValue({ sessionId: 'sibling', transcriptPath: '/t/sibling.jsonl' })
vi.mocked(processSessionOf).mockResolvedValue('resumed')
const failure = new Error('native evidence unavailable')
if (kind === 'copilot-process') vi.mocked(processSessionOf).mockRejectedValueOnce(failure)
else if (kind === 'continuation') vi.mocked(continuationOf).mockRejectedValueOnce(failure)
else if (kind === 'claude-resume' || kind === 'codex-resume') vi.mocked(findResumedTranscript).mockRejectedValueOnce(failure)
else vi.mocked(transcriptOf).mockRejectedValueOnce(failure)
vi.mocked(run.deps.registry.register).mockImplementation(request => {
const entry = rows.find(row => row.processIdentity?.pid === request.processIdentity?.pid)!
Object.assign(entry, { sessionId: request.sessionId, transcriptPath: request.transcriptPath })
return { entry, ...meta({ isNew: true }) } as never
})
const held = observed({ engine, processIdentity: rows[0]!.processIdentity!, resumeSessionId: alreadyBound ? null : 'resumed' })
const onProbeStatus = vi.fn(), onRemoved = vi.fn(), onDormant = vi.fn()
const reconciler = new TerminalAgentReconciler({
current: () => rows, backends: [], backendOrder: ['tmux'], onProbeStatus, onRemoved, onDormant,
onDiscovered: run.binding.bindObservedAgent, onObserved: run.binding.bindObservedAgent,
probe: async () => ({ processTableAvailable: true, targets: [], ambiguousPlacements: new Set(),
agents: [held, observed({ engine: 'codex', processIdentity: rows[1]!.processIdentity! })] }),
})
try {
await expect(reconciler.start(60_000)).resolves.toBeUndefined()
expect(rows[0]!.sessionId).toBe(alreadyBound ? 'previous' : '')
expect(rows[1]!.sessionId).toBe('sibling')
expect(onProbeStatus).toHaveBeenCalledWith({ ready: true, error: null })
expect(onRemoved).not.toHaveBeenCalled(); expect(onDormant).not.toHaveBeenCalled()
expect(run.deps.stoppedAgents.save).toHaveBeenCalledExactlyOnceWith(rows[1])
expect(console.log).toHaveBeenCalledWith('[discovery] held binding held · native evidence unavailable')
vi.mocked(continuationOf).mockResolvedValue({ sessionId: 'resumed', transcriptPath: '/t/resumed.jsonl' })
await run.binding.bindObservedAgent(held)
expect(rows[0]!.sessionId).toBe('resumed')
} finally { reconciler.stop() }
})
it('discards a rejected native read after the session has changed ownership', async () => {
const run = setup(), row = agent({ sessionId: '' })
vi.mocked(run.deps.registry.byProcess).mockReturnValue(row)
let reject!: (error: Error) => void
vi.mocked(findResumedTranscript).mockReturnValueOnce(new Promise((_, no) => { reject = no }))
const pending = run.binding.bindObservedAgent(observed({ resumeSessionId: 'resumed' }))
row.sessionId = 'replacement'; reject(new Error('obsolete lookup failed')); await pending
expect(run.deps.registry.register).not.toHaveBeenCalled()
expect(console.log).not.toHaveBeenCalled()
})
it.each([new Error('reader unavailable'), 'reader unavailable'])('contains an optional attachment failure after binding', async error => {
const log = vi.spyOn(console, 'error').mockImplementation(() => {})
const run = setup({ attachSession: vi.fn(async () => { throw error }) })
vi.mocked(run.deps.registry.byProcess).mockReturnValue(agent({ sessionId: '' }))
vi.mocked(run.deps.registry.register).mockReturnValue({ entry: agent(), ...meta({ isNew: true }) } as never)
await run.binding.bindObservedAgent(observed({ resumeSessionId: 'resumed' }))
await vi.waitFor(() => expect(log).toHaveBeenCalledWith('[agent] a1 transcript attachment is unavailable: reader unavailable'))
expect(run.deps.registry.register).toHaveBeenCalledOnce()
expect(run.deps.registry.unbindSession).not.toHaveBeenCalled()
})
it.each(['binding', 'process', 'stop', 'changing'] as const)('discards a delayed lookup after %s changed its authority', async change => {
const run = setup()
const entry = agent({ sessionId: '', processIdentity: { pid: 42, startMarker: '2026-10-04T10:00:00Z', executable: 'cursor' } })
vi.mocked(run.deps.registry.byProcess).mockReturnValue(entry)
let answer!: (path: string | null) => void
vi.mocked(transcriptOf).mockReturnValueOnce(new Promise(resolve => { answer = resolve }))
const pending = run.binding.bindObservedAgent(observed({ engine: 'cursor', resumeSessionId: 'resumed' }))
if (change === 'binding') entry.sessionId = 'newer'
if (change === 'process') vi.mocked(run.deps.registry.byProcess).mockReturnValue(undefined)
if (change === 'stop') vi.mocked(isRecentlyDeleted).mockImplementation(id => id === entry.agentId)
if (change === 'changing') run.binding.whileChanging(() => true)
answer('/fixture/transcript.jsonl'); await pending
expect(run.deps.registry.register).not.toHaveBeenCalled()
})
it.each(['newer owner', 'target stopped'] as const)('rechecks the target after resume evidence waits: %s', async change => {
const run = setup()
vi.mocked(run.deps.registry.byProcess).mockReturnValue(agent({ sessionId: '' }))
let answer!: (path: string | null) => void
vi.mocked(transcriptOf).mockReturnValueOnce(new Promise(resolve => { answer = resolve }))
const pending = run.binding.bindObservedAgent(observed({ engine: 'cursor', resumeSessionId: 'r' }))
if (change === 'newer owner') run.bySession.set('r', agent({ agentId: 'newer', processIdentity: {
pid: 43, startMarker: '2026-10-04T11:00:00Z', executable: 'cursor',
} }))
else vi.mocked(isRecentlyDeleted).mockImplementation(id => id === 'r')
answer('/fixture/transcript.jsonl'); await pending
expect(run.deps.registry.register).not.toHaveBeenCalled()
})
it.each(['copilot', 'claude'] as const)('rejects a delayed %s continuation after the receiving binding changes', async engine => {
const run = setup()
const entry = agent({ engine, transcriptPath: '/t/s1.jsonl' })
vi.mocked(run.deps.registry.byProcess).mockReturnValue(entry)
let answer!: () => void
if (engine === 'copilot') vi.mocked(processSessionOf).mockResolvedValue('s2').mockReturnValueOnce(new Promise(resolve => { answer = () => resolve('s2') }))
else vi.mocked(continuationOf).mockReturnValueOnce(new Promise(resolve => { answer = () => resolve({ sessionId: 's2', transcriptPath: '/t/s2.jsonl' }) }))
const pending = run.binding.bindObservedAgent(observed({ engine }))
entry.sessionId = 'newer'
answer(); await pending
expect(run.deps.registry.register).not.toHaveBeenCalled()
})
it('does not take a Copilot resume target that was stopped during its transcript lookup', async () => {
const run = setup()
vi.mocked(run.deps.registry.byProcess).mockReturnValue(agent({ engine: 'copilot' }))
vi.mocked(processSessionOf).mockResolvedValue('s2')
let answer!: (path: string | null) => void
vi.mocked(transcriptOf).mockReturnValueOnce(new Promise(resolve => { answer = resolve }))
const pending = run.binding.bindObservedAgent(observed({ engine: 'copilot' }))
await vi.waitFor(() => expect(answer).toBeTypeOf('function'))
vi.mocked(isRecentlyDeleted).mockImplementation(id => id === 's2')
answer('/fixture/transcript.jsonl'); await pending
expect(run.deps.registry.register).not.toHaveBeenCalled()
})
it.each(['s3', null])('holds a Copilot conversation changed to %s during transcript lookup', async next => {
const run = setup(), row = agent({ engine: 'copilot' })
vi.mocked(run.deps.registry.byProcess).mockReturnValue(row)
vi.mocked(processSessionOf).mockResolvedValueOnce('s2').mockResolvedValueOnce(next)
await run.binding.bindObservedAgent(observed({ engine: 'copilot' }))
expect(run.deps.registry.register).not.toHaveBeenCalled()
expect(row.sessionId).toBe('s1')
expect(console.log).toHaveBeenCalledWith(expect.stringContaining('process conversation changed during transcript lookup'))
})
describe('an agent that already has a session', () => {
it('follows Copilot to the session it /resumed into, and only to a new one', async () => {
const run = setup()
vi.mocked(run.deps.registry.byProcess).mockReturnValue(agent({ engine: 'copilot' } as Partial<RegisteredSession>))
await run.binding.bindObservedAgent(observed({ engine: 'copilot' }))
vi.mocked(processSessionOf).mockResolvedValueOnce('s1')
await run.binding.bindObservedAgent(observed({ engine: 'copilot' }))
vi.mocked(processSessionOf).mockResolvedValueOnce('deleted')
vi.mocked(isRecentlyDeleted).mockImplementation(id => id === 'deleted')
await run.binding.bindObservedAgent(observed({ engine: 'copilot' }))
expect(run.deps.registry.register).not.toHaveBeenCalled()
vi.mocked(processSessionOf).mockResolvedValue('s2')
const rotated = agent({ engine: 'copilot', sessionId: 's2' } as Partial<RegisteredSession>)
vi.mocked(run.deps.registry.register).mockReturnValueOnce({ entry: rotated, ...meta({ isNew: true }) } as never)
await run.binding.bindObservedAgent(observed({ engine: 'copilot' }))
expect(processSessionOf).toHaveBeenLastCalledWith('copilot', '/copilot', 42)
expect(transcriptOf).toHaveBeenLastCalledWith('copilot', '/copilot', 's2')
expect(vi.mocked(run.deps.registry.register).mock.calls[0][0]).toMatchObject({ sessionId: 's2', transcriptPath: '/t/copilot.jsonl', source: 'copilot-resume' })
expect(run.deps.attachSession).toHaveBeenCalledWith(rotated, true, false, false)
// Not new to the registry, or no transcript yet: registered as it is, attached by its hook later.
vi.mocked(transcriptOf).mockResolvedValueOnce(null)
vi.mocked(run.deps.registry.register).mockReturnValueOnce({ entry: rotated, ...meta() } as never)
await run.binding.bindObservedAgent(observed({ engine: 'copilot' }))
expect(vi.mocked(run.deps.registry.register).mock.calls[1][0]).toMatchObject({ transcriptPath: undefined })
expect(run.deps.attachSession).toHaveBeenCalledTimes(1)
})
it('follows Claude Code to the file its transcript rolled over to, when that is new', async () => {
const run = setup()
vi.mocked(run.deps.registry.byProcess).mockReturnValue(agent({ transcriptPath: '/t/s1.jsonl' }))
await run.binding.bindObservedAgent(observed())
for (const continuation of [{ sessionId: 's1' }, { sessionId: 'known' }, { sessionId: 'deleted' }]) {
vi.mocked(continuationOf).mockResolvedValueOnce({ ...continuation, transcriptPath: '/t/x.jsonl' } as never)
}
vi.mocked(run.deps.registry.has).mockImplementation((sessionId: string) => sessionId === 'known')
vi.mocked(isRecentlyDeleted).mockImplementation((sessionId?: string) => sessionId === 'deleted')
for (let i = 0; i < 3; i++) await run.binding.bindObservedAgent(observed())
expect(run.deps.registry.register).not.toHaveBeenCalled()
vi.mocked(continuationOf).mockResolvedValue({ sessionId: 's2', transcriptPath: '/t/s2.jsonl' } as never)
vi.mocked(run.deps.registry.register).mockReturnValueOnce({ entry: agent({ sessionId: 's2' }), ...meta({ isNew: true }) } as never)
await run.binding.bindObservedAgent(observed())
expect(vi.mocked(run.deps.registry.register).mock.calls[0][0]).toMatchObject({ engine: 'claude', sessionId: 's2', source: 'claude-continuation', hookEvent: 'ClaudeContinuation' })
expect(continuationOf).toHaveBeenCalledWith('claude', '/t/s1.jsonl')
expect(run.deps.attachSession).toHaveBeenCalledTimes(1)
vi.mocked(run.deps.registry.register).mockReturnValueOnce(null)
await run.binding.bindObservedAgent(observed())
expect(run.deps.attachSession).toHaveBeenCalledTimes(1)
})
it('leaves any other engine, or Claude Code without a transcript, as it is', async () => {
const run = setup()
vi.mocked(run.deps.registry.byProcess).mockReturnValueOnce(agent({ engine: 'pi' } as Partial<RegisteredSession>)).mockReturnValueOnce(agent())
await run.binding.bindObservedAgent(observed({ engine: 'pi' }))
await run.binding.bindObservedAgent(observed())
expect(continuationOf).not.toHaveBeenCalled()
})
})
describe('a resume named on the command line', () => {
it('finds each engine\'s transcript where that engine keeps it', async () => {
const run = setup()
vi.mocked(run.deps.registry.byProcess).mockReturnValue(agent({ sessionId: '' }))
const expected: Record<string, string | undefined> = {
cursor: '/t/cursor.jsonl', grok: '/t/grok.jsonl', agy: '/t/agy.jsonl', copilot: '/t/copilot.jsonl',
claude: '/t/resumed.jsonl', codex: '/t/resumed.jsonl', pi: undefined,
}
for (const engine of Object.keys(expected)) {
await run.binding.bindObservedAgent(observed({ engine, resumeSessionId: `${engine}-resumed` } as Partial<DiscoveredTerminalAgent>))
}
expect(vi.mocked(run.deps.registry.register).mock.calls.map(([input]) => [input.engine, input.transcriptPath, input.source, input.hookEvent])).toEqual(
Object.entries(expected).map(([engine, path]) => [engine, path, 'terminal-resume', 'TerminalResumeDiscovery']),
)
expect(transcriptOf).toHaveBeenCalledWith('cursor', '/cursor', 'cursor-resumed', '/work')
expect(transcriptOf).toHaveBeenCalledWith('grok', '/grok', 'grok-resumed', '/work')
expect(transcriptOf).toHaveBeenCalledWith('agy', '/agy', 'agy-resumed', '/work')
expect(findResumedTranscript).toHaveBeenCalledWith('codex', 'codex-resumed', { codexHome: undefined })
})
it('binds and follows Copilot resume while the optional loader cannot answer', async () => {
const run = setup()
vi.mocked(run.deps.registry.byProcess).mockReturnValue(agent({ sessionId: '' }))
vi.mocked(loadEngine).mockImplementation(() => new Promise(() => {}))
try {
for (const engine of ['cursor', 'grok', 'agy', 'copilot']) {
await run.binding.bindObservedAgent(observed({ engine, resumeSessionId: 'r' } as Partial<DiscoveredTerminalAgent>))
}
expect(vi.mocked(run.deps.registry.register).mock.calls.map(([input]) => [input.engine, input.transcriptPath])).toEqual(['cursor', 'grok', 'agy', 'copilot'].map(engine => [engine, `/t/${engine}.jsonl`]))
// Copilot can also switch conversation while optional interpretation is unavailable.
vi.mocked(run.deps.registry.byProcess).mockReturnValue(agent({ engine: 'copilot' } as Partial<RegisteredSession>))
vi.mocked(processSessionOf).mockResolvedValue('s2')
await run.binding.bindObservedAgent(observed({ engine: 'copilot' }))
expect(run.deps.registry.register).toHaveBeenCalledTimes(5)
expect(loadEngine).not.toHaveBeenCalled()
} finally { vi.mocked(loadEngine).mockReset() }
// Claude Code and Codex find theirs with no engine code loaded.
vi.mocked(loadEngine).mockClear()
vi.mocked(run.deps.registry.byProcess).mockReturnValue(agent({ sessionId: '' }))
for (const engine of ['claude', 'codex']) {
await run.binding.bindObservedAgent(observed({ engine, resumeSessionId: `${engine}-resumed` } as Partial<DiscoveredTerminalAgent>))
}
expect(loadEngine).not.toHaveBeenCalled()
})
it('needs a transcript for the engines whose sessions are files, and skips a deleted session', async () => {
const run = setup()
vi.mocked(run.deps.registry.byProcess).mockReturnValue(agent({ sessionId: '', codexHome: '/codex' } as Partial<RegisteredSession>))
vi.mocked(transcriptOf).mockResolvedValueOnce(null)
vi.mocked(transcriptOf).mockResolvedValueOnce(null)
vi.mocked(findResumedTranscript).mockResolvedValueOnce(null).mockResolvedValueOnce(null)
for (const engine of ['cursor', 'grok', 'claude', 'codex']) {
await run.binding.bindObservedAgent(observed({ engine, resumeSessionId: 'r' } as Partial<DiscoveredTerminalAgent>))
}
vi.mocked(transcriptOf).mockResolvedValueOnce(null)
vi.mocked(transcriptOf).mockResolvedValueOnce(null)
await run.binding.bindObservedAgent(observed({ engine: 'agy', resumeSessionId: 'r' } as Partial<DiscoveredTerminalAgent>))
await run.binding.bindObservedAgent(observed({ engine: 'copilot', resumeSessionId: 'r' } as Partial<DiscoveredTerminalAgent>))
vi.mocked(isRecentlyDeleted).mockReturnValueOnce(true)
await run.binding.bindObservedAgent(observed({ resumeSessionId: 'gone' } as Partial<DiscoveredTerminalAgent>))
// agy and Copilot can bind before their file exists; the others cannot.
expect(vi.mocked(run.deps.registry.register).mock.calls.map(([input]) => input.engine)).toEqual(['agy', 'copilot'])
expect(findResumedTranscript).toHaveBeenCalledWith('codex', 'r', { codexHome: '/codex' })
})
it('gives a resumed session to the newer process, never to an older one or one whose start is unknown', async () => {
const run = setup()
vi.mocked(run.deps.registry.byProcess).mockReturnValue(agent({ sessionId: '' }))
// The holder started after this process (10:00), or this process's start cannot be read: it stays.
run.bySession.set('r', agent({ agentId: 'newer', processIdentity: { pid: 1, startMarker: '2026-10-04T11:00:00Z' } } as Partial<RegisteredSession>))
await run.binding.bindObservedAgent(observed({ resumeSessionId: 'r' } as Partial<DiscoveredTerminalAgent>))
await run.binding.bindObservedAgent(observed({ resumeSessionId: 'r', processIdentity: { pid: 42, startMarker: 'not a time' } } as Partial<DiscoveredTerminalAgent>))
expect(run.deps.registry.register).not.toHaveBeenCalled()
// A holder that started earlier, one whose start is unknown, or this very agent: the session moves.
run.bySession.set('r', agent({ agentId: 'older', processIdentity: { pid: 1, startMarker: '2026-10-04T09:00:00Z' } } as Partial<RegisteredSession>))
await run.binding.bindObservedAgent(observed({ resumeSessionId: 'r' } as Partial<DiscoveredTerminalAgent>))
run.bySession.set('r', agent({ agentId: 'older' }))
await run.binding.bindObservedAgent(observed({ resumeSessionId: 'r' } as Partial<DiscoveredTerminalAgent>))
run.bySession.set('r', agent({ agentId: 'a1' }))
await run.binding.bindObservedAgent(observed({ resumeSessionId: 'r' } as Partial<DiscoveredTerminalAgent>))
expect(run.deps.registry.register).toHaveBeenCalledTimes(3)
})
it('moves a session from the agent that had it, telling everything that held it for that agent', async () => {
const run = setup()
vi.mocked(run.deps.registry.byProcess).mockReturnValue(agent({ sessionId: '' }))
const previous = agent({ agentId: 'old', processIdentity: { pid: 1, startMarker: '2026-10-04T09:00:00Z' } } as Partial<RegisteredSession>)
run.bySession.set('r', previous)
vi.mocked(run.deps.registry.register).mockReturnValue({ entry: agent({ sessionId: 'r' }), ...meta({ isNew: true }) } as never)
await run.binding.bindObservedAgent(observed({ resumeSessionId: 'r' } as Partial<DiscoveredTerminalAgent>))
expect(run.deps.input.forget).toHaveBeenCalledWith('old')
expect(run.deps.deviceInput.forget).toHaveBeenCalledWith('old')
expect(run.deps.announceSession).toHaveBeenCalledWith(previous)
expect(run.deps.attachSession).toHaveBeenCalled()
})
})
describe('a repair', () => {
it('keeps a stopped parent out of an unbound fork\'s fallback discovery', async () => {
const owners = { settle: vi.fn(() => []) }, run = setup({ owners })
const parent = agent({ agentId: 'parent-agent', sessionId: 'parent', active: false })
const fork = agent({ sessionId: '', forkedFrom: { agentId: parent.agentId, name: 'Parent', sessionId: parent.sessionId } })
vi.mocked(run.deps.registry.byProcess).mockReturnValue(fork)
vi.mocked(run.deps.stoppedAgents.get).mockReturnValue(parent)
vi.mocked(findLiveSession).mockImplementation(async (_engine, _cwd, _start, options) =>
options?.excludedSessionId === parent.sessionId ? null : { sessionId: parent.sessionId, transcriptPath: '/parent' })
await run.binding.bindObservedAgent(observed())
expect(run.deps.registry.register).not.toHaveBeenCalled()
expect(run.deps.stoppedAgents.save).not.toHaveBeenCalled()
expect(owners.settle).not.toHaveBeenCalled()
expect(fork.sessionId).toBe('')
})
it.each(['rebound', 'stopped'] as const)('does not publish native Codex evidence after its owner was %s', async change => {
const run = setup(), entry = agent({ engine: 'codex', sessionId: '' }), seen = observed({ engine: 'codex' })
vi.mocked(run.deps.registry.byProcess).mockReturnValue(entry)
let answer!: (value: { sessionId: string; transcriptPath: string }) => void
vi.mocked(findLiveSession).mockReturnValueOnce(new Promise(resolve => { answer = resolve }))
const pending = run.binding.bindObservedAgent(seen)
expect(findLiveSession).toHaveBeenCalledWith('codex', '/work', expect.any(Number), expect.objectContaining({ expectedProcess: seen.processIdentity }))
if (change === 'rebound') entry.sessionId = 'replacement'
else vi.mocked(run.deps.registry.byProcess).mockReturnValue(undefined)
answer({ sessionId: 'native', transcriptPath: '/fixture/rollout.jsonl' }); await pending
expect(run.deps.registry.register).not.toHaveBeenCalled()
expect(run.deps.attachSession).not.toHaveBeenCalled()
})
it('looks for the session a new process opened, sweeping eagerly, then once a minute', async () => {
vi.useFakeTimers()
vi.setSystemTime(Date.parse('2026-10-04T10:00:00Z'))
const run = setup()
vi.mocked(run.deps.registry.byProcess).mockReturnValue(agent({ sessionId: '' }))
for (let sweep = 0; sweep < 30; sweep++) await run.binding.bindObservedAgent(observed())
expect(findLiveSession).toHaveBeenCalledTimes(24)
vi.advanceTimersByTime(60_000)
await run.binding.bindObservedAgent(observed())
expect(findLiveSession).toHaveBeenCalledTimes(25)
expect(findLiveSession).toHaveBeenLastCalledWith('claude', '/work', Date.parse('2026-10-04T10:00:00Z'), { bornOnly: true, pid: 42, codexHome: undefined, hermesHome: undefined, expectedProcess: observed().processIdentity })
})
it('binds what it finds, with the Hermes home it was found in, and starts the count over', async () => {
const run = setup()
vi.mocked(run.deps.registry.byProcess).mockReturnValue(agent({ sessionId: '', codexHome: '/codex', hermesHome: '/hermes' } as Partial<RegisteredSession>))
vi.mocked(findLiveSession).mockResolvedValueOnce({ sessionId: 'found', transcriptPath: '/t/found.jsonl', hermesHome: '/hermes' } as never)
vi.mocked(run.deps.registry.register).mockReturnValue({ entry: agent({ sessionId: 'found' }), ...meta({ isNew: true }) } as never)
await run.binding.bindObservedAgent(observed({ engine: 'hermes' }))
expect(findLiveSession).toHaveBeenCalledWith('hermes', '/work', expect.any(Number), expect.objectContaining({ hermesHome: '/hermes' }))
expect(vi.mocked(run.deps.registry.register).mock.calls[0][0]).toMatchObject({
sessionId: 'found', transcriptPath: '/t/found.jsonl', hermesHome: '/hermes', source: 'process-repair', hookEvent: 'ProcessRepair',
})
vi.mocked(findLiveSession).mockResolvedValueOnce({ sessionId: 'found2', transcriptPath: '/t/found2.jsonl' } as never)
await run.binding.bindObservedAgent(observed())
expect(vi.mocked(run.deps.registry.register).mock.calls[1][0]).not.toHaveProperty('hermesHome')
expect(run.deps.attachSession).toHaveBeenCalledTimes(2)
})
it('finds nothing to bind for an unknown start, nothing found, or a session taken or deleted', async () => {
const run = setup()
vi.mocked(run.deps.registry.byProcess).mockReturnValue(agent({ sessionId: '', agentId: 'repair' }))
await run.binding.bindObservedAgent(observed({ processIdentity: { pid: 42, startMarker: 'unknown' } } as Partial<DiscoveredTerminalAgent>))
expect(findLiveSession).not.toHaveBeenCalled()
await run.binding.bindObservedAgent(observed())
vi.mocked(findLiveSession).mockResolvedValueOnce({ sessionId: 'taken' } as never).mockResolvedValueOnce({ sessionId: 'deleted' } as never)
vi.mocked(run.deps.registry.has).mockImplementation((sessionId: string) => sessionId === 'taken')
vi.mocked(isRecentlyDeleted).mockImplementation((sessionId?: string) => sessionId === 'deleted')
await run.binding.bindObservedAgent(observed())
await run.binding.bindObservedAgent(observed())
// Registered but not new: nothing more to do.
vi.mocked(findLiveSession).mockResolvedValueOnce({ sessionId: 'same' } as never)
vi.mocked(run.deps.registry.register).mockReturnValueOnce({ entry: agent({ sessionId: 'same' }), ...meta() } as never)
await run.binding.bindObservedAgent(observed())
expect(run.deps.registry.register).toHaveBeenCalledTimes(1)
expect(run.deps.attachSession).not.toHaveBeenCalled()
})
})
})
describe('a transcript\'s birth time', () => {
const at = (birthtimeMs: number, ctimeMs: number, mtimeMs: number) => async () => ({ birthtimeMs, ctimeMs, mtimeMs })
it('is its birth time, else its change time, else its write time, and 0 when unreadable or not a time', async () => {
expect(await statBirthMs('/t', at(3, 2, 1))).toBe(3)
expect(await statBirthMs('/t', at(0, 2, 1))).toBe(2)
expect(await statBirthMs('/t', at(0, 0, 1))).toBe(1)
expect(await statBirthMs('/t', at(Number.POSITIVE_INFINITY, 0, 0))).toBe(0)
expect(await statBirthMs('/t', at(0, 0, Number.NaN))).toBe(0)
expect(await statBirthMs('/t', async () => { throw new Error('ENOENT') })).toBe(0)
})
})