@crouton-kit/crouter 0.3.64 → 0.3.66

package/dist/clients/attach/graph-overlay.js

@@ -384,25 +384,46 @@ export class GraphOverlay {
         if (idx < 0)
             idx = Math.max(0, rows.findIndex((r) => r.id === this.self));
         const cur = rows[idx];
+        // Cycle rows (↺ back-refs) carry the SAME id as the real node they echo, so a
+        // cursor landing on one resolves back to the earlier real row on the next
+        // findIndex — the cursor snaps up and can't pass the echo. They're non-
+        // actionable (focusing re-targets the real node you can already reach), so
+        // navigation skips them: the cursor only ever rests on a unique, real row.
+        const isSelectable = (r) => r !== undefined && !r.cycle;
+        const step = (from, dir) => {
+            for (let i = from + dir; i >= 0 && i < rows.length; i += dir) {
+                if (isSelectable(rows[i]))
+                    return i;
+            }
+            return from; // no selectable row that way — hold position
+        };
+        const edge = (dir) => {
+            const start = dir === 1 ? 0 : rows.length - 1;
+            for (let i = start; i >= 0 && i < rows.length; i += dir) {
+                if (isSelectable(rows[i]))
+                    return i;
+            }
+            return idx;
+        };
         if (matchesKey(data, 'j')) {
-            idx = Math.min(rows.length - 1, idx + 1);
+            idx = step(idx, 1);
             this.cursorId = rows[idx]?.id ?? this.cursorId;
             this.tui.requestRender();
             return;
         }
         if (matchesKey(data, 'k')) {
-            idx = Math.max(0, idx - 1);
+            idx = step(idx, -1);
             this.cursorId = rows[idx]?.id ?? this.cursorId;
             this.tui.requestRender();
             return;
         }
         if (matchesKey(data, 'g')) {
-            this.cursorId = rows[0]?.id ?? this.cursorId;
+            this.cursorId = rows[edge(1)]?.id ?? this.cursorId;
             this.tui.requestRender();
             return;
         }
         if (matchesKey(data, 'shift+g')) {
-            this.cursorId = rows[rows.length - 1]?.id ?? this.cursorId;
+            this.cursorId = rows[edge(-1)]?.id ?? this.cursorId;
             this.tui.requestRender();
             return;
         }

package/dist/commands/node-lifecycle-revive.js

@@ -20,7 +20,7 @@ import { InputError } from '../core/io.js';
 import { reviveNode } from '../core/runtime/revive.js';
 import { waitForBrokerViewSocket } from '../core/runtime/placement.js';
 import { getNode, fullName } from '../core/canvas/index.js';
-import { isPidAlive } from '../core/canvas/pid.js';
+import { recordedPidLiveness } from '../core/canvas/pid.js';
 import { readFault } from '../core/runtime/fault.js';
 import { isBusy } from '../core/runtime/busy.js';
 import { faultNeedsYou } from '../core/canvas/status-glyph.js';
@@ -114,7 +114,14 @@ export const nodeReviveLeaf = defineLeaf({
         if (now) {
             const pid = meta.pi_pid;
             const stall = readFault(nodeId);
-            if (pid == null || !isPidAlive(pid)) {
+            // Identity-aware AND requires CONFIRMED alive — --now's whole job is to
+            // SIGTERM this pid, so a bare isPidAlive risks signalling a STRANGER
+            // process that reused a dead broker's recycled pid. `dead` (including a
+            // positively confirmed reuse) correctly refuses here. `indeterminate`
+            // (can't confirm identity either way, e.g. a transient `ps` probe
+            // failure) ALSO refuses — only a positively confirmed-alive-and-ours pid
+            // is ever signaled by this command.
+            if (pid == null || recordedPidLiveness(pid, meta.pi_pid_identity) !== 'alive') {
                 throw new InputError({
                     error: 'not_hanging',
                     message: `${nodeId} has no live broker — nothing to kick. --now is for a HANGING node (live broker parked on an active fault).`,

package/dist/core/__tests__/full/broker-crash-teardown.test.js

@@ -44,7 +44,21 @@ import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { createHarness } from '../helpers/harness.js';
 import { subscribe } from '../../canvas/canvas.js';
-import { isPidAlive } from '../../canvas/pid.js';
+import { isPidAlive, capturePidIdentities } from '../../canvas/pid.js';
+// Diagnostic-only, gated behind CRTR_DEBUG_PID_LIVENESS (same env var as the
+// isRecordedPidAlive trace in pid.ts): logs whether the SIGKILLed pid reads
+// alive and what identity ps reports for it, right at the two moments that
+// matter for the intermittent Linux-only crash-revive wedge — directly after
+// confirming the kill and again just before the grace-elapsed tick — so a real
+// run shows whether the pid was reused during the grace window. No effect on
+// test behavior when the env var is unset.
+function debugLogPidState(label, pid) {
+    if (!process.env.CRTR_DEBUG_PID_LIVENESS)
+        return;
+    const identities = capturePidIdentities([pid]);
+    const identity = identities === null ? 'probe-null' : identities.has(pid) ? JSON.stringify(identities.get(pid)) : 'no-entry';
+    process.stderr.write(`[broker-crash-teardown] ${label}: pid=${pid} isPidAlive=${isPidAlive(pid)} capturePidIdentities=${identity}\n`);
+}
 // crtrd.ts module const (not exported): the fresh-pi-boot grace window the daemon
 // waits before grace-reviving / boot-failing a pi observed dead. Reference:
 // crtrd.ts `REVIVE_GRACE_MS = 20_000`.
@@ -81,9 +95,11 @@ test('CRASH → grace-revive RESUME (one-writer), then clean teardown on close',
     // Actions run: crouter-development/prove-ci-fixes-in-actions). The waitFor's
     // successful resolution already IS the proof of deadness at this point.
     await h.waitFor(() => !isPidAlive(oldPid), { label: 'crashed broker pid is dead' });
+    debugLogPidState('after waitFor(!isPidAlive(oldPid))', oldPid);
     const NOW = 5_000_000;
     await h.tick(NOW); // pid dead, intent null → handleBrokerLiveness → handleLiveWindow marks pending
     assert.equal(h.bootCount(id), boots, 'inside the grace window → NOT yet revived');
+    debugLogPidState('before grace-elapsed tick', oldPid);
     await h.tick(NOW + REVIVE_GRACE_MS + 1); // grace elapsed → reviveNode(resume:true)
     // This is the file's SECOND real broker boot (crash-revive), on an
     // oversubscribed CI runner sharing the host with the other full-tier files'

package/dist/core/__tests__/on-read-crouter-home-fence.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/on-read-crouter-home-fence.test.js

@@ -0,0 +1,67 @@
+// The on-read POSITIONAL walk must never treat the crouter home (`~/.crouter`,
+// the user scope root) as a project ancestor. Canvas runtime artifacts live at
+// `~/.crouter/canvas/nodes/<id>/{reports,context}/...`, so a naive ancestor
+// walk from such a read climbs THROUGH `~/.crouter` and would inject whatever
+// lives at `~/.crouter/.crouter/memory/` — e.g. a differently-scoped node whose
+// cwd resolved its private project store there. That leaks one node's private
+// memory into every unrelated node that reads a canvas file. This test pins the
+// fence: reading a canvas artifact must not surface a store nested in the
+// crouter home.
+//
+// Run: node --import tsx/esm --test src/core/__tests__/on-read-crouter-home-fence.test.ts
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { closeDb } from '../canvas/db.js';
+import { resetScopeCache } from '../scope.js';
+import { spawnNode } from '../runtime/nodes.js';
+import { renderOnReadDocs } from '../substrate/on-read.js';
+let canvasHome;
+let fakeHome;
+let prevHomeEnv;
+before(() => {
+    prevHomeEnv = process.env['HOME'];
+});
+beforeEach(() => {
+    closeDb();
+    resetScopeCache();
+    // A private user HOME so `homedir()`/`userScopeRoot()` resolve into our
+    // sandbox, not the real machine.
+    fakeHome = mkdtempSync(join(tmpdir(), 'crtr-fence-home-'));
+    process.env['HOME'] = fakeHome;
+    // The node graph (canvas.db) lives in its own CRTR_HOME so spawnNode does not
+    // touch the fake user home; the read path we test is constructed by hand.
+    canvasHome = mkdtempSync(join(tmpdir(), 'crtr-fence-canvas-'));
+    process.env['CRTR_HOME'] = canvasHome;
+});
+after(() => {
+    closeDb();
+    resetScopeCache();
+    rmSync(canvasHome, { recursive: true, force: true });
+    rmSync(fakeHome, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+    if (prevHomeEnv === undefined)
+        delete process.env['HOME'];
+    else
+        process.env['HOME'] = prevHomeEnv;
+});
+test('a store nested in the crouter home does not leak into a canvas-artifact read', () => {
+    const node = spawnNode({ kind: 'general', cwd: fakeHome, parent: null }).node_id;
+    // A private store misresolved into the crouter home: `~/.crouter/.crouter/memory/`.
+    const leakedStore = join(fakeHome, '.crouter', '.crouter', 'memory');
+    mkdirSync(leakedStore, { recursive: true });
+    writeFileSync(join(leakedStore, 'private-thing.md'), '---\nkind: knowledge\n' +
+        "when-and-why-to-read: When X, read this because Y.\n" +
+        'file-read-visibility: content\n---\n' +
+        'PRIVATE ASSISTANT MEMORY MUST NOT LEAK\n');
+    // A canvas runtime artifact under the crouter home — the shape of every node
+    // report/context file the harness auto-reads.
+    const reportFile = join(fakeHome, '.crouter', 'canvas', 'nodes', 'somenode', 'reports', 'r.md');
+    mkdirSync(join(fakeHome, '.crouter', 'canvas', 'nodes', 'somenode', 'reports'), { recursive: true });
+    writeFileSync(reportFile, '# a node report\n');
+    const rendered = renderOnReadDocs(node, reportFile, new Set());
+    assert.ok(!rendered.includes('PRIVATE ASSISTANT MEMORY MUST NOT LEAK'), `crouter-home-nested store must not surface on a canvas read; got: ${rendered}`);
+    assert.ok(!rendered.includes('private-thing'), `crouter-home-nested store name must not surface on a canvas read; got: ${rendered}`);
+});

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

package/dist/core/canvas/pid.js

@@ -60,31 +60,118 @@ export function isPidAlive(pid) {
     }
     return !isZombie(pid);
 }
-/** 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. */
-export function isRecordedPidAlive(pid, expectedIdentity) {
-    if (!isPidAlive(pid))
-        return false; // gone/zombie → dead (unchanged path)
-    if (expectedIdentity == null)
-        return true; // no baseline → trust isPidAlive (legacy behavior)
+/** Split a `composeIdentity` fingerprint (`lstart` or `lstart#ticks`) into its
+ *  coarse (`lstart`, second-granular, portable) and fine (`ticks`, Linux-only
+ *  jiffies, best-effort) parts. `#` never appears in `lstart` itself (a `ps`
+ *  timestamp), so the first `#` unambiguously separates them. */
+function splitIdentity(identity) {
+    const i = identity.indexOf('#');
+    return i === -1 ? { base: identity, ticks: undefined } : { base: identity.slice(0, i), ticks: identity.slice(i + 1) };
+}
+/** 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 function identitiesMatch(a, b) {
+    const ia = splitIdentity(a);
+    const ib = splitIdentity(b);
+    if (ia.base !== ib.base)
+        return false;
+    if (ia.ticks !== undefined && ib.ticks !== undefined)
+        return ia.ticks === ib.ticks;
+    return true;
+}
+export function recordedPidLiveness(pid, expectedIdentity) {
+    const debug = Boolean(process.env.CRTR_DEBUG_PID_LIVENESS);
+    const alive = isPidAlive(pid);
+    if (!alive) {
+        if (debug)
+            logPidLivenessDecision(pid, alive, expectedIdentity, 'no-probe', 'isPidAlive=false → dead', 'dead');
+        return 'dead'; // gone/zombie → dead (unchanged path)
+    }
+    if (expectedIdentity == null) {
+        if (debug)
+            logPidLivenessDecision(pid, alive, expectedIdentity, 'no-probe', 'no baseline → trust isPidAlive', 'alive');
+        return 'alive'; // no baseline → trust isPidAlive (legacy behavior)
+    }
     const current = capturePidIdentities([pid]);
-    if (current == null)
-        return true; // probe itself failed → fail-open
+    if (current == null) {
+        if (debug)
+            logPidLivenessDecision(pid, alive, expectedIdentity, 'probe-null', 'ps probe failed → indeterminate', 'indeterminate');
+        return 'indeterminate'; // probe itself failed → we don't know (THE fix: was fail-open alive)
+    }
     const actual = current.get(pid);
-    if (actual === undefined)
-        return true; // present but no identity row (race) → fail-open
-    return actual === expectedIdentity; // different identity → REUSED → dead
+    if (actual === undefined) {
+        if (debug)
+            logPidLivenessDecision(pid, alive, expectedIdentity, 'no-entry', 'no identity row for pid (race) → dead', 'dead');
+        return 'dead'; // isPidAlive said alive but it's gone now → dead
+    }
+    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';
+}
+/** 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 function isRecordedPidAlive(pid, expectedIdentity) {
+    return recordedPidLiveness(pid, expectedIdentity) !== '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 the intermittent Linux-only CI crash-revive wedge
+ *  (`broker-crash-teardown.test.ts`'s 'CRASH → grace-revive RESUME'): the
+ *  goal is for a single stderr line per call to make BOTH a passing run ("pid
+ *  read dead → revive") and a wedged run ("read alive via <branch>") 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). Shared by triggers.ts (cancel-time reap of
@@ -294,7 +381,9 @@ export function captureTeardownSnapshot(rootPid, expectedIdentity) {
     if (table === null)
         return { tree: [rootPid], identities: null, reused: false };
     const currentRootIdentity = table.identities.get(rootPid);
-    const reused = expectedIdentity != null && currentRootIdentity !== undefined && currentRootIdentity !== expectedIdentity;
+    const reused = expectedIdentity != null &&
+        currentRootIdentity !== undefined &&
+        !identitiesMatch(currentRootIdentity, expectedIdentity);
     if (reused)
         return { tree: [], identities: null, reused: true };
     const tree = [rootPid, ...descendantPidsFrom(rootPid, table.childrenOf)];
@@ -362,7 +451,7 @@ export function killProcessTreePids(pids, signal = 'SIGTERM', identities) {
         if (identities != null && current != null) {
             const expected = identities.get(pid);
             const actual = current.get(pid);
-            const reused = expected !== undefined && actual !== undefined && actual !== expected;
+            const reused = expected !== undefined && actual !== undefined && !identitiesMatch(actual, expected);
             if (reused)
                 continue;
         }

package/dist/core/runtime/revive-all.js

@@ -13,7 +13,7 @@
 // self-guards the double-spawn. The selection predicate (`isDisconnected`) is
 // pure so the scope rules are unit-testable without booting a single process.
 import { listNodes, getNode } from '../canvas/index.js';
-import { isPidAlive } from '../canvas/pid.js';
+import { recordedPidLiveness } from '../canvas/pid.js';
 import { reviveNode } from './revive.js';
 /** Statuses a node lands in DELIBERATELY: a worker that finished its own work
  *  (`done`) or a node a human closed/reaped (`canceled`). The daemon never
@@ -56,7 +56,13 @@ export function listDisconnected() {
     const out = [];
     for (const row of listNodes()) {
         const meta = getNode(row.node_id);
-        if (meta !== null && isDisconnected(meta, isPidAlive))
+        // IDENTITY-aware AND requires CONFIRMED alive: a bare isPidAlive would
+        // misread a recycled pi_pid as "engine running" and SKIP the node, so it
+        // never reaches reviveNode's own identity-aware double-launch guard
+        // (Round 2 of the pid-reuse-liveness fix, fold-in Major). `dead` OR
+        // `indeterminate` both count as disconnected/eligible here — only a
+        // positively confirmed-alive read is treated as "still connected".
+        if (meta !== null && isDisconnected(meta, (pid) => recordedPidLiveness(pid, meta.pi_pid_identity) === 'alive'))
             out.push(meta);
     }
     return out;

package/dist/core/runtime/revive.js

@@ -29,7 +29,7 @@ import { fanDoctrineWake } from './close.js';
 import { buildPiArgv } from './launch.js';
 import { buildReviveKickoff, drainBearings } from './kickoff.js';
 import { headlessBrokerHost } from './host.js';
-import { isRecordedPidAlive } from '../canvas/pid.js';
+import { recordedPidLiveness } from '../canvas/pid.js';
 import { reconcileBootLiveness } from '../canvas/boot.js';
 import { clearFault } from './fault.js';
 import { clearInjectedDocs } from '../substrate/injected-store.js';
@@ -89,14 +89,24 @@ export function reviveNode(nodeId, opts) {
     // actually matters, so it's safe to call on every revive regardless of
     // entry point (daemon tick, or a direct/manual `node lifecycle revive`).
     reconcileBootLiveness();
-    // Double-revive guard: the broker's isAlive is identity-aware liveness on
-    // pi_pid, so a node whose broker pid is still running (and CONFIRMED to
-    // still be that same broker, not a reused pid) was already revived by
-    // another path — re-launching would put a SECOND broker on the same
-    // session file. No-op. A bare isPidAlive would misread a reused pid (heavy
-    // forking, esp. Linux) as "still alive" and skip the relaunch forever.
+    // Double-revive guard: identity-aware liveness on pi_pid, requiring
+    // CONFIRMED alive — not the fail-open-to-alive boolean adapter. A node
+    // whose broker pid is CONFIRMED still running as that same broker (not a
+    // reused pid) was already revived by another path — re-launching would put
+    // a SECOND broker on the same session file. No-op. A bare isPidAlive would
+    // misread a reused pid (heavy forking, esp. Linux) as "still alive" and
+    // skip the relaunch forever; conversely, treating an INDETERMINATE read
+    // (can't confirm either way, e.g. a transient `ps` probe failure) as
+    // "alive" here would risk the opposite failure — silently skipping a
+    // needed relaunch and stranding the node with no engine. So this guard
+    // blocks ONLY on a positively confirmed-alive read; `dead` AND
+    // `indeterminate` both proceed to relaunch. We accept that tradeoff: an
+    // `indeterminate` read CAN come from a genuinely live broker whose identity
+    // `ps` probe transiently failed, so proceeding risks a rare double-launch —
+    // but stranding a truly-dead node with no engine is the worse failure, and
+    // recovering from it is far harder, so we bias toward relaunching.
     const live = getNode(nodeId) ?? meta;
-    if (isRecordedPidAlive(live.pi_pid, live.pi_pid_identity)) {
+    if (recordedPidLiveness(live.pi_pid, live.pi_pid_identity) === 'alive') {
         return {
             window: null,
             session: live.tmux_session ?? null,

package/dist/core/substrate/on-read.js

@@ -58,6 +58,7 @@ import { pathExists, readText, walkFiles } from '../fs-utils.js';
 import { parseFrontmatterGeneric } from '../frontmatter.js';
 import { evalCondition } from '../predicate.js';
 import { listAllMemoryDocs } from '../memory-resolver.js';
+import { userScopeRoot } from '../scope.js';
 import { assembleNodeSubject, buildCeilingIndex, displayName, effectiveRung, gatePasses, normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, resolveDocName, } from './index.js';
 import { cachedSubstrateDocs } from './session-cache.js';
 // Ancestor dirs we never look inside for a `.crouter/memory/` store (the read
@@ -156,16 +157,26 @@ function hasExplicitTrigger(doc) {
  *  `.crouter/memory/`, walking from the read file up to $HOME (or the
  *  filesystem root for a read outside $HOME), skipping junk ancestors. The
  *  user-global `~/.crouter/memory/` store is deliberately skipped: otherwise
- *  every file read under $HOME would surface unrelated user-wide preferences. */
+ *  every file read under $HOME would surface unrelated user-wide preferences.
+ *
+ *  The crouter home (`~/.crouter`, the user scope root) is skipped for the same
+ *  reason it is never a project scope root (scope.ts's `isProjectScopeDir`): it
+ *  is the user scope, not a project ancestor. Without this fence, reading any
+ *  canvas runtime artifact (`~/.crouter/canvas/nodes/.../reports|context/...`)
+ *  walks up THROUGH `~/.crouter` and would inject whatever lives at
+ *  `~/.crouter/.crouter/memory/` — e.g. a differently-scoped node whose cwd
+ *  resolved its project store there — leaking one node's private memory into
+ *  every unrelated node that reads a canvas file. */
 function positionalCandidates(absReadFile) {
     const out = [];
     const seenDocPaths = new Set();
     const home = realpathOrSelf(homedir());
+    const userRoot = realpathOrSelf(userScopeRoot());
     const fsRoot = parse(absReadFile).root;
     let dir = dirname(absReadFile);
     let depth = 0;
     while (true) {
-        if (dir !== home && !isJunkAncestor(dir)) {
+        if (dir !== home && dir !== userRoot && !isJunkAncestor(dir)) {
             const memDir = join(dir, CRTR_DIR_NAME, 'memory');
             if (pathExists(memDir)) {
                 for (const file of safeWalkMd(memDir)) {

package/dist/daemon/crtrd.js

@@ -64,7 +64,7 @@ import { FAULT_QUIET_MS, readFault, recordFault } from '../core/runtime/fault.js
 import { fanDoctrineWake } from '../core/runtime/close.js';
 import { logger } from '../core/log.js';
 export { FAULT_QUIET_MS };
-import { isPidAlive, isRecordedPidAlive } from '../core/canvas/pid.js';
+import { isPidAlive, isRecordedPidAlive, recordedPidLiveness } from '../core/canvas/pid.js';
 import { reconcileBootLiveness } from '../core/canvas/boot.js';
 import { listLivePanes, tearDownNode } from '../core/runtime/placement.js';
 import { reviveNode } from '../core/runtime/revive.js';
@@ -705,14 +705,24 @@ async function handleNodeLiveness(row, now, revivedThisTick) {
     // its turn is over, and the engine never exited — past the grace it kills the
     // engine so the dead-pid refresh branch below revives it fresh.
     //
-    // Liveness here is IDENTITY-aware, not a bare isPidAlive: on a heavily-
+    // Liveness here is IDENTITY-aware AND requires CONFIRMED alive, not a bare
+    // isPidAlive or the fail-open-to-alive boolean adapter: on a heavily-
     // forking host (esp. Linux, where low pids recycle fast) a just-dead
-    // broker's pid can be reused by an unrelated process before this tick
-    // runs, and a bare isPidAlive would report the STRANGER as "our broker
-    // alive" — clearing the grace clock forever and wedging revive (the
-    // recorded-pid-reuse hang). isRecordedPidAlive guards against that with
-    // the launch-time identity baseline (`row.pi_pid_identity`).
-    if (pid != null && isRecordedPidAlive(pid, row.pi_pid_identity)) {
+    // broker's pid can be reused by an unrelated process within milliseconds,
+    // AND the `ps` probe confirming identity can itself intermittently fail.
+    // Either misread as "alive" here doesn't just misreport this one tick — it
+    // clears `unhealthySince` (the grace clock), discarding the daemon's memory
+    // that the node had already been observed dead, so the VERY NEXT tick treats
+    // a dead-for-20s+ node as a brand-new first observation and restarts the
+    // whole grace window from scratch (the confirmed Round-2 crash-revive wedge:
+    // a single `probe-null` read on a Linux CI runner wedged
+    // broker-crash-teardown.test.ts's 'CRASH → grace-revive RESUME'). So only a
+    // POSITIVELY CONFIRMED-alive read (`recordedPidLiveness === 'alive'`) may
+    // clear the clock; `'dead'` AND `'indeterminate'` both fall through to the
+    // ordinary not-alive path below, which now CONTRIBUTES to the grace window
+    // instead of zeroing it — robust to a flicker, and still revives promptly
+    // once a node is truly gone for the full grace duration.
+    if (pid != null && recordedPidLiveness(pid, row.pi_pid_identity) === 'alive') {
         unhealthySince.delete(id);
         clearStrandedRelaunchState(id); // a live engine means the stranding resolved
         handleYieldStall(row, pid, now);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.64",
+  "version": "0.3.66",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",