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.

16.7 KB
Raw Blame
import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
import { homedir, tmpdir } from 'node:os'
import { dirname, join } from 'node:path'

import { afterEach, describe, expect, it, vi } from 'vitest'

import { UNSETTLED } from './types.js'
import {
  absoluteFolder, entries, epochMs, fileStamp, firstLine, folderKey, gitCommonDir, harnessTtys, listProcesses, parseLine, parseLsof, parseTtys,
  processAlive, processCwds, processTtys, processView, readHead, readJson, readTail, readText, record, run, sameProject, scanMemo, text, UUID,
  within,
} from './support.js'

const dirs: string[] = []
afterEach(() => { for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true }) })
function home(): string {
  const dir = mkdtempSync(join(tmpdir(), 'externals-support-'))
  dirs.push(dir)
  return dir
}

describe('reading files', () => {
  it('reads a head, a tail and a first line, and reads nothing from what is not there', async () => {
    const dir = home()
    const path = join(dir, 'a.jsonl')
    writeFileSync(path, 'first line\nsecond line\nthird')
    expect(await readHead(path, 5)).toBe('first')
    expect(await readTail(path, 5)).toBe('third')
    expect(await readTail(path, 1_000)).toBe('first line\nsecond line\nthird')
    expect(await firstLine(path, 1_000)).toBe('first line')
    // A first line longer than what is read is not a line.
    expect(await firstLine(path, 4)).toBeNull()
    expect(await readHead(join(dir, 'none'), 5)).toBe('')
    expect(await readTail(join(dir, 'none'), 5)).toBe('')
    expect(await firstLine(join(dir, 'none'), 5)).toBeNull()
  })

  it('lists a folder, and nothing for one that is missing', async () => {
    const dir = home()
    writeFileSync(join(dir, 'x'), '')
    expect((await entries(dir)).map((entry) => entry.name)).toEqual(['x'])
    expect(await entries(join(dir, 'none'))).toEqual([])
  })

  it('reads JSON files and lines, and says null for anything half-written', async () => {
    const dir = home()
    writeFileSync(join(dir, 'ok.json'), '{"a":1}')
    writeFileSync(join(dir, 'bad.json'), '{"a":')
    expect(await readJson(join(dir, 'ok.json'))).toEqual({ a: 1 })
    expect(await readJson(join(dir, 'bad.json'))).toBeNull()
    expect(await readJson(join(dir, 'none.json'))).toBeNull()
    expect(await readText(join(dir, 'ok.json'))).toBe('{"a":1}')
    expect(await readText(join(dir, 'none.json'))).toBe('')
    expect(parseLine('[1]')).toEqual([1])
    expect(parseLine('nope')).toBeNull()
  })

  it("stamps a file by size and time, and nothing that is not a file", async () => {
    const dir = home()
    const path = join(dir, 'f')
    writeFileSync(path, 'abc')
    const stamp = await fileStamp(path)
    expect(stamp?.stamp).toMatch(/^3:\d/)
    expect(stamp?.mtime).toBeGreaterThan(0)
    expect(await fileStamp(dir)).toBeNull()
    expect(await fileStamp(join(dir, 'none'))).toBeNull()
  })
})

