@north-light/crouter 0.3.154 → 0.3.157

package/dist/core/runtime/broker.js

@@ -3,9 +3,8 @@
 // One broker process per node — the SOLE host. It hosts ONE pi engine IN-PROCESS
 // via the SDK (createAgentSession), is the SOLE writer of the node's session
 // `.jsonl`, listens on `nodeDir(id)/view.sock`, fans the single engine event
-// stream out to N viewers, serializes the drive commands of EVERY writable
-// viewer through one frame loop, and fans blocking extension dialogs out to all
-// of them (first answer wins). The engine has no terminal of its own; a
+// stream out to N viewers, serializes a single controller's drive commands, and
+// routes blocking extension dialogs. The engine has no terminal of its own; a
 // tmux pane (or web tab) is only a viewer of this socket. It
 // runs one turn-cycle and, when the engine settles (the stophook calls
 // ctx.shutdown(), or the engine goes idle), disposes the engine and exits 0 —
@@ -96,8 +95,8 @@ export function isUnknownModel(model) {
         model.api === 'unknown');
 }
 /**
- * Route a writable client's `prompt`/`follow_up` frame against the LIVE session
- * state. The client picks its frame type off a possibly-STALE `isStreaming`
+ * Route a controller `prompt`/`follow_up` frame against the LIVE session state.
+ * The controller picks its frame type off a possibly-STALE `isStreaming`
  * snapshot, so the broker is authoritative and the client's choice is a HINT:
  *
  *  - m-B (streaming-safe prompt): a `prompt` arriving mid-stream needs
@@ -379,10 +378,10 @@ const MAX_PENDING_BYTES = 32 * 1024 * 1024; // 32 MiB
  *  after its message_end). */
 const MESSAGE_UPDATE_COALESCE_MS = 75;
 /** Broker-side default dialog timeout (C2 anti-deadlock, T4). When an extension
- *  dialog is forwarded to every writable client, the broker ALWAYS arms a timeout
- *  (this default, or a shorter per-dialog `opts.timeout` if the extension passed
- *  one) so unanswered dialogs — including ones whose writable viewers all detach
- *  — can never hang the agent turn forever. On fire it resolves to the SAFE default
+ *  dialog is forwarded to a controller, the broker ALWAYS arms a timeout (this
+ *  default, or a shorter per-dialog `opts.timeout` if the extension passed one)
+ *  so a controller that never answers — or detaches and is never replaced — can
+ *  never hang the agent turn forever. On fire it resolves to the SAFE default
  *  (deny for confirm; cancel/undefined for select/input/editor). */
 const DEFAULT_DIALOG_TIMEOUT_MS = 120_000; // 120 s
 /** Admission bound for `runReplacement` (one active head + at most one queued
@@ -572,7 +571,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
     // survives a session replacement (new_session/switch_session/fork), not only at
     // boot.
     // -------------------------------------------------------------------------
-    // Socket fan-out state
+    // Socket fan-out + controller arbitration state
     // -------------------------------------------------------------------------
     const sockPath = viewSocketPath(nodeId);
     const attachPath = join(jobDir(nodeId), 'attach.json');
@@ -586,32 +585,36 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
     const displayStatuses = new Map();
     const displayWidgets = new Map();
     let displayTitle;
+    let controllerId = null;
     let disposed = false;
     let agentRunActive = false;
     let shutdownRequested = false;
     let server;
-    // Every client whose `hello` claimed the writable role and whose transport is
-    // still usable. Liveness matters because on a unix socket a peer destroy()
-    // delivers EOF (readableEnded) promptly while the matching 'close' can lag
-    // arbitrarily behind undrainable pending writes — a departed peer must not be
-    // counted as an answerer a dialog fan-out waits on. Roles are FIXED per client,
-    // so this is a pure filter, never an arbitration.
-    const writableClients = () => {
-        const out = [];
+    // Liveness-aware: a controllerId whose client's transport is already gone counts
+    // as NO controller, so control self-heals the instant a controller's peer departs
+    // — WITHOUT waiting for the socket 'close' event. On a unix socket a peer
+    // destroy() delivers EOF (readableEnded) promptly, but the matching 'close' can
+    // lag arbitrarily while undrainable pending writes to the gone peer flush; under
+    // load that lag stranded control on a dead client and froze admission (a fresh
+    // controller hello was denied for the whole window — the one-writer reattach
+    // deadlock the G9 gate locks). Treating an ended/destroyed/unwritable holder as
+    // free closes that window at every read of the controller (admission included).
+    const controllerClient = () => {
+        if (controllerId === null)
+            return null;
         for (const c of clients) {
-            if (!c.helloed || c.role !== 'controller')
+            if (c.id !== controllerId)
                 continue;
             if (c.socket.destroyed || c.socket.readableEnded || !c.socket.writable)
-                continue;
-            out.push(c);
+                return null;
+            return c;
         }
-        return out;
+        return null;
     };
-    // Persist viewer presence to job/attach.json when the set of helloed viewers
-    // changes (a hello is accepted, or a client drops/is shed) so out-of-process
+    // Persist viewer presence to job/attach.json on every viewer state change
+    // (hello accepted, client drop/shed, control handoff) so out-of-process
     // readers (the GRAPH view's attached-row tint) can see whether a human is
-    // watching this paneless node. Presence is a truthful COUNT and nothing more —
-    // there is no owner to record. Plain writeFileSync, matching telemetry.json's
+    // watching this paneless node. Plain writeFileSync, matching telemetry.json's
     // convention; best-effort — presence writing must never crash the broker.
     // disposeAndExit unlinks the file, so a clean exit never leaves a stale claim
     // (readers additionally trust it only while the node is 'active', fencing off
@@ -625,15 +628,25 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
             const dirPath = jobDir(nodeId);
             if (!existsSync(dirPath))
                 mkdirSync(dirPath, { recursive: true });
-            writeFileSync(attachPath, JSON.stringify({ viewers, updated: new Date().toISOString() }, null, 2), 'utf8');
+            writeFileSync(attachPath, JSON.stringify({ viewers, controller_id: controllerId, updated: new Date().toISOString() }, null, 2), 'utf8');
         }
         catch {
             /* presence is best-effort; never crash the broker */
         }
     };
