@crouton-kit/crouter 0.3.39 → 0.3.41

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 {