@crouton-kit/crouter 0.3.19 → 0.3.21

package/dist/commands/node.js

@@ -119,6 +119,7 @@ const nodeNew = defineLeaf({
             { kind: 'flag', name: 'root', type: 'bool', required: false, constraint: 'Spawn an INDEPENDENT root instead of a managed child: no parent (top-level on the canvas), NO subscription back to you (you are NOT woken by it), resident lifecycle. It records spawned_by=you for provenance and is brought forefront so it can be driven directly. Use for a node you hand off and do not manage (e.g. a sub-orchestrator a human will discuss with).' },
             { kind: 'flag', name: 'fork-from', type: 'string', required: false, constraint: 'FORK the new node from an existing pi conversation instead of starting it fresh: pass a node id (forks from that node\'s session), an absolute session `.jsonl` path, or a partial pi session uuid. pi copies that whole history into a NEW session for the child (the source is untouched), then the prompt is delivered as the next message — i.e. the child wakes up as a continuation of that conversation. Use to branch exploratory work off a node that already built up the context you need, instead of re-deriving it. One-shot at birth: the fork resumes its own session thereafter.' },
             { kind: 'flag', name: 'headless', type: 'bool', required: false, constraint: 'Spawn the node on the HEADLESS broker host (no tmux pane) instead of a tmux window. Overrides the `headless` config default for this spawn; omit to use that default (which itself defaults to a tmux pane).' },
+            { kind: 'flag', name: 'model', type: 'enum', choices: ['ultra', 'strong', 'medium', 'light'], required: false, constraint: 'Override the model the node runs on, by capability TIER: ultra (frontier), strong (opus), medium (sonnet), light (haiku). Omit to use the kind\'s persona default (explore=light, every other kind=strong). The override is durable — it survives revives and polymorphs (promote/demote).' },
         ],
         output: [
             { name: 'node_id', type: 'string', required: true, constraint: 'The new node id.' },
@@ -148,9 +149,10 @@ const nodeNew = defineLeaf({
         const parent = input['parent'];
         const root = input['root'] === true;
         const forkFrom = input['forkFrom'];
+        const model = input['model'];
         // Host precedence: explicit --headless flag > config `headless` default > tmux.
         const hostKind = input['headless'] === true ? 'broker' : readConfig('user').headless === true ? 'broker' : 'tmux';
-        const res = spawnChild({ kind, mode, cwd, name, prompt, parent, root, forkFrom, hostKind });
+        const res = spawnChild({ kind, mode, cwd, name, prompt, parent, root, forkFrom, hostKind, model });
         return {
             node_id: res.node.node_id,
             name: res.node.name,
@@ -162,7 +164,14 @@ const nodeNew = defineLeaf({
                 : childFollowUp(parent ?? process.env['CRTR_NODE_ID']),
         };
     },
-    render: (r) => `<spawned name="${r['name']}" id="${r['node_id']}" status="${r['status']}">\n${r['follow_up']}\n</spawned>`,
+    render: (r) => {
+        const win = r['window'] ? ` in window ${r['window']}` : '';
+        const lines = [`Spawned "${r['name']}" (${r['node_id']}) — ${r['status']}${win}.`];
+        if (r['session'])
+            lines.push(`- session: ${r['session']}`);
+        lines.push('', String(r['follow_up']));
+        return lines.join('\n');
+    },
 });
 // ---------------------------------------------------------------------------
 // node list — the active canvas (or a status slice)
@@ -350,9 +359,16 @@ const nodeRecycle = defineLeaf({
         const res = await recycleNode(id, pane);
         return { recycled: res.recycled, node_id: id, finalized: res.finalized, delivered: res.delivered.length, new_root: res.newRoot ?? undefined };
     },
-    render: (r) => r['recycled'] === true
-        ? `<recycled id="${r['node_id']}" finalized="${r['finalized']}" delivered="${r['delivered']}" new_root="${r['new_root'] ?? ''}"/>`
-        : `<recycle-failed id="${r['node_id'] ?? ''}">not in tmux, or no agent in this pane</recycle-failed>`,
+    render: (r) => {
+        if (r['recycled'] !== true)
+            return `Recycle failed for ${r['node_id'] ?? '?'} — not in tmux, or no agent in this pane.`;
+        const lines = [`Recycled the pane — finished ${r['node_id']}.`, `- finalized: ${r['finalized']}`];
+        if (r['finalized'] === true)
+            lines.push(`- delivered: ${r['delivered']}`);
+        if (r['new_root'])
+            lines.push(`- new root: ${r['new_root']}`);
+        return lines.join('\n');
+    },
 });
 // ---------------------------------------------------------------------------
 // node close — close a node + cascade-cancel its exclusive subtree (Alt+C → x)
@@ -396,9 +412,12 @@ const nodeClose = defineLeaf({
         const res = closeNode(id);
         return { closed: true, node_id: res.root, count: res.closed.length, closed_ids: res.closed, spared: res.spared };
     },
-    render: (r) => r['closed'] === true
-        ? `<closed id="${r['node_id']}" count="${r['count']}" spared="${r['spared']?.length ?? 0}"/>`
-        : `<close-failed/>`,
+    render: (r) => {
+        if (r['closed'] !== true)
+            return 'Close failed — no node found in this pane to close.';
+        const spared = r['spared']?.length ?? 0;
+        return `Closed ${r['node_id']} and its exclusive subtree — ${r['count']} node(s) closed${spared > 0 ? `, ${spared} spared (still managed from outside the subtree)` : ''}.`;
+    },
 });
 // ---------------------------------------------------------------------------
 // node cycle — DFS-walk the canvas one window at a time (Alt+] / Alt+[)
@@ -484,8 +503,8 @@ const nodeCycle = defineLeaf({
         return { focused: res.focused, node_id: targetId, name: target.name, from: fromId };
     },
     render: (r) => r['focused'] === true
-        ? `<cycled to="${r['node_id']}" name="${r['name'] ?? ''}" from="${r['from'] ?? ''}"/>`
-        : `<cycle-noop>no other live node to focus</cycle-noop>`,
+        ? `Cycled to "${r['name'] ?? ''}" (${r['node_id']}) — from ${r['from'] ?? '?'}.`
+        : 'No other live node to focus.',
 });
 // ---------------------------------------------------------------------------
 // node msg — direct-address any node at a wake tier (wakes a dormant target)
