@crouton-kit/crouter 0.3.27 → 0.3.29

package/dist/core/__tests__/error-stall-recycle.test.js

@@ -0,0 +1,141 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/error-stall-recycle.test.ts
+//
+// BUG-REGRESSION (§I error-stall; gh issue #4 — node mqaeqzdu-0746b3b7, a 9h
+// zombie). A provider outage exhausted the engine's SDK retry budget mid-task:
+// pi appended trailing stopReason:'error' assistant messages to the session
+// .jsonl and PARKED (the stophook's agent_end returns early on 'error' — "stay
+// alive for re-steering"). A headless node has no human to re-steer it, so the
+// broker stayed alive, status stayed 'active', and the daemon's pid-only
+// liveness check read it healthy for 9 hours while its parent believed it was
+// working. The daemon is the authority: a live, not-busy, intent-null engine
+// whose session file has been quiet past ERROR_STALL_QUIET_MS and whose last
+// assistant message stopped with 'error' is force-killed, so the ordinary
+// dead-pid crash path grace-revives RESUME on the saved session — the exact
+// manual recovery (kill broker + canvas revive) that fixed the zombie by hand.
+//
+// Three legs: the pure truth table (E1 — errorStallVerdict), the tail-signature
+// parser (E2 — trailingEngineError), and the daemon integration over a real
+// live pid the daemon must SIGTERM (E3 — superviseTick with an injected clock).
+// Regression check: drop §I and E3's "engine killed" assert goes RED (the
+// parked error engine lives forever, never recovered).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { writeFileSync, utimesSync, mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createHeadlessHarness } from './helpers/harness.js';
+import { errorStallVerdict, trailingEngineError, ERROR_STALL_QUIET_MS, isPidAlive, } from '../../daemon/crtrd.js';
+// ---------------------------------------------------------------------------
+// Session-jsonl line builders (the shape pi writes: {type:'message', message}).
+// ---------------------------------------------------------------------------
+function line(message) {
+    return JSON.stringify({ type: 'message', id: 'x', timestamp: new Date().toISOString(), message });
+}
+const assistant = (stopReason, errorMessage) => line({ role: 'assistant', stopReason, ...(errorMessage === undefined ? {} : { errorMessage }) });
+const toolResult = () => line({ role: 'toolResult' });
+const user = () => line({ role: 'user' });
+// ---------------------------------------------------------------------------
+// E1 — the pure error-stall truth table.
+// ---------------------------------------------------------------------------
+test('E1 errorStallVerdict: kill ONLY a live, not-busy, intent-null engine, quiet past grace, with a trailing error', () => {
+    const G = ERROR_STALL_QUIET_MS;
+    // The one 'kill' case.
+    assert.equal(errorStallVerdict(true, null, false, G, true), 'kill', 'alive+no-intent+!busy+quiet>=grace+error → kill');
+    assert.equal(errorStallVerdict(true, null, false, G + 60_000, true), 'kill', 'well past grace → kill');
+    // Recent session activity → leave (something is still making progress).
+    assert.equal(errorStallVerdict(true, null, false, G - 1, true), 'leave', 'within quiet grace → leave');
+    assert.equal(errorStallVerdict(true, null, false, null, true), 'leave', 'unknown quiet span → leave');
+    // No trailing error → a healthy park (attended root, awaiting node) — leave.
+    assert.equal(errorStallVerdict(true, null, false, G + 60_000, false), 'leave', 'last turn not an error → leave');
+    // A working engine is NEVER killed (wedged-on-bash is recovered by killing the
+    // subprocess, not the node).
+    assert.equal(errorStallVerdict(true, null, true, G + 60_000, true), 'leave', 'busy (mid-turn) → leave');
+    // A pending intent belongs to other paths (§H refresh; idle-release dormancy).
+    assert.equal(errorStallVerdict(true, 'refresh', false, G + 60_000, true), 'leave', 'intent=refresh → leave (§H owns it)');
+    assert.equal(errorStallVerdict(true, 'idle-release', false, G + 60_000, true), 'leave', 'intent=idle-release → leave');
+    // A dead/unknown pid is the ordinary revive path's job.
+    assert.equal(errorStallVerdict(false, null, false, G + 60_000, true), 'leave', 'dead pid → leave');
+    assert.equal(errorStallVerdict(null, null, false, G + 60_000, true), 'leave', 'unknown pid → leave');
+});
+// ---------------------------------------------------------------------------
+// E2 — the tail-signature parser.
+// ---------------------------------------------------------------------------
+test('E2 trailingEngineError: only a trailing error assistant turn matches', () => {
+    // The observed zombie shape: trailing zero-token error assistant messages.
+    assert.equal(trailingEngineError([assistant('toolUse'), toolResult(), assistant('error', 'Connection error.')].join('\n')), 'Connection error.', 'trailing error turn → its errorMessage');
+    // Trailing non-assistant lines (toolResults, an injected user message that
+    // never got a response) are walked past to the last assistant turn.
+    assert.equal(trailingEngineError([assistant('error', 'Connection error.'), user()].join('\n')), 'Connection error.', 'trailing injected user line is walked past');
+    // A healthy park / human abort is NOT a wedge.
+    assert.equal(trailingEngineError([assistant('error', 'x'), toolResult(), assistant('stop')].join('\n')), null, 'recovered after an earlier error → null');
+    assert.equal(trailingEngineError(assistant('aborted')), null, 'human Esc → null');
+    // A tail cut mid-line (the 64KB boundary) is skipped, not fatal.
+    assert.equal(trailingEngineError(['ut"}}garbage-fragment', assistant('error', 'boom')].join('\n')), 'boom', 'cut first fragment is skipped');
+    // An error turn with no errorMessage still reads as a wedge.
+    assert.notEqual(trailingEngineError(assistant('error')), null, 'error with no errorMessage still matches');
+    assert.equal(trailingEngineError(null), null, 'no tail → null');
+    assert.equal(trailingEngineError(''), null, 'empty tail → null');
+});
+// ---------------------------------------------------------------------------
+// E3 — daemon integration: a parked trailing-error engine is force-recycled.
+// ---------------------------------------------------------------------------
+const T0 = 9_000_000_000;
+test('E3 daemon force-kills a wedged engine: live, not-busy, intent-null, session quiet past grace with a trailing error turn', { timeout: 30_000 }, async () => {
+    const h = await createHeadlessHarness({ sessionPrefix: 'crtr-e3' });
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-e3-'));
+    // Real live subprocesses standing in for the parked engines; `sleep` dies on
+    // SIGTERM, so the daemon's force-kill is directly observable.
+    const wedged = spawn('sleep', ['300'], { stdio: 'ignore' });
+    const parked = spawn('sleep', ['300'], { stdio: 'ignore' });
+    try {
+        // The WEDGED node: session ends in an error turn, quiet for > the grace.
+        const wedgedFile = join(dir, 'wedged.jsonl');
+        writeFileSync(wedgedFile, [assistant('toolUse'), toolResult(), assistant('error', 'Connection error.')].join('\n') + '\n');
+        const staleSec = (T0 - ERROR_STALL_QUIET_MS - 1) / 1000;
+        utimesSync(wedgedFile, staleSec, staleSec);
+        const wedgedId = h.fabricateBrokerNode({
+            kind: 'developer',
+            status: 'active',
+            pi_pid: wedged.pid,
+            pi_session_id: 'sess-e3-wedged',
+            pi_session_file: wedgedFile,
+        });
+        // The CONTROL node: equally old and quiet, but its last turn is a healthy
+        // 'stop' (an attended root overnight) — must NEVER be killed.
+        const parkedFile = join(dir, 'parked.jsonl');
+        writeFileSync(parkedFile, [assistant('toolUse'), toolResult(), assistant('stop')].join('\n') + '\n');
+        utimesSync(parkedFile, staleSec, staleSec);
+        h.fabricateBrokerNode({
+            kind: 'developer',
+            status: 'active',
+            pi_pid: parked.pid,
+            pi_session_id: 'sess-e3-parked',
+            pi_session_file: parkedFile,
+        });
+        assert.equal(isPidAlive(wedged.pid), true, 'precondition: the wedged engine is alive');
+        // --- TICK @ T0: the session has already been quiet past the grace (the
+        //     file mtime is the clock — no arming tick), so the daemon SIGTERMs
+        //     the wedged engine on sight. ---
+        await h.tick(T0);
+        await h.waitFor(() => (isPidAlive(wedged.pid) ? null : true), {
+            label: 'daemon SIGTERM killed the wedged trailing-error engine (§I)',
+            timeoutMs: 10_000,
+        });
+        assert.equal(isPidAlive(wedged.pid), false, 'the wedged engine was force-killed');
+        assert.equal(isPidAlive(parked.pid), true, 'the healthily-parked engine was NOT touched');
+        assert.equal(h.node(wedgedId).intent ?? null, null, 'intent stays null — the dead-pid CRASH branch owns the revive (resume)');
+    }
+    finally {
+        for (const c of [wedged, parked]) {
+            try {
+                c.kill('SIGKILL');
+            }
+            catch {
+                /* already gone */
+            }
+        }
+        rmSync(dir, { recursive: true, force: true });
+        await h.dispose();
+    }
+});

