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.

harnessd: launchd and systemd supervision, opt-in (harness service install) (#781)

Deee491d34b9c65
diff --git a/cli/e2e/cli.e2e.ts b/cli/e2e/cli.e2e.ts
new file mode 100644
index 000000000..6bcb238b6
--- /dev/null
+++ b/cli/e2e/cli.e2e.ts
@@ -0,0 +1,298 @@
+/**
+ * `harness start`, `stop` and `status` as people run them: from the INSTALLED bundle, the
+ * `~/.harness/cli/cli.js` the installer lays down, run on the managed Node it records, under a
+ * throwaway home with its own data folder, port and private tmux server.
+ *
+ * Every other end-to-end file boots the master itself; these are the commands that start and stop it,
+ * which `harness service install` changes (lib/platformDaemon.ts). Without the service nothing may
+ * change and no platform may be asked; with it, start and stop go through launchd or systemd; and a
+ * definition written for another data folder is not this daemon's.
+ *
+ * launchctl, systemctl and loginctl are fakes (harness/fakePlatform.mjs), first on PATH: they record
+ * every call and fail loudly where none may be made, and where the platform is allowed they run the
+ * master from the definition, as launchd and systemd would. The real ones are never run. Both
+ * definitions run on any computer: HARNESSD_TEST_PLATFORM picks the one `harness service` uses.
+ */
+import { execFileSync, spawn } from 'node:child_process'
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { afterAll, afterEach, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import { LAUNCHD_LABEL, SYSTEMD_UNIT, launchdPlist, systemdUnit } from '../src/harnessd/platform.js'
+import { LocalClient } from './harness/client.js'
+import { CLI_ROOT, IsolatedDaemon, until } from './harness/daemon.js'
+
+type Platform = 'launchd' | 'systemd'
+const uid = process.getuid!()
+
+interface Machine {
+ /** The throwaway machine: its environment, port, private tmux and fake engines. Never started
+ * itself: `harness start` starts the daemon here. */
+ daemon: IsolatedDaemon
+ /** The installed bundle, and the managed Node it runs on. */
+ cli: string
+ node: string
+ /** What every `harness` command here runs with. */
+ env: NodeJS.ProcessEnv
+ /** The fake platform tools' folder. */
+ fakes: string
+ /** The platform `harness service` uses here, and where it writes the definition. */
+ platform: Platform
+ definition: string
+}
+
+let bundleDir: string | null = null
+let bundle = ''
+beforeAll(() => {
+ // The run's bundle when there is one (E2E_BUNDLE=1), else one built for this file, as it ships.
+ if (process.env.E2E_BUNDLE_PATH) { bundle = process.env.E2E_BUNDLE_PATH; return }
+ bundleDir = mkdtempSync(join(tmpdir(), 'harness-cli-e2e-'))
+ execFileSync(process.execPath, ['build-bundle.mjs'], { cwd: CLI_ROOT, env: { ...process.env, BUNDLE_OUT_DIR: bundleDir }, stdio: 'pipe' })
+ bundle = join(bundleDir, 'cli.js')
+}, 180_000)
+afterAll(() => { if (bundleDir) rmSync(bundleDir, { recursive: true, force: true }) })
+
+const alive = (pid: number | null | undefined): boolean => IsolatedDaemon.alive(pid ?? null)
+const pidOf = (m: Machine): number | null => {
+ try { return Number(readFileSync(join(m.daemon.dataDir, 'adapter.pid'), 'utf8').trim()) || null } catch { return null }
+}
+const calls = (m: Machine): string[][] => {
+ const file = join(m.fakes, 'calls.jsonl')
+ return existsSync(file) ? readFileSync(file, 'utf8').trim().split('\n').filter(Boolean).map((line) => JSON.parse(line) as string[]) : []
+}
+const platformPid = (m: Machine): number | null => {
+ const file = join(m.fakes, 'state.json')
+ return existsSync(file) ? (JSON.parse(readFileSync(file, 'utf8')) as { pid: number | null }).pid : null
+}
+const allow = (m: Machine, mode: 'forbidden' | 'platform') =>
+ writeFileSync(join(m.fakes, 'config.json'), JSON.stringify({ mode, baseEnv: m.env }))
+
+/** Run `harness <args>` the way a terminal does: the managed Node on the installed bundle. */
+function harness(m: Machine, ...args: string[]): Promise<{ status: number | null; stdout: string; stderr: string }> {
+ return new Promise((resolve) => {
+ const child = spawn(m.node, [m.cli, ...args], { cwd: m.daemon.root, env: m.env, stdio: ['ignore', 'pipe', 'pipe'] })
+ let stdout = ''
+ let stderr = ''
+ child.stdout.on('data', (chunk: Buffer) => { stdout += chunk.toString() })
+ child.stderr.on('data', (chunk: Buffer) => { stderr += chunk.toString() })
+ child.on('close', (status) => resolve({ status, stdout, stderr }))
+ })
+}
+const said = (run: { stdout: string; stderr: string }) => `${run.stdout}\n${run.stderr}`
+
+const row = async (client: LocalClient, agentId: string) =>
+ ((await client.request<{ agents: Array<Record<string, any>> }>('agents_list', { includeStopped: true }, 30_000)).agents)
+ .find((agent) => agent.id === agentId)
+async function create(m: Machine, client: LocalClient, folder: string): Promise<Record<string, any>> {
+ const cwd = join(m.daemon.projectsDir, folder)
+ mkdirSync(cwd, { recursive: true })
+ const created = await client.request('agent_create', { engine: 'claude', cwd, bypassPermission: true }, 90_000)
+ expect(created.error, JSON.stringify(created)).toBeUndefined()
+ return until(`${folder} to bind its conversation`, async () => {
+ const agent = await row(client, created.agent.id)
+ return agent?.sessionId && agent.status === 'active' ? agent : null
+ }, 60_000, 500)
+}
+const back = (client: LocalClient, agent: Record<string, any>) =>
+ until(`${agent.id.slice(0, 8)} to be back`, async () => {
+ const now = await row(client, agent.id)
+ return now?.status === 'active' && now.sessionId === agent.sessionId ? now : null
+ }, 60_000, 500)
+const panes = (m: Machine) => m.daemon.tmux.run('list-panes', '-a', '-F', '#{pane_id} #{pane_pid}')
+/** A process's command line, as ps prints it. */
+const commandOf = (pid: number): string => execFileSync('ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf8' }).trim()
+const escape = (text: string) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+const statusOf = async (m: Machine) => await (await fetch(`http://127.0.0.1:${m.daemon.port}/api/status`)).json() as Record<string, any>
+
+describe('harness start, stop and status from the installed bundle', () => {
+ let machine: Machine | undefined
+ /** Every master and core a test saw, stopped at its end whatever happened. */
+ const seen = new Set<number>()
+ afterEach(async () => {
+ const m = machine
+ machine = undefined
+ if (!m) return
+ for (const pid of [pidOf(m), platformPid(m), ...seen]) if (pid) seen.add(pid)
+ for (const pid of seen) { try { process.kill(pid, 'SIGTERM') } catch { /* gone */ } }
+ await until('every daemon process of the test to go', () => [...seen].every((pid) => !alive(pid)), 10_000).catch(() => {
+ for (const pid of seen) { try { process.kill(pid, 'SIGKILL') } catch { /* gone */ } }
+ })
+ seen.clear()
+ await m.daemon.close()
+ })
+
+ async function install(platform: Platform = process.platform === 'darwin' ? 'launchd' : 'systemd'): Promise<Machine> {
+ const daemon = await IsolatedDaemon.create()
+ const home = daemon.env.HOME!
+ // The bundle where the installer puts it, beside its hook script.
+ const cliDir = join(home, '.harness', 'cli')
+ mkdirSync(cliDir, { recursive: true })
+ const cli = join(cliDir, 'cli.js')
+ copyFileSync(bundle, cli)
+ copyFileSync(join(dirname(bundle), 'notify.mjs'), join(cliDir, 'notify.mjs'))
+ // The managed Node as the installer records it: a runtime folder, and current-node naming its binary.
+ const runtime = daemon.env.ADAPTER_RUNTIME_DIR!
+ const node = join(runtime, 'node-e2e', 'bin', 'node')
+ mkdirSync(dirname(node), { recursive: true })
+ symlinkSync(process.execPath, node)
+ writeFileSync(join(runtime, 'current-node'), `${node}\n`)
+ const fakes = join(daemon.root, 'platform-bin')
+ mkdirSync(fakes)
+ const fake = pathToFileURL(join(CLI_ROOT, 'e2e', 'harness', 'fakePlatform.mjs')).href
+ for (const name of ['launchctl', 'systemctl', 'loginctl']) {
+ writeFileSync(join(fakes, name), `#!${process.execPath}\nimport(${JSON.stringify(fake)}).then((m) => m.run(${JSON.stringify(name)}))\n`, { mode: 0o755 })
+ }
+ const env: NodeJS.ProcessEnv = {
+ ...daemon.env, PATH: `${fakes}:${daemon.env.PATH}`, XDG_CONFIG_HOME: join(home, '.config'), HARNESSD_TEST_PLATFORM: platform,
+ }
+ // The defaults, all under the throwaway home: never a folder of the person running the tests.
+ for (const name of ['ADAPTER_CLI_DIR', 'HARNESS_BIN_DIR', 'HARNESS_LOGS_DIR', 'HARNESS_ENV_FILE', 'DOTENV_CONFIG_PATH']) delete env[name]
+ const definition = platform === 'launchd'
+ ? join(home, 'Library', 'LaunchAgents', `${LAUNCHD_LABEL}.plist`)
+ : join(home, '.config', 'systemd', 'user', SYSTEMD_UNIT)
+ const m: Machine = { daemon, cli, node, env, fakes, platform, definition }
+ allow(m, 'forbidden')
+ machine = m
+ onTestFailed(() => {
+ const log = join(daemon.dataDir, 'harness.log')
+ console.log(`---- platform calls\n${calls(m).map((call) => call.join(' ')).join('\n')}`)
+ console.log(`---- daemon log\n${existsSync(log) ? readFileSync(log, 'utf8').split('\n').slice(-120).join('\n') : '(none)'}`)
+ })
+ return m
+ }
+
+ it('without the service: start runs a master and core, an agent outlives stop in tmux and is back on the next start, and no platform is asked', async () => {
+ const m = await install()
+ const started = await harness(m, 'start')
+ expect(started.status, said(started)).toBe(0)
+ expect(started.stdout).toContain('● started · this computer only (not signed in)')
+ const master = pidOf(m)!
+ expect(alive(master)).toBe(true)
+ expect((await fetch(`http://127.0.0.1:${m.daemon.port}/api/health`)).ok).toBe(true)
+ const status = await statusOf(m)
+ expect(status.pid).toBe(master)
+ const core = status.corePid as number
+ expect(core).not.toBe(master)
+ seen.add(master).add(core)
+ // harnessd's master (it retitles itself), running the installed bundle's core.
+ expect(commandOf(master)).toBe('harnessd')
+ expect(commandOf(core)).toMatch(new RegExp(` ${escape(m.cli)} __run$`))
+
+ const running = await harness(m, 'status')
+ expect(running.stdout).toMatch(/status +● running · this computer only \(not signed in\)/)
+ expect(running.stdout).toMatch(new RegExp(`pid +${master}\\n`))
+ expect(running.stdout).not.toContain('supervisor')
+
+ // An agent made through the local socket, as the desktop app makes one.
+ let client = await LocalClient.connect(m.daemon)
+ const agent = await create(m, client, 'outlives-stop')
+ client.close()
+ const before = await panes(m)
+
+ const stopped = await harness(m, 'stop')
+ expect(stopped.stdout, said(stopped)).toContain(`machine stopped (pid ${master})`)
+ await until('the master and its core to go', () => !alive(master) && !alive(core), 10_000)
+ expect(pidOf(m)).toBeNull()
+ expect(await panes(m), 'the agent lives on in tmux').toBe(before)
+ expect((await harness(m, 'status')).stdout).toMatch(/status +○ stopped/)
+
+ const again = await harness(m, 'start')
+ expect(again.status, said(again)).toBe(0)
+ seen.add(pidOf(m)!)
+ client = await LocalClient.connect(m.daemon)
+ await back(client, agent)
+ client.close()
+ expect(await panes(m)).toBe(before)
+ expect((await harness(m, 'stop')).status).toBe(0)
+ expect(calls(m), 'no platform tool was asked anything').toEqual([])
+ })
+
+ it.each(['launchd', 'systemd'] as const)('with the service installed for this data folder: start and stop go through %s, and status names it', async (platform) => {
+ const m = await install(platform)
+ allow(m, 'platform')
+ const installed = await harness(m, 'service', 'install')
+ expect(installed.status, said(installed)).toBe(0)
+ expect(installed.stdout).toContain(`✓ harnessd runs under ${platform} (pid ${pidOf(m)})`)
+ const first = pidOf(m)!
+ seen.add(first)
+ expect(platformPid(m), `${platform} runs the master`).toBe(first)
+ expect(commandOf(first)).toBe('harnessd')
+ const firstCore = (await statusOf(m)).corePid as number
+ seen.add(firstCore)
+ expect(commandOf(firstCore)).toMatch(new RegExp(` ${escape(m.cli)} __run$`))
+ const definition = readFileSync(m.definition, 'utf8')
+ expect(definition).toContain(m.node)
+ expect(definition).toContain(m.cli)
+ expect(definition).toContain(join(m.daemon.dataDir, 'harness.log'))
+
+ const status = await harness(m, 'status')
+ expect(status.stdout).toMatch(new RegExp(`supervisor +${platform} · starts at login, comes back if it dies`))
+ expect(status.stdout).toMatch(new RegExp(`pid +${first}\\n`))
+
+ let client = await LocalClient.connect(m.daemon)
+ const agent = await create(m, client, 'under-the-platform')
+ client.close()
+ const before = await panes(m)
+
+ let from = calls(m).length
+ const stopped = await harness(m, 'stop')
+ expect(stopped.stdout, said(stopped)).toContain(`machine stopped (pid ${first})`)
+ expect(calls(m).slice(from)).toContainEqual(platform === 'launchd'
+ ? ['launchctl', 'bootout', `gui/${uid}/${LAUNCHD_LABEL}`]
+ : ['systemctl', '--user', 'kill', '--kill-who=main', '--signal=SIGTERM', SYSTEMD_UNIT])
+ await until('the master to go', () => !alive(first), 10_000)
+ expect(await panes(m), 'the agent lives on in tmux').toBe(before)
+ expect((await harness(m, 'status')).stdout).toMatch(/status +○ stopped/)
+
+ from = calls(m).length
+ const again = await harness(m, 'start')
+ expect(again.status, said(again)).toBe(0)
+ expect(again.stdout).toMatch(new RegExp(`supervisor +${platform}`))
+ expect(calls(m).slice(from)).toContainEqual(platform === 'launchd'
+ ? ['launchctl', 'bootstrap', `gui/${uid}`, m.definition]
+ : ['systemctl', '--user', 'start', SYSTEMD_UNIT])
+ const second = pidOf(m)!
+ seen.add(second)
+ expect(second).not.toBe(first)
+ expect(platformPid(m)).toBe(second)
+ client = await LocalClient.connect(m.daemon)
+ await back(client, agent)
+ client.close()
+
+ // Uninstalled, the daemon goes back to the usual way, and the platform is out of it.
+ const removed = await harness(m, 'service', 'uninstall')
+ expect(removed.status, said(removed)).toBe(0)
+ expect(removed.stdout).toContain(`${platform} no longer runs harnessd`)
+ expect(removed.stdout).toContain('starting it the usual way')
+ expect(existsSync(m.definition)).toBe(false)
+ const third = pidOf(m)!
+ seen.add(third)
+ expect(alive(second)).toBe(false)
+ expect(third).not.toBe(second)
+ allow(m, 'forbidden')
+ from = calls(m).length
+ expect((await harness(m, 'status')).stdout).not.toContain('supervisor')
+ expect((await harness(m, 'stop')).stdout).toContain(`machine stopped (pid ${third})`)
+ expect(calls(m).slice(from)).toEqual([])
+ expect(await panes(m)).toBe(before)
+ })
+
+ it.each(['launchd', 'systemd'] as const)('ignores a %s definition written for another data folder', async (platform) => {
+ const m = await install(platform)
+ const other = join(m.daemon.root, 'other-data')
+ const def = { nodePath: m.node, scriptPath: m.cli, logFile: join(other, 'harness.log'), home: m.env.HOME!, env: { ADAPTER_DATA_DIR: other } }
+ mkdirSync(dirname(m.definition), { recursive: true })
+ writeFileSync(m.definition, platform === 'launchd' ? launchdPlist(def) : systemdUnit(def))
+
+ const started = await harness(m, 'start')
+ expect(started.status, said(started)).toBe(0)
+ expect(started.stdout).not.toContain('supervisor')
+ const master = pidOf(m)!
+ seen.add(master)
+ expect((await harness(m, 'status')).stdout).not.toContain('supervisor')
+ expect((await harness(m, 'stop')).stdout).toContain(`machine stopped (pid ${master})`)
+ expect(calls(m), 'no platform tool was asked anything').toEqual([])
+ expect(readFileSync(m.definition, 'utf8'), 'and the other folder\'s definition is left as it was').toContain(other)
+ })
+})
diff --git a/cli/e2e/harness/fakePlatform.mjs b/cli/e2e/harness/fakePlatform.mjs
new file mode 100644
index 000000000..df21f7912
--- /dev/null
+++ b/cli/e2e/harness/fakePlatform.mjs
@@ -0,0 +1,191 @@
+/**
+ * Fake `launchctl`, `systemctl` and `loginctl` for the end-to-end tests of `harness service` and of
+ * `harness start`/`stop` under a platform (e2e/cli.e2e.ts). Unlike the unit tests' fake
+ * (src/testing/fakePlatform.ts) this one RUNS the master: it reads the definition `harness service
+ * install` wrote, the plist's ProgramArguments or the unit's ExecStart, and starts it detached with its
+ * environment, working directory and log, as launchd and systemd do. Its stops signal that master.
+ *
+ * Put the folder of these scripts first on the PATH the CLI is given: they shadow the real ones by
+ * name, and nothing in the CLI names the real ones by path. Every call is recorded (calls.jsonl).
+ *
+ * Two modes, in config.json beside the scripts:
+ * forbidden every call fails loudly (exit 99): for a machine where no platform may be asked at all.
+ * platform a small launchd or systemd. Stop jobs (`systemctl stop`, `restart`, `disable --now`) fail
+ * loudly too: tmux built with systemd support makes every pane PartOf the unit, and the CLI
+ * must never send one (harnessd/platform.ts `stop`).
+ *
+ * The master is given the test's isolated environment (config.baseEnv) beside the definition's own, as
+ * launchd gives a job its own environment beside the plist's. It refuses to start one without a private
+ * TMUX_TMPDIR: a master on the person's own tmux server is the one thing this must never make.
+ */
+import { spawn } from 'node:child_process'
+import { appendFileSync, closeSync, existsSync, openSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+const LABEL = 'ai.autonomous.harness.harnessd'
+const UNIT = 'harnessd.service'
+
+export async function run(name) {
+ const dir = dirname(process.argv[1])
+ const argv = process.argv.slice(2)
+ appendFileSync(join(dir, 'calls.jsonl'), `${JSON.stringify([name, ...argv])}\n`)
+ const config = JSON.parse(readFileSync(join(dir, 'config.json'), 'utf8'))
+ const stateFile = join(dir, 'state.json')
+ const state = existsSync(stateFile) ? JSON.parse(readFileSync(stateFile, 'utf8')) : { loaded: false, enabled: false, pid: null }
+ const save = () => writeFileSync(stateFile, JSON.stringify(state))
+ const end = (status, message) => {
+ if (message) process.stderr.write(`${message}\n`)
+ save()
+ process.exit(status)
+ }
+ const loudly = (why) => end(99, `FAKE ${name} ${argv.join(' ')}: ${why}`)
+ if (config.mode !== 'platform') loudly('called on a machine where no platform may be asked')
+
+ const alive = (pid) => { if (!pid) return false; try { process.kill(pid, 0); return true } catch { return false } }
+ const running = () => alive(state.pid)
+ const startMaster = (job) => {
+ const env = { ...config.baseEnv, ...job.env }
+ if (!env.TMUX_TMPDIR || !config.baseEnv.TMUX_TMPDIR || env.TMUX) loudly('refusing to start a master without a private tmux server')
+ const log = openSync(job.log, 'a')
+ const child = spawn(job.argv[0], job.argv.slice(1), { cwd: job.cwd, env, detached: true, stdio: ['ignore', log, log] })
+ closeSync(log)
+ child.unref()
+ state.pid = child.pid
+ state.started = (state.started ?? 0) + 1
+ }
+ const waitGone = async (pid, ms) => {
+ const deadline = Date.now() + ms
+ while (alive(pid) && Date.now() < deadline) await new Promise((done) => setTimeout(done, 50))
+ if (alive(pid)) { try { process.kill(pid, 'SIGKILL') } catch { /* gone */ } }
+ }
+
+ if (name === 'launchctl') {
+ const [verb, target, file] = argv
+ const service = `gui/${process.getuid()}/${LABEL}`
+ switch (verb) {
+ case 'print':
+ if (target === `gui/${process.getuid()}`) { process.stdout.write(`${target} = {\n\ttype = Aqua\n}\n`); end(0) }
+ if (target !== service) loudly('unexpected target')
+ if (!state.loaded) end(113, `Could not find service "${LABEL}" in domain for port`)
+ process.stdout.write(`${service} = {\n\tstate = ${running() ? 'running' : 'not running'}\n${running() ? `\tpid = ${state.pid}\n` : ''}\tlast exit code = 0\n}\n`)
+ end(0)
+ case 'enable':
+ if (target !== service) loudly('unexpected target')
+ end(0)
+ case 'bootstrap': {
+ if (target !== `gui/${process.getuid()}` || !file) loudly('unexpected arguments')
+ if (state.loaded) end(5, 'Bootstrap failed: 5: Input/output error')
+ state.loaded = true
+ startMaster(plist(readFileSync(file, 'utf8'))) // RunAtLoad
+ state.file = file
+ end(0)
+ }
+ case 'kickstart':
+ if (target !== service) loudly('unexpected target')
+ if (!state.loaded) end(113, `Could not find service "${LABEL}" in domain for port`)
+ if (!running()) startMaster(plist(readFileSync(state.file, 'utf8')))
+ end(0)
+ case 'bootout': {
+ if (target !== service) loudly('unexpected target')
+ if (!state.loaded) end(3, 'Boot-out failed: 3: No such process')
+ const pid = state.pid
+ state.loaded = false
+ state.pid = null
+ save()
+ if (alive(pid)) { process.kill(pid, 'SIGTERM'); await waitGone(pid, 10_000) }
+ end(0)
+ }
+ default: loudly('not a verb this fake knows')
+ }
+ }
+
+ if (name === 'systemctl') {
+ if (argv[0] !== '--user') loudly('only the user manager is ours to ask')
+ const [verb, ...rest] = argv.slice(1)
+ const unitFile = join(config.baseEnv.XDG_CONFIG_HOME, 'systemd', 'user', UNIT)
+ switch (verb) {
+ case 'daemon-reload': state.loaded = existsSync(unitFile); end(0)
+ case 'reset-failed': end(0)
+ case 'show': {
+ if (rest[0] !== UNIT) loudly('unexpected unit')
+ const pid = running() ? state.pid : 0
+ if (rest.includes('--property=MainPID')) { process.stdout.write(`MainPID=${pid}\n`); end(0) }
+ process.stdout.write(`LoadState=${state.loaded ? 'loaded' : 'not-found'}\nUnitFileState=${state.enabled ? 'enabled' : state.loaded ? 'disabled' : ''}\nActiveState=${pid ? 'active' : 'inactive'}\nSubState=${pid ? 'running' : 'dead'}\nMainPID=${pid}\nResult=success\n`)
+ end(0)
+ }
+ case 'enable':
+ if (rest.at(-1) !== UNIT) loudly('unexpected unit')
+ state.enabled = true
+ if (rest.includes('--now') && !running()) startMaster(unit(readFileSync(unitFile, 'utf8')))
+ end(0)
+ case 'start':
+ if (rest[0] !== UNIT) loudly('unexpected unit')
+ if (!running()) startMaster(unit(readFileSync(unitFile, 'utf8')))
+ end(0)
+ case 'kill': {
+ if (rest.at(-1) !== UNIT || !rest.includes('--kill-who=main') || !rest.includes('--signal=SIGTERM')) loudly('unexpected arguments')
+ if (!running()) end(1, `Failed to kill unit ${UNIT}: No main process to kill`)
+ process.kill(state.pid, 'SIGTERM') // systemctl kill does not wait; the CLI does
+ end(0)
+ }
+ case 'disable':
+ if (rest.includes('--now')) loudly('a stop job: it would stop every pane PartOf the unit')
+ state.enabled = false
+ end(0)
+ case 'stop':
+ case 'restart':
+ loudly('a stop job: it would stop every pane PartOf the unit')
+ default: loudly('not a verb this fake knows')
+ }
+ }
+
+ if (name === 'loginctl') { process.stdout.write('Linger=yes\n'); end(0) }
+ loudly('not faked')
+}
+
+const unxml = (text) => text.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, '&')
+
+/** The job in a plist `harness service install` wrote. */
+function plist(text) {
+ const body = text.replace(/<!--[\s\S]*?-->/g, '')
+ const value = (key) => unxml(new RegExp(`<key>${key}</key>\\s*<string>([^<]*)</string>`).exec(body)?.[1] ?? '')
+ const argv = [...(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(body)?.[1] ?? '').matchAll(/<string>([^<]*)<\/string>/g)].map((m) => unxml(m[1]))
+ const env = {}
+ for (const m of (/<key>EnvironmentVariables<\/key>\s*<dict>([\s\S]*?)<\/dict>/.exec(body)?.[1] ?? '').matchAll(/<key>([^<]*)<\/key>\s*<string>([^<]*)<\/string>/g)) env[unxml(m[1])] = unxml(m[2])
+ return { argv, env, cwd: value('WorkingDirectory'), log: value('StandardOutPath') }
+}
+
+/** systemd's quoting, as harnessd/platform.ts writes it: double-quoted words with C escapes. */
+function words(line) {
+ const out = []
+ let at = 0
+ while (at < line.length) {
+ while (line[at] === ' ') at++
+ if (at >= line.length) break
+ if (line[at] !== '"') { const next = line.indexOf(' ', at); out.push(line.slice(at, next < 0 ? undefined : next)); at = next < 0 ? line.length : next; continue }
+ let word = ''
+ at++
+ while (at < line.length && line[at] !== '"') {
+ if (line[at] === '\\') { word += line[at + 1]; at += 2 } else { word += line[at]; at++ }
+ }
+ out.push(word)
+ at++
+ }
+ return out
+}
+
+/** The job in a unit `harness service install` wrote. */
+function unit(text) {
+ const job = { argv: [], env: {}, cwd: '', log: '' }
+ for (const line of text.split('\n')) {
+ const at = line.indexOf('=')
+ if (line.startsWith('#') || at < 0) continue
+ const key = line.slice(0, at)
+ const value = line.slice(at + 1)
+ if (key === 'ExecStart') job.argv = words(value).map((word, index) => (index ? word.replace(/\$\$/g, '$') : word).replace(/%%/g, '%'))
+ if (key === 'Environment') { const [pair] = words(value); const eq = pair.indexOf('='); job.env[pair.slice(0, eq)] = pair.slice(eq + 1).replace(/%%/g, '%') }
+ if (key === 'WorkingDirectory') job.cwd = value.replace(/%%/g, '%')
+ if (key === 'StandardOutput' && value.startsWith('append:')) job.log = value.slice('append:'.length).replace(/%%/g, '%')
+ }
+ return job
+}
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 842f6b042..ad680c54f 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -51,7 +51,7 @@ import { DeviceFleet } from './device/deviceFleet.js'
import { registry, projectDisplayName, validTranscriptPath, type RegisteredSession } from './lib/registry.js'
import { engineSessionTitle } from './lib/sessionTitle.js'
import { installCodexHooks } from './lib/hooks.js'
-import { PID_FILE, daemonPort, isAlive, isDaemonRunning, readPid } from './lib/daemonState.js'
+import { DAEMON_LOG_FILE, HARNESSD_STATUS_FILE, PID_FILE, daemonPort, isAlive, isDaemonRunning, readPid } from './lib/daemonState.js'
import { clearSafeModeMarker, readSafeModeMarker, runBootHandoff, safeModeDisposition, safeModeStatusBody, SafeModeRequest, writeSafeModeMarker } from './lib/daemonSafeMode.js'
import { awakeTimeout } from './lib/sleepAware.js'
import {
@@ -59,6 +59,8 @@ import {
} from './lib/daemonLaunch.js'
import { SpawnLockBusyError, describeSpawnLockBusyPlainly, describeSpawnLockFailure, describeSpawnLockOwner, describeSpawnLockWaitPlainly, withSpawnLock } from './lib/daemonSpawnLock.js'
import { stopDaemonProcess } from './lib/daemonStop.js'
+import { installedPlatform, serviceDefinition, startUnderPlatform } from './lib/platformDaemon.js'
+import { serviceCommand, serviceCommandDeps } from './lib/serviceCommand.js'
import { ensureTmuxOnPath } from './lib/tmuxOnPath.js'
import { flashCommand } from './lib/flash.js'
import { readOrMintComputerId } from './lib/computerIdentity.js'
@@ -236,9 +238,7 @@ import {
// Daemon stdout/stderr. Capped at LOG_MAX_BYTES — see prepareLogFile/trimLogFile in lib/log.ts.
-const LOG_FILE = join(env.ADAPTER_DATA_DIR, 'harness.log')
-/** What harnessd's master last said about itself, for `harness status` when no core answers. */
-const HARNESSD_STATUS_FILE = join(env.ADAPTER_DATA_DIR, 'harnessd-status.json')
+const LOG_FILE = DAEMON_LOG_FILE
// Pre-rename name. Adopted (renamed, keeping the inode) the first time a daemon opens the log, so a
// machine that updates mid-run keeps its history instead of stranding it in a file nobody tails.
// The log has had three names; this slot holds the OLDEST. The middle one (`machine.log`) is adopted
@@ -350,6 +350,10 @@ Machine:
harness stop stop the background adapter (keeps the SSO session)
harness reset stop the adapter and clear local CLI state
harness status show whether it's running (+ version)
+ harness service install run the daemon under launchd (macOS) or systemd (Linux): it starts at login
+ and comes back if it dies; start and stop then go through it (opt-in)
+ harness service uninstall undo that: the daemon goes back to \`harness start\`
+ harness service status what launchd or systemd has registered, and whether it runs (--json)
harness logs export zip the last 7 days of logs (app, CLI, dial, daemon) to the Desktop
harness tui all of Harness in this terminal: swarms, panes, every machine (⌥O ⌥P ⌥N)
harness new [agent] [@machine] [folder|name] [-- task]
@@ -430,6 +434,11 @@ Env: BACKEND_WS_URL (${env.BACKEND_WS_URL}), WEB_URL (${env.WEB_URL}), ADAPTER_D
process.exit(exitCode)
}
+/** The `supervisor` row: who keeps the daemon running when it is not `harness start`. */
+function supervisorRow(platform: string): string {
+ return `${platform} · starts at login, comes back if it dies (harness service status)`
+}
+
/** Compact a home-relative path with `~` for display. */
function tildify(p: string): string {
const h = homedir()
@@ -4291,6 +4300,8 @@ function printInfoBlock(opts: {
status: string; pid: number; machineId?: string; sessions: number; version: string
/** The `device` row's text (this machine's key code and whether the account holds it); only `status` shows it. */
device?: string
+ /** Who keeps the daemon running, when launchd or systemd does (`harness service install`). */
+ supervisor?: string
connection: { backendUrl: string | null; autonomousEnv: string | null; signedIn: boolean; dataDir: string | null; authDir: string | null }
}): void {
const row = (k: string, v: string): string => ` ${k.padEnd(10)} ${v}`
@@ -4312,6 +4323,7 @@ function printInfoBlock(opts: {
if (opts.connection.authDir) console.log(row('auth', tildify(opts.connection.authDir)))
console.log(row('agents', `${opts.sessions} available`))
console.log(row('pid', String(opts.pid)))
+ if (opts.supervisor) console.log(row('supervisor', opts.supervisor))
console.log(row('logs', tildify(LOG_FILE)))
console.log(row('dial log', tildify(join(env.HARNESS_LOGS_DIR, 'dial-YYYYMMDD.log'))))
console.log(row('dashboard', `http://127.0.0.1:${daemonPort()}`))
@@ -4392,6 +4404,19 @@ async function spawnDaemon(session: AuthSession | null, runtimeNode: string | nu
mkdirSync(env.ADAPTER_DATA_DIR, { recursive: true, mode: 0o700 })
prepareLogFile(LOG_FILE, LEGACY_LOG_FILE) // adopt an older name + enforce the cap before we tail from here
const logOffset = existsSync(LOG_FILE) ? readFileSync(LOG_FILE).length : 0
+ // Opted in to launchd or systemd (`harness service install`): the platform runs the master, and one
+ // spawned here would be a second supervisor beside it (lib/platformDaemon.ts).
+ const platform = installedPlatform()
+ if (platform) {
+ const started = await startUnderPlatform(serviceDefinition({ logFile: LOG_FILE }))
+ if (!started.ok) {
+ const fail = connectFailure(launchDeps.readLogSlice(logOffset), daemonPort())
+ console.error(`\n✗ ${fail?.detail ?? started.detail}`)
+ console.error(` logs ${tildify(LOG_FILE)} · harness service status`)
+ process.exit(1)
+ }
+ return reportStarted(session, started.pid, platform)
+ }
const logFd = openSync(LOG_FILE, 'a')
// The daemon starts on the managed runtime straight away rather than inheriting this process's
// interpreter and waiting for some later restart to adopt it.
@@ -4421,6 +4446,12 @@ async function spawnDaemon(session: AuthSession | null, runtimeNode: string | nu
process.exit(1)
}
+ return reportStarted(session, child.pid ?? 0)
+}
+
+/** What `harness start` says once the daemon it started is up, and its exit. `supervisor`: launchd or
+ * systemd started it (`harness service install`). */
+async function reportStarted(session: AuthSession | null, pid: number, supervisor?: string): Promise<never> {
// Bound is started. What the daemon does next — dial the backend, retry on its own backoff, sign
// itself out on a 401, step aside on a 409 — is its own business and is logged by it; this command
// used to sit here for up to ten seconds watching the log for "[backend] connected", and a computer
@@ -4433,7 +4464,8 @@ async function spawnDaemon(session: AuthSession | null, runtimeNode: string | nu
status: session
? '● started · connecting to the backend in the background'
: '● started · this computer only (not signed in)',
- pid: child.pid ?? 0,
+ pid,
+ supervisor: supervisor && supervisorRow(supervisor),
machineId: session?.machineId,
sessions: daemonStatus?.sessions ?? 0,
version: daemonStatus?.version ?? VERSION,
@@ -5327,7 +5359,8 @@ async function status(): Promise<void> {
// in the one line a person reads, rather than leaving it looking like an ordinary slow start.
const safeMode = alive ? readSafeModeMarker(env.ADAPTER_DATA_DIR, isAlive) : null
// A core that cannot answer — restarting, starting, crash-looping — is described by its master.
- const master = alive && daemonStatus == null ? describeMasterStatus(readStatusFile(HARNESSD_STATUS_FILE, pid)) : null
+ const masterStatus = alive ? readStatusFile(HARNESSD_STATUS_FILE, pid) : null
+ const master = daemonStatus == null ? describeMasterStatus(masterStatus) : null
printInfoBlock({
// The backend link is the daemon's own business, so `status` is where it is read — `start` no
// longer waits to see it, and a daemon with no backend is still serving every local agent.
@@ -5347,6 +5380,7 @@ async function status(): Promise<void> {
? '● running · backend connected'
: '● running · backend offline — retrying in the background',
pid: pid ?? 0,
+ supervisor: masterStatus?.platform && supervisorRow(masterStatus.platform),
machineId: session?.machineId,
sessions: daemonStatus?.sessions ?? 0,
// A stopped daemon answers nothing, so this falls back to the local build — which is what will run.
@@ -5755,6 +5789,10 @@ switch (cmd) {
case 'stop':
stop().catch(onError)
break
+ case 'service':
+ serviceCommand(rest, serviceCommandDeps({ relaunch: () => launch(false), tildify }))
+ .then((code) => { process.exitCode = code }).catch(onError)
+ break
case 'reset':
resetCommand().catch(onError)
break
diff --git a/cli/src/cliCommand.spec.ts b/cli/src/cliCommand.spec.ts
index 72dd95209..d0657d34e 100644
--- a/cli/src/cliCommand.spec.ts
+++ b/cli/src/cliCommand.spec.ts
@@ -1,11 +1,12 @@
import { spawn, spawnSync, type ChildProcess } from 'child_process'
-import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs'
import { createServer, type RequestListener, type Server } from 'node:http'
import type { AddressInfo } from 'node:net'
import { join } from 'path'
import { fileURLToPath } from 'url'
import { afterEach, describe, expect, it } from 'vitest'
import { listenLocalSocket, localSocketPath } from './lib/localSocket.js'
+import { fakePlatform } from './testing/fakePlatform.js'
const CLI_ROOT = fileURLToPath(new URL('..', import.meta.url))
const CLI_SOURCE = join(CLI_ROOT, 'src', 'cli.ts')
@@ -298,3 +299,66 @@ describe('start beside a daemon that serves another account', () => {
.resolves.toBe('alive')
}, 20_000)
})
+
+describe('harness service, through the CLI', () => {
+ // The whole command as a person runs it, on a throwaway home with fake launchctl or systemctl ALONE
+ // on PATH: nothing can reach this machine's launchd or systemd, or the person's daemon.
+ const platform = process.platform === 'darwin' ? 'launchd' : 'systemd'
+ const standIns: number[] = []
+ afterEach(() => { for (const pid of standIns.splice(0)) { try { process.kill(pid, 'SIGKILL') } catch { /* gone */ } } })
+
+ /** A process standing in for the master the platform starts. Not this test's child, so it is reaped
+ * the moment the fake platform stops it. */
+ function standIn(): number {
+ const spawned = spawnSync(process.execPath, ['-e', `
+ const c = require('node:child_process').spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { detached: true, stdio: 'ignore' })
+ c.unref(); console.log(c.pid)
+ `], { encoding: 'utf8' })
+ const pid = Number(spawned.stdout.trim())
+ standIns.push(pid)
+ return pid
+ }
+
+ it.skipIf(platform === 'systemd' && process.platform !== 'linux')('installs, reports, stops through the platform and uninstalls', async () => {
+ const root = freshRoot()
+ const master = standIn()
+ const fake = fakePlatform(join(root, 'bin'), { pidFile: join(root, 'data', 'adapter.pid'), nextPid: master, killable: [master] })
+ mkdirSync(join(root, 'cli'), { recursive: true })
+ writeFileSync(join(root, 'cli', 'cli.js'), '// the installed bundle\n')
+ const extra = { PATH: fake.bin, XDG_CONFIG_HOME: join(root, '.config') }
+ const file = platform === 'launchd'
+ ? join(root, 'Library', 'LaunchAgents', 'ai.autonomous.harness.harnessd.plist')
+ : join(root, '.config', 'systemd', 'user', 'harnessd.service')
+
+ const before = await runAsync(root, ['service', 'status', '--json'], extra)
+ expect(before.status, before.stderr).toBe(0)
+ expect(JSON.parse(before.stdout)).toMatchObject({ supported: true, platform, file, installed: false, registered: false })
+
+ const install = await runAsync(root, ['service', 'install'], extra)
+ expect(install.status, install.stderr).toBe(0)
+ expect(install.stdout).toContain(`✓ harnessd runs under ${platform} (pid ${master})`)
+ expect(readFileSync(file, 'utf8')).toContain(join(root, 'data', 'harness.log'))
+ expect(readFileSync(file, 'utf8')).toContain(join(root, 'cli', 'cli.js'))
+
+ const status = await runAsync(root, ['service', 'status'], extra)
+ expect(status.stdout).toContain(`● running (pid ${master})`)
+
+ // What the master writes when the platform runs it; `harness status` names its supervisor.
+ writeFileSync(join(root, 'data', 'harnessd-status.json'), JSON.stringify({ state: 'running', masterPid: master, platform }))
+ const machine = await runAsync(root, ['status'], extra)
+ expect(machine.stdout).toMatch(new RegExp(`supervisor +${platform} · starts at login, comes back if it dies`))
+
+ const stop = await runAsync(root, ['stop'], extra)
+ expect(stop.stdout).toContain(`machine stopped (pid ${master})`)
+ expect(fake.calls().map((call) => call.join(' '))).toContainEqual(platform === 'launchd'
+ ? expect.stringMatching(/^launchctl bootout gui\/\d+\/ai\.autonomous\.harness\.harnessd$/)
+ : 'systemctl --user kill --kill-who=main --signal=SIGTERM harnessd.service')
+ expect(fake.state().pid).toBeNull()
+
+ const uninstall = await runAsync(root, ['service', 'uninstall'], extra)
+ expect(uninstall.status, uninstall.stderr).toBe(0)
+ expect(uninstall.stdout).toContain(`no longer runs harnessd`)
+ expect(uninstall.stdout).not.toContain('starting it the usual way')
+ expect(existsSync(file)).toBe(false)
+ }, 60_000)
+})
diff --git a/cli/src/harnessd/AGENTS.md b/cli/src/harnessd/AGENTS.md
index 82ce990f6..896b8b179 100644
--- a/cli/src/harnessd/AGENTS.md
+++ b/cli/src/harnessd/AGENTS.md
@@ -1,6 +1,7 @@
# harnessd's master
-The process `harness start` launches. It keeps the core and the services running, and nothing else.
+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
@@ -14,3 +15,8 @@ The process `harness start` launches. It keeps the core and the services running
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, 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.
diff --git a/cli/src/harnessd/master.spec.ts b/cli/src/harnessd/master.spec.ts
index 17552b76c..49e406c11 100644
--- a/cli/src/harnessd/master.spec.ts
+++ b/cli/src/harnessd/master.spec.ts
@@ -262,6 +262,36 @@ describe('runMaster', () => {
expect(readStatusFile(statusFile, process.pid)).toMatchObject({ state: 'stopped', lastExitReason: 'stopped' })
})
+ it('says in its status file when launchd or systemd runs it, so `harness stop` asks the platform', async () => {
+ const pidFile = join(dir, 'adapter.pid')
+ const statusFile = join(dir, 'harnessd-status.json')
+ const logged = join(dir, 'master.log')
+ const core = join(dir, 'core.cjs')
+ writeFileSync(core, `
+ process.send({ type: 'harnessd:bound', protocol: 2, port: 1 })
+ process.send({ type: 'harnessd:ready' })
+ setInterval(() => process.send({ type: 'harnessd:heartbeat', rssBytes: 1, heapUsedBytes: 1, loopDelayMs: 0 }), 50)
+ process.on('SIGTERM', () => process.exit(0))
+ `)
+ const exits: number[] = []
+ const signals = new Map<string, () => void>()
+ const log = vi.spyOn(console, 'log').mockImplementation((line: string) => { writeFileSync(logged, `${line}\n`, { flag: 'a' }) })
+ try {
+ runMaster({
+ nodePath: process.execPath, execArgv: [], scriptPath: core, pidFile, statusFile,
+ restoreUpdate: () => {}, confirmUpdate: () => {},
+ env: { ...process.env, HARNESSD_PLATFORM: 'launchd' },
+ exit: (code) => exits.push(code), onSignal: (signal, listener) => signals.set(signal, listener),
+ })
+ await until('the core to be ready', () => readStatusFile(statusFile, process.pid)?.state === 'running')
+ expect(readStatusFile(statusFile, process.pid)).toMatchObject({ platform: 'launchd' })
+ expect(readFileSync(logged, 'utf8')).toContain('[harnessd] run by launchd, which starts this master again if it dies')
+ signals.get('SIGTERM')!()
+ await until('the master to finish', () => exits.length > 0)
+ } finally { log.mockRestore() }
+ expect(exits).toEqual([0])
+ })
+
it('runs the services it is told to beside the core, with one token for both, restarts them, and stops them with it', async () => {
const pidFile = join(dir, 'adapter.pid')
const seen = join(dir, 'seen')
diff --git a/cli/src/harnessd/master.ts b/cli/src/harnessd/master.ts
index 9fcb7b800..f737eb2bc 100644
--- a/cli/src/harnessd/master.ts
+++ b/cli/src/harnessd/master.ts
@@ -8,6 +8,7 @@ import { randomBytes } from 'node:crypto'
import { readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
import { performance } from 'node:perf_hooks'
import { trimLogFile } from '../lib/log.js'
+import { platformFromEnv, type PlatformName } from './platform.js'
import type { MasterMessage } from './protocol.js'
import { KNOWN_SERVICES, ServiceSupervisor, serviceOptions, serviceSpecs } from './services.js'
import { DEFAULT_SUPERVISOR_OPTIONS, Supervisor, type CoreHandle, type SupervisorOptions, type SupervisorStatus } from './supervisor.js'
@@ -94,7 +95,7 @@ export function coreExecArgv(execArgv: readonly string[], heapLimitMiB: number):
* is crash-looping, restarting, or in safe mode. Written whole and renamed into place, so a reader
* never sees half of it.
*/
-export function writeStatusFile(file: string, status: SupervisorStatus & { masterPid: number }): void {
+export function writeStatusFile(file: string, status: MasterStatusFile): void {
const temp = `${file}.${status.masterPid}.tmp`
try {
writeFileSync(temp, `${JSON.stringify(status)}\n`)
@@ -105,7 +106,9 @@ export function writeStatusFile(file: string, status: SupervisorStatus & { maste
}
}
-export type MasterStatusFile = SupervisorStatus & { masterPid: number }
+/** `platform`: launchd or systemd runs this master (`harness service install`); absent when
+ * `harness start` or the desktop app started it. How `harness stop` knows to ask the platform. */
+export type MasterStatusFile = SupervisorStatus & { masterPid: number; platform?: PlatformName }
/** Keep `file` under its cap from now on; returns what stops it. Nothing to trim, nothing to stop. */
export function trimLogEvery(file: string | undefined, ms = LOG_TRIM_INTERVAL_MS, trim: (file: string) => boolean = trimLogFile): () => void {
@@ -174,6 +177,9 @@ export function runMaster(config: MasterConfig): Supervisor {
// one file in place would race.
const stopTrimming = trimLogEvery(config.logFile)
const log = (line: string) => console.log(`${new Date().toISOString().replace('T', ' ').slice(0, 23)} ${line}`)
+ // Set by the launchd agent or systemd unit `harness service install` writes (./platform.ts).
+ const platform = platformFromEnv(env)
+ if (platform) log(`[harnessd] run by ${platform}, which starts this master again if it dies`)
// A new one every boot, given to the core and to each service: how the core knows a service
// connection is one this master started, and no other local process.
const token = randomBytes(24).toString('hex')
@@ -195,7 +201,7 @@ export function runMaster(config: MasterConfig): Supervisor {
})),
now: () => performance.now(),
wallClock: () => Date.now(),
- writeStatus: (status) => { if (config.statusFile) writeStatusFile(config.statusFile, { ...status, masterPid: process.pid }) },
+ writeStatus: (status) => { if (config.statusFile) writeStatusFile(config.statusFile, { ...status, masterPid: process.pid, ...(platform ? { platform } : {}) }) },
setTimer: (run, ms) => setTimeout(run, ms),
clearTimer: (timer) => clearTimeout(timer as ReturnType<typeof setTimeout>),
claimPidFile: () => writeFileSync(config.pidFile, `${process.pid}\n`),
diff --git a/cli/src/harnessd/platform.spec.ts b/cli/src/harnessd/platform.spec.ts
new file mode 100644
index 000000000..6a067d372
--- /dev/null
+++ b/cli/src/harnessd/platform.spec.ts
@@ -0,0 +1,406 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { homedir, tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { fakePlatform, type FakePlatform } from '../testing/fakePlatform.js'
+import {
+ COMMAND_TIMEOUT_MS, LAUNCHD_LABEL, PLATFORM_ENV, PlatformService, RESTART_THROTTLE_S, STOP_TIMEOUT_S, SYSTEMD_UNIT,
+ currentUid, defaultPlatformDeps, launchdPlist, platformFor, platformFromEnv, systemdUnit,
+ type CommandResult, type PlatformDeps, type ServiceDefinition,
+} from './platform.js'
+
+const definition = (over: Partial<ServiceDefinition> = {}): ServiceDefinition => ({
+ nodePath: '/Users/demo/.harness/runtime/node-v22.12.0-darwin-arm64/bin/node',
+ scriptPath: '/Users/demo/.harness/cli/cli.js',
+ logFile: '/Users/demo/.harness/cli/data/harness.log',
+ home: '/Users/demo',
+ env: {},
+ ...over,
+})
+
+/** An in-memory PlatformDeps whose commands answer from a table, for what the fakes do not say. */
+function stubDeps(answers: Record<string, CommandResult>, files: Record<string, string> = {}, over: Partial<PlatformDeps> = {}) {
+ const calls: string[] = []
+ const deps: PlatformDeps = {
+ run: (command, args) => {
+ const call = [command, ...args].join(' ')
+ calls.push(call)
+ const key = Object.keys(answers).find((prefix) => call.startsWith(prefix))
+ return key ? answers[key] : { status: 0, stdout: '', stderr: '' }
+ },
+ readFile: (path) => files[path] ?? null,
+ writeFile: (path, content) => { files[path] = content },
+ removeFile: (path) => { delete files[path] },
+ uid: 501,
+ home: '/Users/demo',
+ ...over,
+ }
+ return { deps, calls, files }
+}
+
+const ok = (stdout = ''): CommandResult => ({ status: 0, stdout, stderr: '' })
+const fail = (status: number | null, stderr = '', stdout = ''): CommandResult => ({ status, stdout, stderr })
+
+describe('which platform', () => {
+ it('is launchd on macOS, systemd on Linux, and none elsewhere', () => {
+ expect(platformFor('darwin')).toBe('launchd')
+ expect(platformFor('linux')).toBe('systemd')
+ expect(platformFor('win32')).toBeNull()
+ })
+
+ it('runs the master only when its definition says so', () => {
+ expect(platformFromEnv({ [PLATFORM_ENV]: 'launchd' })).toBe('launchd')
+ expect(platformFromEnv({ [PLATFORM_ENV]: 'systemd' })).toBe('systemd')
+ expect(platformFromEnv({ [PLATFORM_ENV]: 'cron' })).toBeNull()
+ expect(platformFromEnv({})).toBeNull()
+ })
+
+ it('knows this process\'s user, and copes without one', () => {
+ expect(currentUid({ getuid: () => 501 })).toBe(501)
+ expect(currentUid({})).toBe(0)
+ expect(currentUid()).toBe(process.getuid!())
+ })
+})
+
+describe('the launchd agent', () => {
+ let dir: string
+ beforeEach(() => { dir = mkdtempSync(join(tmpdir(), 'harnessd-plist-')) })
+ afterEach(() => rmSync(dir, { recursive: true, force: true }))
+
+ it('runs the master in the foreground, keeps it alive after a crash, logs to the daemon log and lets tmux outlive it', () => {
+ const plist = launchdPlist(definition({ env: { ADAPTER_DATA_DIR: '/Users/demo/data' } }))
+ expect(plist).toContain(`<string>${LAUNCHD_LABEL}</string>`)
+ expect(plist).toMatch(/<key>ProgramArguments<\/key>\s*<array>\s*<string>\/Users\/demo\/\.harness\/runtime\/node-v22\.12\.0-darwin-arm64\/bin\/node<\/string>\s*<string>\/Users\/demo\/\.harness\/cli\/cli\.js<\/string>\s*<string>__harnessd<\/string>\s*<\/array>/)
+ expect(plist).toMatch(/<key>KeepAlive<\/key>\s*<dict>\s*<key>SuccessfulExit<\/key>\s*<false\/>\s*<key>Crashed<\/key>\s*<true\/>\s*<\/dict>/)
+ expect(plist).toMatch(/<key>AbandonProcessGroup<\/key>\s*<true\/>/)
+ expect(plist).toMatch(new RegExp(`<key>ThrottleInterval</key>\\s*<integer>${RESTART_THROTTLE_S}</integer>`))
+ expect(plist).toMatch(/<key>StandardOutPath<\/key>\s*<string>\/Users\/demo\/\.harness\/cli\/data\/harness\.log<\/string>\s*<key>StandardErrorPath<\/key>\s*<string>\/Users\/demo\/\.harness\/cli\/data\/harness\.log<\/string>/)
+ expect(plist).toMatch(/<key>HARNESSD_PLATFORM<\/key>\s*<string>launchd<\/string>/)
+ expect(plist).toMatch(/<key>ADAPTER_DATA_DIR<\/key>\s*<string>\/Users\/demo\/data<\/string>/)
+ })
+
+ it('escapes what XML would misread', () => {
+ const plist = launchdPlist(definition({ home: '/Users/d&<m>"o\'', env: { WEIRD: '<&>' } }))
+ expect(plist).toContain('<string>/Users/d&amp;&lt;m&gt;&quot;o&apos;</string>')
+ expect(plist).toContain('<string>&lt;&amp;&gt;</string>')
+ })
+
+ // plutil reads it exactly as launchd will: the dictionary below is what launchd is given.
+ it.skipIf(!existsSync('/usr/bin/plutil'))('is a property list plutil accepts, holding exactly what it means to', () => {
+ const file = join(dir, `${LAUNCHD_LABEL}.plist`)
+ writeFileSync(file, launchdPlist(definition({ home: '/Users/d&mo', env: { PORT: '18474' } })))
+ const lint = spawnSync('/usr/bin/plutil', ['-lint', file], { encoding: 'utf8' })
+ expect(lint.status, lint.stdout + lint.stderr).toBe(0)
+ const parsed = JSON.parse(spawnSync('/usr/bin/plutil', ['-convert', 'json', '-o', '-', file], { encoding: 'utf8' }).stdout)
+ expect(parsed).toEqual({
+ Label: LAUNCHD_LABEL,
+ ProgramArguments: [definition().nodePath, definition().scriptPath, '__harnessd'],
+ EnvironmentVariables: { PORT: '18474', HARNESSD_PLATFORM: 'launchd' },
+ WorkingDirectory: '/Users/d&mo',
+ RunAtLoad: true,
+ KeepAlive: { SuccessfulExit: false, Crashed: true },
+ ThrottleInterval: RESTART_THROTTLE_S,
+ ExitTimeOut: STOP_TIMEOUT_S,
+ AbandonProcessGroup: true,
+ ProcessType: 'Interactive',
+ StandardOutPath: definition().logFile,
+ StandardErrorPath: definition().logFile,
+ })
+ })
+
+ it('refuses a relative path, a path across lines, and a variable it cannot carry', () => {
+ expect(() => launchdPlist(definition({ nodePath: 'node' }))).toThrow(/node path/)
+ expect(() => launchdPlist(definition({ logFile: '/tmp/a\nb.log' }))).toThrow(/log path/)
+ expect(() => launchdPlist(definition({ env: { 'NOT A NAME': '1' } }))).toThrow(/cannot carry/)
+ expect(() => systemdUnit(definition({ env: { OK: 'two\nlines' } }))).toThrow(/cannot carry/)
+ })
+})
+
+describe('the systemd unit', () => {
+ it('runs the master in the foreground, restarts it on failure, logs to the daemon log and stops only the master', () => {
+ const unit = systemdUnit(definition({ nodePath: '/home/demo/.harness/runtime/node/bin/node', scriptPath: '/home/demo/.harness/cli/cli.js', logFile: '/home/demo/.harness/cli/data/harness.log', home: '/home/demo' }))
+ const lines = unit.split('\n')
+ expect(lines).toContain('ExecStart="/home/demo/.harness/runtime/node/bin/node" "/home/demo/.harness/cli/cli.js" "__harnessd"')
+ expect(lines).toContain('Environment="HARNESSD_PLATFORM=systemd"')
+ expect(lines).toContain('Restart=on-failure')
+ expect(lines).toContain('KillMode=process')
+ expect(lines).toContain(`TimeoutStopSec=${STOP_TIMEOUT_S}`)
+ expect(lines).toContain('StandardOutput=append:/home/demo/.harness/cli/data/harness.log')
+ expect(lines).toContain('StandardError=append:/home/demo/.harness/cli/data/harness.log')
+ expect(lines).toContain('WorkingDirectory=/home/demo')
+ expect(lines).toContain('WantedBy=default.target')
+ expect(lines.indexOf('[Unit]')).toBeLessThan(lines.indexOf('[Service]'))
+ expect(lines.indexOf('[Service]')).toBeLessThan(lines.indexOf('[Install]'))
+ // Every setting line belongs to a section and is a key=value pair; the rest are comments.
+ for (const line of lines.filter((line) => line && !line.startsWith('#') && !line.startsWith('['))) expect(line).toMatch(/^[A-Za-z]+=/)
+ })
+
+ it('escapes systemd\'s specifiers, its variables and its quotes', () => {
+ const unit = systemdUnit(definition({ nodePath: '/opt/my node/100%/$HOME/"q"\\b/node', scriptPath: '/opt/$cli/cli.js', home: '/home/50%', logFile: '/logs/50%.log', env: { A: 'x"y%z$w\\v' } }))
+ // The program is substituted for no variable, so its `$` stays single; an argument's is doubled.
+ expect(unit).toContain('ExecStart="/opt/my node/100%%/$HOME/\\"q\\"\\\\b/node" "/opt/$$cli/cli.js" "__harnessd"')
+ expect(unit).toContain('Environment="A=x\\"y%%z$w\\\\v"')
+ expect(unit).toContain('WorkingDirectory=/home/50%%')
+ expect(unit).toContain('StandardOutput=append:/logs/50%%.log')
+ })
+
+ const analyze = ['/usr/bin/systemd-analyze', '/bin/systemd-analyze'].find((path) => existsSync(path))
+ it.skipIf(!analyze)('passes systemd-analyze verify', () => {
+ const dir = mkdtempSync(join(tmpdir(), 'harnessd-unit-'))
+ try {
+ const script = join(dir, 'cli.js')
+ writeFileSync(script, '')
+ const unit = join(dir, SYSTEMD_UNIT)
+ writeFileSync(unit, systemdUnit(definition({ nodePath: process.execPath, scriptPath: script, logFile: join(dir, 'harness.log'), home: dir })))
+ const verify = spawnSync(analyze!, ['verify', unit], { encoding: 'utf8' })
+ expect(verify.status, verify.stdout + verify.stderr).toBe(0)
+ } finally { rmSync(dir, { recursive: true, force: true }) }
+ })
+})
+
+describe('the default dependencies', () => {
+ let dir: string
+ let fake: FakePlatform
+ beforeEach(() => {
+ dir = mkdtempSync(join(tmpdir(), 'harnessd-deps-'))
+ fake = fakePlatform(join(dir, 'bin'))
+ })
+ afterEach(() => rmSync(dir, { recursive: true, force: true }))
+
+ it('run commands from the PATH they are given, and say when one is not there', () => {
+ const deps = defaultPlatformDeps({ env: { PATH: fake.bin }, uid: 501, home: join(dir, 'home') })
+ expect(deps.run('loginctl', ['show-user', '501', '--property=Linger'])).toEqual({ status: 0, stdout: 'Linger=yes\n', stderr: '' })
+ expect(fake.calls()).toEqual([['loginctl', 'show-user', '501', '--property=Linger']])
+ const missing = deps.run('plutil', ['-lint', 'x'])
+ expect(missing.status).toBeNull()
+ expect(missing.stdout).toBe('')
+ expect(missing.error).toMatch(/ENOENT/)
+ expect(COMMAND_TIMEOUT_MS).toBeGreaterThan(STOP_TIMEOUT_S * 1000)
+ })
+
+ it('write whole, into a folder they make, readable by launchd and by nobody else to write', () => {
+ const deps = defaultPlatformDeps({ env: { PATH: fake.bin }, uid: 501, home: join(dir, 'home') })
+ const file = join(dir, 'home', 'Library', 'LaunchAgents', 'x.plist')
+ expect(deps.readFile(file)).toBeNull()
+ deps.writeFile(file, 'one')
+ deps.writeFile(file, 'two')
+ expect(deps.readFile(file)).toBe('two')
+ expect(statSync(file).mode & 0o022).toBe(0)
+ deps.removeFile(file)
+ deps.removeFile(file)
+ expect(existsSync(file)).toBe(false)
+ })
+
+ it('take this process\'s user, home and environment unless told otherwise, and an absolute XDG_CONFIG_HOME only', () => {
+ const own = defaultPlatformDeps()
+ expect(own.uid).toBe(process.getuid!())
+ expect(own.home).toBe(homedir())
+ expect(defaultPlatformDeps({ env: { XDG_CONFIG_HOME: '/x/config' }, uid: 1, home: '/h' }).configHome).toBe('/x/config')
+ expect(defaultPlatformDeps({ env: { XDG_CONFIG_HOME: 'relative' }, uid: 1, home: '/h' }).configHome).toBeUndefined()
+ expect(defaultPlatformDeps({ env: {}, uid: 1, home: '/h' }).configHome).toBeUndefined()
+ })
+})
+
+describe('PlatformService over fake launchctl', () => {
+ let dir: string
+ let home: string
+ let fake: FakePlatform
+ let service: PlatformService
+ beforeEach(() => {
+ dir = mkdtempSync(join(tmpdir(), 'harnessd-launchd-'))
+ home = join(dir, 'home')
+ fake = fakePlatform(join(dir, 'bin'))
+ service = new PlatformService('launchd', defaultPlatformDeps({ env: { PATH: fake.bin }, uid: 501, home }))
+ })
+ afterEach(() => rmSync(dir, { recursive: true, force: true }))
+ const verbs = () => fake.calls().map((call) => call.slice(0, 2).join(' '))
+
+ it('lives in ~/Library/LaunchAgents under its label, in the user\'s GUI domain', () => {
+ expect(service.file).toBe(join(home, 'Library', 'LaunchAgents', `${LAUNCHD_LABEL}.plist`))
+ expect(service.target).toBe(`gui/501/${LAUNCHD_LABEL}`)
+ })
+
+ it('writes its definition once, knows it as this data folder\'s, and rewrites it only when it changes', () => {
+ const def = definition({ home })
+ expect(service.installed()).toBe(false)
+ expect(service.ownedBy(def.logFile)).toBe(false)
+ expect(service.write(def)).toBe(true)
+ expect(service.write(def)).toBe(false)
+ expect(service.installed()).toBe(true)
+ expect(service.current(def)).toBe(true)
+ expect(service.ownedBy(def.logFile)).toBe(true)
+ expect(service.ownedBy('/elsewhere/harness.log')).toBe(false)
+ expect(service.current({ ...def, nodePath: '/other/node' })).toBe(false)
+ expect(service.write({ ...def, nodePath: '/other/node' })).toBe(true)
+ expect(readFileSync(service.file, 'utf8')).toContain('<string>/other/node</string>')
+ })
+
+ it('registers, starts, stops and unregisters through bootstrap, kickstart and bootout', () => {
+ const def = definition({ home })
+ expect(service.preflight()).toEqual({ ok: true })
+ expect(service.inspect()).toMatchObject({ registered: false, pid: null, installed: false, unreachable: null })
+ service.write(def)
+ expect(service.register()).toEqual({ ok: true })
+ expect(service.inspect()).toMatchObject({ installed: true, registered: true, pid: 4242, state: 'running', lastExit: '(never exited)', failed: false, linger: null })
+ expect(service.stop()).toEqual({ ok: true })
+ expect(service.inspect()).toMatchObject({ registered: false, pid: null })
+ expect(service.stop()).toEqual({ ok: true }) // nothing loaded: nothing to boot out
+ expect(service.start(false)).toEqual({ ok: true }) // not loaded: loaded again, which starts it
+ fake.set({ pid: null, nextPid: 4343 })
+ expect(service.inspect()).toMatchObject({ registered: true, pid: null, state: 'not running', lastExit: '1' })
+ expect(service.start(false)).toEqual({ ok: true }) // loaded: kickstarted
+ expect(service.inspect().pid).toBe(4343)
+ expect(service.start(true)).toEqual({ ok: true }) // rewritten: booted out and loaded from the new file
+ expect(service.unregister()).toEqual({ ok: true })
+ expect(existsSync(service.file)).toBe(false)
+ expect(verbs()).toEqual([
+ 'launchctl print', 'launchctl print', 'launchctl enable', 'launchctl bootstrap', 'launchctl print',
+ 'launchctl print', 'launchctl bootout', 'launchctl print', 'launchctl print',
+ 'launchctl print', 'launchctl bootstrap', 'launchctl print',
+ 'launchctl print', 'launchctl kickstart', 'launchctl print',
+ 'launchctl print', 'launchctl bootout', 'launchctl bootstrap',
+ 'launchctl print', 'launchctl bootout',
+ ])
+ expect(fake.calls()).toContainEqual(['launchctl', 'bootstrap', 'gui/501', service.file])
+ expect(fake.calls()).toContainEqual(['launchctl', 'enable', `gui/501/${LAUNCHD_LABEL}`])
+ })
+
+ it('says why when launchd will not take it', () => {
+ fake.set({ guiDomain: false })
+ expect(service.preflight()).toEqual({ ok: false, detail: expect.stringMatching(/^launchctl print gui\/501 failed \(exit 113\): Could not find domain.* logged in at the screen$/) })
+ service.write(definition({ home }))
+ expect(service.register()).toEqual({ ok: false, detail: expect.stringContaining('Bootstrap failed: 125') })
+ fake.set({ guiDomain: true, fail: { 'launchctl enable': { status: 1, stderr: 'not permitted' } } })
+ expect(service.register()).toEqual({ ok: false, detail: 'launchctl enable gui/501/ai.autonomous.harness.harnessd failed (exit 1): not permitted' })
+ fake.set({ fail: { 'launchctl bootout': { status: 5, stderr: 'Boot-out failed: 5: Input/output error' } }, loaded: true })
+ expect(service.start(true)).toEqual({ ok: false, detail: expect.stringContaining('Boot-out failed: 5') })
+ expect(service.unregister()).toEqual({ ok: false, detail: expect.stringContaining('Boot-out failed: 5') })
+ expect(existsSync(service.file)).toBe(true)
+ })
+
+ it('reports launchd unreachable when launchctl cannot be run at all', () => {
+ const lost = new PlatformService('launchd', defaultPlatformDeps({ env: { PATH: join(dir, 'empty') }, uid: 501, home }))
+ expect(lost.inspect()).toMatchObject({ registered: false, unreachable: expect.stringMatching(/^launchctl print gui\/501\/ai\.autonomous\.harness\.harnessd could not be run: .*ENOENT/) })
+ expect(lost.start(false)).toEqual({ ok: false, detail: expect.stringContaining('could not be run') })
+ })
+})
+
+describe('PlatformService over fake systemctl', () => {
+ let dir: string
+ let home: string
+ let fake: FakePlatform
+ let service: PlatformService
+ beforeEach(() => {
+ dir = mkdtempSync(join(tmpdir(), 'harnessd-systemd-'))
+ home = join(dir, 'home')
+ fake = fakePlatform(join(dir, 'bin'))
+ service = new PlatformService('systemd', defaultPlatformDeps({ env: { PATH: fake.bin }, uid: 1000, home }))
+ })
+ afterEach(() => rmSync(dir, { recursive: true, force: true }))
+ const verbs = () => fake.calls().map((call) => (call[0] === 'systemctl' ? [call[0], call[2]] : call.slice(0, 2)).join(' '))
+
+ it('lives in ~/.config/systemd/user, or under XDG_CONFIG_HOME', () => {
+ expect(service.file).toBe(join(home, '.config', 'systemd', 'user', SYSTEMD_UNIT))
+ expect(service.target).toBe(SYSTEMD_UNIT)
+ const xdg = new PlatformService('systemd', defaultPlatformDeps({ env: { PATH: fake.bin, XDG_CONFIG_HOME: join(dir, 'xdg') }, uid: 1000, home }))
+ expect(xdg.file).toBe(join(dir, 'xdg', 'systemd', 'user', SYSTEMD_UNIT))
+ })
+
+ it('knows a unit as this data folder\'s by its log', () => {
+ const def = definition({ home })
+ service.write(def)
+ expect(service.ownedBy(def.logFile)).toBe(true)
+ expect(service.ownedBy('/elsewhere/harness.log')).toBe(false)
+ })
+
+ it('registers with enable --now, starts, and stops and unregisters without a stop job', () => {
+ const def = definition({ home })
+ expect(service.preflight()).toEqual({ ok: true })
+ expect(service.inspect()).toMatchObject({ registered: false, pid: null, state: 'inactive (dead)', failed: false, lastExit: null, linger: true })
+ service.write(def)
+ expect(service.register()).toEqual({ ok: true })
+ expect(service.inspect()).toMatchObject({ installed: true, registered: true, pid: 4242, state: 'active (running)' })
+ expect(service.stop()).toEqual({ ok: true })
+ expect(service.inspect()).toMatchObject({ registered: true, pid: null })
+ expect(service.start(false)).toEqual({ ok: true })
+ expect(service.start(true)).toEqual({ ok: true })
+ fake.set({ failed: true, pid: null, linger: 'no' })
+ expect(service.inspect()).toMatchObject({ failed: true, state: 'failed (failed)', lastExit: 'start-limit-hit', linger: false })
+ expect(service.unregister()).toEqual({ ok: true })
+ expect(existsSync(service.file)).toBe(false)
+ expect(verbs()).toEqual([
+ 'systemctl daemon-reload', 'systemctl show', 'loginctl show-user',
+ 'systemctl daemon-reload', 'systemctl enable', 'systemctl show', 'loginctl show-user',
+ 'systemctl show', 'systemctl kill', 'systemctl show', 'loginctl show-user',
+ 'systemctl reset-failed', 'systemctl start',
+ 'systemctl daemon-reload', 'systemctl reset-failed', 'systemctl start',
+ 'systemctl show', 'loginctl show-user',
+ 'systemctl disable', 'systemctl show', 'systemctl daemon-reload', 'systemctl reset-failed',
+ ])
+ expect(fake.calls()).toContainEqual(['systemctl', '--user', 'enable', '--now', SYSTEMD_UNIT])
+ expect(fake.calls()).toContainEqual(['systemctl', '--user', 'kill', '--kill-who=main', '--signal=SIGTERM', SYSTEMD_UNIT])
+ expect(fake.calls()).toContainEqual(['systemctl', '--user', 'disable', SYSTEMD_UNIT])
+ // A stop job would be passed to every pane scope PartOf this unit: none is ever sent.
+ for (const call of fake.calls()) expect(call.filter((word) => ['stop', 'restart', '--now'].includes(word) && call[2] !== 'enable')).toEqual([])
+ })
+
+ it('stops a unit whose file is already gone, and says why when systemd will not take it', () => {
+ expect(service.unregister()).toEqual({ ok: true })
+ expect(fake.calls()[0]).toEqual(['systemctl', '--user', 'show', SYSTEMD_UNIT, '--property=MainPID'])
+ fake.set({ pid: 4242 })
+ expect(service.unregister()).toEqual({ ok: true })
+ expect(fake.calls()).toContainEqual(['systemctl', '--user', 'kill', '--kill-who=main', '--signal=SIGTERM', SYSTEMD_UNIT])
+ fake.set({ pid: 4242, fail: { 'systemctl kill': { status: 1, stderr: 'Access denied' } } })
+ expect(service.unregister()).toEqual({ ok: false, detail: expect.stringContaining('Access denied') })
+ fake.set({ pid: null, fail: {} })
+ fake.set({ fail: { 'systemctl daemon-reload': { status: 1, stderr: 'Failed to connect to bus: No medium found' } } })
+ expect(service.preflight()).toEqual({ ok: false, detail: 'systemctl --user daemon-reload failed (exit 1): Failed to connect to bus: No medium found' })
+ expect(service.register()).toMatchObject({ ok: false })
+ expect(service.start(true)).toMatchObject({ ok: false })
+ service.write(definition({ home }))
+ fake.set({ fail: { 'systemctl disable': { status: 1, stderr: 'Access denied' } } })
+ expect(service.unregister()).toEqual({ ok: false, detail: expect.stringContaining('Access denied') })
+ expect(existsSync(service.file)).toBe(true)
+ fake.set({ fail: { 'systemctl show': { status: 1, stderr: 'Failed to connect to bus' } }, linger: null })
+ expect(service.inspect()).toMatchObject({ registered: false, linger: null, unreachable: expect.stringContaining('Failed to connect to bus') })
+ })
+})
+
+describe('discarding a definition that could not be registered', () => {
+ it('removes the file alone, and has systemd forget it', () => {
+ for (const platform of ['launchd', 'systemd'] as const) {
+ const { deps, calls, files } = stubDeps({})
+ const service = new PlatformService(platform, deps)
+ service.write(definition())
+ service.discard()
+ expect(files).toEqual({})
+ expect(calls).toEqual(platform === 'systemd' ? ['systemctl --user daemon-reload'] : [])
+ }
+ })
+})
+
+describe('reading what the platform says', () => {
+ it('takes launchd\'s listing as it comes: no state, no pid, no last exit', () => {
+ const { deps } = stubDeps({ 'launchctl print': ok('gui/501/x = {\n\tactive count = 0\n}\n') })
+ expect(new PlatformService('launchd', deps).inspect()).toMatchObject({ registered: true, pid: null, state: null, lastExit: null })
+ })
+
+ it('takes systemctl show as it comes: no active state, no sub-state, odd lines, an unknown linger', () => {
+ const { deps } = stubDeps({
+ 'systemctl --user show': ok('=orphan\nnot a property\nUnitFileState=disabled\nMainPID=0\n'),
+ 'loginctl': ok('Linger=maybe\n'),
+ })
+ expect(new PlatformService('systemd', deps).inspect()).toMatchObject({ registered: false, pid: null, state: null, lastExit: null, linger: null })
+ const { deps: active } = stubDeps({ 'systemctl --user show': ok('ActiveState=active\nResult=\n') })
+ expect(new PlatformService('systemd', active).inspect()).toMatchObject({ state: 'active', lastExit: null })
+ })
+
+ it('says how a command failed: killed with no status, silent, or speaking only on stdout', () => {
+ const { deps } = stubDeps({ 'launchctl kickstart': fail(null), 'launchctl print gui/501/': ok('state = running\n'), 'launchctl bootstrap': fail(5, '', 'on stdout\nmore') })
+ const service = new PlatformService('launchd', deps)
+ expect(service.start(false)).toEqual({ ok: false, detail: 'launchctl kickstart gui/501/ai.autonomous.harness.harnessd failed (exit none)' })
+ const { deps: unloaded } = stubDeps({ 'launchctl print': fail(113), 'launchctl bootstrap': fail(5, '', 'on stdout\nmore') })
+ expect(new PlatformService('launchd', unloaded).start(false)).toEqual({ ok: false, detail: 'launchctl bootstrap gui/501 /Users/demo/Library/LaunchAgents/ai.autonomous.harness.harnessd.plist failed (exit 5): on stdout' })
+ })
+})
diff --git a/cli/src/harnessd/platform.ts b/cli/src/harnessd/platform.ts
new file mode 100644
index 000000000..0f3a19e75
--- /dev/null
+++ b/cli/src/harnessd/platform.ts
@@ -0,0 +1,518 @@
+/**
+ * Something supervises the supervisor: on macOS a launchd user agent, on Linux a systemd user unit, runs
+ * the master in the foreground and starts it again if it dies (docs/design/2026-10-03-harnessd.md,
+ * "Supervision"). Before this, nothing restarted a master that died but the desktop app running
+ * `harness start` again, up to a minute later, and on a computer without the app nothing did.
+ *
+ * Opt-in, through `harness service install` (src/lib/serviceCommand.ts). Nothing here runs for anyone
+ * who has not asked for it, and the desktop app does not use it yet.
+ *
+ * This file writes and removes the definition (the agent's plist, the unit file) and registers it with
+ * launchctl or systemctl. Everything it does to the operating system goes through `PlatformDeps`, so
+ * the tests run it against a temporary home and fake launchctl and systemctl binaries, never against
+ * this machine's.
+ */
+import { spawnSync } from 'node:child_process'
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, isAbsolute, join } from 'node:path'
+
+export type PlatformName = 'launchd' | 'systemd'
+
+/**
+ * Set by the definition, so the master knows the platform runs it and says so in its status file. The
+ * CLI does not read it from its own environment: a shell in a tmux pane the daemon started inherits it,
+ * and would otherwise believe it was the platform.
+ */
+export const PLATFORM_ENV = 'HARNESSD_PLATFORM'
+
+export const LAUNCHD_LABEL = 'ai.autonomous.harness.harnessd'
+export const SYSTEMD_UNIT = 'harnessd.service'
+
+/**
+ * launchd starts the job at most once every this many seconds (its own default, written down so it
+ * does not move under us); systemd waits this long before a restart. A master that dies after running
+ * a while is started again at once; one that cannot start at all is tried every ten seconds by launchd,
+ * and left failed by systemd after five tries in a minute rather than looped.
+ */
+export const RESTART_THROTTLE_S = 10
+export const SYSTEMD_RESTART_S = 2
+/** How long the platform gives the master to stop before it kills it: well past the master's own
+ * ordered stop (the core gets 2.5 s, the services 1.5 s beside it). */
+export const STOP_TIMEOUT_S = 10
+/** A launchctl or systemctl call that takes longer than this is reported as failed, never waited on. */
+export const COMMAND_TIMEOUT_MS = 30_000
+
+/** The platform that would supervise harnessd on this operating system; null where neither runs. */
+export function platformFor(os: NodeJS.Platform): PlatformName | null {
+ return os === 'darwin' ? 'launchd' : os === 'linux' ? 'systemd' : null
+}
+
+/** The platform running this master, as its definition says; null when `harness start` or the desktop
+ * app started it. */
+export function platformFromEnv(env: NodeJS.ProcessEnv): PlatformName | null {
+ const value = env[PLATFORM_ENV]
+ return value === 'launchd' || value === 'systemd' ? value : null
+}
+
+/** What the platform runs: `<node> <cli.js> __harnessd`, its log, and the environment it is given. */
+export interface ServiceDefinition {
+ nodePath: string
+ scriptPath: string
+ /** stdout and stderr, appended: the log `harness start` gives the master, which it trims itself. */
+ logFile: string
+ /** The working directory, the user's home: what a systemd user unit gets by default. */
+ home: string
+ /** Variables the master needs beside `PLATFORM_ENV`, already chosen by the caller. */
+ env: Record<string, string>
+}
+
+/** A path or value with a control character in it cannot be written into a unit file, and has no
+ * business in a plist either. */
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u001f\u007f]/
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+function checked(definition: ServiceDefinition): ServiceDefinition {
+ for (const [what, path] of [['node', definition.nodePath], ['cli', definition.scriptPath], ['log', definition.logFile], ['home', definition.home]] as const) {
+ if (!isAbsolute(path) || CONTROL.test(path)) throw new Error(`the ${what} path for the service must be absolute, on one line: ${JSON.stringify(path)}`)
+ }
+ for (const [name, value] of Object.entries(definition.env)) {
+ if (!ENV_NAME.test(name) || CONTROL.test(value)) throw new Error(`the service cannot carry ${JSON.stringify(name)}=${JSON.stringify(value)}`)
+ }
+ return definition
+}
+
+const xml = (text: string): string =>
+ text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&apos;')
+
+/** The launchd agent: `~/Library/LaunchAgents/<label>.plist`. */
+export function launchdPlist(definition: ServiceDefinition): string {
+ const { nodePath, scriptPath, logFile, home, env } = checked(definition)
+ const environment = Object.entries({ ...env, [PLATFORM_ENV]: 'launchd' })
+ .map(([name, value]) => `\t\t<key>${xml(name)}</key>\n\t\t<string>${xml(value)}</string>`).join('\n')
+ return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!-- harnessd, the Harness daemon, under launchd. Written by "harness service install" and removed by
+ "harness service uninstall"; "harness service status" says what launchd has registered. -->
+<plist version="1.0">
+<dict>
+ <key>Label</key>
+ <string>${LAUNCHD_LABEL}</string>
+ <!-- The master in the foreground: a launchd job must not daemonize, or launchd thinks it died. -->
+ <key>ProgramArguments</key>
+ <array>
+ <string>${xml(nodePath)}</string>
+ <string>${xml(scriptPath)}</string>
+ <string>__harnessd</string>
+ </array>
+ <key>EnvironmentVariables</key>
+ <dict>
+${environment}
+ </dict>
+ <key>WorkingDirectory</key>
+ <string>${xml(home)}</string>
+ <!-- Started at login, and again after any exit but a clean one: a crash, a kill, an uncaught error.
+ A clean exit is a stop someone asked for, or this computer signed out for good, and stays stopped. -->
+ <key>RunAtLoad</key>
+ <true/>
+ <key>KeepAlive</key>
+ <dict>
+ <key>SuccessfulExit</key>
+ <false/>
+ <key>Crashed</key>
+ <true/>
+ </dict>
+ <key>ThrottleInterval</key>
+ <integer>${RESTART_THROTTLE_S}</integer>
+ <key>ExitTimeOut</key>
+ <integer>${STOP_TIMEOUT_S}</integer>
+ <!-- launchd kills a dead job's process group by default. The agents live in tmux and must outlive
+ the daemon: nothing outside the daemon decides what lives when it stops, as when "harness start"
+ runs it. Its core and services leave by themselves when the master's channel closes. -->
+ <key>AbandonProcessGroup</key>
+ <true/>
+ <!-- A job without a ProcessType has its CPU and I/O throttled. The daemon serves panes someone is
+ typing into, and the tmux server it starts runs under the job's limits: an app's, which are none. -->
+ <key>ProcessType</key>
+ <string>Interactive</string>
+ <key>StandardOutPath</key>
+ <string>${xml(logFile)}</string>
+ <key>StandardErrorPath</key>
+ <string>${xml(logFile)}</string>
+</dict>
+</plist>
+`
+}
+
+/**
+ * One word of an ExecStart= line: quoted, with systemd's specifiers (%) escaped, and in an argument its
+ * variables ($) too. Not in the program: systemd substitutes no variable there, so it would leave `$$`
+ * as two dollars (systemd 259, checked with systemd-analyze verify).
+ */
+const execWord = (word: string, index: number): string => {
+ const quoted = word.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/%/g, '%%')
+ return `"${index === 0 ? quoted : quoted.replace(/\$/g, '$$$$')}"`
+}
+/** An Environment= assignment: quoted, specifiers escaped; `$` means nothing there. */
+const environmentWord = (name: string, value: string): string => `"${`${name}=${value}`.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/%/g, '%%')}"`
+/** A path in a setting that takes one path as its whole value: only the specifiers to escape. */
+const pathValue = (path: string): string => path.replace(/%/g, '%%')
+
+/** The systemd user unit: `~/.config/systemd/user/harnessd.service`. */
+export function systemdUnit(definition: ServiceDefinition): string {
+ const { nodePath, scriptPath, logFile, home, env } = checked(definition)
+ const environment = Object.entries({ ...env, [PLATFORM_ENV]: 'systemd' })
+ .map(([name, value]) => `Environment=${environmentWord(name, value)}`).join('\n')
+ return `# harnessd, the Harness daemon, under systemd. Written by \`harness service install\` and removed by
+# \`harness service uninstall\`; \`harness service status\` says what systemd has registered.
+[Unit]
+Description=Harness daemon (harnessd)
+Documentation=https://github.com/autonomous-ai/openharness/blob/main/docs/design/2026-10-03-harnessd.md
+# Five failed starts in a minute leave it failed rather than looping, as when its Node is gone.
+StartLimitIntervalSec=60
+StartLimitBurst=5
+
+[Service]
+# The master in the foreground. It holds no sockets of its own, so no Type=notify: its core binds them.
+Type=simple
+ExecStart=${[nodePath, scriptPath, '__harnessd'].map(execWord).join(' ')}
+${environment}
+WorkingDirectory=${pathValue(home)}
+# Started again after a crash or a kill. A clean exit is a stop someone asked for, or this computer
+# signed out for good, and stays stopped.
+Restart=on-failure
+RestartSec=${SYSTEMD_RESTART_S}
+# KillMode=process: a stop, a restart or the master's death signals the master alone. The default,
+# control-group, kills every process in this unit's cgroup, and everything the daemon starts lands in
+# it: a tmux server it starts, and with it every agent. The master stops its own core and services in
+# order, inside TimeoutStopSec, and they leave by themselves if it dies. The cleaner split would be a
+# scope of tmux's own (systemd-run --user --scope tmux ...), which this unit could then stop with
+# control-group; it means changing how the core starts tmux, and a unit that only works with that
+# change is a unit nobody can turn back. Consequences: a tmux server the daemon started is listed
+# under this unit, and systemd notes it as left over on the next start; no MemoryMax= here, which
+# would cover the agents too; and, where tmux is built with systemd support, each pane lives in a
+# scope PartOf this unit, so a stop job (systemctl --user stop or restart) stops every agent all the
+# same. \`harness stop\` signals the master instead, and its clean exit stops nothing else: use it.
+KillMode=process
+TimeoutStopSec=${STOP_TIMEOUT_S}
+# Appended, as \`harness start\` opens it; the master keeps it under its cap. append: needs systemd 240.
+StandardOutput=append:${pathValue(logFile)}
+StandardError=append:${pathValue(logFile)}
+
+[Install]
+WantedBy=default.target
+`
+}
+
+/** A launchctl, systemctl or loginctl run to its end. `error`: it could not be run at all. */
+export interface CommandResult {
+ status: number | null
+ stdout: string
+ stderr: string
+ error?: string
+}
+
+/** Everything this file does to the operating system. */
+export interface PlatformDeps {
+ /** Run a command by name, without a shell, and wait for it. */
+ run(command: string, args: string[]): CommandResult
+ /** A file's text, or null when it cannot be read. */
+ readFile(path: string): string | null
+ /** Write whole and rename into place, making the folder first. */
+ writeFile(path: string, content: string): void
+ removeFile(path: string): void
+ uid: number
+ home: string
+ /** `$XDG_CONFIG_HOME`, where systemd looks for user units first; `~/.config` when unset. */
+ configHome?: string
+}
+
+/** This process's user id; 0 where Node has no notion of one. */
+export function currentUid(proc: { getuid?: () => number } = process): number {
+ return typeof proc.getuid === 'function' ? proc.getuid() : 0
+}
+
+/**
+ * The real thing: commands looked up on `env.PATH` (Node searches the PATH of the environment it is
+ * given), files on disk. The tests hand it a PATH holding only fake binaries and a temporary home.
+ */
+export function defaultPlatformDeps(options: { env?: NodeJS.ProcessEnv; uid?: number; home?: string } = {}): PlatformDeps {
+ const env = options.env ?? process.env
+ const configHome = env.XDG_CONFIG_HOME
+ return {
+ run: (command, args) => {
+ // `launchctl print` lists the whole job, and a domain's listing runs to hundreds of kilobytes.
+ const result = spawnSync(command, args, { env, encoding: 'utf8', timeout: COMMAND_TIMEOUT_MS, maxBuffer: 32 * 1024 * 1024 })
+ return { status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? '', ...(result.error ? { error: result.error.message } : {}) }
+ },
+ readFile: (path) => { try { return readFileSync(path, 'utf8') } catch { return null } },
+ writeFile: (path, content) => {
+ mkdirSync(dirname(path), { recursive: true })
+ const temp = `${path}.${process.pid}.tmp`
+ // Not writable by others: launchd skips a plist with "dubious permissions".
+ writeFileSync(temp, content, { mode: 0o644 })
+ renameSync(temp, path)
+ },
+ removeFile: (path) => rmSync(path, { force: true }),
+ uid: options.uid ?? currentUid(),
+ home: options.home ?? homedir(),
+ ...(configHome && isAbsolute(configHome) ? { configHome } : {}),
+ }
+}
+
+/** What the platform says about harnessd. */
+export interface PlatformState {
+ platform: PlatformName
+ /** The definition's path. */
+ file: string
+ /** `gui/<uid>/<label>`, or the unit's name. */
+ target: string
+ /** The definition is on disk. */
+ installed: boolean
+ /** launchd has the job loaded; systemd has the unit enabled. */
+ registered: boolean
+ /** The master's pid, as the platform knows it. */
+ pid: number | null
+ /** The platform's own words: `running`, `not running`; `active (running)`, `failed (failed)`… */
+ state: string | null
+ /** systemd gave up on it (its start limit). */
+ failed: boolean
+ /** How the master last ended, as the platform puts it, when it says. */
+ lastExit: string | null
+ /** systemd: the user manager lingers, so the unit runs without a login session. null: launchd, or
+ * unknown. */
+ linger: boolean | null
+ /** The platform could not be asked (no user manager, no launchctl), and why. */
+ unreachable: string | null
+}
+
+export type Outcome = { ok: true } | { ok: false; detail: string }
+
+const firstLine = (text: string): string => text.trim().split('\n')[0].trim()
+
+function failure(command: string, args: string[], result: CommandResult): string {
+ const what = `${command} ${args.join(' ')}`
+ if (result.error) return `${what} could not be run: ${result.error}`
+ const said = firstLine(result.stderr) || firstLine(result.stdout)
+ return `${what} failed (exit ${result.status ?? 'none'})${said ? `: ${said}` : ''}`
+}
+
+/** `Key=Value` lines, as `systemctl show` prints them. */
+function properties(text: string): Record<string, string> {
+ const found: Record<string, string> = {}
+ for (const line of text.split('\n')) {
+ const at = line.indexOf('=')
+ if (at > 0) found[line.slice(0, at).trim()] = line.slice(at + 1).trim()
+ }
+ return found
+}
+
+/** harnessd's definition and registration on one platform. */
+export class PlatformService {
+ constructor(readonly platform: PlatformName, private readonly deps: PlatformDeps) {}
+
+ /** Where the definition lives. */
+ get file(): string {
+ return this.platform === 'launchd'
+ ? join(this.deps.home, 'Library', 'LaunchAgents', `${LAUNCHD_LABEL}.plist`)
+ : join(this.deps.configHome ?? join(this.deps.home, '.config'), 'systemd', 'user', SYSTEMD_UNIT)
+ }
+
+ /** What launchctl or systemctl is told to act on. */
+ get target(): string {
+ return this.platform === 'launchd' ? `gui/${this.deps.uid}/${LAUNCHD_LABEL}` : SYSTEMD_UNIT
+ }
+
+ render(definition: ServiceDefinition): string {
+ return this.platform === 'launchd' ? launchdPlist(definition) : systemdUnit(definition)
+ }
+
+ installed(): boolean {
+ return this.deps.readFile(this.file) !== null
+ }
+
+ /**
+ * The definition on disk runs the daemon whose log is `logFile`, that is, the daemon of this data
+ * folder. A definition written for another one (another ADAPTER_DATA_DIR) is not this CLI's to start
+ * or stop, and a test with its own data folder never acts on the person's real registration.
+ */
+ ownedBy(logFile: string): boolean {
+ const content = this.deps.readFile(this.file)
+ if (content === null) return false
+ return this.platform === 'launchd'
+ ? content.includes(`<key>StandardOutPath</key>\n\t<string>${xml(logFile)}</string>\n`)
+ : content.includes(`\nStandardOutput=append:${pathValue(logFile)}\n`)
+ }
+
+ /** The definition on disk is the one this install would write. */
+ current(definition: ServiceDefinition): boolean {
+ return this.deps.readFile(this.file) === this.render(definition)
+ }
+
+ /** Write the definition when it differs from the one on disk; says whether it did. */
+ write(definition: ServiceDefinition): boolean {
+ const content = this.render(definition)
+ if (this.deps.readFile(this.file) === content) return false
+ this.deps.writeFile(this.file, content)
+ return true
+ }
+
+ inspect(): PlatformState {
+ const base = { platform: this.platform, file: this.file, target: this.target, installed: this.installed(), linger: null, unreachable: null }
+ if (this.platform === 'launchd') {
+ const result = this.launchctl('print', this.target)
+ if (result.error) return { ...base, registered: false, pid: null, state: null, failed: false, lastExit: null, unreachable: failure('launchctl', ['print', this.target], result) }
+ if (result.status !== 0) return { ...base, registered: false, pid: null, state: null, failed: false, lastExit: null }
+ const pid = /^[ \t]*pid = (\d+)[ \t]*$/m.exec(result.stdout)
+ return {
+ ...base,
+ registered: true,
+ pid: pid ? Number(pid[1]) : null,
+ state: /^[ \t]*state = (.+?)[ \t]*$/m.exec(result.stdout)?.[1] ?? null,
+ failed: false,
+ lastExit: /^[ \t]*last exit code = (.+?)[ \t]*$/m.exec(result.stdout)?.[1] ?? null,
+ }
+ }
+ const args = ['--user', 'show', SYSTEMD_UNIT, '--property=LoadState,UnitFileState,ActiveState,SubState,MainPID,Result']
+ const result = this.deps.run('systemctl', args)
+ const linger = this.linger()
+ if (result.error || result.status !== 0) {
+ return { ...base, linger, registered: false, pid: null, state: null, failed: false, lastExit: null, unreachable: failure('systemctl', args, result) }
+ }
+ const shown = properties(result.stdout)
+ const pid = Number(shown.MainPID)
+ return {
+ ...base,
+ linger,
+ registered: shown.UnitFileState === 'enabled',
+ pid: pid > 0 ? pid : null,
+ state: shown.ActiveState ? `${shown.ActiveState}${shown.SubState ? ` (${shown.SubState})` : ''}` : null,
+ failed: shown.ActiveState === 'failed',
+ lastExit: shown.Result && shown.Result !== 'success' ? shown.Result : null,
+ }
+ }
+
+ /**
+ * Whether the platform can take the job at all, asked before anything is stopped: launchd's GUI
+ * domain exists only while the user is logged in at the screen (an SSH session alone has none), and
+ * `systemctl --user` needs the user's manager.
+ */
+ preflight(): Outcome {
+ if (this.platform === 'launchd') {
+ const result = this.launchctl('print', `gui/${this.deps.uid}`)
+ return result.status === 0 ? { ok: true } : { ok: false, detail: `${failure('launchctl', ['print', `gui/${this.deps.uid}`], result)} — launchd runs a user agent only for a user logged in at the screen` }
+ }
+ return this.systemctl('daemon-reload')
+ }
+
+ /** Register the definition just written, which starts the master: launchd loads the job (RunAtLoad),
+ * systemd enables the unit and starts it. */
+ register(): Outcome {
+ if (this.platform === 'launchd') {
+ // A job someone disabled stays disabled through a bootstrap; installing is asking for it.
+ const enabled = this.launchctl('enable', this.target)
+ if (enabled.status !== 0) return { ok: false, detail: failure('launchctl', ['enable', this.target], enabled) }
+ return this.checked('launchctl', ['bootstrap', `gui/${this.deps.uid}`, this.file])
+ }
+ const reloaded = this.systemctl('daemon-reload')
+ return reloaded.ok ? this.systemctl('enable', '--now', SYSTEMD_UNIT) : reloaded
+ }
+
+ /**
+ * Start the master. `refreshed`: the definition was rewritten just now, so a job launchd still has
+ * loaded is loaded again from the new file, and systemd rereads it.
+ */
+ start(refreshed: boolean): Outcome {
+ if (this.platform === 'launchd') {
+ const loaded = this.launchctl('print', this.target).status === 0
+ if (loaded && !refreshed) return this.checked('launchctl', ['kickstart', this.target])
+ if (loaded) {
+ const out = this.checked('launchctl', ['bootout', this.target])
+ if (!out.ok) return out
+ }
+ return this.checked('launchctl', ['bootstrap', `gui/${this.deps.uid}`, this.file])
+ }
+ if (refreshed) {
+ const reloaded = this.systemctl('daemon-reload')
+ if (!reloaded.ok) return reloaded
+ }
+ // After five failed starts systemd refuses a start until it is told to forget them.
+ this.deps.run('systemctl', ['--user', 'reset-failed', SYSTEMD_UNIT])
+ return this.systemctl('start', SYSTEMD_UNIT)
+ }
+
+ /**
+ * Stop the master and keep it stopped: launchd unloads the job until the next login or start; under
+ * systemd the master is told to stop and exits cleanly, which Restart=on-failure leaves stopped, and
+ * the unit stays enabled for the next login.
+ *
+ * Under systemd a signal, never a stop job (`systemctl stop`). tmux built with systemd support puts
+ * every pane in a scope PartOf the unit that started its server, and a stop job on this unit is passed
+ * to every one of them: each agent is stopped, whatever KillMode says. Seen with Fedora's tmux 3.7c
+ * under systemd 259, where `systemctl --user stop` ended every pane and a clean exit of the master
+ * ended none. The same goes for `restart` and `disable --now`, so nothing here uses them.
+ */
+ stop(): Outcome {
+ if (this.platform === 'launchd') {
+ if (this.launchctl('print', this.target).status !== 0) return { ok: true }
+ return this.checked('launchctl', ['bootout', this.target])
+ }
+ const main = Number(properties(this.deps.run('systemctl', ['--user', 'show', SYSTEMD_UNIT, '--property=MainPID']).stdout).MainPID)
+ if (!(main > 0)) return { ok: true }
+ // --kill-who: systemd 252 renamed it --kill-whom and kept this spelling, which older ones know.
+ return this.systemctl('kill', '--kill-who=main', '--signal=SIGTERM', SYSTEMD_UNIT)
+ }
+
+ /** Stop the master, unregister it and remove the definition. A unit whose file is already gone is
+ * stopped all the same. */
+ unregister(): Outcome {
+ if (this.platform === 'launchd') {
+ const stopped = this.stop()
+ if (!stopped.ok) return stopped
+ this.deps.removeFile(this.file)
+ return { ok: true }
+ }
+ // `disable` without --now, then the master stopped by a signal: no stop job reaches the panes (see stop).
+ if (this.installed()) {
+ const disabled = this.systemctl('disable', SYSTEMD_UNIT)
+ if (!disabled.ok) return disabled
+ }
+ const stopped = this.stop()
+ if (!stopped.ok) return stopped
+ this.deps.removeFile(this.file)
+ const reloaded = this.systemctl('daemon-reload')
+ // Forgets a failed state the unit left, so `systemctl --user --failed` does not list a unit that is gone.
+ this.deps.run('systemctl', ['--user', 'reset-failed', SYSTEMD_UNIT])
+ return reloaded
+ }
+
+ /** Remove the definition and nothing else: an install that could not register leaves nothing half
+ * done, so `harness start` runs the daemon as it did before. */
+ discard(): void {
+ this.deps.removeFile(this.file)
+ // Best effort: a manager that could not take the unit may not take a reload either.
+ if (this.platform === 'systemd') this.deps.run('systemctl', ['--user', 'daemon-reload'])
+ }
+
+ /** systemd: whether the user manager lingers. Unknown when loginctl cannot say. */
+ private linger(): boolean | null {
+ const result = this.deps.run('loginctl', ['show-user', String(this.deps.uid), '--property=Linger'])
+ if (result.status !== 0) return null
+ const value = properties(result.stdout).Linger
+ return value === 'yes' ? true : value === 'no' ? false : null
+ }
+
+ private launchctl(...args: string[]): CommandResult {
+ return this.deps.run('launchctl', args)
+ }
+
+ private systemctl(...args: string[]): Outcome {
+ return this.checked('systemctl', ['--user', ...args])
+ }
+
+ private checked(command: string, args: string[]): Outcome {
+ const result = this.deps.run(command, args)
+ return result.status === 0 && !result.error ? { ok: true } : { ok: false, detail: failure(command, args, result) }
+ }
+}
diff --git a/cli/src/lib/daemonState.ts b/cli/src/lib/daemonState.ts
index 33b0774a3..d3d0373ed 100644
--- a/cli/src/lib/daemonState.ts
+++ b/cli/src/lib/daemonState.ts
@@ -13,6 +13,10 @@ import { hasAuthSession } from './authSession.js'
import { savedDaemonPort } from './daemonEndpoint.js'
export const PID_FILE = join(env.ADAPTER_DATA_DIR, 'adapter.pid')
+/** The daemon's console: the master's and its core's stdout and stderr. Capped (lib/log.ts). */
+export const DAEMON_LOG_FILE = join(env.ADAPTER_DATA_DIR, 'harness.log')
+/** What harnessd's master last said about itself, for `harness status` when no core answers. */
+export const HARNESSD_STATUS_FILE = join(env.ADAPTER_DATA_DIR, 'harnessd-status.json')
/** This user's recorded TCP port; the configured port still names its private Unix socket. */
export function daemonPort(): number {
diff --git a/cli/src/lib/daemonStop.spec.ts b/cli/src/lib/daemonStop.spec.ts
index 21651499c..75b70cd7e 100644
--- a/cli/src/lib/daemonStop.spec.ts
+++ b/cli/src/lib/daemonStop.spec.ts
@@ -73,4 +73,75 @@ describe('stopDaemonProcess', () => {
expect(existsSync(PID_FILE)).toBe(false)
expect(state.released).toBe(1)
})
+
+ describe('when launchd or systemd runs the master', () => {
+ it('asks the platform, waits for the master to go, and sends no signal of its own', async () => {
+ const { stopDaemonProcess } = await load()
+ const { PID_FILE } = await import('./daemonState.js')
+ writeFileSync(PID_FILE, '500\n')
+ const state = { pid: 500, alive: new Set([500]), killed: [] as string[], locked: 0, released: 0 }
+ let asked = 0
+ const deps = fakeDeps(state, {
+ stopPlatform: () => { asked++; return { ok: true, stopped: 500 } },
+ sleep: async () => { state.alive.delete(500) }, // the master finishes its ordered stop
+ })
+ await expect(stopDaemonProcess(deps)).resolves.toEqual({ pid: 500, stopped: true })
+ expect(asked).toBe(1)
+ expect(state.killed).toEqual([])
+ expect(existsSync(PID_FILE)).toBe(false)
+ expect(state.released).toBe(1)
+ })
+
+ it('leaves a pid file that names someone else by the time the master has gone', async () => {
+ const { stopDaemonProcess } = await load()
+ const { PID_FILE } = await import('./daemonState.js')
+ writeFileSync(PID_FILE, '500\n')
+ const state = { pid: 500, alive: new Set([500]), killed: [] as string[], locked: 0, released: 0 }
+ const deps = fakeDeps(state, {
+ stopPlatform: () => ({ ok: true, stopped: 500 }),
+ sleep: async () => { state.alive.delete(500); state.pid = 501; writeFileSync(PID_FILE, '501\n') },
+ })
+ await expect(stopDaemonProcess(deps)).resolves.toEqual({ pid: 500, stopped: true })
+ expect(existsSync(PID_FILE)).toBe(true)
+ })
+
+ it('signals the master itself when the platform cannot stop it, or has not in time', async () => {
+ const { stopDaemonProcess, PLATFORM_STOP_WAIT_MS } = { ...(await load()), ...(await import('./platformDaemon.js')) }
+ const warnings: string[] = []
+ const refused = { pid: 500, alive: new Set([500]), killed: [] as string[], locked: 0, released: 0 }
+ await stopDaemonProcess(fakeDeps(refused, { stopPlatform: () => ({ ok: false, detail: 'launchctl bootout failed' }), warn: (m) => warnings.push(m) }))
+ expect(warnings).toEqual([' ! launchctl bootout failed — stopping it directly'])
+ expect(refused.killed).toEqual(['500:SIGTERM', '500:SIGKILL'])
+ const slow = { pid: 500, alive: new Set([500]), killed: [] as string[], locked: 0, released: 0 }
+ const slept: number[] = []
+ const clock = { now: 0 }
+ await stopDaemonProcess(fakeDeps(slow, { stopPlatform: () => ({ ok: true, stopped: 500 }), now: () => clock.now, sleep: async (ms) => { slept.push(ms); clock.now += ms } }))
+ expect(clock.now).toBeGreaterThanOrEqual(PLATFORM_STOP_WAIT_MS)
+ expect(slow.killed).toEqual(['500:SIGTERM', '500:SIGKILL'])
+ })
+
+ it('changes nothing when no platform runs it, or nothing was running', async () => {
+ const { stopDaemonProcess } = await load()
+ const none = { pid: 500, alive: new Set([500]), killed: [] as string[], locked: 0, released: 0 }
+ await expect(stopDaemonProcess(fakeDeps(none, { stopPlatform: () => null }))).resolves.toEqual({ pid: 500, stopped: true })
+ expect(none.killed).toEqual(['500:SIGTERM', '500:SIGKILL'])
+ const idle = { pid: null, alive: new Set<number>(), killed: [] as string[], locked: 0, released: 0 }
+ let asked = 0
+ await expect(stopDaemonProcess(fakeDeps(idle, { stopPlatform: () => { asked++; return { ok: true, stopped: null } } }))).resolves.toEqual({ pid: null, stopped: false })
+ expect(asked).toBe(1)
+ expect(idle.killed).toEqual([])
+ })
+
+ it('stops with signals a daemon `harness start` spawned beside the platform\'s, once the platform\'s has gone', async () => {
+ const { stopDaemonProcess } = await load()
+ const state = { pid: 500, alive: new Set([500]), killed: [] as string[], locked: 0, released: 0 }
+ await expect(stopDaemonProcess(fakeDeps(state, { stopPlatform: () => ({ ok: true, stopped: 600 }) }))).resolves.toEqual({ pid: 500, stopped: true })
+ expect(state.killed).toEqual(['500:SIGTERM', '500:SIGKILL'])
+ })
+
+ it('asks the platform by default, which for a data folder no platform runs is nobody', async () => {
+ const { defaultStopDeps } = await load()
+ expect(defaultStopDeps().stopPlatform!()).toBeNull()
+ })
+ })
})
diff --git a/cli/src/lib/daemonStop.ts b/cli/src/lib/daemonStop.ts
index 23b7c973a..95365a12d 100644
--- a/cli/src/lib/daemonStop.ts
+++ b/cli/src/lib/daemonStop.ts
@@ -10,6 +10,7 @@
import { rmSync } from 'fs'
import { PID_FILE, isAlive, readPid } from './daemonState.js'
import { acquireSpawnLock, describeSpawnLockFailure, describeSpawnLockOwner, SPAWN_LOCK_WAIT_MS } from './daemonSpawnLock.js'
+import { PLATFORM_STOP_WAIT_MS, stopUnderPlatform, type PlatformStop } from './platformDaemon.js'
export interface StopDeps {
readPid: () => number | null
@@ -20,6 +21,11 @@ export interface StopDeps {
/** Acquire the spawn lock; resolves to a release. Injected so the stop sequence is testable alone. */
lock: () => Promise<() => void>
warn: (message: string) => void
+ /**
+ * Ask launchd or systemd to stop the master when it runs it (`harness service install`,
+ * lib/platformDaemon.ts); null when it does not, and nothing was asked. Left out, nothing is.
+ */
+ stopPlatform?: () => PlatformStop | null
}
export function defaultStopDeps(): StopDeps {
@@ -44,6 +50,7 @@ export function defaultStopDeps(): StopDeps {
}
},
warn: (m) => console.warn(m),
+ stopPlatform: () => stopUnderPlatform(),
}
}
@@ -53,6 +60,8 @@ export const STOP_GRACE_MS = 3_000
export async function stopDaemonProcess(deps: StopDeps = defaultStopDeps()): Promise<{ pid: number | null; stopped: boolean }> {
const release = await deps.lock()
try {
+ const stopped = await stopThroughPlatform(deps)
+ if (stopped !== null) return { pid: stopped, stopped: true }
const pid = deps.readPid()
if (!pid || !deps.isAlive(pid)) {
// A pid file naming nothing is debris from a crash; nobody else can be relying on it.
@@ -72,3 +81,33 @@ export async function stopDaemonProcess(deps: StopDeps = defaultStopDeps()): Pro
release()
}
}
+
+/**
+ * The platform's half of a stop, when launchd or systemd runs the master: it is asked to stop it, and
+ * keeps it stopped, where a signal from here would read to it as a crash and bring the master back.
+ * Returns the pid it stopped; null when it was not asked, stopped nothing, or has not stopped it in
+ * time, and the signals in `stopDaemonProcess` take it from there.
+ */
+async function stopThroughPlatform(deps: StopDeps): Promise<number | null> {
+ if (!deps.stopPlatform) return null
+ const outcome = deps.stopPlatform()
+ if (!outcome) return null
+ if (!outcome.ok) {
+ deps.warn(` ! ${outcome.detail} — stopping it directly`)
+ return null
+ }
+ const master = outcome.stopped
+ if (master === null) return null
+ // bootout and `systemctl stop` can return before the master has finished its own ordered stop.
+ const deadline = deps.now() + PLATFORM_STOP_WAIT_MS
+ while (deps.isAlive(master)) {
+ if (deps.now() >= deadline) return null
+ await deps.sleep(150)
+ }
+ const pid = deps.readPid()
+ if (pid === master) { try { rmSync(PID_FILE, { force: true }) } catch { /* ignore */ } }
+ // A daemon `harness start` spawned beside the platform's (two supervisors, which `harness service`
+ // exists to prevent) is the signals' to stop.
+ if (pid !== null && pid !== master && deps.isAlive(pid)) return null
+ return master
+}
diff --git a/cli/src/lib/platformDaemon.spec.ts b/cli/src/lib/platformDaemon.spec.ts
new file mode 100644
index 000000000..859379475
--- /dev/null
+++ b/cli/src/lib/platformDaemon.spec.ts
@@ -0,0 +1,178 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { homedir, tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { env } from '../config/env.js'
+import { PlatformService, defaultPlatformDeps, type PlatformName, type PlatformState } from '../harnessd/platform.js'
+import { fakePlatform, type FakePlatform } from '../testing/fakePlatform.js'
+import { HARNESSD_STATUS_FILE } from './daemonState.js'
+import {
+ CARRIED_ENV, describeState, installedPlatform, platformDaemonDeps, serviceDefinition, startUnderPlatform, stopUnderPlatform,
+ supervisingPlatform, waitForMaster, waitGone, type PlatformDaemonDeps,
+} from './platformDaemon.js'
+
+/** A fake clock and a pid file the fake platform writes, over fake launchctl or systemctl. */
+function world(platform: PlatformName) {
+ const dir = mkdtempSync(join(tmpdir(), 'platform-daemon-'))
+ const home = join(dir, 'home')
+ const pidFile = join(dir, 'adapter.pid')
+ const fake = fakePlatform(join(dir, 'bin'), { pidFile })
+ const clock = { now: 0 }
+ const dead = new Set<number>()
+ const service = new PlatformService(platform, defaultPlatformDeps({ env: { PATH: fake.bin }, uid: 501, home }))
+ const deps: PlatformDaemonDeps = {
+ service,
+ logFile: join(dir, 'data', 'harness.log'),
+ readPid: () => { try { return Number(readFileSync(pidFile, 'utf8')) || null } catch { return null } },
+ // The platform's master lives while the fake runs it; any other pid lives unless a test kills it.
+ isAlive: (pid) => !dead.has(pid) && (fake.state().pid === pid || pid !== fake.state().nextPid),
+ masterPlatform: () => null,
+ now: () => clock.now,
+ sleep: async (ms) => { clock.now += ms },
+ }
+ const definition = serviceDefinition({ logFile: deps.logFile, source: {}, nodePath: '/opt/node/bin/node', scriptPath: join(dir, 'cli.js'), home })
+ return { dir, home, pidFile, fake, clock, dead, service, deps, definition }
+}
+
+describe('the platform that supervises harnessd', () => {
+ it('is this operating system\'s, unless the end-to-end suite names another', () => {
+ expect(supervisingPlatform('darwin', {})).toBe('launchd')
+ expect(supervisingPlatform('linux', {})).toBe('systemd')
+ expect(supervisingPlatform('win32', {})).toBeNull()
+ expect(supervisingPlatform('darwin', { HARNESSD_TEST_PLATFORM: 'systemd' })).toBe('systemd')
+ expect(supervisingPlatform('win32', { HARNESSD_TEST_PLATFORM: 'launchd' })).toBe('launchd')
+ expect(supervisingPlatform('linux', { HARNESSD_TEST_PLATFORM: 'upstart' })).toBe('systemd')
+ })
+})
+
+describe('the definition for this install', () => {
+ it('carries only the settings that decide which daemon this is, and only when set', () => {
+ const definition = serviceDefinition({
+ logFile: '/data/harness.log', nodePath: '/n', scriptPath: '/c.js', home: '/h',
+ source: { ADAPTER_DATA_DIR: '/data', PORT: '18474', ADAPTER_UPDATE_DISABLE: 'true', HARNESS_ENV_FILE: '', SECRET_TOKEN: 'x', PATH: '/bin' },
+ })
+ expect(definition).toEqual({ nodePath: '/n', scriptPath: '/c.js', logFile: '/data/harness.log', home: '/h', env: { ADAPTER_DATA_DIR: '/data', PORT: '18474', ADAPTER_UPDATE_DISABLE: 'true' } })
+ expect(CARRIED_ENV).toContain('HARNESS_AUTH_DIR')
+ })
+
+ it('runs the managed Node and the installed bundle from this home by default', () => {
+ const definition = serviceDefinition({ logFile: '/data/harness.log' })
+ expect(definition.scriptPath).toBe(join(env.ADAPTER_CLI_DIR, 'cli.js'))
+ expect(definition.nodePath).toBe(process.execPath) // the test runtime folder has no managed Node
+ expect(definition.home).toBe(homedir())
+ expect(definition.env.ADAPTER_DATA_DIR).toBe(process.env.ADAPTER_DATA_DIR)
+ })
+})
+
+describe.each(['launchd', 'systemd'] as const)('under %s', (platform) => {
+ let w: ReturnType<typeof world>
+ beforeEach(() => { w = world(platform) })
+ afterEach(() => rmSync(w.dir, { recursive: true, force: true }))
+
+ it('counts as installed only with a definition written for this data folder', () => {
+ expect(installedPlatform(w.deps)).toBeNull()
+ w.service.write({ ...w.definition, logFile: '/another/data/harness.log' })
+ expect(installedPlatform(w.deps)).toBeNull()
+ w.service.write(w.definition)
+ expect(installedPlatform(w.deps)).toBe(platform)
+ expect(installedPlatform({ ...w.deps, service: null })).toBeNull()
+ })
+
+ it('starts the master through the platform, rewriting a stale definition first, and waits for it', async () => {
+ await expect(startUnderPlatform(w.definition, w.deps, 1_000)).resolves.toEqual({ ok: true, pid: 4242, refreshed: true })
+ expect(readFileSync(w.service.file, 'utf8')).toBe(w.service.render(w.definition))
+ w.fake.set({ pid: null, nextPid: 4343 })
+ rmSync(w.pidFile)
+ await expect(startUnderPlatform(w.definition, w.deps, 1_000)).resolves.toEqual({ ok: true, pid: 4343, refreshed: false })
+ })
+
+ it('says why when the platform will not start it, or it does not come up', async () => {
+ await expect(startUnderPlatform(w.definition, { ...w.deps, service: null })).resolves.toEqual({ ok: false, detail: 'neither launchd nor systemd runs harnessd on this computer' })
+ w.fake.set({ fail: { [platform === 'launchd' ? 'launchctl bootstrap' : 'systemctl start']: { status: 5, stderr: 'refused' } } })
+ await expect(startUnderPlatform(w.definition, w.deps, 1_000)).resolves.toEqual({ ok: false, detail: expect.stringContaining('refused') })
+ w.fake.set({ fail: {}, pidFile: null })
+ const late = await startUnderPlatform(w.definition, w.deps, 1_000)
+ expect(late).toEqual({ ok: false, detail: expect.stringMatching(new RegExp(`^${platform} did not bring harnessd up within 1s \\(.*pid 4242\\)$`)) })
+ })
+
+ it('stops the master through the platform when its definition is this folder\'s, or the master says the platform runs it', () => {
+ expect(stopUnderPlatform({ ...w.deps, service: null })).toBeNull()
+ expect(stopUnderPlatform(w.deps)).toBeNull()
+ expect(w.fake.calls()).toEqual([])
+ w.service.write(w.definition)
+ w.service.register()
+ expect(stopUnderPlatform(w.deps)).toEqual({ ok: true, stopped: 4242 })
+ expect(w.fake.state().pid).toBeNull()
+ // Its file removed by hand, the job still loaded: the master's status file is what says so.
+ w.service.start(false)
+ rmSync(w.service.file)
+ expect(stopUnderPlatform({ ...w.deps, masterPlatform: () => (platform === 'launchd' ? 'systemd' : 'launchd') })).toBeNull()
+ expect(stopUnderPlatform({ ...w.deps, masterPlatform: () => platform })).toEqual({ ok: true, stopped: 4242 })
+ expect(stopUnderPlatform({ ...w.deps, masterPlatform: () => platform })).toBeNull()
+ // Installed, and asked with nothing running: the platform ran no master to wait on.
+ w.service.write(w.definition)
+ expect(stopUnderPlatform(w.deps)).toEqual({ ok: true, stopped: null })
+ w.fake.set(platform === 'launchd' ? { fail: { 'launchctl print': { status: 1, stderr: 'no' } } } : { pid: 4242, fail: { 'systemctl kill': { status: 1, stderr: 'no' } } })
+ expect(stopUnderPlatform(w.deps)).toEqual(platform === 'launchd' ? { ok: true, stopped: null } : { ok: false, detail: expect.stringContaining('no') })
+ })
+})
+
+describe('waiting', () => {
+ const clocked = (alive: (pid: number, now: number) => boolean, pid: () => number | null = () => 7) => {
+ const clock = { now: 0 }
+ return { clock, deps: { readPid: pid, isAlive: (p: number) => alive(p, clock.now), now: () => clock.now, sleep: async (ms: number) => { clock.now += ms } } }
+ }
+
+ it('for the master to claim the pid file, until the deadline', async () => {
+ let at = 0
+ const { deps } = clocked((_, now) => now >= 500, () => (at++ > 0 ? 7 : null))
+ await expect(waitForMaster(deps, 1_000)).resolves.toBe(7)
+ const { deps: never } = clocked(() => false)
+ await expect(waitForMaster(never, 1_000)).resolves.toBeNull()
+ })
+
+ it('for a master to go, until the deadline', async () => {
+ const { deps } = clocked((_, now) => now < 300)
+ await expect(waitGone(deps, 7, 1_000)).resolves.toBe(true)
+ const { deps: stubborn } = clocked(() => true)
+ await expect(waitGone(stubborn, 7, 1_000)).resolves.toBe(false)
+ })
+})
+
+describe('describing what the platform says', () => {
+ const state = (over: Partial<PlatformState>): PlatformState => ({
+ platform: 'launchd', file: '/f', target: 't', installed: true, registered: true, pid: null, state: null, failed: false,
+ lastExit: null, linger: null, unreachable: null, ...over,
+ })
+
+ it('in one line', () => {
+ expect(describeState(state({ unreachable: 'launchctl print failed' }))).toBe('could not ask launchd: launchctl print failed')
+ expect(describeState(state({ registered: false }))).toBe('not loaded')
+ expect(describeState(state({ platform: 'systemd', registered: false }))).toBe('not enabled')
+ expect(describeState(state({ platform: 'systemd', registered: false, state: 'active (running)', pid: 4 }))).toBe('not enabled · active (running) · pid 4')
+ expect(describeState(state({ state: 'running', pid: 9, lastExit: '(never exited)' }))).toBe('running · pid 9')
+ expect(describeState(state({ state: 'not running', lastExit: '1' }))).toBe('not running · last exit 1')
+ expect(describeState(state({}))).toBe('registered')
+ })
+})
+
+describe('this computer\'s dependencies', () => {
+ it('read which platform runs the master from the status file it wrote', async () => {
+ const deps = platformDaemonDeps()
+ expect(deps.service?.platform).toBe(process.platform === 'darwin' ? 'launchd' : process.platform === 'linux' ? 'systemd' : undefined)
+ expect(deps.logFile).toBe(join(process.env.ADAPTER_DATA_DIR!, 'harness.log'))
+ writeFileSync(HARNESSD_STATUS_FILE, JSON.stringify({ state: 'running', masterPid: 77, platform: 'systemd' }))
+ try {
+ expect(deps.masterPlatform(77)).toBe('systemd')
+ expect(deps.masterPlatform(78)).toBeNull()
+ writeFileSync(HARNESSD_STATUS_FILE, JSON.stringify({ state: 'running', masterPid: 77 }))
+ expect(deps.masterPlatform(77)).toBeNull()
+ } finally { rmSync(HARNESSD_STATUS_FILE, { force: true }) }
+ expect(deps.readPid()).toBeNull()
+ expect(deps.isAlive(process.pid)).toBe(true)
+ const before = deps.now()
+ await deps.sleep(5)
+ expect(deps.now()).toBeGreaterThanOrEqual(before)
+ expect(platformDaemonDeps({ logFile: '/x.log' }).logFile).toBe('/x.log')
+ })
+})
diff --git a/cli/src/lib/platformDaemon.ts b/cli/src/lib/platformDaemon.ts
new file mode 100644
index 000000000..8c40b4aa1
--- /dev/null
+++ b/cli/src/lib/platformDaemon.ts
@@ -0,0 +1,172 @@
+/**
+ * Where the rest of the CLI meets launchd or systemd, once someone has opted in with
+ * `harness service install` (./serviceCommand.ts; the definitions are ../harnessd/platform.ts).
+ *
+ * One supervisor per machine. When the platform runs the master, `harness start` asks the platform to
+ * start it rather than spawning a second master beside it, and every stop (`harness stop`, and the
+ * stops inside logout, reset, update and a forced login) asks the platform to stop it: a signal from
+ * here would read to launchd or systemd as a crash, and bring the master back. For anyone who has not
+ * opted in, both find no definition and change nothing.
+ *
+ * The CLI never decides this from its own environment. HARNESSD_PLATFORM is set for the master by its
+ * definition, and a shell in a tmux pane the daemon started inherits it; it would otherwise believe it
+ * was the platform. What counts is the definition on disk, and what the running master wrote in its
+ * status file.
+ */
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { env } from '../config/env.js'
+import { readStatusFile } from '../harnessd/master.js'
+import { PlatformService, defaultPlatformDeps, platformFor, type PlatformName, type PlatformState, type ServiceDefinition } from '../harnessd/platform.js'
+import { DAEMON_LOG_FILE, HARNESSD_STATUS_FILE, isAlive, readPid } from './daemonState.js'
+import { managedNodePath } from './nodeRuntime.js'
+
+/**
+ * The CLI's own settings that decide which daemon this is, carried into the definition when they are
+ * set, so the platform runs the daemon `harness start` from this shell would: where its state, bundle
+ * and sign-in live, its port, its environment file, and a local build's update pin. Without them a
+ * definition written from a shell with ADAPTER_DATA_DIR set would run a master on the default folder,
+ * whose pid file that shell's `harness start` would wait on in vain. Anything else belongs in the file
+ * HARNESS_ENV_FILE names.
+ */
+export const CARRIED_ENV = ['ADAPTER_DATA_DIR', 'ADAPTER_CLI_DIR', 'HARNESS_AUTH_DIR', 'PORT', 'HARNESS_ENV_FILE', 'ADAPTER_UPDATE_DISABLE'] as const
+
+/** How long a start through the platform waits for the master to claim the pid file, which it does once
+ * its core has bound: as long as `harness start` waits for one it spawned (daemonLaunch BIND_WAIT_MS). */
+export const PLATFORM_START_WAIT_MS = 60_000
+/** How long a stop waits for the platform's master to go: past the platform's own deadline to stop it
+ * (STOP_TIMEOUT_S), after which `harness stop`'s own signals take over. */
+export const PLATFORM_STOP_WAIT_MS = 12_000
+
+export interface PlatformDaemonDeps {
+ /** harnessd's registration with this computer's platform; null where there is none (not macOS or Linux). */
+ service: PlatformService | null
+ /** The daemon's log, which is also how a definition is known to be this data folder's. */
+ logFile: string
+ readPid(): number | null
+ isAlive(pid: number): boolean
+ /** What runs the master `pid`, as its status file says. */
+ masterPlatform(pid: number): PlatformName | null
+ now(): number
+ sleep(ms: number): Promise<void>
+}
+
+/**
+ * The platform that would supervise harnessd here: this operating system's, or the one
+ * HARNESSD_TEST_PLATFORM names, for the end-to-end suite only, which runs both definitions on any
+ * computer against fake launchctl and systemctl (e2e/cli.e2e.ts). Unset, it changes nothing.
+ */
+export function supervisingPlatform(os: NodeJS.Platform, env: NodeJS.ProcessEnv): PlatformName | null {
+ const forced = env.HARNESSD_TEST_PLATFORM
+ return forced === 'launchd' || forced === 'systemd' ? forced : platformFor(os)
+}
+
+/** This computer's: its platform, its pid file, the status file its master writes. */
+export function platformDaemonDeps(overrides: Partial<PlatformDaemonDeps> = {}): PlatformDaemonDeps {
+ const platform = supervisingPlatform(process.platform, process.env)
+ return {
+ service: platform ? new PlatformService(platform, defaultPlatformDeps()) : null,
+ logFile: DAEMON_LOG_FILE,
+ readPid,
+ isAlive,
+ masterPlatform: (pid) => readStatusFile(HARNESSD_STATUS_FILE, pid)?.platform ?? null,
+ now: () => Date.now(),
+ sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+ ...overrides,
+ }
+}
+
+/** What the platform runs for this install: the managed Node (as the desktop app runs the CLI) and the
+ * installed bundle, the daemon's log, and the settings to carry from `source`. */
+export function serviceDefinition(options: { logFile: string; source?: NodeJS.ProcessEnv; nodePath?: string; scriptPath?: string; home?: string }): ServiceDefinition {
+ const source = options.source ?? process.env
+ const carried: Record<string, string> = {}
+ for (const name of CARRIED_ENV) {
+ const value = source[name]
+ if (value) carried[name] = value
+ }
+ return {
+ nodePath: options.nodePath ?? managedNodePath(),
+ scriptPath: options.scriptPath ?? join(env.ADAPTER_CLI_DIR, 'cli.js'),
+ logFile: options.logFile,
+ home: options.home ?? homedir(),
+ env: carried,
+ }
+}
+
+/** The platform that runs harnessd here: its definition is on disk, written for this data folder. */
+export function installedPlatform(deps: PlatformDaemonDeps = platformDaemonDeps()): PlatformName | null {
+ return deps.service?.ownedBy(deps.logFile) ? deps.service.platform : null
+}
+
+/** What the platform did with a stop: `stopped` is the master it was running, for the caller to wait
+ * on, or null when it ran none. */
+export type PlatformStop = { ok: true; stopped: number | null } | { ok: false; detail: string }
+
+/**
+ * Ask the platform to stop the master when it runs it: the definition is installed for this data
+ * folder, or the running master says the platform started it (a definition removed by hand leaves the
+ * job loaded). Null when no platform runs it, and nothing was asked.
+ */
+export function stopUnderPlatform(deps: PlatformDaemonDeps = platformDaemonDeps()): PlatformStop | null {
+ const service = deps.service
+ if (!service) return null
+ const pid = deps.readPid()
+ const runsIt = pid !== null && deps.isAlive(pid) && deps.masterPlatform(pid) === service.platform
+ if (!runsIt && !service.ownedBy(deps.logFile)) return null
+ // Its own pid for its master: a daemon `harness start` spawned beside it is not the platform's to stop.
+ const master = service.inspect().pid
+ const outcome = service.stop()
+ return outcome.ok ? { ok: true, stopped: master } : outcome
+}
+
+export type StartOutcome = { ok: true; pid: number; refreshed: boolean } | { ok: false; detail: string }
+
+/**
+ * Start the master through the platform and wait for it to come up. The definition is rewritten first
+ * when this install's would differ, a Node runtime that moved or a bundle elsewhere, so that a stale one
+ * cannot go on failing at every login. Called under the spawn lock, with no daemon running.
+ */
+export async function startUnderPlatform(definition: ServiceDefinition, deps: PlatformDaemonDeps = platformDaemonDeps(), waitMs = PLATFORM_START_WAIT_MS): Promise<StartOutcome> {
+ const service = deps.service
+ if (!service) return { ok: false, detail: 'neither launchd nor systemd runs harnessd on this computer' }
+ const refreshed = service.write(definition)
+ const started = service.start(refreshed)
+ if (!started.ok) return started
+ const pid = await waitForMaster(deps, waitMs)
+ if (pid !== null) return { ok: true, pid, refreshed }
+ return { ok: false, detail: `${service.platform} did not bring harnessd up within ${Math.round(waitMs / 1000)}s (${describeState(service.inspect())})` }
+}
+
+/** The master's pid once it has claimed the pid file, which it does when its core has bound; null if
+ * none has by the deadline. */
+export async function waitForMaster(deps: Pick<PlatformDaemonDeps, 'readPid' | 'isAlive' | 'now' | 'sleep'>, timeoutMs: number): Promise<number | null> {
+ const deadline = deps.now() + timeoutMs
+ for (;;) {
+ const pid = deps.readPid()
+ if (pid !== null && deps.isAlive(pid)) return pid
+ if (deps.now() >= deadline) return null
+ await deps.sleep(250)
+ }
+}
+
+/** Whether `pid` is gone by the deadline. */
+export async function waitGone(deps: Pick<PlatformDaemonDeps, 'isAlive' | 'now' | 'sleep'>, pid: number, timeoutMs: number): Promise<boolean> {
+ const deadline = deps.now() + timeoutMs
+ while (deps.isAlive(pid)) {
+ if (deps.now() >= deadline) return false
+ await deps.sleep(150)
+ }
+ return true
+}
+
+/** One line on what the platform says: for `harness service status`, and a start that failed. */
+export function describeState(state: PlatformState): string {
+ if (state.unreachable) return `could not ask ${state.platform}: ${state.unreachable}`
+ const parts: string[] = []
+ if (!state.registered) parts.push(state.platform === 'launchd' ? 'not loaded' : 'not enabled')
+ if (state.state) parts.push(state.state)
+ if (state.pid !== null) parts.push(`pid ${state.pid}`)
+ else if (state.lastExit) parts.push(`last exit ${state.lastExit}`)
+ return parts.join(' · ') || 'registered'
+}
diff --git a/cli/src/lib/serviceCommand.spec.ts b/cli/src/lib/serviceCommand.spec.ts
new file mode 100644
index 000000000..ead2c51c0
--- /dev/null
+++ b/cli/src/lib/serviceCommand.spec.ts
@@ -0,0 +1,318 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { PlatformService, defaultPlatformDeps, type PlatformName } from '../harnessd/platform.js'
+import { fakePlatform, type FakePlatform } from '../testing/fakePlatform.js'
+import { serviceDefinition } from './platformDaemon.js'
+import { SERVICE_USAGE, serviceCommand, serviceCommandDeps, type ServiceCommandDeps } from './serviceCommand.js'
+
+/**
+ * A computer in a temporary folder: a home, a data folder, an installed bundle, a pid file, and fake
+ * launchctl or systemctl that run a stand-in master (pid 4242) and write its pid as the real one does.
+ */
+function computer(platform: PlatformName) {
+ const dir = mkdtempSync(join(tmpdir(), 'service-command-'))
+ const home = join(dir, 'home')
+ const data = join(dir, 'data')
+ const pidFile = join(data, 'adapter.pid')
+ const script = join(dir, 'cli', 'cli.js')
+ mkdirSync(join(dir, 'cli'), { recursive: true })
+ writeFileSync(script, '// the installed bundle\n')
+ const fake = fakePlatform(join(dir, 'bin'), { pidFile })
+ const clock = { now: 0 }
+ /** A daemon `harness start` spawned, outside the platform: alive until `stopDaemon` stops it. */
+ const outside = { pid: null as number | null }
+ const out: string[] = []
+ const err: string[] = []
+ const stops: string[] = []
+ const relaunches: number[] = []
+ const service = new PlatformService(platform, defaultPlatformDeps({ env: { PATH: fake.bin }, uid: 501, home }))
+ const readPid = (): number | null => { try { return Number(readFileSync(pidFile, 'utf8')) || null } catch { return null } }
+ const deps: ServiceCommandDeps = {
+ service,
+ logFile: join(data, 'harness.log'),
+ readPid,
+ isAlive: (pid) => pid === outside.pid || pid === fake.state().pid,
+ masterPlatform: () => null,
+ now: () => clock.now,
+ sleep: async (ms) => { clock.now += ms },
+ definition: () => serviceDefinition({ logFile: join(data, 'harness.log'), source: { ADAPTER_DATA_DIR: data }, nodePath: '/opt/node/bin/node', scriptPath: script, home }),
+ bundleExists: (path) => existsSync(path),
+ ensureDir: (path) => { mkdirSync(path, { recursive: true }) },
+ stopDaemon: async () => {
+ const pid = readPid()
+ stops.push(String(pid))
+ if (pid === outside.pid) { outside.pid = null; rmSync(pidFile, { force: true }) }
+ return { pid, stopped: pid !== null }
+ },
+ withLock: (_purpose, fn) => fn(),
+ relaunch: async () => { relaunches.push(clock.now) },
+ out: (line) => out.push(line),
+ err: (line) => err.push(line),
+ tildify: (path) => path.replace(dir, '~'),
+ startWaitMs: 1_000,
+ }
+ /** A daemon running outside the platform, as `harness start` leaves one. */
+ const runOutside = (pid: number) => { outside.pid = pid; mkdirSync(data, { recursive: true }); writeFileSync(pidFile, `${pid}\n`) }
+ return { dir, home, data, pidFile, script, fake, clock, out, err, stops, relaunches, service, deps, runOutside, outside }
+}
+
+describe('harness service', () => {
+ it('prints its usage when asked, and refuses a verb it does not know', async () => {
+ const c = computer('launchd')
+ try {
+ await expect(serviceCommand([], c.deps)).resolves.toBe(0)
+ await expect(serviceCommand(['--help'], c.deps)).resolves.toBe(0)
+ await expect(serviceCommand(['help'], c.deps)).resolves.toBe(0)
+ expect(c.out).toEqual([SERVICE_USAGE, SERVICE_USAGE, SERVICE_USAGE])
+ await expect(serviceCommand(['restart'], c.deps)).resolves.toBe(2)
+ expect(c.err[0]).toMatch(/^Unknown command: harness service restart/)
+ expect(c.fake.calls()).toEqual([])
+ } finally { rmSync(c.dir, { recursive: true, force: true }) }
+ })
+
+ it('says so on a computer with neither launchd nor systemd', async () => {
+ const c = computer('launchd')
+ try {
+ const none = { ...c.deps, service: null }
+ await expect(serviceCommand(['install'], none)).resolves.toBe(1)
+ await expect(serviceCommand(['status'], none)).resolves.toBe(0)
+ expect(c.err).toEqual([
+ 'harness service runs harnessd under launchd (macOS) or systemd (Linux); this computer has neither.',
+ 'harness service runs harnessd under launchd (macOS) or systemd (Linux); this computer has neither.',
+ ])
+ await expect(serviceCommand(['status', '--json'], none)).resolves.toBe(0)
+ expect(c.out).toEqual(['{"supported":false}'])
+ } finally { rmSync(c.dir, { recursive: true, force: true }) }
+ })
+})
+
+describe.each(['launchd', 'systemd'] as const)('harness service under %s', (platform) => {
+ let c: ReturnType<typeof computer>
+ beforeEach(() => { c = computer(platform) })
+ afterEach(() => rmSync(c.dir, { recursive: true, force: true }))
+ const verbs = () => c.fake.calls().map((call) => (call[0] === 'systemctl' ? [call[0], call[2]] : call.slice(0, 2)).join(' '))
+
+ describe('install', () => {
+ it('writes the definition, registers it, and waits for the master the platform starts', async () => {
+ await expect(serviceCommand(['install'], c.deps)).resolves.toBe(0)
+ expect(readFileSync(c.service.file, 'utf8')).toBe(c.service.render(c.deps.definition()))
+ expect(readFileSync(c.service.file, 'utf8')).toContain(c.data)
+ expect(c.fake.state()).toMatchObject({ loaded: true, pid: 4242 })
+ expect(c.stops).toEqual([]) // nothing was running to stop
+ expect(existsSync(c.data)).toBe(true) // the log's folder, which the platform will not make
+ expect(c.out[0]).toBe(`✓ harnessd runs under ${platform} (pid 4242): it starts at login and comes back if it dies.`)
+ expect(c.out).toContain(' undo: harness service uninstall')
+ expect(verbs()).toEqual(platform === 'launchd'
+ ? ['launchctl print', 'launchctl print', 'launchctl enable', 'launchctl bootstrap', 'launchctl print']
+ : ['systemctl daemon-reload', 'systemctl show', 'loginctl show-user', 'systemctl daemon-reload', 'systemctl enable', 'systemctl show', 'loginctl show-user'])
+ })
+
+ it('stops a daemon `harness start` left running first, so there is one supervisor', async () => {
+ c.runOutside(31337)
+ await expect(serviceCommand(['install'], c.deps)).resolves.toBe(0)
+ expect(c.stops).toEqual(['31337'])
+ expect(c.outside.pid).toBeNull()
+ expect(c.fake.state().pid).toBe(4242)
+ })
+
+ it('does nothing when it already runs under the platform from this definition', async () => {
+ await serviceCommand(['install'], c.deps)
+ const before = c.fake.calls().length
+ await expect(serviceCommand(['install'], c.deps)).resolves.toBe(0)
+ expect(c.out.at(-1)).toBe(`harnessd already runs under ${platform} (pid 4242); nothing to change.`)
+ expect(c.fake.calls().slice(before).map((call) => call.join(' '))).not.toContainEqual(expect.stringMatching(/bootstrap|enable/))
+ expect(c.stops).toEqual([])
+ })
+
+ it('moves the platform\'s master onto a definition that changed', async () => {
+ await serviceCommand(['install'], c.deps)
+ const definition = c.deps.definition
+ c.deps.definition = () => ({ ...definition(), nodePath: '/opt/newer-node/bin/node' })
+ c.fake.set({ nextPid: 4343 })
+ c.deps.stopDaemon = async () => { c.stops.push('platform'); c.service.stop(); return { pid: 4242, stopped: true } }
+ await expect(serviceCommand(['install'], c.deps)).resolves.toBe(0)
+ expect(c.stops).toEqual(['platform'])
+ expect(readFileSync(c.service.file, 'utf8')).toContain('/opt/newer-node/bin/node')
+ expect(c.fake.state().pid).toBe(4343)
+ })
+
+ it('refuses without the installed bundle, and touches nothing', async () => {
+ rmSync(c.script)
+ await expect(serviceCommand(['install'], c.deps)).resolves.toBe(1)
+ expect(c.err[0]).toBe(`✗ No installed CLI at ~/cli/cli.js. ${platform} runs the installed bundle: install it first, then run this again.`)
+ expect(existsSync(c.service.file)).toBe(false)
+ expect(c.fake.calls()).toEqual([])
+ })
+
+ it('leaves a computer the platform cannot serve as it was', async () => {
+ c.runOutside(31337)
+ c.fake.set(platform === 'launchd' ? { guiDomain: false } : { fail: { 'systemctl daemon-reload': { status: 1, stderr: 'Failed to connect to bus' } } })
+ await expect(serviceCommand(['install'], c.deps)).resolves.toBe(1)
+ expect(c.err[0]).toMatch(new RegExp(`^✗ ${platform} cannot run harnessd here: `))
+ expect(existsSync(c.service.file)).toBe(false)
+ expect(c.stops).toEqual([])
+ expect(c.outside.pid).toBe(31337)
+ })
+
+ it('discards a definition the platform would not take, and says the daemon it stopped needs a start', async () => {
+ c.runOutside(31337)
+ c.fake.set({ fail: { [platform === 'launchd' ? 'launchctl bootstrap' : 'systemctl enable']: { status: 5, stderr: 'refused' } } })
+ await expect(serviceCommand(['install'], c.deps)).resolves.toBe(1)
+ expect(existsSync(c.service.file)).toBe(false)
+ expect(c.err).toEqual([
+ expect.stringMatching(new RegExp(`^✗ ${platform} would not take harnessd: .*refused$`)),
+ ' The daemon was stopped to hand it over; `harness start` starts it again, as before.',
+ ])
+ })
+
+ it('says so when the master does not come up', async () => {
+ c.fake.set({ pidFile: null })
+ await expect(serviceCommand(['install'], c.deps)).resolves.toBe(1)
+ expect(c.err[0]).toMatch(new RegExp(`^✗ ${platform} has harnessd, but it did not come up \\(.*pid 4242\\)\\.$`))
+ expect(c.err[1]).toBe(' logs ~/data/harness.log · harness service status')
+ })
+ })
+
+ describe('uninstall', () => {
+ it('has nothing to remove when nothing is installed', async () => {
+ await expect(serviceCommand(['uninstall'], c.deps)).resolves.toBe(0)
+ expect(c.out).toEqual([`harnessd is not installed with ${platform}; nothing to remove.`])
+ })
+
+ it('unregisters, removes the definition, and starts the daemon the usual way', async () => {
+ await serviceCommand(['install'], c.deps)
+ c.out.length = 0
+ await expect(serviceCommand(['uninstall'], c.deps)).resolves.toBe(0)
+ expect(existsSync(c.service.file)).toBe(false)
+ expect(c.fake.state()).toMatchObject({ pid: null })
+ expect(c.out).toEqual([`✓ removed ~/home/${platform === 'launchd' ? 'Library/LaunchAgents/ai.autonomous.harness.harnessd.plist' : '.config/systemd/user/harnessd.service'}: ${platform} no longer runs harnessd.`, ' starting it the usual way…'])
+ expect(c.relaunches).toHaveLength(1)
+ expect(c.stops).toEqual([])
+ })
+
+ it('stops a master the platform let outlive its unregistering, before starting one the usual way', async () => {
+ await serviceCommand(['install'], c.deps)
+ const isAlive = c.deps.isAlive
+ c.deps.isAlive = (pid) => pid === 4242 || isAlive(pid) // it does not go when the platform lets it
+ await expect(serviceCommand(['uninstall'], c.deps)).resolves.toBe(0)
+ expect(c.clock.now).toBeGreaterThanOrEqual(12_000)
+ expect(c.stops).toHaveLength(1)
+ expect(c.relaunches).toHaveLength(1)
+ })
+
+ it('starts nothing when the daemon was not running under the platform', async () => {
+ await serviceCommand(['install'], c.deps)
+ c.service.stop()
+ c.runOutside(31337)
+ await expect(serviceCommand(['uninstall'], c.deps)).resolves.toBe(0)
+ expect(existsSync(c.service.file)).toBe(false)
+ expect(c.relaunches).toEqual([])
+ expect(c.outside.pid).toBe(31337)
+ })
+
+ it('keeps the definition and says why when the platform will not let it go', async () => {
+ await serviceCommand(['install'], c.deps)
+ c.fake.set({ fail: { [platform === 'launchd' ? 'launchctl bootout' : 'systemctl disable']: { status: 1, stderr: 'not now' } } })
+ await expect(serviceCommand(['uninstall'], c.deps)).resolves.toBe(1)
+ expect(c.err[0]).toMatch(/^✗ .*not now$/)
+ expect(existsSync(c.service.file)).toBe(true)
+ expect(c.relaunches).toEqual([])
+ })
+ })
+
+ describe('status', () => {
+ const status = async (...flags: string[]) => {
+ c.out.length = 0
+ await expect(serviceCommand(['status', ...flags], c.deps)).resolves.toBe(0)
+ return c.out
+ }
+
+ it('says when it is not installed, and how to opt in', async () => {
+ expect(await status()).toEqual([
+ `harnessd · ${platform}`,
+ ` status ○ not installed · \`harness start\` runs the daemon; \`harness service install\` hands it to ${platform}`,
+ ])
+ })
+
+ it('says when the platform runs it, where its definition is, and what the platform calls it', async () => {
+ await serviceCommand(['install'], c.deps)
+ const lines = await status()
+ expect(lines[1]).toBe(' status ● running (pid 4242) · starts at login, comes back if it dies')
+ expect(lines[2]).toMatch(new RegExp(`^ (agent |unit ) ~/home/`))
+ expect(lines[3]).toBe(` target ${c.service.target}`)
+ expect(lines).toHaveLength(4)
+ expect(JSON.parse((await status('--json'))[0])).toEqual({
+ supported: true, platform, file: c.service.file, target: c.service.target, installed: true, current: true, registered: true,
+ running: true, pid: 4242, state: platform === 'launchd' ? 'running' : 'active (running)', lastExit: platform === 'launchd' ? '(never exited)' : null,
+ failed: false, linger: platform === 'launchd' ? null : true, unreachable: null,
+ })
+ })
+
+ it('says when it is installed but stopped, and when the definition is out of date', async () => {
+ await serviceCommand(['install'], c.deps)
+ c.service.stop()
+ expect((await status())[1]).toBe(platform === 'launchd'
+ ? ' status ◍ installed, not loaded · it starts at your next login, or now with `harness start`'
+ : ` status ◍ registered, not running (inactive (dead)) · \`harness start\` starts it`)
+ c.deps.definition = () => ({ ...serviceDefinition({ logFile: c.deps.logFile, source: {}, nodePath: '/moved/node', scriptPath: c.script, home: c.home }) })
+ expect(await status()).toContain(' ! the definition is not the one this install would write (another Node, bundle or setting): `harness service install` rewrites it')
+ })
+
+ it('says when the platform has it but not its file, or cannot be asked', async () => {
+ if (platform === 'launchd') {
+ await serviceCommand(['install'], c.deps)
+ c.fake.set({ pid: null })
+ expect((await status())[1]).toBe(' status ◍ registered, not running (not running · last exit 1) · `harness start` starts it')
+ rmSync(c.service.file)
+ expect((await status())[1]).toBe(' status ◍ registered without its file · `harness service uninstall` clears it')
+ c.fake.set({ fail: { 'launchctl print': { status: 1, stderr: 'x' } } })
+ expect((await status())[1]).toBe(' status ○ not installed · `harness start` runs the daemon; `harness service install` hands it to launchd')
+ } else {
+ c.fake.set({ loaded: true })
+ c.service.write(c.deps.definition())
+ expect((await status())[1]).toBe(' status ◍ installed, not enabled · `harness service install` enables it')
+ c.fake.set({ fail: { 'systemctl show': { status: 1, stderr: 'Failed to connect to bus' } } })
+ expect((await status())[1]).toMatch(/^ status \? could not ask systemd: systemctl --user show .*Failed to connect to bus$/)
+ }
+ })
+
+ it('warns when systemd gave up, and when a logout would end the user manager', async () => {
+ if (platform === 'launchd') return
+ await serviceCommand(['install'], c.deps)
+ c.fake.set({ failed: true, pid: null, linger: 'no' })
+ const lines = await status()
+ expect(lines).toContain(' ! systemd gave up after repeated failures (start-limit-hit): `harness start` tries again · logs ~/data/harness.log')
+ expect(lines).toContain(' ! lingering is off: logging out of your last session ends your user manager, and with it the daemon')
+ c.out.length = 0
+ c.fake.set({ linger: 'no', failed: false })
+ rmSync(c.service.file)
+ await serviceCommand(['install'], c.deps)
+ expect(c.out).toContain(' and a tmux server it started. `loginctl enable-linger` keeps them running.')
+ })
+ })
+})
+
+describe('this computer\'s command dependencies', () => {
+ it('build the definition from this install, make folders, hold the spawn lock and print to the console', async () => {
+ const deps = serviceCommandDeps({ relaunch: async () => {}, tildify: (path) => path })
+ expect(deps.definition().logFile).toBe(join(process.env.ADAPTER_DATA_DIR!, 'harness.log'))
+ const dir = mkdtempSync(join(tmpdir(), 'service-deps-'))
+ try {
+ deps.ensureDir(join(dir, 'a', 'b'))
+ expect(existsSync(join(dir, 'a', 'b'))).toBe(true)
+ expect(deps.bundleExists(join(dir, 'a'))).toBe(true)
+ expect(deps.bundleExists(join(dir, 'none'))).toBe(false)
+ } finally { rmSync(dir, { recursive: true, force: true }) }
+ await expect(deps.withLock('start', async () => 'held')).resolves.toBe('held')
+ const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+ const error = vi.spyOn(console, 'error').mockImplementation(() => {})
+ try {
+ deps.out('o')
+ deps.err('e')
+ expect(log).toHaveBeenCalledWith('o')
+ expect(error).toHaveBeenCalledWith('e')
+ } finally { log.mockRestore(); error.mockRestore() }
+ })
+})
diff --git a/cli/src/lib/serviceCommand.ts b/cli/src/lib/serviceCommand.ts
new file mode 100644
index 000000000..ba45145ed
--- /dev/null
+++ b/cli/src/lib/serviceCommand.ts
@@ -0,0 +1,217 @@
+/**
+ * `harness service install | uninstall | status`: harnessd under launchd (macOS) or systemd (Linux).
+ *
+ * The platform runs the master in the foreground from login on, and starts it again if it dies: before,
+ * nothing restarted a master that died but the desktop app running `harness start` again, and on a
+ * computer without the app nothing did. Agents keep running in tmux whenever the daemon stops, as now.
+ *
+ * Opt-in. Without it nothing changes, and the desktop app does not use it yet. Once installed,
+ * `harness start` and `harness stop` act through the platform (./platformDaemon.ts), so there is one
+ * supervisor per machine. The definitions themselves are ../harnessd/platform.ts.
+ */
+import { existsSync, mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+import type { PlatformState, ServiceDefinition } from '../harnessd/platform.js'
+import { describeSpawnLockOwner, withSpawnLock, type SpawnLockPurpose } from './daemonSpawnLock.js'
+import { stopDaemonProcess } from './daemonStop.js'
+import {
+ PLATFORM_START_WAIT_MS, PLATFORM_STOP_WAIT_MS, describeState, platformDaemonDeps, serviceDefinition, waitForMaster, waitGone,
+ type PlatformDaemonDeps,
+} from './platformDaemon.js'
+
+export interface ServiceCommandDeps extends PlatformDaemonDeps {
+ /** What the platform would run for this install. */
+ definition(): ServiceDefinition
+ /** The installed bundle the definition runs is there. */
+ bundleExists(path: string): boolean
+ /** Make the log's folder: launchd and systemd open the log, but do not make its folder. */
+ ensureDir(path: string): void
+ /** `harness stop`'s stop. Re-entrant under the spawn lock this command holds. */
+ stopDaemon(): Promise<{ pid: number | null; stopped: boolean }>
+ /** Run `fn` holding the daemon spawn lock, so no `harness start` lands in the middle. */
+ withLock<T>(purpose: SpawnLockPurpose, fn: () => Promise<T>): Promise<T>
+ /** `harness start` the usual way, after an uninstall: it prints the daemon's status and exits. */
+ relaunch(): Promise<void>
+ out(line: string): void
+ err(line: string): void
+ tildify(path: string): string
+ /** How long to wait for the master to come up. */
+ startWaitMs?: number
+}
+
+export const SERVICE_USAGE = [
+ 'Usage: harness service <install | uninstall | status> [--json]',
+ '',
+ ' install run harnessd under launchd (macOS) or systemd (Linux): it starts at login and comes back',
+ ' if it dies. `harness start` and `harness stop` then go through the platform. Agents keep',
+ ' running in tmux whenever the daemon stops, as they do now',
+ ' uninstall stop that, and start the daemon the usual way again',
+ ' status what launchd or systemd has registered, and whether it runs (--json for machines)',
+ '',
+ 'Opt-in: without it, `harness start` (or the desktop app) runs the daemon, as it always has.',
+].join('\n')
+
+export async function serviceCommand(argv: string[], deps: ServiceCommandDeps): Promise<number> {
+ const words = argv.filter((arg) => !arg.startsWith('-'))
+ const json = argv.includes('--json')
+ const verb = words[0]
+ if (verb === undefined || verb === 'help' || argv.includes('-h') || argv.includes('--help')) {
+ deps.out(SERVICE_USAGE)
+ return 0
+ }
+ if (!['install', 'uninstall', 'status'].includes(verb)) {
+ deps.err(`Unknown command: harness service ${verb}\n\n${SERVICE_USAGE}`)
+ return 2
+ }
+ if (!deps.service) {
+ if (json && verb === 'status') deps.out(JSON.stringify({ supported: false }))
+ else deps.err('harness service runs harnessd under launchd (macOS) or systemd (Linux); this computer has neither.')
+ return verb === 'status' ? 0 : 1
+ }
+ if (verb === 'install') return installService(deps)
+ if (verb === 'uninstall') return uninstallService(deps)
+ return serviceStatus(deps, json)
+}
+
+async function installService(deps: ServiceCommandDeps): Promise<number> {
+ const service = deps.service!
+ const name = service.platform
+ const definition = deps.definition()
+ if (!deps.bundleExists(definition.scriptPath)) {
+ deps.err(`✗ No installed CLI at ${deps.tildify(definition.scriptPath)}. ${name} runs the installed bundle: install it first, then run this again.`)
+ return 1
+ }
+ // Asked before anything is written or stopped: a computer the platform cannot serve keeps its daemon.
+ const preflight = service.preflight()
+ if (!preflight.ok) {
+ deps.err(`✗ ${name} cannot run harnessd here: ${preflight.detail}`)
+ return 1
+ }
+ // Under the spawn lock from here: once the definition is on disk a `harness start` (the desktop app
+ // runs one whenever the daemon looks down) goes through the platform too, and must not land between
+ // the stop and the registration.
+ return deps.withLock('start', async () => {
+ const pid = deps.readPid()
+ const running = pid !== null && deps.isAlive(pid)
+ const before = service.inspect()
+ const rewritten = service.write(definition)
+ if (!rewritten && before.registered && running && before.pid === pid) {
+ deps.out(`harnessd already runs under ${name} (pid ${pid}); nothing to change.`)
+ return 0
+ }
+ deps.ensureDir(dirname(definition.logFile))
+ // One supervisor: whatever runs now, a master `harness start` spawned or the platform's own on an
+ // older definition, stops first. The agents keep running in tmux.
+ if (running || before.registered) await deps.stopDaemon()
+ const registered = service.register()
+ if (!registered.ok) {
+ service.discard()
+ deps.err(`✗ ${name} would not take harnessd: ${registered.detail}`)
+ if (running) deps.err(' The daemon was stopped to hand it over; `harness start` starts it again, as before.')
+ return 1
+ }
+ const up = await waitForMaster(deps, deps.startWaitMs ?? PLATFORM_START_WAIT_MS)
+ if (up === null) {
+ deps.err(`✗ ${name} has harnessd, but it did not come up (${describeState(service.inspect())}).`)
+ deps.err(` logs ${deps.tildify(deps.logFile)} · harness service status`)
+ return 1
+ }
+ deps.out(`✓ harnessd runs under ${name} (pid ${up}): it starts at login and comes back if it dies.`)
+ deps.out(` ${service.platform === 'launchd' ? 'agent' : 'unit '} ${deps.tildify(service.file)}`)
+ deps.out(' `harness start` and `harness stop` now go through it; agents keep running in tmux when the daemon stops.')
+ deps.out(' undo: harness service uninstall')
+ lingerNote(service.inspect(), deps)
+ return 0
+ })
+}
+
+async function uninstallService(deps: ServiceCommandDeps): Promise<number> {
+ const service = deps.service!
+ const name = service.platform
+ const before = service.inspect()
+ if (!before.installed && !before.registered) {
+ deps.out(`harnessd is not installed with ${name}; nothing to remove.`)
+ return 0
+ }
+ const pid = deps.readPid()
+ // The platform's own master is the daemon: once it goes, the daemon is started the usual way.
+ const platformRan = pid !== null && deps.isAlive(pid) && before.pid === pid
+ const removed = await deps.withLock('stop', async () => {
+ const outcome = service.unregister()
+ if (outcome.ok && platformRan && !await waitGone(deps, pid, PLATFORM_STOP_WAIT_MS)) await deps.stopDaemon()
+ return outcome
+ })
+ if (!removed.ok) {
+ deps.err(`✗ ${removed.detail}`)
+ return 1
+ }
+ deps.out(`✓ removed ${deps.tildify(service.file)}: ${name} no longer runs harnessd.`)
+ if (!platformRan) return 0
+ deps.out(' starting it the usual way…')
+ await deps.relaunch()
+ return 0
+}
+
+function serviceStatus(deps: ServiceCommandDeps, json: boolean): number {
+ const service = deps.service!
+ const name = service.platform
+ const state = service.inspect()
+ const current = state.installed && service.current(deps.definition())
+ if (json) {
+ deps.out(JSON.stringify({
+ supported: true, platform: state.platform, file: state.file, target: state.target, installed: state.installed, current,
+ registered: state.registered, running: state.pid !== null, pid: state.pid, state: state.state, lastExit: state.lastExit,
+ failed: state.failed, linger: state.linger, unreachable: state.unreachable,
+ }))
+ return 0
+ }
+ deps.out(`harnessd · ${name}`)
+ deps.out(` status ${statusLine(state, name)}`)
+ if (state.installed || state.registered) {
+ deps.out(` ${service.platform === 'launchd' ? 'agent ' : 'unit '} ${deps.tildify(state.file)}`)
+ deps.out(` target ${state.target}`)
+ }
+ if (state.installed && !current) deps.out(' ! the definition is not the one this install would write (another Node, bundle or setting): `harness service install` rewrites it')
+ if (state.failed) deps.out(` ! systemd gave up after repeated failures${state.lastExit ? ` (${state.lastExit})` : ''}: \`harness start\` tries again · logs ${deps.tildify(deps.logFile)}`)
+ lingerNote(state, deps)
+ return 0
+}
+
+function statusLine(state: PlatformState, name: string): string {
+ if (state.unreachable) return `? could not ask ${name}: ${state.unreachable}`
+ if (!state.installed && !state.registered) return `○ not installed · \`harness start\` runs the daemon; \`harness service install\` hands it to ${name}`
+ if (state.registered && !state.installed) return `◍ registered without its file · \`harness service uninstall\` clears it`
+ if (!state.registered) {
+ return state.platform === 'launchd'
+ ? '◍ installed, not loaded · it starts at your next login, or now with `harness start`'
+ : '◍ installed, not enabled · `harness service install` enables it'
+ }
+ if (state.pid !== null) return `● running (pid ${state.pid}) · starts at login, comes back if it dies`
+ return `◍ registered, not running (${describeState(state)}) · \`harness start\` starts it`
+}
+
+/** systemd without lingering ends the user's manager at their last logout, and everything under it. */
+function lingerNote(state: PlatformState, deps: Pick<ServiceCommandDeps, 'out'>): void {
+ if (state.linger !== false) return
+ deps.out(' ! lingering is off: logging out of your last session ends your user manager, and with it the daemon')
+ deps.out(' and a tmux server it started. `loginctl enable-linger` keeps them running.')
+}
+
+/** This computer's, for cli.ts: `relaunch` and `tildify` are the CLI's own. */
+export function serviceCommandDeps(options: { relaunch: () => Promise<void>; tildify: (path: string) => string }): ServiceCommandDeps {
+ const base = platformDaemonDeps()
+ return {
+ ...base,
+ definition: () => serviceDefinition({ logFile: base.logFile }),
+ bundleExists: (path) => existsSync(path),
+ ensureDir: (path) => { mkdirSync(path, { recursive: true, mode: 0o700 }) },
+ stopDaemon: () => stopDaemonProcess(),
+ withLock: (purpose, fn) => withSpawnLock(purpose, fn, {
+ onWaiting: (owner) => console.log(` the daemon is ${describeSpawnLockOwner(owner)} — waiting for it to finish…`),
+ }),
+ relaunch: options.relaunch,
+ out: (line) => console.log(line),
+ err: (line) => console.error(line),
+ tildify: options.tildify,
+ }
+}
diff --git a/cli/src/testing/fakePlatform.ts b/cli/src/testing/fakePlatform.ts
new file mode 100644
index 000000000..266b412a2
--- /dev/null
+++ b/cli/src/testing/fakePlatform.ts
@@ -0,0 +1,157 @@
+/**
+ * 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 { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+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
+}
+
+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 })),
+ }
+}
diff --git a/docs/design/2026-10-03-harnessd.md b/docs/design/2026-10-03-harnessd.md
index d081500d1..48f5cd29c 100644
--- a/docs/design/2026-10-03-harnessd.md
+++ b/docs/design/2026-10-03-harnessd.md
@@ -68,7 +68,7 @@ is in [2026-10-04-harnessd-before-after.md](2026-10-04-harnessd-before-after.md)
│ │
│ unix socket + 127.0.0.1:18473 relay server │
┌─┴─────────────────────────────────────────────────────────────────────────────────────────┴────┐
-│ │ harnessd supervised by launchd / systemd (planned) │ │
+│ │ harnessd supervised by launchd / systemd (opt-in) │ │
│ │ │ │
│ │ ┌────────────────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ MASTER · the supervisor │ │ │
@@ -336,6 +336,8 @@ the parts still to build say so.
supervisor per machine. tmux must stay out of the daemon's process group and cgroup — a systemd
stop kills everything in the unit's cgroup by default, and launchd kills a dead job's process
group — so agents keep running when the daemon stops, the way containerd shims keep containers.
+ Built as an opt-in, `harness service install` (see Rollout); not installed by default, and the
+ desktop app still runs `harness start`, which then goes through the platform.
- **Versioned spawn protocol.** Master and core may differ during an update. Messages are only ever
added, unknown ones are ignored, and each side states its protocol in its first message.
@@ -522,6 +524,32 @@ Done so far:
(`cli/src/core/transcripts/history.ts`, at 100%). The socket's case is one call into the slot cli.ts
binds, and the four database engines share one windowing path instead of a copy each. Every reply is
unchanged, field for field. `backendSocket.ts` is down from 3,482 lines to 3,139.
+- **Platform supervision, opt-in** (`harness service install | uninstall | status`;
+ `cli/src/harnessd/platform.ts`, `cli/src/lib/serviceCommand.ts`, `cli/src/lib/platformDaemon.ts`). A
+ launchd user agent (`~/Library/LaunchAgents/ai.autonomous.harness.harnessd.plist`) or a systemd user
+ unit (`~/.config/systemd/user/harnessd.service`) runs `<managed node> ~/.harness/cli/cli.js __harnessd`
+ in the foreground from login on, and starts it again after any exit but a clean one (launchd
+ `KeepAlive` with `SuccessfulExit` false and a 10 s `ThrottleInterval`; systemd `Restart=on-failure`).
+ Both append to `harness.log`, which the master trims. **It is opt-in: nothing changes for anyone who
+ does not run it, and the desktop app does not use it yet.**
+ - One supervisor per machine: once installed, `harness start` asks the platform to start the master
+ instead of spawning a second one, and every stop (stop, logout, reset, update) asks it to stop it,
+ since a signal from the CLI would read as a crash. The master records the platform in its status
+ file (`HARNESSD_PLATFORM`, set by the definition) and `harness status` shows a supervisor row.
+ - tmux outlives the daemon: the agent sets `AbandonProcessGroup`, the unit `KillMode=process`. Run
+ against a real systemd 259 (a Fedora container), tmux built with systemd support put every pane in a
+ scope `PartOf` the unit, so a stop job (`systemctl --user stop`, `restart`, `disable --now`) ended every
+ agent whatever `KillMode` said. So the CLI stops the master with a signal through systemd
+ (`systemctl --user kill --kill-who=main`) and lets it exit cleanly; the same container showed the
+ agents outliving stop and uninstall, and a killed master restarted. A tmux server in a scope of its
+ own (`systemd-run --user --scope`) would make stop jobs safe as well: a core change, still open.
+ - Tested against a temporary home and fake `launchctl` and `systemctl` alone on PATH, never the real
+ ones; `plutil -lint` checks the plist, and `systemd-analyze verify` the unit where it exists.
+ `e2e/cli.e2e.ts` runs `harness start`, `stop` and `status` from the installed bundle on the managed
+ Node: without the service no platform tool is asked and an agent outlives a stop in tmux; with it,
+ fakes that run the master from the definition (both platforms, on any computer, through
+ `HARNESSD_TEST_PLATFORM`) see start and stop go through them; another data folder's definition is
+ ignored.
Next, in order:
@@ -534,7 +562,8 @@ Next, in order:
4. **Services out of process,** one at a time, each behind its manifest entry and able to fall back
to in-process for one release: devices first, then relay (with the self-hosting settings),
models, workspaces, search, viewers, teams, the light host, Companion and Memory.
-5. **Platform supervision** (launchd agent, systemd user unit) and the master re-executing itself on
+5. **Platform supervision by default** (built as an opt-in above; the desktop app watching instead of
+ respawning, registered through `SMAppService` on macOS) and the master re-executing itself on
update.
6. **State directory move,** last, once nothing else is changing.
@@ -828,7 +857,8 @@ vitest configuration, as the orchestrator, sharing and resume suites already do.
- **Platform supervision by default.** Whether the launchd agent and systemd unit are installed on
every install, which on macOS asks the user once (Login Items).
- **tmux server.** Agents on the user's default tmux server, or a dedicated one that `tmux
- kill-server` cannot reach.
+ kill-server` cannot reach; and under systemd, whether the core starts it in a scope of its own, so a
+ stop job on the unit no longer reaches the panes (see Rollout, platform supervision).
- **Service defaults.** Which services start on a new install and which wait to be needed (a device
paired, sharing used, a viewer installed), and which light ones share the host.
- **Safe mode.** Whether three crashes in five minutes is the right trigger, and what a degraded core