@crouton-kit/crouter 0.3.14 → 0.3.16

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

@@ -0,0 +1,238 @@
+import { test, before, beforeEach, after } 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 { DatabaseSync } from 'node:sqlite';
+import { openDb, closeDb, migrate, MIGRATIONS } from '../canvas/db.js';
+import { canvasDbPath, ensureHome } from '../canvas/paths.js';
+const RUNTIME_COLUMNS = ['intent', 'pi_pid', 'window', 'tmux_session'];
+let home;
+function userVersion(db) {
+    return db.prepare('PRAGMA user_version').get()
+        .user_version;
+}
+function nodeColumns(db) {
+    return db.prepare('PRAGMA table_info(nodes)').all().map((r) => r.name);
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-migration-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    // Fresh db + dirs per test for isolation.
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('opening a fresh home migrates to the latest user_version', () => {
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length);
+});
+test('a fresh db has the four additive runtime columns', () => {
+    const db = openDb();
+    const cols = nodeColumns(db);
+    for (const c of RUNTIME_COLUMNS) {
+        assert.ok(cols.includes(c), `expected nodes.${c} to exist`);
+    }
+    // `status` predates Phase 1 and must not be duplicated.
+    assert.equal(cols.filter((c) => c === 'status').length, 1, 'status must appear exactly once');
+});
+test('a simulated v0 db migrates forward without data loss', () => {
+    // Build a v0 db by hand: the baseline tables only, user_version 0, no runtime
+    // columns — exactly the shape of the live fleet before this phase.
+    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
+    );
+    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)
+    );
+  `);
+    raw.exec('PRAGMA user_version = 0;');
+    raw
+        .prepare('INSERT INTO nodes (node_id, name, kind, status, cwd, created) VALUES (?,?,?,?,?,?)')
+        .run('n1', 'N1', 'general', 'done', '/tmp/work', '2020-01-01T00:00:00Z');
+    raw
+        .prepare('INSERT INTO edges (type, from_id, to_id, created) VALUES (?,?,?,?)')
+        .run('subscribes_to', 'n1', 'n1', '2020-01-01T00:00:00Z');
+    // Precondition: genuinely a v0 db with no runtime columns.
+    assert.equal(userVersion(raw), 0);
+    assert.ok(!nodeColumns(raw).includes('intent'));
+    raw.close();
+    // openDb() runs the migration runner forward.
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    // Runtime columns now exist.
+    const cols = nodeColumns(db);
+    for (const c of RUNTIME_COLUMNS) {
+        assert.ok(cols.includes(c), `expected nodes.${c} after migration`);
+    }
+    // Pre-existing data is intact — no loss, no mutation of existing columns.
+    const row = db
+        .prepare('SELECT node_id, status, cwd FROM nodes WHERE node_id = ?')
+        .get('n1');
+    assert.equal(row.node_id, 'n1');
+    assert.equal(row.status, 'done');
+    assert.equal(row.cwd, '/tmp/work');
+    const edgeCount = db.prepare('SELECT COUNT(*) AS n FROM edges').get().n;
+    assert.equal(edgeCount, 1);
+    // The new columns are seeded NULL for the migrated row — nothing observed.
+    const rt = db
+        .prepare('SELECT intent, pi_pid, "window", tmux_session FROM nodes WHERE node_id = ?')
+        .get('n1');
+    assert.equal(rt['intent'], null);
+    assert.equal(rt['pi_pid'], null);
+    assert.equal(rt['window'], null);
+    assert.equal(rt['tmux_session'], null);
+});
+// --- v4: edges FK ON DELETE CASCADE (the one irreversible rebuild) ------------
+/** Build a hand-rolled db at exactly v3 (baseline tables + the four runtime
+ *  columns, edges with NO foreign key, `user_version = 3`) — the shape the live
+ *  fleet reaches just before v4. Caller seeds it, we close it; the next openDb()
+ *  runs only v4 over it. */
+function buildV3Db() {
+    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
+    );
+    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)
+    );
+    PRAGMA user_version = 3;
+  `);
+    return raw;
+}
+function insertNode(db, id) {
+    db.prepare('INSERT INTO nodes (node_id, name, kind, status, cwd, created) VALUES (?,?,?,?,?,?)').run(id, id, 'general', 'active', '/tmp/work', '2020-01-01T00:00:00Z');
+}
+function insertEdge(db, type, from, to) {
+    db.prepare('INSERT INTO edges (type, from_id, to_id, created) VALUES (?,?,?,?)').run(type, from, to, '2020-01-01T00:00:00Z');
+}
+function edgeCount(db) {
+    return db.prepare('SELECT COUNT(*) AS n FROM edges').get().n;
+}
+test('v4 migrates a db with a pre-existing orphan edge without throwing', () => {
+    const raw = buildV3Db();
+    insertNode(raw, 'n1');
+    insertNode(raw, 'n2');
+    insertEdge(raw, 'subscribes_to', 'n1', 'n2'); // non-orphan: both endpoints exist
+    insertEdge(raw, 'spawned_by', 'n1', 'ghost'); // ORPHAN: 'ghost' has no node row
+    assert.equal(userVersion(raw), 3);
+    assert.equal(edgeCount(raw), 2);
+    raw.close();
+    // openDb() runs v4. It must NOT throw on the orphan, and must drop it.
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length); // migrated forward to the head
+    // The orphan edge is filtered; the non-orphan edge + its count are preserved.
+    assert.equal(edgeCount(db), 1);
+    const surviving = db
+        .prepare('SELECT type, from_id, to_id FROM edges')
+        .get();
+    assert.equal(surviving.type, 'subscribes_to');
+    assert.equal(surviving.from_id, 'n1');
+    assert.equal(surviving.to_id, 'n2');
+});
+test('v4 leaves the FK live: an edge to a missing node is rejected', () => {
+    const raw = buildV3Db();
+    insertNode(raw, 'n1');
+    raw.close();
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    // Inserting an edge whose endpoint has no node row now violates the FK.
+    assert.throws(() => db
+        .prepare('INSERT INTO edges (type, from_id, to_id, active, created) VALUES (?,?,?,?,?)')
+        .run('spawned_by', 'n1', 'missing', 1, '2020-01-01T00:00:00Z'), /FOREIGN KEY|constraint/i);
+    // A fully-valid edge (both endpoints present) still inserts fine.
+    insertNode(db, 'n3');
+    assert.doesNotThrow(() => db
+        .prepare('INSERT INTO edges (type, from_id, to_id, active, created) VALUES (?,?,?,?,?)')
+        .run('subscribes_to', 'n1', 'n3', 1, '2020-01-01T00:00:00Z'));
+});
+test('v4 deleting a node cascade-deletes its edges', () => {
+    const raw = buildV3Db();
+    insertNode(raw, 'a');
+    insertNode(raw, 'b');
+    insertEdge(raw, 'subscribes_to', 'a', 'b');
+    insertEdge(raw, 'spawned_by', 'b', 'a');
+    raw.close();
+    const db = openDb();
+    assert.equal(edgeCount(db), 2);
+    // Delete one endpoint — every edge touching it cascades away.
+    db.prepare('DELETE FROM nodes WHERE node_id = ?').run('a');
+    assert.equal(edgeCount(db), 0);
+});
+test('v4 is idempotent on re-open', () => {
+    const raw = buildV3Db();
+    insertNode(raw, 'n1');
+    insertEdge(raw, 'subscribes_to', 'n1', 'n1');
+    raw.close();
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    assert.equal(edgeCount(db), 1);
+    // Re-running migrate() directly is a no-op (gate skips applied steps); the
+    // edges table is NOT rebuilt again.
+    assert.doesNotThrow(() => migrate(db));
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    assert.equal(edgeCount(db), 1);
+    // Re-opening from disk is likewise a no-op — the FK + data persist.
+    closeDb();
+    const db2 = openDb();
+    assert.equal(userVersion(db2), MIGRATIONS.length);
+    assert.equal(edgeCount(db2), 1);
+});
+test('migration is idempotent on re-open and on re-run', () => {
+    // First open migrates v0 -> latest.
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    // Re-running migrate() directly is a no-op (the gate skips applied steps).
+    // If the gate were broken, the second ALTER ADD COLUMN would throw.
+    assert.doesNotThrow(() => migrate(db));
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    // Re-opening from disk is likewise a no-op — no duplicate-column error.
+    closeDb();
+    const db2 = openDb();
+    assert.equal(userVersion(db2), MIGRATIONS.length);
+    const cols = nodeColumns(db2);
+    for (const c of RUNTIME_COLUMNS) {
+        assert.ok(cols.includes(c), `expected nodes.${c} to persist`);
+    }
+});