-    // Shed a client — destroy the socket + remove it — used by both the M1
-    // backpressure drop and the G7 frame-overflow drop. 'close' (→ drop) follows
-    // the destroy.
+    // Free control if the departing/dropped client held it (shared by drop +
+    // dropSlowClient). controllerId can outlive the socket until 'close' fires, so
+    // releasing here keeps arbitration correct the instant a controller is shed.
+    const releaseControlIfHeldBy = (client) => {
+        if (client.id !== '' && client.id === controllerId) {
+            controllerId = null;
+            broadcastControlChanged();
+        }
+    };
+    // Shed a client — destroy the socket + remove it + release its control — used by
+    // both the M1 backpressure drop and the G7 frame-overflow drop. 'close' (→ drop)
+    // follows the destroy; releasing control here makes the shed immediate so a
+    // misbehaving controller can't keep arbitration pinned until 'close' fires.
     const dropClient = (client, reason) => {
         if (!clients.has(client))
             return; // already gone
@@ -648,6 +661,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
         });
         clients.delete(client);
         persistAttachState(); // a viewer was shed
+        releaseControlIfHeldBy(client);
         try {
             client.socket.destroy();
         }
@@ -1311,6 +1325,10 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
         flushPendingUpdate();
         broadcast(event);
     };
+    const broadcastControlChanged = () => {
+        persistAttachState(); // every control change is a viewer-state change
+        broadcast({ type: 'control_changed', controller_id: controllerId });
+    };
     // Persist a live model switch into the node's durable launch recipe so it
     // survives a yield/revive. pi's `/model` (→ set_model/cycle_model) only
     // mutates the in-memory engine; without this the node reverts to its
