@crouton-kit/crouter 0.3.33 → 0.3.34

package/dist/core/__tests__/full/cascade-close.test.js

@@ -1,10 +1,10 @@
 // Run with: node --import tsx/esm --test src/core/__tests__/cascade-close.test.ts
 //
 // CASCADE CLOSE + exclusive-subtree ownership — a FAITHFUL integration test of
-// `crtr node close` on a MIDDLE node, driven through the REAL CLI against a REAL
+// `crtr node lifecycle close` on a MIDDLE node, driven through the REAL CLI against a REAL
 // isolated tmux session with REAL fake-pi vehicles in REAL panes, asserting off
 // the canvas data layer and checked against the state-model ORACLE
-// (state-model.md §4 `node close`, §5 cascade-close ownership, invariant 3,
+// (state-model.md §4 `node lifecycle close`, §5 cascade-close ownership, invariant 3,
 // ambiguity A5).
 //
 // WHY this exists alongside the unit `close.test.ts`: that test exercises
@@ -32,11 +32,11 @@
 //     └── S                sideways sibling subtree — MUST survive
 //         └── G
 //
-//   close(B) ⇒ exclusive subtree {B,C,D,E} reaped; A,S,G untouched.
+//   close(B) ⇒ exclusive subtree {B,C,D,E} canceled; A,S,G untouched.
 //
 // CRITICAL DELIVERABLE (ambiguity A5): the EXACT terminal status a cascade-
-// reaped descendant receives under `node close`. CURRENT behavior, asserted
-// end-to-end below: status === 'canceled', intent === null (cleared) — for the
+// closed descendant receives under `node lifecycle close`. With the fixtures made
+// non-empty below: status === 'canceled', intent === null (cleared) — for the
 // cascade ROOT and EVERY descendant alike (`transition(id,'cancel')`,
 // close.ts → lifecycle.ts cancel row: status='canceled', intent=null, from '*').
 // This differs from the ancestor-RESET path (`reapDescendants` → `reap` → 'done')
@@ -52,12 +52,18 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { createHarness, hasTmux } from '../helpers/harness.js';
 import { isPidAlive } from '../../canvas/pid.js';
 function sessionExists(session) {
     return spawnSync('tmux', ['has-session', '-t', session], { stdio: 'ignore' }).status === 0;
 }
