@crouter/api 0.3.387 → 0.3.389

package/dist/core/canvas/pid.js

@@ -0,0 +1,948 @@
+// 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. canvas.ts,
+// revive.ts, placement.ts, and crtrd.ts all probe liveness through it.
+import { spawn, spawnSync } from 'node:child_process';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { readKernelBootId } from './boot-id.js';
+/** Classify the current `ps` row for a pid. BSD ps and procps-ng both report a
+ *  leading `Z` for zombies and exit silently with empty output when no process
+ *  matches. Only a probe that could not run is unknown; that is the sole
+ *  fail-open result. */
+function psProcessState(pid) {
+    if (procfsUsable())
+        return procProcessState(pid);
+    try {
+        const r = spawnSync('ps', ['-o', 'stat=', '-p', String(pid)], { encoding: 'utf8', timeout: 2000 });
+        if (r.error != null || r.signal != null || typeof r.stdout !== 'string')
+            return 'unknown';
+        if (typeof r.stderr === 'string' && r.stderr.trim() !== '')
+            return 'unknown';
+        const stat = r.stdout.trim();
+        if (stat === '')
+            return 'gone';
+        return stat.charAt(0) === 'Z' ? 'zombie' : 'live';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** True if a process with `pid` is currently alive. `kill(pid, 0)` provides the
+ *  initial existence check; EPERM means the foreign process exists. For our
+ *  processes, the later `ps` read is authoritative because it also distinguishes
+ *  zombies and processes reaped between the two probes. Only an unavailable
+ *  `ps` probe fails open to alive. A null/undefined pid reads dead. */
+export function isPidAlive(pid) {
+    if (pid == null)
+        return false;
+    try {
+        process.kill(pid, 0);
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+    const state = psProcessState(pid);
+    return state !== 'zombie' && state !== 'gone';
+}
+/** Existence-only liveness for READ-ONLY display projections: the signal-0
+ *  probe alone, no `ps`. A zombie reads alive here, which a dashboard column
+ *  tolerates and which no lifecycle decision may rely on — revive, teardown,
+ *  and every other authority stays on `isPidAlive`. Exists because the
+ *  dashboard snapshot runs this per live row per request; a `ps` spawn each
+ *  time was a third of daemon CPU on a large canvas. */
+export function isPidPresent(pid) {
+    if (pid == null)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+/** 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. */
+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.
+ *
+ *  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: 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`:
+ *  `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}`;
+}
+/** The `ps` invocation both snapshot captures share, so the synchronous and
+ *  asynchronous forms can never sample different columns. */
+const PS_SNAPSHOT_ARGS = ['-Ao', 'pid=,ppid=,stat=,lstart=,command='];
+const PS_SNAPSHOT_TIMEOUT_MS = 2000;
+export function captureLivenessSnapshot() {
+    if (procfsUsable())
+        return readProcfsSnapshot();
+    let stdout;
+    try {
+        const r = spawnSync('ps', [...PS_SNAPSHOT_ARGS], {
+            encoding: 'utf8',
+            timeout: PS_SNAPSHOT_TIMEOUT_MS,
+            maxBuffer: 8 * 1024 * 1024,
+        });
+        if (r.status !== 0 || typeof r.stdout !== 'string')
+            return null;
+        stdout = r.stdout;
+    }
+    catch {
+        return null;
+    }
+    return parseLivenessTable(stdout);
+}
+/** The same sample without blocking the event loop, for callers running inside
+ *  crtrd's detached work: one `ps` read classifies every pid they care about,
+ *  where a per-pid `spawnSync` probe would stall broker supervision and the API
+ *  socket for the duration of each probe. `null` means the probe failed, which
+ *  every caller must preserve as unknown rather than absence. */
+export async function captureLivenessSnapshotAsync() {
+    if (procfsUsable())
+        return readProcfsSnapshotAsync();
+    const stdout = await new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn('ps', [...PS_SNAPSHOT_ARGS]);
+        }
+        catch {
+            return resolve(null);
+        }
+        let out = '';
+        let settled = false;
+        const settle = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(value);
+        };
+        const timer = setTimeout(() => {
+            try {
+                child.kill('SIGKILL');
+            }
+            catch { /* already gone */ }
+            settle(null);
+        }, PS_SNAPSHOT_TIMEOUT_MS);
+        timer.unref?.();
+        child.stdout.on('data', (d) => (out += d.toString()));
+        child.stderr.on('data', () => { });
+        child.on('error', () => settle(null));
+        child.on('close', (status) => settle(status === 0 ? out : null));
+    });
+    return stdout === null ? null : parseLivenessTable(stdout);
+}
+export function parseProcStat(raw) {
+    const open = raw.indexOf('(');
+    const close = raw.lastIndexOf(')');
+    if (open === -1 || close === -1 || close < open)
+        return null;
+    const rest = raw.slice(close + 2).trim().split(/\s+/);
+    // state(0) ppid(1) ... starttime(19) — proc(5) fields 3, 4 and 22.
+    const state = rest[0];
+    const ppid = Number(rest[1]);
+    const starttime = rest[19];
+    if (state === undefined || state === '' || !Number.isInteger(ppid) || ppid < 0)
+        return null;
+    if (starttime === undefined || !/^\d+$/.test(starttime))
+        return null;
+    return { comm: raw.slice(open + 1, close), state, ppid, starttime };
+}
+/** `/proc/<pid>/cmdline` (NUL-separated argv) as the single space-joined line
+ *  `ps -o command=` prints; kernel threads and zombies, whose cmdline is
+ *  empty, show as `[comm]` exactly as `ps` renders them. */
+export function procCommandLine(rawCmdline, comm) {
+    const joined = rawCmdline.replace(/\0+$/, '').split('\0').join(' ').trim();
+    return joined === '' ? `[${comm}]` : joined;
+}
+let procfsAvailable;
+/** True when this host serves identities from `/proc` (Linux, procfs mounted,
+ *  boot_id readable). Decided once per process: it cannot change underneath a
+ *  running daemon, and a per-probe re-check would defeat the point. */
+function procfsUsable() {
+    if (procfsAvailable === undefined) {
+        procfsAvailable = process.platform === 'linux' && readKernelBootId() !== null && procStatOf(process.pid) !== null;
+    }
+    return procfsAvailable;
+}
+const LIVE_PROC = { root: '/proc', bootId: () => bootIdBase() };
+/** One pid's parsed stat; `null` when it is absent OR unreadable (callers that
+ *  must tell those apart use `readProcStat`). */
+function procStatOf(pid, src = LIVE_PROC) {
+    const r = readProcStat(pid, src);
+    return r === 'unreadable' || r === 'denied' || r === 'gone' ? null : r;
+}
+/** `denied` is a permission refusal (EACCES/EPERM) — what a `hidepid=1` procfs
+ *  answers for another user's pid. It is kept apart from `unreadable` (any other
+ *  failure, or a stat that does not parse) because only a refusal on a process
+ *  this user does not own is safe to leave out of a whole-table sample. */
+function readProcStat(pid, src = LIVE_PROC) {
+    let raw;
+    try {
+        raw = readFileSync(`${src.root}/${pid}/stat`, 'utf8');
+    }
+    catch (e) {
+        return classifyProcReadError(e);
+    }
+    return parseProcStat(raw) ?? 'unreadable';
+}
+function classifyProcReadError(e) {
+    const code = e.code;
+    if (code === 'ENOENT' || code === 'ESRCH')
+        return 'gone';
+    return code === 'EACCES' || code === 'EPERM' ? 'denied' : 'unreadable';
+}
+/** Whether a process whose `stat` was refused is provably someone else's: its
+ *  `/proc/<pid>` directory is owned by a different uid than ours. Anything we
+ *  cannot establish (no uid, the directory unreadable for another reason) is
+ *  treated as possibly ours — a refusal on a process that may matter must fail
+ *  the sample, never read as absence. `gone` means it vanished meanwhile. */
+function procOwnership(pid, src) {
+    const self = src.selfUid !== undefined ? src.selfUid() : (process.getuid?.() ?? null);
+    if (self === null)
+        return 'own-or-unknown';
+    try {
+        return statSync(`${src.root}/${pid}`).uid === self ? 'own-or-unknown' : 'foreign';
+    }
+    catch (e) {
+        return classifyProcReadError(e) === 'gone' ? 'gone' : 'own-or-unknown';
+    }
+}
+/** What a whole-table scan does with a pid whose stat could not be read:
+ *  `skip` (vanished, or another user's process this user is not allowed to see
+ *  — absent, exactly as `ps` omits it under `hidepid`) or `fail`. */
+function scanDisposition(failure, pid, src) {
+    if (failure === 'gone')
+        return 'skip';
+    if (failure === 'unreadable')
+        return 'fail';
+    const owner = procOwnership(pid, src);
+    return owner === 'own-or-unknown' ? 'fail' : 'skip';
+}
+function procIdentity(stat, src = LIVE_PROC) {
+    const bootId = src.bootId();
+    return bootId === null ? null : `${bootId}#${stat.starttime}`;
+}
+function procProcessState(pid, src = LIVE_PROC) {
+    const stat = readProcStat(pid, src);
+    if (stat === 'gone')
+        return 'gone';
+    if (stat === 'denied' || stat === 'unreadable')
+        return 'unknown';
+    return stat.state === 'Z' || stat.state === 'X' ? 'zombie' : 'live';
+}
+function procIdentities(pids, src = LIVE_PROC) {
+    const out = new Map();
+    for (const pid of pids) {
+        const stat = readProcStat(pid, src);
+        if (stat === 'gone')
+            continue;
+        if (stat === 'unreadable' || stat === 'denied')
+            return null;
+        const identity = procIdentity(stat, src);
+        if (identity === null)
+            return null;
+        out.set(pid, identity);
+    }
+    return out;
+}
+function procCommand(pid, src = LIVE_PROC) {
+    const stat = readProcStat(pid, src);
+    if (stat === 'gone' || stat === 'unreadable' || stat === 'denied')
+        return null;
+    try {
+        const command = procCommandLine(readFileSync(`${src.root}/${pid}/cmdline`, 'utf8'), stat.comm);
+        return command === '' ? null : command;
+    }
+    catch {
+        return null;
+    }
+}
+function addProcfsRow(src, rows, pid, stat, rawCmdline) {
+    const identity = procIdentity(stat, src);
+    if (identity === null)
+        return false;
+    rows.processes.set(pid, { zombie: stat.state === 'Z' || stat.state === 'X', identity, command: procCommandLine(rawCmdline, stat.comm) });
+    const siblings = rows.childrenOf.get(stat.ppid);
+    if (siblings === undefined)
+        rows.childrenOf.set(stat.ppid, [pid]);
+    else
+        siblings.push(pid);
+    return true;
+}
+function procPids(root) {
+    try {
+        return readdirSync(root).filter((name) => /^\d+$/.test(name)).map(Number).filter((pid) => pid > 0);
+    }
+    catch {
+        return null;
+    }
+}
+/** One whole-table sample from procfs. Skipped as absent, as in a `ps` sample:
+ *  a pid that vanishes between the listing and its read, and a pid whose stat
+ *  is refused (EACCES/EPERM — `hidepid=1`) when its `/proc/<pid>` directory is
+ *  owned by another uid (this user cannot see it, and `ps` would not list it).
+ *  Every other read failure — including a refusal on a process we own or whose
+ *  owner we cannot establish — fails the whole sample, which every caller
+ *  treats as unknown. */
+export function readProcfsSnapshot(src = LIVE_PROC) {
+    const pids = procPids(src.root);
+    if (pids === null)
+        return null;
+    const rows = { processes: new Map(), childrenOf: new Map() };
+    for (const pid of pids) {
+        const stat = readProcStat(pid, src);
+        if (stat === 'gone' || stat === 'denied' || stat === 'unreadable') {
+            if (scanDisposition(stat === 'gone' ? 'gone' : stat, pid, src) === 'skip')
+                continue;
+            return null;
+        }
+        let cmdline = '';
+        try {
+            cmdline = readFileSync(`${src.root}/${pid}/cmdline`, 'utf8');
+        }
+        catch (e) {
+            const code = e.code;
+            if (code === 'ENOENT' || code === 'ESRCH')
+                continue;
+            // An unreadable cmdline only costs the command text (shown as `[comm]`);
+            // the identity and parentage — what every safety decision uses — came
+            // from `stat`.
+        }
+        if (!addProcfsRow(src, rows, pid, stat, cmdline))
+            return null;
+    }
+    return rows;
+}
+/** The same sample without blocking the event loop (crtrd's detached work). */
+export async function readProcfsSnapshotAsync(src = LIVE_PROC) {
+    const pids = procPids(src.root);
+    if (pids === null)
+        return null;
+    const rows = { processes: new Map(), childrenOf: new Map() };
+    const BATCH = 64;
+    for (let i = 0; i < pids.length; i += BATCH) {
+        const batch = pids.slice(i, i + BATCH);
+        const read = await Promise.all(batch.map(async (pid) => {
+            try {
+                const stat = parseProcStat(await readFile(`${src.root}/${pid}/stat`, 'utf8'));
+                if (stat === null)
+                    return 'failed';
+                const cmdline = await readFile(`${src.root}/${pid}/cmdline`, 'utf8').catch((e) => {
+                    if (e.code === 'ENOENT' || e.code === 'ESRCH')
+                        throw e;
+                    return ''; // unreadable cmdline costs only the command text, as in the sync sample
+                });
+                return { pid, stat, cmdline };
+            }
+            catch (e) {
+                // `stat` is read first, so an ENOENT/ESRCH can also come from the
+                // cmdline read of a pid that exited between the two — gone either way.
+                return scanDisposition(classifyProcReadError(e), pid, src) === 'skip' ? 'gone' : 'failed';
+            }
+        }));
+        for (const item of read) {
+            if (item === 'gone')
+                continue;
+            if (item === 'failed')
+                return null;
+            if (!addProcfsRow(src, rows, item.pid, item.stat, item.cmdline))
+                return null;
+        }
+    }
+    return rows;
+}
+/** Every live process's pid, parent pid and full command line, for callers that
+ *  only match command text or walk parentage (stray-daemon sweep, viewer-pane
+ *  detection). `null` when no sample could be taken. Same backend rule as the
+ *  rest of this module: `/proc` where usable, `ps` elsewhere. */
+export function listProcessTable() {
+    if (procfsUsable()) {
+        const snapshot = readProcfsSnapshot();
+        if (snapshot === null)
+            return null;
+        const ppidOf = new Map();
+        for (const [ppid, kids] of snapshot.childrenOf)
+            for (const kid of kids)
+                ppidOf.set(kid, ppid);
+        return [...snapshot.processes].map(([pid, p]) => ({ pid, ppid: ppidOf.get(pid) ?? 0, command: p.command }));
+    }
+    try {
+        const r = spawnSync('ps', ['-ax', '-o', 'pid=,ppid=,command='], { encoding: 'utf8', timeout: 2000, maxBuffer: 8 * 1024 * 1024 });
+        if (r.status !== 0 || typeof r.stdout !== 'string')
+            return null;
+        const out = [];
+        for (const line of r.stdout.split('\n')) {
+            const m = /^\s*(\d+)\s+(\d+)\s+(.*)$/.exec(line);
+            if (m === null)
+                continue;
+            out.push({ pid: Number(m[1]), ppid: Number(m[2]), command: m[3].trim() });
+        }
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
+/** Test seam: exercise the `/proc` backend against a fake tree. */
+export const procfsBackendForTest = { procIdentities, procProcessState, procCommand, readProcfsSnapshot, readProcfsSnapshotAsync };
+function parseLivenessTable(stdout) {
+    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. 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: 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 is unsafe:
+ *  `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;
+    if (procfsUsable())
+        return procIdentities(valid);
+    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;
+    if (procfsUsable())
+        return procCommand(pid);
+    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, excludePid) {
+    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 excluded = excludePid !== undefined && Number.isInteger(excludePid) && excludePid > 0
+        ? new Set([excludePid, ...descendantPidsFrom(excludePid, table.childrenOf)])
+        : undefined;
+    const tree = [rootPid, ...descendantPidsFrom(rootPid, table.childrenOf)].filter((pid) => !excluded?.has(pid));
+    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)
+ *  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, 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 unguarded behavior):
+ *
+ *    - 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));
+}