@crouton-kit/crouter 0.3.40 → 0.3.42

package/dist/commands/revive.js

@@ -3,8 +3,10 @@
 // Bypasses the daemon: directly relaunches the broker engine for a node that is
 // done, idle, or dead. Default behavior resumes the saved pi conversation by its
 // absolute session-file path (--session <path>) when that .jsonl still exists,
-// else falls through to a fresh launch; pass --fresh to force a clean pi session
-// against the context dir.
+// else falls through to a fresh launch. `--fresh` skips the true resume: if the
+// `.jsonl` already exists it CYCLES in place instead (same file, a fresh
+// `crtr-cycle` branch — `resumed:false`), and only starts a genuinely clean
+// session when no `.jsonl` exists yet (also `resumed:false`).
 //
 // `--all` sweeps EVERY disconnected node (engine not running, resumable session)
 // in one shot — the recovery for a reboot / mass-crash / daemon-down-a-while
@@ -19,6 +21,22 @@ import { getNode, fullName } from '../core/canvas/index.js';
 import { isPidAlive } from '../core/canvas/pid.js';
 import { readFault } from '../core/runtime/fault.js';
 import { isBusy } from '../core/runtime/busy.js';
+import { faultNeedsYou } from '../core/canvas/status-glyph.js';
+/** --now eligibility for a live, non-busy fault: a daemon-owned AUTO retry
+ *  (kick it early instead of waiting out the schedule), or any fault the
+ *  canvas dashboard flags "needs you" (`faultNeedsYou`, status-glyph.ts) — the
+ *  disposition that otherwise has NO sanctioned recovery verb (issue #115).
+ *  Both are scoped to `pi→provider`: refuses a client-owned auto retry
+ *  (redialing) already in flight, and refuses any OTHER link — notably a
+ *  `daemon→node` wedge fault, which --now can't clear (SIGTERM doesn't touch
+ *  the runaway subprocess; see `wedged-child-on-runaway-bash`). */
+export function isNowEligibleFault(fault) {
+    if (fault === null || fault.link !== 'pi→provider')
+        return false;
+    if (faultNeedsYou(fault))
+        return true;
+    return fault.retry.by === 'daemon';
+}
 // ---------------------------------------------------------------------------
 // revive node
 // ---------------------------------------------------------------------------
