@north-light/crouter 0.3.318 → 0.3.320

package/dist/core/canvas/pid.js

@@ -1,683 +1,4 @@
-// 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 } from 'node:fs';
-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) {
-    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() {
-    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() {
-    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);
-}
-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;
-    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, 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));
-}
+var x=Object.defineProperty;var u=(e,t)=>x(e,"name",{value:t,configurable:!0});import{spawn as $,spawnSync as m}from"node:child_process";import{readFileSync as E}from"node:fs";import{readKernelBootId as O}from"./boot-id.js";function P(e){try{const t=m("ps",["-o","stat=","-p",String(e)],{encoding:"utf8",timeout:2e3});if(t.error!=null||t.signal!=null||typeof t.stdout!="string"||typeof t.stderr=="string"&&t.stderr.trim()!=="")return"unknown";const n=t.stdout.trim();return n===""?"gone":n.charAt(0)==="Z"?"zombie":"live"}catch{return"unknown"}}u(P,"psProcessState");function p(e){if(e==null)return!1;try{process.kill(e,0)}catch(n){return n.code==="EPERM"}const t=P(e);return t!=="zombie"&&t!=="gone"}u(p,"isPidAlive");function J(e){if(e==null)return!1;try{return process.kill(e,0),!0}catch(t){return t.code==="EPERM"}}u(J,"isPidPresent");const b=/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;function g(e){const t=e.indexOf("#");if(t===-1)return{base:e,ticks:void 0};const n=e.slice(t+1);return{base:e.slice(0,t),ticks:/^\d+$/.test(n)?n:void 0}}u(g,"splitIdentity");function S(e,t){const n=g(e),r=g(t);return n.ticks!==void 0&&r.ticks!==void 0?b.test(n.base)&&b.test(r.base)?n.base===r.base&&n.ticks===r.ticks:n.ticks===r.ticks:n.base===r.base}u(S,"identitiesMatch");function U(e,t,n){const r=!!process.env.CRTR_DEBUG_PID_LIVENESS;if(e==null)return"dead";if(n===null)return r&&d(e,!1,t,"probe-null","ps snapshot failed \u2192 indeterminate","indeterminate"),"indeterminate";const i=n?.processes.get(e),s=n===void 0?p(e):i!==void 0&&!i.zombie;if(!s)return r&&d(e,s,t,n===void 0?"no-probe":"no-entry","process absent/zombie \u2192 dead","dead"),"dead";if(t==null)return r&&d(e,s,t,"no-probe","no baseline \u2192 trust process presence","alive"),"alive";let o;if(n===void 0){const l=w([e]);if(l==null)return r&&d(e,s,t,"probe-null","ps probe failed \u2192 indeterminate","indeterminate"),"indeterminate";if(o=l.get(e),o===void 0)return r&&d(e,s,t,"no-entry","no identity row for pid (race) \u2192 dead","dead"),"dead"}else o=i.identity;const c=S(o,t);return r&&d(e,s,t,"value",c?"identity matches expected \u2192 alive":"identity differs from expected \u2192 REUSED \u2192 dead",c?"alive":"dead",o),c?"alive":"dead"}u(U,"recordedPidLiveness");function d(e,t,n,r,i,s,o){const c=[`pid=${String(e)}`,`isPidAlive=${t}`,`expectedIdentity=${n===void 0?"undefined":n===null?"null":JSON.stringify(n)}`,`capturePidIdentities=${r}${r==="value"?`(${JSON.stringify(o)})`:""}`,`branch=${JSON.stringify(i)}`,`returned=${s}`];process.stderr.write(`[recordedPidLiveness] ${c.join(" ")}
+`)}u(d,"logPidLivenessDecision");function _(e,t="SIGTERM"){if(!(!Number.isInteger(e)||e<=0))try{process.kill(-e,t)}catch{}}u(_,"killProcessGroup");function A(e){try{const t=E(`/proc/${e}/stat`,"utf8"),n=t.lastIndexOf(")");if(n===-1)return null;const i=t.slice(n+2).trim().split(/\s+/)[19];return i!==void 0&&/^\d+$/.test(i)?i:null}catch{return null}}u(A,"procStartTicks");const M=6e4;function L(e,t=Date.now,n=M){let r=null,i=0;return()=>{if(r!==null)return r;const s=t();if(s<i)return null;const o=e();return o!==null?r=o:(i=s+n,null)}}u(L,"makeBootIdCache");const R=L(O);function j(e){const{base:t,ticks:n}=g(e);return n!==void 0&&!b.test(t)}u(j,"isLegacyTicksIdentity");function F(e){const{base:t,ticks:n}=g(e);return n!==void 0&&b.test(t)}u(F,"isBootScopedIdentity");function k(e,t,n={}){const r=n.ticks!==void 0?n.ticks:A(e);return r===null?t:`${(n.bootId!==void 0?n.bootId:R())??t}#${r}`}u(k,"composeIdentity");const I=["-Ao","pid=,ppid=,stat=,lstart=,command="],v=2e3;function N(){let e;try{const t=m("ps",[...I],{encoding:"utf8",timeout:v,maxBuffer:8388608});if(t.status!==0||typeof t.stdout!="string")return null;e=t.stdout}catch{return null}return T(e)}u(N,"captureLivenessSnapshot");async function H(){const e=await new Promise(t=>{let n;try{n=$("ps",[...I])}catch{return t(null)}let r="",i=!1;const s=u(c=>{i||(i=!0,clearTimeout(o),t(c))},"settle"),o=setTimeout(()=>{try{n.kill("SIGKILL")}catch{}s(null)},v);o.unref?.(),n.stdout.on("data",c=>r+=c.toString()),n.stderr.on("data",()=>{}),n.on("error",()=>s(null)),n.on("close",c=>s(c===0?r:null))});return e===null?null:T(e)}u(H,"captureLivenessSnapshotAsync");function T(e){const t=new Map,n=new Map;for(const r of e.split(`
+`)){const i=r.trim();if(i==="")continue;const s=/^(\d+)\s+(\d+)\s+(\S+)\s+(\S+(?:\s+\S+){4})\s+(.+)$/.exec(i);if(s===null)continue;const o=Number(s[1]),c=Number(s[2]),l=s[3],f=s[4],a=s[5].trim();if(!Number.isInteger(o)||o<=0||!Number.isInteger(c)||c<0||a==="")continue;t.set(o,{zombie:l.startsWith("Z"),identity:k(o,f),command:a});const y=n.get(c);y===void 0?n.set(c,[o]):y.push(o)}return{processes:t,childrenOf:n}}u(T,"parseLivenessTable");function h(e,t){const n=[],r=new Set([e]),i=[...t.get(e)??[]];for(;i.length>0;){const s=i.shift();if(r.has(s))continue;r.add(s),n.push(s);const o=t.get(s);o!==void 0&&i.push(...o)}return n}u(h,"descendantPidsFrom");function B(e){if(!Number.isInteger(e)||e<=0)return[];const t=N();return t===null?[]:h(e,t.childrenOf)}u(B,"descendantPids");function w(e){const t=e.filter(r=>Number.isInteger(r)&&r>0),n=new Map;if(t.length===0)return n;try{const r=m("ps",["-o","pid=,lstart=","-p",t.join(",")],{encoding:"utf8",timeout:2e3});if(r.error!=null||r.signal!=null||typeof r.stdout!="string"||typeof r.stderr=="string"&&r.stderr.trim()!=="")return null;for(const i of r.stdout.split(`
+`)){const s=i.trim();if(s==="")continue;const o=s.indexOf(" ");if(o===-1)continue;const c=Number(s.slice(0,o)),l=s.slice(o+1).trim();!Number.isInteger(c)||c<=0||l===""||n.set(c,k(c,l))}return n}catch{return null}}u(w,"capturePidIdentities");function K(e){if(!Number.isInteger(e)||e<=0)return null;try{const t=m("ps",["-o","command=","-p",String(e)],{encoding:"utf8",timeout:2e3});if(t.status!==0||typeof t.stdout!="string")return null;const n=t.stdout.trim();return n===""?null:n}catch{return null}}u(K,"capturePidCommand");function V(e,t,n){if(!Number.isInteger(e)||e<=0)return{tree:[],identities:null,reused:!1};const r=N();if(r===null)return{tree:[e],identities:null,reused:!1};const i=r.processes.get(e)?.identity;if(t!=null&&i!==void 0&&!S(i,t))return{tree:[],identities:null,reused:!0};const o=n!==void 0&&Number.isInteger(n)&&n>0?new Set([n,...h(n,r.childrenOf)]):void 0,c=[e,...h(e,r.childrenOf)].filter(f=>!o?.has(f)),l=new Map;for(const f of c){const a=r.processes.get(f)?.identity;a!==void 0&&l.set(f,a)}return{tree:c,identities:l,reused:!1}}u(V,"captureTeardownSnapshot");function Z(e,t="SIGTERM",n){const r=n!=null?w(e):void 0;for(const i of e){if(n!=null&&r!=null){const s=n.get(i),o=r.get(i);if(s!==void 0&&o!==void 0&&!S(o,s))continue}if(_(i,t),!(!Number.isInteger(i)||i<=0))try{process.kill(i,t)}catch{}}}u(Z,"killProcessTreePids");function q(e){return p(e)?!0:B(e).some(t=>p(t))}u(q,"isProcessTreeAlive");function W(e){return e.some(t=>p(t))}u(W,"isAnyPidAlive");export{N as captureLivenessSnapshot,H as captureLivenessSnapshotAsync,K as capturePidCommand,w as capturePidIdentities,V as captureTeardownSnapshot,k as composeIdentity,B as descendantPids,S as identitiesMatch,W as isAnyPidAlive,F as isBootScopedIdentity,j as isLegacyTicksIdentity,p as isPidAlive,J as isPidPresent,q as isProcessTreeAlive,_ as killProcessGroup,Z as killProcessTreePids,L as makeBootIdCache,U as recordedPidLiveness};