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 * as fs from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { createHomeAdopter, homeIsAbsolute, homeIsNetworkOrDevice, inspectJournalEntry, networkHomeSentence, readAdoptedHomes } from './homeAdoption.js'
import { NATIVE_EVIDENCE_MS } from './nativeEvidence.js'
const clock = vi.hoisted(() => ({ now: 0, remaining: Infinity }))
const platform = vi.hoisted(() => ({ windows: false }))
vi.mock('node:perf_hooks', async original => ({ ...await original<object>(), performance: { now: () => --clock.remaining < 0 ? 3_001 : clock.now } })) // past NATIVE_EVIDENCE_MS
vi.mock('./windowsFiles.js', async original => {
const actual = await original<typeof import('./windowsFiles.js')>()
return { ...actual,
hostPlatform: () => platform.windows ? 'win32' : actual.hostPlatform(),
journalFlushFlags: () => actual.journalFlushFlags(platform.windows ? 'win32' : undefined),
}
})
vi.mock('node:fs', async original => {
const actual = await original<typeof fs>()
return { ...actual, openSync: vi.fn(actual.openSync), closeSync: vi.fn(actual.closeSync),
fsyncSync: vi.fn(actual.fsyncSync), linkSync: vi.fn(actual.linkSync),
readSync: vi.fn(actual.readSync), writeFileSync: vi.fn(actual.writeFileSync), opendirSync: vi.fn(actual.opendirSync), lstatSync: vi.fn(actual.lstatSync) }
})
let actual: typeof fs, root = '', file = ''
let adopter: ReturnType<typeof createHomeAdopter>
const empty = () => ({ claude: [], codex: [] as string[] })
const add = (...codex: string[]) => ({ claude: [], codex })
const record = (index: number) => join(file + '.adoptions', `${String(index).padStart(3, '0')}.json`)
const seal = (index: number) => index ? join(file + '.confirmations', `${String(index).padStart(3, '0')}.committed`) : file + '.adopted'
const unavailable = () => Object.assign(new Error('fixture storage unavailable'), { code: 'EIO' })
const files = new Map<number, string>()
beforeEach(async () => {
clock.now = 0; clock.remaining = Infinity; platform.windows = false
actual = await vi.importActual<typeof fs>('node:fs')
for (const name of ['openSync', 'closeSync', 'fsyncSync', 'linkSync', 'readSync', 'writeFileSync', 'opendirSync', 'lstatSync'] as const) {
vi.mocked(fs[name]).mockReset().mockImplementation(actual[name] as never)
}
files.clear()
vi.mocked(fs.openSync).mockImplementation((...args) => {
const fd = actual.openSync(...args); files.set(fd, String(args[0])); return fd
})
vi.mocked(fs.closeSync).mockImplementation(fd => { actual.closeSync(fd); files.delete(fd) })
root = actual.realpathSync(actual.mkdtempSync(join(tmpdir(), 'durable-home-adoption-')))
file = join(root, 'data', 'engine-homes.json')
adopter = createHomeAdopter(file)
})
afterEach(() => { vi.restoreAllMocks(); actual.rmSync(root, { recursive: true, force: true }) })
describe('durable monotone home adoption', () => {
it('does not reopen a Windows journal record for a flush after its staged bytes were synced', () => {
platform.windows = true
expect(adopter.adopt(add('C:\\saved'))).toEqual(add('C:\\saved'))
const writableRecordOpens = vi.mocked(fs.openSync).mock.calls.filter(([path, flags]) =>
String(path) === record(0) && typeof flags === 'number' && (flags & 3) === fs.constants.O_RDWR)
expect(writableRecordOpens).toHaveLength(0)
})
it('leaves a new installation alone for an empty request', () => {
expect(adopter.adopt(empty())).toEqual(empty())
expect(actual.existsSync(file + '.adoptions')).toBe(false)
})
it('preserves the imported file and reads committed homes independently of module memory', () => {
actual.mkdirSync(join(root, 'data'), { mode: 0o700 })
const original = '{"codex":["/previous"]}\n'
actual.writeFileSync(file, original, { mode: 0o600 })
expect(() => adopter.adopt(add('/new'))).not.toThrow()
expect(adopter.adopt(add('/new'))).toEqual(add('/previous', '/new'))
expect(actual.readFileSync(file, 'utf8')).toBe(original)
expect(readAdoptedHomes(file).homes).toEqual(add('/previous', '/new'))
const first = actual.readFileSync(record(0), 'utf8')
expect(adopter.adopt(add('/new'))).toEqual(add('/previous', '/new'))
expect(actual.readFileSync(record(0), 'utf8')).toBe(first)
expect(actual.existsSync(record(1))).toBe(false)
actual.writeFileSync(file, '{"claude":["/external"]}', { mode: 0o600 })
expect(adopter.adopt(add('/later'))).toEqual({ claude: ['/external'], codex: ['/previous', '/new', '/later'] })
expect(readAdoptedHomes(file).homes).toEqual({ claude: ['/external'], codex: ['/previous', '/new', '/later'] })
})
it.each(['same', 'different', 'last-slot'] as const)('rebases an exclusive-publication loser without losing a winner: %s', mode => {
const prior = mode === 'last-slot' ? Array.from({ length: 62 }, (_, n) => `/saved-${n}`) : ['/saved']
adopter.adopt(add(...prior))
let raced = false
vi.mocked(fs.linkSync).mockImplementation((from, to) => {
if (String(to) === record(1) && !raced) {
raced = true
createHomeAdopter(file).adopt(add(mode === 'same' ? '/requested' : '/peer'))
}
return actual.linkSync(from, to)
})
if (mode === 'last-slot') expect(() => adopter.adopt(add('/requested'))).toThrow('known session-home limit')
else expect(adopter.adopt(add('/requested')).codex).toEqual([...prior, ...(mode === 'same' ? [] : ['/peer']), '/requested'])
const found = readAdoptedHomes(file).homes.codex
expect(found).toEqual([...prior, ...(mode === 'same' ? ['/requested'] : ['/peer']), ...(mode === 'different' ? ['/requested'] : [])])
expect(actual.existsSync(record(mode === 'different' ? 3 : 2))).toBe(false)
expect(raced).toBe(true)
})
it.each(['write', 'stage-flush', 'record-link', 'journal-flush', 'confirmation-link', 'confirmation-flush'] as const)
('does not acknowledge a failed %s, and an idempotent retry confirms it', phase => {
adopter.adopt(add('/saved'))
let published = false, confirmed = false, failed = false
const fail = () => { failed = true; throw unavailable() }
vi.mocked(fs.writeFileSync).mockImplementation((...args) => {
if (!failed && phase === 'write') fail()
return actual.writeFileSync(...args)
})
vi.mocked(fs.linkSync).mockImplementation((from, to) => {
if (String(to) === record(1)) {
if (!failed && phase === 'record-link') fail()
published = true
}
if (String(to) === seal(1)) {
if (!failed && phase === 'confirmation-link') fail()
confirmed = true
}
return actual.linkSync(from, to)
})
vi.mocked(fs.fsyncSync).mockImplementation(fd => {
const path = files.get(fd)
if (!failed && ((phase === 'stage-flush' && path?.includes('/.staging/'))
|| (phase === 'journal-flush' && published && path === file + '.adoptions')
|| (phase === 'confirmation-flush' && confirmed && path === file + '.confirmations'))) fail()
actual.fsyncSync(fd)
})
expect(() => adopter.adopt(add('/requested'))).toThrow(/durable adoption/)
expect(failed).toBe(true)
if (published && !confirmed) expect(() => readAdoptedHomes(file)).toThrow('unconfirmed adoption')
expect(adopter.adopt(add('/requested'))).toEqual(add('/saved', '/requested'))
expect(readAdoptedHomes(file).homes).toEqual(add('/saved', '/requested'))
expect(files.size).toBe(0)
})
it.each([false, true])('finishes a complete abandoned record after restart, including without another home request (empty=%s)', emptyRequest => {
adopter.adopt(add('/saved'))
vi.mocked(fs.linkSync).mockImplementation((from, to) => {
if (String(to) === seal(1)) throw unavailable()
return actual.linkSync(from, to)
})
expect(() => adopter.adopt(add('/interrupted'))).toThrow()
expect(() => readAdoptedHomes(file)).toThrow('unconfirmed adoption')
vi.mocked(fs.linkSync).mockImplementation(actual.linkSync)
let recovered
expect(() => { recovered = adopter.adopt(emptyRequest ? empty() : add('/later')) }).not.toThrow()
expect(recovered).toEqual(add('/saved', '/interrupted', ...(emptyRequest ? [] : ['/later'])))
})
it.each(['journal', 'confirmations', 'tail', 'legacy'] as const)('holds missing committed %s evidence and recovers when restored', target => {
actual.mkdirSync(join(root, 'data'), { mode: 0o700 })
actual.writeFileSync(file, '{"codex":["/previous"]}', { mode: 0o600 })
adopter.adopt(add('/first')); adopter.adopt(add('/second'))
const lost = target === 'journal' ? file + '.adoptions' : target === 'confirmations' ? file + '.confirmations' : target === 'tail' ? record(1) : file
actual.renameSync(lost, lost + '.owned-backup')
expect(() => readAdoptedHomes(file)).toThrow(/journal|catalog/)
expect(() => adopter.adopt(add('/third'))).toThrow(/journal|catalog/)
actual.renameSync(lost + '.owned-backup', lost)
expect(readAdoptedHomes(file).homes).toEqual(add('/previous', '/first', '/second'))
})
it.each(['record', 'confirmation', 'unknown', 'symlink-staging', 'writable-record', 'oversized'] as const)
('preserves foreign or incomplete %s evidence without repair by replacement', target => {
adopter.adopt(add('/saved'))
if (target === 'record') actual.writeFileSync(record(0), '{ partial')
if (target === 'confirmation') actual.writeFileSync(seal(0), 'foreign\n')
if (target === 'unknown') actual.writeFileSync(join(file + '.adoptions', 'unknown'), 'foreign')
if (target === 'symlink-staging') {
actual.renameSync(join(file + '.adoptions', '.staging'), join(root, 'owned-staging'))
actual.symlinkSync(join(root, 'owned-staging'), join(file + '.adoptions', '.staging'))
}
if (target === 'writable-record') actual.chmodSync(record(0), 0o666)
if (target === 'oversized') actual.writeFileSync(record(0), 'x'.repeat(70_000))
const before = actual.readFileSync(record(0), 'utf8')
expect(() => readAdoptedHomes(file)).toThrow()
expect(() => adopter.adopt(add('/new'))).toThrow()
expect(actual.readFileSync(record(0), 'utf8')).toBe(before)
})
it('rechecks the whole record pool after reading its final entry', () => {
adopter.adopt(add('/saved')); adopter.adopt(add('/later'))
let changed = false
vi.mocked(fs.readSync).mockImplementation((...args) => {
const count = actual.readSync(...args as Parameters<typeof actual.readSync>)
if (!changed && files.get(args[0]) === record(1)) {
changed = true
actual.writeFileSync(record(0), actual.readFileSync(record(0), 'utf8').replace('/saved', '/other'))
}
return count
})
expect(() => readAdoptedHomes(file)).toThrow('changed during its catalog read')
})
it('checks for a concurrent addition after the final proof pass', () => {
adopter.adopt(add('/saved'))
let reads = 0, appended = false
vi.mocked(fs.readSync).mockImplementation((...args) => {
const count = actual.readSync(...args as Parameters<typeof actual.readSync>)
if (files.get(args[0]) === record(0) && ++reads === 2) {
appended = true
createHomeAdopter(file).adopt(add('/competitor'))
}
return count
})
expect(() => readAdoptedHomes(file)).toThrow('changed during its catalog read')
expect(appended).toBe(true)
expect(readAdoptedHomes(file).homes).toEqual(add('/saved', '/competitor'))
})
it('checks absent journal evidence again after a concurrent first adoption', () => {
actual.mkdirSync(join(root, 'data'), { mode: 0o700 })
actual.writeFileSync(file, '{"codex":[]}', { mode: 0o600 })
let reads = 0, appended = false
const open = vi.mocked(fs.openSync).getMockImplementation()!
vi.mocked(fs.openSync).mockImplementation((...args) => {
if (String(args[0]) === file && ++reads === 2) {
appended = true
createHomeAdopter(file).adopt(add('/competitor'))
}
return open(...args)
})
expect(() => readAdoptedHomes(file)).toThrow('changed during its catalog read')
expect(appended).toBe(true)
})
it.each(['first', 'append', 'idempotent'] as const)('imports a baseline appearing during %s publication before acknowledgement', phase => {
if (phase !== 'first') adopter.adopt(add('/saved'))
let changed = false
const external = () => { changed = true; actual.writeFileSync(file, '{"codex":["/external"]}', { mode: 0o600 }) }
vi.mocked(fs.linkSync).mockImplementation((from, to) => {
if (!changed && phase !== 'idempotent' && String(to) === record(phase === 'first' ? 0 : 1)) external()
return actual.linkSync(from, to)
})
vi.mocked(fs.fsyncSync).mockImplementation(fd => {
if (!changed && phase === 'idempotent' && files.get(fd) === file + '.confirmations') external()
actual.fsyncSync(fd)
})
const result = adopter.adopt(add(phase === 'idempotent' ? '/saved' : '/requested'))
expect(result.codex).toContain('/external')
expect(changed).toBe(true)
actual.unlinkSync(file)
expect(() => readAdoptedHomes(file)).toThrow('missing its adopted legacy catalog')
actual.writeFileSync(file, '{}', { mode: 0o600 })
expect(readAdoptedHomes(file).homes.codex).toContain('/external')
})
it.each(['replacement', 'removal'] as const)('retains a completely observed baseline across a deadline hold and %s', change => {
let probes = 0
vi.mocked(fs.linkSync).mockImplementation((from, to) => {
if (String(to) === record(0)) actual.writeFileSync(file, '{"codex":["/competitor"]}', { mode: 0o600 })
return actual.linkSync(from, to)
})
vi.mocked(fs.lstatSync).mockImplementation(((path, options) => {
// Let the final complete read return B, then exhaust the next rebase before B is imported.
if (String(path) === record(127) && ++probes === 2) clock.remaining = 1
return actual.lstatSync(path, options)
}) as typeof fs.lstatSync)
expect(() => adopter.adopt(add('/requested'))).toThrow('work deadline')
expect(adopter.observations()).toEqual({ homes: add('/requested', '/competitor'), legacyRequired: true, exhausted: false })
expect(actual.existsSync(record(1))).toBe(false)
clock.remaining = Infinity
vi.mocked(fs.lstatSync).mockImplementation(actual.lstatSync)
if (change === 'removal') {
actual.unlinkSync(file)
expect(() => adopter.adopt(add('/requested'))).toThrow('missing its observed legacy catalog')
}
actual.writeFileSync(file, '{}', { mode: 0o600 })
expect(adopter.adopt(empty()).codex).toEqual(['/requested', '/competitor'])
expect(readAdoptedHomes(file).homes.codex).toContain('/competitor')
actual.unlinkSync(file)
expect(() => readAdoptedHomes(file)).toThrow('missing its adopted legacy catalog')
})
it('keeps observation overflow held through later retries', () => {
actual.mkdirSync(join(root, 'data'), { mode: 0o700 })
actual.writeFileSync(file, JSON.stringify(add('/first')), { mode: 0o600 })
vi.mocked(fs.fsyncSync).mockImplementationOnce(() => { throw unavailable() })
expect(() => adopter.adopt(empty())).toThrow()
actual.writeFileSync(file, JSON.stringify(add(...Array.from({ length: 63 }, (_, n) => `/next-${n}`))))
expect(() => adopter.adopt(empty())).toThrow('known session-home limit')
actual.writeFileSync(file, JSON.stringify(add('/first')))
expect(() => adopter.adopt(empty())).toThrow('retained observation limit')
expect(adopter.observations().exhausted).toBe(true)
expect(actual.existsSync(record(0))).toBe(false)
})
it.each(['journal', 'confirmations', 'both'] as const)('holds an ancestor redirected only during %s enumeration to an old valid prefix', target => {
adopter.adopt(add('/saved'))
const old = join(root, 'old-data'), current = join(root, 'data'), aside = join(root, 'aside')
actual.cpSync(current, old, { recursive: true })
adopter.adopt(add('/competitor'))
let redirected = false
vi.mocked(fs.opendirSync).mockImplementation((path, options) => {
const wanted = target === 'journal' ? file + '.adoptions' : file + '.confirmations'
if (target === 'both' ? ![file + '.adoptions', file + '.confirmations'].includes(String(path)) : String(path) !== wanted) return actual.opendirSync(path, options)
redirected = true
actual.renameSync(current, aside); actual.symlinkSync(old, current)
try { return actual.opendirSync(path, options) }
finally { actual.unlinkSync(current); actual.renameSync(aside, current) }
})
expect(() => readAdoptedHomes(file)).toThrow('numbered entry pool')
expect(redirected).toBe(true)
})
it('holds an addition after its next slot was inspected during the final numbered pass', () => {
adopter.adopt(add('/saved'))
let probes = 0, appended = false
vi.mocked(fs.lstatSync).mockImplementation(((path, options) => {
if (String(path) === record(127) && ++probes === 2) {
appended = true
createHomeAdopter(file).adopt(add('/late-competitor'))
}
return actual.lstatSync(path, options)
}) as typeof fs.lstatSync)
expect(() => readAdoptedHomes(file)).toThrow('changed its directory during enumeration')
expect(appended).toBe(true)
})
it.each([['relative'], ['/bad\0path'], ['/' + 'x'.repeat(4096)], Array.from({ length: 64 }, (_, n) => `/home-${n}`)].map(paths => ({ paths })))
('refuses an invalid request without publishing any prefix: $paths', ({ paths }) => {
expect(() => adopter.adopt(add(...paths))).toThrow('invalid home list')
expect(actual.existsSync(record(0))).toBe(false)
})
it('holds when an I/O call exhausts the shared work deadline', () => {
vi.mocked(fs.fsyncSync).mockImplementation(fd => { actual.fsyncSync(fd); clock.now += NATIVE_EVIDENCE_MS + 1 })
expect(() => adopter.adopt(add('/held'))).toThrow('work deadline')
expect(actual.existsSync(record(0))).toBe(false)
})
})
describe('the adoption journal on Windows', () => {
const ntfs = (kind: 'file' | 'dir' | 'link') => ({
dev: 1n, ino: 2n, uid: 0n, size: 10n, mtimeNs: 1n, ctimeNs: 1n, mode: kind === 'dir' ? 0o40666n : 0o100666n,
isFile: () => kind === 'file', isDirectory: () => kind === 'dir', isSymbolicLink: () => kind === 'link',
}) as unknown as fs.BigIntStats
it('trusts a file and folder NTFS reports with no owner and every write bit, on Windows only', () => {
expect(() => inspectJournalEntry(ntfs('file'), false, 'win32')).not.toThrow()
expect(() => inspectJournalEntry(ntfs('dir'), true, 'win32')).not.toThrow()
expect(() => inspectJournalEntry(ntfs('file'), false, 'linux')).toThrow(/unsafe owner, type or write permission/)
})
it('still refuses a link or junction on Windows', () => {
expect(() => inspectJournalEntry(ntfs('link'), false, 'win32')).toThrow(/unsafe owner, type or write permission/)
expect(() => inspectJournalEntry(ntfs('link'), true, 'win32')).toThrow(/unsafe owner, type or write permission/)
})
it('takes a Windows home on Windows and a POSIX home elsewhere', () => {
expect(homeIsAbsolute('C:\\Users\\u\\.claude-work', 'win32')).toBe(true)
expect(homeIsAbsolute('c:/Users/u/.codex-2', 'win32')).toBe(false)
expect(homeIsAbsolute('\\\\server\\share\\.claude', 'win32')).toBe(false)
expect(homeIsAbsolute('/Users/u/.claude', 'win32')).toBe(false)
expect(homeIsAbsolute('/Users/u/.claude', 'darwin')).toBe(true)
expect(homeIsAbsolute('C:\\Users\\u\\.claude', 'linux')).toBe(false)
})
it('catches a network or device path on Windows alone', () => {
for (const home of ['\\\\server\\share\\.codex', '\\\\?\\C:\\Users\\u', '\\\\.\\pipe\\x', '//server/share']) expect(homeIsNetworkOrDevice(home, 'win32')).toBe(true)
for (const home of ['C:\\Users\\u\\.codex', 'C:/Users/u/.codex', '/Users/u/.codex', '']) expect(homeIsNetworkOrDevice(home, 'win32')).toBe(false)
for (const platform of ['darwin', 'linux'] as const) expect(homeIsNetworkOrDevice('\\\\server\\share', platform)).toBe(false)
})
it('names the setting and a folder in the person\'s own profile', () => {
expect(networkHomeSentence('CODEX_HOME', 'C:\\Users\\ann')).toBe('CODEX_HOME names a network or device path, which Harness does not use for an engine home on Windows. Set it to a folder on this computer\'s drive, such as C:\\Users\\ann\\.codex.')
expect(networkHomeSentence('CLAUDE_CONFIG_DIR', 'C:\\Users\\ann')).toContain('such as C:\\Users\\ann\\.claude.')
expect(networkHomeSentence('HERMES_HOME', 'C:\\Users\\ann')).toMatch(/drive\.$/)
})
it('round-trips a home built from the real temp folder through seal and inspect on this host', () => {
const home = join(root, 'home')
const adopter = createHomeAdopter(file)
adopter.adopt({ claude: [home], codex: [] })
expect(readAdoptedHomes(file).homes).toEqual({ claude: [home], codex: [] })
})
})