@@ -580,7 +599,7 @@ const nodeSubscribe = defineLeaf({
         subscribe(subscriber, publisher, !passive);
         return { subscribed: true, subscriber, publisher, mode: passive ? 'passive' : 'active' };
     },
-    render: (r) => `<subscribed subscriber="${r['subscriber']}" publisher="${r['publisher']}" mode="${r['mode']}"/>`,
+    render: (r) => `Subscribed ${r['subscriber']} → ${r['publisher']} (${r['mode']}).`,
 });
 const nodeUnsubscribe = defineLeaf({
     name: 'unsubscribe',
@@ -607,7 +626,7 @@ const nodeUnsubscribe = defineLeaf({
         unsubscribe(subscriber, publisher);
         return { unsubscribed: true, subscriber, publisher };
     },
-    render: (r) => `<unsubscribed subscriber="${r['subscriber']}" publisher="${r['publisher']}"/>`,
+    render: (r) => `Unsubscribed ${r['subscriber']} from ${r['publisher']}.`,
 });
 // ---------------------------------------------------------------------------
 // node promote — become an orchestrator (the worker→orchestrator polymorph)
@@ -682,6 +701,7 @@ function setLifecycle(id, value, opts) {
     const { launch } = buildLaunchSpec(target.kind, target.mode, {
         lifecycle: value,
         hasManager: target.parent !== null,
+        model: target.model_override ?? undefined,
     });
     const meta = updateNode(id, { lifecycle: value, launch });
     // --detach: shove the still-running agent into the background crtr session,
@@ -725,7 +745,7 @@ const nodeDemote = defineLeaf({
         const res = setLifecycle(id, 'terminal', { pane, detach: input['detach'] === true });
         return { node_id: res.node_id, lifecycle: res.lifecycle, detached: res.detached };
     },
-    render: (r) => `<demoted node="${r['node_id']}" lifecycle="${r['lifecycle']}"${r['detached'] === true ? ' detached="true"' : ''}/>`,
+    render: (r) => `Demoted ${r['node_id']} — lifecycle now ${r['lifecycle']} (in place)${r['detached'] === true ? ', relocated to the background crtr session' : ''}.`,
 });
 // ---------------------------------------------------------------------------
 // node lifecycle — flip the lifecycle axis (terminal ↔ resident), independent
@@ -762,7 +782,7 @@ const nodeLifecycle = defineLeaf({
         const res = setLifecycle(id, value, { pane, detach: input['detach'] === true });
         return { node_id: res.node_id, lifecycle: res.lifecycle, detached: res.detached };
     },
-    render: (r) => `<lifecycle node="${r['node_id']}" set="${r['lifecycle']}"${r['detached'] === true ? ' detached="true"' : ''}/>`,
+    render: (r) => `Set ${r['node_id']} lifecycle → ${r['lifecycle']}${r['detached'] === true ? ', relocated to the background crtr session' : ''}.`,
 });
 // ---------------------------------------------------------------------------
 // node yield — refresh: discard context, revive fresh against the roadmap
