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
/**
* Fake `launchctl`, `systemctl` and `loginctl` for the tests of `harness service` (harnessd/platform.ts,
* lib/serviceCommand.ts): a small model of what launchd and systemd do with harnessd's job, kept in a
* folder of their own, recording every call.
*
* Hand the code under test a PATH that is this folder ALONE. Node looks a command up on the PATH of the
* environment it is given, so a fake that is missing fails as ENOENT and is never the real binary: a
* test cannot register anything with this machine's launchd or systemd, or stop the person's daemon.
*/
import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
import { createRequire } from 'node:module'
import { tmpdir } from 'node:os'
import { basename, join, resolve } from 'node:path'
import { runInNewContext } from 'node:vm'
export interface FakePlatformState {
/** launchd: the user's GUI domain exists (someone is logged in at the screen). */
guiDomain: boolean
/** launchd: the job is loaded. systemd: the unit's file is known to the manager. */
loaded: boolean
/** systemd: enabled for the next login. */
enabled: boolean
/** The master's pid while the platform runs it; null while it does not. */
pid: number | null
/** The pid the next start runs the master as. */
nextPid: number
/** When set, a start writes `nextPid` here, as the master claims the pid file once its core binds;
* a stop removes it, as the master does on its way out. */
pidFile: string | null
/** systemd: the unit gave up (its start limit). */
failed: boolean
/** loginctl's answer for Linger; null makes loginctl fail. */
linger: 'yes' | 'no' | null
/** Calls that fail instead, keyed by `<command> <first argument after --user>`. */
fail: Record<string, { status: number; stderr: string }>
/** Pids a stop may SIGTERM, as launchd and systemd do the master: only stand-ins a test started
* itself, never a number that could be someone's real process. */
killable: number[]
}
export interface FakePlatform {
/** The folder to put alone on PATH. */
bin: string
/** Every call, as argv arrays with the command first. */
calls(): string[][]
state(): FakePlatformState
set(change: Partial<FakePlatformState>): void
/**
* The same fakes, run in this process instead of as one: `PlatformDeps.run` for a test that is about
* what harness does with launchd or systemd, not about how it starts their commands. Each call as a
* process costs a node start, and on macOS the first run of a freshly written executable waits on the
* system's check of it: 220 ms at a load of 100, 600 ms with 12 busy loops more, against 16 ms for one
* already run (2026-10-06). A test makes three such files and up to ten calls, and serviceCommand.spec.ts
* timed out 12 times in one loaded unit run.
*/
run(command: string, args: string[]): { status: number | null; stdout: string; stderr: string; error?: string }
}
/** What `process.exit` throws inside an in-process run, so the script stops where it would have. */
class FakeExit {
constructor(readonly status: number) {}
}
const DEFAULTS: FakePlatformState = {
guiDomain: true, loaded: false, enabled: false, pid: null, nextPid: 4242, pidFile: null, failed: false, linger: 'yes', fail: {}, killable: [],
}
// One script for all three commands, told apart by the name it was run as. Plain CommonJS on the
// node running the tests, named by its absolute path in the shebang, so it needs nothing from PATH.
const SCRIPT = String.raw`
const fs = require('node:fs')
const path = require('node:path')
const dir = path.dirname(process.argv[1])
const name = path.basename(process.argv[1])
let args = process.argv.slice(2)
fs.appendFileSync(path.join(dir, 'calls.jsonl'), JSON.stringify([name, ...args]) + '\n')
const stateFile = path.join(dir, 'state.json')
const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'))
const save = () => fs.writeFileSync(stateFile, JSON.stringify(state))
const out = (text) => process.stdout.write(text)
const end = (status, stderr = '') => { if (stderr) process.stderr.write(stderr + '\n'); save(); process.exit(status) }
if (name === 'systemctl' && args[0] === '--user') args = args.slice(1)
const failing = state.fail[name + ' ' + args[0]]
if (failing) end(failing.status, failing.stderr)
const run = () => {
state.pid = state.nextPid
state.failed = false
if (state.pidFile) fs.writeFileSync(state.pidFile, state.pid + '\n')
}
const halt = () => {
if (state.pid !== null && state.killable.includes(state.pid)) { try { process.kill(state.pid, 'SIGTERM') } catch {} }
if (state.pidFile && state.pid !== null) {
try { if (Number(fs.readFileSync(state.pidFile, 'utf8')) === state.pid) fs.rmSync(state.pidFile) } catch {}
}
state.pid = null
}
const label = 'ai.autonomous.harness.harnessd'
if (name === 'launchctl') {
const [verb, target, file] = args
switch (verb) {
case 'print':
if (!target.includes('/' + label)) {
if (!state.guiDomain) end(113, 'Could not find domain for port identifier: ' + target)
out(target + ' = {\n\ttype = Aqua\n}\n'); end(0)
}
if (!state.loaded) end(113, 'Could not find service "' + label + '" in domain for port')
out(target + ' = {\n\tactive count = 1\n\tpath = /fake/' + label + '.plist\n\ttype = LaunchAgent\n\tstate = ' + (state.pid ? 'running' : 'not running') + '\n\n\tprogram = /fake/node\n\targuments = {\n\t\t/fake/node\n\t}\n')
if (state.pid) out('\tpid = ' + state.pid + '\n\tlast exit code = (never exited)\n')
else out('\tlast exit code = 1\n')
out('}\n'); end(0)
case 'enable': end(0)
case 'bootstrap':
if (!state.guiDomain) end(125, 'Bootstrap failed: 125: Domain does not support specified action')
if (state.loaded) end(5, 'Bootstrap failed: 5: Input/output error')
if (!fs.existsSync(file)) end(2, 'Bootstrap failed: 2: No such file or directory')
state.loaded = true; run(); end(0)
case 'kickstart':
if (!state.loaded) end(113, 'Could not find service "' + label + '" in domain for port')
if (!state.pid) run()
end(0)
case 'bootout':
if (!state.loaded) end(3, 'Boot-out failed: 3: No such process')
state.loaded = false; halt(); end(0)
default: end(64, 'Unrecognized subcommand: ' + verb)
}
}
if (name === 'systemctl') {
const verb = args[0]
switch (verb) {
case 'show':
if (args.includes('--property=MainPID')) { out('MainPID=' + (state.pid ?? 0) + '\n'); end(0) }
out('LoadState=' + (state.loaded ? 'loaded' : 'not-found') + '\nUnitFileState=' + (state.enabled ? 'enabled' : state.loaded ? 'disabled' : '') +
'\nActiveState=' + (state.failed ? 'failed' : state.pid ? 'active' : 'inactive') + '\nSubState=' + (state.failed ? 'failed' : state.pid ? 'running' : 'dead') +
'\nMainPID=' + (state.pid ?? 0) + '\nResult=' + (state.failed ? 'start-limit-hit' : 'success') + '\n')
end(0)
case 'daemon-reload': state.loaded = true; end(0)
case 'reset-failed': state.failed = false; end(0)
case 'enable': state.enabled = true; if (args[1] === '--now' && !state.pid) run(); end(0)
case 'start': if (!state.pid) run(); end(0)
case 'stop': halt(); end(0)
case 'kill': if (!state.pid) end(1, 'Failed to kill unit harnessd.service: No main process to kill'); halt(); end(0)
case 'disable': state.enabled = false; if (args[1] === '--now') halt(); end(0)
default: end(1, 'Unknown command verb ' + verb)
}
}
if (name === 'loginctl') {
if (state.linger === null) end(1, 'Failed to get user: User ID is not logged in or lingering')
out('Linger=' + state.linger + '\n'); end(0)
}
end(127, name + ': not faked')
`
export function fakePlatform(bin: string, initial: Partial<FakePlatformState> = {}): FakePlatform {
// Never a folder that could be on someone's real PATH.
if (!resolve(bin).startsWith(resolve(tmpdir())) && !resolve(bin).startsWith('/tmp/') && !resolve(bin).startsWith('/private/tmp/')) {
throw new Error(`fake platform binaries belong in a temporary folder, not ${bin}`)
}
mkdirSync(bin, { recursive: true })
for (const name of ['launchctl', 'systemctl', 'loginctl']) {
const file = join(bin, name)
writeFileSync(file, `#!${process.execPath}\n${SCRIPT}`)
chmodSync(file, 0o755)
}
const stateFile = join(bin, 'state.json')
writeFileSync(stateFile, JSON.stringify({ ...DEFAULTS, ...initial }))
const callsFile = join(bin, 'calls.jsonl')
return {
bin,
calls: () => existsSync(callsFile) ? readFileSync(callsFile, 'utf8').trim().split('\n').filter(Boolean).map((line) => JSON.parse(line) as string[]) : [],
state: () => JSON.parse(readFileSync(stateFile, 'utf8')) as FakePlatformState,
set: (change) => writeFileSync(stateFile, JSON.stringify({ ...(JSON.parse(readFileSync(stateFile, 'utf8')) as FakePlatformState), ...change })),
run: (command, args) => {
// As a PATH of this folder alone: anything not faked is not found, never the real command.
if (!['launchctl', 'systemctl', 'loginctl'].includes(basename(command)) || command !== basename(command)) {
return { status: null, stdout: '', stderr: '', error: `spawnSync ${command} ENOENT` }
}
let stdout = ''
let stderr = ''
const fakeProcess = {
argv: [process.execPath, join(bin, command), ...args],
stdout: { write: (text: string) => { stdout += text; return true } },
stderr: { write: (text: string) => { stderr += text; return true } },
exit: (status: number) => { throw new FakeExit(status) },
kill: (pid: number, signal: NodeJS.Signals) => process.kill(pid, signal),
}
try {
runInNewContext(SCRIPT, { require: createRequire(import.meta.url), process: fakeProcess })
} catch (error) {
if (error instanceof FakeExit) return { status: error.status, stdout, stderr }
throw error
}
return { status: 0, stdout, stderr }
},
}
}