@north-light/crouter 0.3.172 → 0.3.174

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

@@ -2,14 +2,14 @@
 //   1. A passive subscriber's pushes land in passive.jsonl, NOT inbox.jsonl
 //      (so the inbox-watcher never wakes it); an active subscriber's land in
 //      inbox.jsonl as before.
-//   2. drainPassive reads + clears the accumulator (surfaces exactly once).
+//   2. the broker drain reads + clears the accumulator (surfaces exactly once).
 //   3. canvas-passive-context formats drained entries as timestamped XML and
 //      transforms an `input` event into pre-text + the original message.
 //
 // Run: node --import tsx/esm --test src/core/__tests__/passive-subscription.test.ts
 import { test, before, beforeEach, afterEach, after } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, rmSync, existsSync, appendFileSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, rmSync, existsSync, readFileSync, appendFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, join } from 'node:path';
 import { createNode, subscribe } from '../canvas/canvas.js';
@@ -17,11 +17,18 @@ import { closeDb } from '../canvas/db.js';
 import { inboxPath, passivePath, apiSocketPath } from '../canvas/paths.js';
 import { createApiServer } from '../../daemon/api/server.js';
 import { push } from '../feed/feed.js';
-import { appendPassive, readPassive, drainPassive } from '../feed/passive.js';
+import { appendPassive } from '../feed/passive.js';
 import { readInboxSince } from '../feed/inbox.js';
+import { drainBrokerPassive } from '../runtime/broker/passive.js';
 import { readLeaf } from '../../commands/canvas-history/read.js';
-import registerCanvasPassiveContext, { formatPassive } from '../../pi-extensions/canvas-passive-context.js';
+import registerCanvasPassiveContext from '../../pi-extensions/canvas-passive-context.js';
 let home;
+function readPassiveEntries(nodeId) {
+    const path = passivePath(nodeId);
+    if (!existsSync(path))
+        return [];
+    return readFileSync(path, 'utf8').split('\n').filter(Boolean).map((line) => JSON.parse(line));
+}
 // The one test that resolves an emitted feed ref drives `canvas history read`'s
 // leaf (`readLeaf`), a thin CLI forwarder to crtrd since the API re-plumb. Stand
 // up a real in-process `createApiServer()` on the isolated CRTR_HOME's socket so
