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.

28.4 KB
Raw Blame
/**
 * Finding `harness-pty` and the host build it is (the target), finding hosts by their instance (their discovery files),
 * and starting one when there is none. In production harnessd keeps the host running (sub-project B); this is how the
 * daemon gets one without it, in development and tests.
 */
import { execFileSync, spawn } from 'node:child_process'
import { accessSync, constants, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs'
import net from 'node:net'
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import { env } from '../../config/env.js'
import { scrubTerminalContext } from '../terminalEnvironment.js'
import { PtyHostClient, type PtyHostDiscovery } from './client.js'
import { discoveryFileName, hostInstanceName, instanceProtocol } from './instance.js'
import { PTY_PROTOCOL, SUPPORTED_PTY_PROTOCOLS } from './protocol.js'
import { pidAlive, recordedProcessDead, startMarkerMs, type HostLiveness, type HostProcessRow } from '../processProof.js'

// Moved to ../processProof.ts with the daemon's own record; still exported from here for the pty host's callers.
export { pidAlive, startMarkerMs, type HostLiveness, type HostProcessRow }

const BINARY = process.platform === 'win32' ? 'harness-pty.exe' : 'harness-pty'
/** How long a host we started has to publish its discovery file. */
const START_WAIT_MS = 5_000
const POLL_MS = 25
/** How long a connection may take to be accepted: as long as `PtyHostClient.connect` gives a hello. */
const CONNECT_TIMEOUT_MS = 5_000
/** How long `harness-pty version` may take. */
const VERSION_TIMEOUT_MS = 5_000

function runnable(file: string): boolean {
  try {
    accessSync(file, process.platform === 'win32' ? constants.F_OK : constants.X_OK)
    return true
  } catch {
    return false
  }
}

export const VERSION_DIR = /^\d+(\.\d+)*$/

/**
 * Orders two versions: their dotted numbers first, then a pre-release (`-dev.win1`) before its release, as semver
 * does, and build metadata (`+…`) not at all. A host's version is any build string (a dev build's is not a plain
 * number), so a part that is not a number counts as 0. The order is total: two versions that differ only in how they
 * are written are told apart by that, so readdir's order never picks.
 */
export function compareVersions(a: string, b: string): number {
  const va = versionParts(a)
  const vb = versionParts(b)
  for (let i = 0; i < Math.max(va.core.length, vb.core.length); i++) {
    const d = (va.core[i] ?? 0) - (vb.core[i] ?? 0)
    if (d !== 0) return d
  }
  if (va.pre !== vb.pre) {
    if (va.pre === null) return 1
    if (vb.pre === null) return -1
    return va.pre < vb.pre ? -1 : 1
  }
  // `1.0` and `1.0.0` are the same version; order them anyway so readdir's order cannot pick.
  return a.length - b.length || (a < b ? -1 : a > b ? 1 : 0)
}

function versionParts(version: string): { core: number[]; pre: string | null } {
  const plain = version.split('+')[0]
  const dash = plain.indexOf('-')
  const core = (dash < 0 ? plain : plain.slice(0, dash)).split('.').map((part) => Number(part) || 0)
  return { core, pre: dash < 0 ? null : plain.slice(dash + 1) }
}

export interface PtyHostBinaryOptions {
  env?: NodeJS.ProcessEnv
  runtimeDir?: string
  /** The bundle's own directory (`dist/` in a release); the binary is looked for in its `pty/`. */
  besideDir?: string
}

/**
 * `<runtime>/pty/current-pty`: the name of the `<runtime>/pty/<version>/` directory whose host the installed CLI
 * ships, as `current-grid` pins grid (gridBinary.ts). The installer writes it (sub-project B); this reads it. Only a
 * version name is taken, so the pointer can never name a file outside `<runtime>/pty/`.
 */
export function currentPtyVersion(runtimeDir: string = env.ADAPTER_RUNTIME_DIR): string | null {
  try {
    const recorded = readFileSync(path.join(runtimeDir, 'pty', 'current-pty'), 'utf8').trim()
    return VERSION_DIR.test(recorded) ? recorded : null
  } catch {
    return null
  }
}

/**
 * The `harness-pty` to start, or null when there is none:
 * 1. `HARNESS_PTY_BIN`, as it is (a wrong override should fail loudly, not fall back);
 * 2. `<runtime>/pty/<version>/harness-pty[.exe]` for the version `current-pty` names. Binaries install per version
 *    because Windows cannot overwrite a running .exe (spec §4, host upgrade); older ones stay for the hosts still
 *    draining on them. Pinned, not the newest directory there: a newer one may be another install's, of another
 *    protocol, or one that has not finished (Task 12's review);
 * 3. in `pty/` beside the bundle, where `build-bundle.mjs` puts it with its ConPTY payload for local Windows testing
 *    (scripts/lib/ptyPayload.mjs).
 */
export function ptyHostBinary(options: PtyHostBinaryOptions = {}): string | null {
  const override = (options.env ?? process.env).HARNESS_PTY_BIN?.trim()
  if (override) return override
  const runtimeDir = options.runtimeDir ?? env.ADAPTER_RUNTIME_DIR
  const version = currentPtyVersion(runtimeDir)
  if (version) {
    const file = path.join(runtimeDir, 'pty', version, BINARY)
    if (runnable(file)) return file
  }
  const beside = path.join(options.besideDir ?? path.dirname(fileURLToPath(import.meta.url)), 'pty', BINARY)
  return runnable(beside) ? beside : null
}

/** `<home>/run/<instance's discovery file>`, or null for anything that is not an instance. */
function discoveryPath(home: string, instance: string): string | null {
  const name = discoveryFileName(instance)
  return name ? path.join(home, 'run', name) : null
}

/**
 * The discovery file named [name] in [home]'s run directory, or null when it is missing or not one. A file's own
 * `instance` and `protocol` must be well formed and agree with each other and with the file's name: a copy under
 * another name, or a file that names another instance, is not that instance's.
 */
function readDiscoveryFile(home: string, name: string): PtyHostDiscovery | null {
  try {
    const value = JSON.parse(readFileSync(path.join(home, 'run', name), 'utf8'))
    if (
      value && typeof value === 'object'
      && typeof value.instance === 'string'
      && discoveryFileName(value.instance) === name
      && value.protocol === instanceProtocol(value.instance)
      && typeof value.endpoint === 'string'
      && typeof value.pid === 'number'
      && typeof value.version === 'string'
      && typeof value.token === 'string'
    ) {
      const { protocol, instance, endpoint, pid, version, token } = value
      return { protocol, instance, endpoint, pid, version, token }
    }
  } catch {
    // Missing, or caught mid-way by a reader that is not atomic: the caller looks again.
  }
  return null
}

/** [instance]'s discovery file (a legacy `p<n>` from `pty-host-<n>.json`), or null when it is missing or not one. */
export function readInstanceDiscovery(home: string, instance: string): PtyHostDiscovery | null {
  const name = discoveryFileName(instance)
  return name ? readDiscoveryFile(home, name) : null
}

const DISCOVERY_FILE = /^pty-host-.+\.json$/

/**
 * Every host discovery file in [home]: legacy (`pty-host-<n>.json`) and versioned, of every protocol, supported or
 * not. Oldest first: by protocol, then by version (`compareVersions`).
 */
export function listDiscoveries(home: string): PtyHostDiscovery[] {
  let names: string[]
  try {
    names = readdirSync(path.join(home, 'run'))
  } catch {
    return []
  }
  return names
    .filter((name) => DISCOVERY_FILE.test(name))
    .flatMap((name) => readDiscoveryFile(home, name) ?? [])
    .sort((a, b) => a.protocol - b.protocol || compareVersions(a.version, b.version) || (a.instance < b.instance ? -1 : 1))
}

/** What `harness-pty version` says of its build. */
export interface PtyHostBinaryVersion { version: string; protocol: number; features: string[] }

/** `binaryVersion`'s, with whether the build is from before features (and so before versioned instances). */
type ReadVersion = PtyHostBinaryVersion & { legacy: boolean }

/** `binaryVersion`'s answers, by path: kept while the file's mtime is the same, so each build is run once. */
const versions = new Map<string, { mtimeMs: number; value: ReadVersion }>()

function readBinaryVersion(binary: string): ReadVersion | null {
  const key = path.resolve(binary)
  let mtimeMs: number
  try {
    mtimeMs = statSync(key).mtimeMs
  } catch {
    return null
  }
  const known = versions.get(key)
  if (known && known.mtimeMs === mtimeMs) return known.value
  let value: ReadVersion | null = null
  try {
    // Synchronous: once per build.
    const parsed = JSON.parse(runVersionCommand(binary).trim()) as Record<string, unknown> | null
    const features = parsed?.features
    if (
      parsed && typeof parsed === 'object'
      && typeof parsed.version === 'string' && parsed.version !== ''
      && Number.isSafeInteger(parsed.protocol) && (parsed.protocol as number) >= 1
      && (features === undefined || (Array.isArray(features) && features.every((name) => typeof name === 'string')))
    ) {
      value = {
        version: parsed.version, protocol: parsed.protocol as number,
        features: features === undefined ? [] : [...features as string[]], legacy: features === undefined,
      }
    }
  } catch {
    // Did not run, timed out, or said something else: no version. Asked again next time.
  }
  if (value) versions.set(key, { mtimeMs, value })
  return value
}

/**
 * How this CLI asks a PTY build what it is: `<binary> version`, an argument array so no shell reads the path, hidden
 * so no console flashes on Windows, within 5 s. One definition for `runVersionCommand` here (synchronous, the daemon's
 * `binaryVersion`) and the payload canary's asynchronous run (lib/windows/ptyPayload.ts `probeVersionLine`), which must
 * never block the updater's event loop.
 */
export const VERSION_COMMAND = {
  args: ['version'] as readonly string[],
  options: { encoding: 'utf8', timeout: VERSION_TIMEOUT_MS, windowsHide: true } as const,
}

/** What `<binary> version` prints, or a throw when it fails to run, exits non-zero or takes longer than 5 s. */
export function runVersionCommand(binary: string): string {
  return execFileSync(binary, [...VERSION_COMMAND.args], { ...VERSION_COMMAND.options, stdio: ['ignore', 'pipe', 'ignore'] })
}

/**
 * What [binary] says it is (`harness-pty version`: `{"version","protocol","features"}`), or null when it cannot be
 * run or says something else. A build from before features lists none: `[]`. Run with a 5 s timeout, hidden, and
 * cached by path and mtime.
 */
export function binaryVersion(binary: string): PtyHostBinaryVersion | null {
  const read = readBinaryVersion(binary)
  return read ? { version: read.version, protocol: read.protocol, features: [...read.features] } : null
}

/**
 * `previous` of `pty-pending.json` (lib/windows/ptyInstall.ts `PTY_PENDING`), or null with no marker. Read here rather
 * than imported: ptyInstall.ts imports this module.
 */
function probationPrevious(ptyRoot: string): string | null {
  try {
    const previous: unknown = JSON.parse(readFileSync(path.join(ptyRoot, 'pty-pending.json'), 'utf8'))?.previous
    return typeof previous === 'string' && previous !== '' ? previous : null
  } catch {
    return null
  }
}

/** The builds `targetHost` said it would not target, by path and version: said once each. */
const toldUnsupported = new Set<string>()

/** The host build new panes go to: the one this daemon would start. */
export interface PtyHostTarget {
  protocol: number
  version: string
  instance: string
  features: readonly string[]
  /** `installed`: the version is the one `current-pty` names (the binary is that folder's); `binary`: it said so. */
  source: 'installed' | 'binary'
}

/**
 * The target host: the build `ptyHostBinary()` resolves. Its version is the one `current-pty` names when the binary
 * is that folder's, else the binary's own (a dev build's `HARNESS_PTY_BIN`, the bundle's). Its protocol and features
 * are always the binary's (`binaryVersion`). Null when there is no binary or it cannot say what it is: the version,
 * or the protocol, is then unknown, and the caller does what it did before targets.
 *
 * The instance is the one the host will publish: named from the binary's own version (instance.rs names it so), and
 * `p<protocol>` for a build from before features, which predates versioned instances too.
 *
 * A build of a protocol outside `SUPPORTED_PTY_PROTOCOLS` is no target either (said once per binary): a paired host left
 * in `current-pty` without the CLI build that needs it (spec §5, the pairing rule), which `ensurePtyHost` would only
 * find incompatible. Unknown, the daemon takes the newest running host it speaks, as it did before targets.
 */
export function targetHost(options: PtyHostBinaryOptions = {}): PtyHostTarget | null {
  const binary = ptyHostBinary(options)
  if (!binary) return null
  const read = readBinaryVersion(binary)
  if (!read) return null
  if (!SUPPORTED_PTY_PROTOCOLS.includes(read.protocol)) {
    const key = `${path.resolve(binary)}\u0000${read.version}`
    if (!toldUnsupported.has(key)) {
      toldUnsupported.add(key)
      console.error(`[terminal] ptyhost: the host ${read.version} speaks protocol ${read.protocol}, which this daemon does not (it speaks ${SUPPORTED_PTY_PROTOCOLS.join(' and ')}): target unknown, the newest running host of protocol ${PTY_PROTOCOL} is used`)
    }
    return null
  }
  const runtimeDir = options.runtimeDir ?? env.ADAPTER_RUNTIME_DIR
  const current = currentPtyVersion(runtimeDir)
  const installed = current !== null && path.resolve(binary) === path.resolve(runtimeDir, 'pty', current, BINARY)
  return {
    protocol: read.protocol,
    version: installed ? current : read.version,
    instance: read.legacy ? `p${read.protocol}` : hostInstanceName(read.protocol, read.version),
    features: [...read.features],
    source: installed ? 'installed' : 'binary',
  }
}

const DEFAULT_LIVENESS: HostLiveness = { alive: (pid) => pidAlive(pid) }

/**
 * Whether the host [discovery] names is proven dead, so nothing should dial its endpoint: a Windows host that died
 * leaves its file naming a pipe that any user can see in `\\.\pipe\` and create once the host's last instance is
 * gone, and dialling it hands the hello (and the daemon's identity, libuv sets no SQOS) to whoever did. Proof: the
 * pid runs no process; or the process table has no such pid; or the process with it started after the discovery
 * file was written (the pid was given to another process since). No proof (a table that cannot be read, a file that
 * cannot be stat'ed) is not death: the endpoint is dialled as before, and a hello that fails there stays an error.
 */
export async function discoveredHostDead(
  home: string,
  discovery: Pick<PtyHostDiscovery, 'instance' | 'pid'>,
  liveness: HostLiveness = DEFAULT_LIVENESS,
): Promise<boolean> {
  const file = discoveryPath(home, discovery.instance)
  // Not an instance: no file to judge it by, so no proof.
  if (!file) return false
  return recordedProcessDead(file, discovery.pid, liveness)
}

export type PtyHostUnavailable = { unavailable: string; code: 'PTY_HOST_UNAVAILABLE' }
export type EnsurePtyHostResult = { client: PtyHostClient } | PtyHostUnavailable | { incompatible: string }

export interface EnsurePtyHostOptions {
  /**
   * The host new panes go to (`targetHost`): only its instance is connected to, and the binary is started for it.
   * Null when the target is unknown: the newest running host of `PTY_PROTOCOL`, whatever its build, as before targets.
   */
  target: PtyHostTarget | null
  /** The binary to start; `null` means there is none. Defaults to `ptyHostBinary()`. */
  binary?: string | null
  /** How long a started host has to publish its discovery file. */
  waitMs?: number
  /** How a discovery file's host is proven dead before it is dialled (`discoveredHostDead`); its pid alone by default. */
  liveness?: HostLiveness
}

const unavailable = (reason: string): PtyHostUnavailable => ({ unavailable: reason, code: 'PTY_HOST_UNAVAILABLE' })

type Connected = { client: PtyHostClient } | { incompatible: string } | null

/**
 * The host [instance]'s discovery file names: a client, `{ incompatible }` when it answers but refuses this
 * daemon, or null when nothing answers there (or there is no file).
 */
async function connectInstance(home: string, instance: string, liveness: HostLiveness): Promise<Connected> {
  const discovery = readInstanceDiscovery(home, instance)
  if (!discovery) return null
  // A dead host's endpoint is never dialled: no host, so the caller starts one (a drain backend's judges it gone).
  if (await discoveredHostDead(home, discovery, liveness)) return null
  const result = await PtyHostClient.connect(discovery)
  if (result instanceof PtyHostClient) return { client: result }
  if (result === null) return null
  // A host that restarted between our read and our hello has a new token: read the file again.
  const again = readInstanceDiscovery(home, instance)
  if (again && (again.token !== discovery.token || again.endpoint !== discovery.endpoint)) {
    if (await discoveredHostDead(home, again, liveness)) return null
    const retried = await PtyHostClient.connect(again)
    if (retried instanceof PtyHostClient) return { client: retried }
    if (retried === null) return null
    return { incompatible: retried.incompatible }
  }
  return { incompatible: result.incompatible }
}

/** The hosts a start for [instance] (null: any build of `PTY_PROTOCOL`) waits for or finds, oldest first. */
function hostsFor(home: string, instance: string | null): PtyHostDiscovery[] {
  if (instance !== null) {
    const discovery = readInstanceDiscovery(home, instance)
    return discovery ? [discovery] : []
  }
  return listDiscoveries(home).filter((discovery) => discovery.protocol === PTY_PROTOCOL)
}

/**
 * [instance]'s host; with null, the newest host of `PTY_PROTOCOL` that answers, else the first refusal. A dead host's
 * endpoint is never dialled (`connectInstance`).
 */
async function connectExisting(home: string, instance: string | null, liveness: HostLiveness): Promise<Connected> {
  if (instance !== null) return connectInstance(home, instance, liveness)
  let refused: Connected = null
  for (const discovery of hostsFor(home, null).reverse()) {
    const result = await connectInstance(home, discovery.instance, liveness)
    if (result && 'client' in result) return result
    refused ??= result
  }
  return refused
}

/**
 * Whether something accepts a connection at `endpoint` within `timeoutMs` (the hello's own limit); it is closed
 * without a hello. A connection never accepted (a stopped host's full backlog) counts as nothing there, and must not
 * hold the shared start for this home.
 */
export function reachable(endpoint: string, timeoutMs = CONNECT_TIMEOUT_MS): Promise<boolean> {
  return new Promise(resolve => {
    const socket = net.connect(endpoint)
    const finish = (accepted: boolean) => {
      clearTimeout(timer)
      socket.destroy()
      resolve(accepted)
    }
    const timer = setTimeout(() => finish(false), timeoutMs)
    socket.once('connect', () => finish(true))
    socket.once('error', () => finish(false))
  })
}

/** One start per home and instance at a time in this process; concurrent callers share it. */
const starting = new Map<string, Promise<PtyHostUnavailable | null>>()

function startHost(home: string, instance: string | null, binary: string | null, waitMs: number, liveness: HostLiveness): Promise<PtyHostUnavailable | null> {
  const key = `${path.resolve(home)}\u0000${instance ?? ''}`
  let start = starting.get(key)
  if (!start) {
    start = spawnAndWait(home, instance, binary, waitMs, liveness).finally(() => starting.delete(key))
    starting.set(key, start)
  }
  return start
}

/**
 * Start `binary serve --home <home>` and wait for a discovery file of [instance] (null: of any build of
 * `PTY_PROTOCOL`) that was not there before, or names another pid.
 */
async function spawnAndWait(home: string, instance: string | null, binary: string | null, waitMs: number, liveness: HostLiveness): Promise<PtyHostUnavailable | null> {
  const seen = (discovery: PtyHostDiscovery) => `${discovery.instance}\u0000${discovery.pid}`
  const before = hostsFor(home, instance)
  const known = new Set(before.map(seen))
  // A caller that found no host may arrive just after another caller's start finished. Not a dead host's endpoint:
  // something else may have taken its name (`discoveredHostDead`).
  const live = (discovery: PtyHostDiscovery) => discoveredHostDead(home, discovery, liveness).then((dead) => !dead)
  const answering = async (discoveries: PtyHostDiscovery[]) => {
    for (const discovery of discoveries) if (await live(discovery) && await reachable(discovery.endpoint)) return true
    return false
  }
  if (await answering(before)) return null
  if (!binary) return unavailable('harness-pty is not installed')
  let failed: string | null = null
  let exitedCleanly = false
  try {
    // Detached so the host outlives this daemon: panes must survive a daemon restart, as tmux's
    // do. On Windows the host also breaks away from the daemon's job by re-executing itself.
    // Without the daemon's own tmux identity (`TMUX`, `TMUX_PANE`), which a daemon started from a tmux pane has:
    // every pane the host spawns inherits its environment, and would read as that tmux pane's to a hook or a shell.
    // In the home, not the daemon's directory: a running program's directory cannot be removed on Windows, and the
    // daemon's may be an old install's. On the first start of a home (a fresh HARNESS_PTY_DIR) it is made first.
    mkdirSync(home, { recursive: true, mode: 0o700 })
    const child = spawn(binary, ['serve', '--home', home], {
      cwd: home, detached: true, windowsHide: true, stdio: 'ignore', env: scrubTerminalContext({ ...process.env }),
    })
    child.once('error', err => { failed ??= `could not start ${binary}: ${err.message}` })
    child.once('exit', (code, signal) => {
      // 0 is a host that found another one already serving this home.
      if (code === 0) exitedCleanly = true
      else failed ??= `${binary} exited with ${code === null ? `signal ${signal}` : `code ${code}`}`
    })
    child.unref()
  } catch (err) {
    return unavailable(`could not start ${binary}: ${(err as Error).message}`)
  }
  const deadline = Date.now() + waitMs
  while (Date.now() < deadline) {
    await new Promise(resolve => setTimeout(resolve, POLL_MS))
    if (failed) return unavailable(failed)
    const now = hostsFor(home, instance)
    if (now.some((discovery) => !known.has(seen(discovery)))) return null
    if (exitedCleanly && await answering(now)) return null
  }
  return unavailable(`harness-pty did not publish its discovery file within ${waitMs} ms`)
}

/**
 * A client of the host serving `home` that new panes go to, starting the host first when nothing answers at the
 * endpoint its discovery file names. With a target, that is the target's instance alone: a host of another build is
 * never connected to, though it runs. Without one (null), the newest running host of `PTY_PROTOCOL`. `incompatible`
 * is a host that answers and refuses this daemon; starting another would not replace it.
 */
export async function ensurePtyHost(home: string, options: EnsurePtyHostOptions): Promise<EnsurePtyHostResult> {
  const liveness = options.liveness ?? DEFAULT_LIVENESS
  const instance = options.target?.instance ?? null
  const existing = await connectExisting(home, instance, liveness)
  if (existing) return existing
  const binary = options.binary !== undefined ? options.binary : ptyHostBinary()
  const failed = await startHost(home, instance, binary, options.waitMs ?? START_WAIT_MS, liveness)
  if (failed) return failed
  // The host this start found or made published a discovery file, but nothing answers where it says.
  return (await connectExisting(home, instance, liveness)) ?? unavailable('no harness-pty answers at the endpoint its discovery file names')
}

/**
 * `reachPtyHost`'s: nothing answered. What the discovery file named, for the caller to judge whether that host is gone
 * (a drain backend checks the process table, ptyHostBackend.ts): `pid` from a readable file, else null; `missing`
 * when there is no file at all, which a read that failed (caught mid-write, unreadable) is not.
 */
export type PtyHostUnreached = PtyHostUnavailable & { pid: number | null; missing: boolean }
export type ReachPtyHostResult = { client: PtyHostClient } | { incompatible: string } | PtyHostUnreached

/**
 * A client of [instance]'s host serving `home`, never starting one: how a drain backend reaches a host that new panes
 * no longer go to (ptyHost/drain.ts). Whether a host that does not answer has gone is not decided here: a file that
 * could not be read, or a pid that runs, is no proof either way.
 */
export async function reachPtyHost(home: string, instance: string, liveness: HostLiveness = DEFAULT_LIVENESS): Promise<ReachPtyHostResult> {
  const name = discoveryFileName(instance)
  // Not an instance: there is no file it could have.
  if (!name) return { ...unavailable(`${JSON.stringify(instance)} is not a pty host instance`), pid: null, missing: true }
  const discovery = readInstanceDiscovery(home, instance)
  if (!discovery) {
    const missing = !existsSync(path.join(home, 'run', name))
    return { ...unavailable(missing ? `there is no ${name}` : `${name} cannot be read`), pid: null, missing }
  }
  const existing = await connectInstance(home, instance, liveness)
  if (existing) return existing
  return { ...unavailable(`nothing answers for the ${instance} host (pid ${discovery.pid})`), pid: discovery.pid, missing: false }
}

/**
 * Take down what [instance]'s host that has exited left published: its discovery file, and its socket file on
 * Unix. Only while the file still names [pid] and that process is gone: a host that took its place keeps its own.
 * A host that shut down (protocol 2 on) has removed them itself; a protocol 1 host ended by its pid leaves them.
 */
export function forgetExitedHost(home: string, instance: string, pid: number): void {
  const discovery = readInstanceDiscovery(home, instance)
  const file = discoveryPath(home, instance)
  if (!discovery || !file || discovery.pid !== pid || pidAlive(pid)) return
  rmSync(file, { force: true })
  // The host's lock and pane-id counter sit beside its discovery file under the same name. The host cannot delete the
  // lock itself: removing it before the lock is released lets a host starting meanwhile lock an unlinked file while
  // another makes a new one. Here the host is proven gone, so no one holds either; one a scanner still holds stays
  // for the next time.
  for (const ext of ['lock', 'panes']) {
    try { rmSync(file.replace(/\.json$/, `.${ext}`), { force: true }) } catch { /* held for now */ }
  }
  if (process.platform !== 'win32' && path.isAbsolute(discovery.endpoint)
    && path.dirname(discovery.endpoint) === path.join(home, 'run')) rmSync(discovery.endpoint, { force: true })
}

/**
 * Delete the `<runtime>/pty/<version>/` directories no host runs from any more, after a drained host has gone: every
 * version older than the one `current-pty` names (the installed CLI's) whose version no running host of [home] has
 * (any instance's discovery file, legacy or versioned: its `version`, its pid alive). The current one, newer ones (another install's, perhaps not
 * finished), the one a version on probation would roll back to (`pty-pending.json`'s `previous`), and anything that
 * is not a version directory stay. Nothing goes without a `current-pty`: with no
 * installed CLI's word, no version is known to be old. A directory that cannot be removed (a running .exe on
 * Windows, of some other home's host) stays for the next time. Returns the versions removed.
 */
export function removeUnusedPtyVersions(home: string, runtimeDir: string = env.ADAPTER_RUNTIME_DIR): string[] {
  const current = currentPtyVersion(runtimeDir)
  if (!current) return []
  const root = path.join(runtimeDir, 'pty')
  const running = new Set(listDiscoveries(home).filter((host) => pidAlive(host.pid)).map((host) => host.version))
  // While a version is on probation, the one it replaced is what a rollback puts back, host or not.
  const rollback = probationPrevious(root)
  if (rollback) running.add(rollback)
  let names: string[]
  try {
    names = readdirSync(root)
  } catch {
    return []
  }
  const removed: string[] = []
  for (const name of names) {
    if (!VERSION_DIR.test(name) || compareVersions(name, current) >= 0 || running.has(name)) continue
    const dir = path.join(root, name)
    try {
      if (!statSync(dir).isDirectory()) continue
      rmSync(dir, { recursive: true, force: true })
      removed.push(name)
    } catch (error) {
      console.error(`[terminal] ptyhost: could not remove ${dir}: ${(error as Error).message}`)
    }
  }
  return removed
}