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.

12.9 KB
Raw Blame
/**
 * Harness's updater, in a process of its own that harnessd's master runs (`harness __service updater`,
 * harnessd/services.ts `UPDATER_HOST`), only for the installed copy with updates on (masterProcess.ts).
 *
 * It checks the release manifest for a newer CLI and a newer hn, downloads and verifies them, runs the new
 * CLI's canary and stages it (lib/selfUpdate.ts, tui/install.ts), then tells the master (`harnessd:staged`).
 * The master asks the core to hand over (`harnessd:update`) and judges the new build on probation, as when
 * the core staged it itself. That is what it was until now: the core's process downloaded builds, a 15 s
 * canary and minutes of downloads in a process that must never go down, and a core in safe mode ran on
 * only for its updater. Here a broken download or a hung check costs this process alone, and a core that
 * cannot start at all still gets its fix (docs/design/2026-10-06-core-boundary-next.md, "Updaters").
 *
 * Once it has staged a build it exits with `SERVICE_EXIT_RESTART`, and the master starts it again at once:
 * a staging is the updater's last act on the bundle it runs, and the next check is the new build's.
 *
 * On Windows it checks the terminal host's payload too (lib/windows/ptyUpdate.ts), under a master that judges one
 * (`HARNESSD_JUDGES_PTY`). A host alone is staged and told as `ptyVersion`; a host and a build found at one check go
 * in one lock hold and one message, the host first. Either staging ends this process the same way, and the next run
 * checks both again. A host of a protocol above this build's (a paired one) goes in only with the build that needs it;
 * if that build then fails to stage, the host is taken back out and nothing is told (lib/windows/ptyUpdate.ts
 * `takeBackPty`).
 */
import { userInfo } from 'node:os'
import { env } from '../config/env.js'
import { isTeamAccount, readTeamConfig } from '../team/config.js'
import { SERVICE_EXIT_RESTART, type StagedUpdate, type UpdaterMessage } from '../harnessd/protocol.js'
import { describeSpawnLockOwner, withSpawnLock } from '../lib/daemonSpawnLock.js'
import { DOWNLOAD_LIMITS, downloadVerified, isLocalDevBuild, retireCliVersions, startSelfUpdater } from '../lib/selfUpdate.js'
import { currentCli } from '../lib/windows/installLayout.js'
import { processRetireDeps } from '../lib/windows/cliVersions.js'
import { preparePtyPayload, ptyManifestUrl, ptyPlatformKey } from '../lib/windows/ptyPayload.js'
import { installedPtyProtocol, startPtyUpdater, sweepPtyLeftovers, takeBackPty, type StagedHost } from '../lib/windows/ptyUpdate.js'
import { startTuiUpdater } from '../tui/update.js'
import { VERSION } from '../version.js'
import { harnessdEnv } from '../lib/harnessdEnv.js'
import { dirname } from 'node:path'
import type { ServiceProcess } from './process.js'

export interface UpdaterServiceDeps {
  /** Tell the master; `sent` once the message has left (an exit before it would lose it). */
  tell(message: UpdaterMessage, sent: () => void): void
  exit(code: number): void
  startCli: typeof startSelfUpdater
  startHn: typeof startTuiUpdater
  log(line: string): void
  /** Windows: retire the older CLI builds (lib/selfUpdate.ts `retireCliVersions`), once as the updater starts — it
   *  starts again after every build it stages, and with every master. Left out elsewhere. */
  retire?: () => Promise<unknown>
  /** The build that is installed, which the start line names: on Windows the one `cli\current` points to, which after a
   *  rollback is not the build this process runs from. This process's VERSION when left out. */
  installedVersion?: () => string
  /** Windows: the terminal host's poller, and the install root it works in (`bin\`, `runtime\pty\`). Left out
   *  elsewhere. */
  startPty?: typeof startPtyUpdater
  ptyRootDir?: string
  /** Windows: the protocol of the installed host, which a CLI build must not need more than (lib/selfUpdate.ts
   *  `installedPtyProtocol`). Left out elsewhere. */
  installedPtyProtocol?: () => number | null
  /** Whether this daemon is a Mac's Harness Team account (team/config.ts names its user); real by default. */
  inTeamAccount?: () => boolean
}

