@crouton-kit/crouter 0.3.17 → 0.3.19

package/dist/core/__tests__/human-surface-target.test.js

@@ -0,0 +1,98 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/human-surface-target.test.ts
+//
+// BUG REGRESSION: `crtr human ask|approve|review|notify` surfaced its humanloop
+// TUI in the backstage `crtr` session (the asking node's own pane) — a session
+// the user never watches — because spawnAndDetach was called with no `-t`
+// target. The fix routes the TUI to the HIGHEST FOCUSED node of the asking
+// node's graph (the viewport the user is actually watching the work in).
+//
+// This locks in the PURE selection (`graphSurfaceTarget`, db-only, no tmux):
+// walk the asking node's spine to its root, enumerate the tree root-first, and
+// return the focus row of the node closest to the root that occupies a viewport.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, subscribe } from '../canvas/canvas.js';
+import { openFocusRow, closeFocusRow, getFocusByNode } from '../canvas/focuses.js';
+import { closeDb } from '../canvas/db.js';
+import { graphSurfaceTarget } from '../runtime/placement.js';
+let home;
+let savedTmux;
+function node(id, parent) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'developer',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        parent,
+    };
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-human-surface-'));
+    process.env['CRTR_HOME'] = home;
+    savedTmux = process.env['TMUX'];
+    delete process.env['TMUX']; // PURE: graphSurfaceTarget never touches tmux
+});
+after(() => {
+    closeDb();
+    if (savedTmux !== undefined)
+        process.env['TMUX'] = savedTmux;
+    rmSync(home, { recursive: true, force: true });
+});
+// Graph R → M → W (parent edges + the auto-subscribe spine the runtime builds:
+// a parent subscribes_to its child, so view(R) walks down to M then W).
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    home = mkdtempSync(join(tmpdir(), 'crtr-human-surface-'));
+    process.env['CRTR_HOME'] = home;
+    createNode(node('R', null));
+    createNode(node('M', 'R'));
+    createNode(node('W', 'M'));
+    subscribe('R', 'M');
+    subscribe('M', 'W');
+});
+test('highest focused = the root when only the root is on screen', () => {
+    openFocusRow('f-r', '%10', 'work', 'R');
+    const t = graphSurfaceTarget('W');
+    assert.equal(t?.node_id, 'R');
+    assert.equal(t?.pane, '%10');
+});
+test('falls to the focused mid-orchestrator when the root is NOT on screen', () => {
+    openFocusRow('f-m', '%20', 'work', 'M');
+    assert.equal(graphSurfaceTarget('W')?.node_id, 'M');
+});
+test('picks the SHALLOWEST focused node when several are on screen', () => {
+    openFocusRow('f-m', '%20', 'work', 'M');
+    openFocusRow('f-w', '%30', 'work', 'W');
+    // M is closer to the root than W → M wins.
+    assert.equal(graphSurfaceTarget('W')?.node_id, 'M');
+    openFocusRow('f-r', '%10', 'work', 'R');
+    // Root trumps everything.
+    assert.equal(graphSurfaceTarget('W')?.node_id, 'R');
+});
+test('null when nothing in the graph is on screen (caller falls back)', () => {
+    assert.equal(graphSurfaceTarget('W'), null);
+});
+test('a focus row with no pane is skipped, not selected', () => {
+    openFocusRow('f-r', null, null, 'R'); // focus exists but not yet placed on a pane
+    openFocusRow('f-m', '%20', 'work', 'M');
+    assert.equal(graphSurfaceTarget('W')?.node_id, 'M');
+});
+test('the asking node itself, when it is the focused root, is returned', () => {
+    openFocusRow('f-r', '%10', 'work', 'R');
+    assert.equal(graphSurfaceTarget('R')?.node_id, 'R');
+});
+test('sanity: a closed focus drops out of the selection', () => {
+    openFocusRow('f-m', '%20', 'work', 'M');
+    assert.equal(graphSurfaceTarget('W')?.node_id, 'M');
+    closeFocusRow('f-m');
+    assert.equal(getFocusByNode('M'), null);
+    assert.equal(graphSurfaceTarget('W'), null);
+});

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

@@ -7,10 +7,11 @@
 // the regression guard for the old "build had hidden side effects" smell.
 import { test, before, after, beforeEach } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync, existsSync } from 'node:fs';