@@ -1395,16 +1413,17 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
         },
     });
     // Send a client its catch-up snapshot. welcome.pending_dialog carries a single
-    // still-in-flight dialog to a WRITABLE client attaching mid-dialog; an observer
-    // can never answer one, so observers get null. The pendingDialogs map is
+    // still-in-flight dialog to a controller attaching mid-dialog (T4); only the
+    // controller can answer one, so observers get null. The pendingDialogs map is
     // insertion-ordered — the first entry is the canonical one carried here; any
-    // extras are replayed explicitly by the caller (rare: concurrent dialogs).
+    // extras are re-routed explicitly by the caller (rare: concurrent dialogs).
     const sendWelcome = (client) => {
         const first = client.role === 'controller' ? pendingDialogs.values().next().value : undefined;
         sendFrame(client, {
             type: 'welcome',
             snapshot: buildSnapshot(),
             role: client.role,
+            controller_id: controllerId,
             pending_dialog: first !== undefined ? first.request : null,
             agentDir: getAgentDir(),
         }, true);
@@ -1413,15 +1432,13 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
         // after an idle brief was painted still sees it on first paint, and there is
         // no window between `welcome` and the replay where chrome renders blank.
     };
-    // Attach-mid-dialog replay: a dialog raised before this client attached is
-    // still pending (a peer detaching never cancels one — see makeBrokerUiContext),
-    // so a writable client joining afterwards is handed every in-flight dialog and
-    // becomes a full peer in the race to answer it. `welcome.pending_dialog` already
-    // carried the FIRST entry, so this replays only the extras.
-    const replayExtraPendingDialogsTo = (client) => {
-        const pend = [...pendingDialogs.values()];
-        for (let i = 1; i < pend.length; i++)
-            sendFrame(client, pend[i].request);
+    // T4 re-route on become-controller: a dialog raised while a prior controller was
+    // attached stays pending after that controller detaches (it is NOT cancelled —
+    // see makeBrokerUiContext / the M2 keep-pending fix), so whoever takes control
+    // next must be handed it to answer.
+    const reroutePendingDialogsTo = (client) => {
+        for (const d of pendingDialogs.values())
+            sendFrame(client, d.request);
     };
     // After a session-replacing op (new_session/switch_session/fork) the engine's
     // entire message history changed, so every attached viewer must rebuild from a
@@ -1494,15 +1511,14 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
     };
     // -------------------------------------------------------------------------
     // Extension-dialog routing (C2). makeBrokerUiContext owns the dialogPromise;
-    // here we just give it the three broker-side hooks it needs: the live set of
-    // writable clients (empty = nobody can answer → noOp fallback), how to forward a
-    // dialog to one of them, and the pending-dialog registry whichever one answers
-    // first settles through. The zero-writable path NEVER hangs and NEVER waits on a
-    // per-dialog timeout (design §5.4's timeout premise is false — see
-    // makeBrokerUiContext).
+    // here we just give it the three broker-side hooks it needs: who the current
+    // controller is (null = zero viewers → noOp fallback), how to forward a dialog
+    // to that controller, and the pending-dialog registry the controller answers
+    // through. The zero-viewer path NEVER hangs and NEVER waits on a per-dialog
+    // timeout (design §5.4's timeout premise is false — see makeBrokerUiContext).
     // -------------------------------------------------------------------------
     const uiContext = makeBrokerUiContext({
-        writable: writableClients,
+        controller: controllerClient,
         forward: (client, request) => sendFrame(client, request),
         pending: pendingDialogs,
         broadcast: broadcastUi,
@@ -1715,7 +1731,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
     runtime?.setRebindSession((candidateSession) => enqueueRebind(candidateSession, runtime.services));
     await enqueueRebind(session, services);
     // -------------------------------------------------------------------------
-    // Drive the engine on behalf of a writable client.
+    // Drive the engine on behalf of the single controller.
     // -------------------------------------------------------------------------
     // ---------------------------------------------------------------------------
     // Inline memory-reference inventory (design: inline memory references) — a
@@ -1933,23 +1949,21 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
         }
     };
     // -------------------------------------------------------------------------
