@crouton-kit/crouter 0.3.39 → 0.3.41

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

@@ -6,5 +6,159 @@ export declare function isPidAlive(pid: number | null | undefined): boolean;
  *  swallowing ESRCH (already gone). Shared by triggers.ts (cancel-time reap of
  *  an in-flight predicate evaluation) and daemon/predicate-eval.ts (per-eval
  *  timeout + stale-lease recovery kills). Lives beside isPidAlive: canvas/ is
- *  the lowest shared layer every process-liveness/-teardown primitive sits at. */
+ *  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;
+/** 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 (spawn
+ *  error, non-zero exit, non-string stdout): 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. */
+export declare function capturePidIdentities(pids: readonly number[]): Map<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;

package/dist/core/canvas/pid.js

@@ -7,6 +7,8 @@
 // so it is exempt from the "only canvas.ts touches the db" rule. Collapses the
 // four near-identical copies that used to live in canvas.ts, revive.ts,
 // placement.ts, and crtrd.ts into one (Phase 3 review reuse MINOR-1).
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 /** True if a process with `pid` is currently alive (signal-0 probe). `kill(pid,
  *  0)` throws ESRCH when the process is gone; EPERM means it exists but isn't
  *  ours — still alive. A null/undefined pid (legacy / never-booted) reads dead. */
