@robota-sdk/agent-ui-web 3.2.1 → 3.3.1

package/src/hooks/useSessionClient.ts

@@ -1,11 +1,12 @@
 /**
- * GUI-005 — the transport-neutral session reducer for the GUI presentation layer. Reconstructs conversation
+ * The transport-neutral session reducer for the GUI presentation layer. Reconstructs conversation
  * state from the wire `TServerMessage` stream, independent of HOW the bytes arrive (a `TMakeSessionClient`
  * factory over `{onMessage, onStatusChange}`). The core is **generic over its status type** (default
  * `TConnectionStatus`) so a surface with extra connection states (e.g. the browser WebRTC surface) can widen it
  * WITHOUT this core depending on that surface's types — keeping the dependency direction acyclic.
  */
 
+import { isObserverMessageType } from '@robota-sdk/agent-transport';
 import { useState, useEffect, useRef, useCallback } from 'react';
 
 import { excludedCommandMessage, isExcludedCommand } from './excluded-commands.js';
@@ -53,7 +54,7 @@ import type {
   TPermissionResultValue,
 } from '@robota-sdk/agent-interface-session';
 import type { IExecutionWorkspaceSnapshot } from '@robota-sdk/agent-interface-execution';
-import type { TServerMessage } from '@robota-sdk/agent-transport';
+import type { TServerMessage, TSessionSurfaceRole } from '@robota-sdk/agent-transport';
 
 export type {
   IActiveTool,
@@ -82,7 +83,7 @@ function nextSilentCommandRequestId(): string {
 }
 
 /**
- * #3288: a finished turn's text and tool calls, in the order they actually happened — a running
+ * A finished turn's text and tool calls, in the order they actually happened — a running
  * turn accumulates these alongside (not instead of) the legacy `streamingText`/`activeTools` live
  * view, and `finishTurn` flushes them as SEPARATE conversation entries in order, instead of one
  * tools-block followed by one merged text block. Consecutive tool calls with no text between them
@@ -117,7 +118,7 @@ function pushToolStartSegment(segments: TTurnSegment[], tool: IActiveTool): TTur
 }
 
 /**
- * #3288: attribute a `tool_end` to its call by executionId first — two same-named parallel calls
+ * Attribute a `tool_end` to its call by executionId first — two same-named parallel calls
  * can finish out of start order, and matching by name+running alone would close whichever running
  * call of that name is found first, not the one that actually finished. Falls back to name+running
  * only when the event carries no executionId (legacy fixtures / hosts that predate it).
@@ -188,7 +189,7 @@ function applyToolEndToSegments(segments: TTurnSegment[], state: IToolState): TT
 }
 
 /**
- * #3288: the files an Edit/Write call touched during the turn, aggregated by path — the "Changed
+ * The files an Edit/Write call touched during the turn, aggregated by path — the "Changed
  * files" row's data. `diffLines` keeps the LATEST edit's diff (what a click on the file opens); the
  * +/- counts sum every edit to that path within the turn.
  */
@@ -220,7 +221,7 @@ function activeToolFromHistoricalState(state: IToolState): IActiveTool {
 }
 
 /**
- * #3288 §2: turns the server's chronological `IHistoryDisplaySegment[]` (a reload/reconnect/resume
+ * Turns the server's chronological `IHistoryDisplaySegment[]` (a reload/reconnect/resume
  * replay) into the SAME `TConversationEntry[]` shape a live turn's `finishTurn` produces — reusing its
  * exact segment-accumulation and "Changed files" logic, so the two paths cannot draw the turn/grouping
  * boundary differently. A `'text', role: 'user'` segment is both its own entry AND the turn boundary:
@@ -272,6 +273,10 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
   const [status, setStatus] = useState<TStatus>('disconnected' as TStatus);
   // The app-view requests read this to refuse at once when no connection exists to answer them.
   const statusRef = useRef<TStatus>('disconnected' as TStatus);
+  // The role the host gave this connection; null until it answers and again once the connection drops.
+  const [role, setRole] = useState<TSessionSurfaceRole | null>(null);
+  const roleRef = useRef<TSessionSurfaceRole | null>(null);
+  const isObserving = useCallback((): boolean => roleRef.current === 'observe', []);
   const [messages, setMessages] = useState<TConversationEntry[]>([]);
   const [activeTools, setActiveTools] = useState<IActiveTool[]>([]);
   const [streamingText, setStreamingText] = useState('');
@@ -284,15 +289,15 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
   const [sessionName, setSessionName] = useState<string | null>(null);
   const [sessionNotices, setSessionNotices] = useState<readonly ISessionNotice[]>([]);
   const [commandCatalog, setCommandCatalog] = useState<TCommandCatalog | null>(null);
-  // #3282 §4e: `send` (below) reads this on every `command` message to catch an excluded command —
+  // `send` (below) reads this on every `command` message to catch an excluded command —
   // a ref (not the state above) so `send`'s identity never changes as the catalog arrives or is
   // refreshed, matching every other value a stable callback in this file reads this way.
   const commandCatalogRef = useRef<TCommandCatalog | null>(null);
   const [sessionStatus, setSessionStatus] = useState<TSessionStatus | null>(null);
-  // #3289 §3: learned from the first frame the server sends this connection, so its own messages and
+  // Learned from the first frame the server sends this connection, so its own messages and
   // prompts never carry a "from" label — only ANOTHER driver's do.
   const [ownDriverId, setOwnDriverId] = useState<TDriverId | null>(null);
-  // #3282 §4e: `/help` opens the GUI's own Help sheet — it never reaches the session (`send` below
+  // `/help` opens the GUI's own Help sheet — it never reaches the session (`send` below
   // catches it), so there is no round trip and no stale terminal-style text dump to replace.
   const [helpOpen, setHelpOpen] = useState(false);
   const openHelp = useCallback((): void => setHelpOpen(true), []);
@@ -302,7 +307,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
   const streamingTextRef = useRef('');
   // The tools of the running turn, mirrored so the turn's end can keep them in the conversation.
   const activeToolsRef = useRef<IActiveTool[]>([]);
-  // #3288: the running turn's text/tools in the order they happened — see `TTurnSegment` above.
+  // The running turn's text/tools in the order they happened — see `TTurnSegment` above.
   const turnSegmentsRef = useRef<TTurnSegment[]>([]);
   // A screen this surface's command asked for: it answers the command in place of the command's own
   // reply — with the "not available" line (`text`), or with nothing when the screen opened (null).
@@ -323,7 +328,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
   }, []);
   /**
    * End the running turn: its text and tool calls stay in the conversation as SEPARATE entries, in
-   * the order they happened (#3288) — not one tools-block grouped ahead of a single merged reply.
+   * the order they happened — not one tools-block grouped ahead of a single merged reply.
    */
   const finishTurn = useCallback(
     (toolStatus: (tool: IActiveTool) => IActiveTool['status']): void => {
@@ -344,7 +349,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
           appendEntry({ id: segment.id, role: 'assistant', content: segment.text });
         }
       }
-      // #3288: a turn that changed files ends with one compact summary row, after everything else.
+      // A turn that changed files ends with one compact summary row, after everything else.
       const changedFiles = collectChangedFiles(segments);
       if (changedFiles.length > 0) {
         appendEntry({ id: nextId(), role: 'changed-files', files: changedFiles });
@@ -354,7 +359,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
   );
   // Commands this surface sent whose result has not come back — a screen request pairs with one.
   const commandsInFlightRef = useRef(0);
-  // #3282 §2 (part 2): the `requestId`s of commands sent via `sendCommandSilently`, still awaiting
+  // The `requestId`s of commands sent via `sendCommandSilently`, still awaiting
   // their `command_result`. The wire already correlates a command with its reply by `requestId` (see
   // `TClientMessage`'s `command` / `TServerMessage`'s `command_result` in `@robota-sdk/agent-transport`)
   // — a plain `send` command and a `sendCommandSilently` command can be outstanding at once, and only
@@ -375,18 +380,21 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
   const executionDetailInputRef = useRef<string | null>(null);
   const send = useCallback(
     (msg: TClientMessage): void => {
+      // A frame an observer may not send never leaves, so nothing may start waiting for its reply.
+      // The surface's own answers (`/help`, an excluded command) still run below.
+      const refused = isObserving() && !isObserverMessageType(msg.type);
       if (msg.type === 'send-background-task') {
-        if (executionDetailInputRef.current !== null) return;
+        if (refused || executionDetailInputRef.current !== null) return;
         executionDetailInputRef.current = msg.taskId;
         setExecutionDetailInput({ taskId: msg.taskId, status: 'pending' });
       }
       if (msg.type === 'command') {
-        // #3282 §4e: `/help` is the GUI's own Help sheet — never sent to the session.
+        // `/help` is the GUI's own Help sheet — never sent to the session.
         if (msg.name === 'help') {
           setHelpOpen(true);
           return;
         }
-        // #3282 §4e: a command the GUI leaves out on purpose is caught here, before the session ever
+        // A command the GUI leaves out on purpose is caught here, before the session ever
         // sees it — its own plain sentence answers in place of the session's refusal, exactly like a
         // typed command's own result would (same entry shape, same place in the conversation). The
         // catalog entry (when known) carries `runner`/`surfaces`, so a client-only command excluded
@@ -403,15 +411,17 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
           });
           return;
         }
+        if (refused) return;
         commandsInFlightRef.current += 1;
       }
