Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

22.1 KB
Raw Blame
/**
 * `harness service install | uninstall | status`: harnessd under launchd (macOS), systemd (Linux) or Task
 * Scheduler (Windows, which starts the master rather than running it: `installTask`).
 *
 * 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 { execFile } from 'node:child_process'
import { existsSync, mkdirSync } from 'node:fs'
import { dirname } from 'node:path'
import { PLATFORM_LABEL, type PlatformState, type ServiceDefinition } from '../harnessd/platform.js'
import { describeSpawnLockOwner, readSpawnLockOwner, withSpawnLock, type SpawnLockPurpose } from './daemonSpawnLock.js'
import { stopDaemonProcess } from './daemonStop.js'
import {
  CARRIED_ENV, PLATFORM_START_WAIT_MS, PLATFORM_STOP_WAIT_MS, TASK_RUN_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
  /** Windows: [name] as set for the Windows user (`HKCU\Environment`, what `setx` writes), null when it is not or
   *  could not be read (`readUserEnvironment`). */
  userEnvironment?(name: string): Promise<string | null>
  /** Windows: someone holds the daemon spawn lock, as the task's own `harness start --if-down` does once it runs. */
  lockHeld?(): boolean
}

/**
 * `harness service install`'s exit code on Windows when the task is registered and will start harnessd at the next
 * sign-in, but did not start it now (Task Scheduler runs the task only in a signed-in Windows session). install.ps1 told
 * that apart from a failure only by this: with exit 1 it said "Harness could not set itself to start when you sign in"
 * of a task it had just registered (the Windows install job, B5.12). 5: harness.exe already exits 3 for a broken install
 * and 4 for a Node that does not start (pty/src/command.rs), and the CLI exits 1 and 2 (usage).
 */
export const SERVICE_REGISTERED_NOT_RUNNING = 5

/** As long as `reg query` is given: it reads one value. */
export const USER_ENVIRONMENT_TIMEOUT_MS = 3_000

/** `execFile`'s shape, as far as `readUserEnvironment` uses it. */
export type RegRun = (
  file: string, args: string[], options: { timeout: number; windowsHide: boolean }, done: (error: Error | null, stdout: string) => void,
) => unknown

/**
 * [name] from the Windows user's environment (`reg query HKCU\Environment /v <name>`, 3 s): a text value as it is
 * written, or null when there is none, it is not text, or reg failed, timed out or could not run. Never rejects.
 */
export function readUserEnvironment(name: string, run: RegRun = execFile as unknown as RegRun): Promise<string | null> {
  return new Promise((resolve) => {
    try {
      run('reg', ['query', 'HKCU\\Environment', '/v', name], { timeout: USER_ENVIRONMENT_TIMEOUT_MS, windowsHide: true }, (error, stdout) => {
        if (error) { resolve(null); return }
        // `    PORT    REG_SZ    18621`: names are case-insensitive on Windows.
        for (const line of String(stdout).split(/\r?\n/)) {
          const match = /^\s+(\S+)\s+REG_(?:EXPAND_)?SZ\s+(.*)$/.exec(line)
          if (match && match[1]!.toLowerCase() === name.toLowerCase()) { resolve(match[2]!); return }
        }
        resolve(null)
      })
    } catch {
      resolve(null)
    }
  })
}

export const SERVICE_USAGE = [
  'Usage: harness service <install | uninstall | status> [--json]',
  '',
  '  install    run harnessd under launchd (macOS), systemd (Linux) or Task Scheduler (Windows): 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, systemd or Task Scheduler 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')

/** Windows: Task Scheduler starts the daemon, it does not run it, and there is no tmux (harnessd/platform.ts). */
export const WINDOWS_SERVICE_USAGE = [
  'Usage: harness service <install | uninstall | status> [--json]',
  '',
  '  install    have Task Scheduler start the Harness daemon when you sign in to Windows,',
  '             and again within 5 minutes if it stops. `harness start` and `harness stop` then go through it',
  '  uninstall  remove that task: the daemon keeps running, and `harness start` starts it after this',
  '  status     what Task Scheduler has registered, and whether it is turned on (--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]
  const usage = deps.service?.platform === 'taskscheduler' ? WINDOWS_SERVICE_USAGE : SERVICE_USAGE
  if (verb === undefined || verb === 'help' || argv.includes('-h') || argv.includes('--help')) {
    deps.out(usage)
    return 0
  }
  if (!['install', 'uninstall', 'status'].includes(verb)) {
    deps.err(`Unknown command: harness service ${verb}\n\n${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), systemd (Linux) or Task Scheduler (Windows); this computer has none of them.')
    return verb === 'status' ? 0 : 1
  }
  if (deps.service.os && verb !== 'status') {
    deps.err(`Harness OS runs harnessd under ${deps.service.target} already: \`harness start\` and \`harness stop\` go through it, and there is nothing to ${verb}.`)
    return 1
  }
  if (verb === 'install') return installService(deps)
  if (verb === 'uninstall') return uninstallService(deps)
  return serviceStatus(deps, json)
}

