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, constants, openSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, symlinkSync, utimesSync, writeFileSync } from 'node:fs'
import { join } from 'node:path'
import { tmpdir } from 'node:os'
import type { RegisteredSession } from './registry.js'
vi.mock('node:fs', async original => { const fs = await original<typeof import('node:fs')>(); return { ...fs, openSync: vi.fn(fs.openSync), readFileSync: vi.fn(fs.readFileSync) } })
let directory = ''
beforeEach(() => {
vi.resetModules()
directory = mkdtempSync(join(tmpdir(), 'harness-stopped-'))
vi.stubEnv('ADAPTER_DATA_DIR', directory)
})
afterEach(() => {
vi.mocked(openSync).mockRestore()
vi.mocked(readFileSync).mockRestore()
vi.unstubAllEnvs()
rmSync(directory, { recursive: true, force: true })
})
describe('saved catalog reads', () => {
it('saves a held conversation without persisting its transient identity verdict', async () => {
const { saved, store } = await fixture()
store.save({ ...saved, identityHold: 'The session-home catalog is unavailable.', evidenceRevision: 3, interpretationHold: 'pending', admissionHold: 'Waiting for native source' })
const raw = JSON.parse(readFileSync(join(directory, 'stopped-agents', `${saved.agentId}.json`), 'utf8'))
expect(raw.session.sessionId).toBe(saved.sessionId)
expect(raw.session).not.toHaveProperty('identityHold')
expect(raw.session).not.toHaveProperty('admissionHold')
expect(raw.session).not.toHaveProperty('interpretationHold')
expect(raw.session).not.toHaveProperty('evidenceRevision')
expect(store.get(saved.agentId)).not.toHaveProperty('identityHold')
})
it('does not reread unchanged records for status snapshots, but resume still reads the file', async () => {
const { saved, store } = await fixture()
store.save(saved)
const first = store.list()
vi.mocked(readFileSync).mockClear()
for (let i = 0; i < 20; i++) expect(store.available([])).toEqual(first)
expect(readFileSync).not.toHaveBeenCalled()
expect(store.get(saved.agentId)).toEqual(first[0])
expect(readFileSync).toHaveBeenCalledTimes(1)
})
it('keeps cached records private and filters the current live inventory on every call', async () => {
const { saved, store } = await fixture()
store.save(saved)
const [first] = store.list()
first.title = 'A caller changed this'
first.runtimes[0].paneId = '%999'
first.processIdentity!.pid = 1
expect(store.list()[0]).toMatchObject({ title: saved.title, runtimes: saved.runtimes, processIdentity: saved.processIdentity })
expect(store.available([saved])).toEqual([])
expect(store.available([])).toHaveLength(1)
})
it('periodically revalidates file contents and refreshes after a backwards clock change', async () => {
const { saved, store } = await fixture()
store.save(saved)
const now = Date.now()
const clock = vi.spyOn(Date, 'now').mockReturnValue(now)
try {
store.list()
vi.mocked(readFileSync).mockClear()
clock.mockReturnValue(now + 30_000)
expect(store.list()).toHaveLength(1)
expect(readFileSync).toHaveBeenCalledTimes(1)
vi.mocked(readFileSync).mockClear()
clock.mockReturnValue(now - 1)
expect(store.list()).toHaveLength(1)
expect(readFileSync).toHaveBeenCalledTimes(1)
} finally { clock.mockRestore() }
})
it('sees saves, patches, external replacements, in-place edits and deletion immediately', async () => {
const { saved, store } = await fixture()
store.save(saved)
store.list()
store.patch(saved.agentId, { cwd: '/changed' })
expect(store.list()[0].cwd).toBe('/changed')
store.save({ ...saved, title: 'Updated title' })
expect(store.list()[0].title).toBe('Updated title')
const file = join(directory, 'stopped-agents', `${saved.agentId}.json`)
const replacement = `${file}.tmp`
const raw = JSON.parse(readFileSync(file, 'utf8'))
raw.session.title = 'External edit'
writeFileSync(replacement, JSON.stringify(raw), { mode: 0o600 })
renameSync(replacement, file)
expect(store.list()[0].title).toBe('External edit')
const before = statSync(file)
raw.session.title = 'External next' // Same length; restoring mtime must not conceal the edit.
writeFileSync(file, JSON.stringify(raw))
utimesSync(file, before.atime, before.mtime)
expect(store.list()[0].title).toBe('External next')
rmSync(file)
expect(store.list()).toEqual([])
store.save(saved)
expect(store.list()[0].sessionId).toBe(saved.sessionId)
})
it('drops a warmed record when corrupted, unsafe, or replaced by a symlink', async () => {
const { saved, store } = await fixture()
store.save(saved)
const file = join(directory, 'stopped-agents', `${saved.agentId}.json`)
const raw = readFileSync(file, 'utf8')
store.list()
writeFileSync(file, '{')
expect(store.list()).toEqual([])
writeFileSync(file, raw)
expect(store.list()).toHaveLength(1)
chmodSync(file, 0o666)
expect(store.list()).toEqual([])
expect(() => store.get(saved.agentId)).toThrow()
chmodSync(file, 0o600)
expect(store.list()).toHaveLength(1)
rmSync(file)
const target = join(directory, 'other.json')
writeFileSync(target, raw, { mode: 0o600 })
symlinkSync(target, file)
expect(store.list()).toEqual([])
expect(() => store.get(saved.agentId)).toThrow()
expect(readFileSync(target, 'utf8')).toBe(raw)
chmodSync(join(directory, 'stopped-agents'), 0o777)
expect(() => store.list()).toThrow()
})
it('does not cache a read under the identity of a replacement made during that read', async () => {
const { saved, store } = await fixture()
store.save(saved)
const file = join(directory, 'stopped-agents', `${saved.agentId}.json`)
const raw = JSON.parse(readFileSync(file, 'utf8'))
raw.session.title = 'Replacement'
const replacement = `${file}.tmp`
writeFileSync(replacement, JSON.stringify(raw), { mode: 0o600 })
const real = await vi.importActual<typeof import('node:fs')>('node:fs')
vi.mocked(readFileSync).mockImplementationOnce((...args: any[]) => {
const value = (real.readFileSync as (...args: any[]) => any)(...args)
renameSync(replacement, file)
return value
})
expect(store.list()[0].title).toBe(saved.title)
expect(store.list()[0].title).toBe('Replacement')
})
it('bounds retained bytes while keeping every large record visible and fresh', async () => {
const { saved, store } = await fixture()
store.save(saved)
const base = join(directory, 'stopped-agents')
rmSync(join(base, `${saved.agentId}.json`))
for (let i = 0; i < 10; i++) {
writeFileSync(join(base, `large-${i}.json`), JSON.stringify({ version: 1,
session: { ...saved, agentId: `large-${i}`, title: 'x'.repeat(512 * 1024) } }), { mode: 0o600 })
}
expect(store.list()).toHaveLength(10)
vi.mocked(readFileSync).mockClear()
expect(store.list()).toHaveLength(10)
// Ten half-megabyte files exceed the cache's byte budget; some must stay on disk.
expect(vi.mocked(readFileSync).mock.calls.length).toBeGreaterThan(0)
expect(vi.mocked(readFileSync).mock.calls.length).toBeLessThan(10)
for (let i = 0; i < 10; i++) rmSync(join(base, `large-${i}.json`))
expect(store.list()).toEqual([])
store.save(saved)
store.list()
vi.mocked(readFileSync).mockClear()
expect(store.list()).toHaveLength(1)
expect(readFileSync).not.toHaveBeenCalled()
})
it('bounds cached record count without thrashing or hiding a larger catalog', async () => {
const { saved, store } = await fixture()
store.save(saved)
const base = join(directory, 'stopped-agents')
rmSync(join(base, `${saved.agentId}.json`))
for (let i = 0; i < 2050; i++) {
const agentId = `bounded-${String(i).padStart(4, '0')}`
writeFileSync(join(base, `${agentId}.json`), JSON.stringify({ version: 1,
session: { ...saved, agentId } }), { mode: 0o600 })
}
expect(store.list()).toHaveLength(2050)
for (let pass = 0; pass < 2; pass++) {
vi.mocked(readFileSync).mockClear()
expect(store.list()).toHaveLength(2050)
expect(readFileSync).toHaveBeenCalledTimes(2)
}
// 2,050 files written and listed three times: 0.8 to 0.9 s alone on the Mac Studio, 7.7 s inside `npm run test:resume`
// beside six other files at a load of 6 to 7, past the 5 s default (task #4405).
}, 30_000)
})
async function fixture() {
const { registry } = await import('./registry.js')
const { StoppedAgentStore } = await import('./stoppedAgents.js')
const entry = registry.openPendingAgent({ engine: 'codex', runtimes: [{ backend: 'tmux', paneId: '%8' }], cwd: '/tmp/work', defaultName: 'My work', codexHome: '/tmp/profile', dsh: 'autonomous/fixture', permissionMode: 'plan' })!
const saved: RegisteredSession = { ...entry, sessionId: 'conversation-123', title: 'Continue my work', processIdentity: { pid: 98765, executable: 'codex', startMarker: 'old-process' } }
const store = new StoppedAgentStore(join(directory, 'stopped-agents'))
return { registry, StoppedAgentStore, saved, store }
}
describe('stopped harness persistence', () => {
it('retains the conversation and launch profile after removal and store reload', async () => {
const { registry, StoppedAgentStore, saved, store } = await fixture()
store.save(saved)
registry.removeAgent(saved.agentId)
const restored = new StoppedAgentStore(join(directory, 'stopped-agents')).get(saved.agentId)!
expect(restored).toMatchObject({ agentId: saved.agentId, sessionId: 'conversation-123', engine: 'codex', cwd: '/tmp/work', codexHome: '/tmp/profile', dsh: 'autonomous/fixture', permissionMode: 'plan', active: false })
expect(registry.list()).toHaveLength(0)
expect(registry.advertised()).toHaveLength(0)
expect(store.available([])).toHaveLength(1)
expect(statSync(join(directory, 'stopped-agents', `${saved.agentId}.json`)).mode & 0o777).toBe(0o600)
})
it('patches one field of an archive without touching its name or activity time', async () => {
const { saved, store } = await fixture()
store.save({ ...saved, defaultName: 'harness Desktop' })
const before = store.get(saved.agentId)!
expect(store.patch(saved.agentId, { cwd: '/tmp/work-repaired' })).toBe(true)
const after = store.get(saved.agentId)!
expect(after).toEqual({ ...before, cwd: '/tmp/work-repaired' })
expect(after.touchedAt).toBe(before.touchedAt)
expect(after.defaultName).toBe('harness Desktop')
expect(store.patch('never-saved', { cwd: '/tmp' })).toBe(false)
})
// The global "last used" order must not forget an agent because it was paused: the archive keeps
// the stamp, the store reads it back, and the resumed row carries it into the live registry.
it('keeps when an app last opened the agent through a stop and a resume', async () => {
const { registry, StoppedAgentStore, saved, store } = await fixture()
const opened = registry.markOpened(saved.agentId)!.lastOpenedAt!
expect(opened).toBeGreaterThan(0)
store.save({ ...registry.byAgent(saved.agentId)!, sessionId: saved.sessionId })
registry.removeAgent(saved.agentId)
const archived = new StoppedAgentStore(join(directory, 'stopped-agents')).get(saved.agentId)!
expect(archived.lastOpenedAt).toBe(opened)
const resumed = registry.resumePendingAgent(archived, [{ backend: 'tmux', paneId: '%77' }])!
expect(resumed.lastOpenedAt).toBe(opened)
expect(registry.byAgent(saved.agentId)?.lastOpenedAt).toBe(opened)
})
it('T1 keeps a fork origin with its parent session through save, get and list', async () => {
const { registry, StoppedAgentStore, store } = await fixture()
const origin = { agentId: 'p', name: 'Parent', sessionId: 'p-sess', transcriptPath: '/x/p-sess.jsonl' }
const fork = registry.openPendingAgent({ engine: 'claude', runtimes: [{ backend: 'tmux', paneId: '%9' }], cwd: '/tmp/work', forkedFrom: origin })!
store.save({ ...fork, sessionId: 'fork-sess', active: false })
const fresh = new StoppedAgentStore(join(directory, 'stopped-agents'))
expect(fresh.get(fork.agentId)?.forkedFrom).toEqual(origin)
expect(fresh.list().find(row => row.agentId === fork.agentId)?.forkedFrom).toEqual(origin)
})
it('reads a stopped fork saved by an older daemon, and drops a malformed origin without failing the read', async () => {
const { registry, StoppedAgentStore, store } = await fixture()
const fork = registry.openPendingAgent({ engine: 'claude', runtimes: [{ backend: 'tmux', paneId: '%10' }], cwd: '/tmp/work',
forkedFrom: { agentId: 'p', name: 'Parent' } })!
store.save({ ...fork, active: false })
const file = join(directory, 'stopped-agents', `${fork.agentId}.json`)
const rewrite = (forkedFrom: unknown) => {
const record = JSON.parse(readFileSync(file, 'utf8'))
record.session.forkedFrom = forkedFrom
writeFileSync(file, JSON.stringify(record), { mode: 0o600 })
}
const fresh = () => new StoppedAgentStore(join(directory, 'stopped-agents'))
expect(fresh().get(fork.agentId)?.forkedFrom).toEqual({ agentId: 'p', name: 'Parent' })
rewrite({ agentId: 'p', name: 'Parent', sessionId: 'p-sess', transcriptPath: 'relative.jsonl', extra: 'x' })
expect(fresh().get(fork.agentId)?.forkedFrom).toEqual({ agentId: 'p', name: 'Parent', sessionId: 'p-sess' })
rewrite({ agentId: 7 })
const malformed = fresh().get(fork.agentId)
expect(malformed?.agentId).toBe(fork.agentId)
expect(malformed && 'forkedFrom' in malformed).toBe(false)
expect(fresh().list().find(row => row.agentId === fork.agentId)).toBeTruthy()
})
// Another harness took its conversation (core/agents/conversationOwners.ts): moved aside, never deleted.
it('sets a record aside, with its reservation, and lists it no more', async () => {
const { StoppedAgentStore, saved, store } = await fixture()
store.save(saved)
expect(store.beginResume(saved.agentId)).toBeTruthy()
const before = readFileSync(join(directory, 'stopped-agents', `${saved.agentId}.json`), 'utf8')
expect(store.list()).toHaveLength(1)
expect(store.supersede(saved.agentId)).toMatchObject({ agentId: saved.agentId, sessionId: 'conversation-123' })
expect(readFileSync(join(directory, 'stopped-agents', 'superseded', `${saved.agentId}.json`), 'utf8')).toBe(before)
expect(statSync(join(directory, 'stopped-agents', 'superseded')).mode & 0o777).toBe(0o700)
expect(store.resumeReservedAt(saved.agentId)).toBeNull()
expect(store.get(saved.agentId)).toBeNull()
expect(store.list()).toEqual([])
expect(store.ids()).toEqual([])
expect(new StoppedAgentStore(join(directory, 'stopped-agents')).list()).toEqual([])
// Nothing to set aside: an unsafe id, an absent record, one already set aside.
expect(store.supersede('../escape')).toBeNull()
expect(store.supersede('never-saved')).toBeNull()
expect(store.supersede(saved.agentId)).toBeNull()
})
it('hides a running identity or conversation, without discarding its archive', async () => {
const { saved, store } = await fixture()
store.save(saved)
expect(store.available([saved])).toEqual([])
expect(store.available([{ ...saved, agentId: 'another-agent' }])).toEqual([])
expect(store.available([{ ...saved, agentId: 'another-agent', codexHome: '/other/profile' }])).toHaveLength(1)
expect(store.available([])).toHaveLength(1)
})
it.each([true, false])('hides a live Codex conversation across explicit and implicit default profiles, archived explicit=%s', async explicit => {
const { saved, store } = await fixture()
const { env } = await import('../config/env.js')
const defaultHome = join(env.CODEX_HOME, '.')
store.save({ ...saved, engine: 'codex', codexHome: explicit ? defaultHome : null })
const running = { ...saved, engine: 'codex' as const, agentId: 'replacement', codexHome: explicit ? null : defaultHome }
expect(store.available([running])).toEqual([])
expect(store.get(saved.agentId)?.sessionId).toBe(saved.sessionId)
expect(store.available([{ ...running, codexHome: '/another/codex-profile' }])).toHaveLength(1)
})
it('stopping the shell left by an exited engine preserves its conversation', async () => {
const { saved, store } = await fixture()
store.save(saved)
store.save({ ...saved, engine: 'terminal', sessionId: '', codexHome: null, dsh: null })
expect(store.get(saved.agentId)).toMatchObject({ engine: 'codex', sessionId: 'conversation-123', codexHome: '/tmp/profile' })
})
it('resumes on a new route with the same identity and refuses a duplicate claim', async () => {
const { registry, saved, store } = await fixture()
store.save(saved)
registry.removeAgent(saved.agentId)
const resumed = registry.resumePendingAgent(store.get(saved.agentId)!, [{ backend: 'tmux', paneId: '%99' }])!
expect(resumed).toMatchObject({ agentId: saved.agentId, sessionId: saved.sessionId, tmuxPane: '%99', processIdentity: null, launch: { state: 'starting' }, permissionMode: 'plan', codexHome: '/tmp/profile' })
expect(registry.resumePendingAgent(saved, [{ backend: 'tmux', paneId: '%100' }])).toBeNull()
expect(registry.advertised()).toHaveLength(1)
})
it('does not follow a planted archive symlink or overwrite unsafe state', async () => {
const { saved, store } = await fixture()
store.save(saved)
const file = join(directory, 'stopped-agents', `${saved.agentId}.json`)
const other = join(directory, 'other.json')
writeFileSync(other, 'untouched', { mode: 0o600 })
rmSync(file)
symlinkSync(other, file)
expect(() => store.get(saved.agentId)).toThrow()
expect(() => store.save(saved)).toThrow()
expect(readFileSync(other, 'utf8')).toBe('untouched')
rmSync(file)
store.save(saved)
chmodSync(file, 0o666)
expect(() => store.get(saved.agentId)).toThrow()
})
})
it('keeps the original identity searchable while preserving the surviving shell route', async () => {
const { registry, saved, store } = await fixture()
// Use the actual row, as the daemon does after registering its session.
Object.assign(registry.byAgent(saved.agentId)!, saved)
store.save(saved)
const shell = registry.releaseEngine(saved.agentId, true)!
expect(shell.agentId).not.toBe(saved.agentId)
expect(shell).toMatchObject({ engine: 'terminal', sessionId: '', tmuxPane: '%8', processIdentity: null })
expect(registry.byAgent(saved.agentId)).toBeUndefined()
expect(registry.bySession(saved.sessionId)).toBeUndefined()
expect(store.available(registry.list()).map(row => row.agentId)).toEqual([saved.agentId])
const resumed = registry.resumePendingAgent(store.get(saved.agentId)!, [{ backend: 'tmux', paneId: '%99' }])!
expect(resumed.agentId).toBe(saved.agentId)
expect(registry.byRuntimeTerminal({ backend: 'tmux', paneId: '%8' })?.agentId).toBe(shell.agentId)
expect(registry.list()).toHaveLength(2)
})
it('reserves allocation across daemon restarts and different receipt IDs', async () => {
const { store, StoppedAgentStore, saved } = await fixture()
const token = store.beginResume(saved.agentId)!
const restarted = new StoppedAgentStore(join(directory, 'stopped-agents'))
expect(restarted.beginResume(saved.agentId)).toBeNull()
restarted.finishResume(saved.agentId, 'someone-else')
expect(store.beginResume(saved.agentId)).toBeNull()
restarted.finishResume(saved.agentId, token)
expect(store.beginResume(saved.agentId)).not.toBeNull()
})
// A reservation left behind by a crash can be half-written, and that is exactly the one the
// age-based takeover in `resumeAgentService` has to be able to clear.
it('reports how long a reservation has been held, and clears a half-written one', async () => {
const { store, saved } = await fixture()
const before = Date.now()
expect(store.resumeReservedAt(saved.agentId)).toBeNull()
const token = store.beginResume(saved.agentId)!
const held = store.resumeReservedAt(saved.agentId)
expect(held).not.toBeNull()
expect(held!).toBeGreaterThanOrEqual(before - 1000)
writeFileSync(join(directory, 'stopped-agents', `${saved.agentId}.resume`), '{"token": "trunc')
// A caller clearing ITS OWN reservation still has to read the marker to know it is its own.
expect(() => store.finishResume(saved.agentId, token)).toThrow()
expect(store.resumeReservedAt(saved.agentId)).not.toBeNull()
// A caller taking it over is not asking whose it is.
store.finishResume(saved.agentId)
expect(store.resumeReservedAt(saved.agentId)).toBeNull()
expect(store.beginResume(saved.agentId)).not.toBeNull()
})
it('keeps readable archives discoverable beside corrupt, unsupported and mismatched records', async () => {
const { saved, store } = await fixture()
expect(store.list()).toEqual([])
store.save(saved)
const base = join(directory, 'stopped-agents')
for (const [id, content] of Object.entries({ corrupt: '{', version: JSON.stringify({ version: 99 }), invalid: JSON.stringify({ version: 1, session: {} }), mismatch: JSON.stringify({ version: 1, session: saved }) })) {
writeFileSync(join(base, `${id}.json`), content, { mode: 0o600 })
}
writeFileSync(join(base, 'unrelated.tmp'), 'skip')
expect(store.list().map(row => row.agentId)).toEqual([saved.agentId])
expect(store.get('missing')).toBeNull()
expect(store.get('../invalid')).toBeNull()
expect(() => store.save({ ...saved, agentId: '../invalid' })).toThrow()
expect(() => store.beginResume('../invalid')).toThrow()
store.finishResume('../invalid')
store.finishResume('absent')
chmodSync(base, 0o777)
expect(() => store.list()).toThrow()
})
it('persists a standalone shell and a runtime without the legacy tmux alias', async () => {
const { saved, store } = await fixture()
store.save({ ...saved, engine: 'terminal', sessionId: '', tmuxPane: '', runtimes: [{ backend: 'unknown', endpointId: 'fixture', paneId: '1' } as any], primaryRuntimeKey: ['unknown', 'fixture', '1'].join('\0'), codexHome: null })
const disk = JSON.parse(readFileSync(join(directory, 'stopped-agents', `${saved.agentId}.json`), 'utf8'))
expect(disk.session).not.toHaveProperty('tmuxPane')
expect(disk.session.sessionId).toBe('')
store.save({ ...saved, agentId: 'null-profile', codexHome: null })
expect(store.available([{ ...saved, agentId: 'live', codexHome: null }]).some(row => row.agentId === 'null-profile')).toBe(false)
expect(store.available([{ ...saved, sessionId: '' }])).toBeDefined()
})
it('fails closed on corrupt reservation data and unsafe reservation files', async () => {
const { saved, store } = await fixture()
const token = store.beginResume(saved.agentId)!
const marker = join(directory, 'stopped-agents', `${saved.agentId}.resume`)
writeFileSync(marker, '{')
expect(() => store.finishResume(saved.agentId, token)).toThrow()
expect(store.beginResume(saved.agentId)).toBeNull()
rmSync(marker)
// A directory in place of the reservation cannot be unlinked as a file.
symlinkSync('/dev/null', marker)
expect(() => store.finishResume(saved.agentId)).toThrow()
rmSync(marker)
// Fail before allocation if private-state traversal itself is unsafe.
chmodSync(join(directory, 'stopped-agents'), 0o777)
expect(() => store.beginResume(saved.agentId)).toThrow()
})
it('does not allocate when reserving disk space fails', async () => {
const { saved, store } = await fixture()
store.save(saved)
const real = await vi.importActual<typeof import('node:fs')>('node:fs')
vi.mocked(openSync).mockImplementation((file, flags, mode) => {
if (typeof flags === 'number' && (flags & constants.O_EXCL)) throw Object.assign(new Error('disk full'), { code: 'ENOSPC' })
return real.openSync(file, flags, mode)
})
expect(() => store.beginResume(saved.agentId)).toThrow('disk full')
expect(store.get(saved.agentId)?.sessionId).toBe(saved.sessionId)
})
it('an unbound observation of the same process keeps its confirmed conversation', async () => {
const { saved, store } = await fixture()
saved.transcriptPath = '/history.jsonl'; saved.boundAt = 1; saved.source = 'hook'; store.save(saved)
store.save({ ...saved, sessionId: '', transcriptPath: null, title: 'Renamed', boundAt: null, source: null })
expect(store.get(saved.agentId)).toMatchObject({ sessionId: saved.sessionId, transcriptPath: '/history.jsonl', title: 'Renamed', boundAt: 1, source: 'hook' })
})
it.each(['same', 'missing', 'different'] as const)('preserves an unbound Hermes conversation only with a compatible home: %s', async mode => {
const { saved, store } = await fixture()
Object.assign(saved, { engine: 'hermes', hermesHome: '/fixture/hermes' })
store.save(saved)
const hermesHome = mode === 'missing' ? undefined : mode === 'same' ? saved.hermesHome : '/fixture/other-hermes'
store.save({ ...saved, sessionId: '', transcriptPath: null, hermesHome })
expect(store.get(saved.agentId)).toMatchObject({
sessionId: mode === 'different' ? '' : saved.sessionId,
hermesHome: mode === 'different' ? hermesHome : saved.hermesHome,
})
})
it('a pathless observation of the same conversation keeps its captured native path', async () => {
const { saved, store } = await fixture()
saved.hermesHome = '/fixture/hermes'
store.save({ ...saved, transcriptPath: '/history.jsonl', source: 'stop-repair' })
store.save({ ...saved, transcriptPath: null, title: 'A newer title', source: 'hook' })
expect(store.get(saved.agentId)).toMatchObject({ sessionId: saved.sessionId,
transcriptPath: '/history.jsonl', title: 'A newer title', source: 'hook' })
store.save({ ...saved, transcriptPath: '/replacement.jsonl' })
expect(store.get(saved.agentId)?.transcriptPath).toBe('/replacement.jsonl')
})
it.each(['agent', 'conversation', 'engine', 'registration', 'profile', 'hermes home', 'missing process', 'pid', 'start', 'ticks', 'executable'])
('never transfers a captured path across a changed identity: %s', async mode => {
const { saved, store } = await fixture()
saved.processIdentity!.startTicks = 100
store.save({ ...saved, transcriptPath: '/history.jsonl' })
const next: RegisteredSession = { ...saved, transcriptPath: null, processIdentity: { ...saved.processIdentity! } }
if (mode === 'agent') next.agentId = 'another-agent'
if (mode === 'conversation') next.sessionId = 'another-conversation'
if (mode === 'engine') next.engine = 'claude'
if (mode === 'registration') next.registeredAt++
if (mode === 'profile') next.codexHome = '/another/profile'
if (mode === 'hermes home') next.hermesHome = '/another/hermes'
if (mode === 'missing process') next.processIdentity = null
if (mode === 'pid') next.processIdentity!.pid++
if (mode === 'start') { delete next.processIdentity!.startTicks; next.processIdentity!.startMarker = 'new' }
if (mode === 'ticks') next.processIdentity!.startTicks = 200
if (mode === 'executable') next.processIdentity!.executable = 'other'
store.save(next)
expect(store.get(next.agentId)?.transcriptPath).toBeNull()
})
it.each(['engine', 'missing', 'previous missing', 'pid', 'start', 'executable'])('does not transfer a binding to a different process: %s', async mode => {
const { saved, store } = await fixture()
store.save(mode === 'previous missing' ? { ...saved, processIdentity: null } : saved)
const next = { ...saved, sessionId: '', processIdentity: { ...saved.processIdentity! } } as RegisteredSession
if (mode === 'engine') next.engine = 'claude'
if (mode === 'missing') next.processIdentity = null
if (mode === 'pid') next.processIdentity!.pid++
if (mode === 'start') next.processIdentity!.startMarker = 'new'
if (mode === 'executable') next.processIdentity!.executable = 'other'
store.save(next); expect(store.get(saved.agentId)?.sessionId).toBe('')
})
it('lists the id of every saved record, unreadable ones included, and none before the folder exists', async () => {
const { saved, store } = await fixture()
expect(store.ids()).toEqual([])
store.save(saved)
writeFileSync(join(directory, 'stopped-agents', 'broken.json'), '{not json')
expect(store.ids().sort()).toEqual([saved.agentId, 'broken'].sort())
expect(store.list().map((s) => s.agentId)).toEqual([saved.agentId])
})
// The handoff asks whether any stopped record holds a conversation (handoffDiscovery `ownedByOther`) and
// fails closed when it cannot tell. An unreadable folder answered "no records" would let a handoff bind a
// conversation a stopped harness still owns.
it('says it cannot list the records when the folder cannot be read, never that there are none', async () => {
const { saved, store } = await fixture()
store.save(saved)
chmodSync(join(directory, 'stopped-agents'), 0o000)
try {
// Root reads through any mode: there is no unreadable folder to show.
if (process.getuid?.() !== 0) expect(() => store.ids()).toThrow(expect.objectContaining({ code: 'EACCES' }))
} finally { chmodSync(join(directory, 'stopped-agents'), 0o700) }
// A file where the folder should be is not "none yet" either.
const elsewhere = new (await import('./stoppedAgents.js')).StoppedAgentStore(join(directory, 'stopped-agents', `${saved.agentId}.json`))
expect(() => elsewhere.ids()).toThrow(expect.objectContaining({ code: 'ENOTDIR' }))
})
// Purging a stopped harness's saved session (purgeAgentService) is the one permanent deletion: Stop keeps
// the record, this removes it.
it('permanently deletes a stopped record, at once for every reader, and refuses an identity that is not one', async () => {
const { saved, StoppedAgentStore, store } = await fixture()
store.save(saved)
store.save({ ...saved, agentId: 'kept' })
// Warm the catalog, as a status snapshot does: the deletion must not be served from it afterwards.
expect(store.list().map((row) => row.agentId).sort()).toEqual([saved.agentId, 'kept'].sort())
store.remove(saved.agentId)
expect(store.get(saved.agentId)).toBeNull()
expect(store.list().map((row) => row.agentId)).toEqual(['kept'])
expect(store.ids()).toEqual(['kept'])
expect(new StoppedAgentStore(join(directory, 'stopped-agents')).get(saved.agentId)).toBeNull()
// Removing it again, or one never saved, is nothing to do; a path is never an identity.
expect(() => store.remove(saved.agentId)).not.toThrow()
expect(() => store.remove('never-saved')).not.toThrow()
expect(() => store.remove('../kept')).toThrow('Invalid stopped harness identity.')
expect(store.get('kept')?.agentId).toBe('kept')
})
// Only a harness identity names a record: a name in the folder that is not one is never read as a saved
// harness, and an identity that is a path never reaches outside the folder.
it('lists only files named by a harness identity, and never looks outside its folder for a reservation', async () => {
const { saved, store } = await fixture()
store.save(saved)
const base = join(directory, 'stopped-agents')
writeFileSync(join(base, 'not an id.json'), JSON.stringify({ version: 1, session: { ...saved, agentId: 'not an id' } }), { mode: 0o600 })
expect(store.list().map((row) => row.agentId)).toEqual([saved.agentId])
// A reservation beside the folder, where `../escape` would point.
writeFileSync(join(directory, 'escape.resume'), '{}', { mode: 0o600 })
expect(store.resumeReservedAt('../escape')).toBeNull()
expect(store.resumeReservedAt(saved.agentId)).toBeNull()
})