@@ -905,10 +925,6 @@ function etaHint(fireAt, now) {
         return ` (~${hrs}h)`;
     return ` (~${Math.round(ms / 86_400_000)}d)`;
 }
-/** Escape a value for a rendered XML attribute (list rows carry free-text notes). */
-function xmlAttr(s) {
-    return s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-}
 // node wake at ---------------------------------------------------------------
 const nodeWakeAt = defineLeaf({
     name: 'at',
@@ -1008,7 +1024,10 @@ const nodeWakeAt = defineLeaf({
                 : `Bare self-alarm armed. You wake in a fresh window at ${fireAt}${eta}. End your turn now to go dormant; do not push final. The wake re-reads your roadmap.`;
         return { id, kind, fires_at: fireAt, recur: cadenceDisplay(recur), target, guidance };
     },
-    render: (r) => `<wake-armed id="${r['id']}" kind="${r['kind']}" fires-at="${r['fires_at']}" recur="${r['recur']}" target="${r['target']}">\n${r['guidance']}\n</wake-armed>`,
+    render: (r) => {
+        const recur = r['recur'] !== 'none' ? `, recurs ${r['recur']}` : '';
+        return `Armed ${r['kind']} wake ${r['id']} — fires ${r['fires_at']}${recur}, target ${r['target']}.\n\n${r['guidance']}`;
+    },
 });
 // node wake until ------------------------------------------------------------
 const nodeWakeUntil = defineLeaf({
@@ -1060,7 +1079,7 @@ const nodeWakeUntil = defineLeaf({
         const guidance = `Deadline armed. You wake on the first inbox message, or at ${w.fireAt}${eta} if none arrives. Now delegate / end your turn to go dormant — whichever fires first cancels the other.`;
         return { id, fires_at: w.fireAt, target: 'self', guidance };
     },
-    render: (r) => `<deadline-armed id="${r['id']}" fires-at="${r['fires_at']}" target="${r['target']}">\n${r['guidance']}\n</deadline-armed>`,
+    render: (r) => `Armed deadline ${r['id']} — fires ${r['fires_at']}, target ${r['target']}.\n\n${r['guidance']}`,
 });
 // node wake spawn -----------------------------------------------------------
 const nodeWakeSpawn = defineLeaf({
@@ -1161,7 +1180,10 @@ const nodeWakeSpawn = defineLeaf({
             : `Deferred spawn armed: a fresh ${kind} node is born at ${fireAt}${eta}. No node exists yet — inspect/cancel via \`crtr node wake list\` / \`crtr node wake cancel ${id}\`. Pick up other work or end your turn.`;
         return { id, kind, fires_at: fireAt, recur: cadenceDisplay(recur), guidance };
     },
-    render: (r) => `<spawn-deferred id="${r['id']}" kind="${r['kind']}" fires-at="${r['fires_at']}" recur="${r['recur']}">\n${r['guidance']}\n</spawn-deferred>`,
+    render: (r) => {
+        const recur = r['recur'] !== 'none' ? `, recurs ${r['recur']}` : '';
+        return `Armed deferred spawn ${r['id']} — a ${r['kind']} node, fires ${r['fires_at']}${recur}.\n\n${r['guidance']}`;
+    },
 });
 // node wake list -------------------------------------------------------------
 const nodeWakeList = defineLeaf({
@@ -1243,10 +1265,13 @@ const nodeWakeList = defineLeaf({
     },
     render: (r) => {
         const wakes = r['wakes'];
-        const rows = wakes.map((w) => `  <wake id="${w['id']}" kind="${w['kind']}" next="${w['next']}" recur="${xmlAttr(String(w['recur']))}" target="${xmlAttr(String(w['target']))}" owner="${xmlAttr(String(w['owner']))}" note="${xmlAttr(String(w['note']))}"/>`);
-        const body = rows.length > 0 ? '\n' + rows.join('\n') + '\n' : '\n';
-        return (`<wakes scope="${xmlAttr(String(r['scope']))}" count="${wakes.length}">${body}</wakes>\n` +
-            '<follow_up>Cancel one with `crtr node wake cancel <id>`. Fired one-shots are gone; a recurrence shows its NEXT fire, not past slots.</follow_up>');
+        const follow = 'Cancel one with `crtr node wake cancel <id>`. Fired one-shots are gone; a recurrence shows its NEXT fire, not past slots.';
+        if (wakes.length === 0)
+            return `No pending wakes in scope ${r['scope']}.\n\n${follow}`;
+        const cell = (v) => String(v).replace(/\|/g, '\\|').replace(/\n/g, ' ');
+        const head = '| id | kind | next | recur | target | owner | note |\n| --- | --- | --- | --- | --- | --- | --- |';
+        const rows = wakes.map((w) => `| ${cell(w['id'])} | ${cell(w['kind'])} | ${cell(w['next'])} | ${cell(w['recur'])} | ${cell(w['target'])} | ${cell(w['owner'])} | ${cell(w['note'])} |`);
+        return `${wakes.length} pending wake(s) in scope ${r['scope']}.\n\n${head}\n${rows.join('\n')}\n\n${follow}`;
     },
 });
 // node wake cancel -----------------------------------------------------------
@@ -1273,7 +1298,7 @@ const nodeWakeCancel = defineLeaf({
         cancelWake(id);
         return { id, was_pending: wasPending };
     },
-    render: (r) => `<wake-canceled id="${r['id']}" was-pending="${r['was_pending']}"/>`,
+    render: (r) => `Canceled wake ${r['id']}${r['was_pending'] === true ? '' : ' (already gone — no-op)'}.`,
 });
 // node wake (branch) ---------------------------------------------------------
 const nodeWake = defineBranch({

package/dist/commands/push.js

@@ -112,7 +112,7 @@ function makeTierLeaf(tier) {
                 : tier === 'urgent'
                     ? `Urgent report fanned to ${n} subscriber(s) — they are force-woken.`
                     : `Progress report fanned to ${n} subscriber(s).`;
-            return `<pushed tier="${tier}" status="${r['status']}" delivered="${n}">\n${line}\nreport: ${r['report_path']}\n</pushed>`;
+            return `${line}\n\n- report: ${r['report_path']}`;
         },
     });
 }
@@ -161,16 +161,16 @@ const feedReadLeaf = defineLeaf({
         const n = Array.isArray(r['entries']) ? r['entries'].length : 0;
         const rawDigest = typeof r['digest'] === 'string' ? r['digest'] : '';
         if (n > 0 && rawDigest.trim() !== '') {
-            return `<feed node="${r['node_id']}" unread="${n}">\n${rawDigest}\n</feed>`;
+            return `${n} unread pointer${n === 1 ? '' : 's'} drained from ${r['node_id']}'s inbox.\n\n${rawDigest.trim()}`;
         }
         // Empty drain has two distinct causes — say which, honestly. An inbox that
         // already holds entries was drained when the watcher woke you (the wake
         // message WAS that digest); a never-used inbox simply has nothing yet.
         const total = typeof r['inbox_total'] === 'number' ? r['inbox_total'] : 0;
-        const digest = total > 0
-            ? 'Nothing unread — but your inbox is not empty. The watcher drains your inbox to wake you, so the entries you already saw in your wake message are the same ones you would read here; that is why this is empty. Re-read the whole history (full message bodies included) with `crtr feed read --all`, or dereference the refs from the wake digest you already have.'
-            : 'Inbox empty — nothing has arrived from your subscriptions yet. Expected while workers run: a worker that has not pushed yet leaves no pointer, and it will wake you the moment it does. The wake is automatic — just continue your own work or end your turn. (Reach for `crtr feed peek` only if you suspect a worker died, not to confirm a live one.)';
-        return `<feed node="${r['node_id']}" unread="${n}">\n${digest}\n</feed>`;
+        const explanation = total > 0
+            ? 'Your inbox is not empty, though. The watcher drains your inbox to wake you, so the entries you already saw in your wake message are the same ones you would read here; that is why this is empty. Re-read the whole history (full message bodies included) with `crtr feed read --all`, or dereference the refs from the wake digest you already have.'
+            : 'Your inbox is empty — nothing has arrived from your subscriptions yet. Expected while workers run: a worker that has not pushed yet leaves no pointer, and it will wake you the moment it does. The wake is automatic — just continue your own work or end your turn. (Reach for `crtr feed peek` only if you suspect a worker died, not to confirm a live one.)';
+        return `No unread pointers for ${r['node_id']} (unread=0).\n\n${explanation}`;
     },
 });
 // ---------------------------------------------------------------------------
@@ -249,28 +249,23 @@ const feedPeekLeaf = defineLeaf({
             const tail = unread > 0
                 ? `${unread} unread report${unread === 1 ? '' : 's'} sit in your inbox — run \`crtr feed read\` to absorb ${unread === 1 ? 'it' : 'them'}.`
                 : 'If you spawned workers, they have finished and detached, or you never subscribed. Nothing will wake you.';
-            return `<peek node="${id}" subscriptions="0" unread="${unread}" verdict="empty">\nNo nodes below you. ${tail}\n</peek>`;
+            return `No nodes below you (0 subscriptions, ${unread} unread). ${tail}`;
         }
         const working = kids.filter((k) => k.status === 'active' || k.status === 'idle');
         const liveWaking = working.filter((k) => k.active); // active sub to a live node = it will wake me
         const done = kids.filter((k) => k.status === 'done' || k.status === 'canceled');
         const dead = kids.filter((k) => k.status === 'dead');
-        let verdict;
         let line;
         if (dead.length > 0) {
-            verdict = 'attention';
             line = `\u26a0 ${dead.length} below you ${dead.length === 1 ? 'is' : 'are'} dead and will NOT wake you. Inspect with \`crtr node inspect show <id>\`, then re-delegate or proceed without ${dead.length === 1 ? 'it' : 'them'}.`;
         }
         else if (liveWaking.length > 0) {
-            verdict = 'working';
             line = `Safe to yield \u2014 ${liveWaking.length} worker${liveWaking.length === 1 ? '' : 's'} running async will wake you on the next push. Nothing to do now; end your turn and chill.`;
         }
         else if (unread > 0) {
-            verdict = 'ready';
             line = `Nothing still running, but ${unread} unread report${unread === 1 ? '' : 's'} \u2014 run \`crtr feed read\` to absorb ${unread === 1 ? 'it' : 'them'}, then continue or finish.`;
         }
         else {
-            verdict = 'idle';
             line = 'Everything below you has finished and been drained \u2014 nothing is running. Continue your own work, or `crtr push final` to finish.';
         }
         const rows = kids.map((k) => {
@@ -279,10 +274,10 @@ const feedPeekLeaf = defineLeaf({
                 ? `pushed ${fmtAge(k.last_push.ts)} [${k.last_push.kind}]${k.last_push.ref !== null ? ` ref:${k.last_push.ref}` : ''}`
                 : 'no push yet';
             const glyph = STATUS_GLYPH[k.status] ?? '?';
-            return `  ${glyph} ${k.node_id}  ${k.kind}  ${k.name}${sub}  \u00b7 ${k.status} \u00b7 spawned ${fmtAge(k.spawned)} \u00b7 cyc ${k.cycles} \u00b7 ${push}`;
+            return `- ${glyph} ${k.name}${sub} (${k.node_id}) \u00b7 ${k.kind} \u00b7 ${k.status} \u00b7 spawned ${fmtAge(k.spawned)} \u00b7 cyc ${k.cycles} \u00b7 ${push}`;
         }).join('\n');
-        const attrs = `node="${id}" subscriptions="${kids.length}" working="${working.length}" done="${done.length}" dead="${dead.length}" unread="${unread}" verdict="${verdict}"`;
-        return `<peek ${attrs}>\n${line}\n\n${rows}\n</peek>`;
+        const summary = `${kids.length} node${kids.length === 1 ? '' : 's'} below you — ${working.length} working, ${done.length} done, ${dead.length} dead, ${unread} unread:`;
+        return `${line}\n\n${summary}\n${rows}`;
     },
 });
 // ---------------------------------------------------------------------------

package/dist/commands/tmux-spread.js

@@ -125,5 +125,20 @@ export const tmuxSpreadLeaf = defineLeaf({
             focused: spread.focused,
         };
     },
-    render: (r) => `<spread node window="${r['window'] ?? ''}" joined="${r['children_joined'].length}" overflow="${r['overflow'].length}" focused="${r['focused']}"/>`,
+    render: (r) => {
+        const joined = r['children_joined'] ?? [];
+        const overflow = r['overflow'] ?? [];
+        const where = r['window'] !== undefined && r['window'] !== ''
+            ? ` into window ${r['window']}${r['session'] !== undefined ? ` (session ${r['session']})` : ''}`
+            : '';
+        const lead = `Spread node${where} — ${joined.length} child pane(s) joined, ${overflow.length} overflow, ${r['focused'] === true ? 'window focused' : 'window not focused'}.`;
+        const blocks = [lead];
+        if (joined.length > 0) {
+            blocks.push(['Children joined:', ...joined.map((c) => `- ${c}`)].join('\n'));
+        }
+        if (overflow.length > 0) {
+            blocks.push(['Overflow (max_panes_per_window reached):', ...overflow.map((c) => `- ${c}`)].join('\n'));
+        }
+        return blocks.join('\n\n');
+    },
 });

