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
// Cross-unit seams of the A2/A3 fork handoff, with the real modules on each side rather than fakes:
// - the fork record as cli.ts builds it at `agent_fork` → registry.openPendingAgent (normalizer) → the stopped
// copy (StoppedAgentStore save/get, through strictPersistedRow) → lib/agentHandoff.ts inheritance;
// - lib/agentHandoff.ts's transcript gate and lookup wired to the real registry.validTranscriptPath and
// sessionRepair.findResumedTranscript, as cli.ts wires them (`backend.handoffRequestProvider`);
// - lib/handoffDiscovery.ts (through cli.ts's `handoffProviderDeps`) over the real sessionRepair searches: Claude only
// by its per-process record, never a folder scan; ownership checked against the real stopped store, failing closed.
// The unit specs pin each side with fakes; this one pins that the pieces agree.
import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { basename, join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import type { RegisteredSession } from './lib/registry.js'
const CHANGE = '0123456789abcdef0123456789abcdef'
const OTHER_CHANGE = 'fedcba9876543210fedcba9876543210'
const PARENT_SESSION = '11111111-2222-4333-8444-555555555555'
const FOUND_SESSION = '99999999-8888-4777-8666-555555555555'
let root: string
let ws: string
let projects: string
let data: string
const saved: Record<string, string | undefined> = {}
beforeEach(() => {
root = realpathSync(mkdtempSync(join(tmpdir(), 'handoff-fork-int-')))
ws = join(root, 'ws')
projects = join(root, 'claude', 'projects')
data = join(root, 'data')
for (const dir of [ws, projects, data, join(root, 'codex')]) mkdirSync(dir, { recursive: true })
for (const key of ['ADAPTER_DATA_DIR', 'CLAUDE_PROJECTS_DIR', 'CODEX_HOME']) saved[key] = process.env[key]
process.env.ADAPTER_DATA_DIR = data
process.env.CLAUDE_PROJECTS_DIR = projects
process.env.CODEX_HOME = join(root, 'codex')
vi.resetModules()
})
afterEach(() => {
for (const [key, value] of Object.entries(saved)) {
if (value === undefined) delete process.env[key]
else process.env[key] = value
}
rmSync(root, { recursive: true, force: true })
})
async function modules() {
const registryModule = await import('./lib/registry.js')
const repair = await import('./lib/sessionRepair.js')
const discovery = await import('./lib/handoffDiscovery.js')
const publication = await import('./core/handoffDependencies.js')
const handoff = await import('./lib/agentHandoff.js')
const stopped = await import('./lib/stoppedAgents.js')
const stores = await import('./engines/sessionStores.js')
registryModule.registry.load()
return { ...registryModule, ...repair, ...discovery, ...publication, ...handoff, ...stopped, processSession: stores.processSessionOf }
}
type Mods = Awaited<ReturnType<typeof modules>>
const iso = (ms: number): string => new Date(ms).toISOString()
/** A Claude main transcript: each [ask, answer, at] becomes a user record and an assistant record. */
function claudeFile(path: string, turns: Array<[string, string, number]>, extra: Record<string, unknown> = {}): string {
mkdirSync(join(path, '..'), { recursive: true })
const lines: string[] = []
turns.forEach(([ask, answer, at], i) => {
lines.push(JSON.stringify({ sessionId: basename(path, '.jsonl'), type: 'user', uuid: `u${i}`, isSidechain: false, cwd: ws, timestamp: iso(at), ...extra, message: { role: 'user', content: ask } }))
lines.push(JSON.stringify({ sessionId: basename(path, '.jsonl'), type: 'assistant', uuid: `a${i}`, isSidechain: false, cwd: ws, timestamp: iso(at + 1_000), ...extra, message: { role: 'assistant', content: [{ type: 'text', text: answer }], stop_reason: 'end_turn' } }))
})
writeFileSync(path, lines.join('\n') + '\n')
return path
}
/** The `forkedFrom` expression of cli.ts's `agent_fork` handler, applied to `source`. */
function forkOriginAsCliBuildsIt(source: RegisteredSession, sourceName: string) {
return {
agentId: source.agentId, name: sourceName,
...(source.sessionId ? { sessionId: source.sessionId, ...(source.transcriptPath ? { transcriptPath: source.transcriptPath } : {}) } : {}),
}
}
/**
* The provider deps through cli.ts's own factory (`handoffProviderDeps`), with the real registry, stopped store,
* transcript lookup, gate and session searches; only the mirror is faked, loudly, so any use of it shows.
*/
function cliDeps(m: Mods, rows: RegisteredSession[], over: { findLiveSession?: Mods['findLiveSession']; processSession?: Mods['processSession'] } = {}) {
const stoppedDir = join(data, 'stopped-agents')
const store = new m.StoppedAgentStore(stoppedDir)
return m.createHandoffDependencies({
registry: {
resolve: (id) => rows.find((s) => s.agentId === id) ?? null,
byAgent: (id) => rows.find((s) => s.agentId === id),
bySession: (sid) => rows.find((s) => s.sessionId === sid),
},
stopped: {
get: (id) => store.get(id),
ids: () => {
try { return readdirSync(stoppedDir).filter((name) => name.endsWith('.json')).map((name) => name.slice(0, -5)) }
catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []; throw error }
},
},
mirror: {
recentAsks: () => ['MIRROR-ASK'],
lastFullText: () => 'MIRROR-ANSWER',
recent: () => [{ kind: 'summary', recap: 'MIRROR-RECAP', text: 'MIRROR-RECAP' }],
} as unknown as Parameters<Mods['handoffProviderDeps']>[0]['mirror'],
databaseHistory: () => undefined,
findLiveSession: over.findLiveSession ?? m.findLiveSession,
processSession: over.processSession ?? m.processSession,
isRecentlyDeleted: () => false,
findResumedTranscript: m.findResumedTranscript,
validTranscriptPath: m.validTranscriptPath,
}, data)
}
const handoffMd = (agentId: string, change = CHANGE): string => readFileSync(join(ws, '.harness', 'handoff', `${agentId}-${change}.md`), 'utf8')
describe('fork record → registry → stopped copy → inheritance (real modules)', () => {
/** A bound Claude parent with one ask before the fork and one far after it, and its fork as the daemon opens it. */
async function forkOfParent(m: Mods, parentFilePath = join(projects, '-ws', `${PARENT_SESSION}.jsonl`)) {
const t0 = Date.now()
const parentFile = claudeFile(parentFilePath, [['PRE-FORK ask: add a retry', 'Retry added.', t0 - 120_000], ['POST-FORK ask', 'Later work.', t0 + 600_000]])
const parent = {
agentId: 'parent-1', sessionId: PARENT_SESSION, engine: 'claude', cwd: ws, transcriptPath: parentFile,
// Rebound after the fork: only a RECORDED session may still be inherited.
registeredAt: t0 - 3_600_000, boundAt: t0 + 60_000, projectDir: 'ws',
} as unknown as RegisteredSession
const fork = m.registry.openPendingAgent({
engine: 'claude', runtimes: [{ backend: 'tmux', paneId: '%7' }], cwd: ws,
forkedFrom: forkOriginAsCliBuildsIt(parent, 'harness Devops'),
})!
return { parent, parentFile, fork }
}
it.each(['live', 'restarted', 'stopped'] as const)('the %s fork inherits exactly the recorded session up to the fork', async (label) => {
const m = await modules()
const { parent, parentFile, fork } = await forkOfParent(m)
expect(fork.forkedFrom).toEqual({ agentId: 'parent-1', name: 'harness Devops', sessionId: PARENT_SESSION, transcriptPath: parentFile })
// A daemon restart: a fresh registry module loads the row from disk (the 03-verify-r1 major: load() lost forkedFrom).
vi.resetModules()
const reloaded = await import('./lib/registry.js')
reloaded.registry.load()
const restartedFork = reloaded.registry.byAgent(fork.agentId)!
expect(restartedFork.forkedFrom).toEqual(fork.forkedFrom)
// The stopped copy, as Change agent on a stopped fork resolves it (cli.ts: registry.resolve ?? stoppedAgents.get).
const store = new m.StoppedAgentStore(join(data, 'stopped-agents'))
store.save({ ...fork, active: false })
const stoppedFork = new m.StoppedAgentStore(join(data, 'stopped-agents')).get(fork.agentId)!
expect(stoppedFork.forkedFrom).toEqual(fork.forkedFrom)
{
const row = { live: fork, restarted: restartedFork, stopped: stoppedFork }[label]
const changeId = { live: CHANGE, restarted: OTHER_CHANGE, stopped: 'a'.repeat(32) }[label]
const findLiveSession = vi.fn(m.findLiveSession)
const claudeProcessSession = vi.fn(m.processSession)
const result = await m.prepareAgentHandoff(cliDeps(m, [parent, row], { findLiveSession, processSession: claudeProcessSession }), { agentId: row.agentId, changeId, targetEngine: 'codex' })
expect(result, label).toEqual({ file: `.harness/handoff/${row.agentId}-${changeId}.md`, gitRepo: false, cwd: ws, degraded: ['git'] })
const md = handoffMd(row.agentId, changeId)
expect(md, label).toContain('PRE-FORK ask: add a retry')
expect(md, label).toContain('History: inherited from `harness Devops` (agent `parent-1`)')
expect(md, label).not.toContain('POST-FORK ask')
expect(md, label).not.toMatch(/MIRROR-(ASK|ANSWER|RECAP)/)
expect(md, label).not.toContain(parentFile)
expect(findLiveSession, label).not.toHaveBeenCalled()
expect(claudeProcessSession, label).not.toHaveBeenCalled()
}
})
it('a recorded transcript that moved is found again by session id through the real lookup', async () => {
const m = await modules()
const { parent, parentFile, fork } = await forkOfParent(m)
const movedTo = join(projects, '-ws-moved', `${PARENT_SESSION}.jsonl`)
mkdirSync(join(movedTo, '..'), { recursive: true })
renameSync(parentFile, movedTo)
// The parent now runs another session: its current file must not stand in for the recorded one.
const current = claudeFile(join(projects, '-ws', 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee.jsonl'), [['NEW SESSION ask', 'New.', Date.now() - 1_000]])
const moved = { ...parent, sessionId: 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee', transcriptPath: current } as RegisteredSession
const result = await m.prepareAgentHandoff(cliDeps(m, [moved, fork]), { agentId: fork.agentId, changeId: CHANGE, targetEngine: 'codex' })
expect(result.file).toBe(`.harness/handoff/${fork.agentId}-${CHANGE}.md`)
const md = handoffMd(fork.agentId)
expect(md).toContain('PRE-FORK ask: add a retry')
expect(md).not.toContain('NEW SESSION ask')
expect(md).not.toContain('POST-FORK ask')
})
it('a recorded transcript outside the engine root fails the real gate: nothing is inherited', async () => {
const m = await modules()
// A path the registry normalizer accepts (absolute) but validTranscriptPath does not vouch for.
const { parent, fork } = await forkOfParent(m, join(root, 'elsewhere', `${PARENT_SESSION}.jsonl`))
await expect(m.prepareAgentHandoff(cliDeps(m, [parent, fork]), { agentId: fork.agentId, changeId: CHANGE, targetEngine: 'codex' }))
.rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
expect(existsSync(join(ws, '.harness'))).toBe(false)
})
})
describe('discovery through the real Claude process record (handoffDiscovery ↔ sessionRepair ↔ agentHandoff)', () => {
const PID = 4242
// Second precision, as Claude's procStart and the daemon's start marker carry it.
const startMarker = (): string => new Date(Math.floor((Date.now() - 2_000) / 1000) * 1000).toISOString()
/** An unbound, live, non-fork Claude agent with a process identity, as the registry keeps a pane it launched. */
function unbound(marker: string | null, pid: number | null = PID): RegisteredSession {
return {
agentId: 'agent-new', sessionId: '', engine: 'claude', cwd: ws, transcriptPath: null,
registeredAt: Date.parse(marker ?? new Date().toISOString()), boundAt: null, projectDir: 'ws',
...(marker || pid ? { processIdentity: { pid, executable: '/usr/bin/claude', startMarker: marker } } : {}),
} as unknown as RegisteredSession
}
/** Claude's per-process record (`<projects>/../sessions/<pid>.json`). */
function processRecord(sessionId: string, procStart: string, cwd = ws): void {
mkdirSync(join(projects, '..', 'sessions'), { recursive: true })
writeFileSync(join(projects, '..', 'sessions', `${PID}.json`), JSON.stringify({ pid: PID, procStart, cwd, sessionId }))
}
const ownFile = (at: number): string => claudeFile(join(projects, '-ws', `${FOUND_SESSION}.jsonl`), [['OWN ask: fix the login bug', 'Fixed.', at]])
const ask = (m: Mods, deps: ReturnType<typeof cliDeps>, change = CHANGE) =>
m.prepareAgentHandoff(deps, { agentId: 'agent-new', changeId: change, targetEngine: 'codex' })
it('hands over the session the process record names, read through the real lookup and gate', async () => {
const m = await modules()
const marker = startMarker()
const own = ownFile(Date.parse(marker) + 500)
processRecord(FOUND_SESSION, marker)
const findLiveSession = vi.fn(m.findLiveSession)
const result = await ask(m, cliDeps(m, [unbound(marker)], { findLiveSession }))
expect(result).toEqual({ file: `.harness/handoff/agent-new-${CHANGE}.md`, gitRepo: false, cwd: ws, degraded: ['git'] })
const md = handoffMd('agent-new')
expect(md).toContain('OWN ask: fix the login bug')
expect(md).toContain(`- Session: \`${FOUND_SESSION}\``)
expect(md).not.toMatch(/MIRROR-(ASK|ANSWER|RECAP)/)
expect(md).not.toContain(own)
expect(findLiveSession).not.toHaveBeenCalled()
})
it('never scans the project folder for Claude: no process record, nothing, even beside a born session', async () => {
const m = await modules()
const marker = startMarker()
ownFile(Date.parse(marker) + 500)
const findLiveSession = vi.fn(m.findLiveSession)
const claudeProcessSession = vi.fn(m.processSession)
const result = await ask(m, cliDeps(m, [unbound(marker)], { findLiveSession, processSession: claudeProcessSession }))
expect(claudeProcessSession).toHaveBeenCalledTimes(1)
expect(findLiveSession).not.toHaveBeenCalled()
expect(result).toEqual({ file: null, gitRepo: false, cwd: ws, degraded: [] })
expect(existsSync(join(ws, '.harness'))).toBe(false)
})
it('looks nowhere without both a start marker and a pid', async () => {
const m = await modules()
const marker = startMarker()
ownFile(Date.parse(marker) + 500)
processRecord(FOUND_SESSION, marker)
for (const [label, row] of [['no marker', unbound(null)], ['no pid', unbound(marker, null)], ['no identity', unbound(null, null)]] as const) {
const findLiveSession = vi.fn(m.findLiveSession)
const claudeProcessSession = vi.fn(m.processSession)
await expect(ask(m, cliDeps(m, [row], { findLiveSession, processSession: claudeProcessSession })), label).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
expect(claudeProcessSession, label).not.toHaveBeenCalled()
expect(findLiveSession, label).not.toHaveBeenCalled()
}
})
it('ignores a conclusively older process record and holds a current record naming another folder', async () => {
const m = await modules()
const marker = startMarker()
ownFile(Date.parse(marker) + 500)
processRecord(FOUND_SESSION, new Date(Date.parse(marker) - 60_000).toISOString())
await expect(ask(m, cliDeps(m, [unbound(marker)]))).resolves.toEqual({ file: null, gitRepo: false, cwd: ws, degraded: [] })
processRecord(FOUND_SESSION, marker, root)
await expect(ask(m, cliDeps(m, [unbound(marker)]), OTHER_CHANGE)).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
expect(existsSync(join(ws, '.harness'))).toBe(false)
})
it('never hands over a session a stopped agent holds, read from the real stopped store', async () => {
const m = await modules()
const marker = startMarker()
ownFile(Date.parse(marker) + 500)
processRecord(FOUND_SESSION, marker)
const holder = m.registry.openPendingAgent({ engine: 'claude', runtimes: [{ backend: 'tmux', paneId: '%9' }], cwd: ws })!
new m.StoppedAgentStore(join(data, 'stopped-agents')).save({ ...holder, sessionId: FOUND_SESSION, active: false })
await expect(ask(m, cliDeps(m, [unbound(marker)]))).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
})
it('fails closed on one unreadable stopped record, whoever it belonged to', async () => {
const m = await modules()
const marker = startMarker()
ownFile(Date.parse(marker) + 500)
processRecord(FOUND_SESSION, marker)
const other = m.registry.openPendingAgent({ engine: 'claude', runtimes: [{ backend: 'tmux', paneId: '%10' }], cwd: ws })!
const store = new m.StoppedAgentStore(join(data, 'stopped-agents'))
store.save({ ...other, sessionId: 'unrelated-session', active: false })
// Readable and not the holder: discovery goes ahead.
expect((await ask(m, cliDeps(m, [unbound(marker)]))).file).toBe(`.harness/handoff/agent-new-${CHANGE}.md`)
// One more record that cannot be read (the store's list() would skip it silently): nothing is handed over.
rmSync(join(ws, '.harness'), { recursive: true, force: true })
writeFileSync(join(data, 'stopped-agents', 'broken-1.json'), '{not json', { mode: 0o600 })
await expect(ask(m, cliDeps(m, [unbound(marker)]), OTHER_CHANGE)).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
})
it('a fork in the same folder never searches, even with a matching process record', async () => {
const m = await modules()
const marker = startMarker()
ownFile(Date.parse(marker) + 500)
processRecord(FOUND_SESSION, marker)
const fork = { ...unbound(marker), forkedFrom: { agentId: 'gone-parent', name: 'Gone' } } as RegisteredSession
const findLiveSession = vi.fn(m.findLiveSession)
const claudeProcessSession = vi.fn(m.processSession)
await expect(ask(m, cliDeps(m, [fork], { findLiveSession, processSession: claudeProcessSession }))).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
expect(findLiveSession).not.toHaveBeenCalled()
expect(claudeProcessSession).not.toHaveBeenCalled()
})
})