+      if (refused) return;
       if (msg.type === 'switch-session' || msg.type === 'new-session') {
         sessionChangesInFlightRef.current += 1;
         if (msg.requestId !== undefined) sessionChangeRequestIdsRef.current.add(msg.requestId);
       }
       clientRef.current?.send(msg);
     },
-    [appendEntry],
+    [appendEntry, isObserving],
   );
   /** One session change this surface asked for has been answered. */
   const settleSessionChange = useCallback((requestId?: string): void => {
@@ -419,7 +429,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
     if (requestId !== undefined) sessionChangeRequestIdsRef.current.delete(requestId);
   }, []);
   /**
-   * #3282 §2 (part 2): run a command the same way `send` does, but flag it as controls-triggered —
+   * Run a command the same way `send` does, but flag it as controls-triggered —
    * the model/mode/effort pop-up menus use this instead of `send` directly, so their change is
    * confirmed by the control's own label (via the `get-status` refresh `command_result` already
    * triggers) rather than a conversation card. A typed `/command` still goes through plain `send`
@@ -428,7 +438,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
    * `TClientMessage` — giving `command` a `requestId` there would let ANY caller of `send` opt a typed
    * command into silence, which is exactly what this must not allow.
    *
-   * #3282 §4e: `send` also intercepts `help` and an excluded command before either reaches the wire —
+   * `send` also intercepts `help` and an excluded command before either reaches the wire —
    * for `help` that opens the sheet regardless of how it was asked for, but an excluded command's
    * interception adds a VISIBLE info card, defeating the silence this function promises. Every current
    * caller (model/mode/effort) names neither, so this is dormant, not exercised — a future caller must
@@ -453,18 +463,18 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
   const { handleProjectMessage, ...projectPanelState } = useProjectPanelState(send);
   const isConnected = useCallback((): boolean => statusRef.current === 'connected', []);
   const { handleAppViewMessage, rejectPendingAppRequests, readAppView, callAppTool } =
-    useAppViewRequests(send, isConnected);
+    useAppViewRequests(send, isConnected, isObserving);
   const {
     handleSessionsMessage,
     canListSessions,
     markCurrent,
     armRestore,
     ...sessionDirectoryState
-  } = useSessionDirectoryState(send);
+  } = useSessionDirectoryState(send, isObserving);
   const { requestSessions, setSessionSidebarOpen } = sessionDirectoryState;
   const { handleSettingsMessage, openSettings, refreshSettings, ...settingsState } =
     useSettingsState(send);
-  // #3282 §4b: read inside `handleMessage` via a ref, never `settingsState.settingsOpen` directly —
+  // Read inside `handleMessage` via a ref, never `settingsState.settingsOpen` directly —
   // that reactive value would have to sit in `handleMessage`'s own dependency array, which sits in
   // the connection effect's dependency array below: opening/closing Settings would give
   // `handleMessage` a new identity each time, tearing down and reopening the WebSocket underneath it.
@@ -486,7 +496,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
 
   const handleMessage = useCallback(
     (msg: TServerMessage): void => {
-      // ARCH-2164: touching the exhaustive registry here keeps every decoded variant tied to an
+      // Touching the exhaustive registry here keeps every decoded variant tied to an
       // explicit GUI ownership decision, including variants intentionally handled by focused views.
       void SERVER_MESSAGE_HANDLING[msg.type];
       if (handleUsageMessage(msg)) return;
@@ -498,14 +508,19 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
       if (handleSessionsMessage(msg)) return;
       if (handleSettingsMessage(msg)) return;
       if (handleAgentDefinitionsMessage(msg)) return;
-      // #3282 §4 part b-3: exclusively owns `background_tasks` (the Scheduled group's roster); a
+      // Exclusively owns `background_tasks` (the Scheduled group's roster); a
       // schedule write instead rides the generic `command`/`cancel-background-task` messages, so
       // for THOSE types this always returns false — it only refreshes on top of whatever else those
       // types already do below, never in place of it.
       if (handleSchedulesMessage(msg)) return;
       switch (msg.type) {
+        case 'surface_role': {
+          roleRef.current = msg.role;
+          setRole(msg.role);
+          break;
+        }
         case 'messages': {
-          // #3288 §2: `display` is the server's projection of this same history into tool rows,
+          // `display` is the server's projection of this same history into tool rows,
           // diffs and "Changed files" — a reload/reconnect/resume replay renders THAT. `display` is
           // absent only for a host that predates it; that host still gets a working (text-only)
           // transcript, exactly what this branch always did.
@@ -538,7 +553,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
           const next = streamingTextRef.current + msg.delta;
           streamingTextRef.current = next;
           setStreamingText(next);
-          // #3288: also track WHERE this text sits relative to the turn's tool calls, for finishTurn.
+          // Also track WHERE this text sits relative to the turn's tool calls, for finishTurn.
           turnSegmentsRef.current = appendTextDeltaToSegments(turnSegmentsRef.current, msg.delta);
           break;
         }
@@ -555,7 +570,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
         }
         case 'tool_end': {
           const { state } = msg;
-          // #3288: attribute to the ONE matching running call (executionId-first) — never map over
+          // Attribute to the ONE matching running call (executionId-first) — never map over
           // every running same-named entry, which would close all of them at once.
           updateActiveTools((prev) => {
             const idx = findRunningToolIndex(prev, state);
@@ -572,7 +587,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
           setExecutionWorkspace(msg.snapshot);
           break;
         }
-        // #3288 §1: a Stop that did not take effect (e.g. the task/loop had already finished) is
+        // A Stop that did not take effect (e.g. the task/loop had already finished) is
         // worth telling the operator; a success shows itself through the snapshot update above.
         case 'background_task_control_result': {
           if (msg.action === 'send' && executionDetailInputRef.current === msg.taskId) {
@@ -596,7 +611,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
           }
           break;
         }
-        // #3280 §2: the prompt queued behind a running turn — shown above the composer, editable
+        // The prompt queued behind a running turn — shown above the composer, editable
         // and removable (`cancel-queue`). `pending: null` means nothing waits; the row disappears.
         case 'pending': {
           setQueuedPrompt(
@@ -607,12 +622,12 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
         case 'permission_request':
         case 'ask_request':
         case 'prompt_resolved': {
-          // REMOTE-007/009: the paired owner renders + answers its own prompts (local == remote).
+          // The paired owner renders + answers its own prompts (local == remote).
           setPendingPrompts((prev) => applyPromptEvent(prev, msg));
           break;
         }
         case 'ui_intent': {
-          // #3189: `/resume` asks for the session picker — the sidebar, when the host lists sessions.
+          // `/resume` asks for the session picker — the sidebar, when the host lists sessions.
           if (guiScreenForUiIntent(msg.event.intent) === 'session-sidebar' && canListSessions()) {
             setSessionSidebarOpen(true);
             requestSessions();
@@ -624,7 +639,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
             }
             break;
           }
-          // #3282 §4a: `/settings` asks for the Settings screen — always available on this surface.
+          // `/settings` asks for the Settings screen — always available on this surface.
           if (guiScreenForUiIntent(msg.event.intent) === 'settings') {
             openSettings();
             if (commandsInFlightRef.current > 0) {
@@ -635,7 +650,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
             }
             break;
           }
-          // #3282 §4 part b-2: `/plugin` asks for the plugin manager — the Settings screen's
+          // `/plugin` asks for the plugin manager — the Settings screen's
           // Plugins section, the way `show-settings` opens the screen itself above.
           if (guiScreenForUiIntent(msg.event.intent) === 'settings-plugins') {
             openSettings('plugins');
@@ -647,7 +662,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
             }
             break;
           }
-          // #3282 §4 part b-3: `/agent` (bare) asks for the switcher — always available on this
+          // `/agent` (bare) asks for the switcher — always available on this
           // surface, unlike the session picker, which needs a host that lists sessions.
           if (guiScreenForUiIntent(msg.event.intent) === 'agent-switcher') {
             openAgentSwitcher();
@@ -659,8 +674,8 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
             }
             break;
           }
-          // CMD-004 Stage D: a command this surface issued requested a screen the GUI does not have.
-          // The command's result follows; the unavailable line answers it (TC-05, never silent).
+          // A command this surface issued requested a screen the GUI does not have.
+          // The command's result follows; the unavailable line answers it (never silent).
           const unavailable = {
             name: uiIntentCommandName(msg.event.intent),
             text: describeUiIntentForGui(msg.event.intent),
@@ -679,14 +694,14 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
           }
           break;
         }
-        // CMD-004 Stage E: broadcast session events — a rename/clear executed by the HOST (from any
+        // Broadcast session events — a rename/clear executed by the HOST (from any
         // surface, co-driving included) is reflected here; never a silent drop.
         case 'session_renamed': {
           setSessionName(msg.event.name);
           requestSessions();
           break;
         }
-        // #3189: the host made another session current — drop what this one showed, re-read it all.
+        // The host made another session current — drop what this one showed, re-read it all.
         case 'session_switched': {
           rejectPendingAppRequests('The active session changed.');
           settleSessionChange();
@@ -747,7 +762,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
           ]);
           break;
         }
-        // #3189: a new or switch this surface asked for was refused; the reason is the toast, and
+        // A new or switch this surface asked for was refused; the reason is the toast, and
         // commands in flight are untouched. Only the client that asked is told.
         case 'session_change_failed': {
           if (
@@ -763,7 +778,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
           ]);
           break;
         }
-        // #3289 §1: a row's rename landed — refresh the listing so its title (or the live one, if it
+        // A row's rename landed — refresh the listing so its title (or the live one, if it
         // was current) is current everywhere it shows.
         case 'session_renamed_in_list': {
           requestSessions();
@@ -776,7 +791,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
           ]);
           break;
         }
-        // #3289 §1: a row was deleted. If it was this surface's own session, `session_switched`
+        // A row was deleted. If it was this surface's own session, `session_switched`
         // already arrived (the host switches away before answering) and reset the conversation; this
         // only needs the listing refreshed so the row is gone everywhere it shows.
         case 'session_deleted': {
@@ -865,7 +880,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
           send({ type: 'get-status' });
           send({ type: 'get-commands' });
           commandsInFlightRef.current = Math.max(0, commandsInFlightRef.current - 1);
-          // #3282 §4b: a successful `/provider` command run through the raw command path (Add, Edit,
+          // A successful `/provider` command run through the raw command path (Add, Edit,
           // Duplicate — Use/Model/Delete already return a fresh snapshot from their own
           // `update-settings` reply) changes the "Providers & Models" list; refresh it if the screen
           // is open, the same way `get-status` above refreshes the model/mode chips. Never touches
@@ -873,13 +888,13 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
           if (msg.name === 'provider' && msg.success && settingsOpenRef.current) {
             refreshSettings();
           }
-          // #3282 §2 (part 2): identify silence by THIS reply's own `requestId`, not by position or
+          // Identify silence by THIS reply's own `requestId`, not by position or
           // count — see `silentCommandRequestIdsRef` above. No `requestId` (an older host, or a typed
           // command) always falls through to `silent = false`, never the reverse.
           const silent =
             msg.requestId !== undefined && silentCommandRequestIdsRef.current.delete(msg.requestId);
-          // #3282 §4 part b-3: a selection made in the agent switcher sheet — its own plain
-          // confirmation line answers it, never a conversation card (issue #3282 §4's decided design).
+          // A selection made in the agent switcher sheet — its own plain
+          // confirmation line answers it, never a conversation card.
           if (resolveSwitchResult(msg.requestId, msg)) break;
           const unavailable = pendingIntentRef.current;
           pendingIntentRef.current = null;
@@ -898,7 +913,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
           }
           // A command that starts a turn (a skill) says nothing itself; the turn is its answer.
           if (msg.message.trim().length === 0) break;
-          // #3282 §2 (part 2): a change made through a status control confirms itself through the
+          // A change made through a status control confirms itself through the
           // control's own label (the `get-status` refresh above lands it) — no conversation card. A
           // failure still needs saying, as a plain notice rather than a card, and the label is left
           // unchanged since nothing actually applied. A typed command (plain `send`) keeps its card
@@ -924,7 +939,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
         case 'complete':
         case 'interrupted': {
           send({ type: 'get-status' });
-          // #3280 §2: the turn ending can advance the queue (its next entry now runs) or, if this
+          // The turn ending can advance the queue (its next entry now runs) or, if this
           // was an abort, drop it entirely (`abort()` clears the whole queue) — either way the
           // composer's queued-message row is stale until this reply refreshes it.
           send({ type: 'get-pending' });
@@ -984,6 +999,10 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
     const onStatusChange = (next: TStatus): void => {
       statusRef.current = next;
       setStatus(next);
+      if (next !== 'connected') {
+        roleRef.current = null;
+        setRole(null);
+      }
       // A reply lost with the connection never arrives; the views waiting on one learn that now.
       if (next !== 'connected') {
         rejectPendingAppRequests();
@@ -1002,9 +1021,11 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
         sessionChangesInFlightRef.current = 0;
         sessionChangeRequestIdsRef.current.clear();
         pendingIntentRef.current = null;
+        // First, so its reply precedes the session listing the reconnect restore reads.
+        client.send({ type: 'get-surface-role' });
         client.send({ type: 'get-commands' });
         client.send({ type: 'get-status' });
-        // #3280 §2: a reconnect that lands back on the SAME session (the common case) fires no
+        // A reconnect that lands back on the SAME session (the common case) fires no
         // `session_switched` — its own `get-pending` would be missed — so ask here too, or a stale
         // `queuedPrompt` from before the drop keeps showing (with working Edit/Remove) until the
         // turn it was queued behind happens to end.
@@ -1015,7 +1036,16 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
         requestSchedules();
       }
     };
-    const client = makeClient({ onMessage: handleMessage, onStatusChange });
+    const inner = makeClient({ onMessage: handleMessage, onStatusChange });
+    // The host is the authority; this only keeps an observer from sending what the host would refuse.
+    const client: ISessionClientHandle = {
+      connect: () => inner.connect(),
+      disconnect: () => inner.disconnect(),
+      send: (msg) => {
+        if (roleRef.current === 'observe' && !isObserverMessageType(msg.type)) return;
+        inner.send(msg);
+      },
+    };
     clientRef.current = client;
     client.connect();
     return () => {
@@ -1045,6 +1075,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
     commandCatalog,
     sessionStatus,
     ownDriverId,
+    role,
     send,
     sendCommandSilently,
     pendingPrompts,
@@ -1077,7 +1108,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
 export function useWsSession(
   url: string,
 ): IWsSessionState<TConnectionStatus> & { connectionLost: boolean } {
-  // Issue #3280 §5: retries gave up — the runtime is not coming back by itself. A presentation layer
+  // Retries gave up — the runtime is not coming back by itself. A presentation layer
   // (e.g. `SessionSurface`) reads this to show a banner instead of a callback-driven screen swap.
   const [connectionLost, setConnectionLost] = useState(false);
   const makeClient = useCallback<TMakeSessionClient<TConnectionStatus>>(

package/src/index.ts

@@ -23,7 +23,7 @@ export type {
   TSessionListing,
   TSessionsError,
 } from './hooks/session-client-types.js';
-// Issue #3280 §5: a host that can restart the runtime calls this before reloading the page, so the
+// A host that can restart the runtime calls this before reloading the page, so the
 // first session listing after reconnecting can switch back to the session the person was in.
 export { rememberSessionForRestore } from './hooks/use-session-directory.js';
 
@@ -46,7 +46,7 @@ export type {
 export { applyPromptEvent, permissionResponse, askResponse } from './hooks/prompt-state.js';
 export type { TPendingPrompt } from './hooks/prompt-state.js';
 
-// ── UI-intent (command screen-request) state — CMD-004 Stage D ──
+// ── UI-intent (command screen-request) state — ──
 export { describeUiIntentForGui, guiScreenForUiIntent } from './hooks/ui-intent-state.js';
 
 // ── Presentation components ─────────────────────────────────
@@ -60,12 +60,12 @@ export { SessionSurface, CenteredChrome } from './components/SessionSurface.js';
 export type { IComposerHandle, IPickedFile } from './components/Composer.js';
 export { SessionSidebar } from './components/SessionSidebar.js';
 export { SessionMonitor } from './components/SessionMonitor.js';
-// #3282 §4a: the shared modal-shell primitive (also consumed by #3282 §2's mode-change confirmation
-// and #3289 §1's session-delete confirmation) and the Settings screen it backs.
+// The shared modal-shell primitive (also consumed by the mode-change confirmation
+// and the session-delete confirmation) and the Settings screen it backs.
 export { Dialog, ConfirmDialog } from './components/Dialog.js';
 export type { IDialogProps, IConfirmDialogProps } from './components/Dialog.js';
 export { SettingsScreen } from './components/SettingsScreen.js';
-// #3282 §4e: the Help sheet `/help` opens instead of the terminal-style text list.
+// The Help sheet `/help` opens instead of the terminal-style text list.
 export { HelpSheet } from './components/HelpSheet.js';
 // Pieces of a surface's chrome, not roots: render them inside a `agent-ui` scope.
 export { ProductMark, ProductWordmark } from './components/Brand.js';

package/src/schedule-view.ts

@@ -1,5 +1,5 @@
 /**
- * #3282 §4 part b-3 — plain-words presentation for the Agents panel's "Scheduled" group. Never an
+ * Plain-words presentation for the Agents panel's "Scheduled" group. Never an
  * ISO string or a cron expression: a concrete `nextFireAt` is shown in local time as "Today 9:00" /
  * "Tomorrow 9:00" / a weekday / a date; a handful of common cron shapes are phrased ("Every weekday
  * at 9:00"); anything else falls back to "Repeats".

package/src/styles/surface.css

@@ -216,7 +216,7 @@
 }
 
 /*
- * A code block's own horizontal scrollbar (#3289 §2) stays visible rather than only-on-hover like the
+ * A code block's own horizontal scrollbar stays visible rather than only-on-hover like the
  * rest of the page (`theme.css`'s quiet overlay scrollbar) — a long unwrapped line needs a standing
  * signal that there is more of it, not one that only appears once the person already found the edge.
  * `.gui-code-scroll::-webkit-scrollbar-thumb` outranks that page-wide bare `::-webkit-scrollbar-thumb`