Skip to content

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.

15.2 KB
Raw Blame
import * as fs from 'node:fs'
import { tmpdir } from 'node:os'
import { dirname, join } from 'node:path'
import { afterEach, beforeEach, expect, it, vi } from 'vitest'
import { NativeFiles } from './kit/nativeFiles.js'
import { NativeEvidenceBudget } from './kit/nativeEvidence.js'

vi.mock('node:perf_hooks', async original => ({ ...await original<object>(), performance: { now: () => 0 } }))
vi.mock('node:fs', async original => {
  const actual = await original<typeof import('node:fs')>()
  return { ...actual, openSync: vi.fn(actual.openSync), readSync: vi.fn(actual.readSync), closeSync: vi.fn(actual.closeSync),
    opendirSync: vi.fn(actual.opendirSync), lstatSync: vi.fn(actual.lstatSync) }
})
let root: string, home: string, file: string, actual: typeof fs, bindings: typeof import('./transcriptBindings.js')
const A = 'aaaaaaaa-1111-4111-8111-aaaaaaaaaaaa', B = 'bbbbbbbb-2222-4222-8222-bbbbbbbbbbbb'
const record = (id = A, source: unknown = 'cli') => JSON.stringify({ type: 'session_meta', payload: { id, cwd: root, source } }) + '\n'
function write(path: string, text = record()): void { fs.mkdirSync(dirname(path), { recursive: true }); fs.writeFileSync(path, text, { mode: 0o600 }) }
const proof = () => bindings.savedTranscriptEvidence('codex', A, file)
beforeEach(async () => {
  actual = await vi.importActual<typeof fs>('node:fs')
  vi.mocked(fs.openSync).mockReset().mockImplementation(actual.openSync)
  vi.mocked(fs.readSync).mockReset().mockImplementation(actual.readSync)
  vi.mocked(fs.closeSync).mockReset().mockImplementation(actual.closeSync)
  vi.mocked(fs.opendirSync).mockReset().mockImplementation(actual.opendirSync)
  vi.mocked(fs.lstatSync).mockReset().mockImplementation(actual.lstatSync)
  root = fs.realpathSync(fs.mkdtempSync(join(tmpdir(), 'binding-transcript-')))
  home = join(root, 'codex'); file = join(home, 'sessions', 'day', `rollout-${A}.jsonl`)
  vi.stubEnv('ADAPTER_DATA_DIR', join(root, 'data')); vi.stubEnv('CODEX_HOME', home)
  vi.stubEnv('CLAUDE_PROJECTS_DIR', join(root, 'claude', 'projects'))
  vi.stubEnv('COMMANDCODE_HOME', join(root, 'commandcode')); vi.stubEnv('GROK_HOME', join(root, 'grok'))
  vi.stubEnv('AGY_HOME', join(root, 'agy')); vi.stubEnv('COPILOT_HOME', join(root, 'copilot'))
  write(join(root, 'data', 'engine-homes.json'), '{}'); write(file)
  vi.resetModules(); bindings = await import('./transcriptBindings.js')
})
afterEach(() => { vi.restoreAllMocks(); vi.unstubAllEnvs(); fs.rmSync(root, { recursive: true, force: true }) })

