@crouton-kit/crouter 0.3.40 → 0.3.42

package/dist/core/worktree.js

@@ -0,0 +1,158 @@
+import { existsSync, mkdirSync, rmdirSync } from 'node:fs';
+import { gitSync } from './git.js';
+import { crtrHome } from './canvas/paths.js';
+import { getNode, updateNode } from './canvas/index.js';
+export class WorktreeError extends Error {
+    code;
+    next;
+    detail;
+    constructor(code, message, next, detail) {
+        super(message);
+        this.name = 'WorktreeError';
+        this.code = code;
+        this.next = next;
+        this.detail = detail;
+    }
+}
+function runGit(cwd, args, code, next) {
+    const res = gitSync(args, cwd);
+    if (res.status !== 0) {
+        const detail = (res.stderr.trim() || res.stdout.trim()).trim();
+        throw new WorktreeError(code, `git ${args.join(' ')} failed`, next, detail);
+    }
+    return res.stdout.trim();
+}
+export function managedWorktreesRoot() {
+    return `${crtrHome()}/worktrees`;
+}
+export function managedWorktreePath(nodeId) {
+    return `${managedWorktreesRoot()}/${nodeId}`;
+}
+export function hasOpenManagedWorktree(node) {
+    return node?.managed_worktree?.state === 'open';
+}
+export function openManagedWorktreeForNode(nodeId) {
+    const node = getNode(nodeId);
+    const wt = node?.managed_worktree;
+    return wt?.state === 'open' ? wt : null;
+}
+function repoRootFor(cwd) {
+    return runGit(cwd, ['rev-parse', '--show-toplevel'], 'not_git_repo', 'Pass --cwd pointing inside a git repository.');
+}
+function requireOriginMain(repoRoot) {
+    return runGit(repoRoot, ['rev-parse', 'origin/main'], 'missing_origin_main', 'Managed worktrees land by rebasing onto origin/main. Fetch/create origin/main, then retry.');
+}
+export function createManagedWorktree(cwd, nodeId) {
+    const repoRoot = repoRootFor(cwd);
+    const baseSha = requireOriginMain(repoRoot);
+    const path = managedWorktreePath(nodeId);
+    if (existsSync(path)) {
+        throw new WorktreeError('worktree_path_exists', `managed worktree path already exists: ${path}`, 'Remove the stale path or choose a fresh node id.');
+    }
+    const branch = `crtr/${nodeId}`;
+    runGit(repoRoot, ['worktree', 'add', '-b', branch, path, 'origin/main'], 'worktree_add_failed', 'Inspect the git error, fix the repository/worktree state, then retry spawning with --worktree.');
+    return {
+        state: 'open',
+        path,
+        branch,
+        repo_root: repoRoot,
+        base_ref: 'origin/main',
+        base_sha: baseSha,
+        created: new Date().toISOString(),
+    };
+}
+function statusPorcelain(cwd) {
+    return runGit(cwd, ['status', '--porcelain'], 'status_failed', 'Inspect the worktree manually, then retry.');
+}
+function currentBranch(cwd) {
+    return runGit(cwd, ['rev-parse', '--abbrev-ref', 'HEAD'], 'branch_check_failed', 'Inspect the worktree manually, then retry.');
+}
+function gitPath(cwd, logicalPath) {
+    return runGit(cwd, ['rev-parse', '--git-path', logicalPath], 'git_path_failed', 'Inspect the worktree manually, then retry.');
+}
+export function isRebaseInProgress(cwd) {
+    return existsSync(gitPath(cwd, 'rebase-merge')) || existsSync(gitPath(cwd, 'rebase-apply'));
+}
+export function closeManagedWorktree(nodeId) {
+    const node = getNode(nodeId);
+    if (node === null) {
+        throw new WorktreeError('unknown_node', `unknown node: ${nodeId}`, 'Run this from a live node, or pass a real node id once that command supports it.');
+    }
+    const wt = openManagedWorktreeForNode(nodeId);
+    if (wt === null) {
+        throw new WorktreeError('no_managed_worktree', `node ${nodeId} has no open managed worktree`, 'Nothing to close for this node.');
+    }
+    if (!existsSync(wt.path)) {
+        throw new WorktreeError('worktree_missing', `managed worktree path is missing: ${wt.path}`, 'Ask the human with `crtr human ask` before changing node state; the checkout disappeared outside crouter.');
+    }
+    if (isRebaseInProgress(wt.path)) {
+        throw new WorktreeError('rebase_in_progress', 'this managed worktree is mid-rebase', `Resolve conflicts in ${wt.path}, run \`git rebase --continue\` there, then rerun \`crtr worktree close\`.`);
+    }
+    const dirty = statusPorcelain(wt.path);
+    if (dirty !== '') {
+        throw new WorktreeError('dirty_worktree', 'managed worktree has uncommitted changes', `Commit the work in ${wt.path} (or ask the human with \`crtr human ask\` if you do not know whether to keep it), then rerun \`crtr worktree close\`.`);
+    }
+    const branch = currentBranch(wt.path);
+    if (branch !== wt.branch) {
+        const found = branch === 'HEAD' ? 'detached HEAD' : branch;
+        throw new WorktreeError('wrong_branch', `managed worktree is not on its recorded branch (expected ${wt.branch}, found ${found})`, `Check out ${wt.branch} in ${wt.path} before closing, or ask the human with \`crtr human ask\` if you are unsure why it changed, then rerun \`crtr worktree close\`.`);
+    }
+    runGit(wt.path, ['fetch', 'origin', 'main'], 'fetch_failed', 'Network/remote state blocked landing. Ask the human with `crtr human ask` if this is not a transient git/network issue.');
+    const rebase = gitSync(['rebase', 'origin/main'], wt.path);
+    if (rebase.status !== 0) {
+        const detail = (rebase.stderr.trim() || rebase.stdout.trim()).trim();
+        throw new WorktreeError('rebase_failed', 'rebase onto origin/main did not complete', `Resolve conflicts in ${wt.path}, run \`git rebase --continue\` there, then rerun \`crtr worktree close\`. If the blocker is not mechanical, ask the human with \`crtr human ask\`.`, detail);
+    }
+    const push = gitSync(['push', 'origin', 'HEAD:main'], wt.path);
+    if (push.status !== 0) {
+        const detail = (push.stderr.trim() || push.stdout.trim()).trim();
+        throw new WorktreeError('push_main_failed', 'could not fast-forward/push origin/main from this worktree', 'Do not force-push main. Ask the human with `crtr human ask` how to land this managed worktree.', detail);
+    }
+    // The push landing IS the point of no return: persist `state: 'closed'`
+    // IMMEDIATELY, before reading the landed sha or attempting any cleanup below.
+    // Worktree removal and branch deletion are best-effort from here on — their
+    // failure is cosmetic (a stray checkout / local ref) and must never re-strand
+    // `state: 'open'` behind a dead end that permanently blocks push-final.
+    updateNode(nodeId, { managed_worktree: { ...wt, state: 'closed', closed: new Date().toISOString() } });
+    const pushedSha = runGit(wt.path, ['rev-parse', 'HEAD'], 'pushed_sha_failed', 'The branch landed and the node is already marked closed, but crouter could not read the landed commit SHA. Inspect the checkout manually to confirm the landed commit; no further close action is needed.');
+    const remove = gitSync(['worktree', 'remove', wt.path], wt.repo_root);
+    const worktreeRemoved = remove.status === 0;
+    if (worktreeRemoved && existsSync(wt.path)) {
+        // `git worktree remove` can leave the (now empty) mount dir behind; tidy it best-effort.
+        try {
+            rmdirSync(wt.path);
+        }
+        catch { /* non-empty or busy — leave it */ }
+    }
+    // wt.path IS the calling node's own pi-process cwd — a process can never chdir
+    // itself out of a directory that vanishes out from under it, so once removal
+    // deletes it every subsequent bash/chdir in this node fails permanently and the
+    // mandated post-close `crtr push final` can never run. Recreate it as an empty
+    // tombstone directory so the path still resolves; the branch is already landed
+    // and `state: 'closed'` already persisted above, so this is purely about keeping
+    // the node's cwd alive, not about worktree bookkeeping.
+    if (!existsSync(wt.path)) {
+        try {
+            mkdirSync(wt.path, { recursive: true });
+        }
+        catch { /* best-effort; leaves cwd broken only if this also fails */ }
+    }
+    const worktreeRemoveError = worktreeRemoved
+        ? undefined
+        : `local worktree checkout at ${wt.path} landed but could not be removed automatically (${(remove.stderr.trim() || remove.stdout.trim()).trim()}); run \`git -C ${wt.repo_root} worktree remove ${wt.path}\` after confirming it is safe to delete.`;
+    const branchDelete = gitSync(['branch', '-d', wt.branch], wt.repo_root);
+    const branchDeleted = branchDelete.status === 0;
+    const branchDeleteError = branchDeleted
+        ? undefined
+        : `local branch ${wt.branch} landed but could not be deleted automatically; run \`git -C ${wt.repo_root} branch -d ${wt.branch}\` after confirming it is merged.`;
+    return {
+        node_id: nodeId,
+        branch: wt.branch,
+        worktree_path: wt.path,
+        pushed_sha: pushedSha,
+        worktree_removed: worktreeRemoved,
+        ...(worktreeRemoveError !== undefined ? { worktree_remove_error: worktreeRemoveError } : {}),
+        branch_deleted: branchDeleted,
+        ...(branchDeleteError !== undefined ? { branch_delete_error: branchDeleteError } : {}),
+    };
+}

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 {