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.

11.6 KB
Raw Blame
/**
 * `harness uninstall`'s end of the Harness terminal host (pty/, A): the panes the daemon could not stop as harnesses
 * (a terminal, an agent whose stop was refused), then the host. Each pane is killed with the op the daemon uses, which
 * gives it its grace, then the host is asked to shut down, which it does only with no pane left.
 *
 * A host that does not answer, refuses to shut down, or speaks a protocol without `shutdown`, is ended by its pid, on
 * every platform only once one read of the process table proves the pid is the host this home's discovery file named:
 * a harness-pty image, with a start marker, started no later than the file was written, running `serve --home` this
 * home. A pid alone proves nothing: the pty home outlives a reboot or a host crash, after which the recorded pid can
 * be any of the user's processes, or another install's host (the review of B5.7, round 1). The kill is B3's
 * identity-checked one (pid + start marker): TerminateProcess on Windows, SIGTERM on Unix, never a tree kill.
 */
import { statSync } from 'node:fs'
import path from 'node:path'
import { env } from '../../config/env.js'
import type { PtyHostClient, PtyHostDiscovery } from '../ptyHost/client.js'
import { discoveryFileName } from '../ptyHost/instance.js'
import { discoveredHostDead, listDiscoveries, pidAlive, reachPtyHost, type HostLiveness } from '../ptyHost/launch.js'
import { SHUTDOWN_PROTOCOL, SUPPORTED_PTY_PROTOCOLS } from '../ptyHost/protocol.js'
import { startedNoLaterThan, startMarkerMs } from '../processProof.js'
import { argvTokens, processRows, type ProcessRow } from '../processTable.js'
import { windowsProcessRows } from '../windows/processTable.js'
import { terminateVerified } from '../windows/terminate.js'

/** As long as `harness stop` gives the daemon (daemonStop.ts STOP_GRACE_MS). */
export const PANE_GRACE_MS = 3_000
export const HOST_EXIT_WAIT_MS = 5_000

export type HostClient = Pick<PtyHostClient, 'call' | 'close' | 'protocol' | 'pid'>
type HostRow = Pick<ProcessRow, 'pid' | 'executable' | 'startMarker'> & Partial<ProcessRow>

export interface PtyHostsDeps {
  platform: NodeJS.Platform
  /** The pty home (HARNESS_PTY_DIR) whose hosts these are: a host must run `serve --home` it to be ended. */
  home: string
  /** This home's discovery records, each with when it was written as it was read (null when that could not be read):
   *  a host that agreed to shut down removes its record before it exits, and is still judged against it. */
  discover(): RecordedHost[]
  reach(instance: string): Promise<{ client: HostClient } | { unreachable: string }>
  alive(pid: number): boolean
  /** A's proof that the discovery file's host has gone (its pid now belongs to a later process). */
  dead(discovery: PtyHostDiscovery): Promise<boolean>
  rows(): Promise<readonly HostRow[] | null>
  /** The identity-checked kill: TerminateProcess on Windows, SIGTERM on Unix. */
  terminate(pid: number, startMarker: string): Promise<'ended' | 'gone' | 'mismatch'>
  sleep(ms: number): Promise<void>
}

export interface RecordedHost { discovery: PtyHostDiscovery; written: number | null }

export interface PtyHostEnd { pid: number; protocol: number; panes: number; how: 'shut down' | 'ended' | 'gone' | 'left'; detail?: string }

async function gone(deps: PtyHostsDeps, pid: number, ms: number): Promise<boolean> {
  for (let waited = 0; deps.alive(pid); waited += 100) {
    if (waited >= ms) return false
    await deps.sleep(100)
  }
  return true
}