package/dist/core/__tests__/fixtures/fake-engine.d.ts

@@ -80,11 +80,22 @@ declare class FakeSession {
     private readonly messageLog;
     constructor(sm: SessionManager, loader: ResourceLoader | undefined);
     get messages(): unknown[];
+    get sessionManager(): {
+        buildSessionContext: () => {
+            messages: unknown[];
+            thinkingLevel: string;
+            model: null;
+        };
+    };
     get sessionId(): string;
     get sessionFile(): string | undefined;
     get model(): {
         id: string;
     } | undefined;
+    private currentModel;
+    setModel(model: {
+        id: string;
+    }): Promise<void>;
     get isStreaming(): boolean;
     getSessionStats(): Record<string, unknown>;
     setSessionName(_name: string): void;
@@ -92,6 +103,15 @@ declare class FakeSession {
     steer(_text: string): Promise<void>;
     followUp(_text: string): Promise<void>;
     abort(): Promise<void>;
+    /** In-place tree rewind (broker `navigate_tree`). Mirrors the real SDK's
+     *  contract: the session file is unchanged, the live history is truncated,
+     *  and the navigated-to user message's text comes back as `editorText`. The
+     *  fake's "rewind" drops the last accrued turn so a re-welcome snapshot is
+     *  observably shorter (the navigate-tree-rewelcome regression lock). */
+    navigateTree(targetId: string, _options?: unknown): Promise<{
+        editorText?: string;
+        cancelled: boolean;
+    }>;
     subscribe(listener: (event: unknown) => void): () => void;
     /** Fan one typed AgentSessionEvent out to every broker subscriber. A throwing
      *  listener is recorded, never propagated (mirrors the broker's m7 try/catch). */
@@ -117,7 +137,10 @@ declare class FakeSession {
 interface FakeServices {
     resourceLoader: ResourceLoader;
     modelRegistry: {
-        find: (provider: string, id: string) => undefined;
+        find: (provider: string, id: string) => {
+            provider: string;
+            id: string;
+        } | undefined;
     };
 }
 export declare function createAgentSessionServices(options: {

package/dist/core/__tests__/fixtures/fake-engine.js

@@ -167,6 +167,16 @@ class FakeSession {
     get messages() {
         return this.messageLog;
     }
+    // The broker's catch-up snapshot reconstructs history from the persisted
+    // session tree (sessionManager.buildSessionContext) — the single source of
+    // truth, since `session.messages` can be sliced by pi's retry/overflow/
+    // compaction recovery. Mirror that surface so the fake's snapshot still serves
+    // the accrued history (G2/G3). The fake's persisted analog IS messageLog.
+    get sessionManager() {
+        return {
+            buildSessionContext: () => ({ messages: this.messageLog, thinkingLevel: 'off', model: null }),
+        };
+    }
     get sessionId() {
         return this.sm.getSessionId();
     }
@@ -174,7 +184,15 @@ class FakeSession {
         return this.sm.getSessionFile();
     }
     get model() {
-        return undefined;
+        return this.currentModel;
+    }
+    // set_model regression surface: the broker resolves the spec via the services
+    // registry stub below, calls setModel, then broadcasts `model_changed` off
+    // this getter — store whatever it hands us.
+    currentModel;
+    setModel(model) {
+        this.currentModel = model;
+        return Promise.resolve();
     }
     get isStreaming() {
         return this.streaming;
@@ -205,6 +223,15 @@ class FakeSession {
     abort() {
         return Promise.resolve();
     }
+    /** In-place tree rewind (broker `navigate_tree`). Mirrors the real SDK's
+     *  contract: the session file is unchanged, the live history is truncated,
+     *  and the navigated-to user message's text comes back as `editorText`. The
+     *  fake's "rewind" drops the last accrued turn so a re-welcome snapshot is
+     *  observably shorter (the navigate-tree-rewelcome regression lock). */
+    navigateTree(targetId, _options) {
+        this.messageLog.pop();
+        return Promise.resolve({ cancelled: false, editorText: `rewound-to:${targetId}` });
+    }
     // --- the single engine event stream the broker fans out (broker.ts subscribes
     //     here and broadcasts each event VERBATIM to every attached viewer) --------
     subscribe(listener) {
@@ -571,7 +598,10 @@ export async function createAgentSessionServices(options) {
     await loader.reload();
     return {
         resourceLoader: loader,
-        modelRegistry: { find: () => undefined },
+        // A minimal model stub for any spec: the lifecycle harness passes no boot
+        // model (so this is never hit at boot), but the set_model regression test
+        // drives the broker's findModelSpec → session.setModel path through it.
+        modelRegistry: { find: (provider, id) => ({ provider, id }) },
     };
 }
 export async function createAgentSessionFromServices(options) {

package/dist/core/__tests__/fixtures/fake-pi-host.js

@@ -129,7 +129,7 @@ let eventSeq = 0;
 // Append a durable record of every fired event BEFORE its handlers run. This is
 // the harness's robust "the host received my command and is dispatching it"
 // signal — it survives even when a handler tears the process down mid-flight
-// (e.g. agent_end→reviveInPlace does respawn-pane -k on our own pane), which is
+// (e.g. agent_end on a refresh/done node drives the broker shutdown), which is
 // exactly the case where an after-the-fact ack would be lost.
 function recordEvent(event, ev) {
     try {
@@ -219,7 +219,7 @@ const boot = {
 };
 writeFileSync(join(nodeDir, 'fake-pi.boot.json'), JSON.stringify(boot, null, 2));
 // Append-only boot log so the harness can count re-boots (a resume after an
-// idle-release wake, or a fresh pi after a refresh-yield reviveInPlace).
+// idle-release wake, or a fresh pi after a refresh-yield).
 try {
     appendFileSync(join(nodeDir, 'fake-pi.boots.jsonl'), JSON.stringify(boot) + '\n');
 }

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

@@ -11,7 +11,8 @@
 //     is rejected (upholds "a node occupies <=1 focus", Q5)
 //   - independent focus rows don't contend
 //   - placement focusOf / isFocused / focusByPane / focusedNodes / listFocuses
-//     agree with the rows
+//     GC dead-pane viewer rows on read (liveOrPrune), and pass null-pane rows
+//     through (broker-host cut: placement reads self-heal the viewer registry)
 import { test, before, beforeEach, after } from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdtempSync, rmSync } from 'node:fs';
@@ -136,7 +137,7 @@ test('open / setOccupant / close round-trip with the reads', () => {
     setFocusOccupant('f1', 'B');
     assert.equal(getFocusByNode('A'), null, 'A no longer occupies the focus');
     assert.deepEqual(getFocusByNode('B'), { focus_id: 'f1', pane: '%a', session: 'Sa', node_id: 'B' });
-    // setFocusPane re-points the pane + session cache (reconcileFocus, Step 6).
+    // setFocusPane re-points the pane + session cache after a viewer move.
     setFocusPane('f1', '%a2', 'Sa2');
     assert.deepEqual(getFocusById('f1'), { focus_id: 'f1', pane: '%a2', session: 'Sa2', node_id: 'B' });
     assert.equal(getFocusByPane('%a'), null, 'the old pane no longer resolves');
@@ -161,7 +162,7 @@ test('UNIQUE(node_id): hot-swapping an occupant onto an already-focused node is
     openFocusRow('f1', '%a', 'Sa', 'A');
     openFocusRow('f2', '%b', 'Sb', 'B');
     // B already occupies f2 — moving it onto f1 via setFocusOccupant must throw
-    // (the Q5 vacate-first is retargetFocus's job, Step 6, not this setter's).
+    // (the Q5 vacate-first is placement.focus()'s job, not this setter's).
     assert.throws(() => setFocusOccupant('f1', 'B'), /UNIQUE|constraint/i);
     assert.deepEqual(getFocusByNode('A'), { focus_id: 'f1', pane: '%a', session: 'Sa', node_id: 'A' });
     assert.deepEqual(getFocusByNode('B'), { focus_id: 'f2', pane: '%b', session: 'Sb', node_id: 'B' });
@@ -179,18 +180,29 @@ test('independent focus rows do not contend', () => {
     assert.deepEqual(listFocuses().map((f) => f.focus_id), ['f2']);
 });
 // ---------------------------------------------------------------------------
-// Placement reads — focusOf / isFocused / focusByPane / focusedNodes / listFocuses
-// agree with the rows.
+// Placement reads — focusOf / isFocused / focusByPane / focusedNodes /
+// listFocuses GC dead-pane viewer rows on read (broker-host cut: liveOrPrune).
+// A row whose viewer pane no longer exists is pruned the next time it is read,
+// so the registry self-heals without a sweeper; a row with a null pane (a
+// registered-but-not-yet-realized viewer) is passed through. A live tmux pane
+// can't be fabricated in the fast tier, so we cover the prune + null-pane paths
+// here; the live-pane read is covered in the full-tier broker lifecycle suite.
 // ---------------------------------------------------------------------------
-test('placement focus reads agree with the focus rows', () => {
+test('placement reads GC dead-pane viewer rows and keep null-pane rows', () => {
     openDb();
-    openFocusRow('f1', '%a', 'Sa', 'A');
-    openFocusRow('f2', '%b', 'Sb', 'B');
-    assert.deepEqual(focusOf('A'), { focus_id: 'f1', pane: '%a', session: 'Sa', node_id: 'A' });
+    openFocusRow('f1', '%a', 'Sa', 'A'); // %a is not a live tmux pane → pruned on read
+    openFocusRow('f2', null, 'Sb', 'B'); // null pane (not realized yet) → kept
+    // The dead-pane row is GC'd on read: placement returns null AND the row is
+    // removed from the canvas table (self-healing registry).
+    assert.equal(focusOf('A'), null, 'a viewer whose pane is gone is pruned on read');
+    assert.equal(getFocusByNode('A'), null, 'the pruned row is closed in the db');
+    assert.equal(isFocused('A'), false);
+    assert.equal(focusByPane('%a'), null, 'focusByPane prunes the dead pane too');
+    // The null-pane row survives (liveOrPrune only prunes a non-null dead pane).
+    assert.deepEqual(focusOf('B'), { focus_id: 'f2', pane: null, session: 'Sb', node_id: 'B' });
+    assert.equal(isFocused('B'), true);
     assert.equal(focusOf('Z'), null, 'an unfocused node has no focus');
-    assert.equal(isFocused('A'), true);
     assert.equal(isFocused('Z'), false);
-    assert.deepEqual(focusByPane('%b'), { focus_id: 'f2', pane: '%b', session: 'Sb', node_id: 'B' });
-    assert.deepEqual(focusedNodes(), new Set(['A', 'B']));
-    assert.deepEqual(placementListFocuses().map((f) => f.node_id), ['A', 'B']);
+    assert.deepEqual(focusedNodes(), new Set(['B']));
+    assert.deepEqual(placementListFocuses().map((f) => f.node_id), ['B']);
 });

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

@@ -72,19 +72,36 @@ test('resolveForkSource resolves a node id to its absolute session FILE', () =>
     createNode(node('src', { pi_session_id: 'uuid-1', pi_session_file: '/abs/src.jsonl' }));
     assert.equal(resolveForkSource('src'), '/abs/src.jsonl');
 });
-test('resolveForkSource falls back to the bare session id when no file captured', () => {
+test('resolveForkSource THROWS when a node has a session id but no captured FILE', () => {
+    // Broker-cut contract (U6/§B.broker): the broker forks an absolute .jsonl PATH,
+    // never a bare session id. A node row carrying only pi_session_id (no
+    // pi_session_file) can no longer be forked — it fails loudly pre-launch.
     createNode(node('src', { pi_session_id: 'uuid-1' }));
-    assert.equal(resolveForkSource('src'), 'uuid-1');
+    assert.throws(() => resolveForkSource('src'), /no pi session yet|session FILE/);
 });
 test('resolveForkSource throws when the node has no pi session to fork yet', () => {
     createNode(node('fresh'));
     assert.throws(() => resolveForkSource('fresh'), /no pi session yet/);
 });
-test('resolveForkSource passes a path straight through', () => {
+test('resolveForkSource passes an absolute path straight through', () => {
     assert.equal(resolveForkSource('/some/where/sess.jsonl'), '/some/where/sess.jsonl');
 });
-test('resolveForkSource passes an unknown bare/partial uuid through to pi', () => {
-    assert.equal(resolveForkSource('019e8ce3-322e'), '019e8ce3-322e');
+test('resolveForkSource makes a relative path absolute', () => {
+    assert.equal(resolveForkSource('sub/sess.jsonl'), join(process.cwd(), 'sub/sess.jsonl'));
+});
+test('resolveForkSource THROWS on a bare/partial uuid that resolves to no session', () => {
+    // Broker-cut contract (U6): an unknown bare/partial uuid is scanned against
+    // pi's sessions store and fails loudly when it matches nothing — it is no
+    // longer passed through verbatim (the broker fork won't resolve a uuid).
+    const sessRoot = mkdtempSync(join(tmpdir(), 'crtr-pi-agent-'));
+    process.env['PI_CODING_AGENT_DIR'] = sessRoot;
+    try {
+        assert.throws(() => resolveForkSource('019e8ce3-322e'), /no pi session/);
+    }
+    finally {
+        delete process.env['PI_CODING_AGENT_DIR'];
+        rmSync(sessRoot, { recursive: true, force: true });
+    }
 });
 test('resolveForkSource rejects an empty reference', () => {
     assert.throws(() => resolveForkSource('   '), /requires a node id/);

package/dist/core/__tests__/full/broker-control-preempt.test.d.ts

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

package/dist/core/__tests__/full/broker-control-preempt.test.js

@@ -0,0 +1,61 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/full/broker-control-preempt.test.ts
+// (FULL tier — boots a real isolated tmux session + a real headless broker.)
+//
+// BUG-REGRESSION (broker-universal-host cut, design §D preemptive handoff; U1
+// report mq8ftenr-5d55313d). Before the cut, `request_control` granted control
+// ONLY when controllerId===null and otherwise returned a `control_held` error —
+// so a second client could NEVER preempt a live (and usually idle/abandoned)
+// controller. With every node now broker-hosted, a tmux pane and a web tab are
+// true peers: either must be able to take control of a node the other currently
+// drives. The fix makes request_control preemptive last-requester-wins — it
+// ALWAYS succeeds, reassigning control to the requester and broadcasting a
+// control_changed that demotes the prior controller. There is no `control_held`
+// error frame anymore.
+//
+// Drive: controller A attaches and holds control; observer B then requests
+// control. Assert control reassigns to B, a control_changed broadcasts demoting
+// A, and B got NO error frame back (the old `control_held` reject is gone).
+// Regression check: restore the controllerId!==null reject and B's request is
+// refused (controller_id stays A / B receives an error) → these asserts go RED.
+import { test, before, after, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { createHeadlessHarness } from '../helpers/harness.js';
+import { createAttachKit } from '../helpers/broker-clients.js';
+let h;
+let id;
+const kit = createAttachKit(() => h);
+const { attach, attachUntil } = kit;
+before(async () => {
+    h = await createHeadlessHarness({ sessionPrefix: 'crtr-ctrlpreempt' });
+    const root = h.spawnRoot('control-preempt suite root');
+    id = await h.spawnHeadlessChild(root, 'headless worker — control preemption');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+afterEach(() => {
+    kit.closeAll();
+});
+test('D3 — a second client preempts the live controller (last-requester-wins); the prior controller is demoted, no control_held reject', async () => {
+    // A attaches and is granted control (controllerId was null). attachUntil
+    // suffixes the client_id per retry, so the broker-assigned id is the welcome's.
+    const bId = 'd3-B';
+    const a = await attachUntil(id, 'controller', 'd3-A', (x) => x.welcome.role === 'controller', 'A admitted controller');
+    const aId = a.welcome.controller_id;
+    assert.ok(aId !== null, 'A holds control after attach');
+    // B attaches as an observer while A holds control (its welcome reflects A).
+    const b = await attach(id, 'observer', bId);
+    assert.equal(b.welcome.role, 'observer', 'B starts as an observer (A holds control)');
+    assert.equal(b.welcome.controller_id, aId, 'B sees A as the current controller');
+    // B preempts. Under the OLD model this returned a control_held error and B
+    // never became controller; under §D it ALWAYS succeeds.
+    b.send({ type: 'request_control' });
+    // A is demoted via a broadcast control_changed naming B as the new controller.
+    const changed = await a.waitFrame((f) => f.type === 'control_changed' && f.controller_id === bId, 'A receives control_changed demoting it to B');
+    assert.equal(changed.controller_id, bId, 'control reassigned to B (last-requester-wins)');
+    // B sees itself as the controller too (same broadcast).
+    await b.waitFrame((f) => f.type === 'control_changed' && f.controller_id === bId, 'B observes itself become controller');
+    // The old `control_held` reject is gone: B's request drew NO error frame.
+    assert.ok(!b.frames.some((f) => f.type === 'error'), 'B received NO error frame — there is no control_held reject in the preemptive model');
+});

package/dist/core/__tests__/full/broker-model-changed-broadcast.test.d.ts

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

package/dist/core/__tests__/full/broker-model-changed-broadcast.test.js

@@ -0,0 +1,57 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/full/broker-model-changed-broadcast.test.ts
+//
+// FULL TIER (real-boot-bound): tmux-free, but it boots a REAL broker process,
+// so it lives in full/ (CI), not the fast local loop.
+//
+// BUG-REGRESSION (real, observed 2026-06-11 in `crtr attach`): switching the
+// model (/model <provider/id> or the picker) visibly did nothing — the viewer's
+// status bar kept showing the OLD model until some unrelated event happened to
+// arrive.
+//
+// 3-PART HEADER:
+//  (1) BUG IT LOCKS — pi emits no AgentSessionEvent for a model switch, and the
+//      broker's `set_model`/`cycle_model` handlers replied with only a bare ack
+//      to the REQUESTING client. The new model reached no viewer at all: the
+//      broker now broadcasts a `model_changed` frame (mirroring
+//      snapshot.state.model) to every client after the engine accepts the switch.
+//  (2) WHY BROKER/SOCKET-LEVEL, NOT PANE — the regression is pure frame-plumbing
+//      on view.sock: a controller `set_model` in, an ack + `model_changed`
+//      fan-out. No tmux pane or TUI is involved, so the lock holds headlessly
+//      (createHeadlessHarness + the fake engine, whose registry stub resolves
+//      any `provider/id` and whose setModel stores what it is handed).
+//  (3) HOW IT FAILS ON REGRESSION — pre-fix, NO `model_changed` frame ever
+//      arrives at either the controller or the observer (both waits time out);
+//      the ack alone still passing would not satisfy the broadcast asserts.
+import { test, before, after, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { createHeadlessHarness } from '../helpers/harness.js';
+import { createAttachKit } from '../helpers/broker-clients.js';
+let h;
+let id;
+const kit = createAttachKit(() => h);
+const { attachUntil } = kit;
+before(async () => {
+    h = await createHeadlessHarness({ sessionPrefix: 'crtr-brkmodel' });
+    const root = h.spawnRoot('model-changed-broadcast suite root');
+    id = await h.spawnHeadlessChild(root, 'headless worker — model_changed broadcast gate');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+afterEach(() => {
+    kit.closeAll();
+});
+test('set_model acks the requester and broadcasts model_changed to every viewer', async () => {
+    const c = await attachUntil(id, 'controller', 'model-ctrl', (a) => a.welcome.role === 'controller', 'model-ctrl admitted controller');
+    const o = await attachUntil(id, 'observer', 'model-obs', (a) => a.welcome.role === 'observer', 'model-obs admitted observer');
+    c.send({ type: 'set_model', model: 'anthropic/fake-fable' });
+    const ack = await c.waitFrame((f) => f.type === 'ack' && f.for === 'set_model', 'set_model ack');
+    assert.ok(ack.type === 'ack' && ack.ok, 'set_model acked ok');
+    // BOTH the requester and the observer hear the switch. Pre-fix: no
+    // model_changed frame exists, so neither wait ever resolves.
+    const cm = await c.waitFrame((f) => f.type === 'model_changed', 'controller receives model_changed');
+    assert.ok(cm.type === 'model_changed' && cm.model === 'fake-fable', 'controller sees the new model id');
+    const om = await o.waitFrame((f) => f.type === 'model_changed', 'observer receives model_changed');
+    assert.ok(om.type === 'model_changed' && om.model === 'fake-fable', 'observer sees the new model id');
+});

package/dist/core/__tests__/full/broker-navigate-tree-rewelcome.test.d.ts

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

package/dist/core/__tests__/full/broker-navigate-tree-rewelcome.test.js

@@ -0,0 +1,80 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/full/broker-navigate-tree-rewelcome.test.ts
+//
+// FULL TIER (real-boot-bound): tmux-free, but it boots a REAL broker process,
+// so it lives in full/ (CI), not the fast local loop.
+//
+// BUG-REGRESSION (real, observed 2026-06-11 in `crtr attach`): double-Esc (or
+// /tree) opened the session-tree picker, but SELECTING an entry visibly did
+// nothing — the viewer stayed on the old transcript instead of traveling back
+// to the chosen point in time.
+//
+// 3-PART HEADER:
+//  (1) BUG IT LOCKS — the broker's `navigate_tree` handler called
+//      session.navigateTree() (which rewinds IN-PLACE: same session file, new
+//      leaf, NO relayed AgentSessionEvent) and then only acked. Unlike the
+//      session-replacing ops (new_session/switch_session/fork → runReplacement
+//      → reWelcomeAll), it never re-snapshotted the viewers, so every attached
+//      client kept rendering the abandoned branch. The navigated-to user
+//      message's `editorText` (pi parity: the tree navigator restores it to the
+//      editor) was dropped on the floor too.
+//  (2) WHY BROKER/SOCKET-LEVEL, NOT PANE — the regression is pure frame-plumbing
+//      on view.sock: a controller `navigate_tree` in, a re-`welcome` fan-out +
+//      ack.detail out. No tmux pane or TUI is involved, so the lock holds
+//      headlessly (createHeadlessHarness + the fake engine, whose navigateTree
+//      pops the last accrued turn and returns `rewound-to:<targetId>`).
+//  (3) HOW IT FAILS ON REGRESSION — pre-fix, NO second welcome ever arrives
+//      (the re-welcome waits time out) and the navigate_tree ack carries no
+//      detail; the rewound-history assert (the turn token gone from the new
+//      snapshot) also goes red if the re-welcome serves a stale snapshot.
+import { test, before, after, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { createHeadlessHarness } from '../helpers/harness.js';
+import { createAttachKit, frameHas, tok } from '../helpers/broker-clients.js';
+let h;
+let id;
+const kit = createAttachKit(() => h);
+const { attachUntil } = kit;
+before(async () => {
+    h = await createHeadlessHarness({ sessionPrefix: 'crtr-brknav' });
+    const root = h.spawnRoot('navigate-tree-rewelcome suite root');
+    id = await h.spawnHeadlessChild(root, 'headless worker — navigate-tree rewelcome gate');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+afterEach(() => {
+    kit.closeAll();
+});
+const welcomes = (frames) => frames.filter((f) => f.type === 'welcome');
+test('navigate_tree re-welcomes every viewer onto the rewound transcript and acks the editor text', async () => {
+    const c = await attachUntil(id, 'controller', 'nav-ctrl', (a) => a.welcome.role === 'controller', 'nav-ctrl admitted controller');
+    // Accrue one observable turn so the rewind has something to drop.
+    const token = tok('NAV-TURN');
+    c.send({ type: 'prompt', text: token });
+    await c.waitFrame((f) => f.type === 'agent_end' && frameHas(f, token), 'turn relayed before navigate');
+    // The observer attaches AFTER the turn so its first welcome deterministically
+    // holds the token (the pre-navigate baseline) — same accrual trick as G3.
+    const o = await attachUntil(id, 'observer', 'nav-obs', (a) => frameHas(a.welcome, token), 'observer welcome holds the pre-navigate turn');
+    c.send({ type: 'navigate_tree', targetId: 'entry-x' });
+    // The ack carries the navigated-to user message's text in detail (the viewer
+    // restores it to the editor). Pre-fix: ack had no detail.
+    const ack = await c.waitFrame((f) => f.type === 'ack' && f.for === 'navigate_tree', 'navigate_tree ack');
+    assert.ok(ack.type === 'ack' && ack.ok, 'navigate_tree acked ok');
+    assert.equal(ack.type === 'ack' ? ack.detail : undefined, 'rewound-to:entry-x', 'ack.detail carries the rewound-to editor text');
+    // BOTH viewers get re-welcomed onto the rewound history. Pre-fix: no second
+    // welcome ever arrives (navigate_tree only acked).
+    await h.waitFor(() => (welcomes(c.frames).length >= 2 ? true : null), {
+        label: 'controller re-welcomed after navigate_tree',
+    });
+    await h.waitFor(() => (welcomes(o.frames).length >= 2 ? true : null), {
+        label: 'observer re-welcomed after navigate_tree',
+    });
+    // The re-welcome serves the REWOUND transcript: the fake's navigateTree popped
+    // the last accrued turn, so the token present in the observer's first welcome
+    // must be gone from its second.
+    const [first, second] = welcomes(o.frames);
+    assert.ok(frameHas(first, token), 'pre-navigate welcome holds the turn');
+    assert.ok(!frameHas(second, token), 're-welcome serves the rewound transcript (turn dropped)');
+    assert.equal(second.snapshot.messages.length, first.snapshot.messages.length - 1, 're-welcome history is exactly one turn shorter');
+});