package/dist/core/__tests__/pane-column.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/pane-column.test.js

@@ -0,0 +1,153 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/pane-column.test.ts
+//
+// STEP 2 of the placement/focus migration: the `pane` runtime column —
+// LOCATION's authoritative handle (the durable tmux `%pane_id`). This step is
+// PURELY ADDITIVE: the column exists, setPresence writes it, getNode/getRow read
+// it back, but nothing READS it for behavior yet (population wires up in Steps
+// 3+). Covers:
+//   - migration v5 adds `pane` to a fresh db (and a legacy v4 db migrates up)
+//   - createNode seeds pane; setPresence writes it atomically with window/session
+//   - getNode (hydrated view) + getRow (row) both read pane back
+//   - a row never given a pane reads pane=null (legacy/back-compat)
+//   - the migration is idempotent / forward-only (re-open is a no-op)
+import { test, before, beforeEach, after } 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 { DatabaseSync } from 'node:sqlite';
+import { createNode, getNode, getRow, setPresence } from '../canvas/canvas.js';
+import { openDb, closeDb, migrate, MIGRATIONS } from '../canvas/db.js';
+import { canvasDbPath, ensureHome } from '../canvas/paths.js';
+let home;
+function node(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...over,
+    };
+}
+function userVersion(db) {
+    return db.prepare('PRAGMA user_version').get().user_version;
+}
+function nodeColumns(db) {
+    return db.prepare('PRAGMA table_info(nodes)').all().map((r) => r.name);
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-pane-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+// ---------------------------------------------------------------------------
+// Migration v5 — the additive `pane` column.
+// ---------------------------------------------------------------------------
+test('a fresh db migrates to the latest version and has the pane column', () => {
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    assert.ok(nodeColumns(db).includes('pane'), 'nodes.pane exists on a fresh db');
+});
+test('a v4 db migrates forward, adding pane=NULL without disturbing existing data', () => {
+    // Hand-build a db at exactly v4: baseline + the four v2 runtime columns +
+    // edges WITH the v4 FK shape, user_version=4 — the shape just before v5.
+    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
+    );
+    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),
+      FOREIGN KEY (from_id) REFERENCES nodes(node_id) ON DELETE CASCADE,
+      FOREIGN KEY (to_id)   REFERENCES nodes(node_id) ON DELETE CASCADE
+    );
+    PRAGMA user_version = 4;
+  `);
+    raw
+        .prepare('INSERT INTO nodes (node_id, name, kind, status, cwd, created, window, tmux_session) VALUES (?,?,?,?,?,?,?,?)')
+        .run('legacy', 'Legacy', 'general', 'idle', '/tmp/work', '2020-01-01T00:00:00Z', '@9', 'crtr');
+    assert.equal(userVersion(raw), 4);
+    assert.ok(!nodeColumns(raw).includes('pane'), 'precondition: no pane column at v4');
+    raw.close();
+    // openDb() runs v5 forward.
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    assert.ok(nodeColumns(db).includes('pane'), 'pane column added by v5');
+    // The pre-existing row is intact; its pane backfills NULL (additive default).
+    const row = db
+        .prepare('SELECT status, window, tmux_session, pane FROM nodes WHERE node_id = ?')
+        .get('legacy');
+    assert.equal(row['status'], 'idle', 'existing status untouched');
+    assert.equal(row['window'], '@9', 'existing window untouched');
+    assert.equal(row['tmux_session'], 'crtr', 'existing session untouched');
+    assert.equal(row['pane'], null, 'pane defaults NULL for a legacy row');
+});
+test('the migration is idempotent / forward-only on re-run and re-open', () => {
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    // Re-running migrate() is a no-op — the gate skips applied steps, so the v5
+    // ALTER ADD COLUMN never fires twice (which would throw "duplicate column").
+    assert.doesNotThrow(() => migrate(db));
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    // Re-opening from disk is likewise a no-op.
+    closeDb();
+    const db2 = openDb();
+    assert.equal(userVersion(db2), MIGRATIONS.length);
+    assert.ok(nodeColumns(db2).includes('pane'));
+});
+// ---------------------------------------------------------------------------
+// Round-trip: pane is a RUNTIME field, authoritative in the row, read back by
+// both the hydrated view (getNode) and the row (getRow).
+// ---------------------------------------------------------------------------
+test('createNode seeds pane and getNode/getRow read it back', () => {
+    createNode(node('n', { tmux_session: 'crtr', window: '@1', pane: '%5' }));
+    assert.equal(getNode('n')?.pane, '%5', 'getNode hydrates pane from the row');
+    assert.equal(getRow('n')?.pane, '%5', 'getRow returns pane on the NodeRow');
+});
+test('a node created without a pane reads pane=null (legacy / back-compat)', () => {
+    createNode(node('n', { tmux_session: 'crtr', window: '@1' }));
+    assert.equal(getNode('n')?.pane, null, 'no pane given → null on the hydrated view');
+    assert.equal(getRow('n')?.pane, null, 'no pane given → null on the row');
+});
+test('setPresence writes pane atomically alongside window + session', () => {
+    createNode(node('n'));
+    setPresence('n', { tmux_session: 'user-sess', window: '@2', pane: '%7' });
+    const m = getNode('n');
+    assert.equal(m?.pane, '%7', 'setPresence wrote the pane');
+    assert.equal(m?.window, '@2', 'setPresence wrote the window in the same statement');
+    assert.equal(m?.tmux_session, 'user-sess', 'setPresence wrote the session in the same statement');
+});
+test('setPresence without pane writes null (the Step-2 contract: nobody reads pane yet)', () => {
+    createNode(node('n', { pane: '%7' }));
+    assert.equal(getNode('n')?.pane, '%7');
+    // A presence write that omits pane resets it to null — fine for Step 2 because
+    // no reader depends on pane until the placement layer lands (Steps 3+).
+    setPresence('n', { tmux_session: 'crtr', window: '@3' });
+    assert.equal(getNode('n')?.pane, null, 'omitted pane → null (no half-written LOCATION)');
+});
+test('pane is a RUNTIME field — it never leaks into meta.json identity', () => {
+    createNode(node('n', { pane: '%5' }));
+    setPresence('n', { pane: '%9', window: '@1', tmux_session: 'crtr' });
+    // meta.json is durable identity only; the runtime pane lives in the row.
+    const onDisk = openDb().prepare('SELECT pane FROM nodes WHERE node_id = ?').get('n');
+    assert.equal(onDisk.pane, '%9', 'pane is authoritative in the row');
+});

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

@@ -9,7 +9,7 @@
 // Run: node --import tsx/esm --test src/core/__tests__/passive-subscription.test.ts
 import { test, before, beforeEach, after } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync, existsSync } from 'node:fs';
+import { mkdtempSync, rmSync, existsSync, appendFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createNode, subscribe } from '../canvas/canvas.js';
@@ -96,6 +96,29 @@ test('drainPassive reads then clears (surfaces exactly once)', () => {
     assert.equal(drainPassive('observer').length, 0);
     assert.equal(readPassive('observer').length, 0);
 });
+test('drainPassive tolerates a corrupt line — keeps every good entry, loses only the bad one', () => {
+    createNode(node('observer'));
+    appendPassive('observer', { from: 'a', tier: 'normal', kind: 'update', label: 'one' });
+    appendPassive('observer', { from: 'b', tier: 'normal', kind: 'update', label: 'two' });
+    // A torn/garbage line lands between good entries (a partial write, a crash
+    // mid-append). The whole feed must NOT be discarded over it.
+    appendFileSync(passivePath('observer'), '{not valid json\n', 'utf8');
+    appendPassive('observer', { from: 'c', tier: 'normal', kind: 'update', label: 'three' });
+    const drained = drainPassive('observer');
+    assert.equal(drained.length, 3, 'all three good entries survive the corrupt line');
+    assert.deepEqual(drained.map((e) => e.label), ['one', 'two', 'three']);
+    // And it still cleared: a second drain is empty (snapshot removed).
+    assert.equal(drainPassive('observer').length, 0);
+    assert.equal(existsSync(passivePath('observer')), false);
+});
+test('readPassive tolerates a corrupt line without clearing', () => {
+    createNode(node('observer'));
+    appendPassive('observer', { from: 'a', tier: 'normal', kind: 'update', label: 'one' });
+    appendFileSync(passivePath('observer'), 'garbage}\n', 'utf8');
+    appendPassive('observer', { from: 'b', tier: 'normal', kind: 'update', label: 'two' });
+    const read = readPassive('observer');
+    assert.deepEqual(read.map((e) => e.label), ['one', 'two']);
+});
 test('formatPassive renders timestamped XML update blocks', () => {
     const entries = [
         { ts: '2026-06-03T12:00:00.000Z', from: 'pub-a', tier: 'normal', kind: 'update', label: 'alpha happened' },

package/dist/core/__tests__/persona-compose.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,53 @@
+// Run: node --import tsx/esm --test src/core/__tests__/persona-compose.test.ts
+//
+// The static system-prompt composer (core/personas/resolve.ts) varies the
+// runtime protocol on TWO axes beyond kind×mode:
+//   • lifecycle (terminal | resident) — the "how you end" contract.
+//   • spine position (hasManager) — whether the push-up family is taught AT ALL.
+// These assert the four corners, especially the resident+no-manager root that
+// must never hear about `push` (final OR update).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { resolve } from '../personas/index.js';
+// The lifecycle fragment is identified by its signature contract phrase, not by
+// the raw "push final" substring — the resident fragment legitimately NAMES
+// `push final` only to forbid it. The kind body is now lifecycle-neutral, so the
+// only finish contract in the prompt is whichever fragment composed.
+const TERMINAL_CONTRACT = /owe a final result and you reap when done/i;
+const RESIDENT_CONTRACT = /never forced to submit a final result/i;
+const PUSH_UP = /crtr push (update|urgent)/i;
+test('terminal + has-manager (the default child worker): terminal finish + push up', () => {
+    const p = resolve('general', 'base', { lifecycle: 'terminal', hasManager: true });
+    assert.match(p.systemPrompt, TERMINAL_CONTRACT, 'a terminal node owes a final and finishes via push final');
+    assert.doesNotMatch(p.systemPrompt, RESIDENT_CONTRACT);
+    assert.match(p.systemPrompt, PUSH_UP, 'a managed node reports up via push update/urgent');
+    assert.equal(p.lifecycle, 'terminal');
+});
+test('resident + no-manager (the user-facing root): resident finish, and NO push-up family at all', () => {
+    const p = resolve('general', 'base', { lifecycle: 'resident', hasManager: false });
+    assert.match(p.systemPrompt, RESIDENT_CONTRACT, 'a resident root is never forced to submit');
+    assert.doesNotMatch(p.systemPrompt, TERMINAL_CONTRACT, 'it does not get the terminal finish contract');
+    assert.doesNotMatch(p.systemPrompt, PUSH_UP, 'a top-of-spine root has nobody to push up to');
+    assert.match(p.systemPrompt, /top of your spine/i, 'oriented as top-of-spine');
+    assert.match(p.systemPrompt, /dormant/i, 'told it goes dormant and wakes');
+});
+test('resident + has-manager (interactable sub-orchestrator): resident finish, but still push up', () => {
+    const p = resolve('general', 'base', { lifecycle: 'resident', hasManager: true });
+    assert.match(p.systemPrompt, RESIDENT_CONTRACT, 'resident is never forced to submit a final');
+    assert.doesNotMatch(p.systemPrompt, TERMINAL_CONTRACT);
+    assert.match(p.systemPrompt, PUSH_UP, 'still reports progress up to its manager');
+});
+test('terminal + no-manager (a terminal root): terminal finish, but no push up', () => {
+    const p = resolve('general', 'base', { lifecycle: 'terminal', hasManager: false });
+    assert.match(p.systemPrompt, TERMINAL_CONTRACT, 'terminal still finishes via push final (self-completes)');
+    assert.doesNotMatch(p.systemPrompt, PUSH_UP, 'nobody subscribes, so no report-up family');
+});
+test('the lifecycle-neutral base survives in every corner (delegate + human ask)', () => {
+    for (const hasManager of [true, false]) {
+        for (const lifecycle of ['terminal', 'resident']) {
+            const p = resolve('general', 'base', { lifecycle, hasManager });
+            assert.match(p.systemPrompt, /crtr node new/, `delegate verb present (${lifecycle}/${hasManager})`);
+            assert.match(p.systemPrompt, /crtr human ask/, `human-ask present (${lifecycle}/${hasManager})`);
+        }
+    }
+});

package/dist/core/__tests__/persona-subkind.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,62 @@
+// 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
+// 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.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { resolve } from '../personas/resolve.js';
+import { subKindsFor, availableKinds } from '../personas/loader.js';
+const PLAN_REVIEWER_KINDS = [
+    'plan/reviewers/architecture-fit',
+    'plan/reviewers/code-smells',
+    'plan/reviewers/pattern-consistency',
+    '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');
+    for (const s of subs) {
+        assert.ok(s.summary.length > 0, `${s.kind} carries a non-empty summary`);
+    }
+});
+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('availableKinds() contains no plan/reviewers/* — sub-kinds 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()`);
+    }
+    assert.ok(!kinds.some((k) => k.includes('reviewers')), 'no kind contains "reviewers"');
+});
+test('resolve(plan, orchestrator) renders the menu with all five reviewer strings', () => {
+    const p = resolve('plan', 'orchestrator', { lifecycle: 'terminal', hasManager: true });
+    assert.match(p.systemPrompt, new RegExp(MENU_HEADER), 'the menu header is present');
+    for (const k of PLAN_REVIEWER_KINDS) {
+        assert.ok(p.systemPrompt.includes(k), `menu lists ${k}`);
+    }
+});
+test('resolve(plan, base) ALSO renders the menu (render-for-both decision)', () => {
+    const p = resolve('plan', 'base', { lifecycle: 'terminal', hasManager: true });
+    assert.match(p.systemPrompt, new RegExp(MENU_HEADER), 'a base plan node sees the roster too');
+    for (const k of PLAN_REVIEWER_KINDS) {
+        assert.ok(p.systemPrompt.includes(k), `menu lists ${k}`);
+    }
+});
+test('resolve(general, orchestrator) does NOT render the menu (visibility = membership)', () => {
+    const p = resolve('general', 'orchestrator', { lifecycle: 'terminal', hasManager: true });
+    assert.doesNotMatch(p.systemPrompt, new RegExp(MENU_HEADER), 'general owns no roster, so no menu');
+});
+test('a reviewer sub-kind boots as a real composed persona with the terminal finish contract and no menu', () => {
+    const p = resolve('plan/reviewers/security', 'base', { lifecycle: 'terminal', hasManager: true });
+    assert.ok(p.systemPrompt.includes('concrete exploit path'), 'the security-reviewer lens expertise is present');
+    assert.match(p.systemPrompt, /owe a final result and you reap when done/i, 'the terminal finish contract composed in — it boots as a real persona');
+    assert.doesNotMatch(p.systemPrompt, new RegExp(MENU_HEADER), 'a sub-kind owns no roster of its own — it renders no menu');
+});

package/dist/core/__tests__/persona.test.d.ts

@@ -0,0 +1 @@
+export {};