/** [cliDir]: the CLI folder the retirement looks at, this user's own unless a test names one of its own. */
export const processUpdaterDeps = (platform: NodeJS.Platform = process.platform, cliDir: string = env.ADAPTER_CLI_DIR): UpdaterServiceDeps => ({
  tell: (message, sent) => {
    // Under its master, the spawn channel; started by hand, there is no one to tell, and nothing to wait on.
    if (!process.send) { sent(); return }
    process.send(message, () => sent())
  },
  exit: (code) => process.exit(code),
  startCli: startSelfUpdater,
  startHn: startTuiUpdater,
  log: (line) => console.log(line),
  // Under the lock every stage takes: a `harness update` that renames a build's folder into place and then moves the
  // pointer to it must not find the folder gone in between.
  ...(platform === 'win32' ? {
    retire: () => withSpawnLock('update', () => retireCliVersions(cliDir, processRetireDeps())),
    installedVersion: () => currentCli(dirname(cliDir))?.version ?? VERSION,
    startPty: startPtyUpdater,
    ptyRootDir: dirname(cliDir),
    installedPtyProtocol: () => installedPtyProtocol(dirname(cliDir)),
  } : {}),
})

export function runUpdaterService(_options?: unknown, deps: UpdaterServiceDeps = processUpdaterDeps()): ServiceProcess {
  // What its master, or the core it runs beside, said: held out of process.env (lib/harnessdEnv.ts).
  const harnessd = harnessdEnv()
  const installed = deps.installedVersion?.() ?? VERSION
  const limits = { idleMs: env.ADAPTER_UPDATE_IDLE_MS, deadlineMs: env.ADAPTER_UPDATE_DEADLINE_MS, floorBytesPerSecond: DOWNLOAD_LIMITS.floorBytesPerSecond }
  // One lock section at a time in this process. The spawn lock is re-entrant, so it does not keep this process's two
  // pollers apart: a host installed while the CLI's handover is under way would be told in a second message.
  let section: Promise<unknown> = Promise.resolve()
  const oneAtATime = <T>(fn: () => Promise<T>): Promise<T> => {
    const run = section.then(fn, fn)
    section = run.catch(() => {})
    return run
  }
  // The lock spans the byte swap and the word to the master: a `harness start` or `harness update` that
  // lands between them would stage over the backup this one just made.
  const withLock = <T>(fn: () => Promise<T>): Promise<T> => oneAtATime(() => withSpawnLock('handoff', fn, {
    onWaiting: (owner) => deps.log(`[update] waiting — the daemon is ${describeSpawnLockOwner(owner)}`),
  }))
  const handOver = (staged: StagedUpdate): Promise<void> => new Promise<void>((done) => {
    deps.tell({ type: 'harnessd:staged', ...staged }, () => {
      done()
      deps.exit(SERVICE_EXIT_RESTART)
    })
  })
  const pty = startPty(deps, harnessd, installed, limits, withLock, handOver)
  // Windows: what installs leave in bin\ and runtime\pty\ is swept at every start, under the lock; the poller does
  // that itself before its first check, and without one (a master from before, an unusable manifest URL) it is done
  // here. A bin file missing whose aside file holds its bytes is put back first, and while one is not, nothing goes.
  if (!pty && deps.ptyRootDir !== undefined) {
    const root = deps.ptyRootDir
    void withLock(async () => { sweepPtyLeftovers(root, deps.log) })
      .catch((error: unknown) => deps.log(`[update] could not sweep the terminal host's leftovers (${error instanceof Error ? error.message : String(error)}) — the next start tries again`))
  }
  // A host the CLI's handover took (`beforeStage`) and has not told yet: if that stage fails, a supported one is told on
  // its own, and a paired one taken back out.
  let ptyTaken: StagedHost | null = null
  const cli = deps.startCli({
    currentVersion: VERSION,
    // The Harness Team account takes releases even over the local build setup may have copied into it (selfUpdate.ts).
    ...((deps.inTeamAccount ?? inTeamAccount)() ? { followReleases: true } : {}),
    url: env.ADAPTER_UPDATE_URL,
    key: env.ADAPTER_UPDATE_KEY,
    dir: env.ADAPTER_CLI_DIR,
    intervalMs: env.ADAPTER_UPDATE_CHECK_MS,
    slotSecond: env.ADAPTER_UPDATE_SLOT_SEC,
    withLock: (fn) => withLock(async () => {
      try {
        return await fn()
      } finally {
        // Installed for this handover and then the build's stage failed. A supported host is on disk, on probation, and
        // must still be handed over, or no master would judge it. A paired one would come up under this build, which
        // cannot open a pane on it, and a master judging it with this build's core would likely keep it: it is taken
        // back out, and nothing is handed over; its poller, finished by that install, checks again, backed off as a
        // refused payload is, and prepares it again for the build after.
        const taken = ptyTaken
        ptyTaken = null
        if (taken?.paired && deps.ptyRootDir !== undefined) {
          takeBackPty(deps.ptyRootDir, deps.log, '[update] ')
          pty?.takenBack()
        } else if (taken !== null) await handOver({ ptyVersion: taken.version })
      }
    }),
    // A paired host (one of a protocol above this build's) goes in only for the build that needs it: the poller is told
    // which protocol that is, and the CLI's protocol rule hears what is ready to go in first.
    ...(pty ? {
      beforeStage: async (ptyProtocol: number) => {
        ptyTaken = await pty.readyToStage(ptyProtocol)
        return ptyTaken && { version: ptyTaken.version, protocol: ptyTaken.protocol }
      },
      readyPtyProtocol: () => pty.readyProtocol(),
    } : {}),
    onStaged: (version, ptyVersion) => {
      ptyTaken = null
      return handOver({ version, ...(ptyVersion ? { ptyVersion } : {}) })
    },
    limits,
    // Under any master: a build that needs a host this machine does not have would open no pane, whoever judged it.
    ...(deps.installedPtyProtocol ? { installedPtyProtocol: deps.installedPtyProtocol } : {}),
    // A master judges a build staged while the one before is on probation (#807). Beside a core, under a
    // master too old to run the updater (core/updaterBeside.ts), only one that says so: one from before
    // rolled the newer build back with the one it judged.
    stageWhileJudged: harnessd.HARNESSD_UPDATER_BESIDE_CORE !== '1' || harnessd.HARNESSD_JUDGES_SUPERSEDED === '1',
  })
  // hn is an independent, optional download: its failure never holds up the CLI's fix.
  const hn = deps.startHn({
    currentVersion: VERSION,
    isInstalledCopy: true,
    disabled: env.ADAPTER_UPDATE_DISABLE,
    intervalMs: env.ADAPTER_UPDATE_CHECK_MS,
    slotSecond: env.ADAPTER_UPDATE_SLOT_SEC,
  })
  // Never in the way of the update itself: a pass that fails is the next start's to repeat.
  void deps.retire?.().catch((error: unknown) => deps.log(`[update] retiring older CLI builds failed: ${error instanceof Error ? error.message : String(error)}`))
  // A development build is never replaced (lib/selfUpdate.ts isLocalDevBuild): it said "on" and polled in silence (G5).
  deps.log(isLocalDevBuild(installed)
    ? `[update] self-update off · v${installed} is a development build, which never takes an update`
    : `[update] self-update on · v${installed} · every ${Math.round(env.ADAPTER_UPDATE_CHECK_MS / 1000)}s`)
  return { stop: () => { cli.stop(); hn.stop(); pty?.stop() } }
}