@@ -50,7 +68,7 @@ export const reviveLeaf = defineLeaf({
                 type: 'bool',
                 required: false,
                 default: false,
-                constraint: 'When set, start a clean pi session (no --session). Default: resume the saved conversation. Ignored with --all (which always resumes).',
+                constraint: 'When set, do NOT do a true resume. If the node already has a session `.jsonl`, this instead CYCLES it in place — reuses that SAME file, resets the tree leaf, and roots a fresh `crtr-cycle` branch (a clean-context restart that still carries the file\'s history, output `resumed:false`). Only when no `.jsonl` exists yet does this start a genuinely brand-new session (also `resumed:false`). Default (no --fresh): a true resume — replays the existing `.jsonl` as-is (`resumed:true`). Ignored with --all (which always resumes).',
             },
             {
                 kind: 'flag',
@@ -58,7 +76,7 @@ export const reviveLeaf = defineLeaf({
                 type: 'bool',
                 required: false,
                 default: false,
-                constraint: 'On-demand kick of an active-fault node (parked on a provider-owned fault, broker still alive). Its broker pid is alive, so an ordinary revive no-ops (double-launch guard) — --now SIGTERMs the live broker instead, so the daemon\'s crash→grace→resume path brings it back in ~20s instead of waiting out the auto-recovery grace. Only valid for a node that has a live daemon-owned auto provider fault and a live pid. Mutually exclusive with --all/--fresh.',
+                constraint: 'On-demand kick of an active-fault node (parked on a `pi→provider` fault, broker still alive). Its broker pid is alive, so an ordinary revive no-ops (double-launch guard) — --now SIGTERMs the live broker instead, so the daemon\'s crash→grace→resume path brings it back in ~20s. Valid for a live `pi→provider` fault that is either a daemon-owned auto retry (kicks it early), or ANY fault the canvas dashboard flags "needs you" (e.g. exhausted retries, an auth fault you just fixed) — that disposition otherwise has no recovery verb. Mutually exclusive with --all/--fresh.',
             },
             // --force is a DELIBERATELY UNDOCUMENTED confirmation gate for --all (hidden
             // from -h; see FlagParam.hidden). Silas's intent (2026-06-13): a mass revive
@@ -80,7 +98,7 @@ export const reviveLeaf = defineLeaf({
         output: [
             { name: 'window', type: 'string', required: false, constraint: 'Always null — the revived broker is headless and opens no tmux window. Kept for caller back-compat.' },
             { name: 'session', type: 'string', required: false, constraint: 'The node\'s last live location session, or null — the headless broker has no tmux session of its own.' },
-            { name: 'resumed', type: 'boolean', required: false, constraint: 'True when pi was told to --session the saved conversation. Single-node revive only.' },
+            { name: 'resumed', type: 'boolean', required: false, constraint: 'True ONLY for a true resume (the existing `.jsonl` replayed as-is). False for a --fresh revive, whether that landed as an in-place CYCLE (an existing `.jsonl` reused with a fresh `crtr-cycle` branch — pi is still told --session, but this is not a resume) or a genuinely fresh launch (no `.jsonl` existed). Single-node revive only.' },
             { name: 'ready', type: 'boolean', required: false, constraint: 'True when the revived broker\'s view.sock accepted a connection before return — the node is immediately attachable/drivable. Single-node revive only.' },
             { name: 'mode', type: 'string', required: false, constraint: '"preview" (the --all candidate list, nothing launched), "revived" (the --all sweep ran), or absent for a single-node revive.' },
             { name: 'candidates', type: 'string', required: false, constraint: '--all preview: the node ids that WOULD be revived (newline-joined). Empty when none are disconnected.' },
@@ -145,8 +163,8 @@ export const reviveLeaf = defineLeaf({
         // reviveNode would no-op the double-launch guard) — SIGTERM it so the daemon's
         // ordinary crash→grace→resume path recovers it on the saved session, the same
         // thing the daemon does at the auto-recovery grace, just on demand. Gated on
-        // a live pid and a daemon-owned provider fault so it can't be used to nuke a
-        // healthy node.
+        // a live pid and an eligible pi→provider fault (`isNowEligibleFault` above) so
+        // it can't be used to nuke a healthy node.
         if (now) {
             const pid = meta.pi_pid;
             const stall = readFault(nodeId);
@@ -157,11 +175,11 @@ export const reviveLeaf = defineLeaf({
                     next: 'Revive a dormant node with `crtr canvas revive ' + nodeId + '` (no --now).',
                 });
             }
-            if (stall === null || stall.link !== 'pi→provider' || stall.retry.by !== 'daemon' || stall.retry.disposition !== 'auto') {
+            if (!isNowEligibleFault(stall)) {
                 throw new InputError({
                     error: 'not_hanging',
-                    message: `${nodeId} is live but not an active daemon-owned provider fault — --now refuses to SIGTERM a healthy node.`,
-                    next: 'Use --now only on a node the canvas shows as hanging (⚠). For a routine relaunch, omit --now.',
+                    message: `${nodeId} is live but has no pi→provider fault eligible for --now (either healthy, or a client-owned retry / non-provider fault already being handled elsewhere) — --now refuses to SIGTERM a node that isn't stuck on a kickable provider fault.`,
+                    next: 'Use --now only on a node the canvas shows as hanging (⚠) with a `pi→provider` fault. For a routine relaunch, omit --now.',
                 });
             }
             // The daemon never kills a BUSY engine (its verdict paths all return 'leave'

package/dist/commands/sys/__tests__/setup-core.test.js

@@ -0,0 +1,19 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync } from 'node:fs';
+import { resolveBundledPiCliPath } from '../../../core/runtime/pi-cli.js';
+test('resolveBundledPiCliPath uses crouter bundled pi instead of a standalone pi on PATH', () => {
+    const prevPath = process.env.PATH;
+    process.env.PATH = '';
+    try {
+        const cliPath = resolveBundledPiCliPath();
+        assert.equal(existsSync(cliPath), true);
+        assert.match(cliPath, /@earendil-works[\/]pi-coding-agent[\/]dist[\/]cli\.js$/);
+    }
+    finally {
+        if (prevPath === undefined)
+            delete process.env.PATH;
+        else
+            process.env.PATH = prevPath;
+    }
+});

package/dist/commands/sys/doctor.js

@@ -71,7 +71,7 @@ function faultRemediation(fault) {
         auth: 're-authenticate',
         protocol: 'fix the protocol mismatch',
         other: 'fix the underlying issue',
-        wedged: 'read `crtr memory read wedged-child-on-runaway-bash` and, if a runaway subprocess is to blame, kill the subprocess (not the node)',
+        wedged: 'read `crtr memory read wedged-child-on-runaway-bash` — if a runaway subprocess is to blame, kill it (not the node); if the broker had no subprocess, the daemon already SIGTERM-kicked it to resume on its own (recheck node status; nudge it if it came back idle)',
     };
     const progress = fault.retry.disposition === 'auto'
         ? fault.retry.by === 'client'

package/dist/commands/sys/setup-core.js

@@ -4,6 +4,7 @@ import { homedir } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
 import { builtinPiPackageDir } from '../../core/scope.js';
 import { readJsonIfExists } from '../../core/fs-utils.js';
+import { resolveBundledPiCliPath } from '../../core/runtime/pi-cli.js';
 const PACKAGE_COPY = {
     'crtr-extensions': {
         name: 'pi-crtr-extensions',
@@ -285,8 +286,8 @@ function runShellCommand(command) {
         throw new Error(`command failed: ${command}`);
     }
 }
-function installPiPackage(source) {
-    const result = spawnSync('pi', ['install', source], { stdio: 'inherit' });
+function installPiPackage(source, piCliPath = resolveBundledPiCliPath()) {
+    const result = spawnSync(process.execPath, [piCliPath, 'install', source], { stdio: 'inherit' });
     if (result.status !== 0) {
         throw new Error(`pi install failed: ${source}`);
     }

package/dist/commands/sys/setup.js

@@ -506,7 +506,7 @@ export const sysSetupLeaf = defineLeaf({
         outputKind: 'object',
         effects: [
             'Opens a pi-tui wizard that collects companion package installs, system dependency installs, and an Exa API key.',
-            'Runs pi installs for the selected bundled packages, writes EXA_API_KEY to ~/.crouter/exa.key when provided, and prints a summary.',
+            'Runs the bundled pi CLI to install the selected companion packages, writes EXA_API_KEY to ~/.crouter/exa.key when provided, and prints a summary.',
         ],
     },
     run: async () => {

package/dist/commands/worktree.d.ts

@@ -0,0 +1,2 @@
+import { type BranchDef } from '../core/command.js';
+export declare function registerWorktree(): BranchDef;

package/dist/commands/worktree.js

@@ -0,0 +1,94 @@
+import { defineBranch, defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { closeManagedWorktree, WorktreeError } from '../core/worktree.js';
+function requireCallerNode() {
+    const id = process.env['CRTR_NODE_ID'];
+    if (id === undefined || id.trim() === '') {
+        throw new InputError({
+            error: 'no_node_context',
+            message: 'CRTR_NODE_ID is not set — worktree commands run inside a canvas node.',
+            next: 'Run this command from a node process spawned by the runtime.',
+        });
+    }
+    return id.trim();
+}
+function mapWorktreeError(err) {
+    if (!(err instanceof WorktreeError))
+        return null;
+    return new InputError({
+        error: err.code,
+        message: err.message,
+        ...(err.detail !== undefined ? { received: err.detail } : {}),
+        next: err.next,
+    });
+}
+const worktreeClose = defineLeaf({
+    name: 'close',
+    description: 'land and close the current node-managed worktree',
+    whenToUse: 'you are inside the node that owns an open managed worktree and are ready to rebase it onto origin/main, push it to main, and (best-effort) remove the worktree and delete the branch before finishing',
+    help: {
+        name: 'worktree close',
+        summary: 'land and close the current node-managed worktree',
+        params: [],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The caller node id whose managed worktree was closed.' },
+            { name: 'branch', type: 'string', required: true, constraint: 'The worktree branch that was fast-forwarded into main.' },
+            { name: 'pushed_sha', type: 'string', required: true, constraint: 'The landed commit SHA that was pushed to origin/main.' },
+            { name: 'worktree_path', type: 'string', required: true, constraint: 'The managed worktree path that was closed (best-effort removed; see worktree_removed).' },
+            { name: 'worktree_removed', type: 'boolean', required: true, constraint: 'True when the worktree directory was removed; false means the push still landed (the close is done) but automatic removal failed and needs a manual follow-up.' },
+            { name: 'worktree_remove_error', type: 'string', required: false, constraint: 'Present only when worktree_removed is false: the manual cleanup command to run.' },
+            { name: 'branch_deleted', type: 'boolean', required: true, constraint: 'True when the local branch was deleted; false means the push still landed (the close is done) but the local branch cleanup failed and needs a manual follow-up.' },
+            { name: 'branch_delete_error', type: 'string', required: false, constraint: 'Present only when branch_deleted is false: the manual cleanup command to run.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Fetches origin/main, rebases the worktree onto it, fast-forwards origin/main, marks the node-managed worktree closed, then attempts (best-effort) to remove the worktree and delete the local branch.',
+        ],
+    },
+    run: async () => {
+        const nodeId = requireCallerNode();
+        try {
+            return { ...closeManagedWorktree(nodeId) };
+        }
+        catch (err) {
+            const mapped = mapWorktreeError(err);
+            if (mapped !== null)
+                throw mapped;
+            throw err;
+        }
+    },
+    render: (r) => {
+        const branch = String(r['branch'] ?? '');
+        const sha = String(r['pushed_sha'] ?? '');
+        const path = String(r['worktree_path'] ?? '');
+        let base = `Managed worktree landed — branch ${branch} pushed as ${sha}.`;
+        const notes = [];
+        if (r['worktree_removed'] === false) {
+            notes.push(String(r['worktree_remove_error'] ?? `worktree checkout at ${path} could not be removed automatically.`));
+        }
+        else {
+            base += ` Worktree removed at ${path}.`;
+        }
+        if (r['branch_deleted'] === false) {
+            notes.push(String(r['branch_delete_error'] ?? `local branch ${branch} could not be deleted automatically.`));
+        }
+        if (notes.length > 0)
+            return `${base} Note: ${notes.join(' ')}`;
+        return base;
+    },
+});
+export function registerWorktree() {
+    return defineBranch({
+        name: 'worktree',
+        rootEntry: {
+            concept: 'crouter-managed git worktrees tied to node lifecycle',
+            desc: 'close a node-owned managed worktree',
+            useWhen: 'landing completed work from inside the node that owns the worktree',
+        },
+        help: {
+            name: 'worktree',
+            summary: 'manage a node-owned git worktree',
+        },
+        children: [worktreeClose],
+    });
+}

package/dist/core/__tests__/boot.test.js

@@ -1,6 +1,6 @@
 // Run with: node --import tsx/esm --test src/core/__tests__/boot.test.ts
 //
-// BUG LOCKED (Hearth P6 Bug B — a sandbox/VM destroy+recreate, or a host
+// BUG LOCKED (a sandbox/VM destroy+recreate, or a host
 // reboot, leaves stale `pi_pid` values in the durable canvas.db; a pid-reuse
 // collision on the fresh boot can fool `isPidAlive` into reading a dead
 // broker as alive, wedging the node forever). reconcileBootLiveness is the
@@ -61,11 +61,11 @@ test('bootChanged: no persisted history is never a change (never clears a genuin
 test('bootChanged: same kernel boot_id is the SAME boot (daemon restart, no reboot)', () => {
     assert.equal(bootChanged(ident('boot-A', 1_000_000 + 5_000), ident('boot-A', 1_000_000)), false, 'identical boot_id — same boot regardless of epoch');
 });
-test('bootChanged: a DIFFERENT boot_id under 60s wall-delta is still detected (Major-2 regression)', () => {
+test('bootChanged: a DIFFERENT boot_id under 60s wall-delta is still detected', () => {
     // A genuinely fast reboot/recreate: boot B starts only 42s after boot A
-    // (Hearth\'s measured recreate window), well inside the 60s wall tolerance.
+    // (a measured real-world recreate window), well inside the 60s wall tolerance.
     // The exact kernel boot_id catches it with NO reliance on the wall-clock
-    // window — the case the old epoch-only compare false-negatived.
+    // window — boot_id is the primary signal, not wall time.
     assert.equal(bootChanged(ident('boot-B', 1_000_000 + 42_000), ident('boot-A', 1_000_000)), true, 'distinct boot_id 42s apart — a real quick recreate, detected');
 });
 test('bootChanged: same boot_id with a huge epoch jump is NOT a boot change (NTP step within a boot)', () => {

package/dist/core/__tests__/canvas.test.js

@@ -60,6 +60,20 @@ test('updateNode merges meta and re-indexes the row', () => {
     // unspecified fields preserved
     assert.equal(getNode('a')?.kind, 'general');
 });
+// Regression: cycle_pending is an IDENTITY field (meta.json-only, no db
+// column — like pi_session_file) written by reviveNode/canvas-stophook and
+// read back by the daemon's retry sites. writeMeta only persists keys listed
+// in IDENTITY_KEYS; if cycle_pending is missing from that whitelist, updateNode
+// silently drops it and getNode reads back undefined, so retryResumeMode
+// always falls back to strict resume (the exact bug this guards against).
+test('cycle_pending survives the updateNode/getNode meta.json round-trip', () => {
+    createNode(node('a'));
+    assert.equal(getNode('a')?.cycle_pending, undefined); // never set
+    updateNode('a', { cycle_pending: true });
+    assert.equal(getNode('a')?.cycle_pending, true);
+    updateNode('a', { cycle_pending: false });
+    assert.equal(getNode('a')?.cycle_pending, false);
+});
 test('setStatus updates both meta and row', () => {
     createNode(node('a'));
     setStatus('a', 'done');
@@ -139,13 +153,11 @@ test('recordSpawn writes the audit-only spawned_by edge', () => {
     assert.equal(subscriptionsOf('child').length, 0);
     assert.equal(subscribersOf('parent').length, 0);
 });
-// --- Regression: Hearth M0 cold-boot 0-byte meta.json -----------------------
-// A bare write-temp-then-rename WITHOUT fsync left meta.json 0-byte on the guest's
-// durable NFS home after a sandbox recreate (the open inode is silly-renamed and the
-// new content never flushed). Cold-boot's `canvas rebuild-index` + `canvas revive`
-// then JSON.parse('') → "Unexpected end of JSON input" → the chain dies → guest
-// daemon-only, no web on 7878. Fix: writeMeta fsyncs temp+parent dir (durable), and
-// readMeta/rebuildIndex tolerate an empty/corrupt meta as MISSING instead of throwing.
+// --- Durability contract: meta.json is durable and never truncated -------
+// writeMeta uses atomic rename with fsync on both the temp file and parent
+// directory to ensure atomicity and durability. readMeta/rebuildIndex tolerate
+// an empty/corrupt meta.json as MISSING (returning null) rather than throwing,
+// gracefully handling rare disk/NFS anomalies without breaking recovery.
 test('writeMeta produces a durable, non-empty, atomically-named meta.json', () => {
     createNode(node('a'));
     const p = nodeMetaPath('a');

package/dist/core/__tests__/child-followup.test.js

@@ -42,6 +42,7 @@ after(() => {
     delete process.env['CRTR_HOME'];
 });
 const STD = 'Two moves only';
+const DEDUPE = 'duplicate';
 const YIELD = 'crtr node yield';
 test('readContextTokens: prefers context_tokens, falls back to tokens_in, else null', () => {
     createNode(node('n1'));
@@ -59,25 +60,34 @@ test('childFollowUp: orchestrator past 100k → yield nudge with rounded k', ()
     const msg = childFollowUp('orch');
     assert.match(msg, /crtr node yield/);
     assert.match(msg, /~135k/); // rounded
+    assert.match(msg, new RegExp(DEDUPE));
     assert.doesNotMatch(msg, /Two moves only/);
 });
 test('childFollowUp: orchestrator below 100k → standard road sign', () => {
     createNode(node('orch', { mode: 'orchestrator' }));
     writeTelemetry('orch', { context_tokens: 80_000 });
-    assert.match(childFollowUp('orch'), new RegExp(STD));
-    assert.doesNotMatch(childFollowUp('orch'), new RegExp(YIELD));
+    const msg = childFollowUp('orch');
+    assert.match(msg, new RegExp(STD));
+    assert.match(msg, new RegExp(DEDUPE));
+    assert.doesNotMatch(msg, new RegExp(YIELD));
 });
 test('childFollowUp: base spawner past 100k → standard (only orchestrators yield)', () => {
     createNode(node('base', { mode: 'base' }));
     writeTelemetry('base', { context_tokens: 150_000 });
-    assert.match(childFollowUp('base'), new RegExp(STD));
+    const msg = childFollowUp('base');
+    assert.match(msg, new RegExp(STD));
+    assert.match(msg, new RegExp(DEDUPE));
 });
 test('childFollowUp: orchestrator with no telemetry → standard (unknown size)', () => {
     createNode(node('orch', { mode: 'orchestrator' }));
-    assert.match(childFollowUp('orch'), new RegExp(STD));
+    const msg = childFollowUp('orch');
+    assert.match(msg, new RegExp(STD));
+    assert.match(msg, new RegExp(DEDUPE));
 });
 test('childFollowUp: missing / undefined spawner → standard', () => {
     assert.match(childFollowUp(undefined), new RegExp(STD));
     assert.match(childFollowUp(''), new RegExp(STD));
-    assert.match(childFollowUp('ghost'), new RegExp(STD)); // no such node
+    const msg = childFollowUp('ghost');
+    assert.match(msg, new RegExp(STD)); // no such node
+    assert.match(msg, new RegExp(DEDUPE));
 });

package/dist/core/__tests__/daemon-boot.test.js

@@ -12,7 +12,7 @@ import { superviseTick, readPidfile } from '../../daemon/crtrd.js';
 import { verifyDaemonStartup } from '../../daemon/manage.js';
 import { waitForBrokerViewSocket } from '../runtime/placement.js';
 import { viewSocketPath } from '../canvas/paths.js';
-import { signBrandedHostArtifacts, brandedHostWorks } from '../runtime/branded-host.js';
+import { signBrandedHostArtifacts, brandedHostWorks, codesignIdentitiesForBrandedHost } from '../runtime/branded-host.js';
 import { markBusy, clearBusy } from '../runtime/busy.js';
 let home;
 function node(id, over = {}) {
@@ -301,6 +301,11 @@ test('signBrandedHostArtifacts signs the copied libnode before the branded binar
     signBrandedHostArtifacts('/tmp/crouter', '/tmp/libnode.dylib', (path) => signed.push(path));
     assert.deepEqual(signed, ['/tmp/libnode.dylib', '/tmp/crouter']);
 });
+test('codesignIdentitiesForBrandedHost prefers configured or discovered identities and otherwise ad-hoc signs', () => {
+    assert.deepEqual(codesignIdentitiesForBrandedHost({ configured: 'Developer ID Application: Example', discovered: 'Apple Development: Local' }), ['Developer ID Application: Example']);
+    assert.deepEqual(codesignIdentitiesForBrandedHost({ discovered: 'Apple Development: Local' }), ['Apple Development: Local']);
+    assert.deepEqual(codesignIdentitiesForBrandedHost(), ['-']);
+});
 test('brandedHostWorks health-checks if a binary is executable', () => {
     // Issue #102: the branded host binary can be corrupted or killed by macOS
     // before exec, causing spawn() to fail silently. The health-check detects this.

package/dist/core/__tests__/daemon-wedge.test.js

@@ -12,7 +12,7 @@
 // fires on its own (fails toward 'pending', not 'wedged').
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { wedgeVerdict, WEDGE_QUIET_MS, WEDGE_CPU_MAX_PERCENT, sumTreeCpu } from '../../daemon/crtrd.js';
+import { wedgeVerdict, WEDGE_QUIET_MS, WEDGE_CPU_MAX_PERCENT, sumTreeCpu, treeHasDescendants } from '../../daemon/crtrd.js';
 test('wedgeVerdict: a node whose turn already ended is never wedged, regardless of the other signals', () => {
     assert.equal(wedgeVerdict({ busy: false, quietForMs: null, cpuPercent: null }), 'leave');
     assert.equal(wedgeVerdict({ busy: false, quietForMs: 10 * 60 * 60_000, cpuPercent: 0 }), 'leave');
@@ -85,3 +85,20 @@ test('sumTreeCpu: malformed/blank lines are skipped; empty output returns null',
     assert.equal(sumTreeCpu('', 100), null);
     assert.equal(sumTreeCpu('   \n  \n', 100), null);
 });
+// ---------------------------------------------------------------------------
+// treeHasDescendants (pure) — issue #119: the broker-alone case has no
+// subprocess to kill, so remediation must branch on this instead of assuming
+// a runaway child always exists.
+// ---------------------------------------------------------------------------
+test('treeHasDescendants: broker alone in its own tree — nothing to kill', () => {
+    const ps = ['  100     1  0.0'].join('\n');
+    assert.equal(treeHasDescendants(ps, 100), false);
+});
+test('treeHasDescendants: a child present — a subprocess to kill', () => {
+    const ps = ['  100     1  0.0', '  200   100  0.0'].join('\n');
+    assert.equal(treeHasDescendants(ps, 100), true);
+});
+test('treeHasDescendants: root pid absent from the ps output returns null (can\'t tell)', () => {
+    const ps = ['  200     1  0.0'].join('\n');
+    assert.equal(treeHasDescendants(ps, 100), null);
+});

package/dist/core/__tests__/fault-classifier.test.js

@@ -0,0 +1,30 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/fault-classifier.test.ts
+//
+// Issue #94 — a fatal provider AUTH fault (a dead OAuth grant) must classify as
+// kind 'auth' + disposition 'fatal', NOT 'other'. The stophook hands `classify`
+// a raw provider error STRING (not an HTTP object), so the text branch alone
+// has to recognise auth — otherwise `invalid_grant` mislabelled as 'other' and
+// the canvas said "other · needs you" instead of "auth · needs you". Both are
+// fatal, but the taxonomy must name the cause so the notice can say re-login.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { classify } from '../fault-classifier.js';
+test('invalid_grant text classifies as fatal auth (issue #94)', () => {
+    const c = classify('pi→provider', 'Anthropic token refresh failed: invalid_grant');
+    assert.equal(c.kind, 'auth');
+    assert.equal(c.disposition, 'fatal');
+});
+test('"refresh token not found or invalid" is auth, not a transient connection blip', () => {
+    const c = classify('pi→provider', 'Refresh token not found or invalid');
+    assert.equal(c.kind, 'auth', 'must not fall into the not-found/connection branch');
+    assert.equal(c.disposition, 'fatal');
+});
+test('the auth branch does not steal transient rate-limit / overloaded errors', () => {
+    assert.equal(classify('pi→provider', 'rate limit exceeded (429)').kind, 'rate-limit');
+    assert.equal(classify('pi→provider', 'Overloaded: server busy (529)').kind, 'overloaded');
+    assert.equal(classify('pi→provider', 'ECONNRESET while streaming').kind, 'connection');
+});
+test('HTTP 401/403 objects still classify as auth (unchanged path)', () => {
+    assert.equal(classify('pi→provider', { status: 401, statusText: 'Unauthorized' }).kind, 'auth');
+    assert.equal(classify('pi→provider', { status: 403 }).kind, 'auth');
+});

package/dist/core/__tests__/fixtures/fake-engine.d.ts

@@ -17,6 +17,19 @@ export declare class SessionManager {
     static open(path: string): SessionManager;
     getSessionId(): string;
     getSessionFile(): string;
+    private leafId;
+    /** Cycling support (crtr-cycle marker) — mirrors the real SDK's getLeafId/
+     *  resetLeaf/appendCustomEntry just enough that `buildBrokerSession`'s cycling
+     *  branch (broker.ts) doesn't throw. The fake has no real cross-boot tree at
+     *  this point (FakeSession builds a fresh SessionTree every boot regardless),
+     *  so these are recording stubs, not a faithful branch model —
+     *  cycleAwareMessages already degrades to single-cycle passthrough for a
+     *  session manager without getEntries/getBranch (never implemented on the
+     *  fake), so multi-cycle REPLAY is out of scope for the fixture; only "does
+     *  not crash" is in scope. */
+    getLeafId(): string | null;
+    resetLeaf(): void;
+    appendCustomEntry(_customType: string, _data?: unknown): string;
 }
 type Handler = (ev: unknown, ctx: unknown) => void | Promise<void>;
 interface BindExtensionsOpts {

package/dist/core/__tests__/fixtures/fake-engine.js

@@ -100,6 +100,26 @@ export class SessionManager {
     getSessionFile() {
         return this.sessionFile;
     }
+    leafId = null;
+    /** Cycling support (crtr-cycle marker) — mirrors the real SDK's getLeafId/
+     *  resetLeaf/appendCustomEntry just enough that `buildBrokerSession`'s cycling
+     *  branch (broker.ts) doesn't throw. The fake has no real cross-boot tree at
+     *  this point (FakeSession builds a fresh SessionTree every boot regardless),
+     *  so these are recording stubs, not a faithful branch model —
+     *  cycleAwareMessages already degrades to single-cycle passthrough for a
+     *  session manager without getEntries/getBranch (never implemented on the
+     *  fake), so multi-cycle REPLAY is out of scope for the fixture; only "does
+     *  not crash" is in scope. */
+    getLeafId() {
+        return this.leafId;
+    }
+    resetLeaf() {
+        this.leafId = null;
+    }
+    appendCustomEntry(_customType, _data) {
+        this.leafId = `fake-cycle-${randomUUID().slice(0, 8)}`;
+        return this.leafId;
+    }
 }
 // ---------------------------------------------------------------------------
 // AgentSessionEvent stream synthesis (T8 / G1, G3, G4, G8). The fake emits a

package/dist/core/__tests__/full/spike-harness.test.js

@@ -11,7 +11,8 @@
 // canvas transitions.
 //
 // Milestones (de-risk order):
-//   1. SEAM      — piCommand substitutes CRTR_PI_BINARY only when set (pure unit).
+//   1. SEAM      — piCommand execs the bundled pi CLI by default, substitutes
+//                  CRTR_PI_BINARY only when set (pure unit).
 //   2. ROUND-TRIP— real `node new --headless` → real broker boots with CRTR_NODE_ID
 //                  + the -e canvas extensions intact (GO/NO-GO).
 //   3. REAL HOOKS— the broker loads the real stophook: session_start captures
@@ -41,7 +42,8 @@
 import { test, before, after } from 'node:test';
 import assert from 'node:assert/strict';
 import { createHarness } from '../helpers/harness.js';
-import { piCommand } from '../../runtime/placement.js';
+import { piCommand, shellQuote } from '../../runtime/placement.js';
+import { bundledPiCommandForShell } from '../../runtime/pi-cli.js';
 import { CANVAS_EXTENSIONS } from '../../runtime/launch.js';
 let h;
 let root;
@@ -56,13 +58,14 @@ after(async () => {
 // ===========================================================================
 // MILESTONE 1 — the CRTR_PI_BINARY seam (pure unit; no boot, no tmux).
 // ===========================================================================
-test('M1 seam: piCommand exec\'s `pi` when CRTR_PI_BINARY is unset, substitutes when set', () => {
+test('M1 seam: piCommand execs the bundled pi CLI when CRTR_PI_BINARY is unset, substitutes when set', () => {
     const saved = process.env['CRTR_PI_BINARY'];
     try {
         delete process.env['CRTR_PI_BINARY'];
+        const bundled = bundledPiCommandForShell(shellQuote);
         const unset = piCommand(['-e', '/abs/ext.ts', '-n', 'label']);
-        assert.equal(unset, "pi '-e' '/abs/ext.ts' '-n' 'label'", 'unset → identical to exec pi');
-        assert.ok(unset.startsWith('pi '), 'unset → leads with the literal pi binary');
+        assert.equal(unset, `${bundled} '-e' '/abs/ext.ts' '-n' 'label'`, 'unset → identical to exec\'ing the bundled pi CLI');
+        assert.ok(unset.startsWith(bundled), 'unset → leads with the resolved bundled-pi command');
         process.env['CRTR_PI_BINARY'] = '/tmp/fake-pi';
         const set = piCommand(['-e', '/abs/ext.ts']);
         assert.ok(set.startsWith('/tmp/fake-pi '), 'set → leads with the substituted binary');

package/dist/core/__tests__/grace-clock.test.js

@@ -34,7 +34,22 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
 import { createHarness } from './helpers/harness.js';
-import { isPidAlive } from '../../daemon/crtrd.js';
+import { isPidAlive, retryResumeMode } from '../../daemon/crtrd.js';
+// ===========================================================================
+// retryResumeMode (pure) — a crash-retry of a dead/stranded engine retries AS
+// A CYCLE (resume:false) when the dead attempt's own launch was itself a
+// cycling revive that never reached session_start (cycle_pending), and
+// resumes STRICTLY (resume:true) otherwise. See canvas.test.ts's
+// updateNode/getNode round-trip for the companion guarantee that cycle_pending
+// actually survives the meta.json persistence the daemon reads it back from.
+// ===========================================================================
+test('retryResumeMode: cycle_pending=true retries as a cycle, everything else resumes strictly', () => {
+    assert.equal(retryResumeMode({ cycle_pending: true }), false, 'a pending cycling attempt retries AS a cycle');
+    assert.equal(retryResumeMode({ cycle_pending: false }), true, 'cycle_pending=false resumes strictly');
+    assert.equal(retryResumeMode({ cycle_pending: null }), true, 'cycle_pending=null resumes strictly');
+    assert.equal(retryResumeMode({}), true, 'cycle_pending undefined resumes strictly');
+    assert.equal(retryResumeMode(null), true, 'no meta at all resumes strictly');
+});
 // A pid that is reaped (dead) by the time spawnSync returns — the "dead but
 // supervised" pid the grace path judges.
 function deadPid() {
@@ -103,7 +118,8 @@ test('grace clock: a dead-pi broker does NOT revive within REVIVE_GRACE_MS, but
             assert.equal(b.cycles ?? 0, 1, 'past REVIVE_GRACE_MS: the dead pi is revived → cycles bumped to 1');
             assert.equal(b.status, 'active', 'B active after the grace-window revive (transition(revive))');
             assert.equal(b.intent ?? null, null, 'intent cleared by the revive');
-            assert.equal(b.pi_pid ?? null, null, 'pi_pid cleared by the window-backed revive (clearPid)');
+            assert.notEqual(b.pi_pid, dead, 'pi_pid no longer the stale dead pid — the revive records the fresh broker pid immediately');
+            assert.equal(b.pi_pid == null ? false : b.pi_pid > 0, true, 'revive leaves no pid=null boot window for the daemon to false-crash (cc2c754)');
         }
     }
     finally {