-    // Command-op helpers (T3, §2.3). The write guard is hoisted here (it was
-    // inlined twice) and reused by all mutating ops; the ack/error replies
+    // Command-op helpers (T3, §2.3). The controller guard is hoisted here (it was
+    // inlined twice) and reused by all controller-only ops; the ack/error replies
     // and a few resolvers keep the per-op cases one-liners.
     // -------------------------------------------------------------------------
-    /** Reject a read-only client for a mutating op. The decision reads this
-     *  client's OWN fixed role — there is no shared writer slot, so any number of
-     *  writable clients pass concurrently. Returns true when rejected (the caller
-     *  should `break`). */
-    const notWritable = (client, what, id) => {
-        if (client.role === 'controller')
+    /** Reject a non-controller for a controller-only op. Returns true when rejected
+     *  (the caller should `break`). */
+    const notController = (client, what, id) => {
+        if (client.id === controllerId)
             return false;
         sendFrame(client, {
             type: 'error',
-            code: 'read_only',
-            message: `a read-only client may not ${what}`,
+            code: 'not_controller',
+            message: `only the controlling client may ${what}`,
             // M1: echo a correlated request's id so its pending-by-id promise rejects
-            // rather than hanging (e.g. a read-only `dequeue`).
+            // rather than hanging (e.g. a non-controller `dequeue`).
             ...(id !== undefined ? { id } : {}),
         });
         return true;
@@ -2069,7 +2083,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
     // -------------------------------------------------------------------------
     // Read-op data builders (operator-view picker payloads, §5 Unit A). Each is a
     // PURE getter read against the live engine session — the data a native pi
-    // picker's constructor needs, serialized for the viewer. Not role-gated
+    // picker's constructor needs, serialized for the viewer. Not controller-gated
     // (read-only, like get_commands), so the web bridge's observer connection can
     // populate pickers too.
     // -------------------------------------------------------------------------
@@ -2292,28 +2306,29 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
     const handleFrame = (client, frame) => {
         switch (frame.type) {
             case 'hello': {
-                // Admit at the REQUESTED role — unconditionally. `controller` is a
-                // per-client write capability, not a singleton slot, so an arriving
-                // writable client never demotes (or is demoted by) an already-attached
-                // one: N terminal panes and browser tabs are all writable at once.
-                //
-                // A repeated hello on an already-helloed socket must not RE-role it: the
-                // role is fixed for the socket's lifetime, so every downstream gate and
-                // every already-fanned-out dialog keep the authority the first welcome
-                // stated. A duplicate hello still re-sends the catch-up snapshot.
-                const firstHello = !client.helloed;
                 client.id = frame.client_id;
-                if (firstHello) {
-                    client.helloed = true;
-                    client.role = frame.role === 'controller' ? 'controller' : 'observer';
+                client.helloed = true;
+                // First-attach-wins (§5.3), but only against a LIVE controller: admit as
+                // controller iff none is currently held by a live client (controllerClient
+                // is liveness-aware, so a controllerId stranded on a departed peer reads as
+                // free here). Otherwise read-only observer.
+                if (frame.role === 'controller' && controllerClient() === null) {
+                    client.role = 'controller';
+                    controllerId = client.id;
+                }
+                else {
+                    client.role = 'observer';
                 }
                 sendWelcome(client);
-                if (firstHello)
-                    persistAttachState(); // a helloed viewer arrived
-                // welcome carried the FIRST pending dialog; replay any extras so a writable
-                // client attaching mid-dialog can answer every in-flight dialog.
-                if (client.role === 'controller')
-                    replayExtraPendingDialogsTo(client);
+                persistAttachState(); // a helloed viewer arrived
+                if (client.role === 'controller') {
+                    // welcome carried the FIRST pending dialog (T4); forward any extras so a
+                    // controller attaching mid-dialog can answer every in-flight dialog.
+                    const pend = [...pendingDialogs.values()];
+                    for (let i = 1; i < pend.length; i++)
+                        sendFrame(client, pend[i].request);
+                    broadcastControlChanged();
+                }
                 break;
             }
             case 'prompt':
@@ -2321,7 +2336,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
             case 'follow_up':
             case 'abort':
             case 'bash': {
-                if (notWritable(client, 'drive the engine'))
+                if (notController(client, 'drive the engine'))
                     break;
                 driveEngine(client, frame);
                 break;
@@ -2346,7 +2361,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
                 // race between acceptance (agent_start) and rejection; a steer route
                 // joins a turn already running, so no new agent_start is coming and its
                 // ack stays at routing time.
-                if (notWritable(client, 'drive the engine', frame.id))
+                if (notController(client, 'drive the engine', frame.id))
                     break;
                 const via = session.isStreaming ? 'steer' : 'prompt';
                 let delivered = false;
@@ -2385,17 +2400,46 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
                 break;
             }
             case 'extension_ui_response': {
-                if (notWritable(client, 'answer dialogs'))
+                if (notController(client, 'answer dialogs'))
                     break;
-                // First response for this id wins: `resolve` settles the entry and deletes
-                // it, so every later response from a peer that was also fanned this dialog
-                // finds nothing here and is a silent no-op.
                 pendingDialogs.get(frame.id)?.resolve(frame);
                 break;
             }
+            case 'request_control': {
+                // §D preemptive handoff (last-requester-wins): a control request ALWAYS
+                // succeeds, reassigning control to the requester and demoting the prior
+                // controller to observer. This makes a tmux pane and a web tab true peers —
+                // either can take control of a node the other currently drives — which is
+                // the broker-is-the-host invariant (the prior cooperative-only model could
+                // not preempt an idle/abandoned controller, the common case). The prior
+                // controller demotes itself on receiving the control_changed broadcast
+                // (viewer.ts already does this; the web client implements the same
+                // rule). Idempotent when the requester already holds control.
+                if (client.id === controllerId)
+                    break;
+                const prior = controllerClient();
+                if (prior !== null)
+                    prior.role = 'observer';
+                controllerId = client.id;
+                client.role = 'controller';
+                broadcastControlChanged();
+                reroutePendingDialogsTo(client); // T4: hand the new controller pending dialogs
+                break;
+            }
+            case 'release_control': {
+                if (client.id === controllerId) {
+                    controllerId = null;
+                    client.role = 'observer';
+                    // M2 (T4): do NOT cancel in-flight dialogs on release — keep them pending
+                    // under the broker-side default timeout so a brief release/reattach (or a
+                    // handoff to another observer) never loses an answerable dialog.
+                    broadcastControlChanged();
+                }
+                break;
+            }
             // --- extended engine-command ops (T3, §1.2 floor set) ------------------
             case 'set_model': {
-                if (notWritable(client, 'set the model'))
+                if (notController(client, 'set the model'))
                     break;
                 const requested = parseModelSpec(frame.model);
                 let model;
@@ -2442,7 +2486,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
                 break;
             }
             case 'deliver_custom_message': {
-                if (notWritable(client, 'deliver a custom message'))
+                if (notController(client, 'deliver a custom message'))
                     break;
                 // Never triggers a turn either way. `nextTurn` folds the message into
                 // whatever turn comes next (situational context); omitting it pushes
@@ -2462,7 +2506,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
                 break;
             }
             case 'cycle_model': {
-                if (notWritable(client, 'cycle the model'))
+                if (notController(client, 'cycle the model'))
                     break;
                 void session
                     .cycleModel(frame.direction)
@@ -2474,7 +2518,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
                 break;
             }
             case 'cycle_ladder': {
-                if (notWritable(client, 'cycle the model ladder'))
+                if (notController(client, 'cycle the model ladder'))
                     break;
                 // Resolve the next interleaved-ladder rung from the current model+thinking
                 // spec, then reuse the set_model path (registry resolve + thinking apply).
@@ -2523,7 +2567,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
                 break;
             }
             case 'cycle_thinking': {
-                if (notWritable(client, 'cycle the thinking level'))
+                if (notController(client, 'cycle the thinking level'))
                     break;
                 try {
                     session.cycleThinkingLevel();
@@ -2535,7 +2579,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
                 break;
             }
             case 'dequeue': {
-                if (notWritable(client, 'dequeue messages', frame.id))
+                if (notController(client, 'dequeue messages', frame.id))
                     break;
                 try {
                     const { steering, followUp } = session.clearQueue();
@@ -2547,7 +2591,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
                 break;
             }
             case 'set_thinking_level': {
-                if (notWritable(client, 'set the thinking level'))
+                if (notController(client, 'set the thinking level'))
                     break;
                 try {
                     session.setThinkingLevel(frame.level);
@@ -2559,7 +2603,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
                 break;
             }
             case 'set_auto_retry': {
-                if (notWritable(client, 'set auto-retry'))
+                if (notController(client, 'set auto-retry'))
                     break;
                 try {
                     session.setAutoRetryEnabled(frame.enabled);
@@ -2571,7 +2615,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
                 break;
             }
             case 'set_auto_compaction': {
-                if (notWritable(client, 'set auto-compaction'))
+                if (notController(client, 'set auto-compaction'))
                     break;
                 try {
                     session.setAutoCompactionEnabled(frame.enabled);
@@ -2583,7 +2627,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
                 break;
             }
             case 'compact': {
-                if (notWritable(client, 'compact the session'))
+                if (notController(client, 'compact the session'))
                     break;
                 void session
                     .compact(frame.instructions)
@@ -2592,7 +2636,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
                 break;
             }
             case 'set_session_name': {
-                if (notWritable(client, 'rename the session'))
+                if (notController(client, 'rename the session'))
                     break;
                 try {
                     session.setSessionName(frame.name);
@@ -2703,7 +2747,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
                 break;
             }
             case 'navigate_tree': {
-                if (notWritable(client, 'navigate the session tree'))
+                if (notController(client, 'navigate the session tree'))
                     break;
                 // navigateTree rewinds IN-PLACE (same session file, new leaf) and emits no
                 // relayed event, so every viewer must be re-snapshotted onto the rewound
@@ -2721,7 +2765,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
                 break;
             }
             case 'reload': {
-                if (notWritable(client, 'reload'))
+                if (notController(client, 'reload'))
                     break;
                 // A SUCCESSFUL reload invalidates the memoized ref inventory (work item
                 // 3) so the next read-op/submission re-walks the corpus, AND clears the
@@ -2740,7 +2784,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
                 break;
             }
             case 'export': {
-                if (notWritable(client, 'export the session'))
+                if (notController(client, 'export the session'))
                     break;
                 if (frame.format === 'jsonl') {
                     try {
@@ -2761,25 +2805,25 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
                 break;
             }
             case 'new_session': {
-                if (notWritable(client, 'start a new session'))
+                if (notController(client, 'start a new session'))
                     break;
                 runReplacement(client, 'new_session', (rt) => rt.newSession());
                 break;
             }
             case 'switch_session': {
-                if (notWritable(client, 'switch sessions'))
+                if (notController(client, 'switch sessions'))
                     break;
                 runReplacement(client, 'switch_session', (rt) => rt.switchSession(frame.path));
                 break;
             }
             case 'fork': {
-                if (notWritable(client, 'fork the session'))
+                if (notController(client, 'fork the session'))
                     break;
                 runReplacement(client, 'fork', (rt) => rt.fork(frame.entryId));
                 break;
             }
             case 'clone': {
-                if (notWritable(client, 'clone the session'))
+                if (notController(client, 'clone the session'))
                     break;
                 runReplacement(client, 'clone', async (rt) => {
                     const sm = session.sessionManager;
@@ -2796,7 +2840,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
                 break;
             }
             case 'share': {
-                if (notWritable(client, 'share the session'))
+                if (notController(client, 'share the session'))
                     break;
                 const tmpPath = join(tmpdir(), `pi-share-${Date.now()}.html`);
                 void session.exportToHtml(tmpPath)
@@ -2826,11 +2870,13 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
                 break;
             }
             case 'reload_auth': {
-                // Open to any client, observers included: reload_auth is an idempotent
-                // local re-read of the shared auth.json + a model-registry refresh. It
-                // does NOT steer the conversation, so there is nothing to role-gate —
-                // which is what lets the daemon's canvas-wide fan (one /login propagated
-                // to every live broker) ride an observer connection.
+                // Open to any client: reload_auth is an idempotent local re-read of the
+                // shared auth.json + a model-registry refresh. It does NOT steer the
+                // conversation, so there is nothing to gate behind controller. Gating it
+                // forced callers (notably the daemon's canvas-wide fan, which propagates
+                // a single /login to every live broker) to first request_control, which
+                // ALWAYS preempts — silently demoting any attached human to observer on
+                // every login. Letting an observer trigger this is the safer default.
                 try {
                     // pi 0.82: crouter's CredentialStore reads auth.json fresh under the
                     // lock on every call, so there is no cached credential view left to
@@ -2989,10 +3035,12 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
         const drop = () => {
             clients.delete(client);
             persistAttachState(); // a viewer disconnected
-            // A writable client detaching does NOT cancel in-flight dialogs — they stay
-            // pending under the broker-side default timeout, so a peer that is still
-            // attached (or one that attaches next and gets the replay) can still answer.
-            // Only an answer, the timeout, or an abort resolves one.
+            // M2 (T4): controller detach frees control but does NOT cancel in-flight
+            // dialogs — they stay pending under the broker-side default timeout so a
+            // brief detach/reattach (or a handoff to another observer who takes control)
+            // never loses an answerable dialog. Only the timeout or a new controller's
+            // answer resolves one.
+            releaseControlIfHeldBy(client);
         };
         socket.on('close', drop);
         socket.on('error', () => {
@@ -3551,33 +3599,26 @@ export function makeBrokerUiContext(deps) {
     // OPTIONAL on dialog opts, editor() takes none, and almost no real extension
     // passes one (permission-gate / confirm-destructive / plan-mode / subagent all
     // omit it). A timeout-reliant unattended node therefore deadlocks the agent
-    // turn FOREVER. So with NO WRITABLE client attached we fall back to the SDK's
-    // noOp UI behavior — resolve to the default (deny / cancel / undefined)
-    // IMMEDIATELY, never arming a timer, never waiting. With one or more, the dialog
-    // is fanned out to all of them under a broker-side timeout+abort, so viewers
-    // that attach but never answer cannot hang the turn either.
+    // turn FOREVER. So with ZERO viewers attached we fall back to the SDK's noOp UI
+    // behavior — resolve to the default (deny / cancel / undefined) IMMEDIATELY,
+    // never arming a timer, never waiting. (Phase 4 adds the WITH-viewer forwarding
+    // path, wrapped in a broker-side timeout+abort so a controller that attaches
+    // but never answers cannot hang the turn either.)
     const dialogPromise = (defaultValue, request, parse, opts) => {
         if (opts?.signal?.aborted)
             return Promise.resolve(defaultValue);
-        // Snapshot the writable set ONCE, at raise time — the fan-out targets and the
-        // zero-answerer decision must agree.
-        const targets = deps.writable();
-        // C2 (Wave-0, KEEP): nobody can answer at raise time → noOp, resolved at once.
-        // No timer, no wait, no deadlock.
-        if (targets.length === 0)
+        const controller = deps.controller();
+        // C2 (Wave-0, KEEP): no controller at raise time → noOp, resolved at once. No
+        // timer, no wait, no deadlock. This is the genuine zero-controller path.
+        if (controller === null)
             return Promise.resolve(defaultValue);
-        // At least one writable client: register the dialog FIRST (so a client that
-        // attaches mid-dialog gets it replayed and joins the race), fan it out to every
-        // target, and ALWAYS arm a broker-side timeout (C2 anti-deadlock): viewers that
-        // never answer — or all detach — can never hang the turn. Honor a shorter
-        // per-dialog timeout if the extension passed one; otherwise the broker default.
-        // On fire it resolves to the SAFE default (deny/cancel/undefined). A detach
-        // does NOT cancel this — only an answer, the timeout, or an abort.
-        //
-        // EVERY settlement path runs the same `cleanup` (drop the entry, so a later
-        // answer for this id is a no-op) and then broadcasts `extension_ui_dismiss`
-        // keyed to this id, so all peers close their copy of exactly this dialog and
-        // nothing else.
+        // A controller is attached: forward the dialog, register it (so a re-routed /
+        // re-attaching controller can answer it — T4), and ALWAYS arm a broker-side
+        // timeout (T4/C2 anti-deadlock): a controller that never answers — or detaches
+        // and is never replaced — can never hang the turn. Honor a shorter per-dialog
+        // timeout if the extension passed one; otherwise the broker default. On fire
+        // it resolves to the SAFE default (deny/cancel/undefined). NOTE: controller
+        // detach does NOT cancel this (M2) — only an answer, the timeout, or an abort.
         return new Promise((resolve) => {
             let timer;
             const cleanup = () => {
@@ -3590,10 +3631,10 @@ export function makeBrokerUiContext(deps) {
                 cleanup();
                 // The extension aborted this request out-of-band (e.g. an OAuth loopback
                 // callback won the race against a still-open manual-paste dialog). Tell
-                // every peer to tear down THIS overlay by id — an unanswered dialog whose
-                // broker entry we just dropped would otherwise linger onscreen with nothing
-                // left to answer it. Keyed to request.id so only the abandoned dialog is
-                // dismissed, never an unrelated one.
+                // the controller to tear down THIS overlay by id — an unanswered dialog
+                // whose broker entry we just dropped would otherwise linger onscreen with
+                // nothing left to answer it. Keyed to request.id so only the abandoned
+                // dialog is dismissed, never an unrelated one.
                 deps.broadcast({ type: 'extension_ui_dismiss', id: request.id });
                 resolve(defaultValue);
             };
@@ -3606,8 +3647,8 @@ export function makeBrokerUiContext(deps) {
             timer = setTimeout(() => {
                 cleanup();
                 // Same correlated teardown as onAbort: the broker resolved this dialog on
-                // its own timeout, so every peer's overlay (none of which has an
-                // independent timer) must be dismissed by id or it lingers forever.
+                // its own timeout, so the controller's overlay (which has no independent
+                // timer) must be dismissed by id or it lingers forever.
                 deps.broadcast({ type: 'extension_ui_dismiss', id: request.id });
                 resolve(defaultValue);
             }, ms);
@@ -3617,16 +3658,10 @@ export function makeBrokerUiContext(deps) {
                 request,
                 resolve: (r) => {
                     cleanup();
-                    // The first answer settled it; tell every OTHER client that was fanned
-                    // this dialog (and the answerer, for whom it is an idempotent no-op) to
-                    // close its copy. Without this, peers would sit on an overlay whose
-                    // answer can never arrive.
-                    deps.broadcast({ type: 'extension_ui_dismiss', id: request.id });
                     resolve(parse(r));
                 },
             });
-            for (const target of targets)
-                deps.forward(target, request);
+            deps.forward(controller, request);
         });
     };
     const noop = () => { };