@crouton-kit/crouter 0.3.40 → 0.3.41

package/dist/daemon/crtrd.d.ts

@@ -1,4 +1,4 @@
-import { type NodeRow } from '../core/canvas/index.js';
+import { type NodeRow, type NodeMeta } from '../core/canvas/index.js';
 import { FAULT_QUIET_MS } from '../core/runtime/fault.js';
 export { FAULT_QUIET_MS };
 import { isPidAlive } from '../core/canvas/pid.js';
@@ -35,14 +35,15 @@ export declare function wedgeVerdict(input: {
     quietForMs: number | null;
     cpuPercent: number | null;
 }): WedgeVerdict;
-/** Pure: sum CPU% across a process's entire tree (itself + every descendant).
- *  Parses `ps -ax -o pid=,ppid=,pcpu=` output, builds a ppid→children map, and
- *  DFS's from `rootPid` collecting root + all descendants; malformed/blank
- *  lines are skipped. Returns `null` if `rootPid` never appears in the output
- *  (can't measure at all — treated as UNKNOWN by wedgeVerdict, never as
- *  “low”) or the output has no parsable rows. Exported for direct unit testing
- *  — no process access of its own, mirroring wedgeVerdict's purity. */
 export declare function sumTreeCpu(psOutput: string, rootPid: number): number | null;
+/** Pure (issue #119): does `rootPid` have ANY descendant in this ps snapshot
+ *  — a runaway subprocess to kill — or does the broker stand ALONE in its own
+ *  tree (nothing to kill; the engine itself stalled)? Shares `parsePsTree`
+ *  with `sumTreeCpu` so the two facts the wedge remediation needs come from
+ *  one `ps` sample. Null when `rootPid` isn't in the sample at all (can't
+ *  tell — same "unknown, never treated as a fact" stance `sumTreeCpu` takes on
+ *  a missing root). Exported for direct unit testing. */
+export declare function treeHasDescendants(psOutput: string, rootPid: number): boolean | null;
 export type LivenessVerdict = 'leave' | 'pending' | 'revive';
 /** Decide what to do with a node whose engine pid is DEAD, from how long it's
  *  been dead. Pure — the time/revive side effects live in handleNodeLiveness;
@@ -51,6 +52,14 @@ export type LivenessVerdict = 'leave' | 'pending' | 'revive';
  *  upstream by handleNodeLiveness.)
  *    deadFor: ms since first observed dead, or null on the first observation. */
 export declare function livenessVerdict(piPidAlive: boolean | null, deadFor: number | null): LivenessVerdict;
+/** Whether a crash-retry of a dead/stranded engine should resume STRICTLY
+ *  (true) or retry the SAME launch attempt's cycling mode (false). Mirrors
+ *  reviveNode's own cycle_pending flag (set true right before every cycling
+ *  launch, cleared the instant session_start confirms boot) — so a cycling
+ *  revive that died pre-session_start is retried AS a cycle (re-appending the
+ *  marker + kickoff), never stranded as a strict resume into an empty marker
+ *  branch. Pure so it's unit-testable without a fabricated node. */
+export declare function retryResumeMode(meta: Pick<NodeMeta, 'cycle_pending'> | null): boolean;
 export declare const DEAD_REAP_GRACE_MS: number;
 /** Read the pid stored in the pidfile, or null if absent / malformed. */
 export declare function readPidfile(): number | null;

package/dist/daemon/crtrd.js

@@ -18,7 +18,10 @@
 //   • pid dead + intent==='refresh' → fresh respawn (node asked to yield).
 //   • pid dead + intent==='idle-release' → dormant by choice; the second pass
 //     revives (resume) when its inbox gains an unseen entry.
-//   • pid dead + any other intent → grace-revive RESUME on the saved session.
+//   • pid dead + any other intent → grace-revive RESUME on the saved session,
+//     UNLESS the dead engine's last launch attempt was itself an in-flight
+//     cycle (cycle_pending) — then retry it AS a cycle instead of stranding it
+//     as a strict resume into an empty marker branch.
 //
 // §H refresh-authority: a stale in-process stophook (pi extensions never reload,
 // so a days-old resident carries an old hook) can leave intent='refresh' on a
@@ -38,14 +41,16 @@
 // daemon keeps the live broker parked and retries it via the inbox-based
 // fault-recovery pass so the ordinary dead-pid crash path never needs an
 // out-of-band launch.