it('verifies an owned exact binding and follows a canonical alias', () => {
  const alias = join(home, 'sessions', 'alias.jsonl'); fs.symlinkSync(file, alias)
  for (const path of [file, alias]) {
    const result = bindings.savedTranscriptEvidence('codex', A, path)
    expect(result.path).toBe(path); expect(() => result.verify()).not.toThrow()
  }
})
it('holds a fresh malformed catalog, but an explicit profile remains independent', () => {
  const old = proof()
  fs.writeFileSync(join(root, 'data', 'engine-homes.json'), '{')
  expect(proof).toThrow('catalog')
  expect(() => old.verify()).toThrow('catalog')
  const explicit = bindings.savedTranscriptEvidence('codex', A, file, home)
  expect(explicit.path).toBe(file); expect(() => explicit.verify()).not.toThrow()
  fs.writeFileSync(join(root, 'data', 'engine-homes.json'), '{}')
  expect(proof().path).toBe(file)
})
it('never uses a now-omitted moved home as permission to release its binding', () => {
  fs.writeFileSync(join(root, 'data', 'engine-homes.json'), JSON.stringify({ codex: [join(root, 'moved')] }))
  proof().verify()
  fs.writeFileSync(join(root, 'data', 'engine-homes.json'), '{}')
  expect(proof).toThrow('omits')
})
it('distinguishes a proven outside or absent file from an unreadable file', () => {
  const outside = join(root, 'elsewhere.jsonl'); write(outside)
  for (const path of [outside, join(home, 'sessions', 'absent.jsonl')]) {
    const result = bindings.transcriptEvidence('codex', path)
    expect(result.valid).toBe(false); expect(() => result.verify()).not.toThrow()
  }
  vi.mocked(fs.openSync).mockImplementation(((path: fs.PathLike, ...args: unknown[]) => {
    if (String(path) === file) throw Object.assign(new Error('fixture denied'), { code: 'EACCES' })
    return Reflect.apply(actual.openSync, actual, [path, ...args])
  }) as typeof fs.openSync)
  expect(proof).toThrow('binding file could not be read')
})
it('keeps an absent announced file fenced to its existing parent and root', () => {
  const path = join(home, 'sessions', 'day', 'announced.jsonl')
  const result = bindings.transcriptEvidence('codex', path, undefined, true)
  expect(result.valid).toBe(true); result.verify()
  write(path)
  expect(() => result.verify()).toThrow('changed')
})
it('requires an owned announced parent and retains its ownership until publication', () => {
  const path = join(dirname(file), 'announced.jsonl')
  const result = bindings.transcriptEvidence('codex', path, undefined, true)
  vi.mocked(fs.lstatSync).mockImplementation(((path: fs.PathLike, ...args: unknown[]) => {
    const stat = Reflect.apply(actual.lstatSync, actual, [path, ...args])
    return String(path) === dirname(file) ? Object.assign(stat, { uid: stat.uid + 1n }) : stat
  }) as typeof fs.lstatSync)
  expect(() => result.verify()).toThrow('changed')
  expect(() => bindings.transcriptEvidence('codex', path, undefined, true)).toThrow('owner')
})
it('does not authorize a dangling leaf alias through its original parent', () => {
  const path = join(dirname(file), 'announced.jsonl')
  fs.symlinkSync(join(root, 'outside-absent.jsonl'), path)
  expect(() => bindings.transcriptEvidence('codex', path, undefined, true)).toThrow('absent leaf')
})
it.each([
  ['commandcode', 'commandcode/projects/project/session.jsonl'],
  ['grok', 'grok/sessions/project/session/updates.jsonl'],
  ['agy', 'agy/brain/session/transcript.jsonl'],
  ['copilot', 'copilot/session-state/session/events.jsonl'],
] as const)('fences the unwritten %s derived locator before its root exists', (engine, suffix) => {
  const path = join(root, suffix)
  expect(bindings.transcriptEvidence(engine, path).valid).toBe(false)
  const result = bindings.transcriptEvidence(engine, path, undefined, 'derived')
  expect(result.valid).toBe(true); result.verify()
  fs.mkdirSync(dirname(path), { recursive: true })
  expect(() => result.verify()).toThrow('changed')
  const parentOnly = bindings.transcriptEvidence(engine, path, undefined, 'derived')
  expect(parentOnly.valid).toBe(true); parentOnly.verify()
  write(path, '')
  expect(() => parentOnly.verify()).toThrow('changed')
  expect(bindings.transcriptEvidence(engine, path).valid).toBe(true)
})
it('does not let an unwritten locator borrow a dangling directory or leaf alias', () => {
  const base = join(root, 'commandcode', 'projects')
  fs.mkdirSync(base, { recursive: true })
  for (const [path, link] of [[join(base, 'project', 'session.jsonl'), join(base, 'project')],
    [join(base, 'session.jsonl'), join(base, 'session.jsonl')]]) {
    fs.symlinkSync(join(root, 'outside-absent'), link)
    expect(() => bindings.transcriptEvidence('commandcode', path, undefined, 'derived')).toThrow('absent leaf')
    fs.rmSync(link)
  }
})
it('requires owned surviving ancestry and keeps a derived locator inside its declared root', () => {
  const path = join(root, 'commandcode', 'projects', 'project', 'session.jsonl')
  const result = bindings.transcriptEvidence('commandcode', path, undefined, 'derived')
  vi.mocked(fs.lstatSync).mockImplementation(((at: fs.PathLike, ...args: unknown[]) => {
    const info = Reflect.apply(actual.lstatSync, actual, [at, ...args])
    return String(at) === root ? Object.assign(info, { uid: info.uid + 1n }) : info
  }) as typeof fs.lstatSync)
  expect(() => result.verify()).toThrow('changed')
  expect(() => bindings.transcriptEvidence('commandcode', path, undefined, 'derived')).toThrow('owner')
  vi.mocked(fs.lstatSync).mockImplementation(actual.lstatSync)
  expect(bindings.transcriptEvidence('commandcode', join(root, 'outside', 'session.jsonl'), undefined, 'derived').valid).toBe(false)
})
it('does not treat an existing unreadable derived transcript as an unwritten locator', () => {
  const path = join(root, 'commandcode', 'projects', 'project', 'session.jsonl')
  write(path, '')
  vi.mocked(fs.openSync).mockImplementation(((at: fs.PathLike, ...args: unknown[]) => {
    if (String(at) === path) throw Object.assign(new Error('fixture denied'), { code: 'EACCES' })
    return Reflect.apply(actual.openSync, actual, [at, ...args])
  }) as typeof fs.openSync)
  expect(() => bindings.transcriptEvidence('commandcode', path, undefined, 'derived')).toThrow('could not be read')
})
it.each(['', '{', record().slice(0, -4), ' '.repeat(128 * 1024) + record(), record(A, { future: 'unknown' })])('holds an incomplete or unknown native header', text => {
  fs.writeFileSync(file, text)
  expect(proof).toThrow()
})
it('holds invalid UTF-8 in metadata but does not decode a truncated body after its complete line', () => {
  fs.writeFileSync(file, Buffer.from([123, 255, 125]))
  expect(proof).toThrow('UTF-8')
  fs.writeFileSync(file, Buffer.concat([Buffer.from(record()), Buffer.from([255])]))
  expect(proof().path).toBe(file)
})
it('finishes short reads and bounds a non-progressing or excessive read sequence', () => {
  vi.mocked(fs.readSync).mockImplementation(((fd: number, bytes: Buffer, offset: number, length: number, position: number) =>
    actual.readSync(fd, bytes, offset, Math.min(length, 7), position)) as typeof fs.readSync)
  expect(proof().path).toBe(file)
  vi.mocked(fs.readSync).mockReturnValue(0)
  expect(proof).toThrow('ended')
  vi.mocked(fs.readSync).mockImplementation(((fd: number, bytes: Buffer, offset: number, _length: number, position: number) =>
    actual.readSync(fd, bytes, offset, 1, position)) as typeof fs.readSync)
  expect(proof).toThrow('read-operation limit')
})
it('binds the opened descriptor even if a pathname is swapped and restored before the open returns', () => {
  const foreign = join(root, 'foreign.jsonl'); write(foreign, record(B))
  vi.mocked(fs.openSync).mockImplementation(((path: fs.PathLike, ...args: unknown[]) =>
    Reflect.apply(actual.openSync, actual, [String(path) === file ? foreign : path, ...args])) as typeof fs.openSync)
  expect(proof).toThrow('unconfirmed identity')
})
it('preserves a complete header across body appends and holds a changed header at commit', () => {
  const first = proof(); fs.appendFileSync(file, '{"body":"new turn"}\n'); first.verify()
  const next = proof(); fs.writeFileSync(file, record(B))
  expect(() => next.verify()).toThrow('header changed')
})
it('does not let a repeated header read replace the earlier evidence in one operation', async () => {
  const { sessionStoreOf } = await import('./sessionStoreContracts.js')
  const files = new NativeFiles(), first = sessionStoreOf('codex')!.first!
  files.header(file, first); fs.writeFileSync(file, record(B))
  expect(() => files.header(file, first)).toThrow('header changed')
})
it('retains path ancestry across a replacement that keeps the same file inode', () => {
  const read = proof(), replacement = join(root, 'replacement')
  fs.mkdirSync(replacement); fs.linkSync(file, join(replacement, `rollout-${A}.jsonl`))
  fs.renameSync(dirname(file), join(root, 'original')); fs.renameSync(replacement, dirname(file))
  expect(() => read.verify()).toThrow('path or alias changed')
})

