@north-light/crouter 0.3.154 → 0.3.157

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

@@ -78,10 +78,10 @@ export interface SessionStatsSummary {
     assistant_messages: number;
     cost?: number;
 }
-/** 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. */
+/** Viewer/controller presence for a node. */
 export interface Presence {
     viewers: number;
+    controller: string | null;
 }
 /** Git working-tree change counts for the meta strip. */
 export interface GitStatus {
@@ -276,9 +276,7 @@ export interface ResolveDeckResponse {
  * `isStreaming` (spec C.10).
  */
 export type SessionState = RpcSessionState;
-/** 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. */
+/** Web role of one browser tab's session connection. */
 export type WebRole = 'observer' | 'controller';
 /** Upstream broker connectivity, surfaced to the tab (spec §6.2). */
 export type BrokerStatus = 'connected' | 'reconnecting' | 'down' | 'revived';

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-writable dialogs resolve to deny/cancel IMMEDIATELY (noOp), never
+// C2 — zero-viewer 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 writable() snapshot that reports zero writable viewers.
+// with a controller() that reports zero viewers.
 // ===========================================================================
-test('C2 — zero-writable UI context resolves dialogs to deny/cancel immediately (noOp, no hang)', async () => {
+test('C2 — zero-viewer UI context resolves dialogs to deny/cancel immediately (noOp, no hang)', async () => {
     const ctx = makeBrokerUiContext({
-        writable: () => [], // ZERO writable viewers attached
+        controller: () => null, // ZERO viewers attached
         forward: () => {
-            throw new Error('C2: must NOT forward a dialog when no writable viewer is attached');
+            throw new Error('C2: must NOT forward a dialog when no controller is attached');
         },
         pending: new Map(),
         broadcast: () => { },
@@ -274,7 +274,7 @@ test('C2 — zero-writable UI context resolves dialogs to deny/cancel immediatel
 test('broker UI exposes the live provider pin policy to package extensions', () => {
     let pinned = false;
     const ctx = makeBrokerUiContext({
-        writable: () => [],
+        controller: () => null,
         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 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
+// 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
 // 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 when its writable viewer detaches, resolving only on the broker-side timeout', async () => {
+test('M2 — a forwarded dialog stays pending on controller detach, 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
-        writable: () => (attached ? [{ id: 'c1' }] : []),
+        controller: () => (attached ? { id: 'c1' } : null),
         forward: () => {
-            /* a real writable viewer would receive the request over its socket */
+            /* a real controller would receive the request over its socket */
         },
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         pending: pending,
         broadcast: () => { },
     });
-    // 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.
+    // 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.
     const p = ctx.confirm('proceed?', 'really?', { timeout: 80 });
-    assert.equal(pending.size, 1, 'M2: a forwarded dialog is pending while a writable viewer is attached');
+    assert.equal(pending.size, 1, 'M2: a forwarded dialog is pending while a controller 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');
-    // The writable viewer detaches → the dialog STAYS pending (the broker no longer cancels it).
+    // Controller detaches → the dialog STAYS pending (the broker no longer cancels it).
     attached = false;
-    assert.equal(pending.size, 1, 'M2: writable-viewer detach does NOT cancel the in-flight dialog');
+    assert.equal(pending.size, 1, 'M2: 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__/chat-view-reconnect.test.js

@@ -41,16 +41,23 @@ test('local invalid/no-node stream failures close asynchronously after the chann
         assert.equal(events[1]?.startsWith('close:'), true, `${target}: follows with streamClose`);
     }
 });
-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;
+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,
+    };
     const ctx = {
         get state() {
             return current;
@@ -58,13 +65,6 @@ test('reconnect keeps the requested role while welcome and read_only remain auth
         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,32 +74,11 @@ test('reconnect keeps the requested role while welcome and read_only remain auth
             quit() { },
         },
     };
-    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']);
+    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');
     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,32 +3,27 @@
 // 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: multi-writer
-// admission, decoder overflow isolation, and backpressure shedding.
+// T8 — the `crtr surface attach` acceptance gate for G4/G7/G8: controller
+// arbitration, decoder overflow isolation, and backpressure shedding.
 //
 // 3-PART HEADER (headless):
-//  (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.
+//  (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.
 //  (3) HOW THE HEADLESS DRIVE ASSERTS THE CONTRACT — the real socket responses
-//      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.
+//      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.
 //
-// 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.
+// 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.
 import { test, before, after, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
 import { createHeadlessHarness } from '../helpers/harness.js';
@@ -37,7 +32,9 @@ 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, connectRaw } = kit;
+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`);
 before(async () => {
     h = await createHeadlessHarness({ sessionPrefix: 'crtr-brklim' });
     const root = h.spawnRoot('broker-attach-limits suite root');
@@ -52,44 +49,23 @@ afterEach(() => {
 });
 const brokerPid = () => h.node(id).pi_pid;
 // ---------------------------------------------------------------------------
-// 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.
+// 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 — 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');
+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');
 });
 // ---------------------------------------------------------------------------
 // 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. 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.
+// (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.
 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;
-// Attach a writable client for the gate; its role remains fixed for this socket.
+// 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`);
 before(async () => {
     h = await createHeadlessHarness({ sessionPrefix: 'crtr-brkstrm' });

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

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

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

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