@north-light/crouter 0.3.154

package/dist/core/canvas/pid.js

@@ -0,0 +1,636 @@
+// src/core/canvas/pid.ts
+//
+// The ONE shared signal-0 liveness probe. It lives at the canvas/ layer — the
+// LOWEST shared layer — so canvas/, runtime/, AND daemon/ can all import it
+// "down" without a reverse-layer violation (runtime/ sits above canvas/, daemon/
+// above runtime/). It is a pure process-existence utility, NOT data-model access,
+// so it is exempt from the "only canvas.ts touches the db" rule. Collapses the
+// four near-identical copies that used to live in canvas.ts, revive.ts,
+// placement.ts, and crtrd.ts into one (Phase 3 review reuse MINOR-1).
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { readKernelBootId } from './boot-id.js';
+/** Is `pid` a ZOMBIE (exited, awaiting reap by its parent)? `kill(pid, 0)`
+ *  reports a zombie as a perfectly normal alive process — its PID is still
+ *  occupied in the process table — so callers relying on that signal-0 probe
+ *  alone (see `isPidAlive`) misread a dead broker as alive forever whenever
+ *  its spawning process never reaps it (crouton-labs zombie-broker bug: the
+ *  front door's foreground attach session parks its OWN event loop for the
+ *  whole session — see `bootRoot` in runtime/boot-root.ts — so it can't process
+ *  the SIGCHLD that would otherwise reap its detached broker child in real
+ *  time). `ps -o stat=` reports a leading `Z` for a zombie on BOTH BSD ps
+ *  (macOS) and procps-ng (Linux), so one portable probe covers both platforms
+ *  without a Linux-only `/proc` special case. Best-effort: any probe failure
+ *  (spawn error, no matching row, non-zero exit) reads as NOT a zombie —
+ *  fail-open, matching this module's other guards; a probe failure must never
+ *  be misread as proof of death (a live pid IS alive; only a positive `Z`
+ *  read says otherwise). */
+function isZombie(pid) {
+    try {
+        const r = spawnSync('ps', ['-o', 'stat=', '-p', String(pid)], { encoding: 'utf8', timeout: 2000 });
+        if (r.status !== 0 || typeof r.stdout !== 'string')
+            return false;
+        return r.stdout.trim().charAt(0) === 'Z';
+    }
+    catch {
+        return false;
+    }
+}
+/** True if a process with `pid` is currently alive (signal-0 probe) AND not a
+ *  zombie. `kill(pid, 0)` throws ESRCH when the process is gone; EPERM means
+ *  it exists but isn't ours — still alive (a foreign process is never OUR
+ *  zombie, so the `isZombie` check is skipped for that branch — see below). A
+ *  null/undefined pid (legacy / never-booted) reads dead.
+ *
+ *  The zombie check matters because EVERY broker this module supervises is
+ *  spawned `detached: true` by crtr itself (`headlessBrokerHost.launch`) — a
+ *  dead broker whose spawning process hasn't reaped it yet is a zombie, and
+ *  `kill(pid, 0)` alone reports it as alive, wedging the daemon's revive guard
+ *  (`isPidAlive(pi_pid)`, `revive.ts`) forever: the daemon never revives an
+ *  already-live-looking row, so a refreshed/crashed node whose broker zombied
+ *  out under a long-lived spawning process (see `isZombie`'s doc) never comes
+ *  back on its own. */
+export function isPidAlive(pid) {
+    if (pid == null)
+        return false;
+    try {
+        process.kill(pid, 0);
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+    return !isZombie(pid);
+}
+/** Matches the kernel `boot_id` UUID shape (`/proc/sys/kernel/random/boot_id`),
+ *  used to tell a NEW-format identity base (a per-boot UUID) apart from a
+ *  LEGACY one (a `ps lstart` wall-clock timestamp). A boot_id is a lowercase
+ *  hex UUID; an `lstart` string is a human-readable date — the two never
+ *  collide, so this cleanly classifies which comparison rule an identity's
+ *  base obeys (see `identitiesMatch`). */
+const BOOT_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Split a `composeIdentity` fingerprint (`<base>` or `<base>#<ticks>`, where
+ *  `base` is a per-boot `boot_id` UUID on Linux-with-procfs or the portable
+ *  `ps lstart` timestamp otherwise) into its coarse base and fine `ticks`
+ *  (Linux-only jiffies) parts. `#` never appears in a `boot_id` or an `lstart`
+ *  timestamp, so the first `#` unambiguously separates them. Only a NON-EMPTY,
+ *  purely-numeric suffix counts as ticks (the shape `procStartTicks` and
+ *  `composeIdentity` guarantee); a malformed or empty suffix (`A#`, `A#bad`,
+ *  `A#1#2`) is treated as ABSENT ticks, so the base compare then applies — a
+ *  garbage suffix must never be trusted as a fine discriminator (review
+ *  Minor). */
+function splitIdentity(identity) {
+    const i = identity.indexOf('#');
+    if (i === -1)
+        return { base: identity, ticks: undefined };
+    const suffix = identity.slice(i + 1);
+    return { base: identity.slice(0, i), ticks: /^\d+$/.test(suffix) ? suffix : undefined };
+}
+/** THE single precision-aware identity compare, used EVERYWHERE two
+ *  `composeIdentity` fingerprints are compared (this module's own
+ *  `recordedPidLiveness`, `captureTeardownSnapshot`'s reuse check, and
+ *  `killProcessTreePids`'s reuse check) — centralized so no call site can
+ *  drift from this rule (review Major #1, Round 2 of the pid-reuse-liveness
+ *  fix).
+ *
+ *  Two hazards this closes, both in the false-DEAD direction (the dangerous
+ *  one — a false DEAD lets `reviveNode`'s double-launch guard relaunch a
+ *  SECOND broker onto a still-live session):
+ *
+ *  1. `composeIdentity` appends the `#<ticks>` Linux discriminator only when
+ *     `/proc/<pid>/stat` happens to be readable at capture time — so the SAME
+ *     live process can be recorded plain `lstart` on one capture and
+ *     `lstart#ticks` on another (a transient `/proc` read failure, or
+ *     capturing on a platform/container without procfs). A naive `===` reads
+ *     that as a reuse (different string) and reports `dead` for a broker that
+ *     never died.
+ *  2. `lstart` is NOT stable for a live process on every host. It is derived
+ *     from `/proc/stat` btime (wall-clock boot epoch) + starttime jiffies, so
+ *     a clock correction / suspend-resume shifts btime and re-anchors the
+ *     SAME live process's `lstart` by seconds between two captures. Observed
+ *     on Blaxel unikraft guests: pid+ticks identical across probes, `lstart`
+ *     drifting +81s — a base-first compare then reads the live home-node
+ *     broker as reused/dead every cycle, driving an uncapped revive loop.
+ *
+ *  A third hazard the base itself once carried: `ticks` (jiffies-since-boot)
+ *  RESET on every boot and can repeat across boots, so ticks-alone is only
+ *  safe WITHIN one boot. `composeIdentity` therefore boot-SCOPES the base on
+ *  Linux-with-procfs — the base IS the kernel `boot_id` UUID — so a
+ *  new-format identity is `<bootId>#<ticks>` and equality means same boot AND
+ *  same process. This closes the cross-boot false match at the root, without
+ *  plumbing boot reconciliation ahead of every caller.
+ *
+ *  Rule: split both on `#`.
+ *   - BOTH sides carry `#ticks` AND both bases are `boot_id` UUIDs
+ *     (new-format vs new-format): match iff base AND ticks are equal. A
+ *     different boot_id with equal ticks is NOT a match (the cross-boot
+ *     collision).
+ *   - BOTH sides carry `#ticks` but a base is NOT a boot_id UUID on EITHER
+ *     side — a LEGACY `lstart#ticks` row recorded before this repo boot-scoped
+ *     the base, or a Linux host that has procfs ticks but no readable boot_id:
+ *     ticks DECIDE it alone (the prior landed semantics). This is a NARROW
+ *     format-migration path so an in-place upgrade never false-kills a live
+ *     broker whose row still holds `lstart#ticks`; it is NOT a general
+ *     fallback — new-format vs new-format always demands base+ticks above.
+ *   - EITHER side lacks a valid `#ticks` suffix (macOS / no procfs / transient
+ *     `/proc` miss / malformed suffix): fall back to the coarse base —
+ *     matching iff the bases agree (fail-open to same-process, matching this
+ *     module's universal discipline: only a POSITIVE mismatch counts as reuse,
+ *     never an absence of evidence). */
+export function identitiesMatch(a, b) {
+    const ia = splitIdentity(a);
+    const ib = splitIdentity(b);
+    if (ia.ticks !== undefined && ib.ticks !== undefined) {
+        if (BOOT_ID_RE.test(ia.base) && BOOT_ID_RE.test(ib.base)) {
+            return ia.base === ib.base && ia.ticks === ib.ticks;
+        }
+        return ia.ticks === ib.ticks; // legacy lstart#ticks (either side) → ticks-alone migration
+    }
+    return ia.base === ib.base;
+}
+export function recordedPidLiveness(pid, expectedIdentity, snapshot) {
+    const debug = Boolean(process.env.CRTR_DEBUG_PID_LIVENESS);
+    if (pid == null)
+        return 'dead';
+    if (snapshot === null) {
+        if (debug)
+            logPidLivenessDecision(pid, false, expectedIdentity, 'probe-null', 'ps snapshot failed → indeterminate', 'indeterminate');
+        return 'indeterminate';
+    }
+    const snapshotProcess = snapshot?.processes.get(pid);
+    const alive = snapshot === undefined ? isPidAlive(pid) : snapshotProcess !== undefined && !snapshotProcess.zombie;
+    if (!alive) {
+        if (debug)
+            logPidLivenessDecision(pid, alive, expectedIdentity, snapshot === undefined ? 'no-probe' : 'no-entry', 'process absent/zombie → dead', 'dead');
+        return 'dead';
+    }
+    if (expectedIdentity == null) {
+        if (debug)
+            logPidLivenessDecision(pid, alive, expectedIdentity, 'no-probe', 'no baseline → trust process presence', 'alive');
+        return 'alive';
+    }
+    let actual;
+    if (snapshot === undefined) {
+        const current = capturePidIdentities([pid]);
+        if (current == null) {
+            if (debug)
+                logPidLivenessDecision(pid, alive, expectedIdentity, 'probe-null', 'ps probe failed → indeterminate', 'indeterminate');
+            return 'indeterminate';
+        }
+        actual = current.get(pid);
+        if (actual === undefined) {
+            if (debug)
+                logPidLivenessDecision(pid, alive, expectedIdentity, 'no-entry', 'no identity row for pid (race) → dead', 'dead');
+            return 'dead';
+        }
+    }
+    else {
+        actual = snapshotProcess.identity;
+    }
+    const matches = identitiesMatch(actual, expectedIdentity);
+    if (debug)
+        logPidLivenessDecision(pid, alive, expectedIdentity, 'value', matches ? 'identity matches expected → alive' : 'identity differs from expected → REUSED → dead', matches ? 'alive' : 'dead', actual);
+    return matches ? 'alive' : 'dead';
+}
+/** Diagnostic-only decision trace for `recordedPidLiveness`, gated entirely
+ *  behind `CRTR_DEBUG_PID_LIVENESS` — callers must check the env var
+ *  themselves before calling this so the (tiny) formatting cost is paid ONLY
+ *  when the env var is set; this function does no env check of its own.
+ *  Written to trace subtle PID-reuse decisions at the remaining signal and
+ *  teardown authorization sites: the goal is for a single stderr line per call
+ *  to make both an identity match and a reused/indeterminate identity fully
+ *  self-explaining, without changing any return value. `capturePidIdentities`
+ *  outcome is reported as one of three DISTINCT cases — `probe-null` (the
+ *  `ps` probe itself failed), `no-entry` (probe succeeded but the map has no
+ *  row for this pid), or `value` (probe succeeded and found an identity,
+ *  printed verbatim) — plus `no-probe` for the two branches that return
+ *  before `capturePidIdentities` is ever called. Kept as permanent
+ *  observability for this primitive, not a throwaway debug print: pid-reuse
+ *  liveness is subtle enough that the next person chasing a wedge here should
+ *  find this already in place. */
+function logPidLivenessDecision(pid, isPidAliveResult, expectedIdentity, probeOutcome, branch, returned, actualIdentity) {
+    const parts = [
+        `pid=${String(pid)}`,
+        `isPidAlive=${isPidAliveResult}`,
+        `expectedIdentity=${expectedIdentity === undefined ? 'undefined' : expectedIdentity === null ? 'null' : JSON.stringify(expectedIdentity)}`,
+        `capturePidIdentities=${probeOutcome}${probeOutcome === 'value' ? `(${JSON.stringify(actualIdentity)})` : ''}`,
+        `branch=${JSON.stringify(branch)}`,
+        `returned=${returned}`,
+    ];
+    process.stderr.write(`[recordedPidLiveness] ${parts.join(' ')}\n`);
+}
+/** SIGTERM a process GROUP by pid (the negative-pid convention) — best-effort,
+ *  swallowing ESRCH (already gone). Used by cron cancellation, timeout, and
+ *  stale-lease recovery. Lives beside isPidAlive: canvas/ is
+ *  the lowest shared layer every process-liveness/-teardown primitive sits at.
+ *  Guards `pid` before signaling (review nit, crouter#98): never hit pid 0
+ *  (which means "my own group") or a negative/non-integer value. */
+export function killProcessGroup(pid, signal = 'SIGTERM') {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return;
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        /* already gone */
+    }
+}
+/** Linux-only higher-resolution discriminator layered onto `lstart` (crouter#98
+ *  review finding, minor): `ps lstart` is only second-granular, so a PID reused
+ *  within the same wall-clock second compares equal and slips past the reuse
+ *  guard. `/proc/<pid>/stat`'s `starttime` field is the kernel's own jiffies-
+ *  since-boot counter for that process — effectively unique per pid even for
+ *  same-second reuse. `comm` (field 2) is parenthesized and may itself contain
+ *  spaces/parens, so this splits on the LAST `)` rather than counting fields
+ *  from the front. Returns `null` (never throws) on any read/parse failure —
+ *  no `/proc` (macOS, containers without procfs), a raced-away pid, or a
+ *  malformed line — so this is purely additive precision, never a hard
+ *  dependency: `composeIdentity` falls back to plain `lstart` in every such
+ *  case, exactly matching this module's pre-existing cross-platform coarse
+ *  behavior. */
+function procStartTicks(pid) {
+    try {
+        const raw = readFileSync(`/proc/${pid}/stat`, 'utf8');
+        const closeParen = raw.lastIndexOf(')');
+        if (closeParen === -1)
+            return null;
+        // Fields after `(comm)`, 0-indexed from `state` (proc(5) field 3): state(0)
+        // ppid(1) pgrp(2) session(3) tty_nr(4) tpgid(5) flags(6) minflt(7)
+        // cminflt(8) majflt(9) cmajflt(10) utime(11) stime(12) cutime(13)
+        // cstime(14) priority(15) nice(16) num_threads(17) itrealvalue(18)
+        // starttime(19) — proc(5) field 22.
+        const rest = raw.slice(closeParen + 2).trim().split(/\s+/);
+        const starttime = rest[19];
+        return starttime !== undefined && /^\d+$/.test(starttime) ? starttime : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** How long a FAILED (`null`) boot_id read is remembered as negative before the
+ *  next call is allowed to re-read. Bounds the cost on a genuinely no-boot_id
+ *  host (macOS / no procfs) to one throwing `/proc` read per window rather than
+ *  one per identity composition — identity is composed per supervised row per
+ *  daemon tick and per process in a full ps-table capture, so an uncapped
+ *  retry-on-null is a synchronous read storm there. Kept short so a transient
+ *  miss on a real boot_id host still recovers promptly. */
+const BOOT_ID_NEGATIVE_TTL_MS = 60_000;
+/** The kernel `boot_id` (`/proc/sys/kernel/random/boot_id`) is stable for the
+ *  whole lifetime of this process — it only changes on a kernel boot, which
+ *  necessarily kills this process — so once a real value is read it is cached
+ *  for good, rather than re-read for every row of a whole-process-table `ps`
+ *  scan. Only SUCCESSFUL reads are cached forever: a `null` read is negative
+ *  for `BOOT_ID_NEGATIVE_TTL_MS`, after which the next call retries — so a
+ *  transient `/proc` miss on a boot_id-capable host still recovers (never
+ *  permanently downgraded to legacy `lstart#ticks`), while a genuinely
+ *  no-boot_id host is not hammered with a synchronous throwing read on every
+ *  identity composition. `now` is injectable for tests. */
+export function makeBootIdCache(read, now = Date.now, negativeTtlMs = BOOT_ID_NEGATIVE_TTL_MS) {
+    let cached = null;
+    let retryAfter = 0;
+    return () => {
+        if (cached !== null)
+            return cached;
+        const t = now();
+        if (t < retryAfter)
+            return null; // within the negative-cache window — don't re-read
+        const v = read();
+        if (v !== null)
+            return (cached = v);
+        retryAfter = t + negativeTtlMs;
+        return null;
+    };
+}
+const bootIdBase = makeBootIdCache(readKernelBootId);
+/** Is `identity` a LEGACY (pre-boot-scoped) baseline — a `<lstart>#<ticks>` row
+ *  whose base is NOT a boot_id UUID but which DOES carry ticks? These are the
+ *  rows the one-time startup migration re-records once this platform can
+ *  compose boot-scoped identities (see `migrateLegacyPidIdentities`). */
+export function isLegacyTicksIdentity(identity) {
+    const { base, ticks } = splitIdentity(identity);
+    return ticks !== undefined && !BOOT_ID_RE.test(base);
+}
+/** Is `identity` a NEW-format boot-scoped baseline — `<bootId>#<ticks>` with a
+ *  real boot_id UUID base AND ticks? The startup migration only re-records a
+ *  legacy row when the pid's CURRENT identity comes out in this shape (i.e. the
+ *  platform now composes new-format), never otherwise. */
+export function isBootScopedIdentity(identity) {
+    const { base, ticks } = splitIdentity(identity);
+    return ticks !== undefined && BOOT_ID_RE.test(base);
+}
+/** Compose the stable, BOOT-SCOPED process-identity fingerprint used
+ *  everywhere in this module. ALWAYS used to build an identity string, never a
+ *  raw field directly, so every identity captured anywhere (launch-time
+ *  `recordPid`, the teardown snapshot, and the escalation-window re-check) is
+ *  comparable apples-to-apples.
+ *
+ *  Platform capability, not layered fallbacks — the base is the finest STABLE
+ *  per-boot anchor available:
+ *   - Linux-with-procfs (the production guest shape): `<bootId>#<ticks>` — the
+ *     per-boot `boot_id` UUID plus the per-process jiffies-since-boot. Ticks
+ *     reset per boot and can repeat, so scoping the base to the boot is what
+ *     makes an equal-ticks compare safe ACROSS boots (see `identitiesMatch`).
+ *   - Linux-with-procfs but no readable `boot_id` (if that combination
+ *     exists): `<lstart>#<ticks>` — the prior landed behavior.
+ *   - No procfs ticks (macOS / containers without procfs): `<lstart>` alone —
+ *     unchanged coarse behavior. The base is only ever a `boot_id` when a
+ *     `ticks` discriminator is ALSO present; a bare `boot_id` (shared by every
+ *     process on the boot) would be a useless per-process identity. */
+export function composeIdentity(pid, lstart, deps = {}) {
+    // `deps` is a TEST-ONLY seam: it lets a unit test drive the composition with
+    // an injected ticks/boot_id pair (so `<bootId>#<ticks>` composition is
+    // provable off-Linux, where real `/proc` reads return null), without adding
+    // any runtime branch — production callers pass no `deps` and read the real
+    // `/proc` values exactly as before.
+    const ticks = deps.ticks !== undefined ? deps.ticks : procStartTicks(pid);
+    if (ticks === null)
+        return lstart;
+    const bootId = deps.bootId !== undefined ? deps.bootId : bootIdBase();
+    return `${bootId ?? lstart}#${ticks}`;
+}
+export function captureLivenessSnapshot() {
+    let stdout;
+    try {
+        const r = spawnSync('ps', ['-Ao', 'pid=,ppid=,stat=,lstart=,command='], {
+            encoding: 'utf8',
+            timeout: 2000,
+            maxBuffer: 8 * 1024 * 1024,
+        });
+        if (r.status !== 0 || typeof r.stdout !== 'string')
+            return null;
+        stdout = r.stdout;
+    }
+    catch {
+        return null;
+    }
+    const processes = new Map();
+    const childrenOf = new Map();
+    for (const line of stdout.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '')
+            continue;
+        // lstart is five whitespace-delimited fields on BSD ps and procps-ng.
+        const m = /^(\d+)\s+(\d+)\s+(\S+)\s+(\S+(?:\s+\S+){4})\s+(.+)$/.exec(trimmed);
+        if (m === null)
+            continue;
+        const pid = Number(m[1]);
+        const ppid = Number(m[2]);
+        const stat = m[3];
+        const lstart = m[4];
+        const command = m[5].trim();
+        if (!Number.isInteger(pid) || pid <= 0 || !Number.isInteger(ppid) || ppid < 0 || command === '')
+            continue;
+        processes.set(pid, { zombie: stat.startsWith('Z'), identity: composeIdentity(pid, lstart), command });
+        const siblings = childrenOf.get(ppid);
+        if (siblings === undefined)
+            childrenOf.set(ppid, [pid]);
+        else
+            siblings.push(pid);
+    }
+    return { processes, childrenOf };
+}
+/** BFS over an already-parsed ppid → children-pid[] map, starting from
+ *  `rootPid`'s children. Pure (no `ps` spawn) — split out of `descendantPids`
+ *  so `captureTeardownSnapshot` can walk the SAME process snapshot it
+ *  already paid for, rather than re-spawning `ps`. */
+function descendantPidsFrom(rootPid, childrenOf) {
+    const out = [];
+    const seen = new Set([rootPid]);
+    const queue = [...(childrenOf.get(rootPid) ?? [])];
+    while (queue.length > 0) {
+        const pid = queue.shift();
+        if (seen.has(pid))
+            continue; // guard against a malformed/cyclic ps snapshot
+        seen.add(pid);
+        out.push(pid);
+        const kids = childrenOf.get(pid);
+        if (kids !== undefined)
+            queue.push(...kids);
+    }
+    return out;
+}
+/** Every transitive descendant of `rootPid`, discovered by walking `ps`'s
+ *  pid/ppid table (BFS) — NOT process-GROUP membership. This is the fix for
+ *  crouton-labs/crouter#98: the pi SDK's bash tool spawns its shell child with
+ *  `detached: true` (verified in `@earendil-works/pi-agent-core`'s
+ *  `harness/env/nodejs.js`), which calls `setsid()` and puts that child in a
+ *  brand-new process GROUP of its own — so `kill(-rootPid)` never reaches it.
+ *  `setsid()` changes only SID/PGID, NEVER ppid, so the child (and its own
+ *  descendants) is still discoverable by walking parentage from `rootPid`, as
+ *  long as `rootPid`'s OS process is still alive when we walk (a fully-dead
+ *  parent is reparented away by the kernel immediately on exit, severing this
+ *  link — the wedged-but-alive broker this fix targets never hits that). Best-
+ *  effort: returns `[]` (never throws) on any `ps` failure, exactly like
+ *  `killProcessGroup`'s ESRCH-swallowing. */
+export function descendantPids(rootPid) {
+    if (!Number.isInteger(rootPid) || rootPid <= 0)
+        return [];
+    const table = captureLivenessSnapshot();
+    if (table === null)
+        return [];
+    return descendantPidsFrom(rootPid, table.childrenOf);
+}
+/** Capture a portable process-identity fingerprint — `ps`'s `lstart` column,
+ *  the process's full wall-clock start time — for each of `pids`, in ONE
+ *  batched `ps -p <list>` call. `lstart` is a standard format keyword on BOTH
+ *  BSD ps (macOS) and procps-ng (Linux), so this needs no `/proc` parsing or
+ *  other Linux-only machinery. Used to guard against PID REUSE during the
+ *  multi-second teardown escalation ladder (crouter#98 review finding 3): a
+ *  captured pid can exit and the OS can recycle it for an unrelated process
+ *  before the SIGKILL rung fires, and a bare `kill(pid, 0)` / `kill(pid, sig)`
+ *  cannot tell the difference.
+ *
+ *  Returns `null` — NOT an empty map — when the `ps` PROBE ITSELF failed (it
+ *  could not be spawned, or was killed by the timeout): a probe failure means
+ *  we have NO information, which is a fundamentally different outcome from a
+ *  probe that SUCCEEDED and simply found no row for a given pid (that pid is
+ *  genuinely gone). Collapsing these two into the same empty map was the
+ *  final-review bug (crouter#98 signal-safety finding): `killProcessTreePids`
+ *  cannot tell "pid confirmed gone" from "we don't know" without this
+ *  distinction, and misreading a failed probe as positive proof of
+ *  absence/reuse either signals a reused stranger or — worse — silently skips
+ *  reaping a real live orphan. A successful call may still return a map with
+ *  no entry for some/all of `pids` (those pids have no current row — genuinely
+ *  gone); that is the valid empty-or-partial case and is NOT a failure.
+ *
+ *  EXIT STATUS IS NOT THE FAILURE SIGNAL. `ps` exits 1 — on BOTH BSD ps and
+ *  procps-ng — when it matched no process at all, which is precisely the
+ *  "probe succeeded, that pid is gone" case, and exits 1 with PARTIAL stdout
+ *  when only some of a batch's pids still exist. Reading a non-zero exit as a
+ *  probe failure therefore turned every confirmed-dead pid into
+ *  `'indeterminate'` (`recordedPidLiveness`), so a just-killed broker read as
+ *  "can't confirm" — never as dead. Callers that fail open on indeterminate
+ *  (`ensureAttach`'s revive decision, the daemon's exit policy) then treat a
+ *  dead broker as live forever. Discriminate on whether the PROCESS RAN
+ *  (`r.error`/`r.signal`) and whether it complained (`stderr`), never on what
+ *  it exited with: a real argument/usage failure writes a diagnostic to stderr
+ *  (`ps: process id too large`), while "matched nothing" is silent. */
+export function capturePidIdentities(pids) {
+    const valid = pids.filter((pid) => Number.isInteger(pid) && pid > 0);
+    const out = new Map();
+    if (valid.length === 0)
+        return out;
+    try {
+        const r = spawnSync('ps', ['-o', 'pid=,lstart=', '-p', valid.join(',')], { encoding: 'utf8', timeout: 2000 });
+        if (r.error != null || r.signal != null || typeof r.stdout !== 'string')
+            return null;
+        if (typeof r.stderr === 'string' && r.stderr.trim() !== '')
+            return null;
+        for (const line of r.stdout.split('\n')) {
+            const trimmed = line.trim();
+            if (trimmed === '')
+                continue;
+            // Only the FIRST token (pid) is split on whitespace — `lstart` is a
+            // human-readable timestamp that itself CONTAINS spaces (e.g. "Wed Jul
+            // 3 10:23:45 2026"), so everything after the first space is kept
+            // verbatim as the identity string. Exact string equality later is
+            // sufficient; nothing here needs to parse it as a real date.
+            const spaceIdx = trimmed.indexOf(' ');
+            if (spaceIdx === -1)
+                continue;
+            const pid = Number(trimmed.slice(0, spaceIdx));
+            const startedAt = trimmed.slice(spaceIdx + 1).trim();
+            if (!Number.isInteger(pid) || pid <= 0 || startedAt === '')
+                continue;
+            out.set(pid, composeIdentity(pid, startedAt));
+        }
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read one pid's current full command line for a destructive caller that
+ *  must freshly re-confirm process ownership immediately before signaling.
+ *  Failure and absence both return null, so uncertainty never authorizes a
+ *  signal. */
+export function capturePidCommand(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return null;
+    try {
+        const r = spawnSync('ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf8', timeout: 2000 });
+        if (r.status !== 0 || typeof r.stdout !== 'string')
+            return null;
+        const command = r.stdout.trim();
+        return command === '' ? null : command;
+    }
+    catch {
+        return null;
+    }
+}
+export function captureTeardownSnapshot(rootPid, expectedIdentity) {
+    if (!Number.isInteger(rootPid) || rootPid <= 0)
+        return { tree: [], identities: null, reused: false };
+    const table = captureLivenessSnapshot();
+    if (table === null)
+        return { tree: [rootPid], identities: null, reused: false };
+    const currentRootIdentity = table.processes.get(rootPid)?.identity;
+    const reused = expectedIdentity != null &&
+        currentRootIdentity !== undefined &&
+        !identitiesMatch(currentRootIdentity, expectedIdentity);
+    if (reused)
+        return { tree: [], identities: null, reused: true };
+    const tree = [rootPid, ...descendantPidsFrom(rootPid, table.childrenOf)];
+    const identities = new Map();
+    for (const pid of tree) {
+        const id = table.processes.get(pid)?.identity;
+        if (id !== undefined)
+            identities.set(pid, id);
+    }
+    return { tree, identities, reused: false };
+}
+/** Best-effort signal against every pid in an ALREADY-CAPTURED tree snapshot
+ *  (typically `[rootPid, ...descendantPids(rootPid)]`, taken ONCE by the
+ *  caller before sending any signal — see the doc on `isProcessTreeAlive` for
+ *  why re-deriving via `ps` after signaling starts is unsafe). Signals EACH
+ *  pid's OWN process group (a detached SDK-spawned descendant is its own
+ *  group leader — the pi bash tool's shell child, crouton-labs/crouter#98)
+ *  PLUS a plain `kill(pid)` on each (belt-and-suspenders for a pid that is
+ *  NOT its own group leader). Every signal is best-effort — `killProcessGroup`
+ *  swallows ESRCH and the plain `kill` here does too — so firing this against
+ *  an already-fully-dead snapshot is a harmless no-op.
+ *
+ *  `identities`, when supplied (crouter#98 review finding 3), is a
+ *  `capturePidIdentities` snapshot taken alongside the pid list at the SAME
+ *  moment — `null` if that INITIAL capture's `ps` probe itself failed (see
+ *  `capturePidIdentities`'s doc). Before signaling EITHER the group or the
+ *  plain kill for a pid, this re-derives CURRENT identities in one fresh
+ *  batched call and compares — but ONLY skips on POSITIVE proof of reuse; any
+ *  failure or absence of evidence falls through to the normal signal path
+ *  (fail-open, matching this module's pre-guard behavior — final review,
+ *  crouter#98 signal-safety finding):
+ *
+ *    - baseline identity present AND the current probe SUCCEEDED AND the
+ *      current identity for this pid is present AND DIFFERENT — the OS has
+ *      recycled this pid for an unrelated process since the snapshot — SKIP
+ *      (the sole skip condition; this is the actual reused-pid hazard finding
+ *      3 targets).
+ *    - baseline identity present but the pid is now simply GONE (current
+ *      probe succeeded, no row for this pid) — it died naturally in the
+ *      meantime, not reused — SIGNAL as normal (harmless no-op on the plain
+ *      kill; load-bearing for the group kill, which can still reach a
+ *      surviving process that shares this now-dead pid's process GROUP).
+ *    - baseline had NO identity at all for this pid (the pid was ALREADY dead
+ *      at snapshot time — e.g. a broker that crashed before `teardown()` ever
+ *      ran) — SIGNAL as normal regardless of the current probe: this is
+ *      exactly how `killProcessGroup` on an already-dead root still reaches a
+ *      live process sharing its process group (the pgid persists after the
+ *      group leader exits; see `host-teardown-process-group.test.ts`'s "dead
+ *      broker" case).
+ *    - the INITIAL capture's probe failed outright (`identities === null`) —
+ *      we have NO baseline to compare against for ANY pid — SIGNAL as normal
+ *      for the whole list; the CURRENT probe is not even attempted (nothing
+ *      to compare it to).
+ *    - the baseline succeeded but the CURRENT probe (taken here) fails — we
+ *      have NO current information — SIGNAL as normal for the whole list; a
+ *      failed probe must never be read as "gone" (would risk reaching a
+ *      reused stranger, the residual risk this guard cannot close) NOR as
+ *      "reused" (would wrongly disable the reap for every real live pid).
+ *
+ *  Callers that omit `identities` entirely (pre-existing call sites) keep the
+ *  prior unguarded behavior. */
+export function killProcessTreePids(pids, signal = 'SIGTERM', identities) {
+    const current = identities != null ? capturePidIdentities(pids) : undefined;
+    for (const pid of pids) {
+        if (identities != null && current != null) {
+            const expected = identities.get(pid);
+            const actual = current.get(pid);
+            const reused = expected !== undefined && actual !== undefined && !identitiesMatch(actual, expected);
+            if (reused)
+                continue;
+        }
+        killProcessGroup(pid, signal);
+        if (!Number.isInteger(pid) || pid <= 0)
+            continue;
+        try {
+            process.kill(pid, signal);
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
+/** Is `rootPid`'s process TREE — itself or any CURRENT descendant — still
+ *  alive, re-deriving the descendant set fresh via `ps` on every call? Safe
+ *  ONLY before any signal has been sent to this tree. Once a signal kills the
+ *  root (it's typically its own process-group leader — see `launch()` in
+ *  host.ts), the kernel reparents any surviving child away from `rootPid`
+ *  IMMEDIATELY (standard orphan handling, confirmed empirically: a killed
+ *  parent's child shows `ppid=1` within the same tick, not lazily) —
+ *  silently "losing" that child from a fresh `descendantPids` walk even
+ *  though it is still very much alive. Use this ONLY to watch a tree you have
+ *  not touched yet (e.g. waiting out a graceful-shutdown grace window); once
+ *  you start signaling, capture the pid list ONCE and check it with
+ *  `isAnyPidAlive` instead — see `killProcessTreePids`. */
+export function isProcessTreeAlive(rootPid) {
+    if (isPidAlive(rootPid))
+        return true;
+    return descendantPids(rootPid).some((pid) => isPidAlive(pid));
+}
+/** Is any pid in an ALREADY-CAPTURED pid list (see `killProcessTreePids`)
+ *  still alive? Pure signal-0 check against the fixed list — NEVER re-walks
+ *  `ps` — the correct liveness check once you've started signaling a tree
+ *  (see `isProcessTreeAlive`'s doc for why re-deriving after that point would
+ *  silently drop a still-alive orphan). */
+export function isAnyPidAlive(pids) {
+    return pids.some((pid) => isPidAlive(pid));
+}