-test('cascade close: middle-node close reaps EXACTLY its subtree (canceled), ancestor + sideways untouched, edges persist', { skip: !hasTmux() ? 'tmux unavailable' : false, timeout: 180_000 }, async () => {
+function seedAssistantSession(sessionFile) {
+    mkdirSync(join(sessionFile, '..'), { recursive: true });
+    writeFileSync(sessionFile, JSON.stringify({ type: 'message', message: { role: 'assistant', content: [{ type: 'text', text: 'hi' }] } }) + '\n');
+}
+test('cascade close: middle-node lifecycle close cancels EXACTLY its subtree, ancestor + sideways untouched, edges persist', { skip: !hasTmux() ? 'tmux unavailable' : false, timeout: 180_000 }, async () => {
     const h = await createHarness({ sessionPrefix: 'crtr-cascade' });
     try {
         // ===================================================================
@@ -73,16 +79,23 @@ test('cascade close: middle-node close reaps EXACTLY its subtree (canceled), anc
         const D = await h.spawnChild(B, 'B child two'); // breadth: B has {C, D}
         const S = await h.spawnChild(A, 'sideways sibling of B'); // sideways subtree
         const G = await h.spawnChild(S, 'child of the sideways sibling');
-        const subtree = [B, C, D, E]; // B's exclusive subtree (the expected reap set)
+        const subtree = [B, C, D, E]; // B's exclusive subtree (the expected cancel set)
         const sideways = [S, G]; // a sibling subtree — must be wholly untouched
+        // Make the close-path fixtures NON-EMPTY so close exercises cancel+notice
+        // semantics instead of the new reap-empty path.
+        for (const id of subtree) {
+            const sessionFile = h.node(id).pi_session_file;
+            assert.ok(sessionFile !== null && sessionFile !== undefined, `${id} has a session file`);
+            seedAssistantSession(sessionFile);
+        }
         // Pre-close sanity: every node live + present, spine wired as drawn.
         {
             for (const id of [B, C, D, E, S, G]) {
-                assert.equal(h.status(id), 'active', `${id} active before close`);
+                assert.ok(h.status(id) === 'active' || h.status(id) === 'idle', `${id} live before close`);
                 const pid = h.node(id).pi_pid;
                 assert.ok(pid != null && isPidAlive(pid), `${id} broker engine alive before close`);
             }
-            assert.equal(h.status(A), 'active', 'A (root) active before close');
+            assert.ok(h.status(A) === 'active' || h.status(A) === 'idle', 'A (root) live before close');
             // Spine: A→{B,S}, B→{C,D}, C→{E}, S→{G} (all active spawn-seed edges).
             const subIds = (n) => h.subscriptions(n).map((s) => s.node_id).sort();
             assert.deepEqual(subIds(A), [B, S].sort(), 'A subscribes_to B and S');
@@ -105,19 +118,19 @@ test('cascade close: middle-node close reaps EXACTLY its subtree (canceled), anc
         const aInboxBefore = h.inbox(A);
         assert.ok(aInboxBefore.some((e) => e.from === B && e.kind === 'update'), "A's inbox holds B's pre-close update (non-vacuous 'intact' baseline)");
         // ===================================================================
-        // CLOSE the MIDDLE node B, through the REAL CLI (`crtr node close --node B`,
+        // CLOSE the MIDDLE node B, through the REAL CLI (`crtr node lifecycle close --node B`,
         // run AS the root A). closeNode is synchronous in the subprocess: by the
         // time it returns, rows are flipped and panes are killed.
         // ===================================================================
-        const closeRes = h.cli(A, ['node', 'close', '--node', B]);
-        assert.equal(closeRes.code, 0, `node close exit 0\n${closeRes.stderr}`);
+        const closeRes = h.cli(A, ['node', 'lifecycle', 'close', '--node', B]);
+        assert.equal(closeRes.code, 0, `node lifecycle close exit 0\n${closeRes.stderr}`);
         // The CLI's own rendered report (plain markdown): cascade root B, exactly
         // 4 closed, 0 spared (no spared clause is emitted when none were spared).
         assert.match(closeRes.stdout, new RegExp(`^Closed ${B} and its exclusive subtree — 4 node\\(s\\) closed\\.`), `close report names B as root, count=4, spared=0\n${closeRes.stdout}`);
         // ===================================================================
         // ASSERT 1 — the A5 DELIVERABLE: the EXACT terminal status of every
-        // cascade-reaped node. CURRENT behavior: status='canceled', intent=null,
-        // for the ROOT (B) and EVERY descendant {C,D,E} identically.
+        // cascade-closed node. With the fixtures now non-empty, close exercises
+        // cancel+notice semantics and the rows remain present as canceled husks.
         // ===================================================================
         for (const id of subtree) {
             const n = h.node(id);
@@ -125,11 +138,11 @@ test('cascade close: middle-node close reaps EXACTLY its subtree (canceled), anc
             assert.strictEqual(n.intent ?? null, null, `${id} intent cleared to null on cancel`);
         }
         // Pin the exact field tuple once more, explicitly, for the human decision:
-        // a cascade-reaped descendant under `node close` reads (canceled, null) —
+        // a cascade-closed descendant under `node lifecycle close` reads (canceled, null) —
         // NOT (done, done) and NOT (done, null). This is the confirmed A5 fact.
         {
             const e = h.node(E); // the deepest descendant
-            assert.deepEqual({ status: e.status, intent: e.intent ?? null }, { status: 'canceled', intent: null }, "deepest reaped descendant E: (status,intent) === ('canceled', null)");
+            assert.deepEqual({ status: e.status, intent: e.intent ?? null }, { status: 'canceled', intent: null }, "deepest closed descendant E: (status,intent) === ('canceled', null)");
         }
         // ===================================================================
         // ASSERT 2 — broker ENGINE torn down for the ENTIRE subtree (the real
@@ -146,7 +159,7 @@ test('cascade close: middle-node close reaps EXACTLY its subtree (canceled), anc
         }
         // ===================================================================
         // ASSERT 3 — EXCLUSIVE-SUBTREE OWNERSHIP: nothing ABOVE (A) and nothing
-        // SIDEWAYS (S, G) was reaped. close(B) reaped EXACTLY B's own subtree.
+        // SIDEWAYS (S, G) was reaped. close(B) canceled EXACTLY B's own subtree.
         // ===================================================================
         // Ancestor A — lifecycle untouched (still the live resident root), but A is
         // the SURVIVING manager of the close-root B, so the wake doctrine fix WAKES
@@ -168,7 +181,7 @@ test('cascade close: middle-node close reaps EXACTLY its subtree (canceled), anc
         }
         // Sideways subtree S→G — wholly alive: status active AND broker engine alive.
         for (const id of sideways) {
-            assert.equal(h.status(id), 'active', `${id} (sideways) still active — not reaped`);
+            assert.equal(h.status(id), 'active', `${id} (sideways) still active — not canceled`);
             const pid = h.node(id).pi_pid;
             assert.ok(pid != null && isPidAlive(pid), `${id} (sideways) broker engine still alive`);
         }

package/dist/core/__tests__/full/detach-focus.test.js

@@ -5,7 +5,7 @@
 // BROKER-CUT ADAPTATION (taste/broker-is-the-host, 2026-06-10): every node is a
 // detached headless broker. After a09b71f a managed child opens NO viewer on
 // spawn — a viewer is opened on demand via `node focus`, registering its
-// `crtr attach` VIEWER pane in the focuses table. The engine is NOT in a pane, so the
+// `crtr surface attach` VIEWER pane in the focuses table. The engine is NOT in a pane, so the
 // pre-cut "relocate the still-running pi pane to the backstage" behavior —
 // detachToBackground's engine break-pane/release path, and its isGenerating()
 // gate that released a non-generating node to dormant — is DELETED. The Bug-1
@@ -60,7 +60,7 @@ test('node demote --detach: flips terminal in place, CLOSES the viewer pane + fo
         assert.equal(b0.status, 'active', 'B active after boot');
         const brokerPid = b0.pi_pid;
         assert.ok(brokerPid != null && isPidAlive(brokerPid), 'B broker engine alive before detach');
-        // Put B genuinely "on screen": `node focus` opens its one `crtr attach`
+        // Put B genuinely "on screen": `node focus` opens its one `crtr surface attach`
         // VIEWER pane beside a caller pane in the harness session, registering the
         // viewer focus row (§A.3) — the on-demand viewer the detach then tears down.
         const caller = makePane(h.session);

package/dist/core/__tests__/hearth-bootstrap.test.js

@@ -0,0 +1,136 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { buildBootstrapScript } from '../hearth/providers/blaxel-bootstrap.js';
+const FIRST_BOOT_OPTS = {
+    guestHome: '/home/agent',
+    crtrVersion: '0.3.33',
+    relayToken: 'relay-token',
+    webPort: 7878,
+    piAuthJson: '{"anthropic":{"type":"oauth","refresh":"r","access":"a","expires":1}}',
+    piPackages: ['npm:pi-claude-oauth-adapter@0.1.2'],
+    modelLaddersJson: '{"modelLadders":{"anthropic":{"strong":"anthropic/claude-opus-4-8:high"},"openai":{"strong":"openai-codex/gpt-5.5:high"},"defaultProvider":"anthropic"}}',
+    isFirstProvision: true,
+};
+function indexOf(script, needle) {
+    const i = script.indexOf(needle);
+    assert.ok(i !== -1, `expected to find ${JSON.stringify(needle)} in script`);
+    return i;
+}
+test('first provision seeds config/ladders and pi settings, never the rotation pool, and never installs', () => {
+    const script = buildBootstrapScript(FIRST_BOOT_OPTS);
+    // Seeds that DO belong (config template + model ladders + pi settings +
+    // optional single auth.json).
+    assert.match(script, /settings\.json/);
+    assert.match(script, /pi-crtr-extensions/);
+    assert.match(script, /CRTR_CONFIG_JSON/);
+    assert.match(script, /PI_AUTH_JSON/);
+    // The rotation pool is dead product — bridge/migration only, never emitted
+    // by the rewritten bootstrap regardless of opts shape.
+    assert.doesNotMatch(script, /ANTHROPIC_SUBSCRIPTIONS_JSON/);
+    assert.doesNotMatch(script, /OPENAI_CODEX_SUBSCRIPTIONS_JSON/);
+    assert.doesNotMatch(script, /PROVIDER_ROTATION_JSON/);
+    assert.doesNotMatch(script, /anthropic-subscriptions\.json/);
+    assert.doesNotMatch(script, /openai-codex-subscriptions\.json/);
+    assert.doesNotMatch(script, /provider-rotation\.json/);
+    // No boot-time install of any kind — the image bakes crtr; bootstrap only
+    // asserts it.
+    assert.doesNotMatch(script, /npm install/);
+});
+test('recreate (isFirstProvision:false) emits no seeds at all and revives the existing node', () => {
+    const script = buildBootstrapScript({
+        ...FIRST_BOOT_OPTS,
+        isFirstProvision: false,
+        nodeId: 'node-123',
+    });
+    assert.doesNotMatch(script, /settings\.json/);
+    assert.doesNotMatch(script, /CRTR_CONFIG_JSON/);
+    assert.doesNotMatch(script, /PI_AUTH_JSON/);
+    assert.doesNotMatch(script, /ANTHROPIC_SUBSCRIPTIONS_JSON/);
+    assert.doesNotMatch(script, /OPENAI_CODEX_SUBSCRIPTIONS_JSON/);
+    assert.doesNotMatch(script, /PROVIDER_ROTATION_JSON/);
+    assert.match(script, /'\/usr\/local\/bin\/crtr' canvas revive 'node-123'/);
+    assert.doesNotMatch(script, /node new --root/);
+});
+test('recreate without a nodeId fails fast at script-generation time, not inside the guest', () => {
+    assert.throws(() => buildBootstrapScript({ ...FIRST_BOOT_OPTS, isFirstProvision: false, nodeId: null }));
+    assert.throws(() => buildBootstrapScript({ ...FIRST_BOOT_OPTS, isFirstProvision: false, nodeId: '  ' }));
+});
+test('an empty relay token fails fast at script-generation time — the web lane must never bind unauthenticated', () => {
+    assert.throws(() => buildBootstrapScript({ ...FIRST_BOOT_OPTS, relayToken: '' }));
+    assert.throws(() => buildBootstrapScript({ ...FIRST_BOOT_OPTS, relayToken: '   ' }));
+});
+test('asserts the baked crtr command surface — never falls back to the retired top-level alias', () => {
+    const script = buildBootstrapScript(FIRST_BOOT_OPTS);
+    assert.match(script, /'\/usr\/local\/bin\/crtr' surface web -h/);
+    assert.match(script, /'\/usr\/local\/bin\/crtr' surface web serve -h/);
+    assert.match(script, /command surface assertion FAILED/);
+    assert.match(script, /'\/usr\/local\/bin\/crtr' surface web serve --host 0\.0\.0\.0/);
+    // Never the retired top-level alias, anywhere in the script (e.g. as a
+    // fallback if the surface assertion fails).
+    assert.doesNotMatch(script, /[^/]crtr web serve/);
+});
+test('asserts the pinned crtr version against the baked binary and fails closed on mismatch', () => {
+    const script = buildBootstrapScript(FIRST_BOOT_OPTS);
+    assert.match(script, /'\/usr\/local\/bin\/crtr' --json sys version/);
+    assert.match(script, /crtr version assertion FAILED/);
+    assert.match(script, /!= '0\.3\.33'/);
+});
+test('every web-serve invocation carries a non-empty --token, enforcing relay-token auth on every lane', () => {
+    const firstBoot = buildBootstrapScript(FIRST_BOOT_OPTS);
+    const recreate = buildBootstrapScript({ ...FIRST_BOOT_OPTS, isFirstProvision: false, nodeId: 'node-123' });
+    for (const script of [firstBoot, recreate]) {
+        const serveLine = script.split('\n').find((line) => line.includes('surface web serve --host'));
+        assert.ok(serveLine, 'expected a crtr surface web serve invocation');
+        assert.match(serveLine, /--token 'relay-token'/);
+    }
+});
+test('every crtr invocation targets the baked binary by absolute path, never a bare PATH lookup, defeating a stale volume-installed crtr shadowing it (review Major 1)', () => {
+    const firstBoot = buildBootstrapScript(FIRST_BOOT_OPTS);
+    const recreate = buildBootstrapScript({ ...FIRST_BOOT_OPTS, isFirstProvision: false, nodeId: 'node-123' });
+    for (const script of [firstBoot, recreate]) {
+        assert.match(script, /'\/usr\/local\/bin\/crtr' --json sys version/);
+        assert.match(script, /'\/usr\/local\/bin\/crtr' surface web -h/);
+        assert.match(script, /'\/usr\/local\/bin\/crtr' surface web serve -h/);
+        assert.match(script, /'\/usr\/local\/bin\/crtr' canvas daemon start/);
+        assert.match(script, /'\/usr\/local\/bin\/crtr' surface web serve --host 0\.0\.0\.0/);
+        // No bare `crtr <subcommand>` invocation anywhere — only the `command -v
+        // crtr` shadow-detection probe and human-readable error-message text are
+        // allowed to reference it by bare name.
+        const bareInvocations = script
+            .split('\n')
+            .filter((line) => !line.trim().startsWith('printf'))
+            .filter((line) => /(^|[\s(])crtr (canvas|surface|--json)/.test(line));
+        assert.deepEqual(bareInvocations, []);
+    }
+    assert.match(firstBoot, /'\/usr\/local\/bin\/crtr' --json node new --root/);
+});
+test('asserts a bare `crtr` PATH lookup resolves to the baked binary, catching a stale volume-installed crtr shadowing it', () => {
+    const script = buildBootstrapScript(FIRST_BOOT_OPTS);
+    assert.match(script, /resolved_crtr="\$\(command -v crtr 2>\/dev\/null \|\| true\)"/);
+    assert.match(script, /if \[ "\$resolved_crtr" != '\/usr\/local\/bin\/crtr' \]; then/);
+    assert.match(script, /stale crtr shadowing baked binary/);
+});
+test('exports a PATH with the baked /usr/local/bin ahead of the legacy (dead) per-home runtime bin dir', () => {
+    const script = buildBootstrapScript(FIRST_BOOT_OPTS);
+    assert.match(script, /export PATH='\/usr\/local\/bin:\/usr\/bin:\/bin'/);
+    assert.doesNotMatch(script, /crtr-runtime\/bin/);
+});
+test('mkdirs the tmpfs CRTR_SOCK_DIR/CRTR_PIDFILE dirs strictly before the daemon starts, and CRTR_CANVAS_DB stays unset', () => {
+    const script = buildBootstrapScript(FIRST_BOOT_OPTS);
+    assert.match(script, /export CRTR_SOCK_DIR='\/run\/crtr\/socks'/);
+    assert.match(script, /export CRTR_PIDFILE='\/run\/crtr\/crtrd\.pid'/);
+    assert.match(script, /export CRTR_HOME='\/home\/agent\/\.crouter\/canvas'/);
+    assert.doesNotMatch(script, /CRTR_CANVAS_DB=/);
+    assert.match(script, /unset CRTR_CANVAS_DB/);
+    const mkdirIdx = indexOf(script, '/run/crtr/socks');
+    const daemonStartIdx = indexOf(script, "'/usr/local/bin/crtr' canvas daemon start");
+    assert.ok(mkdirIdx < daemonStartIdx, 'tmpfs mkdir must precede daemon start');
+    const mkdirLine = script.split('\n').find((line) => line.startsWith('mkdir -p') && line.includes('/run/crtr/socks'));
+    assert.ok(mkdirLine, 'expected a single mkdir line covering the tmpfs dirs');
+});
+test('primes the baked pi Claude OAuth adapter into the npm cache path pi resolves, existence-gated', () => {
+    const script = buildBootstrapScript(FIRST_BOOT_OPTS);
+    assert.match(script, /\/opt\/crouter\/node_modules\/pi-claude-oauth-adapter/);
+    assert.match(script, /\.pi\/agent\/npm\/node_modules\/pi-claude-oauth-adapter/);
+    assert.match(script, /cp -R/);
+});

package/dist/core/__tests__/helpers/harness.js

@@ -344,7 +344,7 @@ export async function createHarness(opts = {}) {
         async spawnHeadlessChild(parentId, task, o = {}) {
             const before = new Set(nodeDirs());
             // POST-CUT: `--headless` is gone — EVERY node is a broker. spawnChild may
-            // still open a background `crtr attach` viewer WINDOW (the §A.3 spawn UX),
+            // still open a background `crtr surface attach` viewer WINDOW (the §A.3 spawn UX),
             // but that viewer connects to the broker over view.sock as a SEPARATE
             // process and never touches the engine — so the broker-socket gates here
             // (zero-viewer dialogs, controller arbitration, one-writer) are unaffected

package/dist/core/__tests__/live-mutation-verbs.test.js

@@ -8,9 +8,9 @@
 //
 // THREE-PART LOCK HEADER ──────────────────────────────────────────────────
 // (1) BUG LOCKED — the demote/recycle SPLIT and the A4 steer-loss boundary:
-//     • `node demote` flips lifecycle→TERMINAL IN PLACE — keeps MODE, parentage,
+//     • `node lifecycle demote` flips lifecycle→TERMINAL IN PLACE — keeps MODE, parentage,
 //       and a live (active) status; NOT finalized. It is NOT a mode flip.
-//     • `node recycle` is FINISH+RECYCLE — pushes a final → done (mode KEPT), and
+//     • `node lifecycle recycle` is FINISH+RECYCLE — pushes a final → done (mode KEPT), and
 //       mints a DIFFERENT fresh general/base/resident root.
 //     • A4: a base→orchestrator yield auto-promotes (mode→orchestrator) and sets
 //       intent=refresh but NEVER commits persona_ack — the drift is left pending
@@ -49,16 +49,16 @@ function persona(m) {
 }
 // ===========================================================================
 // (b) THE demote / recycle SPLIT — two DISTINCT verbs:
-//   • `node demote`  flips a LIVE node's lifecycle→TERMINAL IN PLACE — it keeps
+//   • `node lifecycle demote`  flips a LIVE node's lifecycle→TERMINAL IN PLACE — it keeps
 //     its MODE and parentage, keeps running (active), is NOT finalized; it now
 //     merely owes a final up the spine (vision F5). MODE is untouched.
-//   • `node recycle` is FINISH+RECYCLE — push final → done, then recycle the pane
+//   • `node lifecycle recycle` is FINISH+RECYCLE — push final → done, then recycle the pane
 //     into a FRESH general/base/resident root (a DIFFERENT node). The recycled
 //     node keeps mode=orchestrator (it is merely `done`).
 // This test drives demote via the real CLI verb and recycle via the real
 // recycleNode, pinning each behavior at the model layer.
 // ===========================================================================
-test('node demote flips lifecycle→terminal IN PLACE; node recycle is FINISH+RECYCLE', { timeout: 20_000 }, async () => {
+test('node lifecycle demote flips lifecycle→terminal IN PLACE; node lifecycle recycle is FINISH+RECYCLE', { timeout: 20_000 }, async () => {
     const h = await createHeadlessHarness({ sessionPrefix: 'crtr-live-demote' });
     try {
         const A = h.spawnRoot('resident root');
@@ -66,7 +66,7 @@ test('node demote flips lifecycle→terminal IN PLACE; node recycle is FINISH+RE
         subscribe(A, B, true);
         // Make B resident + orchestrator so the demote's flip→terminal is visible
         // and we can prove MODE/parentage survive it.
-        assert.equal(h.cli(B, ['node', 'lifecycle', 'resident', '--node', B]).code, 0, 'B → resident');
+        assert.equal(h.cli(B, ['node', 'config', '--lifecycle', 'resident', '--node', B]).code, 0, 'B → resident');
         assert.equal(h.cli(B, ['node', 'promote', '--kind', 'developer']).code, 0, 'promote B');
         {
             const b = h.node(B);
@@ -74,10 +74,10 @@ test('node demote flips lifecycle→terminal IN PLACE; node recycle is FINISH+RE
             assert.equal(b.mode, 'orchestrator', 'B orchestrator before demote');
         }
         const bParent = h.node(B).parent;
-        // --- node demote: flip-to-terminal IN PLACE. Keeps B alive, MODE/parentage
+        // --- node lifecycle demote: flip-to-terminal IN PLACE. Keeps B alive, MODE/parentage
         //     untouched, NOT finalized.
-        const dem = h.cli(B, ['node', 'demote', '--node', B]);
-        assert.equal(dem.code, 0, `node demote exit 0\n${dem.stderr}`);
+        const dem = h.cli(B, ['node', 'lifecycle', 'demote', '--node', B]);
+        assert.equal(dem.code, 0, `node lifecycle demote exit 0\n${dem.stderr}`);
         assert.match(dem.stdout, /^Demoted /, `demote rendered\n${dem.stdout}`);
         {
             const b = h.node(B);
@@ -87,7 +87,7 @@ test('node demote flips lifecycle→terminal IN PLACE; node recycle is FINISH+RE
             assert.equal(b.status, 'active', 'demote does NOT finish B — it keeps running in place');
             assert.notEqual(b.intent ?? null, 'done', 'demote does NOT finalize B');
         }
-        // --- node recycle: FINISH + RECYCLE. Driven through the real recycleNode.
+        // --- node lifecycle recycle: FINISH + RECYCLE. Driven through the real recycleNode.
         //     Its FINISH+MINT model half runs fully; the pane respawn is the only
         //     tmux artifact (no pane for a broker node), so recycled:false while
         //     finalized:true and a fresh root IS minted — the bug-lock (recycle ≠

package/dist/core/__tests__/live-mutation.test.js

@@ -2,7 +2,7 @@
 //
 // HEADLESS RETARGET (foundation-spec §C.12 + §E). AXIS: LIVE MUTATION of the
 // 2×2 state vector (mode {base,orchestrator} × lifecycle {terminal,resident})
-// driven through the REAL `node lifecycle` / `node promote` CLI verbs against
+// driven through the REAL `node config --lifecycle` / `node promote` CLI verbs against
 // FABRICATED broker-hosted (paneless) nodes — no real tmux session, no pane
 // chrome, and NO real broker boot. The mutation verbs and the decisions they
 // gate are host-independent model logic, so the file never pays the ~5s SDK-boot
@@ -50,7 +50,7 @@ function persona(m) {
 }
 const SIGNALS = { pushedFinal: false, askedHuman: false };
 // ===========================================================================
-// (a) LIFECYCLE FLIP — `crtr node lifecycle` on a LIVE node, both directions,
+// (a) LIFECYCLE FLIP — `crtr node config --lifecycle` on a LIVE node, both directions,
 //     observing the idle-release DECISION change. A round-trip on ONE node
 //     (terminal→resident→terminal) proves both directions: a flipped-resident
 //     node no longer idle-releases (evaluateStop → dormant); flipped-terminal it
@@ -86,13 +86,13 @@ test('live lifecycle flip: terminal→resident suppresses idle-release; resident
         // --- FLIP 1: terminal → RESIDENT (live). Oracle §4: sets lifecycle + the
         //     launch spec, status/intent UNTOUCHED. ---
         {
-            const res = h.cli(B, ['node', 'lifecycle', 'resident', '--node', B]);
-            assert.equal(res.code, 0, `lifecycle resident exit 0\n${res.stderr}`);
+            const res = h.cli(B, ['node', 'config', '--lifecycle', 'resident', '--node', B]);
+            assert.equal(res.code, 0, `config --lifecycle resident exit 0\n${res.stderr}`);
             const b = h.node(B);
             assert.equal(b.lifecycle, 'resident', 'B → resident');
             assert.equal(b.mode, 'base', 'mode UNCHANGED by a lifecycle flip (orthogonal axis)');
-            assert.equal(b.status, 'active', 'status UNTOUCHED by node lifecycle (oracle §4)');
-            assert.equal(b.intent ?? null, null, 'intent UNTOUCHED by node lifecycle (oracle §4)');
+            assert.equal(b.status, 'active', 'status UNTOUCHED by node config --lifecycle (oracle §4)');
+            assert.equal(b.intent ?? null, null, 'intent UNTOUCHED by node config --lifecycle (oracle §4)');
         }
         // THE SUPPRESSION LOCK — as RESIDENT, B's stop is 'dormant' (NOT awaiting):
         // a resident node is never forced to submit a final, so it does NOT idle-
@@ -108,8 +108,8 @@ test('live lifecycle flip: terminal→resident suppresses idle-release; resident
         }
         // --- FLIP 2: resident → TERMINAL (live), on the now-resident node. ---
         {
-            const res = h.cli(B, ['node', 'lifecycle', 'terminal', '--node', B]);
-            assert.equal(res.code, 0, `lifecycle terminal exit 0\n${res.stderr}`);
+            const res = h.cli(B, ['node', 'config', '--lifecycle', 'terminal', '--node', B]);
+            assert.equal(res.code, 0, `config --lifecycle terminal exit 0\n${res.stderr}`);
             const b = h.node(B);
             assert.equal(b.lifecycle, 'terminal', 'B → terminal');
             assert.equal(b.status, 'active', 'status still UNTOUCHED by the flip');

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

@@ -6,6 +6,7 @@ import { join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { openDb, closeDb, migrate, MIGRATIONS } from '../canvas/db.js';
 import { canvasDbPath, ensureHome } from '../canvas/paths.js';
+import { listTriggers } from '../canvas/triggers.js';
 const RUNTIME_COLUMNS = ['intent', 'pi_pid', 'window', 'tmux_session'];
 let home;
 function userVersion(db) {
@@ -271,3 +272,126 @@ test('bug #99: a stale v4 db with later columns already present migrates cleanly
     assert.equal(row.pane, '%9');
     assert.equal(row.host_kind, 'broker');
 });
+// --- v9: wakeups → triggers (the unified node-trigger-grammar substrate) ---
+/** Build a hand-rolled db at exactly v8: baseline nodes/edges + the v7
+ *  `wakeups` table, `user_version = 8` — the shape the live fleet reaches just
+ *  before v9. Caller seeds `wakeups` rows, we close it; the next openDb() runs
+ *  only v9 over it. */
+function buildV8DbWithWakeups() {
+    ensureHome();
+    const raw = new DatabaseSync(canvasDbPath());
+    raw.exec(`
+    CREATE TABLE nodes (
+      node_id    TEXT PRIMARY KEY,
+      name       TEXT NOT NULL,
+      kind       TEXT NOT NULL,
+      mode       TEXT NOT NULL DEFAULT 'base',
+      lifecycle  TEXT NOT NULL DEFAULT 'terminal',
+      status     TEXT NOT NULL DEFAULT 'active',
+      cwd        TEXT NOT NULL,
+      parent     TEXT,
+      created    TEXT NOT NULL,
+      intent       TEXT,
+      pi_pid       INTEGER,
+      window       TEXT,
+      tmux_session TEXT,
+      pane         TEXT,
+      host_kind    TEXT
+    );
+    CREATE TABLE edges (
+      type     TEXT NOT NULL,
+      from_id  TEXT NOT NULL,
+      to_id    TEXT NOT NULL,
+      active   INTEGER NOT NULL DEFAULT 1,
+      created  TEXT NOT NULL,
+      PRIMARY KEY (type, from_id, to_id)
+    );
+    CREATE TABLE wakeups (
+      wakeup_id  TEXT PRIMARY KEY,
+      node_id    TEXT,
+      owner_id   TEXT NOT NULL,
+      fire_at    TEXT NOT NULL,
+      kind       TEXT NOT NULL,
+      recur      TEXT,
+      payload    TEXT,
+      created    TEXT NOT NULL,
+      FOREIGN KEY (node_id) REFERENCES nodes(node_id) ON DELETE CASCADE
+    );
+    PRAGMA user_version = 8;
+  `);
+    insertNode(raw, 'armer');
+    insertNode(raw, 'tgt');
+    return raw;
+}
+function insertWakeup(db, row) {
+    db.prepare('INSERT INTO wakeups (wakeup_id, node_id, owner_id, fire_at, kind, recur, payload, created) VALUES (?,?,?,?,?,?,?,?)').run(row.wakeup_id, row.node_id, row.owner_id, row.fire_at, row.kind, row.recur ?? null, row.payload ?? null, '2020-01-01T00:00:00Z');
+}
+test('v9 migrates every wakeups row into triggers, preserving ids/fire data, then drops wakeups', () => {
+    const raw = buildV8DbWithWakeups();
+    insertWakeup(raw, { wakeup_id: 'wk-bare', node_id: 'tgt', owner_id: 'armer', fire_at: '2026-01-01T00:00:00.000Z', kind: 'bare' });
+    insertWakeup(raw, {
+        wakeup_id: 'wk-noted',
+        node_id: 'tgt',
+        owner_id: 'armer',
+        fire_at: '2026-01-02T00:00:00.000Z',
+        kind: 'noted',
+        payload: JSON.stringify({ body: 'check CI', label: 'check CI' }),
+    });
+    insertWakeup(raw, {
+        wakeup_id: 'wk-deadline',
+        node_id: 'tgt',
+        owner_id: 'tgt',
+        fire_at: '2026-01-03T00:00:00.000Z',
+        kind: 'deadline',
+        payload: JSON.stringify({ body: 'timed out', timeout: true, label: 'timed out' }),
+    });
+    insertWakeup(raw, {
+        wakeup_id: 'wk-spawn-cron',
+        node_id: null,
+        owner_id: 'armer',
+        fire_at: '2026-01-04T00:00:00.000Z',
+        kind: 'spawn',
+        recur: JSON.stringify({ every: '6h' }),
+        payload: JSON.stringify({ kind: 'general', mode: 'base', cwd: '/tmp/work', prompt: 'go', parent: 'armer' }),
+    });
+    assert.equal(userVersion(raw), 8);
+    raw.close();
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    // The old table is gone — not kept as a parallel alias.
+    const tables = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all().map((r) => r.name);
+    assert.ok(!tables.includes('wakeups'), 'wakeups table is dropped after migration');
+    assert.ok(tables.includes('triggers'), 'triggers table exists');
+    const byId = (id) => db.prepare('SELECT * FROM triggers WHERE trigger_id = ?').get(id);
+    const bare = byId('wk-bare');
+    assert.equal(bare.owner_id, 'armer');
+    assert.equal(bare.node_id, 'tgt');
+    assert.equal(bare.action, 'msg');
+    assert.equal(bare.action_mode, 'fresh_revive');
+    assert.equal(bare.trigger_type, 'at');
+    assert.equal(bare.fire_at, '2026-01-01T00:00:00.000Z');
+    const noted = byId('wk-noted');
+    assert.equal(noted.action, 'msg');
+    assert.equal(noted.action_mode, 'inbox_message');
+    assert.equal(noted.trigger_type, 'at');
+    assert.deepEqual(JSON.parse(noted.payload), { body: 'check CI', label: 'check CI' });
+    const deadline = byId('wk-deadline');
+    assert.equal(deadline.action, 'msg');
+    assert.equal(deadline.action_mode, 'deadline_message');
+    assert.equal(deadline.trigger_type, 'until', "a deadline row's trigger_type is 'until', not 'at'");
+    assert.equal(deadline.node_id, 'tgt');
+    const spawnCron = byId('wk-spawn-cron');
+    assert.equal(spawnCron.action, 'new');
+    assert.equal(spawnCron.action_mode, 'node_birth');
+    assert.equal(spawnCron.trigger_type, 'every', 'a recurring spawn keeps trigger_type=every');
+    assert.equal(spawnCron.node_id, null, 'a detached spawn-cron stays canvas-detached');
+    assert.equal(spawnCron.recur, JSON.stringify({ every: '6h' }));
+    // The migrated rows are readable via the current triggers DAO, keyed by
+    // trigger_id (preserved from wakeup_id) and the current action/action_mode
+    // vocabulary rather than the dropped per-kind wakeups shape.
+    const allTriggers = listTriggers({ canvas: true });
+    assert.equal(allTriggers.length, 4);
+    const migratedBare = allTriggers.find((t) => t.trigger_id === 'wk-bare');
+    assert.equal(migratedBare.action_mode, 'fresh_revive');
+    assert.equal(migratedBare.node_id, 'tgt');
+});

package/dist/core/__tests__/on-read-dedup-resume.test.js

@@ -20,6 +20,7 @@ import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync } from 'node:
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { closeDb } from '../canvas/db.js';
+import { resetScopeCache } from '../scope.js';
 import { injectedDocsPath } from '../canvas/paths.js';
 import { spawnNode } from '../runtime/nodes.js';
 import { renderOnReadDocs } from '../substrate/on-read.js';
@@ -27,20 +28,32 @@ import { loadInjectedDocs, saveInjectedDocs, clearInjectedDocs, } from '../subst
 const FIXTURE_BODY = 'Fixture body that must surface exactly once.';
 let home;
 let work;
+let prevHomeEnv;
 before(() => {
     home = mkdtempSync(join(tmpdir(), 'crtr-onread-home-'));
     process.env['CRTR_HOME'] = home;
+    prevHomeEnv = process.env['HOME'];
 });
 beforeEach(() => {
     closeDb();
+    resetScopeCache();
     rmSync(home, { recursive: true, force: true });
+    if (prevHomeEnv === undefined)
+        delete process.env['HOME'];
+    else
+        process.env['HOME'] = prevHomeEnv;
     work = mkdtempSync(join(tmpdir(), 'crtr-onread-work-'));
 });
 after(() => {
     closeDb();
+    resetScopeCache();
     rmSync(home, { recursive: true, force: true });
     rmSync(work, { recursive: true, force: true });
     delete process.env['CRTR_HOME'];
+    if (prevHomeEnv === undefined)
+        delete process.env['HOME'];
+    else
+        process.env['HOME'] = prevHomeEnv;
 });
 test('injected-store round-trips and clears', () => {
     const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
@@ -51,6 +64,33 @@ test('injected-store round-trips and clears', () => {
     assert.ok(!existsSync(injectedDocsPath(node)), 'clear removes the file');
     assert.deepEqual([...loadInjectedDocs(node)], [], 'load after clear is empty');
 });
+test('user-global memory docs do not fire positionally for every file under home', () => {
+    const fakeHome = mkdtempSync(join(tmpdir(), 'crtr-onread-user-home-'));
+    process.env['HOME'] = fakeHome;
+    resetScopeCache();
+    const node = spawnNode({ kind: 'general', cwd: join(fakeHome, 'work'), parent: null }).node_id;
+    const userMemDir = join(fakeHome, '.crouter', 'memory');
+    mkdirSync(userMemDir, { recursive: true });
+    writeFileSync(join(userMemDir, 'noisy-global.md'), '---\nkind: preference\n' +
+        'when-and-why-to-read: When reading any file, this preference should be read because this fixture must not fire positionally\n' +
+        'file-read-visibility: content\n---\n' +
+        'NOISY USER BODY\n');
+    const projectMemDir = join(fakeHome, 'work', '.crouter', 'memory');
+    mkdirSync(projectMemDir, { recursive: true });
+    writeFileSync(join(projectMemDir, 'local.md'), '---\nkind: knowledge\n' +
+        'when-and-why-to-read: When reading project files, this reference should be read because local project memories remain positional\n' +
+        'file-read-visibility: content\n---\n' +
+        'LOCAL PROJECT BODY\n');
+    const readFile = join(fakeHome, 'work', 'ideas.md');
+    writeFileSync(readFile, 'turn off xml closer\n');
+    const rendered = renderOnReadDocs(node, readFile, new Set());
+    assert.ok(!rendered.includes('NOISY USER BODY'), 'user-global doc is not positional');
+    assert.ok(rendered.includes('LOCAL PROJECT BODY'), 'project doc still fires positionally');
+    assert.ok(rendered.includes('<memory kind="knowledge" name="local"'), 'memory docs render as memory tags');
+    assert.ok(!rendered.includes('triggered-by='), 'read target is not repeated on child items');
+    assert.ok(!rendered.includes('<auto-loaded-context file='), 'read target is not repeated on the wrapper');
+    rmSync(fakeHome, { recursive: true, force: true });
+});
 test('on-read doc surfaces once, stays deduped across a revive(resume), re-surfaces after a fresh launch', () => {
     const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
     // A positional substrate doc in a `.crouter/memory/` ancestor of the read file.