@a2f0/agent-tool 0.1.29 → 0.1.31

package/src/processes/commands.ts

@@ -0,0 +1,283 @@
+// `proc start|list|stop` and `teardown`: long-running processes started through agent-tool are
+// recorded so they can be found and stopped, and teardown reports everything a piece of work
+// may have left running in the repository before an agent says it is done.
+import { spawn } from "node:child_process";
+import { closeSync, realpathSync } from "node:fs";
+import { constants } from "node:os";
+import path from "node:path";
+import { createLog } from "../commands/logFile";
+import { plainText } from "../commands/output";
+import { assert, git, output } from "../workflows/core";
+import { claimedBy, ledgerDirectory, membersOf, newId, observe, readRecords, removeRecord, saveRecord, type ProcessRecord, type ProcessState } from "./ledger";
+import { ancestors, carrying, listeningPorts, processTable, startOf, workingDirectories, type ProcessRow } from "./table";
+
+const STOP_GRACE_MS = 5000;
+const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
+// A bound on another wait that does not itself keep the process alive once that wait is over.
+const bound = (ms: number) => new Promise<undefined>(resolve => { (setTimeout(resolve, ms) as unknown as NodeJS.Timeout).unref(); });
+
+function within(root: string, candidate: string): boolean {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+
+function signal(pid: number, value: NodeJS.Signals, group: boolean): void {
+  try { process.kill(group ? -pid : pid, value); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error; }
+}
+
+interface Described { id: string; label: string | null; state: ProcessState; keep: boolean; pid: number; command: string[]; cwd: string; log: string; startedAt: string; members: { pid: number; command: string }[]; ports: string[] }
+
+// Read-only: `proc list` and report-only `teardown` never write records.
+function describe(record: ProcessRecord, table: Map<number, ProcessRow>, ports: Map<number, string[]>, others: ProcessRecord[]): Described {
+  const { state, members } = membersOf(record, table, others);
+  return {
+    id: record.id, label: record.label, state, keep: record.keep, pid: record.pid, command: record.command, cwd: record.cwd, log: record.log, startedAt: record.startedAt,
+    members: members.map(row => ({ pid: row.pid, command: row.command })),
+    ports: [...new Set(members.flatMap(row => ports.get(row.pid) ?? []))].sort(),
+  };
+}
+
+const alive = (state: ProcessState) => state === "running" || state === "orphaned";
+
+/**
+ * Stops one record's processes: SIGTERM to its group and to members outside it, then SIGKILL
+ * after the grace period. Every member seen is remembered with its start time, so a descendant
+ * that left the group and outlived its parent is still signalled, and only while it is the same
+ * process; the group is signalled only while its leader, or a member of it, is ours.
+ */
+async function stopRecord(directory: string, record: ProcessRecord, grace = STOP_GRACE_MS): Promise<{ id: string; stopped: boolean; remaining: number[] }> {
+  const known = new Map<number, string>();
+  const look = () => {
+    const table = processTable(), others = readRecords(directory).records, { state, members } = membersOf(record, table, others);
+    observe(directory, record, state, members);
+    for (const member of members) known.set(member.pid, member.started);
+    const claimed = claimedBy(record, table, others);
+    const live = [...known].filter(([pid, started]) => table.get(pid)?.started === started && !claimed.has(pid)).map(([pid]) => table.get(pid)!);
+    // The group id is ours while our leader runs, or while a member we know still holds it;
+    // otherwise it may name someone else's group, and members are signalled one by one.
+    return { group: state === "running" || live.some(member => member.pgid === record.pid), live };
+  };
+  const send = (value: NodeJS.Signals) => {
+    const { group, live } = look();
+    if (group) signal(record.pid, value, true);
+    for (const member of live) if (!group || member.pgid !== record.pid) signal(member.pid, value, false);
+  };
+  const running = () => { const { group, live } = look(); return group || live.length > 0; };
+  send("SIGTERM");
+  const deadline = performance.now() + grace;
+  while (performance.now() < deadline && running()) await sleep(50);
+  send("SIGKILL");
+  for (let tries = 0; tries < 20 && running(); tries += 1) await sleep(50);
+  const { group, live } = look();
+  const stopped = !group && live.length === 0;
+  // observe() may have rewritten the record while stopping; remove it only after the last look.
+  if (stopped) removeRecord(directory, record.id);
+  return { id: record.id, stopped, remaining: stopped ? [] : live.map(row => row.pid) };
+}
+
+/**
+ * The members of a launcher's group that are provably its own once the launcher has exited and
+ * the group id could name another group: those carrying the record's id, or started while the
+ * launcher ran, to the second `ps` reports with a second's margin either side.
+ */
+export function adoptable(candidates: ProcessRow[], tagged: Set<number>, spawnedAt: number, exitedAt: number): ProcessRow[] {
+  const from = Math.floor(spawnedAt / 1000) * 1000 - 1000, until = exitedAt + 1000;
+  return candidates.filter(row => {
+    const at = Date.parse(`${row.started} UTC`);
+    return tagged.has(row.pid) || (at >= from && at <= until);
+  });
+}
+
+async function start(args: string[]): Promise<number> {
+  let label: string | null = null, keep = false;
+  while (args.length && args[0] !== "--") {
+    const flag = args.shift();
+    if (flag === "--label") {
+      const value = args.shift();
+      assert(value && value.length <= 120, "--label requires 1 to 120 characters.");
+      label = plainText(value);
+    } else if (flag === "--keep") keep = true;
+    else throw new Error(`Unknown proc start argument '${flag}'.`);
+  }
+  assert(args.shift() === "--" && args[0], "Usage: agent-tool proc start [--label text] [--keep] -- <command> [args...]");
+  const directory = ledgerDirectory();
+  // Without a working ps nothing started could be identified, recorded or stopped later.
+  try { processTable(); }
+  catch (error) { throw new Error(`Cannot inspect processes with ps, so nothing was started: ${(error as Error).message}`); }
+  const id = newId(), { log, fd } = createLog("agent-tool-proc-");
+  let record: ProcessRecord | undefined;
+  try {
+    // Its own process group, so stopping it reaches everything it starts that stays in the group.
+    const spawnedAt = Date.now();
+    let exitedAt: number | undefined;
+    const child = spawn(args[0]!, args.slice(1), { cwd: process.cwd(), detached: true, stdio: ["ignore", fd, fd], env: { ...process.env, AGENT_TOOL_PROCESS: id } });
+    const exited = new Promise<{ code: number | null; signal?: NodeJS.Signals | null; error?: string }>(resolve => {
+      child.once("error", error => resolve({ code: (error as NodeJS.ErrnoException).code === "ENOENT" ? 127 : 126, error: error.message }));
+      child.once("exit", (code, signal) => { exitedAt = Date.now(); resolve({ code, signal }); });
+    });
+    if (child.pid) {
+      const started = startOf(child.pid);
+      if (started) {
+        record = { schemaVersion: 1, id, label, pid: child.pid, started, command: [...args], cwd: process.cwd(), log, startedAt: new Date().toISOString(), keep };
+        try { saveRecord(directory, record); }
+        catch (error) {
+          // An unrecorded process could never be found and stopped by teardown.
+          signal(child.pid, "SIGKILL", true);
+          await Promise.race([exited, bound(2000)]);
+          throw new Error(`Could not record the process, so it was stopped: ${(error as Error).message}`);
+        }
+      } else if (!(await Promise.race([exited, bound(300)]))) {
+        // Running, but its identity could not be read, so it could never be stopped safely later.
+        signal(child.pid, "SIGKILL", true);
+        await Promise.race([exited, bound(2000)]);
+        throw new Error("Could not read the started process's identity with ps; stopped it. Nothing was recorded.");
+      }
+    }
+    // A command that fails at once is reported here rather than found later.
+    const early = await Promise.race([exited, bound(300)]);
+    child.unref();
+    if (child.pid) {
+      const table = processTable();
+      if (table.get(child.pid)?.started === record?.started && record) {
+        const { state, members } = membersOf(record, table, readRecords(directory).records);
+        observe(directory, record, state, members);
+      } else if (!table.has(child.pid)) {
+        // The launcher exited, perhaps before its identity could be read, and its group id may
+        // already name another group. A member is ours when it carries this record's id, or
+        // started while the launcher ran (to the second `ps` reports, with a second's margin).
+        const candidates = [...table.values()].filter(row => row.pgid === child.pid);
+        const survivors = adoptable(candidates, carrying(candidates.map(row => row.pid), "AGENT_TOOL_PROCESS", id), spawnedAt, exitedAt ?? Date.now());
+        if (survivors.length) {
+          record ??= { schemaVersion: 1, id, label, pid: child.pid, started: "", command: [...args], cwd: process.cwd(), log, startedAt: new Date().toISOString(), keep };
+          record.members = survivors.map(row => ({ pid: row.pid, started: row.started }));
+          try { saveRecord(directory, record); }
+          catch (error) {
+            for (const row of survivors) signal(row.pid, "SIGKILL", false);
+            throw new Error(`Could not record the processes the command left running, so they were stopped: ${(error as Error).message}`);
+          }
+        }
+      }
+    }
+    const receipt = { id, ...(label ? { label } : {}), pid: child.pid ?? null, keep, log, ...(early ? { exited: early.code, ...(early.signal ? { signal: early.signal } : {}), ...(early.error ? { error: early.error } : {}) } : {}) };
+    if (early && record && !alive(membersOf(record, processTable()).state)) removeRecord(directory, id);
+    output(receipt);
+    if (early?.signal) return 128 + (constants.signals[early.signal] ?? 0);
+    return early && early.code !== 0 ? (early.code ?? 1) : 0;
+  } finally { closeSync(fd); }
+}
+
+function parseStopTargets(args: string[]): { all: boolean; ids: string[]; grace: number } {
+  let all = false, grace = STOP_GRACE_MS;
+  const ids: string[] = [];
+  while (args.length) {
+    const value = args.shift()!;
+    if (value === "--all") all = true;
+    else if (value === "--grace-ms") {
+      grace = Number(args.shift());
+      assert(Number.isInteger(grace) && grace >= 0 && grace <= 60_000, "--grace-ms requires 0 to 60000.");
+    } else { assert(/^[a-f0-9]{8}$/.test(value), `Unknown process id '${value}'.`); ids.push(value); }
+  }
+  assert(all !== ids.length > 0, "Usage: agent-tool proc stop <id...>|--all [--grace-ms N]");
+  return { all, ids, grace };
+}
+
+export async function procCommand(args: string[]): Promise<number> {
+  const action = args.shift();
+  if (action === "start") return start(args);
+  const directory = ledgerDirectory();
+  if (action === "list") {
+    assert(args.length === 0, "Usage: agent-tool proc list");
+    const { records, skipped } = readRecords(directory), table = processTable(), { ports } = listeningPorts();
+    output({ processes: records.map(record => describe(record, table, ports, records)), skipped });
+    return 0;
+  }
+  assert(action === "stop", "Usage: agent-tool proc <start|list|stop>");
+  const { all, ids, grace } = parseStopTargets(args);
+  const { records, skipped } = readRecords(directory);
+  for (const id of ids) assert(records.some(record => record.id === id), `No recorded process '${id}'.`);
+  const results = [];
+  for (const record of records.filter(record => all || ids.includes(record.id))) results.push(await stopRecord(directory, record, grace));
+  output({ stopped: results, skipped });
+  // An unreadable record may name processes --all could not stop.
+  return results.every(result => result.stopped) && (!all || skipped.length === 0) ? 0 : 1;
+}
+
+export interface TeardownReport {
+  ok: boolean;
+  applied: boolean;
+  root: string;
+  /** Recorded processes still running: they fail teardown unless started with --keep. */
+  leftover: Described[];
+  kept: Described[];
+  /** Records whose processes have ended; --apply removes them. */
+  finished: { id: string; label: string | null; state: ProcessState }[];
+  stopped: { id: string; stopped: boolean; remaining: number[] }[];
+  /** Processes started some other way whose working directory is in the repository. Listeners fail teardown. */
+  untracked: { pid: number; command: string; cwd: string; ports: string[] }[];
+  worktrees: { path: string; branch: string | null }[];
+  unavailable: string[];
+  skipped: { file: string; reason: string }[];
+}
+
+function survey(root: string, directory: string): Omit<TeardownReport, "ok" | "applied" | "stopped"> {
+  const table = processTable(), { records, skipped } = readRecords(directory);
+  const listening = listeningPorts(), cwd = workingDirectories(table.keys());
+  const described = records.map(record => describe(record, table, listening.ports, records));
+  const owned = new Set(described.flatMap(item => alive(item.state) ? item.members.map(member => member.pid) : []));
+  const excluded = ancestors(table);
+  const untracked = [...cwd.cwd].flatMap(([pid, directoryOf]) => {
+    const row = table.get(pid);
+    if (!row || excluded.has(pid) || owned.has(pid) || !within(root, directoryOf)) return [];
+    // Processes this command started to look (ps, lsof) are its children.
+    if (row.ppid === process.pid) return [];
+    const ports = listening.ports.get(pid) ?? [];
+    // A pipeline's other commands (`agent-tool teardown | jq`) share its shell and group; one that
+    // listens is still reported, since a server backgrounded from the same shell looks alike.
+    const self = table.get(process.pid);
+    if (self && row.pgid === self.pgid && row.ppid === self.ppid && ports.length === 0) return [];
+    return [{ pid, command: row.command, cwd: directoryOf, ports }];
+  }).sort((a, b) => a.pid - b.pid);
+  const worktrees: { path: string; branch: string | null }[] = [];
+  let current: { path: string; branch: string | null } | undefined;
+  for (const line of git(["worktree", "list", "--porcelain"]).split("\n")) {
+    if (line.startsWith("worktree ")) worktrees.push(current = { path: line.slice(9), branch: null });
+    else if (line.startsWith("branch ") && current) current.branch = line.slice(7).replace(/^refs\/heads\//, "");
+  }
+  return {
+    root,
+    leftover: described.filter(item => alive(item.state) && !item.keep),
+    kept: described.filter(item => alive(item.state) && item.keep),
+    finished: described.filter(item => !alive(item.state)).map(item => ({ id: item.id, label: item.label, state: item.state })),
+    untracked,
+    // The first entry is the main worktree; the rest were added and may need removing.
+    worktrees: worktrees.slice(1),
+    unavailable: [...(listening.available ? [] : ["listening ports (lsof)"]), ...(cwd.available ? [] : ["working directories (lsof)"])],
+    skipped,
+  };
+}
+
+export async function teardownCommand(args: string[]): Promise<number> {
+  let apply = false;
+  for (const value of args) {
+    assert(value === "--apply" && !apply, "Usage: agent-tool teardown [--apply]");
+    apply = true;
+  }
+  const root = realpathSync(git(["rev-parse", "--show-toplevel"])), directory = ledgerDirectory();
+  const stopped: TeardownReport["stopped"] = [];
+  if (apply) {
+    const { records } = readRecords(directory), table = processTable();
+    for (const record of records) {
+      const { state, members } = membersOf(record, table, records);
+      observe(directory, record, state, members);
+      if (!alive(state)) removeRecord(directory, record.id);
+      else if (!record.keep) stopped.push(await stopRecord(directory, record));
+    }
+  }
+  const found = survey(root, directory);
+  // A clean report needs every inspection: without lsof a listening server would go unseen.
+  // Unreadable records may name running processes, so they fail teardown too.
+  const ok = found.leftover.length === 0 && found.untracked.every(item => item.ports.length === 0) && found.unavailable.length === 0 && found.skipped.length === 0;
+  output({ ok, applied: apply, ...found, stopped } satisfies TeardownReport);
+  return ok ? 0 : 1;
+}

package/src/processes/ledger.ts

@@ -0,0 +1,123 @@
+// Long-running processes agent-tool started for a repository, recorded one file each under the
+// Git common directory, so every worktree and clone-local session sees the same list and it
+// survives branch switches. A record names the process group agent-tool created; whether that
+// group still runs is decided from the live process table, never from the record alone.
+import { randomUUID } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { git } from "../workflows/core";
+import { carrying, type ProcessRow } from "./table";
+
+export interface ProcessRecord {
+  schemaVersion: 1;
+  id: string;
+  label: string | null;
+  /** The group leader agent-tool spawned; its pid is the group id. */
+  pid: number;
+  /** The leader's start time as `ps` prints it, which tells a reused pid apart. */
+  started: string;
+  command: string[];
+  cwd: string;
+  log: string;
+  startedAt: string;
+  /** Started to outlive the work, such as a dev server the user asked to keep: teardown reports it without failing. */
+  keep: boolean;
+  /** Members seen while the leader ran, by start time, so they are still known once it has gone. */
+  members?: { pid: number; started: string }[];
+}
+
+export type ProcessState = "running" | "orphaned" | "exited" | "replaced";
+
+export function ledgerDirectory(cwd = process.cwd()): string {
+  return path.join(git(["rev-parse", "--path-format=absolute", "--git-common-dir"], cwd), "agent-tool", "processes");
+}
+
+export function newId(): string { return randomUUID().slice(0, 8); }
+
+export function saveRecord(directory: string, record: ProcessRecord): void {
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const file = path.join(directory, `${record.id}.json`), temporary = `${file}.${randomUUID()}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+  renameSync(temporary, file);
+}
+
+export function removeRecord(directory: string, id: string): void { rmSync(path.join(directory, `${id}.json`), { force: true }); }
+
+const ID = /^[a-f0-9]{8}$/;
+// Generous enough for any argv the OS accepts plus the member list, which keeps only live members.
+const MAX_RECORD_BYTES = 4 * 1024 * 1024;
+const MAX_MEMBERS = 1000;
+
+function valid(value: unknown): value is ProcessRecord {
+  const record = value as ProcessRecord;
+  return !!record && record.schemaVersion === 1 && typeof record.id === "string" && ID.test(record.id) && Number.isInteger(record.pid) && record.pid > 1
+    && typeof record.started === "string" && Array.isArray(record.command) && record.command.every(arg => typeof arg === "string")
+    && typeof record.cwd === "string" && typeof record.log === "string" && typeof record.startedAt === "string"
+    && (record.label === null || typeof record.label === "string") && typeof record.keep === "boolean"
+    && (record.members === undefined || (Array.isArray(record.members) && record.members.every(member => Number.isInteger(member?.pid) && typeof member.started === "string")));
+}
+
+/** Every record, and the files that could not be read as one. */
+export function readRecords(directory: string): { records: ProcessRecord[]; skipped: { file: string; reason: string }[] } {
+  const records: ProcessRecord[] = [], skipped: { file: string; reason: string }[] = [];
+  for (const file of existsSync(directory) ? readdirSync(directory).filter(name => name.endsWith(".json")).sort() : []) {
+    try {
+      const full = path.join(directory, file), stat = lstatSync(full);
+      if (!stat.isFile() || stat.size > MAX_RECORD_BYTES) throw new Error("Not a process record file.");
+      const record = JSON.parse(readFileSync(full, "utf8")) as unknown;
+      if (!valid(record) || `${record.id}.json` !== file) throw new Error("Invalid process record.");
+      records.push(record);
+    } catch (error) { skipped.push({ file, reason: (error as Error).message }); }
+  }
+  return { records, skipped };
+}
+
+/**
+ * The processes that belong to a record. While its leader runs, that is its group and the live
+ * descendants of the group. Once the leader has gone its pid, and so the group id, can be reused,
+ * so a leaderless member counts only when it was seen while the leader ran (same pid and start
+ * time) or carries the record's AGENT_TOOL_PROCESS id; descendants of counted members count too.
+ */
+/** The live leaders of records other than `record`, which own their own process trees. */
+export function claimedBy(record: ProcessRecord, table: Map<number, ProcessRow>, others: ProcessRecord[]): Set<number> {
+  return new Set(others.filter(other => other.id !== record.id && table.get(other.pid)?.started === other.started).map(other => other.pid));
+}
+
+export function membersOf(record: ProcessRecord, table: Map<number, ProcessRow>, others: ProcessRecord[] = []): { state: ProcessState; members: ProcessRow[] } {
+  // Another record's live leader, and everything under it, belongs to that record, even when it
+  // was started from inside this one (a nested `proc start --keep`).
+  const claimed = claimedBy(record, table, others);
+  const leader = table.get(record.pid);
+  const ours = !!leader && leader.started === record.started;
+  const seen = new Set((record.members ?? []).map(member => `${member.pid} ${member.started}`));
+  const known = (row: ProcessRow) => seen.has(`${row.pid} ${row.started}`);
+  let group: ProcessRow[] = [];
+  // Another process now holding the leader's pid makes the group id unreliable too: only
+  // remembered members still count.
+  if (ours) group = [...table.values()].filter(row => row.pgid === record.pid);
+  else if (!leader) {
+    const candidates = [...table.values()].filter(row => row.pgid === record.pid);
+    const tagged = carrying(candidates.filter(row => !known(row)).map(row => row.pid), "AGENT_TOOL_PROCESS", record.id);
+    group = candidates.filter(row => known(row) || tagged.has(row.pid));
+  }
+  // Members seen before, wherever they are now: a descendant that left the group keeps its
+  // identity after its parent exits and it is no longer anyone's descendant.
+  const members = new Map([...group, ...[...table.values()].filter(known)].filter(row => !claimed.has(row.pid)).map(row => [row.pid, row]));
+  // Children that left the group (setsid, a new process group) are still reached through their parents.
+  for (let grew = true; grew;) {
+    grew = false;
+    for (const row of table.values()) if (!members.has(row.pid) && !claimed.has(row.pid) && members.has(row.ppid)) { members.set(row.pid, row); grew = true; }
+  }
+  const list = [...members.values()].sort((a, b) => a.pid - b.pid);
+  return { state: ours ? "running" : list.length ? "orphaned" : leader ? "replaced" : "exited", members: list };
+}
+
+/** Remembers the live members seen while the leader runs, for when it has gone; dead ones are dropped. */
+export function observe(directory: string, record: ProcessRecord, state: ProcessState, members: ProcessRow[]): void {
+  if (state !== "running") return;
+  const next = members.slice(0, MAX_MEMBERS).map(row => ({ pid: row.pid, started: row.started }));
+  const key = (list: { pid: number; started: string }[]) => list.map(member => `${member.pid} ${member.started}`).sort().join("\n");
+  if (key(next) === key(record.members ?? [])) return;
+  record.members = next;
+  try { saveRecord(directory, record); } catch { /* Best effort: an unrecorded member is only found while the leader runs. */ }
+}

package/src/processes/table.ts

@@ -0,0 +1,111 @@
+// The machine's processes as agent-tool sees them: identity (pid, parent, group and start time),
+// working directory, and listening TCP ports. Read through `ps`, `lsof` and, on Linux, `/proc`,
+// so it needs nothing beyond the operating system.
+import { execFileSync } from "node:child_process";
+import { readFileSync, readlinkSync } from "node:fs";
+
+export interface ProcessRow { pid: number; ppid: number; pgid: number; started: string; command: string }
+
+// One locale and time zone, so start times read the same in every shell that compares them.
+const C_LOCALE = { ...process.env, LC_ALL: "C", LANG: "C", TZ: "UTC" };
+// `stat` is one token; `lstart` prints a fixed-width date of five fields, such as `Fri Oct 30 21:43:01 2026`.
+const ROW = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+([A-Z][a-z]{2}\s+[A-Z][a-z]{2}\s+\d{1,2}\s+\d{2}:\d{2}:\d{2}\s+\d{4})\s(.*)$/;
+
+/**
+ * Rows of `ps -o pid=,ppid=,pgid=,stat=,lstart=,command=`. Zombies are left out: they have
+ * exited, cannot be signalled, and may never be reaped where PID 1 does not reap orphans.
+ */
+export function parseRows(text: string): ProcessRow[] {
+  return text.split("\n").flatMap(line => {
+    const match = ROW.exec(line);
+    if (!match || match[4]!.startsWith("Z")) return [];
+    return [{ pid: Number(match[1]), ppid: Number(match[2]), pgid: Number(match[3]), started: match[5]!.replace(/\s+/g, " "), command: match[6]!.trim() }];
+  });
+}
+
+/** Every live process, by pid. */
+export function processTable(): Map<number, ProcessRow> {
+  const text = execFileSync("ps", ["-A", "-o", "pid=,ppid=,pgid=,stat=,lstart=,command="], { encoding: "utf8", env: C_LOCALE, maxBuffer: 64 * 1024 * 1024 });
+  return new Map(parseRows(text).map(row => [row.pid, row]));
+}
+
+/** When a running process started, as `ps` prints it, or undefined once it has gone. */
+export function startOf(pid: number): string | undefined {
+  try {
+    const text = execFileSync("ps", ["-o", "stat=,lstart=", "-p", String(pid)], { encoding: "utf8", env: C_LOCALE, stdio: ["ignore", "pipe", "ignore"] }).trim();
+    const match = /^(\S+)\s+(.+)$/.exec(text);
+    return match && !match[1]!.startsWith("Z") ? match[2]!.replace(/\s+/g, " ") : undefined;
+  } catch { return undefined; }
+}
+
+/** lsof's output, or undefined when it is missing or failed rather than finding nothing. */
+function lsof(args: string[]): string | undefined {
+  try {
+    return execFileSync("lsof", args, { encoding: "utf8", env: C_LOCALE, stdio: ["ignore", "pipe", "pipe"], maxBuffer: 64 * 1024 * 1024 });
+  } catch (error) {
+    // lsof exits 1 when nothing matches, perhaps with warnings. With another diagnostic, any other status, a
+    // missing binary or a signal, the inspection failed and may have missed what it looked for.
+    const result = error as { status?: number | null; stdout?: string; stderr?: string };
+    const failures = (result.stderr ?? "").split("\n").filter(line => line.trim() && !line.startsWith("lsof: WARNING"));
+    return result.status === 1 && failures.length === 0 ? result.stdout ?? "" : undefined;
+  }
+}
+
+/** Parses `lsof -F pn` output into the names each pid holds. */
+export function parseFields(text: string): Map<number, string[]> {
+  const found = new Map<number, string[]>();
+  let pid = 0;
+  for (const line of text.split("\n")) {
+    if (line.startsWith("p")) pid = Number(line.slice(1));
+    else if (line.startsWith("n") && pid) found.set(pid, [...found.get(pid) ?? [], line.slice(1)]);
+  }
+  return found;
+}
+
+/** Each process's working directory; `available` is false when neither lsof nor /proc can say. */
+export function workingDirectories(pids: Iterable<number>): { available: boolean; cwd: Map<number, string> } {
+  const text = lsof(["-a", "-d", "cwd", "-F", "pn"]);
+  if (text !== undefined) return { available: true, cwd: new Map([...parseFields(text)].map(([pid, names]) => [pid, names[0]!])) };
+  if (process.platform !== "linux") return { available: false, cwd: new Map() };
+  const cwd = new Map<number, string>();
+  for (const pid of pids) { try { cwd.set(pid, readlinkSync(`/proc/${pid}/cwd`)); } catch { /* Gone or not ours. */ } }
+  return { available: true, cwd };
+}
+
+/** The TCP addresses each process listens on; `available` is false without lsof. */
+export function listeningPorts(): { available: boolean; ports: Map<number, string[]> } {
+  const text = lsof(["-nP", "-iTCP", "-sTCP:LISTEN", "-F", "pn"]);
+  if (text === undefined) return { available: false, ports: new Map() };
+  return { available: true, ports: new Map([...parseFields(text)].map(([pid, names]) => [pid, [...new Set(names)]])) };
+}
+
+/** This process and every process above it, which teardown never reports or stops. */
+export function ancestors(table: Map<number, ProcessRow>, pid = process.pid): Set<number> {
+  const found = new Set<number>();
+  for (let current: number | undefined = pid; current && !found.has(current); current = table.get(current)?.ppid) found.add(current);
+  return found;
+}
+
+/**
+ * The processes among `pids` whose environment carries `NAME=value`, as `proc start` sets for
+ * everything it launches. macOS hides the environment of protected system binaries, which then
+ * never match.
+ */
+export function carrying(pids: number[], name: string, value: string): Set<number> {
+  const found = new Set<number>(), entry = `${name}=${value}`;
+  if (pids.length === 0) return found;
+  if (process.platform === "linux") {
+    for (const pid of pids) {
+      try { if (readFileSync(`/proc/${pid}/environ`, "latin1").split("\0").includes(entry)) found.add(pid); } catch { /* Gone or not ours. */ }
+    }
+    return found;
+  }
+  try {
+    const text = execFileSync("ps", ["-E", "-ww", "-o", "pid=,command=", "-p", pids.join(",")], { encoding: "utf8", env: C_LOCALE, stdio: ["ignore", "pipe", "ignore"], maxBuffer: 64 * 1024 * 1024 });
+    for (const line of text.split("\n")) {
+      const match = /^\s*(\d+)\s(.*)$/.exec(line);
+      if (match && ` ${match[2]} `.includes(` ${entry} `)) found.add(Number(match[1]));
+    }
+  } catch { /* None readable. */ }
+  return found;
+}

package/src/review/executable.ts

@@ -1,32 +1,8 @@
-import { accessSync, constants, realpathSync, statSync } from "node:fs";
-import path from "node:path";
+import { outsideExecutable } from "../system/executable";
 import type { ReviewerEnv } from "./runReview";
 
-function within(root: string, candidate: string): boolean {
-  const relative = path.relative(root, candidate);
-  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
-}
-
-/**
- * Find a PATH executable whose entry and target both lie outside the
- * repository. `candidate` keeps the PATH entry, which multi-call binaries such
- * as `bunx` need; `resolved` is its real file.
- */
-export function outsideExecutable(name: string, env: ReviewerEnv, repositoryRoot = process.cwd()): { candidate: string; resolved: string } | undefined {
-  const root = realpathSync(repositoryRoot);
-  for (const directory of (env.PATH ?? "").split(path.delimiter)) {
-    if (!path.isAbsolute(directory)) continue;
-    const candidate = path.join(directory, name);
-    try {
-      accessSync(candidate, constants.X_OK);
-      const resolved = realpathSync(candidate);
-      if (!statSync(resolved).isFile() || within(root, candidate) || within(root, resolved)) continue;
-      return { candidate, resolved };
-    } catch { /* Continue searching outside the repository. */ }
-  }
-  // Never fall back to a predictable path or PATH resolution after rejection.
-  return undefined;
-}
+// The generic PATH lookup lives in the primitives layer; re-exported for existing callers.
+export { outsideExecutable };
 
 /** Never launch a reviewer binary supplied by the repository being reviewed. */
 export function reviewExecutable(name: string, env: ReviewerEnv, repositoryRoot = process.cwd()): string | undefined {