diff --git a/AGENTS.md b/AGENTS.md
index d51365a9..4e4206af 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -30,15 +30,15 @@ pnpm build       # build lib, vscode extension, and website
 
 The primary job of a spec is to be an accurate reference for the current state of the code. Read the relevant spec before modifying a feature it covers — the spec describes invariants, edge cases, and design decisions that are not obvious from the code alone.
 
-- **`docs/specs/glossary.md`** — Canonical vocabulary for Session states, layers (Process / Registry / View / Link / Activity / Snapshot), transition verbs, and the Liskov contract on Registry APIs. Read this first. Other specs defer to it when naming a state or a verb.
-- **`docs/specs/layout.md`** — Tiling layout, pane/door containers, dockview configuration, modes (passthrough/command), keyboard shortcuts, selection overlay, spatial navigation, minimize/reattach, inline rename, session lifecycle, session persistence, and theming. Read this when touching: `Wall.tsx`, `Baseboard.tsx`, `Door.tsx`, `TerminalPane.tsx`, `spatial-nav.ts`, `layout-snapshot.ts`, `terminal-registry.ts`, `session-save.ts`, `session-restore.ts`, `reconnect.ts`, `index.css`, `theme.css`, or any keyboard/navigation/mode behavior.
+- **`docs/specs/glossary.md`** — Canonical vocabulary: the **Surface** model (a Pane's durable occupant — a terminal **Session** or a **browser** surface, with a per-kind axis table), Session states and layers (Process / Registry / View / Link / Activity / Snapshot), the `Window ⊃ Workspace ⊃ Pane ⊃ Surface` containment hierarchy and the Workspace union status, transition verbs, and the Liskov contract on Registry APIs. Read this first. Other specs defer to it when naming a state, a surface kind, or a verb.
+- **`docs/specs/layout.md`** — Tiling layout, pane/door containers, dockview configuration, modes (passthrough/command), keyboard shortcuts, selection overlay, spatial navigation, minimize/reattach, inline rename, the standalone workspace strip (tabs, switching, lifecycle), session lifecycle, session persistence, and theming. Read this when touching: `Wall.tsx`, `Baseboard.tsx`, `Door.tsx`, `TerminalPane.tsx`, `standalone/src/AppBar.tsx`, `spatial-nav.ts`, `layout-snapshot.ts`, `terminal-registry.ts`, `session-save.ts`, `session-restore.ts`, `reconnect.ts`, `index.css`, `theme.css`, or any keyboard/navigation/mode/workspace behavior.
 - **`docs/specs/dor-cli.md`** - the `dor` CLI which is prepended onto the path of every terminal that dormouse launches.
 - **`docs/specs/dor-browser.md`** — The unified `dor` browser surface: a single `BrowserPanel` (`surfaceType: 'browser'`) with a swappable `renderMode` (`ab-screencast` / `ab-popout` / `iframe`). Covers the `dor ab` / `dor agent-browser` screencast viewer that delegates to the user's own agent-browser install (canvas screencast, input forwarding, tabs, pop-out modal) and the `dor iframe` renderer (an `<iframe>` fronted by a host-owned transparent proxy that injects a keyboard side-channel, models focus, and renders real error pages). Builds on the surface handle model in `dor-cli.md`. Read this when touching: `lib/src/components/wall/BrowserPanel.tsx`, `browser-surface.ts`, `browser-url.ts`, `AgentBrowserPanel.tsx`, `IframePanel.tsx`, `SurfacePaneHeader.tsx`, `AgentBrowserScreenModal.tsx`, `lib/src/components/wall/agent-browser-{connection,ports,screen,screenshot-loop,sessions,input}.ts`, `lib/src/lib/agent-browser-tab.ts`, `lib/src/host/agent-browser-host.ts`, `lib/src/host/iframe-proxy.ts`, `iframe-proxy-rewrite.ts`, `lib/src/lib/iframe-proxy-registry.ts`, `lib/src/lib/platform/iframe-proxy-types.ts`, `dor/src/commands/agent-browser.ts`, `dor/src/commands/iframe.ts`, `vscode-ext/src/agent-browser-host.ts`, `vscode-ext/src/iframe-proxy-host.ts`, or the browser surface wiring in `Wall.tsx`.
-- **`docs/specs/alert.md`** — Activity monitoring state machine, alert trigger/clearing rules, attention model, TODO lifecycle, bell button visual states and interaction, door alert indicators, hardening (a11y, motion, i18n, overflow), notification protocols (`OSC 9` / `OSC 9;4` / `OSC 99` / `OSC 777` / `BEL`), the `ActivityNotification` model, notification text handling and security, and the notification preview/detail UI. Read this when touching: `activity-monitor.ts`, `alert-manager.ts`, `AlertManager` notification/progress paths, the alert bell or TODO pill in `Wall.tsx` (TerminalPaneHeader), alert indicators in `Door.tsx`, the `a`/`t` keyboard shortcuts, or TODO notification preview UI. Layout.md defers to this spec for all alert/TODO behavior.
+- **`docs/specs/alert.md`** — Activity monitoring state machine, alert trigger/clearing rules, attention model, TODO lifecycle, bell button visual states and interaction, door alert indicators, hardening (a11y, motion, i18n, overflow), notification protocols (`OSC 9` / `OSC 9;4` / `OSC 99` / `OSC 777` / `BEL`), the `ActivityNotification` model, notification text handling and security, the notification preview/detail UI, and the Workspace union projection (ringing/todo/count). Read this when touching: `activity-monitor.ts`, `alert-manager.ts`, `AlertManager` notification/progress paths, the alert bell or TODO pill in `Wall.tsx` (TerminalPaneHeader), alert indicators in `Door.tsx`, the `a`/`t` keyboard shortcuts, or TODO notification preview UI. Layout.md defers to this spec for all alert/TODO behavior.
 - **`docs/specs/terminal-state.md`** — Terminal semantic state for CWD, shell prompt/editing/running/finished lifecycle, command runs, terminal title fallback, normalized semantic OSC events (`OSC 7`, `OSC 9;9`, `OSC 133`, `OSC 633`, `OSC 1337`, `OSC 0/2`), title-candidate diagnostics, header derivation, and grouping keys. Read this when touching `terminal-state.ts`, `terminal-state-store.ts`, semantic event parsing in `terminal-protocol.ts`, adapter semantic event forwarding, or derived pane/door labels.
 - **`docs/specs/terminal-escapes.md`** — Registry of every terminal escape sequence Dormouse parses or responds to: supported OSCs with pointers to the spec defining their behavior (alert.md or terminal-state.md), the canonical parsing-location and `pty:data` strip semantics, supported CSI sequences (`CSI > q`, DECSET/DECRST observation, kitty keyboard protocol) and replay-time CSI filtering, iTerm2 self-identification (env vars, fail-inertly rule), and known-unimplemented iTerm2 and clipboard-capable sequences. Read this when touching: OSC parsing at the PTY data boundary, CSI handlers in `terminal-protocol.ts` / `mouse-mode-observer.ts` / `terminal-report-filter.ts`, the iTerm2 identity env vars (`TERM_PROGRAM`, `LC_TERMINAL`), or adding support for a new escape sequence.
-- **`docs/specs/transport.md`** — Adapter-agnostic protocol shared across VS Code, standalone, and fake adapters: PTY lifecycle (decoupled from webview), `replayChunks`/`scrollbackChunks` buffering, reconnection sequence (`dormouse:init` → `pty:list` + `pty:replay`), the full webview ↔ host message protocol, persisted-session types, and universal invariants (shell login args, scrollback trailing newline, replay drop-replies-only). Read this when touching: `pty-manager.ts`, `pty-host.js`, `pty-core.js`, `message-router.ts`, `message-types.ts`, `vscode-adapter.ts`, `fake-adapter.ts`, `reconnect.ts`, `session-save.ts`, `session-restore.ts`, `session-types.ts`, or any code crossing the webview/host boundary.
-- **`docs/specs/vscode.md`** — VS Code-specific layer: hosting modes (WebviewView + WebviewPanel), extension manifest, VS Code persistence flow (`workspaceState`, `vscode.setState`, `WebviewPanelSerializer`, deactivate ordering, `mergeAlertStates` rule, `retainContextWhenHidden`), theme integration (`--vscode-*` → `--color-*` with the runtime resolver), CSP, build pipeline, and dream-architecture commands. The transport protocol it speaks (PTY lifecycle, message protocol, persisted-session types) lives in `transport.md`. Read this when touching: `extension.ts`, `webview-view-provider.ts`, `session-state.ts`, `webview-html.ts`, the theme resolver/observer in `terminal-theme.ts`, or VS Code commands and context keys.
+- **`docs/specs/transport.md`** — Adapter-agnostic protocol shared across VS Code, standalone, and fake adapters: PTY lifecycle (decoupled from webview), `replayChunks`/`scrollbackChunks` buffering, reconnection sequence (`dormouse:init` → `pty:list` + `pty:replay`), the full webview ↔ host message protocol, persisted-session types (including the `PersistedWorkspace` / `PersistedWindow` container and its migration), and universal invariants (shell login args, scrollback trailing newline, replay drop-replies-only). Read this when touching: `pty-manager.ts`, `pty-host.js`, `pty-core.js`, `message-router.ts`, `message-types.ts`, `vscode-adapter.ts`, `fake-adapter.ts`, `reconnect.ts`, `session-save.ts`, `session-restore.ts`, `session-types.ts`, or any code crossing the webview/host boundary.
+- **`docs/specs/vscode.md`** — VS Code-specific layer: hosting modes (WebviewView + WebviewPanel), the webview ↔ Workspace mapping and union-status reflection onto native tab icon/title and view badge, extension manifest, VS Code persistence flow (`workspaceState`, `vscode.setState`, `WebviewPanelSerializer`, deactivate ordering, `mergeAlertStates` rule, `retainContextWhenHidden`), theme integration (`--vscode-*` → `--color-*` with the runtime resolver), CSP, build pipeline, and dream-architecture commands. The transport protocol it speaks (PTY lifecycle, message protocol, persisted-session types) lives in `transport.md`. Read this when touching: `extension.ts`, `webview-view-provider.ts`, `session-state.ts`, `webview-html.ts`, the theme resolver/observer in `terminal-theme.ts`, or VS Code commands and context keys.
 - **`docs/specs/tutorial.md`** — Playground tutorial on the website: 3-pane layout, interactive `tut` TUI runner with three sections (keyboard navigation, alerts/TODOs, copy/paste), per-item detection wired to `WallEvent` / activity store / mouse-selection store, single-key `dormouse-tut-v3` localStorage scheme, theme picker, and FakePtyAdapter extensions (`sendOutput`, `pumpActivity`, `setInputHandler`). Read this when touching: `website/src/pages/PlaygroundDesktop.tsx`, `website/src/pages/PocketPlayground.tsx`, `website/src/components/PocketTerminalExperience.tsx`, `website/src/lib/playground-routing.ts`, the `website/src/pages/Playground.tsx` and `website/src/pages/Pocket.tsx` redirect dispatchers, `website/src/lib/tut-runner.ts`, `website/src/lib/tut-detector.ts`, `website/src/lib/tutorial-state.ts`, `website/src/lib/tut-items.ts`, `website/src/lib/tutorial-shell.ts`, `lib/src/components/ThemePicker.tsx`, `lib/src/lib/themes/`, `lib/src/lib/platform/fake-scenarios.ts` (tutorial scenarios), the `WallEvent` union, or the `onApiReady`/`onEvent`/`initialPaneIds` props on Wall.
 - **`docs/specs/theme.md`** — Theme system: two-layer CSS variable strategy, theme data model, conversion pipeline, bundled themes, localStorage store, shared ThemePicker component, standalone AppBar picker, runtime OpenVSX installer. Read this when touching: `lib/src/lib/themes/`, `lib/src/components/ThemePicker.tsx`, `lib/src/theme.css`, `lib/scripts/bundle-themes.mjs`, `standalone/src/AppBar.tsx` (theme picker), `standalone/src/main.tsx` (theme restore), or `website/src/components/SiteHeader.tsx` (themeAware mode).
 - **`docs/specs/mouse-and-clipboard.md`** — Terminal-owned text selection, copy (Raw / Rewrapped), bracketed paste, smart URL/path extension, mouse-reporting override UI (icon + banner), and the state matrix for which layer owns mouse events. Read this when touching: `lib/src/lib/mouse-selection.ts`, `lib/src/lib/mouse-mode-observer.ts`, `lib/src/lib/clipboard.ts`, `lib/src/lib/rewrap.ts`, `lib/src/lib/selection-text.ts`, `lib/src/lib/smart-token.ts`, `lib/src/components/SelectionOverlay.tsx`, `lib/src/components/SelectionPopup.tsx`, the mouse icon / override banner / Cmd+C-V handling in `lib/src/components/Wall.tsx`, or the parser hooks + mouse listeners in `lib/src/lib/terminal-registry.ts`.
diff --git a/DESIGN.md b/DESIGN.md
index d75d379c..6ffcc1b1 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -221,7 +221,8 @@ The system uses **raised surfaces**, not "cards." There are no nested cards. The
 
 ### Navigation
 
-The system has no traditional top-nav. Two surfaces play navigational roles:
+The system has no traditional product top-nav. Three surfaces play navigational roles:
+- **Workspace strip** (standalone app bar, top): horizontal tabs, one per Workspace, for switching between Workspaces within one window. Inactive tabs carry the union alert/TODO indicators (bell + TODO pill) borrowed from the Door vocabulary; the active tab carries none. This is standalone app-bar chrome around the Wall — see `docs/specs/layout.md` and `docs/specs/alert.md` — and its exact visual treatment is being designed in Storybook. VS Code surfaces the same status on its own native tab/badge chrome instead (`docs/specs/vscode.md`).
 - **Baseboard** (bottom of the app): horizontal strip of doors representing minimized panes plus chrome action buttons. Doors are the primary navigation affordance to a minimized terminal. Button style: `h-5 rounded px-1.5 text-sm font-medium font-mono text-muted` with `hover:bg-surface-raised hover:text-foreground transition-colors`.
 - **Pane Header (TerminalPaneHeader)**: the tab-replacing strip at the top of each pane. Tab-bar styling is stripped from dockview entirely (`--dv-tabs-and-actions-container-*` overrides); the React header IS the tab.
 
diff --git a/docs/specs/alert.md b/docs/specs/alert.md
index a81f4dee..b82a9e81 100644
--- a/docs/specs/alert.md
+++ b/docs/specs/alert.md
@@ -2,7 +2,7 @@
 
 > See `docs/specs/glossary.md` for Session / Pane / Door vocabulary. This spec uses it throughout.
 
-Alert state belongs to the **Session** Activity layer. It survives Pane <-> Door movement and is destroyed with the Session.
+Terminal alert state belongs to the **Session** Activity layer. It survives Pane <-> Door movement and is destroyed with the Session. This spec also defines how the Workspace union counts browser-surface TODO flags: a browser Surface has no Session Activity machine, can never ring, and carries only a user-set TODO flag as Surface state that is destroyed with that browser Surface.
 
 Dormouse can owe the user attention in three ways:
 
@@ -22,7 +22,7 @@ Terminal-report and command-exit alerts do not require WATCHING to be enabled. A
 
 ## Public State
 
-Source of truth: `AlertState` / `ActivityNotification` in `lib/src/lib/alert-manager.ts` and `SessionStatus` in `lib/src/lib/activity-monitor.ts` define the public Activity state. Internal state is deliberately split into independent tracks (`watchingStatus`, `protocolStatus`, `commandExitStatus`, plus `progress` and `commandExitWatch` companion state) so each axis evolves without entangling the others.
+Source of truth: `AlertState` / `ActivityNotification` in `lib/src/lib/alert-manager.ts` and `SessionStatus` in `lib/src/lib/activity-monitor.ts` define the public Activity state for terminal Sessions. Internal state is deliberately split into independent tracks (`watchingStatus`, `protocolStatus`, `commandExitStatus`, plus `progress` and `commandExitWatch` companion state) so each axis evolves without entangling the others.
 
 Public `status` is a projection — first match wins:
 
@@ -173,6 +173,31 @@ Clearing behavior:
 
 `attentionDismissedRing` exists so the next bell click after an attention-based dismissal opens the dialog instead of silently disabling WATCHING.
 
+## Workspace union
+
+> See `docs/specs/glossary.md` for the Workspace / Window containers.
+>
+> **Not yet implemented (stage 2b).** The union projection and its surfacing are specified ahead of the code. The implemented piece (stage 2a) is that a browser Surface's user-set `todo` round-trips to the activity store live, so its door shows the TODO pill — the same input the union will read once it exists.
+
+A Workspace projects a **union status** over the attention state of the Surfaces it contains (terminal Sessions and browser Surfaces alike — see `docs/specs/glossary.md`):
+
+- `ringing` — any member terminal Session's public `status` is `ALERT_RINGING`. Only terminal Sessions ring; a browser Surface has no BEL/OSC source and never reaches `ALERT_RINGING`.
+- `todo` — any member Surface has `todo === true`. A terminal Session or a browser Surface may be flagged.
+- `count` — number of member Surfaces owing attention (ringing or `todo`), for the numeric badge a host may show.
+
+Rules:
+
+- The union is **display-only** and derived. It never enters the terminal Activity state machine, never fires a fresh ring, and produces no sound or notification of its own; it only mirrors member state. Every terminal ringing/TODO transition above remains per-Session, and every browser TODO transition remains per-browser Surface.
+- Membership includes minimized (`Doored`) Surfaces and, in standalone, the Surfaces of inactive (unmounted) Workspaces. A terminal Session's Activity survives minimize and unmount (glossary I2/I3) and a browser Surface's `todo` survives in its persisted params, so a backgrounded Surface can light up its Workspace's indicator.
+- Attention suppression needs no special-casing: a per-Session ring is already suppressed while that Session is attended, so the union simply reflects whatever rings survive.
+
+Where the union surfaces is host-specific:
+
+- **Standalone:** each inactive Workspace's tab in the strip shows the union `ringing` bell and `todo` pill, reusing the Door indicator vocabulary (`bellIconClass`, the TODO pill). The **active** Workspace's tab shows no union indicator — its rings and TODOs are already visible on its own panes and doors. See `docs/specs/layout.md`.
+- **VS Code:** the host reflects the **terminal** portion of each Workspace's union onto the webview's native chrome — an editor tab's icon (and optionally title) and the sidebar view's numeric badge. Browser-surface TODO stays webview-local and is not shown on native chrome until a future webview→host Surface-state channel exists. See `docs/specs/vscode.md`.
+
+This spec fixes the projection and the surfacing rules; the exact visual treatment of the standalone strip is settled in the Storybook UI pass.
+
 ## UI Contract
 
 ### Pane Header
diff --git a/docs/specs/dor-browser.md b/docs/specs/dor-browser.md
index 7ad5133d..94b3cdd0 100644
--- a/docs/specs/dor-browser.md
+++ b/docs/specs/dor-browser.md
@@ -1,8 +1,9 @@
 # Dor Browser Surface
 
-> See `docs/specs/glossary.md` for canonical Session and Pane vocabulary, and
-> `docs/specs/dor-cli.md` for the shared `dor` CLI, surface handle model, and
-> host control plumbing this surface builds on.
+> See `docs/specs/glossary.md` for canonical Surface / Session / Pane vocabulary
+> (a browser pane is a **browser Surface**), and `docs/specs/dor-cli.md` for the
+> shared `dor` CLI, surface handle model, and host control plumbing this surface
+> builds on.
 
 Dormouse has one dockview component for web content: `BrowserPanel`, persisted as
 `surfaceType: 'browser'` with a swappable `renderMode`.
diff --git a/docs/specs/dor-cli.md b/docs/specs/dor-cli.md
index df561528..544f63d8 100644
--- a/docs/specs/dor-cli.md
+++ b/docs/specs/dor-cli.md
@@ -1,8 +1,9 @@
 # Dor CLI
 
-> See `docs/specs/glossary.md` for canonical Session and Pane vocabulary.
-> `dor` uses `surface` for user-facing CLI handles. Pane remains layout
-> vocabulary in the implementation and in existing compatibility commands.
+> See `docs/specs/glossary.md` for canonical Surface / Session / Pane vocabulary.
+> A **Surface** (the durable occupant of a Pane — a terminal Session or a browser
+> surface) is `dor`'s user-facing CLI handle. Pane remains layout vocabulary in the
+> implementation and in existing compatibility commands.
 
 Dormouse bundles a `dor` CLI into every terminal it launches. The CLI is the
 public API; any socket used underneath it is private host plumbing.
@@ -113,11 +114,15 @@ that owns that surface when one is available.
 
 ## Handle Model
 
-Dormouse currently exposes one workspace and one window internally, but no
-workspace/window targeting CLI flags. Each visible Pane has one selected
-surface. Most surfaces are terminals; `dor iframe` introduces a non-terminal
-iframe surface. User-facing `dor` commands should expose surface handles; Pane
-remains layout vocabulary and compatibility-command terminology.
+Dormouse supports multiple Workspaces within one Window (`docs/specs/glossary.md`):
+standalone hosts several Workspaces with one active, and VS Code maps each webview
+to a Workspace. The handle model therefore reserves `workspace:<n|name>` and
+`window:<n>` refs. The full containment hierarchy is `Window ⊃ Workspace ⊃ Pane ⊃
+Surface`. Each visible Pane has one selected Surface; a Surface is a terminal (a
+Session) or a browser surface — the `iframe` / agent-browser renderers of `dor`'s
+unified `browser` surface (`docs/specs/dor-browser.md`). User-facing `dor` commands
+expose Surface handles; Pane remains layout vocabulary and compatibility-command
+terminology.
 
 Invariants:
 
@@ -130,14 +135,21 @@ Invariants:
   `surface:1`, `pane:2`.
 - List output defaults to refs; commands that list handles accept
   `--id-format refs|uuids|both`.
-- Workspace/window refs and target flags will be added only when Dormouse
-  actually supports them.
+- Workspace/window refs are defined now that Dormouse supports multiple
+  Workspaces: `workspace:<n>` (and `workspace:<name>` when exactly one Workspace
+  matches) and `window:<n>` select a container. A `--workspace` target flag and
+  `dor workspace` management commands (list / new / rename / close / switch) are
+  the next handles to expose; like every other command they ship with their
+  snapshot-tested help and the control methods that back them, not ahead of them.
 
 ## Current Implemented Commands
 
 Implemented commands call private `surface.*` control methods. `surface.list`
 derives its response from current Dockview panels plus terminal state/activity
-snapshots where available, then returns `workspace:1` and `window:1`.
+snapshots where available, then returns `workspace:1` and `window:1`. Once
+`surface.list` is made Workspace-aware it tags each surface with the real
+`workspace:<n>` / `window:<n>` membership defined above; until then it reports the
+single active Workspace.
 
 Command tails captured after `--` are sent as raw argv arrays (`command:
 string[]`); the host — not `dor` — quotes them for the target shell. `dor`
diff --git a/docs/specs/glossary.md b/docs/specs/glossary.md
index e72cda88..dade9f87 100644
--- a/docs/specs/glossary.md
+++ b/docs/specs/glossary.md
@@ -4,17 +4,92 @@ This glossary is the canonical vocabulary for states, entities, and transitions
 
 ## The core idea
 
-A **Session** is the durable unit. A Session's state lives on six orthogonal axes — change one without touching the others. A caller holding a `SessionId` can reason about each axis independently.
+A **Surface** is the durable occupant of a Pane — what a user thinks of as "the content in this slot." A Surface is one of two kinds:
+
+- a **terminal Surface**, which Dormouse calls a **Session**: a PTY-backed shell with scrollback and semantic terminal state. This is the unit the six-axis model below describes.
+- a **browser Surface**: a web view rendered as an `iframe` or an agent-browser screencast / pop-out (`docs/specs/dor-browser.md`). It participates in only a subset of the axes — see [Panes and Surfaces](#panes-and-surfaces).
+
+A **Session**'s state lives on six orthogonal axes — change one without touching the others. A caller holding a `SessionId` can reason about each axis independently. Unless a passage says "Surface" or "browser Surface," it is describing a Session.
 
 The **Liskov contract**: a Session is substitutable across most operations regardless of which states it currently occupies. `kill` and `rename` work universally. State-gated operations (`write`, `focus`) document their preconditions in glossary terms rather than failing silently.
 
+## Panes and Surfaces
+
+The unit of *layout* is a **Pane**; the unit of *content* is a **Surface**.
+
+| Term | Is | Owner |
+|---|---|---|
+| **Pane** | A slot in the tiling layout (one dockview panel). Holds one or more Surfaces, exactly one selected. | `lib/src/components/Wall.tsx` (dockview) |
+| **Surface** | The content in a Pane: a **terminal** (a Session) or a **browser** Surface. | `Wall.tsx`; browser surfaces per `docs/specs/dor-browser.md` |
+
+Today every Pane holds exactly one Surface, but the model reserves multiple Surfaces per Pane (a future in-pane surface strip) — which is why a Surface ref (`surface:N`) is distinct from a Pane ref (`pane:N`).
+
+**Surface kinds** — the `type` a `dor` handle reports, derived from the Pane's params, never stored on the id:
+
+| Kind | Sub-kinds | Backed by |
+|---|---|---|
+| `terminal` | — | a PTY + xterm.js instance — i.e. a **Session** |
+| `browser` | `iframe`, `ab-screencast`, `ab-popout` | an iframe proxy grant, or an agent-browser daemon session (`docs/specs/dor-browser.md`) |
+
+A **Session** runs the full six-axis model below. A **browser Surface** participates only where a web view meaningfully can:
+
+| Axis | Terminal Surface (Session) | Browser Surface |
+|---|---|---|
+| **View** | full | full — `Paned` / `Zoomed` / `Doored` / `Hidden` all apply |
+| **Activity** | full machine (ring + TODO) | **TODO only** — a user may flag it; it never auto-rings (no BEL/OSC source) |
+| **Snapshot** | scrollback, cwd, alert | its `surfaceType` + render params (`docs/specs/transport.md`) |
+| **Process** | PTY (`Live`/`Exited`/`Tombstoned`/`Absent`) | none — host lifetime is the agent-browser session or proxy grant, keyed outside the Pane id |
+| **Registry** | xterm Terminal + persistent DOM element | none — DOM owned by dockview (`renderer:'always'`); focus via a lightweight handle |
+| **Link** | resume / replay over the live PTY | none — rebuilt from persisted params, not replayed |
+
+The containment hierarchy the `dor` CLI handle model commits to (`docs/specs/dor-cli.md`):
+
+```
+Window ⊃ Workspace ⊃ Pane ⊃ Surface  (terminal = Session | browser)
+```
+
+**Surface identity:** a Surface's id is its dockview panel id. For a terminal Surface that id *is* the `SessionId` and is stable (I1). A browser Surface's id is **not** preserved across a render-mode swap: switching `iframe` ⇄ `ab-screencast` ⇄ `ab-popout` replaces the Surface in the same Pane slot (new id), preserving only the slot and target URL (`docs/specs/dor-browser.md`).
+
+## Containers
+
+A Surface never floats free: it sits in a **Pane**, every Pane belongs to exactly one **Workspace**, and every Workspace belongs to one **Window**. Workspace and Window are containers, not Session layers — they group Surfaces rather than describing one Surface's state, so they sit beside the six axes above, not on them.
+
+| Container | Holds | Owner |
+|---|---|---|
+| **Window** | One or more Workspaces. The OS frame (the standalone Tauri window) or the host frame (a VS Code window). | host (Tauri / VS Code) |
+| **Workspace** | A named set of Panes and their Surfaces, plus the layout that arranges them (dockview snapshot + doors). Exactly one **Wall** renders one Workspace. | `lib/src/components/Wall.tsx` at render time; persisted per `docs/specs/transport.md` |
+
+A **Workspace** is the durable grouping a user thinks of as "a window's worth of panes." It has a `WorkspaceId`, a user-facing `name`, the Surfaces it contains, and the layout that arranges them. The pre-workspace model had exactly one implicit Workspace per Window; the model now allows several.
+
+How many are visible at once is host-specific:
+
+- **Standalone** hosts many Workspaces in one Window but mounts only one at a time — the **active** Workspace. Switching mounts the target Workspace's Surfaces and unmounts the previous one's; PTYs stay `Live` and Activity keeps flowing. Workspaces appear as a tab strip (see `docs/specs/layout.md`).
+- **VS Code** maps one Workspace to one webview: the sidebar/panel `WebviewView` is the default Workspace, and each `dormouse.open` editor-tab `WebviewPanel` is an independent Workspace. Several are visible at once. A webview owns its terminal Sessions' PTYs (`ownedPtyIds`, `docs/specs/transport.md`) plus its own browser Surfaces; see `docs/specs/vscode.md`.
+
+### Workspace union status
+
+A Workspace projects a **union status** over its member Surfaces' Activity (transition rules in `docs/specs/alert.md`):
+
+- `ringing` — any member Surface has `status === 'ALERT_RINGING'`. Only terminal Sessions ring.
+- `todo` — any member Surface has `todo === true`: a terminal Session, or a browser Surface a user has flagged.
+- `count` — number of member Surfaces currently owing attention (ringing or `todo`), for hosts that show a numeric badge.
+
+The union is **display-only**: it is derived from member Activity, never enters the Activity state machine, and never itself fires a ring. Minimized (`Doored`) and unmounted (inactive-Workspace) Surfaces are included, because their Activity (Session) or persisted params (browser Surface) survive minimize/unmount (I2, I3).
+
+### Implementation status
+
+This vocabulary is the target model; it lands in stages, so parts of it are specified ahead of the code. As of this spec:
+
+- **Implemented** — **Pane** and **Surface** as first-class concepts, the terminal/browser surface kinds and their per-axis participation, `surfaceType` in the persisted snapshot, and the restore/resume handling that keeps browser Surfaces (no stray PTY, saved layout preserved; `docs/specs/transport.md`). A browser Surface's user-set `todo` already round-trips to the activity store live.
+- **Not yet implemented** — the **Workspace** and **Window** containers themselves: `PersistedWorkspace` / `PersistedWindow`, the container verbs (`switchWorkspace` / `createWorkspace` / `closeWorkspace` / `renameWorkspace`), the union projection, and the standalone workspace strip. The app today runs exactly one implicit Workspace per Window. The container layer lands behind a feature flag (**stage 2b**, dormant in-app), the switching UI follows (**stage 3**), and real multi-Workspace support comes last (**stage 4**). Container/union/strip passages below and in the area specs are forward-looking until then.
+
 ## Layers
 
 | Layer | Tracks | Owner |
 |---|---|---|
 | **Process** | PTY life on the host | `vscode-ext/src/pty-manager.ts` |
 | **Registry** | xterm.js Terminal + persistent DOM element + cached Activity state | `lib/src/lib/terminal-registry.ts` facade, backed by `terminal-store.ts`, `terminal-lifecycle.ts`, and `session-activity-store.ts` |
-| **View** | Where and how the session renders | `lib/src/components/Wall.tsx` plus `lib/src/components/wall/` |
+| **View** | Where and how a Surface renders (terminal and browser alike) | `lib/src/components/Wall.tsx` plus `lib/src/components/wall/` |
 | **Link** | Webview ↔ host relationship | `lib/src/lib/reconnect.ts` |
 | **Activity** | Alert / attention state machine | `lib/src/lib/alert-manager.ts` |
 | **Snapshot** | Persisted-to-disk projection | `lib/src/lib/session-save.ts` / `session-restore.ts` |
@@ -48,7 +123,7 @@ A **Session** is the tuple of its `SessionId` plus one state per layer. `Session
 | `Paned` | Rendered as a pane in the content area (dockview group) |
 | `Zoomed` | Subset of `Paned` — the selected pane is maximized |
 | `Doored` | Rendered as a door on the baseboard |
-| `Hidden` | In neither — the webview itself is closed, or the session is mid-transition |
+| `Hidden` | In neither pane nor door — the webview is closed, the Surface belongs to an inactive Workspace (standalone), or the Surface is mid-transition. Process and Activity are unaffected. |
 
 ### Link
 
@@ -65,6 +140,8 @@ Keep the existing state machine (see `docs/specs/alert.md` for transition rules)
 
 `WATCHING_DISABLED` · `NOTHING_TO_SHOW` · `MIGHT_BE_BUSY` · `BUSY` · `OSC_NOTIF_BUSY` · `COMMAND_EXIT_ARMED` · `MIGHT_NEED_ATTENTION` · `ALERT_RINGING`
 
+Terminal Sessions run this machine. A browser Surface has no machine: it carries only an optional user-set `todo` and never reaches `ALERT_RINGING` (there is no BEL/OSC source to ring it).
+
 ### Snapshot
 
 | State | Meaning |
@@ -82,12 +159,16 @@ A user verb is an intentional action that produces a single observable change.
 | Verb | Effect |
 |---|---|
 | `spawn` | Create a new Session (Process: Absent → Live) |
-| `kill` | Request termination (Process: Live → Tombstoned, Registry: Mounted → Disposed, View: any → Hidden) |
+| `kill` | Terminate a Surface. Terminal: Process Live → Tombstoned, Registry Mounted → Disposed. Browser: closes its agent-browser session or iframe proxy grant. Either way View: any → Hidden. |
 | `minimize` | Pane → Door (View: Paned → Doored) |
 | `reattach` | Door → Pane (View: Doored → Paned) |
 | `rename` | Update title; layer-agnostic |
 | `zoom` / `unzoom` | Paned ↔ Zoomed |
 | `swap` | Exchange Registry entries across two View slots without touching Processes |
+| `switchWorkspace` | Activate a different Workspace: mount its Surfaces, unmount the previously active Workspace's (standalone). View: target's Surfaces Hidden → Paned/Doored, previous active's Paned/Doored → Hidden. Process and Activity unchanged. |
+| `createWorkspace` | Add a new Workspace to the Window; standalone makes it active and spawns its first pane |
+| `closeWorkspace` | Remove a Workspace, `kill`-ing each member Surface |
+| `renameWorkspace` | Update a Workspace's `name`; touches no Session |
 
 ### System verbs
 
@@ -123,6 +204,10 @@ A caller holding a `SessionId` can issue universal operations without branching.
 - I4: `Registry: Orphaned` is transient. Steady states are `Mounted` or `Disposed`.
 - I5: `kill` is universally valid. It always terminates at (Process: Tombstoned, Registry: Disposed, View: Hidden).
 - I6: `rename` is universally valid including when `Process = Exited` and `View = Doored`.
+- I7: Every Surface sits in exactly one Pane; every Pane and its Surfaces belong to exactly one Workspace; every Workspace belongs to one Window.
+- I8: `switchWorkspace` preserves Process and Activity for both Workspaces. Mounting an inactive Workspace's Surfaces must not fire a fresh ring, the same rule as `mount` / `reattach` in I3.
+- I9: A Workspace's union status is a pure projection of its member Surfaces' Activity. It has no independent state and is destroyed with the Workspace.
+- I10: A terminal Surface's id is its stable `SessionId` (I1). A browser Surface's id is *not* preserved across a render-mode swap: the swap replaces the Surface in the same Pane slot, preserving only the slot and target URL.
 
 ## Retired / overloaded terms
 
@@ -134,14 +219,17 @@ Use glossary names instead of these. The left column retains a meaning only wher
 | **reconnect** | Retired. Live-PTY case → **resume**; cold start → **restore**. |
 | **restore** | Keeps its meaning for cold-start rehydrate. Do not use it for Door→Pane (that is **reattach**) or for alert-manager seeding (that is **seed**). |
 | **attach** | Retired at the DOM layer (was `attachTerminal`) → **mount**. User-level "reattach" (Door→Pane) keeps the `re-` prefix. |
-| **session** | Keeps its meaning as the durable identity. Do not use it for the Activity projection (that is `ActivityState`, not `SessionUiState`). |
-| **terminal** | Keeps its meaning for the `xterm.Terminal` instance. Prose meaning "the whole thing" is **Session**. |
-| **panel / pane** | Prefer **pane**. Use "panel" only when quoting dockview's own API (`api.panels`, `addPanel`). |
+| **session** | The durable identity of a **terminal Surface**. Do not use it for the Activity projection (that is `ActivityState`, not `SessionUiState`), nor for the agent-browser daemon's lowercase `session` string (`dormouse.1.<key>`), which is not a Dormouse durable unit. |
+| **terminal** | Keeps its meaning for the `xterm.Terminal` instance. Prose meaning "the whole thing" is **Session** (a terminal Surface). |
+| **surface** | A glossary term, not retired: the durable occupant of a Pane (a terminal Session or a browser Surface). Use **Session** only for the terminal kind; use **Surface** when a statement holds for both. |
+| **panel / pane** | Prefer **pane** for the layout slot. Use "panel" only when quoting dockview's own API (`api.panels`, `addPanel`). |
 
 ## Naming conventions
 
 - Layer names and state names are `PascalCase` nouns (`Paned`, `Tombstoned`).
 - Verbs are `camelCase` in code and lowercase in prose (`minimize`, not `Minimize`).
 - Event kind strings match the verb: `'minimizeChange'`, not `'detachChange'`.
-- A persisted type is `Persisted<Shape>` where `<Shape>` is the glossary noun (`PersistedPane`, `PersistedDoor`).
+- A persisted type is `Persisted<Shape>` where `<Shape>` is the glossary noun (`PersistedPane`, `PersistedDoor`, `PersistedWorkspace`, `PersistedWindow`).
 - A handle type is `<Layer>State` (`ActivityState`, not `SessionUiState`).
+- Surface kinds are lowercase strings: the CLI `SurfaceType` is `'terminal' | 'iframe' | 'agent-browser'`; the component-level split is `'terminal' | 'browser'`. A browser Surface records its kind via `surfaceType` on its persisted per-pane record (`docs/specs/transport.md`).
+- Container names are `PascalCase` nouns (`Workspace`, `Window`); their ids are `WorkspaceId` and `WindowId`. Container verbs keep the container as a suffix (`createWorkspace`, `switchWorkspace`) to stay distinct from the layer-agnostic Session `rename`.
diff --git a/docs/specs/layout.md b/docs/specs/layout.md
index 0e423388..585c7e48 100644
--- a/docs/specs/layout.md
+++ b/docs/specs/layout.md
@@ -4,20 +4,24 @@
 
 ## Conceptual model
 
+A **Pane** holds a **Surface** — the content in that layout slot. A Surface is either a **terminal Session** or a **browser surface** (`iframe` / agent-browser); `docs/specs/glossary.md` is canonical for the Pane / Surface / Session model and `docs/specs/dor-browser.md` for browser surfaces. This spec uses "Session" where a statement is terminal-specific and "Surface" where it holds for both kinds.
+
 A **Session** is a single PTY instance — a running shell process with its scrollback, environment, and semantic terminal state. Sessions are managed by the terminal registry and persist independently of how they are displayed. Each session also carries Activity state (projected alert status, optional TODO flag, and optional protocol notification detail). CWD, foreground-command lifecycle, command titles, terminal titles, header derivation, and grouping keys are defined in `docs/specs/terminal-state.md`.
 
-A Session's **View** state places it in one of two containers:
+A Surface's **View** state places it in one of two containers:
 
-- **Pane** — a visible container in the content area. The session's terminal output is rendered via xterm.js. The pane has a header with controls and acts as the drag handle for layout rearrangement.
-- **Door** — a minimized container in the baseboard. The session is still alive (PTY running, output buffered) but not visible. The door shows the session's title plus alert and TODO indicators, and looks like a mouse hole cut into the baseboard.
+- **Pane** — a visible container in the content area. A terminal Surface renders its output via xterm.js; a browser surface renders through `BrowserPanel`. The pane has a header with controls and acts as the drag handle for layout rearrangement.
+- **Door** — a minimized container in the baseboard. The Surface is still alive (a terminal's PTY keeps running and buffering output; a browser surface's backing session or proxy grant stays alive) but not visible. The door shows the Surface's title plus alert and TODO indicators, and looks like a mouse hole cut into the baseboard.
 
-Transitioning between Pane and Door does not alter the Session in any way.
+Transitioning between Pane and Door does not alter the Surface in any way.
 Minimizing a pane creates a door; reattaching a door creates a pane. Terminal
 content, scrollback, and process state are preserved across transitions. For
 non-terminal browser surfaces, the backing browser session remains alive while
 the visible viewer resources are released: no canvas, screencast WebSocket,
 screenshot loop, or input forwarding runs while the surface is a Door.
 
+A **Workspace** is the named group of Surfaces rendered by a single **Wall**, together with their layout (see `docs/specs/glossary.md`). A Window may hold several Workspaces. This spec covers how Workspaces are presented and switched in the standalone app — the tab strip and the one-Wall-per-Workspace mounting below. VS Code maps each Workspace to its own webview instead; see `docs/specs/vscode.md`.
+
 ## Shell layout
 
 There are two areas:
@@ -141,6 +145,30 @@ Clicking an overflow arrow reveals one door in that direction. A longer title ma
 
 Extreme case: a single door with a very long title, with more doors on both sides. Show both arrows with counts, and the single door with as much title as fits (ellipsis for the rest).
 
+## Workspaces
+
+> See `docs/specs/glossary.md` for the Workspace / Window containers and `docs/specs/alert.md` for the union status. VS Code's per-webview mapping is in `docs/specs/vscode.md`.
+>
+> **Not yet implemented (stages 2b/3).** This section is specified ahead of the code. The app today runs one implicit Workspace; the container, switching, and strip land behind a feature flag (the glossary's Implementation status has the staging). Stage 2a — `surfaceType` persistence and the browser-surface restore/resume fixes — is implemented.
+
+A **Workspace** is one Wall's worth of Surfaces (terminal Sessions and browser surfaces) plus its layout, with a user-facing name. The standalone Window hosts several Workspaces but mounts only one — the **active** Workspace — at a time. Each Workspace owns its own Content (dockview layout) and Baseboard (doors).
+
+### Workspace strip (standalone)
+
+The standalone app bar (`standalone/src/AppBar.tsx`) carries a horizontal **workspace strip**: one tab per Workspace, living in the app bar's draggable region at the top of the window. Each tab shows the Workspace `name` and, for **inactive** Workspaces, the union `ringing` bell and `todo` pill from `docs/specs/alert.md`, reusing the Door indicator vocabulary. The **active** Workspace's tab shows no union indicator: its alerts are already visible on its own panes and doors. Exact tab visuals are settled in the Storybook UI pass.
+
+### Switching
+
+Activating another Workspace (`switchWorkspace`) mounts the target Workspace's Surfaces into the Wall — rebuilding its dockview layout and reattaching its doors — and unmounts the previously active Workspace's Surfaces. For a terminal Surface this reuses the `mount` / `unmount` registry ops: the Registry entry and PTY survive `unmount`, so Process stays `Live`. A browser surface's backing agent-browser session or proxy grant likewise survives while its viewer resources are released. Because a terminal's Activity keeps flowing while unmounted, an inactive Workspace's tab can begin ringing or showing TODO while the user is elsewhere. Mounting must not fire a fresh ring (glossary I8, mirroring the minimize/reattach rule I3).
+
+### Lifecycle
+
+- **Create** (`createWorkspace`): adds a new Workspace, gives it a default name (`Workspace N`), makes it active, and spawns a single fresh pane — matching the empty-state behavior in Session persistence below.
+- **Close** (`closeWorkspace`): `kill`s each member Surface and removes the Workspace. Closing a Workspace that contains touched Surfaces confirms first (reusing the kill-confirm vocabulary); the exact confirmation surface is settled in the Storybook UI pass. The last remaining Workspace cannot be closed — there is always one active Workspace, just as there is always one visible pane (corner case #10).
+- **Rename** (`renameWorkspace`): edits the Workspace `name` only. It does not touch any Surface title or the per-pane inline rename.
+
+Concrete switch/create/close/rename keyboard shortcuts are chosen alongside the Storybook UI pass. Command mode is the natural home for them, following the tmux *window* bindings the rest of the keymap mirrors (a Dormouse Workspace is the analogue of a tmux window).
+
 ## Modes
 
 Wall starts in `command` mode by default. Embedders may pass `initialMode="passthrough"` when the first pane is an already-running interactive surface that should receive keyboard input immediately.
@@ -280,7 +308,7 @@ User-pin titles must not start with `<idle>` (the sentinel that prefixes the aut
 
 ## Session lifecycle and terminal registry
 
-Pane IDs are session IDs. `TerminalPane` calls `getOrCreateTerminal(id)` on React mount and `unmountElement(id)` on React unmount. The session (xterm.js instance, PTY, DOM element) persists in the registry across mount/unmount cycles — the DOM element is detached from its container but the Registry entry stays `Mounted`.
+For a terminal Surface the pane ID is its session ID. `TerminalPane` calls `getOrCreateTerminal(id)` on React mount and `unmountElement(id)` on React unmount. The session (xterm.js instance, PTY, DOM element) persists in the registry across mount/unmount cycles — the DOM element is detached from its container but the Registry entry stays `Mounted`. A browser surface's pane ID is a Surface id with no registry entry or PTY (`docs/specs/glossary.md`); its DOM is owned by dockview and it is reconstructed from persisted params, not from the registry.
 
 - **Create**: `getOrCreateTerminal` spawns xterm.js + UnicodeGraphemesAddon + FitAddon + PTY, returns existing if already created. The xterm instance sets `allowProposedApi: true` because UnicodeGraphemesAddon activates through xterm's proposed Unicode API.
 - **Resume**: `resumeTerminal` creates xterm entry and writes replay data without spawning a new PTY. Used when the webview is recreated while the host retains Live PTYs (Link: Severed → Resuming → Live).
@@ -296,6 +324,8 @@ Pane IDs are session IDs. `TerminalPane` calls `getOrCreateTerminal(id)` on Reac
 
 Layout, scrollback, cwd, minimized items, user-pinned titles, untouched state, and alert state are saved to persistent storage via a debounced save (500ms). Derived command/app labels shown on minimized doors are display-only and are not persisted as user-pinned titles. Saves are triggered by layout changes, panel add/remove, and a 30s periodic interval. Saves are flushed immediately on PTY exit, `pagehide`, and extension shutdown requests.
 
+In standalone, each Workspace's snapshot is wrapped in a Window snapshot that records every Workspace (name + layout) and which one is active, so all Workspaces — not just the mounted one — survive a restart. VS Code persists one Workspace per webview exactly as today (one snapshot per `WebviewView` / `WebviewPanel`). The persisted container types (`PersistedWorkspace`, `PersistedWindow`) and their migration live in `docs/specs/transport.md`.
+
 Saved snapshots are read through `readPersistedSession()`, which accepts the canonical object shape and defensively parses a JSON-stringified blob before validation and migration. This keeps malformed storage inert while covering hosts that hand back serialized JSON instead of the parsed object.
 
 On startup, recovery is priority-based:
diff --git a/docs/specs/mobile-ui.md b/docs/specs/mobile-ui.md
index 2e14dda5..f25d62aa 100644
--- a/docs/specs/mobile-ui.md
+++ b/docs/specs/mobile-ui.md
@@ -78,7 +78,8 @@ The mobile UI is split into fixed and flexible regions:
 
 The mobile session header and pane content come from `MobileWall`, a mobile
 composition that displays one active terminal session at a time. Desktop `Wall`
-remains the tiling workspace; mobile does not expose split-pane layout. The
+remains the tiling workspace layout; mobile does not expose split-pane layout or
+multiple Workspaces. The
 mobile wrapper owns the two selectors and the fixed-height reserve. The selector
 block should use one divider between the Touch and Input rows, with no divider
 above Touch and no divider below Input. The mobile session header should not use
diff --git a/docs/specs/shortcuts.md b/docs/specs/shortcuts.md
index 43a41f18..a85c0ba8 100644
--- a/docs/specs/shortcuts.md
+++ b/docs/specs/shortcuts.md
@@ -4,7 +4,7 @@ Complete reference for Dormouse's keyboard shortcuts. Shortcuts are grouped by t
 
 Dormouse has two modes:
 
-- **Workspace mode** (a.k.a. "command" mode internally) — keys drive pane layout.
+- **Command mode** — keys drive pane and workspace layout. (Internally `command`; this reference previously called it "Workspace mode," renamed to free the word "Workspace" for the pane-group container — see `docs/specs/glossary.md`.)
 - **Terminal mode** (a.k.a. "passthrough" mode) — keys go to the running program, except copy/paste and the mode-switch gesture.
 
 In the VS Code extension host, selected workbench chords are mirrored: the terminal receives the key, and Dormouse also runs the matching VS Code workbench command. See [the VS Code host spec](vscode.md) for the exact allowlist.
@@ -13,11 +13,11 @@ In the VS Code extension host, selected workbench chords are mirrored: the termi
 
 | Key | Action | Description |
 |-----|--------|-------------|
-| Left ⌘ → Right ⌘ (within 500 ms) | Toggle mode | Tap left Command, then right Command within 500 ms to swap between workspace and terminal mode. |
+| Left ⌘ → Right ⌘ (within 500 ms) | Toggle mode | Tap left Command, then right Command within 500 ms to swap between command and terminal mode. |
 | Left Shift → Right Shift (within 500 ms) | Toggle mode | Same as above, but with the Shift keys. |
-| `Enter` (workspace) | Enter terminal mode | Switch the selected pane into passthrough (or reattach a minimized door). |
+| `Enter` (command) | Enter terminal mode | Switch the selected pane into passthrough (or reattach a minimized door). |
 
-## Pane actions (workspace mode)
+## Pane actions (command mode)
 
 | Key | Action | Description |
 |-----|--------|-------------|
@@ -27,16 +27,20 @@ In the VS Code extension host, selected workbench chords are mirrored: the termi
 | `m` or `d` | Minimize / reattach | Minimize the selected pane to the baseboard, or reattach a minimized door. |
 | `k` or `x` | Kill | Kill the selected pane or door. Prompts for a random character to confirm. |
 | `,` | Rename | Enter rename mode for the selected pane's title. |
-| `a` | Toggle alert | Dismiss or toggle the bell alert for the selected pane. |
-| `t` | Toggle todo | Toggle the TODO marker on or off for the selected pane. |
+| `a` | Toggle alert | Dismiss or toggle the bell alert for the selected pane. Meaningful only for a terminal Surface — a browser surface has no bell to ring (`docs/specs/glossary.md`). |
+| `t` | Toggle todo | Toggle the TODO marker on or off for the selected pane's Surface. Works on any Surface — a terminal Session or a browser surface. |
 
-## Navigation (workspace mode)
+## Navigation (command mode)
 
 | Key | Action | Description |
 |-----|--------|-------------|
 | `↑` / `↓` / `←` / `→` | Move selection | Move selection to the adjacent pane or door. Press the opposite direction to return. |
 | `⌘↑` / `⌘↓` / `⌘←` / `⌘→` (macOS)<br>`Ctrl`+arrows (others) | Swap terminals | Swap terminal sessions between two panes — layout and titles swap; selection follows the terminal. |
 
+## Workspaces (command mode)
+
+> Workspace switch / create / close / rename shortcuts are being finalized in the Storybook UI pass, following the tmux *window* bindings the rest of the keymap mirrors. They are listed here once bound. See `docs/specs/layout.md` and `docs/specs/glossary.md` for the Workspace model.
+
 ## Selection & drag
 
 | Key | Action | Description |
@@ -64,11 +68,11 @@ On macOS, `Ctrl+C` / `Ctrl+V` pass through to the running program; only the ⌘-
 | `Enter` | Confirm rename | Save the new name while renaming a pane. |
 | `Tab` / `Shift+Tab` | Focus cycle | Cycle focus through elements of an open popover or dialog. |
 | Prompted character | Confirm kill | Type the character shown in the kill prompt to confirm termination. |
-| `a` (alert dialog open) | Toggle alert | Same as workspace `a`. |
-| `t` (alert dialog open) | Toggle todo | Same as workspace `t`. |
+| `a` (alert dialog open) | Toggle alert | Same as command-mode `a`. |
+| `t` (alert dialog open) | Toggle todo | Same as command-mode `t`. |
 
 ## Implementation references
 
-- Primary keyboard handler: `lib/src/components/wall/use-wall-keyboard.ts` (workspace key dispatch, mode toggle, dialog key handlers)
+- Primary keyboard handler: `lib/src/components/wall/use-wall-keyboard.ts` (command-mode key dispatch, mode toggle, dialog key handlers)
 - Selection popup copy bindings: `lib/src/components/SelectionPopup.tsx`
 - Alt-to-toggle-block selection: `lib/src/lib/terminal-mouse-router.ts`
diff --git a/docs/specs/transport.md b/docs/specs/transport.md
index a297678b..bbe376aa 100644
--- a/docs/specs/transport.md
+++ b/docs/specs/transport.md
@@ -93,6 +93,8 @@ Non-obvious message contracts:
 
 VS Code-only workbench chord mirroring uses `dormouse:runWorkbenchCommand` from webview to host. The host validates the requested command against the allowlist in `lib/src/lib/vscode-keybindings.ts` (see [the VS Code host spec](vscode.md)) before calling `vscode.commands.executeCommand`; generic command execution over the webview boundary is not allowed.
 
+Workspace union status (`docs/specs/alert.md`) adds no new message. Standalone computes it in-webview — the app bar's workspace strip and the Walls share one webview, so the strip reads the activity store and browser-surface state directly. VS Code computes only the host-visible native-chrome projection from the module-level `AlertManager` filtered to each router's `ownedPtyIds`, then writes it onto native chrome; the host already receives every PTY's alert state, but it does not receive browser-surface TODO without a future webview→host Surface-state message (`docs/specs/vscode.md`).
+
 | Direction | Message | Source type | Contract |
 | --- | --- | --- | --- |
 | Webview → host | `dormouse:openExternal` | `WebviewMessage` | Request the host to open a user-confirmed external URI from an OSC 8 hyperlink. Hosts must revalidate and reject malformed, control-character-bearing, or blocked pseudo-scheme targets (`javascript:`, `data:`, `blob:`, `about:`). |
@@ -106,7 +108,13 @@ The OSC parsing/stripping rules that produce `pty:data` and `terminal:semanticEv
 
 ## Persisted session types
 
-Source of truth: `lib/src/lib/session-types.ts` defines the persisted-session interfaces (`PersistedSession` v3, `PersistedPane`, `PersistedAlertState`, `PersistedDoor`) and their v1→v2→v3 migrations.
+Source of truth: `lib/src/lib/session-types.ts` defines the persisted-session interfaces (`PersistedSession` v3, `PersistedPane` — now carrying `surfaceType` — `PersistedAlertState`, `PersistedDoor`) and their v1→v2→v3 migrations.
+
+**Surface kinds in the snapshot (stage 2a, implemented).** Each `PersistedPane` records a `surfaceType` (`docs/specs/glossary.md`): `'terminal'` (the default, omitted from the row to keep terminal snapshots byte-identical) or `'browser'`. This is the discriminator that routes restore/resume. `restoreSession` skips terminal restoration for a browser pane, so it no longer mints a stray PTY + xterm for each browser pane id (`session-restore.ts`); the resume plan keeps browser panes (and minimized browser doors) even though they have no live PTY, so the saved `layout`'s panel set still matches and is not discarded (`reconnect.ts`). A browser pane rebuilds from the dockview `layout` blob (visible) or `PersistedDoor.params` (minimized); its render params (`renderMode`, `url`, agent-browser `session`) live there, not in `PersistedPane` — `surfaceType` alone is enough to route restore. A pane lacking `surfaceType` reads as `'terminal'`, so older snapshots migrate transparently.
+
+**Workspace/Window containers (stage 2b, not yet implemented).** The container layer below is specified ahead of the code (`docs/specs/glossary.md` → Implementation status). A **Workspace** will persist as a `PersistedWorkspace`: a `WorkspaceId`, a user-facing `name`, and the Workspace's `PersistedSession` (its panes, doors, and dockview layout). The standalone Window will persist as a `PersistedWindow`: the ordered list of `PersistedWorkspace` plus the active `WorkspaceId`. VS Code will not use `PersistedWindow`; each webview persists exactly one `PersistedSession` — its single Workspace — through the same per-surface state API as today (`workspaceState` for the view, `vscode.setState()` per editor panel; see `docs/specs/vscode.md`).
+
+Versioning and migration (stage 2b): introducing the Window container advances the standalone top-level snapshot version. A pre-workspace `PersistedSession` (v3) will migrate to a single `PersistedWorkspace` named `Workspace 1`, marked active, inside a `PersistedWindow`. The standalone reader applies this migration; a host that hands back a bare `PersistedSession` (VS Code, or legacy standalone storage) is read as one Workspace. Migrations stay additive — older shapes keep flowing v1→v2→v3→(window) without losing panes, doors, alert state, or surface kind.
 
 Every saved-session entry point must pass through `readPersistedSession()`. That reader accepts both the canonical parsed object and a JSON-stringified session blob before validating/migrating; this covers host state APIs that may hand back the inner serialized JSON string.
 
diff --git a/docs/specs/vscode.md b/docs/specs/vscode.md
index f5746225..4ada5729 100644
--- a/docs/specs/vscode.md
+++ b/docs/specs/vscode.md
@@ -1,6 +1,6 @@
 # Dormouse VS Code Integration Spec
 
-> See `docs/specs/glossary.md` for Session / Pane / Door vocabulary. See `docs/specs/transport.md` for the PTY lifecycle, message protocol, persisted-session types, and adapter-agnostic invariants that VS Code shares with the standalone and fake adapters. This spec covers the VS Code-specific layer: panel/view registration, persistence APIs, theme integration, CSP, build, and dream-architecture commands.
+> See `docs/specs/glossary.md` for Session / Surface / Pane / Door vocabulary. See `docs/specs/transport.md` for the PTY lifecycle, message protocol, persisted-session types, and adapter-agnostic invariants that VS Code shares with the standalone and fake adapters. This spec covers the VS Code-specific layer: panel/view registration, persistence APIs, theme integration, CSP, build, and dream-architecture commands.
 
 ## What's built
 
@@ -103,6 +103,23 @@ VS Code-specific consequences:
 
 PTY lifecycle, buffering, the reconnection sequence, and the full message protocol live in `docs/specs/transport.md`.
 
+### Workspaces
+
+> See `docs/specs/glossary.md` for the Workspace / Window containers and `docs/specs/alert.md` for the union status.
+>
+> **Not yet implemented (stage 2b).** The webview↔Workspace mapping is the conceptual frame; VS Code already partitions PTYs per webview, but Dormouse does not yet compute a per-Workspace union or reflect it onto native chrome (see the "Not yet implemented" bullet below). Stage 2a (`surfaceType` persistence, browser-surface restore/resume) is implemented and adapter-agnostic.
+
+In VS Code, **one webview is one Workspace**. The bottom-panel `WebviewView` ("Dormouse") is the default Workspace; each `dormouse.open` editor-tab `WebviewPanel` is an independent Workspace. Unlike standalone, several Workspaces are visible at once, and VS Code — not Dormouse — owns their tabs, creation, and closing: opening a Dormouse editor tab creates a Workspace and closing the tab closes it, so Dormouse adds no create/rename/close affordances here. A webview owns the terminal Sessions whose PTYs its router tracks (`ownedPtyIds`, `docs/specs/transport.md`) plus any browser surfaces rendered in it; together those are the Workspace's Surfaces.
+
+#### Surfacing union status on native chrome
+
+The host computes each Workspace's native-chrome attention projection (`ringing` / `todo` / `count`) from the module-level `AlertManager`, scoped to that webview's `ownedPtyIds`. That means VS Code native chrome reflects terminal Session ring + TODO only. Browser-surface TODO remains webview-local Surface state and is not included in `panel.iconPath`, `panel.title`, or `view.badge` unless a future webview→host Surface-state channel is added; the existing `alert:state` channel is keyed by PTY-backed Session ids only.
+
+- **Editor tab (`WebviewPanel`):** reassign `panel.iconPath` between normal / ringing / TODO icon variants, and optionally fold the Workspace name or a status marker into `panel.title`. Both properties are writable after creation (`title: string`, `iconPath?: Uri | { light, dark }`).
+- **Sidebar/panel view (`WebviewView`):** set `view.badge = { value: count, tooltip }` for a numeric attention badge on the activity-bar icon, visible even when the view is collapsed; `view.description` may carry status text. `view.title` is writable too but stays "Dormouse". `ViewBadge` is numeric only (no custom color or glyph), so the editor-tab icon swap carries the ringing-vs-TODO distinction the badge cannot.
+
+Reflection updates on every `AlertManager.onStateChange` for an owned PTY and on router attach/detach (a Workspace gaining or losing Sessions). When a Workspace's union is clear, the badge is set to `undefined` and the icon returns to the normal variant. Icon artwork is settled in the Storybook/asset pass.
+
 ### Shell selection
 
 The VS Code view title contributes `Dormouse: Select Shell` and `Dormouse: New Terminal`. The selected shell name is mirrored into the `WebviewView.description`, and `dormouse:selectedShell` keeps the webview's default-shell slot current for split/spawn/restore paths.
@@ -213,3 +230,4 @@ vscode.commands.executeCommand('setContext', 'dormouse.mode', 'normal');
 - Commands not registered: `dormouse.newPane`, `closePane`, `nextPane`, `prevPane`, `enterTerminalMode`, `enterNormalMode`, `listSessions`, `reattach`
 - No status bar item showing active session count
 - No QuickPick for listing/reattaching PTY sessions
+- Workspace union status not yet reflected onto `panel.iconPath` / `panel.title` (editor tabs) or `view.badge` / `view.description` (bottom-panel view) — the model and chrome contract are in the Workspaces section above
diff --git a/lib/src/components/Wall.tsx b/lib/src/components/Wall.tsx
index 409d645f..75e34b04 100644
--- a/lib/src/components/Wall.tsx
+++ b/lib/src/components/Wall.tsx
@@ -15,6 +15,7 @@ import { markAgentBrowserSessionClosed } from './wall/agent-browser-sessions';
 import { KILL_CONFIRM_MS, KILL_SHAKE_MS, KillConfirmOverlay, randomKillChar, type ConfirmKill } from './KillConfirm';
 import {
   clearSessionAttention,
+  clearLocalSurfaceActivity,
   disposeSession,
   dismissOrToggleAlert,
   focusSession,
@@ -597,6 +598,7 @@ export function Wall({
     if (!api || !panel) return;
     closeAgentBrowserSession(panel.params);
     orchestrateKill(api, id, selectPane, setSelectedId, killInProgressRef, overlayElRef);
+    clearLocalSurfaceActivity(id);
     fireEvent({ type: 'kill', id });
   }, [fireEvent, selectPane]);
 
@@ -1091,6 +1093,7 @@ export function Wall({
       position: { referencePanel: panel, direction: 'within' },
     });
     api.removePanel(panel);
+    clearLocalSurfaceActivity(oldId);
     selectPane(newId);
     return newId;
   }, [generatePaneId, selectPane]);
diff --git a/lib/src/components/wall/use-session-persistence.ts b/lib/src/components/wall/use-session-persistence.ts
index 0c814ae7..9125cfc7 100644
--- a/lib/src/components/wall/use-session-persistence.ts
+++ b/lib/src/components/wall/use-session-persistence.ts
@@ -4,6 +4,7 @@ import { pasteFilePaths } from '../../lib/clipboard';
 import { getPlatform } from '../../lib/platform';
 import { saveSession } from '../../lib/session-save';
 import { UNNAMED_PANEL_TITLE } from '../../lib/terminal-registry';
+import { isBrowserParams } from './browser-surface';
 import type { DooredItem, WallSelectionKind } from './wall-types';
 
 export function useSessionPersistence({
@@ -27,7 +28,11 @@ export function useSessionPersistence({
     const api = apiRef.current;
     if (!api) return Promise.resolve();
 
-    const panes = api.panels.map((p) => ({ id: p.id, title: p.title ?? UNNAMED_PANEL_TITLE }));
+    const panes = api.panels.map((p) => ({
+      id: p.id,
+      title: p.title ?? UNNAMED_PANEL_TITLE,
+      surfaceType: isBrowserParams(p.params) ? ('browser' as const) : ('terminal' as const),
+    }));
     return saveSession(getPlatform(), api.toJSON(), panes, doorsRef.current ?? []);
   }, [apiRef, doorsRef]);
 
diff --git a/lib/src/lib/reconnect.test.ts b/lib/src/lib/reconnect.test.ts
index ab8a96a7..d8fb7cfa 100644
--- a/lib/src/lib/reconnect.test.ts
+++ b/lib/src/lib/reconnect.test.ts
@@ -3,11 +3,13 @@ import type { PlatformAdapter, PtyInfo } from './platform/types';
 import type { PersistedSession } from './session-types';
 
 const terminalRegistryMocks = vi.hoisted(() => ({
+  restoreBrowserSurfaceTodo: vi.fn(),
   resumeTerminal: vi.fn(),
   restoreTerminal: vi.fn(),
 }));
 
 vi.mock('./terminal-registry', () => ({
+  restoreBrowserSurfaceTodo: terminalRegistryMocks.restoreBrowserSurfaceTodo,
   resumeTerminal: terminalRegistryMocks.resumeTerminal,
   restoreTerminal: terminalRegistryMocks.restoreTerminal,
 }));
@@ -292,4 +294,120 @@ describe('resumeOrRestore', () => {
       layout,
     });
   });
+
+  it('keeps the saved layout and a visible browser pane when only terminals have live PTYs', async () => {
+    const layout = { panels: { 'pane-term': {}, 'pane-web': {} } };
+    const saved: PersistedSession = {
+      version: 3,
+      layout,
+      panes: [
+        { id: 'pane-term', title: 'Terminal', cwd: null, scrollback: null, resumeCommand: null },
+        { id: 'pane-web', title: 'localhost', cwd: null, scrollback: null, resumeCommand: null, surfaceType: 'browser' },
+      ],
+    };
+
+    const result = await resumeOrRestore(createPlatform([
+      { id: 'pane-term', alive: true },
+    ], saved));
+
+    expect(result).toEqual({
+      paneIds: ['pane-term', 'pane-web'],
+      doors: [],
+      layout,
+    });
+    // The browser pane has no PTY and is never resumed as a terminal.
+    expect(terminalRegistryMocks.resumeTerminal).toHaveBeenCalledTimes(1);
+    expect(terminalRegistryMocks.resumeTerminal).toHaveBeenCalledWith('pane-term', 'pane-term-replay', expect.anything());
+  });
+
+  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,
+      layout,
+      panes: [
+        { id: 'pane-term', title: 'Terminal', cwd: null, scrollback: null, resumeCommand: null },
+        {
+          id: 'pane-web',
+          title: 'localhost',
+          cwd: null,
+          scrollback: null,
+          resumeCommand: null,
+          surfaceType: 'browser',
+          alert: { status: 'WATCHING_DISABLED', watchingEnabled: false, todo: true, notification: null },
+        },
+      ],
+    };
+
+    await resumeOrRestore(createPlatform([
+      { id: 'pane-term', alive: true },
+    ], saved));
+
+    // 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 () => {
+    const saved: PersistedSession = {
+      version: 3,
+      layout: { panels: { 'pane-term': {}, 'stale-term': {}, 'pane-web': {} } },
+      panes: [
+        { id: 'pane-term', title: 'Terminal', cwd: null, scrollback: null, resumeCommand: null },
+        { id: 'stale-term', title: 'Stale terminal', cwd: null, scrollback: null, resumeCommand: null },
+        { id: 'pane-web', title: 'localhost', cwd: null, scrollback: null, resumeCommand: null, surfaceType: 'browser' },
+      ],
+    };
+
+    const result = await resumeOrRestore(createPlatform([
+      { id: 'pane-term', alive: true },
+    ], saved));
+
+    expect(result).toEqual({
+      paneIds: ['pane-term'],
+      doors: [],
+      layout: undefined,
+    });
+  });
+
+  it('keeps a minimized browser door alive across resume despite having no PTY', async () => {
+    const layout = { panels: { 'pane-term': {} } };
+    const doors = [{
+      id: 'door-web',
+      title: 'localhost',
+      component: 'browser',
+      params: { surfaceType: 'browser', renderMode: 'iframe', url: 'http://localhost:5173' },
+      neighborId: 'pane-term',
+      direction: 'right' as const,
+      remainingPaneIds: ['pane-term'],
+      layoutAtMinimize: layout,
+      layoutAtMinimizeSignature: 'sig',
+    }];
+    const saved: PersistedSession = {
+      version: 3,
+      layout,
+      doors,
+      panes: [
+        { id: 'pane-term', title: 'Terminal', cwd: null, scrollback: null, resumeCommand: null },
+        { id: 'door-web', title: 'localhost', cwd: null, scrollback: null, resumeCommand: null, surfaceType: 'browser' },
+      ],
+    };
+
+    const result = await resumeOrRestore(createPlatform([
+      { id: 'pane-term', alive: true },
+    ], saved));
+
+    expect(result).toEqual({
+      paneIds: ['pane-term'],
+      doors,
+      layout,
+    });
+  });
 });
