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 { afterEach, beforeEach, expect, it, vi } from 'vitest'
import { link, mkdtemp, mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises'
import { join } from 'node:path'
import { tmpdir } from 'node:os'
import { SessionCheckpointStore } from './sessionCheckpoint.js'
import { registry, type RegisteredSession } from './registry.js'
import { sqliteReadAll } from './sqliteRead.js'
import { env } from '../config/env.js'
import { piSessionFolder } from './sessionSearch/externals/pi.js'
const faults = vi.hoisted(() => ({ wrote: undefined as ((path: string) => Promise<void>) | undefined }))
vi.mock('node:fs/promises', async importOriginal => {
const real = await importOriginal<typeof import('node:fs/promises')>()
return { ...real, rm: vi.fn(real.rm), open: async (...args: Parameters<typeof real.open>) => {
const handle = await real.open(...args)
if (String(args[0]).endsWith('.history.tmp')) {
const write = handle.write.bind(handle)
handle.write = (async (...values: Parameters<typeof write>) => {
const result = await write(...values)
const fault = faults.wrote; faults.wrote = undefined
await fault?.(String(args[0]))
return result
}) as typeof handle.write
}
return handle
} }
})
vi.mock('./sqliteRead.js', () => ({ sqliteReadAll: vi.fn() }))
let root: string
let history: string
let directory: string
let row: RegisteredSession
let store: SessionCheckpointStore
const transcript = (body: string) => JSON.stringify({ type: 'session_meta', payload: { id: 'conversation', cwd: '/tmp', source: 'cli' } }) + '\n' + body
beforeEach(async () => {
faults.wrote = undefined
root = await mkdtemp(join(tmpdir(), 'harness-close-checkpoint-'))
const home = join(root, 'profile')
await mkdir(join(home, 'sessions'), { recursive: true, mode: 0o700 })
history = join(home, 'sessions', 'conversation.jsonl')
await writeFile(history, transcript('{"history":"retained conversation"}\n'), { mode: 0o600 })
row = registry.openPendingAgent({ engine: 'codex', cwd: '/tmp', codexHome: home, runtimes: [{ backend: 'tmux', paneId: '%777' }] })!
Object.assign(row, { sessionId: 'conversation', transcriptPath: history })
directory = join(root, 'checkpoints')
store = new SessionCheckpointStore(directory)
})
afterEach(async () => { vi.restoreAllMocks(); for (const s of registry.list()) registry.removeAgent(s.agentId); await rm(root, { recursive: true, force: true }) })
const manifest = async () => JSON.parse(await readFile(join(directory, (await readdir(directory)).find(f => /^[a-f0-9]{64}\.json$/.test(f))!), 'utf8'))
async function piSession() {
const previousHome = env.PI_HOME
env.PI_HOME = join(root, 'pi')
// This fixture owns every possible source; never scan the developer's Pi store.
const cwd = join(root, 'workspace'); await mkdir(cwd)
Object.assign(row, { engine: 'pi', sessionId: 'preallocated-session', transcriptPath: null, cwd })
const folder = join(env.PI_HOME, 'agent', 'sessions', piSessionFolder(row.cwd!))
await mkdir(folder, { recursive: true })
const path = join(folder, `2026-10-04T12-00-00-000Z_${row.sessionId}.jsonl`)
return { path, restore: () => { env.PI_HOME = previousHome }, history: `${JSON.stringify({ type: 'session', version: 3, id: row.sessionId, cwd: row.cwd })}\n` }
}
it('checkpoints a Pi startup failure with an ID but no conversation file', async () => {
const pi = await piSession()
try {
await expect(store.save(row)).rejects.toThrow('Could not save this terminal')
const screen = 'Error: No API key found for the selected model.\nUnsent draft'
await store.save(row, { screen })
const saved = await manifest()
expect(saved.source).toBeNull()
expect(JSON.parse(await readFile(join(directory, saved.file), 'utf8'))).toMatchObject({
engine: 'pi', sessionId: row.sessionId, screen,
})
await store.save(row, { screen: null }) // post-exit checkpoint
expect(await manifest()).toEqual(saved)
} finally { pi.restore() }
})
it.each(['before', 'during'] as const)('backs up a Pi transcript first written %s Close', async when => {
const pi = await piSession()
try {
if (when === 'during') await store.save(row, { screen: 'Waiting for the first reply' })
await writeFile(pi.path, pi.history)
await store.save(row)
const saved = await manifest()
expect(saved.source).toBe(pi.path)
expect(await readFile(join(directory, saved.file), 'utf8')).toBe(pi.history)
expect(row.transcriptPath).toBeNull() // the captured registry row can still be stale
await rm(pi.path)
await expect(store.save(row, { screen: 'Still visible' })).rejects.toThrow('conversation file is unavailable')
expect(await manifest()).toEqual(saved)
} finally { pi.restore() }
})
it('closes a resumed Pi chat that never wrote a conversation file, keeping its screen', async () => {
// Found on a real machine: a Pi chat stopped before its first reply and resumed carries resumeOnly,
// an ID, no transcript path and no file anywhere. Close was refused for good ("conversation file is
// unavailable") though there was no history to lose.
const pi = await piSession()
try {
row.resumeOnly = true
await expect(store.save(row)).rejects.toThrow('Could not save this terminal')
await store.save(row, { screen: 'Waiting for the first reply' })
const saved = await manifest()
expect(saved.source).toBeNull()
expect(JSON.parse(await readFile(join(directory, saved.file), 'utf8'))).toMatchObject({ engine: 'pi', screen: 'Waiting for the first reply' })
} finally { pi.restore() }
})
it('still refuses a resumed Pi chat whose history file is gone once it was backed up', async () => {
const pi = await piSession()
try {
await writeFile(pi.path, pi.history)
await store.save(row)
await rm(pi.path)
row.resumeOnly = true
await expect(store.save(row, { screen: 'Still visible' })).rejects.toThrow('conversation file is unavailable')
} finally { pi.restore() }
})
it.each(['known', 'unreadable', 'ambiguous', 'unreadable store'] as const)('does not replace %s Pi history with only a screen', async state => {
const pi = await piSession()
try {
if (state === 'known') row.transcriptPath = pi.path
if (state === 'unreadable') await writeFile(pi.path, '{partial')
if (state === 'unreadable store') {
const folder = join(pi.path, '..')
await rm(folder, { recursive: true })
await writeFile(folder, 'not a directory')
}
if (state === 'ambiguous') {
await writeFile(pi.path, pi.history)
await writeFile(join(pi.path, '..', `other_${row.sessionId}.jsonl`), pi.history)
}
await expect(store.save(row, { screen: 'Visible terminal' })).rejects.toThrow()
expect((await readdir(directory)).filter(file => file.endsWith('.history'))).toEqual([])
} finally { pi.restore() }
})
it('does not back up a different Pi ID or a project with the same encoded folder', async () => {
const pi = await piSession()
try {
const other = join(root, 'different-project'); await mkdir(other)
await writeFile(pi.path, `${JSON.stringify({ type: 'session', id: row.sessionId, cwd: other })}\n`)
await store.save(row, { screen: 'Startup screen' })
expect((await manifest()).source).toBeNull()
await writeFile(pi.path, `${JSON.stringify({ type: 'session', id: `other_${row.sessionId}`, cwd: row.cwd })}\n`)
await store.save(row, { screen: 'Startup screen' })
expect((await manifest()).source).toBeNull()
} finally { pi.restore() }
})
it.each(['partial', 'ambiguous', 'workspace unavailable'] as const)('holds %s Pi evidence without changing an earlier checkpoint or screen', async state => {
const pi = await piSession()
try {
await store.save(row, { screen: 'The original unsent draft' })
const before = Object.fromEntries(await Promise.all((await readdir(directory)).map(async file => [file, await readFile(join(directory, file), 'utf8')])))
const duplicate = join(pi.path, '..', `other_${row.sessionId}.jsonl`)
if (state === 'partial') await writeFile(pi.path, '{partial')
if (state === 'ambiguous') { await writeFile(pi.path, pi.history); await writeFile(duplicate, pi.history) }
if (state === 'workspace unavailable') await writeFile(pi.path, JSON.stringify({ type: 'session', id: row.sessionId, cwd: join(root, 'missing-workspace') }) + '\n')
await expect(store.save(row, { screen: 'A later unsent draft' })).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
const after = Object.fromEntries(await Promise.all((await readdir(directory)).map(async file => [file, await readFile(join(directory, file), 'utf8')])))
expect(after).toEqual(before)
await rm(duplicate, { force: true }); await writeFile(pi.path, pi.history)
await store.save(row, { screen: 'A later unsent draft' })
expect((await manifest()).source).toBe(pi.path)
} finally { pi.restore() }
})
it('preserves a newly typed draft even when native history has not changed', async () => {
await store.save(row, { screen: 'first draft' })
const first = await manifest()
await store.save(row, { screen: 'new unsent draft' })
expect(await manifest()).toEqual(first)
const screen = (await readdir(directory)).find(f => f.endsWith('.screen.json'))!
expect(JSON.parse(await readFile(join(directory, screen), 'utf8')).screen).toBe('new unsent draft')
expect((await stat(join(directory, screen))).mode & 0o777).toBe(0o600)
await store.save(row)
expect(JSON.parse(await readFile(join(directory, screen), 'utf8')).screen).toBe('new unsent draft')
})
it.each(['terminal', 'claude', 'codex'] as const)('requires a durable screen for unbound %s', async engine => {
row.engine = engine; row.sessionId = ''; row.transcriptPath = null
await expect(store.save(row)).rejects.toThrow('Could not save this terminal')
await store.save(row, { screen: 'unsent work' })
const before = await manifest()
await store.save(row)
expect(await manifest()).toEqual(before)
expect(JSON.parse(await readFile(join(directory, before.file), 'utf8')).screen).toBe('unsent work')
})
it('retains the full native transcript with private permissions, independently of the original', async () => {
await store.save(row)
const saved = await manifest()
const backup = join(directory, saved.file)
expect(saved).toMatchObject({ version: 1, agentId: row.agentId, sessionId: row.sessionId, source: history })
expect(await readFile(backup, 'utf8')).toBe(await readFile(history, 'utf8'))
expect((await stat(backup)).mode & 0o777).toBe(0o600)
expect((await stat(directory)).mode & 0o777).toBe(0o700)
await rm(history)
expect(await readFile(backup, 'utf8')).toContain('retained conversation')
})
it('retains a conversation larger than a copy chunk with exact bytes', async () => {
const contents = transcript('long conversation\n'.repeat(25000))
await writeFile(history, contents)
await store.save(row)
const saved = await manifest()
expect(await readFile(join(directory, saved.file), 'utf8')).toBe(contents)
expect(saved.bytes).toBe(Buffer.byteLength(contents))
})
it('reuses an unchanged checkpoint and replaces it only after a complete new save', async () => {
await store.save(row)
const first = await manifest()
await store.save(row)
expect(await manifest()).toEqual(first)
await writeFile(history, transcript('{"history":"last flushed response"}\n'))
await store.save(row)
const last = await manifest()
expect(last.file).not.toBe(first.file)
expect(await readFile(join(directory, last.file), 'utf8')).toContain('last flushed response')
expect((await readdir(directory)).filter(f => f.endsWith('.history'))).toEqual([last.file])
})
it.each(['missing', 'empty', 'outside profile', 'unbound'])('refuses %s history without destroying an earlier checkpoint', async mode => {
await store.save(row)
const saved = await manifest()
if (mode === 'missing') await rm(history)
if (mode === 'empty') await writeFile(history, '')
if (mode === 'outside profile') row.transcriptPath = join(root, 'unrelated')
if (mode === 'unbound') row.sessionId = ''
await expect(store.save(row)).rejects.toThrow()
expect(await manifest()).toEqual(saved)
expect(await readFile(join(directory, saved.file), 'utf8')).toContain('retained conversation')
})
it('does not hide a corrupt manifest by discarding the last known checkpoint', async () => {
await store.save(row)
const saved = await manifest()
const file = (await readdir(directory)).find(f => f.endsWith('.json'))!
await writeFile(join(directory, file), '{incomplete')
await expect(store.save(row)).rejects.toThrow('Could not back up')
expect(await readFile(join(directory, saved.file), 'utf8')).toContain('retained conversation')
})
it.each(['opencode', 'kilo', 'hermes', 'devin'] as const)('exports %s through read-only SQLite, keeping the shared database intact', async engine => {
row.engine = engine
row.transcriptPath = null
const sql = vi.mocked(sqliteReadAll).mockReset().mockResolvedValue({ ok: true, via: 'builtin', rows: [{ id: 'conversation', message: 'Stored in WAL' }] })
await store.save(row)
const saved = await manifest()
expect(await readFile(join(directory, saved.file), 'utf8')).toContain('Stored in WAL')
// OpenCode first looks for its v2 tables (holding this session, here); every read is a SELECT of this conversation.
const probes = engine === 'opencode' ? sql.mock.calls.splice(0, 2) : []
expect(probes.map(([, query, params]) => [query, params ?? []])).toEqual(engine === 'opencode' ? [
["SELECT name FROM sqlite_master WHERE type='table' AND name='session_v2';", []],
['SELECT id FROM session_v2 WHERE id = ?;', ['conversation']],
] : [])
for (const [, query, params] of sql.mock.calls) {
expect(query).toMatch(/^SELECT \* FROM /)
expect(params).toEqual(['conversation'])
}
})
it('treats a locked or missing database as a save failure, never an empty successful backup', async () => {
row.engine = 'hermes'
vi.mocked(sqliteReadAll).mockResolvedValue({ ok: false, reason: 'transient' })
await expect(store.save(row)).rejects.toThrow('Could not read')
expect(await readdir(directory)).toEqual([])
// OpenCode's look for its v2 tables fails the same way, whether at the table or at this session.
row.engine = 'opencode'
await expect(store.save(row)).rejects.toThrow('Could not read')
vi.mocked(sqliteReadAll).mockReset().mockResolvedValueOnce({ ok: true, via: 'builtin', rows: [{ name: 'session_v2' }] })
.mockResolvedValueOnce({ ok: false, reason: 'transient' })
await expect(store.save(row)).rejects.toThrow('Could not read')
expect(await readdir(directory)).toEqual([])
})
it('rebuilds a missing backup and refuses a missing terminal snapshot', async () => {
await store.save(row)
await rm(join(directory, (await manifest()).file))
await store.save(row)
expect(await readFile(join(directory, (await manifest()).file), 'utf8')).toContain('retained conversation')
row.engine = 'terminal'; row.sessionId = ''
await store.save(row, { screen: 'draft' })
for (const file of await readdir(directory)) if (file.endsWith('.history')) await rm(join(directory, file))
await expect(store.save(row)).rejects.toThrow('Could not save this terminal')
})
it('refuses an unset conversation path instead of inventing an empty checkpoint', async () => {
row.transcriptPath = null
await expect(store.save(row)).rejects.toThrow('conversation file is unavailable')
})
it('rejects a transcript changed during copy and retains the last committed backup', async () => {
await store.save(row)
const previous = await manifest()
await writeFile(history, transcript('new turn\n'))
faults.wrote = async () => {
await writeFile(history, transcript('a response arrived while copying\n'))
}
await expect(store.save(row)).rejects.toThrow('changed while saving')
expect(await manifest()).toEqual(previous)
expect(await readFile(join(directory, previous.file), 'utf8')).toContain('retained conversation')
})
it('rejects a checkpoint that gained an unexpected hard link before commit', async () => {
faults.wrote = async target => {
await link(target, join(root, 'unexpected-link'))
}
await expect(store.save(row)).rejects.toThrow('Could not back up')
expect((await readdir(directory)).some(file => file.endsWith('.json'))).toBe(false)
})
it('keeps a successful new checkpoint when cleanup of the older copy fails', async () => {
await store.save(row)
const before = await manifest()
await writeFile(history, transcript('new conversation state\n'))
vi.mocked(rm).mockRejectedValueOnce(new Error('file busy'))
await store.save(row)
const after = await manifest()
expect(after.file).not.toBe(before.file)
expect(await readFile(join(directory, after.file), 'utf8')).toContain('new conversation state')
})
it('reports the save failure even if cleanup also fails', async () => {
row.transcriptPath = null
vi.mocked(rm).mockRejectedValueOnce(new Error('temporary busy')).mockRejectedValueOnce(new Error('destination busy'))
await expect(store.save(row)).rejects.toThrow('conversation file is unavailable')
})