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
harnessd's master
The process harness start launches (or launchd or systemd, once harness service install opted in).
It keeps the core and the services running, and nothing else.
Rules
- No feature code, no network, no sockets. Everything here could otherwise fail, and the master is
the one process that must not. Import only Node built-ins and the files in this folder (and the log
trimmer);
src/architecture.spec.tschecks it. - Everything that touches the operating system is injected (
SupervisorDeps,ServiceSupervisorDeps), so every decision is a unit test with fake timers. 100% coverage per file (npm run test:harnessd). - The spawn protocol only grows (
protocol.ts): messages are added, never changed or removed, and unknown ones are ignored, because during an update an older master supervises a newer core. - The core is always restarted; a service may be parked. Never let a failing service stop the core or the master.
- Platform supervision is opt-in (
platform.ts,harness service install): launchd or systemd runs the master in the foreground, or, on Windows, Task Scheduler startsharness start --if-downat logon and every five minutes (platform.tstaskSchedulerXml), which starts a master when none runs; and the CLI starts and stops it through the platform, never beside it. Under systemd, never stop the unit with a stop job (systemctl stop,restart,disable --now): tmux built with systemd support makes every pane PartOf the unit that started its server, so a stop job ends every agent.stop()signals the master instead. The desktop app does not use it yet. - The master replaces itself only in the gap before a core starts (
reexec.ts): no core running, services stopped and reaped first, in place so the pid stays. Never exec with a child running: it would lose its channel, and become an orphan or a zombie no one reaps. A master started on cli.js does it once more, before it has started anything: onto the lean bundle cli.js carries, so the master parses its own code and not the whole CLI's (../masterProcess.ts). Windows has no exec: there the master starts its replacement throughharness-launch.exeand leaves once it holds the pid file (reexec.tsHandOverDeps), under the spawn lock (released as the old master leaves; the replacement does not take it) and with a token in the marker, so a replacement that comes up after the old master gave up leaves rather than run beside it. Windows has no SIGTERM either: the master stops its children withharnessd:shutdown(stopByMessage). A bundle whose probe does not say it takes a handover (PROBE_HANDOVER) is not handed over to. - The lean bundle is only ever an optimisation (
leanBundle.ts,leanServices.ts). A service is started from it only while its files are the ones its master started with and cli.js is the bundle they came from, and not after it died twice from it before beating; from cli.js otherwise. Other masters (another build, a secondharness start) may share the data folder: each claims the folder it runs from, and one is removed only once no live master claims it.lean-offin the data folder turns it off for masters launchd or systemd start. Never exec onto a file without checking it is there: a failed exec cannot be caught (reexec.ts). - Each process runs under its own name (
processName.ts): Activity Monitor andtopname a process after the file exec'd, and the master, core and each service are started through a hard link of the managed node (harnessd,harnessd-core,harnessd-<service>), titled the same. The links live in<runtime>/node-…/libexec/harnessd/— neverbin/, which agent panes get on PATH — are made only for the managed runtime's node, never a bareharness(the dial'spgrep -x harnessmeans the app), and any failure runs the process asnode. Children a process starts usebaseNode(process.execPath). - Updates are the master's to run, never the core's. The updater runs in a process the master starts
(
UPDATER_HOST,../services/updaterProcess.ts): it downloads, verifies, canaries and stages a build, then says so (harnessd:staged); the master asks the core to hand over (harnessd:update) and judges the new core on probation, as before. On Windows it stages a terminal host payload too (ptyVersion, only under a master that setsHARNESSD_JUDGES_PTY), and the same probation rolls back or keeps both (../lib/windows/ptyUpdate.ts). A build that needs a host protocol above the installed host's is staged only with a payload of that protocol, the host first, in one handover (spec §5's protocol and pairing rules). Only the updater's process (UPDATER_PROCESS) can start this, or exit 75 to be restarted at once. From any other service,harnessd:stagedis logged once and ignored, and exit 75 counts as a crash. The master itself still makes no network call. Every core this master starts hearsHARNESSD_UPDATES=master; a core under a master from before that runs the updater beside itself, in its own process (../core/updaterBeside.ts). - A process on demand starts only when the core asks (
onDemandinSERVICE_HOSTS,services.ts). The core sendsharnessd:wantfor one of its services; from then on it is kept running like any other. A core that speaks an older protocol than the process'saskedSincenever asks, sounaskedstarts it as that core binds. Making a process on demand bumpsHARNESSD_PROTOCOLand setsaskedSinceto it. Awantis heard before the core binds too: a core signed in asks for the gateway as it starts, so the relay comes up beside it. HARNESSD_*are for harnessd's processes alone, never a child's. What the master tells the core and each service (the service token among them) leaves process.env first thing in those processes (../lib/harnessdEnv.tsholdHarnessdEnv), and is read throughharnessdEnv(), neverprocess.env.HARNESSD_*. Left in, every child inherited it: the tmux server the core starts copies its environment into every pane, and every agent and terminal had them (found 2026-10-11). A harnessd process the core starts (the updater beside it, a master it hands over to, the master's probe) is given it explicitly. The core also unsets them from a tmux server an earlier boot started (TmuxBackend.unsetServerEnvironment).