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.

6.4 KB
Raw Blame

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

  1. 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.ts checks it.
  2. 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).
  3. 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.
  4. The core is always restarted; a service may be parked. Never let a failing service stop the core or the master.
  5. Platform supervision is opt-in (platform.ts, harness service install): launchd or systemd runs the master in the foreground, or, on Windows, Task Scheduler starts harness start --if-down at logon and every five minutes (platform.ts taskSchedulerXml), 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.
  6. 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 through harness-launch.exe and leaves once it holds the pid file (reexec.ts HandOverDeps), 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 with harnessd:shutdown (stopByMessage). A bundle whose probe does not say it takes a handover (PROBE_HANDOVER) is not handed over to.
  7. 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 second harness 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-off in 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).
  8. Each process runs under its own name (processName.ts): Activity Monitor and top name 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/ — never bin/, which agent panes get on PATH — are made only for the managed runtime's node, never a bare harness (the dial's pgrep -x harness means the app), and any failure runs the process as node. Children a process starts use baseNode(process.execPath).
  9. 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 sets HARNESSD_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:staged is logged once and ignored, and exit 75 counts as a crash. The master itself still makes no network call. Every core this master starts hears HARNESSD_UPDATES=master; a core under a master from before that runs the updater beside itself, in its own process (../core/updaterBeside.ts).
  10. A process on demand starts only when the core asks (onDemand in SERVICE_HOSTS, services.ts). The core sends harnessd:want for one of its services; from then on it is kept running like any other. A core that speaks an older protocol than the process's askedSince never asks, so unasked starts it as that core binds. Making a process on demand bumps HARNESSD_PROTOCOL and sets askedSince to it. A want is heard before the core binds too: a core signed in asks for the gateway as it starts, so the relay comes up beside it.
  11. 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.ts holdHarnessdEnv), and is read through harnessdEnv(), never process.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).