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.

17.7 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { spawn, spawnSync } from 'node:child_process'
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs'
import { tmpdir } from 'os'
import { join } from 'path'
import { processStartMarker } from './processLiveness.js'

let dataDir = ''

async function loadLock() {
  vi.resetModules()
  process.env.ADAPTER_DATA_DIR = dataDir
  return import('./daemonSpawnLock.js')
}

const lockDir = () => join(dataDir, 'adapter.spawn.lock')
const ownerFile = () => join(lockDir(), 'owner.json')

/** A real process that stays alive until killed — a lock owner whose liveness is not faked. */
function sleeper(): ReturnType<typeof spawn> {
  return spawn(process.execPath, ['-e', 'setTimeout(() => {}, 100000)'], { stdio: 'ignore' })
}

const waitFor = async (predicate: () => boolean, ms = 3000): Promise<void> => {
  const deadline = Date.now() + ms
  while (!predicate()) {
    if (Date.now() > deadline) throw new Error('condition not met in time')
    await new Promise((r) => setTimeout(r, 20))
  }
}

describe('daemon spawn lock', () => {
  beforeEach(() => {
    dataDir = mkdtempSync(join(tmpdir(), 'adapter-spawn-lock-'))
  })

  afterEach(() => {
    rmSync(dataDir, { recursive: true, force: true })
    delete process.env.ADAPTER_DATA_DIR
  })

  it('acquires, records this process as the owner, and releases', async () => {
    const lock = await loadLock()
    const release = await lock.acquireSpawnLock('start')
    expect(existsSync(ownerFile())).toBe(true)
    const owner = lock.readSpawnLockOwner()
    expect(owner?.pid).toBe(process.pid)
    expect(owner?.purpose).toBe('start')
    release()
    expect(existsSync(lockDir())).toBe(false)
    expect(lock.readSpawnLockOwner()).toBeNull()
  })

  it('is re-entrant within one process and drops the lock only with the outermost release', async () => {
    const lock = await loadLock()
    const outer = await lock.acquireSpawnLock('update')
    const inner = await lock.acquireSpawnLock('start') // update → launch
    expect(lock.readSpawnLockOwner()?.purpose).toBe('update') // the outer section's identity holds
    inner()
    expect(existsSync(lockDir())).toBe(true)
    outer()
    expect(existsSync(lockDir())).toBe(false)
  })

  it('withSpawnLock releases on a throw', async () => {
    const lock = await loadLock()
    await expect(lock.withSpawnLock('handoff', async () => { throw new Error('boom') })).rejects.toThrow('boom')
    expect(existsSync(lockDir())).toBe(false)
  })

  it('waits for a live holder and reports it once, then acquires when it lets go', async () => {
    const lock = await loadLock()
    const holder = sleeper()
    await waitFor(() => !!holder.pid)
    mkdirSync(lockDir(), { mode: 0o700 })
    writeFileSync(ownerFile(), JSON.stringify({
      pid: holder.pid, startMarker: '', token: 'held-by-child', purpose: 'handoff', since: Date.now(),
    }), { mode: 0o600 })

    const waiting: unknown[] = []
    const acquired = lock.acquireSpawnLock('start', { waitMs: 5000, onWaiting: (o) => waiting.push(o) })
    // Generous: every poll reads the holder's start marker through `ps`, which a loaded box can
    // take a good fraction of a second over.
    await waitFor(() => waiting.length > 0, 2000)
    expect(waiting).toHaveLength(1)
    expect((waiting[0] as { pid: number }).pid).toBe(holder.pid)
    expect(readFileSync(ownerFile(), 'utf8')).toContain('held-by-child') // still theirs

    holder.kill('SIGKILL')
    const release = await acquired
    expect(lock.readSpawnLockOwner()?.pid).toBe(process.pid)
    release()
  })

  it('gives up with SpawnLockBusyError carrying the owner when the holder outlives the wait', async () => {
    const lock = await loadLock()
    const holder = sleeper()
    await waitFor(() => !!holder.pid)
    mkdirSync(lockDir(), { mode: 0o700 })
    writeFileSync(ownerFile(), JSON.stringify({
      pid: holder.pid, startMarker: '', token: 't', purpose: 'update', since: Date.now(),
    }), { mode: 0o600 })
    try {
      await expect(lock.acquireSpawnLock('start', { waitMs: 300 })).rejects.toMatchObject({
        name: 'SpawnLockBusyError',
        owner: { pid: holder.pid, purpose: 'update' },
      })
      expect(existsSync(ownerFile())).toBe(true)
    } finally {
      holder.kill('SIGKILL')
    }
  })

  it('takes the lock synchronously for a caller that cannot wait on its event loop, re-entrant, and null while a live holder keeps it', async () => {
    const lock = await loadLock()
    const release = lock.tryAcquireSpawnLockSync('update', 100)
    expect(release).not.toBeNull()
    expect(lock.readSpawnLockOwner()).toMatchObject({ pid: process.pid, purpose: 'update' })
    // Inside another section of this process: a nested handle.
    const nested = lock.tryAcquireSpawnLockSync('update', 100)
    nested!()
    expect(existsSync(lockDir())).toBe(true)
    release!()
    expect(existsSync(lockDir())).toBe(false)

    const holder = sleeper()
    await waitFor(() => !!holder.pid)
    mkdirSync(lockDir(), { mode: 0o700 })
    writeFileSync(ownerFile(), JSON.stringify({ pid: holder.pid, startMarker: '', token: 't', purpose: 'start', since: Date.now() }), { mode: 0o600 })
    try {
      const started = Date.now()
      expect(lock.tryAcquireSpawnLockSync('update', 300)).toBeNull()
      expect(Date.now() - started).toBeGreaterThanOrEqual(250)
      expect(readFileSync(ownerFile(), 'utf8')).toContain('"token":"t"')
    } finally {
      holder.kill('SIGKILL')
    }
    // A dead holder's lock is reclaimed, as the asynchronous wait reclaims it.
    await waitFor(() => holder.exitCode !== null || holder.signalCode !== null)
    const reclaimed = lock.tryAcquireSpawnLockSync('update', 1000)
    expect(lock.readSpawnLockOwner()?.pid).toBe(process.pid)
    reclaimed!()
    // Something that is not a lock: null at once.
    writeFileSync(lockDir(), 'a file')
    expect(lock.tryAcquireSpawnLockSync('update', 1000)).toBeNull()
  })

  it('reclaims a lock whose owner is dead', async () => {
    const lock = await loadLock()
    const dead = spawnSync(process.execPath, ['-e', 'process.exit(0)'])
    expect(dead.status).toBe(0)
    mkdirSync(lockDir(), { mode: 0o700 })
    writeFileSync(ownerFile(), JSON.stringify({
      pid: 999_999_999, startMarker: '', token: 'stale', purpose: 'start', since: Date.now() - 60_000,
    }), { mode: 0o600 })
    const release = await lock.acquireSpawnLock('start', { waitMs: 1000 })
    expect(lock.readSpawnLockOwner()?.pid).toBe(process.pid)
    release()
  })

  it('reclaims a lock whose pid has been reused by another process generation', async () => {
    const lock = await loadLock()
    mkdirSync(lockDir(), { mode: 0o700 })
    writeFileSync(ownerFile(), JSON.stringify({
      pid: process.pid, startMarker: '', generationMarker: `${processStartMarker(process.pid)}-earlier`, token: 'stale', purpose: 'start', since: Date.now(),
    }), { mode: 0o600 })
    const release = await lock.acquireSpawnLock('start', { waitMs: 1000 })
    expect(lock.readSpawnLockOwner()?.token).not.toBe('stale')
    release()
  })

  it('reclaims an ownerless directory once it is clearly debris, not one being created', async () => {
    const lock = await loadLock()
    mkdirSync(lockDir(), { mode: 0o700 })
    // Fresh and ownerless: someone is between mkdir and the O_EXCL write — do not touch it yet.
    await expect(lock.acquireSpawnLock('start', { waitMs: 250 })).rejects.toMatchObject({ name: 'SpawnLockBusyError', owner: null })
    // Age it past the debris threshold.
    const old = new Date(Date.now() - 10_000)
    const { utimesSync } = await import('fs')
    utimesSync(lockDir(), old, old)
    const release = await lock.acquireSpawnLock('start', { waitMs: 1000 })
    expect(lock.readSpawnLockOwner()?.pid).toBe(process.pid)
    release()
  })

  it('reclaims a lock whose owner record names no one (cut short by a crash or a full disk) once it is debris', async () => {
    const lock = await loadLock()
    mkdirSync(lockDir(), { mode: 0o700 })
    writeFileSync(ownerFile(), '', { mode: 0o600 })
    // Fresh: someone is between the O_EXCL create and the write.
    await expect(lock.acquireSpawnLock('start', { waitMs: 250 })).rejects.toMatchObject({ name: 'SpawnLockBusyError', owner: null })
    const old = new Date(Date.now() - 10_000)
    const { utimesSync } = await import('fs')
    utimesSync(lockDir(), old, old)
    // The record is what was written last: it alone being fresh still means a lock being made.
    await expect(lock.acquireSpawnLock('start', { waitMs: 250 })).rejects.toMatchObject({ name: 'SpawnLockBusyError', owner: null })
    utimesSync(ownerFile(), old, old)
    const release = await lock.acquireSpawnLock('start', { waitMs: 1000 })
    expect(lock.readSpawnLockOwner()?.pid).toBe(process.pid)
    release()
    expect(existsSync(lockDir())).toBe(false)
  })

  it('leaves no lock behind when its owner record cannot be written, so the next taker is not shut out', async () => {
    vi.doMock('fs', async (importOriginal) => {
      const fs = await importOriginal<typeof import('fs')>()
      return {
        ...fs,
        writeFileSync: (...args: Parameters<typeof fs.writeFileSync>) => {
          if (typeof args[0] === 'number') throw Object.assign(new Error('ENOSPC: no space left on device, write'), { code: 'ENOSPC' })
          return fs.writeFileSync(...args)
        },
      }
    })
    try {
      const lock = await loadLock()
      await expect(lock.acquireSpawnLock('update', { waitMs: 250 })).rejects.toMatchObject({ code: 'ENOSPC' })
      expect(existsSync(lockDir())).toBe(false)
    } finally { vi.doUnmock('fs') }
    const lock = await loadLock()
    const release = await lock.acquireSpawnLock('update', { waitMs: 250 })
    expect(lock.readSpawnLockOwner()?.purpose).toBe('update')
    release()
  })

  it('refuses a lock directory with an unsafe mode rather than reading it', async () => {
    const lock = await loadLock()
    mkdirSync(lockDir(), { mode: 0o777 })
    const { chmodSync } = await import('fs')
    chmodSync(lockDir(), 0o777)
    writeFileSync(ownerFile(), JSON.stringify({ pid: 1, startMarker: '', token: 't', purpose: 'start', since: 0 }), { mode: 0o600 })
    expect(() => lock.readSpawnLockOwner()).toThrow(/unsafe/)
  })

  it('gives up AT ONCE, naming the path, when something that is not a lock sits at the lock path', async () => {
    // A plain file — from a stray `touch`, a bad restore, whatever. Waiting 45s would never turn it
    // into a directory, and a stop that could not get past it would be a stop that does not work.
    const lock = await loadLock()
    writeFileSync(lockDir(), 'not a directory')
    const started = Date.now()
    await expect(lock.acquireSpawnLock('start', { waitMs: 45_000 })).rejects.toMatchObject({
      name: 'SpawnLockBusyError',
      owner: null,
      reason: expect.stringContaining('remove it by hand'),
    })
    expect(Date.now() - started).toBeLessThan(2_000)
    expect(lock.describeSpawnLockFailure(new lock.SpawnLockBusyError(null, 'why'))).toBe('why')
  })

  it('tells a person what Harness is still doing, without a pid or a lock in the sentence', async () => {
    // The desktop's sign-in screen shows this verbatim: the technical line is for stderr.
    const lock = await loadLock()
    const busy = (purpose: 'start' | 'update' | 'handoff' | 'stop' | 'login') =>
      new lock.SpawnLockBusyError({ pid: 4242, startMarker: '', token: 't', purpose, since: Date.now() })
    expect(lock.describeSpawnLockBusyPlainly(busy('update'))).toBe('Harness is still updating on this computer. Try again in a moment.')
    expect(lock.describeSpawnLockBusyPlainly(busy('login'))).toBe('Another sign-in is already in progress on this computer. Try again in a moment.')
    for (const purpose of ['start', 'handoff', 'stop'] as const) {
      const said = lock.describeSpawnLockBusyPlainly(busy(purpose))
      expect(said).toMatch(/^Harness is still .* on this computer\. Try again in a moment\.$/)
      expect(said).not.toMatch(/4242|lock|pid/)
    }
    expect(lock.describeSpawnLockBusyPlainly(new lock.SpawnLockBusyError(null))).toBe('Harness is busy on this computer. Try again in a moment.')
    // Not a lock at all is not going to clear itself: no "try again", a terminal instead.
    expect(lock.describeSpawnLockBusyPlainly(new lock.SpawnLockBusyError(null, 'not a lock this CLI made: /x — remove it by hand')))
      .toBe('Harness cannot sign in on this computer right now. Run `harness login --force` in a terminal to see why.')
  })

  it('tells a sign-in that waits on the lock what it waits for, in a person\'s words', async () => {
    // The desktop shows the waiting line verbatim while a sign-in sits behind the lock, so it names
    // what Harness is doing — and, when the holder is another sign-in, says exactly that.
    const lock = await loadLock()
    const owner = (purpose: 'start' | 'update' | 'handoff' | 'stop' | 'login') =>
      ({ pid: 4242, startMarker: '', token: 't', purpose, since: Date.now() })
    for (const purpose of ['start', 'update', 'handoff', 'stop', 'login'] as const) {
      const said = lock.describeSpawnLockWaitPlainly(owner(purpose))
      expect(said).toMatch(/^[^.]+ — waiting for it to finish…$/)
      expect(said).not.toMatch(/pid|4242|lock/)
    }
    expect(lock.describeSpawnLockWaitPlainly(owner('login'))).toMatch(/^Another sign-in/)
    expect(lock.describeSpawnLockWaitPlainly(owner('update'))).toBe('Harness is still updating on this computer — waiting for it to finish…')
  })

  it('serializes two real spawners racing for the lock', async () => {
    // Each child takes the lock, appends "<pid> in", sleeps, appends "<pid> out". Serialized, the
    // trace is in/out/in/out; a broken lock interleaves in/in.
    const trace = join(dataDir, 'trace.log')
    const script = join(dataDir, 'racer.mts') // .mts: the temp dir has no package.json, so .ts would run as CJS
    const lockModule = join(process.cwd(), 'src', 'lib', 'daemonSpawnLock.ts')
    writeFileSync(script, `
      import { appendFileSync } from 'fs'
      import { withSpawnLock } from ${JSON.stringify(lockModule)}
      await withSpawnLock('start', async () => {
        appendFileSync(${JSON.stringify(trace)}, process.pid + ' in\\n')
        await new Promise((r) => setTimeout(r, 400))
        appendFileSync(${JSON.stringify(trace)}, process.pid + ' out\\n')
      })
    `)
    const tsx = join(process.cwd(), 'node_modules', '.bin', 'tsx')
    const run = () => new Promise<number | null>((resolve) => {
      const c = spawn(tsx, [script], { env: { ...process.env, ADAPTER_DATA_DIR: dataDir }, stdio: 'inherit' })
      c.on('exit', (code) => resolve(code))
    })
    const codes = await Promise.all([run(), run(), run()])
    expect(codes).toEqual([0, 0, 0])
    const lines = readFileSync(trace, 'utf8').trim().split('\n')
    expect(lines).toHaveLength(6)
    for (let i = 0; i < lines.length; i += 2) {
      const [inPid, inWord] = lines[i].split(' ')
      const [outPid, outWord] = lines[i + 1].split(' ')
      expect(inWord).toBe('in')
      expect(outWord).toBe('out')
      expect(outPid).toBe(inPid)
    }
    expect(existsSync(lockDir())).toBe(false)
  }, 30_000)

  it('on Windows, reads an owner whatever its mode says: Windows reports 0666, and the profile\'s ACL is what protects it', async () => {
    const lock = await loadLock()
    mkdirSync(lockDir(), { mode: 0o700 })
    writeFileSync(ownerFile(), JSON.stringify({ pid: 4242, startMarker: '', token: 't', purpose: 'start', since: 1 }), { mode: 0o666 })
    spawnSync('chmod', ['0777', lockDir()])
    spawnSync('chmod', ['0666', ownerFile()])
    expect(() => lock.readSpawnLockOwner('darwin')).toThrow(/unsafe owner, mode, or type/)
    expect(lock.readSpawnLockOwner('win32')).toMatchObject({ pid: 4242, token: 't', purpose: 'start' })
  })

  it('knows a Windows owner whose pid now runs a process that started after it took the lock', async () => {
    const lock = await loadLock()
    const owner = { pid: 4242, startMarker: '', token: 't', purpose: 'start' as const, since: Date.parse('2026-10-16T00:00:00Z') }
    const at = (ms: number) => `w:${(BigInt(ms) + 11_644_473_600_000n) * 10_000n}`
    expect(lock.spawnLockOwnerReused(owner, { startMarker: at(owner.since - 1_000) })).toBe(false)
    expect(lock.spawnLockOwnerReused(owner, { startMarker: at(owner.since + 60_000) })).toBe(true)
    expect(lock.spawnLockOwnerReused(owner, null)).toBe(false)
    expect(lock.spawnLockOwnerReused(owner, { startMarker: 'unreadable' })).toBe(false)
  })

  it('releases an abandoned lock only while it is still the one that was judged', async () => {
    const lock = await loadLock()
    mkdirSync(lockDir(), { mode: 0o700 })
    const since = Date.parse('2026-10-16T00:00:00Z')
    writeFileSync(ownerFile(), JSON.stringify({ pid: 4242, startMarker: '', token: 't', purpose: 'start', since }), { mode: 0o600 })
    const at = (ms: number) => `w:${(BigInt(ms) + 11_644_473_600_000n) * 10_000n}`
    const reissued = { pid: 4242, startMarker: at(since + 60_000) }
    const judged = lock.readSpawnLockOwner()!
    // Another lock now (another token, pid or time), or a row that does not show the pid reissued: it stays.
    expect(lock.releaseAbandonedSpawnLock({ ...judged, token: 'other' }, reissued)).toBe(false)
    expect(lock.releaseAbandonedSpawnLock({ ...judged, pid: 4243 }, { ...reissued, pid: 4243 })).toBe(false)
    expect(lock.releaseAbandonedSpawnLock({ ...judged, since: since - 1 }, reissued)).toBe(false)
    expect(lock.releaseAbandonedSpawnLock(judged, { pid: 4242, startMarker: at(since - 1_000) })).toBe(false)
    expect(lock.releaseAbandonedSpawnLock(judged, { ...reissued, pid: 99 })).toBe(false)
    expect(existsSync(lockDir())).toBe(true)
    expect(lock.releaseAbandonedSpawnLock(judged, reissued)).toBe(true)
    expect(lock.releaseAbandonedSpawnLock(judged, reissued)).toBe(false)
    expect(existsSync(lockDir())).toBe(false)
  })
})