package/dist/commands/view-cycle.js

@@ -117,9 +117,13 @@ export const viewCycleLeaf = defineLeaf({
         catch { /* best-effort */ }
         return { cycled: true, view: targetId, from: current };
     },
-    render: (r) => r['cycled'] === true
-        ? `<view-cycled to="${r['view']}" from="${r['from'] ?? ''}"/>`
-        : r['from'] !== undefined
-            ? `<view-cycle-noop>no other view to switch to</view-cycle-noop>`
-            : `<view-cycle-noop>this pane is not hosting a view</view-cycle-noop>`,
+    render: (r) => {
+        if (r['cycled'] === true) {
+            return `Cycled the monitor to view "${r['view']}" (from "${r['from']}").`;
+        }
+        if (r['from'] !== undefined) {
+            return `No other view to switch to — the pane is still on "${r['from']}".`;
+        }
+        return 'Nothing to cycle — this pane is not hosting a view.';
+    },
 });

package/dist/commands/view-run.js

@@ -181,11 +181,12 @@ export const viewRunLeaf = defineLeaf({
     render: (result) => {
         const hosted = result['hosted'];
         if (hosted === 'window') {
-            return `<view-opened mode="window" view="${result['view']}" window="${result['window']}" pane="${result['pane']}"/>`;
+            return `Opened view "${result['view']}" as a window monitor — window ${result['window']}, pane ${result['pane']}.`;
         }
         if (hosted === 'split') {
-            return `<view-opened mode="split" view="${result['view']}" pane="${result['pane']}"/>`;
+            return `Opened view "${result['view']}" as a split monitor — pane ${result['pane']}.`;
         }
+        // In-pane host: the terminal was held until quit; nothing to report.
         return '';
     },
 });