function child(): string {
  const path = join(home, 'sessions', 'child', `rollout-${B}.jsonl`)
  write(path, record(B, { subagent: { thread_spawn: { parent_thread_id: A, depth: 1 } } }))
  return path
}
it('repairs a child overwrite only after proving the whole parent pool', () => {
  const path = child(), held = bindings.savedTranscriptEvidence('codex', A, path)
  expect(held.path).toBe(file); held.verify()
  const competitor = join(home, 'sessions', 'later', `rollout-${A}.jsonl`)
  write(competitor)
  expect(() => held.verify()).toThrow('directory pool changed')
  expect(() => bindings.savedTranscriptEvidence('codex', A, path)).toThrow('more than one')
})
it.each(['file', 'directory'])('does not repair through an outside %s alias', kind => {
  const path = child(), outside = join(root, 'outside')
  fs.mkdirSync(outside); fs.renameSync(file, join(outside, `rollout-${A}.jsonl`))
  if (kind === 'file') fs.symlinkSync(join(outside, `rollout-${A}.jsonl`), file)
  else fs.symlinkSync(outside, join(home, 'sessions', 'linked'))
  expect(() => bindings.savedTranscriptEvidence('codex', A, path)).toThrow('escaped')
})
it('holds an escaped directory before reading even its empty candidate pool', () => {
  const path = child(), outside = join(root, 'empty-outside')
  fs.mkdirSync(outside); fs.symlinkSync(outside, join(home, 'sessions', 'linked'))
  expect(() => bindings.savedTranscriptEvidence('codex', A, path)).toThrow('directory escaped')
})
it('retains absent and present roots in an explicit operation scope', () => {
  const moved = join(root, 'moved'), sessions = join(moved, 'sessions')
  fs.writeFileSync(join(root, 'data', 'engine-homes.json'), JSON.stringify({ codex: [moved] }))
  const scope = bindings.transcriptRootEvidence('codex')
  const result = bindings.savedTranscriptEvidence('codex', A, file, undefined, undefined, scope)
  result.verify(); scope.verify()
  fs.mkdirSync(sessions, { recursive: true })
  expect(() => scope.verify()).toThrow('changed')
})
it('retains an unreadable competing directory even after the parent was found', () => {
  const path = child(), blocked = join(home, 'sessions', 'blocked'); fs.mkdirSync(blocked)
  vi.mocked(fs.opendirSync).mockImplementation(((path: fs.PathLike, ...args: unknown[]) => {
    if (String(path) === blocked) throw Object.assign(new Error('fixture denied'), { code: 'EACCES' })
    return Reflect.apply(actual.opendirSync, actual, [path, ...args])
  }) as typeof fs.opendirSync)
  expect(() => bindings.savedTranscriptEvidence('codex', A, path)).toThrow('could not be read completely')
})
it('does not infer an empty directory from an iterator acquired during an ancestor round trip', () => {
  const path = child(), sessions = join(home, 'sessions'), elsewhere = join(root, 'empty')
  fs.mkdirSync(elsewhere)
  // Every look makes its own round trip, so the route never holds still.
  let trips = 0
  vi.mocked(fs.opendirSync).mockImplementation(((path: fs.PathLike, ...args: unknown[]) => {
    if (String(path) !== sessions) return Reflect.apply(actual.opendirSync, actual, [path, ...args])
    fs.renameSync(home, home + '-aside'); fs.mkdirSync(home); fs.mkdirSync(sessions)
    const result = Reflect.apply(actual.opendirSync, actual, [sessions, ...args])
    fs.renameSync(home, `${home}-temporary-${++trips}`); fs.renameSync(home + '-aside', home)
    return result
  }) as typeof fs.opendirSync)
  expect(() => bindings.savedTranscriptEvidence('codex', A, path)).toThrow('ancestor changed')
})
it('holds pool overflow, expired work and failed descriptor close', () => {
  const directory = join(root, 'wide'); fs.mkdirSync(directory)
  for (let index = 0; index < 4097; index++) fs.writeFileSync(join(directory, String(index)), '')
  expect(() => new NativeFiles().entries(directory)).toThrow('entry limit')
  expect(() => new NativeFiles(new NativeEvidenceBudget(-1)).file(file)).toThrow('deadline')
  vi.mocked(fs.closeSync).mockImplementation(fd => { actual.closeSync(fd); throw new Error('fixture close failed') })
  expect(() => new NativeFiles().file(file)).toThrow('could not be closed')
}, 30_000)