diff --git a/lib/src/lib/reconnect.ts b/lib/src/lib/reconnect.ts
index 46b9e3b5..7c2d0db3 100644
--- a/lib/src/lib/reconnect.ts
+++ b/lib/src/lib/reconnect.ts
@@ -1,5 +1,5 @@
 import type { PlatformAdapter, PtyInfo } from './platform/types';
-import { resumeTerminal } from './terminal-registry';
+import { restoreBrowserSurfaceTodo, resumeTerminal } from './terminal-registry';
 import { readPersistedSession, type PersistedDoor } from './session-types';
 import { restoreSession } from './session-restore';
 
@@ -102,6 +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) {
+    restoreBrowserSurfaceTodo(pane);
     if (!liveSet.has(pane.id)) continue;
     result.set(pane.id, { title: pane.title, untouched: pane.untouched });
   }
@@ -119,10 +120,14 @@ function getSavedResumePlan(savedState: unknown, liveIds: string[]): ReconnectRe
   const savedSet = new Set(saved.panes.map((p) => p.id));
   if (!liveIds.every((id) => savedSet.has(id))) return null;
 
-  const doors = (saved.doors ?? []).filter((item) => liveSet.has(item.id));
+  // Browser surfaces have no PTY, so they never appear in the live-PTY set. Keep
+  // them anyway — they are reconstructed from the saved layout blob / door
+  // params (docs/specs/transport.md). Omitting them would drop the saved layout
+  // (the visible-pane mismatch below) and lose minimized browser doors.
+  const doors = (saved.doors ?? []).filter((item) => liveSet.has(item.id) || item.component === 'browser');
   const doorIds = new Set(doors.map((item) => item.id));
   const paneIds = saved.panes
