@crouton-kit/crouter 0.3.65 → 0.3.67

package/dist/core/canvas/browse/app.js

@@ -11,9 +11,11 @@ import { execFileSync } from 'node:child_process';
 import { resolve } from 'node:path';
 import { dashboardRowsAllFromSource, enrichRowsFromSource, loadPreviewFromSource, renderForestFromSource } from '../render.js';
 import { localCanvasSource } from '../source.js';
+import { RemoteCanvasSource } from '../remote-canvas-source.js';
 import { closeNode } from '../../runtime/close.js';
 import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress, } from '../../tui/terminal.js';
 import { buildTree, flatten, pruneNode, TABS } from './model.js';
+import { createCoalescedRebuilder } from './rebuild-coalescer.js';
 // Sort cycle for the `s` key. Starts on the default `attention` ordering; one `s`
 // press restores the structural `tree` view, then relevance/recency, then back.
 const SORT_CYCLE = ['attention', 'tree', 'relevance', 'recency'];
@@ -26,8 +28,22 @@ function viewportHeight(rowsTotal, search, previewOn) {
     const previewH = previewOn ? PREVIEW_HEIGHT : 0;
     return Math.max(1, rows - headerHeight(search) - 1 /* footer */ - previewH);
 }
+/** Wires a RemoteEventStream's `nodes`/`inbox` events through the coalescer
+ *  (`rebuild-coalescer.ts`) so a burst of SSE events collapses to ONE rebuild
+ *  round, never one N+1 remote-subprocess rebuild per event. Exported (rather
+ *  than left inline in `runBrowse`) so the coalescer integration test can
+ *  drive this ACTUAL wiring, not just `createCoalescedRebuilder` in isolation
+ *  — the test asserts this function routes through the coalescer rather than
+ *  calling `rebuild()` directly per event. */
+export function wireEventStreamRebuild(eventStream, rebuild) {
+    const rebuilder = createCoalescedRebuilder(rebuild);
+    const unsubscribe = eventStream.subscribe(() => rebuilder.trigger());
+    eventStream.start();
+    return { rebuilder, unsubscribe };
+}
 export async function runBrowse(opts = {}) {
     const source = opts.source ?? localCanvasSource;
+    const isRemote = source instanceof RemoteCanvasSource;
     // No TTY → print the static forest and exit 0 (no raw mode).
     if (!process.stdin.isTTY) {
         process.stdout.write(await renderForestFromSource(source) + '\n');
@@ -35,18 +51,41 @@ export async function runBrowse(opts = {}) {
     }
     // Snapshot the canvas. Drop kind:'human' control-plane decks — they have no pi
     // session, so `node focus` refuses them; they are never a navigation/resume
-    // target (mirrors the node focus guard).
-    const rows = (await dashboardRowsAllFromSource(source)).filter((r) => r.kind !== 'human');
-    const nodeRows = await source.listNodes();
-    const rootIds = nodeRows
-        .filter((n) => n.parent === null && n.kind !== 'human')
-        .map((n) => n.node_id);
-    const childIds = new Map();
-    await Promise.all(nodeRows.map(async (n) => {
-        childIds.set(n.node_id, (await source.subscriptionsOf(n.node_id).catch(() => [])).map((s) => s.node_id));
-    }));
-    const tree = buildTree(rows, rootIds, (id) => childIds.get(id) ?? []);
-    const totalNodes = tree.nodes.size;
+    // target (mirrors the node focus guard). Factored into a function so the SSE
+    // listener below can re-pull the tree on a `nodes`/`inbox` event instead of
+    // recomputing over a stale snapshot.
+    let rows;
+    let nodeRows;
+    let rootIds;
+    let childIds;
+    let tree;
+    let totalNodes;
+    // Remote-only: pending-ask counts per node, merged from one
+    // `askCountsForView` call per forest root (RemoteCanvasSource.askCountsForView
+    // already shells a single `canvas attention map --view <root>` per root, same
+    // cost class as the per-node `subscriptionsOf` fan-out this snapshot already
+    // does below) — fetched once per snapshot rebuild, not per flush/keystroke, so
+    // enrichRowsFromSource's per-row loop stays a pure sync-shaped map lookup.
+    let remoteAskCounts = {};
+    const rebuildSnapshot = async () => {
+        rows = (await dashboardRowsAllFromSource(source)).filter((r) => r.kind !== 'human');
+        nodeRows = await source.listNodes();
+        rootIds = nodeRows
+            .filter((n) => n.parent === null && n.kind !== 'human')
+            .map((n) => n.node_id);
+        const nextChildIds = new Map();
+        await Promise.all(nodeRows.map(async (n) => {
+            nextChildIds.set(n.node_id, (await source.subscriptionsOf(n.node_id).catch(() => [])).map((s) => s.node_id));
+        }));
+        childIds = nextChildIds;
+        tree = buildTree(rows, rootIds, (id) => childIds.get(id) ?? []);
+        totalNodes = tree.nodes.size;
+        if (isRemote) {
+            const maps = await Promise.all(rootIds.map((root) => source.askCountsForView(root).catch(() => ({}))));
+            remoteAskCounts = Object.assign({}, ...maps);
+        }
+    };
+    await rebuildSnapshot();
     // Default cwd scope = the dir browse was launched from (the request). The popup
     // / command passes --cwd; resolve it so it compares cleanly against stored cwds.
     // null when unknown → All dirs (the toggle's other state).
@@ -82,10 +121,43 @@ export async function runBrowse(opts = {}) {
             restoreTerminal();
         }
         catch { /* best-effort */ }
+        unsubscribeEventStream?.();
+        rebuilder?.stop();
+        opts.eventStream?.stop();
     };
     // Safety net: an uncaught throw in the (un-unit-tested) keystroke path must
     // never strand the tty in raw + alt-screen + hidden-cursor.
     process.once('exit', cleanup);
+    // Remote-only live invalidation: `canvas browse` has no local fs-watch/poll to
+    // replace (there is none — this is a one-shot snapshot TUI, re-rendering only
+    // on keystrokes). This is net-new plumbing for the remote case only: when a
+    // pre-built RemoteEventStream is threaded in (canvas-browse.ts, once it has
+    // already resolved the target's credentials), a `nodes`/`inbox` SSE event
+    // invalidates the remote source's cache and triggers the same recompute +
+    // coalesced repaint a keystroke would. The local (no eventStream) path is
+    // untouched.
+    let unsubscribeEventStream;
+    let rebuilder;
+    if (opts.eventStream !== undefined) {
+        if (source instanceof RemoteCanvasSource)
+            source.invalidate();
+        // `trigger()` debounces a burst into one rebuild, and single-flights it
+        // against an already-in-flight rebuild — see wireEventStreamRebuild above.
+        const wired = wireEventStreamRebuild(opts.eventStream, async () => {
+            try {
+                if (source instanceof RemoteCanvasSource)
+                    source.invalidate();
+                await rebuildSnapshot();
+                recompute(curRow()?.id);
+                scheduleFlush();
+            }
+            catch (err) {
+                logAsyncFailure('SSE rebuild failed', err);
+            }
+        });
+        rebuilder = wired.rebuilder;
+        unsubscribeEventStream = wired.unsubscribe;
+    }
     const logAsyncFailure = (label, err) => {
         process.stderr.write(`[crtr browse] ${label}: ${String(err?.message ?? err)}\n`);
     };
@@ -154,7 +226,7 @@ export async function runBrowse(opts = {}) {
             if (r !== undefined)
                 slice.push(r);
         }
-        await enrichRowsFromSource(source, slice);
+        await enrichRowsFromSource(source, slice, remoteAskCounts);
         const cur = curRow();
         if (cur !== undefined) {
             const r = rowOf(cur.id);
@@ -166,6 +238,7 @@ export async function runBrowse(opts = {}) {
             query: state.query, search: state.search, totalNodes,
             cwdScope: state.cwdScope, sort: state.sort, preview: state.preview,
             residentsOnly: state.residentsOnly, pendingClose: state.pendingClose,
+            readOnly: isRemote,
         }, size, caps);
         process.stdout.write(frame);
     };
