@north-light/crouter 0.3.154

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

@@ -0,0 +1,81 @@
+/** Root of the global canvas home (`~/.crouter/canvas` unless `CRTR_HOME` is set).
+ *  Nested under the `.crouter` scope root so the whole runtime lives in one
+ *  visible top-level dir; `canvas/` keeps node-graph runtime state separate from
+ *  durable user content (memory/plugins/marketplaces/config) at the scope root. */
+export declare function crtrHome(): string;
+/** Absolute path to the SQLite canvas db file — always `canvas.db` under the
+ *  canvas home, beside the node data it indexes. Guest deployments (Blaxel
+ *  volumes, local-docker mounts) put the whole canvas home on durable
+ *  block storage, which supports SQLite's advisory fcntl/WAL locking like any
+ *  local disk — so the db shares the node data's location and survives a
+ *  sandbox recreate together with `nodes/`. */
+export declare function canvasDbPath(): string;
+/** Absolute path to a node's broker `view.sock` — always `view.sock` under the
+ *  node dir. Stale socket files (a host reboot, a sandbox recreate on a
+ *  durable volume) are harmless: the broker unlinks any existing socket before
+ *  it binds. */
+export declare function viewSocketPath(nodeId: string): string;
+export declare function nodesRoot(): string;
+/** Absolute path to crtrd's API listener unix socket, a sibling of
+ *  `canvasDbPath()` under the canvas home (`~/.crouter/canvas/crtrd.sock` unless
+ *  `CRTR_HOME` is set). Pure path builder — no db reach — so both the daemon
+ *  (which binds it) and a CLI-side resolver can import it freely. `src/api`'s
+ *  `CrtrClient.forLocalSocket()` deliberately re-derives this same path from a
+ *  Node-builtin `join(crtrHome-equivalent, 'crtrd.sock')` rather than importing
+ *  here, to keep the exported `/api` contract dependency-light; the two must
+ *  agree. */
+export declare function apiSocketPath(): string;
+/** Global, cwd-agnostic broker cache of per-session picker metadata, keyed by
+ *  absolute `.jsonl` path. Shared across every node's broker (paths are absolute)
+ *  and survives broker restarts so the first `/resume` open after a restart is
+ *  also fast. Machine-local performance state — safe to delete; rebuilt on demand. */
+export declare function sessionListCachePath(): string;
+/** Whether a persisted node ID is safe as a single filesystem path segment. */
+export declare function isSafeNodeId(nodeId: string): boolean;
+export declare function nodeDir(nodeId: string): string;
+export declare function contextDir(nodeId: string): string;
+/** Replace the literal env-var tokens `$CRTR_CONTEXT_DIR` / `$CRTR_NODE_ID` in
+ *  agent-facing doc text with the node's real values, so a doc surfaced INTO a
+ *  node hands it a concrete absolute path instead of a shell-only string. The
+ *  env vars only expand in bash; an agent that pastes `$CRTR_CONTEXT_DIR/x.md`
+ *  into the (non-expanding) Write tool creates a literal `$CRTR_CONTEXT_DIR/`
+ *  dir under the project repo. The resolved absolute path works in both bash and
+ *  Write, so this substitution is strictly safer. Callers must only apply it
+ *  when they have a concrete node to render for (never on generic, node-less
+ *  output). Pure string work — no I/O. */
+export declare function interpolateNodePaths(text: string, nodeId: string): string;
+export declare function jobDir(nodeId: string): string;
+export declare function reportsDir(nodeId: string): string;
+/** Overflow store for inbox entries whose inline body exceeds the digest's
+ *  bounded preview (a direct `node message send` or a close/cancel doctrine
+ *  wake) — the full body spills here, mirroring how a
+ *  push's body always lives in a file, never inline; the inbox entry then
+ *  carries `ref` at this path, same as a push pointer. */
+export declare function messagesDir(nodeId: string): string;
+export declare function nodeMetaPath(nodeId: string): string;
+export declare function inboxPath(nodeId: string): string;
+/** The node-owned ambient "current situation" sidecar — the latest hidden
+ *  `<situational-context>` text injected into bearings/kickoff (see
+ *  `runtime/situational-context.ts`), upserted in place rather than appended so
+ *  only the newest applet/situation state is ever carried. Lives beside
+ *  meta.json/inbox.jsonl (node-runtime state) rather than under context/ (the
+ *  user-authored artifact store), because it is ambient machine state, not a
+ *  document a human wrote. */
+export declare function situationalContextPath(nodeId: string): string;
+/** Passive-subscription accumulator. Pushes from publishers this node subscribes
+ *  to PASSIVELY land here instead of inbox.jsonl — the inbox-watcher never polls
+ *  it, so they never wake the node. Drained as XML pre-text on the next message. */
+export declare function passivePath(nodeId: string): string;
+export declare function transcriptPath(nodeId: string): string;
+export declare function sessionPtrPath(nodeId: string): string;
+/** On-read injection dedup set — the doc realpaths already surfaced on-read in
+ *  this node's CURRENT conversation transcript. Persisted so the once-per-
+ *  transcript dedup survives a dormancy → revive(resume) cycle: a resume reuses
+ *  the same .jsonl transcript in a NEW pi process, so the in-memory set would
+ *  otherwise start empty and re-inject docs already present in the transcript.
+ *  Deleted by the launch paths that start a FRESH transcript. */
+export declare function injectedDocsPath(nodeId: string): string;
+/** Create the full directory skeleton for a node. Idempotent. */
+export declare function ensureNodeDirs(nodeId: string): void;
+/** Ensure the canvas home exists. Idempotent. */
+export declare function ensureHome(): void;