-    .filter((pane) => liveSet.has(pane.id) && !doorIds.has(pane.id))
+    .filter((pane) => !doorIds.has(pane.id) && (liveSet.has(pane.id) || pane.surfaceType === 'browser'))
     .map((pane) => pane.id);
   const layoutPanelIds = getLayoutPanelIds(saved.layout);
   const layoutMatchesVisiblePanes =
@@ -131,7 +136,7 @@ function getSavedResumePlan(savedState: unknown, liveIds: string[]): ReconnectRe
     layoutPanelIds.every((id) => paneIds.includes(id));
 
   return {
-    paneIds,
+    paneIds: layoutMatchesVisiblePanes ? paneIds : paneIds.filter((id) => liveSet.has(id)),
     doors,
     layout: layoutMatchesVisiblePanes ? saved.layout : undefined,
   };
diff --git a/lib/src/lib/session-activity-store.ts b/lib/src/lib/session-activity-store.ts
index 191bda00..17785878 100644
--- a/lib/src/lib/session-activity-store.ts
+++ b/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,6 +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) {
+    clearLocalSurfaceActivity(id);
+    return;
+  }
+
+  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) {
@@ -187,13 +233,25 @@ export function clearSessionAttention(id?: string): void {
 }
 
 export function toggleSessionTodo(id: string): void {
+  if (!registry.has(id)) {
+    setLocalSurfaceTodo(id, !getActivity(id).todo);
+    return;
+  }
   getPlatform().alertToggleTodo(resolveTerminalSessionId(id));
 }
 
 export function markSessionTodo(id: string): void {
+  if (!registry.has(id)) {
+    setLocalSurfaceTodo(id, true);
+    return;
+  }
   getPlatform().alertMarkTodo(resolveTerminalSessionId(id));
 }
 
 export function clearSessionTodo(id: string): void {
+  if (!registry.has(id)) {
+    setLocalSurfaceTodo(id, false);
+    return;
+  }
   getPlatform().alertClearTodo(resolveTerminalSessionId(id));
 }
diff --git a/lib/src/lib/session-restore.test.ts b/lib/src/lib/session-restore.test.ts
index 1defd213..b5ed7bdb 100644
--- a/lib/src/lib/session-restore.test.ts
+++ b/lib/src/lib/session-restore.test.ts
@@ -4,11 +4,13 @@ import type { PersistedSession } from './session-types';
 
 const terminalRegistryMocks = vi.hoisted(() => ({
   getDefaultShellOpts: vi.fn(),
+  restoreBrowserSurfaceTodo: vi.fn(),
   restoreTerminal: vi.fn(),
 }));
 
 vi.mock('./terminal-registry', () => ({
   getDefaultShellOpts: terminalRegistryMocks.getDefaultShellOpts,
+  restoreBrowserSurfaceTodo: terminalRegistryMocks.restoreBrowserSurfaceTodo,
   restoreTerminal: terminalRegistryMocks.restoreTerminal,
 }));
 
@@ -102,4 +104,55 @@ describe('restoreSession', () => {
       untouched: true,
     }));
   });
