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
/** Real private transcripts exercise Change agent's identity boundary, including descriptor ABA. */
import * as fs from 'node:fs'
import * as promises from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { dirname, join } from 'node:path'
import { afterEach, beforeEach, expect, it, vi } from 'vitest'
import type { RegisteredSession } from '../lib/registry.js'
const fixtureGit = vi.hoisted(() => ({ enabled: false }))
vi.mock('node:child_process', () => {
const forbidden = () => { throw Error('Host binaries are forbidden in native handoff fixtures') }
const execFile = Object.assign(() => forbidden(), { [Symbol.for('nodejs.util.promisify.custom')]: async (command: string, args: string[]) => {
if (!fixtureGit.enabled || command !== 'git') return forbidden()
const stdout = args.includes('--is-inside-work-tree') ? 'true\n' : args.includes('--git-path') ? '.git/info/exclude\n'
: args.includes('--abbrev-ref') ? 'fixture\n' : args.includes('--short') ? 'a1b2c3\n' : ''
return { stdout, stderr: '' }
} })
return { execFile, execFileSync: forbidden, exec: forbidden, execSync: forbidden,
spawn: forbidden, spawnSync: forbidden, fork: forbidden }
})
const summaryFault = vi.hoisted(() => ({ fail: false }))
vi.mock('../lib/compactSummary.js', async original => {
const actual = await original<typeof import('../lib/compactSummary.js')>()
return { ...actual, readCompactSummary: (...args: Parameters<typeof actual.readCompactSummary>) =>
summaryFault.fail ? Promise.reject(new Error('fixture summary fault')) : actual.readCompactSummary(...args) }
})
vi.mock('node:fs/promises', async original => ({ ...await original<object>() }))
vi.mock('node:fs', async original => ({ ...await original<object>() }))
const ID = 'aaaaaaaa-1111-4111-8111-aaaaaaaaaaaa', OTHER = 'bbbbbbbb-2222-4222-8222-bbbbbbbbbbbb'
const CHANGE = '1'.repeat(32), AT = Date.parse('2026-10-10T08:00:00Z')
let root: string, cwd: string, path: string, catalog: string, row: RegisteredSession
const write = (file: string, text: string) => { fs.mkdirSync(dirname(file), { recursive: true, mode: 0o700 }); fs.writeFileSync(file, text, { mode: 0o600 }) }
const transcript = (id = ID, text = 'Keep the reviewed conversation', source: unknown = 'cli') => [
{ type: 'session_meta', payload: { id, cwd, source } },
{ timestamp: '2026-10-10T07:00:00Z', type: 'event_msg', payload: { type: 'user_message', message: text } },
{ timestamp: '2026-10-10T07:00:01Z', type: 'event_msg', payload: { type: 'agent_message', message: 'Reviewed answer' } },
{ timestamp: '2026-10-10T07:00:02Z', type: 'event_msg', payload: { type: 'task_complete' } },
].map(line => JSON.stringify(line)).join('\n') + '\n'
beforeEach(() => {
fixtureGit.enabled = false
summaryFault.fail = false
root = fs.realpathSync(fs.mkdtempSync(join(tmpdir(), 'native-handoff-authority-'))); cwd = join(root, 'project')
for (const name of ['HOME', 'ADAPTER_DATA_DIR', 'ADAPTER_RUNTIME_DIR', 'CODEX_HOME', 'CLAUDE_CONFIG_DIR',
'PI_HOME', 'XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'XDG_STATE_HOME']) {
vi.stubEnv(name, join(root, name)); fs.mkdirSync(join(root, name), { recursive: true, mode: 0o700 })
}
vi.stubEnv('USERPROFILE', join(root, 'HOME'))
vi.stubEnv('TZ', 'UTC'); fs.mkdirSync(cwd)
catalog = join(root, 'ADAPTER_DATA_DIR', 'engine-homes.json'); write(catalog, '{}')
path = join(root, 'CODEX_HOME', 'sessions', `${ID}.jsonl`); write(path, transcript())
row = { agentId: 'selected', sessionId: ID, engine: 'codex', cwd, transcriptPath: path,
registeredAt: AT, boundAt: AT, codexHome: null, hermesHome: null, processIdentity: null,
runtimes: [{ backend: 'tmux', paneId: '%1' }] } as RegisteredSession
vi.resetModules()
})
afterEach(() => { vi.restoreAllMocks(); vi.unstubAllEnvs(); vi.resetModules(); fs.rmSync(root, { recursive: true, force: true }) })
async function setup(rows = [row], found = true) {
const { prepareAgentHandoff } = await import('../lib/agentHandoff.js')
const { createHandoffDependencies } = await import('./handoffDependencies.js')
const { validTranscriptPath } = await import('../lib/registry.js')
const current = new Map(rows.map(entry => [entry.agentId, entry]))
const saved = new Map<string, RegisteredSession>()
// Real registry/store methods use their receiver. Composition must preserve it.
class Registry {
constructor(readonly rows: Map<string, RegisteredSession>) {}
resolve(id: string) { return structuredClone(this.rows.get(id)) }
byAgent(id: string) { return this.rows.get(id) }
bySession(id: string) { return [...this.rows.values()].find(row => row.sessionId === id) }
}
class Stopped {
constructor(readonly rows: Map<string, RegisteredSession>) {}
get(id: string) { return this.rows.get(id) ?? null }
ids() { return [...this.rows.keys()] }
}
const deps = createHandoffDependencies({
registry: new Registry(current), stopped: new Stopped(saved),
mirror: { recentAsks: () => ['A mirror must not bypass unknown native identity'], lastFullText: () => undefined, recent: () => [] },
databaseHistory: () => undefined, findLiveSession: async () => found ? ({ sessionId: ID, transcriptPath: path }) : null,
processSession: async () => null, isRecentlyDeleted: () => false, findResumedTranscript: async () => path, validTranscriptPath,
}, join(root, 'ADAPTER_DATA_DIR'))
return { current, saved, deps, prepare: () => prepareAgentHandoff(deps, { agentId: row.agentId, targetEngine: 'claude', changeId: CHANGE }) }
}
const noPublication = () => expect(fs.existsSync(join(cwd, '.harness', 'handoff'))).toBe(false)
it.each(['claude', 'codex'] as const)('hands off recent context from a 2 GiB %s transcript within a bounded read', async engine => {
if (engine === 'claude') {
path = join(root, 'CLAUDE_CONFIG_DIR', 'projects', 'fixture', `${ID}.jsonl`)
vi.stubEnv('CLAUDE_PROJECTS_DIR', dirname(dirname(path)))
row = { ...row, engine, transcriptPath: path }
}
const records = engine === 'codex' ? transcript() : [
{ type: 'user', sessionId: ID, cwd, isCompactSummary: true, message: { role: 'user', content: 'Earlier design decisions survive compaction.' } },
{ type: 'user', sessionId: ID, cwd, timestamp: '2026-10-10T07:00:00Z', message: { role: 'user', content: 'Keep the reviewed conversation' } },
{ type: 'assistant', sessionId: ID, cwd, timestamp: '2026-10-10T07:00:01Z', message: {
role: 'assistant', content: [{ type: 'text', text: 'Reviewed answer' }], stop_reason: 'end_turn' } },
].map(line => JSON.stringify(line)).join('\n') + '\n'
write(path, records)
// A sparse output record models the reported 2 GB Claude log without allocating its contents.
const fd = fs.openSync(path, 'r+')
try {
fs.ftruncateSync(fd, 2 * 1024 ** 3)
fs.writeSync(fd, '\n' + records, 2 * 1024 ** 3)
} finally { fs.closeSync(fd) }
const open = promises.open
let bytesRead = 0
vi.spyOn(promises, 'open').mockImplementation(async (...args) => {
const handle = await open(...args)
if (String(args[0]) === path) {
const read = handle.read.bind(handle)
handle.read = (async (...args: Parameters<typeof read>) => {
const result = await read(...args)
bytesRead += result.bytesRead
return result
}) as typeof handle.read
}
return handle
})
const ctx = await setup(), started = performance.now()
const result = await ctx.prepare()
console.log(`[handoff-budget] ${engine}: ${Math.round(performance.now() - started)} ms, ${bytesRead} body bytes`)
// Turns use at most 16 MiB; Claude's separate, bounded compaction-summary lookup uses at most 8 MiB.
expect(bytesRead).toBeLessThanOrEqual((engine === 'claude' ? 24 : 16) * 1024 * 1024)
expect(result.degraded).toContain('transcript')
const markdown = fs.readFileSync(join(cwd, result.file!), 'utf8')
const history = fs.readFileSync(join(cwd, result.file!.replace(/\.md$/, '.transcript.md')), 'utf8')
for (const document of [markdown, history]) {
expect(document).toContain('Keep the reviewed conversation')
expect(document).toContain('Reviewed answer')
expect(document).toContain('Older history was omitted')
}
expect(markdown).not.toContain('The whole conversation')
if (engine === 'claude') expect(markdown).toContain('Earlier design decisions survive compaction.')
}, 15_000)
it.each(['own', 'fork'])('does not mistake an omitted %s conversation for empty history', async mode => {
const fd = fs.openSync(path, 'r+')
try {
fs.ftruncateSync(fd, 32 * 1024 * 1024)
fs.writeSync(fd, '\n', 32 * 1024 * 1024)
if (mode === 'fork') fs.writeSync(fd, transcript().replaceAll('07:00:', '09:00:'), 32 * 1024 * 1024 + 1)
} finally { fs.closeSync(fd) }
const parent = { ...row }
if (mode === 'fork') row = { ...row, agentId: 'fork', sessionId: '', transcriptPath: null,
forkedFrom: { agentId: parent.agentId, name: 'Parent', sessionId: ID, transcriptPath: path } }
const ctx = await setup(mode === 'fork' ? [row, parent] : [row])
await expect(ctx.prepare()).rejects.toMatchObject({ code: 'HANDOFF_UNAVAILABLE' })
noPublication()
})
it.each(['wrong header', 'incomplete header', 'delegated header', 'unavailable catalog'])('holds an own handoff with %s, without a mirror fallback', async fault => {
const ctx = await setup()
if (fault === 'wrong header') write(path, transcript(OTHER))
if (fault === 'incomplete header') write(path, '{"type":"session_meta","payload":')
if (fault === 'delegated header') write(path, transcript(ID, 'Delegated work', { subagent: { thread_spawn: { parent_thread_id: OTHER } } }))
if (fault === 'unavailable catalog') write(catalog, '{')
await expect(ctx.prepare()).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
noPublication()
})
it('reads only the exact opened descriptor when a pathname moves away and back around open', async () => {
const ctx = await setup(), open = promises.open
let swapped = false
vi.spyOn(promises, 'open').mockImplementation(async (...args) => {
if (String(args[0]) !== path || swapped) return open(...args)
swapped = true
fs.renameSync(path, path + '.original'); write(path, transcript(OTHER, 'Unreviewed private conversation'))
try { return await open(...args) }
finally { fs.renameSync(path, path + '.foreign'); fs.renameSync(path + '.original', path) }
})
await expect(ctx.prepare()).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
expect(swapped).toBe(true); noPublication()
expect(fs.readFileSync(path, 'utf8')).toBe(transcript())
})
it.each(['same-inode header', 'same-header body', 'catalog', 'binding', 'runtime'])('holds before publishing when %s changes after its asynchronous read', async fault => {
const ctx = await setup()
ctx.deps.lastFullText = async () => {
await Promise.resolve()
if (fault === 'same-inode header') write(path, transcript(OTHER))
if (fault === 'same-header body') write(path, transcript(ID, 'Replaced conversation body'))
if (fault === 'catalog') write(catalog, '{')
if (fault === 'binding') ctx.current.set(row.agentId, { ...row, boundAt: AT + 1 })
if (fault === 'runtime') ctx.current.set(row.agentId, { ...row, runtimes: [{ backend: 'tmux', paneId: '%2' }] })
return undefined
}
await expect(ctx.prepare()).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
noPublication()
})
it('keeps an existing handoff unchanged while its native identity is unavailable and recovers on the same request', async () => {
const ctx = await setup(), original = transcript()
const result = await ctx.prepare()
expect(result.file).toBeTypeOf('string')
const file = join(cwd, result.file!), before = fs.readFileSync(file, 'utf8')
write(path, transcript(OTHER))
await expect(ctx.prepare()).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
expect(fs.readFileSync(file, 'utf8')).toBe(before)
write(path, original)
expect(await ctx.prepare()).toMatchObject({ file: result.file })
expect(fs.readFileSync(file, 'utf8')).toBe(before)
})
it('rejects a body rewrite during the final native header fence before any reservation', async () => {
const ctx = await setup(), bindings = await import('../engines/transcriptBindings.js')
const evidence = bindings.controlTranscriptEvidence
let armed = false, fired = false
ctx.deps.lastFullText = () => { armed = true; return undefined }
vi.spyOn(bindings, 'controlTranscriptEvidence').mockImplementation((...args) => {
const proof = evidence(...args)
return { ...proof, verify: key => {
proof.verify(key)
if (armed && !fired) { fired = true; write(path, transcript(ID, 'Rewritten during the final fence')) }
} }
})
await expect(ctx.prepare()).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
expect(fired).toBe(true); noPublication()
expect(fs.existsSync(join(root, 'ADAPTER_DATA_DIR', 'handoff-receipts'))).toBe(false)
})
it.each(['reservation', 'transcript link'])('recovers a durably reserved native snapshot after %s interruption and append', async fault => {
const ctx = await setup(), link = fs.linkSync
let fired = false
vi.spyOn(fs, 'linkSync').mockImplementation((from, to) => {
link(from, to)
if (!fired && (fault === 'reservation' ? String(to).includes('handoff-receipts') && String(to).endsWith('.json') : String(to).endsWith('.transcript.md'))) {
fired = true; throw Object.assign(Error('interrupted after the owned link'), { code: 'EIO' })
}
})
await expect(ctx.prepare()).rejects.toMatchObject({ code: 'HANDOFF_UNAVAILABLE' })
expect(fired).toBe(true)
fs.appendFileSync(path, JSON.stringify({ timestamp: '2026-10-10T07:00:05Z', type: 'event_msg', payload: { type: 'user_message', message: 'Appended after the snapshot' } }) + '\n')
const fresh = await setup(), result = await fresh.prepare()
expect(result.file).toBeTypeOf('string')
const text = fs.readFileSync(join(cwd, result.file!), 'utf8')
expect(text).toContain('Keep the reviewed conversation'); expect(text).not.toContain('Appended after the snapshot')
expect(await processPrepare(fresh)).toMatchObject({ file: result.file })
})
it.each(['full then empty', 'empty then full'])('keeps the first durable result for the same intent: %s', async direction => {
const empty = transcript().split('\n')[0] + '\n'
if (direction === 'empty then full') write(path, empty)
const ctx = await setup(), first = await ctx.prepare()
write(path, direction === 'full then empty' ? empty : transcript())
const fresh = await setup()
expect(await processPrepare(fresh)).toMatchObject({ file: first.file, gitRepo: first.gitRepo })
if (first.file) expect(fs.readFileSync(join(cwd, first.file), 'utf8')).toContain('Keep the reviewed conversation')
else noPublication()
const { prepareAgentHandoff } = await import('../lib/agentHandoff.js')
write(path, empty)
await expect(prepareAgentHandoff(fresh.deps, { agentId: row.agentId, changeId: CHANGE, targetEngine: 'codex' }))
.rejects.toMatchObject({ code: 'CHANGE_CONFLICT' })
})
it.each(['full then empty', 'empty then full'])('recovers an interrupted Git snapshot with %s native history', async direction => {
fixtureGit.enabled = true
const exclude = join(cwd, '.git', 'info', 'exclude'), empty = transcript().split('\n')[0] + '\n'
write(exclude, '# Existing project exclusion\n')
if (direction === 'empty then full') write(path, empty)
const ctx = await setup(), link = fs.linkSync
let fired = false
vi.spyOn(fs, 'linkSync').mockImplementation((from, to) => {
link(from, to)
if (!fired && String(to).includes('handoff-receipts') && String(to).endsWith('.json')) {
fired = true; throw Error('Interrupted after durable reservation')
}
})
await expect(ctx.prepare()).rejects.toMatchObject({ code: 'HANDOFF_UNAVAILABLE' })
expect(fired).toBe(true); noPublication()
write(path, direction === 'full then empty' ? empty : transcript())
fs.appendFileSync(exclude, '# Added while the request was held\n')
const result = await processPrepare(await setup())
expect(result).toMatchObject({ gitRepo: true })
if (direction === 'full then empty') {
expect(result.file).toBeTypeOf('string')
expect(fs.readFileSync(join(cwd, result.file as string), 'utf8')).toContain('Keep the reviewed conversation')
expect(fs.readFileSync(exclude, 'utf8')).toContain('.harness/handoff/')
} else { expect(result.file).toBeNull(); noPublication() }
expect(fs.readFileSync(exclude, 'utf8')).toContain('# Added while the request was held\n')
})
it('does not accept another valid ancestor file with the same session ID', async () => {
const parent = { ...row, agentId: 'parent' }
row = { ...row, sessionId: '', transcriptPath: null, forkedFrom: { agentId: parent.agentId, name: 'Parent', sessionId: ID, transcriptPath: path } }
const ctx = await setup([row, parent])
const result = await processPrepare(ctx, async prepared => {
const { readNativeHandoff } = await import('../lib/nativeHandoffRead.js')
const second = join(dirname(path), 'other', `${ID}.jsonl`)
write(second, transcript(ID, 'Different native body under the same ID'))
prepared.reads[0] = (await readNativeHandoff({ engine: 'codex', sessionId: ID, transcriptPath: second }, parent.agentId, undefined, cwd, {})).witness
})
expect(result).toMatchObject({ error: 'IDENTITY_UNAVAILABLE', held: true }); noPublication()
})
it('does not inherit a fork link whose exact file now names another native conversation', async () => {
const parent = { ...row, agentId: 'parent' }
row = { ...row, sessionId: '', transcriptPath: null,
forkedFrom: { agentId: parent.agentId, name: 'Parent', sessionId: ID, transcriptPath: path } }
const ctx = await setup([row, parent])
write(path, transcript(OTHER))
await expect(ctx.prepare()).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
noPublication()
})
it.each(['recorded', 'parent path', 'legacy', 'stopped', 'by ID'])('publishes exactly the selected %s ancestor through the core', async kind => {
const parent = { ...row, agentId: 'parent' }
row = { ...row, sessionId: '', transcriptPath: null, forkedFrom: { agentId: parent.agentId, name: 'Parent',
...(kind === 'legacy' ? {} : { sessionId: ID, transcriptPath: kind === 'parent path' ? join(root, 'unrelated.jsonl') : path }) } }
const ctx = await setup([row, parent])
if (kind === 'stopped') { ctx.current.delete(parent.agentId); ctx.saved.set(parent.agentId, parent) }
if (kind === 'by ID') {
const next = join(dirname(path), 'moved', `${ID}.jsonl`)
fs.mkdirSync(dirname(next)); fs.renameSync(path, next); path = next
ctx.current.set(parent.agentId, { ...parent, sessionId: OTHER, transcriptPath: null })
}
const result = await processPrepare(ctx)
expect(result.file).toBeTypeOf('string')
expect(fs.readFileSync(join(cwd, result.file as string), 'utf8')).toContain('Keep the reviewed conversation')
})
it.each(['missing link', 'wrong parent', 'other project', 'invalid cutoff', 'late legacy binding'])
('rejects %s ancestry even when the service supplies matching current row fingerprints', async fault => {
const parent = { ...row, agentId: 'parent' }
row = { ...row, sessionId: '', transcriptPath: null,
forkedFrom: { agentId: parent.agentId, name: 'Parent', sessionId: ID, transcriptPath: path } }
const ctx = await setup([row, parent])
const result = await processPrepare(ctx, async prepared => {
const child = ctx.current.get(row.agentId)!, ancestor = ctx.current.get(parent.agentId)!
if (fault === 'missing link') child.forkedFrom = undefined
if (fault === 'wrong parent') child.forkedFrom = { agentId: 'unselected', name: 'Another parent' }
if (fault === 'other project') { ancestor.cwd = join(root, 'other-project'); fs.mkdirSync(ancestor.cwd) }
if (fault === 'invalid cutoff') child.registeredAt = NaN
if (fault === 'late legacy binding') {
child.forkedFrom = { agentId: parent.agentId, name: 'Parent' }; ancestor.boundAt = AT + 1
}
const { handoffSessionFact } = await import('../lib/handoffAuthority.js')
prepared.sessions = [handoffSessionFact(child), handoffSessionFact(ancestor)]
})
expect(result).toMatchObject({ error: 'IDENTITY_UNAVAILABLE', held: true }); noPublication()
})
it('refuses a by-ID file without the current core selection witness', async () => {
const parent = { ...row, agentId: 'parent' }
row = { ...row, sessionId: '', transcriptPath: null,
forkedFrom: { agentId: parent.agentId, name: 'Parent', sessionId: ID, transcriptPath: path } }
const ctx = await setup([row, parent]), next = join(dirname(path), 'moved', `${ID}.jsonl`)
fs.mkdirSync(dirname(next)); fs.renameSync(path, next); path = next
ctx.current.set(parent.agentId, { ...parent, sessionId: OTHER, transcriptPath: null })
const { createHandoffPublisher } = await import('./handoffPublication.js')
// This core instance did not observe the lookup supplied by the earlier service preparation.
ctx.deps.publish = createHandoffPublisher({ directory: join(root, 'ADAPTER_DATA_DIR'),
resolve: id => ctx.current.get(id), ownedByOther: () => false, isRecentlyDeleted: () => false })
expect(await processPrepare(ctx)).toMatchObject({ error: 'IDENTITY_UNAVAILABLE', held: true }); noPublication()
})
it.each(['engine', 'path'])('refuses a discovery read whose %s differs from the core observation', async fault => {
row = { ...row, sessionId: '', transcriptPath: null,
processIdentity: { pid: 4242, executable: 'codex', startMarker: '2026-10-10T07:00:00Z' } }
const ctx = await setup()
const result = await processPrepare(ctx, prepared => {
if (fault === 'engine') prepared.reads[0].engine = 'claude'
else prepared.reads[0].path = join(root, 'other-transcript')
})
expect(result).toMatchObject({ error: 'IDENTITY_UNAVAILABLE', held: true }); noPublication()
})
it.each([true, false])('requires a real core discovery observation, including confirmed empty (found: %s)', async found => {
row = { ...row, sessionId: '', transcriptPath: null,
processIdentity: { pid: 4242, executable: 'codex', startMarker: '2026-10-10T07:00:00Z' } }
const ctx = await setup([row], found), result = await processPrepare(ctx)
if (found) expect(result.file).toBeTypeOf('string')
else { expect(result).toMatchObject({ file: null, degraded: [] }); noPublication() }
})
it('checks unrelated stopped ownership through the store receiver', async () => {
const ctx = await setup()
ctx.saved.set('other', { ...row, agentId: 'other', sessionId: OTHER })
expect((await ctx.prepare()).file).toBeTypeOf('string')
})
it('uses a bound fork own history without consulting an absent parent', async () => {
row.forkedFrom = { agentId: 'absent', name: 'Parent' }
const ctx = await setup()
expect((await ctx.prepare()).file).toBeTypeOf('string')
})
it('walks a complete intermediate fork chain with no bound session', async () => {
const parent = { ...row, agentId: 'parent' }, middle = { ...row, agentId: 'middle', sessionId: '', transcriptPath: null,
forkedFrom: { agentId: parent.agentId, name: 'Parent', sessionId: ID, transcriptPath: path } }
row = { ...row, sessionId: '', transcriptPath: null, forkedFrom: { agentId: middle.agentId, name: 'Middle' } }
expect((await processPrepare(await setup([row, middle, parent]))).file).toBeTypeOf('string')
})
it('holds discovery whose process owner changes while the lookup is pending', async () => {
row = { ...row, sessionId: '', transcriptPath: null,
processIdentity: { pid: 4242, executable: 'codex', startMarker: '2026-10-10T07:00:00Z' } }
const ctx = await setup(), discover = ctx.deps.discoverSession!
ctx.deps.discoverSession = async source => {
const found = await discover(source)
ctx.current.set(row.agentId, { ...row, processIdentity: { ...row.processIdentity!, pid: 4243 } })
return found
}
await expect(ctx.prepare()).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
noPublication()
})
/** Real service frames are serialized in both directions; the core builds the request witness. */
async function processPrepare(ctx: Awaited<ReturnType<typeof setup>>,
beforePublish?: (prepared: import('../lib/handoffAuthority.js').PreparedHandoff, revoke: (why: 'closed' | 'expired' | 'replaced') => void) => void | Promise<void>) {
const { conversationReads, answerConversationQuery } = await import('./conversationQueries.js')
const { createServiceLinks } = await import('./serviceLinks.js')
const { fakeCore } = await import('../testing/fakeCore.js')
const { handoffCoreApi } = await import('../services/handoffProcess.js')
const { startHandoff } = await import('../services/handoff.js')
const clone = <T>(value: T): T => JSON.parse(JSON.stringify(value))
const core = fakeCore({ dataDir: join(root, 'ADAPTER_DATA_DIR'), conversations: conversationReads(ctx.deps) })
const replies = new Map<string, (payload: Record<string, unknown>) => void>()
let clock = 0, next = 0
const owner = { local: true, owner: true, connection: 'private-fixture-owner' }
const links = createServiceLinks({ token: 'fixture-token', owned: { handoff: ['agent_handoff_prepare'] }, log: () => {}, now: () => clock,
answer: async (_service, query, payload, authority) => {
const wire = clone(payload)
if (query === 'publish') await beforePublish?.(wire.prepared as never, why => {
if (why === 'closed') links.closeConnection(owner.connection)
if (why === 'expired') clock = 6_000
if (why === 'replaced') links.accept('handoff', 'fixture-token', { sendFrame: () => true }, () => {})
})
return answerConversationQuery(core, query, wire, authority)
} })
const processCore = handoffCoreApi(core.dataDir, (query, payload) => new Promise(resolve => {
const requestId = `query-${++next}`; replies.set(requestId, resolve)
link.receive(clone({ type: 'service_query', payload: { ...payload, query, requestId } }))
}))
const service = startHandoff(processCore)
const link = links.accept('handoff', 'fixture-token', { sendFrame: frame => {
const wire = clone(frame)
if (wire.type === 'service_query_result') replies.get(String(wire.payload!.requestId))!(wire.payload!)
else if (wire.type === 'agent_handoff_prepare') void Promise.resolve(service.agent_handoff_prepare!(wire.payload!, owner))
.then(reply => link.receive(clone({ type: 'agent_handoff_prepare_result', payload: { ...reply, requestId: wire.payload!.requestId } })))
return true
} }, () => {})!
try { return await new Promise<Record<string, unknown>>(resolve => links.route('agent_handoff_prepare',
{ agentId: row.agentId, changeId: CHANGE, targetEngine: 'claude' }, owner, resolve)) }
finally {
link.closed()
for (const reply of replies.values()) reply({ error: 'SERVICE_UNAVAILABLE' })
await new Promise(resolve => setImmediate(resolve))
}
}
it.each(['project', 'conversation', 'profile', 'engine', 'omitted read', 'foreign owner', 'target engine', 'unknown read field',
'extra foreign read', 'duplicate read', 'native path', 'native key', 'native version', 'missing native route', 'missing fork chain'])('the core refuses a JSON preparation with altered %s authority', async fault => {
if (fault === 'missing fork chain') row = { ...row, sessionId: '', transcriptPath: null, forkedFrom: { agentId: 'parent', name: 'Parent' } }
const ctx = await setup(), other = join(root, 'other-project'); fs.mkdirSync(other)
if (fault === 'missing fork chain') {
// Capture a valid own preparation, then supply an unbound fork fact with no ancestral witness.
const { handoffSessionFact } = await import('../lib/handoffAuthority.js')
const { prepareAgentHandoff } = await import('../lib/agentHandoff.js')
ctx.current.set(row.agentId, { ...row, sessionId: ID, transcriptPath: path, forkedFrom: undefined })
const publish = ctx.deps.publish!
ctx.deps.publish = (prepared, permit) => {
ctx.current.set(row.agentId, row)
prepared.sessions = [handoffSessionFact(row)]; prepared.reads = []; prepared.documents = null; prepared.result.file = null
return publish(prepared, permit)
}
await expect(prepareAgentHandoff(ctx.deps, { agentId: row.agentId, changeId: CHANGE, targetEngine: 'claude' })).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
noPublication(); return
}
const result = await processPrepare(ctx, async prepared => {
if (fault === 'project') {
const { NativeFiles } = await import('../engines/kit/nativeFiles.js')
const { nativeFileKey } = await import('../engines/kit/nativePaths.js')
const { handoffGitRoute } = await import('../lib/handoffGit.js')
const files = new NativeFiles(), destination = files.locate(other)!
prepared.project = { cwd: other, path: other, fileKey: nativeFileKey(destination.info), route: files.paths.snapshot() }
prepared.result.cwd = other; prepared.git = handoffGitRoute(other)
}
if (fault === 'conversation') {
const { readNativeHandoff } = await import('../lib/nativeHandoffRead.js')
const foreign = join(root, 'CODEX_HOME', 'sessions', `${OTHER}.jsonl`)
write(foreign, transcript(OTHER, 'Another valid native conversation'))
prepared.reads[0] = (await readNativeHandoff({ engine: 'codex', sessionId: OTHER, transcriptPath: foreign }, row.agentId, undefined, cwd, {})).witness
}
if (fault === 'profile') prepared.reads[0].profile = join(root, 'other-profile')
if (fault === 'engine') prepared.reads[0].engine = 'claude'
if (fault === 'omitted read') prepared.reads = []
if (fault === 'foreign owner') prepared.reads[0].ownerAgentId = 'unrecorded-owner'
if (fault === 'target engine') prepared.request.targetEngine = 'codex'
if (fault === 'unknown read field') Object.assign(prepared.reads[0], { extra: 'x'.repeat(1024 * 1024) })
if (fault === 'extra foreign read') prepared.reads.push({ ...prepared.reads[0], ownerAgentId: 'foreign' })
if (fault === 'duplicate read') prepared.reads.push({ ...prepared.reads[0] })
if (fault === 'native path') prepared.reads[0].readPath = other
if (fault === 'native key') prepared.reads[0].fileKey = '1:2'
if (fault === 'native version') prepared.reads[0].version = 'changed'
if (fault === 'missing native route') prepared.reads[0].route = prepared.reads[0].route.slice(1)
})
expect(result).toMatchObject({ held: true, retryable: true })
expect(result.file).toBeUndefined(); noPublication(); expect(fs.existsSync(join(other, '.harness'))).toBe(false)
})
it.each(['closed', 'expired', 'replaced'] as const)('holds a %s originating request before the JSON publish query can commit', async why => {
const ctx = await setup()
const result = await processPrepare(ctx, (_prepared, revoke) => revoke(why))
expect(result.error).toBeTypeOf('string'); expect(result.file).toBeUndefined(); noPublication()
expect(await processPrepare(ctx)).toMatchObject({ file: expect.any(String) })
})
it('keeps the complete intermediate fork chain authoritative after the history read', async () => {
const parent = { ...row, agentId: 'parent' }, intermediate = { ...row, agentId: 'intermediate', sessionId: '', transcriptPath: null,
forkedFrom: { agentId: parent.agentId, name: 'Parent', sessionId: ID, transcriptPath: path } }
row = { ...row, sessionId: '', transcriptPath: null, forkedFrom: { agentId: intermediate.agentId, name: 'Intermediate' } }
const ctx = await setup([row, intermediate, parent])
const result = await processPrepare(ctx, () => { ctx.current.get(intermediate.agentId)!.forkedFrom = { agentId: 'other-parent', name: 'Other' } })
expect(result).toMatchObject({ error: 'IDENTITY_UNAVAILABLE', held: true }); noPublication()
})
// Claude Code writes what it remembered of a compacted conversation as a flagged record; the handoff reads the
// latest one from the descriptor it verified (lib/compactSummary.ts). Codex's compaction is encrypted: none.
it('reads the latest compaction summary from a verified Claude transcript, and none from Codex', async () => {
vi.stubEnv('CLAUDE_PROJECTS_DIR', join(root, 'CLAUDE_CONFIG_DIR', 'projects'))
const claude = join(root, 'CLAUDE_CONFIG_DIR', 'projects', 'project', `${ID}.jsonl`)
write(claude, [
{ type: 'user', sessionId: ID, cwd, isSidechain: false, timestamp: '2026-10-10T07:00:00Z', message: { role: 'user', content: 'start' } },
{ type: 'user', sessionId: ID, cwd, isCompactSummary: true, timestamp: '2026-10-10T07:10:00Z', message: { role: 'user', content: 'old summary' } },
{ type: 'user', sessionId: ID, cwd, isCompactSummary: true, timestamp: '2026-10-10T07:20:00Z', message: { role: 'user', content: [{ type: 'text', text: 'We chose Postgres.' }] } },
{ type: 'user', sessionId: ID, cwd, timestamp: '2026-10-10T07:21:00Z', message: { role: 'user', content: 'next?' } },
].map(line => JSON.stringify(line)).join('\n') + '\n')
const { readNativeHandoff } = await import('../lib/nativeHandoffRead.js')
const read = await readNativeHandoff({ engine: 'claude', sessionId: ID, transcriptPath: claude }, 'selected', undefined, cwd, {})
expect(read.summary).toEqual({ text: 'We chose Postgres.', failed: false })
expect((await readNativeHandoff({ engine: 'codex', sessionId: ID, transcriptPath: path }, 'selected', undefined, cwd, {})).summary)
.toEqual({ text: null, failed: false })
})
// Core validates what it publishes. A summary that could not be read is optional context left out of the record:
// it must be published as degraded, never refused (a refusal held the switch the summary was only meant to help).
it('publishes through core with a summary that could not be read', async () => {
vi.stubEnv('CLAUDE_PROJECTS_DIR', join(root, 'CLAUDE_CONFIG_DIR', 'projects'))
const claude = join(root, 'CLAUDE_CONFIG_DIR', 'projects', 'project', `${ID}.jsonl`)
write(claude, [
{ type: 'user', sessionId: ID, cwd, isSidechain: false, timestamp: '2026-10-10T07:00:00Z', message: { role: 'user', content: 'pick a database' } },
{ type: 'assistant', sessionId: ID, cwd, timestamp: '2026-10-10T07:00:05Z', message: { role: 'assistant', content: [{ type: 'text', text: 'Postgres' }] } },
].map(line => JSON.stringify(line)).join('\n') + '\n')
row = { ...row, engine: 'claude', transcriptPath: claude } as RegisteredSession
summaryFault.fail = true
const { prepare } = await setup([row])
const result = await prepare()
expect(result.degraded).toContain('summary')
expect(result.file).toMatch(/^\.harness\/handoff\/selected-/)
})