Give browser surfaces a first-class activity slot; centralize browser pane record

- Move browser-surface TODO out of the transient primedActivityStates map into a
  dedicated localSurfaceActivity store (cleared on kill/replace, never consumed
  by terminal creation, live PTY outranks a stale reused-id entry)
- Extract shared restoreBrowserSurfaceTodo helper for the restore/resume paths
- Centralize the persisted browser-pane shape into browserPersistedPane() in lib,
  shared by session-save and the VS Code host refresh

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: nedtwigg

lib/src/components/Wall.tsx

@@ -15,7 +15,7 @@ import { markAgentBrowserSessionClosed } from './wall/agent-browser-sessions';
 import { KILL_CONFIRM_MS, KILL_SHAKE_MS, KillConfirmOverlay, randomKillChar, type ConfirmKill } from './KillConfirm';
 import {
   clearSessionAttention,
-  clearPrimedActivity,
+  clearLocalSurfaceActivity,
   disposeSession,
   dismissOrToggleAlert,
   focusSession,
@@ -598,7 +598,7 @@ export function Wall({
     if (!api || !panel) return;
     closeAgentBrowserSession(panel.params);
     orchestrateKill(api, id, selectPane, setSelectedId, killInProgressRef, overlayElRef);
-    clearPrimedActivity(id);
+    clearLocalSurfaceActivity(id);
     fireEvent({ type: 'kill', id });
   }, [fireEvent, selectPane]);
 
@@ -1093,7 +1093,7 @@ export function Wall({
       position: { referencePanel: panel, direction: 'within' },
     });
     api.removePanel(panel);
-    clearPrimedActivity(oldId);
+    clearLocalSurfaceActivity(oldId);
     selectPane(newId);
     return newId;
   }, [generatePaneId, selectPane]);

lib/src/lib/reconnect.test.ts

@@ -3,13 +3,13 @@ import type { PlatformAdapter, PtyInfo } from './platform/types';
 import type { PersistedSession } from './session-types';
 
 const terminalRegistryMocks = vi.hoisted(() => ({
-  primeActivity: vi.fn(),
+  restoreBrowserSurfaceTodo: vi.fn(),
   resumeTerminal: vi.fn(),
   restoreTerminal: vi.fn(),
 }));
 
 vi.mock('./terminal-registry', () => ({
-  primeActivity: terminalRegistryMocks.primeActivity,
+  restoreBrowserSurfaceTodo: terminalRegistryMocks.restoreBrowserSurfaceTodo,
   resumeTerminal: terminalRegistryMocks.resumeTerminal,
   restoreTerminal: terminalRegistryMocks.restoreTerminal,
 }));
@@ -320,7 +320,7 @@ describe('resumeOrRestore', () => {
     expect(terminalRegistryMocks.resumeTerminal).toHaveBeenCalledWith('pane-term', 'pane-term-replay', expect.anything());
   });
 
