The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
harnessd: launchd and systemd supervision, opt-in (harness service install) (#781)
Deee491d34b9c65
diff --git a/cli/e2e/cli.e2e.ts b/cli/e2e/cli.e2e.tsnew file mode 100644index 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.mjsnew file mode 100644index 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(/</g, '<').replace(/>/g, '>').replace(/"/g, '"').replace(/'/g, "'").replace(/&/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.tsindex 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 stateharness 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 Desktopharness 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_Dprocess.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?: stringconnection: { 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 | numkdirSync(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 hereconst 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 | nuprocess.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 | nustatus: 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) : nullprintInfoBlock({// 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)+ breakcase 'reset':resetCommand().catch(onError)breakdiff --git a/cli/src/cliCommand.spec.ts b/cli/src/cliCommand.spec.tsindex 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.mdindex 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 runningunknown 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 thecore 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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&<m>"o'</string>')+ expect(plist).toContain('<string><&></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.tsnew file mode 100644index 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, '&').replace(/</g, '<').replace(/>/g, '>').replace(/"/g, '"').replace(/'/g, ''')++/** 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.tsindex 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.tsindex 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.tsindex 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_000export 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()): Prorelease()}}++/**+ * 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.mdindex 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 systemdstop kills everything in the unit's cgroup by default, and launchd kills a dead job's processgroup — 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 everadded, 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.tsbinds, and the four database engines share one windowing path instead of a copy each. Every reply isunchanged, 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 backto 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 onupdate.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 onevery 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 devicepaired, 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