-import { tmpdir } from 'node:os';
+import { mkdtempSync, rmSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { createNode, subscribe } from '../canvas/canvas.js';
+import { reportsDir } from '../canvas/paths.js';
 import { closeDb } from '../canvas/db.js';
 import { drainBearings, buildReviveKickoff, writeYieldMessage, yieldMessagePath, } from '../runtime/kickoff.js';
 import { appendInbox, readCursor } from '../feed/inbox.js';
@@ -28,7 +29,9 @@ function node(id) {
     };
 }
 before(() => {
-    home = mkdtempSync(join(tmpdir(), 'crtr-kickoff-'));
+    // Under homedir (not tmpdir) so report paths fall under the home prefix and
+    // exercise the tildify() collapse in reportHistoryLines.
+    home = mkdtempSync(join(homedir(), '.crtr-kickoff-'));
     process.env['CRTR_HOME'] = home;
 });
 beforeEach(() => {
@@ -70,6 +73,37 @@ test('the feed block frames awaiting workers as alive + auto-waking, so a fresh
     assert.ok(/wake you the moment/.test(msg), 'states the wake is automatic on push');
     assert.ok(/still working, not stalled/.test(msg), 'frames the empty feed as expected, not a problem');
 });
+test('a fresh revive is pointed at its subscriptions\' on-disk report history (catch-up bug)', () => {
+    // Regression for the fresh-revive catch-up bug: on a refresh-yield
+    // (resume:false) the old conversation is gone AND the inbox cursor has already
+    // advanced past everything drained pre-yield, so the revived node loses sight
+    // of reports its subscriptions pushed BEFORE the yield. The bodies persist
+    // forever at reports/<ts>-<kind>.md; the kickoff must point the node at those
+    // existing paths so it can catch up. Asserts the paths are rendered.
+    const parent = createNode(node('p1'));
+    const worker = createNode(node('w1'));
+    subscribe(parent.node_id, worker.node_id);
+    // The worker pushed two reports BEFORE the parent's refresh-yield.
+    const dir = reportsDir(worker.node_id);
+    mkdirSync(dir, { recursive: true });
+    const older = join(dir, '20260608T120000-update.md');
+    const newer = join(dir, '20260608T130000-final.md');
+    writeFileSync(older, '---\n---\nearly progress', 'utf8');
+    writeFileSync(newer, '---\n---\nthe result', 'utf8');
+    const msg = buildReviveKickoff(parent, drainBearings(parent));
+    // Both existing report PATHS surface (most recent first), so the revived node
+    // can dereference the history its advanced cursor would otherwise hide. They
+    // render home-relative with a leading ~ (the absolute home prefix is wasted
+    // context tokens; ~ is still dereferenceable by the revived node).
+    const olderRel = '~' + older.slice(homedir().length);
+    const newerRel = '~' + newer.slice(homedir().length);
+    assert.ok(msg.includes(olderRel), 'older report path surfaced, home-relative (~)');
+    assert.ok(msg.includes(newerRel), 'newer report path surfaced, home-relative (~)');
+    assert.ok(!msg.includes(older), 'absolute home prefix not rendered');
+    assert.ok(msg.indexOf(newerRel) < msg.indexOf(olderRel), 'most recent report listed first');
+    // ...and the hint that the full inbox history is replayable cursor-independently.
+    assert.ok(/feed read --all/.test(msg), 'points at the cursor-independent full-history replay');
+});
 test('buildReviveKickoff is pure — building twice eats nothing', () => {
     const id = 'n2';
     const meta = createNode(node(id));

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

@@ -2,8 +2,8 @@
 //
 // AXIS: LIVE MUTATION of the 2×2 state vector (mode {base,orchestrator} ×
 // lifecycle {terminal,resident}) while a node is ACTIVE/LIVE — driven through
-// the REAL `crtr node lifecycle` / `node promote` / `node demote` CLI verbs
-// against a live fake-pi, with the REAL stophook / kickoff / daemon hooks doing
+// the REAL `crtr node lifecycle` / `node promote` / `node demote` / `node recycle`
+// CLI verbs against a live fake-pi, with the REAL stophook / kickoff / daemon hooks doing
 // the work. Every assertion reads the canvas data layer and is checked against
 // the state-model ORACLE (mq1su40t .../state-model.md).
 //
@@ -219,54 +219,71 @@ test('live mode flip: promote base→orchestrator recomposes persona_ack at turn
     }
 });
 // ===========================================================================
-// (b) MODE FLIP — demote. ⚑ FLAG vs the task framing ("demote orchestrator back
-//     to base; assert the mode field changes"): the `node demote` verb does NOT
-//     flip the SAME live node's mode orchestrator→base. Per ORACLE §4 (which
-//     matches the code: demote.ts) it FINISHES the node (push final → done) and
-//     RECYCLES the pane into a FRESH general/base/resident root — a DIFFERENT
-//     node. The demoted node keeps mode=orchestrator (it is merely `done`).
-//     There is NO live verb that flips a node orchestrator→base, so the
-//     persona.ts `baseModeGuidance` (orchestrator→base) is effectively
-//     UNREACHABLE via live mutation. This test pins the real behavior so the
-//     contradiction is visible; production is NOT changed.
+// (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 is FINISH+RECYCLE, not an orchestrator→base mode flip (current behavior vs task framing)', { skip: SKIP, timeout: 120_000 }, async () => {
+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' });
-        // Promote B so it is genuinely an orchestrator before we demote it.
+        // 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 b0 = h.node(B);
-        assert.equal(b0.mode, 'orchestrator', 'B is orchestrator before demote');
-        // 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(b0.window);
+        {
+            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');
-        // DEMOTE via the real verb (TMUX_PANE is scrubbed from child env → pass --pane).
-        const res = h.cli(B, ['node', 'demote', '--node', B, '--pane', pane]);
-        assert.equal(res.code, 0, `demote exit 0\n${res.stderr}`);
-        // The leaf renders `<demoted ... finalized=".." new_root=".."/>` (not JSON).
-        assert.match(res.stdout, /<demoted /, `demote recycled the pane\n${res.stdout}`);
+        // 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 demoted node is FINISHED, not mode-flipped.
+        // The recycled node is FINISHED, not mode-flipped.
         {
             const b = h.node(B);
-            assert.equal(b.status, 'done', 'demoted node → done (finished), NOT re-roled');
+            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', '⚑ demoted node KEEPS mode=orchestrator — demote is NOT an orchestrator→base flip');
-            assert.ok(finalized, 'demote pushed a final for the node');
+            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 — that is where "base"
-        // comes from, not a mutation of B.
+        // 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)');
-            // Born acked to its own persona → it will never see an orchestrator→base
-            // drift steer: that persona path is unreachable through live mutation.
-            assert.deepEqual(fresh.persona_ack, { mode: 'base', lifecycle: 'resident' }, 'fresh root born acked base×resident — no orchestrator→base drift will ever fire');
+            assert.deepEqual(fresh.persona_ack, { mode: 'base', lifecycle: 'resident' }, 'fresh root born acked base×resident');
         }
     }
     finally {

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

@@ -1,31 +1,20 @@
-// Tests for the three-tier scoped memory (src/core/runtime/memory.ts):
-//   1. The three store paths land under crtrHome (user-global / project / node).
-//   2. projectKey resolves the git-repo-root (walk up for .git), and falls back
-//      to the cwd itself when not inside a repo.
-//   3. seed* are guarded/idempotent (never clobber an evolved index).
-//   4. promote() seeds ALL THREE stores, guarded across re-promotion.
-//   5. The kernel + promotion guidance name the type\u2192store mapping.
-//
-// CRTR_HOME isolation, like context-intro.test.ts.
+// Tests for the substrate memory surface in the orchestration kernel:
+//   1. The kernel names the three memory scopes and the document substrate flow
+//      (crtr memory write/list/find/read).
+//   2. Promotion guidance names the three stores without re-listing their dirs.
 //
 // Run: node --import tsx/esm --test src/core/__tests__/memory.test.ts
 import { test, before, beforeEach, after } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync } from 'node:fs';
+import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { closeDb } from '../canvas/db.js';
-import { crtrHome } from '../canvas/paths.js';
-import { mangleCwd } from '../artifact.js';
 import { spawnNode } from '../runtime/nodes.js';
 import { promote } from '../runtime/promote.js';
 import { personaDrift } from '../runtime/persona.js';
 import { loadKernel } from '../personas/index.js';
-import { memoryDir, memoryPath, userMemoryDir, userMemoryPath, hasUserMemory, readUserMemory, seedUserMemory, projectKey, projectMemoryDir, projectMemoryPath, hasProjectMemory, readProjectMemory, seedProjectMemory, hasMemory, USER_MEMORY_TEMPLATE, PROJECT_MEMORY_TEMPLATE, } from '../runtime/memory.js';
 let home;
-// Scratch repos created per-test for the git-root keying cases; tracked so they
-// can be removed in `after` regardless of which test created them.
-const scratch = [];
 before(() => {
     home = mkdtempSync(join(tmpdir(), 'crtr-memory-'));
     process.env['CRTR_HOME'] = home;
@@ -37,116 +26,35 @@ beforeEach(() => {
 after(() => {
     closeDb();
     rmSync(home, { recursive: true, force: true });
-    for (const d of scratch)
-        rmSync(d, { recursive: true, force: true });
     delete process.env['CRTR_HOME'];
 });
 // ---------------------------------------------------------------------------
-// Store paths
-// ---------------------------------------------------------------------------
-test('the three stores all live under crtrHome, at their scoped paths', () => {
-    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
-    // user-global: <crtrHome>/memory/
-    assert.equal(userMemoryDir(), join(crtrHome(), 'memory'));
-    assert.equal(userMemoryPath(), join(crtrHome(), 'memory', 'MEMORY.md'));
-    // project: <crtrHome>/projects/<key>/memory/
-    assert.equal(projectMemoryDir('/tmp/work'), join(crtrHome(), 'projects', projectKey('/tmp/work'), 'memory'));
-    assert.equal(projectMemoryPath('/tmp/work'), join(projectMemoryDir('/tmp/work'), 'MEMORY.md'));
-    // node-local: <crtrHome>/nodes/<id>/context/memory/ (unchanged)
-    assert.ok(memoryDir(meta.node_id).startsWith(join(crtrHome(), 'nodes', meta.node_id)));
-    assert.ok(memoryPath(meta.node_id).endsWith('/context/memory/MEMORY.md'));
-});
-// ---------------------------------------------------------------------------
-// projectKey: git-root vs not-in-a-repo fallback
-// ---------------------------------------------------------------------------
-test('projectKey resolves the git-repo-root by walking up for a .git entry', () => {
-    const repo = mkdtempSync(join(tmpdir(), 'crtr-repo-'));
-    scratch.push(repo);
-    mkdirSync(join(repo, '.git')); // a .git directory marks the repo root
-    const nested = join(repo, 'pkg', 'src');
-    mkdirSync(nested, { recursive: true });
-    // A cwd deep inside the repo keys to the repo ROOT, not the cwd.
-    assert.equal(projectKey(nested), mangleCwd(repo));
-    assert.equal(projectKey(repo), mangleCwd(repo));
-    // A .git FILE (worktree/submodule) is recognized the same way.
-    const wt = mkdtempSync(join(tmpdir(), 'crtr-wt-'));
-    scratch.push(wt);
-    writeFileSync(join(wt, '.git'), 'gitdir: /elsewhere\n');
-    assert.equal(projectKey(join(wt, 'a')), mangleCwd(wt));
-});
-test('projectKey falls back to the mangled cwd when not inside a repo', () => {
-    const bare = mkdtempSync(join(tmpdir(), 'crtr-bare-'));
-    scratch.push(bare);
-    const sub = join(bare, 'x', 'y');
-    mkdirSync(sub, { recursive: true });
-    // No .git anywhere up the tree \u2192 the cwd itself is the key.
-    assert.equal(projectKey(sub), mangleCwd(sub));
-});
-// ---------------------------------------------------------------------------
-// seed*: guarded / idempotent
-// ---------------------------------------------------------------------------
-test('seedUserMemory / seedProjectMemory write the template once, then never clobber', () => {
-    assert.equal(hasUserMemory(), false);
-    assert.equal(seedUserMemory(), true, 'first seed writes');
-    assert.equal(readUserMemory(), USER_MEMORY_TEMPLATE);
-    assert.equal(hasUserMemory(), true);
-    const evolved = '# Memory\n\n- [Likes terse replies](terse.md) \u2014 keep it short\n';
-    writeFileSync(userMemoryPath(), evolved);
-    assert.equal(seedUserMemory(), false, 'second seed is a no-op');
-    assert.equal(readUserMemory(), evolved, 'evolved index left untouched');
-    assert.equal(seedProjectMemory('/tmp/work'), true, 'project first seed writes');
-    assert.equal(readProjectMemory('/tmp/work'), PROJECT_MEMORY_TEMPLATE);
-    assert.equal(seedProjectMemory('/tmp/work'), false, 'project second seed is a no-op');
-});
-// ---------------------------------------------------------------------------
-// promote(): seeds all three, guarded across re-promotion
-// ---------------------------------------------------------------------------
-test('promote() seeds all three stores and surfaces all three paths', () => {
-    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
-    assert.equal(hasMemory(meta.node_id), false);
-    assert.equal(hasUserMemory(), false);
-    assert.equal(hasProjectMemory('/tmp/work'), false);
-    const res = promote(meta.node_id);
-    assert.ok(hasMemory(meta.node_id), 'node-local seeded');
-    assert.ok(hasUserMemory(), 'user-global seeded');
-    assert.ok(hasProjectMemory('/tmp/work'), 'project seeded');
-    assert.ok(existsSync(userMemoryDir()), 'user dir created for direct writes');
-    assert.ok(existsSync(projectMemoryDir('/tmp/work')), 'project dir created for direct writes');
-    assert.equal(res.memoryPath, memoryPath(meta.node_id));
-    assert.equal(res.userMemoryPath, userMemoryPath());
-    assert.equal(res.projectMemoryPath, projectMemoryPath('/tmp/work'));
-});
-test('promote() is idempotent across re-promotion \u2014 never clobbers evolved stores', () => {
-    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
-    promote(meta.node_id);
-    const evolvedUser = '# Memory\n\n- [CTO, terse](cto.md) \u2014 senior, wants density\n';
-    const evolvedProject = '# Memory\n\n- [ESM only](esm.md) \u2014 .js extensions required\n';
-    writeFileSync(userMemoryPath(), evolvedUser);
-    writeFileSync(projectMemoryPath('/tmp/work'), evolvedProject);
-    promote(meta.node_id); // re-promote
-    assert.equal(readUserMemory(), evolvedUser, 'user store survived re-promotion');
-    assert.equal(readProjectMemory('/tmp/work'), evolvedProject, 'project store survived re-promotion');
-});
-// ---------------------------------------------------------------------------
-// The kernel + guidance name the type\u2192store mapping
+// Kernel + guidance: substrate flow, not MEMORY.md
 // ---------------------------------------------------------------------------
-test('the orchestration kernel names the three stores and the type\u2192store mapping', () => {
+test('the orchestration kernel names the three stores and the substrate commands', () => {
     const kernel = loadKernel();
     for (const store of ['user-global', 'project', 'node-local']) {
         assert.ok(kernel.includes(store), `kernel names the ${store} store`);
     }
-    // The type taxonomy still drives placement.
-    assert.match(kernel, /`type`/, 'kernel still frames the type taxonomy');
-    assert.match(kernel, /user.*\u2192.*user-global|`user` \u2192 user-global/, 'maps user \u2192 user-global');
-});
-test('promotion guidance names all three stores so a base-spawned node learns where to write', () => {
+    // The substrate commands must be present.
+    assert.ok(kernel.includes('crtr memory write'), 'kernel mentions crtr memory write');
+    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.
+    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');
+});
+test('promotion guidance references the three stores; no <memory> block', () => {
     const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
     promote(meta.node_id);
-    // Guidance is now built by the persona injector, not returned by promote().
-    const guidance = personaDrift(meta.node_id)?.guidance ?? '';
+    const drift = personaDrift(meta.node_id);
+    assert.ok(drift !== null, 'promotion drifts the persona');
+    const guidance = drift.guidance;
+    // It NAMES the three stores so a promoting node knows its memory scopes.
     for (const store of ['user-global', 'project', 'node-local']) {
         assert.ok(guidance.includes(store), `guidance names the ${store} store`);
     }
-    assert.ok(guidance.includes(userMemoryDir()), 'guidance names the user-global dir');
-    assert.ok(guidance.includes(projectMemoryDir('/tmp/work')), 'guidance names the project dir');
+    // 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');
 });

package/dist/core/__tests__/persona-subkind.test.js

@@ -1,15 +1,18 @@
 // Run: node --import tsx/esm --test src/core/__tests__/persona-subkind.test.ts
 //
-// Scoped persona sub-kinds: a kind owns specialist reviewer personas at
-// `<kind>/reviewers/<name>/base.md`, enumerated by `subKindsFor(kind)` and
+// Scoped persona sub-personas: a kind has specialist reviewer personas at
+// `<kind>/reviewers/<name>/PERSONA.md`, enumerated by `subPersonasFor(kind)` and
 // rendered into that kind's composed prompt (and nowhere else) by `resolve`.
-// Visibility = membership: only `plan` sees the `plan/reviewers/*` menu; the
-// sub-kinds never pollute the global `availableKinds()` list; and a sub-kind
-// itself boots as a real composed persona with the terminal finish contract.
+// Visibility = membership (the sub-persona's `availableTo`, default = its
+// top-level ancestor kind): only `plan` sees the `plan/reviewers/*` menu; the
+// `reviewers/` grouping dir is transparent so the kind string keeps it; the
+// sub-personas never pollute the global `availableKinds()` list; and a
+// sub-persona itself boots as a real composed persona with the terminal finish
+// contract.
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { resolve } from '../personas/resolve.js';
-import { subKindsFor, availableKinds } from '../personas/loader.js';
+import { subPersonasFor, availableKinds } from '../personas/loader.js';
 const PLAN_REVIEWER_KINDS = [
     'plan/reviewers/architecture-fit',
     'plan/reviewers/code-smells',
@@ -17,19 +20,19 @@ const PLAN_REVIEWER_KINDS = [
     'plan/reviewers/requirements-coverage',
     'plan/reviewers/security',
 ];
-const MENU_HEADER = 'Reviewer sub-kinds you may spawn';
-test('subKindsFor("plan") returns the five reviewers sorted, each with a non-empty summary', () => {
-    const subs = subKindsFor('plan');
-    assert.deepEqual(subs.map((s) => s.kind), PLAN_REVIEWER_KINDS, 'the five plan reviewer kind strings in sorted order');
+const MENU_HEADER = 'Sub-personas you may spawn';
+test('subPersonasFor("plan") returns the five reviewers sorted, each with a non-empty whenToUse', () => {
+    const subs = subPersonasFor('plan');
+    assert.deepEqual(subs.map((s) => s.kind), PLAN_REVIEWER_KINDS, 'the five plan reviewer kind strings in sorted order — the transparent reviewers/ dir keeps the full kind path');
     for (const s of subs) {
-        assert.ok(s.summary.length > 0, `${s.kind} carries a non-empty summary`);
+        assert.ok(s.whenToUse.length > 0, `${s.kind} carries a non-empty whenToUse`);
     }
 });
-test('sub-kinds do not recurse and absent rosters yield []', () => {
-    assert.deepEqual(subKindsFor('explore'), [], 'explore owns no reviewers/');
-    assert.deepEqual(subKindsFor('plan/reviewers/security'), [], 'a sub-kind owns no nested reviewers/ — no recursion');
+test('availability is membership: a kind with no available sub-personas yields []', () => {
+    assert.deepEqual(subPersonasFor('explore'), [], 'no sub-persona is availableTo explore');
+    assert.deepEqual(subPersonasFor('plan/reviewers/security'), [], 'the five reviewers default availableTo:[plan] — none are available to a reviewer kind');
 });
-test('availableKinds() contains no plan/reviewers/* — sub-kinds never pollute the global list', () => {
+test('availableKinds() contains no plan/reviewers/* — sub-personas never pollute the global list', () => {
     const kinds = availableKinds();
     for (const k of PLAN_REVIEWER_KINDS) {
         assert.ok(!kinds.includes(k), `${k} must not appear in availableKinds()`);

package/dist/core/__tests__/placement-focus.test.js

@@ -267,6 +267,11 @@ test('detachToBackground: a FOCUSED node sent to the backstage CLOSES its focus
             createNode(node('N', { pane: focusPane, tmux_session: user, window: userWindow, status: 'active', pi_pid: process.pid, home_session: back }));
             openFocusRow('f1', focusPane, user, 'N'); // N is the focus occupant
             assert.equal(getFocusByNode('N')?.focus_id, 'f1', 'precondition: N is focused');
+            // N must read as GENERATING for the relocate-to-backstage path: detach now
+            // gates the break-pane (Bug 1 / Invariant P) on isGenerating = busy &&
+            // pidAlive. pi_pid is this (alive) process; set the busy marker so N is
+            // genuinely mid-turn (otherwise the gate would RELEASE + reap it instead).
+            markBusy('N');
             const ok = detachToBackground('N', focusPane);
             assert.equal(ok, true, 'the break to the backstage succeeded');
             // The fix: N is now generating-but-UNFOCUSED, so its focus row is CLOSED.