@crouter/api 0.3.387 → 0.3.388

package/dist/core/canvas/pid.d.ts

@@ -0,0 +1,391 @@
+type PsProcessState = 'zombie' | 'gone' | 'live' | '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 declare function isPidAlive(pid: number | null | undefined): boolean;
+/** 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 declare function isPidPresent(pid: number | null | undefined): boolean;
+/** 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 declare function identitiesMatch(a: string, b: string): boolean;
+/** Three-valued liveness verdict for a RECORDED node pid, identity-guarded
+ *  against PID REUSE using the launch-time baseline (`pi_pid_identity`,
+ *  captured by `recordPid`). On a heavily-forking host — esp. Linux, where
+ *  low pids recycle fast — a broker's recorded pid can be reused by an
+ *  unrelated process (or the `ps` probe confirming it can itself
+ *  intermittently fail) within milliseconds of the broker dying; collapsing
+ *  "confirmed alive", "confirmed dead/reused", and "couldn't confirm either
+ *  way" into one boolean forces every caller to fail open to ALIVE on the
+ *  third case — which, upstream in the daemon's grace-clock bookkeeping, is
+ *  worse than misreporting one tick: a single such read WIPES the daemon's
+ *  memory that the node had already been observed dead, restarting the whole
+ *  grace window from scratch (the confirmed Round-2 crash-revive wedge, in
+ *  the pre-fleet daemon's liveness bookkeeping). Exposing the third state lets callers
+ *  decide for themselves whether "can't confirm" should act like alive or
+ *  dead for their own direction of risk.
+ *
+ *  Without a snapshot this preserves the historical per-pid probes. With a
+ *  snapshot it classifies process presence, zombie state, and identity from
+ *  that one authoritative table read:
+ *    - absent or zombie pid → `'dead'`. Load-bearing: a SIGKILLed detached
+ *      broker awaiting reap must still be revived rather than read as live.
+ *    - `expectedIdentity == null` (legacy row / launch capture failed) →
+ *      `'alive'` (preserve pre-identity behavior — no baseline to check
+ *      against).
+ *    - `ps` probe itself failed (`capturePidIdentities` → `null`) →
+ *      `'indeterminate'`. THIS is the branch the Round-2 fix changes: it used
+ *      to fail open to `true` (alive) here, which is the confirmed root cause
+ *      of the wedge.
+ *    - probe succeeded but has no row for this pid (alive per signal-0 a
+ *      moment ago, gone now) → `'dead'`.
+ *    - probe succeeded and the identity is present → `'alive'` iff
+ *      `identitiesMatch` says so, else `'dead'` (positively reused). */
+export type RecordedPidLiveness = 'alive' | 'dead' | 'indeterminate';
+export declare function recordedPidLiveness(pid: number | null | undefined, expectedIdentity: string | null | undefined, snapshot?: PsLivenessSnapshot | null): RecordedPidLiveness;
+/** 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 declare function killProcessGroup(pid: number, signal?: NodeJS.Signals): void;
+/** 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 declare function makeBootIdCache(read: () => string | null, now?: () => number, negativeTtlMs?: number): () => string | null;
+/** 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 declare function isLegacyTicksIdentity(identity: string): boolean;
+/** 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 declare function isBootScopedIdentity(identity: string): boolean;
+/** 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 declare function composeIdentity(pid: number, lstart: string, deps?: {
+    ticks?: string | null;
+    bootId?: string | null;
+}): string;
+/** One authoritative process-table sample. Supervision, broker census,
+ *  teardown tree walks, identity guards, and zombie detection can all classify
+ *  from this one read instead of spawning a `ps` probe per pid. `null` means the
+ *  probe itself failed; callers preserve that as unknown rather than absence. */
+export interface PsLivenessProcess {
+    zombie: boolean;
+    identity: string;
+    command: string;
+}
+export interface PsLivenessSnapshot {
+    processes: ReadonlyMap<number, PsLivenessProcess>;
+    childrenOf: ReadonlyMap<number, number[]>;
+}
+export declare function captureLivenessSnapshot(): PsLivenessSnapshot | null;
+/** 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 declare function captureLivenessSnapshotAsync(): Promise<PsLivenessSnapshot | null>;
+/** Parsed `/proc/<pid>/stat`: `comm` is parenthesized and may itself contain
+ *  spaces/parens, so fields are counted after the LAST `)`. */
+interface ProcStat {
+    comm: string;
+    state: string;
+    ppid: number;
+    starttime: string;
+}
+export declare function parseProcStat(raw: string): ProcStat | null;
+/** `/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 declare function procCommandLine(rawCmdline: string, comm: string): string;
+/** Where a procfs read comes from: the real `/proc` in production, a fake tree
+ *  plus a fixed boot id in tests. */
+interface ProcSource {
+    root: string;
+    bootId: () => string | null;
+    /** The uid this process runs as; defaults to `process.getuid()`. Tests inject
+     *  one so a fake tree (owned by the test user) can hold a "foreign" entry. */
+    selfUid?: () => number | null;
+}
+declare function procProcessState(pid: number, src?: ProcSource): PsProcessState;
+declare function procIdentities(pids: readonly number[], src?: ProcSource): Map<number, string> | null;
+declare function procCommand(pid: number, src?: ProcSource): string | 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 declare function readProcfsSnapshot(src?: ProcSource): PsLivenessSnapshot | null;
+/** The same sample without blocking the event loop (crtrd's detached work). */
+export declare function readProcfsSnapshotAsync(src?: ProcSource): Promise<PsLivenessSnapshot | null>;
+/** 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 declare function listProcessTable(): {
+    pid: number;
+    ppid: number;
+    command: string;
+}[] | null;
+/** Test seam: exercise the `/proc` backend against a fake tree. */
+export declare const procfsBackendForTest: {
+    procIdentities: typeof procIdentities;
+    procProcessState: typeof procProcessState;
+    procCommand: typeof procCommand;
+    readProcfsSnapshot: typeof readProcfsSnapshot;
+    readProcfsSnapshotAsync: typeof readProcfsSnapshotAsync;
+};
+/** 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 declare function descendantPids(rootPid: number): number[];
+/** 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 declare function capturePidIdentities(pids: readonly number[]): Map<number, string> | 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 declare function capturePidCommand(pid: number): string | null;
+/** The full pre-signal snapshot `teardown()` needs, taken ONCE, from ONE `ps`
+ *  table: the process TREE rooted at `rootPid`
+ *  (itself + every transitive descendant) alongside each member's identity
+ *  fingerprint — PLUS, load-bearing, a launch-time-identity REUSE check on
+ *  `rootPid` itself before the tree is even walked.
+ *
+ *  The hazard this closes: the PID-reuse guard elsewhere in this module (see
+ *  `killProcessTreePids`) only ever compared identities captured across the
+ *  teardown ESCALATION window (a few seconds) — it had no idea whether
+ *  `rootPid` (the broker pid recorded on the node row at LAUNCH time, possibly
+ *  hours or days earlier) had ALREADY been recycled for an unrelated process
+ *  before `teardown()` was ever called. In that case the naive snapshot would
+ *  capture the STRANGER's current identity as the "expected" baseline and
+ *  cheerfully SIGTERM/SIGKILL it and whatever the stranger's OWN process tree
+ *  turns out to be — exactly the wrong-victim risk finding 1 targets.
+ *
+ *  `expectedIdentity` is the LAUNCH-time identity recorded on the node row
+ *  (`recordPid`'s `capturePidIdentities([pid])` snapshot, taken the instant the
+ *  broker was spawned/bound) — `null` for a node booted before this field
+ *  existed, or if that original capture itself failed. When `expectedIdentity`
+ *  is present AND the CURRENT probe for `rootPid` succeeds AND finds a DIFFERENT
+ *  identity, `rootPid` is provably a different OS process than the broker this
+ *  node ever launched: `reused: true`, `tree: []`, `identities: null` — the
+ *  caller must treat this exactly like "nothing to tear down", and must NOT
+ *  walk `descendantPids` from this poisoned root (those "descendants" would be
+ *  the STRANGER's children, not this node's). Every other case (no baseline,
+ *  the pid is simply gone, the probe itself failed) falls through to the
+ *  normal walk — fail-open, matching every other guard in this module: a
+ *  MISMATCH is the only thing that skips, never an absence of evidence. */
+export interface TeardownSnapshot {
+    /** `[rootPid, ...descendants]`, or `[]` when `reused` is true (nothing safe
+     *  to signal) or `rootPid` itself is invalid. */
+    tree: number[];
+    /** Identity fingerprint per pid in `tree`, from the SAME `ps` table read as
+     *  the tree walk — or `null` when that probe failed outright (fail-open: the
+     *  caller's downstream `killProcessTreePids` signals unguarded in that case,
+     *  same as an omitted `identities` arg). Always `null` when `reused` is true
+     *  (there is no tree to guard). */
+    identities: Map<number, string> | null;
+    /** True iff `rootPid`'s CURRENT identity is POSITIVELY known to differ from
+     *  `expectedIdentity` — the pid was already reused by an unrelated process
+     *  before this snapshot was taken. Callers must skip ALL signaling when true. */
+    reused: boolean;
+}
+export declare function captureTeardownSnapshot(rootPid: number, expectedIdentity: string | null, excludePid?: number): TeardownSnapshot;
+/** 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 declare function killProcessTreePids(pids: readonly number[], signal?: NodeJS.Signals, identities?: ReadonlyMap<number, string> | null): void;
+/** 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 declare function isProcessTreeAlive(rootPid: number): boolean;
+/** 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 declare function isAnyPidAlive(pids: readonly number[]): boolean;
+export {};