@@ -459,7 +532,10 @@ export async function runBrowse(opts = {}) {
         }
         // Close-out the selected node (+ its exclusive subtree). If anything in that
         // subtree is actively streaming, confirm first (y/n); otherwise close at once.
+        // No-op against a remote canvas — mutations are disabled (footer says so).
         if (input === 'x') {
+            if (isRemote)
+                return;
             if (row === undefined) {
                 scheduleFlush();
                 return;
@@ -510,7 +586,10 @@ export async function runBrowse(opts = {}) {
         // waiting out the 5-min auto-revive grace. Shells `node lifecycle revive <id>
         // --now` (browse goes through commands, never touching the runtime directly). 'k' is
         // vim-up here, so the kick is on SHIFT-K.
+        // No-op against a remote canvas — mutations are disabled (footer says so).
         if (input === 'K') {
+            if (isRemote)
+                return;
             if (row !== undefined) {
                 const r = rowOf(row.id);
                 if (r?.hanging != null)
@@ -519,8 +598,11 @@ export async function runBrowse(opts = {}) {
             scheduleFlush();
             return;
         }
-        // Resume.
+        // Resume. No-op against a remote canvas — mutations/focus are disabled
+        // (footer says so).
         if (key.return) {
+            if (isRemote)
+                return;
             if (row !== undefined)
                 selectAndFocus(row.id);
             return;
@@ -566,7 +648,7 @@ export async function runBrowse(opts = {}) {
             return;
         const end = Math.min(warmIdx + WARM_CHUNK, warmRows.length);
         const slice = warmRows.slice(warmIdx, end);
-        await enrichRowsFromSource(source, slice);
+        await enrichRowsFromSource(source, slice, remoteAskCounts);
         await Promise.all(slice.map((r) => loadPreviewFromSource(source, r)));
         warmIdx = end;
         // A live search may match the freshly-warmed prompts → recompute + repaint.

package/dist/core/canvas/browse/rebuild-coalescer.d.ts

@@ -0,0 +1,7 @@
+export interface CoalescedRebuilder {
+    /** Called on every SSE event. Cheap — only schedules/marks work. */
+    trigger: () => void;
+    /** Cancels any pending debounce timer (does not abort an in-flight rebuild). */
+    stop: () => void;
+}
+export declare function createCoalescedRebuilder(rebuild: () => Promise<void>, debounceMs?: number): CoalescedRebuilder;

package/dist/core/canvas/browse/rebuild-coalescer.js

@@ -0,0 +1,61 @@
+// rebuild-coalescer.ts — single-flight + debounce coalescing for a burst of
+// SSE-triggered rebuilds (`canvas browse`'s remote path — see app.ts).
+//
+// A remote `RemoteEventStream` `nodes`/`inbox` event means "invalidate + re-pull
+// the tree", which for a remote source costs one `node inspect list` plus N
+// `node inspect show` round trips. A burst of events (several nodes changing at
+// once) must NOT fan into one overlapping rebuild per event — it must collapse
+// to one rebuild per burst. This module is the pure, TTY-free coalescing policy
+// so it can be unit-tested without the raw-mode stdin loop in app.ts:
+//
+//   - `trigger()` debounces a burst into ONE rebuild call after `debounceMs` of
+//     quiet.
+//   - if a rebuild is already in flight when the debounce fires (or another
+//     trigger lands mid-rebuild), it does NOT launch an overlapping rebuild —
+//     it marks exactly one trailing rebuild to run immediately after the
+//     in-flight one finishes.
+//
+// Net effect: N events in a burst → 1 rebuild (or, if the burst spans an
+// in-flight rebuild, 2: the one already running + one trailing catch-up) —
+// never N overlapping rebuilds.
+export function createCoalescedRebuilder(rebuild, debounceMs = 200) {
+    let timer;
+    let inFlight = false;
+    let pending = false;
+    const run = () => {
+        inFlight = true;
+        void rebuild().finally(() => {
+            inFlight = false;
+            if (pending) {
+                // A trailing catch-up was armed while this rebuild ran — fire it
+                // immediately (no further debounce: the just-finished rebuild WAS the
+                // quiet period), collapsing every event that landed mid-flight into
+                // exactly one follow-up rebuild, not one per event.
+                pending = false;
+                run();
+            }
+        });
+    };
+    const trigger = () => {
+        if (inFlight) {
+            // Already rebuilding — mark one trailing catch-up instead of starting a
+            // second overlapping rebuild or re-arming the debounce timer (which
+            // would keep pushing the catch-up back on every further event).
+            pending = true;
+            return;
+        }
+        if (timer !== undefined)
+            return; // already debounced in this quiet window
+        timer = setTimeout(() => {
+            timer = undefined;
+            run();
+        }, debounceMs);
+    };
+    const stop = () => {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+    };
+    return { trigger, stop };
+}

package/dist/core/canvas/browse/render.d.ts

@@ -29,6 +29,10 @@ export interface RenderState {
      *  a descendant) is actively streaming. Holds the node id being confirmed; the
      *  footer becomes the y/n prompt. null/undefined = no pending confirm. */
     pendingClose?: string | null;
+    /** Set when the source is a remote canvas: mutation/focus keys (`x`/`K`/Enter)
+     *  are disabled, so the footer drops their hints instead of advertising a
+     *  dead action. undefined/false = local, byte-identical footer. */
+    readOnly?: boolean;
 }
 /**
  * Render the whole frame. Returns a single string that, written as-is, repaints

package/dist/core/canvas/browse/render.js

@@ -479,7 +479,9 @@ export function renderFrame(state, size, caps = { color: false, color256: false
         const hangingHint = cursorRow?.hanging != null ? 'K revive now  ' : '';
         const footer = state.search
             ? '⏎ commit  Esc cancel  ⌫ delete'
-            : `${hangingHint}↑↓ move  →/← tree  ⏎ resume  x close  Tab tabs  / search  s sort  c cwd  r residents  p preview  q quit`;
+            : state.readOnly === true
+                ? '↑↓ move  →/← tree  Tab tabs  / search  s sort  c cwd  r residents  p preview  q quit  — read-only remote canvas'
+                : `${hangingHint}↑↓ move  →/← tree  ⏎ resume  x close  Tab tabs  / search  s sort  c cwd  r residents  p preview  q quit`;
         lines.push(`${DIM}${clip(footer, width)}${RESET}`);
     }
     // Assemble: home, each line cleared to EOL, then clear below.

package/dist/core/canvas/nav-model.d.ts

@@ -19,8 +19,10 @@ export declare const YELLOW = "\u001B[33m";
 export declare const CYAN = "\u001B[36m";
 export declare const GRAY = "\u001B[90m";
 /** Overlay-aware glyph for a node: hanging ⚠ outranks streaming ⟳, which
- *  outranks the base status glyph. */
-export declare function nodeGlyph(node: NodeMeta | null): string;
+ *  outranks the base status glyph. `remote` skips the local `readFault` /
+ *  `isPidAlive` / `isBusy` reads entirely (a remote node id may collide with a
+ *  local one) and renders the bare status glyph instead. */
+export declare function nodeGlyph(node: NodeMeta | null, remote?: boolean): string;
 /** Visible width, ignoring ANSI escapes. */
 export declare function visibleWidth(s: string): number;
 /** Truncate to `max` VISIBLE columns: escape sequences are copied through
@@ -59,11 +61,14 @@ export interface Telemetry {
 export declare function readTelemetry(nodeId: string): Telemetry;
 export declare function fmtTokens(n: number): string;
 /** The context-window cell — live window fill rounded to the nearest 1k (the same
- *  figure pi's footer shows), NOT a per-turn token delta. */
-export declare function tokensCell(id: string): string;
+ *  figure pi's footer shows), NOT a per-turn token delta. `remote` skips the local
+ *  `telemetry.json` read entirely and reports 0 (a remote node id may collide
+ *  with a local one). */
+export declare function tokensCell(id: string, remote?: boolean): string;
 /** Dimmed live "what is it doing" cue for an ACTIVE node — the last tool it ran.
- *  Empty for non-active rows (stale once a node parks) and when none is recorded. */
-export declare function activityCell(id: string, node: NodeMeta | null): string;
+ *  Empty for non-active rows (stale once a node parks) and when none is recorded.
+ *  `remote` skips the local `telemetry.json` read entirely and reports empty. */
+export declare function activityCell(id: string, node: NodeMeta | null, remote?: boolean): string;
 /** Revive-count badge (meta.cycles). Hidden on the first cycle (0) to cut noise. */
 export declare function cycleBadge(node: NodeMeta | null): string;
 /** Short on-screen label: the explicit handle when set, else the pi-generated
@@ -71,10 +76,14 @@ export declare function cycleBadge(node: NodeMeta | null): string;
  *  the nav chrome shows just the first so rows stay compact. */
 export declare function navLabel(node: NodeMeta | null, id: string): string;
 export declare function shortId(id: string): string;
-/** Node ids currently shown in a tmux focus viewport. Built once per render. */
-export declare function focusedNodeIds(): Set<string>;
-/** True when a human is watching `id` right now (tmux focus or broker viewer). */
-export declare function isAttached(id: string, node: NodeMeta | null, focused: ReadonlySet<string>): boolean;
+/** Node ids currently shown in a tmux focus viewport. Built once per render.
+ *  `remote` skips the local `listFocuses()` SQLite read entirely and reports
+ *  none focused (a remote node id may collide with a local one). */
+export declare function focusedNodeIds(remote?: boolean): Set<string>;
+/** True when a human is watching `id` right now (tmux focus or broker viewer).
+ *  `remote` skips the local `attach.json` read entirely and reports false (a
+ *  remote node id may collide with a local one). */
+export declare function isAttached(id: string, node: NodeMeta | null, focused: ReadonlySet<string>, remote?: boolean): boolean;
 export declare function fetchAsksMap(rootId: string): Record<string, number>;
 /** First manager (by created) — the UP step for the ancestry spine. */
 export declare function managerOf(id: string): string | undefined;

package/dist/core/canvas/nav-model.js

@@ -63,11 +63,16 @@ function streamingFor(node) {
     return isBusy(node.node_id);
 }
 /** Overlay-aware glyph for a node: hanging ⚠ outranks streaming ⟳, which
- *  outranks the base status glyph. */
-export function nodeGlyph(node) {
+ *  outranks the base status glyph. `remote` skips the local `readFault` /
+ *  `isPidAlive` / `isBusy` reads entirely (a remote node id may collide with a
+ *  local one) and renders the bare status glyph instead. */
+export function nodeGlyph(node, remote = false) {
     if (node === null)
         return '?';
-    const v = resolveNodeVisual(node.status, { streaming: streamingFor(node), hanging: hangingFor(node) });
+    const v = resolveNodeVisual(node.status, {
+        streaming: remote ? false : streamingFor(node),
+        hanging: remote ? null : hangingFor(node),
+    });
     return `${ESC}${v.color}m${v.glyph}${RESET}`;
 }
 const ANSI_RE = /\x1b\[[0-9;]*m/g;
@@ -205,13 +210,18 @@ export function fmtTokens(n) {
     return n < 1_000 ? `${n}` : `${Math.round(n / 1_000)}k`;
 }
 /** The context-window cell — live window fill rounded to the nearest 1k (the same
- *  figure pi's footer shows), NOT a per-turn token delta. */
-export function tokensCell(id) {
-    return fmtTokens(readTelemetry(id).context_tokens ?? 0);
+ *  figure pi's footer shows), NOT a per-turn token delta. `remote` skips the local
+ *  `telemetry.json` read entirely and reports 0 (a remote node id may collide
+ *  with a local one). */
+export function tokensCell(id, remote = false) {
+    return fmtTokens(remote ? 0 : (readTelemetry(id).context_tokens ?? 0));
 }
 /** Dimmed live "what is it doing" cue for an ACTIVE node — the last tool it ran.
- *  Empty for non-active rows (stale once a node parks) and when none is recorded. */
-export function activityCell(id, node) {
+ *  Empty for non-active rows (stale once a node parks) and when none is recorded.
+ *  `remote` skips the local `telemetry.json` read entirely and reports empty. */
+export function activityCell(id, node, remote = false) {
+    if (remote)
+        return '';
     if (node?.status !== 'active')
         return '';
     const a = (readTelemetry(id).last_activity ?? '').trim();
@@ -248,8 +258,12 @@ export function shortId(id) {
 //                 (src/core/runtime/broker.ts). Trusted only while the node is
 //                 'active': a broker crash can leave a stale file.
 // ---------------------------------------------------------------------------
-/** Node ids currently shown in a tmux focus viewport. Built once per render. */
-export function focusedNodeIds() {
+/** Node ids currently shown in a tmux focus viewport. Built once per render.
+ *  `remote` skips the local `listFocuses()` SQLite read entirely and reports
+ *  none focused (a remote node id may collide with a local one). */
+export function focusedNodeIds(remote = false) {
+    if (remote)
+        return new Set();
     try {
         return new Set(listFocuses().map((f) => f.node_id));
     }
@@ -257,8 +271,12 @@ export function focusedNodeIds() {
         return new Set();
     }
 }
-/** True when a human is watching `id` right now (tmux focus or broker viewer). */
-export function isAttached(id, node, focused) {
+/** True when a human is watching `id` right now (tmux focus or broker viewer).
+ *  `remote` skips the local `attach.json` read entirely and reports false (a
+ *  remote node id may collide with a local one). */
+export function isAttached(id, node, focused, remote = false) {
+    if (remote)
+        return false;
     if (focused.has(id))
         return true;
     if (node?.status !== 'active')

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

@@ -13,19 +13,77 @@
  *  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;
-/** Like `isPidAlive`, but guards a RECORDED node pid against PID REUSE using the
- *  launch-time identity 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 after the broker
- *  dies; a bare `isPidAlive` then reports the STRANGER as "our broker alive",
- *  wedging every daemon supervise/revive decision (the daemon never revives a
- *  row that looks alive; `reviveNode`'s double-launch guard never relaunches).
- *  Returns false the instant the pid's CURRENT identity is POSITIVELY known to
- *  differ from `expectedIdentity` (the recycle case). Fail-open everywhere else
- *  — no baseline (legacy row / capture failed at launch), `ps` probe failure, or
- *  a pid present-but-unreadable — exactly matching `captureTeardownSnapshot`'s
- *  discipline: a MISMATCH is the ONLY thing that reads dead, never an absence of
- *  evidence. */
+/** 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).
+ *
+ *  The hazard this closes: `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
+ *  `===` then reads that as a reuse (different string) and reports `dead` for
+ *  a broker that never actually died — the false-DEAD direction, which can
+ *  make `reviveNode`'s double-launch guard wrongly relaunch a SECOND broker
+ *  onto a still-live session.
+ *
+ *  Rule: split both on `#`. Bases (`lstart`) differ → definitely NOT a match
+ *  (different process, or the same pid reused in a different second). Bases
+ *  match and BOTH carry a `#ticks` suffix → match iff the suffixes are equal
+ *  (this still catches genuine same-second reuse, the case `procStartTicks`
+ *  exists for). Bases match and EITHER lacks the suffix → coarse-vs-fine,
+ *  can't distinguish → MATCH (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 — see
+ *  `crtrd.ts`'s `handleNodeLiveness`). 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.
+ *
+ *  Reuses the existing primitives — this is a classification layered on top
+ *  of `isPidAlive` + `capturePidIdentities`, never a new `ps` parse:
+ *    - `!isPidAlive(pid)` → `'dead'`. Load-bearing: this is what preserves
+ *      zombie handling — `isPidAlive` already treats a gone pid AND a zombie
+ *      (SIGKILLed detached broker awaiting reap) as dead, which is the entire
+ *      reason a wedged zombie broker still gets revived. Do not bypass it.
+ *    - `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): RecordedPidLiveness;
+/** Boolean teardown-direction adapter over `recordedPidLiveness`, kept so
+ *  every pre-existing signalling caller stays behavior-identical: `dead` is
+ *  the ONLY thing that reads false. `indeterminate` (can't confirm either
+ *  way) reads true alongside `alive` — never signal a maybe-ours pid on mere
+ *  uncertainty, matching this module's universal discipline (a POSITIVE
+ *  mismatch is the only thing that changes behavior, never an absence of
+ *  evidence). Callers that need to distinguish "confirmed alive" from
+ *  "can't confirm" (e.g. a double-launch guard, where treating uncertainty as
+ *  alive risks silently skipping a needed relaunch) must call
+ *  `recordedPidLiveness` directly instead of this adapter. */
 export declare function isRecordedPidAlive(pid: number | null | undefined, expectedIdentity: string | null | undefined): boolean;
 /** SIGTERM a process GROUP by pid (the negative-pid convention) — best-effort,
  *  swallowing ESRCH (already gone). Shared by triggers.ts (cancel-time reap of