export async function endPtyHosts(deps: PtyHostsDeps): Promise<PtyHostEnd[]> {
  const ended: PtyHostEnd[] = []
  for (const recorded of deps.discover()) {
    const { discovery } = recorded
    const { pid, protocol } = discovery
    if (!deps.alive(pid) || await deps.dead(discovery)) { ended.push({ pid, protocol, panes: 0, how: 'gone' }); continue }
    let panes = 0
    let why: string
    const reached = await deps.reach(discovery.instance)
    if ('client' in reached) {
      const client = reached.client
      let agreed = false
      why = `its protocol (${client.protocol}) has no shutdown`
      try {
        for (let round = 0; round < 2; round++) {
          const inventory = await client.call({ op: 'inventory' })
          if (inventory.state !== 'ok') why = `its panes could not be listed (${inventory.reason})`
          const rows = inventory.state === 'ok' ? inventory.value.panes : []
          for (const row of rows) if ((await client.call({ op: 'kill', pane: row.pane, graceMs: PANE_GRACE_MS })).state === 'ok') panes++
          if (rows.length) await deps.sleep(PANE_GRACE_MS)
          if (client.protocol < SHUTDOWN_PROTOCOL) break
          // A pane made between the inventory and the shutdown is refused, and gets one more round. An answer lost on
          // the way (`unknown`) may be a host already exiting: it is waited for like an `ok`.
          const shutdown = await client.call({ op: 'shutdown' })
          if (shutdown.state !== 'failed') { agreed = true; break }
          why = `it would not shut down (${shutdown.reason})`
        }
      } finally {
        client.close()
      }
      // Only a host that agreed is waited for: one that refused, or has no shutdown, is not about to exit.
      if (agreed) {
        if (await gone(deps, pid, HOST_EXIT_WAIT_MS)) { ended.push({ pid, protocol, panes, how: 'shut down' }); continue }
        why = 'it agreed to shut down but did not exit'
      }
    } else {
      why = reached.unreachable
    }
    ended.push({ pid, protocol, panes, ...await force(deps, recorded, why) })
  }
  return ended
}

const HOST_IMAGE = /(^|[\\/])harness-pty(\.exe)?$/i

/**
 * Whether [row]'s image is a harness-pty. macOS `ps -o comm=` cuts the image's path to 16 characters (measured
 * 2026-10-18: `/Users/<user>/`, `pty/target/relea`), so on Unix a comm that is the start of the program argv names
 * stands for it, and that program is checked instead. The program is everything before ` serve`, since `ps` quotes no
 * path with a space in it.
 */
function hostImage(row: HostRow, platform: NodeJS.Platform): boolean {
  if (HOST_IMAGE.test(row.executable)) return true
  if (platform === 'win32' || !row.executable) return false
  const text = row.args ?? ''
  const serve = text.search(/\sserve(\s|$)/)
  const program = row.nativeArgv?.[0] ?? (serve >= 0 ? text.slice(0, serve) : argvTokens(text)[0] ?? '')
  return HOST_IMAGE.test(program) && program.startsWith(row.executable)
}

/**
 * Whether [row] runs `serve --home` [home]. Windows paths compare without case, as Windows opens them. Unix `ps` joins
 * argv with spaces and quotes nothing, so a home with a space in it is looked for in the text as a whole, followed by
 * the next flag or the end.
 */
function servesHome(row: HostRow, home: string, platform: NodeJS.Platform): boolean {
  const paths = platform === 'win32' ? path.win32 : path.posix
  const same = (a: string, b: string) => {
    const [x, y] = [paths.resolve(a), paths.resolve(b)]
    return platform === 'win32' ? x.toLowerCase() === y.toLowerCase() : x === y
  }
  const argv = row.nativeArgv ?? argvTokens(row.args ?? '')
  const serve = argv.indexOf('serve')
  if (serve >= 0) {
    for (let at = argv.indexOf('--home', serve + 1); at >= 0; at = argv.indexOf('--home', at + 1)) {
      const value = argv[at + 1]
      // Tokens split from text: a word after the value that is not the next flag means the value was cut there
      // (`serve --home /x/pty old` is not the home /x/pty).
      const next = row.nativeArgv ? undefined : argv[at + 2]
      if (value !== undefined && same(value, home) && (next === undefined || next.startsWith('--'))) return true
    }
  }
  if (platform === 'win32' || row.nativeArgv || !/\s/.test(home)) return false
  const text = row.args ?? ''
  const serveAt = text.search(/(^|\s)serve(\s|$)/)
  if (serveAt < 0) return false
  return [home, paths.resolve(home)].some((wanted) => {
    const flag = ` --home ${wanted}`
    for (let at = text.indexOf(flag, serveAt); at >= 0; at = text.indexOf(flag, at + 1)) {
      const after = text.slice(at + flag.length)
      if (after === '' || after.startsWith(' --')) return true
    }
    return false
  })
}

