@north-light/crouter 0.3.157 → 0.3.158

package/dist/api/client.d.ts

@@ -1,5 +1,5 @@
 import type { DaemonRestartDTO, HealthDTO, StatusDTO } from './dto/health.js';
-import type { ArtifactListDTO, ArtifactsQuery, ContextListDTO, CreateNodeRequest, ListNodesQuery, NodeDetailDTO, NodeSnapshotDTO, NodeSummaryDTO, TranscriptDTO, TranscriptQuery } from './dto/nodes.js';
+import type { ArtifactListDTO, ArtifactsQuery, ContextListDTO, CreateNodeRequest, ListNodesQuery, NodeDetailDTO, NodeSessionDTO, NodeSnapshotDTO, NodeSummaryDTO, TranscriptDTO, TranscriptQuery } from './dto/nodes.js';
 import type { InterruptResultDTO, MessageResultDTO, SendMessageRequest } from './dto/messages.js';
 import type { PushReportRequest, PushReportResultDTO, ReportDTO, ReportsQuery } from './dto/reports.js';
 import type { CloseRequest, CloseResultDTO, PromoteRequest, RelaunchRootResultDTO, ReviveRequest, ReviveResultDTO, WaitRequest, YieldRequest } from './dto/lifecycle.js';
@@ -125,6 +125,9 @@ export declare class CrtrClient {
     getReports(id: string, q?: ReportsQuery): Promise<ReportDTO[]>;
     getTranscript(id: string, q?: TranscriptQuery): Promise<TranscriptDTO>;
     getSnapshot(id: string): Promise<NodeSnapshotDTO>;
+    /** The node's conversation exactly as it ran — raw `.jsonl` bytes plus the
+     *  assembled system prompt. For exports; `getSnapshot` is for renderers. */
+    getSession(id: string): Promise<NodeSessionDTO>;
     getArtifacts(id: string, q?: ArtifactsQuery): Promise<ArtifactListDTO>;
     getContext(id: string): Promise<ContextListDTO>;
     /** Read an absolute host path as UTF-8 (capped, `truncated` when clipped) for

package/dist/api/client.js

@@ -219,6 +219,11 @@ export class CrtrClient {
     getSnapshot(id) {
         return this.request('GET', routes.nodeSnapshot(this.nodePath(id)));
     }
+    /** The node's conversation exactly as it ran — raw `.jsonl` bytes plus the
+     *  assembled system prompt. For exports; `getSnapshot` is for renderers. */
+    getSession(id) {
+        return this.request('GET', routes.nodeSession(this.nodePath(id)));
+    }
     getArtifacts(id, q) {
         return this.request('GET', withQuery(routes.nodeArtifacts(this.nodePath(id)), q));
     }

package/dist/api/dto/broker.d.ts

@@ -31,7 +31,7 @@ export interface BrokerWelcomeFrame<M = unknown> {
 }
 /**
  * The broker-control frames a relay consumer reads: `welcome` (catch-up snapshot)
- * and `error`. The broker interleaves others (display_*, control_changed, ack, …)
+ * and `error`. The broker interleaves others (display_*, ack, …)
  * under non-colliding `type` discriminants; a relay mapper drops those through its
  * `default` arm untyped, so they are not enumerated here.
  */

package/dist/api/dto/nodes.d.ts

@@ -145,6 +145,21 @@ export interface NodeSnapshotDTO {
     }[];
     captured_at: IsoTime;
 }