@@ -76,7 +83,7 @@ test('passive push accumulates in passive.jsonl, not inbox.jsonl', async () => {
     const result = await push('pub', { kind: 'update', body: 'first observation\nmore detail' });
     // The emitted feed ref is the same canonical handle accepted by `canvas
     // history read`, while PushResult.reportPath remains an absolute path.
-    const acc = readPassive('observer');
+    const acc = readPassiveEntries('observer');
     const ref = acc[0].ref;
     assert.equal(ref, `pub:reports/${basename(result.reportPath)}`);
     const resolved = await readLeaf.run({ ref });
@@ -113,21 +120,21 @@ test('mixed active + passive subscribers route to their own stores', async () =>
     assert.deepEqual(new Set(res.deliveredTo), new Set(['active-sub', 'passive-sub']));
     assert.equal(readInboxSince('active-sub').length, 1);
     assert.equal(existsSync(passivePath('active-sub')), false);
-    assert.equal(readPassive('passive-sub').length, 1);
+    assert.equal(readPassiveEntries('passive-sub').length, 1);
     assert.equal(existsSync(inboxPath('passive-sub')), false);
 });
-test('drainPassive reads then clears (surfaces exactly once)', () => {
+test('broker passive drain reads then clears (surfaces exactly once)', () => {
     createNode(node('observer'));
     appendPassive('observer', { from: 'a', tier: 'normal', kind: 'update', label: 'one' });
     appendPassive('observer', { from: 'b', tier: 'normal', kind: 'update', label: 'two' });
-    const drained = drainPassive('observer');
+    const drained = drainBrokerPassive('observer');
     assert.equal(drained.length, 2);
     assert.deepEqual(drained.map((e) => e.label), ['one', 'two']); // oldest first
     // Cleared — a second drain is empty.
-    assert.equal(drainPassive('observer').length, 0);
-    assert.equal(readPassive('observer').length, 0);
+    assert.equal(drainBrokerPassive('observer').length, 0);
+    assert.equal(readPassiveEntries('observer').length, 0);
 });
-test('drainPassive tolerates a corrupt line — keeps every good entry, loses only the bad one', () => {
+test('broker passive drain tolerates a corrupt line — keeps every good entry, loses only the bad one', () => {
     createNode(node('observer'));
     appendPassive('observer', { from: 'a', tier: 'normal', kind: 'update', label: 'one' });
     appendPassive('observer', { from: 'b', tier: 'normal', kind: 'update', label: 'two' });
@@ -135,43 +142,13 @@ test('drainPassive tolerates a corrupt line — keeps every good entry, loses on
     // mid-append). The whole feed must NOT be discarded over it.
     appendFileSync(passivePath('observer'), '{not valid json\n', 'utf8');
     appendPassive('observer', { from: 'c', tier: 'normal', kind: 'update', label: 'three' });
-    const drained = drainPassive('observer');
+    const drained = drainBrokerPassive('observer');
     assert.equal(drained.length, 3, 'all three good entries survive the corrupt line');
     assert.deepEqual(drained.map((e) => e.label), ['one', 'two', 'three']);
     // And it still cleared: a second drain is empty (snapshot removed).
-    assert.equal(drainPassive('observer').length, 0);
+    assert.equal(drainBrokerPassive('observer').length, 0);
     assert.equal(existsSync(passivePath('observer')), false);
 });
-test('readPassive tolerates a corrupt line without clearing', () => {
-    createNode(node('observer'));
-    appendPassive('observer', { from: 'a', tier: 'normal', kind: 'update', label: 'one' });
-    appendFileSync(passivePath('observer'), 'garbage}\n', 'utf8');
-    appendPassive('observer', { from: 'b', tier: 'normal', kind: 'update', label: 'two' });
-    const read = readPassive('observer');
-    assert.deepEqual(read.map((e) => e.label), ['one', 'two']);
-});
-test('formatPassive renders timestamped XML update blocks', () => {
-    const entries = [
-        {
-            entry_id: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
-            operation_id: '11111111111111111111111111111111',
-            ts: '2026-06-03T12:00:00.000Z',
-            from: 'pub-a', tier: 'normal', kind: 'update', label: 'alpha happened',
-        },
-        {
-            entry_id: 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
-            operation_id: '22222222222222222222222222222222',
-            ts: '2026-06-03T12:05:00.000Z',
-            from: 'pub-b', tier: 'urgent', kind: 'final', label: 'beta done',
-        },
-    ];
-    const xml = formatPassive(entries);
-    assert.match(xml, /<passive-subscription-backlog count="2"/);
-    assert.match(xml, /<update from="pub-a" kind="update" at="2026-06-03T12:00:00.000Z">/);
-    assert.match(xml, /alpha happened/);
-    assert.match(xml, /<update from="pub-b" kind="final" at="2026-06-03T12:05:00.000Z">/);
-    assert.match(xml, /<\/passive-subscription-backlog>/);
-});
 function makeFakePi() {
     return { on(e, h) { if (e === 'input')
             this.handler = h; } };
@@ -186,27 +163,27 @@ test('input handler injects drained backlog as pre-text, then clears it', async
     registerCanvasPassiveContext(pi);
     assert.ok(pi.handler, 'input handler registered');
     // First message → backlog drains in as pre-text before the user's text.
-    const out = pi.handler({ type: 'input', text: 'hey what happened', source: 'interactive' });
+    const out = await pi.handler({ type: 'input', text: 'hey what happened', source: 'interactive' });
     assert.equal(out.action, 'transform');
     assert.match(out.text, /<passive-subscription-backlog/);
     assert.match(out.text, /the body of the report/); // dereferenced report body
     assert.match(out.text, /hey what happened$/); // original message preserved at the end
     // Second message → nothing accumulated → left untouched.
-    const out2 = pi.handler({ type: 'input', text: 'still there?', source: 'interactive' });
+    const out2 = await pi.handler({ type: 'input', text: 'still there?', source: 'interactive' });
     assert.ok(out2 === undefined || out2.action === 'continue');
     // Oversized canonical reports must leave an actionable reader command in the
     // truncation tail, using the exact ref emitted into the passive feed.
     await push('pub', { kind: 'update', body: 'oversized report line '.repeat(250) });
-    const oversizedRef = readPassive('observer')[0].ref;
-    const out3 = pi.handler({ type: 'input', text: 'show me the rest', source: 'interactive' });
+    const oversizedRef = readPassiveEntries('observer')[0].ref;
+    const out3 = await pi.handler({ type: 'input', text: 'show me the rest', source: 'interactive' });
     assert.equal(out3.action, 'transform');
     assert.ok(out3.text.includes(`crtr canvas history read ${oversizedRef}`), 'truncation tail names the canonical reader and emitted ref');
 });
-test('input handler is inert when nothing is accumulated', () => {
+test('input handler is inert when nothing is accumulated', async () => {
     createNode(node('observer'));
     process.env['CRTR_NODE_ID'] = 'observer';
     const pi = makeFakePi();
     registerCanvasPassiveContext(pi);
-    const out = pi.handler({ type: 'input', text: 'plain message', source: 'interactive' });
+    const out = await pi.handler({ type: 'input', text: 'plain message', source: 'interactive' });
     assert.ok(out === undefined || out.action === 'continue');
 });

package/dist/core/__tests__/preview-registry-sync.test.js

@@ -4,8 +4,7 @@
 // src/core/preview-registry.ts is a hand-maintained, zero-import mirror of
 // every leaf's `help.preview.suppressOutput` — it has to be hand-maintained
 // (not computed) because the attach viewer can never import the live command
-// tree (build-root.ts pulls in every subtree, including the web client's
-// Tailwind native binary — see command-preview-implementation.md). This test
+// tree (build-root.ts pulls in every command subtree). This test
 // is the only thing that keeps the mirror honest: it walks the real,
 // buildRoot()-assembled tree (safe here — this is a test, not the attach
 // bundle) and asserts the set of leaves declaring `suppressOutput: true`

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

@@ -3,13 +3,17 @@ import assert from 'node:assert/strict';
 import { mkdtempSync, rmSync, existsSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { createNode, getRow, subscribe, recordSpawn, subscribersOf, subscriptionsOf, pruneNodes, } from '../canvas/canvas.js';
+import { createNode, getRow, subscribe, recordPid, recordSpawn, subscribersOf, subscriptionsOf, pruneNodes, pruneToLimit, } from '../canvas/canvas.js';
 import { closeDb, openDb } from '../canvas/db.js';
 import { nodeDir } from '../canvas/paths.js';
 let home;
 const DAY = 86_400_000;
 const old = () => new Date(Date.now() - 30 * DAY).toISOString();
 const now = () => new Date().toISOString();
+// A timestamp `secondsAgo` before now — for the count-based pruner, created
+// order doubles as recency order (no telemetry.json is written, so recencyMs
+// falls back to the created epoch).
+const at = (secondsAgo) => new Date(Date.now() - secondsAgo * 1000).toISOString();
 function node(id, over = {}) {
     return {
         node_id: id,
@@ -133,3 +137,92 @@ test('prune retains an old terminal node with an open managed worktree', () => {
     assert.ok(getRow('old-worktree') !== null, 'node remains to own its managed worktree');
     assert.ok(existsSync(nodeDir('old-worktree')), 'node dir remains');
 });
+test('count pruning keeps all live nodes even when liveCount exceeds the cap', () => {
+    // 5 live (active/idle with a running pi) + 2 old terminal; cap of 3.
+    // target = max(3, 5) = 5, so NO live node is ever deleted; the 2 terminal
+    // fall beyond rank 5 and are pruned.
+    for (let i = 0; i < 5; i++) {
+        createNode(node(`live-${i}`, { status: 'active', created: at(i) }));
+        recordPid(`live-${i}`, process.pid); // process.pid is alive → isPidAlive true
+    }
+    createNode(node('old-a', { status: 'dead', created: at(100) }));
+    createNode(node('old-b', { status: 'done', created: at(101) }));
+    const result = pruneToLimit({ maxNodes: 3 });
+    assert.equal(result.dryRun, false);
+    assert.deepEqual(result.pruned.map((p) => p.node_id).sort(), ['old-a', 'old-b']);
+    for (let i = 0; i < 5; i++) {
+        assert.ok(getRow(`live-${i}`) !== null, `live-${i} must survive past the cap`);
+    }
+});
+test('count pruning deletes the oldest terminal nodes beyond max(cap, liveCount)', () => {
+    // 1 live + 5 terminal of descending recency; cap of 3 → target = max(3,1) = 3.
+    // Ranked by recency DESC: live-0, term-0, term-1 (top 3, kept), then
+    // term-2, term-3, term-4 (rank >= 3, pruned).
+    createNode(node('live-0', { status: 'idle', created: at(0) }));
+    recordPid('live-0', process.pid);
+    for (let i = 0; i < 5; i++) {
+        createNode(node(`term-${i}`, { status: 'dead', created: at(10 + i) }));
+    }
+    const result = pruneToLimit({ maxNodes: 3 });
+    assert.deepEqual(result.pruned.map((p) => p.node_id).sort(), ['term-2', 'term-3', 'term-4']);
+    // The kept set: the live node + the two newest terminal.
+    for (const id of ['live-0', 'term-0', 'term-1']) {
+        assert.ok(getRow(id) !== null, `${id} must survive`);
+        assert.ok(existsSync(nodeDir(id)), `${id} dir must survive`);
+    }
+    // The pruned set: rows AND dirs gone.
+    for (const id of ['term-2', 'term-3', 'term-4']) {
+        assert.equal(getRow(id), null, `${id} row should be pruned`);
+        assert.ok(!existsSync(nodeDir(id)), `${id} dir should be removed`);
+    }
+});
+test('count pruning dry-run reports candidates without deleting rows or dirs', () => {
+    createNode(node('live-0', { status: 'idle', created: at(0) }));
+    recordPid('live-0', process.pid);
+    for (let i = 0; i < 5; i++) {
+        createNode(node(`term-${i}`, { status: 'dead', created: at(10 + i) }));
+    }
+    const result = pruneToLimit({ maxNodes: 3, dryRun: true });
+    assert.equal(result.dryRun, true);
+    assert.deepEqual(result.pruned.map((p) => p.node_id).sort(), ['term-2', 'term-3', 'term-4']);
+    for (const id of ['term-2', 'term-3', 'term-4']) {
+        assert.ok(getRow(id) !== null, `${id} row must survive a dry run`);
+        assert.ok(existsSync(nodeDir(id)), `${id} dir must survive a dry run`);
+    }
+});
+test('a non-terminal node with a dead pid is never a count-prune candidate (issue #114)', () => {
+    // An active row whose broker crashed: status stays 'active' but pi_pid is
+    // NULL (never recorded), so isPidAlive would be false. It must still be
+    // protected — crash-recovery, not the count-based pruner, owns this row —
+    // even though it's the oldest node and cap is exceeded by newer terminal rows.
+    createNode(node('crashed-active', { status: 'active', created: at(100) }));
+    for (let i = 0; i < 5; i++) {
+        createNode(node(`term-${i}`, { status: 'dead', created: at(i) }));
+    }
+    const result = pruneToLimit({ maxNodes: 3 });
+    assert.ok(!result.pruned.some((p) => p.node_id === 'crashed-active'), 'a crashed-but-active node must not be selected for pruning');
+    assert.ok(getRow('crashed-active') !== null, 'crashed-active row must survive');
+    assert.ok(existsSync(nodeDir('crashed-active')), 'crashed-active dir must survive');
+});
+test('count pruning retains an open managed worktree node beyond the cap', () => {
+    createNode(node('open-worktree', {
+        status: 'dead',
+        created: at(100),
+        managed_worktree: {
+            state: 'open',
+            path: join(home, 'worktrees', 'open-worktree'),
+            branch: 'crtr/open-worktree',
+            repo_root: '/tmp/repo',
+            base_ref: 'main',
+            base_sha: 'base',
+            created: at(100),
+        },
+    }));
+    for (let i = 0; i < 3; i++) {
+        createNode(node(`term-${i}`, { status: 'dead', created: at(i) }));
+    }
+    const result = pruneToLimit({ maxNodes: 1 });
+    assert.ok(!result.pruned.some((p) => p.node_id === 'open-worktree'));
+    assert.ok(getRow('open-worktree') !== null, 'node remains to own its managed worktree');
+    assert.ok(existsSync(nodeDir('open-worktree')), 'node dir remains');
+});

package/dist/core/__tests__/review-model-floor.test.js

@@ -43,20 +43,6 @@ test('base review ignores a light override and keeps its medium floor', () => {
     assert.equal(spec('review', 'light'), expected(REVIEW_FLOOR));
     assert.equal(spec('review', 'haiku'), expected(REVIEW_FLOOR));
 });
-test('no base kind defaults below the medium rung', () => {
-    const kinds = defaultKindsConfig();
-    for (const kind of [
-        'general', 'developer', 'design', 'plan', 'spec', 'review',
-        'plan/reviewers/requirements-coverage', 'plan/reviewers/pattern-consistency',
-        'plan/reviewers/code-smells', 'plan/reviewers/security', 'plan/reviewers/architecture-fit',
-        'spec/requirements',
-    ]) {
-        // Kind defaults are provider-qualified and differ per kind; what must hold
-        // for every one of these is the rung, not the provider or the concrete id.
-        const rung = kinds[kind].model.split('/').pop();
-        assert.ok(rung === 'medium' || rung === 'strong' || rung === 'ultra', `${kind} defaults to ${kinds[kind].model}`);
-    }
-});
 test('plan reviewer sub-kinds also keep their medium worker floor', () => {
     assert.equal(spec('plan/reviewers/security', 'light'), expected('medium'));
     assert.equal(spec('plan/reviewers/requirements-coverage', 'light'), expected('medium'));
@@ -68,24 +54,6 @@ test('review still permits equal-or-stronger explicit models', () => {
     assert.equal(spec('review', 'strong'), expected('strong'));
     assert.equal(spec('review', 'ultra'), expected('ultra'));
 });
-test('concrete overrides stay pinned while logical provider/strength overrides remain unpinned', () => {
-    const qualified = buildLaunchSpec('developer', 'base', {
-        lifecycle: 'terminal', hasManager: true, cwd: home, profileId: null, model: 'anthropic/ultra',
-    }).launch;
-    const exact = buildLaunchSpec('developer', 'base', {
-        lifecycle: 'terminal', hasManager: true, cwd: home, profileId: null, model: 'openai/gpt-5',
-    }).launch;
-    const bare = buildLaunchSpec('developer', 'base', {
-        lifecycle: 'terminal', hasManager: true, cwd: home, profileId: null, model: 'ultra',
-    }).launch;
-    assert.equal(qualified.modelProviderPinned, false);
-    assert.equal(exact.modelProviderPinned, true);
-    assert.equal(bare.modelProviderPinned, false);
-});
-test('explore remains cheap by default and may explicitly run light', () => {
-    assert.equal(spec('explore'), expected(defaultKindsConfig()['explore'].model));
-    assert.equal(spec('explore', 'light'), expected('light'));
-});
 // `node new --model` widened to the full spec grammar (provider/tier, exact
 // provider/id, family alias) alongside the bare tier — the review floor must
 // still hold no matter which shape the requested model arrives in.

package/dist/core/__tests__/seam/broker-attach-multiclient.test.js

@@ -0,0 +1,255 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/seam/broker-attach-multiclient.test.ts
+//
+// COMPILED SEAM (real-boot-bound): tmux-free, but it boots a REAL broker process
+// (~5s pi-SDK load), so it lives in seam/ (CI), not the fast local loop.
+//
+// The MULTI-CLIENT half of the `crtr surface attach` acceptance gate: everything
+// whose contract is "more than one viewer is attached at once". One shared broker
+// serves all four journeys.
+//
+// 3-PART HEADER (headless):
+//  (1) CONTRACT — every client that hellos as `controller` is welcomed writable,
+//      simultaneously and independently; each writable client may submit, every
+//      connected client (both writers plus a read-only observer) receives the
+//      merged stream of both submissions and the `model_changed` broadcast, and a
+//      client that hellos as `observer` is rejected with error{read_only} when it
+//      tries to drive. ONE blocking dialog fans to EVERY writable client, is
+//      handed to a writable client attaching MID-dialog via
+//      `welcome.pending_dialog`, is settled by the FIRST response with ITS value,
+//      dismisses every peer by id, and ignores a late peer answer. An in-place
+//      session mutation (`navigate_tree`) re-welcomes every viewer onto the
+//      rewound transcript. A late joiner's welcome is COMPLETE: retained display
+//      levels ride in `welcome.snapshot.display` and no display edge follows it.
+//  (2) WHY BROKER/SOCKET-LEVEL, NOT PANE/WINDOW — role admission, dialog fan-out,
+//      re-welcome fan-out and catch-up shape are broker-process and view.sock
+//      contracts, exercised over a pure Unix socket using the production
+//      ViewSocketClient with a real broker process and no tmux pane or window.
+//  (3) HOW THE HEADLESS DRIVE ASSERTS THE CONTRACT — the real socket responses
+//      provide the welcome roles, per-writer relay frames, the read-only
+//      rejection, the fanned dialog frames plus the value and latency recorded in
+//      fake-pi.dialog.jsonl, the second welcome after navigate_tree, and the
+//      welcome payload of a late joiner.
+//
+// One shared broker is booted in before() and reused across every test. There is
+// no writer slot to hand off, so each test simply attaches at the role it wants;
+// afterEach closes the prior sockets, which is also what leaves the broker
+// VIEWERLESS for the display catch-up test.
+import { test, before, after, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { createHeadlessHarness } from '../helpers/harness.js';
+import { isPidAlive } from '../../canvas/pid.js';
+import { createAttachKit, delay, tok, frameHas } from '../helpers/broker-clients.js';
+let h;
+let id; // ONE shared broker, reused across every test (1 real boot)
+const kit = createAttachKit(() => h);
+const { attach, attachUntil } = kit;
+before(async () => {
+    h = await createHeadlessHarness({ sessionPrefix: 'crtr-brkmulti' });
+    const root = h.spawnRoot('broker-attach-multiclient suite root');
+    id = await h.spawnHeadlessChild(root, 'headless worker — multi-client gates');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+afterEach(() => {
+    kit.closeAll();
+});
+const brokerPid = () => h.node(id).pi_pid;
+// Attach a writable client. Every `hello` claiming `controller` is admitted
+// writable — attaching a peer never demotes an already-attached one.
+const writer = async (cid) => {
+    const a = await attach(id, 'controller', cid);
+    assert.equal(a.welcome.role, 'controller', `${cid}: admitted writable, not demoted by an existing peer`);
+    return a;
+};
+const observer = async (cid) => {
+    const a = await attach(id, 'observer', cid);
+    assert.equal(a.welcome.role, 'observer', `${cid}: an observer hello stays read-only`);
+    return a;
+};
+// The broker handles one client's frames in order, so an `ack` for a get_commands
+// sent AFTER some other frame proves that earlier frame was already processed.
+// Used to make "a late peer answer changed nothing" a deterministic assertion
+// instead of a sleep.
+const barrier = async (c, label) => {
+    c.send({ type: 'get_commands' });
+    await c.waitFrame((f) => f.type === 'ack' && f.for === 'get_commands', label);
+};
+const isRequest = (f) => f.type === 'extension_ui_request';
+const dismissFor = (reqId) => (f) => f.type === 'extension_ui_dismiss' && f.id === reqId;
+const welcomes = (frames) => frames.filter((f) => f.type === 'welcome');
+// ---------------------------------------------------------------------------
+// G4 — multi-writer admission + read-only gating + broadcast fan-out. Guards: two
+// simultaneous `controller` hellos are BOTH welcomed writable, each one's own
+// submission reaches the engine, every connected client sees BOTH turns, an
+// explicit observer that tries to drive is rejected with error{read_only}, and a
+// model switch — for which pi emits no AgentSessionEvent at all — reaches EVERY
+// viewer as a `model_changed` frame rather than only acking the requester
+// (observed 2026-06-11: the status bar kept showing the old model).
+// Failure mode: a singleton writer slot demoting the second client, a writer
+// whose prompt is silently dropped, fan-out that misses a viewer, a read-only
+// client that can drive the engine, or a model switch only its requester hears.
+// ---------------------------------------------------------------------------
+test('G4 — two simultaneous clients are both welcomed controller, each submits, all clients see both turns and the model switch; an observer drive → error{read_only}', async () => {
+    const [w1, w2] = await Promise.all([
+        attach(id, 'controller', 'g4-writer-1'),
+        attach(id, 'controller', 'g4-writer-2'),
+    ]);
+    assert.equal(w1.welcome.role, 'controller', 'first client is welcomed writable');
+    assert.equal(w2.welcome.role, 'controller', 'second SIMULTANEOUS client is ALSO welcomed writable (no singleton slot)');
+    const obs = await attach(id, 'observer', 'g4-observer');
+    assert.equal(obs.welcome.role, 'observer', 'an explicit observer hello stays read-only');
+    // A read-only client may not drive the engine — the role is per-client and
+    // fixed by its own hello, so this rejection is independent of who else is
+    // attached.
+    obs.send({ type: 'prompt', text: 'a read-only client must not drive' });
+    const err = await obs.waitFrame((f) => f.type === 'error', 'G4 observer prompt rejected');
+    assert.equal(err.code, 'read_only', 'G4: observer prompt → error{read_only}');
+    // Each writer submits its OWN token. Submissions are sequenced (a prompt sent
+    // mid-stream routes as a steer and produces no second turn), so each turn is
+    // driven to its terminal agent_end before the next writer submits.
+    const tokenA = tok('G4-WRITER-1');
+    w1.send({ type: 'prompt', text: tokenA });
+    await w1.waitFrame((f) => f.type === 'agent_end' && frameHas(f, tokenA), 'G4 writer 1 saw its own turn');
+    const tokenB = tok('G4-WRITER-2');
+    w2.send({ type: 'prompt', text: tokenB });
+    await w2.waitFrame((f) => f.type === 'agent_end' && frameHas(f, tokenB), 'G4 writer 2 saw its own turn');
+    // The merged stream: EVERY connected client — both writers and the read-only
+    // observer — receives BOTH writers' turns.
+    await w2.waitFrame((f) => f.type === 'agent_end' && frameHas(f, tokenA), 'G4 writer 2 ALSO received writer 1 turn');
+    await w1.waitFrame((f) => f.type === 'agent_end' && frameHas(f, tokenB), 'G4 writer 1 ALSO received writer 2 turn');
+    await obs.waitFrame((f) => f.type === 'agent_end' && frameHas(f, tokenA), 'G4 observer received writer 1 turn');
+    await obs.waitFrame((f) => f.type === 'agent_end' && frameHas(f, tokenB), 'G4 observer received writer 2 turn');
+    // A model switch has no AgentSessionEvent to ride: the broker mirrors
+    // snapshot.state.model to every client itself. Pre-fix only the requester's
+    // bare ack existed, so both model_changed waits time out.
+    w1.send({ type: 'set_model', model: 'anthropic/fake-fable' });
+    const ack = await w1.waitFrame((f) => f.type === 'ack' && f.for === 'set_model', 'G4 set_model ack');
+    assert.ok(ack.type === 'ack' && ack.ok, 'G4: set_model acked ok to the requester');
+    const cm = await w1.waitFrame((f) => f.type === 'model_changed', 'G4 requester receives model_changed');
+    assert.ok(cm.type === 'model_changed' && cm.model?.id === 'fake-fable', 'G4: the requester sees the new model id');
+    const om = await obs.waitFrame((f) => f.type === 'model_changed', 'G4 observer receives model_changed');
+    assert.ok(om.type === 'model_changed' && om.model?.id === 'fake-fable', 'G4: a read-only observer ALSO hears the switch');
+});
+// ---------------------------------------------------------------------------
+// G5 — dialog fan-out, mid-dialog handoff, and first-response settlement.
+// Guards: ONE blocking dialog reaches EVERY writable client (never a single
+// owner), a writable client attaching MID-dialog is handed it via
+// welcome.pending_dialog and becomes a full peer in the race to answer, the first
+// answer unblocks the engine with ITS value (not the default), every fanned
+// client gets the correlated extension_ui_dismiss, and a peer answering
+// afterwards is a no-op. An observer is never fanned an answerable dialog.
+// Failure modes: a dialog only one viewer can see (the others sit blind), a
+// late-joining writable viewer blind to an in-flight dialog, peers left holding
+// an overlay nothing can answer, or a late peer answer re-settling a dead dialog.
+// ---------------------------------------------------------------------------
+test('G5 — one dialog fans out to every writable client and to a mid-dialog joiner, the first response settles it, all are dismissed, and a late peer response is a no-op', async () => {
+    const base = h.dialogResults(id).length;
+    const a = await writer('g5-A');
+    const b = await writer('g5-B');
+    const obs = await observer('g5-obs'); // must never be fanned an answerable dialog
+    h.fakeCmd(id, { cmd: 'dialog', timeout: 30_000 }); // generous: a writable client answers first
+    const reqA = await a.waitFrame(isRequest, 'G5 dialog fanned out to writable A');
+    const reqB = await b.waitFrame(isRequest, 'G5 dialog fanned out to writable B');
+    const reqId = reqA.id;
+    assert.equal(reqB.id, reqId, 'G5: both writable clients were fanned the SAME dialog id, not two dialogs');
+    assert.equal(reqA.method, 'confirm', 'G5: the fanned dialog is the confirm() the engine raised');
+    // A writable client attaching MID-dialog is handed the pending dialog in its
+    // welcome (retry covers the beat between the raise and this attach); an
+    // observer attaching mid-dialog is not.
+    assert.equal(obs.welcome.pending_dialog, null, 'G5: an observer welcome never carries a pending dialog');
+    const late = await attachUntil(id, 'controller', 'g5-late', (x) => x.welcome.role === 'controller' && x.welcome.pending_dialog != null, 'G5 writable client attaches mid-dialog and is handed the pending dialog');
+    assert.equal(late.welcome.pending_dialog.id, reqId, 'G5: welcome.pending_dialog is the SAME dialog the peers hold');
+    assert.equal(late.welcome.pending_dialog.method, 'confirm', 'G5: the pending dialog is the confirm()');
+    // The mid-dialog joiner answers FIRST — the engine must proceed with its true,
+    // not the false default.
+    late.send({ type: 'extension_ui_response', id: reqId, confirmed: true });
+    await late.waitFrame(dismissFor(reqId), 'G5 answerer receives the correlated dismiss');
+    await a.waitFrame(dismissFor(reqId), 'G5 peer A receives the correlated dismiss for the dialog it never answered');
+    await b.waitFrame(dismissFor(reqId), 'G5 peer B receives the correlated dismiss for the dialog it never answered');
+    const results = await h.waitFor(() => (h.dialogResults(id).length > base ? h.dialogResults(id) : null), { label: 'G5 dialog settled by the first response', timeoutMs: 15_000 });
+    assert.equal(results[base].resolved, true, 'G5: the engine proceeded with the first answer (true), not the default (false)');
+    // The observer was attached the whole time: it saw the broadcast dismiss but was
+    // never handed the answerable request.
+    await obs.waitFrame(dismissFor(reqId), 'G5 observer sees the broadcast dismiss (ordering barrier)');
+    assert.equal(obs.frames.filter(isRequest).length, 0, 'G5: an observer is never fanned an answerable dialog');
+    // B answers the already-settled dialog. The broker deleted the entry on the first
+    // response, so this finds nothing and is a silent no-op: no second engine
+    // resolution, and the recorded answer stays the first answerer's.
+    b.send({ type: 'extension_ui_response', id: reqId, confirmed: false });
+    await barrier(b, 'G5 broker processed B late response (ordered ack)');
+    const settled = h.dialogResults(id);
+    assert.equal(settled.length, base + 1, 'G5: the late peer response resolved nothing — no second dialog entry');
+    assert.equal(settled[base].resolved, true, "G5: the late peer response did not overwrite the first answerer's value");
+    assert.equal(isPidAlive(brokerPid()), true, 'G5: the late no-op response did not fault the broker');
+});
+// ---------------------------------------------------------------------------
+// G9 — re-welcome after an IN-PLACE session mutation (real bug, observed
+// 2026-06-11 in `crtr surface attach`: double-Esc/`/tree` opened the session-tree
+// picker, but SELECTING an entry visibly did nothing). session.navigateTree()
+// rewinds in place — same session file, new leaf, NO relayed AgentSessionEvent —
+// so unlike the session-REPLACING ops (new_session/switch_session/fork →
+// runReplacement → reWelcomeAll) the handler used to only ack, leaving every
+// attached client rendering the abandoned branch and dropping the navigated-to
+// user message's editorText. Failure mode: no second welcome arrives at all, or
+// the re-welcome serves a stale snapshot.
+// ---------------------------------------------------------------------------
+test('G9 — navigate_tree re-welcomes every viewer onto the rewound transcript and acks the editor text', async () => {
+    const c = await writer('nav-ctrl');
+    // 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), 'G9 turn relayed before navigate');
+    // The observer attaches AFTER the turn so its first welcome deterministically
+    // holds the token (the pre-navigate baseline).
+    const o = await attachUntil(id, 'observer', 'nav-obs', (a) => frameHas(a.welcome, token), 'G9 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', 'G9 navigate_tree ack');
+    assert.ok(ack.type === 'ack' && ack.ok, 'G9: navigate_tree acked ok');
+    assert.equal(ack.type === 'ack' ? ack.detail : undefined, 'rewound-to:entry-x', 'G9: 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: 'G9 controller re-welcomed' });
+    await h.waitFor(() => (welcomes(o.frames).length >= 2 ? true : null), { label: 'G9 observer re-welcomed' });
+    // 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), 'G9: pre-navigate welcome holds the turn');
+    assert.ok(!frameHas(second, token), 'G9: re-welcome serves the rewound transcript (turn dropped)');
+    assert.equal(second.snapshot.messages.length, first.snapshot.messages.length - 2, 'G9: re-welcome history is exactly one turn shorter (a turn = user + assistant = 2 tree messages)');
+});
+// ---------------------------------------------------------------------------
+// G10 — catch-up is ONE atomic frame. `ctx.ui.setStatus/setWidget/setTitle` are
+// LEVELS with no pi getter, so the broker is their only holder; it ships that
+// held state as `welcome.snapshot.display` and sends NO display edge after the
+// welcome, so a late joiner renders complete chrome on its FIRST paint. Painting
+// here happens with ZERO viewers attached (afterEach closed the previous test's
+// clients), so only retention can carry it. Pre-2026-07-24 `sendWelcome`
+// re-emitted N synthetic display frames after the snapshot: catch-up was
+// non-atomic and the viewer had to clear-and-rebuild, painting blank chrome in
+// the gap. Both halves of that cut fail this test.
+// ---------------------------------------------------------------------------
+test('G10 — retained extension display state rides IN welcome.snapshot.display, and no display edge follows the welcome', async () => {
+    const DISPLAY_METHODS = new Set(['setStatus', 'setWidget', 'setTitle']);
+    const isDisplayFrame = (f) => f.type === 'extension_ui_request' && f.method !== undefined && DISPLAY_METHODS.has(f.method);
+    h.fakeCmd(id, { cmd: 'display', text: 'crtr-brief', reason: 'painted while detached' });
+    const a = await attachUntil(id, 'observer', 'g10-late-joiner', (at) => at.welcome.snapshot.display?.statuses['crtr-brief'] !== undefined, 'G10 welcome.snapshot.display carries the retained status');
+    const display = a.welcome.snapshot.display;
+    assert.equal(display.statuses['crtr-brief'], 'painted while detached', 'G10: setStatus level survived in the snapshot');
+    assert.deepEqual(display.widgets['crtr-brief'], { lines: ['painted while detached'], placement: 'aboveEditor' }, 'G10: setWidget level survived in the snapshot, placement included');
+    assert.equal(display.title, 'painted while detached', 'G10: setTitle level survived in the snapshot');
+    // Atomicity: the welcome is COMPLETE. Give the broker a generous beat to emit a
+    // replay it must not emit, then assert nothing display-shaped arrived at all.
+    await delay(500);
+    assert.deepEqual(a.frames.filter((f) => isDisplayFrame(f)).map((f) => f.method), [], 'G10: catch-up is the welcome alone — no synthetic display edges replayed after it');
+    // A LIVE paint still arrives as an edge frame: the snapshot replaces the replay,
+    // not the ongoing relay.
+    h.fakeCmd(id, { cmd: 'display', text: 'crtr-live', reason: 'painted while attached' });
+    const live = (await a.waitFrame((f) => f.type === 'extension_ui_request' && f.statusKey === 'crtr-live', 'G10 a live setStatus still relays as an extension_ui_request edge'));
+    assert.equal(live.method, 'setStatus');
+    assert.equal(live.statusText, 'painted while attached');
+});