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

package/src/components/SessionSurfaceChrome.tsx

@@ -14,7 +14,7 @@ const STATUS: Record<string, { dot: string; label: string }> = {
   error: { dot: 'bg-destructive', label: 'Connection error' },
 };
 
-/** #3282 §4c: every view the primary nav can show — 'project' is always offered (desktop and
+/** Every view the primary nav can show — 'project' is always offered (desktop and
  *  browser alike); 'usage' only where the host opted the surface into it. */
 export type TSessionView = 'chat' | 'usage' | 'project';
 
@@ -25,7 +25,7 @@ const VIEW_LABEL: Readonly<Record<TSessionView, string>> = {
 };
 
 /**
- * #3289 §1 — the folder this session works in, wherever `document.title` is settable: a page (the
+ * The folder this session works in, wherever `document.title` is settable: a page (the
  * browser tab) and the desktop window that loads it (Electron follows the page's title unless told
  * otherwise, and nothing in `apps/agent-app/electron/main.ts` overrides it — see its own SPEC note).
  * Absent while the host has not said, so a not-yet-connected surface keeps whatever title it loaded
@@ -58,14 +58,14 @@ export function SessionTitleBar({
   status: string;
   surface?: string;
   title?: string | null;
-  /** The folder this session works in (#3289 §1); absent when the host has not said. */
+  /** The folder this session works in; absent when the host has not said. */
   workspace?: { readonly name: string; readonly path: string };
   showBrand: boolean;
   view: TSessionView;
   onView: (view: TSessionView) => void;
   personalUsageEnabled: boolean;
   /**
-   * #3282 §2 (part 2): mirrors `ConnectionBanner`'s own "give-up" flag (`useWsSession`'s
+   * Mirrors `ConnectionBanner`'s own "give-up" flag (`useWsSession`'s
    * `connectionLost`) so this corner indicator can tell exactly when that banner is on screen, to
    * never say the same thing twice.
    */
