@crouton-kit/crouter 0.3.16 → 0.3.18

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__/lifecycle.test.js

@@ -67,18 +67,11 @@ test('finalize: illegal from done|dead|canceled → throws, status untouched', (
     }
 });
 // ---------------------------------------------------------------------------
-// reap → done + intent cleared, legal from ANY status (forced teardown)
-// ---------------------------------------------------------------------------
-test('reap: any status → done + intent cleared', () => {
-    for (const from of ALL) {
-        mk(`n_${from}`, from, 'refresh');
-        const m = transition(`n_${from}`, 'reap');
-        assert.equal(m.status, 'done', `reap from ${from}`);
-        assert.equal(m.intent, null, `reap from ${from} clears intent`);
-    }
-});
-// ---------------------------------------------------------------------------
-// cancel → canceled + intent cleared, legal from ANY status
+// cancel → canceled + intent cleared, legal from ANY status (forced teardown).
+// A5 (human-confirmed 2026-06-06): the `reap` event was COLLAPSED into `cancel`
+// — they were identical (status differed only; both intent=null, from=ANY, no
+// side effects in transition()). Every external reap (close cascade AND
+// reset/relaunch) now routes through `cancel`; `done` is reserved for finalize.
 // ---------------------------------------------------------------------------
 test('cancel: any status → canceled + intent cleared', () => {
     for (const from of ALL) {
@@ -172,7 +165,7 @@ test('boot: illegal from done|dead|canceled → throws', () => {
 // unknown node → throws for every event
 // ---------------------------------------------------------------------------
 test('transition on an unknown node throws', () => {
-    for (const ev of ['finalize', 'reap', 'cancel', 'crash', 'yield', 'release', 'revive', 'boot']) {
+    for (const ev of ['finalize', 'cancel', 'crash', 'yield', 'release', 'revive', 'boot']) {
         assert.throws(() => transition('ghost', ev), /unknown node/);
     }
 });

package/dist/core/__tests__/live-mutation.test.d.ts

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

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

@@ -0,0 +1,341 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/live-mutation.test.ts
+//
+// 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 work. Every assertion reads the canvas data layer and is checked against
+// the state-model ORACLE (mq1su40t .../state-model.md).
+//
+// This file is ADDITIVE and uses ONLY the public Harness API + a couple of pure
+// test-local helpers (noted below). It does not edit harness.ts / fake-pi-host.ts
+// or any production file.
+//
+// Coverage rationale (grep of src/core/__tests__/ before writing):
+//   • persona.test.ts        — UNIT-level personaDrift/transitionGuidance (pure
+//                              functions; no live pi, no turn_end firing).
+//   • stop-guard.test.ts      — UNIT-level evaluateStop (no live flip via CLI).
+//   • daemon-liveness.test.ts — superviseTick over BORN-terminal idle-release
+//                              rows (never a live lifecycle FLIP).
+//   • flagship-lifecycle      — B born terminal idle-releases; A born resident
+//                              stays live; promote+turn fires the steer ONCE.
+// GENUINELY MISSING (this file): the LIVE FLIP itself — flipping a running
+// node's lifecycle/mode through the real verb and proving the runtime behavior
+// (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.
+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 (candidates to fold into harness.ts later) -----
+/** 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;
+}
+// ===========================================================================
+// (a) LIFECYCLE FLIP — `crtr node lifecycle` on a LIVE node, both directions,
+//     observing the idle-release behavior change. A round-trip on ONE live
+//     node (terminal→resident→terminal) proves both directions faithfully:
+//     a flipped-resident node no longer idle-releases (stays live, daemon does
+//     NOT release it); flipped-terminal it idle-releases again on pi-death.
+// ===========================================================================
+test('live lifecycle flip: terminal→resident suppresses idle-release; resident→terminal restores it', { skip: SKIP, timeout: 120_000 }, async () => {
+    const h = await createHarness({ sessionPrefix: 'crtr-live-life' });
+    try {
+        // A (resident root, data-layer) ─ B (base/terminal, live) ─ C (base/terminal, live).
+        // B holds an ACTIVE live subscription to C → a TERMINAL B that stops is
+        // legitimately 'awaiting' (stop-guard) and would idle-release. That live
+        // sub is the precondition that makes the resident-vs-terminal flip the
+        // ONLY variable.
+        const A = h.spawnRoot('resident root');
+        const B = await h.spawnChild(A, 'do the work', { kind: 'developer' });
+        const C = await h.spawnChild(B, 'a subtask');
+        {
+            const b = h.node(B);
+            assert.deepEqual(persona(b), { mode: 'base', lifecycle: 'terminal' }, 'B born base×terminal');
+            assert.equal(b.status, 'active', 'B active');
+            assert.equal(b.intent ?? null, null, 'B no intent');
+            assert.equal(h.status(C), 'active', 'C active — B holds a live sub to it');
+            assert.ok(h.subscriptions(B).some((s) => s.node_id === C && s.active), 'B subscribes_to C (active) — the awaiting precondition');
+        }
+        // --- FLIP 1: terminal → RESIDENT (live). Oracle §4: sets lifecycle + the
+        // launch spec, status/intent UNTOUCHED. ---
+        {
+            const res = h.cli(B, ['node', 'lifecycle', 'resident', '--node', B]);
+            assert.equal(res.code, 0, `lifecycle resident exit 0\n${res.stderr}`);
+            const b = h.node(B);
+            assert.equal(b.lifecycle, 'resident', 'B → resident');
+            assert.equal(b.mode, 'base', 'mode UNCHANGED by a lifecycle flip (orthogonal axis)');
+            assert.equal(b.status, 'active', 'status UNTOUCHED by node lifecycle (oracle §4)');
+            assert.equal(b.intent ?? null, null, 'intent UNTOUCHED by node lifecycle (oracle §4)');
+        }
+        // B stops AS RESIDENT: agent_end runs the stop-guard, which keys on
+        // lifecycle==='resident' → 'dormant' → the handler does NOT shut pi down
+        // (oracle §3a). So B stays active, pi alive, pane held — it does NOT
+        // idle-release despite holding the same live sub that would release a
+        // terminal node.
+        await h.stop(B);
+        // MINOR-2: asserting a NON-event (B must NOT idle-release) cannot be a single
+        // immediate read — h.stop() resolves once agent_end is RECORDED, BEFORE the
+        // handler completes, so a regression where the resident 'dormant' branch
+        // wrongly ran transition('release') + ctx.shutdown() asynchronously would
+        // still observe the pre-release state and false-pass. Instead POLL-STABLE:
+        // sample repeatedly across a real settle (a daemon tick partway, so the
+        // handler + a full superviseTick have both run) and assert the invariant
+        // holds on EVERY sample. A regression that idle-releases within the window
+        // is caught the moment it flips.
+        {
+            const deadline = Date.now() + 2_000;
+            let ticked = false;
+            for (;;) {
+                const b = h.node(B);
+                assert.equal(b.status, 'active', 'resident B stays ACTIVE on stop (dormant, not released)');
+                assert.equal(b.intent ?? null, null, 'resident B has NO idle-release intent');
+                assert.equal(h.paneAlive(B), true, 'resident B keeps its live pi/pane (no shutdown)');
+                assert.equal(h.status(C), 'active', 'C untouched while B is dormant-resident');
+                // Drive a real daemon decision pass midway: a superviseTick sees B
+                // active + pane-alive + pid-alive → handleLiveWindow 'leave'. If the
+                // daemon wrongly released a resident node, the next sample catches it.
+                if (!ticked) {
+                    await h.tick();
+                    ticked = true;
+                }
+                if (Date.now() >= deadline)
+                    break;
+                await new Promise((r) => setTimeout(r, 100));
+            }
+        }
+        // --- FLIP 2: resident → TERMINAL (live), on the now-resident live node. ---
+        {
+            const res = h.cli(B, ['node', 'lifecycle', 'terminal', '--node', B]);
+            assert.equal(res.code, 0, `lifecycle terminal exit 0\n${res.stderr}`);
+            const b = h.node(B);
+            assert.equal(b.lifecycle, 'terminal', 'B → terminal');
+            assert.equal(b.status, 'active', 'status still UNTOUCHED by the flip');
+            assert.equal(b.intent ?? null, null, 'intent still UNTOUCHED by the flip');
+        }
+        // B stops AS TERMINAL now: stop-guard sees terminal + an active live sub to
+        // C → 'awaiting' → transition('release') + ctx.shutdown(). idle/idle-release;
+        // pi dies; UNFOCUSED backstage pane closes (oracle §3b). The exact behavior
+        // the resident flip had suppressed.
+        await h.stop(B);
+        await h.waitForStatus(B, 'idle');
+        {
+            const b = h.node(B);
+            assert.equal(b.status, 'idle', 'terminal B idle-releases on stop');
+            assert.equal(b.intent, 'idle-release', 'intent=idle-release (transition release)');
+        }
+        await h.waitForPaneGone(B);
+        assert.equal(h.paneAlive(B), false, 'unfocused terminal B → pane closed on idle-release');
+        assert.equal(h.status(C), 'active', 'C still active while B sleeps');
+    }
+    finally {
+        const session = h.session;
+        await h.dispose();
+        assert.equal(sessionExists(session), false, 'isolated session killed — no stray');
+    }
+});
+// ===========================================================================
+// (b) MODE FLIP — promote: base → orchestrator on a LIVE node. The flip itself
+//     does NOT commit the persona ack; the turn_end injector recomposes (commits
+//     the ack + delivers the steer) on the next turn, and a second turn is a
+//     no-op (drift cleared). Flagship asserts the steer fires once; the NEW
+//     assertions here are the persona_ack MUTATION across the live flip and the
+//     idempotence — neither is covered elsewhere.
+// ===========================================================================
+test('live mode flip: promote base→orchestrator recomposes persona_ack at turn_end (and is idempotent)', { skip: SKIP, timeout: 120_000 }, async () => {
+    const h = await createHarness({ sessionPrefix: 'crtr-live-mode' });
+    try {
+        const A = h.spawnRoot('resident root');
+        const B = await h.spawnChild(A, 'do the work', { kind: 'developer' });
+        {
+            const b = h.node(B);
+            assert.deepEqual(persona(b), { mode: 'base', lifecycle: 'terminal' }, 'B born base×terminal');
+            // Invariant 11: born acked to its own persona → no spurious drift turn 1.
+            assert.deepEqual(b.persona_ack, { mode: 'base', lifecycle: 'terminal' }, 'persona_ack born equal to the initial persona (invariant 11)');
+        }
+        // PROMOTE (live): mode→orchestrator, lifecycle UNCHANGED, status/intent
+        // untouched (no transition). Crucially promote does NOT commit the ack —
+        // the drift is left PENDING for the injector.
+        {
+            const res = h.cli(B, ['node', 'promote', '--kind', 'developer']);
+            assert.equal(res.code, 0, `promote exit 0\n${res.stderr}`);
+            const b = h.node(B);
+            assert.equal(b.mode, 'orchestrator', 'B → orchestrator');
+            assert.equal(b.lifecycle, 'terminal', 'lifecycle UNCHANGED (promote is mode-only)');
+            assert.equal(b.status, 'active', 'status untouched by promote');
+            assert.equal(b.intent ?? null, null, 'intent untouched by promote');
+            assert.deepEqual(b.persona_ack, { mode: 'base', lifecycle: 'terminal' }, 'promote does NOT commit the ack — drift left PENDING for the injector');
+        }
+        // A TURN fires turn_end: personaDrift base→orchestrator → inject the
+        // orchestration guidance as a STEER, then commitPersonaAck. agent_end then
+        // stalls (orchestrator, no live sub, no final) → reprompt → B stays alive.
+        const injBefore = h.injected(B).length;
+        await h.turn(B, 'orchestrating');
+        const fresh = await h.waitFor(() => {
+            const slice = h.injected(B).slice(injBefore);
+            return orchestrationSteers(slice).length > 0 ? slice : null;
+        }, { timeoutMs: 15_000, label: 'base→orchestrator steer at turn_end' });
+        assert.ok(orchestrationSteers(fresh).length >= 1, 'turn_end delivered the orchestration guidance as a steer');
+        {
+            const b = h.node(B);
+            assert.deepEqual(b.persona_ack, { mode: 'orchestrator', lifecycle: 'terminal' }, 'persona RECOMPOSE committed: persona_ack advanced to the new persona at turn_end');
+            assert.equal(b.status, 'active', 'B not stranded — reprompt keeps it alive');
+        }
+        // IDEMPOTENCE: a SECOND turn finds no drift (ack already committed) → NO
+        // new persona steer is injected.
+        const injBeforeSecond = h.injected(B).length;
+        await h.turn(B, 'orchestrating again');
+        const afterSecond = h.injected(B).slice(injBeforeSecond);
+        assert.equal(orchestrationSteers(afterSecond).length, 0, 'no fresh orchestration steer on the second turn — drift cleared (idempotent recompose)');
+        assert.equal(h.node(B).mode, 'orchestrator', 'B still orchestrator');
+    }
+    finally {
+        const session = h.session;
+        await h.dispose();
+        assert.equal(sessionExists(session), false, 'isolated session killed — no stray');
+    }
+});
+// ===========================================================================
+// (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.
+// ===========================================================================
+test('node demote is FINISH+RECYCLE, not an orchestrator→base mode flip (current behavior vs task framing)', { 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.
+        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);
+        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}`);
+        const newRoot = /new_root="([^"]+)"/.exec(res.stdout)?.[1];
+        const finalized = /finalized="true"/.test(res.stdout);
+        // ⚑ The demoted 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.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');
+        }
+        // The fresh root is a DIFFERENT, BASE×RESIDENT node — that is where "base"
+        // comes from, not a mutation of B.
+        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');
+        }
+    }
+    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__/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()`);