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

package/docs/SPEC.md

@@ -68,6 +68,11 @@ does not own session lifecycle, conversation history, or agent runtime state.
   a schedule or a goal alone (no running background task or loop) still opens the rail, and a
   schedule's Pause/Resume and Delete, and a goal's Cancel, run the same command/control paths their
   slash commands already use — the panel adds no write this package did not already expose.
+- **The surface follows the host's role.** The session client learns its effective role from the
+  host when it connects and, while it observes, sends nothing an observer may not send; the surface
+  then offers only what an observer can do: the conversation, its work and the project's reads, with
+  no composer, answers, session switching or control that changes the session or its work. The host
+  remains the authority; hiding a control is presentation, not enforcement.
 - The title bar and the page title both name the workspace folder the session works in, once the
   host has said one; the desktop window follows the page title.
 - A pending permission or ask prompt is visible whatever view is open, because a gated turn waits

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robota-sdk/agent-ui-web",
-  "version": "3.2.1",
+  "version": "3.3.0",
   "description": "Browser-safe React session presentation, wire reducer, WebSocket client and runtime-host contract for consumer-owned agent renderers.",
   "license": "AGPL-3.0-only OR LicenseRef-Commercial",
   "type": "module",
@@ -60,11 +60,11 @@
     "pretendard": "^1.3.9",
     "react-markdown": "^10.1.0",
     "remark-gfm": "^4.0.1",
-    "@robota-sdk/agent-interface-execution": "3.2.1",
-    "@robota-sdk/agent-interface-session": "3.2.1",
-    "@robota-sdk/agent-transport": "3.2.1",
-    "@robota-sdk/agent-interface-command": "3.2.1",
-    "@robota-sdk/agent-interface-transport": "3.2.1"
+    "@robota-sdk/agent-interface-command": "^3.2.2",
+    "@robota-sdk/agent-interface-execution": "^3.2.2",
+    "@robota-sdk/agent-interface-transport": "^3.2.2",
+    "@robota-sdk/agent-interface-session": "^3.2.2",
+    "@robota-sdk/agent-transport": "^3.3.0"
   },
   "peerDependencies": {
     "react": ">=18"

package/src/components/AgentActivityPanel.tsx

@@ -115,7 +115,7 @@ export function AgentActivityPanel({
                   task={task}
                   onPause={onPauseSchedule}
                   onResume={onResumeSchedule}
-                  onRequestDelete={() => setPendingDeleteId(task.id)}
+                  onRequestDelete={onDeleteSchedule ? () => setPendingDeleteId(task.id) : undefined}
                 />
               ))}
             </div>