@@ -73,7 +73,7 @@ export function SessionTitleBar({
 }): React.ReactElement {
   const state = STATUS[status] ?? STATUS.disconnected;
   useWorkspaceDocumentTitle(workspace);
-  // #3282 §2 (part 2): the same "has this surface ever connected" rule `ConnectionBanner` uses to
+  // The same "has this surface ever connected" rule `ConnectionBanner` uses to
   // decide whether it has anything to show — kept in step here so the corner text disappears exactly
   // when, and only when, the banner takes over saying it (never both, never neither).
   const everConnectedRef = useRef(false);
@@ -81,7 +81,7 @@ export function SessionTitleBar({
     if (status === 'connected') everConnectedRef.current = true;
   }, [status]);
   const bannerShown = status !== 'connected' && (connectionLost || everConnectedRef.current);
-  // #3282 §4c principle 4 (#3277): everything the agent implements is usable from the GUI through
+  // Everything the agent implements is usable from the GUI through
   // organized screens — the Project panel (git status/diff, project memory) is one, offered next to
   // Chat on every surface, desktop and browser alike; Usage stays surface-gated.
   const items: readonly TSessionView[] = personalUsageEnabled
@@ -142,7 +142,7 @@ export function SessionTitleBar({
 const BANNER_COLUMN = 'mx-auto w-full max-w-[760px] px-6';
 
 /**
- * A connection that drops after a working session (issue #3280 §5): a banner directly above the
+ * A connection that drops after a working session: a banner directly above the
  * conversation — never a full-screen replacement — so the conversation and its history stay visible
  * and scrollable throughout. Shown as soon as the drop happens; says nothing on the very first
  * connect, because nothing has been lost yet.
@@ -234,7 +234,7 @@ function displayProvider(provider: string | undefined): string {
 }
 
 /**
- * A provider/session error classified at the wire boundary (#3289 §3) as one plain sentence naming
+ * A provider/session error classified at the wire boundary as one plain sentence naming
  * what happened and, where there is one, the next step — `null` for a notice this classification does
  * not cover, which keeps showing its own `message` instead.
  *

package/src/components/SettingsGeneralSection.tsx

@@ -6,7 +6,7 @@ import type { ISettingsSnapshot, TSettingsPatch } from '@robota-sdk/agent-interf
 
 /**
  * Language, output style and preset — reusing the exact choices and descriptions the runtime
- * already builds for `/language`, `/output-style` and `/preset` (#3282 §4a). Never internal ids:
+ * already builds for `/language`, `/output-style` and `/preset`. Never internal ids:
  * every pop-up shows the runtime's human labels.
  */
 export function SettingsGeneralSection({

package/src/components/SettingsMcpSection.tsx

@@ -92,7 +92,7 @@ function ServerRow({
 }
 
 /**
- * The MCP Servers section (#3282 §4 part b-2): every configured server's name, where it is
+ * The MCP Servers section: every configured server's name, where it is
  * configured, its live connection status and tool count, an enable/disable switch (approve/reject),
  * an expandable list of its tool names, and a section-level Reload. Adding or editing a server is
  * left out — the runtime has no command path that writes MCP config (recorded in

package/src/components/SettingsPermissionsSection.tsx

@@ -48,7 +48,7 @@ function PermissionRuleRow({
 }
 
 /**
- * Default permission mode, the rules `/permissions` shows, and the sandbox switch (#3282 §4a).
+ * Default permission mode, the rules `/permissions` shows, and the sandbox switch.
  * "Skip all checks" as the mode and a preset that would set it both go through
  * `onRequestModeChange`'s parent-owned confirmation before anything is sent.
  */

package/src/components/SettingsPluginsSection.tsx

@@ -60,7 +60,7 @@ function PluginRow({
 }
 
 /**
- * The Plugins section (#3282 §4 part b-2): every installed plugin's name, description and enabled
+ * The Plugins section: every installed plugin's name, description and enabled
  * state, an enable/disable switch, a section-level Reload, and — local surfaces only — install and
  * uninstall, since installing runs third-party code. `canInstall` (from the snapshot) mirrors the
  * refusal `/plugin install|uninstall` itself gives a remote device or an observer.

package/src/components/SettingsProvidersSection.tsx

@@ -14,7 +14,7 @@ const PRIMARY_BUTTON = `${BUTTON} bg-primary text-primary-foreground hover:opaci
 const SECONDARY_BUTTON = `${BUTTON} bg-raised text-foreground hover:bg-hover`;
 const DESTRUCTIVE_BUTTON = `${BUTTON} text-destructive hover:bg-destructive/10`;
 
-/** The "Model" action: a `PopupMenu` of this ONE profile's catalog models (#3282 §4b). */
+/** The "Model" action: a `PopupMenu` of this ONE profile's catalog models. */
 function ProviderModelButton({
   profile,
   modelList,
@@ -142,7 +142,7 @@ function ProviderProfileRow({
 }
 
 /**
- * The configured provider profiles (#3282 §4b), each row a plain provider name, its model's label,
+ * The configured provider profiles, each row a plain provider name, its model's label,
  * a checkmark on the one in use, and a plain connection state when one is known. Every action goes
  * through the same path the equivalent command does: Use/Model apply through `state.updateSettings`
  * (the same `field` patterns Preset/Mode/Sandbox use); Edit/Test/Duplicate/Add dispatch the raw
@@ -169,7 +169,7 @@ export function SettingsProvidersSection({
   onRequestDelete: (profileName: string) => void;
 }): React.ReactElement {
   // The "Model" button needs each profile's catalog as soon as this section is visible, not only
-  // once a person opens one — `list-models` is a cheap, observer-safe read (#3282 §2).
+  // once a person opens one — `list-models` is a cheap, observer-safe read.
   // Intentionally empty deps: fetch once per mount, not on every render.
   useEffect(() => {
     onRequestModelList();

package/src/components/SettingsScreen.tsx

@@ -19,7 +19,7 @@ interface ISettingsSectionDefinition {
 }
 
 /**
- * The Settings screen's sections (#3282 §4). Adding a later section (Advisor) is one entry here plus
+ * The Settings screen's sections. Adding a later section (Advisor) is one entry here plus
  * one component in the switch below — nothing else in this file changes.
  */
 const SECTIONS: readonly ISettingsSectionDefinition[] = [
@@ -36,7 +36,7 @@ type TPendingPluginAction =
   | { kind: 'uninstall'; plugin: ISettingsPlugin };
 
 /**
- * A large modal sheet with a section sidebar on the left and content on the right (#3282 §4a) — the
+ * A large modal sheet with a section sidebar on the left and content on the right — the
  * GUI's Settings screen, opened by the sidebar's gear button, the desktop app's ⌘, menu item, or
  * `/settings` (its `show-settings` `ui_intent` calls `state.openSettings()`, wired in
  * `useSessionClient`). Every change applies at once; there is no Save button. Esc and the Close
@@ -56,7 +56,7 @@ export function SettingsScreen({ state }: { state: IWsSessionState }): React.Rea
   const [pendingPluginAction, setPendingPluginAction] = useState<TPendingPluginAction | null>(null);
   const [mcpReloading, setMcpReloading] = useState(false);
   const [pluginsReloading, setPluginsReloading] = useState(false);
-  // #3282 §4b: the profile a pending "Delete…" confirms, or null when none is pending.
+  // The profile a pending "Delete…" confirms, or null when none is pending.
   const [pendingProviderDelete, setPendingProviderDelete] = useState<string | null>(null);
 
   // Each time the screen opens, land on the section the opener asked for (`/plugin` → Plugins,

package/src/components/StatusControls.tsx

@@ -10,7 +10,7 @@ import type { IPopupMenuItem, IPopupMenuSection } from './PopupMenu.js';
 import type { TCommandCatalog, TModelListSnapshot, TSessionStatus } from '../hooks/session-client-types.js';
 
 /**
- * #3282 §2 (part 2) — the plain label for each effort selection. Kept in step with
+ * The plain label for each effort selection. Kept in step with
  * `EFFORT_LEVEL_LABELS` in `packages/agent-framework/src/effort/effort-resolution.ts` (which
  * `agent-command`'s `/effort` re-exports and reports as its own outcome text) — this package cannot
  * import that one directly (it is a Node-side package this browser bundle does not depend on), so the
@@ -28,7 +28,7 @@ const EFFORT_LEVEL_LABELS: Readonly<Record<TSessionStatus['effort'], string>> =
   max: 'Maximum',
 };
 
-/** The primary row (#3282 §2 design point 4); the rest sit under "More". */
+/** The primary row; the rest sit under "More". */
 const EFFORT_PRIMARY: readonly TSessionStatus['effort'][] = ['auto', 'low', 'medium', 'high'];
 const EFFORT_MORE: readonly TSessionStatus['effort'][] = ['none', 'minimal', 'xhigh', 'max'];
 
@@ -48,7 +48,7 @@ const CHIP_CLASS =
   'flex min-w-0 items-center gap-1.5 rounded-lg px-2 py-1 text-[13px] text-muted-foreground hover:bg-hover hover:text-foreground disabled:cursor-not-allowed disabled:opacity-60 disabled:hover:bg-transparent';
 const CHIP_WARNING_CLASS = 'text-warning hover:text-warning';
 
-/** One status chip that opens a `PopupMenu` HIG pop-up beneath it (#3282 §2). */
+/** One status chip that opens a `PopupMenu` HIG pop-up beneath it. */
 function StatusChip({
   chipLabel,
   value,
@@ -79,7 +79,7 @@ function StatusChip({
         aria-label={`${chipLabel}: ${value}`}
         aria-haspopup="menu"
         aria-expanded={open}
-        // #3289 §2: below `md` the value text is hidden (icon-only) — the tooltip is where it stays
+        // Below `md` the value text is hidden (icon-only) — the tooltip is where it stays
         // reachable on hover and keyboard focus, so it always carries the value, not just "Change X".
         title={connected ? `${chipLabel}: ${value}` : 'Reconnecting…'}
         disabled={!connected}
@@ -90,7 +90,7 @@ function StatusChip({
         className={`${CHIP_CLASS} ${warning ? CHIP_WARNING_CLASS : ''}`}
       >
         {icon}
-        {/* #3289 §2: below `md` (the same breakpoint the session-list sheet uses) the chip collapses
+        {/* Below `md` (the same breakpoint the session-list sheet uses) the chip collapses
             to its icon alone — never a truncated fragment ("d…", "claude-…") — the value stays
             reachable via the tooltip above and the accessible name either way. */}
         <span className="hidden truncate md:inline">{value}</span>
@@ -110,7 +110,7 @@ function StatusChip({
 const ICON_PROPS = { size: 14, strokeWidth: 1.75, 'aria-hidden': true } as const;
 
 /**
- * Model · mode · effort, each a pop-up menu (#3282 §2), and the context the conversation fills.
+ * Model · mode · effort, each a pop-up menu, and the context the conversation fills.
  * Every menu applies its choice through the same command wire path the equivalent typed slash
  * command uses — `onSilentCommand` — so `/model <id>`, `/mode <name>` and `/effort <value>` and a
  * click in these menus can never drift apart; the control's own chip label (fed by the session's next
@@ -129,14 +129,14 @@ export function StatusRow({
   catalog: TCommandCatalog | null;
   modelList: TModelListSnapshot | null;
   onRequestModelList: () => void;
-  /** #3282 §4b: "Manage providers…" opens Settings at the Providers & Models section. */
+  /** "Manage providers…" opens Settings at the Providers & Models section. */
   onManageProviders: () => void;
   /** Applies a model/mode/effort choice without a conversation card (see the module doc). */
   onSilentCommand: (name: string, args?: string) => void;
   connected: boolean;
 }): React.ReactElement {
   const used = status ? Math.round(status.context.usedPercentage) : null;
-  // #3282 §2: "Skip all checks" asks for confirmation on the shared `ConfirmDialog` (#3331) before
+  // "Skip all checks" asks for confirmation on the shared `ConfirmDialog` before
   // applying — every other mode applies at once. `true` while that confirmation is open.
   const [pendingBypassConfirm, setPendingBypassConfirm] = useState(false);
 
@@ -158,7 +158,7 @@ export function StatusRow({
           key: 'manage-providers',
           label: 'Manage providers…',
           kind: 'action',
-          // #3282 §4b: opens Settings at the "Providers & Models" section — the same list, Use/Model/
+          // Opens Settings at the "Providers & Models" section — the same list, Use/Model/
           // Edit/Test/Duplicate/Delete actions and "Add provider…" flow now live there instead of in
           // this menu's own server-driven picker.
           onSelect: onManageProviders,
@@ -175,7 +175,7 @@ export function StatusRow({
           label: sub.displayName ?? sub.name,
           description: sub.description,
           checked: sub.name === status?.permissionMode,
-          // #3282 §2: every mode but "Skip all checks" applies at once; that one opens a
+          // Every mode but "Skip all checks" applies at once; that one opens a
           // confirmation first (rendered below) instead of applying here directly.
           onSelect:
             sub.name === 'bypassPermissions'
@@ -253,8 +253,8 @@ export function StatusRow({
         <ContextRing percent={used ?? 0} />
         {used === null ? '' : `${used}%`}
       </span>
-      {/* #3282 §2: matches the wording the Settings screen's own permission-mode picker already
-          ships for the identical action (#3331's `SettingsScreen.tsx`), so switching to "Skip all
+      {/* Matches the wording the Settings screen's own permission-mode picker already
+          ships for the identical action (`SettingsScreen.tsx`), so switching to "Skip all
           checks" reads the same warning regardless of which control was used. */}
       <ConfirmDialog
         open={pendingBypassConfirm}

package/src/components/composer-attachments.ts

@@ -1,5 +1,5 @@
 /**
- * #3282 §4d — pure logic behind the composer's attach button and drag-and-drop, kept apart from
+ * Pure logic behind the composer's attach button and drag-and-drop, kept apart from
  * `Composer.tsx` so it is testable without React or a DOM.
  *
  * The runtime resolves `@relative/path` references already (`prompt-file-reference-resolver.ts` in
@@ -26,7 +26,7 @@ export const MAX_ATTACHMENT_TOTAL_BYTES = 256 * 1024;
  */
 export const MAX_ATTACHMENT_COUNT = 8;
 
-/** Shown whenever a file cannot be resolved to a path inside the workspace — rule 3 (#3282 §4). */
+/** Shown whenever a file cannot be resolved to a path inside the workspace — rule 3. */
 export const ATTACHMENT_NO_PATH_NOTICE = 'Only files inside this project folder can be attached.';
 
 /** Shown once the running count of attachments would pass `MAX_ATTACHMENT_COUNT`. */
@@ -50,7 +50,7 @@ export interface IDraftAttachment {
 }
 
 /**
- * One file the desktop host's native "Attach files" dialog returned (#3282 §4d). Kept in structural
+ * One file the desktop host's native "Attach files" dialog returned. Kept in structural
  * sync with `IPickedFile` in `apps/agent-gui-web/src/gui-host.ts` and
  * `apps/agent-app/electron/sidecar.ts` — the three are not imported across the Electron/browser/
  * presentation package boundaries, same as this codebase already does for the trust question.
@@ -228,11 +228,11 @@ export function evaluateCandidateFile(
 }
 
 /**
- * Inserts each chip as the runtime's existing `@relative/path` reference syntax — rule 2 (#3282 §4).
+ * Inserts each chip as the runtime's existing `@relative/path` reference syntax — rule 2.
  * Always prefixed with `./`: the parser's `isPathLikeReference` only treats a token as a file
  * reference when it has a `.` somewhere or an explicit relative-path prefix, so a dotless name like
  * `Makefile`, `Dockerfile` or `LICENSE` — common, useful, and never refused for lacking one — would
- * otherwise be sent as plain text with no file and no diagnostic (follow-up to #3282 §4d). `./` makes
+ * otherwise be sent as plain text with no file and no diagnostic. `./` makes
  * every path path-like regardless of its name, and the resolver collapses it back to the plain
  * relative path before use.
  */

package/src/driver-labels.ts

@@ -1,5 +1,5 @@
 /**
- * #3289 §3 — plain, human labels for a REMOTE-014 E5 driver id, and whether one names the SAME KIND
+ * Plain, human labels for a driver id, and whether one names the SAME KIND
  * of surface as this connection's own. Shared by every place the GUI shows who drove a turn (a
  * message, a permission/ask prompt): the person's own input never carries a label, and a turn from a
  * different kind of surface does — in words, never a raw id.
@@ -16,7 +16,7 @@ import { AGENT_DRIVER_ID, OWNER_DRIVER_ID } from '@robota-sdk/agent-interface-se
 import type { TDriverId } from '@robota-sdk/agent-interface-session';
 
 /**
- * `remote` (a plain WS remote connection's own id, `'remote:ws'`) and `peer` (an unrelated REMOTE-014
+ * `remote` (a plain WS remote connection's own id, `'remote:ws'`) and `peer` (an unrelated
  * mesh peer's turn, `'peer:<sessionId>'`) are kept as DIFFERENT kinds even though both render the same
  * label text: a plain WS viewer's own id is `'remote:ws'`, and folding a peer's turn into that same
  * kind would make `isSameSurface` treat a co-driver's turn as this connection's own and hide it — the
@@ -76,7 +76,7 @@ export function humanDriverLabel(driverId: TDriverId): string {
 
 /**
  * The ready-to-render attribution phrase: "from <label>" for a co-driver, or "Automatic — loop"
- * for the agent's own wake-ups — "from automatic" reads as a typo, not a source. #3288 §1: every
+ * for the agent's own wake-ups — "from automatic" reads as a typo, not a source. Every
  * `AGENT_DRIVER_ID` turn is, today, a loop's own injected iteration (fixed or self-paced —
  * `requestWakeup` in `interactive-session.ts` is the one place that stamps this id); if a
  * differently-sourced agent-wakeup turn is ever added, this label needs to name that source

package/src/execution-entry-status.ts

@@ -1,5 +1,5 @@
 /**
- * #3288 §1: one true-status label for an execution-workspace entry, shared by the Agents panel row
+ * One true-status label for an execution-workspace entry, shared by the Agents panel row
  * and its detail sheet so the two never say something different about the same entry.
  *
  * A completed task whose result still reports a refused tool call is not "Done" — it is "Needs

package/src/goal-view.ts

@@ -1,5 +1,5 @@
 /**
- * #3282 §4 part b-3 — the Agents panel's Goal row: the objective, and its status in plain words.
+ * The Agents panel's Goal row: the objective, and its status in plain words.
  */
 
 import type { IGoalState } from '@robota-sdk/agent-interface-session';

package/src/hooks/command-menu.ts

@@ -1,8 +1,8 @@
 /**
- * #3186 — what the composer's `/` menu offers for a draft. Pure, so the matching is testable without
+ * What the composer's `/` menu offers for a draft. Pure, so the matching is testable without
  * rendering: the TUI's autocomplete offers commands and skills the same way.
  *
- * #3282 §4e: a command the GUI cannot run at all (`isExcludedCommand`) never appears here — there is
+ * A command the GUI cannot run at all (`isExcludedCommand`) never appears here — there is
  * nothing useful for choosing it to do, and typing it by hand is answered separately (see
  * `excluded-commands.ts`, `useSessionClient.ts`). Commands are listed before skills, each in its own
  * group, so the menu can head them "Commands" and "Skills".

package/src/hooks/excluded-commands.ts

@@ -1,9 +1,9 @@
 /**
- * #3282 §4e — built-in commands left out of the GUI on purpose (the design decisions in
+ * Built-in commands left out of the GUI on purpose (the design decisions in
  * `packages/agent-gui-web/docs/SPEC.md` group them by reason). The `/` menu never lists one of these
  * (`command-menu.ts`), and typing one by hand anyway is caught before it reaches the session
  * (`useSessionClient.ts`'s `send`) and answered with the plain sentence here — never the session's own
- * refusal, and never the generic "not available on this surface" line CMD-004 uses for a screen this
+ * refusal, and never the generic "not available on this surface" line used for a screen this
  * surface simply has not built yet (see `ui-intent-state.ts`).
  */
 

package/src/hooks/prompt-state.ts

@@ -1,5 +1,5 @@
 /**
- * Pure prompt-state derivation for the web UI (REMOTE-009 Step 4 / REMOTE-007 render+answer).
+ * Pure prompt-state derivation for the web UI (render + answer).
  *
  * The paired browser is the session OWNER (local == remote), so it must render and ANSWER the owner's own
  * permission/ask prompts. The server carries `permission_request`/`ask_request` (a prompt appears) and
@@ -32,9 +32,9 @@ export function applyPromptEvent(
 ): readonly TPendingPrompt[] {
   switch (msg.type) {
     case 'permission_request': {
-      // REMOTE-014 E5: keep requesterDriverId so the surface can show WHICH driver's turn raised the
-      // prompt. Issue #3288 §1: keep `requester` too, so it can show WHICH background agent did.
-      // #3288 §2: diffLines/diffFile (Edit/Write) and cwd (Shell, only when it differs) are the
+      // Keep requesterDriverId so the surface can show WHICH driver's turn raised the
+      // prompt. Keep `requester` too, so it can show WHICH background agent did.
+      // diffLines/diffFile (Edit/Write) and cwd (Shell, only when it differs) are the
       // server's diff/command preview — carried through unchanged so the prompt can render them
       // instead of raw args.
       const { id, toolName, toolArgs, requesterDriverId, requester, diffLines, diffFile, cwd } =

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

@@ -4,7 +4,7 @@ export type TServerMessageHandling =
   'reducer-state' | 'visible-notice' | 'intentionally-not-rendered' | 'transport-control';
 
 /**
- * ARCH-2164: exhaustive ownership for every decoded server variant on the shared GUI surface.
+ * Exhaustive ownership for every decoded server variant on the shared GUI surface.
  * Adding a wire variant without deciding its GUI disposition is a compile error instead of a silent
  * reducer omission. `intentionally-not-rendered` is an explicit disposition for server-side query
  * snapshots and domain events that this session/usage surface does not currently visualize.
@@ -28,10 +28,10 @@ export const SERVER_MESSAGE_HANDLING = {
   turn_source: 'intentionally-not-rendered',
   commands: 'reducer-state',
   session_status: 'reducer-state',
-  // #3282 §2 part 2: the reply to `list-models`, fed into `modelList` state by the model control's
+  // The reply to `list-models`, fed into `modelList` state by the model control's
   // pop-up menu (`useModelListState`).
   model_list: 'reducer-state',
-  // #3282 §4 part b-3: the agent switcher sheet's own correlated request/response state (`useAgentSwitcherState`).
+  // The agent switcher sheet's own correlated request/response state (`useAgentSwitcherState`).
   agent_definitions: 'reducer-state',
   sessions: 'reducer-state',
   sessions_error: 'reducer-state',
@@ -47,10 +47,10 @@ export const SERVER_MESSAGE_HANDLING = {
   stored_session_usage_report: 'reducer-state',
   stored_session_usage_report_error: 'visible-notice',
   executing: 'intentionally-not-rendered',
-  // #3280 §2: the prompt queued behind a running turn — shown above the composer with Edit/Remove.
+  // The prompt queued behind a running turn — shown above the composer with Edit/Remove.
   pending: 'reducer-state',
   execution_workspace_event: 'reducer-state',
-  // #3288 §1: the Agents panel's detail sheet reads a page at a time.
+  // The Agents panel's detail sheet reads a page at a time.
   execution_detail: 'reducer-state',
   execution_detail_error: 'reducer-state',
   // Esc's loop stop is a TUI-only shortcut; this surface's loops stop through the Agents panel
@@ -58,7 +58,7 @@ export const SERVER_MESSAGE_HANDLING = {
   waiting_loop_stop: 'intentionally-not-rendered',
   // The Agents panel already reflects a task's cancel/close/send through `execution_workspace_event`;
   // nothing here renders this narrower, task-only event on its own.
-  // #3282 §4c: the Project panel's reads — reduced into state by `useProjectPanelState`.
+  // The Project panel's reads — reduced into state by `useProjectPanelState`.
   project_status: 'reducer-state',
   project_diff: 'reducer-state',
   project_memory: 'reducer-state',
@@ -70,7 +70,7 @@ export const SERVER_MESSAGE_HANDLING = {
   plan_event: 'intentionally-not-rendered',
   context_file_refreshed: 'intentionally-not-rendered',
   branch_event: 'intentionally-not-rendered',
-  // #3282 §4 part b-3: the Agents panel's "Scheduled" group's own roster (`useSchedulesState`).
+  // The Agents panel's "Scheduled" group's own roster (`useSchedulesState`).
   background_tasks: 'reducer-state',
   background_task: 'intentionally-not-rendered',
   background_job_groups: 'intentionally-not-rendered',
@@ -82,14 +82,16 @@ export const SERVER_MESSAGE_HANDLING = {
   ui_intent: 'reducer-state',
   session_renamed: 'reducer-state',
   history_cleared: 'reducer-state',
-  // #3288 §1: a failed Stop (e.g. a task that finished a moment before it arrived) is worth telling
-  // the operator; a success shows itself through the workspace snapshot's own update. #3282 §4 part
-  // b-3: a schedule's Delete uses this same `cancel-background-task` write — `useSchedulesState`
+  // A failed Stop (e.g. a task that finished a moment before it arrived) is worth telling
+  // the operator; a success shows itself through the workspace snapshot's own update. A schedule's
+  // Delete uses this same `cancel-background-task` write — `useSchedulesState`
   // refreshes the roster on a successful cancel, and a failure gets the same visible notice as Stop.
   background_task_control_result: 'visible-notice',
   protocol_error: 'visible-notice',
   resume_gap: 'transport-control',
-  // #3282 §4a: the Settings screen's own correlated request/response state (`useSettingsState`).
+  // The connection's effective role: the session client holds it and stops sending what an observer may not.
+  surface_role: 'reducer-state',
+  // The Settings screen's own correlated request/response state (`useSettingsState`).
   settings: 'reducer-state',
   settings_error: 'reducer-state',
 } as const satisfies Readonly<Record<TServerMessage['type'], TServerMessageHandling>>;