package/dist/core/canvas/paths.js

@@ -0,0 +1,164 @@
+// The `~/.crouter/canvas/` layout. One global, cwd-agnostic home for the whole canvas.
+//
+//   ~/.crouter/canvas/
+//     canvas.db                 sqlite (WAL) — topology only (nodes + edges)
+//     nodes/<node_id>/
+//       meta.json               source of truth for the node's row
+//       context/                roadmap.md, initial-prompt.md, explore-*.md, artifacts
+//       job/                    log.jsonl (canonical broker events), telemetry.json and fault (current state), broker.log (raw residue)
+//       reports/                append-only push history (<ts>-<kind>.md)
+//       messages/               overflow bodies for inbox entries too long to inline
+//       inbox.jsonl             messages + coalesced subscription feed
+//       transcript.jsonl        mirror/pointer of the pi session
+//       session.ptr             pi session id/path
+//
+// `CRTR_HOME` overrides the root (used by tests and isolated runs).
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import { CRTR_DIR_NAME } from '../../types.js';
+/** Root of the global canvas home (`~/.crouter/canvas` unless `CRTR_HOME` is set).
+ *  Nested under the `.crouter` scope root so the whole runtime lives in one
+ *  visible top-level dir; `canvas/` keeps node-graph runtime state separate from
+ *  durable user content (memory/plugins/marketplaces/config) at the scope root. */
+export function crtrHome() {
+    const override = process.env['CRTR_HOME'];
+    return override !== undefined && override !== ''
+        ? override
+        : join(homedir(), CRTR_DIR_NAME, 'canvas');
+}
+/** Absolute path to the SQLite canvas db file — always `canvas.db` under the
+ *  canvas home, beside the node data it indexes. Guest deployments (Blaxel
+ *  volumes, local-docker mounts) put the whole canvas home on durable
+ *  block storage, which supports SQLite's advisory fcntl/WAL locking like any
+ *  local disk — so the db shares the node data's location and survives a
+ *  sandbox recreate together with `nodes/`. */
+export function canvasDbPath() {
+    return join(crtrHome(), 'canvas.db');
+}
+/** Absolute path to a node's broker `view.sock` — always `view.sock` under the
+ *  node dir. Stale socket files (a host reboot, a sandbox recreate on a
+ *  durable volume) are harmless: the broker unlinks any existing socket before
+ *  it binds. */
+export function viewSocketPath(nodeId) {
+    assertSafeNodeId(nodeId);
+    return join(nodeDir(nodeId), 'view.sock');
+}
+export function nodesRoot() {
+    return join(crtrHome(), 'nodes');
+}
+/** Absolute path to crtrd's API listener unix socket, a sibling of
+ *  `canvasDbPath()` under the canvas home (`~/.crouter/canvas/crtrd.sock` unless
+ *  `CRTR_HOME` is set). Pure path builder — no db reach — so both the daemon
+ *  (which binds it) and a CLI-side resolver can import it freely. `src/api`'s
+ *  `CrtrClient.forLocalSocket()` deliberately re-derives this same path from a
+ *  Node-builtin `join(crtrHome-equivalent, 'crtrd.sock')` rather than importing
+ *  here, to keep the exported `/api` contract dependency-light; the two must
+ *  agree. */
+export function apiSocketPath() {
+    return join(crtrHome(), 'crtrd.sock');
+}
+/** Global, cwd-agnostic broker cache of per-session picker metadata, keyed by
+ *  absolute `.jsonl` path. Shared across every node's broker (paths are absolute)
+ *  and survives broker restarts so the first `/resume` open after a restart is
+ *  also fast. Machine-local performance state — safe to delete; rebuilt on demand. */
+export function sessionListCachePath() {
+    return join(crtrHome(), 'session-list-cache.json');
+}
+const MAX_NODE_ID_BYTES = 128;
+/** Whether a persisted node ID is safe as a single filesystem path segment. */
+export function isSafeNodeId(nodeId) {
+    return typeof nodeId === 'string'
+        && nodeId !== ''
+        && nodeId !== '.'
+        && nodeId !== '..'
+        && !/[\\/\0]/u.test(nodeId)
+        && Buffer.byteLength(nodeId, 'utf8') <= MAX_NODE_ID_BYTES;
+}
+function assertSafeNodeId(nodeId) {
+    if (!isSafeNodeId(nodeId)) {
+        throw new TypeError('node_id must be a non-empty path segment of at most 128 UTF-8 bytes');
+    }
+}
+export function nodeDir(nodeId) {
+    assertSafeNodeId(nodeId);
+    return join(nodesRoot(), nodeId);
+}
+export function contextDir(nodeId) {
+    return join(nodeDir(nodeId), 'context');
+}
+/** Replace the literal env-var tokens `$CRTR_CONTEXT_DIR` / `$CRTR_NODE_ID` in
+ *  agent-facing doc text with the node's real values, so a doc surfaced INTO a
+ *  node hands it a concrete absolute path instead of a shell-only string. The
+ *  env vars only expand in bash; an agent that pastes `$CRTR_CONTEXT_DIR/x.md`
+ *  into the (non-expanding) Write tool creates a literal `$CRTR_CONTEXT_DIR/`
+ *  dir under the project repo. The resolved absolute path works in both bash and
+ *  Write, so this substitution is strictly safer. Callers must only apply it
+ *  when they have a concrete node to render for (never on generic, node-less
+ *  output). Pure string work — no I/O. */
+export function interpolateNodePaths(text, nodeId) {
+    return text
+        .replaceAll('$CRTR_CONTEXT_DIR', contextDir(nodeId))
+        .replaceAll('$CRTR_NODE_ID', nodeId);
+}
+export function jobDir(nodeId) {
+    return join(nodeDir(nodeId), 'job');
+}
+export function reportsDir(nodeId) {
+    return join(nodeDir(nodeId), 'reports');
+}
+/** Overflow store for inbox entries whose inline body exceeds the digest's
+ *  bounded preview (a direct `node message send` or a close/cancel doctrine
+ *  wake) — the full body spills here, mirroring how a
+ *  push's body always lives in a file, never inline; the inbox entry then
+ *  carries `ref` at this path, same as a push pointer. */
+export function messagesDir(nodeId) {
+    return join(nodeDir(nodeId), 'messages');
+}
+export function nodeMetaPath(nodeId) {
+    return join(nodeDir(nodeId), 'meta.json');
+}
+export function inboxPath(nodeId) {
+    return join(nodeDir(nodeId), 'inbox.jsonl');
+}
+/** The node-owned ambient "current situation" sidecar — the latest hidden
+ *  `<situational-context>` text injected into bearings/kickoff (see
+ *  `runtime/situational-context.ts`), upserted in place rather than appended so
+ *  only the newest applet/situation state is ever carried. Lives beside
+ *  meta.json/inbox.jsonl (node-runtime state) rather than under context/ (the
+ *  user-authored artifact store), because it is ambient machine state, not a
+ *  document a human wrote. */
+export function situationalContextPath(nodeId) {
+    return join(nodeDir(nodeId), 'situational-context.md');
+}
+/** Passive-subscription accumulator. Pushes from publishers this node subscribes
+ *  to PASSIVELY land here instead of inbox.jsonl — the inbox-watcher never polls
+ *  it, so they never wake the node. Drained as XML pre-text on the next message. */
+export function passivePath(nodeId) {
+    return join(nodeDir(nodeId), 'passive.jsonl');
+}
+export function transcriptPath(nodeId) {
+    return join(nodeDir(nodeId), 'transcript.jsonl');
+}
+export function sessionPtrPath(nodeId) {
+    return join(nodeDir(nodeId), 'session.ptr');
+}
+/** On-read injection dedup set — the doc realpaths already surfaced on-read in
+ *  this node's CURRENT conversation transcript. Persisted so the once-per-
+ *  transcript dedup survives a dormancy → revive(resume) cycle: a resume reuses
+ *  the same .jsonl transcript in a NEW pi process, so the in-memory set would
+ *  otherwise start empty and re-inject docs already present in the transcript.
+ *  Deleted by the launch paths that start a FRESH transcript. */
+export function injectedDocsPath(nodeId) {
+    return join(nodeDir(nodeId), 'injected-docs.json');
+}
+/** Create the full directory skeleton for a node. Idempotent. */
+export function ensureNodeDirs(nodeId) {
+    for (const d of [contextDir(nodeId), jobDir(nodeId), reportsDir(nodeId)]) {
+        mkdirSync(d, { recursive: true });
+    }
+}
+/** Ensure the canvas home exists. Idempotent. */
+export function ensureHome() {
+    mkdirSync(nodesRoot(), { recursive: true });
+}

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