describe('reading values', () => {
  it('takes strings, records, uuids and absolute folders only when they are what they say', () => {
    expect(text('a')).toBe('a')
    expect(text(1)).toBe('')
    expect(record({ a: 1 })).toEqual({ a: 1 })
    expect(record([1])).toBeNull()
    expect(record(null)).toBeNull()
    expect(record('x')).toBeNull()
    expect(UUID.test('11111111-2222-4333-8444-555555555555')).toBe(true)
    expect(UUID.test('not-a-uuid')).toBe(false)
    expect(absoluteFolder('/work')).toBe('/work')
    expect(absoluteFolder('work')).toBeNull()
    expect(absoluteFolder(3)).toBeNull()
  })

  it('reads a time in every unit the engines write', () => {
    const ms = Date.parse('2026-09-27T10:00:00Z')
    expect(epochMs(ms / 1000)).toBe(ms)
    expect(epochMs(ms / 1000 + 0.25)).toBe(ms + 250)
    expect(epochMs(ms)).toBe(ms)
    expect(epochMs(ms * 1000)).toBe(ms)
    expect(epochMs(ms * 1_000_000)).toBe(ms)
    expect(epochMs('2026-09-27T10:00:00Z')).toBe(ms)
    expect(epochMs(String(ms / 1000))).toBe(ms)
    expect(epochMs('no time')).toBeNull()
    expect(epochMs(0)).toBeNull()
    expect(epochMs(-5)).toBeNull()
    expect(epochMs(Number.NaN)).toBeNull()
    expect(epochMs(null)).toBeNull()
  })

  it('says whether a path is a folder or inside it', () => {
    expect(within('/a/b', '/a/b')).toBe(true)
    expect(within('/a/b', '/a/b/c/d')).toBe(true)
    expect(within('/a/b', '/a/bc')).toBe(false)
    expect(within('/a/b', '/a')).toBe(false)
  })
})

describe('scanMemo', () => {
  it('reads again only what changed, and forgets what a scan did not ask for', async () => {
    const memo = scanMemo({ excluded: ['/data/harness'] })
    let reads = 0
    const read = async () => ++reads
    const ctx = memo.context()
    expect(await ctx.memo('a', '1', read)).toBe(1)
    expect(await ctx.memo('a', '1', read)).toBe(1)
    expect(await ctx.memo('a', '2', read)).toBe(2)
    expect(await ctx.memo('b', '1', read)).toBe(3)
    memo.prune()
    // The next scan asks only for a: b is forgotten, and read again when asked.
    const next = memo.context()
    expect(await next.memo('a', '2', read)).toBe(2)
    memo.prune()
    expect(await memo.context().memo('b', '1', read)).toBe(4)
    expect(ctx.excluded('/data/harness/summary-scratch')).toBe(true)
    expect(ctx.excluded('/work')).toBe(false)
  })

  it("keeps a file's head for good once it can be judged, and reads it again until then", async () => {
    const memo = scanMemo()
    let reads = 0
    let answer: string | null | typeof UNSETTLED = UNSETTLED
    const read = async () => { reads++; return answer }
    const ctx = memo.context()
    expect(await ctx.head('f', '1', read)).toBeNull()
    expect(await ctx.head('f', '1', read)).toBeNull()
    expect(reads).toBe(1)
    answer = 'head'
    expect(await ctx.head('f', '2', read)).toBe('head')
    expect(await ctx.head('f', '3', read)).toBe('head')
    expect(reads).toBe(2)
    answer = null
    expect(await ctx.head('g', '1', read)).toBeNull()
    expect(await ctx.head('g', '2', read)).toBeNull()
    expect(reads).toBe(3)
    memo.prune()
    memo.prune()
    expect(await memo.context().head('g', '9', read)).toBeNull()
    expect(reads).toBe(4)
  })

  it('lets the daemon breathe every so often, and has sensible defaults', async () => {
    const ctx = scanMemo({ excluded: [], paceEvery: 2 }).context()
    await ctx.pace()
    await ctx.pace()
    const plain = scanMemo().context()
    expect(plain.excluded('/anything')).toBe(false)
    for (let i = 0; i < 64; i++) await plain.pace()
  })
})