async function force(deps: PtyHostsDeps, { discovery, written }: RecordedHost, why: string): Promise<Pick<PtyHostEnd, 'how' | 'detail'>> {
  const { pid } = discovery
  // One read: the row that proves the identity is the one whose start marker the kill checks.
  const row = (await deps.rows())?.find((candidate) => candidate.pid === pid)
  if (!row?.startMarker) return { how: 'left', detail: `${why}, and its start time could not be read` }
  if (!hostImage(row, deps.platform)) return { how: 'left', detail: `${why}, and pid ${pid} is not a harness-pty process` }
  // Exited since the top of the loop: it is not a later process to be judged.
  if (!deps.alive(pid)) return { how: 'gone' }
  // Fail closed: a pid is the recorded host only when its start is known to be no later than its record.
  if (written === null || startMarkerMs(row.startMarker) === null) return { how: 'left', detail: `${why}, and its record's time could not be read` }
  if (!startedNoLaterThan(row, written)) {
    return { how: 'left', detail: `${why}, and pid ${pid} started after its record was written, so it is another process` }
  }
  if (!servesHome(row, deps.home, deps.platform)) return { how: 'left', detail: `${why}, and pid ${pid} is not the host of ${deps.home}` }
  const outcome = await deps.terminate(pid, row.startMarker)
  if (outcome === 'mismatch') return { how: 'left', detail: `${why}; pid ${pid} changed while it was being ended` }
  if (outcome === 'gone') return { how: 'gone' }
  // TerminateProcess has ended it; SIGTERM only asks.
  if (deps.platform === 'win32' || await gone(deps, pid, HOST_EXIT_WAIT_MS)) return { how: 'ended' }
  return { how: 'left', detail: `${why}, and it outlived SIGTERM` }
}

function writtenAt(file: string): number | null {
  try {
    return statSync(file).mtimeMs
  } catch {
    return null
  }
}

/** This computer's hosts, in HARNESS_PTY_DIR. */
export function ptyHostsDeps(home: string = env.HARNESS_PTY_DIR): PtyHostsDeps {
  // The process table on every platform: Windows reads it from harness-pty, Unix from `ps` (with `lstart` markers).
  const rows = process.platform === 'win32' ? () => windowsProcessRows(null) : processRows
  const liveness: HostLiveness = { alive: pidAlive, rows }
  return {
    platform: process.platform,
    home,
    discover: () => {
      // Each record's time before the records: one rewritten in between is judged against the older time, which a
      // later host fails, so the error is on the side of leaving it. Keyed by instance: a legacy `p2` and any number
      // of versioned `p2-<tag>` hosts of one protocol each have their own record.
      const written = new Map(listDiscoveries(home).map((found) => [found.instance, writtenAt(path.join(home, 'run', discoveryFileName(found.instance) ?? ''))]))
      return listDiscoveries(home)
        .filter((discovery) => SUPPORTED_PTY_PROTOCOLS.includes(discovery.protocol))
        .map((discovery) => ({ discovery, written: written.get(discovery.instance) ?? null }))
    },
    reach: async (instance) => {
      const result = await reachPtyHost(home, instance, liveness)
      return 'client' in result ? { client: result.client } : { unreachable: 'incompatible' in result ? result.incompatible : result.unavailable }
    },
    alive: pidAlive,
    dead: (discovery) => discoveredHostDead(home, discovery, liveness),
    rows,
    terminate: process.platform === 'win32'
      ? (pid, marker) => terminateVerified(pid, marker)
      : (pid, marker) => terminateVerified(pid, marker, { rows: processRows, kill: (target) => { process.kill(target, 'SIGTERM') } }),
    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
  }
}