@@ -0,0 +1,335 @@
+/** True if a process with `pid` is currently alive (signal-0 probe) AND not a
+ *  zombie. `kill(pid, 0)` throws ESRCH when the process is gone; EPERM means
+ *  it exists but isn't ours — still alive (a foreign process is never OUR
+ *  zombie, so the `isZombie` check is skipped for that branch — see below). A
+ *  null/undefined pid (legacy / never-booted) reads dead.
+ *
+ *  The zombie check matters because EVERY broker this module supervises is
+ *  spawned `detached: true` by crtr itself (`headlessBrokerHost.launch`) — a
+ *  dead broker whose spawning process hasn't reaped it yet is a zombie, and
+ *  `kill(pid, 0)` alone reports it as alive, wedging the daemon's revive guard
+ *  (`isPidAlive(pi_pid)`, `revive.ts`) forever: the daemon never revives an
+ *  already-live-looking row, so a refreshed/crashed node whose broker zombied
+ *  out under a long-lived spawning process (see `isZombie`'s doc) never comes
+ *  back on its own. */
+export declare function isPidAlive(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 (review Major #1, Round 2 of the pid-reuse-liveness
+ *  fix).
+ *
+ *  Two hazards this closes, both in the false-DEAD direction (the dangerous
+ *  one — a false DEAD lets `reviveNode`'s double-launch guard relaunch a
+ *  SECOND broker onto a still-live session):
+ *
+ *  1. `composeIdentity` appends the `#<ticks>` Linux discriminator only when
+ *     `/proc/<pid>/stat` happens to be readable at capture time — so the SAME
+ *     live process can be recorded plain `lstart` on one capture and
+ *     `lstart#ticks` on another (a transient `/proc` read failure, or
+ *     capturing on a platform/container without procfs). A naive `===` reads
+ *     that as a reuse (different string) and reports `dead` for a broker that
+ *     never died.
+ *  2. `lstart` is NOT stable for a live process on every host. It is derived
+ *     from `/proc/stat` btime (wall-clock boot epoch) + starttime jiffies, so
+ *     a clock correction / suspend-resume shifts btime and re-anchors the
+ *     SAME live process's `lstart` by seconds between two captures. Observed
+ *     on Blaxel unikraft guests: pid+ticks identical across probes, `lstart`
+ *     drifting +81s — a base-first compare then reads the live home-node
+ *     broker as reused/dead every cycle, driving an uncapped revive loop.
+ *
+ *  A third hazard the base itself once carried: `ticks` (jiffies-since-boot)
+ *  RESET on every boot and can repeat across boots, so ticks-alone is only
+ *  safe WITHIN one boot. `composeIdentity` therefore boot-SCOPES the base on
+ *  Linux-with-procfs — the base IS the kernel `boot_id` UUID — so a
+ *  new-format identity is `<bootId>#<ticks>` and equality means same boot AND
+ *  same process. This closes the cross-boot false match at the root, without
+ *  plumbing boot reconciliation ahead of every caller.
+ *
+ *  Rule: split both on `#`.
+ *   - BOTH sides carry `#ticks` AND both bases are `boot_id` UUIDs
+ *     (new-format vs new-format): match iff base AND ticks are equal. A
+ *     different boot_id with equal ticks is NOT a match (the cross-boot
+ *     collision).
+ *   - BOTH sides carry `#ticks` but a base is NOT a boot_id UUID on EITHER
+ *     side — a LEGACY `lstart#ticks` row recorded before this repo boot-scoped
+ *     the base, or a Linux host that has procfs ticks but no readable boot_id:
+ *     ticks DECIDE it alone (the prior landed semantics). This is a NARROW
+ *     format-migration path so an in-place upgrade never false-kills a live
+ *     broker whose row still holds `lstart#ticks`; it is NOT a general
+ *     fallback — new-format vs new-format always demands base+ticks above.
+ *   - EITHER side lacks a valid `#ticks` suffix (macOS / no procfs / transient
+ *     `/proc` miss / malformed suffix): fall back to the coarse base —
+ *     matching iff the bases agree (fail-open to same-process, matching this
+ *     module's universal discipline: only a POSITIVE mismatch counts as reuse,
+ *     never an absence of evidence). */
+export 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 (review nit, crouter#98): 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;
+/** Every transitive descendant of `rootPid`, discovered by walking `ps`'s
+ *  pid/ppid table (BFS) — NOT process-GROUP membership. This is the fix for
+ *  crouton-labs/crouter#98: the pi SDK's bash tool spawns its shell child with
+ *  `detached: true` (verified in `@earendil-works/pi-agent-core`'s
+ *  `harness/env/nodejs.js`), which calls `setsid()` and puts that child in a
+ *  brand-new process GROUP of its own — so `kill(-rootPid)` never reaches it.
+ *  `setsid()` changes only SID/PGID, NEVER ppid, so the child (and its own
+ *  descendants) is still discoverable by walking parentage from `rootPid`, as
+ *  long as `rootPid`'s OS process is still alive when we walk (a fully-dead
+ *  parent is reparented away by the kernel immediately on exit, severing this
+ *  link — the wedged-but-alive broker this fix targets never hits that). Best-
+ *  effort: returns `[]` (never throws) on any `ps` failure, exactly like
+ *  `killProcessGroup`'s ESRCH-swallowing. */
+export 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 (crouter#98 review finding 3): a
+ *  captured pid can exit and the OS can recycle it for an unrelated process
+ *  before the SIGKILL rung fires, and a bare `kill(pid, 0)` / `kill(pid, sig)`
+ *  cannot tell the difference.
+ *
+ *  Returns `null` — NOT an empty map — when the `ps` PROBE ITSELF failed (it
+ *  could not be spawned, or was killed by the timeout): a probe failure means
+ *  we have NO information, which is a fundamentally different outcome from a
+ *  probe that SUCCEEDED and simply found no row for a given pid (that pid is
+ *  genuinely gone). Collapsing these two into the same empty map was the
+ *  final-review bug (crouter#98 signal-safety finding): `killProcessTreePids`
+ *  cannot tell "pid confirmed gone" from "we don't know" without this
+ *  distinction, and misreading a failed probe as positive proof of
+ *  absence/reuse either signals a reused stranger or — worse — silently skips
+ *  reaping a real live orphan. A successful call may still return a map with
+ *  no entry for some/all of `pids` (those pids have no current row — genuinely
+ *  gone); that is the valid empty-or-partial case and is NOT a failure.
+ *
+ *  EXIT STATUS IS NOT THE FAILURE SIGNAL. `ps` exits 1 — on BOTH BSD ps and
+ *  procps-ng — when it matched no process at all, which is precisely the
+ *  "probe succeeded, that pid is gone" case, and exits 1 with PARTIAL stdout
+ *  when only some of a batch's pids still exist. Reading a non-zero exit as a
+ *  probe failure therefore turned every confirmed-dead pid into
+ *  `'indeterminate'` (`recordedPidLiveness`), so a just-killed broker read as
+ *  "can't confirm" — never as dead. Callers that fail open on indeterminate
+ *  (`ensureAttach`'s revive decision, the daemon's exit policy) then treat a
+ *  dead broker as live forever. Discriminate on whether the PROCESS RAN
+ *  (`r.error`/`r.signal`) and whether it complained (`stderr`), never on what
+ *  it exited with: a real argument/usage failure writes a diagnostic to stderr
+ *  (`ps: process id too large`), while "matched nothing" is silent. */
+export 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 (crouter#98 final review, Fix 1): 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): 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, crouton-labs/crouter#98)
+ *  PLUS a plain `kill(pid)` on each (belt-and-suspenders for a pid that is
+ *  NOT its own group leader). Every signal is best-effort — `killProcessGroup`
+ *  swallows ESRCH and the plain `kill` here does too — so firing this against
+ *  an already-fully-dead snapshot is a harmless no-op.
+ *
+ *  `identities`, when supplied (crouter#98 review finding 3), is a
+ *  `capturePidIdentities` snapshot taken alongside the pid list at the SAME
+ *  moment — `null` if that INITIAL capture's `ps` probe itself failed (see
+ *  `capturePidIdentities`'s doc). Before signaling EITHER the group or the
+ *  plain kill for a pid, this re-derives CURRENT identities in one fresh
+ *  batched call and compares — but ONLY skips on POSITIVE proof of reuse; any
+ *  failure or absence of evidence falls through to the normal signal path
+ *  (fail-open, matching this module's pre-guard behavior — final review,
+ *  crouter#98 signal-safety finding):
+ *
+ *    - baseline identity present AND the current probe SUCCEEDED AND the
+ *      current identity for this pid is present AND DIFFERENT — the OS has
+ *      recycled this pid for an unrelated process since the snapshot — SKIP
+ *      (the sole skip condition; this is the actual reused-pid hazard finding
+ *      3 targets).
+ *    - baseline identity present but the pid is now simply GONE (current
+ *      probe succeeded, no row for this pid) — it died naturally in the
+ *      meantime, not reused — SIGNAL as normal (harmless no-op on the plain
+ *      kill; load-bearing for the group kill, which can still reach a
+ *      surviving process that shares this now-dead pid's process GROUP).
+ *    - baseline had NO identity at all for this pid (the pid was ALREADY dead
+ *      at snapshot time — e.g. a broker that crashed before `teardown()` ever
+ *      ran) — SIGNAL as normal regardless of the current probe: this is
+ *      exactly how `killProcessGroup` on an already-dead root still reaches a
+ *      live process sharing its process group (the pgid persists after the
+ *      group leader exits; see `host-teardown-process-group.test.ts`'s "dead
+ *      broker" case).
+ *    - the INITIAL capture's probe failed outright (`identities === null`) —
+ *      we have NO baseline to compare against for ANY pid — SIGNAL as normal
+ *      for the whole list; the CURRENT probe is not even attempted (nothing
+ *      to compare it to).
+ *    - the baseline succeeded but the CURRENT probe (taken here) fails — we
+ *      have NO current information — SIGNAL as normal for the whole list; a
+ *      failed probe must never be read as "gone" (would risk reaching a
+ *      reused stranger, the residual risk this guard cannot close) NOR as
+ *      "reused" (would wrongly disable the reap for every real live pid).
+ *
+ *  Callers that omit `identities` entirely (pre-existing call sites) keep the
+ *  prior unguarded behavior. */
+export 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;