@north-light/crouter 0.3.157 → 0.3.159

package/dist/clients/attach/input/controller.js

@@ -19,7 +19,7 @@ import { join } from 'node:path';
 import { BROKER_READ_CAPS, encodeFrame, } from '../../../core/runtime/broker-protocol.js';
 import { isBlockingDialog, renderDialog } from '../overlays/dialogs.js';
 import { readClipboardImage, writeClipboardImageToFile } from './clipboard-image.js';
-import { dispatchSlashCommand, isSlashCommand } from '../slash/dispatch.js';
+import { dispatchSlashCommand, isSlashCommand, readOnlySlashRefusal } from '../slash/dispatch.js';
 import { buildForkPicker, buildModelPicker, buildScopedModelsPicker, buildSessionPicker, buildSettingsPicker, buildTreePicker, } from '../overlays/pickers.js';
 import { buildMcpPicker, readMcpServers, startMcpServerAction, MCP_EMPTY_STATE_HINT } from '../overlays/mcp.js';
 import { buildFileReviewPicker } from '../overlays/file-review.js';
@@ -36,28 +36,28 @@ const DOUBLE_ESCAPE_MS = 500;
  *  as inline base64, so a paste can no longer push a frame toward this ceiling. */
 const MAX_FRAME_BYTES = BROKER_READ_CAPS.maxLineBytes - 4 * 1024 * 1024;
 /** ClientToBroker frame types that mutate the engine/session — everything the
- *  broker gates behind controller-only (`notController` in broker.ts) PLUS
- *  `request_control`/`release_control` (control-claim frames; no current UI
- *  path sends them, gated anyway for defense-in-depth) and `reload_auth`
- *  (open to any role server-side, but viewer-local login/logout are disabled
- *  entirely for remote below — this entry is belt-and-suspenders in case a
- *  future path routes it through onCommand). A REMOTE attach (`--canvas`) is
- *  a strictly VIEW-ONLY surface (Phase 3 review Major 1): even though the
- *  broker would itself reject these from an observer, the input layer must
- *  never even emit one — server-side rejection alone is not the contract.
+ *  broker gates behind a writable role (`read_only` in broker.ts), plus
+ *  `reload_auth`
+ *  (open to any role server-side, but viewer-local login/logout are unwired for
+ *  a read-only viewer — this entry is belt-and-suspenders in case a
+ *  future path routes it through onCommand). A read-only viewer — an observer
+ *  (`--observer`) or a REMOTE attach (`--canvas`, always an observer) — is
+ *  a strictly VIEW-ONLY surface: even though the broker would itself reject
+ *  these from an observer, the input layer must never even emit one —
+ *  server-side rejection alone is not the contract.
  *  `dequeue` is listed for documentation completeness even though it never
  *  reaches `emitCommand` (it rides the separate `onRequest` read-op channel —
- *  see `handleDequeue`'s own remote guard). Read-only frames (get_commands,
+ *  see `handleDequeue`'s own capability guard). Read-only frames (get_commands,
  *  list_models, list_sessions, get_tree, get_settings, list_scoped_models)
  *  and hello/bye/shutdown/extension_ui_response are deliberately absent —
  *  reads stay live for remote (pickers just never get the chance to select,
- *  see slash/dispatch.ts's REMOTE_SAFE_BUILTIN_NAMES gate). */
+ *  see slash/dispatch.ts's READ_ONLY_SAFE_BUILTIN_NAMES gate). */
 const DRIVE_FRAME_TYPES = new Set([
     'prompt', 'steer', 'follow_up', 'abort', 'bash',
     'set_model', 'cycle_model', 'cycle_ladder', 'cycle_thinking', 'set_thinking_level', 'dequeue',
     'set_auto_retry', 'set_auto_compaction', 'compact', 'new_session',
     'switch_session', 'fork', 'set_session_name', 'navigate_tree', 'reload',
-    'export', 'clone', 'share', 'request_control', 'release_control', 'reload_auth',
+    'export', 'clone', 'share', 'reload_auth',
 ]);
 export class InputController {
     tui;
@@ -93,22 +93,42 @@ export class InputController {
         this.hooks = hooks;
         this.wire();
     }
+    /** Why this viewer may not mutate the engine, or `undefined` when it may. The
+     *  ONE capability gate: a remote attach and an `--observer` attach are both
+     *  read-only, and the role is fixed at hello, so this answer cannot change
+     *  mid-session. */
+    readOnlyReason() {
+        if (this.hooks.remote === true)
+            return 'Read-only remote attach';
+        if ((this.hooks.role ?? 'controller') !== 'controller')
+            return 'Read-only observer attach';
+        return undefined;
+    }
     /** Central choke point for every command frame the input layer emits (direct
-     *  keybindings, emitDrive, and the slash-command/picker `send` sink). Local
-     *  attach (`hooks.remote` false/absent) is byte-for-byte unchanged. */
+     *  keybindings, emitDrive, and the slash-command/picker `send` sink). Returns
+     *  false when the gate refused the frame, so callers stop without emitting
+     *  it. A writable local attach is byte-for-byte unchanged. */
     emitCommand(frame) {
-        if (this.hooks.remote === true && DRIVE_FRAME_TYPES.has(frame.type)) {
-            this.notify('Read-only remote attach — cannot drive the engine');
-            return;
+        const reason = this.readOnlyReason();
+        if (reason !== undefined && DRIVE_FRAME_TYPES.has(frame.type)) {
+            this.notify(`${reason} — cannot drive the engine`);
+            return false;
         }
         this.hooks.onCommand(frame);
+        return true;
+    }
+    /** The model-ladder keybinding (alt+m / alt+shift+m), which viewer.ts's global
+     *  key listener owns rather than the editor's action table. Public so that
+     *  binding rides the gate above instead of going straight to the socket. */
+    cycleLadder(direction) {
+        this.emitCommand({ type: 'cycle_ladder', direction });
     }
     /** Render extension UI requests from the broker. Blocking dialogs route their
      *  answer back to the broker; non-blocking notify requests become the viewer's
      *  normal notice line and NOTHING else — a notify must never tear down an
      *  unrelated blocking dialog whose broker request is still pending. A dialog is
-     *  torn down only by (a) a NEW blocking dialog superseding it (control handoff
-     *  re-route), (b) its own answer, or (c) a correlated {@link dismissDialog}
+     *  torn down only by (a) a NEW blocking dialog superseding it, (b) its own
+     *  answer, or (c) a correlated {@link dismissDialog}
      *  from the broker (the request was aborted/timed out out-of-band). */
     attachDialog(req) {
         if (req.method === 'notify') {
@@ -218,6 +238,7 @@ export class InputController {
             nodeId: this.hooks.nodeId,
             profileId: this.hooks.profileId,
             remote: this.hooks.remote,
+            role: this.hooks.role,
             onGraph: this.hooks.onGraph,
             onQuit: this.hooks.onQuit,
             onCopy: this.hooks.onCopy,
@@ -241,7 +262,9 @@ export class InputController {
     // (via slashContext) AND by keybinding (onAction, below).
     // -------------------------------------------------------------------------
     /** Send a command frame to the broker (picker selection sink). */
-    send = (frame) => this.emitCommand(frame);
+    send = (frame) => {
+        this.emitCommand(frame);
+    };
     /** Fetch a picker payload (narrowed on `kind`), then build + show its overlay
      *  iff this open is still the latest (m4: a stale slow reply is dropped). Any
      *  failure — unwired channel, wrong kind, request error, or a throwing builder
@@ -426,9 +449,17 @@ export class InputController {
         if (!trimmed)
             return;
         if (isSlashCommand(trimmed)) {
+            const slashCtx = this.slashContext();
+            // A read-only viewer's refusal is surfaced BEFORE dispatch, so no command
+            // or engine frame is emitted.
+            const refusal = readOnlySlashRefusal(trimmed, slashCtx);
+            if (refusal !== undefined) {
+                this.notify(refusal);
+                return;
+            }
             // Recognized builtin/scoped-out → handled here; unrecognized falls through
             // and is sent to the engine as a prompt (extension command).
-            if (dispatchSlashCommand(trimmed, this.slashContext())) {
+            if (dispatchSlashCommand(trimmed, slashCtx)) {
                 this.editor.setText('');
                 return;
             }
@@ -479,7 +510,7 @@ export class InputController {
             ? { type: 'steer', text: expanded }
             : { type: 'prompt', text: expanded };
         if (!this.emitDrive(frame))
-            return; // too large — keep editor to trim
+            return; // refused or too large — no frame emitted
         this.editor.addToHistory(trimmed);
         this.editor.setText('');
         this.clearPastedImages();
@@ -567,8 +598,9 @@ export class InputController {
      *  (pi's `restoreQueuedMessagesToEditor`: queued text first, joined by blank
      *  lines). A read-AND-mutate op over the correlated request channel. */
     async handleDequeue() {
-        if (this.hooks.remote === true) {
-            this.notify('Read-only remote attach — cannot restore queued messages');
+        const reason = this.readOnlyReason();
+        if (reason !== undefined) {
+            this.notify(`${reason} — cannot restore queued messages`);
             return;
         }
         if (this.hooks.onRequest === undefined) {
@@ -599,8 +631,7 @@ export class InputController {
     }
     /** Send a drive frame iff the WHOLE encoded frame fits under MAX_FRAME_BYTES
      *  (the broker destroys the socket on any line over its 24 MiB read cap). Over
-     *  the ceiling → notify + refuse so the caller leaves the editor + pending
-     *  images intact for the user to trim, never a socket-destroying overflow. */
+     *  the ceiling → notify + refuse without sending a socket-destroying overflow. */
     emitDrive(frame) {
         let bytes;
         try {
@@ -615,8 +646,7 @@ export class InputController {
             this.notify(`Message too large to send (${mib} MiB) — shorten the text or remove an attached image`);
             return false;
         }
-        this.emitCommand(frame);
-        return true;
+        return this.emitCommand(frame);
     }
     async handlePaste() {
         try {

package/dist/clients/attach/overlays/dialogs.d.ts

@@ -1,8 +1,7 @@
 import { KeybindingsManager, type TUI } from '@earendil-works/pi-tui';
 import type { RpcExtensionUIRequest, RpcExtensionUIResponse } from '../../../core/runtime/broker-protocol.js';
 /** Handle for a rendered dialog: tear it down (without responding) when the
- *  request is superseded — e.g. the broker resolves it on its own timeout, or a
- *  control handoff re-routes it. */
+ *  request is superseded, answered, or dismissed by the broker. */
 export interface DialogHandle {
     dismiss(): void;
 }

package/dist/clients/attach/overlays/graph.d.ts

@@ -1,6 +1,7 @@
 import { type Component, type TUI } from '@earendil-works/pi-tui';
 import { type BindingResolution, type BindingId } from '../../../core/keybindings/index.js';
 import type { CanvasSource } from '../../../core/canvas/source.js';
+import type { ClientRole } from '../../../core/runtime/broker-protocol.js';
 import type { AttachPalette } from '../config.js';
 export declare class GraphOverlay implements Component {
     private readonly tui;
@@ -9,7 +10,9 @@ export declare class GraphOverlay implements Component {
     private readonly palette;
     private bindings;
     private readonly source;
+    private readonly role;
     private readonly onRefreshFailure;
+    private readonly onNotice;
     private handle;
     /** Manual fold OVERRIDES (h collapses → userCollapsed, l expands → userExpanded);
      *  both override the default activity-driven policy and survive open/close. */
@@ -29,7 +32,7 @@ export declare class GraphOverlay implements Component {
      *  default and makes Enter/r/m/x no-op instead of shelling local lifecycle
      *  commands against a remote graph row. See the file header. */
     private readonly remote;
-    constructor(tui: TUI, self: string, getAsks: () => Record<string, number>, palette: AttachPalette, bindings: BindingResolution<BindingId>, source: CanvasSource, onRefreshFailure?: (cause?: unknown) => void);
+    constructor(tui: TUI, self: string, getAsks: () => Record<string, number>, palette: AttachPalette, bindings: BindingResolution<BindingId>, source: CanvasSource, role?: ClientRole, onRefreshFailure?: (cause?: unknown) => void, onNotice?: (message: string) => void);
     /** The tmux-focus set for `isAttached`, fetched via crtrd (was nav-model's
      *  focusedNodeIds → listFocuses db read). Empty for a remote source (a remote
      *  node id may collide with a local focus row); a failed API call degrades to

package/dist/clients/attach/overlays/graph.js

@@ -59,7 +59,7 @@ const GRAPH_PRIMARY_LOCAL_HINTS = [
     ['crtr.graph.close-subtree', 'close'],
     ['crtr.graph.focus-manager', 'manager'],
 ];
-const GRAPH_PRIMARY_REMOTE_HINTS = [
+const GRAPH_PRIMARY_READ_ONLY_HINTS = [
     ['crtr.graph.dismiss', 'dismiss'],
 ];
 const GRAPH_NAV_HINTS = [
@@ -77,7 +77,9 @@ export class GraphOverlay {
     palette;
     bindings;
     source;
+    role;
     onRefreshFailure;
+    onNotice;
     handle;
     /** Manual fold OVERRIDES (h collapses → userCollapsed, l expands → userExpanded);
      *  both override the default activity-driven policy and survive open/close. */
@@ -97,14 +99,16 @@ export class GraphOverlay {
      *  default and makes Enter/r/m/x no-op instead of shelling local lifecycle
      *  commands against a remote graph row. See the file header. */
     remote;
-    constructor(tui, self, getAsks, palette, bindings, source, onRefreshFailure = () => { }) {
+    constructor(tui, self, getAsks, palette, bindings, source, role = 'controller', onRefreshFailure = () => { }, onNotice = () => { }) {
         this.tui = tui;
         this.self = self;
         this.getAsks = getAsks;
         this.palette = palette;
         this.bindings = bindings;
         this.source = source;
+        this.role = role;
         this.onRefreshFailure = onRefreshFailure;
+        this.onNotice = onNotice;
         this.remote = source instanceof RemoteCanvasSource;
     }
     /** The tmux-focus set for `isAttached`, fetched via crtrd (was nav-model's
@@ -415,7 +419,7 @@ export class GraphOverlay {
                 ['crtr.graph.confirm.cancel', 'cancel'],
             ]).join(' · ')}${RESET}`
             : `${DIM}${this.fitHints([
-                ...(this.remote ? GRAPH_PRIMARY_REMOTE_HINTS : GRAPH_PRIMARY_LOCAL_HINTS),
+                ...(this.remote || this.role !== 'controller' ? GRAPH_PRIMARY_READ_ONLY_HINTS : GRAPH_PRIMARY_LOCAL_HINTS),
                 ...GRAPH_NAV_HINTS,
             ], Math.max(1, width - 5))}${RESET}`; // budget matches borderRow's span
         // Frame the panel: title in the top border, hint in the bottom border, tree
@@ -555,13 +559,15 @@ export class GraphOverlay {
         }
         // Focus/revive/manager/close actions drive local lifecycle/focus (`crtr surface node focus` /
         // `crtr node lifecycle revive` / `crtr node lifecycle close`) against
-        // `this.cursorId` — a REMOTE graph row's id has no relationship to this
-        // machine's canvas.db (or, worse, collides with one that does), so all four
-        // no-op in remote mode instead of shelling a local mutation command against
-        // a remote id. Their hints are omitted remotely.
+        // `this.cursorId`. A remote graph row has no relationship to this machine's
+        // canvas, and an observer is read-only, so neither may shell a local action.
         if (this.matches('crtr.graph.focus', data)) {
             if (this.remote)
                 return;
+            if (this.role !== 'controller') {
+                this.onNotice('Read-only observer attach — cannot focus nodes');
+                return;
+            }
             if (this.cursorId !== undefined)
                 this.focusTarget(this.cursorId);
             this.close();
@@ -570,6 +576,10 @@ export class GraphOverlay {
         if (this.matches('crtr.graph.revive', data)) {
             if (this.remote)
                 return;
+            if (this.role !== 'controller') {
+                this.onNotice('Read-only observer attach — cannot revive nodes');
+                return;
+            }
             const target = this.cursorId;
             const node = target === undefined ? null : snapshot?.nodes.get(target) ?? null;
             if (target !== undefined && node !== null && node.status !== 'active' && node.status !== 'idle') {
@@ -581,6 +591,10 @@ export class GraphOverlay {
         if (this.matches('crtr.graph.focus-manager', data)) {
             if (this.remote)
                 return;
+            if (this.role !== 'controller') {
+                this.onNotice('Read-only observer attach — cannot focus nodes');
+                return;
+            }
             const mgr = snapshot?.managerOf.get(this.self);
             if (mgr !== undefined) {
                 this.focusTarget(mgr);
@@ -591,6 +605,10 @@ export class GraphOverlay {
         if (this.matches('crtr.graph.close-subtree', data)) {
             if (this.remote)
                 return;
+            if (this.role !== 'controller') {
+                this.onNotice('Read-only observer attach — cannot close nodes');
+                return;
+            }
             const target = this.cursorId ?? this.self;
             const n = snapshot?.nodes.get(target) ?? null;
             const nm = n !== null ? fullName(n) : shortId(target);

package/dist/clients/attach/session/context.d.ts

@@ -1,4 +1,5 @@
 import type { Container, TUI } from '@earendil-works/pi-tui';
+import type { ClientRole } from '../../../core/runtime/broker-protocol.js';
 import type { CanvasSource } from '../../../core/canvas/source.js';
 import type { NodeMeta } from '../../../core/canvas/types.js';
 import type { BrokerClient } from '../../../core/broker-client/index.js';
@@ -31,6 +32,12 @@ export interface AttachSession {
     /** THE single remote/read-only fact, derived once in `runAttach` from
      *  `--canvas` and threaded from here. No collaborator may re-derive it. */
     readonly remote: boolean;
+    /** THE single capability fact, resolved once in `runAttach` by
+     *  `resolveHelloRole(remote, observer)` and claimed in every hello (including
+     *  reconnects), so it can never be renegotiated mid-session. `'observer'`
+     *  makes this viewer read-only: no collaborator may emit a mutating frame or
+     *  drive the node out of band. */
+    readonly role: ClientRole;
     /** Viewer-LOCAL concerns only: `cwd` drives theming and this pane's own git
      *  status, and is the CLI's own cwd for a remote attach — never the remote
      *  node's directory. */

package/dist/clients/attach/session/frames.js

@@ -127,11 +127,6 @@ export function createFrameHandler(ctx, fx) {
                     fx.attachDialog(frame.pending_dialog);
                 break;
             }
-            case 'control_changed':
-                // Our own role follows from matching the broker's controller_id to the
-                // client_id we sent in `hello` — the reducer does that, and the footer
-                // repaint rides the role slice.
-                break;
             case 'model_changed': {
                 // The broker's own post-set_model/cycle_model announcement (pi emits no
                 // engine event for a model switch) already moved the footer's model
@@ -142,9 +137,7 @@ export function createFrameHandler(ctx, fx) {
                 break;
             }
             case 'error':
-                fx.setNotice(frame.code === 'not_controller'
-                    ? 'read-only — another viewer is the controller'
-                    : `error: ${frame.message}`);
+                fx.setNotice(frame.code === 'read_only' ? 'read-only' : `error: ${frame.message}`);
                 break;
             case 'ack':
                 handleAck(frame);

package/dist/clients/attach/session/input-wiring.d.ts

@@ -28,4 +28,4 @@ export interface InputWiringHooks {
     setChipColor: (color: string | null) => void;
 }
 /** Build the viewer's InputController with every hook answered. */
-export declare function createInputController(ctx: Pick<AttachSession, 'nodeId' | 'remote' | 'meta' | 'socket' | 'tui' | 'editor' | 'containers'>, km: KeybindingsManager, hooks: InputWiringHooks): InputController;
+export declare function createInputController(ctx: Pick<AttachSession, 'nodeId' | 'remote' | 'role' | 'meta' | 'socket' | 'tui' | 'editor' | 'containers'>, km: KeybindingsManager, hooks: InputWiringHooks): InputController;

package/dist/clients/attach/session/input-wiring.js

@@ -18,8 +18,13 @@ import { buildLoginPicker, buildLogoutPicker } from '../overlays/auth.js';
 import { defaultAgentDir } from '../config.js';
 /** Build the viewer's InputController with every hook answered. */
 export function createInputController(ctx, km, hooks) {
-    const { nodeId, remote, socket, tui, editor, containers } = ctx;
+    const { nodeId, remote, role, socket, tui, editor, containers } = ctx;
     const { setNotice } = hooks;
+    // The viewer's fixed capability, resolved once at hello: an `--observer`
+    // attach (and a remote one, which is always an observer) may read but never
+    // mutate. Every mutating hook below is wired only when this is true; the
+    // read-op channel (`onRequest`) and the read-only getters stay wired for all.
+    const writable = !remote && role === 'controller';
     // `/copy` — the last assistant message (ChatView keeps it current from both
     // the welcome snapshot and the live stream) → the system clipboard.
     const copyLastAssistant = () => {
@@ -35,14 +40,15 @@ export function createInputController(ctx, km, hooks) {
     // model), so they run entirely in this process and then tell the broker to
     // reload with a `reload_auth` frame.
     //
-    // A REMOTE attach (`--canvas`) disables both entirely (Phase 3 review Major 1,
-    // 1d): they target the LOCAL `auth.json` via `defaultAgentDir()`, the wrong
-    // host for a remote node. The read-only-command gate (slash/dispatch.ts)
-    // already blocks `/login` and `/logout` before dispatch — leaving these
-    // unwired is belt-and-suspenders, so there is no path to a `reload_auth`
-    // frame for remote even if something else called the hooks directly.
+    // A read-only viewer wires NEITHER. A REMOTE attach (`--canvas`) disables both
+    // because they target the LOCAL `auth.json` via `defaultAgentDir()`, the wrong
+    // host for a remote node (Phase 3 review Major 1, 1d); an OBSERVER because
+    // switching credentials and telling the broker to reload them mutates the
+    // engine's auth, which a read-only viewer must not do. Unwired here means the
+    // slash context carries no picker at all, so `/login` and `/logout` report
+    // themselves unavailable rather than reaching a `reload_auth` frame.
     const reloadAuth = () => socket.send({ type: 'reload_auth' });
-    const authPickers = remote
+    const authPickers = !writable
         ? {}
         : {
             openLoginPicker: () => {
@@ -64,6 +70,7 @@ export function createInputController(ctx, km, hooks) {
         nodeId,
         profileId: ctx.meta.profile_id ?? undefined,
         remote,
+        role,
         onGraph: hooks.toggleGraph,
         onNodeMetadata: hooks.openNodeMetadata,
         onQuit: hooks.quit,
@@ -93,10 +100,13 @@ export function createInputController(ctx, km, hooks) {
         // Dormant-node input: the node has no live broker, so a submitted prompt
         // cannot reach a socket. The reconnect supervisor reports dormancy and the
         // text is delivered as a wake message (revive + deliver) instead, so the
-        // still-open input box just works. Local only — a remote attach cannot
-        // drive, leaves `onDormantSubmit` unwired, and prompts fall through.
+        // still-open input box just works. Writable viewers only — a remote or
+        // observer attach cannot drive, leaves `onDormantSubmit` unwired, and
+        // prompts fall through. This is the one mutating path that never touches the
+        // broker (it goes to crtrd via `cliClient`), so leaving it wired for an
+        // observer would let a read-only viewer wake and message the node.
         isDormant: hooks.isDormant,
-        onDormantSubmit: remote ? undefined : (msgText) => {
+        onDormantSubmit: !writable ? undefined : (msgText) => {
             void (async () => {
                 try {
                     // Text typed into a node's box IS the human talking to it — mark it

package/dist/clients/attach/session/mode.d.ts

@@ -13,12 +13,13 @@ export declare function requestModeSwitch(cwd: string, nodeId: string, remote: b
  *  Owning both here is what keeps `mode` from being a mutable the key handler
  *  and the editor painter both reach into. */
 export interface ModeBadge {
-    /** Advance to the next mode and repaint. A REMOTE attach no-ops entirely
-     *  (there is no remote-safe mode-switch protocol), badge included. */
+    /** Advance to the next mode and repaint. A read-only viewer no-ops entirely,
+     *  badge included: a REMOTE attach has no remote-safe mode-switch protocol,
+     *  and an OBSERVER may not change the node's mode at all. */
     cycle: () => void;
 }
 /** Resolve the initial mode, paint the badge, and return the cycle verb. */
-export declare function createModeBadge(ctx: Pick<AttachSession, 'nodeId' | 'remote' | 'meta' | 'tui' | 'editor'>): ModeBadge;
+export declare function createModeBadge(ctx: Pick<AttachSession, 'nodeId' | 'remote' | 'role' | 'meta' | 'tui' | 'editor'>): ModeBadge;
 /** The badge chip painted for each mode: spec is blue, plan is amber, normal is
  *  unstyled (no badge chrome when there is nothing to say). */
 export declare function modeBadgeStyle(mode: Mode): (s: string) => string;

package/dist/clients/attach/session/mode.js

@@ -61,7 +61,7 @@ export function requestModeSwitch(cwd, nodeId, remote, mode, writeRequest = writ
 }
 /** Resolve the initial mode, paint the badge, and return the cycle verb. */
 export function createModeBadge(ctx) {
-    const { nodeId, remote, meta, tui, editor } = ctx;
+    const { nodeId, remote, role, meta, tui, editor } = ctx;
     let mode = resolveInitialMode(meta.cwd, nodeId, remote);
     const paint = () => {
         editor.mode = mode === 'normal' ? '' : mode;
@@ -70,6 +70,11 @@ export function createModeBadge(ctx) {
     paint();
     return {
         cycle: () => {
+            // The mode request rewrites how the node's engine behaves, so it rides the
+            // session's fixed capability like every other mutation: an observer reads
+            // the badge the broker publishes and changes nothing.
+            if (role !== 'controller')
+                return;
             const next = nextMode(mode);
             if (!requestModeSwitch(meta.cwd, nodeId, remote, next))
                 return;

package/dist/clients/attach/session/reconnect.d.ts

@@ -2,9 +2,9 @@ import type { ClientRole } from '../../../core/runtime/broker-protocol.js';
 import type { BrokerToClient } from '../../../core/runtime/broker-protocol.js';
 import type { AttachSession } from './context.js';
 export interface ReconnectHooks {
-    /** This viewer's CURRENT role, read at send time — see `sendHello`. */
-    role: () => ClientRole;
-    /** This viewer's stable client id, echoed by the broker to prove control. */
+    /** This viewer's fixed role, resolved from the original attach flags. */
+    role: ClientRole;
+    /** This viewer's stable client id, echoed by the broker in the hello. */
     clientId: string;
     /** Every broker frame, in wire order. */
     onFrame: (frame: BrokerToClient) => void;

package/dist/clients/attach/session/reconnect.js

@@ -23,16 +23,15 @@ export function createReconnect(ctx, hooks) {
     // `dead`/`canceled` keep the corpse.
     let finalizedDone = false;
     // The handshake the viewer sends on connect AND on every successful redial.
-    // After a broker refresh / crash-revive the fresh process has no controller
-    // and no memory of us, so re-`hello` reclaims our role and the `welcome`
-    // snapshot repaints full scrollback/state. Sends the CURRENT role, not the
-    // `--observer` flag we started with: if a `control_changed` demoted us at
-    // runtime, re-hello'ing as 'controller' would let us reclaim control from the
-    // new controller after a refresh — the demotion must survive the reconnect.
+    // After a broker refresh / crash-revive the fresh process has no memory of
+    // this client, so re-`hello` resumes the role chosen at the original attach
+    // and the `welcome` snapshot repaints full scrollback/state. The role is
+    // deliberately fixed for the lifetime of this viewer: local writable attaches
+    // stay writable, while observers stay observers across every redial.
     const sendHello = () => {
         socket.send({
             type: 'hello',
-            role: hooks.role(),
+            role: hooks.role,
             client_id: hooks.clientId,
             term: { cols: process.stdout.columns ?? 80, rows: process.stdout.rows ?? 24 },
         });

package/dist/clients/attach/session/state-sync.d.ts

@@ -35,4 +35,4 @@ export interface SessionStateSync {
      *  callers fold first, then notice. `off` collapses to the bare model name. */
     modelThinkingLabel: () => string | undefined;
 }
-export declare function createSessionStateSync(role: ClientRole, clientId: string, fx: StateSyncEffects): SessionStateSync;
+export declare function createSessionStateSync(role: ClientRole, fx: StateSyncEffects): SessionStateSync;

package/dist/clients/attach/session/state-sync.js

@@ -12,7 +12,7 @@
 // slice it leaves alone, so each repaint below is gated on a `!==` against the
 // previous value. No change flags, no repaint-everything.
 import { initialSessionState, reduce } from '../../../core/session-model/session-state.js';
-export function createSessionStateSync(role, clientId, fx) {
+export function createSessionStateSync(role, fx) {
     let session = initialSessionState(role);
     /** Repaint exactly the chrome whose SLICE of session state changed. */
     const renderDelta = (prev) => {
@@ -46,7 +46,7 @@ export function createSessionStateSync(role, clientId, fx) {
         state: () => session,
         fold: (frame) => {
             const prev = session;
-            session = reduce(session, frame, clientId);
+            session = reduce(session, frame);
             renderDelta(prev);
         },
         patchLocal: (patch) => {

package/dist/clients/attach/slash/dispatch.d.ts

@@ -1,5 +1,5 @@
 import type { AutocompleteItem, SlashCommand } from '@earendil-works/pi-tui';
-import type { BrokerSnapshot, ClientToBroker } from '../../../core/runtime/broker-protocol.js';
+import type { BrokerSnapshot, ClientRole, ClientToBroker } from '../../../core/runtime/broker-protocol.js';
 /** Everything a slash handler needs: the frame sink, a notice sink, the latest
  *  engine state (for read-only commands like `/session`), and the cwd (for the
  *  default `/export` path). */
@@ -19,6 +19,13 @@ export interface SlashContext {
      *  notifies + no-ops them instead of executing (see `REMOTE_UNSAFE_CANVAS_NAMES`
      *  below). Defaults to `false` so every existing local caller is unaffected. */
     remote?: boolean;
+    /** This viewer's FIXED capability, resolved once for the hello handshake
+     *  (`resolveHelloRole`) and never renegotiated. `'observer'` (`--observer`,
+     *  and every remote attach) makes the viewer read-only: the commands that
+     *  drive the engine or mutate the node through the crtr CLI are refused with
+     *  a notice, while the read-only/viewer-local ones stay live. Absent →
+     *  `'controller'`, so every existing writable caller is unaffected. */
+    role?: ClientRole;
     /** The canvas node this viewer is attached to — used by `/promote` (passed
      *  as `--node`). Falls back to `CRTR_NODE_ID` when absent; if neither is set
      *  `/promote` notifies and no-ops. (Unit Q wires this from `runAttach`.) */
@@ -76,6 +83,11 @@ export declare const CANVAS_SLASH_COMMANDS: ReadonlyArray<{
     name: string;
     description: string;
 }>;
+/** The same gate, entered from raw editor text: the InputController asks BEFORE
+ *  dispatching so a refused command is reported without reaching command
+ *  dispatch. Unrecognized (extension) commands answer `undefined` here — they
+ *  ride the normal `prompt` path, which the controller's own drive gate covers. */
+export declare function readOnlySlashRefusal(text: string, ctx: SlashContext): string | undefined;
 /** Every leading-command name this viewer consumes ENTIRELY locally — the
  *  message never reaches the engine as prose, whether dispatched or blocked
  *  with a notice (a remote-unsafe canvas/builtin command still returns