@crouton-kit/crouter 0.3.19 → 0.3.21

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

@@ -103,8 +103,9 @@ test('cascade close: middle-node close reaps EXACTLY its subtree (canceled), anc
         // ===================================================================
         const closeRes = h.cli(A, ['node', 'close', '--node', B]);
         assert.equal(closeRes.code, 0, `node close exit 0\n${closeRes.stderr}`);
-        // The CLI's own rendered report: cascade root B, exactly 4 closed, 0 spared.
-        assert.match(closeRes.stdout, new RegExp(`<closed id="${B}" count="4" spared="0"\\s*/>`), `close report names B as root, count=4, spared=0\n${closeRes.stdout}`);
+        // The CLI's own rendered report (plain markdown): cascade root B, exactly
+        // 4 closed, 0 spared (no spared clause is emitted when none were spared).
+        assert.match(closeRes.stdout, new RegExp(`^Closed ${B} and its exclusive subtree — 4 node\\(s\\) closed\\.`), `close report names B as root, count=4, spared=0\n${closeRes.stdout}`);
         // ===================================================================
         // ASSERT 1 — the A5 DELIVERABLE: the EXACT terminal status of every
         // cascade-reaped node. CURRENT behavior: status='canceled', intent=null,

package/dist/core/__tests__/context-intro.test.js

@@ -1,10 +1,8 @@
 // Tests for the <crtr-context> bearings preamble:
 //   1. Worker and orchestrator bearings carry the `## References` block
-//      (substrate reference docs + node-local docs as `###` sub-sections) in
-//      place of the removed `<memory>` block — no `label · dir` stanzas, no
-//      `(empty)` markers, no MEMORY.md index inlining. Orchestrators add the
-//      across-cycles framing; promotion delivers that same orchestrator
-//      context-dir framing to a node that spawned base.
+//      (substrate reference docs + node-local docs as `###` sub-sections).
+//      Orchestrators add the across-cycles framing; promotion delivers that
+//      same orchestrator context-dir framing to a node that spawned base.
 //   2. canvas-context-intro injects the block as its own session message at
 //      session_start (before the first prompt), idempotent across resumes.
 //
@@ -36,53 +34,51 @@ after(() => {
     delete process.env['CRTR_HOME'];
     delete process.env['CRTR_NODE_ID'];
 });
-test('worker bearings: base framing + ## References block (no <memory>, no label·dir stanzas), NO across-cycles framing', () => {
-    // Bug-regression: review finding M1 — buildContextBearings was changed from
-    // buildMemoryBlock (<memory> + label·dir per-store stanzas) to
-    // renderReferencesBlock (## References + ### <name> sub-sections). This test
-    // locks in the new contract.
+test('worker bearings: base framing + ## References block, NO across-cycles framing', () => {
+    // Bug-regression: review finding M1 — buildContextBearings renders the
+    // ## References block (renderReferencesBlock): ## References + ### <name>
+    // sub-sections. This test locks in that contract.
     const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
     // Seed a node-local substrate doc so the ## References block is non-empty.
     const dir = memoryDir(meta.node_id);
     mkdirSync(dir, { recursive: true });
-    writeFileSync(join(dir, 'test-ref.md'), '---\nkind: reference\nwhen: when testing\nwhy: regression fixture\nsystem-prompt-visibility: preview\n---\nTest body.\n');
+    writeFileSync(join(dir, 'test-ref.md'), '---\nkind: reference\nwhen-and-why-to-read: When testing, this reference should be read because it is a regression fixture\nsystem-prompt-visibility: preview\n---\nTest body.\n');
     const block = buildContextIntro(meta.node_id);
     assert.match(block, new RegExp(`<crtr-context dir="${contextDir(meta.node_id)}">`));
     assert.match(block, /shared document store, not a task tracker/, 'base = shared docs, not tasks');
-    // New contract: NO <memory> block — replaced by ## References.
+    // Reference content renders ONLY as ## References + ### sub-sections.
     assert.doesNotMatch(block, /<memory>/, 'no <memory> block');
-    // New contract: NO label·dir stanza headers (the removed per-store format).
+    // Per-store stanza headers (label · dir) never appear.
     assert.doesNotMatch(block, /user-global · /, 'no user-global label·dir stanza');
     assert.doesNotMatch(block, /node-local · /, 'no node-local label·dir stanza');
-    // New contract: NO (empty) placeholder (the removed empty-store marker).
+    // No (empty) placeholder marker.
     assert.doesNotMatch(block, /\(empty\)/, 'no (empty) placeholder');
-    // Reference content renders as ## References + ### sub-sections — no other shape.
     assert.match(block, /## References\n\n###/, '## References followed by ### sub-sections');
     // A terminal worker must NOT carry the orchestrator across-cycles framing.
     assert.doesNotMatch(block, /refresh cycles/, 'no across-cycles framing for a terminal worker');
     assert.match(block, /<\/crtr-context>/);
 });
-test('orchestrator bearings: across-cycles framing + node-local substrate docs ride into ## References; the MEMORY.md index never renders', () => {
-    // Bug-regression: review finding M1 — buildContextBearings replaced the old
-    // <memory> pointer-line block with ## References. Node-local substrate docs
-    // render as ### sub-sections at their rung; the old index file never surfaces.
+test('orchestrator bearings: across-cycles framing + node-local substrate docs ride into ## References; a non-substrate .md file is never inlined', () => {
+    // Bug-regression: review finding M1 — buildContextBearings renders ## References.
+    // Node-local substrate docs render as ### sub-sections at their rung; a
+    // non-substrate .md file (no frontmatter `kind`) never surfaces.
     const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
     promote(meta.node_id); // flip to orchestrator mode — the across-cycles gate
     const dir = memoryDir(meta.node_id);
     mkdirSync(dir, { recursive: true });
-    // Write a MEMORY.md file to verify it is never surfaced in the block.
+    // Write a non-substrate MEMORY.md file to verify it is never surfaced in the block.
     const legacyIndexPath = join(dir, 'MEMORY.md');
     writeFileSync(legacyIndexPath, '# memory index — one pointer line per memory; how-to in "Your long-term memory".\n\n- [Flaky build](flaky-build.md) — first run fails\n');
     // A node-local substrate doc DOES ride into ## References at its rung.
-    writeFileSync(join(dir, 'flaky-build.md'), '---\nkind: reference\nwhen: when the build flakes\nwhy: first run fails\nsystem-prompt-visibility: preview\n---\nFirst run always fails; rerun once.\n');
+    writeFileSync(join(dir, 'flaky-build.md'), '---\nkind: reference\nwhen-and-why-to-read: When the build flakes, this reference should be read because the first run fails\nsystem-prompt-visibility: preview\n---\nFirst run always fails; rerun once.\n');
     const block = buildContextIntro(meta.node_id);
     assert.match(block, /shared document store, not a task tracker/, 'still carries the base framing');
     assert.match(block, /refresh cycles/, 'orchestrator gets the across-cycles framing');
     assert.doesNotMatch(block, /<memory>/, 'no <memory> block');
     assert.match(block, /## References\n/, 'references block present');
     assert.match(block, /### flaky-build\n/, 'node-local doc gets its ### sub-section');
-    assert.match(block, /when the build flakes, read this reference\. first run fails\./, 'preview rung renders the routing line');
-    // The index file itself never renders: no header comment, no pointer line, no path.
+    assert.match(block, /When the build flakes, this reference should be read because the first run fails\./, 'preview rung renders the routing line');
+    // The non-substrate file never renders: no header line, no pointer line, no path.
     assert.ok(!block.includes('# memory index'), 'the index header comment is NOT inlined');
     assert.ok(!block.includes('- [Flaky build](flaky-build.md)'), 'index pointer lines are NOT inlined');
     assert.ok(!block.includes(legacyIndexPath), 'no absolute index (MEMORY.md) path');
@@ -90,9 +86,9 @@ test('orchestrator bearings: across-cycles framing + node-local substrate docs r
     assert.match(block, /<\/crtr-context>/);
 });
 test('orchestrator bearings: no per-store stanzas or (empty) markers; a rung-none node-local doc still surfaces as a ### title stub', () => {
-    // Bug-regression: review findings M1 + M6 — the three-store `label · dir`
-    // stanzas and (empty) markers are gone, and node-local docs are NOT filtered
-    // on rung: a migrated node-local reference defaults
+    // Bug-regression: review findings M1 + M6 — the ## References block carries no
+    // per-store `label · dir` stanzas or (empty) markers, and node-local docs are
+    // NOT filtered on rung: a migrated node-local reference defaults
     // system-prompt-visibility: none and must still ride into ## References as
     // its bare title (never its body).
     const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
@@ -101,7 +97,7 @@ test('orchestrator bearings: no per-store stanzas or (empty) markers; a rung-non
     mkdirSync(dir, { recursive: true });
     writeFileSync(join(dir, 'rung-none-fact.md'), '---\nkind: reference\n---\nbody that must not render at the none rung\n');
     const block = buildContextIntro(meta.node_id);
-    // No per-store stanza headers, no (empty) markers, no index paths.
+    // No per-store stanza headers, no (empty) markers, no MEMORY.md paths.
     assert.ok(!block.includes(`node-local · ${memoryDir(meta.node_id)}`), 'no node-local stanza header');
     assert.ok(!block.includes('user-global · '), 'no user-global stanza header');
     assert.ok(!block.includes('project · '), 'no project stanza header');

package/dist/core/__tests__/detach-focus.test.js

@@ -109,7 +109,7 @@ test('node demote --detach on a FOCUSED node: flips terminal, relocates the pane
         //     breaks the pane back into h.session.
         const res = h.cli(B, ['node', 'demote', '--node', B, '--pane', bPane, '--detach']);
         assert.equal(res.code, 0, `node demote --detach exit 0\n${res.stderr}`);
-        assert.match(res.stdout, /detached="true"/, `the agent was detached\n${res.stdout}`);
+        assert.match(res.stdout, /relocated to the background/, `the agent was detached\n${res.stdout}`);
         closeDb();
         const b = getNode(B);
         // (a) lifecycle flipped to terminal IN PLACE.
@@ -180,7 +180,7 @@ test('node demote --detach on a NON-GENERATING focused node: RELEASES to dormant
         // --- Drive the REAL verb on the non-generating focused node.
         const res = h.cli(B, ['node', 'demote', '--node', B, '--pane', bPane, '--detach']);
         assert.equal(res.code, 0, `node demote --detach exit 0\n${res.stderr}`);
-        assert.match(res.stdout, /detached="true"/, `the agent was detached\n${res.stdout}`);
+        assert.match(res.stdout, /relocated to the background/, `the agent was detached\n${res.stdout}`);
         closeDb();
         const b = getNode(B);
         // (b) RELEASED to dormant — idle + intent='idle-release' (revivable via inbox

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 {};