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 { 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'])
})
})