-  it('primes browser surface TODO state from persisted alert during live resume', async () => {
+  it('restores browser surface TODO from the persisted alert during live resume', async () => {
     const layout = { panels: { 'pane-term': {}, 'pane-web': {} } };
     const saved: PersistedSession = {
       version: 3,
@@ -343,12 +343,16 @@ describe('resumeOrRestore', () => {
       { id: 'pane-term', alive: true },
     ], saved));
 
-    expect(terminalRegistryMocks.primeActivity).toHaveBeenCalledWith('pane-web', {
-      status: 'WATCHING_DISABLED',
-      watchingEnabled: false,
-      todo: true,
-      notification: null,
-    });
+    // Resume delegates the browser pane to restoreBrowserSurfaceTodo, which owns
+    // routing the persisted TODO into the local activity store (verified against
+    // the real store in terminal-registry.alert.test.ts).
+    expect(terminalRegistryMocks.restoreBrowserSurfaceTodo).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: 'pane-web',
+        surfaceType: 'browser',
+        alert: expect.objectContaining({ todo: true }),
+      }),
+    );
   });
 
   it('drops visible browser panes from terminal fallback when the saved layout is rejected', async () => {

lib/src/lib/reconnect.ts

@@ -1,5 +1,5 @@
 import type { PlatformAdapter, PtyInfo } from './platform/types';
-import { primeActivity, resumeTerminal } from './terminal-registry';
+import { restoreBrowserSurfaceTodo, resumeTerminal } from './terminal-registry';
 import { readPersistedSession, type PersistedDoor } from './session-types';
 import { restoreSession } from './session-restore';
 
@@ -102,14 +102,7 @@ function getSavedPaneResumeInfo(savedState: unknown, liveIds: string[]): Map<str
   const liveSet = new Set(liveIds);
   const result = new Map<string, { title: string; untouched: boolean }>();
   for (const pane of saved.panes) {
-    if (pane.surfaceType === 'browser' && pane.alert?.todo === true) {
-      primeActivity(pane.id, {
-        status: 'WATCHING_DISABLED',
-        watchingEnabled: false,
-        todo: true,
-        notification: null,
-      });
-    }
+    restoreBrowserSurfaceTodo(pane);
     if (!liveSet.has(pane.id)) continue;
     result.set(pane.id, { title: pane.title, untouched: pane.untouched });
   }

lib/src/lib/session-activity-store.ts

@@ -1,7 +1,7 @@
 import type { SessionStatus } from './activity-monitor';
 import type { AlertButtonActionResult } from './alert-manager';
 import type { AlertStateDetail } from './platform/types';
-import type { PersistedAlertState } from './session-types';
+import type { PersistedAlertState, PersistedPane } from './session-types';
 import { getPlatform } from './platform';
 import {
   getEntryByPtyId,
@@ -21,8 +21,19 @@ export const DEFAULT_ACTIVITY_STATE: ActivityState = {
 
 const activityListeners = new Set<() => void>();
 let cachedSnapshot: Map<string, ActivityState> | null = null;
+
+// Transient staging for activity that arrives *before* a terminal registry entry
+// exists. Consumed and deleted when the entry is minted (consumePrimedActivity).
 const primedActivityStates = new Map<string, Partial<ActivityState>>();
 
+// Persistent activity for non-PTY surfaces (browser iframes / agent-browser).
+// A browser surface never gets a registry entry, so — unlike primedActivityStates
+// — this is its permanent home: keyed by pane id, written when its TODO toggles
+// or is restored, and cleared only when the pane is killed or replaced
+// (clearLocalSurfaceActivity). Kept separate so terminal creation never consumes
+// it and a no-arg primed reset never wipes it.
+const localSurfaceActivity = new Map<string, ActivityState>();
+
 export function notifyActivityListeners(): void {
   cachedSnapshot = null;
   activityListeners.forEach((listener) => listener());
@@ -37,7 +48,7 @@ export function getActivitySnapshot(): Map<string, ActivityState> {
   if (cachedSnapshot) return cachedSnapshot;
 
   const snapshot = new Map<string, ActivityState>();
-  const ids = new Set<string>([...registry.keys(), ...primedActivityStates.keys()]);
+  const ids = new Set<string>([...registry.keys(), ...primedActivityStates.keys(), ...localSurfaceActivity.keys()]);
   for (const id of ids) {
     const state = readActivity(id);
     if (state) {
@@ -67,10 +78,13 @@ function readLiveActivity(id: string): ActivityState | null {
 function readActivity(id: string): ActivityState | null {
   const primedState = primedActivityStates.get(id);
   const liveState = readLiveActivity(id);
+  const localState = localSurfaceActivity.get(id);
 
-  if (!liveState && !primedState) return null;
+  if (!liveState && !primedState && !localState) return null;
+  // A live PTY is authoritative, so it outranks a stale local-surface entry left
+  // behind if an id is reused; primed staging overrides on top.
   return {
-    ...(liveState ?? DEFAULT_ACTIVITY_STATE),
+    ...(liveState ?? localState ?? DEFAULT_ACTIVITY_STATE),
     ...primedState,
   };
 }
@@ -103,24 +117,38 @@ export function clearPrimedActivity(id?: string): void {
   notifyActivityListeners();
 }
 
+/**
+ * Drop the activity for a non-PTY surface. Called when a browser pane is killed
+ * or replaced (Wall.tsx) so its TODO doesn't outlive the pane or leak onto a
+ * later terminal that reuses the id.
+ */
+export function clearLocalSurfaceActivity(id: string): void {
+  if (!localSurfaceActivity.delete(id)) return;
+  notifyActivityListeners();
+}
+
 function setLocalSurfaceTodo(id: string, todo: boolean): void {
   if (!todo) {
-    if (!primedActivityStates.delete(id)) return;
-    notifyActivityListeners();
+    clearLocalSurfaceActivity(id);
     return;
   }
 
-  const current = readActivity(id) ?? DEFAULT_ACTIVITY_STATE;
-  primedActivityStates.set(id, {
-    ...current,
-    status: 'WATCHING_DISABLED',
-    watchingEnabled: false,
-    todo: true,
-    notification: null,
-  });
+  localSurfaceActivity.set(id, { ...DEFAULT_ACTIVITY_STATE, todo: true });
   notifyActivityListeners();
 }
 
+/**
+ * Restore a browser surface's persisted TODO into the local activity store.
+ * Browser surfaces have no PTY, so the TODO is reconstructed from the saved pane
+ * (the `alert` blob) rather than replayed from a PTY alert. Shared by the cold
+ * restore (session-restore.ts) and live resume (reconnect.ts) paths.
+ */
+export function restoreBrowserSurfaceTodo(pane: Pick<PersistedPane, 'id' | 'surfaceType' | 'alert'>): void {
+  if (pane.surfaceType === 'browser' && pane.alert?.todo === true) {
+    setLocalSurfaceTodo(pane.id, true);
+  }
+}
+
 export function consumePrimedActivity(id: string): Partial<ActivityState> | undefined {
   const primed = primedActivityStates.get(id);
   if (primed) {

lib/src/lib/session-restore.test.ts

@@ -4,13 +4,13 @@ import type { PersistedSession } from './session-types';
 
 const terminalRegistryMocks = vi.hoisted(() => ({
   getDefaultShellOpts: vi.fn(),
-  primeActivity: vi.fn(),
+  restoreBrowserSurfaceTodo: vi.fn(),
   restoreTerminal: vi.fn(),
 }));
 
 vi.mock('./terminal-registry', () => ({
   getDefaultShellOpts: terminalRegistryMocks.getDefaultShellOpts,
-  primeActivity: terminalRegistryMocks.primeActivity,
+  restoreBrowserSurfaceTodo: terminalRegistryMocks.restoreBrowserSurfaceTodo,
   restoreTerminal: terminalRegistryMocks.restoreTerminal,
 }));
 
@@ -123,7 +123,7 @@ describe('restoreSession', () => {
     expect(result?.paneIds).toEqual(['pane-term', 'pane-web']);
   });
 
-  it('primes browser surface TODO state from persisted alert during cold restore', () => {
+  it('restores browser surface TODO from the persisted alert during cold restore', () => {
     const saved: PersistedSession = {
       version: 3,
       layout: { panels: { 'pane-web': {} } },
@@ -144,11 +144,15 @@ describe('restoreSession', () => {
     restoreSession(createPlatform(saved));
 
     expect(terminalRegistryMocks.restoreTerminal).not.toHaveBeenCalled();
-    expect(terminalRegistryMocks.primeActivity).toHaveBeenCalledWith('pane-web', {
-      status: 'WATCHING_DISABLED',
-      watchingEnabled: false,
-      todo: true,
-      notification: null,
-    });
+    // Cold restore delegates the browser pane to restoreBrowserSurfaceTodo, which
+    // owns routing the persisted TODO into the local activity store (verified
+    // against the real store in terminal-registry.alert.test.ts).
+    expect(terminalRegistryMocks.restoreBrowserSurfaceTodo).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: 'pane-web',
+        surfaceType: 'browser',
+        alert: expect.objectContaining({ todo: true }),
+      }),
+    );
   });
 });

lib/src/lib/session-restore.ts

@@ -1,6 +1,6 @@
 import type { PlatformAdapter } from './platform/types';
 import { readPersistedSession, type PersistedDoor } from './session-types';
-import { getDefaultShellOpts, primeActivity, restoreTerminal } from './terminal-registry';
+import { getDefaultShellOpts, restoreBrowserSurfaceTodo, restoreTerminal } from './terminal-registry';
 
 export interface RestoredSession {
   paneIds: string[];
@@ -20,14 +20,7 @@ export function restoreSession(platform: PlatformAdapter): RestoredSession | nul
     // them via fromJSON (docs/specs/transport.md). Calling restoreTerminal here
     // would mint a stray PTY + xterm for the pane id that never gets mounted.
     if (pane.surfaceType === 'browser') {
-      if (pane.alert?.todo === true) {
-        primeActivity(pane.id, {
-          status: 'WATCHING_DISABLED',
-          watchingEnabled: false,
-          todo: true,
-          notification: null,
-        });
-      }
+      restoreBrowserSurfaceTodo(pane);
       continue;
     }
     restoreTerminal(pane.id, {

lib/src/lib/session-save.ts

@@ -1,5 +1,5 @@
 import type { PlatformAdapter } from './platform/types';
-import { readPersistedSession, type PersistedDoor, type PersistedPane, type PersistedSession, type PersistedSurfaceType } from './session-types';
+import { browserPersistedPane, readPersistedSession, type PersistedDoor, type PersistedPane, type PersistedSession, type PersistedSurfaceType } from './session-types';
 import { detectResumeCommand } from './resume-patterns';
 import { getActivity, getLivePersistedAlertState, getTerminalPaneState, isUntouched, resolveTerminalSessionId } from './terminal-registry';
 import { UNNAMED_PANEL_TITLE } from './terminal-state';
@@ -35,24 +35,10 @@ export async function saveSession(
     [...allPanes.values()].map(async (pane) => {
       const previousPane = previousPanes.get(pane.id);
       if (pane.surfaceType === 'browser') {
+        // The activity store already holds this surface's TODO; persist it as the
+        // alert blob (ActivityState is assignable to PersistedAlertState).
         const activity = getActivity(pane.id);
-        return {
-          id: pane.id,
-          title: pane.title,
-          cwd: null,
-          scrollback: null,
-          resumeCommand: null,
-          untouched: false,
-          alert: activity.todo
-            ? {
-              status: 'WATCHING_DISABLED' as const,
-              watchingEnabled: false,
-              todo: true,
-              notification: null,
-            }
-            : null,
-          surfaceType: 'browser' as const,
-        };
+        return browserPersistedPane(pane, activity.todo ? activity : null);
       }
 
       const liveAlert = getLivePersistedAlertState(pane.id);

lib/src/lib/session-types.ts

@@ -28,6 +28,29 @@ export interface PersistedPane {
   surfaceType?: PersistedSurfaceType;
 }
 
+/**
+ * Build the persisted record for a browser surface. Browser panes have no PTY,
+ * so the terminal-only fields (cwd/scrollback/resumeCommand/untouched) are always
+ * blank; the dockview `layout` blob reconstructs the surface and `alert` carries
+ * the optional TODO. Single source of truth shared by the renderer save path
+ * (`session-save.ts`) and the VS Code host refresh (`vscode-ext/session-state.ts`).
+ */
+export function browserPersistedPane(
+  pane: { id: string; title: string },
+  alert: PersistedAlertState | null,
+): PersistedPane {
+  return {
+    id: pane.id,
+    title: pane.title,
+    cwd: null,
+    scrollback: null,
+    resumeCommand: null,
+    untouched: false,
+    alert,
+    surfaceType: 'browser',
+  };
+}
+
 export interface PersistedDoor {
   id: string;
   title: string;

lib/src/lib/terminal-registry.alert.test.ts

@@ -97,8 +97,10 @@ import {
   applyTerminalSemanticEvents,
   isPaneOscDriven,
   mountElement,
+  clearLocalSurfaceActivity,
   clearSessionAttention,
   clearSessionTodo,
+  restoreBrowserSurfaceTodo,
   disposeAllSessions,
   disposeSession,
   unmountElement,
@@ -488,6 +490,36 @@ describe('terminal-registry alert behavior', () => {
     alertToggleSpy.mockRestore();
   });
 
+  it('Browser surface: restoreBrowserSurfaceTodo replays a persisted TODO; clearLocalSurfaceActivity drops it', () => {
+    const browserId = 'pane-browser-restore';
+
+    // Only browser panes whose persisted alert carries a TODO are replayed.
+    restoreBrowserSurfaceTodo({ id: browserId, surfaceType: 'browser', alert: { status: 'WATCHING_DISABLED', todo: false } });
+    expect(getActivity(browserId).todo).toBe(false);
+    restoreBrowserSurfaceTodo({ id: 'pane-term-x', surfaceType: 'terminal', alert: { status: 'WATCHING_DISABLED', todo: true } });
+    expect(getActivity('pane-term-x').todo).toBe(false);
+
+    restoreBrowserSurfaceTodo({ id: browserId, surfaceType: 'browser', alert: { status: 'WATCHING_DISABLED', todo: true } });
+    expect(getActivity(browserId).todo).toBe(true);
+
+    // Killing/replacing the pane clears the local surface activity entirely.
+    clearLocalSurfaceActivity(browserId);
+    expect(getActivity(browserId).todo).toBe(false);
+  });
+
+  it('Browser surface: a reused id prefers a live PTY over a stale local-surface TODO', () => {
+    const id = 'reused-id';
+    restoreBrowserSurfaceTodo({ id, surfaceType: 'browser', alert: { status: 'WATCHING_DISABLED', todo: true } });
+    expect(getActivity(id).todo).toBe(true);
+
+    // A terminal later minted with the same id wins: the stale browser TODO is
+    // ignored rather than leaking onto the PTY's activity.
+    createSession(id);
+    expect(getActivity(id).todo).toBe(false);
+
+    clearLocalSurfaceActivity(id);
+  });
+
   it('Story 8: disable alerts clears ring and stops tracking', () => {
     const id = 'story-8';
     createSession(id);