@@ -231,7 +231,8 @@ function ScheduleCard({
   task: IBackgroundTaskState<'scheduled'>;
   onPause?: (taskId: string) => void;
   onResume?: (taskId: string) => void;
-  onRequestDelete: () => void;
+  /** Absent when the schedule is shown without controls (an observer). */
+  onRequestDelete?: () => void;
 }): React.ReactElement {
   const isPaused = task.status === 'paused';
   return (
@@ -242,34 +243,40 @@ function ScheduleCard({
       <p className="mt-1 text-[13px] text-muted-foreground">
         {describeScheduleTiming(task)} · {describeScheduleStatus(task)}
       </p>
-      <div className="mt-2 flex items-center gap-3">
-        {isPaused ? (
-          <button
-            type="button"
-            onClick={() => onResume?.(task.id)}
-            className="flex items-center gap-1.5 rounded-lg px-2 py-1 text-[13px] text-muted-foreground hover:bg-hover hover:text-foreground"
-          >
-            <Play size={11} fill="currentColor" aria-hidden="true" />
-            Resume
-          </button>
-        ) : (
-          <button
-            type="button"
-            onClick={() => onPause?.(task.id)}
-            className="flex items-center gap-1.5 rounded-lg px-2 py-1 text-[13px] text-muted-foreground hover:bg-hover hover:text-foreground"
-          >
-            <Pause size={11} fill="currentColor" aria-hidden="true" />
-            Pause
-          </button>
-        )}
-        <button
-          type="button"
-          onClick={onRequestDelete}
-          className="flex items-center gap-1.5 rounded-lg px-2 py-1 text-[13px] text-destructive hover:bg-destructive/10"
-        >
-          Delete…
-        </button>
-      </div>
+      {onResume || onPause || onRequestDelete ? (
+        <div className="mt-2 flex items-center gap-3">
+          {isPaused
+            ? onResume && (
+                <button
+                  type="button"
+                  onClick={() => onResume(task.id)}
+                  className="flex items-center gap-1.5 rounded-lg px-2 py-1 text-[13px] text-muted-foreground hover:bg-hover hover:text-foreground"
+                >
+                  <Play size={11} fill="currentColor" aria-hidden="true" />
+                  Resume
+                </button>
+              )
+            : onPause && (
+                <button
+                  type="button"
+                  onClick={() => onPause(task.id)}
+                  className="flex items-center gap-1.5 rounded-lg px-2 py-1 text-[13px] text-muted-foreground hover:bg-hover hover:text-foreground"
+                >
+                  <Pause size={11} fill="currentColor" aria-hidden="true" />
+                  Pause
+                </button>
+              )}
+          {onRequestDelete && (
+            <button
+              type="button"
+              onClick={onRequestDelete}
+              className="flex items-center gap-1.5 rounded-lg px-2 py-1 text-[13px] text-destructive hover:bg-destructive/10"
+            >
+              Delete…
+            </button>
+          )}
+        </div>
+      ) : null}
     </div>
   );
 }
@@ -293,7 +300,7 @@ function GoalCard({
       <p className="mt-1.5 pl-[26px] text-[13px] text-muted-foreground">
         {describeGoalStatus(goal)}
       </p>
-      {goal.status === 'active' && (
+      {goal.status === 'active' && onCancel && (
         <div className="mt-2 pl-[26px]">
           <button
             type="button"

package/src/components/Composer.tsx

@@ -690,7 +690,8 @@ export function GoalBar({
   onStop,
 }: {
   status: TSessionStatus | null;
-  onStop: () => void;
+  /** Absent for an observer: the goal is shown without a Stop. */
+  onStop?: () => void;
 }): React.ReactElement | null {
   const goal = status?.goal;
   if (!goal || goal.status !== 'active') return null;
@@ -707,15 +708,17 @@ export function GoalBar({
       <span className="flex-shrink-0 text-[13px] tabular-nums text-subtle">
         {goal.iterations}/{goal.maxIterations}
       </span>
-      <button
-        type="button"
-        aria-label="Stop goal"
-        onClick={onStop}
-        className="flex flex-shrink-0 items-center gap-1.5 rounded-lg px-2 py-1 text-[13px] text-muted-foreground hover:bg-hover hover:text-foreground"
-      >
-        <Square size={11} fill="currentColor" aria-hidden="true" />
-        Stop
-      </button>
+      {onStop && (
+        <button
+          type="button"
+          aria-label="Stop goal"
+          onClick={onStop}
+          className="flex flex-shrink-0 items-center gap-1.5 rounded-lg px-2 py-1 text-[13px] text-muted-foreground hover:bg-hover hover:text-foreground"
+        >
+          <Square size={11} fill="currentColor" aria-hidden="true" />
+          Stop
+        </button>
+      )}
       <span
         aria-hidden="true"
         className="absolute bottom-0 left-0 h-[2px] bg-accent/70 transition-[width]"

package/src/components/SessionSurface.tsx

@@ -106,7 +106,7 @@ function SetupPanel({
 export function SessionSurface({
   state,
   surface,
-  personalUsageEnabled = false,
+  personalUsageEnabled: personalUsageRequested = false,
   draftMode = 'persistent',
   onReconnect,
   pickFiles,
@@ -138,6 +138,8 @@ export function SessionSurface({
 
   appViewSandboxUrl?: string;
 }): React.ReactElement {
+  // An observer sees the session but changes nothing; the host stays the authority, this is presentation.
+  const readOnly = state.role === 'observe';
   const [view, setView] = useState<TSessionView>('chat');
   const { identity } = useProductIdentity();
   const appViewHost = useMemo(
@@ -150,6 +152,8 @@ export function SessionSurface({
     }),
     [appViewSandboxUrl, state.readAppView, state.callAppTool, identity.displayName, surface],
   );
+  // The personal usage read is not admitted for an observer.
+  const personalUsageEnabled = personalUsageRequested && !readOnly;
   const composerRef = useRef<IComposerHandle>(null);
   const tasks = state.executionWorkspace?.entries ?? [];
   // The main thread alone is this conversation; the rail earns its width only for work beside it.
@@ -180,8 +184,10 @@ export function SessionSurface({
   // #3282 §3: no provider is configured — the session is running (a placeholder stands in for the
   // real one), but there is nothing to reply with yet.
   const setupRequired = state.sessionStatus?.setupRequired === true;
+  // Switching, starting, renaming and deleting sessions are driver actions: an observer has no sidebar.
   const hasSessionList =
-    (state.sessionListing ?? null) !== null || state.sessionsError?.code === 'list_failed';
+    !readOnly &&
+    ((state.sessionListing ?? null) !== null || state.sessionsError?.code === 'list_failed');
   const sidebarOpen = hasSessionList && state.sessionSidebarOpen;
   const usage = personalUsageEnabled && view === 'usage';
   const project = view === 'project';
@@ -292,24 +298,28 @@ export function SessionSurface({
           <div className="min-h-0 flex-1">
             <PersonalUsageDashboard state={state} />
             {/* A gated turn waits on this answer, so it shows over whatever view is open. */}
-            <PermissionPrompt
-              layout="modal"
-              prompts={state.pendingPrompts}
-              onAnswerPermission={state.answerPermission}
-              onAnswerAsk={state.answerAsk}
-              ownDriverId={state.ownDriverId}
-            />
+            {readOnly ? null : (
+              <PermissionPrompt
+                layout="modal"
+                prompts={state.pendingPrompts}
+                onAnswerPermission={state.answerPermission}
+                onAnswerAsk={state.answerAsk}
+                ownDriverId={state.ownDriverId}
+              />
+            )}
           </div>
         ) : project ? (
           <div className="min-h-0 flex-1">
             <ProjectPanel state={state} onOpenMemoryInEditor={onOpenMemoryInEditor} />
-            <PermissionPrompt
-              layout="modal"
-              prompts={state.pendingPrompts}
-              onAnswerPermission={state.answerPermission}
-              onAnswerAsk={state.answerAsk}
-              ownDriverId={state.ownDriverId}
-            />
+            {readOnly ? null : (
+              <PermissionPrompt
+                layout="modal"
+                prompts={state.pendingPrompts}
+                onAnswerPermission={state.answerPermission}
+                onAnswerAsk={state.answerAsk}
+                ownDriverId={state.ownDriverId}
+              />
+            )}
           </div>
         ) : (
           <div className="flex min-h-0 flex-1">
@@ -320,7 +330,7 @@ export function SessionSurface({
                 onReconnect={onReconnect}
               />
               <div className="min-h-0 flex-1 overflow-hidden">
-                {setupRequired ? (
+                {setupRequired && !readOnly ? (
                   <SetupPanel
                     onSetUp={() => state.send({ type: 'command', name: 'provider', args: 'add' })}
                     disabled={state.status !== 'connected'}
@@ -328,7 +338,7 @@ export function SessionSurface({
                 ) : isEmpty ? (
                   <EmptyState />
                 ) : (
-                  <AppViewHostContext.Provider value={appViewHost}>
+                  <AppViewHostContext.Provider value={readOnly ? null : appViewHost}>
                     <ConversationView
                       messages={state.messages}
                       activeTools={state.activeTools}
@@ -344,19 +354,32 @@ export function SessionSurface({
               >
                 <GoalBar
                   status={state.sessionStatus ?? null}
-                  onStop={() => state.send({ type: 'command', name: 'goal', args: 'cancel' })}
-                />
-                <PermissionPrompt
-                  layout="dock"
-                  prompts={state.pendingPrompts}
-                  onAnswerPermission={state.answerPermission}
-                  onAnswerAsk={state.answerAsk}
-                  ownDriverId={state.ownDriverId}
-                  onFocusReturn={() => composerRef.current?.focus()}
+                  onStop={
+                    readOnly
+                      ? undefined
+                      : () => state.send({ type: 'command', name: 'goal', args: 'cancel' })
+                  }
                 />
+                {readOnly ? null : (
+                  <PermissionPrompt
+                    layout="dock"
+                    prompts={state.pendingPrompts}
+                    onAnswerPermission={state.answerPermission}
+                    onAnswerAsk={state.answerAsk}
+                    ownDriverId={state.ownDriverId}
+                    onFocusReturn={() => composerRef.current?.focus()}
+                  />
+                )}
                 {/* #3282 §3: hidden while there is no provider to send to — the setup panel's own
                     button is the only way in, so nobody types into a composer that goes nowhere. */}
-                {setupRequired ? null : (
+                {readOnly ? (
+                  <p
+                    role="status"
+                    className="rounded-2xl bg-card px-4 py-3 text-center text-[14px] text-muted-foreground"
+                  >
+                    Read-only: you are watching this session.
+                  </p>
+                ) : setupRequired ? null : (
                   <Composer
                     ref={composerRef}
                     draftMode={draftMode}
@@ -409,13 +432,17 @@ export function SessionSurface({
                   selectedEntryId={state.openEntryId ?? undefined}
                   onSelect={(entry) => state.openExecutionDetail(entry.id)}
                   onReturnToConversation={() => state.closeExecutionDetail()}
-                  onStop={stopExecutionEntry}
+                  onStop={readOnly ? undefined : stopExecutionEntry}
                   schedules={state.scheduledTasks}
                   goal={currentGoal}
-                  onPauseSchedule={state.pauseSchedule}
-                  onResumeSchedule={state.resumeSchedule}
-                  onDeleteSchedule={state.deleteSchedule}
-                  onCancelGoal={() => state.send({ type: 'command', name: 'goal', args: 'cancel' })}
+                  onPauseSchedule={readOnly ? undefined : state.pauseSchedule}
+                  onResumeSchedule={readOnly ? undefined : state.resumeSchedule}
+                  onDeleteSchedule={readOnly ? undefined : state.deleteSchedule}
+                  onCancelGoal={
+                    readOnly
+                      ? undefined
+                      : () => state.send({ type: 'command', name: 'goal', args: 'cancel' })
+                  }
                 />
               </aside>
             )}
@@ -428,14 +455,14 @@ export function SessionSurface({
               complete={state.executionDetailComplete}
               onClose={() => state.closeExecutionDetail()}
               onLoadMore={() => state.loadMoreExecutionDetail()}
-              onStop={openEntry ? () => stopExecutionEntry(openEntry) : undefined}
+              onStop={openEntry && !readOnly ? () => stopExecutionEntry(openEntry) : undefined}
               inputState={state.executionDetailInput}
               mode={state.executionDetailMode}
               unreadable={state.executionDetailUnreadable}
               onShowEarlier={state.showEarlierExecutionDetail}
               onShowLive={state.showLiveExecutionDetail}
               onSend={
-                openEntry
+                openEntry && !readOnly
                   ? (prompt) =>
                       state.send({
                         type: 'send-background-task',
@@ -445,7 +472,7 @@ export function SessionSurface({
                   : undefined
               }
               onContinue={
-                openEntry?.resumeSessionId
+                openEntry?.resumeSessionId && !readOnly
                   ? () => {
                       if (openEntry.resumeSessionId) state.switchSession(openEntry.resumeSessionId);
                     }
@@ -457,8 +484,8 @@ export function SessionSurface({
       </div>
 
       <SessionNotices state={state} />
-      <SettingsScreen state={state} />
-      <AgentSwitcherSheet state={state} />
+      {readOnly ? null : <SettingsScreen state={state} />}
+      {readOnly ? null : <AgentSwitcherSheet state={state} />}
       <HelpSheet
         open={state.helpOpen}
         onClose={() => state.closeHelp()}

package/src/hooks/server-message-handling.ts

@@ -89,6 +89,8 @@ export const SERVER_MESSAGE_HANDLING = {
   background_task_control_result: 'visible-notice',
   protocol_error: 'visible-notice',
   resume_gap: 'transport-control',
+  // The connection's effective role: the session client holds it and stops sending what an observer may not.
+  surface_role: 'reducer-state',
   // #3282 §4a: the Settings screen's own correlated request/response state (`useSettingsState`).
   settings: 'reducer-state',
   settings_error: 'reducer-state',

package/src/hooks/session-client-types.ts

@@ -16,7 +16,11 @@ import type {
   IExecutionDetailRecord,
   IExecutionWorkspaceSnapshot,
 } from '@robota-sdk/agent-interface-execution';
-import type { IWireAgentDefinitionSummary, TServerMessage } from '@robota-sdk/agent-transport';
+import type {
+  IWireAgentDefinitionSummary,
+  TServerMessage,
+  TSessionSurfaceRole,
+} from '@robota-sdk/agent-transport';
 
 export type { TAppToolArguments, TAppToolOutcome, TAppView } from '../app-view/types.js';
 
@@ -204,6 +208,8 @@ export interface IWsSessionState<TStatus extends string = TConnectionStatus> {
   sessionName: string | null;
   /** This connection's own driver id, learned from the server's first frame; null until then. */
   ownDriverId: TDriverId | null;
+  /** The role the host gave this connection, learned when it connects; null until the host answers. */
+  role: TSessionSurfaceRole | null;
   /** Null until the session has answered; refreshed after every command. */
   commandCatalog: TCommandCatalog | null;
   /** Null until the session has answered; refreshed after every command and turn. */

package/src/hooks/use-app-view-requests.ts

@@ -20,6 +20,7 @@ function nextRequestId(prefix: string): string {
 }
 
 const CONNECTION_CLOSED = 'The connection to the session closed.';
+const READ_ONLY = 'This session is read-only.';
 
 /**
  * The key a finished call's app view is read and called by, taken from the tool row's `appView`
@@ -53,6 +54,7 @@ function callAppToolMessage(
 export function useAppViewRequests(
   send: (msg: TClientMessage) => void,
   isConnected: () => boolean,
+  isObserving: () => boolean,
 ): {
   readAppView: (viewKey: string, signal?: AbortSignal) => Promise<TAppView>;
   callAppTool: (
@@ -92,6 +94,11 @@ export function useAppViewRequests(
           reject(new Error(signal?.aborted ? 'The app view closed.' : CONNECTION_CLOSED));
           return;
         }
+        // An observer's request is never sent, so no reply would come.
+        if (isObserving()) {
+          reject(new Error(READ_ONLY));
+          return;
+        }
         const requestId = nextRequestId(`${requestOwner}_${prefix}`);
         const dispose = (): void => signal?.removeEventListener('abort', abort);
         const abort = (): void => {
@@ -109,7 +116,7 @@ export function useAppViewRequests(
           reject(error instanceof Error ? error : new Error(String(error)));
         }
       }),
-    [isConnected, requestOwner, send],
+    [isConnected, isObserving, requestOwner, send],
   );
 
   const readAppView = useCallback(

package/src/hooks/use-session-directory.ts

@@ -81,7 +81,10 @@ function initialSidebarOpen(): boolean {
  * on its primary one. After a reconnect to such a host this surface goes back to the session it was
  * on; an older host has one session for everyone, so there is nothing to go back to.
  */
-export function useSessionDirectoryState(send: (msg: TClientMessage) => void): TSessionDirectoryState & {
+export function useSessionDirectoryState(
+  send: (msg: TClientMessage) => void,
+  isObserving: () => boolean,
+): TSessionDirectoryState & {
   handleSessionsMessage: (msg: TServerMessage) => boolean;
   /** Whether the host can list sessions, as far as its last answer says. */
   canListSessions: () => boolean;
@@ -148,12 +151,14 @@ export function useSessionDirectoryState(send: (msg: TClientMessage) => void): T
       // launch with no remembered id never reaches here (target stays null), so nothing switches.
       clearStoredRestoreId(browserNamespace);
       if (target === listing.currentSessionId) return;
+      // An observer never moves the session, so there is nothing to go back to.
+      if (isObserving()) return;
       if (!keepsSessionsLive(listing)) return;
       // A session the host no longer lists (an empty one it never saved) is nothing to go back to.
       if (!listing.sessions.some((row) => row.id === target)) return;
       send({ type: 'switch-session', sessionId: target, requestId: nextRequestId('session_change') });
     },
-    [send, browserNamespace],
+    [send, browserNamespace, isObserving],
   );
 
   const handleSessionsMessage = useCallback(

package/src/hooks/useSessionClient.ts

@@ -6,6 +6,7 @@
  * 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,
@@ -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('');
@@ -375,8 +380,11 @@ 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' });
       }
@@ -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 => {
@@ -453,14 +463,14 @@ 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);
@@ -504,6 +514,11 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
       // 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,
           // diffs and "Changed files" — a reload/reconnect/resume replay renders THAT. `display` is
@@ -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,6 +1021,8 @@ 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
@@ -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,