package/dist/core/__tests__/broker-attach-limits.test.d.ts

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

package/dist/core/__tests__/broker-attach-limits.test.js

@@ -0,0 +1,157 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/broker-attach-limits.test.ts
+//
+// T8 — the `crtr attach` acceptance gate, gates G4/G7/G8/G9 (controller
+// arbitration, decoder overflow caps, backpressure shedding, and the load-bearing
+// ONE-WRITER proof). Split out of broker-lifecycle.test.ts (see its header for
+// the full file map); the tests are the original acceptance gate, unchanged, on
+// their own isolated harness. Each test drives the REAL detached broker process +
+// REAL view.sock with the enriched fake engine, using the PRODUCTION
+// ViewSocketClient (helpers/broker-clients.ts) as the controller/observer — raw
+// node:net only where the client lifecycle is awkward (G7 oversized line, G8
+// stalled viewer). The engine is hosted IN-PROCESS by the broker, so engine pid
+// == broker pid == node.pi_pid == boot.pid.
+import { test, before, after, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { join } from 'node:path';
+import { createHarness, hasTmux } from './helpers/harness.js';
+import { isPidAlive } from '../canvas/pid.js';
+import { createAttachKit, delay, tok, frameHas, brokerLogText, lsofHolders, } from './helpers/broker-clients.js';
+let h;
+let root;
+const kit = createAttachKit(() => h);
+const { attach, attachUntil, connectRaw } = kit;
+before(async () => {
+    if (!hasTmux())
+        return;
+    h = await createHarness({ sessionPrefix: 'crtr-brklim' });
+    root = h.spawnRoot('broker-attach-limits suite root');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+afterEach(() => {
+    kit.closeAll();
+});
+const brokerPid = (id) => h.node(id).pi_pid;
+// ---------------------------------------------------------------------------
+// G4 — arbitration + observer read. Guards: 2nd client is admitted observer, an
+// observer prompt is rejected not_controller, BOTH clients receive the relay.
+// Failure mode: two controllers, or an observer driving the engine, or fan-out
+// that misses a viewer.
+// ---------------------------------------------------------------------------
+test('G4 — second client is observer; observer prompt → error{not_controller}; both receive the stream', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — G4');
+    const c1 = await attach(id, 'controller', 'g4-ctrl');
+    assert.equal(c1.welcome.role, 'controller', 'first client holds control');
+    const c2 = await attach(id, 'controller', 'g4-second'); // requests control; held → observer
+    assert.equal(c2.welcome.role, 'observer', 'second client is admitted read-only observer (first-attach-wins)');
+    c2.send({ type: 'prompt', text: 'observer must not drive' });
+    const err = await c2.waitFrame((f) => f.type === 'error', 'G4 observer prompt rejected');
+    assert.equal(err.code, 'not_controller', 'G4: observer prompt → error{not_controller}');
+    const token = tok('G4-BROADCAST');
+    c1.send({ type: 'prompt', text: token });
+    await c1.waitFrame((f) => f.type === 'agent_end' && frameHas(f, token), 'G4 controller received the stream');
+    await c2.waitFrame((f) => f.type === 'agent_end' && frameHas(f, token), 'G4 observer ALSO received the stream');
+});
+// ---------------------------------------------------------------------------
+// G7 — decoder overflow (guards C5 OOM). A client line over BROKER_READ_CAPS is
+// cap-and-dropped; the broker survives and other clients are unaffected. Failure
+// mode: an unbounded decoder buffer growing the broker to OOM.
+// ---------------------------------------------------------------------------
+test('G7 — an oversized client line is dropped (frame_overflow), the broker survives, other clients unaffected', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — G7');
+    const pid = brokerPid(id);
+    const boots = h.bootCount(id);
+    const survivor = await attach(id, 'observer', 'g7-survivor');
+    // 26 MiB with NO newline > BROKER_READ_CAPS.maxLineBytes (24 MiB) → the bounded
+    // FrameDecoder throws FrameOverflowError; the broker drops the peer.
+    const bad = await connectRaw(id, { read: true });
+    bad.writeRaw(Buffer.alloc(26 * 1024 * 1024, 0x78));
+    await bad.waitClosed('G7 oversized peer dropped by the broker');
+    await h.waitFor(() => /frame overflow/.test(brokerLogText(h, id)) || null, { label: 'G7 broker logged the frame-overflow drop' });
+    // The broker survives and the other client is unaffected: a fresh turn relays.
+    const token = tok('G7-AFTER');
+    h.fakeCmd(id, { cmd: 'stream', text: token });
+    await survivor.waitFrame((f) => f.type === 'agent_end' && frameHas(f, token), 'G7 survivor still receives live frames');
+    assert.equal(isPidAlive(pid), true, 'G7: the broker survived the overflow');
+    assert.equal(brokerPid(id), pid, 'G7: broker pid unchanged');
+    assert.equal(h.bootCount(id), boots, 'G7: no reboot');
+});
+// ---------------------------------------------------------------------------
+// G8 — backpressure leak (guards M1). A stalled (non-reading) viewer is shed at
+// the HWM (32 MiB byte cap) while the broker + other viewers are unaffected.
+// Failure mode: an indefinitely-growing per-viewer queue (broker OOM) or a slow
+// viewer back-pressuring the shared engine.
+// ---------------------------------------------------------------------------
+test('G8 — a stalled viewer is dropped at the backpressure HWM; the broker + fast viewers are unaffected', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — G8');
+    const pid = brokerPid(id);
+    const fast = await attach(id, 'observer', 'g8-fast'); // reads normally
+    // A helloed viewer that NEVER reads (paused socket). It must be in the broadcast
+    // set before the flood; hello, then a short beat for the broker to process it.
+    const stalled = await connectRaw(id, { read: false });
+    stalled.send({ type: 'hello', role: 'observer', client_id: 'g8-stalled' });
+    await delay(400);
+    // A fast event stream: ~60 MiB across 240 message_update frames. The stalled
+    // viewer's per-viewer backlog crosses the 32 MiB byte cap → dropped; the fast
+    // viewer drains between frames (per-update yield) and survives.
+    //
+    // The DROP SIGNAL is the broker's own log line, NOT the stalled socket's 'close':
+    // a PAUSED node socket does not surface the peer FIN/close until it is resumed,
+    // so the broker-side `backpressure high-water mark exceeded` line is the
+    // deterministic, race-free proof that the slow viewer was shed at the HWM.
+    const token = tok('G8-FLOOD');
+    h.fakeCmd(id, { cmd: 'stream', text: token, updates: 240, padBytes: 256 * 1024, tool: false });
+    await h.waitFor(() => /backpressure high-water mark exceeded/.test(brokerLogText(h, id)) || null, { label: 'G8 broker shed the stalled viewer at the HWM', timeoutMs: 30_000 });
+    // The fast viewer drained the WHOLE stream (agent_end is the terminal frame) —
+    // proving only the stalled viewer was shed, while the fast one was unaffected.
+    await fast.waitFrame((f) => f.type === 'agent_end' && frameHas(f, token), 'G8 fast viewer received the whole stream', 30_000);
+    assert.equal(isPidAlive(pid), true, 'G8: the broker survived the slow-viewer flood');
+    assert.equal(brokerPid(id), pid, 'G8: broker pid unchanged (the engine was not back-pressured into a restart)');
+});
+// ---------------------------------------------------------------------------
+// G9 — the load-bearing ONE-WRITER assertion. Across attach→detach→reattach the
+// broker pid AND engine pid (the same, in-process) are UNCHANGED and no second
+// engine is ever spawned; the viewer holds ONLY the socket (never the .jsonl).
+// Failure mode: a viewer that spawns/forks a second engine or opens the session
+// .jsonl — the corruption the headless design exists to prevent.
+// ---------------------------------------------------------------------------
+test('G9 — one-writer: broker/engine pid stable across attach→detach→reattach; no second engine; viewer holds only the socket', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — G9');
+    const pid0 = brokerPid(id);
+    const boots0 = h.bootCount(id);
+    const c1 = await attach(id, 'controller', 'g9-a');
+    const a = tok('G9-A');
+    c1.send({ type: 'prompt', text: a });
+    await c1.waitFrame((f) => f.type === 'agent_end' && frameHas(f, a), 'G9 first turn relayed');
+    c1.send({ type: 'bye' });
+    c1.close();
+    await delay(300);
+    assert.equal(brokerPid(id), pid0, 'G9: broker/engine pid unchanged after detach');
+    assert.equal(isPidAlive(pid0), true, 'G9: the one engine is still alive after detach');
+    assert.equal(h.bootCount(id), boots0, 'G9: no second engine spawned across detach');
+    // attachUntil (not a fixed sleep) synchronizes on the controller handoff: the
+    // detach's controllerId=null lands a beat after close, so retry until the
+    // reattach is admitted controller before driving the second prompt.
+    const c2 = await attachUntil(id, 'controller', 'g9-b', (x) => x.welcome.role === 'controller', 'G9 reattach re-takes control');
+    assert.equal(c2.welcome.role, 'controller', 'G9: the reattached client drives the SAME engine as controller');
+    const b = tok('G9-B');
+    c2.send({ type: 'prompt', text: b });
+    await c2.waitFrame((f) => f.type === 'agent_end' && frameHas(f, b), 'G9 reattached controller drives the SAME engine');
+    assert.equal(brokerPid(id), pid0, 'G9: STILL the same broker/engine pid after reattach (one writer, never two)');
+    assert.equal(isPidAlive(pid0), true, 'G9: the single engine is alive across the full cycle');
+    assert.equal(h.bootCount(id), boots0, 'G9: exactly one engine boot across attach→detach→reattach');
+    // fd-check (best-effort): the viewer host (this test process) must NOT hold the
+    // session .jsonl — only the broker may. With the fake engine the .jsonl is not
+    // held open continuously, so the meaningful assertion is that the VIEWER never
+    // appears among its holders (and any holder that exists is the broker).
+    const jsonl = join(h.home, 'nodes', id, 'fake-session.jsonl');
+    const holders = lsofHolders(jsonl);
+    if (holders !== null) {
+        assert.ok(!holders.includes(process.pid), 'G9: the attach client (this process) does NOT hold the session .jsonl');
+        for (const holder of holders) {
+            assert.equal(holder, pid0, 'G9: the ONLY holder of the session .jsonl is the broker/engine');
+        }
+    }
+});

package/dist/core/__tests__/broker-attach-stream.test.d.ts

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