@crouton-kit/crouter 0.3.18 → 0.3.20

package/dist/core/__tests__/home-session.test.js

@@ -7,7 +7,7 @@
 //   - home_session round-trips through meta.json (it IS durable identity)
 //   - the birth-session decision (`resolveBirthSession`) for the child /
 //     inline-root / --root cases each site sets home_session from
-//   - demote-recycle + relaunch (pane-recycle) births populate home_session
+//   - recycle + relaunch (pane-recycle) births populate home_session
 //   - a legacy meta with NO home_session defaults to tmux_session ?? nodeSession()
 import { test, before, after, beforeEach } from 'node:test';
 import assert from 'node:assert/strict';
@@ -17,10 +17,10 @@ import { join } from 'node:path';
 import { createNode, getNode, updateNode } from '../canvas/canvas.js';
 import { nodeMetaPath } from '../canvas/paths.js';
 import { closeDb } from '../canvas/db.js';
-import { resolveBirthSession, homeSessionOf } from '../runtime/nodes.js';
+import { resolveBirthSession, homeSessionOf, childBackstageOf } from '../runtime/nodes.js';
 import { nodeSession } from '../runtime/nodes.js';
 import { relaunchRoot } from '../runtime/reset.js';
-import { demoteNode } from '../runtime/demote.js';
+import { recycleNode } from '../runtime/recycle.js';
 let home;
 function node(id, over = {}) {
     return {
@@ -35,7 +35,7 @@ function node(id, over = {}) {
         ...over,
     };
 }
-/** Make ensureDaemon (called by demoteNode) a no-op by faking a live daemon
+/** Make ensureDaemon (called by recycleNode) a no-op by faking a live daemon
  *  pidfile pointing at THIS test process — so no real daemon is ever spawned. */
 function fakeLiveDaemon() {
     writeFileSync(join(home, 'crtrd.pid'), String(process.pid), 'utf8');
@@ -106,6 +106,39 @@ test('homeSessionOf: unknown node falls back to the backstage', () => {
     assert.equal(homeSessionOf('ghost'), nodeSession());
 });
 // ---------------------------------------------------------------------------
+// childBackstageOf — the session a node's CHILDREN spawn into (their
+// CRTR_ROOT_SESSION). REGRESSION for the front-door-root subtree-exile bug:
+// a refreshed inline root (home_session = a USER session it adopted) was
+// sourcing children's CRTR_ROOT_SESSION from home_session, so every yield
+// re-pointed its entire subtree into the user's working session. A root's
+// children must always flow to the shared backstage `nodeSession()`, never the
+// user session, while a managed child's children inherit its backstage
+// home_session. (Bug: node mq2u219p spawned all 13 children into `cli`.)
+// ---------------------------------------------------------------------------
+test('childBackstageOf: a managed child uses its backstage home_session', () => {
+    // A child's home_session is ALWAYS the backstage it was born into; its live
+    // tmux_session may be a user session (focus taint) but must NOT leak to kids.
+    createNode(node('child', { parent: 'p', home_session: 'crtr', tmux_session: 'user-sess' }));
+    assert.equal(childBackstageOf('child'), 'crtr', 'children inherit the backstage, not the tainted LOCATION');
+});
+test('childBackstageOf: a front-door ROOT routes children to the backstage, NOT its adopted user session', () => {
+    // The bug: an inline root adopts the user's session as home_session ('cli').
+    // Sourcing children's CRTR_ROOT_SESSION from home_session exiled the whole
+    // subtree into 'cli' on every refresh-yield. A root (parent === null) must
+    // route children to nodeSession() instead.
+    createNode(node('root', { parent: null, home_session: 'cli', tmux_session: 'cli' }));
+    assert.equal(childBackstageOf('root'), nodeSession(), "a root's children flow to the backstage");
+    assert.notEqual(childBackstageOf('root'), 'cli', 'NEVER the user session the root pane adopted');
+});
+test('childBackstageOf: a root honors CRTR_NODE_SESSION for the backstage', () => {
+    process.env['CRTR_NODE_SESSION'] = 'my-backstage';
+    createNode(node('root', { parent: null, home_session: 'cli' }));
+    assert.equal(childBackstageOf('root'), 'my-backstage', 'the backstage default is env-overridable');
+});
+test('childBackstageOf: unknown node falls back to the backstage', () => {
+    assert.equal(childBackstageOf('ghost'), nodeSession());
+});
+// ---------------------------------------------------------------------------
 // The birth-session decision each site sets home_session from. Pure, so the
 // child / inline-root / --root births are testable without a live tmux (the
 // real spawnChild/bootRoot are tmux + pi + process.exit coupled).
@@ -130,7 +163,7 @@ test('birth: the inline front door (bootRoot) homes to its adopted session', ()
 });
 // ---------------------------------------------------------------------------
 // Pane-recycle births populate home_session. relaunchRoot (option C) is fully
-// unit-testable (injected respawn, no tmux); demoteNode runs to completion with
+// unit-testable (injected respawn, no tmux); recycleNode runs to completion with
 // no tmux (respawn dispatch just fails) once the daemon spawn is neutralized.
 // ---------------------------------------------------------------------------
 test('relaunch birth: the fresh root homes to the recycled pane session', () => {
@@ -141,13 +174,13 @@ test('relaunch birth: the fresh root homes to the recycled pane session', () =>
     assert.ok(res !== null, 'relaunchRoot minted a fresh root');
     assert.equal(getNode(res.newNodeId)?.home_session, 'crtr', 'fresh root homes to the recycled pane session');
 });
-test('demote birth: the recycled root populates home_session (backstage when no pane location)', async () => {
+test('recycle birth: the recycled root populates home_session (backstage when no pane location)', async () => {
     createNode(node('M', { parent: null, lifecycle: 'resident', tmux_session: 'crtr', window: '@3' }));
     fakeLiveDaemon(); // createNode ensured the home dir; now neutralize ensureDaemon
     // No live tmux → paneLocation('%0') is null → home_session defaults to the
     // backstage. The respawn dispatch fails (no tmux), but the fresh root is still
     // born — and must carry a populated home_session.
-    const res = await demoteNode('M', '%0');
-    assert.ok(res.newRoot !== null, 'demote minted a fresh root');
+    const res = await recycleNode('M', '%0');
+    assert.ok(res.newRoot !== null, 'recycle minted a fresh root');
     assert.equal(getNode(res.newRoot)?.home_session, nodeSession(), 'recycled root homes to the backstage');
 });

package/dist/core/__tests__/human-new-window-regression.test.d.ts

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

package/dist/core/__tests__/human-new-window-regression.test.js

@@ -0,0 +1,101 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/human-new-window-regression.test.ts
+//
+// BUG REGRESSION: `crtr human ask|approve|review|notify` opened NO pane at all.
+//
+// spawnAndDetach's 'new-window' placement passed a tmux PANE id straight to
+// `new-window -t` (`new-window -d -a -t %<pane>`). tmux REJECTS a pane id for
+// new-window — it exits 1 with "can't specify pane here"; only `split-window -t`
+// accepts a pane. So once a node's watched window held >= max_panes_per_window
+// panes, pickPlacement (shared.ts) chose 'new-window', spawnAndDetach FAILED,
+// spawnHumanJob returned {spawned:false}, and the humanloop TUI never appeared.
+// Deterministic for any user whose watched window is already at the pane cap.
+//
+// Regression from 829c1a1 ("land prompts in the watched node's session"), which
+// began routing the TUI to the watched node's pane id but never converted it to
+// the session:window form new-window needs.
+//
+// THE FIX: spawnAndDetach resolves the target pane to its session:window
+// (`paneWindowTarget`) before `new-window -t`. This drives the REAL production
+// spawnAndDetach against a REAL but isolated tmux session — no mocks — mirroring
+// dead-pane-regression.test.ts.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { hasTmux } from './helpers/harness.js';
+import { spawnAndDetach } from '../spawn.js';
+const SKIP = !hasTmux();
+function tmux(args) {
+    const r = spawnSync('tmux', args, { encoding: 'utf8' });
+    return { code: r.status ?? -1, out: (r.stdout ?? '').trim(), err: (r.stderr ?? '').trim() };
+}
+/** window id of a pane (across the server). '' on error. */
+function windowOfPane(pane) {
+    return tmux(['display-message', '-p', '-t', pane, '#{window_id}']).out;
+}
+/** Every pane in the session, across all its windows. */
+function sessionPanes(session) {
+    const r = tmux(['list-panes', '-s', '-t', session, '-F', '#{pane_id}']);
+    if (r.code !== 0)
+        return [];
+    return r.out.split('\n').filter((l) => l.trim() !== '');
+}
+test('human-new-window regression: spawnAndDetach new-window into a watched-pane SPAWNS (no longer "can\'t specify pane here")', { skip: SKIP ? 'tmux unavailable' : false, timeout: 60_000 }, async () => {
+    const session = `crtr-newwin-${process.pid}-${Date.now().toString(36)}`;
+    const origTmux = process.env['TMUX'];
+    let tmuxOverridden = false;
+    try {
+        // --- isolated session on whatever server the current env targets -------
+        const created = tmux(['new-session', '-d', '-s', session, '-c', process.cwd(), 'sleep 100000']);
+        assert.equal(created.code, 0, `create isolated session failed: ${created.err}`);
+        const info = tmux([
+            'display-message', '-p', '-t', `${session}:`,
+            '#{pane_id}\t#{window_id}\t#{socket_path}',
+        ]);
+        assert.equal(info.code, 0, `display-message failed: ${info.err}`);
+        const [basePane, baseWindow, socketPath] = info.out.split('\t');
+        assert.ok(basePane && baseWindow && socketPath, `parsed session info: ${info.out}`);
+        // ====================================================================
+        // CONTROL — prove the bug is REAL and the guard NON-VACUOUS: the pre-fix
+        // call shape (a PANE id straight into `new-window -t`) is REJECTED by tmux.
+        // ====================================================================
+        const ctl = tmux(['new-window', '-d', '-a', '-t', basePane, '-c', process.cwd(), 'sleep 100000']);
+        assert.notEqual(ctl.code, 0, 'CONTROL: new-window with a PANE id must FAIL (pre-fix call shape)');
+        assert.match(ctl.err, /can't specify pane here/i, `CONTROL: tmux rejects a pane id for new-window — got: ${ctl.err}`);
+        // spawnAndDetach gates on isInTmux() (Boolean(process.env.TMUX)) and shells
+        // `tmux` with no -L, so point TMUX at THIS session's socket — both our
+        // helpers and spawnAndDetach then drive the same server holding `session`.
+        process.env['TMUX'] = `${socketPath},0,0`;
+        tmuxOverridden = true;
+        // ====================================================================
+        // MAIN — the REAL production spawnAndDetach, 'new-window' placement,
+        // pinned to the watched PANE (exactly what detachHumanTui passes when
+        // pickPlacement returns 'new-window').
+        // ====================================================================
+        const res = spawnAndDetach({
+            command: 'sleep 100000', // long-lived stand-in for `crtr human _run`
+            cwd: process.cwd(),
+            placement: 'new-window',
+            detached: true, // don't switch the client (matches detachHumanTui)
+            killAfterSeconds: 0, // no self-kill of the originating pane
+            targetPane: basePane, // a PANE id — the exact value that used to break new-window
+        });
+        // (a) THE FIX: it SPAWNS (pre-fix this was 'spawn-failed' / no pane).
+        assert.equal(res.status, 'spawned', `spawnAndDetach should spawn a pane: ${res.message}`);
+        const pane = res.paneId;
+        assert.ok(pane && pane.startsWith('%'), `spawnAndDetach returned a %pane id: ${pane}`);
+        // (b) it landed in the SAME session as the watched pane (not stranded /
+        //     leaked into the global current session), in a NEW window.
+        assert.ok(sessionPanes(session).includes(pane), 'spawned pane lives in the watched pane\'s session');
+        assert.notEqual(windowOfPane(pane), baseWindow, 'spawned pane is in a NEW window (new-window placement), not the watched pane\'s window');
+    }
+    finally {
+        tmux(['kill-session', '-t', session]);
+        if (tmuxOverridden) {
+            if (origTmux === undefined)
+                delete process.env['TMUX'];
+            else
+                process.env['TMUX'] = origTmux;
+        }
+        assert.equal(spawnSync('tmux', ['has-session', '-t', session], { stdio: 'ignore' }).status === 0, false, 'isolated session killed — no stray');
+    }
+});

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-verbs.test.d.ts

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

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 `<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__/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).
 //
@@ -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,124 +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) 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');
-    }
-});