+
+  it('does not spawn a terminal for a browser surface, but keeps it in paneIds', () => {
+    const saved: PersistedSession = {
+      version: 3,
+      layout: { panels: { 'pane-term': {}, 'pane-web': {} } },
+      panes: [
+        { id: 'pane-term', title: 'Terminal', cwd: null, scrollback: null, resumeCommand: null, untouched: false },
+        { id: 'pane-web', title: 'localhost', cwd: null, scrollback: null, resumeCommand: null, untouched: false, surfaceType: 'browser' },
+      ],
+    };
+
+    const result = restoreSession(createPlatform(saved));
+
+    expect(terminalRegistryMocks.restoreTerminal).toHaveBeenCalledTimes(1);
+    expect(terminalRegistryMocks.restoreTerminal).toHaveBeenCalledWith('pane-term', expect.objectContaining({ title: 'Terminal' }));
+    // The browser pane stays in paneIds so the layout blob recreates and selects it.
+    expect(result?.paneIds).toEqual(['pane-term', 'pane-web']);
+  });
+
+  it('restores browser surface TODO from the persisted alert during cold restore', () => {
+    const saved: PersistedSession = {
+      version: 3,
+      layout: { panels: { 'pane-web': {} } },
+      panes: [
+        {
+          id: 'pane-web',
+          title: 'localhost',
+          cwd: null,
+          scrollback: null,
+          resumeCommand: null,
+          untouched: false,
+          surfaceType: 'browser',
+          alert: { status: 'WATCHING_DISABLED', watchingEnabled: false, todo: true, notification: null },
+        },
+      ],
+    };
+
+    restoreSession(createPlatform(saved));
+
+    expect(terminalRegistryMocks.restoreTerminal).not.toHaveBeenCalled();
+    // 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 }),
+      }),
+    );
+  });
 });
