@crouton-kit/crouter 0.3.19 → 0.3.21

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

@@ -0,0 +1,175 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/live-mutation-verbs.test.ts
+//
+// AXIS: LIVE MUTATION, part 2 — the demote/recycle verb split and the A4
+// promote-then-yield boundary. Split out of live-mutation.test.ts (see its
+// header for the coverage rationale and the oracle reference) so node:test's
+// file-level parallelism applies; each test builds its OWN isolated harness and
+// is moved here UNCHANGED.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { createHarness, hasTmux } from './helpers/harness.js';
+const SKIP = !hasTmux() ? 'tmux unavailable' : false;
+function sessionExists(session) {
+    return spawnSync('tmux', ['has-session', '-t', session], { stdio: 'ignore' }).status === 0;
+}
+// --- pure test-local helpers (shared verbatim with live-mutation.test.ts) ---
+/** The injected entries delivered as a turn-boundary `steer`. */
+function steers(inj) {
+    return inj.filter((e) => e.deliverAs === 'steer');
+}
+/** A steer carrying the base→orchestrator orchestration guidance. */
+function orchestrationSteers(inj) {
+    return steers(inj).filter((e) => /ORCHESTRATOR/i.test(e.content));
+}
+/** Normalize the two persona axes off a NodeMeta for deepEqual. */
+function persona(m) {
+    return { mode: m.mode, lifecycle: m.lifecycle };
+}
+/** The first %pane_id of a tmux window. The spawn path records window+session
+ *  but NOT pane (spawn.ts: pane is null until a reconcile/focus), so a node's
+ *  live pane must be resolved from its window here. */
+function firstPaneOf(window) {
+    const r = spawnSync('tmux', ['list-panes', '-t', window, '-F', '#{pane_id}'], { encoding: 'utf8' });
+    if (r.status !== 0)
+        return null;
+    return r.stdout.split('\n').map((s) => s.trim()).filter(Boolean)[0] ?? null;
+}
+// ===========================================================================
+// (b) THE demote / recycle SPLIT — two DISTINCT verbs after the rename:
+//   • `node demote`  flips a LIVE node's lifecycle→TERMINAL IN PLACE — it keeps
+//     its pane, its MODE, and its parentage, keeps running, is NOT finalized; it
+//     now merely owes a final up the spine (vision F5). It is NOT an
+//     orchestrator→base mode flip — MODE is untouched (so persona.ts
+//     `baseModeGuidance` stays unreachable via live mutation, as before).
+//   • `node 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 BOTH real verbs on one live node and pins each behavior.
+// ===========================================================================
+test('node demote flips lifecycle→terminal IN PLACE; node recycle is FINISH+RECYCLE', { skip: SKIP, timeout: 120_000 }, async () => {
+    const h = await createHarness({ sessionPrefix: 'crtr-live-demote' });
+    try {
+        const A = h.spawnRoot('resident root');
+        const B = await h.spawnChild(A, 'do the work', { kind: 'developer' });
+        // 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', 'promote', '--kind', 'developer']).code, 0, 'promote B');
+        {
+            const b = h.node(B);
+            assert.equal(b.lifecycle, 'resident', 'B resident before demote');
+            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
+        //     untouched, NOT finalized.
+        const dem = h.cli(B, ['node', 'demote', '--node', B]);
+        assert.equal(dem.code, 0, `node demote exit 0\n${dem.stderr}`);
+        assert.match(dem.stdout, /^Demoted /, `demote rendered\n${dem.stdout}`);
+        {
+            const b = h.node(B);
+            assert.equal(b.lifecycle, 'terminal', 'demote flips lifecycle→terminal IN PLACE');
+            assert.equal(b.mode, 'orchestrator', 'demote leaves MODE untouched (not an orchestrator→base flip)');
+            assert.equal(b.parent, bParent, 'demote leaves parentage unchanged');
+            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 the SAME pane into a fresh root.
+        //     Resolve B's live %pane_id from its window (the row's `pane` is null
+        //     until a reconcile; the spawn path records only window+session).
+        const pane = firstPaneOf(h.node(B).window);
+        assert.ok(typeof pane === 'string' && pane !== '', 'B has a live pane to recycle');
+        // RECYCLE via the real verb (TMUX_PANE is scrubbed from child env → pass --pane).
+        const res = h.cli(B, ['node', 'recycle', '--node', B, '--pane', pane]);
+        assert.equal(res.code, 0, `recycle exit 0\n${res.stderr}`);
+        // The leaf renders plain markdown: a lead sentence + `- finalized:` / `- new root:` bullets.
+        assert.match(res.stdout, /^Recycled the pane /, `recycle recycled the pane\n${res.stdout}`);
+        const newRoot = /- new root: (\S+)/.exec(res.stdout)?.[1];
+        const finalized = /- finalized: true/.test(res.stdout);
+        // The recycled node is FINISHED, not mode-flipped.
+        {
+            const b = h.node(B);
+            assert.equal(b.status, 'done', 'recycled node → done (finished), NOT re-roled');
+            assert.equal(b.intent, 'done', 'intent=done (finalize), per the push-final path');
+            assert.equal(b.mode, 'orchestrator', 'recycled node KEEPS mode=orchestrator — recycle is NOT a mode flip');
+            assert.ok(finalized, 'recycle pushed a final for the node');
+        }
+        // The fresh root is a DIFFERENT, BASE×RESIDENT node.
+        assert.ok(typeof newRoot === 'string' && newRoot !== B, 'a fresh root (≠ B) was minted');
+        {
+            const fresh = h.node(newRoot);
+            assert.deepEqual(persona(fresh), { mode: 'base', lifecycle: 'resident' }, 'recycled root is born base×resident (general)');
+            assert.deepEqual(fresh.persona_ack, { mode: 'base', lifecycle: 'resident' }, 'fresh root born acked base×resident');
+        }
+    }
+    finally {
+        const session = h.session;
+        await h.dispose();
+        assert.equal(sessionExists(session), false, 'isolated session killed — no stray');
+    }
+});
+// ===========================================================================
+// (b) A4 BOUNDARY — promote-then-yield emits a steer that is discarded. The
+//     oracle/flagship boundary: the base→orchestrator guidance lands as a STEER
+//     only if a turn_end fires while the drift is pending. A `node yield` on a
+//     base node auto-promotes (mode→orchestrator, ack NOT committed) and its
+//     agent_end goes STRAIGHT to reviveInPlace (b') with NO preceding turn_end —
+//     so the only steer-delivery site (turn_end) is BYPASSED. Two deterministic
+//     facts pin the boundary, both confirmed by direct observation:
+//       (1) NO orchestration STEER is ever delivered (the LOSS).
+//       (2) The ack is silently advanced base→orchestrator at the refresh DRAIN
+//           (reviveInPlace→drainBearings→commitPersonaAck), NOT via a steer — so
+//           neither this turn nor (per A4) the fresh revive re-offers it as a
+//           steer; the guidance survives only in the kickoff PROMPT it built.
+//     ⚑ FLAGGED (not fixed): the in-place refresh of this LARGE pending-drift
+//        kickoff prompt did NOT complete a fresh fake-pi boot in the harness (it
+//        stayed at 1 boot, intent=refresh, ack=orchestrator, pane alive) — a
+//        base→orchestrator yield's giant <persona-transition> kickoff pushed
+//        through respawn-pane did not bring up the fresh vehicle. Whether a real
+//        edge (oversized argv through respawn-pane) or a harness artifact, it is
+//        out of scope to fix; this test asserts only the deterministic boundary.
+// ===========================================================================
+test('A4: a base→orchestrator yield with no preceding turn_end loses the orchestration STEER (ack advances silently at the refresh drain)', { skip: SKIP, timeout: 120_000 }, async () => {
+    const h = await createHarness({ sessionPrefix: 'crtr-live-a4' });
+    try {
+        const A = h.spawnRoot('resident root');
+        const B = await h.spawnChild(A, 'do the work', { kind: 'developer' });
+        assert.deepEqual(persona(h.node(B)), { mode: 'base', lifecycle: 'terminal' }, 'B born base×terminal');
+        const injBefore = h.injected(B).length;
+        // `crtr node yield` (base → auto-promote → intent=refresh). INTERMEDIATE
+        // state, BEFORE any agent_end: mode flipped, ack NOT yet committed (the
+        // turn_end injector has not run), intent=refresh, drift PENDING.
+        const y = h.cli(B, ['node', 'yield', 'refresh against the roadmap']);
+        assert.equal(y.code, 0, `node yield exit 0\n${y.stderr}`);
+        {
+            const b = h.node(B);
+            assert.equal(b.mode, 'orchestrator', 'yield auto-promoted base→orchestrator');
+            assert.equal(b.intent, 'refresh', 'intent=refresh set by the yield');
+            assert.deepEqual(b.persona_ack, { mode: 'base', lifecycle: 'terminal' }, 'ack STILL base — promote/yield never commits it; only an injector does');
+        }
+        // Fire the stop: agent_end sees intent=refresh → (b') reviveInPlace, whose
+        // drainBearings commits the ack synchronously BEFORE the respawn. NO
+        // turn_end fires this turn, so the turn_end steer site is bypassed.
+        await h.stop(B);
+        // (2) The ack is silently advanced to orchestrator at the refresh DRAIN —
+        // not by any steer. (waitFor: the agent_end handler runs after h.stop
+        // observes the recorded event.)
+        await h.waitFor(() => {
+            const a = h.node(B)?.persona_ack;
+            return a?.mode === 'orchestrator' && a?.lifecycle === 'terminal';
+        }, { timeoutMs: 20_000, label: 'persona_ack advanced at the refresh drain (not via a steer)' });
+        assert.deepEqual(h.node(B).persona_ack, { mode: 'orchestrator', lifecycle: 'terminal' }, 'ack committed base→orchestrator by drainBearings during reviveInPlace');
+        // (1) ⚑ LOSS site: across the whole yield→refresh, NO orchestration
+        // guidance was ever delivered as a turn-boundary STEER (the only steer
+        // site, turn_end, never ran). The ack moved without the agent ever being
+        // steered with the new-role guidance — it survives only in the kickoff
+        // prompt drainBearings built for the (here, non-booting) fresh vehicle.
+        assert.equal(orchestrationSteers(h.injected(B).slice(injBefore)).length, 0, '⚑ A4: no orchestration STEER delivered — the turn_end injector was bypassed by the yield');
+    }
+    finally {
+        const session = h.session;
+        await h.dispose();
+        assert.equal(sessionExists(session), false, 'isolated session killed — no stray');
+    }
+});

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

@@ -24,6 +24,10 @@
 // (idle-release vs dormant; persona-ack recompose; the A4 boundary) changes
 // accordingly. None of the above drives `crtr node lifecycle` on a live node,
 // nor asserts persona_ack mutation across a live promote, nor the A4 loss site.
+//
+// Part 2 of this axis — the demote/recycle verb split and the A4 promote-then-
+// yield boundary — lives in live-mutation-verbs.test.ts (split for node:test
+// file-level parallelism; each test holds its own isolated harness).
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
@@ -45,15 +49,6 @@ function orchestrationSteers(inj) {
 function persona(m) {
     return { mode: m.mode, lifecycle: m.lifecycle };
 }
-/** The first %pane_id of a tmux window. The spawn path records window+session
- *  but NOT pane (spawn.ts: pane is null until a reconcile/focus), so a node's
- *  live pane must be resolved from its window here. */
-function firstPaneOf(window) {
-    const r = spawnSync('tmux', ['list-panes', '-t', window, '-F', '#{pane_id}'], { encoding: 'utf8' });
-    if (r.status !== 0)
-        return null;
-    return r.stdout.split('\n').map((s) => s.trim()).filter(Boolean)[0] ?? null;
-}
 // ===========================================================================
 // (a) LIFECYCLE FLIP — `crtr node lifecycle` on a LIVE node, both directions,
 //     observing the idle-release behavior change. A round-trip on ONE live
@@ -218,141 +213,3 @@ test('live mode flip: promote base→orchestrator recomposes persona_ack at turn
         assert.equal(sessionExists(session), false, 'isolated session killed — no stray');
     }
 });
-// ===========================================================================
-// (b) THE demote / recycle SPLIT — two DISTINCT verbs after the rename:
-//   • `node demote`  flips a LIVE node's lifecycle→TERMINAL IN PLACE — it keeps
-//     its pane, its MODE, and its parentage, keeps running, is NOT finalized; it
-//     now merely owes a final up the spine (vision F5). It is NOT an
-//     orchestrator→base mode flip — MODE is untouched (so persona.ts
-//     `baseModeGuidance` stays unreachable via live mutation, as before).
-//   • `node 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 BOTH real verbs on one live node and pins each behavior.
-// ===========================================================================
-test('node demote flips lifecycle→terminal IN PLACE; node recycle is FINISH+RECYCLE', { skip: SKIP, timeout: 120_000 }, async () => {
-    const h = await createHarness({ sessionPrefix: 'crtr-live-demote' });
-    try {
-        const A = h.spawnRoot('resident root');
-        const B = await h.spawnChild(A, 'do the work', { kind: 'developer' });
-        // 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', 'promote', '--kind', 'developer']).code, 0, 'promote B');
-        {
-            const b = h.node(B);
-            assert.equal(b.lifecycle, 'resident', 'B resident before demote');
-            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
-        //     untouched, NOT finalized.
-        const dem = h.cli(B, ['node', 'demote', '--node', B]);
-        assert.equal(dem.code, 0, `node demote exit 0\n${dem.stderr}`);
-        assert.match(dem.stdout, /<demoted /, `demote rendered\n${dem.stdout}`);
-        {
-            const b = h.node(B);
-            assert.equal(b.lifecycle, 'terminal', 'demote flips lifecycle→terminal IN PLACE');
-            assert.equal(b.mode, 'orchestrator', 'demote leaves MODE untouched (not an orchestrator→base flip)');
-            assert.equal(b.parent, bParent, 'demote leaves parentage unchanged');
-            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 the SAME pane into a fresh root.
-        //     Resolve B's live %pane_id from its window (the row's `pane` is null
-        //     until a reconcile; the spawn path records only window+session).
-        const pane = firstPaneOf(h.node(B).window);
-        assert.ok(typeof pane === 'string' && pane !== '', 'B has a live pane to recycle');
-        // RECYCLE via the real verb (TMUX_PANE is scrubbed from child env → pass --pane).
-        const res = h.cli(B, ['node', 'recycle', '--node', B, '--pane', pane]);
-        assert.equal(res.code, 0, `recycle exit 0\n${res.stderr}`);
-        // The leaf renders `<recycled ... finalized=".." new_root=".."/>` (not JSON).
-        assert.match(res.stdout, /<recycled /, `recycle recycled the pane\n${res.stdout}`);
-        const newRoot = /new_root="([^"]+)"/.exec(res.stdout)?.[1];
-        const finalized = /finalized="true"/.test(res.stdout);
-        // The recycled node is FINISHED, not mode-flipped.
-        {
-            const b = h.node(B);
-            assert.equal(b.status, 'done', 'recycled node → done (finished), NOT re-roled');
-            assert.equal(b.intent, 'done', 'intent=done (finalize), per the push-final path');
-            assert.equal(b.mode, 'orchestrator', 'recycled node KEEPS mode=orchestrator — recycle is NOT a mode flip');
-            assert.ok(finalized, 'recycle pushed a final for the node');
-        }
-        // The fresh root is a DIFFERENT, BASE×RESIDENT node.
-        assert.ok(typeof newRoot === 'string' && newRoot !== B, 'a fresh root (≠ B) was minted');
-        {
-            const fresh = h.node(newRoot);
-            assert.deepEqual(persona(fresh), { mode: 'base', lifecycle: 'resident' }, 'recycled root is born base×resident (general)');
-            assert.deepEqual(fresh.persona_ack, { mode: 'base', lifecycle: 'resident' }, 'fresh root born acked base×resident');
-        }
-    }
-    finally {
-        const session = h.session;
-        await h.dispose();
-        assert.equal(sessionExists(session), false, 'isolated session killed — no stray');
-    }
-});
-// ===========================================================================
-// (b) A4 BOUNDARY — promote-then-yield emits a steer that is discarded. The
-//     oracle/flagship boundary: the base→orchestrator guidance lands as a STEER
-//     only if a turn_end fires while the drift is pending. A `node yield` on a
-//     base node auto-promotes (mode→orchestrator, ack NOT committed) and its
-//     agent_end goes STRAIGHT to reviveInPlace (b') with NO preceding turn_end —
-//     so the only steer-delivery site (turn_end) is BYPASSED. Two deterministic
-//     facts pin the boundary, both confirmed by direct observation:
-//       (1) NO orchestration STEER is ever delivered (the LOSS).
-//       (2) The ack is silently advanced base→orchestrator at the refresh DRAIN
-//           (reviveInPlace→drainBearings→commitPersonaAck), NOT via a steer — so
-//           neither this turn nor (per A4) the fresh revive re-offers it as a
-//           steer; the guidance survives only in the kickoff PROMPT it built.
-//     ⚑ FLAGGED (not fixed): the in-place refresh of this LARGE pending-drift
-//        kickoff prompt did NOT complete a fresh fake-pi boot in the harness (it
-//        stayed at 1 boot, intent=refresh, ack=orchestrator, pane alive) — a
-//        base→orchestrator yield's giant <persona-transition> kickoff pushed
-//        through respawn-pane did not bring up the fresh vehicle. Whether a real
-//        edge (oversized argv through respawn-pane) or a harness artifact, it is
-//        out of scope to fix; this test asserts only the deterministic boundary.
-// ===========================================================================
-test('A4: a base→orchestrator yield with no preceding turn_end loses the orchestration STEER (ack advances silently at the refresh drain)', { skip: SKIP, timeout: 120_000 }, async () => {
-    const h = await createHarness({ sessionPrefix: 'crtr-live-a4' });
-    try {
-        const A = h.spawnRoot('resident root');
-        const B = await h.spawnChild(A, 'do the work', { kind: 'developer' });
-        assert.deepEqual(persona(h.node(B)), { mode: 'base', lifecycle: 'terminal' }, 'B born base×terminal');
-        const injBefore = h.injected(B).length;
-        // `crtr node yield` (base → auto-promote → intent=refresh). INTERMEDIATE
-        // state, BEFORE any agent_end: mode flipped, ack NOT yet committed (the
-        // turn_end injector has not run), intent=refresh, drift PENDING.
-        const y = h.cli(B, ['node', 'yield', 'refresh against the roadmap']);
-        assert.equal(y.code, 0, `node yield exit 0\n${y.stderr}`);
-        {
-            const b = h.node(B);
-            assert.equal(b.mode, 'orchestrator', 'yield auto-promoted base→orchestrator');
-            assert.equal(b.intent, 'refresh', 'intent=refresh set by the yield');
-            assert.deepEqual(b.persona_ack, { mode: 'base', lifecycle: 'terminal' }, 'ack STILL base — promote/yield never commits it; only an injector does');
-        }
-        // Fire the stop: agent_end sees intent=refresh → (b') reviveInPlace, whose
-        // drainBearings commits the ack synchronously BEFORE the respawn. NO
-        // turn_end fires this turn, so the turn_end steer site is bypassed.
-        await h.stop(B);
-        // (2) The ack is silently advanced to orchestrator at the refresh DRAIN —
-        // not by any steer. (waitFor: the agent_end handler runs after h.stop
-        // observes the recorded event.)
-        await h.waitFor(() => {
-            const a = h.node(B)?.persona_ack;
-            return a?.mode === 'orchestrator' && a?.lifecycle === 'terminal';
-        }, { timeoutMs: 20_000, label: 'persona_ack advanced at the refresh drain (not via a steer)' });
-        assert.deepEqual(h.node(B).persona_ack, { mode: 'orchestrator', lifecycle: 'terminal' }, 'ack committed base→orchestrator by drainBearings during reviveInPlace');
-        // (1) ⚑ LOSS site: across the whole yield→refresh, NO orchestration
-        // guidance was ever delivered as a turn-boundary STEER (the only steer
-        // site, turn_end, never ran). The ack moved without the agent ever being
-        // steered with the new-role guidance — it survives only in the kickoff
-        // prompt drainBearings built for the (here, non-booting) fresh vehicle.
-        assert.equal(orchestrationSteers(h.injected(B).slice(injBefore)).length, 0, '⚑ A4: no orchestration STEER delivered — the turn_end injector was bypassed by the yield');
-    }
-    finally {
-        const session = h.session;
-        await h.dispose();
-        assert.equal(sessionExists(session), false, 'isolated session killed — no stray');
-    }
-});

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

@@ -29,7 +29,7 @@ after(() => {
     delete process.env['CRTR_HOME'];
 });
 // ---------------------------------------------------------------------------
-// Kernel + guidance: substrate flow, not MEMORY.md
+// Kernel + guidance: the document substrate flow
 // ---------------------------------------------------------------------------
 test('the orchestration kernel names the three stores and the substrate commands', () => {
     const kernel = loadKernel();
@@ -41,7 +41,7 @@ test('the orchestration kernel names the three stores and the substrate commands
     assert.ok(kernel.includes('crtr memory list'), 'kernel mentions crtr memory list');
     assert.ok(kernel.includes('crtr memory find'), 'kernel mentions crtr memory find');
     assert.ok(kernel.includes('crtr memory read'), 'kernel mentions crtr memory read');
-    // The old MEMORY.md pointer-line flow must NOT be present.
+    // It teaches the substrate flow only — no MEMORY.md pointer-line index.
     assert.ok(!kernel.includes('MEMORY.md'), 'kernel does not mention MEMORY.md');
     assert.ok(!kernel.includes('pointer line'), 'kernel does not teach the pointer-line flow');
 });
@@ -55,6 +55,6 @@ test('promotion guidance references the three stores; no <memory> block', () =>
     for (const store of ['user-global', 'project', 'node-local']) {
         assert.ok(guidance.includes(store), `guidance names the ${store} store`);
     }
-    // The old <memory> block reference must NOT be present in guidance.
-    assert.ok(!guidance.includes('<memory>'), 'guidance does not point at the removed <memory> block');
+    // The guidance points at the substrate flow, not a <memory> block.
+    assert.ok(!guidance.includes('<memory>'), 'guidance does not point at a <memory> block');
 });

package/dist/core/__tests__/subscription-delivery.test.js

@@ -79,10 +79,10 @@ test('multi-level subscription delivery: active subscriber WOKEN vs passive subs
         {
             const passiveRes = h.cli(P, ['node', 'subscribe', T, '--passive']);
             assert.equal(passiveRes.code, 0, `P→T passive subscribe exit 0\n${passiveRes.stderr}`);
-            assert.match(passiveRes.stdout, /mode="passive"/, 'P→T wired PASSIVE');
+            assert.match(passiveRes.stdout, /\(passive\)/, 'P→T wired PASSIVE');
             const activeRes = h.cli(P, ['node', 'subscribe', K]);
             assert.equal(activeRes.code, 0, `P→K active subscribe exit 0\n${activeRes.stderr}`);
-            assert.match(activeRes.stdout, /mode="active"/, 'P→K wired ACTIVE');
+            assert.match(activeRes.stdout, /\(active\)/, 'P→K wired ACTIVE');
         }
         // T now has BOTH an active (B) and a passive (P) subscriber — the crux.
         assert.deepEqual(edgeSet(h.subscribers(T)), new Set([`${B}:active`, `${P}:passive`]), 'T has B(active) + P(passive) as subscribers — the same-target split');
@@ -103,7 +103,7 @@ test('multi-level subscription delivery: active subscriber WOKEN vs passive subs
         {
             const res = h.cli(X, ['node', 'subscribe', K, '--passive']);
             assert.equal(res.code, 0, `X→K passive subscribe exit 0\n${res.stderr}`);
-            assert.match(res.stdout, /mode="passive"/, 'X→K wired PASSIVE-only (its ONLY subscription)');
+            assert.match(res.stdout, /\(passive\)/, 'X→K wired PASSIVE-only (its ONLY subscription)');
         }
         assert.deepEqual(edgeSet(h.subscriptions(X)), new Set([`${K}:passive`]), 'X holds exactly one tie: K(passive) — no active live subscription');
         const injBeforeStall = h.injected(X).length;

package/dist/core/bootstrap.js

@@ -30,36 +30,40 @@ const BOOT_SKILL_MARKER_PREFIX = '<!-- crtr-boot-skill v';
 function bootSkillBody() {
     return `---
 name: crtr-skills
-description: 'Capture, list, search, and load skills via the crtr CLI. Skills are durable agent memory — markdown future LLM sessions load on demand. Use when the user wants to remember/save knowledge, build a context primer, or recall a previously saved skill. Triggers: "save", "remember", "build context for", "what skills do we have", "skill for X".'
+description: 'Author, list, search, and load crtr memory documents (skills, references, preferences) via the crtr CLI. These are durable agent memory — markdown future LLM sessions load on demand. Use when the user wants to remember/save knowledge, build a context primer, or recall a previously saved doc. Triggers: "save", "remember", "build context for", "what skills do we have", "skill for X".'
 argument-hint: [topic or verb]
 ---
 
 ${BOOT_SKILL_MARKER}
 
-# /crtr-skills — skill router
+# /crtr-skills — crtr memory router
 
-Skills = durable agent memory. Written for **future LLM sessions**, not the
-user. \`crtr skill\` is the index — discoverable via list/search/grep.
+crtr memory documents = durable agent memory (kind: skill, reference, or
+preference). Written for **future LLM sessions**, not the user. \`crtr memory\`
+is the surface — author, discover, and load them.
 
 ## Route by intent
 
 - **Capture** ("save", "remember", "build context for", "make a skill"):
-  \`crtr skill create $ARGUMENTS\` → pick template (primer/playbook/freeform)
-  → \`crtr skill template <type> $ARGUMENTS\` for the full workflow. Follow it
-  directly.
-- **Find** ("what do we have on X"): \`crtr skill search "$ARGUMENTS"\` →
-  \`crtr skill show <name>\` on the best hit.
-- **Load by name**: \`crtr skill show <name>\`.
-- **List all**: \`crtr skill list\`.
-- **Anything else**: \`crtr skill\` (no args) prints the full workflow guide.
+  \`crtr memory write <name> --kind <skill|reference|preference>\` with the
+  body piped on stdin — e.g.
+  \`crtr memory write $ARGUMENTS --kind skill <<'EOF' … EOF\`. Run
+  \`crtr memory write -h\` for the full frontmatter schema
+  (--when-and-why-to-read, --short-form, --scope, visibility rungs), then
+  \`crtr memory lint\` to validate what you wrote.
+- **Find** ("what do we have on X"): \`crtr memory find "$ARGUMENTS"\` →
+  \`crtr memory read <name>\` on the best hit (add --body/--grep to search
+  bodies).
+- **Load by name**: \`crtr memory read <name>\`.
+- **List all**: \`crtr memory list\`.
 
 If \`$ARGUMENTS\` is empty, ask the user what they want before running.
 
 ## Rules
 
 - CLI stdout is the prompt — act on it, don't paraphrase to the user.
-- Don't load \`create\` and \`template\` outputs in the same turn (progressive
-  disclosure). \`create\` decides type; \`template\` returns the workflow.
+- Append \`-h\` at any leaf (\`crtr memory write -h\`) for its full schema
+  before authoring.
 - If \`crtr\` is not on PATH, tell the user and stop.
 `;
 }

package/dist/core/canvas/canvas.js

@@ -22,7 +22,7 @@ import { ensureHome, ensureNodeDirs, nodeMetaPath, nodeDir, nodesRoot, } from '.
 const IDENTITY_KEYS = [
     'node_id', 'name', 'description', 'cycles', 'created', 'cwd', 'host_kind', 'kind', 'mode',
     'lifecycle', 'persona_ack', 'parent', 'spawned_by', 'fork_from', 'passive_default',
-    'home_session', 'pi_session_id', 'pi_session_file', 'launch',
+    'home_session', 'pi_session_id', 'pi_session_file', 'model_override', 'launch',
 ];
 /** Project any node object down to its durable-identity subset. */
 function toIdentity(m) {

package/dist/core/canvas/types.d.ts

@@ -104,6 +104,12 @@ export interface NodeIdentity {
      *  PATH is opened directly — immune to any cwd discrepancy. Null for older
      *  nodes booted before this field existed → revive falls back to the bare id. */
     pi_session_file?: string | null;
+    /** A caller-pinned model TIER (ultra/strong/medium/light) that overrides the
+     *  persona's declared default. Durable so it survives a polymorph: every
+     *  spec-rebuild path (promote/demote/lifecycle/reset) re-passes it to
+     *  buildLaunchSpec, while the persona default is recomputed fresh for the
+     *  (possibly new) kind. Null/undefined ⇒ use the persona default. */
+    model_override?: string | null;
     /** Full pi launch recipe; rewritten on every polymorph. */
     launch?: LaunchSpec;
 }

package/dist/core/help.d.ts

@@ -94,7 +94,7 @@ export interface RootEntry {
     useWhen: string;
     /** Optional bounded block this subtree contributes to its <name> block at
      *  root. Returns a complete self-named state element (build it with
-     *  stateBlock), e.g. `<skills count="42">…</skills>`. Aggregate, never an
+     *  stateBlock), e.g. `<kinds count="7">…</kinds>`. Aggregate, never an
      *  unbounded enumeration on a cold path. Soft-fails to omission on
      *  null/throw. */
     dynamicState?: () => string | null;
@@ -141,7 +141,7 @@ export interface BranchHelp {
      *  child's purpose lives in its own listing row). */
     model?: string;
     /** Bounded runtime aggregate as a complete self-named state element (build
-     *  it with stateBlock), e.g. `<skills count="42">…</skills>`. Renderer
+     *  it with stateBlock), e.g. `<kinds count="7">…</kinds>`. Renderer
      *  soft-fails to omission if this returns null or throws. */
     dynamicState?: () => string | null;
     /** Parent-level listing assembled by defineBranch from the actual child defs.

package/dist/core/help.js

@@ -105,7 +105,7 @@ export function renderRoot(h) {
         for (const l of rootSubcommandLines(c))
             lines.push(l);
         // dynamicState returns a complete self-named element (e.g.
-        // <skills count="42">…</skills>) — emit it as-is, nested in the command.
+        // <kinds count="7">…</kinds>) — emit it as-is, nested in the command.
         const state = evalDynamic(c.dynamicState);
         if (state !== null)
             lines.push(state);

package/dist/core/render.d.ts

@@ -1,9 +1,10 @@
 import type { LeafHelp } from './help.js';
 import type { ErrorPayload } from './io.js';
-/** Schema-driven fallback: turn a result object into agent-ready XML+markdown.
+/** Schema-driven fallback: turn a result object into agent-ready plain markdown.
  *  Field order follows the leaf's declared output schema; any extra keys append
- *  after. Scalars become attributes or a bullet list, prose and collections
- *  become their own fenced blocks. */
+ *  after. Scalars (and nested objects) list as `- name: value` bullets, prose
+ *  fields render as paragraphs, and arrays become a count lead-in plus a table
+ *  or bullets. No root tag — the result is read as a continuation of the prompt. */
 export declare function renderResult(result: Record<string, unknown>, help: LeafHelp): string;
 /** Render a structured failure as an instruction-shaped block: what broke, what
  *  was received, and the recovery road sign — the same recovery info the JSON