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.

14.3 KB
Raw Blame
import * as fs from 'node:fs'
import * as asyncFs from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { dirname, join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { readHomeCatalog } from './homeCatalog.js'
import { NATIVE_EVIDENCE_MS } from './nativeEvidence.js'

const clock = vi.hoisted(() => ({ now: 0 }))
vi.mock('node:perf_hooks', async original => ({ ...await original<object>(), performance: { now: () => clock.now } }))
vi.mock('node:fs', async original => {
  const actual = await original<typeof import('node:fs')>()
  return { ...actual, lstatSync: vi.fn(actual.lstatSync), openSync: vi.fn(actual.openSync),
    readSync: vi.fn(actual.readSync), fstatSync: vi.fn(actual.fstatSync), closeSync: vi.fn(actual.closeSync), linkSync: vi.fn(actual.linkSync) }
})
vi.mock('node:fs/promises', async original => {
  const actual = await original<typeof import('node:fs/promises')>()
  return { ...actual, opendir: vi.fn(actual.opendir) }
})
vi.mock('../../lib/loginShellEnv.js', () => ({ loginShellEnvironment: () => ({}) }))
let actual: typeof fs, root = ''
let homes: typeof import('../../lib/engineHomes.js')
let repair: typeof import('../../lib/sessionRepair.js')
const path = (...parts: string[]) => join(root, ...parts)
const catalog = () => path('data', 'engine-homes.json')
const ID = 'aaaaaaaa-1111-4222-8333-444444444444'
function write(text: unknown): void {
  fs.mkdirSync(dirname(catalog()), { recursive: true })
  fs.writeFileSync(catalog(), typeof text === 'string' ? text : JSON.stringify(text), { mode: 0o600 })
}
function transcript(home: string): string {
  const file = join(home, 'sessions', 'day', `rollout-${ID}.jsonl`)
  fs.mkdirSync(dirname(file), { recursive: true })
  fs.writeFileSync(file, JSON.stringify({ type: 'session_meta', payload: { id: ID, cwd: path('work'), source: 'cli' } }) + '\n')
  return file
}
beforeEach(async () => {
  actual = await vi.importActual<typeof fs>('node:fs')
  vi.mocked(asyncFs.opendir).mockReset().mockImplementation((await vi.importActual<typeof asyncFs>('node:fs/promises')).opendir)
  for (const name of ['lstatSync', 'openSync', 'readSync', 'fstatSync', 'closeSync', 'linkSync'] as const) {
    vi.mocked(fs[name]).mockReset().mockImplementation(actual[name] as never)
  }
  clock.now = 0
  root = actual.realpathSync(fs.mkdtempSync(join(tmpdir(), 'home-catalog-')))
  for (const [name, value] of Object.entries({ HOME: path('home'), ADAPTER_DATA_DIR: path('data'),
    ADAPTER_RUNTIME_DIR: path('runtime'), CODEX_HOME: path('codex'), CLAUDE_PROJECTS_DIR: path('claude', 'projects') })) vi.stubEnv(name, value)
  vi.resetModules()
  homes = await import('../../lib/engineHomes.js')
  repair = await import('../../lib/sessionRepair.js')
})
afterEach(() => {
  homes.resetEngineHomes(); vi.restoreAllMocks(); vi.unstubAllEnvs()
  actual.rmSync(root, { recursive: true, force: true })
})

describe('fresh complete native home evidence', () => {
  it('reads a new installation and bypasses catalog evidence for explicit profiles and other engines', () => {
    expect(homes.nativeSessionRoots('codex')).toEqual([path('codex', 'sessions')])
    write('{ incomplete')
    expect(homes.nativeSessionRoots('codex', path('profile'))).toEqual([path('profile', 'sessions')])
    expect(homes.nativeSessionRoots('pi')).toEqual([])
    expect(homes.nativeSessionRoots('toString')).toEqual([])
    expect(() => homes.nativeSessionRoots('claude', path('profile'))).toThrow(/catalog/)
  })

  it('reads each complete list fresh, deduplicates only equal paths and returns independent arrays', () => {
    write({ claude: [path('c'), path('c')], codex: [path('a')] })
    expect(homes.nativeSessionRoots('claude')).toEqual([path('claude', 'projects'), path('c', 'projects')])
    const first = homes.nativeSessionRoots('codex'); first.push('/not-evidence')
    write({ claude: [path('c')], codex: [path('a'), path('b')] })
    expect(homes.nativeSessionRoots('codex')).toEqual([path('codex', 'sessions'), path('a', 'sessions'), path('b', 'sessions')])
  })

  it('does not reuse the legacy inode/mtime/size stamp when a competitor is added', async () => {
    const own = transcript(path('codex')); transcript(path('moved'))
    const text = JSON.stringify({ codex: [path('moved')] })
    write('{"codex":[]}'.padEnd(text.length, ' '))
    const before = actual.statSync(catalog())
    // Pin a representable timestamp before priming the old stamp cache.
    actual.utimesSync(catalog(), before.atime, new Date('2026-10-09T00:00:00Z'))
    expect(homes.movedHomes('codex')).toEqual([])
    await expect(repair.findResumedTranscript('codex', ID)).resolves.toBe(own)
    write(text); actual.utimesSync(catalog(), before.atime, new Date('2026-10-09T00:00:00Z'))
    expect(homes.movedHomes('codex')).toEqual([path('moved')]) // The durable catalog reader now refreshes legacy callers too.
    await expect(repair.findResumedTranscript('codex', ID)).rejects.toThrow('more than one transcript')
  })

  it.each(['{', '[]', 'null', '{"codex":42}', '{"claude":["relative"]}', '{"codex":[null]}',
    '{"future":["/home"]}', '{"codex":["/bad\\u0000path"]}', '{"codex":["/competitor"],"codex":[]}',
    '{"co\\u0064ex":["/competitor"],"codex":[]}'])('holds malformed evidence without rewriting it: %s', text => {
    write(text)
    expect(() => homes.nativeSessionRoots('codex')).toThrow(/saved engine-home catalog/)
    expect(actual.readFileSync(catalog(), 'utf8')).toBe(text)
    write({ codex: [path('recovered')] })
    expect(homes.nativeSessionRoots('codex')).toContain(path('recovered', 'sessions'))
  })

  it.each(['bytes', 'homes', 'path'])('bounds the complete catalog: %s', limit => {
    write(limit === 'bytes' ? '{}'.padEnd(65537, ' ') : { codex: limit === 'homes'
      ? Array.from({ length: 64 }, (_, n) => path(String(n))) : ['/' + 'x'.repeat(4096)] })
    expect(() => readHomeCatalog(catalog())).toThrow(/limit|oversized|invalid home/)
    expect(() => homes.nativeSessionRoots('codex')).toThrow(/limit|oversized|invalid home/)
    if (limit === 'bytes') expect(fs.openSync).not.toHaveBeenCalled()
  })

  it('bounds the raw list before deduplicating repeated homes', () => {
    write({ codex: Array.from({ length: 64 }, () => path('same')) })
    expect(() => readHomeCatalog(catalog())).toThrow('known session-home limit')
  })

  it('holds a catalog that disappears or drops a previously observed home, then recovers', () => {
    write({ codex: [path('a')] }); homes.nativeSessionRoots('codex')
    actual.unlinkSync(catalog())
    expect(() => homes.nativeSessionRoots('codex')).toThrow('previously observed or unsaved home')
    write({ codex: [path('b')] })
    expect(() => homes.nativeSessionRoots('codex')).toThrow('previously observed or unsaved home')
    write({ codex: [path('a'), path('b')] })
    expect(homes.nativeSessionRoots('codex')).toHaveLength(3)
  })

  it('retains a competing home observed by a valid held read across A -> B -> A recovery', async () => {
    const own = transcript(path('codex')); transcript(path('b'))
    write({ codex: [path('a')] })
    await expect(repair.findResumedTranscript('codex', ID)).resolves.toBe(own)
    write({ codex: [path('b')] })
    await expect(repair.findResumedTranscript('codex', ID)).rejects.toThrow('previously observed or unsaved home')
    write({ codex: [path('a')] })
    await expect(repair.findResumedTranscript('codex', ID)).rejects.toThrow('previously observed or unsaved home')
    write({ codex: [path('a'), path('b')] })
    await expect(repair.findResumedTranscript('codex', ID)).rejects.toThrow('more than one transcript')
  })

  it('retains a bounded overflow fact when successive valid catalogs reveal too many homes', () => {
    const first = Array.from({ length: 63 }, (_, n) => path(`observed-${n}`))
    write({ codex: first }); expect(homes.nativeSessionRoots('codex')).toHaveLength(64)
    write({ codex: [path('one-more')] })
    expect(() => homes.nativeSessionRoots('codex')).toThrow('known session-home limit')
    write({ codex: first })
    expect(() => homes.nativeSessionRoots('codex')).toThrow('known session-home limit')
  })

  it('holds an oversized legacy list before copying or iterating it', () => {
    const legacy = Array.from({ length: 64 }, (_, n) => path(`legacy-${n}`))
    write({ codex: legacy }); homes.movedHomes('codex')
    write({ codex: [] })
    let visited = false
    const iterator = Array.prototype[Symbol.iterator]
    Array.prototype[Symbol.iterator] = function (this: unknown[]) {
      if (this.length === 64 && this[0] === legacy[0]) {
        visited = true
        throw new Error('oversized legacy list must not be visited')
      }
      return iterator.call(this)
    }
    try {
      expect(() => homes.nativeSessionRoots('codex')).toThrow('known session-home limit')
      expect(visited).toBe(false)
    } finally { Array.prototype[Symbol.iterator] = iterator }
  })

  it('does not exclude a pending competitor after durable adoption failed to persist', async () => {
    transcript(path('codex')); transcript(path('unsaved'))
    write({ codex: [] })
    vi.mocked(fs.linkSync).mockImplementation(() => { throw new Error('fixture disk unavailable') })
    expect(() => homes.adoptHomes({ CODEX_HOME: path('unsaved') })).toThrow('durable adoption')
    expect(JSON.parse(actual.readFileSync(catalog(), 'utf8'))).toEqual({ codex: [] })
    await expect(repair.findResumedTranscript('codex', ID)).rejects.toThrow(/incomplete record pool|previously observed or unsaved home/)
    vi.mocked(fs.linkSync).mockImplementation(actual.linkSync)
    homes.confirmHomes({ CODEX_HOME: path('unsaved') })
    await expect(repair.findResumedTranscript('codex', ID)).rejects.toThrow('more than one transcript')
  })

  it('keeps the typed hold when the catalog becomes unreadable during exact lookup', async () => {
    write({ codex: [] }); transcript(path('codex'))
    const native = await vi.importActual<typeof asyncFs>('node:fs/promises')
    vi.mocked(asyncFs.opendir).mockImplementationOnce(async (name, options) => {
      const directory = await native.opendir(name, options)
      write('{')
      return directory
    })
    await expect(repair.findResumedTranscript('codex', ID)).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
    write({ codex: [] })
    await expect(repair.findResumedTranscript('codex', ID)).resolves.toBe(transcript(path('codex')))
  })

  it.each(['directory', 'symlink', 'dangling parent', 'write permission'])('holds unsafe native file evidence: %s', kind => {
    fs.mkdirSync(path('data'))
    if (kind === 'directory') fs.mkdirSync(catalog())
    else if (kind === 'symlink') { fs.writeFileSync(path('target'), '{}'); fs.symlinkSync(path('target'), catalog()) }
    else if (kind === 'dangling parent') { fs.rmdirSync(path('data')); fs.symlinkSync(path('missing'), path('data')) }
    else { write({}); fs.chmodSync(catalog(), 0o666) }
    expect(() => homes.nativeSessionRoots('codex')).toThrow(/catalog/)
  })

  it.each(['inspect', 'open', 'read'])('holds %s errors and succeeds on the next fresh read', stage => {
    write({ codex: [path('a')] })
    const method = stage === 'inspect' ? 'lstatSync' : stage === 'open' ? 'openSync' : 'readSync'
    vi.mocked(fs[method]).mockImplementationOnce(() => { throw Object.assign(new Error('denied'), { code: 'EACCES' }) })
    expect(() => homes.nativeSessionRoots('codex')).toThrow(/catalog/)
    expect(homes.nativeSessionRoots('codex')).toContain(path('a', 'sessions'))
  })

  it('handles short reads without accepting a prefix and closes every opened descriptor', () => {
    write({ codex: [path('a')] })
    vi.mocked(fs.readSync).mockImplementation((fd, buffer, options = {}) =>
      actual.readSync(fd, buffer, { ...options, length: Math.min(options.length ?? buffer.byteLength, 3) }))
    expect(readHomeCatalog(catalog()).homes.codex).toEqual([path('a')])
    expect(fs.closeSync).toHaveBeenCalledTimes(1)
    vi.mocked(fs.readSync).mockReturnValueOnce(0)
    expect(() => readHomeCatalog(catalog())).toThrow('ended during its read')
    expect(fs.closeSync).toHaveBeenCalledTimes(2)
  })

  it.each(['operations', 'deadline'])('bounds an unfinished read by %s', limit => {
    write({ codex: [path('a'.repeat(200))] })
    vi.mocked(fs.readSync).mockImplementation((fd, buffer, options = {}) => {
      if (limit === 'deadline') clock.now = NATIVE_EVIDENCE_MS + 1
      return actual.readSync(fd, buffer, limit === 'deadline' ? options : { ...options, length: 1 })
    })
    expect(() => readHomeCatalog(catalog())).toThrow(limit === 'deadline' ? 'read deadline' : 'read-operation limit')
    expect(fs.closeSync).toHaveBeenCalledTimes(1)
  })

  it.each(['append', 'rename', 'ancestor replacement'])('rejects a catalog changed by %s during its descriptor read', kind => {
    write({ codex: [path('a')] })
    vi.mocked(fs.readSync).mockImplementationOnce((fd, buffer, options) => {
      const count = actual.readSync(fd, buffer, options)
      if (kind === 'append') actual.appendFileSync(catalog(), ' ')
      else if (kind === 'rename') { actual.writeFileSync(path('replacement'), '{}'); actual.renameSync(path('replacement'), catalog()) }
      else {
        // Moving the ordinary parent preserves the opened file's inode/ctime. Only the
        // pathname fence can notice that a different catalog now occupies its old path.
        actual.renameSync(path('data'), path('saved-data')); write({})
      }
      return count
    })
    expect(() => readHomeCatalog(catalog())).toThrow('changed during its read')
    expect(fs.closeSync).toHaveBeenCalledTimes(1)
  })

  it('ties an opened descriptor to the inspected inode even when the pathname returns before fstat', () => {
    write({ codex: [path('a')] }); actual.writeFileSync(path('other'), '{}', { mode: 0o600 })
    vi.mocked(fs.openSync).mockImplementationOnce((name, flags) => {
      actual.renameSync(catalog(), path('original')); actual.renameSync(path('other'), catalog())
      const fd = actual.openSync(name, flags)
      actual.renameSync(catalog(), path('other')); actual.renameSync(path('original'), catalog())
      return fd
    })
    expect(() => readHomeCatalog(catalog())).toThrow('changed before it could be opened')
    expect(fs.closeSync).toHaveBeenCalledTimes(1)
  })

  it('rejects invalid UTF-8 instead of turning replacement characters into a native home', () => {
    fs.mkdirSync(path('data'))
    actual.writeFileSync(catalog(), Buffer.concat([Buffer.from('{"codex":["/'), Buffer.from([0xff]), Buffer.from('"]}')]), { mode: 0o600 })
    expect(() => readHomeCatalog(catalog())).toThrow('could not be read completely')
  })
})