Skip to content

Durable coding-agent harnesses (Claude Code, Codex, OpenCode, Pi, fx) on a Workflow SDK World

27.6 KB
Raw Blame
import { type ChildProcess, execFileSync, spawn } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import { existsSync, readdirSync, readFileSync, rmSync } from 'node:fs';
import { appendFile, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { basename, join, resolve } from 'node:path';
import { createInterface, type Interface } from 'node:readline';
import { isAlive } from 'harness-world/anchor';
import { Unavailable, Yield } from 'harness-world';
import type { ProcessHostLike, ProcessLike } from './environment.ts';

/**
 * The process host: where a process harness's child runs. One child per
 * session and drive, in its own process group, with an explicit environment,
 * in a per-session directory, recorded in a pidfile so the next drive on this
 * machine kills a child a dead drive left running before it resumes the
 * session (a child outlives a parent killed with SIGKILL: it is not in the
 * parent's group, and nothing else stops it).
 *
 * POSIX only (process groups, signals).
 */

/**
 * A child that did not start, told apart: a binary that is not on this
 * machine (or cannot run here) is `Unavailable`, which fails the turn
 * instead of having the queue redeliver into the same error (see
 * harness-world's unavailable.ts). Node says `spawn <command> ENOENT` for a
 * missing working directory too, so ENOENT counts only when the binary
 * itself is missing; anything else is the error as it was.
 */
export function spawnFailure(err: unknown, command: string, cwd: string): unknown {
  const e = err as NodeJS.ErrnoException;
  const code = e?.code ?? (/\bUnknown system error -8\b/.test(e?.message ?? '') ? 'ENOEXEC' : undefined);
  const named = command.includes('/');
  if (code === 'ENOENT') {
    if (!existsSync(cwd)) return err;
    if (named && existsSync(command)) return err;
    return new Unavailable(`${command} is not on this machine (spawn ENOENT)`, { code: 'binary_missing', cause: err });
  }
  if ((code === 'EACCES' || code === 'ENOEXEC') && existsSync(cwd) && (!named || existsSync(command))) {
    const why = code === 'EACCES' ? 'is not executable' : 'is not a binary this machine can run';
    return new Unavailable(`${command} ${why} (spawn ${code})`, { code: 'binary_unusable', cause: err });
  }
  return err;
}

/** Where session directories go by default. */
export function defaultRoot(): string {
  if (process.env.HARNESS_PROCESS_ROOT) return resolve(process.env.HARNESS_PROCESS_ROOT);
  // Vercel Functions: only /tmp is writable, and HOME may be read-only.
  if (process.env.VERCEL) return join(tmpdir(), 'harness-sessions');
  return resolve('.sessions');
}

/** A session's directory and the parts of it a child gets. */
export interface SessionDir {
  /** `<root>/<runId>`: the child's default cwd. */
  path: string;
  /** The child's `HOME` (a CLI's config and session files land here, not in the user's home). */
  home: string;
  /** The child's `TMPDIR`. */
  tmp: string;
  /** The host's own files (the pidfile). */
  state: string;
  /**
   * The group registry: one file per process group a shell under this
   * session registered itself in (named by the group id), so what a tool
   * started is killed with the child (see `ProcessHost`). Under `tmp`, which
   * a harness's own sandbox lets its commands write.
   */
  groups: string;
}

/** What the pidfile records about a running child. */
export interface PidRecord {
  pid: number;
  /** A random token in the child's environment (`HARNESS_PROCESS_TOKEN`): proves a pid is still ours on Linux. */
  token: string;
  argv: string[];
  startedAt: number;
  /** Other process groups to kill with it (tools that left the child's group). */
  groups: number[];
}

export interface SpawnOptions {
  command: string;
  args?: string[];
  /**
   * The child's environment, on top of `PATH`, `HOME` (the session's home)
   * and `TMPDIR` (the session's tmp). Nothing else of this process's
   * environment is inherited: pass every variable the child needs, and no
   * secret it does not.
   */
  env?: Record<string, string | undefined>;
  /** Default: the session directory. */
  cwd?: string;
  /** Kill the child's whole group when this aborts (pass `ctx.signal`). */
  signal?: AbortSignal;
  /** Default `pipe` (kept as `stderrTail()`). */
  stderr?: 'pipe' | 'inherit' | 'ignore';
  /**
   * Runs after a stale child is killed and before this one starts, with the
   * session claimed: rebuild the harness's native session files here (from
   * the journal), so no other drive of this host can start a child, and no
   * stale one can write, in between.
   */
  prepare?: (dir: SessionDir) => Promise<void> | void;
  /**
   * Start a watchdog (`watchParent`) that kills the child's group, and every
   * group its tools registered, within about a second of this process
   * dying. A SIGKILL of the drive (a crash, a chaos drill) reaches neither
   * otherwise: the child is in a group of its own, and a command a tool
   * started outlives it. Default false.
   */
  watchdog?: boolean;
}

export interface Exit {
  code: number | null;
  signal: NodeJS.Signals | null;
}

/** A running child on this machine: a `ProcessLike` (its stdio, `alive`, `kill`), plus what only this host has (the `ChildProcess`, its pid, adopted groups). */
export interface HostedProcess extends ProcessLike {
  readonly pid: number;
  readonly child: ChildProcess;
  /** Resolves when the child exits (never rejects). */
  readonly exited: Promise<Exit>;
  /** Whether the child is still running. */
  alive(): boolean;
  /** Kill the child's process group and every adopted group. Default SIGKILL. */
  kill(signal?: NodeJS.Signals): void;
  /** Record another process group (a tool that left the child's group) to kill with this one, now and on the next resume. */
  adopt(pgid: number): Promise<void>;
  /** Write one line to the child's stdin (a value is sent as JSON). False once stdin is closed. */
  send(line: unknown): boolean;
  /** Close the child's stdin. */
  end(): void;
  /** The child's stdout, line by line. One reader per process. */
  lines(): AsyncIterable<string>;
  /** The last few KB of stderr (with `stderr: 'pipe'`). */
  stderrTail(): string;
}

const PIDFILE = 'pid.json';
const STDERR_KEEP = 8192;

/**
 * Sourced by every shell a child starts under the session's environment
 * (`BASH_ENV` for non-interactive bash, `ENV` for an interactive sh, and the
 * session home's `.bashrc`, `.bash_profile`, `.profile` and `.zshenv` for
 * login and interactive shells and every zsh): it records the shell's
 * process group in `HARNESS_PROCESS_GROUPS`. A harness's built-in shell
 * tools (Claude Code's Bash, Codex's shell, OpenCode's shell) start each
 * command in a process group of its own, which a kill of the child's group
 * does not reach, and which outlives the child: the registry is how the
 * host still finds and kills them. It also turns job control off, so a
 * command's processes stay in the registered group. POSIX sh, no fork on
 * Linux (`/proc`), `ps` elsewhere; it never changes the shell's positional
 * parameters.
 */
export const GROUP_REGISTRY_SCRIPT = `# harness-world-process: register this shell's process group (see ProcessHost).
if [ -n "\${HARNESS_PROCESS_GROUPS:-}" ] && [ -d "\$HARNESS_PROCESS_GROUPS" ]; then
  _hwg=
  if [ -r "/proc/\$\$/stat" ]; then
    read -r _hws < "/proc/\$\$/stat"
    _hws=\${_hws##*") "}; _hws=\${_hws#* }; _hws=\${_hws#* }; _hwg=\${_hws%% *}
  else
    _hwg=\$( (ps -o pgid= -p \$\$ | tr -d ' ') 2>/dev/null )
  fi
  # No group id (a sandbox that refuses \`ps\`, as Codex's macOS one does): the pid, for the host to resolve.
  case "\$_hwg" in ''|*[!0-9]*) _hwf="pid-\$\$" ;; *) _hwf=\$_hwg ;; esac
  [ -e "\$HARNESS_PROCESS_GROUPS/\$_hwf" ] || date +%s > "\$HARNESS_PROCESS_GROUPS/\$_hwf" 2>/dev/null
  unset _hwg _hws _hwf
  # No job control: a command stays in this shell's group, the one registered. Claude Code's shell
  # snapshot writes \`set -o monitor\` whatever its state (it matches "on" in \`set -o\`'s output) and is
  # sourced after this file, so bash also turns it off again before each command (a DEBUG trap);
  # without that, each of its commands ran in a group of its own that outlived a crash.
  case \$- in *m*) set +m 2>/dev/null ;; esac
  if [ -n "\${BASH_VERSION:-}" ]; then trap 'case \$- in *m*) set +m ;; esac' DEBUG; fi
fi
`;

/** The session home's shell startup files that source the registry script. */
const STARTUP_FILES = ['.bashrc', '.bash_profile', '.profile', '.zshenv'];

export interface ProcessHostOptions {
  /** Where session directories go. Default `defaultRoot()`. */
  root?: string;
  /** How long a stale child gets to disappear after its SIGKILL before the new one starts. Default 2000 ms. */
  killWaitMs?: number;
}

export class ProcessHost implements ProcessHostLike {
  readonly root: string;
  private readonly killWaitMs: number;
  /** The child each session's current drive in this host runs. */
  private readonly active = new Map<string, HostedProcess>();
  /** Sessions a `spawn` is starting a child for (claimed before its first await). */
  private readonly starting = new Set<string>();

  constructor(options: ProcessHostOptions = {}) {
    // `turbopackIgnore` (here and below): a session's files are made at run time, not the app's to
    // ship. Turbopack's trace of a route that loads this module otherwise takes the whole project,
    // or from node_modules every file of durable-harness.
    this.root = resolve(/* turbopackIgnore: true */ options.root ?? defaultRoot());
    this.killWaitMs = options.killWaitMs ?? 2000;
  }

  /** The session's directory, created if it is missing. */
  async dir(runId: string): Promise<SessionDir> {
    if (!/^[A-Za-z0-9_-]+$/.test(runId)) throw new Error(`harness-world-process: not a run id: ${runId}`);
    const path = join(this.root, runId);
    const tmp = join(path, 'tmp');
    const dir = { path, home: join(path, 'home'), tmp, state: join(path, '.harness'), groups: join(tmp, '.harness-groups') };
    await Promise.all([dir.home, dir.tmp, dir.state, dir.groups].map((d) => mkdir(d, { recursive: true })));
    // The default root is `.sessions` in the app's directory: keep the sessions' files (homes, CLI
    // transcripts, working directories) out of the app's git.
    if (!this.ignored && basename(this.root) === '.sessions') {
      this.ignored = true;
      await writeFile(join(this.root, '.gitignore'), '*\n', { flag: 'wx' }).catch(() => {});
    }
    return dir;
  }
  private ignored = false;

  /** Write the registry script and the startup files that source it into the session's home (idempotent). */
  private async registry(dir: SessionDir): Promise<string> {
    const script = join(dir.state, 'groups.sh');
    if ((await readFile(script, 'utf8').catch(() => '')) !== GROUP_REGISTRY_SCRIPT) await writeFile(script, GROUP_REGISTRY_SCRIPT);
    const line = `[ -r ${shellQuote(script)} ] && . ${shellQuote(script)}`;
    await Promise.all(
      STARTUP_FILES.map(async (name) => {
        const file = join(/* turbopackIgnore: true */ dir.home, name);
        const text = await readFile(/* turbopackIgnore: true */ file, 'utf8').catch(() => undefined);
        if (text === undefined) await writeFile(file, `${line}\n`);
        else if (!text.includes(line)) await appendFile(file, `\n${line}\n`);
      })
    );
    return script;
  }

  /**
   * Kill every process group the session's shells registered (see
   * `GROUP_REGISTRY_SCRIPT`) that is still alive and still ours, and clear
   * the registry. A harness calls it when its drive ends: a process a tool
   * started does not outlive the drive. Returns the groups it killed.
   */
  async killGroups(runId: string): Promise<number[]> {
    const dir = await this.dir(runId);
    return killRegistered(dir.groups, runId);
  }

  /** Remove the session's directory (after `killStale`). The next `dir()` starts empty. */
  async reset(runId: string): Promise<void> {
    await this.killStale(runId);
    await rm(join(this.root, runId), { recursive: true, force: true });
  }

  /** The pidfile's record, if a child was started here and has not exited cleanly. */
  async pidRecord(runId: string): Promise<PidRecord | undefined> {
    const dir = await this.dir(runId);
    try {
      return JSON.parse(await readFile(join(dir.state, PIDFILE), 'utf8')) as PidRecord;
    } catch {
      return undefined;
    }
  }

  /**
   * Kill-before-resume: SIGKILL the process group of a child a previous drive
   * started here and never saw exit, and every group it adopted, then wait
   * (briefly) for them to go. A pid that now belongs to another process is
   * left alone (see `identity`). Returns the groups it killed.
   *
   * A child that a drive of this same host still runs is not stale: two
   * deliveries of one session can overlap (the queue delivers a wake while
   * the last turn's drive winds down), and the kernel settles which one
   * owns the session at its next write. Killing the other's child first
   * would lose its turn, so this throws `Yield('contended')` instead (the
   * delivery is retried in a moment).
   */
  async killStale(runId: string): Promise<number[]> {
    if (this.busy(runId)) throw new Yield('contended', 2);
    return this.killStaleUnclaimed(runId);
  }

  /** Whether a drive of this host runs (or is starting) the session's child. */
  busy(runId: string): boolean {
    return this.starting.has(runId) || !!this.active.get(runId)?.alive();
  }

  private async killStaleUnclaimed(runId: string): Promise<number[]> {
    const dir = await this.dir(runId);
    const file = join(dir.state, PIDFILE);
    const record = await this.pidRecord(runId);
    if (!record) return killRegistered(dir.groups, runId);
    const killed: number[] = [];
    // A leader that is gone leaves its group id reserved while any member
    // lives (no new pid can take it), so a live group is still ours then. A
    // live leader is checked first: its pid may have been reused.
    const own = isAlive(record.pid) ? identity(record) : 'gone';
    if (own !== 'mismatch' && groupAlive(record.pid)) {
      killGroup(record.pid, 'SIGKILL');
      killed.push(record.pid);
    }
    for (const g of record.groups) {
      if (g !== record.pid && groupAlive(g)) {
        killGroup(g, 'SIGKILL');
        killed.push(g);
      }
    }
    // The groups its tools' shells registered: a command that outlived the dead drive.
    killed.push(...killRegistered(dir.groups, runId));
    const deadline = Date.now() + this.killWaitMs;
    while (killed.some(groupAlive) && Date.now() < deadline) await new Promise((r) => setTimeout(r, 25));
    await rm(file, { force: true });
    return killed;
  }

  /**
   * Start the session's child: claim the session in this host (or throw
   * `Yield('contended')`, see `killStale`), kill a stale child, run
   * `prepare`, spawn.
   */
  async spawn(runId: string, options: SpawnOptions): Promise<HostedProcess> {
    if (this.busy(runId)) throw new Yield('contended', 2);
    this.starting.add(runId);
    try {
      await this.killStaleUnclaimed(runId);
      const dir = await this.dir(runId);
      await options.prepare?.(dir);
      return await this.start(runId, dir, options);
    } finally {
      this.starting.delete(runId);
    }
  }

  private async start(runId: string, dir: SessionDir, options: SpawnOptions): Promise<HostedProcess> {
    const token = randomUUID();
    const registry = await this.registry(dir);
    const env: Record<string, string> = {
      PATH: process.env.PATH ?? '/usr/local/bin:/usr/bin:/bin',
      HOME: dir.home,
      TMPDIR: dir.tmp,
      SHELL: defaultShell(),
      BASH_ENV: registry,
      ENV: registry,
    };
    for (const [k, v] of Object.entries(options.env ?? {})) if (v !== undefined) env[k] = v;
    env.HARNESS_PROCESS_SESSION = runId;
    env.HARNESS_PROCESS_TOKEN = token;
    env.HARNESS_PROCESS_GROUPS = dir.groups;
    const args = options.args ?? [];
    const cwd = options.cwd ?? dir.path;
    const child: ChildProcess = spawn(options.command, args, {
      cwd,
      env: env as NodeJS.ProcessEnv,
      // Its own process group (setsid): a kill reaches everything it starts
      // that stays in the group, and nothing reaches it from ours.
      detached: true,
      stdio: ['pipe', 'pipe', options.stderr ?? 'pipe'],
    });
    await new Promise<void>((ok, fail) => {
      child.once('spawn', ok);
      child.once('error', (err) => fail(spawnFailure(err, options.command, cwd)));
    });
    const pid = child.pid!;
    const record: PidRecord = { pid, token, argv: [options.command, ...args], startedAt: Date.now(), groups: [] };
    const file = join(dir.state, PIDFILE);
    await writeFile(file, JSON.stringify(record));

    let stderr = '';
    child.stderr?.on('data', (chunk: Buffer) => {
      stderr = (stderr + chunk.toString('utf8')).slice(-STDERR_KEEP);
    });
    child.stdin?.on('error', () => {}); // EPIPE after the child died: `send` reports it.
    const exited = new Promise<Exit>((done) => {
      child.once('exit', (code, signal) => {
        // A child that exited is no longer stale: the next drive need not kill it.
        void readFile(file, 'utf8')
          .then(async (t) => {
            if ((JSON.parse(t) as PidRecord).token === token) await rm(file, { force: true });
          })
          .catch(() => {})
          .finally(() => done({ code, signal }));
      });
    });
    const groups = new Set<number>([pid]);
    const kill = (signal: NodeJS.Signals = 'SIGKILL') => {
      for (const g of groups) killGroup(g, signal);
      // And what its tools' shells started in groups of their own.
      if (signal === 'SIGKILL') killRegistered(dir.groups, runId);
    };
    const watchdog = options.watchdog ? watchParent(pid, { registry: dir.groups }) : undefined;
    void exited.then(() => {
      // The child is gone: its tools' groups go too (a clean exit included), then the watchdog.
      killRegistered(dir.groups, runId);
      watchdog?.kill();
    });
    const onAbort = () => kill();
    if (options.signal?.aborted) kill();
    else options.signal?.addEventListener('abort', onAbort, { once: true });
    void exited.then(() => options.signal?.removeEventListener('abort', onAbort));
    let rl: Interface | undefined;
    const hosted: HostedProcess = {
      pid,
      child,
      exited,
      alive: () => child.exitCode === null && child.signalCode === null && isAlive(pid),
      kill,
      async adopt(pgid) {
        groups.add(pgid);
        record.groups = [...groups].filter((g) => g !== pid);
        await writeFile(file, JSON.stringify(record));
      },
      send(line) {
        const stdin = child.stdin;
        if (!stdin || stdin.destroyed || stdin.writableEnded) return false;
        stdin.write(`${typeof line === 'string' ? line : JSON.stringify(line)}\n`);
        return true;
      },
      end: () => child.stdin?.end(),
      lines() {
        if (!child.stdout) throw new Error('harness-world-process: the child has no stdout pipe');
        rl ??= createInterface({ input: child.stdout, crlfDelay: Number.POSITIVE_INFINITY });
        return rl;
      },
      stderrTail: () => stderr,
    };
    this.active.set(runId, hosted);
    void exited.then(() => {
      if (this.active.get(runId) === hosted) this.active.delete(runId);
    });
    return hosted;
  }
}

/** Whether a process with this pid exists (a zombie counts): harness-world's, which the kernel's anchor verdicts use too. */
export { isAlive } from 'harness-world/anchor';

/** Whether a process group with this id has any member. */
export function groupAlive(pgid: number): boolean {
  try {
    process.kill(-pgid, 0);
    return true;
  } catch (err) {
    return (err as NodeJS.ErrnoException).code === 'EPERM';
  }
}

function killGroup(pgid: number, signal: NodeJS.Signals): void {
  try {
    process.kill(-pgid, signal);
  } catch {}
}

/**
 * Whether the pidfile's pid is still the child it recorded, before anything
 * kills it: on Linux, the token in `/proc/<pid>/environ`; elsewhere, the
 * command line and start time `ps` reports (macOS does not show another
 * process's environment). `unknown` when neither can be read; the caller then
 * kills only if the pid still leads a process group, as the child did.
 */
export function identity(record: PidRecord): 'match' | 'mismatch' | 'unknown' {
  if (!isAlive(record.pid)) return 'mismatch';
  if (existsSync('/proc/self/environ')) {
    try {
      const env = readFileSync(`/proc/${record.pid}/environ`, 'utf8').split('\0');
      return env.includes(`HARNESS_PROCESS_TOKEN=${record.token}`) ? 'match' : 'mismatch';
    } catch {
      return 'unknown';
    }
  }
  let out: string;
  try {
    out = execFileSync('ps', ['-o', 'etime=,command=', '-p', String(record.pid)], { encoding: 'utf8', timeout: 2000 }).trim();
  } catch {
    return 'unknown';
  }
  if (!out) return 'mismatch';
  const [etime = '', ...rest] = out.split(/\s+/);
  const command = rest.join(' ');
  const startedAt = Date.now() - elapsedSeconds(etime) * 1000;
  // `ps` reports whole seconds.
  if (Math.abs(startedAt - record.startedAt) > 3000) return 'mismatch';
  // `ps` escapes what it cannot print (a newline is `\012`): compare the plain arguments.
  let at = 0;
  for (const arg of record.argv.filter((a) => /^[\x20-\x7e]*$/.test(a))) {
    const i = command.indexOf(arg, at);
    if (i < 0) return 'mismatch';
    at = i + arg.length;
  }
  return 'match';
}

/** `ps` elapsed time, `[[dd-]hh:]mm:ss`, in seconds. */
function elapsedSeconds(etime: string): number {
  const [days, clock] = etime.includes('-') ? etime.split('-') : ['0', etime];
  const parts = clock!.split(':').map(Number);
  while (parts.length < 3) parts.unshift(0);
  const [h, m, s] = parts as [number, number, number];
  return Number(days) * 86400 + h * 3600 + m * 60 + s;
}

/** The shell a child's tools get by default: bash where there is one (its startup files register its group), else sh. */
export function defaultShell(): string {
  for (const sh of ['/bin/bash', '/usr/bin/bash']) if (existsSync(/* turbopackIgnore: true */ sh)) return sh;
  return '/bin/sh';
}

const shellQuote = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`;

/** This process's own process group (never killed through the registry). */
export const ownGroup: number = (() => {
  try {
    if (existsSync('/proc/self/stat')) {
      const rest = readFileSync('/proc/self/stat', 'utf8').split(') ').at(-1)!.split(' ');
      return Number(rest[2]);
    }
    return Number(execFileSync('ps', ['-o', 'pgid=', '-p', String(process.pid)], { encoding: 'utf8', timeout: 2000 }).trim());
  } catch {
    return -1;
  }
})();

/**
 * Kill the live groups in a registry (one file per group id, holding the
 * registration time in seconds) that are still the session's, and remove
 * every entry. A group whose leader is gone while members live is ours (its
 * id stays reserved while it has members); a live leader is checked first
 * (`/proc/<pid>/environ` names the session on Linux; elsewhere its start
 * time is the registration's).
 */
export function killRegistered(registry: string, runId: string): number[] {
  let names: string[];
  try {
    names = readdirSync(registry);
  } catch {
    return [];
  }
  const killed: number[] = [];
  for (const name of names) {
    const file = join(registry, name);
    // `<pgid>`, or `pid-<pid>` from a shell that could not read its group: resolved here, while it lives.
    const byPid = /^pid-(\d+)$/.exec(name);
    const pgid = byPid ? (isAlive(Number(byPid[1])) ? (groupOf(Number(byPid[1])) ?? -1) : -1) : /^\d+$/.test(name) ? Number(name) : -1;
    if (pgid <= 1 || pgid === ownGroup || pgid === process.pid) {
      rmSync(file, { force: true });
      continue;
    }
    if (groupAlive(pgid) && registeredIsOurs(byPid ? Number(byPid[1]) : pgid, runId, file)) {
      killGroup(pgid, 'SIGKILL');
      killed.push(pgid);
    }
    rmSync(file, { force: true });
  }
  return killed;
}

/** The process group of a live pid (`/proc` on Linux, else `ps`), or undefined. */
export function groupOf(pid: number): number | undefined {
  try {
    if (existsSync('/proc/self/stat')) {
      const rest = readFileSync(`/proc/${pid}/stat`, 'utf8').split(') ').at(-1)!.split(' ');
      return Number(rest[2]) || undefined;
    }
    return Number(execFileSync('ps', ['-o', 'pgid=', '-p', String(pid)], { encoding: 'utf8', timeout: 2000 }).trim()) || undefined;
  } catch {
    return undefined;
  }
}

/** Whether a registered process (a group leader, or the shell that registered by pid) is still the session's. */
function registeredIsOurs(pgid: number, runId: string, file: string): boolean {
  if (!isAlive(pgid)) return true;
  if (existsSync('/proc/self/environ')) {
    try {
      // During exec, Linux can expose the new process before its environment
      // is readable. A shell commonly execs its last command just after
      // registering. Retry only an empty read; a populated foreign environment
      // still rejects the group, and persistent emptiness proves no ownership.
      const pause = new Int32Array(new SharedArrayBuffer(4));
      for (let attempt = 0; attempt < 5; attempt++) {
        const env = readFileSync(`/proc/${pgid}/environ`, 'utf8');
        if (env) return env.split('\0').includes(`HARNESS_PROCESS_SESSION=${runId}`);
        if (attempt < 4) Atomics.wait(pause, 0, 0, 1);
      }
      return false;
    } catch {}
  }
  let at: number;
  try {
    at = Number(readFileSync(file, 'utf8').trim()) * 1000;
  } catch {
    return false;
  }
  try {
    const etime = execFileSync('ps', ['-o', 'etime=', '-p', String(pgid)], { encoding: 'utf8', timeout: 2000 }).trim();
    if (!etime) return false;
    return Math.abs(Date.now() - elapsedSeconds(etime) * 1000 - at) <= 5000;
  } catch {
    // No way to tell: only a recent registration.
    return Date.now() - at < 3_600_000;
  }
}

export interface WatchOptions {
  /** The process to watch. Default this one. */
  parent?: number;
  /** A group registry (`SessionDir.groups`) whose groups die with it too. */
  registry?: string;
}

/**
 * The watchdog: a `sh` loop in a process (and group) of its own that, within
 * about a second of `parent` dying, kills the process group `pgid` and every
 * group in `registry`. It leaves by itself once there is nothing left to
 * kill (the group is gone and no registered group is alive), and holds no
 * pipe of the child's and no environment. POSIX `sh`; if it cannot start,
 * the next drive on this machine still kills them (the pidfile, the registry).
 */
export function watchParent(pgid: number, options: WatchOptions = {}): ChildProcess {
  const env: Record<string, string> = { PATH: process.env.PATH ?? '/usr/bin:/bin' };
  const watcher = spawn('/bin/sh', ['-c', WATCH, 'harness-world-process-watch', String(options.parent ?? process.pid), String(pgid), options.registry ?? '', String(ownGroup)], {
    detached: true,
    stdio: 'ignore',
    env: env as NodeJS.ProcessEnv,
  });
  watcher.on('error', () => {});
  watcher.unref();
  return watcher;
}

// No `--` before a group id: dash (Debian's and Ubuntu's `/bin/sh`) reads it as a
// pid ("Illegal number"). `sleep 1 || exit`: with no `sleep` on PATH it leaves
// (the pidfile and the registry still cover the groups) rather than spin.
const WATCH = [
  'P=$1; C=$2; R=$3; S=$4',
  // The group of a pid (a `pid-<pid>` entry): /proc on Linux, else ps.
  'pg() { if [ -r "/proc/$1/stat" ]; then read -r s < "/proc/$1/stat"; s=${s##*") "}; s=${s#* }; s=${s#* }; echo "${s%% *}"; else ps -o pgid= -p "$1" 2>/dev/null | tr -d " "; fi; }',
  'groups() { [ -n "$R" ] && [ -d "$R" ] || return 0; for f in "$R"/*; do g=${f##*/}; case "$g" in pid-*) g=$(pg "${g#pid-}");; esac; case "$g" in ""|*[!0-9]*) continue;; esac; [ "$g" = "$S" ] && continue; [ "$g" -gt 1 ] && echo "$g"; done; }',
  'live() { kill -0 "-$C" 2>/dev/null && return 0; for g in $(groups); do kill -0 "-$g" 2>/dev/null && return 0; done; return 1; }',
  'while kill -0 "$P" 2>/dev/null; do live || exit 0; sleep 1 || exit 0; done',
  'kill -9 "-$C" 2>/dev/null; for g in $(groups); do kill -9 "-$g" 2>/dev/null; done',
].join('\n');