async function installService(deps: ServiceCommandDeps): Promise<number> {
  if (deps.service!.platform === 'taskscheduler') return installTask(deps)
  const service = deps.service!
  const name = PLATFORM_LABEL[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' : service.platform === 'taskscheduler' ? 'task ' : '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 = PLATFORM_LABEL[service.platform]
  const task = service.platform === 'taskscheduler'
  const before = service.inspect()
  // Task Scheduler that could not be asked has not said there is no task: unregister says so (harnessd/platform.ts).
  // `registered` means both tasks there, so one task left on its own, its files gone, is found by its log (re-review N9).
  if (!before.installed && !before.registered && !(task && (before.unreachable || service.registeredFor(deps.logFile)))) {
    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) {
    if (task) {
      // What schtasks said is for whoever looks into it, under a sentence anyone reads.
      deps.err('✗ Harness could not remove the task that starts harnessd: Task Scheduler may still start it when you sign in.')
      deps.err(`  ${removed.detail}`)
    } else 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 = PLATFORM_LABEL[service.platform]
  const state = service.inspect()
  let current = false
  let uncompared: string | null = null
  try {
    current = state.installed && service.current(deps.definition())
  } catch (error) {
    // Windows renders the task with the user's SID, which whoami may not give: then it cannot be compared.
    uncompared = (error as Error).message
  }
  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 ' : service.platform === 'taskscheduler' ? 'task  ' : 'unit  '}      ${deps.tildify(state.file)}`)
    deps.out(`  target      ${state.target}`)
  }
  if (uncompared !== null) deps.out(`  ! Harness could not check the ${service.platform === 'taskscheduler' ? 'task' : 'definition'} against this install: ${uncompared}`)
  else 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.platform === 'taskscheduler') {
    if (!state.registered) return '◍ written, not registered · `harness service install` registers it'
    return state.state === 'disabled'
      ? '◍ registered, but turned off in Task Scheduler · `harness service install` turns it back on'
      : `● registered (${state.state}) · starts the daemon when you sign in to Windows, and again within 5 minutes if it stops`
  }
  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`
}

/**
 * Windows. Task Scheduler does not run the master, it starts it (harnessd/platform.ts), so nothing that runs is stopped:
 * the task is registered under the spawn lock, and run once outside it, when no daemon runs, because the task's own
 * `harness start --if-down` takes that lock and would find it held. Every failure is one sentence a person reads, and
 * what whoami or schtasks said goes on the line below it.
 */
async function installTask(deps: ServiceCommandDeps): Promise<number> {
  const service = deps.service!
  const definition = deps.definition()
  const launcher = definition.launcherPath ?? ''
  for (const needed of [launcher, definition.scriptPath]) {
    if (!deps.bundleExists(needed)) {
      deps.err(`✗ No installed CLI at ${deps.tildify(needed)}. Task Scheduler runs the installed CLI through bin\\harness-launch.exe: install it with install.ps1, then run this again.`)
      return 1
    }
  }
  const preflight = service.preflight()
  if (!preflight.ok) {
    deps.err('✗ Harness could not reach Task Scheduler, so it cannot start harnessd when you sign in to Windows.')
    deps.err(`  ${preflight.detail}`)
    return 1
  }
  const registered = await deps.withLock('start', async () => {
    const before = service.inspect()
    let written: boolean
    try {
      written = service.write(definition)
    } catch (error) {
      // The XML could not be made: whoami could not say who this is, or a path the task cannot hold. Nothing was written.
      return { ok: false as const, unwritten: true, detail: (error as Error).message }
    }
    // A task someone turned off in Task Scheduler is not installed and fine: registered again from the same file,
    // whose <Enabled>true</Enabled> turns it back on (`/Create /F`).
    if (!written && before.registered && before.state !== 'disabled') return 'already' as const
    const outcome = service.register()
    if (!outcome.ok) service.discard()
    // Gone now though it was there: the five-minute task replaced (/F), then removed again with its refused logon task.
    // `registered` means both tasks, so a five-minute task whose logon task was deleted by hand counts by its files (N8).
    return { ...outcome, unwritten: false, lost: !outcome.ok && (before.registered || before.installed) && !service.inspect().registered }
  })
  if (registered !== 'already' && !registered.ok) {
    deps.err(registered.unwritten
      ? '✗ Harness could not set up the task that starts harnessd when you sign in to Windows; nothing was changed.'
      // A refused logon task removes the five-minute task just made (harnessd/platform.ts register), which with /F had
      // replaced the one there before.
      : 'lost' in registered && registered.lost
        ? '✗ Task Scheduler did not accept the new task that starts harnessd, and no longer has the old one: `harness start` still starts harnessd, and `harness service install` tries again.'
        : '✗ Task Scheduler did not accept the task that starts harnessd; nothing was changed.')
    deps.err(`  ${registered.detail}`)
    return 1
  }
  const running = deps.readPid()
  let up = running !== null && deps.isAlive(running) ? running : null
  if (up === null) {
    const started = service.start(false)
    if (!started.ok) {
      deps.err('✗ Task Scheduler has the task that starts harnessd, but would not run it now: `harness start` starts harnessd.')
      deps.err(`  ${started.detail}`)
      return SERVICE_REGISTERED_NOT_RUNNING
    }
    // As `harness start` waits on the task (platformDaemon.ts startThroughTask): a short while, and longer only once the
    // task's own start holds the spawn lock. Over SSH Task Scheduler runs nothing, and this waited the whole minute,
    // then printed a ✗ for what is not a failure (G4, final review R1b-3).
    const wait = deps.startWaitMs ?? PLATFORM_START_WAIT_MS
    up = await waitForMaster(deps, Math.min(TASK_RUN_WAIT_MS, wait))
    if (up === null && !deps.lockHeld?.()) {
      deps.out('Task Scheduler will start Harness when you sign in to Windows. It did not start it now: it runs the task only in a session at the Windows desktop, not over SSH.')
      deps.out('  start it now: harness start')
      return SERVICE_REGISTERED_NOT_RUNNING
    }
    if (up === null) up = await waitForMaster(deps, wait)
    if (up === null) {
      deps.err('✗ Task Scheduler started harnessd, but it did not come up: `harness start` starts it now.')
      deps.err(`  logs ${deps.tildify(deps.logFile)}   ·   harness service status`)
      return SERVICE_REGISTERED_NOT_RUNNING
    }
  }
  if (registered === 'already') deps.out(`harnessd is registered with Task Scheduler already (${service.target}); nothing to change.`)
  else {
    deps.out(`✓ Task Scheduler starts the Harness daemon when you sign in to Windows, and again within 5 minutes if it stops (pid ${up} runs now).`)
    deps.out(`  task   ${service.target}`)
    deps.out('  undo: harness service uninstall')
  }
  // A task's action has no environment of its own (harnessd/platform.ts): it runs with the user's logon environment,
  // and the task is the user's one, whatever data folder this shell names. Reported rather than refused: a value set
  // for the Windows user as well reaches it. PORT is read back from the user's environment: one set with `setx`
  // reaches the task, and was warned of all the same (task-B3.21 finding F4). A read that fails warns, as before.
  let carried = Object.keys(definition.env).filter((name) => (CARRIED_ENV as readonly string[]).includes(name))
  if (carried.includes('PORT') && deps.userEnvironment && await deps.userEnvironment('PORT') === definition.env.PORT) {
    carried = carried.filter((name) => name !== 'PORT')
  }
  if (carried.length) {
    deps.out(`  ! the task starts harness with your Windows user environment, not this shell's: ${carried.join(', ')} set only here ${carried.length > 1 ? 'do' : 'does'} not reach it`)
    deps.out('    so the daemon it starts uses your user settings. Set these for your Windows user, or run this from a shell without them.')
  }
  return 0
}

/** 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,
    userEnvironment: (name) => readUserEnvironment(name),
    lockHeld: () => readSpawnLockOwner() !== null,
  }
}