-// dead-pid crash path grace-revives RESUME on the saved session — the manual
+// dead-pid crash path grace-revives RESUME on the saved session (or, for a
+// crash mid-cycle, retries AS a cycle — see cycle_pending above) — the manual
 // recovery (kill broker + canvas revive) that fixes these by hand.
 //
 // Single-instance guarantee
 //   A PID file prevents double-runs. On start, if the file exists and the
-//   recorded pid is alive, we refuse to start (exit 0). Hearth guests set
-//   CRTR_PIDFILE to keep this process-local on recreate; otherwise it defaults
-//   to crtrHome()/crtrd.pid. On stop (SIGINT/SIGTERM/exit) we remove the file.
+//   recorded pid is alive, we refuse to start (exit 0). Remote/guest deployments
+//   set CRTR_PIDFILE to keep this process-local on recreate; otherwise it
+//   defaults to crtrHome()/crtrd.pid. On stop (SIGINT/SIGTERM/exit) we remove
+//   the file.
 import { writeFileSync, readFileSync, rmSync, existsSync, mkdirSync, statSync, } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
@@ -55,7 +60,7 @@ import { listNodes, getRow, getNode, dueClockTriggers, consumeTrigger, advanceTr
 import { fullName } from '../core/canvas/labels.js';
 import { transition } from '../core/runtime/lifecycle.js';
 import { isBusy, busySince } from '../core/runtime/busy.js';
-import { FAULT_QUIET_MS, recordFault } from '../core/runtime/fault.js';
+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 };
@@ -220,12 +225,19 @@ function handleYieldStall(row, pid, now) {
 // with no wake and no visible fault marker (`node inspect list --hanging`
 // returns nothing — there's no fault recorded, just silence).
 //
-// Detection, not recovery: this NOTIFIES (fans a doctrine wake + records a
-// `daemon→node`/'wedged' fault so the node shows ⌘ “wedged · needs you” on the
-// canvas graph views, same surface `node inspect list --hanging` already reads)
-// — it never kills or restarts the engine. Killing the runaway SUBPROCESS (not
-// the node) is the sanctioned recovery; see `crtr memory read
-// wedged-child-on-runaway-bash`.
+// Detection always NOTIFIES (fans a doctrine wake + records a `daemon→node`/
+// 'wedged' fault so the node shows ⌘ “wedged · needs you” on the canvas graph
+// views, same surface `node inspect list --hanging` already reads). Recovery
+// then branches on whether the broker's process TREE has a descendant:
+//   • descendants present → a runaway SUBPROCESS is the likely cause; the
+//     daemon does NOT touch the engine — kill the subprocess (not the node);
+//     see `crtr memory read wedged-child-on-runaway-bash`.
+//   • no descendants (the broker pid stands alone — e.g. the engine itself
+//     stalled after a model_change, with nothing to kill) → the daemon
+//     performs the ONLY remaining remediation itself: SIGTERM the broker, the
+//     same on-demand kick `canvas revive --now` does, so its own dead-pid
+//     crash-grace path (REVIVE_GRACE_MS) resumes it on the saved session with
+//     no lost context.
 //
 // Two corroborating signals, both generous, so a routine long-running bash/
 // build/test tool call is never mistaken for a wedge:
@@ -256,11 +268,14 @@ function handleYieldStall(row, pid, now) {
 //      ACCEPTED residual: a legitimate subprocess blocked on silent I/O (e.g. a
 //      20-minute download emitting no output, a long `sleep`) reads ~0% tree
 //      CPU and is indistinguishable from a real wedge at the OS level — no CPU
-//      signal can tell a hung child from an I/O-blocked one. This is accepted,
-//      not deferred, because detection only NOTIFIES and never kills: the cost
-//      of that rare false positive is one doctrine wake to a parent, and 20+
-//      minutes of total silence with near-zero tree CPU is itself worth
-//      surfacing either way.
+//      signal can tell a hung child from an I/O-blocked one. This is accepted:
+//      that case still HAS a descendant, so the daemon only notifies (never
+//      kills) — the cost of the rare false positive is one doctrine wake, and
+//      20+ minutes of total silence with near-zero tree CPU is itself worth
+//      surfacing either way. Only the no-descendants branch ever acts, and
+//      SIGTERM-then-resume can't lose context (the saved session is resumed
+//      unchanged), so a false positive there costs one unnecessary restart, not
+//      lost work.
 // ---------------------------------------------------------------------------
 // Generous: routine long tool calls settle well under this; only a turn with
 // zero observed engine progress for 20+ minutes is even a wedge CANDIDATE.
@@ -295,6 +310,15 @@ export function wedgeVerdict(input) {
  *  repeat notice), which is the same tradeoff `notifiedTriggerFailures` and
  *  `unhealthySince` already accept. */
 const wedgeNotifiedAt = new Map();
+/** Fatal-provider-fault notify latch (issue #94), keyed on node id → the
+ *  `fault.since` we already fanned a wake for. A fatal fault (dead OAuth grant,
+ *  bad key, protocol) has NO retry consumer, so an errored turn just leaves the
+ *  node `active` with a live-but-dormant broker and, until now, woke nobody —
+ *  the manager waiting on it hung and later scheduled wakes silently re-failed.
+ *  Deduped on `fault.since` so one episode fans exactly one wake; a later
+ *  episode (fresh `since`) or a cleared fault re-arms. In-memory like every
+ *  other latch here. */
+const fatalFaultNotifiedAt = new Map();
 /** Pure: sum CPU% across a process's entire tree (itself + every descendant).
  *  Parses `ps -ax -o pid=,ppid=,pcpu=` output, builds a ppid→children map, and
  *  DFS's from `rootPid` collecting root + all descendants; malformed/blank
@@ -302,7 +326,7 @@ const wedgeNotifiedAt = new Map();
  *  (can't measure at all — treated as UNKNOWN by wedgeVerdict, never as
  *  “low”) or the output has no parsable rows. Exported for direct unit testing
  *  — no process access of its own, mirroring wedgeVerdict's purity. */
-export function sumTreeCpu(psOutput, rootPid) {
+function parsePsTree(psOutput) {
     const byPid = new Map(); // pid → pcpu
     const childrenOf = new Map(); // ppid → child pids
     for (const line of psOutput.split('\n')) {
@@ -324,6 +348,10 @@ export function sumTreeCpu(psOutput, rootPid) {
         else
             siblings.push(pid);
     }
+    return { byPid, childrenOf };
+}
+export function sumTreeCpu(psOutput, rootPid) {
+    const { byPid, childrenOf } = parsePsTree(psOutput);
     if (!byPid.has(rootPid))
         return null;
     let total = 0;
@@ -341,19 +369,39 @@ export function sumTreeCpu(psOutput, rootPid) {
     }
     return total;
 }
+/** Pure (issue #119): does `rootPid` have ANY descendant in this ps snapshot
+ *  — a runaway subprocess to kill — or does the broker stand ALONE in its own
+ *  tree (nothing to kill; the engine itself stalled)? Shares `parsePsTree`
+ *  with `sumTreeCpu` so the two facts the wedge remediation needs come from
+ *  one `ps` sample. Null when `rootPid` isn't in the sample at all (can't
+ *  tell — same "unknown, never treated as a fact" stance `sumTreeCpu` takes on
+ *  a missing root). Exported for direct unit testing. */
+export function treeHasDescendants(psOutput, rootPid) {
+    const { byPid, childrenOf } = parsePsTree(psOutput);
+    if (!byPid.has(rootPid))
+        return null;
+    return (childrenOf.get(rootPid) ?? []).length > 0;
+}
 /** Sample the broker's WHOLE PROCESS TREE — the broker pid plus every
- *  descendant, summed — via one `ps` shell-out, the OS-level signal that
- *  corroborates the heartbeat silence (see the section banner above). Null on
- *  ANY failure (the shell-out itself failing, `ps` missing, or `sumTreeCpu`
- *  finding the root pid absent/output unparseable) — wedgeVerdict treats null
- *  exactly like “too high”, so a broken probe can only ever suppress a false
- *  fire, never cause one. */
-function readTreeCpuPercent(pid) {
+ *  descendant — via ONE `ps` shell-out, yielding both signals the wedge path
+ *  needs: the summed tree CPU% (corroborates the heartbeat silence) and
+ *  whether the tree has any descendant at all (issue #119 — decides whether
+ *  remediation is "kill the subprocess" or "kick the broker"). Null on ANY
+ *  failure (the shell-out itself failing, `ps` missing, or the root pid
+ *  absent/output unparseable) — wedgeVerdict treats a null cpuPercent exactly
+ *  like “too high”, so a broken probe can only ever suppress a false fire,
+ *  never cause one; a null sample also means handleWedgeDetection never
+ *  attempts the SIGTERM kick on unconfirmed information. */
+function readTreeSample(pid) {
     try {
         const r = spawnSync('ps', ['-ax', '-o', 'pid=,ppid=,pcpu='], { encoding: 'utf8', timeout: 2000 });
         if (r.status !== 0 || typeof r.stdout !== 'string')
             return null;
-        return sumTreeCpu(r.stdout, pid);
+        const cpuPercent = sumTreeCpu(r.stdout, pid);
+        const hasDescendants = treeHasDescendants(r.stdout, pid);
+        if (cpuPercent === null || hasDescendants === null)
+            return null;
+        return { cpuPercent, hasDescendants };
     }
     catch {
         return null;
@@ -372,7 +420,8 @@ function handleWedgeDetection(id, pid, now) {
     }
     const since = busySince(id);
     const quietForMs = since === null ? null : now - since;
-    const cpuPercent = quietForMs !== null && quietForMs >= WEDGE_QUIET_MS ? readTreeCpuPercent(pid) : null;
+    const sample = quietForMs !== null && quietForMs >= WEDGE_QUIET_MS ? readTreeSample(pid) : null;
+    const cpuPercent = sample?.cpuPercent ?? null;
     const verdict = wedgeVerdict({ busy: true, quietForMs, cpuPercent });
     if (verdict !== 'wedged')
         return;
@@ -383,11 +432,43 @@ function handleWedgeDetection(id, pid, now) {
     const meta = getNode(id);
     const name = meta !== null ? fullName(meta) : id;
     const minutes = Math.round((quietForMs ?? WEDGE_QUIET_MS) / 60_000);
-    const label = `Child wedged — ${name} (${id}) is alive and mid-turn but has shown NO engine progress for ` +
-        `${minutes}+ minutes and its process is near-idle. It will NOT recover on its own — read ` +
-        `\`crtr memory read wedged-child-on-runaway-bash\` and, if a runaway subprocess is to blame, kill ` +
-        `the SUBPROCESS (not this node) so its turn can resume with no lost context.`;
-    process.stderr.write(`[crtrd] wedged ${id} (busy ${minutes}+ min with no engine progress, cpu~0%)\n`);
+    // A null sample can't reach here — wedgeVerdict only fires 'wedged' on a
+    // confirmed near-zero cpuPercent, which requires a non-null sample — so
+    // `sample.hasDescendants` is always defined at this point; the `?? true`
+    // is a type-level fallback only, biased toward the SAFER branch (notify,
+    // don't SIGTERM) if that invariant is ever violated.
+    const hasDescendants = sample?.hasDescendants ?? true;
+    let label;
+    if (hasDescendants) {
+        // A runaway subprocess is the likely cause — the daemon does not touch the
+        // engine; the sanctioned recovery is manual (issue #110).
+        label =
+            `Child wedged — ${name} (${id}) is alive and mid-turn but has shown NO engine progress for ` +
+                `${minutes}+ minutes and its process is near-idle. It will NOT recover on its own — read ` +
+                `\`crtr memory read wedged-child-on-runaway-bash\` and kill the runaway SUBPROCESS (not this ` +
+                `node) so its turn can resume with no lost context.`;
+    }
+    else {
+        // No descendant to kill — the engine itself stalled (e.g. mid model_change)
+        // with nothing a human could kill. The daemon performs the same kick
+        // `canvas revive --now` does on demand: SIGTERM the broker, then its own
+        // dead-pid crash-grace path (REVIVE_GRACE_MS) resumes it on the saved
+        // session (issue #119).
+        label =
+            `Child wedged — ${name} (${id}) is alive and mid-turn but has shown NO engine progress for ` +
+                `${minutes}+ minutes, its process is near-idle, AND it has no subprocess to kill (the engine ` +
+                `itself stalled). Kicking it now: SIGTERM to the broker — the daemon's own crash-grace path ` +
+                `resumes it on the saved session within ~${Math.round(REVIVE_GRACE_MS / 1000)}s, no lost context. ` +
+                `If it comes back idle rather than resuming its turn, nudge it (see \`crtr memory read ` +
+                `wedged-child-on-runaway-bash\`).`;
+        try {
+            process.kill(pid, 'SIGTERM');
+        }
+        catch {
+            /* already gone — the dead-pid path picks it up on the very next tick regardless */
+        }
+    }
+    process.stderr.write(`[crtrd] wedged ${id} (busy ${minutes}+ min with no engine progress, cpu~0%, descendants=${hasDescendants})${hasDescendants ? '' : ' — kicked'}\n`);
     try {
         recordFault(id, {
             link: 'daemon→node',
@@ -406,6 +487,52 @@ function handleWedgeDetection(id, pid, now) {
             child: id,
             quiet_ms: quietForMs,
             cpu_percent: cpuPercent,
+            kicked: !hasDescendants,
+        });
+    }
+    catch {
+        /* best-effort, mirrors every other fan-out in this file */
+    }
+}
+/** Enact fatal-provider-fault notification for a LIVE node (issue #94; called
+ *  from the pid-alive branch of handleNodeLiveness). A FATAL fault (auth /
+ *  protocol / other on `pi→provider`) has no auto-retry consumer — the errored
+ *  turn already ended, so the wedge detector (busy-only) never fires and the
+ *  node sits `active` forever with a dormant broker. The daemon owns the
+ *  analogous wedge fan, so it owns this too: fan ONE doctrine wake per fault
+ *  episode telling subscribers the child will not self-recover (and, for auth,
+ *  to re-authenticate so its next wake succeeds). Detection only — the node is
+ *  deliberately NOT terminalized: the auth-reload fan + next wake are its real
+ *  recovery path after a re-login. */
+function handleFatalFault(id, now) {
+    void now;
+    const fault = readFault(id);
+    if (fault === null) {
+        fatalFaultNotifiedAt.delete(id); // fault cleared — next episode re-arms
+        return;
+    }
+    if (fault.retry.disposition !== 'fatal' || fault.link !== 'pi→provider')
+        return;
+    if (fatalFaultNotifiedAt.get(id) === fault.since)
+        return; // already fanned THIS episode
+    fatalFaultNotifiedAt.set(id, fault.since);
+    const meta = getNode(id);
+    const name = meta !== null ? fullName(meta) : id;
+    const isAuth = fault.kind === 'auth';
+    const firstLine = (fault.message.split('\n')[0] ?? '').slice(0, 200);
+    const label = `Child hit a fatal provider fault — ${name} (${id}) got a non-retryable ${fault.kind} error and will NOT recover on its own; ` +
+        `it stays alive but every wake re-fails until the fault clears. ` +
+        (isAuth
+            ? `Its provider credential is dead — re-authenticate (\`/login\`, or re-auth crtr); the child recovers on its next wake once the auth reloads. `
+            : ``) +
+        `Error: ${firstLine}`;
+    process.stderr.write(`[crtrd] fatal-fault ${id} (${fault.kind}, ${fault.link}) — fanning notice to subscribers\n`);
+    try {
+        fanDoctrineWake(id, subscribersOf(id), label, {
+            reason: 'child-fault-fatal',
+            child: id,
+            kind: fault.kind,
+            message: firstLine,
         });
     }
     catch {
@@ -497,6 +624,16 @@ export function livenessVerdict(piPidAlive, deadFor) {
         return 'pending';
     return 'revive';
 }
+/** Whether a crash-retry of a dead/stranded engine should resume STRICTLY
+ *  (true) or retry the SAME launch attempt's cycling mode (false). Mirrors
+ *  reviveNode's own cycle_pending flag (set true right before every cycling
+ *  launch, cleared the instant session_start confirms boot) — so a cycling
+ *  revive that died pre-session_start is retried AS a cycle (re-appending the
+ *  marker + kickoff), never stranded as a strict resume into an empty marker
+ *  branch. Pure so it's unit-testable without a fabricated node. */
+export function retryResumeMode(meta) {
+    return meta?.cycle_pending !== true;
+}
 /** The ONE liveness path for EVERY node. Every node runs on a detached headless
  *  broker; a tmux pane is only a viewer and is never consulted here — liveness is
  *  the recorded engine pid (signal-0) alone. Reuses the existing supervision
@@ -523,7 +660,10 @@ export function livenessVerdict(piPidAlive, deadFor) {
  *      pi_pid right after launch) → leave through a boot grace; a healthy engine
  *      re-records its pid well within it. If the grace ELAPSES with still no pid,
  *      the relaunch died after the pid-clear → grace-revive RESUME on the saved
- *      session (else the node strands 'active' with no engine forever).
+ *      session, UNLESS that dead relaunch was itself a cycling attempt
+ *      (cycle_pending) — then retry it AS a cycle instead (retryResumeMode), so
+ *      it doesn't strand in an empty marker branch (else the node strands
+ *      'active' with no engine forever).
  *    • pid null + pi_session_id null (NEVER booted) → normally the sub-second SDK
  *      boot gap, but a broker that throws BEFORE session_start records no pid and
  *      no session ever — so after a boot grace with STILL nothing, crash +
@@ -533,7 +673,10 @@ export function livenessVerdict(piPidAlive, deadFor) {
  *    • pid dead + intent==='idle-release' → dormant by choice; leave, the second
  *      pass revives (resume) on the next unseen inbox entry.
  *    • pid dead + any other intent (a crash) → grace-revive RESUME on the saved
- *      session (livenessVerdict → REVIVE_GRACE_MS → unhealthySince). */
+ *      session (livenessVerdict → REVIVE_GRACE_MS → unhealthySince), UNLESS the
+ *      dead engine's last launch attempt was itself a cycling revive that never
+ *      reached session_start (cycle_pending) — then retry it AS a cycle instead
+ *      (retryResumeMode). */
 async function handleNodeLiveness(row, now, revivedThisTick) {
     const id = row.node_id;
     const pid = row.pi_pid;
@@ -545,6 +688,7 @@ async function handleNodeLiveness(row, now, revivedThisTick) {
         unhealthySince.delete(id);
         handleYieldStall(row, pid, now);
         handleWedgeDetection(id, pid, now);
+        handleFatalFault(id, now);
         return;
     }
     if (pid == null) {
@@ -594,9 +738,12 @@ async function handleNodeLiveness(row, now, revivedThisTick) {
         unhealthySince.delete(id);
         if (meta.pi_session_id != null) {
             // Grace elapsed with a session but still no pid → a relaunch that died after
-            // the pid-clear, before re-record. Resume it on the saved session.
+            // the pid-clear, before re-record. Resume it on the saved session — unless
+            // that dead relaunch was itself a cycling attempt (cycle_pending), in which
+            // case retry it AS a cycle (retryResumeMode) instead of stranding it as a
+            // strict resume into an empty marker branch.
             process.stderr.write(`[crtrd] revive ${id} (stranded relaunch — pid never re-recorded)\n`);
-            reviveNode(id, { resume: true });
+            reviveNode(id, { resume: retryResumeMode(meta) });
             revivedThisTick.add(id); // third-pass bare double-spawn guard (Maj-4)
             return;
         }
@@ -629,9 +776,13 @@ async function handleNodeLiveness(row, now, revivedThisTick) {
         unhealthySince.delete(id);
         return;
     }
-    // Any other intent → a crash: grace-revive RESUME on the saved session.
-    // reviveNode clears pi_pid until the fresh engine re-records it, so the next
-    // tick won't re-fire on this stale pid.
+    // Any other intent → a crash: grace-revive RESUME on the saved session —
+    // unless the dead engine's last launch attempt was itself a cycling revive
+    // that never reached session_start (cycle_pending), in which case retry it AS
+    // a cycle instead of stranding it as a strict resume into an empty marker
+    // branch. reviveNode clears pi_pid until the fresh engine re-records it, so
+    // the next tick won't re-fire on this stale pid.
+    const meta = getNode(id);
     const since = unhealthySince.get(id);
     const verdict = livenessVerdict(false, since === undefined ? null : now - since);
     if (verdict === 'pending') {
@@ -641,7 +792,7 @@ async function handleNodeLiveness(row, now, revivedThisTick) {
     }
     unhealthySince.delete(id);
     process.stderr.write(`[crtrd] revive ${id} (engine dead, intent=${String(row.intent)})\n`);
-    reviveNode(id, { resume: true });
+    reviveNode(id, { resume: retryResumeMode(meta) });
     revivedThisTick.add(id); // third-pass bare double-spawn guard (Maj-4)
 }
 /** Fail loud for a drifted/broken trigger (design §6.6/Q5): wake the ARMER

package/dist/index.d.ts

@@ -17,3 +17,6 @@ export { ViewSocketClient, BrokerUnavailableError } from './clients/attach/view-
 export { encodeFrame, FrameDecoder, FrameOverflowError, CLIENT_READ_CAPS, BROKER_READ_CAPS, } from './core/runtime/broker-protocol.js';
 export type { FrameDecoderCaps, BrokerSnapshot, ClientRole, WelcomeFrame, ControlChangedFrame, AckFrame, ErrorFrame, ExtensionUIRequestFrame, BrokerToClient, HelloFrame, PromptFrame, SteerFrame, FollowUpFrame, AbortFrame, RequestControlFrame, ReleaseControlFrame, ByeFrame, ShutdownFrame, SetModelFrame, CycleModelFrame, SetThinkingLevelFrame, SetAutoRetryFrame, SetAutoCompactionFrame, CompactFrame, NewSessionFrame, SwitchSessionFrame, ForkFrame, SetSessionNameFrame, GetCommandsFrame, NavigateTreeFrame, ReloadFrame, ExportFrame, ClientToBroker, RpcExtensionUIRequest, RpcExtensionUIResponse, ExtensionUIResponseFrame, } from './core/runtime/broker-protocol.js';
 export type { SessionStats } from '@earendil-works/pi-coding-agent';
+export { general } from './core/errors.js';
+export type { CrtrError } from './core/errors.js';
+export { nowIso } from './core/fs-utils.js';

package/dist/index.js

@@ -25,3 +25,10 @@ export { readTelemetry, readContextTokens } from './core/canvas/telemetry.js';
 export { ViewSocketClient, BrokerUnavailableError } from './clients/attach/view-socket.js';
 // ── Broker wire protocol (codec + frame/protocol types) ──────────────────
 export { encodeFrame, FrameDecoder, FrameOverflowError, CLIENT_READ_CAPS, BROKER_READ_CAPS, } from './core/runtime/broker-protocol.js';
+// ── Utility exports ───────────────────────────────────────────────────────
+// Small side-effect-free helpers consumed by external callers that assemble
+// on top of crtr primitives (e.g. a guest-side process reading crtr's error
+// shape and timestamp convention). Intentionally narrow: only `general` (not
+// `CrtrError`/`notFound`/`usage`/the other error helpers) and `nowIso`.
+export { general } from './core/errors.js';
+export { nowIso } from './core/fs-utils.js';

package/dist/pi-extensions/canvas-context-intro.d.ts

@@ -20,6 +20,7 @@ interface SessionEntryLike {
 interface SessionStartCtxLike {
     sessionManager: {
         getEntries: () => SessionEntryLike[];
+        getBranch?: (fromId?: string) => SessionEntryLike[];
     };
 }
 interface CustomMessageLike {

package/dist/pi-extensions/canvas-context-intro.js

@@ -24,18 +24,23 @@
 // thing a terminal worker's bearings drop). The prose lives in
 // core/runtime/bearings.ts (shared with the promotion guidance dump).
 //
-// IDEMPOTENT across resumes, but FORK-AWARE: a `--session` relaunch restores OUR
-// conversation (whose bearings name OUR node id), so the session_start handler
-// sees it via `sessionManager.getEntries()` and skips — it never accumulates. A
-// `--fork-from` boot, by contrast, COPIES the source node's whole conversation
-// (whose bearings name the SOURCE's node id), so the handler must NOT treat that
-// inherited block as ours; it only skips when a bearings block belonging to OUR
-// node is already present (exact `details.nodeId` stamp, content-match
-// fallback), otherwise it injects ours — whose identity assertion (leading the
-// <crtr-bearings> block) reasserts the fork's identity over the inherited persona. This is ONE of two reinforcing
-// channels: spawn.ts ALSO prepends the same identity assertion to a fork's
-// kickoff prompt (the turn-triggering message), so the override does not rest on
-// a single trailing custom_message.
+// IDEMPOTENT across resumes, but FORK-AWARE and BRANCH-AWARE: the idempotency
+// scan walks only the ACTIVE BRANCH (root-first from the current leaf), not
+// every entry in the file. A `--session` relaunch that is a true resume keeps
+// the same branch, so the scan finds OUR prior bearings (named by OUR node id)
+// and skips — it never accumulates. A post-yield CYCLE roots a fresh branch (the
+// `crtr-cycle` marker), so the scan correctly finds nothing on that fresh branch
+// and injects a new intro, even though an OLDER cycle's intro still sits
+// elsewhere in the same `.jsonl`. A `--fork-from` boot COPIES the source node's
+// whole conversation onto ITS OWN branch (bearings naming the SOURCE's node id,
+// not ours), so the handler must NOT treat that inherited block as ours; it only
+// skips when a bearings block belonging to OUR node is already present on the
+// active branch (exact `details.nodeId` stamp, content-match fallback),
+// otherwise it injects ours — whose identity assertion (leading the
+// <crtr-bearings> block) reasserts the fork's identity over the inherited
+// persona. This is ONE of two reinforcing channels: spawn.ts ALSO prepends the
+// same identity assertion to a fork's kickoff prompt (the turn-triggering
+// message), so the override does not rest on a single trailing custom_message.
 //
 // COLLAPSED BY DEFAULT: a `registerMessageRenderer` keyed to our customType
 // renders the block as a single one-line stub; the full body only appears when
@@ -166,22 +171,28 @@ export function registerCanvasContextIntro(pi) {
             const nodeId = process.env['CRTR_NODE_ID'];
             if (nodeId === undefined || nodeId.trim() === '')
                 return; // not a canvas node
-            // Idempotent on RESUME, but NOT fooled by a FORK. A `--session` relaunch
-            // restores OUR conversation, whose bearings name OUR node id — skip then,
-            // so the block never accumulates. A `--fork-from` boot instead copies the
-            // SOURCE node's whole conversation (its bearings name ITS node id, not
-            // ours), so a naive "any crtr-context present?" check would suppress our
-            // own intro and let the fork inherit — and impersonate — the source. So we
-            // only skip when a bearings block belonging to OUR node is already present.
-            // Primary discriminator: the EXACT `details.nodeId` stamp (machine-
+            // Branch-aware idempotency: scan only the ACTIVE branch (root-first from
+            // the current leaf), not every entry in the file. A post-yield cycle roots a
+            // FRESH branch (the crtr-cycle marker), so scanning the whole file would
+            // find a PRIOR cycle's intro and wrongly skip injecting this cycle's own —
+            // the node's first turn would lack its crtr-context bearings entirely.
+            // Falls back to a whole-file scan only if the engine doesn't expose
+            // getBranch (older/degraded engine). Not fooled by a FORK either way: a
+            // `--fork-from` boot copies the source's whole conversation onto ITS OWN
+            // branch (bearings naming the SOURCE's node id, not ours), so a naive
+            // "any crtr-context present?" check would suppress our own intro and let
+            // the fork inherit — and impersonate — the source. So we only skip when a
+            // bearings block belonging to OUR node is already present on the scanned
+            // branch. Primary discriminator: the EXACT `details.nodeId` stamp (machine-
             // readable, copied on fork, never sent to the LLM). Fallback: a substring
             // match on the block text (our id appears in the identity line AND the
             // context-dir path `…/nodes/<nodeId>/context`) — covers legacy blocks
             // persisted before the stamp existed. Either match ⇒ this is our own
             // resume, not an inherited fork block, so skip.
-            const ours = ctx.sessionManager
-                .getEntries()
-                .some((e) => e.type === 'custom_message' &&
+            const scan = typeof ctx.sessionManager.getBranch === 'function'
+                ? ctx.sessionManager.getBranch()
+                : ctx.sessionManager.getEntries();
+            const ours = scan.some((e) => e.type === 'custom_message' &&
                 e.customType === CONTEXT_INTRO_CUSTOM_TYPE &&
                 (e.details?.nodeId === nodeId || entryText(e).includes(nodeId)));
             if (ours)

package/dist/pi-extensions/canvas-stophook.js

@@ -314,16 +314,22 @@ export function registerCanvasStophook(pi) {
             }
             // Boot / startup / resume / reload / fork → (re)bind this process to its
             // session id, record our OS pid (the daemon's broker-liveness signal), and
-            // CONFIRM any pending refresh-yield. Reaching session_start proves a fresh
-            // engine actually booted, so it is now safe to clear intent='refresh' — a
-            // refresh shuts the broker down and the daemon relaunches it FRESH, which
-            // leaves intent='refresh' set until this boot clears it (the only proof the
-            // relaunch worked; otherwise a failed relaunch would look like a success).
+            // CONFIRM any pending refresh-yield / pending cycle. Reaching session_start
+            // proves a fresh engine actually booted, so it is now safe to clear
+            // intent='refresh' — a refresh shuts the broker down and the daemon
+            // relaunches it FRESH, which leaves intent='refresh' set until this boot
+            // clears it (the only proof the relaunch worked; otherwise a failed relaunch
+            // would look like a success). Clearing `cycle_pending` here is the same
+            // proof for reviveNode's cycling-attempt marker (revive.ts) — it is always
+            // safe to clear on ANY confirmed boot (cycling, resuming, or fresh), since a
+            // pre-session_start crash-retry (crtrd.ts) only needs the flag while boot is
+            // still unconfirmed.
             const existing = getNode(nodeId);
             // Identity (session id/file) → meta; runtime (pid, intent) → atomic row setters.
             updateNode(nodeId, {
                 pi_session_id: id,
                 pi_session_file: sessionFile,
+                cycle_pending: false,
             });
             recordPid(nodeId, process.pid);
             if (existing?.intent === 'refresh')