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, describe, expect, it, vi } from 'vitest'
import {
chmodSync, fsyncSync, mkdirSync, mkdtempSync, readFileSync, renameSync,
rmSync, statSync, symlinkSync, utimesSync, writeFileSync,
} from 'fs'
import { tmpdir } from 'os'
import { join } from 'path'
import type { registry as Registry } from './registry.js'
// Count actual writes; the registry, locks, permission checks and fsyncs still use real files.
vi.mock('fs', async (importOriginal) => {
const fs = await importOriginal<typeof import('fs')>()
return { ...fs, fsyncSync: vi.fn(fs.fsyncSync), renameSync: vi.fn(fs.renameSync), mkdirSync: vi.fn(fs.mkdirSync) }
})
let directory: string
let file: string
let registry: typeof Registry
const input = {
agentId: 'observed-agent', engine: 'claude' as const, tmuxPane: '%31', cwd: '/fixture/project',
processIdentity: { pid: 1031, executable: '/fixture/claude', startMarker: 'fixture-1031' },
}
const plan = {
id: '12345678-1234-1234-1234-123456789012', identity: 'fixture-conversation',
requestedAt: 1790900000000, state: 'waiting' as const,
}
const readRows = () => JSON.parse(readFileSync(file, 'utf8'))
const clearCounts = () => vi.clearAllMocks()
const registryWrites = () => vi.mocked(renameSync).mock.calls.filter(([, target]) => target === file).length
const lockAttempts = () => vi.mocked(mkdirSync).mock.calls.filter(([target]) => target === `${file}.lock`).length
async function observe() {
const row = registry.byAgent(input.agentId)!
await registry.transaction(() => {
expect(registry.updateRuntimes(row.agentId, row.runtimes, row.primaryRuntimeKey)).toBe(true)
expect(registry.updateProcessIdentity(row.agentId, { ...row.processIdentity! })).toBe(true)
})
}
beforeEach(async () => {
vi.resetModules()
vi.useFakeTimers()
vi.setSystemTime(1790900000000)
directory = mkdtempSync(join(tmpdir(), 'registry-observation-'))
file = join(directory, 'registry.json')
for (const key of ['ADAPTER_DATA_DIR', 'CLAUDE_PROJECTS_DIR', 'CODEX_HOME', 'CURSOR_HOME']) vi.stubEnv(key, directory)
registry = (await import('./registry.js')).registry
registry.load()
expect(registry.openProcessAgent(input)).not.toBeNull()
clearCounts()
vi.setSystemTime(Date.now() + 5000)
})
afterEach(() => {
vi.mocked(fsyncSync).mockReset()
vi.useRealTimers()
vi.unstubAllEnvs()
vi.restoreAllMocks()
rmSync(directory, { recursive: true, force: true })
})
describe('unchanged discovery observations', () => {
it('preserves the saved bytes, clock and object identity without locks or fsyncs', async () => {
const row = registry.byAgent(input.agentId)!
const original = readFileSync(file, 'utf8')
const touchedAt = row.touchedAt
registry.setTerminalAvailable(row.agentId, false)
for (let pass = 0; pass < 3; pass++) {
await observe()
expect(registry.openProcessAgent({ ...input, processIdentity: { ...input.processIdentity } })?.entry).toBe(row)
vi.setSystemTime(Date.now() + 5000)
}
expect(registry.terminalAvailable(row.agentId)).toBe(true)
expect(registry.byProcess('claude', input.processIdentity)).toBe(row)
expect(row.touchedAt).toBe(touchedAt)
expect(readFileSync(file, 'utf8')).toBe(original)
expect(registryWrites()).toBe(0)
expect(lockAttempts()).toBe(0)
expect(fsyncSync).not.toHaveBeenCalled()
})
// The daemon rewrote registry.json every 5 s when only key order differed (2026-10-06 profile).
it('does not rewrite a registry saved with another key order, yet writes a real change', async () => {
const reversed = <T extends object>(o: T): T => Object.fromEntries(Object.entries(o).reverse()) as T
const [saved] = readRows()
writeFileSync(file, JSON.stringify([reversed({
...saved, processIdentity: reversed(saved.processIdentity), runtimes: saved.runtimes.map(reversed),
launch: { state: 'ready' }, forkedFrom: { name: 'Parent', agentId: 'parent-agent' },
closePlan: reversed(plan), lastOpenedAt: 1790900000000,
})], null, 2))
clearCounts()
registry.load()
const discover = () => registry.transaction(() => {
registry.updateRuntimes(input.agentId, [{ backend: 'tmux', paneId: '%31' }])
registry.updateProcessIdentity(input.agentId, { ...input.processIdentity })
})
await discover()
expect(registryWrites()).toBe(1)
const bytes = readFileSync(file, 'utf8')
const touchedAt = readRows()[0].touchedAt
clearCounts()
for (let pass = 0; pass < 3; pass++) {
vi.setSystemTime(Date.now() + 5000)
await discover()
}
expect(registryWrites()).toBe(0)
expect(lockAttempts()).toBe(0)
expect(fsyncSync).not.toHaveBeenCalled()
expect(readFileSync(file, 'utf8')).toBe(bytes)
expect(readRows()[0]).toMatchObject({ touchedAt, launch: { state: 'ready' }, closePlan: plan,
forkedFrom: { name: 'Parent', agentId: 'parent-agent' }, lastOpenedAt: 1790900000000 })
await registry.transaction(() => {
registry.updateProcessIdentity(input.agentId, { ...input.processIdentity, startMarker: 'fixture-next' })
})
expect(registryWrites()).toBe(1)
expect(fsyncSync).toHaveBeenCalledTimes(3)
expect(readRows()[0]).toMatchObject({ processIdentity: { startMarker: 'fixture-next' }, touchedAt: Date.now() })
})
it('keeps another process\'s change to a nested field when a different field changes here', () => {
registry.setClosePlan(input.agentId, plan)
const [saved] = readRows()
writeFileSync(file, JSON.stringify([{ ...saved, closePlan: { ...plan, state: 'failed', detail: 'external' } }], null, 2))
registry.updateProcessIdentity(input.agentId, input.processIdentity, 'ori')
expect(readRows()[0]).toMatchObject({ gateway: 'ori', closePlan: { state: 'failed', detail: 'external' } })
expect(registry.byAgent(input.agentId)?.closePlan?.state).toBe('failed')
})
it('still persists a changed route and process generation in one durable transaction', async () => {
const row = registry.byAgent(input.agentId)!
const identity = { ...input.processIdentity, startMarker: 'replacement-generation', executable: '/fixture/new-claude' }
await registry.transaction(() => {
registry.updateRuntimes(row.agentId, [{ backend: 'tmux', paneId: '%32' }])
registry.updateProcessIdentity(row.agentId, identity, 'ori', { baseUrl: 'https://fixture.invalid/relay', model: 'fixture' })
})
expect(registry.byProcess('claude', input.processIdentity)).toBeUndefined()
expect(registry.byProcess('claude', identity)).toBe(row)
expect(registry.byPaneEngine('%31', 'claude')).toBeUndefined()
expect(registry.byPaneEngine('%32', 'claude')).toBe(row)
expect(readRows()[0]).toMatchObject({ processIdentity: identity, gateway: 'ori', tmuxPane: '%32', touchedAt: Date.now() })
expect(registryWrites()).toBe(1)
expect(fsyncSync).toHaveBeenCalledTimes(3)
clearCounts()
await observe()
expect(fsyncSync).not.toHaveBeenCalled()
})
it('durably reactivates a dormant process and finishes a pending launch', async () => {
registry.setActive(input.agentId, false)
registry.setLaunch(input.agentId, { state: 'starting' })
clearCounts()
const row = registry.openProcessAgent(input)!.entry
expect(readRows()[0]).toMatchObject({ active: true, launch: { state: 'ready' }, touchedAt: Date.now() })
expect(registryWrites()).toBe(1)
expect(row.launch?.state).toBe('ready')
clearCounts()
registry.openProcessAgent(input)
expect(fsyncSync).not.toHaveBeenCalled()
registry.setActive(input.agentId, false)
clearCounts()
await observe()
expect(readRows()[0].active).toBe(true)
expect(registryWrites()).toBe(1)
})
it('persists newly learned launch metadata and an unbound folder exactly once', () => {
const learned = { ...input, cwd: '/fixture/moved', codexHome: '/fixture/profile',
hermesHome: '/fixture/hermes', dsh: 'examples/hello-world', gateway: 'ori' as const }
registry.openProcessAgent(learned)
expect(readRows()[0]).toMatchObject({ cwd: learned.cwd, codexHome: learned.codexHome,
hermesHome: learned.hermesHome, dsh: learned.dsh, gateway: 'ori' })
expect(registryWrites()).toBe(1)
clearCounts()
registry.openProcessAgent(learned)
expect(fsyncSync).not.toHaveBeenCalled()
})
it.each(['in-place', 'atomic replacement'])('imports an external session bind on an otherwise unchanged pass (%s)', async (method) => {
const row = registry.byAgent(input.agentId)!
const [external] = readRows()
external.sessionId = 'externally-bound-session'
external.boundAt = Date.now()
external.title = 'Hook title'
const before = statSync(file)
if (method === 'in-place') {
writeFileSync(file, JSON.stringify([external], null, 2))
utimesSync(file, before.atime, before.mtime)
} else {
const next = `${file}.external`
writeFileSync(next, JSON.stringify([external], null, 2), { mode: 0o600 })
renameSync(next, file)
}
clearCounts()
await observe()
expect(registry.get('externally-bound-session')).toBe(row)
expect(row.title).toBe('Hook title')
expect(readRows()[0].sessionId).toBe('externally-bound-session')
clearCounts()
await observe()
expect(fsyncSync).not.toHaveBeenCalled()
})
it('does not trust cached bytes when file permissions or type change', async () => {
const original = readFileSync(file, 'utf8')
const error = vi.spyOn(console, 'error').mockImplementation(() => {})
chmodSync(file, 0o660)
await observe()
expect(error).toHaveBeenCalled()
expect(statSync(file).mode & 0o777).toBe(0o660)
expect(registryWrites()).toBe(0)
chmodSync(file, 0o600)
renameSync(file, `${file}.target`)
symlinkSync(`${file}.target`, file)
clearCounts()
await observe()
expect(error).toHaveBeenCalled()
expect(registryWrites()).toBe(0)
expect(readFileSync(`${file}.target`, 'utf8')).toBe(original)
})
it('retains external additions alongside a local change in the same pass', async () => {
const [original] = readRows()
const other = { ...original, agentId: 'hook-agent', sessionId: 'hook-session', tmuxPane: '%99',
runtimes: [{ backend: 'tmux', paneId: '%99' }], primaryRuntimeKey: 'tmux\u0000%99',
processIdentity: { ...input.processIdentity, pid: 1099, startMarker: 'fixture-1099' } }
writeFileSync(file, JSON.stringify([{ ...original, title: 'external title' }, other]))
await registry.transaction(() => {
registry.updateProcessIdentity(input.agentId, input.processIdentity, 'ori')
registry.updateRuntimes(input.agentId, [{ backend: 'tmux', paneId: '%31' }])
})
expect(registry.get('hook-session')?.agentId).toBe('hook-agent')
expect(registry.byAgent(input.agentId)).toMatchObject({ title: 'external title', gateway: 'ori' })
expect(readRows()).toHaveLength(2)
clearCounts()
await observe()
expect(fsyncSync).not.toHaveBeenCalled()
})
it('imports an external close cancellation without resurrecting it on the next pass', async () => {
const row = registry.byAgent(input.agentId)!
registry.setClosePlan(input.agentId, plan)
const [external] = readRows()
delete external.closePlan
writeFileSync(file, JSON.stringify([external], null, 2))
await observe()
expect(registry.byAgent(input.agentId)).toBe(row)
expect(row.closePlan).toBeUndefined()
clearCounts()
await observe()
expect(readRows()[0].closePlan).toBeUndefined()
expect(fsyncSync).not.toHaveBeenCalled()
})
it('does not treat a removed registry as a matching cached file', async () => {
rmSync(file)
await observe()
// No local change may undo an external deletion. The next discovery can adopt it afresh.
expect(registry.list()).toEqual([])
expect(readRows()).toEqual([])
expect(registryWrites()).toBe(1)
})
it('rechecks the directory permissions even when file bytes match', async () => {
const error = vi.spyOn(console, 'error').mockImplementation(() => {})
chmodSync(directory, 0o770)
await observe()
expect(error).toHaveBeenCalled()
expect(statSync(directory).mode & 0o777).toBe(0o770)
expect(lockAttempts()).toBe(0)
expect(fsyncSync).not.toHaveBeenCalled()
})
it.each(['[{', '[{"schemaVersion":99}]'])('retains an external invalid registry without hiding the failure: %s', async (bytes) => {
const error = vi.spyOn(console, 'error').mockImplementation(() => {})
writeFileSync(file, bytes)
await observe()
expect(error).toHaveBeenCalled()
expect(readFileSync(file, 'utf8')).toBe(bytes)
expect(registryWrites()).toBe(0)
})
it('retries a failed actual change on the next unchanged observation', async () => {
vi.spyOn(console, 'error').mockImplementation(() => {})
vi.mocked(fsyncSync).mockImplementationOnce(() => { throw new Error('fixture disk failure') })
registry.updateProcessIdentity(input.agentId, input.processIdentity, 'ori')
expect(readRows()[0].gateway).not.toBe('ori')
clearCounts()
await observe()
expect(readRows()[0].gateway).toBe('ori')
expect(registryWrites()).toBe(1)
expect(fsyncSync).toHaveBeenCalledTimes(3)
})
it('always durably acknowledges close intents, including identical retries', () => {
registry.setClosePlan(input.agentId, plan)
clearCounts()
registry.setClosePlan(input.agentId, { ...plan })
expect(readRows()[0].closePlan).toEqual(plan)
expect(registryWrites()).toBe(1)
expect(fsyncSync).toHaveBeenCalledTimes(3)
})
it('rejects and rolls back a close intent when storage fails', () => {
vi.mocked(fsyncSync).mockImplementationOnce(() => { throw new Error('fixture disk failure') })
expect(() => registry.setClosePlan(input.agentId, plan)).toThrow('fixture disk failure')
expect(registry.byAgent(input.agentId)?.closePlan).toBeUndefined()
expect(readRows()[0].closePlan).toBeUndefined()
registry.setClosePlan(input.agentId, plan)
expect(readRows()[0].closePlan).toEqual(plan)
})
// Each of these is another process's write this view has not read: a hook's, a second daemon's, a
// command's. CI's registry-observation contract lost the first one when a process was starved.
it('a cancellation from a view that never saw another process\'s close plan removes it', () => {
const [row] = readRows()
writeFileSync(file, JSON.stringify([{ ...row, closePlan: plan }], null, 2))
registry.setClosePlan(input.agentId, null)
expect(readRows()[0].closePlan).toBeUndefined()
expect(registry.byAgent(input.agentId)?.closePlan).toBeUndefined()
})
it('a close retried over another process\'s cancellation is written again', () => {
registry.setClosePlan(input.agentId, plan)
const [row] = readRows()
delete row.closePlan
writeFileSync(file, JSON.stringify([row], null, 2))
registry.setClosePlan(input.agentId, { ...plan })
expect(readRows()[0].closePlan).toEqual(plan)
})
it('a cancellation never brings back a row another process removed', () => {
writeFileSync(file, JSON.stringify([], null, 2))
registry.setClosePlan(input.agentId, null)
expect(readRows()).toEqual([])
expect(registry.byAgent(input.agentId)).toBeUndefined()
})
it('a cancellation whose save failed is not written by a later save', async () => {
const [row] = readRows()
writeFileSync(file, JSON.stringify([{ ...row, closePlan: plan }], null, 2))
vi.mocked(fsyncSync).mockImplementationOnce(() => { throw new Error('fixture disk failure') })
expect(() => registry.setClosePlan(input.agentId, null)).toThrow('fixture disk failure')
await observe()
expect(readRows()[0].closePlan).toEqual(plan)
})
it('never acknowledges a close intent within an uncommitted transaction', async () => {
await expect(registry.transaction(() => registry.setClosePlan(input.agentId, plan)))
.rejects.toThrow('uncommitted registry transaction')
expect(registry.byAgent(input.agentId)?.closePlan).toBeUndefined()
expect(readRows()[0].closePlan).toBeUndefined()
})
})