/** Windows, under a master that judges a host: the terminal host's poller (lib/windows/ptyUpdate.ts). Null otherwise. */
function startPty(
  deps: UpdaterServiceDeps, harnessd: NodeJS.ProcessEnv, installed: string, limits: typeof DOWNLOAD_LIMITS,
  withLock: <T>(fn: () => Promise<T>) => Promise<T>, handOver: (staged: StagedUpdate) => Promise<void>,
): ReturnType<typeof startPtyUpdater> | null {
  if (!deps.startPty || deps.ptyRootDir === undefined) return null
  // Under a master from before, a host staged would be told to no one who rolls it back: it waits for the master to
  // be replaced by one that does (the next CLI update).
  if (harnessd.HARNESSD_JUDGES_PTY !== '1') return null
  const key = ptyPlatformKey()
  let url: string
  try {
    url = ptyManifestUrl(env.ADAPTER_UPDATE_URL)
  } catch (error) {
    deps.log(`[update] no terminal host updates: ${error instanceof Error ? error.message : String(error)}`)
    return null
  }
  if (key === null) return null
  return deps.startPty({
    url, key, rootDir: deps.ptyRootDir,
    intervalMs: env.ADAPTER_UPDATE_CHECK_MS,
    slotSecond: env.ADAPTER_UPDATE_SLOT_SEC,
    installedCli: () => deps.installedVersion?.() ?? installed,
    withLock,
    onStaged: (ptyVersion) => handOver({ ptyVersion }),
    deps: { prepare: (entry, runtimeDir, verified) => preparePtyPayload(entry, runtimeDir, { download: (ref) => downloadVerified(ref, limits) }, verified) },
  })
}

/** This process runs as the Harness Team account its Mac's root-owned config names. An account whose name cannot be read
 *  is not it. */
export function inTeamAccount(config: () => ReturnType<typeof readTeamConfig> = () => readTeamConfig(), user = () => userInfo().username): boolean {
  return isTeamAccount(config, user)
}