+/** `GET /v1/nodes/{id}/session` — the node's conversation exactly as it ran:
+ *  the raw session `.jsonl` bytes plus the assembled system prompt. Unlike
+ *  `NodeSnapshotDTO` nothing is reconstructed or flattened, so every
+ *  session-tree entry, cycle, branch, and custom message role survives. This is
+ *  what an export/download wants; `/snapshot` is what a renderer wants. */
+export interface NodeSessionDTO {
+    node_id: NodeIdDTO;
+    /** Absolute path (inside the node's host) of the file the bytes came from. */
+    session_file: string;
+    /** Verbatim `.jsonl` contents. */
+    session_jsonl: string;
+    /** Assembled system prompt as last captured, or `null` if never written. */
+    system_prompt: string | null;
+    captured_at: IsoTime;
+}
 /** `GET /v1/nodes/{id}/transcript` query. */
 export interface TranscriptQuery {
     limit?: number;

package/dist/api/routes.d.ts

@@ -9,6 +9,7 @@ export declare const routes: {
     readonly reviveAll: () => string;
     readonly node: (id: string) => string;
     readonly nodeSnapshot: (id: string) => string;
+    readonly nodeSession: (id: string) => string;
     readonly nodeTranscript: (id: string) => string;
     readonly nodeContext: (id: string) => string;
     readonly nodeArtifacts: (id: string) => string;

package/dist/api/routes.js

@@ -25,6 +25,7 @@ export const routes = {
     node: (id) => `${V}/nodes/${id}`,
     // Node reads
     nodeSnapshot: (id) => `${V}/nodes/${id}/snapshot`,
+    nodeSession: (id) => `${V}/nodes/${id}/session`,
     nodeTranscript: (id) => `${V}/nodes/${id}/transcript`,
     nodeContext: (id) => `${V}/nodes/${id}/context`,
     nodeArtifacts: (id) => `${V}/nodes/${id}/artifacts`,

package/dist/builtin-views/chat/core.mjs

@@ -45,10 +45,8 @@
  * @property {string|null} target
  * @property {ChatRole} desiredRole
  * @property {any|null} channel
- * @property {string|null} clientId
  * @property {ChatConn} conn
  * @property {ChatRole} role
- * @property {string|null} controllerId
  * @property {ChatSession|null} session
  * @property {ChatTranscript} transcript
  * @property {string} draft
@@ -374,12 +372,10 @@ const core = {
     const target = typeof opts.target === 'string' && opts.target.trim() !== '' ? opts.target : null;
     return {
       target,
-      desiredRole: 'controller',
+      desiredRole: opts.role === 'observer' ? 'observer' : 'controller',
       channel: null,
-      clientId: null,
       conn: 'idle',
       role: 'observer',
-      controllerId: null,
       session: null,
       transcript: initialTranscript(),
       draft: '',
@@ -418,7 +414,6 @@ const core = {
         ctx.set((prev) => ({
           ...prev,
           channel,
-          clientId: channel.id,
           conn: 'connecting',
         }));
       } catch (err) {
@@ -436,7 +431,6 @@ const core = {
       ctx.set((prev) => ({
         ...prev,
         channel: prev.channel ?? channel,
-        clientId: prev.clientId ?? asMaybeText(channel.id),
         conn: 'connecting',
       }));
       ctx.signal.setStatus('connected — waiting for welcome');
@@ -506,8 +500,7 @@ const core = {
           ctx.set((prev) => ({
             ...prev,
             conn: 'open',
-            controllerId: asMaybeText(frame.controller_id),
-            role: frame.controller_id === prev.clientId ? 'controller' : (frame.role ?? 'observer'),
+            role: frame.role ?? prev.desiredRole,
             session,
             transcript,
             pendingDialog: frame.pending_dialog ?? null,
@@ -519,34 +512,14 @@ const core = {
           return;
         }
 
-        case 'control_changed': {
-          ctx.set((prev) => {
-            const nextRole = frame.controller_id === prev.clientId ? 'controller' : 'observer';
-            const changed = nextRole !== prev.role;
-            const demoted = prev.role === 'controller' && nextRole === 'observer';
-            let next = {
-              ...prev,
-              controllerId: asMaybeText(frame.controller_id),
-              role: nextRole,
-              desiredRole: demoted ? 'observer' : prev.desiredRole,
-            };
-            if (changed) {
-              next = notice(next, nextRole === 'controller' ? 'control changed — you are controller' : 'control changed — read-only', 'info');
-            }
-            return next;
-          });
-          return;
-        }
-
         case 'model_changed': {
           ctx.set((prev) => patchSession(prev, { model: asMaybeText(frame.model) }));
           return;
         }
 
         case 'error': {
-          if (frame.code === 'not_controller') {
-            const text = 'read-only — take control before sending';
-            ctx.set((prev) => ({ ...prev, role: 'observer' }));
+          if (frame.code === 'read_only') {
+            const text = 'read-only — sending is disabled';
             ctx.set((prev) => notice(prev, text, 'action'));
             ctx.signal.setBanner(text, 'action');
             return;
@@ -659,7 +632,7 @@ const core = {
         return;
       }
       if (ctx.state.role !== 'controller') {
-        const text = 'read-only — take control before sending';
+        const text = 'read-only — sending is disabled';
         ctx.set((prev) => notice(prev, text, 'action'));
         ctx.signal.setBanner(text, 'action');
         return;
@@ -672,7 +645,7 @@ const core = {
     /** @param {any} ctx */
     abort(ctx) {
       if (ctx.state.role !== 'controller') {
-        const text = 'read-only — take control before sending';
+        const text = 'read-only — sending is disabled';
         ctx.set((prev) => notice(prev, text, 'action'));
         ctx.signal.setBanner(text, 'action');
         return;
@@ -686,24 +659,6 @@ const core = {
       ctx.state.channel.send({ type: 'abort' });
     },
 
-    /** @param {any} ctx */
-    requestControl(ctx) {
-      ctx.set((prev) => ({ ...prev, desiredRole: 'controller' }));
-      if (ctx.state.channel && ctx.state.conn === 'open') ctx.state.channel.send({ type: 'request_control' });
-    },
-
-    /** @param {any} ctx */
-    releaseControl(ctx) {
-      ctx.set((prev) => ({ ...prev, desiredRole: 'observer' }));
-      const channel = ctx.state.channel;
-      if (channel && ctx.state.conn === 'open') {
-        channel.send({ type: 'release_control' });
-      }
-      // Close and reopen as observer so transport-level auto-reconnect cannot
-      // silently reclaim controller role (transports capture role at open time).
-      void ctx.dispatch('reconnect');
-    },
-
     /** @param {any} ctx @param {string|undefined} id */
     clearNotice(ctx, id) {
       ctx.set((prev) => {

package/dist/builtin-views/chat/tui.mjs

@@ -165,12 +165,6 @@ function statusSpans(state) {
   spans.push({ text: ' · role ', style: { dim: true } });
   spans.push({ text: state.role, style: state.role === 'controller' ? { fg: '32', bold: true } : { fg: '33', bold: true } });
 
-  spans.push({ text: ' · ctrl ', style: { dim: true } });
-  spans.push({
-    text: state.controllerId ? (state.controllerId === state.clientId ? 'you' : shortId(state.controllerId) || 'other') : '—',
-    style: state.controllerId === state.clientId ? { fg: '32', bold: true } : { fg: '36', bold: true },
-  });
-
   const model = maybeText(state.session?.model);
   const sessionName = maybeText(state.session?.sessionName);
   if (model || sessionName) {
@@ -332,7 +326,9 @@ export function render(state, draw, content) {
   paintTail(draw, noticeRect, noticeLines(state).slice(-noticeCount));
 
   const draft = tailClip(state.draft, Math.max(0, content.width - 2));
-  draw.spans(composerRow, content.col, [
+  draw.spans(composerRow, content.col, state.role === 'observer' ? [
+    { text: 'Read-only', style: { fg: '33', bold: true } },
+  ] : [
     { text: '> ', style: { fg: '33', bold: true } },
     { text: draft, style: undefined },
     { text: draft ? '█' : '', style: { fg: '33' } },
@@ -346,11 +342,9 @@ const hasNotice = (state) => state.notices.length > 0;
 /** @param {ChatState} state */
 const hasDraft = (state) => state.draft.length > 0;
 /** @param {ChatState} state */
-const isObserver = (state) => state.role === 'observer';
-/** @param {ChatState} state */
-const isController = (state) => state.role === 'controller';
+const canConnect = (state) => state.target != null && state.conn !== 'no-broker' && state.conn !== 'no-node';
 /** @param {ChatState} state */
-const canCompose = (state) => state.target != null && state.conn !== 'no-broker' && state.conn !== 'no-node';
+const canCompose = (state) => canConnect(state) && state.role === 'controller';
 
 /** @type {import('../../core/view/contract.js').KeyBinding<ChatState>[]} */
 export const keymap = [
@@ -359,9 +353,7 @@ export const keymap = [
   { bindingId: 'crtr.view.chat.contextual-cancel', intent: 'abort', when: isControllerStreaming },
   { bindingId: 'crtr.view.chat.contextual-cancel', intent: 'clearNotice', when: hasNotice, payload: (state) => state.notices[state.notices.length - 1]?.id },
   { bindingId: 'crtr.view.chat.contextual-cancel', intent: 'setDraft', when: hasDraft, payload: () => '' },
-  { bindingId: 'crtr.view.chat.reconnect', intent: 'reconnect', when: canCompose, hint: { label: 'reconnect' } },
-  { bindingId: 'crtr.view.chat.request-control', intent: 'requestControl', when: isObserver, hint: { label: 'control' } },
-  { bindingId: 'crtr.view.chat.release-control', intent: 'releaseControl', when: isController, hint: { label: 'yield' } },
+  { bindingId: 'crtr.view.chat.reconnect', intent: 'reconnect', when: canConnect, hint: { label: 'reconnect' } },
   { bindingId: 'crtr.view.chat.quit', intent: 'quit', hint: { label: 'quit' } },
 ];
 

package/dist/builtin-views/chat/web.jsx

@@ -260,12 +260,10 @@ export default function Chat({ state, dispatch }) {
   const streaming = state.session?.isStreaming === true;
   const canSend = state.channel != null && state.conn === 'open' && state.role === 'controller' && state.draft.trim() !== '';
   const canAbort = state.channel != null && state.conn === 'open' && state.role === 'controller' && streaming;
-  const controlLabel = state.role === 'controller' ? 'Release control' : 'Request control';
-  const controlIntent = state.role === 'controller' ? 'releaseControl' : 'requestControl';
   const placeholder = state.conn !== 'open'
     ? 'Waiting for connection…'
     : state.role === 'observer'
-      ? 'Take control before sending…'
+      ? 'Read-only'
       : streaming
         ? 'Type a steer…'
         : 'Type a message…';
@@ -278,7 +276,6 @@ export default function Chat({ state, dispatch }) {
         <Pill label="role" value={state.role} cls={state.role === 'controller' ? 'border-cyan-200 bg-cyan-50 text-cyan-700' : 'border-slate-200 bg-slate-50 text-slate-700'} />
         {model ? <Pill label="model" value={model} cls="border-violet-200 bg-violet-50 text-violet-700" /> : null}
         {sessionName ? <Pill label="session" value={sessionName} cls="border-slate-200 bg-slate-50 text-slate-700" /> : null}
-        {state.controllerId ? <Pill label="controller" value={state.controllerId} cls="border-slate-200 bg-slate-50 text-slate-700" /> : null}
         {typeof state.contextTokens === 'number' ? <Pill label="tokens" value={String(state.contextTokens)} cls="border-slate-200 bg-slate-50 text-slate-700" /> : null}
         {state.transcript.activity ? <Pill label="activity" value={state.transcript.activity} cls="border-amber-200 bg-amber-50 text-amber-800" /> : null}
         {state.queued.length ? <Pill label="queued" value={state.queued.join(' · ')} cls="border-slate-200 bg-slate-50 text-slate-700" /> : null}
@@ -286,9 +283,6 @@ export default function Chat({ state, dispatch }) {
           <button type="button" className="rounded-lg border border-slate-200 bg-white px-3 py-1.5 text-sm text-slate-700 hover:bg-slate-50" onClick={() => dispatch('reconnect')}>
             Reconnect
           </button>
-          <button type="button" className="rounded-lg border border-slate-200 bg-white px-3 py-1.5 text-sm text-slate-700 hover:bg-slate-50" onClick={() => dispatch(controlIntent)}>
-            {controlLabel}
-          </button>
         </div>
       </div>
 
@@ -331,6 +325,7 @@ export default function Chat({ state, dispatch }) {
       <div className="rounded-2xl border border-slate-200 bg-white p-3 shadow-sm">
         <textarea
           value={state.draft}
+          readOnly={state.role === 'observer'}
           onChange={(e) => dispatch('setDraft', e.target.value)}
           onKeyDown={(e) => {
             if (e.key === 'Enter' && !e.shiftKey) {

package/dist/clients/attach/__tests__/oauth-dialog-lifecycle.test.js

@@ -120,7 +120,7 @@ test('extension_ui_dismiss tears down ONLY the overlay whose request id matches'
     ic.dismissDialog('oauth-manual-1');
     assert.equal(hides.length, 1, 'a repeat dismiss must not double-tear-down');
 });
-test('a new blocking dialog still supersedes the previous one (control-handoff re-route unaffected)', () => {
+test('a new blocking dialog still supersedes the previous one (correlated dismissal remains isolated)', () => {
     const { ic, hides } = buildController();
     ic.attachDialog(inputDialog('dialog-a'));
     ic.attachDialog(inputDialog('dialog-b'));

package/dist/clients/attach/chrome/roster.d.ts

@@ -1,6 +1,6 @@
 import type { AttachSession } from '../session/context.js';
 /** The slice of the session the roster reads. */
-export type RosterSession = Pick<AttachSession, 'nodeId' | 'remote' | 'canvasSource' | 'tui' | 'pal' | 'editor' | 'containers'>;
+export type RosterSession = Pick<AttachSession, 'nodeId' | 'remote' | 'role' | 'canvasSource' | 'tui' | 'pal' | 'editor' | 'containers'>;
 export interface RosterHooks {
     /** Live per-node human-ticket counts — read fresh on every rebuild, since the
      *  viewer's attention poll reassigns the map behind us. */

package/dist/clients/attach/chrome/roster.js

@@ -55,7 +55,7 @@ function initialPaneActive() {
     }
 }
 export function createRoster(s, hooks) {
-    const { editor, tui, pal, nodeId, remote, canvasSource } = s;
+    const { editor, tui, pal, nodeId, remote, role, canvasSource } = s;
     const reports = s.containers.reports;
     let items = [];
     let selKey; // undefined ⇒ roster inactive (editor owns the cursor)
@@ -144,6 +144,10 @@ export function createRoster(s, hooks) {
         if (item === undefined || remote)
             return;
         if (item.kind === 'human') {
+            if (role !== 'controller') {
+                hooks.setNotice('Read-only observer attach — cannot open the human inbox');
+                return;
+            }
             exit();
             execFile('hl', ['inbox', 'open'], () => { });
             return;
@@ -163,6 +167,10 @@ export function createRoster(s, hooks) {
             exit();
             return;
         } // already viewing this one
+        if (role !== 'controller') {
+            hooks.setNotice('Read-only observer attach — cannot focus nodes');
+            return;
+        }
         const pane = process.env['TMUX_PANE'];
         if (pane === undefined || pane === '') {
             hooks.setNotice('cannot swap — no tmux pane');

package/dist/clients/attach/command.js

@@ -13,10 +13,10 @@ import { mark } from '../../core/timing.js';
 const attachToLeaf = defineLeaf({
     name: 'to',
     description: 'attach an interactive terminal viewer to a node (reviving it if dormant)',
-    whenToUse: 'you want to WATCH or DRIVE a headless node live in this pane — it connects over the node\'s unix socket to the broker hosting the engine and renders the same chat stream, letting you type prompts (as the controller) or follow read-only (as an observer). A DORMANT node is revived first: crtrd runs reviveNode server-side, then the viewer streams over the broker\'s socket. One controller drives; extra viewers are read-only. The configured detach shortcuts leave the engine running',
+    whenToUse: 'you want to WATCH or DRIVE a headless node live in this pane — it connects over the node\'s unix socket to the broker hosting the engine and renders the same chat stream. Normal local attaches are writable; use --observer for read-only, or --canvas for a remote read-only view. A DORMANT node is revived first: crtrd runs reviveNode server-side, then the viewer streams over the broker\'s socket. The configured detach shortcuts leave the engine running',
     help: {
         name: 'attach to',
-        summary: 'attach a terminal viewer to a headless node\'s running broker (controller by default, --observer for read-only); configured detach shortcuts leave the engine running',
+        summary: 'attach a terminal viewer to a headless node\'s running broker (writable by default, --observer for read-only); configured detach shortcuts leave the engine running',
         params: [
             {
                 kind: 'positional',
@@ -30,7 +30,7 @@ const attachToLeaf = defineLeaf({
                 type: 'bool',
                 required: false,
                 default: false,
-                constraint: 'Attach READ-ONLY: never claim control even if it is free. Default: drive (claim control if available, else fall back to read-only).',
+                constraint: 'Attach READ-ONLY: request the observer role. Default local attaches request the writable controller role.',
             },
             {
                 kind: 'flag',
@@ -51,7 +51,7 @@ const attachToLeaf = defineLeaf({
         outputKind: 'object',
         effects: [
             'Takes over the current pane in raw mode and renders the node\'s live engine stream until you use a configured detach shortcut or the broker exits.',
-            'As controller: sends prompts/steers/dialog answers to the engine over the socket. As observer: read-only.',
+            'As a writable controller: sends prompts/steers/dialog answers to the engine over the socket. As observer: read-only. Multiple writable local viewers may drive the same broker.',
             'A dormant node is revived server-side (crtrd runs reviveNode) before the viewer connects; this LOCAL process NEVER spawns pi and NEVER writes the session — it holds only a socket to the broker.',
             'Outside a TTY (piped): prints a short notice and exits 0 — attach is an interactive program, not a pipe stage.',
         ],
@@ -89,7 +89,7 @@ export function registerAttach() {
         help: {
             name: 'attach',
             summary: 'attach a terminal viewer to a headless node\'s running broker',
-            model: 'The branch opens a viewer in the current pane. A TTY is required; piped invocation prints a notice and exits. By default it claims control and drives the engine; --observer follows read-only. One controller plus any number of observers may watch a node. Configured detach shortcuts detach cleanly and the engine runs on. A dormant node is revived server-side (crtrd runs reviveNode) before the viewer connects. If the broker exits, the viewer holds the pane and auto-reconnects — through a yield/refresh relaunch, and across dormancy until the node wakes again — reporting "broker gone" and exiting only when the node is terminal (done/dead/canceled) or deleted. This local process NEVER spawns pi or writes the session — it holds only a socket to the broker. --canvas <name> is the escape hatch for a node hosted on a different machine\'s canvas — see the leaf\'s own -h.',
+            model: 'The branch opens a viewer in the current pane. A TTY is required; piped invocation prints a notice and exits. Normal local attaches request the writable controller role; --observer and --canvas are read-only. Multiple local writable viewers may watch and drive one broker. Configured detach shortcuts detach cleanly and the engine runs on. A dormant node is revived server-side (crtrd runs reviveNode) before the viewer connects. If the broker exits, the viewer holds the pane and auto-reconnects — through a yield/refresh relaunch, and across dormancy until the node wakes again — reporting "broker gone" and exiting only when the node is terminal (done/dead/canceled) or deleted. This local process NEVER spawns pi or writes the session — it holds only a socket to the broker. --canvas <name> is the escape hatch for a node hosted on a different machine\'s canvas — see the leaf\'s own -h.',
         },
         children: [attachToLeaf],
     });

package/dist/clients/attach/input/controller.d.ts

@@ -1,6 +1,6 @@
 import type { CustomEditor } from '@earendil-works/pi-coding-agent';
 import type { Component, KeybindingsManager, TUI } from '@earendil-works/pi-tui';
-import { type BrokerDataFrame, type BrokerSnapshot, type ClientToBroker, type RpcExtensionUIRequest, type RpcExtensionUIResponse } from '../../../core/runtime/broker-protocol.js';
+import { type BrokerDataFrame, type ClientRole, type BrokerSnapshot, type ClientToBroker, type RpcExtensionUIRequest, type RpcExtensionUIResponse } from '../../../core/runtime/broker-protocol.js';
 import type { ReadOpRequest } from '../../../core/broker-client/index.js';
 import { type Picker, type PickerControls } from '../overlays/pickers.js';
 export interface InputControllerHooks {
@@ -21,9 +21,15 @@ export interface InputControllerHooks {
     profileId?: string;
     /** OPTIONAL: true for a REMOTE attach (`crtr surface attach --canvas`) —
      *  forwarded to the slash context so it can structurally omit/no-op the
-     *  local-only native canvas commands (`/promote`, `/resume-node`, `/context`).
+     *  local-only native canvas commands (`/promote`, `/resume-node`, `/context`),
+     *  and (with {@link InputControllerHooks.role}) one half of the drive gate.
      *  Defaults to `false` (local, unchanged) when absent. */
     remote?: boolean;
+    /** OPTIONAL: this viewer's FIXED capability, resolved once for the hello
+     *  handshake (`resolveHelloRole`) and never renegotiated. `'observer'` makes
+     *  the viewer read-only: no drive frame is emitted, while reads (`onRequest`,
+     *  `get_commands`, the pickers' fetches) stay live. Absent → `'controller'`. */
+    role?: ClientRole;
     /** OPTIONAL: toggle the GRAPH overlay — forwarded to the slash context so
      *  `/graph` opens/closes it (Unit Q wires it from runAttach). */
     onGraph?: () => void;
@@ -99,16 +105,26 @@ export declare class InputController {
     /** Monotonic paste counter — the `N` in `[Image #N]`. */
     private pasteSeq;
     constructor(tui: TUI, editor: CustomEditor, keybindings: KeybindingsManager, hooks: InputControllerHooks);
+    /** 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. */
+    private readOnlyReason;
     /** 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. */
     private emitCommand;
+    /** 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: 'forward' | 'backward'): void;
     /** 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: RpcExtensionUIRequest): void;
     /** Broker-driven correlated dismissal: the broker resolved this request itself
@@ -182,8 +198,7 @@ export declare class InputController {
     private handleDequeue;
     /** 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. */
     private emitDrive;
     private handlePaste;
     /** Register an image path in the paste registry and splice a clean `[Image #N]`