describe('processes', () => {
  it('knows this process is alive, and one that cannot exist is not', () => {
    expect(processAlive(process.pid)).toBe(true)
    expect(processAlive(2 ** 22 + 7)).toBe(false)
  })

  it("runs a command and keeps what it printed, even when it fails", async () => {
    expect(await run('/bin/sh', ['-c', 'printf ok'], 5_000)).toBe('ok')
    expect(await run('/bin/sh', ['-c', 'printf partial; exit 1'], 5_000)).toBe('partial')
    expect(await run('/bin/sh', ['-c', 'exit 1'], 5_000)).toBeNull()
  })

  it('reads lsof and ps output', () => {
    expect(parseLsof('p10\nf3\nn/a\nn/b\np11\nn/c\nx\n')).toEqual(new Map([[10, ['/a', '/b']], [11, ['/c']]]))
    expect(parseLsof('n/orphan\np0\nn/zero\n')).toEqual(new Map())
    expect(parseTtys('  10 ttys003\n  11 ??\n  12 ?\n\n')).toEqual(new Map([
      [10, '/dev/ttys003'], [11, null], [12, null],
    ]))
  })

  it("asks the machine through one view, and reads each process's terminal", async () => {
    const calls: string[] = []
    const exec = async (command: string, args: readonly string[]) => {
      calls.push(`${command} ${args.join(' ')}`)
      return command === 'lsof' ? 'p7\nn/f\n' : '  7 ttys001\n'
    }
    let listed = 0
    const view = processView(exec, () => true, async () => { listed++; return [{ pid: 7, ppid: 1, executable: 'x', args: '' }] })
    expect(await view.list()).toHaveLength(1)
    await view.list()
    expect(listed).toBe(1)
    expect(await view.openFiles([7, 8])).toEqual(new Map([[7, ['/f']]]))
    expect(await view.openFiles([])).toEqual(new Map())
    expect(await view.openFilesOf(['codex', 'Codex'])).toEqual(new Map([[7, ['/f']]]))
    expect(await view.openFilesOf([])).toEqual(new Map())
    expect(view.alive(1)).toBe(true)
    expect(calls).toEqual([
      'lsof -n -P -Fpn -a -p 7,8',
      'lsof -n -P -Fpn -c codex -c Codex',
    ])
    expect(await processTtys([7], exec)).toEqual(new Map([[7, '/dev/ttys001']]))
    expect(await processTtys([], exec)).toEqual(new Map())
    const quiet = processView(async () => null)
    expect(await quiet.openFiles([1])).toEqual(new Map())
    expect(await quiet.openFilesOf(['x'])).toEqual(new Map())
    expect(await processTtys([1], async () => null)).toEqual(new Map())
  })

  it("reads each process's working folder in one bounded look, and leaves out what it cannot read", async () => {
    const calls: string[] = []
    const exec = async (command: string, args: readonly string[]) => {
      calls.push(`${command} ${args.join(' ')}`)
      // lsof says nothing of a gone pid, or of one it may not look at; a pid with no name line is unknown too.
      return 'p7\nfcwd\nn/work/dial\np8\nfcwd\n'
    }
    expect(await processCwds([7, 8, 9], exec, 'darwin')).toEqual(new Map([[7, '/work/dial']]))
    expect(calls).toEqual(['lsof -n -P -a -d cwd -Fpn -p 7,8,9'])
    expect(await processCwds([7], async () => null, 'darwin')).toEqual(new Map())
    expect(await processCwds([], exec, 'darwin')).toEqual(new Map())
    expect(calls).toHaveLength(1)
    // Linux says it in /proc, one link a pid; one it may not read is unknown.
    const links: string[] = []
    const link = async (path: string) => {
      links.push(path)
      if (path === '/proc/8/cwd') throw Object.assign(new Error('denied'), { code: 'EACCES' })
      return path === '/proc/7/cwd' ? '/work/dial' : ''
    }
    expect(await processCwds([7, 8, 9], exec, 'linux', link)).toEqual(new Map([[7, '/work/dial']]))
    expect(links.sort()).toEqual(['/proc/7/cwd', '/proc/8/cwd', '/proc/9/cwd'])
    expect(calls).toHaveLength(1)
  })

  it('keys a folder the same however it is spelled', async () => {
    const dir = home()
    mkdirSync(join(dir, 'project'))
    symlinkSync(join(dir, 'project'), join(dir, 'link'))
    const key = await folderKey(join(dir, 'project'))
    for (const spelling of [`${join(dir, 'project')}/`, join(dir, 'link'), join(dir, 'link', '..', 'project')]) {
      expect(await folderKey(spelling), spelling).toBe(key)
    }
    // A folder that is gone keeps its spelling, less a trailing slash.
    expect(await folderKey(`${join(dir, 'gone')}/`)).toBe(join(dir, 'gone'))
  })

  it("finds a repository's shared store from any of its folders and worktrees, without running git", async () => {
    const dir = home()
    const main = join(dir, 'main'), tree = join(dir, 'tree'), sub = join(dir, 'sub'), odd = join(dir, 'odd')
    mkdirSync(join(main, '.git', 'worktrees', 'tree'), { recursive: true }); mkdirSync(join(main, 'src', 'deep'), { recursive: true })
    mkdirSync(join(tree, 'src'), { recursive: true }); mkdirSync(sub); mkdirSync(odd)
    // A worktree names its own folder in the store, relative or absolute; a submodule its own store.
    writeFileSync(join(tree, '.git'), 'gitdir: ../main/.git/worktrees/tree\n')
    mkdirSync(join(main, '.git', 'modules', 'sub'), { recursive: true })
    writeFileSync(join(sub, '.git'), `gitdir: ${join(main, '.git', 'modules', 'sub')}\n`)
    writeFileSync(join(odd, '.git'), 'not a pointer\n')
    const store = await folderKey(join(main, '.git'))
    expect(await gitCommonDir(join(main, 'src', 'deep'), '/')).toBe(store)
    expect(await gitCommonDir(join(tree, 'src'), '/')).toBe(store)
    expect(await gitCommonDir(sub, '/')).toBe(await folderKey(join(main, '.git', 'modules', 'sub')))
    expect(await gitCommonDir(odd, '/')).toBeNull()
    // Not past the ceiling: a `.git` above it does not make every folder one project.
    mkdirSync(join(dir, 'nested', 'a'), { recursive: true }); mkdirSync(join(dir, 'nested', '.git'))
    expect(await gitCommonDir(join(dir, 'nested', 'a'), join(dir, 'nested'))).toBeNull()
    expect(await gitCommonDir(join(dir, 'nested', 'a'), dir)).toBe(await folderKey(join(dir, 'nested', '.git')))
    // The default ceiling is the folder holding the homes.
    expect(await gitCommonDir(dirname(homedir()))).toBeNull()

    expect(await sameProject(`${main}/`, main, '/')).toBe(true)
    // Within one repository by its store; a folder merely above or below, outside one, is another project.
    expect(await sameProject(main, join(main, 'src', 'deep'), '/')).toBe(true)
    expect(await sameProject(join(main, 'src', 'deep'), main, '/')).toBe(true)
    expect(await sameProject(dir, join(dir, 'nested', 'a'), dir)).toBe(false)
    expect(await sameProject(join(dir, 'nested', 'a'), dir, dir)).toBe(false)
    expect(await sameProject(join(tree, 'src'), join(main, 'src'), '/')).toBe(true)
    expect(await sameProject(sub, main, '/')).toBe(false)
    expect(await sameProject(odd, join(dir, 'nested', 'a'), '/')).toBe(false)
    // A name that only starts like the other is another folder.
    expect(await sameProject(join(dir, 'mainly'), join(dir, 'main'), dir)).toBe(false)
  })

  it('lists the real machine: this very process is among them, with its own open files', async () => {
    const view = processView()
    const me = (await view.list()).find((row) => row.pid === process.pid)
    expect(me?.args).toContain('node')
    const dir = home()
    const held = join(dir, 'held.txt')
    writeFileSync(held, 'x')
    const { open } = await import('node:fs/promises')
    const handle = await open(held, 'r')
    try {
      const files = await view.openFiles([process.pid])
      expect((files.get(process.pid) ?? []).some((path) => path.endsWith('held.txt'))).toBe(true)
    } finally {
      await handle.close()
    }
    expect((await processTtys([process.pid])).has(process.pid)).toBe(true)
    expect(await folderKey((await view.cwds([process.pid])).get(process.pid) ?? '')).toBe(await folderKey(process.cwd()))
  })

  it('lists no processes when ps cannot be read, and each start time when it can be read', async () => {
    expect(await listProcesses(async () => null)).toEqual([])
    const row = { pid: 5, parentPid: 1, executable: 'grok', args: 'grok', startMarker: 'Sun Sep 27 09:05:03 2026' }
    expect(await listProcesses(async () => [row, { ...row, pid: 6, startMarker: 'soon' }])).toEqual([
      { pid: 5, ppid: 1, executable: 'grok', args: 'grok', started: Date.parse(row.startMarker), generation: `ps:${Date.parse(row.startMarker)}` },
      { pid: 6, ppid: 1, executable: 'grok', args: 'grok' },
    ])
    expect((await listProcesses(async () => [{ ...row, startTicks: 42 }]))[0].generation).toBe('linux:42')
  })

  it("knows Harness's own panes by their tmux session names, and by a daemon's tag wherever they moved", async () => {
    const out = '/dev/ttys001\tharness-claude-1\t\n/dev/ttys002\tmy-own\t\n\n/dev/ttys003\n'
      // A daemon's pane the person moved into a session of their own, and one another daemon tagged:
      // either way an agent, never a process a take-over stops.
      + '/dev/ttys004\tmy-claude-work\t0123456789abcdef\n/dev/ttys005\ttheirs\tfedcba9876543210\n'
    expect(await harnessTtys(async () => ({ stdout: out, failed: false, stderr: '' }))).toEqual(new Set(['/dev/ttys001', '/dev/ttys004', '/dev/ttys005']))
    // No server running: no panes of Harness's. Could not ask: nobody can say.
    expect(await harnessTtys(async () => ({ stdout: '', failed: true, stderr: 'no server running on /tmp/tmux-501/default' }))).toEqual(new Set())
    expect(await harnessTtys(async () => ({ stdout: '', failed: true, stderr: 'error connecting to /tmp/x (No such file or directory)' }))).toEqual(new Set())
    expect(await harnessTtys(async () => ({ stdout: '', failed: true, stderr: '' }))).toBeNull()
    // Before tmux 3.0 the tag rides the pane's start command (`paneOwnerFormat`), asked for as such.
    let asked: readonly string[] = []
    const old = '/dev/ttys006\tmy-claude-work\t/usr/bin/env HARNESS_DAEMON=0123456789abcdef\n/dev/ttys007\tmy-own\t\n'
    expect(await harnessTtys(async (_command, args) => { asked = args; return { stdout: old, failed: false, stderr: '' } }, false))
      .toEqual(new Set(['/dev/ttys006']))
    expect(asked.at(-1)).toContain('#{m:/usr/bin/env HARNESS_DAEMON=*,#{pane_start_command}}')
    // A real tmux answers one way or the other: a private one with no server, never the developer's own.
    vi.stubEnv('TMUX', undefined)
    vi.stubEnv('TMUX_PANE', undefined)
    vi.stubEnv('TMUX_TMPDIR', home())
    try {
      expect(await harnessTtys()).toEqual(new Set())
    } finally {
      vi.unstubAllEnvs()
    }
  })

  it('reads entries through a symlinked folder too', async () => {
    const dir = home()
    mkdirSync(join(dir, 'real'))
    writeFileSync(join(dir, 'real', 'f'), '')
    symlinkSync(join(dir, 'real'), join(dir, 'link'))
    expect((await entries(join(dir, 'link'))).map((entry) => entry.name)).toEqual(['f'])
  })
})