@north-light/crouter 0.3.157 → 0.3.159

package/dist/clients/web/web-client/shared/protocol.d.ts

@@ -78,10 +78,10 @@ export interface SessionStatsSummary {
     assistant_messages: number;
     cost?: number;
 }
-/** Viewer/controller presence for a node. */
+/** Viewer presence for a node — a truthful count of attached views. There is
+ *  no owner: every live interactive view is writable at the same time. */
 export interface Presence {
     viewers: number;
-    controller: string | null;
 }
 /** Git working-tree change counts for the meta strip. */
 export interface GitStatus {
@@ -276,7 +276,9 @@ export interface ResolveDeckResponse {
  * `isStreaming` (spec C.10).
  */
 export type SessionState = RpcSessionState;
-/** Web role of one browser tab's session connection. */
+/** Fixed capability of one browser tab's session connection, stated by the
+ *  broker's `welcome`: `controller` is writable, `observer` is read-only. It is
+ *  a per-client capability, never ownership of a shared slot. */
 export type WebRole = 'observer' | 'controller';
 /** Upstream broker connectivity, surfaced to the tab (spec §6.2). */
 export type BrokerStatus = 'connected' | 'reconnecting' | 'down' | 'revived';

package/dist/commands/node.js

@@ -27,7 +27,8 @@ import { profilesStateBlock } from '../core/profiles/state-block.js';
 import { stateBlock } from '../core/help.js';
 import { fuzzyMatch } from '../core/canvas/browse/model.js';
 import { loadPins, savePins } from '../core/canvas/browse/pins.js';
-import { backgroundRunningBashJobs, formatBashElapsed, jobStartedAtMs } from '../core/bash-jobs.js';
+import { existsSync, writeFileSync } from 'node:fs';
+import { activeBackgroundBashJobs, backgroundRunningBashJobs, bashJobPaths, formatBashElapsed, jobStartedAtMs, readJobPgid, tailJobLog } from '../core/bash-jobs.js';
 // The API seam — every canvas mutation/read routes through the daemon (B-1).
 import { cliClient, cliCanvasSource, ApiCanvasSource, rethrowAsCliError, getNodeOrNull } from './api-client.js';
 // Past this much context, an ORCHESTRATOR that spawns a managed child is better
@@ -808,7 +809,7 @@ const nodeBashBackground = defineLeaf({
             { name: 'jobs', type: 'object[]', required: true, constraint: 'Per handed-off job {job_id, elapsed_ms} — the foreground elapsed time in milliseconds at the moment of handoff.' },
         ],
         outputKind: 'object',
-        effects: ['Signals every foreground bash command currently running for the node to return from its tool call immediately while its detached supervisor keeps the command running.', 'Each handed-off command retains its log under the node context jobs directory and sends the node an inbox message when it exits.'],
+        effects: ['Signals every foreground bash command currently running for the node to return from its tool call immediately while its detached supervisor keeps the command running.', 'Each handed-off command retains its log under the node context jobs directory and sends the node an urgent inbox message when it exits, which steers the node mid-turn.'],
     },
     run: async (input) => {
         const pane = input['pane'] ?? process.env['TMUX_PANE'];
@@ -842,16 +843,153 @@ const nodeBashBackground = defineLeaf({
         return `Handed ${result['backgrounded']} bash command(s) to the background job system for ${result['node_id']} · ran ${formatBashElapsed(oldestElapsedMs)} in the foreground.`;
     },
 });
+const nodeBashList = defineLeaf({
+    name: 'list',
+    description: 'list a node’s live background bash jobs',
+    whenToUse: 'the Inspector’s jobs section reads this to show what a node handed off to the background',
+    tier: 'hidden',
+    help: {
+        name: 'node bash list',
+        summary: 'read every still-running background bash job owned by one node',
+        params: [
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node whose background jobs to list. Defaults to the node in --pane, else the caller (CRTR_NODE_ID).' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane showing the target node, when --node is omitted. Defaults to $TMUX_PANE.' },
+            { kind: 'flag', name: 'tail', type: 'int', required: false, default: 0, constraint: 'Include this many trailing log lines per job (0 = none).' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The target node.' },
+            { name: 'jobs', type: 'object[]', required: true, constraint: 'Oldest-first {job_id, command, started_at, elapsed_ms, log_path, pgid, log_tail} for every live background job.' },
+        ],
+        outputKind: 'object',
+        effects: ['Reads the node context jobs directory. Changes nothing.'],
+    },
+    run: async (input) => {
+        const pane = input['pane'] ?? process.env['TMUX_PANE'];
+        let id = input['node'];
+        if (id === undefined || id === '')
+            id = nodeInPane(pane);
+        if (id === undefined || id === '')
+            id = process.env['CRTR_NODE_ID'];
+        if (id === undefined || id === '') {
+            throw new InputError({ error: 'no_node', message: 'no node found for the bash job list', next: 'Run from inside a node, pass --node <id>, or --pane <pane>.' });
+        }
+        const node = await getNodeOrNull(id);
+        if (node === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const now = Date.now();
+        const tail = Math.max(0, Math.trunc(Number(input['tail'] ?? 0)));
+        const dir = contextDir(node.node_id);
+        const jobs = activeBackgroundBashJobs(dir).map((job) => ({
+            job_id: job.jobId,
+            command: job.command,
+            started_at: new Date(job.startedAtMs).toISOString(),
+            elapsed_ms: now - job.startedAtMs,
+            log_path: job.logPath,
+            pgid: readJobPgid(dir, job.jobId) ?? null,
+            log_tail: tailJobLog(job.logPath, tail),
+        }));
+        return { node_id: node.node_id, jobs };
+    },
+    render: (result) => {
+        const jobs = result['jobs'];
+        if (jobs.length === 0)
+            return `No background bash jobs for ${result['node_id']}.`;
+        return jobs.map((job) => `${job.job_id} · ${formatBashElapsed(job.elapsed_ms)} · ${job.command.split('\n')[0]}\n  log: ${job.log_path}`).join('\n');
+    },
+});
+/** SIGTERM the job's process group, give it a moment, then SIGKILL. Returns
+ *  false only when the group was already gone at the first signal. */
+function stopJobGroup(pgid) {
+    try {
+        process.kill(-pgid, 'SIGTERM');
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+const nodeBashKill = defineLeaf({
+    name: 'kill',
+    description: 'stop one of a node’s background bash jobs',
+    whenToUse: 'a human watching the Inspector wants a long-running background job to stop now, or an agent is abandoning work it backgrounded',
+    tier: 'hidden',
+    help: {
+        name: 'node bash kill',
+        summary: 'terminate a background bash job’s process group and tell the owning node it was canceled',
+        params: [
+            { kind: 'positional', name: 'job', required: true, constraint: 'Job id, as reported by node bash list.' },
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node owning the job. Defaults to the node in --pane, else the caller (CRTR_NODE_ID).' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane showing the target node, when --node is omitted. Defaults to $TMUX_PANE.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The owning node.' },
+            { name: 'job_id', type: 'string', required: true, constraint: 'The job that was stopped.' },
+            { name: 'signaled', type: 'boolean', required: true, constraint: 'True when the process group was still alive and received SIGTERM.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Sends SIGTERM (then SIGKILL) to the job’s whole process group, stopping the command and anything it forked.',
+            'Records the job’s exit so it stops showing as live, and sends the owning node an urgent inbox message saying the job was canceled — which steers that node mid-turn.',
+        ],
+    },
+    run: async (input) => {
+        const pane = input['pane'] ?? process.env['TMUX_PANE'];
+        let id = input['node'];
+        if (id === undefined || id === '')
+            id = nodeInPane(pane);
+        if (id === undefined || id === '')
+            id = process.env['CRTR_NODE_ID'];
+        if (id === undefined || id === '') {
+            throw new InputError({ error: 'no_node', message: 'no node found for the bash job', next: 'Run from inside a node, pass --node <id>, or --pane <pane>.' });
+        }
+        const node = await getNodeOrNull(id);
+        if (node === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const jobId = input['job'];
+        const dir = contextDir(node.node_id);
+        const paths = bashJobPaths(dir, jobId);
+        if (!existsSync(paths.dir)) {
+            throw new InputError({ error: 'not_found', message: `no background job ${jobId} for ${node.node_id}`, next: 'List live jobs with `crtr node bash list`.' });
+        }
+        const pgid = readJobPgid(dir, jobId);
+        if (pgid === undefined) {
+            throw new InputError({
+                error: 'not_stoppable',
+                message: `job ${jobId} recorded no process group`,
+                next: `It started before crtr persisted one. Stop it by hand, then it will disappear from the list. Log: ${paths.jobLog}`,
+            });
+        }
+        const signaled = stopJobGroup(pgid);
+        // The supervisor shares the group it leads, so it usually dies with the
+        // command and never writes job.exit. Record the cancellation ourselves —
+        // that sentinel is what retires the job from every live-jobs read.
+        await new Promise((r) => setTimeout(r, 400));
+        try {
+            process.kill(-pgid, 'SIGKILL');
+        }
+        catch { /* already gone */ }
+        if (!existsSync(paths.jobExit))
+            writeFileSync(paths.jobExit, '143\n');
+        await cliClient().sendMessage(node.node_id, {
+            body: `Background bash job ${jobId} was canceled from the Inspector before it finished. Log: ${paths.jobLog}  Command: ${paths.cmdSh}`,
+            tier: 'urgent',
+        });
+        return { node_id: node.node_id, job_id: jobId, signaled };
+    },
+    render: (result) => `Canceled background bash job ${result['job_id']} for ${result['node_id']}${result['signaled'] === true ? '' : ' (its process group was already gone)'}.`,
+});
 const nodeBash = defineBranch({
     name: 'bash',
     description: 'control file-backed bash jobs owned by a node',
-    whenToUse: 'the tmux prefix menu needs to hand a running bash command off without waiting for the automatic timeout',
+    whenToUse: 'a running bash command must be handed off, listed, or stopped — the tmux prefix menu backgrounds, the Inspector’s jobs section lists and cancels',
     tier: 'hidden',
     help: {
         name: 'node bash',
         summary: 'control file-backed bash jobs owned by a node',
     },
-    children: [nodeBashBackground],
+    children: [nodeBashBackground, nodeBashList, nodeBashKill],
 });
 export const surfaceNodeIdLeaf = defineLeaf({
     name: 'id',

package/dist/commands/surface-inspect.js

@@ -8,17 +8,18 @@ import { runCoreView } from '../core/tui/host.js';
 export const surfaceInspectLeaf = defineLeaf({
     name: 'inspect',
     description: 'host the native Inspector for one node',
-    whenToUse: 'you want a live native screen for a node’s overview, raw record, and owner-scoped crons. Use node inspect show for the underlying one-shot data read instead.',
+    whenToUse: 'you want a live native screen for a node’s overview, raw record, owner-scoped crons, and live background bash jobs. Use node inspect show for the underlying one-shot data read instead.',
     help: {
         name: 'surface inspect',
         summary: 'host the native Inspector in this pane (the attach viewer opens it as a tmux popup)',
+        // sections: overview · schedule (armed crons) · jobs (live background bash) · raw
         params: [
             { kind: 'positional', name: 'node', required: true, constraint: 'Node id or resolvable reference to inspect.' },
-            { kind: 'flag', name: 'section', type: 'enum', choices: ['overview', 'schedule', 'raw'], required: false, default: 'overview', constraint: 'Section focused when the Inspector opens.' },
+            { kind: 'flag', name: 'section', type: 'enum', choices: ['overview', 'schedule', 'jobs', 'raw'], required: false, default: 'overview', constraint: 'Section focused when the Inspector opens.' },
         ],
         output: [],
         outputKind: 'object',
-        effects: ['Reads node and cron data through crtr subprocesses and crtrd. Takes over the hosting pane (or popup) until it quits.'],
+        effects: ['Reads node, cron, and background bash job data through crtr subprocesses and crtrd. Takes over the hosting pane (or popup) until it quits.'],
     },
     run: async (input) => {
         const node = input['node'];

package/dist/core/__tests__/broker-sdk-wiring.test.js

@@ -240,16 +240,16 @@ test('C3h — a cooling managed launch target boots model-less rather than falli
 // `<project_context>` block is environment-only. Covered by
 // context-intro.test.ts's environment-only regression.)
 // ===========================================================================
-// C2 — zero-viewer dialogs resolve to deny/cancel IMMEDIATELY (noOp), never
+// C2 — zero-writable dialogs resolve to deny/cancel IMMEDIATELY (noOp), never
 // hanging the turn and never waiting on a per-dialog timeout. Drives the REAL
 // makeBrokerUiContext (the exact ExtensionUIContext the SDK hands extensions),
-// with a controller() that reports zero viewers.
+// with a writable() snapshot that reports zero writable viewers.
 // ===========================================================================
-test('C2 — zero-viewer UI context resolves dialogs to deny/cancel immediately (noOp, no hang)', async () => {
+test('C2 — zero-writable UI context resolves dialogs to deny/cancel immediately (noOp, no hang)', async () => {
     const ctx = makeBrokerUiContext({
-        controller: () => null, // ZERO viewers attached
+        writable: () => [], // ZERO writable viewers attached
         forward: () => {
-            throw new Error('C2: must NOT forward a dialog when no controller is attached');
+            throw new Error('C2: must NOT forward a dialog when no writable viewer is attached');
         },
         pending: new Map(),
         broadcast: () => { },
@@ -274,7 +274,7 @@ test('C2 — zero-viewer UI context resolves dialogs to deny/cancel immediately
 test('broker UI exposes the live provider pin policy to package extensions', () => {
     let pinned = false;
     const ctx = makeBrokerUiContext({
-        controller: () => null,
+        writable: () => [],
         forward: () => { },
         pending: new Map(),
         broadcast: () => { },
@@ -291,36 +291,36 @@ test('broker UI exposes the live provider pin policy to package extensions', ()
 });
 // ===========================================================================
 // M2 (review mq5wkqep / T4) — REPLACES the Wave-0 M-1 cancel-on-detach. A dialog
-// forwarded to a controller that then DETACHES must NOT be cancelled: it stays
-// pending so a brief detach/reattach (or a handoff to another controller) does
-// not lose an answerable dialog. The broker-side default timeout is the ONLY
+// forwarded to a writable viewer that then DETACHES must NOT be cancelled: it
+// stays pending so a brief detach/reattach (or another writable viewer joining)
+// does not lose an answerable dialog. The broker-side default timeout is the ONLY
 // non-answer resolution (proven here with a short per-dialog timeout standing in
 // for the 120s default). Guards against regressing to the over-eager cancel.
 // ===========================================================================
-test('M2 — a forwarded dialog stays pending on controller detach, resolving only on the broker-side timeout', async () => {
+test('M2 — a forwarded dialog stays pending when its writable viewer detaches, resolving only on the broker-side timeout', async () => {
     const pending = new Map();
     let attached = true;
     const ctx = makeBrokerUiContext({
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        controller: () => (attached ? { id: 'c1' } : null),
+        writable: () => (attached ? [{ id: 'c1' }] : []),
         forward: () => {
-            /* a real controller would receive the request over its socket */
+            /* a real writable viewer would receive the request over its socket */
         },
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         pending: pending,
         broadcast: () => { },
     });
-    // Controller attached → confirm() forwards + registers a pending dialog (with the
-    // request retained for welcome.pending_dialog / re-route, T4) and does NOT
-    // resolve yet. A short per-dialog timeout stands in for the 120s broker default.
+    // A writable viewer attached → confirm() forwards + registers a pending dialog
+    // (with the request retained for welcome.pending_dialog / replay, T4) and does
+    // NOT resolve yet. A short per-dialog timeout stands in for the 120s broker default.
     const p = ctx.confirm('proceed?', 'really?', { timeout: 80 });
-    assert.equal(pending.size, 1, 'M2: a forwarded dialog is pending while a controller is attached');
+    assert.equal(pending.size, 1, 'M2: a forwarded dialog is pending while a writable viewer is attached');
     const entry = [...pending.values()][0];
     assert.ok(entry.request, 'M2: the pending entry retains the request (welcome/re-route need it)');
     assert.equal(entry.cancel, undefined, 'M2: there is no cancel-on-detach path anymore');
-    // Controller detaches → the dialog STAYS pending (the broker no longer cancels it).
+    // The writable viewer detaches → the dialog STAYS pending (the broker no longer cancels it).
     attached = false;
-    assert.equal(pending.size, 1, 'M2: detach does NOT cancel the in-flight dialog');
+    assert.equal(pending.size, 1, 'M2: writable-viewer detach does NOT cancel the in-flight dialog');
     // Only the broker-side timeout resolves it, to the SAFE default (deny).
     const resolved = await Promise.race([
         p,

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

@@ -75,7 +75,7 @@ async function waitFor(predicate, timeoutMs = 3000, stepMs = 10) {
         await wait(stepMs);
     }
 }
-test('coalesce inlines short reports with their absolute path and only hints for remaining canonical refs', () => {
+test('coalesce inlines short report bodies with a trailing artifact pointer and only hints for remaining canonical refs', () => {
     freshNode('child');
     const child = createNode({
         node_id: 'child',
@@ -93,8 +93,10 @@ test('coalesce inlines short reports with their absolute path and only hints for
     const digest = coalesce([
         finalizeInboxEntry({ from: 'child', tier: 'normal', kind: 'update', label: 'short report', ref: 'child:reports/short-update.md' }),
     ]);
-    assert.match(digest, new RegExp(`\\[update\\] short report at ${reportPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}:`));
-    assert.match(digest, /short report body/);
+    // The label is NOT reprinted above the body it duplicates; the path trails it.
+    assert.doesNotMatch(digest, /\[update\] short report/);
+    assert.match(digest, /\[update\]\n {4}short report body\n/);
+    assert.match(digest, new RegExp(`\\(report: ${reportPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\)`));
     assert.doesNotMatch(digest, /Dereference a ref with/);
     const guidance = 'Dereference a ref with `crtr canvas history read <ref>`.';
     const canonical = coalesce([

package/dist/core/__tests__/chat-view-reconnect.test.js

@@ -41,23 +41,16 @@ test('local invalid/no-node stream failures close asynchronously after the chann
         assert.equal(events[1]?.startsWith('close:'), true, `${target}: follows with streamClose`);
     }
 });
-test('control_changed demotion updates reconnect intent without clobbering an explicit controller request', () => {
-    let current = {
-        target: 'n1',
-        desiredRole: 'controller',
-        channel: null,
-        clientId: 'client-1',
-        conn: 'open',
-        role: 'controller',
-        controllerId: 'client-1',
-        session: null,
-        transcript: [],
-        draft: '',
-        notices: [],
-        pendingDialog: null,
-        queued: [],
-        contextTokens: undefined,
-    };
+test('reconnect keeps the requested role while welcome and read_only remain authoritative', () => {
+    let current = core.init({ target: 'n1', role: 'controller' });
+    const sent = [];
+    const requestedRoles = [];
+    const closed = [];
+    const channels = [
+        { id: 'first-channel', send(frame) { sent.push(frame); }, close() { closed.push('first-channel'); } },
+        { id: 'replacement-channel', send(frame) { sent.push(frame); }, close() { closed.push('replacement-channel'); } },
+    ];
+    let nextChannel = 0;
     const ctx = {
         get state() {
             return current;
@@ -65,6 +58,13 @@ test('control_changed demotion updates reconnect intent without clobbering an ex
         set(next) {
             current = typeof next === 'function' ? next(current) : next;
         },
+        connect(_stream, opts) {
+            requestedRoles.push(opts.role);
+            return channels[nextChannel++];
+        },
+        dispatch(intent) {
+            return core.intents[intent](ctx);
+        },
         signal: {
             clearBanner() { },
             setBanner() { },
@@ -74,11 +74,32 @@ test('control_changed demotion updates reconnect intent without clobbering an ex
             quit() { },
         },
     };
-    core.intents.streamFrame(ctx, { type: 'control_changed', controller_id: 'other-client' });
-    assert.equal(current.role, 'observer');
-    assert.equal(current.desiredRole, 'observer');
-    current = { ...current, role: 'observer', desiredRole: 'controller' };
-    core.intents.streamFrame(ctx, { type: 'control_changed', controller_id: 'other-client' });
-    assert.equal(current.role, 'observer');
+    core.intents.refresh(ctx);
+    const firstChannel = current.channel;
+    assert.equal(current.desiredRole, 'controller');
+    assert.equal(current.conn, 'connecting');
+    assert.deepEqual(requestedRoles, ['controller']);
+    core.intents.streamOpen(ctx, firstChannel);
+    core.intents.streamFrame(ctx, { type: 'welcome', role: 'controller', snapshot: { state: {}, messages: [] } });
+    assert.equal(current.role, 'controller');
+    assert.equal(current.conn, 'open');
+    core.intents.reconnect(ctx);
+    assert.deepEqual(closed, ['first-channel']);
     assert.equal(current.desiredRole, 'controller');
+    assert.equal(current.channel?.id, 'replacement-channel');
+    assert.deepEqual(requestedRoles, ['controller', 'controller']);
+    const replacementChannel = current.channel;
+    core.intents.streamOpen(ctx, replacementChannel);
+    core.intents.streamFrame(ctx, { type: 'welcome', role: 'observer', snapshot: { state: {}, messages: [] } });
+    assert.equal(current.role, 'observer', 'welcome.role is authoritative for the active connection');
+    assert.equal(current.desiredRole, 'controller', 'the requested controller role survives reconnect');
+    assert.equal(current.conn, 'open');
+    core.intents.streamClose(ctx, { channelId: 'first-channel', reason: 'closed' });
+    assert.equal(current.channel, replacementChannel, 'a stale close cannot clear the replacement channel');
+    assert.equal(current.conn, 'open');
+    core.intents.streamFrame(ctx, { type: 'error', code: 'read_only' });
+    core.intents.setDraft(ctx, 'hello');
+    core.intents.submitDraft(ctx);
+    assert.deepEqual(sent, [], 'read-only welcome state prevents writes');
+    assert.match(current.notices.at(-1).text, /read-only — sending is disabled/);
 });

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

@@ -3,27 +3,32 @@
 // FULL TIER (real-boot-bound): tmux-free, but it boots a REAL broker process
 // (~5s pi-SDK load), so it lives in full/ (CI), not the fast local loop.
 //
-// T8 — the `crtr surface attach` acceptance gate for G4/G7/G8: controller
-// arbitration, decoder overflow isolation, and backpressure shedding.
+// T8 — the `crtr surface attach` acceptance gate for G4/G7/G8: multi-writer
+// admission, decoder overflow isolation, and backpressure shedding.
 //
 // 3-PART HEADER (headless):
-//  (1) CONTRACT — the first client is the controller and a second client is an
-//      admitted read-only observer; observer prompts are rejected while both
-//      clients receive relay frames (G4). An oversized client line is capped and
-//      dropped with frame_overflow while the broker and other clients continue
-//      operating (G7). A stalled non-reading viewer is shed at the 32 MiB
-//      backpressure HWM while the broker and fast viewers remain unaffected (G8).
-//  (2) WHY BROKER/SOCKET-LEVEL, NOT PANE/WINDOW — arbitration, decoder limits, and
-//      the backpressure HWM are broker-process and view.sock contracts. They are
-//      exercised over a pure Unix socket using the production ViewSocketClient and
-//      raw node:net peers, with a real broker process and no tmux pane or window.
+//  (1) CONTRACT — every client that hellos as `controller` is welcomed writable,
+//      simultaneously and independently; each writable client may submit, and
+//      every connected client (both writers plus a read-only observer) receives
+//      the merged stream of both submissions, while a client that hellos as
+//      `observer` is rejected with error{read_only} when it tries to drive (G4).
+//      An oversized client line is capped and dropped with frame_overflow while
+//      the broker and other clients continue operating (G7). A stalled
+//      non-reading viewer is shed at the 32 MiB backpressure HWM while the
+//      broker and fast viewers remain unaffected (G8).
+//  (2) WHY BROKER/SOCKET-LEVEL, NOT PANE/WINDOW — role admission, decoder limits,
+//      and the backpressure HWM are broker-process and view.sock contracts. They
+//      are exercised over a pure Unix socket using the production ViewSocketClient
+//      and raw node:net peers, 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 G4 welcome roles and relay frames, the G7 frame-overflow drop
-//      and broker survival, and the G8 HWM-shed log line and broker survival.
+//      provide the G4 welcome roles, per-writer relay frames and the read-only
+//      rejection, the G7 frame-overflow drop and broker survival, and the G8
+//      HWM-shed log line and broker survival.
 //
-// One shared broker is booted in before() and reused across all three gates. Gates
-// whose first attach must hold control use attachUntil(controller) so a prior gate's
-// controller-detach handoff settles deterministically before they drive.
+// One shared broker is booted in before() and reused across all three gates. There
+// is no writer slot to hand off, so every gate simply attaches at the role it
+// wants.
 import { test, before, after, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
 import { createHeadlessHarness } from '../helpers/harness.js';
@@ -32,9 +37,7 @@ import { createAttachKit, delay, tok, frameHas, brokerLogText, } from '../helper
 let h;
 let id; // ONE shared broker, reused across G4/G7/G8 (1 real boot, not 3)
 const kit = createAttachKit(() => h);
-const { attach, attachUntil, connectRaw } = kit;
-// Admit a controller, waiting out any prior gate's controller-detach handoff.
-const ctrl = (cid) => attachUntil(id, 'controller', cid, (a) => a.welcome.role === 'controller', `${cid} admitted controller`);
+const { attach, connectRaw } = kit;
 before(async () => {
     h = await createHeadlessHarness({ sessionPrefix: 'crtr-brklim' });
     const root = h.spawnRoot('broker-attach-limits suite root');
@@ -49,23 +52,44 @@ afterEach(() => {
 });
 const brokerPid = () => 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.
+// G4 — multi-writer admission + read-only gating. Guards: two simultaneous
+// `controller` hellos are BOTH welcomed writable, each one's own submission
+// reaches the engine, and every connected client sees BOTH turns; an explicit
+// observer that tries to drive is rejected with error{read_only}.
+// Failure mode: a singleton writer slot demoting the second client, a writer
+// whose prompt is silently dropped, fan-out that misses a viewer, or a
+// read-only client that can drive the engine.
 // ---------------------------------------------------------------------------
-test('G4 — second client is observer; observer prompt → error{not_controller}; both receive the stream', async () => {
-    const c1 = await ctrl('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');
+test('G4 — two simultaneous clients are both welcomed controller, each submits, and both see both turns; 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 observer = await attach(id, 'observer', 'g4-observer');
+    assert.equal(observer.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.
+    observer.send({ type: 'prompt', text: 'a read-only client must not drive' });
+    const err = await observer.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 observer.waitFrame((f) => f.type === 'agent_end' && frameHas(f, tokenA), 'G4 observer received writer 1 turn');
+    await observer.waitFrame((f) => f.type === 'agent_end' && frameHas(f, tokenB), 'G4 observer received writer 2 turn');
 });
 // ---------------------------------------------------------------------------
 // G7 — decoder overflow (guards C5 OOM). A client line over BROKER_READ_CAPS is

package/dist/core/__tests__/full/broker-attach-stream.test.js

@@ -32,9 +32,9 @@
 // The engine is hosted IN-PROCESS by the broker, so engine pid == broker pid ==
 // node.pi_pid == boot.pid; "engine pid unchanged" == broker pid unchanged + no new
 // boot. ONE shared broker is booted in before() and reused across all three gates
-// (each just attaches fresh clients) — 1 real boot total, not 3. A gate whose
-// first attach must hold control uses attachUntil(controller) so the prior gate's
-// controller-detach handoff settles deterministically before it drives.
+// (each just attaches fresh clients) — 1 real boot total, not 3. Each gate attaches
+// a fresh writable client; afterEach closes prior sockets before the next gate begins,
+// and each client's role remains fixed for its socket.
 import { test, before, after, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
 import { createHeadlessHarness } from '../helpers/harness.js';
@@ -44,7 +44,7 @@ let h;
 let id; // ONE shared broker, reused across G1/G1b/G2 (1 real boot, not 3)
 const kit = createAttachKit(() => h);
 const { attach, attachUntil } = kit;
-// Admit a controller, waiting out any prior gate's controller-detach handoff.
+// Attach a writable client for the gate; its role remains fixed for this socket.
 const ctrl = (cid) => attachUntil(id, 'controller', cid, (a) => a.welcome.role === 'controller', `${cid} admitted controller`);
 before(async () => {
     h = await createHeadlessHarness({ sessionPrefix: 'crtr-brkstrm' });