@@ -25,8 +27,12 @@ export function isPidAlive(pid) {
  *  swallowing ESRCH (already gone). Shared by triggers.ts (cancel-time reap of
  *  an in-flight predicate evaluation) and daemon/predicate-eval.ts (per-eval
  *  timeout + stale-lease recovery kills). Lives beside isPidAlive: canvas/ is
- *  the lowest shared layer every process-liveness/-teardown primitive sits at. */
+ *  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 function killProcessGroup(pid, signal = 'SIGTERM') {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return;
     try {
         process.kill(-pid, signal);
     }
@@ -34,3 +40,302 @@ export function killProcessGroup(pid, signal = 'SIGTERM') {
         /* already gone */
     }
 }
+/** Linux-only higher-resolution discriminator layered onto `lstart` (crouter#98
+ *  review finding, minor): `ps lstart` is only second-granular, so a PID reused
+ *  within the same wall-clock second compares equal and slips past the reuse
+ *  guard. `/proc/<pid>/stat`'s `starttime` field is the kernel's own jiffies-
+ *  since-boot counter for that process — effectively unique per pid even for
+ *  same-second reuse. `comm` (field 2) is parenthesized and may itself contain
+ *  spaces/parens, so this splits on the LAST `)` rather than counting fields
+ *  from the front. Returns `null` (never throws) on any read/parse failure —
+ *  no `/proc` (macOS, containers without procfs), a raced-away pid, or a
+ *  malformed line — so this is purely additive precision, never a hard
+ *  dependency: `composeIdentity` falls back to plain `lstart` in every such
+ *  case, exactly matching this module's pre-existing cross-platform coarse
+ *  behavior. */
+function procStartTicks(pid) {
+    try {
+        const raw = readFileSync(`/proc/${pid}/stat`, 'utf8');
+        const closeParen = raw.lastIndexOf(')');
+        if (closeParen === -1)
+            return null;
+        // Fields after `(comm)`, 0-indexed from `state` (proc(5) field 3): state(0)
+        // ppid(1) pgrp(2) session(3) tty_nr(4) tpgid(5) flags(6) minflt(7)
+        // cminflt(8) majflt(9) cmajflt(10) utime(11) stime(12) cutime(13)
+        // cstime(14) priority(15) nice(16) num_threads(17) itrealvalue(18)
+        // starttime(19) — proc(5) field 22.
+        const rest = raw.slice(closeParen + 2).trim().split(/\s+/);
+        const starttime = rest[19];
+        return starttime !== undefined && /^\d+$/.test(starttime) ? starttime : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Compose the stable process-identity fingerprint used everywhere in this
+ *  module: `ps lstart` (portable, BSD + Linux) plus the Linux-only jiffies
+ *  discriminator when available (best-effort — see `procStartTicks`). ALWAYS
+ *  used to build an identity string, never `lstart` alone directly, so every
+ *  identity captured anywhere (launch-time `recordPid`, the teardown
+ *  snapshot, and the escalation-window re-check) is comparable apples-to-
+ *  apples. */
+function composeIdentity(pid, lstart) {
+    const ticks = procStartTicks(pid);
+    return ticks !== null ? `${lstart}#${ticks}` : lstart;
+}
+/** One combined `ps` probe over the WHOLE process table — `pid`, `ppid`, AND
+ *  `lstart` per row — parsed into BOTH a ppid → children-pid[] map (for
+ *  descendant-tree walks) and a pid → identity map (`composeIdentity`), from a
+ *  SINGLE `spawnSync` call. Shared by `descendantPids` and
+ *  `captureTeardownSnapshot` so tree membership and identity are always read
+ *  off the SAME table snapshot — closing the small race (crouter#98 final
+ *  review) where two separate `ps` calls could see the process table change
+ *  between them. Returns `null` (never throws) on any `ps` failure. */
+function capturePsTable() {
+    let stdout;
+    try {
+        const r = spawnSync('ps', ['-Ao', 'pid=,ppid=,lstart='], { encoding: 'utf8', timeout: 2000 });
+        if (r.status !== 0 || typeof r.stdout !== 'string')
+            return null;
+        stdout = r.stdout;
+    }
+    catch {
+        return null;
+    }
+    const childrenOf = new Map();
+    const identities = new Map();
+    for (const line of stdout.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '')
+            continue;
+        // pid and ppid are the two leading whitespace-delimited numeric tokens;
+        // `lstart` (a human-readable timestamp that itself CONTAINS spaces, e.g.
+        // "Wed Jul 3 10:23:45 2026") is everything after them, kept verbatim.
+        const m = /^(\d+)\s+(\d+)\s+(.+)$/.exec(trimmed);
+        if (m === null)
+            continue;
+        const pid = Number(m[1]);
+        const ppid = Number(m[2]);
+        const lstart = m[3].trim();
+        if (!Number.isInteger(pid) || pid <= 0 || !Number.isInteger(ppid) || ppid <= 0 || lstart === '')
+            continue;
+        identities.set(pid, composeIdentity(pid, lstart));
+        const siblings = childrenOf.get(ppid);
+        if (siblings === undefined)
+            childrenOf.set(ppid, [pid]);
+        else
+            siblings.push(pid);
+    }
+    return { childrenOf, identities };
+}
+/** BFS over an already-parsed ppid → children-pid[] map, starting from
+ *  `rootPid`'s children. Pure (no `ps` spawn) — split out of `descendantPids`
+ *  so `captureTeardownSnapshot` can walk the SAME `capturePsTable()` result it
+ *  already paid for, rather than re-spawning `ps`. */
+function descendantPidsFrom(rootPid, childrenOf) {
+    const out = [];
+    const seen = new Set([rootPid]);
+    const queue = [...(childrenOf.get(rootPid) ?? [])];
+    while (queue.length > 0) {
+        const pid = queue.shift();
+        if (seen.has(pid))
+            continue; // guard against a malformed/cyclic ps snapshot
+        seen.add(pid);
+        out.push(pid);
+        const kids = childrenOf.get(pid);
+        if (kids !== undefined)
+            queue.push(...kids);
+    }
+    return out;
+}
+/** Every transitive descendant of `rootPid`, discovered by walking `ps`'s
+ *  pid/ppid table (BFS) — NOT process-GROUP membership. 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 function descendantPids(rootPid) {
+    if (!Number.isInteger(rootPid) || rootPid <= 0)
+        return [];
+    const table = capturePsTable();
+    if (table === null)
+        return [];
+    return descendantPidsFrom(rootPid, table.childrenOf);
+}
+/** Capture a portable process-identity fingerprint — `ps`'s `lstart` column,
+ *  the process's full wall-clock start time — for each of `pids`, in ONE
+ *  batched `ps -p <list>` call. `lstart` is a standard format keyword on BOTH
+ *  BSD ps (macOS) and procps-ng (Linux), so this needs no `/proc` parsing or
+ *  other Linux-only machinery. Used to guard against PID REUSE during the
+ *  multi-second teardown escalation ladder (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 (spawn
+ *  error, non-zero exit, non-string stdout): 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. */
+export function capturePidIdentities(pids) {
+    const valid = pids.filter((pid) => Number.isInteger(pid) && pid > 0);
+    const out = new Map();
+    if (valid.length === 0)
+        return out;
+    try {
+        const r = spawnSync('ps', ['-o', 'pid=,lstart=', '-p', valid.join(',')], { encoding: 'utf8', timeout: 2000 });
+        if (r.status !== 0 || typeof r.stdout !== 'string')
+            return null;
+        for (const line of r.stdout.split('\n')) {
+            const trimmed = line.trim();
+            if (trimmed === '')
+                continue;
+            // Only the FIRST token (pid) is split on whitespace — `lstart` is a
+            // human-readable timestamp that itself CONTAINS spaces (e.g. "Wed Jul
+            // 3 10:23:45 2026"), so everything after the first space is kept
+            // verbatim as the identity string. Exact string equality later is
+            // sufficient; nothing here needs to parse it as a real date.
+            const spaceIdx = trimmed.indexOf(' ');
+            if (spaceIdx === -1)
+                continue;
+            const pid = Number(trimmed.slice(0, spaceIdx));
+            const startedAt = trimmed.slice(spaceIdx + 1).trim();
+            if (!Number.isInteger(pid) || pid <= 0 || startedAt === '')
+                continue;
+            out.set(pid, composeIdentity(pid, startedAt));
+        }
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
+export function captureTeardownSnapshot(rootPid, expectedIdentity) {
+    if (!Number.isInteger(rootPid) || rootPid <= 0)
+        return { tree: [], identities: null, reused: false };
+    const table = capturePsTable();
+    if (table === null)
+        return { tree: [rootPid], identities: null, reused: false };
+    const currentRootIdentity = table.identities.get(rootPid);
+    const reused = expectedIdentity != null && currentRootIdentity !== undefined && currentRootIdentity !== expectedIdentity;
+    if (reused)
+        return { tree: [], identities: null, reused: true };
+    const tree = [rootPid, ...descendantPidsFrom(rootPid, table.childrenOf)];
+    const identities = new Map();
+    for (const pid of tree) {
+        const id = table.identities.get(pid);
+        if (id !== undefined)
+            identities.set(pid, id);
+    }
+    return { tree, identities, reused: false };
+}
+/** Best-effort signal against every pid in an ALREADY-CAPTURED tree snapshot
+ *  (typically `[rootPid, ...descendantPids(rootPid)]`, taken ONCE by the
+ *  caller before sending any signal — see the doc on `isProcessTreeAlive` for
+ *  why re-deriving via `ps` after signaling starts is unsafe). Signals EACH
+ *  pid's OWN process group (a detached SDK-spawned descendant is its own
+ *  group leader — the pi bash tool's shell child, 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 function killProcessTreePids(pids, signal = 'SIGTERM', identities) {
+    const current = identities != null ? capturePidIdentities(pids) : undefined;
+    for (const pid of pids) {
+        if (identities != null && current != null) {
+            const expected = identities.get(pid);
+            const actual = current.get(pid);
+            const reused = expected !== undefined && actual !== undefined && actual !== expected;
+            if (reused)
+                continue;
+        }
+        killProcessGroup(pid, signal);
+        if (!Number.isInteger(pid) || pid <= 0)
+            continue;
+        try {
+            process.kill(pid, signal);
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
+/** Is `rootPid`'s process TREE — itself or any CURRENT descendant — still
+ *  alive, re-deriving the descendant set fresh via `ps` on every call? Safe
+ *  ONLY before any signal has been sent to this tree. Once a signal kills the
+ *  root (it's typically its own process-group leader — see `launch()` in
+ *  host.ts), the kernel reparents any surviving child away from `rootPid`
+ *  IMMEDIATELY (standard orphan handling, confirmed empirically: a killed
+ *  parent's child shows `ppid=1` within the same tick, not lazily) —
+ *  silently "losing" that child from a fresh `descendantPids` walk even
+ *  though it is still very much alive. Use this ONLY to watch a tree you have
+ *  not touched yet (e.g. waiting out a graceful-shutdown grace window); once
+ *  you start signaling, capture the pid list ONCE and check it with
+ *  `isAnyPidAlive` instead — see `killProcessTreePids`. */
+export function isProcessTreeAlive(rootPid) {
+    if (isPidAlive(rootPid))
+        return true;
+    return descendantPids(rootPid).some((pid) => isPidAlive(pid));
+}
+/** Is any pid in an ALREADY-CAPTURED pid list (see `killProcessTreePids`)
+ *  still alive? Pure signal-0 check against the fixed list — NEVER re-walks
+ *  `ps` — the correct liveness check once you've started signaling a tree
+ *  (see `isProcessTreeAlive`'s doc for why re-deriving after that point would
+ *  silently drop a still-alive orphan). */
+export function isAnyPidAlive(pids) {
+    return pids.some((pid) => isPidAlive(pid));
+}

package/dist/core/canvas/status-glyph.d.ts

@@ -23,6 +23,13 @@ export declare function resolveNodeVisual(status: NodeStatus, opts: {
         kind: FaultKind;
     } | null;
 }): NodeVisual;
+/** True for exactly the fault dispositions `faultDispositionText` renders as
+ *  "needs you" — nothing (sdk/daemon/client) is auto-driving recovery, so the
+ *  dashboard flags the node for the human. Exported so a recovery verb (e.g.
+ *  `canvas revive --now`, src/commands/revive.ts) can gate on the SAME
+ *  predicate the dashboard advertises instead of drifting out of sync with it
+ *  (issue #115 — `--now` used to reject exactly the nodes shown as "needs you"). */
+export declare function faultNeedsYou(fault: Pick<Fault, 'retry'>): boolean;
 /** Human-friendly active-fault disposition text. `auto` faults show the current
  *  retry attempt plus the next scheduled retry; client-owned redials say
  *  `redialing`; everything else says `needs you`. */

package/dist/core/canvas/status-glyph.js

@@ -70,12 +70,21 @@ function retryCountdown(iso, now) {
         return `${Math.max(1, Math.round(remaining / 60_000))}m`;
     return `${Math.max(1, Math.ceil(remaining / 1000))}s`;
 }
+/** True for exactly the fault dispositions `faultDispositionText` renders as
+ *  "needs you" — nothing (sdk/daemon/client) is auto-driving recovery, so the
+ *  dashboard flags the node for the human. Exported so a recovery verb (e.g.
+ *  `canvas revive --now`, src/commands/revive.ts) can gate on the SAME
+ *  predicate the dashboard advertises instead of drifting out of sync with it
+ *  (issue #115 — `--now` used to reject exactly the nodes shown as "needs you"). */
+export function faultNeedsYou(fault) {
+    return fault.retry.disposition !== 'auto';
+}
 /** Human-friendly active-fault disposition text. `auto` faults show the current
  *  retry attempt plus the next scheduled retry; client-owned redials say
  *  `redialing`; everything else says `needs you`. */
 export function faultDispositionText(fault, now = Date.now()) {
     const retry = fault.retry;
-    if (retry.disposition === 'auto') {
+    if (!faultNeedsYou(fault)) {
         if (retry.by === 'client')
             return 'redialing';
         const progress = typeof retry.attempt === 'number' && typeof retry.max === 'number'

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

@@ -35,6 +35,16 @@ export interface LaunchSpec {
     /** Extra env injected into the pi process. */
     env: Record<string, string>;
 }
+export interface ManagedWorktree {
+    state: 'open' | 'closed';
+    path: string;
+    branch: string;
+    repo_root: string;
+    base_ref: string;
+    base_sha: string;
+    created: string;
+    closed?: string;
+}
 /** A node's DURABLE IDENTITY — the subset that `meta.json` persists on disk.
  *  Written rarely (birth, polymorph, session-id capture, naming); never touched
  *  by a status flip, an intent change, a focus swap, or a pid stamp. The db row
@@ -106,6 +116,15 @@ export interface NodeIdentity {
      *  PATH is opened directly — immune to any cwd discrepancy. Null for older
      *  nodes booted before this field existed → revive falls back to the bare id. */
     pi_session_file?: string | null;
+    /** True while a cycling (refresh-yield, `--crtr-new-cycle`) launch attempt is
+     *  IN FLIGHT and has not yet reached `session_start` — set by reviveNode right
+     *  before it launches a cycling engine, cleared by canvas-stophook's
+     *  session_start handler the instant that boot is confirmed. Lets a pre-
+     *  session_start crash-retry (crtrd.ts) detect "the dead attempt I'm retrying
+     *  was itself a cycle" and retry AS a cycle (resume:false) instead of a strict
+     *  resume — otherwise the retry stops after the first crash-loop attempt and
+     *  strands the node in an empty marker branch with no kickoff. */
+    cycle_pending?: boolean | null;
     /** A caller-pinned model TIER (ultra/strong/medium/light) that overrides the
      *  persona's declared default. Durable so it survives a polymorph: every
      *  spec-rebuild path (promote/demote/lifecycle/reset) re-passes it to
@@ -114,6 +133,8 @@ export interface NodeIdentity {
     model_override?: string | null;
     /** Full pi launch recipe; rewritten on every polymorph. */
     launch?: LaunchSpec;
+    /** Managed git worktree owned by this node (if any). */
+    managed_worktree?: ManagedWorktree | null;
 }
 /** A node's LIVE RUNTIME state — authoritative in the WAL'd `nodes` row, each
  *  field mutated by exactly one atomic single-statement `UPDATE` (setStatus /
@@ -134,6 +155,17 @@ export interface NodeRuntime {
      *  reviveNode until the fresh broker re-records it, so the relaunch gap reads as
      *  a dead pid (guarded by the daemon's revive grace, not a double-spawn). */
     pi_pid?: number | null;
+    /** Stable process-identity fingerprint (`pid.ts`'s `composeIdentity`) captured
+     *  at the SAME moment `pi_pid` is recorded (`recordPid`) — the LAUNCH-time
+     *  baseline `headlessBrokerHost.teardown()` compares `pi_pid`'s CURRENT
+     *  identity against before signaling anything (crouter#98 review finding 1):
+     *  a mismatch proves the OS has already recycled `pi_pid` for an unrelated
+     *  process since this node launched it, and teardown must refuse to signal
+     *  that stranger. `null` for a node booted before this field existed, or if
+     *  the launch-time identity capture itself failed (fail-open — no baseline
+     *  means no guard, not a false mismatch). Cleared to null alongside `pi_pid`
+     *  by `clearPid` and the boot-liveness sweep (a new boot invalidates both). */
+    pi_pid_identity?: string | null;
     /** Presence: the tmux session (its root's home) and window this node renders
      *  in while active. Cleared when the node goes done/dead and its window closes.
      *  The row IS the presence registry (one atomic setPresence per move).
@@ -176,6 +208,8 @@ export interface NodeRow {
     /** Authoritative runtime columns (see NodeRuntime). */
     intent: ExitIntent;
     pi_pid: number | null;
+    /** See `NodeRuntime.pi_pid_identity`. */
+    pi_pid_identity: string | null;
     window: string | null;
     tmux_session: string | null;
     /** The durable LOCATION handle (the tmux `%pane_id`); see NodeRuntime.pane. */

package/dist/core/fault-classifier.js

@@ -6,11 +6,15 @@ function text(value) {
 }
 function classifyProviderText(message) {
     const m = message ?? '';
-    // ORDER MATTERS: rate-limit → overloaded → connection → other.
+    // ORDER MATTERS: rate-limit → overloaded → auth → connection → other.
+    // auth precedes connection so "refresh token not found" (a dead OAuth grant)
+    // reads as fatal auth, not a transient not-found/connection blip.
     if (/rate.?limit|\b429\b|too many requests|quota/i.test(m))
         return 'rate-limit';
     if (/overloaded|\b529\b|\b503\b|capacity|server.{0,3}busy|temporarily unavailable/i.test(m))
         return 'overloaded';
+    if (/invalid_grant|refresh token|unauthori[sz]ed|invalid.?api.?key|authentication failed|\b401\b|\b403\b/i.test(m))
+        return 'auth';
     if (/connection|econnreset|etimedout|enotfound|econnrefused|network|fetch failed|socket hang|timed? out|timeout/i.test(m))
         return 'connection';
     return 'other';

package/dist/core/runtime/bearings.js

@@ -446,6 +446,10 @@ export function buildContextBearings(nodeId) {
     const profileSection = profileNote(nodeId);
     if (profileSection !== '')
         bearings.push('', profileSection);
+    const wt = node?.managed_worktree;
+    if (wt?.state === 'open') {
+        bearings.push('', '## Your managed worktree', `Branch: \`${wt.branch}\`\nWorktree: \`${wt.path}\`\nBase: \`${wt.base_ref}\` @ \`${wt.base_sha}\`\nCommit work here. Land it with \`crtr worktree close\` before finishing; \`crtr push final\` is blocked until this worktree is closed.`);
+    }
     // Orchestrator-only: the across-cycles framing (a terminal has no future cycle).
     if (node?.mode === 'orchestrator')
         bearings.push('', orchestratorContextNote(nodeId));

package/dist/core/runtime/branded-host.d.ts

@@ -3,6 +3,13 @@
  *  to the installed node, shared across every canvas home. */
 export declare function brandedHostDir(): string;
 export declare function brandedHostBin(): string;
+/** macOS keys FDA grants on the Mach-O cdhash. A real developer identity
+ *  keeps that hash stable across branded-host rebuilds; ad-hoc signing is the
+ *  portable default for machines without a local signing certificate. */
+export declare function codesignIdentitiesForBrandedHost(opts?: {
+    configured?: string | null;
+    discovered?: string | null;
+}): string[];
 export declare function signBrandedHostArtifacts(binPath: string, libnodePath: string | null, sign?: (path: string) => void): void;
 export declare function brandedHostWorks(binPath: string): boolean;
 /** Ensure the branded host binary exists and matches the live node; return its