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 { beforeEach, expect, it, vi } from 'vitest'
import { captureResumeIdentity } from './captureResumeIdentity.js'
import { engineKeepsTranscriptFile, type RegisteredSession } from './registry.js'
import { controlTranscriptEvidence, savedTranscriptEvidence } from '../engines/transcriptBindings.js'
import { findLiveSession, findResumedTranscript, processSessionEvidence } from './sessionRepair.js'
import { processRows, resumeSessionId } from './processTable.js'
import { IdentityReadUnavailable, ObservedConversationUnavailable } from '../engines/kit/identityScan.js'
vi.mock('./registry.js', () => ({ engineKeepsTranscriptFile: vi.fn(() => true) }))
vi.mock('../engines/transcriptBindings.js', () => ({ savedTranscriptEvidence: vi.fn(), controlTranscriptEvidence: vi.fn() }))
vi.mock('./sessionRepair.js', () => ({ processSessionEvidence: vi.fn(), findLiveSession: vi.fn(), findResumedTranscript: vi.fn() }))
vi.mock('./processTable.js', () => ({ processRows: vi.fn(), resumeSessionId: vi.fn() }))
vi.mock('./processEvidence.js', async () => {
const { nativeConversationFixture } = await import('../testing/nativeConversationEvidence.js')
const { processRows } = await import('./processTable.js')
return { readProcessEvidence: (...args: Parameters<typeof import('./processEvidence.js')['readProcessEvidence']>) =>
nativeConversationFixture(async () => [], processRows).processes(...args) }
})
let row: RegisteredSession
beforeEach(() => {
vi.resetAllMocks()
row = { engine: 'claude', sessionId: '', cwd: '/work', codexHome: null,
processIdentity: { pid: 77, executable: '/bin/claude', startMarker: 'Mon Sep 21 01:00:00 2026' } } as RegisteredSession
vi.mocked(processRows).mockResolvedValue([{ ...row.processIdentity!, args: 'claude', parentPid: 1 }])
vi.mocked(savedTranscriptEvidence).mockImplementation((_engine, _id, path) => ({ path, fileKey: 'fixture', verify: vi.fn() }))
vi.mocked(controlTranscriptEvidence).mockImplementation((_engine, _id, path) => ({ path, verify: vi.fn() }))
vi.mocked(engineKeepsTranscriptFile).mockReturnValue(true)
vi.mocked(resumeSessionId).mockReturnValue(null)
vi.mocked(processSessionEvidence).mockResolvedValue({ session: null, verify: vi.fn() })
vi.mocked(findLiveSession).mockResolvedValue(null)
vi.mocked(findResumedTranscript).mockResolvedValue(null)
})
it('leaves a shell and a complete binding unchanged', async () => {
row.engine = 'terminal'; expect(await captureResumeIdentity(row)).toBe(row)
row.engine = 'codex'; row.sessionId = 'known'; row.transcriptPath = '/history'
expect(await captureResumeIdentity(row)).toBe(row); expect(processRows).not.toHaveBeenCalled()
})
it('on Windows stops a session no hook has named yet, with nothing to read its process by', async () => {
expect(row.sessionId).toBeFalsy()
expect(await captureResumeIdentity(row, 'win32')).toBe(row)
expect(processSessionEvidence).not.toHaveBeenCalled()
expect(findLiveSession).not.toHaveBeenCalled()
// One a hook named keeps its conversation there as anywhere.
Object.assign(row, { sessionId: 'named', transcriptPath: '/history' })
expect(await captureResumeIdentity(row, 'win32')).toBe(row)
})
it('uses a completely proven parent transcript without changing the saved conversation', async () => {
Object.assign(row, { sessionId: 'parent', transcriptPath: '/child' })
vi.mocked(savedTranscriptEvidence).mockReturnValue({ path: '/parent', fileKey: 'parent-file', verify: vi.fn() })
expect(await captureResumeIdentity(row)).toMatchObject({ sessionId: 'parent', transcriptPath: '/parent' })
expect(row.transcriptPath).toBe('/child')
expect(findResumedTranscript).not.toHaveBeenCalled()
})
it('takes a database-backed engine on its recorded id, with no transcript to check', async () => {
// opencode/kilo/hermes/devin keep the conversation in SQLite: there is no file, and demanding one
// is what used to leave their resume with nothing to reopen.
vi.mocked(engineKeepsTranscriptFile).mockReturnValue(false)
Object.assign(row, { engine: 'opencode', sessionId: 'known' })
expect(await captureResumeIdentity(row)).toBe(row)
expect(findResumedTranscript).not.toHaveBeenCalled()
})
it('captures a database-backed engine id read off the live process', async () => {
vi.mocked(engineKeepsTranscriptFile).mockReturnValue(false)
row.engine = 'opencode'
vi.mocked(findLiveSession).mockResolvedValue({ sessionId: 'live' })
expect(await captureResumeIdentity(row)).toMatchObject({ sessionId: 'live', source: 'stop-repair' })
})
it('captures and preserves the exact Hermes home before stopping its process', async () => {
vi.mocked(engineKeepsTranscriptFile).mockReturnValue(false)
Object.assign(row, { engine: 'hermes', hermesHome: '/known-home' })
vi.mocked(findLiveSession).mockResolvedValue({ sessionId: 'live', hermesHome: '/known-home' })
expect(await captureResumeIdentity(row)).toMatchObject({ sessionId: 'live', hermesHome: '/known-home', source: 'stop-repair' })
expect(findLiveSession).toHaveBeenCalledWith('hermes', '/work', expect.any(Number), expect.objectContaining({ hermesHome: '/known-home' }))
})
it.each([null, '/stale'])('repairs a known id with missing or invalid path %s', async transcriptPath => {
Object.assign(row, { sessionId: 'known', transcriptPath, codexHome: '/profile' })
vi.mocked(savedTranscriptEvidence).mockImplementation((_engine, _id, path) => ({ path: path === '/found' ? path : null, fileKey: 'fixture', verify: vi.fn() }))
vi.mocked(findResumedTranscript).mockResolvedValue('/found')
expect(await captureResumeIdentity(row)).toMatchObject({ sessionId: 'known', transcriptPath: '/found' })
expect(findResumedTranscript).toHaveBeenCalledWith('claude', 'known', { codexHome: '/profile' })
})
it.each([null, '/unsafe'])('holds the known id when its file is unavailable: %s', async path => {
row.sessionId = 'known'; vi.mocked(findResumedTranscript).mockResolvedValue(path)
vi.mocked(savedTranscriptEvidence).mockReturnValue({ path: null, fileKey: null, verify: vi.fn() })
await expect(captureResumeIdentity(row)).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
expect(row.sessionId).toBe('known')
})
it('looks up a preallocated Pi session ID in its own project before stopping', async () => {
Object.assign(row, { engine: 'pi', sessionId: 'preallocated', transcriptPath: null })
expect(await captureResumeIdentity(row)).toBe(row)
expect(findResumedTranscript).toHaveBeenCalledWith('pi', 'preallocated', { codexHome: undefined, cwd: '/work' })
vi.mocked(findResumedTranscript).mockResolvedValue('/first-reply.jsonl')
expect(await captureResumeIdentity(row)).toMatchObject({ sessionId: 'preallocated', transcriptPath: '/first-reply.jsonl' })
})
// Pi keeps its sessions by project folder, and a row restored from an older record can have lost its
// folder. The lookup is asked with no folder rather than a null one, and its refusal ("the Pi conversation
// location is unavailable", sessionRepair) reaches the caller: Stop is then refused (stopAgentService),
// rather than killing an engine whose conversation could never be found again.
it('passes on the lookup\'s refusal for a Pi session whose project folder was not recorded', async () => {
Object.assign(row, { engine: 'pi', sessionId: 'preallocated', transcriptPath: null, cwd: null })
vi.mocked(findResumedTranscript).mockRejectedValue(new Error('The Pi conversation location is unavailable.'))
await expect(captureResumeIdentity(row)).rejects.toThrow('The Pi conversation location is unavailable.')
expect(findResumedTranscript).toHaveBeenCalledWith('pi', 'preallocated', { codexHome: undefined, cwd: undefined })
})
it.each(['identity', 'cwd', 'unknown', 'gone', 'pid', 'executable', 'start'])('refuses missing or changed process evidence: %s', async mode => {
if (mode === 'identity') row.processIdentity = null
if (mode === 'cwd') row.cwd = null
if (mode === 'unknown') vi.mocked(processRows).mockResolvedValue(null)
if (mode === 'gone') vi.mocked(processRows).mockResolvedValue([])
if (mode === 'pid') row.processIdentity!.pid++
if (mode === 'executable') row.processIdentity!.executable = 'other'
if (mode === 'start') row.processIdentity!.startMarker = 'later'
if (['unknown', 'executable', 'start'].includes(mode)) await expect(captureResumeIdentity(row)).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
else expect(await captureResumeIdentity(row)).toBe(row)
expect(findLiveSession).not.toHaveBeenCalled()
})
it.each(['claude', 'codex'] as const)('captures an explicit %s resume without guessing by directory', async engine => {
row.engine = engine; vi.mocked(resumeSessionId).mockReturnValue('exact')
vi.mocked(findResumedTranscript).mockResolvedValue('/exact')
expect(await captureResumeIdentity(row)).toMatchObject({ sessionId: 'exact', transcriptPath: '/exact', source: 'stop-repair' })
expect(findLiveSession).not.toHaveBeenCalled()
})
it('holds an explicit file-backed resume whose announced conversation is unavailable', async () => {
vi.mocked(resumeSessionId).mockReturnValue('exact')
vi.mocked(findResumedTranscript).mockResolvedValue(null)
await expect(captureResumeIdentity(row)).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
expect(findLiveSession).not.toHaveBeenCalled()
})
it('prefers current Claude native metadata to old resume argv', async () => {
vi.mocked(resumeSessionId).mockReturnValue('old')
vi.mocked(processSessionEvidence).mockResolvedValue({ session: { sessionId: 'current', transcriptPath: '/current' }, verify: vi.fn() })
expect(await captureResumeIdentity(row)).toMatchObject({ sessionId: 'current' }); expect(findResumedTranscript).not.toHaveBeenCalled()
expect(processSessionEvidence).toHaveBeenCalledWith('claude', 77, '/work', Date.parse(row.processIdentity!.startMarker), expect.anything())
})
it('captures a unique fresh session before its first hook arrives', async () => {
vi.mocked(findLiveSession).mockResolvedValue({ sessionId: 'new', transcriptPath: '/new' })
expect(await captureResumeIdentity(row)).toMatchObject({ sessionId: 'new', transcriptPath: '/new' })
expect(row.sessionId).toBe('')
expect(findLiveSession).toHaveBeenCalledWith('claude', '/work', Date.parse(row.processIdentity!.startMarker), expect.objectContaining({ pid: 77, bornOnly: true, codexHome: undefined, expectedProcess: row.processIdentity }))
})
it.each(['claude', 'codex'] as const)('does not give an unbound %s fork its parent from the recent-file pool', async engine => {
Object.assign(row, { engine, forkedFrom: { agentId: 'parent-agent', name: 'Parent', sessionId: 'parent', transcriptPath: '/parent' } })
// A parent created in the same process-clock interval is a unique "born" candidate,
// even though its newer turns and conversation still belong to the parent.
vi.mocked(findLiveSession).mockImplementation(async (_engine, _cwd, _start, options) =>
options?.excludedSessionId === 'parent' ? null : { sessionId: 'parent', transcriptPath: '/parent' })
expect(await captureResumeIdentity(row)).toBe(row)
expect(savedTranscriptEvidence).not.toHaveBeenCalled()
expect(findLiveSession).toHaveBeenCalledWith(engine, '/work', expect.any(Number), expect.objectContaining({ excludedSessionId: 'parent' }))
})
it.each(['native record', 'explicit resume', 'new conversation'] as const)('preserves an unbound fork\'s %s evidence', async mode => {
row.forkedFrom = { agentId: 'parent-agent', name: 'Parent', sessionId: 'parent', transcriptPath: '/parent' }
if (mode === 'native record') vi.mocked(processSessionEvidence).mockResolvedValue({ session: { sessionId: 'parent', transcriptPath: '/parent' }, verify: vi.fn() })
if (mode === 'explicit resume') {
vi.mocked(resumeSessionId).mockReturnValue('parent')
vi.mocked(findResumedTranscript).mockResolvedValue('/parent')
}
if (mode === 'new conversation') vi.mocked(findLiveSession).mockResolvedValue({ sessionId: 'child', transcriptPath: '/child' })
expect(await captureResumeIdentity(row)).toMatchObject({ sessionId: mode === 'new conversation' ? 'child' : 'parent', source: 'stop-repair' })
})
it.each([null, { sessionId: 'missing' }, { sessionId: 'unsafe', transcriptPath: '/unsafe' }])('does not bind ambiguous or unsafe history: %s', async found => {
vi.mocked(findLiveSession).mockResolvedValue(found)
vi.mocked(savedTranscriptEvidence).mockReturnValue({ path: null, fileKey: null, verify: vi.fn() })
if (found) await expect(captureResumeIdentity(row)).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
else expect(await captureResumeIdentity(row)).toBe(row)
})
// A close of a harness still starting may stop one whose conversation was never seen (stopAgentService
// `withoutConversation`); a conversation seen and then unreadable is held as seen.
it.each([
['a resume on its command line', () => { vi.mocked(resumeSessionId).mockReturnValue('exact'); vi.mocked(findResumedTranscript).mockResolvedValue(null) }],
['its native record', () => {
vi.mocked(processSessionEvidence).mockResolvedValue({ session: { sessionId: 'current', transcriptPath: '/current' }, verify: vi.fn() })
vi.mocked(savedTranscriptEvidence).mockReturnValue({ path: null, fileKey: null, verify: vi.fn() })
}],
['one found live', () => {
vi.mocked(findLiveSession).mockResolvedValue({ sessionId: 'new', transcriptPath: '/new' })
vi.mocked(savedTranscriptEvidence).mockImplementation(() => { throw new IdentityReadUnavailable('the transcript header is incomplete') })
}],
] as const)('holds a conversation seen through %s and then unreadable as seen', async (_, arrange) => {
arrange()
await expect(captureResumeIdentity(row)).rejects.toBeInstanceOf(ObservedConversationUnavailable)
})
it('a conversation never seen, because its process could not be read, is not held as seen', async () => {
vi.mocked(findLiveSession).mockRejectedValue(new IdentityReadUnavailable('the native control descriptor type is unavailable'))
const error = await captureResumeIdentity(row).catch(e => e)
expect(error).toBeInstanceOf(IdentityReadUnavailable)
expect(error).not.toBeInstanceOf(ObservedConversationUnavailable)
const plain = new Error('disk gone')
vi.mocked(findLiveSession).mockRejectedValue(plain)
await expect(captureResumeIdentity(row)).rejects.toBe(plain)
vi.mocked(resumeSessionId).mockReturnValue('exact')
vi.mocked(findResumedTranscript).mockRejectedValue(plain)
await expect(captureResumeIdentity(row)).rejects.toBe(plain)
const seen = new ObservedConversationUnavailable('Conversation identity is held: seen.')
vi.mocked(findResumedTranscript).mockRejectedValue(seen)
await expect(captureResumeIdentity(row)).rejects.toBe(seen)
})