diff --git a/lib/src/lib/session-restore.ts b/lib/src/lib/session-restore.ts
index 103895ff..e9a8ba19 100644
--- a/lib/src/lib/session-restore.ts
+++ b/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, restoreTerminal } from './terminal-registry';
+import { getDefaultShellOpts, restoreBrowserSurfaceTodo, restoreTerminal } from './terminal-registry';
 
 export interface RestoredSession {
   paneIds: string[];
@@ -16,6 +16,13 @@ export function restoreSession(platform: PlatformAdapter): RestoredSession | nul
   const shellOpts = getDefaultShellOpts();
 
   for (const pane of saved.panes) {
+    // Browser surfaces have no PTY or xterm; the dockview layout blob recreates
+    // 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') {
+      restoreBrowserSurfaceTodo(pane);
+      continue;
+    }
     restoreTerminal(pane.id, {
       cwd: pane.cwd,
       scrollback: pane.scrollback,
diff --git a/lib/src/lib/session-save.test.ts b/lib/src/lib/session-save.test.ts
index e1933888..aafdaebf 100644
--- a/lib/src/lib/session-save.test.ts
+++ b/lib/src/lib/session-save.test.ts
@@ -3,6 +3,7 @@ import type { PlatformAdapter } from './platform/types';
 import type { PersistedSession } from './session-types';
 
 const terminalRegistryMocks = vi.hoisted(() => ({
+  getActivity: vi.fn(),
   getLivePersistedAlertState: vi.fn(),
   getTerminalPaneState: vi.fn(),
   isUntouched: vi.fn(),
@@ -10,6 +11,7 @@ const terminalRegistryMocks = vi.hoisted(() => ({
 }));
 
 vi.mock('./terminal-registry', () => ({
+  getActivity: terminalRegistryMocks.getActivity,
   getLivePersistedAlertState: terminalRegistryMocks.getLivePersistedAlertState,
   getTerminalPaneState: terminalRegistryMocks.getTerminalPaneState,
   isUntouched: terminalRegistryMocks.isUntouched,
@@ -69,6 +71,12 @@ function createPlatform(savedState: PersistedSession | null): PlatformAdapter {
 describe('saveSession', () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    terminalRegistryMocks.getActivity.mockReturnValue({
+      status: 'WATCHING_DISABLED',
+      watchingEnabled: false,
+      todo: false,
+      notification: null,
+    });
     terminalRegistryMocks.resolveTerminalSessionId.mockImplementation((id: string) => id);
     terminalRegistryMocks.getLivePersistedAlertState.mockReturnValue(null);
     terminalRegistryMocks.getTerminalPaneState.mockReturnValue({ titleCandidates: {} });
@@ -206,4 +214,66 @@ describe('saveSession', () => {
       ],
     });
   });
+
+  it('records surfaceType only for browser surfaces, leaving terminal panes unmarked', async () => {
+    const platform = createPlatform(null);
+
+    await saveSession(platform, { root: true }, [
+      { id: 'pane-term', title: 'Terminal', surfaceType: 'terminal' },
+      { id: 'pane-web', title: 'localhost', surfaceType: 'browser' },
+    ]);
+
+    const saved = vi.mocked(platform.saveState).mock.calls[0]![0] as PersistedSession;
+    const term = saved.panes.find((p) => p.id === 'pane-term')!;
+    const web = saved.panes.find((p) => p.id === 'pane-web')!;
+    expect('surfaceType' in term).toBe(false);
+    expect(web.surfaceType).toBe('browser');
+    expect(platform.getScrollback).toHaveBeenCalledWith('pane-term');
+    expect(platform.getCwd).toHaveBeenCalledWith('pane-term');
+    expect(platform.getScrollback).not.toHaveBeenCalledWith('pane-web');
+    expect(platform.getCwd).not.toHaveBeenCalledWith('pane-web');
+  });
+
+  it('records surfaceType browser for a minimized browser door', async () => {
+    const platform = createPlatform(null);
+
+    await saveSession(platform, { root: true }, [], [{
+      id: 'door-web',
+      title: 'localhost',
+      component: 'browser',
+      params: { surfaceType: 'browser', renderMode: 'iframe', url: 'http://localhost:5173' },
+      neighborId: null,
+      direction: 'right',
+      remainingPaneIds: [],
+      layoutAtMinimize: null,
+      layoutAtMinimizeSignature: 'empty',
+    }]);
+
+    const saved = vi.mocked(platform.saveState).mock.calls[0]![0] as PersistedSession;
+    expect(saved.panes.find((p) => p.id === 'door-web')!.surfaceType).toBe('browser');
+    expect(platform.getScrollback).not.toHaveBeenCalledWith('door-web');
+    expect(platform.getCwd).not.toHaveBeenCalledWith('door-web');
+  });
+
+  it('persists local browser surface TODO state in the browser pane alert field', async () => {
+    const platform = createPlatform(null);
+    terminalRegistryMocks.getActivity.mockReturnValue({
+      status: 'WATCHING_DISABLED',
+      watchingEnabled: false,
+      todo: true,
+      notification: null,
+    });
+
+    await saveSession(platform, { root: true }, [
+      { id: 'pane-web', title: 'localhost', surfaceType: 'browser' },
+    ]);
+
+    const saved = vi.mocked(platform.saveState).mock.calls[0]![0] as PersistedSession;
+    expect(saved.panes.find((p) => p.id === 'pane-web')!.alert).toEqual({
+      status: 'WATCHING_DISABLED',
+      watchingEnabled: false,
+      todo: true,
+      notification: null,
+    });
+  });
 });
diff --git a/lib/src/lib/session-save.ts b/lib/src/lib/session-save.ts
index 6a91df2e..2e79c968 100644
--- a/lib/src/lib/session-save.ts
+++ b/lib/src/lib/session-save.ts
@@ -1,7 +1,7 @@
 import type { PlatformAdapter } from './platform/types';
-import { readPersistedSession, type PersistedDoor, type PersistedPane, type PersistedSession } from './session-types';
+import { browserPersistedPane, readPersistedSession, type PersistedDoor, type PersistedPane, type PersistedSession, type PersistedSurfaceType } from './session-types';
 import { detectResumeCommand } from './resume-patterns';
-import { getLivePersistedAlertState, getTerminalPaneState, isUntouched, resolveTerminalSessionId } from './terminal-registry';
+import { getActivity, getLivePersistedAlertState, getTerminalPaneState, isUntouched, resolveTerminalSessionId } from './terminal-registry';
 import { UNNAMED_PANEL_TITLE } from './terminal-state';
 
 function getPreviousPaneMap(platform: PlatformAdapter): Map<string, PersistedPane> {
@@ -15,25 +15,32 @@ function getPreviousPaneMap(platform: PlatformAdapter): Map<string, PersistedPan
 export async function saveSession(
   platform: PlatformAdapter,
   layout: unknown,
-  panes: Array<{ id: string; title: string }>,
+  panes: Array<{ id: string; title: string; surfaceType?: PersistedSurfaceType }>,
   doors: PersistedDoor[] = [],
 ): Promise<void> {
   const previousPanes = getPreviousPaneMap(platform);
-  const allPanes = new Map<string, { id: string; title: string }>();
+  const allPanes = new Map<string, { id: string; title: string; surfaceType: PersistedSurfaceType }>();
   for (const pane of panes) {
-    allPanes.set(pane.id, { id: pane.id, title: persistedVisiblePaneTitle(pane.title) });
+    allPanes.set(pane.id, { id: pane.id, title: persistedVisiblePaneTitle(pane.title), surfaceType: pane.surfaceType ?? 'terminal' });
   }
   const persistedDoors = doors.map((door) => ({
     ...door,
     title: persistedDoorTitle(door.id, door.title, door.component),
   }));
   for (const item of persistedDoors) {
-    allPanes.set(item.id, { id: item.id, title: item.title });
+    allPanes.set(item.id, { id: item.id, title: item.title, surfaceType: item.component === 'browser' ? 'browser' : 'terminal' });
   }
 
   const persisted: PersistedPane[] = await Promise.all(
     [...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 browserPersistedPane(pane, activity.todo ? activity : null);
+      }
+
       const liveAlert = getLivePersistedAlertState(pane.id);
       const sessionId = resolveTerminalSessionId(pane.id);
       const [scrollback, cwd] = await Promise.all([
diff --git a/lib/src/lib/session-types.ts b/lib/src/lib/session-types.ts
index 18ce9498..2e6b7be7 100644
--- a/lib/src/lib/session-types.ts
+++ b/lib/src/lib/session-types.ts
@@ -9,6 +9,14 @@ export interface PersistedAlertState {
   notification?: ActivityNotification | null;
 }
 
+/**
+ * Surface kind recorded per pane (`docs/specs/glossary.md`). Absent reads as
+ * `'terminal'`. A `'browser'` pane has no PTY, scrollback, or registry entry; it
+ * is reconstructed from the dockview `layout` blob, so restore/resume must route
+ * it differently from a terminal (see `session-restore.ts`, `reconnect.ts`).
+ */
+export type PersistedSurfaceType = 'terminal' | 'browser';
+
 export interface PersistedPane {
   id: string;
   cwd: string | null;
@@ -17,6 +25,30 @@ export interface PersistedPane {
   resumeCommand: string | null;
   untouched: boolean;
   alert?: PersistedAlertState | null;
+  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 {
@@ -124,6 +156,7 @@ function isPersistedPaneShape(value: unknown): boolean {
     (typeof value.scrollback === 'string' || value.scrollback === null) &&
     (typeof value.resumeCommand === 'string' || value.resumeCommand === null) &&
     (value.untouched === undefined || typeof value.untouched === 'boolean') &&
+    (value.surfaceType === undefined || value.surfaceType === 'terminal' || value.surfaceType === 'browser') &&
     (value.alert === undefined || isPersistedAlertShape(value.alert))
   );
 }
diff --git a/lib/src/lib/terminal-registry.alert.test.ts b/lib/src/lib/terminal-registry.alert.test.ts
index a12aeedc..47ff02c6 100644
--- a/lib/src/lib/terminal-registry.alert.test.ts
+++ b/lib/src/lib/terminal-registry.alert.test.ts
@@ -97,8 +97,10 @@ import {
   applyTerminalSemanticEvents,
   isPaneOscDriven,
   mountElement,
+  clearLocalSurfaceActivity,
   clearSessionAttention,
   clearSessionTodo,
+  restoreBrowserSurfaceTodo,
   disposeAllSessions,
   disposeSession,
   unmountElement,
@@ -470,6 +472,54 @@ describe('terminal-registry alert behavior', () => {
     });
   });
 
+  it('Browser surface: TODO toggles on a pane id with no registry entry (no PTY/xterm)', () => {
+    // A browser Surface (iframe / agent-browser) has no registry entry. The
+    // `t` shortcut stores TODO in the local activity store instead of sending a
+    // PTY alert message; VS Code only forwards alert state for owned PTYs.
+    const browserId = 'pane-browser';
+    const alertToggleSpy = vi.spyOn(fakePlatform, 'alertToggleTodo');
+    expect(getActivity(browserId).todo).toBe(false);
+
+    toggleSessionTodo(browserId);
+    expect(getActivity(browserId).todo).toBe(true);
+    expect(alertToggleSpy).not.toHaveBeenCalled();
+
+    toggleSessionTodo(browserId);
+    expect(getActivity(browserId).todo).toBe(false);
+    expect(alertToggleSpy).not.toHaveBeenCalled();
+    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);
diff --git a/lib/src/lib/terminal-registry.ts b/lib/src/lib/terminal-registry.ts
index 55dcf33f..d6373381 100644
--- a/lib/src/lib/terminal-registry.ts
+++ b/lib/src/lib/terminal-registry.ts
@@ -14,6 +14,7 @@ export type {
 } from './terminal-state';
 
 export {
+  clearLocalSurfaceActivity,
   clearPrimedActivity,
   clearSessionAttention,
   clearSessionTodo,
@@ -28,6 +29,7 @@ export {
   markSessionAttention,
   markSessionTodo,
   primeActivity,
+  restoreBrowserSurfaceTodo,
   subscribeToActivity,
   toggleSessionAlert,
   toggleSessionTodo,
diff --git a/vscode-ext/src/message-router.ts b/vscode-ext/src/message-router.ts
index 5bfe37c0..1f14ff80 100644
--- a/vscode-ext/src/message-router.ts
+++ b/vscode-ext/src/message-router.ts
@@ -501,6 +501,7 @@ export function attachRouter(
         // because other routers may own PTYs in the global pool.
         if (reconnectable.size === 0 && options?.savedSession) {
           for (const pane of options.savedSession.panes) {
+            if (pane.surfaceType === 'browser') continue;
             if (!globalOwnedPtyIds.has(pane.id)) {
               claim(pane.id);
             }
diff --git a/vscode-ext/src/session-state.ts b/vscode-ext/src/session-state.ts
index 6fa612a4..81d3dc7b 100644
--- a/vscode-ext/src/session-state.ts
+++ b/vscode-ext/src/session-state.ts
@@ -1,7 +1,7 @@
 import * as vscode from 'vscode';
 import * as ptyManager from './pty-manager';
 import type { AlertState } from '../../lib/src/lib/alert-manager';
-import { readPersistedSession, type PersistedAlertState, type PersistedPane, type PersistedSession } from '../../lib/src/lib/session-types';
+import { browserPersistedPane, readPersistedSession, type PersistedAlertState, type PersistedPane, type PersistedSession } from '../../lib/src/lib/session-types';
 import { log } from './log';
 
 const SESSION_STATE_KEY = 'dormouse.session';
@@ -35,10 +35,12 @@ export function mergeAlertStates(state: unknown, alertStates: Map<string, AlertS
   if (!parsed || !Array.isArray(parsed.panes)) return state;
   return {
     ...parsed,
-    panes: parsed.panes.map((pane) => ({
-      ...pane,
-      alert: toPersistedAlert(alertStates.get(pane.id), pane.alert),
-    })),
+    panes: parsed.panes.map((pane) => pane.surfaceType === 'browser'
+      ? pane
+      : {
+        ...pane,
+        alert: toPersistedAlert(alertStates.get(pane.id), pane.alert),
+      }),
   };
 }
 
@@ -57,6 +59,11 @@ export async function refreshSavedSessionStateFromPtys(
 
   const panes = await Promise.all(
     saved.panes.map(async (pane) => {
+      if (pane.surfaceType === 'browser') {
+        log.info(`[session] ${pane.id}: browser surface, skipping PTY refresh`);
+        return browserPersistedPane(pane, pane.alert ?? null);
+      }
+
       const alert = toPersistedAlert(alertStates?.get(pane.id), pane.alert);
 
       if (!ptys.has(pane.id)) {