@crouton-kit/crouter 0.3.19 → 0.3.20

package/dist/core/__tests__/canvas-inbox-watcher-hold.test.js

@@ -0,0 +1,102 @@
+// Tests for the canvas-node inbox watcher pi extension, part 2 — the
+// refresh-yield HOLD path and idle delivery. Split out of
+// canvas-inbox-watcher.test.ts (see its header) so node:test's file-level
+// parallelism applies; the tests and the scaffold are moved here UNCHANGED.
+//
+// Run with: node --import tsx/esm --test src/core/__tests__/canvas-inbox-watcher-hold.test.ts
+import { test, describe, before, after, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import registerCanvasInboxWatcher from '../../pi-extensions/canvas-inbox-watcher.js';
+import { appendInbox } from '../feed/inbox.js';
+import { createNode, setIntent } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+// Mirror the watcher's internal cadence (TICK_MS=800, DEBOUNCE_MS=1000): allow a
+// resolve+seed tick, a read tick, and the debounce window before asserting.
+const TICK_MS = 800;
+const DEBOUNCE_MS = 1000;
+const SETTLE_MS = TICK_MS * 2 + DEBOUNCE_MS + 500;
+let origHome;
+let origNode;
+const homes = [];
+const disposers = [];
+/** Point CRTR_HOME at a fresh temp canvas root and bind CRTR_NODE_ID. */
+function freshNode(nodeId) {
+    const home = join(tmpdir(), `crtr-canvas-watcher-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(home, { recursive: true });
+    homes.push(home);
+    process.env['CRTR_HOME'] = home;
+    process.env['CRTR_NODE_ID'] = nodeId;
+}
+function makeFakePi() {
+    const handlers = {};
+    return {
+        injected: [],
+        on(e, h) { handlers[e] = h; },
+        sendUserMessage(content, options) { this.injected.push({ content, deliverAs: options?.deliverAs }); },
+        fire(e, ev, ctx) { handlers[e]?.(ev, ctx); },
+    };
+}
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+before(() => {
+    origHome = process.env['CRTR_HOME'];
+    origNode = process.env['CRTR_NODE_ID'];
+});
+afterEach(() => {
+    while (disposers.length > 0)
+        disposers.pop()();
+});
+after(() => {
+    if (origHome === undefined)
+        delete process.env['CRTR_HOME'];
+    else
+        process.env['CRTR_HOME'] = origHome;
+    if (origNode === undefined)
+        delete process.env['CRTR_NODE_ID'];
+    else
+        process.env['CRTR_NODE_ID'] = origNode;
+    for (const h of homes) {
+        try {
+            rmSync(h, { recursive: true, force: true });
+        }
+        catch { /* noop */ }
+    }
+});
+describe('canvas inbox watcher — hold + idle delivery', () => {
+    test('refresh-yield in flight: inbox entries are HELD, then delivered once intent clears (no loss)', async () => {
+        freshNode('node-refresh');
+        closeDb(); // rebind the canvas db to this test's fresh home
+        const meta = {
+            node_id: 'node-refresh', name: 'r', created: new Date().toISOString(),
+            cwd: '/tmp', kind: 'general', mode: 'base', lifecycle: 'resident',
+            status: 'active', intent: 'refresh',
+        };
+        createNode(meta);
+        const pi = makeFakePi();
+        disposers.push(registerCanvasInboxWatcher(pi));
+        // Streaming (mid-turn) when a child finishes — normally this would steer.
+        pi.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
+        await wait(TICK_MS + 100);
+        appendInbox('node-refresh', { from: 'child-x', tier: 'urgent', kind: 'final', label: 'done' });
+        await wait(SETTLE_MS);
+        assert.equal(pi.injected.length, 0, 'entries are held while a refresh-yield is in flight (no steer-hijack)');
+        // The fresh pi clears intent on boot; the held entry must then be delivered
+        // — the cursor was never advanced, so nothing is lost.
+        setIntent('node-refresh', null);
+        await wait(SETTLE_MS);
+        assert.equal(pi.injected.length, 1, 'the held entry is delivered once the refresh clears');
+    });
+    test('idle: a finished node triggers a fresh turn (no deliverAs)', async () => {
+        freshNode('node-idle');
+        const pi = makeFakePi();
+        disposers.push(registerCanvasInboxWatcher(pi));
+        // No agent_start fired → watcher treats the node as idle.
+        await wait(TICK_MS + 100);
+        appendInbox('node-idle', { from: 'child-3', tier: 'normal', kind: 'final', label: 'done while idle' });
+        await wait(SETTLE_MS);
+        assert.equal(pi.injected.length, 1);
+        assert.equal(pi.injected[0].deliverAs, undefined, 'idle → sendUserMessage triggers a turn, no deliverAs');
+    });
+});

package/dist/core/__tests__/canvas-inbox-watcher.test.js

@@ -4,6 +4,8 @@
 //
 // Focus: a finished node (push final → InboxEntry kind 'final') must STEER a
 // mid-stream subscriber, not queue behind its current turn as a follow-up.
+// Part 2 — the refresh-yield HOLD path and idle delivery — lives in
+// canvas-inbox-watcher-hold.test.ts (split for node:test file-level parallelism).
 import { test, describe, before, after, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdirSync, rmSync } from 'node:fs';
@@ -11,8 +13,6 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import registerCanvasInboxWatcher from '../../pi-extensions/canvas-inbox-watcher.js';
 import { appendInbox } from '../feed/inbox.js';
-import { createNode, setIntent } from '../canvas/canvas.js';
-import { closeDb } from '../canvas/db.js';
 // Mirror the watcher's internal cadence (TICK_MS=800, DEBOUNCE_MS=1000): allow a
 // resolve+seed tick, a read tick, and the debounce window before asserting.
 const TICK_MS = 800;
@@ -88,38 +88,4 @@ describe('canvas inbox watcher — finished-node delivery', () => {
         assert.equal(pi.injected.length, 1);
         assert.equal(pi.injected[0].deliverAs, 'followUp', 'a normal update is not urgent → followUp');
     });
-    test('refresh-yield in flight: inbox entries are HELD, then delivered once intent clears (no loss)', async () => {
-        freshNode('node-refresh');
-        closeDb(); // rebind the canvas db to this test's fresh home
-        const meta = {
-            node_id: 'node-refresh', name: 'r', created: new Date().toISOString(),
-            cwd: '/tmp', kind: 'general', mode: 'base', lifecycle: 'resident',
-            status: 'active', intent: 'refresh',
-        };
-        createNode(meta);
-        const pi = makeFakePi();
-        disposers.push(registerCanvasInboxWatcher(pi));
-        // Streaming (mid-turn) when a child finishes — normally this would steer.
-        pi.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
-        await wait(TICK_MS + 100);
-        appendInbox('node-refresh', { from: 'child-x', tier: 'urgent', kind: 'final', label: 'done' });
-        await wait(SETTLE_MS);
-        assert.equal(pi.injected.length, 0, 'entries are held while a refresh-yield is in flight (no steer-hijack)');
-        // The fresh pi clears intent on boot; the held entry must then be delivered
-        // — the cursor was never advanced, so nothing is lost.
-        setIntent('node-refresh', null);
-        await wait(SETTLE_MS);
-        assert.equal(pi.injected.length, 1, 'the held entry is delivered once the refresh clears');
-    });
-    test('idle: a finished node triggers a fresh turn (no deliverAs)', async () => {
-        freshNode('node-idle');
-        const pi = makeFakePi();
-        disposers.push(registerCanvasInboxWatcher(pi));
-        // No agent_start fired → watcher treats the node as idle.
-        await wait(TICK_MS + 100);
-        appendInbox('node-idle', { from: 'child-3', tier: 'normal', kind: 'final', label: 'done while idle' });
-        await wait(SETTLE_MS);
-        assert.equal(pi.injected.length, 1);
-        assert.equal(pi.injected[0].deliverAs, undefined, 'idle → sendUserMessage triggers a turn, no deliverAs');
-    });
 });

package/dist/core/__tests__/helpers/broker-clients.d.ts

@@ -0,0 +1,43 @@
+import { type Socket } from 'node:net';
+import type { Harness } from './harness.js';
+import { ViewSocketClient } from '../../../clients/attach/view-socket.js';
+import { type BrokerToClient, type ClientToBroker, type ClientRole, type WelcomeFrame } from '../../runtime/broker-protocol.js';
+export declare const delay: (ms: number) => Promise<void>;
+export declare const tok: (s: string) => string;
+export declare const frameHas: (f: BrokerToClient, token: string) => boolean;
+export declare function brokerLogText(h: Harness, id: string): string;
+/** lsof the holders of `path`, or null when lsof is unavailable (skip the fd
+ *  check). Exit-non-zero with empty stdout means "no holders". */
+export declare function lsofHolders(path: string): number[] | null;
+export interface Attached {
+    client: ViewSocketClient;
+    frames: BrokerToClient[];
+    welcome: WelcomeFrame;
+    send(frame: ClientToBroker): void;
+    waitFrame(pred: (f: BrokerToClient) => boolean, label: string, timeoutMs?: number): Promise<BrokerToClient>;
+    close(): void;
+}
+export interface RawClient {
+    socket: Socket;
+    frames: BrokerToClient[];
+    closed: () => boolean;
+    send(frame: ClientToBroker): void;
+    writeRaw(data: Buffer | string): void;
+    waitClosed(label: string, timeoutMs?: number): Promise<void>;
+    close(): void;
+}
+export interface AttachKit {
+    /** Connect a ViewSocketClient to a node's running broker, hello, await welcome. */
+    attach(id: string, role: ClientRole, clientId: string): Promise<Attached>;
+    /** Attach (as `role`) and retry until the welcome satisfies `pred`. */
+    attachUntil(id: string, role: ClientRole, clientId: string, pred: (a: Attached) => boolean, label: string): Promise<Attached>;
+    /** A raw node:net peer. read:false leaves the socket PAUSED (G8 stalled viewer). */
+    connectRaw(id: string, opts: {
+        read: boolean;
+    }): Promise<RawClient>;
+    /** Close every client opened since the last closeAll — wire into afterEach. */
+    closeAll(): void;
+}
+/** Build the attach kit against a lazily-resolved harness (the harness is
+ *  created in the file's before() hook, after the kit is constructed). */
+export declare function createAttachKit(getH: () => Harness): AttachKit;

package/dist/core/__tests__/helpers/broker-clients.js

@@ -0,0 +1,178 @@
+// helpers/broker-clients.ts — the shared attach-client kit for the broker
+// lifecycle/attach-gate suite (plan T8/T11). Extracted VERBATIM from the original
+// single-file broker-lifecycle.test.ts when it was split into per-area files so
+// node:test's file-level parallelism applies (each file holds its own isolated
+// harness); the helpers are unchanged in behavior.
+//
+// The kit wraps the PRODUCTION attach client (pure node:net + the broker codec,
+// no TUI) as the in-test controller/observer so the G1–G9 gate exercises the REAL
+// client too (§0 one-writer: a viewer holds ONLY a socket), plus a raw node:net
+// peer for the cases where the client lifecycle is awkward (G7 oversized line,
+// G8 stalled viewer).
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createConnection } from 'node:net';
+import { spawnSync } from 'node:child_process';
+import { ViewSocketClient } from '../../../clients/attach/view-socket.js';
+import { CLIENT_READ_CAPS, FrameDecoder, encodeFrame, } from '../../runtime/broker-protocol.js';
+export const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+export const tok = (s) => `${s}-${Math.random().toString(36).slice(2, 8)}`;
+export const frameHas = (f, token) => JSON.stringify(f).includes(token);
+export function brokerLogText(h, id) {
+    try {
+        return readFileSync(join(h.home, 'nodes', id, 'job', 'broker.log'), 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+/** lsof the holders of `path`, or null when lsof is unavailable (skip the fd
+ *  check). Exit-non-zero with empty stdout means "no holders". */
+export function lsofHolders(path) {
+    if (spawnSync('which', ['lsof'], { stdio: 'ignore' }).status !== 0)
+        return null;
+    const out = (spawnSync('lsof', ['-t', '--', path], { encoding: 'utf8' }).stdout ?? '').trim();
+    if (out === '')
+        return [];
+    return out
+        .split('\n')
+        .map((l) => Number(l.trim()))
+        .filter((n) => Number.isFinite(n));
+}
+/** Build the attach kit against a lazily-resolved harness (the harness is
+ *  created in the file's before() hook, after the kit is constructed). */
+export function createAttachKit(getH) {
+    const liveClients = [];
+    // Connect a ViewSocketClient to a node's running broker, hello, await welcome.
+    // awaitBoot returns once the boot proof is written — which is BEFORE the broker's
+    // server.listen() binds view.sock — so a fresh attach can momentarily race the
+    // bind; retry the connect on BrokerUnavailable until it is listening.
+    async function attach(id, role, clientId) {
+        const h = getH();
+        await h.waitFor(() => existsSync(h.brokerSock(id)), { label: `view.sock for ${id}`, timeoutMs: 20_000 });
+        const frames = [];
+        let client;
+        for (let attempt = 0;; attempt++) {
+            client = new ViewSocketClient(id);
+            client.on('frame', (f) => frames.push(f));
+            try {
+                await new Promise((resolve, reject) => {
+                    client.once('connect', resolve);
+                    client.once('error', reject);
+                    client.connect();
+                });
+                break;
+            }
+            catch (err) {
+                client.close();
+                if (attempt >= 30)
+                    throw err;
+                await delay(100);
+            }
+        }
+        client.on('error', () => { }); // post-connect error sink (never throw uncaught)
+        // Register cleanup the instant the socket is connected — BEFORE the hello/welcome
+        // round-trip — so a welcome timeout cannot leak a connected socket past the test.
+        liveClients.push({ close: () => client.close() });
+        const waitFrame = (pred, label, timeoutMs = 15_000) => h.waitFor(() => frames.find(pred) ?? null, { label, timeoutMs });
+        client.send({ type: 'hello', role, client_id: clientId });
+        let welcome;
+        try {
+            welcome = (await waitFrame((f) => f.type === 'welcome', `welcome for ${clientId}`));
+        }
+        catch (err) {
+            client.close();
+            throw err;
+        }
+        return { client, frames, welcome, send: (f) => client.send(f), waitFrame, close: () => client.close() };
+    }
+    // Attach (as `role`) and retry until the welcome satisfies `pred` — used where the
+    // observable lands a beat after a prior action (G3 snapshot accrual, G5b control
+    // handoff after a controller detaches). Deterministic: it polls an observable.
+    async function attachUntil(id, role, clientId, pred, label) {
+        for (let attempt = 0;; attempt++) {
+            const a = await attach(id, role, `${clientId}-${attempt}`);
+            if (pred(a))
+                return a;
+            a.close();
+            if (attempt >= 40)
+                throw new Error(`attachUntil timed out: ${label}`);
+            await delay(150);
+        }
+    }
+    // A raw node:net peer. read:true decodes incoming frames; read:false leaves the
+    // socket PAUSED (no 'data' listener, never resumed) so it never drains — the
+    // stalled viewer (G8) whose backlog the broker must shed at the HWM.
+    async function connectRaw(id, opts) {
+        const h = getH();
+        await h.waitFor(() => existsSync(h.brokerSock(id)), { label: `view.sock for ${id}`, timeoutMs: 20_000 });
+        const frames = [];
+        const decoder = new FrameDecoder(CLIENT_READ_CAPS);
+        let isClosed = false;
+        const socket = await new Promise((resolve, reject) => {
+            const s = createConnection(h.brokerSock(id));
+            s.once('connect', () => resolve(s));
+            s.once('error', reject);
+        });
+        socket.on('close', () => {
+            isClosed = true;
+        });
+        socket.on('error', () => {
+            /* close follows */
+        });
+        if (opts.read) {
+            socket.on('data', (chunk) => {
+                try {
+                    for (const f of decoder.push(chunk))
+                        frames.push(f);
+                }
+                catch {
+                    /* a client-side overflow is irrelevant here */
+                }
+            });
+        }
+        const rc = {
+            socket,
+            frames,
+            closed: () => isClosed,
+            send: (f) => {
+                try {
+                    socket.write(encodeFrame(f));
+                }
+                catch {
+                    /* dead */
+                }
+            },
+            writeRaw: (d) => {
+                try {
+                    socket.write(d);
+                }
+                catch {
+                    /* dead */
+                }
+            },
+            waitClosed: (label, timeoutMs = 15_000) => h.waitFor(() => (isClosed ? true : null), { label, timeoutMs }).then(() => undefined),
+            close: () => {
+                try {
+                    socket.destroy();
+                }
+                catch {
+                    /* ignore */
+                }
+            },
+        };
+        liveClients.push(rc);
+        return rc;
+    }
+    function closeAll() {
+        for (const c of liveClients.splice(0)) {
+            try {
+                c.close();
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    }
+    return { attach, attachUntil, connectRaw, closeAll };
+}

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');
+    }
+});